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

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  GetIssuingPersonalizationDesigns,
  GetIssuingPersonalizationDesign,
  CreateIssuingPersonalizationDesign,
  UpdateIssuingPersonalizationDesign,
  type IssuingPersonalizationDesign as StripeIssuingPersonalizationDesign,
  type CreateIssuingPersonalizationDesignRequestCarrierText,
} from "@distilled.cloud/stripe/stripe";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, 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 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 NAME_MAX_LENGTH = 250;
const LOOKUP_KEY_MAX_LENGTH = 200;
const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

/** Whether this personalization design can be used to create cards. */
export type IssuingPersonalizationDesignStatus = "active" | "inactive" | "rejected" | "review";

/** Reason a card logo was rejected. */
export type IssuingPersonalizationDesignCardLogoRejection =
  | "geographic_location"
  | "inappropriate"
  | "network_name"
  | "non_binary_image"
  | "non_fiat_currency"
  | "other"
  | "other_entity"
  | "promotional_material";

/** Reason carrier text was rejected. */
export type IssuingPersonalizationDesignCarrierTextRejection =
  | "geographic_location"
  | "inappropriate"
  | "network_name"
  | "non_fiat_currency"
  | "other"
  | "other_entity"
  | "promotional_material";

/**
 * Carrier-letter copy for physical bundles that support carrier text.
 */
export interface IssuingPersonalizationDesignCarrierText {
  /**
   * Footer body text of the carrier letter.
   */
  footerBody?: string;
  /**
   * Footer title text of the carrier letter.
   */
  footerTitle?: string;
  /**
   * Header body text of the carrier letter.
   */
  headerBody?: string;
  /**
   * Header title text of the carrier letter.
   */
  headerTitle?: string;
}

/**
 * Whether this design is used when a card is created without a
 * personalization design.
 */
export interface IssuingPersonalizationDesignPreferences {
  /**
   * When true, Stripe uses this design to create cards when one isn't
   * specified. Connected accounts fall back to the platform default if
   * none is set.
   * @default false
   */
  isDefault?: boolean;
}

export interface IssuingPersonalizationDesignProps {
  /**
   * Id of the physical bundle (`ics_…`) this design ships with. Required.
   * Mutable — changing it updates the design in place.
   */
  physicalBundle: string;
  /**
   * Friendly display name. If omitted, a unique name is generated from
   * the stack, stage, and logical id. Mutable.
   */
  name?: string;
  /**
   * Lookup key used to retrieve this design from a static string. Unique
   * per account, max 200 characters. If omitted, a unique key is
   * generated. Mutable — a change transfers the key onto this design.
   */
  lookupKey?: string;
  /**
   * File id (`file_…`) of the card logo. Must have purpose
   * `issuing_logo` (PNG, 1000×200, black on white). Mutable.
   */
  cardLogo?: string;
  /**
   * Carrier-letter copy. Omit or leave empty to clear. Mutable.
   */
  carrierText?: IssuingPersonalizationDesignCarrierText;
  /**
   * Default-design preference. Mutable.
   */
  preferences?: IssuingPersonalizationDesignPreferences;
  /**
   * 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 IssuingPersonalizationDesign = Resource<
  "Stripe.IssuingPersonalizationDesign",
  IssuingPersonalizationDesignProps,
  {
    /** Stripe personalization design id (`ipcd_…`). */
    id: string;
    /** Friendly display name. */
    name: string;
    /** Lookup key used to retrieve this design dynamically. */
    lookupKey: string | undefined;
    /** Physical bundle id (`ics_…`). */
    physicalBundle: string;
    /** Card logo file id, if set. */
    cardLogo: string | undefined;
    /** Carrier-letter copy, if set. */
    carrierText: IssuingPersonalizationDesignCarrierText | undefined;
    /** Whether this design is the account default. */
    isDefault: boolean;
    /**
     * Whether this design is the Connect platform default. Null on
     * non-connected accounts.
     */
    isPlatformDefault: boolean | undefined;
    /** Whether this design can be used to create cards. */
    status: IssuingPersonalizationDesignStatus;
    /** Reasons the card logo was rejected, if any. */
    cardLogoRejectionReasons: IssuingPersonalizationDesignCardLogoRejection[] | undefined;
    /** Reasons the carrier text was rejected, if any. */
    carrierTextRejectionReasons: IssuingPersonalizationDesignCarrierTextRejection[] | undefined;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Unix timestamp when the design was created. */
    created: number;
    /** Whether the design exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Issuing Personalization Design — a physical bundle, optional
 * card logo, and optional carrier text that represent a card product
 * line. Name, lookup key, logo, carrier text, physical bundle,
 * preferences, and metadata update in place.
 *
 * Stripe has no delete, archive, or deactivate API for personalization
 * designs. Destroy is a no-op; the design remains as residue on the
 * account (still listed by `list()` via Alchemy metadata). Account-wide
 * nuke skips this type.
 *
 * Creating designs requires the Stripe Issuing entitlement.
 *
 * @see https://docs.stripe.com/api/issuing/personalization-designs
 *
 * ### Creating a Personalization Design
 * **Example:** Named design on a physical bundle
 * ```typescript
 * const design = yield* Stripe.IssuingPersonalizationDesign("metal-card", {
 *   physicalBundle: "ics_Fiiwz3T83opOUd",
 *   name: "Metal Card",
 * });
 * ```
 *
 * **Example:** Lookup key, carrier text, and metadata
 * ```typescript
 * const design = yield* Stripe.IssuingPersonalizationDesign("metal-card", {
 *   physicalBundle: "ics_Fiiwz3T83opOUd",
 *   name: "Metal Card",
 *   lookupKey: "metal_card_v1",
 *   carrierText: {
 *     headerTitle: "Welcome",
 *     headerBody: "Your card is on its way.",
 *   },
 *   metadata: { line: "metal" },
 * });
 * ```
 *
 * ### Updating a Personalization Design
 * **Example:** Rename and retag
 * ```typescript
 * const design = yield* Stripe.IssuingPersonalizationDesign("metal-card", {
 *   physicalBundle: "ics_Fiiwz3T83opOUd",
 *   name: "Metal Card v2",
 *   lookupKey: "metal_card_v1",
 *   metadata: { line: "metal", version: "2" },
 * });
 * ```
 *
 * ### Retrieving a Personalization Design
 * **Example:** Bind and retrieve
 * ```typescript
 * const retrieve = yield* Stripe.RetrieveIssuingPersonalizationDesign(design);
 * const live = yield* retrieve();
 * ```
 *
 * ### Destroying a Personalization Design
 * **Example:** Destroy is a no-op
 * ```typescript
 * // stack.destroy() leaves the Stripe object in place — there is no
 * // delete/archive API. Residue stays tagged with alchemy_stack.
 * const design = yield* Stripe.IssuingPersonalizationDesign("metal-card", {
 *   physicalBundle: "ics_Fiiwz3T83opOUd",
 *   name: "Metal Card",
 * });
 * ```
 *
 * @resource
 * @product Issuing
 */
export const IssuingPersonalizationDesign = Resource<IssuingPersonalizationDesign>(
  "Stripe.IssuingPersonalizationDesign",
);

type IssuingPersonalizationDesignAttributes = IssuingPersonalizationDesign["Attributes"];

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

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

const toLookupKey = (id: string, lookupKey: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (lookupKey !== undefined && lookupKey.length > 0) return lookupKey;
    if (existing !== undefined && existing.length > 0) return existing;
    return yield* createPhysicalName({
      id,
      maxLength: LOOKUP_KEY_MAX_LENGTH,
      lowercase: true,
    });
  });

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

