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

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  GetPromotionCodes,
  GetPromotionCode,
  CreatePromotionCode,
  UpdatePromotionCode,
  type CreatePromotionCodeRequestRestrictions,
  type CreatePromotionCodeRequestRestrictionsCurrencyOptionsMap,
  type PromotionCode as StripePromotionCode,
} 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 { recordsEqual } from "alchemy/Util/equal";
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";

export interface PromotionCodeCurrencyOption {
  /**
   * Minimum amount (in the currency's minor units) required to redeem this
   * promotion code.
   */
  minimumAmount: number;
}

export interface PromotionCodeRestrictions {
  /**
   * When true, the code can only be redeemed by customers with no successful
   * payments or invoices. Create-only — changing it replaces the code.
   */
  firstTimeTransaction?: boolean;
  /**
   * Minimum amount required to redeem this code. Create-only.
   */
  minimumAmount?: number;
  /**
   * Three-letter ISO currency code for `minimumAmount`. Create-only.
   */
  minimumAmountCurrency?: string;
  /**
   * Per-currency minimum amounts. Mutable on update.
   */
  currencyOptions?: Record<string, PromotionCodeCurrencyOption>;
}

export interface PromotionCodeProps {
  /**
   * Id of the coupon this promotion code redeems. Changing it replaces
   * the promotion code.
   */
  coupon: string;
  /**
   * Customer-facing code. Unique among active promotion codes (case
   * insensitive). Valid characters: `A-Z`, `a-z`, `0-9`, `-`. If omitted,
   * a unique code is generated from the stack, stage, and logical id.
   * Changing it replaces the promotion code.
   */
  code?: string;
  /**
   * Whether the promotion code can currently be redeemed.
   * @default true
   */
  active?: boolean;
  /**
   * Restrict redemption to this customer id. Create-only.
   */
  customer?: string;
  /**
   * Restrict redemption to this customer account id. Create-only.
   */
  customerAccount?: string;
  /**
   * Unix timestamp after which the code can no longer be redeemed.
   * Create-only.
   */
  expiresAt?: number;
  /**
   * Maximum number of times this code can be redeemed. Create-only.
   */
  maxRedemptions?: number;
  /**
   * User metadata. Alchemy ownership keys (`alchemy_stack`,
   * `alchemy_stage`, `alchemy_id`) are merged in automatically. Keys
   * cannot contain `:`.
   */
  metadata?: Record<string, string>;
  /**
   * Redemption restrictions.
   */
  restrictions?: PromotionCodeRestrictions;
}

export interface PromotionCode extends Resource<
  "Stripe.PromotionCode",
  PromotionCodeProps,
  {
    /** Stripe promotion code id (`promo_…`). */
    id: string;
    /** Customer-facing code. */
    code: string;
    /** Whether the code is currently redeemable. */
    active: boolean;
    /** Coupon id this code points at. */
    couponId: string;
    /** Restricted customer id, if any. */
    customer: string | undefined;
    /** Restricted customer account id, if any. */
    customerAccount: string | undefined;
    /** Unix expiry timestamp, if any. */
    expiresAt: number | undefined;
    /** Whether this object exists in live mode. */
    livemode: boolean;
    /** Maximum redemptions, if any. */
    maxRedemptions: number | undefined;
    /** Times this code has been redeemed. */
    timesRedeemed: number;
    /** Unix creation timestamp. */
    created: number;
    /** User metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Current redemption restrictions. */
    restrictions: PromotionCodeRestrictions;
  },
  never,
  Providers
> {}

