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

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  DeleteCoupon,
  GetCoupons,
  GetCoupon,
  CreateCoupon,
  UpdateCoupon,
  type Coupon as StripeCoupon,
  type CreateCouponRequestCurrencyOptionsMap,
} 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;

/** How long a customer who applies this coupon keeps the discount. */
export type CouponDuration = "forever" | "once" | "repeating";

export interface CouponAppliesTo {
  /**
   * Product ids this coupon applies to. Create-only — changing it
   * replaces the coupon.
   */
  products?: string[];
}

export interface CouponCurrencyOption {
  /**
   * Amount (in the currency's minor units) taken off the invoice subtotal.
   */
  amountOff: number;
}

export interface CouponProps {
  /**
   * Unique coupon id (the code used when applying the coupon). If omitted,
   * Stripe generates one. Changing it replaces the coupon.
   */
  couponId?: string;
  /**
   * Name displayed to customers on invoices and receipts. Defaults to the
   * coupon id if omitted. Mutable.
   */
  name?: string;
  /**
   * Percent taken off the invoice subtotal (0–100). Required unless
   * `amountOff` is set. Create-only — changing it replaces the coupon.
   */
  percentOff?: number;
  /**
   * Amount (in `currency` minor units) taken off the invoice subtotal.
   * Required unless `percentOff` is set. Create-only — changing it
   * replaces the coupon.
   */
  amountOff?: number;
  /**
   * Three-letter ISO currency code for `amountOff`. Required when
   * `amountOff` is set. Create-only — changing it replaces the coupon.
   */
  currency?: string;
  /**
   * Per-currency `amountOff` values (amount-based coupons only). Mutable.
   */
  currencyOptions?: Record<string, CouponCurrencyOption>;
  /**
   * How long the discount lasts when applied to a subscription.
   * @default "once"
   */
  duration?: CouponDuration;
  /**
   * Months the discount lasts when `duration` is `repeating`. Create-only.
   */
  durationInMonths?: number;
  /**
   * Maximum redemptions across all customers. Create-only.
   */
  maxRedemptions?: number;
  /**
   * Unix timestamp after which the coupon can no longer be redeemed.
   * Create-only.
   */
  redeemBy?: number;
  /**
   * Restrict the coupon to specific products. Create-only.
   */
  appliesTo?: CouponAppliesTo;
  /**
   * 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 Coupon = Resource<
  "Stripe.Coupon",
  CouponProps,
  {
    /** Stripe coupon id (the redeemable code). */
    id: string;
    /** Name displayed to customers, if set. */
    name: string | undefined;
    /** Percent-off discount, if this is a percent coupon. */
    percentOff: number | undefined;
    /** Amount-off discount (minor units), if this is an amount coupon. */
    amountOff: number | undefined;
    /** Currency of `amountOff`, if this is an amount coupon. */
    currency: string | undefined;
    /** Per-currency amount-off values, if set. */
    currencyOptions: Record<string, CouponCurrencyOption> | undefined;
    /** How long the discount lasts. */
    duration: CouponDuration;
    /** Months the discount lasts when `duration` is `repeating`. */
    durationInMonths: number | undefined;
    /** Maximum redemptions, if set. */
    maxRedemptions: number | undefined;
    /** Unix timestamp after which the coupon cannot be redeemed. */
    redeemBy: number | undefined;
    /** Products this coupon applies to, if restricted. */
    appliesTo: CouponAppliesTo | undefined;
    /** Whether the coupon can still be applied. */
    valid: boolean;
    /** Times this coupon has been redeemed. */
    timesRedeemed: number;
    /** Unix timestamp when the coupon was created. */
    created: number;
    /** Whether the coupon exists in live mode. */
    livemode: boolean;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
  },
  never,
  Providers
>;

