sailfork / t3code-github / .repos/ alchemy-effect/ packages/ stripe/ src/ TaxRate.ts

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  GetTaxRates,
  GetTaxRate,
  CreateTaxRate,
  UpdateTaxRate,
  type TaxRate as StripeTaxRate,
} from "@distilled.cloud/stripe/stripe";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import {
  alchemyMetadataKeys,
  createInternalMetadata,
  diffMetadata,
  hasAlchemyMetadata,
  stripInternalMetadata,
  toMetadata,
} from "./Metadata.ts";
import { isMissingStripeResource } from "./missing.ts";
import type { Providers } from "./Providers.ts";

const DISPLAY_NAME_MAX_LENGTH = 250;
const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

/** High-level Stripe tax type, such as `vat` or `sales_tax`. */
export type TaxRateTaxType =
  | "amusement_tax"
  | "communications_tax"
  | "gst"
  | "hst"
  | "igst"
  | "jct"
  | "lease_tax"
  | "pst"
  | "qst"
  | "retail_delivery_fee"
  | "rst"
  | "sales_tax"
  | "service_tax"
  | "vat";

export interface TaxRateProps {
  /**
   * Display name shown to customers on receipts, invoice PDFs, and the
   * hosted invoice page. If omitted, a unique name is generated from the
   * stack, stage, and logical id. Mutable.
   */
  displayName?: string;
  /**
   * Tax rate percent out of 100. Create-only — changing it replaces the
   * tax rate.
   */
  percentage: number;
  /**
   * Whether this tax is inclusive of the listed price. Create-only —
   * changing it replaces the tax rate.
   */
  inclusive: boolean;
  /**
   * Whether the tax rate can be applied to new invoices, subscriptions,
   * and Checkout Sessions. Inactive rates remain on objects that already
   * use them.
   * @default true
   */
  active?: boolean;
  /**
   * Internal description. Not shown to customers.
   */
  description?: string;
  /**
   * Two-letter ISO 3166-1 alpha-2 country code.
   */
  country?: string;
  /**
   * Jurisdiction label for tax reporting; also appears on customer
   * invoices.
   */
  jurisdiction?: string;
  /**
   * ISO 3166-2 subdivision code without the country prefix (e.g. `"NY"`).
   */
  state?: string;
  /**
   * High-level tax type, such as `vat` or `sales_tax`.
   */
  taxType?: TaxRateTaxType;
  /**
   * User-defined metadata. Alchemy ownership keys (`alchemy_stack` /
   * `alchemy_stage` / `alchemy_id`) are merged in automatically. Keys may
   * not contain `:`. Mutable.
   */
  metadata?: Record<string, string>;
}

