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

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  DeleteCustomerTaxIds,
  GetCustomers,
  GetCustomerTaxIds,
  GetCustomerTaxIdsById,
  GetTaxIdsById,
  CreateCustomerTaxIds,
  type Customer as StripeCustomer,
  type TaxId as StripeTaxId,
  type TaxIdCustomer,
  type TaxIdType,
  type TaxIdVerificationStatus,
} from "@distilled.cloud/stripe/stripe";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import { alchemyMetadataKeys } from "./Metadata.ts";
import { isMissingStripeResource } from "./missing.ts";
import type { Providers } from "./Providers.ts";

const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;
const LIST_CONCURRENCY = 10;

/** Stripe tax ID type used when creating a customer tax ID (e.g. `eu_vat`). */
export type CustomerTaxIdType = Exclude<TaxIdType, "unknown">;

export interface CustomerTaxIdProps {
  /**
   * Id of the Stripe Customer to attach the tax ID to (`cus_…`).
   * Changing it replaces the tax ID.
   */
  customer: string;
  /**
   * Type of the tax ID, such as `eu_vat`, `us_ein`, or `gb_vat`.
   * Changing it replaces the tax ID.
   */
  type: CustomerTaxIdType;
  /**
   * Value of the tax ID (the VAT number, EIN, etc.). Changing it
   * replaces the tax ID.
   */
  value: string;
}