/**
 * A Stripe Coupon — a percent-off or amount-off discount applied to
 * subscriptions, invoices, Checkout sessions, and quotes. Coupons do not
 * apply to one-off charges or PaymentIntents.
 *
 * Create with either `percentOff` or `amountOff` + `currency`. `duration`
 * is `forever`, `once` (the default), or `repeating` (requires
 * `durationInMonths`). Name, metadata, and `currencyOptions` update in
 * place; the discount shape is immutable and changing it replaces the
 * coupon.
 *
 * @see https://docs.stripe.com/api/coupons
 *
 * ### Creating a Coupon
 * **Example:** Percent-off forever
 * ```typescript
 * const welcome = yield* Stripe.Coupon("welcome", {
 *   percentOff: 20,
 *   duration: "forever",
 *   name: "Welcome 20%",
 * });
 * ```
 *
 * **Example:** Amount-off once
 * ```typescript
 * const fiveOff = yield* Stripe.Coupon("five-off", {
 *   amountOff: 500,
 *   currency: "usd",
 *   duration: "once",
 *   name: "$5 off",
 * });
 * ```
 *
 * ### Repeating duration
 * **Example:** 10% off for three months
 * ```typescript
 * const quarterly = yield* Stripe.Coupon("quarterly", {
 *   percentOff: 10,
 *   duration: "repeating",
 *   durationInMonths: 3,
 * });
 * ```
 *
 * ### Updating a Coupon
 * **Example:** Rename and retag
 * ```typescript
 * const welcome = yield* Stripe.Coupon("welcome", {
 *   percentOff: 20,
 *   duration: "forever",
 *   name: "Welcome 20% (updated)",
 *   metadata: { campaign: "spring" },
 * });
 * ```
 *
 * @resource
 * @product Product
 */
export const Coupon = Resource<Coupon>("Stripe.Coupon");

export class CouponNotResolved extends Data.TaggedError("Stripe.CouponNotResolved")<{
  couponId: string | undefined;
}> {}

type CouponAttributes = Coupon["Attributes"];

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

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

const toWireCurrencyOptions = (
  options: Record<string, CouponCurrencyOption> | undefined,
): CreateCouponRequestCurrencyOptionsMap | undefined => {
  if (options === undefined) return undefined;
  return Object.fromEntries(
    Object.entries(options).map(([currency, value]) => [currency, { amount_off: value.amountOff }]),
  );
};

const fromObservedAppliesTo = (
  appliesTo: StripeCoupon["applies_to"] | undefined,
): CouponAppliesTo | undefined => {
  if (appliesTo === undefined) return undefined;
  return { products: appliesTo.products };
};

const toAttrs = (coupon: StripeCoupon): CouponAttributes => ({
  id: coupon.id,
  name: coupon.name ?? undefined,
  percentOff: coupon.percent_off ?? undefined,
  amountOff: coupon.amount_off ?? undefined,
  currency: coupon.currency ?? undefined,
  currencyOptions: fromWireCurrencyOptions(coupon.currency_options),
  duration: coupon.duration,
  durationInMonths: coupon.duration_in_months ?? undefined,
  maxRedemptions: coupon.max_redemptions ?? undefined,
  redeemBy: coupon.redeem_by ?? undefined,
  appliesTo: fromObservedAppliesTo(coupon.applies_to),
  valid: coupon.valid,
  timesRedeemed: coupon.times_redeemed,
  created: coupon.created,
  livemode: coupon.livemode,
  metadata: userMetadata(coupon.metadata),
});

const isMissingCoupon = isMissingStripeResource;

const getById = (coupon: string) =>
  GetCoupon({ coupon }).pipe(Effect.catchIf(isMissingCoupon, () => Effect.undefined));

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