/**
 * A Stripe Promotion Code — a customer-redeemable code for an underlying
 * coupon. Stripe does not hard-delete promotion codes; destroying this
 * resource deactivates it (`active: false`).
 *
 * `code`, `coupon`, `customer`, `expiresAt`, `maxRedemptions`, and most
 * restrictions are immutable. Changing them replaces the promotion code
 * (create a new one, then deactivate the old). `active`, `metadata`, and
 * `restrictions.currencyOptions` update in place.
 *
 * @see https://docs.stripe.com/api/promotion_codes
 *
 * ### Creating a Promotion Code
 * **Example:** Code for an existing coupon
 * ```typescript
 * const welcome = yield* Stripe.PromotionCode("welcome", {
 *   coupon: "25OFF",
 *   code: "WELCOME25",
 * });
 * ```
 *
 * **Example:** Generated code with a redemption cap
 * ```typescript
 * const launch = yield* Stripe.PromotionCode("launch", {
 *   coupon: "10OFF",
 *   maxRedemptions: 100,
 *   metadata: { campaign: "launch" },
 * });
 * ```
 *
 * ### Updating a Promotion Code
 * **Example:** Pause redemptions and update metadata
 * ```typescript
 * const welcome = yield* Stripe.PromotionCode("welcome", {
 *   coupon: "25OFF",
 *   code: "WELCOME25",
 *   active: false,
 *   metadata: { campaign: "paused" },
 * });
 * ```
 *
 * ### Deactivating a Promotion Code
 * **Example:** Destroy deactivates rather than deleting
 * ```typescript
 * // stack.destroy() / resource removal sets active: false
 * const welcome = yield* Stripe.PromotionCode("welcome", {
 *   coupon: "25OFF",
 *   code: "WELCOME25",
 * });
 * ```
 *
 * @resource
 * @product Product
 */
export const PromotionCode = Resource<PromotionCode>("Stripe.PromotionCode");

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

type PromotionCodeAttributes = PromotionCode["Attributes"];

const CODE_MAX_LENGTH = 40;
const LIST_PAGE_SIZE = 100;
const LIST_MAX_PAGES = 100;

const idOf = (value: unknown): string | undefined => {
  if (typeof value === "string") return value;
  if (value !== null && typeof value === "object" && "id" in value) {
    const id = (value as { id?: unknown }).id;
    if (typeof id === "string") return id;
  }
  return undefined;
};

const couponIdOf = (promo: StripePromotionCode): string => idOf(promo.promotion?.coupon) ?? "";

const fromWireCurrencyOptions = (
  options: StripePromotionCode["restrictions"]["currency_options"] | undefined,
): Record<string, PromotionCodeCurrencyOption> | undefined => {
  if (options === undefined) return undefined;
  const out: Record<string, PromotionCodeCurrencyOption> = {};
  for (const [currency, value] of Object.entries(options)) {
    if (value === undefined) continue;
    out[currency] = { minimumAmount: value.minimum_amount };
  }
  return Object.keys(out).length > 0 ? out : undefined;
};

const toWireCurrencyOptions = (
  options: Record<string, PromotionCodeCurrencyOption> | undefined,
): CreatePromotionCodeRequestRestrictionsCurrencyOptionsMap | undefined => {
  if (options === undefined) return undefined;
  return Object.fromEntries(
    Object.entries(options).map(([currency, value]) => [
      currency,
      { minimum_amount: value.minimumAmount },
    ]),
  );
};

const fromObservedRestrictions = (
  restrictions: StripePromotionCode["restrictions"] | undefined,
): PromotionCodeRestrictions => {
  if (restrictions === undefined) return {};
  return {
    firstTimeTransaction: restrictions.first_time_transaction,
    ...(restrictions.minimum_amount != null ? { minimumAmount: restrictions.minimum_amount } : {}),
    ...(restrictions.minimum_amount_currency != null
      ? { minimumAmountCurrency: restrictions.minimum_amount_currency }
      : {}),
    ...(fromWireCurrencyOptions(restrictions.currency_options) !== undefined
      ? {
          currencyOptions: fromWireCurrencyOptions(restrictions.currency_options),
        }
      : {}),
  };
};

const toCreateRestrictions = (
  restrictions: PromotionCodeRestrictions | undefined,
): CreatePromotionCodeRequestRestrictions | undefined => {
  if (restrictions === undefined) return undefined;
  const currency_options = toWireCurrencyOptions(restrictions.currencyOptions);
  const body: CreatePromotionCodeRequestRestrictions = {
    ...(restrictions.firstTimeTransaction !== undefined
      ? { first_time_transaction: restrictions.firstTimeTransaction }
      : {}),
    ...(restrictions.minimumAmount !== undefined
      ? { minimum_amount: restrictions.minimumAmount }
      : {}),
    ...(restrictions.minimumAmountCurrency !== undefined
      ? { minimum_amount_currency: restrictions.minimumAmountCurrency }
      : {}),
    ...(currency_options !== undefined ? { currency_options } : {}),
  };
  return Object.keys(body).length > 0 ? body : undefined;
};