const compactCarrierText = (
  input:
    | {
        footerBody?: string | null;
        footerTitle?: string | null;
        headerBody?: string | null;
        headerTitle?: string | null;
      }
    | null
    | undefined,
): IssuingPersonalizationDesignCarrierText | undefined => {
  if (input == null) return undefined;
  const out: IssuingPersonalizationDesignCarrierText = {};
  if (input.footerBody) out.footerBody = input.footerBody;
  if (input.footerTitle) out.footerTitle = input.footerTitle;
  if (input.headerBody) out.headerBody = input.headerBody;
  if (input.headerTitle) out.headerTitle = input.headerTitle;
  return Object.keys(out).length > 0 ? out : undefined;
};

const fromObservedCarrierText = (
  value: StripeIssuingPersonalizationDesign["carrier_text"],
): IssuingPersonalizationDesignCarrierText | undefined =>
  compactCarrierText(
    value == null
      ? undefined
      : {
          footerBody: value.footer_body,
          footerTitle: value.footer_title,
          headerBody: value.header_body,
          headerTitle: value.header_title,
        },
  );

const toWireCarrierText = (
  input: IssuingPersonalizationDesignCarrierText,
): CreateIssuingPersonalizationDesignRequestCarrierText => ({
  ...(input.footerBody !== undefined ? { footer_body: input.footerBody } : {}),
  ...(input.footerTitle !== undefined ? { footer_title: input.footerTitle } : {}),
  ...(input.headerBody !== undefined ? { header_body: input.headerBody } : {}),
  ...(input.headerTitle !== undefined ? { header_title: input.headerTitle } : {}),
});

const toAttrs = (
  design: StripeIssuingPersonalizationDesign,
): IssuingPersonalizationDesignAttributes => ({
  id: design.id,
  name: design.name ?? "",
  lookupKey: design.lookup_key ?? undefined,
  physicalBundle: idOf(design.physical_bundle) ?? "",
  cardLogo: idOf(design.card_logo),
  carrierText: fromObservedCarrierText(design.carrier_text),
  isDefault: design.preferences.is_default,
  isPlatformDefault: design.preferences.is_platform_default ?? undefined,
  status: design.status,
  cardLogoRejectionReasons: design.rejection_reasons.card_logo ?? undefined,
  carrierTextRejectionReasons: design.rejection_reasons.carrier_text ?? undefined,
  metadata: userMetadata(design.metadata),
  created: design.created,
  livemode: design.livemode,
});

const isMissingDesign = isMissingStripeResource;