const findByAlchemyId = Effect.fn(function* (id: string) {
  const coupons = yield* listAllCoupons();
  const matches: StripeCoupon[] = [];
  for (const coupon of coupons) {
    if (yield* hasAlchemyMetadata(id, tagRecord(coupon.metadata))) {
      matches.push(coupon);
    }
  }
  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 replaceOnCreateOnlyChange = (
  olds: CouponProps | undefined,
  news: CouponProps,
  output: CouponAttributes | undefined,
): boolean => {
  if (news.couponId !== undefined && news.couponId !== (output?.id ?? olds?.couponId)) {
    return true;
  }
  if (
    (news.percentOff ?? output?.percentOff ?? olds?.percentOff) !==
    (output?.percentOff ?? olds?.percentOff)
  ) {
    return true;
  }
  if (
    (news.amountOff ?? output?.amountOff ?? olds?.amountOff) !==
    (output?.amountOff ?? olds?.amountOff)
  ) {
    return true;
  }
  if (
    (news.currency ?? output?.currency ?? olds?.currency) !== (output?.currency ?? olds?.currency)
  ) {
    return true;
  }
  if (
    (news.duration ?? output?.duration ?? olds?.duration ?? "once") !==
    (output?.duration ?? olds?.duration ?? "once")
  ) {
    return true;
  }
  if (
    (news.durationInMonths ?? output?.durationInMonths ?? olds?.durationInMonths) !==
    (output?.durationInMonths ?? olds?.durationInMonths)
  ) {
    return true;
  }
  if (
    (news.maxRedemptions ?? output?.maxRedemptions ?? olds?.maxRedemptions) !==
    (output?.maxRedemptions ?? olds?.maxRedemptions)
  ) {
    return true;
  }
  if (
    (news.redeemBy ?? output?.redeemBy ?? olds?.redeemBy) !== (output?.redeemBy ?? olds?.redeemBy)
  ) {
    return true;
  }
  if (
    news.appliesTo !== undefined &&
    !deepEqual(news.appliesTo, output?.appliesTo ?? olds?.appliesTo, {
      stripNullish: true,
    })
  ) {
    return true;
  }
  return false;
};

export const CouponProvider = () =>
  Provider.succeed(Coupon, {
    stables: [
      "id",
      "percentOff",
      "amountOff",
      "currency",
      "duration",
      "durationInMonths",
      "created",
      "livemode",
    ],

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      if (replaceOnCreateOnlyChange(olds, news, output)) {
        const previousId = output?.id ?? olds?.couponId;
        const nextId = news.couponId ?? previousId;
        return {
          action: "replace" as const,
          deleteFirst: nextId !== undefined && nextId === previousId,
        };
      }
      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* () {
      const coupons = yield* listAllCoupons();
      return coupons
        .filter((coupon) => {
          const metadata = tagRecord(coupon.metadata);
          return metadata[alchemyMetadataKeys.stack] !== undefined;
        })
        .map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const metadata = yield* desiredMetadata(id, news.metadata);
      const currencyOptions = toWireCurrencyOptions(news.currencyOptions);

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

      if (current === undefined) {
        current = yield* CreateCoupon({
          ...(news.couponId !== undefined ? { id: news.couponId } : {}),
          ...(news.name !== undefined ? { name: news.name } : {}),
          ...(news.percentOff !== undefined ? { percent_off: news.percentOff } : {}),
          ...(news.amountOff !== undefined ? { amount_off: news.amountOff } : {}),
          ...(news.currency !== undefined ? { currency: news.currency } : {}),
          ...(currencyOptions !== undefined ? { currency_options: currencyOptions } : {}),
          ...(news.duration !== undefined ? { duration: news.duration } : {}),
          ...(news.durationInMonths !== undefined
            ? { duration_in_months: news.durationInMonths }
            : {}),
          ...(news.maxRedemptions !== undefined ? { max_redemptions: news.maxRedemptions } : {}),
          ...(news.redeemBy !== undefined ? { redeem_by: news.redeemBy } : {}),
          ...(news.appliesTo?.products !== undefined
            ? { applies_to: { products: news.appliesTo.products } }
            : {}),
          metadata,
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-coupon-${instanceId}`,
          }),
        );
      }

      if (current === undefined) {
        return yield* new CouponNotResolved({ couponId: news.couponId });
      }

      const observedMetadata = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMetadata, metadata);
      const metadataChanged = upsert.length > 0 || removed.length > 0;
      const nameChanged = news.name !== undefined && (current.name ?? undefined) !== news.name;
      const observedCurrencyOptions = fromWireCurrencyOptions(current.currency_options);
      const currencyOptionsChanged =
        news.currencyOptions !== undefined &&
        !deepEqual(news.currencyOptions, observedCurrencyOptions, {
          stripNullish: true,
        });

      if (!nameChanged && !metadataChanged && !currencyOptionsChanged) {
        return toAttrs(current);
      }

      const updated = yield* UpdateCoupon({
        coupon: current.id,
        ...(nameChanged ? { name: news.name } : {}),
        ...(currencyOptionsChanged ? { currency_options: currencyOptions } : {}),
        ...(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 }) {
      yield* DeleteCoupon({ coupon: output.id }).pipe(
        Effect.catchIf(isMissingCoupon, () => Effect.void),
      );
    }),
  });