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

import { withRequestOptions } from "@distilled.cloud/stripe";
import type { StripeOpError } from "@distilled.cloud/stripe";
import {
  GetIssuingCards,
  GetIssuingCard,
  CreateIssuingCard,
  UpdateIssuingCard,
  type IssuingCard as StripeIssuingCard,
  type CreateIssuingCardRequestSpendingControls,
} from "@distilled.cloud/stripe/stripe";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, isResolved } from "alchemy/Diff";
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 LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

/** Whether authorizations can be approved on this card. */
export type IssuingCardStatus = "active" | "canceled" | "inactive";

/** The type of Issuing card. Create-only — changing it replaces the card. */
export type IssuingCardType = "physical" | "virtual";

/** Why a previous card is being replaced. Create-only. */
export type IssuingCardReplacementReason = "damaged" | "expired" | "lost" | "stolen";

/** Card-present vs card-not-present authorization presence. */
export type IssuingCardPresence = "not_present" | "present";

/** Interval (or event) a spending limit applies to. */
export type IssuingCardSpendingLimitInterval =
  | "all_time"
  | "daily"
  | "monthly"
  | "per_authorization"
  | "weekly"
  | "yearly";

export interface IssuingCardSpendingLimit {
  /**
   * Maximum amount allowed to spend per interval, in the card's currency
   * minor units.
   */
  amount: number;
  /**
   * Interval (or event) to which the amount applies.
   */
  interval: IssuingCardSpendingLimitInterval;
  /**
   * Merchant categories this limit applies to. Omit to apply to all
   * categories.
   */
  categories?: string[];
}

export interface IssuingCardSpendingControls {
  /**
   * Card-presence statuses from which authorizations are allowed. Cannot
   * be set with `blockedCardPresences`.
   */
  allowedCardPresences?: IssuingCardPresence[];
  /**
   * Merchant categories to allow. All other categories are blocked.
   * Cannot be set with `blockedCategories`.
   */
  allowedCategories?: string[];
  /**
   * ISO 3166 alpha-2 countries from which authorizations are allowed.
   * Cannot be set with `blockedMerchantCountries`.
   */
  allowedMerchantCountries?: string[];
  /**
   * Card-presence statuses from which authorizations are declined. Cannot
   * be set with `allowedCardPresences`.
   */
  blockedCardPresences?: IssuingCardPresence[];
  /**
   * Merchant categories to decline. All other categories are allowed.
   * Cannot be set with `allowedCategories`.
   */
  blockedCategories?: string[];
  /**
   * ISO 3166 alpha-2 countries from which authorizations are declined.
   * Cannot be set with `allowedMerchantCountries`.
   */
  blockedMerchantCountries?: string[];
  /**
   * Amount-based spending limits that apply across this card and any
   * cards it replaced.
   */
  spendingLimits?: IssuingCardSpendingLimit[];
}