const getById = (personalizationDesign: string) =>
  GetIssuingPersonalizationDesign({
    personalization_design: personalizationDesign,
  }).pipe(Effect.catchIf(isMissingDesign, () => Effect.undefined));

const findByLookupKey = Effect.fn(function* (lookupKey: string) {
  const response = yield* GetIssuingPersonalizationDesigns({
    lookup_keys: [lookupKey],
    limit: 1,
  });
  return response.data[0];
});

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

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

const observe = Effect.fn(function* (input: {
  id?: string;
  logicalId: string;
  lookupKey?: string;
}) {
  if (input.id !== undefined) {
    const byId = yield* getById(input.id);
    if (byId !== undefined) return byId;
  }
  if (input.lookupKey !== undefined) {
    const byKey = yield* findByLookupKey(input.lookupKey);
    if (
      byKey !== undefined &&
      (yield* hasAlchemyMetadata(input.logicalId, tagRecord(byKey.metadata)))
    ) {
      return byKey;
    }
  }
  return yield* findByAlchemyId(input.logicalId);
});

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

export const IssuingPersonalizationDesignProvider = () =>
  Provider.succeed(IssuingPersonalizationDesign, {
    stables: ["id", "created", "livemode"],
    // Stripe has no delete/archive API; residue would reappear every nuke.
    nuke: { skip: true },

    diff: Effect.fn(function* ({ news }) {
      if (!isResolved(news)) return undefined;
      return undefined;
    }),

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

    list: Effect.fn(function* () {
      const designs = yield* listAllDesigns();
      return designs
        .filter((design) => {
          const metadata = tagRecord(design.metadata);
          return metadata[alchemyMetadataKeys.stack] !== undefined;
        })
        .map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const name = yield* toName(id, news.name, output?.name);
      const lookupKey = yield* toLookupKey(id, news.lookupKey, output?.lookupKey);
      const metadata = yield* desiredMetadata(id, news.metadata);
      const desiredCardLogo = news.cardLogo;
      const desiredCarrierText = compactCarrierText(news.carrierText);
      const desiredIsDefault = news.preferences?.isDefault ?? false;
      const desiredPhysicalBundle = news.physicalBundle;

      let current = yield* observe({
        id: output?.id,
        logicalId: id,
        lookupKey,
      });

      if (current === undefined) {
        current = yield* CreateIssuingPersonalizationDesign({
          physical_bundle: desiredPhysicalBundle,
          name,
          lookup_key: lookupKey,
          transfer_lookup_key: true,
          metadata,
          ...(desiredCardLogo !== undefined ? { card_logo: desiredCardLogo } : {}),
          ...(desiredCarrierText !== undefined
            ? { carrier_text: toWireCarrierText(desiredCarrierText) }
            : {}),
          ...(desiredIsDefault ? { preferences: { is_default: true } } : {}),
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-issuing-personalization-design-${instanceId}`,
          }),
        );
      }

      const observedMetadata = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMetadata, metadata);
      const metadataChanged = upsert.length > 0 || removed.length > 0;
      const nameChanged = (current.name ?? "") !== name;
      const lookupKeyChanged = (current.lookup_key ?? "") !== lookupKey;
      const physicalBundleChanged = (idOf(current.physical_bundle) ?? "") !== desiredPhysicalBundle;
      const cardLogoChanged = (idOf(current.card_logo) ?? "") !== (desiredCardLogo ?? "");
      const carrierTextChanged = !deepEqual(
        fromObservedCarrierText(current.carrier_text),
        desiredCarrierText,
        { stripNullish: true },
      );
      const preferencesChanged = current.preferences.is_default !== desiredIsDefault;

      if (
        !nameChanged &&
        !lookupKeyChanged &&
        !physicalBundleChanged &&
        !cardLogoChanged &&
        !carrierTextChanged &&
        !preferencesChanged &&
        !metadataChanged
      ) {
        return toAttrs(current);
      }

      const updated = yield* UpdateIssuingPersonalizationDesign({
        personalization_design: current.id,
        ...(nameChanged ? { name } : {}),
        ...(lookupKeyChanged ? { lookup_key: lookupKey, transfer_lookup_key: true } : {}),
        ...(physicalBundleChanged ? { physical_bundle: desiredPhysicalBundle } : {}),
        ...(cardLogoChanged
          ? {
              card_logo: desiredCardLogo !== undefined ? desiredCardLogo : "",
            }
          : {}),
        ...(carrierTextChanged
          ? {
              carrier_text:
                desiredCarrierText !== undefined ? toWireCarrierText(desiredCarrierText) : "",
            }
          : {}),
        ...(preferencesChanged ? { preferences: { is_default: desiredIsDefault } } : {}),
        ...(metadataChanged
          ? {
              metadata: {
                ...Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value])),
                ...Object.fromEntries(removed.map((key) => [key, ""])),
              },
            }
          : {}),
      });
      return toAttrs(updated);
    }),

    delete: Effect.fn(function* (_input) {
      // Stripe has no delete, archive, or deactivate API for Issuing
      // Personalization Designs. Destroy is a no-op; the object remains
      // as residue on the account.
      yield* Effect.void;
    }),
  });