@volter/twin-stripe 0.1.2 → 2.0.0

package/src/semantics/checkout.ts

@@ -0,0 +1,297 @@
+// Checkout Session semantics. The machine in ../manifest.ts says an open session expires or
+// completes and nothing else does. Stripe completes a session when the customer pays on its hosted
+// page (src/screens/checkout.tsx, the session's url), which has no API verb; completing links what
+// the payment made: a succeeded PaymentIntent, an active (or
+// trialing) subscription, or a succeeded SetupIntent. List and retrieve are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { addBillingInterval, applyCouponDiscount, buildDiscount, buildSubscriptionItemsList, declineFor, lineItemEntries, mintClientSecret, paginate, paymentMethodSubObject, resolveLineItem, resolveSubscriptionBillingInterval, resolveTrial } from '../stripe-twin.ts';
+import { afterSuccessOf } from './after-payment.ts';
+import { actingAccount } from './ledger.ts';
+import { mintCharge } from './payment-intents.ts';
+import { collectSubscriptionInvoice, draftSubscriptionInvoice } from './renewals.ts';
+import { storeItems } from './subscriptions.ts';
+import { at, created, fail, finder, path, redeemCoupon, type Row } from './shared.ts';
+
+const CS = 'checkout.session';
+const sessionMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such checkout.session: '${id}'`, 404, 'resource_missing');
+
+// Stripe normalizes the create input into the Session: line_items become the list envelope, and
+// subscription_data (create-only) is kept aside for completion to copy onto the subscription
+/** The discount a session is created with (discounts[0][promotion_code] or [coupon]), or Stripe's refusal: an unknown
+ *  code or coupon, and one that has expired or been deactivated, are refused at create
+ *  (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-discounts, docs.stripe.com/error-codes#coupon-expired).
+ *  Where the documentation stops and the twin decides: the refusals' wording. */
+function discountOf(ctx: SemanticsContext, params: Row, now: number): { coupon: Row; promotion?: string } | Response | undefined {
+  const first = Array.isArray(params.discounts) ? (params.discounts[0] as Row | undefined) : undefined;
+  if (!first || typeof first !== 'object') return undefined;
+  const expired = (what: string) => ctx.refuse({ status: 400, code: 'coupon_expired', param: 'discounts', message: `This ${what} has expired.` });
+  let promotion: string | undefined;
+  let couponId = typeof first.coupon === 'string' ? first.coupon : undefined;
+  if (typeof first.promotion_code === 'string') {
+    const pc = ctx.get('promotion_code', first.promotion_code);
+    if (!pc) return ctx.refuse({ status: 400, code: 'resource_missing', param: 'discounts[0][promotion_code]', message: `No such promotion code: '${first.promotion_code}'` });
+    if (typeof pc.expires_at === 'number' && pc.expires_at <= now) return expired('promotion code');
+    if (pc.active === false) return ctx.refuse({ status: 400, param: 'discounts[0][promotion_code]', message: 'This promotion code is inactive.' });
+    promotion = String(pc.id);
+    couponId = typeof pc.coupon === 'string' ? pc.coupon : String((pc.coupon as Row | undefined)?.id ?? '');
+  }
+  const coupon = couponId ? ctx.get('coupon', couponId) : undefined;
+  if (!coupon) return ctx.refuse({ status: 400, code: 'resource_missing', param: 'discounts[0][coupon]', message: `No such coupon: '${couponId ?? ''}'` });
+  if (coupon.valid === false || (typeof coupon.redeem_by === 'number' && coupon.redeem_by <= now)) return expired('coupon');
+  return { coupon, ...(promotion ? { promotion } : {}) };
+}
+
+/** A payment or subscription session with nothing to sell (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-line_items). */
+function noLineItems(ctx: SemanticsContext): Response {
+  return fail(ctx, 'You must provide at least one recurring price in `subscription` mode when not using `line_items[].price_data` or a Price with `recurring`, and at least one `line_items` for `payment` mode.', 400, 'parameter_missing');
+}
+
+/** A destination charge to an account the platform does not have (docs.stripe.com/connect/destination-charges). */
+function noDestination(ctx: SemanticsContext, destination: unknown): Response {
+  return ctx.refuse({ status: 400, code: 'resource_missing', param: 'payment_intent_data[transfer_data][destination]', message: `No such destination: '${String(destination)}'` });
+}
+
+/** A session's trial Stripe refuses: `subscription_data.trial_end` "Has to be at least 48 hours in the future", and
+ *  `subscription_data.trial_period_days` "Has to be at least 1" (docs.stripe.com/api/checkout/sessions/create). Where the
+ *  documentation stops and the twin decides: the refusals' wording. */
+function sessionTrialRefused(ctx: SemanticsContext, data: unknown, now: number): Response | undefined {
+  if (!data || typeof data !== 'object') return undefined;
+  const { trial_end: end, trial_period_days: days } = data as Row;
+  const endRefused = end !== undefined && !(Number.isInteger(Number(end)) && Number(end) >= now + 48 * 3600);
+  const daysRefused = days !== undefined && !(Number.isInteger(Number(days)) && Number(days) >= 1);
+  return endRefused || daysRefused ? sessionTrialRefusal(ctx, endRefused ? 'trial_end' : 'trial_period_days') : undefined;
+}
+
+function sessionTrialRefusal(ctx: SemanticsContext, param: 'trial_end' | 'trial_period_days'): Response {
+  const message = param === 'trial_end' ? 'The `subscription_data[trial_end]` timestamp has to be at least 48 hours in the future.' : 'The `subscription_data[trial_period_days]` has to be at least 1.';
+  return ctx.refuse({ status: 400, param: `subscription_data[${param}]`, message });
+}
+
+const create: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const mode = typeof params.mode === 'string' ? params.mode : 'payment';
+  if (!['payment', 'subscription', 'setup'].includes(mode)) return fail(ctx, 'Invalid mode: must be one of payment, subscription, or setup.', 400, 'parameter_invalid_string_enum');
+  const entries = lineItemEntries(params);
+  if (mode !== 'setup' && entries.length === 0) return noLineItems(ctx);
+  // hosted Checkout (the only ui_mode the twin models) needs success_url
+  if (params.success_url === undefined || params.success_url === '') return fail(ctx, 'Missing required param: success_url.', 400, 'parameter_missing');
+  const sessionCurrency = typeof params.currency === 'string' ? params.currency : 'usd';
+  const resolved = entries.map((e, i) => resolveLineItem(e, i, sessionCurrency, finder(ctx)));
+  const missing = resolved.find((r) => r.priceMissing);
+  if (missing) return fail(ctx, `No such price: '${missing.priceMissing}'`, 400, 'resource_missing');
+  const items = resolved.map((r) => r.item);
+  const now = Number(ctx.now());
+  const trialRefused = sessionTrialRefused(ctx, params.subscription_data, now);
+  if (trialRefused) return trialRefused;
+  const discount = discountOf(ctx, params, now);
+  if (discount instanceof Response) return discount;
+  const subtotal = items.reduce((n, it) => n + it.amount_subtotal, 0);
+  const off = discount ? applyCouponDiscount(subtotal, discount.coupon) : 0;
+  // the hosted page is at Stripe's own host (the World routes it to src/screens/checkout.tsx)
+  const id = ctx.mint(CS);
+  const fields: Row = {
+    mode, status: 'open',
+    payment_status: mode === 'setup' ? 'no_payment_required' : 'unpaid',
+    url: `https://checkout.stripe.com/c/pay/${id}`, success_url: params.success_url ?? null, cancel_url: params.cancel_url ?? null,
+    customer: params.customer ?? null, client_reference_id: params.client_reference_id ?? null,
+    customer_email: params.customer_email ?? null,
+    // whether paying makes a customer: in payment mode only when asked (`always`), `if_required` by default
+    customer_creation: mode === 'payment' ? (params.customer_creation === 'always' ? 'always' : 'if_required') : null,
+    amount_subtotal: entries.length ? items.reduce((s, it) => s + it.amount_subtotal, 0) : null,
+    amount_total: entries.length ? items.reduce((s, it) => s + it.amount_total, 0) - off : null,
+    currency: items[0]?.currency ?? (entries.length ? sessionCurrency : null), line_items: { object: 'list', data: items, has_more: false, url: `/v1/checkout/sessions/${id}/line_items` }, payment_intent: null, subscription: null, setup_intent: null, invoice: null, payment_method_types: ['card'], expires_at: now + 24 * 3600, custom_fields: [], shipping_options: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null }, automatic_tax: { enabled: false, liability: null, status: null, provider: null }, total_details: { amount_discount: off, amount_shipping: 0, amount_tax: 0 },
+    discounts: discount ? [{ coupon: String(discount.coupon.id), promotion_code: discount.promotion ?? null }] : [],
+    metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {}, livemode: false,
+    // "Details on the state of phone number collection for the session" (docs.stripe.com/api/checkout/sessions/object),
+    // off unless the create enables it
+    phone_number_collection: { enabled: (params.phone_number_collection as Row | undefined)?.enabled === true || (params.phone_number_collection as Row | undefined)?.enabled === 'true' },
+  };
+  if (params.subscription_data && typeof params.subscription_data === 'object') fields._subscription_data = params.subscription_data;
+  // each line's inline price_data, kept for what the session's line cannot carry: whether it recurs (isOneTime) and the
+  // Price a subscription's item is made from at completion (sessionPrices)
+  if (mode === 'subscription' && entries.some((e) => e.price_data && typeof e.price_data === 'object')) fields._price_data = entries.map((e) => (e.price_data && typeof e.price_data === 'object' ? e.price_data : null));
+  // the hosted page's brand name for this session (screens/checkout.tsx, merchantOf), and the account the session was
+  // made on (Stripe-Account: a direct charge), whose name the page shows. Kept apart from `_account`, the books a row is
+  // kept on: paying on the hosted page still makes the PaymentIntent and charge on the platform's books (a gap of the
+  // twin's direct-charge Checkout), so the session's events stay with them.
+  if (params.branding_settings && typeof params.branding_settings === 'object') fields._branding_settings = params.branding_settings;
+  if (actingAccount(ctx)) fields._brand_account = actingAccount(ctx);
+  // a payment session's payment_intent_data shapes the PaymentIntent paying makes: a destination charge's transfer and
+  // the platform's application fee (docs.stripe.com/connect/destination-charges?platform=web&ui=stripe-hosted)
+  const pid = params.payment_intent_data && typeof params.payment_intent_data === 'object' ? (params.payment_intent_data as Row) : undefined;
+  if (pid && mode === 'payment') {
+    const destination = (pid.transfer_data as Row | undefined)?.destination;
+    if (destination !== undefined && (typeof destination !== 'string' || !ctx.get('account', destination))) return noDestination(ctx, destination);
+    fields._payment_intent_data = pid;
+  }
+  if (discount) fields._discount = { coupon: String(discount.coupon.id), promotion_code: discount.promotion ?? null };
+  return ctx.reply(await created(ctx, CS, { id, ...fields }, {}));
+};
+
+// the session's items, a page at a time
+const lineItems: Semantics = async (ctx) => {
+  const s = ctx.get(CS, at(ctx, 'session'));
+  if (!s) return sessionMissing(ctx, at(ctx, 'session'));
+  const li = s.line_items as { data?: Row[] } | undefined;
+  const { page, hasMore } = paginate(Array.isArray(li?.data) ? li!.data! : [], ctx.params);
+  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
+};
+
+const expire: Semantics = async (ctx) => {
+  const id = at(ctx, 'session');
+  const s = ctx.get(CS, id);
+  if (!s) return sessionMissing(ctx, id);
+  const refused = ctx.legal(CS, 'status', 'PostCheckoutSessionsSessionExpire', s.status, undefined, id);
+  if (refused) return ctx.refuse(refused);
+  return ctx.reply(await ctx.write(CS, id, { status: 'expired', url: null }, 'checkout.session.expire'));
+};
+
+/** The card the customer entered on the page. */
+export type EnteredCard = { number: string; exp_month: number; exp_year: number };
+
+/** What completing a session makes, by its mode, as the fields that link it: a payment is a PaymentIntent paid with
+ *  the entered card, its charge in the ledger as any payment's is. */
+async function complete(ctx: SemanticsContext, id: string, existing: Row, card?: EnteredCard): Promise<Row> {
+  const link: Row = { status: 'complete' };
+  const customer = typeof existing.customer === 'string' ? existing.customer : undefined;
+  const currency = typeof existing.currency === 'string' ? existing.currency : 'usd';
+  // the entered card becomes a PaymentMethod, on the customer when there is one, carrying what a later charge to it
+  // answers and what Stripe does after it succeeds (docs.stripe.com/testing#declined-payments, #disputes)
+  const pm = card && existing.mode !== 'setup' ? await created(ctx, 'payment_method', {}, { type: 'card', customer: customer ?? null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null, ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}) }) : undefined;
+  if (existing.mode === 'payment') {
+    const amount = Number(existing.amount_total) || 0;
+    const piId = ctx.mint('payment_intent');
+    const pid = (ctx.row(CS, id)?._payment_intent_data ?? {}) as Row;
+    const connect = {
+      ...(pid.application_fee_amount !== undefined ? { application_fee_amount: Math.trunc(Number(pid.application_fee_amount) || 0) } : {}),
+      ...(pid.transfer_data && typeof pid.transfer_data === 'object' ? { transfer_data: { destination: (pid.transfer_data as Row).destination } } : {}),
+      ...(typeof pid.description === 'string' ? { description: pid.description } : {}),
+      ...(pid.metadata && typeof pid.metadata === 'object' ? { metadata: pid.metadata } : {}),
+    };
+    const fields = { amount, currency, id: piId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}), ...connect };
+    await created(ctx, 'payment_intent', fields, { status: 'succeeded', amount_received: amount, client_secret: mintClientSecret(piId), livemode: false, payment_method_types: ['card'] });
+    const charge = await mintCharge(ctx, piId, fields, amount);
+    await ctx.write('payment_intent', piId, { latest_charge: charge }, 'payment_intent.succeeded');
+    link.payment_intent = piId;
+    link.payment_status = 'paid';
+  } else if (existing.mode === 'subscription') {
+    if (customer) {
+      // the subscription bills the session's own (already resolved) line items, and takes the
+      // session's subscription_data: metadata, description, and a trial as its first period
+      const now = Number(ctx.now());
+      // "Line items with one-time Prices will be on the initial invoice only" (docs.stripe.com/api/checkout/sessions/
+      // create#create_checkout_session-line_items): the subscription's items are the recurring ones
+      const inline = (ctx.row(CS, id)?._price_data as Array<Row | null> | undefined) ?? [];
+      const lines = ((existing.line_items as { data?: unknown } | undefined)?.data as Row[] | undefined) ?? [];
+      const allLineItems = inline.some(Boolean) ? await sessionPrices(ctx, lines, inline) : lines;
+      const sessionLineItems = allLineItems.filter((it) => !isOneTime(it));
+      const oneTime = allLineItems.filter((it) => isOneTime(it));
+      const { interval, interval_count } = resolveSubscriptionBillingInterval(sessionLineItems, finder(ctx));
+      const subId = ctx.mint('subscription');
+      // the session's view never carries its create-only subscription_data: read the stored row
+      const raw = ctx.row(CS, id)?._subscription_data;
+      const subData = (raw && typeof raw === 'object' ? raw : {}) as Row;
+      const subMetadata = subData.metadata && typeof subData.metadata === 'object' ? (subData.metadata as Row) : {};
+      // a trial of `trial_period_days` from now, or to `trial_end` (docs.stripe.com/payments/checkout/free-trials)
+      const trialEnd = resolveTrial(subData, now)?.end ?? null;
+      const sub = await created(ctx, 'subscription', { customer, id: subId }, {
+        status: trialEnd === null ? 'active' : 'trialing', livemode: false, currency, collection_method: 'charge_automatically',
+        // a trial's end is the billing anchor (docs.stripe.com/api/subscriptions/create#create_subscription-trial_end)
+        cancel_at_period_end: false, start_date: now, billing_cycle_anchor: trialEnd ?? now, metadata: subMetadata,
+        description: typeof subData.description === 'string' ? subData.description : null,
+        // the session's discount is the subscription's (docs.stripe.com/payments/checkout/discounts)
+        discounts: sessionDiscount(ctx, id, customer, now), billing_schedules: [],
+        trial_start: trialEnd === null ? null : now, trial_end: trialEnd,
+        current_period_start: now, current_period_end: trialEnd ?? addBillingInterval(now, interval, interval_count),
+        // Checkout saves the card as the subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works)
+        default_payment_method: pm?.id ?? null,
+        items: buildSubscriptionItemsList(sessionLineItems, subId, now, finder(ctx)),
+        automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' },
+        invoice_settings: { issuer: { type: 'self' } },
+      });
+      await storeItems(ctx, subId, ((sub.items as Row | undefined)?.data as Row[] | undefined) ?? []);
+      // its first invoice, paid on the page by the card just entered (nothing is due on a trial's)
+      // (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions)
+      const invoice = await draftSubscriptionInvoice(ctx, sub, { start: now, end: Number(sub.current_period_end), reason: 'subscription_create', trial: trialEnd !== null, once: oneTime });
+      await collectSubscriptionInvoice(ctx, invoice, now, 'external');
+      await ctx.write('subscription', subId, { latest_invoice: invoice }, 'subscription.update');
+      link.subscription = sub.id;
+      link.invoice = invoice;
+    }
+    link.payment_status = 'paid';
+  } else link.setup_intent = await completeSetup(ctx, customer);
+  return link;
+}
+
+/** A line item of a one-time Price: a stored Price, or an inline `price_data`, without `recurring` ("Line items with
+ *  one-time Prices will be on the initial invoice only", docs.stripe.com/api/checkout/sessions/create). */
+export function isOneTime(item: Row, priceData?: Row | null): boolean {
+  if (priceData) return !priceData.recurring;
+  return !!item.price && typeof item.price === 'object' && !(item.price as Row).recurring;
+}
+
+/** A subscription session's lines at completion, each inline `price_data` made the Price it generates ("Data used to
+ *  generate a new Price object inline", the same page), under the product it names or one made from its product_data,
+ *  so the subscription's items bill it. Where the documentation stops and the twin decides: such a Price is archived
+ *  (active=false), as a subscription item's price_data makes one (docs.stripe.com/products-prices/manage-prices). */
+async function sessionPrices(ctx: SemanticsContext, lines: Row[], inline: Array<Row | null>): Promise<Row[]> {
+  const out: Row[] = [];
+  for (const [i, line] of lines.entries()) {
+    const d = inline[i];
+    if (!d) { out.push(line); continue; }
+    const pd = d.product_data && typeof d.product_data === 'object' ? (d.product_data as Row) : undefined;
+    const product = typeof d.product === 'string' ? d.product : String((await created(ctx, 'product', { name: pd?.name ?? 'Item' }, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: ctx.now() })).id);
+    const r = d.recurring && typeof d.recurring === 'object' ? (d.recurring as Row) : undefined;
+    const price = await created(ctx, 'price', {
+      product, currency: String(d.currency ?? line.currency ?? 'usd').toLowerCase(),
+      unit_amount: d.unit_amount_decimal !== undefined ? null : Math.trunc(Number(d.unit_amount) || 0),
+      unit_amount_decimal: d.unit_amount_decimal !== undefined ? String(d.unit_amount_decimal) : String(Math.trunc(Number(d.unit_amount) || 0)),
+      ...(r ? { recurring: { interval: r.interval, interval_count: Math.max(1, Math.trunc(Number(r.interval_count ?? 1)) || 1), usage_type: 'licensed', trial_period_days: null, meter: null } } : { recurring: null }),
+    }, { active: false, livemode: false, billing_scheme: 'per_unit', type: r ? 'recurring' : 'one_time', metadata: {}, lookup_key: null, nickname: null, tax_behavior: 'unspecified' });
+    out.push({ ...line, price });
+  }
+  return out;
+}
+
+/** A setup session saves the card through a succeeded SetupIntent (docs.stripe.com/payments/save-and-reuse?platform=checkout). */
+async function completeSetup(ctx: SemanticsContext, customer: string | undefined): Promise<unknown> {
+  const siId = ctx.mint('setup_intent');
+  const si = await created(ctx, 'setup_intent', { id: siId, ...(customer ? { customer } : {}) }, { status: 'succeeded', usage: 'off_session', client_secret: mintClientSecret(siId), payment_method_types: ['card'], livemode: false });
+  return si.id;
+}
+
+/** The discount a completed subscription session gives its subscription. */
+function sessionDiscount(ctx: SemanticsContext, id: string, customer: string, now: number): Row[] {
+  const d = ctx.row(CS, id)?._discount as Row | undefined;
+  const coupon = d && typeof d.coupon === 'string' ? ctx.get('coupon', d.coupon) : undefined;
+  return coupon ? [{ ...buildDiscount(coupon, customer, now), promotion_code: d?.promotion_code ?? null, checkout_session: id }] : [];
+}
+
+/** The customer paying on the hosted page (src/screens/checkout.tsx): the external actor's move on the
+ *  session's machine, then what the payment made, linked, and the session stored complete. */
+export async function completeSession(ctx: SemanticsContext, id: string, existing: Row, details: Row = {}, card?: EnteredCard): Promise<Row | Response> {
+  const refused = ctx.legal(CS, 'status', 'PostCheckoutSessionsSession', existing.status, 'complete', id, 'external');
+  if (refused) return ctx.refuse(refused);
+  const link = await complete(ctx, id, existing, card);
+  // the discount the buyer took is redeemed (shared.ts redeemCoupon)
+  const d = ctx.row(CS, id)?._discount as Row | undefined;
+  if (d) await redeemCoupon(ctx, d.coupon, d.promotion_code);
+  // the session's url "is only present when the session is active" (docs.stripe.com/api/checkout/sessions/object)
+  return ctx.write(CS, id, { ...details, ...link, url: null }, 'checkout.session.completed');
+}
+
+const update: Semantics = async (ctx) => {
+  const id = at(ctx, 'session');
+  const existing = ctx.get(CS, id);
+  if (!existing) return sessionMissing(ctx, id);
+  // a session completes only when its customer pays on the hosted page (src/screens/checkout.tsx); the API takes no
+  // status, which the parameter check refuses as Stripe does (../stripe-params.ts)
+  return ctx.reply(await ctx.write(CS, id, ctx.params, 'checkout.session.update'));
+};
+
+export const checkout: Record<string, Semantics> = {
+  PostCheckoutSessions: create,
+  GetCheckoutSessionsSessionLineItems: lineItems,
+  PostCheckoutSessionsSessionExpire: expire,
+  PostCheckoutSessionsSession: update,
+};