export interface IssuingCardProps {
  /**
   * Id of the Issuing Cardholder this card is issued to (`ich_…`).
   * Create-only — changing it replaces the card.
   */
  cardholder: string;
  /**
   * Three-letter ISO currency code, lowercase. Supported currencies are
   * `usd` (US), `eur` (EU), and `gbp` (UK). Create-only — changing it
   * replaces the card.
   */
  currency: string;
  /**
   * The type of card to issue.
   * @default "virtual"
   */
  type?: IssuingCardType;
  /**
   * Whether authorizations can be approved on this card. Stripe defaults
   * new cards to `inactive`. Destroying this resource cancels the card
   * (`canceled`); canceled cards cannot be reactivated.
   * @default "inactive"
   */
  status?: "active" | "inactive";
  /**
   * Second line printed on the card (max 24 characters). Create-only —
   * changing it replaces the card.
   */
  secondLine?: string;
  /**
   * Desired expiration month (1–12) when specifying a custom expiration
   * date. Create-only.
   */
  expMonth?: number;
  /**
   * Desired 4-digit expiration year when specifying a custom expiration
   * date. Create-only.
   */
  expYear?: number;
  /**
   * Financial account id this card is attached to. Create-only —
   * changing it replaces the card.
   */
  financialAccount?: string;
  /**
   * Personalization design id belonging to this card. Mutable.
   */
  personalizationDesign?: string;
  /**
   * Card this one replaces, if any. Create-only.
   */
  replacementFor?: string;
  /**
   * Why `replacementFor` is being replaced. Create-only.
   */
  replacementReason?: IssuingCardReplacementReason;
  /**
   * Rules that control spending for this card. Mutable.
   */
  spendingControls?: IssuingCardSpendingControls;
  /**
   * 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 IssuingCard = Resource<
  "Stripe.IssuingCard",
  IssuingCardProps,
  {
    /** Stripe Issuing card id (`ic_…`). */
    id: string;
    /** Id of the cardholder this card belongs to (`ich_…`). */
    cardholder: string;
    /** Three-letter ISO currency code. */
    currency: string;
    /** `virtual` or `physical`. */
    type: IssuingCardType;
    /** Whether authorizations can be approved on this card. */
    status: IssuingCardStatus;
    /** Card brand (e.g. `Visa`). */
    brand: string;
    /** Last 4 digits of the card number. */
    last4: string;
    /** Expiration month. */
    expMonth: number;
    /** Expiration year. */
    expYear: number;
    /** Second line printed on the card, if set. */
    secondLine: string | undefined;
    /** Financial account id, if attached. */
    financialAccount: string | undefined;
    /** Personalization design id, if set. */
    personalizationDesign: string | undefined;
    /** Card this one replaces, if any. */
    replacementFor: string | undefined;
    /** Why the previous card was replaced, if this is a replacement. */
    replacementReason: IssuingCardReplacementReason | undefined;
    /** Why the card was canceled, if canceled. */
    cancellationReason: string | undefined;
    /** Spending controls currently applied to this card. */
    spendingControls: IssuingCardSpendingControls | undefined;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Unix timestamp when the card was created. */
    created: number;
    /** Whether the card exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Issuing Card — a virtual or physical card issued to a
 * Cardholder. `cardholder`, `currency`, `type`, `secondLine`, and
 * custom expiration are immutable (changing them replaces the card).
 * Status, spending controls, personalization design, and metadata
 * update in place.
 *
 * Cards cannot be hard-deleted; destroying this resource cancels the
 * card (`status: canceled`). Canceled cards cannot be reactivated — a
 * later create with the same logical id provisions a new card.
 *
 * Issuing must be enabled on the Stripe account.
 *
 * @see https://docs.stripe.com/api/issuing/cards
 *
 * ### Creating a Card
 * **Example:** Virtual card
 * ```typescript
 * const card = yield* Stripe.IssuingCard("expense-card", {
 *   cardholder: cardholder.id,
 *   currency: "usd",
 *   type: "virtual",
 *   status: "inactive",
 * });
 * ```
 *
 * **Example:** Spending limits and metadata
 * ```typescript
 * const card = yield* Stripe.IssuingCard("expense-card", {
 *   cardholder: cardholder.id,
 *   currency: "usd",
 *   type: "virtual",
 *   status: "active",
 *   spendingControls: {
 *     spendingLimits: [{ amount: 50_000, interval: "monthly" }],
 *   },
 *   metadata: { team: "ops" },
 * });
 * ```
 *
 * ### Updating a Card
 * **Example:** Freeze and retag
 * ```typescript
 * const card = yield* Stripe.IssuingCard("expense-card", {
 *   cardholder: cardholder.id,
 *   currency: "usd",
 *   type: "virtual",
 *   status: "inactive",
 *   metadata: { team: "ops", frozen: "true" },
 * });
 * ```
 *
 * ### Replacing a Card
 * **Example:** Changing type replaces the card
 * ```typescript
 * const card = yield* Stripe.IssuingCard("expense-card", {
 *   cardholder: cardholder.id,
 *   currency: "usd",
 *   type: "physical",
 * });
 * ```
 *
 * @resource
 * @product Issuing
 */
export const IssuingCard = Resource<IssuingCard>("Stripe.IssuingCard");

export class IssuingCardNotResolved extends Data.TaggedError("Stripe.IssuingCardNotResolved")<{
  cardholder: string;
  currency: string;
}> {}

type IssuingCardAttributes = IssuingCard["Attributes"];

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

const expandedId = (
  value: string | { readonly id: string } | null | undefined,
): string | undefined => {
  if (value == null) return undefined;
  if (typeof value === "string") return value;
  return value.id;
};

const toSpendingControls = (
  controls: StripeIssuingCard["spending_controls"] | null | undefined,
): IssuingCardSpendingControls | undefined => {
  if (controls == null) return undefined;
  const spendingLimits = (controls.spending_limits ?? []).map((limit) => ({
    amount: limit.amount,
    interval: limit.interval as IssuingCardSpendingLimitInterval,
    ...(limit.categories != null && limit.categories.length > 0
      ? { categories: [...limit.categories] }
      : {}),
  }));
  const result: IssuingCardSpendingControls = {
    ...(controls.allowed_card_presences != null
      ? {
          allowedCardPresences: [...controls.allowed_card_presences] as IssuingCardPresence[],
        }
      : {}),
    ...(controls.allowed_categories != null
      ? { allowedCategories: [...controls.allowed_categories] }
      : {}),
    ...(controls.allowed_merchant_countries != null
      ? { allowedMerchantCountries: [...controls.allowed_merchant_countries] }
      : {}),
    ...(controls.blocked_card_presences != null
      ? {
          blockedCardPresences: [...controls.blocked_card_presences] as IssuingCardPresence[],
        }
      : {}),
    ...(controls.blocked_categories != null
      ? { blockedCategories: [...controls.blocked_categories] }
      : {}),
    ...(controls.blocked_merchant_countries != null
      ? { blockedMerchantCountries: [...controls.blocked_merchant_countries] }
      : {}),
    ...(spendingLimits.length > 0 ? { spendingLimits } : {}),
  };
  if (
    result.allowedCardPresences === undefined &&
    result.allowedCategories === undefined &&
    result.allowedMerchantCountries === undefined &&
    result.blockedCardPresences === undefined &&
    result.blockedCategories === undefined &&
    result.blockedMerchantCountries === undefined &&
    result.spendingLimits === undefined
  ) {
    return undefined;
  }
  return result;
};

const toWireSpendingControls = (
  controls: IssuingCardSpendingControls,
): CreateIssuingCardRequestSpendingControls => ({
  ...(controls.allowedCardPresences !== undefined
    ? { allowed_card_presences: controls.allowedCardPresences }
    : {}),
  ...(controls.allowedCategories !== undefined
    ? { allowed_categories: controls.allowedCategories }
    : {}),
  ...(controls.allowedMerchantCountries !== undefined
    ? { allowed_merchant_countries: controls.allowedMerchantCountries }
    : {}),
  ...(controls.blockedCardPresences !== undefined
    ? { blocked_card_presences: controls.blockedCardPresences }
    : {}),
  ...(controls.blockedCategories !== undefined
    ? { blocked_categories: controls.blockedCategories }
    : {}),
  ...(controls.blockedMerchantCountries !== undefined
    ? { blocked_merchant_countries: controls.blockedMerchantCountries }
    : {}),
  ...(controls.spendingLimits !== undefined
    ? {
        spending_limits: controls.spendingLimits.map((limit) => ({
          amount: limit.amount,
          interval: limit.interval,
          ...(limit.categories !== undefined ? { categories: limit.categories } : {}),
        })),
      }
    : {}),
});

const toAttrs = (card: StripeIssuingCard): IssuingCardAttributes => ({
  id: card.id,
  cardholder: card.cardholder.id,
  currency: card.currency,
  type: card.type,
  status: card.status,
  brand: card.brand,
  last4: card.last4,
  expMonth: card.exp_month,
  expYear: card.exp_year,
  secondLine: card.second_line ?? undefined,
  financialAccount: card.financial_account ?? undefined,
  personalizationDesign: expandedId(card.personalization_design),
  replacementFor: expandedId(card.replacement_for),
  replacementReason: (card.replacement_reason as IssuingCardReplacementReason | null) ?? undefined,
  cancellationReason: card.cancellation_reason ?? undefined,
  spendingControls: toSpendingControls(card.spending_controls),
  metadata: userMetadata(card.metadata),
  created: card.created,
  livemode: card.livemode,
});

const isMissingCard = isMissingStripeResource;

const isIssuingUnavailable = (error: StripeOpError): boolean =>
  error._tag === "InvalidRequestError" || error._tag === "Forbidden";

const getById = (card: string) =>
  GetIssuingCard({ card }).pipe(
    Effect.map((live) => (live.status === "canceled" ? undefined : live)),
    Effect.catchIf(isMissingCard, () => Effect.undefined),
  );

const getByIdAny = (card: string) =>
  GetIssuingCard({ card }).pipe(Effect.catchIf(isMissingCard, () => Effect.undefined));

const listByStatus = Effect.fn(function* (status: "active" | "inactive") {
  const cards: StripeIssuingCard[] = [];
  let startingAfter: string | undefined;
  for (let page = 0; page < LIST_MAX_PAGES; page++) {
    const response = yield* GetIssuingCards({
      status,
      limit: LIST_PAGE_SIZE,
      ...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
    });
    cards.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 cards;
});

const listLiveCards = Effect.fn(function* () {
  const listed = yield* Effect.all([listByStatus("active"), listByStatus("inactive")], {
    concurrency: 2,
  }).pipe(
    Effect.catchIf(isIssuingUnavailable, () =>
      Effect.succeed([[], []] as [StripeIssuingCard[], StripeIssuingCard[]]),
    ),
  );
  const seen = new Set<string>();
  const cards: StripeIssuingCard[] = [];
  for (const card of [...listed[0], ...listed[1]]) {
    if (seen.has(card.id)) continue;
    seen.add(card.id);
    cards.push(card);
  }
  return cards;
});

const findByAlchemyId = Effect.fn(function* (id: string) {
  const cards = yield* listLiveCards();
  const matches: StripeIssuingCard[] = [];
  for (const card of cards) {
    if (yield* hasAlchemyMetadata(id, tagRecord(card.metadata))) {
      matches.push(card);
    }
  }
  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: IssuingCardProps,
  output: IssuingCardAttributes | undefined,
): boolean => {
  if (output === undefined) return false;
  if (news.cardholder !== output.cardholder) return true;
  if (news.currency !== output.currency) return true;
  if ((news.type ?? "virtual") !== output.type) return true;
  if (news.secondLine !== undefined && news.secondLine !== (output.secondLine ?? undefined)) {
    return true;
  }
  if (news.expMonth !== undefined && news.expMonth !== output.expMonth) {
    return true;
  }
  if (news.expYear !== undefined && news.expYear !== output.expYear) {
    return true;
  }
  if (
    news.financialAccount !== undefined &&
    news.financialAccount !== (output.financialAccount ?? undefined)
  ) {
    return true;
  }
  if (
    news.replacementFor !== undefined &&
    news.replacementFor !== (output.replacementFor ?? undefined)
  ) {
    return true;
  }
  return false;
};

export const IssuingCardProvider = () =>
  Provider.succeed(IssuingCard, {
    stables: [
      "id",
      "cardholder",
      "currency",
      "type",
      "brand",
      "last4",
      "expMonth",
      "expYear",
      "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* () {
      // Canceled cards stay in Stripe but must not re-enter nuke. Filter
      // to alchemy_stack so account-wide teardown only touches our rows.
      const cards = yield* listLiveCards();
      return cards
        .filter((card) => {
          const metadata = tagRecord(card.metadata);
          return metadata[alchemyMetadataKeys.stack] !== undefined;
        })
        .map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const metadata = yield* desiredMetadata(id, news.metadata);
      const desiredType = news.type ?? "virtual";
      const desiredStatus = news.status ?? "inactive";
      const spendingControls =
        news.spendingControls !== undefined
          ? toWireSpendingControls(news.spendingControls)
          : undefined;

      let current: StripeIssuingCard | undefined = yield* observe({
        id: output?.id,
        logicalId: id,
      });
      // A previous generation (same logical id, different immutable
      // fields) must not be reused — Stripe cards cannot change
      // cardholder, currency, type, or printed second line.
      if (current !== undefined && shouldReplace(news, toAttrs(current))) {
        current = undefined;
      }

      if (current === undefined) {
        current = yield* CreateIssuingCard({
          cardholder: news.cardholder,
          currency: news.currency,
          type: desiredType,
          status: desiredStatus,
          metadata,
          ...(news.secondLine !== undefined ? { second_line: news.secondLine } : {}),
          ...(news.expMonth !== undefined ? { exp_month: news.expMonth } : {}),
          ...(news.expYear !== undefined ? { exp_year: news.expYear } : {}),
          ...(news.financialAccount !== undefined
            ? { financial_account: news.financialAccount }
            : {}),
          ...(news.personalizationDesign !== undefined
            ? { personalization_design: news.personalizationDesign }
            : {}),
          ...(news.replacementFor !== undefined ? { replacement_for: news.replacementFor } : {}),
          ...(news.replacementReason !== undefined
            ? { replacement_reason: news.replacementReason }
            : {}),
          ...(spendingControls !== undefined ? { spending_controls: spendingControls } : {}),
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-issuing-card-${instanceId}`,
          }),
        );
      }

      if (current === undefined) {
        return yield* new IssuingCardNotResolved({
          cardholder: news.cardholder,
          currency: news.currency,
        });
      }

      const observedMetadata = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMetadata, metadata);
      const metadataChanged = upsert.length > 0 || removed.length > 0;
      const statusChanged = current.status !== desiredStatus;
      const personalizationChanged =
        news.personalizationDesign !== undefined &&
        expandedId(current.personalization_design) !== news.personalizationDesign;
      const spendingChanged =
        news.spendingControls !== undefined &&
        !deepEqual(news.spendingControls, toSpendingControls(current.spending_controls), {
          stripNullish: true,
        });

      if (!statusChanged && !personalizationChanged && !spendingChanged && !metadataChanged) {
        return toAttrs(current);
      }

      const updated = yield* UpdateIssuingCard({
        card: current.id,
        ...(statusChanged ? { status: desiredStatus } : {}),
        ...(personalizationChanged ? { personalization_design: news.personalizationDesign } : {}),
        ...(spendingChanged ? { spending_controls: spendingControls } : {}),
        ...(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* getByIdAny(output.id);
      if (existing === undefined || existing.status === "canceled") return;
      yield* UpdateIssuingCard({
        card: existing.id,
        status: "canceled",
      }).pipe(Effect.catchIf(isMissingCard, () => Effect.void));
    }),
  });