export type CustomerTaxId = Resource<
  "Stripe.CustomerTaxId",
  CustomerTaxIdProps,
  {
    /** Stripe tax ID object id (`txi_…`). */
    id: string;
    /** Id of the customer this tax ID is attached to (`cus_…`). */
    customer: string;
    /** Type of the tax ID (e.g. `eu_vat`). */
    type: TaxIdType;
    /** Value of the tax ID. */
    value: string;
    /** Two-letter ISO country code inferred from the tax ID, if known. */
    country: string | undefined;
    /** Verification status, if Stripe has attempted verification. */
    verificationStatus: TaxIdVerificationStatus | undefined;
    /** Unix timestamp when the tax ID was created. */
    created: number;
    /** Whether the tax ID exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Customer Tax ID — a tax identifier (VAT, EIN, GST, …) attached
 * to a Customer and printed on invoices. Existence-only: type and value
 * cannot be updated in place; changing `customer`, `type`, or `value`
 * replaces the tax ID. Destroy deletes it.
 *
 * Customer tax IDs have no metadata of their own. Ownership for
 * account-wide `list()` (nuke) is inferred from the parent Customer's
 * Alchemy metadata.
 *
 * @see https://docs.stripe.com/api/customer_tax_ids
 *
 * ### Creating a Customer Tax ID
 * **Example:** Attach an EU VAT number
 * ```typescript
 * const customer = yield* Stripe.Customer("alice", {
 *   email: "alice@example.com",
 * });
 * const vat = yield* Stripe.CustomerTaxId("alice-vat", {
 *   customer: customer.id,
 *   type: "eu_vat",
 *   value: "DE123456789",
 * });
 * ```
 *
 * ### Replacing a Tax ID
 * **Example:** Point at a different VAT number
 * ```typescript
 * const vat = yield* Stripe.CustomerTaxId("alice-vat", {
 *   customer: customer.id,
 *   type: "eu_vat",
 *   value: "DE000000000",
 * });
 * ```
 *
 * @resource
 * @product Customer
 */
export const CustomerTaxId = Resource<CustomerTaxId>("Stripe.CustomerTaxId");

type CustomerTaxIdAttributes = CustomerTaxId["Attributes"];

const customerIdOf = (customer: TaxIdCustomer | null): string | undefined => {
  if (customer == null) return undefined;
  if (typeof customer === "string") return customer;
  return customer.id;
};

const toAttrs = (customer: string, taxId: StripeTaxId): CustomerTaxIdAttributes => ({
  id: taxId.id,
  customer: customerIdOf(taxId.customer) ?? customer,
  type: taxId.type,
  value: taxId.value,
  country: taxId.country ?? undefined,
  verificationStatus: taxId.verification?.status,
  created: taxId.created,
  livemode: taxId.livemode,
});

const isMissing = isMissingStripeResource;

const getById = (id: string, customer?: string) => {
  if (customer !== undefined) {
    return GetCustomerTaxIdsById({ customer, id }).pipe(
      Effect.catchIf(isMissing, () => Effect.undefined),
    );
  }
  return GetTaxIdsById({ id }).pipe(Effect.catchIf(isMissing, () => Effect.undefined));
};

const listTaxIds = Effect.fn(function* (customer: string) {
  const taxIds: StripeTaxId[] = [];
  let startingAfter: string | undefined;
  for (let page = 0; page < LIST_MAX_PAGES; page++) {
    const response = yield* GetCustomerTaxIds({
      customer,
      limit: LIST_PAGE_SIZE,
      ...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
    }).pipe(Effect.catchIf(isMissing, () => Effect.undefined));
    if (response === undefined) {
      break;
    }
    taxIds.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 taxIds;
});

const findByTypeValue = Effect.fn(function* (customer: string, type: string, value: string) {
  const taxIds = yield* listTaxIds(customer);
  const matches = taxIds.filter((taxId) => taxId.type === type && taxId.value === value);
  matches.sort((a, b) => b.created - a.created);
  return matches[0];
});

const listAllCustomers = Effect.fn(function* () {
  const customers: StripeCustomer[] = [];
  let startingAfter: string | undefined;
  for (let page = 0; page < LIST_MAX_PAGES; page++) {
    const response = yield* GetCustomers({
      limit: LIST_PAGE_SIZE,
      ...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
    });
    customers.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 customers;
});

const listAlchemyCustomers = Effect.fn(function* () {
  const customers = yield* listAllCustomers();
  return customers.filter(
    (customer) => tagRecord(customer.metadata)[alchemyMetadataKeys.stack] !== undefined,
  );
});

const observe = Effect.fn(function* (input: {
  id?: string;
  customer?: string;
  type?: string;
  value?: string;
}) {
  if (input.id !== undefined) {
    const byId = yield* getById(input.id, input.customer);
    if (byId !== undefined) return byId;
  }
  if (input.customer !== undefined && input.type !== undefined && input.value !== undefined) {
    return yield* findByTypeValue(input.customer, input.type, input.value);
  }
  return undefined;
});

const shouldReplace = (
  news: CustomerTaxIdProps,
  output: CustomerTaxIdAttributes | undefined,
): boolean => {
  if (output === undefined) return false;
  if (news.customer !== output.customer) return true;
  if (news.type !== output.type) return true;
  if (news.value !== output.value) return true;
  return false;
};

export const CustomerTaxIdProvider = () =>
  Provider.succeed(CustomerTaxId, {
    stables: [
      "id",
      "customer",
      "type",
      "value",
      "country",
      "verificationStatus",
      "created",
      "livemode",
    ],
    nuke: { dependsOn: ["Stripe.Customer"] },

    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* ({ output, olds }) {
      const customer =
        output?.customer ?? (typeof olds?.customer === "string" ? olds.customer : undefined);
      const type = output?.type ?? (typeof olds?.type === "string" ? olds.type : undefined);
      const value = output?.value ?? (typeof olds?.value === "string" ? olds.value : undefined);
      const existing = yield* observe({
        id: output?.id,
        customer,
        type,
        value,
      });
      if (existing === undefined || customer === undefined) return undefined;
      return toAttrs(customer, existing);
    }),

    list: Effect.fn(function* () {
      // Customer tax IDs have no metadata. Fan out from alchemy-owned
      // customers so nuke only tears down tax IDs we created.
      const customers = yield* listAlchemyCustomers();
      const rows = yield* Effect.forEach(
        customers,
        (customer) =>
          listTaxIds(customer.id).pipe(
            Effect.map((taxIds) => taxIds.map((taxId) => toAttrs(customer.id, taxId))),
          ),
        { concurrency: LIST_CONCURRENCY },
      );
      return rows.flat();
    }),

    reconcile: Effect.fn(function* ({ news, output, instanceId }) {
      let current = yield* observe({
        id: output?.id,
        customer: news.customer,
        type: news.type,
        value: news.value,
      });
      if (current !== undefined && shouldReplace(news, toAttrs(news.customer, current))) {
        current = undefined;
      }

      if (current === undefined) {
        current = yield* CreateCustomerTaxIds({
          customer: news.customer,
          type: news.type,
          value: news.value,
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-customer-tax-id-${instanceId}`,
          }),
          Effect.catchIf(
            (e) => e._tag === "InvalidRequestError" || e._tag === "Conflict",
            (e) =>
              observe({
                customer: news.customer,
                type: news.type,
                value: news.value,
              }).pipe(
                Effect.flatMap((found) =>
                  found !== undefined ? Effect.succeed(found) : Effect.fail(e),
                ),
              ),
          ),
        );
      }

      return toAttrs(news.customer, current);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* DeleteCustomerTaxIds({
        customer: output.customer,
        id: output.id,
      }).pipe(Effect.catchIf(isMissing, () => Effect.void));
    }),
  });