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

import { withRequestOptions } from "@distilled.cloud/stripe";
import {
  DeletePlan,
  GetPlans,
  GetPlan,
  CreatePlan,
  UpdatePlan,
  type Plan as StripePlan,
  type PlanProduct,
} from "@distilled.cloud/stripe/stripe";
import { Unowned } from "alchemy/AdoptPolicy";
import { 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;

/** Billing frequency for a legacy Stripe Plan. */
export type PlanInterval = "day" | "month" | "week" | "year";
/** How quantity per period is determined. */
export type PlanUsageType = "licensed" | "metered";
/** How the price per period is computed. */
export type PlanBillingScheme = "per_unit" | "tiered";

export interface PlanProps {
  /**
   * Id of the Stripe Product this plan belongs to (`prod_…`). Mutable
   * until the plan has been used on a subscription.
   */
  product: string;
  /**
   * Three-letter ISO currency code, lowercase (e.g. `"usd"`). Create-only
   * — changing it replaces the plan.
   */
  currency: string;
  /**
   * Billing frequency. Create-only — changing it replaces the plan.
   */
  interval: PlanInterval;
  /**
   * Number of intervals between billings. Maximum of three years
   * (`3` years, `36` months, or `156` weeks). Create-only.
   * @default 1
   */
  intervalCount?: number;
  /**
   * Amount in the currency's minor units (e.g. cents). `0` is a free
   * plan. Required unless `amountDecimal` is set or the plan is tiered.
   * Create-only — changing it replaces the plan.
   */
  amount?: number;
  /**
   * Decimal amount in the currency's minor units, at most 12 decimal
   * places. Mutually exclusive with `amount`. Create-only.
   */
  amountDecimal?: string;
  /**
   * Brief description of the plan, hidden from customers.
   */
  nickname?: string;
  /**
   * Whether the plan can be used for new subscriptions.
   * @default true
   */
  active?: boolean;
  /**
   * Default trial length (days) when subscribing with
   * `trial_from_plan=true`. Mutable.
   */
  trialPeriodDays?: number;
  /**
   * How quantity per period is determined. `licensed` bills the
   * subscription quantity; `metered` aggregates usage records. Create-only.
   * @default "licensed"
   */
  usageType?: PlanUsageType;
  /**
   * How the price per period is computed. Create-only.
   * @default "per_unit"
   */
  billingScheme?: PlanBillingScheme;
  /**
   * Meter that tracks usage for a metered plan. Create-only.
   */
  meter?: string;
  /**
   * User-defined metadata. Alchemy ownership keys (`alchemy_stack` /
   * `alchemy_stage` / `alchemy_id`) are merged in automatically. Keys may
   * not contain `:`.
   */
  metadata?: Record<string, string>;
}

export type Plan = Resource<
  "Stripe.Plan",
  PlanProps,
  {
    /** Stripe plan id. */
    id: string;
    /** Id of the product this plan belongs to. */
    product: string;
    /** Three-letter ISO currency code. */
    currency: string;
    /** Billing frequency. */
    interval: PlanInterval;
    /** Number of intervals between billings. */
    intervalCount: number;
    /** Amount in the currency's minor units, or `undefined` when unset. */
    amount: number | undefined;
    /** Decimal amount in the currency's minor units, or `undefined`. */
    amountDecimal: string | undefined;
    /** Whether the plan can be used for new subscriptions. */
    active: boolean;
    /** Brief description of the plan, hidden from customers. */
    nickname: string | undefined;
    /** Default trial length in days, if set. */
    trialPeriodDays: number | undefined;
    /** How quantity per period is determined. */
    usageType: PlanUsageType;
    /** How the price per period is computed. */
    billingScheme: PlanBillingScheme;
    /** Meter id for a metered plan, if set. */
    meter: string | undefined;
    /** User-defined metadata (Alchemy ownership keys stripped). */
    metadata: Record<string, string>;
    /** Unix timestamp when the plan was created. */
    created: number;
    /** Whether the plan exists in live mode. */
    livemode: boolean;
  },
  never,
  Providers
>;

/**
 * A Stripe Plan — the legacy (pre-Price) catalog object that defines
 * currency, amount, and billing interval for a Product. Prefer
 * {@link Price} for new catalogs; Plan exists for the Plans API.
 *
 * Currency, amount, interval, usage type, and billing scheme are
 * immutable (changing them replaces the plan). Nickname, metadata,
 * `active`, `trialPeriodDays`, and `product` update in place. Destroy
 * hard-deletes the plan; existing subscribers are not affected.
 *
 * @see https://docs.stripe.com/api/plans
 *
 * ### Creating a Plan
 * **Example:** Monthly plan
 * ```typescript
 * const product = yield* Stripe.Product("pro-plan", { name: "Pro Plan" });
 * const plan = yield* Stripe.Plan("pro-monthly", {
 *   product: product.id,
 *   currency: "usd",
 *   interval: "month",
 *   amount: 1500,
 *   nickname: "Pro monthly",
 * });
 * ```
 *
 * **Example:** Yearly plan
 * ```typescript
 * const plan = yield* Stripe.Plan("pro-yearly", {
 *   product: product.id,
 *   currency: "usd",
 *   interval: "year",
 *   amount: 15000,
 *   nickname: "Pro yearly",
 * });
 * ```
 *
 * ### Updating a Plan
 * **Example:** Nickname, metadata, and trial
 * ```typescript
 * const plan = yield* Stripe.Plan("pro-monthly", {
 *   product: product.id,
 *   currency: "usd",
 *   interval: "month",
 *   amount: 1500,
 *   nickname: "Pro monthly (paused)",
 *   trialPeriodDays: 14,
 *   metadata: { tier: "pro" },
 * });
 * ```
 *
 * @resource
 * @product Product
 */
export const Plan = Resource<Plan>("Stripe.Plan");

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

type PlanAttributes = Plan["Attributes"];

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

const productIdOf = (product: PlanProduct | null): string => {
  if (product == null) return "";
  if (typeof product === "string") return product;
  return product.id;
};

const toAttrs = (plan: StripePlan): PlanAttributes => ({
  id: plan.id,
  product: productIdOf(plan.product),
  currency: plan.currency,
  interval: plan.interval as PlanInterval,
  intervalCount: plan.interval_count,
  amount: plan.amount ?? undefined,
  amountDecimal: plan.amount_decimal ?? undefined,
  active: plan.active,
  nickname: plan.nickname ?? undefined,
  trialPeriodDays: plan.trial_period_days ?? undefined,
  usageType: plan.usage_type as PlanUsageType,
  billingScheme: plan.billing_scheme as PlanBillingScheme,
  meter: plan.meter ?? undefined,
  metadata: userMetadata(plan.metadata),
  created: plan.created,
  livemode: plan.livemode,
});

const isMissingPlan = isMissingStripeResource;

const getById = (plan: string) =>
  GetPlan({ plan }).pipe(Effect.catchIf(isMissingPlan, () => Effect.undefined));

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

const listAllPlans = Effect.fn(function* () {
  const [active, inactive] = yield* Effect.all([listByActive(true), listByActive(false)], {
    concurrency: 2,
  });
  const seen = new Set<string>();
  const plans: StripePlan[] = [];
  for (const plan of [...active, ...inactive]) {
    if (seen.has(plan.id)) continue;
    seen.add(plan.id);
    plans.push(plan);
  }
  return plans;
});

const findByAlchemyId = Effect.fn(function* (id: string) {
  const plans = yield* listAllPlans();
  const matches: StripePlan[] = [];
  for (const plan of plans) {
    if (yield* hasAlchemyMetadata(id, tagRecord(plan.metadata))) {
      matches.push(plan);
    }
  }
  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: PlanProps, output: PlanAttributes | undefined) => {
  if (output === undefined) return false;
  if (news.currency !== output.currency) return true;
  if (news.interval !== output.interval) return true;
  if ((news.intervalCount ?? 1) !== output.intervalCount) return true;
  if (news.amount !== undefined && news.amount !== output.amount) {
    return true;
  }
  if (news.amountDecimal !== undefined && news.amountDecimal !== output.amountDecimal) {
    return true;
  }
  if ((news.usageType ?? "licensed") !== output.usageType) return true;
  if ((news.billingScheme ?? "per_unit") !== output.billingScheme) return true;
  if ((news.meter ?? undefined) !== output.meter) return true;
  return false;
};

export const PlanProvider = () =>
  Provider.succeed(Plan, {
    stables: [
      "id",
      "currency",
      "interval",
      "intervalCount",
      "amount",
      "billingScheme",
      "usageType",
      "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* () {
      // The plans API also enumerates recurring prices, which Price's delete
      // archives (active: false). Archived rows are effectively deleted and
      // must not re-enter nuke, so enumerate active plans only.
      const plans = yield* listByActive(true);
      return plans
        .filter((plan) => {
          const metadata = tagRecord(plan.metadata);
          return metadata[alchemyMetadataKeys.stack] !== undefined;
        })
        .map(toAttrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output, instanceId }) {
      const metadata = yield* desiredMetadata(id, news.metadata);
      const desiredActive = news.active ?? true;
      const desiredNickname = news.nickname ?? "";
      const desiredTrialPeriodDays = news.trialPeriodDays;

      let current: StripePlan | undefined = yield* observe({
        id: output?.id,
        logicalId: id,
      });
      // A previous generation (same logical id, different immutable
      // fields) must not be reused — Stripe plans cannot change amount,
      // currency, or billing interval.
      if (current !== undefined && shouldReplace(news, toAttrs(current))) {
        current = undefined;
      }

      if (current === undefined) {
        current = yield* CreatePlan({
          product: news.product,
          currency: news.currency,
          interval: news.interval,
          active: desiredActive,
          metadata,
          ...(news.intervalCount !== undefined ? { interval_count: news.intervalCount } : {}),
          ...(news.amount !== undefined ? { amount: news.amount } : {}),
          ...(news.amountDecimal !== undefined ? { amount_decimal: news.amountDecimal } : {}),
          ...(news.usageType !== undefined ? { usage_type: news.usageType } : {}),
          ...(news.billingScheme !== undefined ? { billing_scheme: news.billingScheme } : {}),
          ...(news.meter !== undefined ? { meter: news.meter } : {}),
          ...(desiredNickname.length > 0 ? { nickname: desiredNickname } : {}),
          ...(desiredTrialPeriodDays !== undefined
            ? { trial_period_days: desiredTrialPeriodDays }
            : {}),
        }).pipe(
          withRequestOptions({
            idempotencyKey: `alchemy-plan-${instanceId}`,
          }),
        );
      }

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

      const observedMetadata = tagRecord(current.metadata);
      const { upsert, removed } = diffMetadata(observedMetadata, metadata);
      const metadataChanged = upsert.length > 0 || removed.length > 0;
      const activeChanged = current.active !== desiredActive;
      const nicknameChanged = (current.nickname ?? "") !== desiredNickname;
      const productChanged = productIdOf(current.product) !== news.product;
      const trialChanged =
        desiredTrialPeriodDays !== undefined &&
        (current.trial_period_days ?? undefined) !== desiredTrialPeriodDays;

      if (
        !activeChanged &&
        !nicknameChanged &&
        !productChanged &&
        !trialChanged &&
        !metadataChanged
      ) {
        return toAttrs(current);
      }

      const updated = yield* UpdatePlan({
        plan: current.id,
        ...(activeChanged ? { active: desiredActive } : {}),
        ...(nicknameChanged ? { nickname: desiredNickname } : {}),
        ...(productChanged ? { product: news.product } : {}),
        ...(trialChanged ? { trial_period_days: desiredTrialPeriodDays } : {}),
        ...(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* DeletePlan({ plan: output.id }).pipe(Effect.catchIf(isMissingPlan, () => Effect.void));
    }),
  });