const toAttrs = (promo: StripePromotionCode): PromotionCodeAttributes => ({
  id: promo.id,
  code: promo.code,
  active: promo.active,
  couponId: couponIdOf(promo),
  customer: idOf(promo.customer),
  customerAccount: promo.customer_account ?? undefined,
  expiresAt: promo.expires_at ?? undefined,
  livemode: promo.livemode,
  maxRedemptions: promo.max_redemptions ?? undefined,
  timesRedeemed: promo.times_redeemed,
  created: promo.created,
  metadata: stripInternalMetadata(tagRecord(promo.metadata)),
  restrictions: fromObservedRestrictions(promo.restrictions),
});

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

const isResourceMissing = isMissingStripeResource;

const getById = (promotionCode: string) =>
  GetPromotionCode({
    promotion_code: promotionCode,
    expand: ["promotion.coupon"],
  }).pipe(Effect.catchIf(isResourceMissing, () => Effect.undefined));

const findByCode = (code: string) =>
  Effect.gen(function* () {
    const [active, inactive] = yield* Effect.all(
      [
        GetPromotionCodes({
          code,
          active: true,
          limit: LIST_PAGE_SIZE,
          expand: ["data.promotion.coupon"],
        }),
        GetPromotionCodes({
          code,
          active: false,
          limit: LIST_PAGE_SIZE,
          expand: ["data.promotion.coupon"],
        }),
      ],
      { concurrency: 2 },
    );
    return (
      active.data.find((item) => item.code === code) ??
      inactive.data.find((item) => item.code === code)
    );
  });

const listByActive = Effect.fn(function* (active: boolean) {
  const items: StripePromotionCode[] = [];
  let startingAfter: string | undefined;
  for (let page = 0; page < LIST_MAX_PAGES; page++) {
    const result = yield* GetPromotionCodes({
      active,
      limit: LIST_PAGE_SIZE,
      expand: ["data.promotion.coupon"],
      ...(startingAfter !== undefined ? { starting_after: startingAfter } : {}),
    });
    items.push(...result.data);
    if (!result.has_more || result.data.length === 0) break;
    startingAfter = result.data[result.data.length - 1]?.id;
    if (startingAfter === undefined) break;
  }
  return items;
});

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

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

const replaceOnCreateOnlyChange = (
  olds: PromotionCodeProps | undefined,
  news: PromotionCodeProps,
  output: PromotionCodeAttributes | undefined,
): boolean => {
  const previousCoupon = output?.couponId || olds?.coupon;
  if (previousCoupon !== undefined && news.coupon !== previousCoupon) {
    return true;
  }
  if (news.code !== undefined && news.code !== (output?.code ?? olds?.code)) {
    return true;
  }
  if ((news.customer ?? undefined) !== (output?.customer ?? olds?.customer)) {
    return true;
  }
  if ((news.customerAccount ?? undefined) !== (output?.customerAccount ?? olds?.customerAccount)) {
    return true;
  }
  if ((news.expiresAt ?? undefined) !== (output?.expiresAt ?? olds?.expiresAt)) {
    return true;
  }
  if ((news.maxRedemptions ?? undefined) !== (output?.maxRedemptions ?? olds?.maxRedemptions)) {
    return true;
  }
  const oldR = olds?.restrictions;
  const newR = news.restrictions;
  const outR = output?.restrictions;
  const desiredFirstTime = newR?.firstTimeTransaction ?? oldR?.firstTimeTransaction ?? false;
  const observedFirstTime = outR?.firstTimeTransaction ?? oldR?.firstTimeTransaction ?? false;
  if (desiredFirstTime !== observedFirstTime) {
    return true;
  }
  if (
    (newR?.minimumAmount ?? oldR?.minimumAmount) !== (outR?.minimumAmount ?? oldR?.minimumAmount)
  ) {
    return true;
  }
  if (
    (newR?.minimumAmountCurrency ?? oldR?.minimumAmountCurrency) !==
    (outR?.minimumAmountCurrency ?? oldR?.minimumAmountCurrency)
  ) {
    return true;
  }
  return false;
};