export type TaxRate = Resource<
  "Stripe.TaxRate",
  TaxRateProps,
  {
    /** Stripe tax rate id (`txr_…`). */
    id: string;
    /** Display name shown to customers. */
    displayName: string;
    /** Tax rate percent out of 100. */
    percentage: number;
    /** Whether this tax is inclusive of the listed price. */
    inclusive: boolean;
    /** Whether the tax rate can be applied to new objects. */
    active: boolean;
    /** Internal description, if set. */
    description: string | undefined;
    /** Two-letter ISO country code, if set. */
    country: string | undefined;
    /** Jurisdiction label, if set. */
    jurisdiction: string | undefined;
    /** ISO 3166-2 subdivision code, if set. */
    state: string | undefined;
    /** High-level tax type, if set. */
    taxType: TaxRateTaxType | undefined;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Unix timestamp when the tax rate was created. */
    created: number;
    /** Whether the tax rate exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Tax Rate — a percent tax applied to invoices, subscriptions,
 * and Checkout Sessions. `percentage` and `inclusive` are immutable and
 * changing them replaces the tax rate. Display name, active, description,
 * jurisdiction fields, and metadata update in place.
 *
 * Stripe does not hard-delete tax rates; destroying this resource
 * deactivates it (`active: false`).
 *
 * @see https://docs.stripe.com/api/tax_rates
 *
 * ### Creating a Tax Rate
 * **Example:** Exclusive sales tax
 * ```typescript
 * const vat = yield* Stripe.TaxRate("vat", {
 *   displayName: "VAT",
 *   percentage: 20,
 *   inclusive: false,
 * });
 * ```
 *
 * **Example:** Inclusive tax with metadata
 * ```typescript
 * const gst = yield* Stripe.TaxRate("gst", {
 *   displayName: "GST",
 *   percentage: 10,
 *   inclusive: true,
 *   taxType: "gst",
 *   metadata: { region: "au" },
 * });
 * ```
 *
 * ### Updating a Tax Rate
 * **Example:** Rename and pause
 * ```typescript
 * const vat = yield* Stripe.TaxRate("vat", {
 *   displayName: "VAT (paused)",
 *   percentage: 20,
 *   inclusive: false,
 *   active: false,
 *   metadata: { region: "eu" },
 * });
 * ```
 *
 * ### Deactivating a Tax Rate
 * **Example:** Destroy deactivates rather than deleting
 * ```typescript
 * // stack.destroy() / resource removal sets active: false
 * const vat = yield* Stripe.TaxRate("vat", {
 *   displayName: "VAT",
 *   percentage: 20,
 *   inclusive: false,
 * });
 * ```
 *
 * @resource
 * @product Tax
 */
export const TaxRate = Resource<TaxRate>("Stripe.TaxRate");

export class TaxRateNotResolved extends Data.TaggedError("Stripe.TaxRateNotResolved")<{
  displayName: string;
}> {}

type TaxRateAttributes = TaxRate["Attributes"];

const userMetadata = (
  metadata: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalMetadata(tagRecord(metadata));

const toDisplayName = (id: string, displayName: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    return (
      displayName ??
      existing ??
      (yield* createPhysicalName({ id, maxLength: DISPLAY_NAME_MAX_LENGTH }))
    );
  });

const toAttrs = (rate: StripeTaxRate): TaxRateAttributes => ({
  id: rate.id,
  displayName: rate.display_name,
  percentage: rate.percentage,
  inclusive: rate.inclusive,
  active: rate.active,
  description: rate.description ?? undefined,
  country: rate.country ?? undefined,
  jurisdiction: rate.jurisdiction ?? undefined,
  state: rate.state ?? undefined,
  taxType: (rate.tax_type ?? undefined) as TaxRateTaxType | undefined,
  metadata: userMetadata(rate.metadata),
  created: rate.created,
  livemode: rate.livemode,
});

const isMissingTaxRate = isMissingStripeResource;

const getById = (taxRate: string) =>
  GetTaxRate({ tax_rate: taxRate }).pipe(Effect.catchIf(isMissingTaxRate, () => Effect.undefined));

const listByActive = Effect.fn(function* (active: boolean) {
  const rates: StripeTaxRate[] = [];
  let startingAfter: string | undefined;
  for (let page = 0; page < LIST_MAX_PAGES; page++) {
    const response = yield* GetTaxRates({
      active,
      limit: LIST_PAGE_SIZE,
      ...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
    });
    rates.push(...response.data);
    if (!response.has_more || response.data.length === 0) {
      break;
    }
    startingAfter = response.data[response.data.length - 1]?.id;
    if (startingAfter === undefined) {
      break;
    }
  }
  return rates;
});

const listAllTaxRates = Effect.fn(function* () {
  const [active, inactive] = yield* Effect.all([listByActive(true), listByActive(false)], {
    concurrency: 2,
  });
  const seen = new Set<string>();
  const rates: StripeTaxRate[] = [];
  for (const rate of [...active, ...inactive]) {
    if (seen.has(rate.id)) continue;
    seen.add(rate.id);
    rates.push(rate);
  }
  return rates;
});

const findByAlchemyId = Effect.fn(function* (id: string) {
  const rates = yield* listAllTaxRates();
  const matches: StripeTaxRate[] = [];
  for (const rate of rates) {
    if (yield* hasAlchemyMetadata(id, tagRecord(rate.metadata))) {
      matches.push(rate);
    }
  }
  matches.sort((a, b) => b.created - a.created);
  return matches[0];
});

const observe = Effect.fn(function* (input: { id?: string; logicalId: string }) {
  if (input.id !== undefined) {
    const byId = yield* getById(input.id);
    if (byId !== undefined) return byId;
  }
  return yield* findByAlchemyId(input.logicalId);
});

const desiredMetadata = Effect.fn(function* (
  id: string,
  metadata: Record<string, string> | undefined,
) {
  return {
    ...toMetadata(metadata),
    ...(yield* createInternalMetadata(id)),
  };
});

const shouldReplace = (news: TaxRateProps, output: TaxRateAttributes | undefined): boolean => {
  if (output === undefined) return false;
  if (news.percentage !== output.percentage) return true;
  if (news.inclusive !== output.inclusive) return true;
  return false;
};

export const TaxRateProvider = () =>
  Provider.succeed(TaxRate, {
    stables: ["id", "percentage", "inclusive", "created", "livemode"],

    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news)) return undefined;
      if (shouldReplace(news, output)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, output }) {
      const existing = yield* observe({
        id: output?.id,
        logicalId: id,
      });
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing);
      return (yield* hasAlchemyMetadata(id, tagRecord(existing.metadata))) ? attrs : Unowned(attrs);
    }),

    list: Effect.fn(function* () {
      // Default list API is active tax rates; inactive (deactivated) rows
      // stay in Stripe but must not re-enter nuke. Filter to alchemy_stack
      // so account-wide teardown only touches our rows.
      const rates = yield* listByActive(true);
      return rates
        .filter((rate) => {
          const metadata = tagRecord(rate.metadata);
          return metadata[alchemyMetadataKeys.stack] !== undefined;
        })
        .map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const displayName = yield* toDisplayName(id, news.displayName, output?.displayName);
      const metadata = yield* desiredMetadata(id, news.metadata);
      const desiredActive = news.active ?? true;

      let current: StripeTaxRate | undefined = yield* observe({
        id: output?.id,
        logicalId: id,
      });
      if (current !== undefined && shouldReplace(news, toAttrs(current))) {
        current = undefined;
      }

      if (current === undefined) {
        current = yield* CreateTaxRate({
          display_name: displayName,
          percentage: news.percentage,
          inclusive: news.inclusive,
          active: desiredActive,
          metadata,
          ...(news.description !== undefined ? { description: news.description } : {}),
          ...(news.country !== undefined ? { country: news.country } : {}),
          ...(news.jurisdiction !== undefined ? { jurisdiction: news.jurisdiction } : {}),
          ...(news.state !== undefined ? { state: news.state } : {}),
          ...(news.taxType !== undefined ? { tax_type: news.taxType } : {}),
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-tax-rate-${instanceId}`,
          }),
        );
      }

      if (current === undefined) {
        return yield* new TaxRateNotResolved({ displayName });
      }

      const observedMetadata = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMetadata, metadata);
      const metadataChanged = upsert.length > 0 || removed.length > 0;
      const displayNameChanged = current.display_name !== displayName;
      const activeChanged = current.active !== desiredActive;
      const descriptionChanged =
        news.description !== undefined && (current.description ?? undefined) !== news.description;
      const countryChanged =
        news.country !== undefined && (current.country ?? undefined) !== news.country;
      const jurisdictionChanged =
        news.jurisdiction !== undefined &&
        (current.jurisdiction ?? undefined) !== news.jurisdiction;
      const stateChanged = news.state !== undefined && (current.state ?? undefined) !== news.state;
      const taxTypeChanged =
        news.taxType !== undefined && (current.tax_type ?? undefined) !== news.taxType;

      if (
        !displayNameChanged &&
        !activeChanged &&
        !descriptionChanged &&
        !countryChanged &&
        !jurisdictionChanged &&
        !stateChanged &&
        !taxTypeChanged &&
        !metadataChanged
      ) {
        return toAttrs(current);
      }

      const updated = yield* UpdateTaxRate({
        tax_rate: current.id,
        ...(displayNameChanged ? { display_name: displayName } : {}),
        ...(activeChanged ? { active: desiredActive } : {}),
        ...(descriptionChanged ? { description: news.description } : {}),
        ...(countryChanged ? { country: news.country } : {}),
        ...(jurisdictionChanged ? { jurisdiction: news.jurisdiction } : {}),
        ...(stateChanged ? { state: news.state } : {}),
        ...(taxTypeChanged ? { tax_type: news.taxType } : {}),
        ...(metadataChanged
          ? {
              metadata: {
                ...Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value])),
                ...Object.fromEntries(removed.map((key) => [key, ""])),
              },
            }
          : {}),
      });
      return toAttrs(updated);
    }),

    delete: Effect.fn(function* ({ output }) {
      const existing = yield* getById(output.id);
      if (existing === undefined || !existing.active) return;
      yield* UpdateTaxRate({
        tax_rate: existing.id,
        active: false,
      }).pipe(Effect.catchIf(isMissingTaxRate, () => Effect.void));
    }),
  });