export const PromotionCodeProvider = () =>
  Provider.succeed(PromotionCode, {
    stables: ["id", "code", "couponId", "created", "livemode"],

    list: Effect.fn(function* () {
      // Promotion codes cannot be deleted; delete deactivates them. Inactive
      // rows are effectively deleted and must not re-enter nuke.
      const items = yield* listByActive(true);
      return items
        .filter((item) => tagRecord(item.metadata)[alchemyMetadataKeys.stack] !== undefined)
        .map(toAttrs);
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      if (replaceOnCreateOnlyChange(olds, news, output)) {
        const previousCode = output?.code ?? olds?.code;
        const nextCode = news.code ?? previousCode;
        return {
          action: "replace" as const,
          deleteFirst: nextCode !== undefined && nextCode === previousCode,
        };
      }
      if ((news.active ?? true) !== (output?.active ?? olds?.active ?? true)) {
        return { action: "update" } as const;
      }
      if (!recordsEqual(news.metadata ?? {}, olds?.metadata ?? {})) {
        return { action: "update" } as const;
      }
      if (
        !deepEqual(
          news.restrictions?.currencyOptions,
          olds?.restrictions?.currencyOptions ?? output?.restrictions.currencyOptions,
          { stripNullish: true },
        )
      ) {
        return { action: "update" } as const;
      }
      return undefined;
    }),

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

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const code = yield* toCode(id, news.code, output?.code);
      const metadata = yield* desiredMetadata(id, news.metadata);
      const active = news.active ?? true;
      const createRestrictions = toCreateRestrictions(news.restrictions);

      let current = yield* observe({ id: output?.id, code });
      // A leftover inactive code with this customer-facing `code` may point
      // at a deleted coupon. Stripe forbids reactivating it — treat it as
      // missing and create a new promotion code instead.
      if (current !== undefined) {
        const observedCoupon = couponIdOf(current);
        if (observedCoupon !== "" && observedCoupon !== news.coupon) {
          current = undefined;
        }
      }

      if (current === undefined) {
        current = yield* CreatePromotionCode({
          promotion: { type: "coupon", coupon: news.coupon },
          expand: ["promotion.coupon"],
          code,
          active,
          ...(news.customer !== undefined ? { customer: news.customer } : {}),
          ...(news.customerAccount !== undefined ? { customer_account: news.customerAccount } : {}),
          ...(news.expiresAt !== undefined ? { expires_at: news.expiresAt } : {}),
          ...(news.maxRedemptions !== undefined ? { max_redemptions: news.maxRedemptions } : {}),
          metadata,
          ...(createRestrictions !== undefined ? { restrictions: createRestrictions } : {}),
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-promotion-code-${instanceId}`,
          }),
          Effect.catchTag("InvalidRequestError", (error) =>
            observe({ id: output?.id, code }).pipe(
              Effect.flatMap((found) =>
                found !== undefined && couponIdOf(found) === news.coupon
                  ? Effect.succeed(found)
                  : Effect.fail(error),
              ),
            ),
          ),
        );
      }

      if (current === undefined) {
        return yield* new PromotionCodeNotResolved({ code });
      }

      if (current.active !== active) {
        current = yield* UpdatePromotionCode({
          promotion_code: current.id,
          active,
        });
      }

      const observedMeta = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMeta, metadata);
      if (upsert.length > 0 || removed.length > 0) {
        current = yield* UpdatePromotionCode({
          promotion_code: current.id,
          metadata: {
            ...Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value])),
            ...Object.fromEntries(removed.map((key) => [key, ""])),
          },
        });
      }

      const desiredCurrency = news.restrictions?.currencyOptions;
      const observedCurrency = fromWireCurrencyOptions(current.restrictions.currency_options);
      if (
        desiredCurrency !== undefined &&
        !deepEqual(desiredCurrency, observedCurrency, { stripNullish: true })
      ) {
        current = yield* UpdatePromotionCode({
          promotion_code: current.id,
          restrictions: {
            currency_options: toWireCurrencyOptions(desiredCurrency),
          },
        });
      }

      const attrs = toAttrs(current);
      return {
        ...attrs,
        couponId: attrs.couponId || news.coupon,
      };
    }),

    delete: Effect.fn(function* ({ output }) {
      const existing = yield* observe({ id: output.id, code: output.code });
      if (existing === undefined || !existing.active) return;
      yield* UpdatePromotionCode({
        promotion_code: existing.id,
        active: false,
      }).pipe(Effect.catchIf(isResourceMissing, () => Effect.void));
    }),
  });