@volter/twin-stripe 2.0.38 → 3.0.1

package/src/semantics/subscriptions.ts

@@ -1,353 +1,51 @@
-// Subscription and SubscriptionItem semantics. A subscription is created with its items, its
-// billing period and, under payment_behavior=default_incomplete, its first invoice and that
-// invoice's PaymentIntent; canceling it is the machine's move in ../manifest.ts. Retrieve of a
-// subscription and of an item are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import {
-  addBillingInterval,
-  applyCouponDiscount,
-  asBool,
-  buildDiscount,
-  buildSubscriptionItemsList,
-  cardError,
-  declineFor,
-  mintClientSecret,
-  priceAmount,
-  resolveSubscriptionBillingInterval,
-  resolveTrial,
-  subscriptionCouponParam,
-  subscriptionHasPrice,
-  subscriptionItemEntries,
-  subscriptionItemPrice,
-} from '../stripe-twin.ts';
-import { finalizedFields } from './invoices.ts';
-import { mintCharge } from './payment-intents.ts';
-import { advanceBilling, clockNow, collectSubscriptionInvoice, draftSubscriptionInvoice, itemQuantity, keptAfter, payerOf, spendOnceCoupon } from './renewals.ts';
-import { at, created, deletedDiscount, expanded, fail, finder, list, newest, redeemCoupon, search, send, where, type Row } from './shared.ts';
-
-const SUB = 'subscription';
-const subMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such subscription: '${id}'`, 404, 'resource_missing');
-
-const create: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const customer = typeof params.customer === 'string' ? params.customer : '';
-  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-  if (!ctx.get('customer', customer)) return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-  const now = clockNow(ctx, customer);
-  const badTrial = trialEndRefused(ctx, params.trial_end, now);
-  if (badTrial) return badTrial;
-  // a coupon (or discounts[0][coupon]) must exist; it becomes the subscription's discount
-  const couponId = subscriptionCouponParam(params);
-  let discounts: Row[] = [];
-  if (couponId) {
-    const coupon = ctx.get('coupon', couponId);
-    if (!coupon) return fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
-    discounts = [buildDiscount(coupon, customer, now)];
-  }
-  // a trial is the current period; otherwise one billing interval of the first item's price. The
-  // period sits top-level: this twin's default API version predates basil moving it onto items.
-  const trial = resolveTrial(params, now);
-  const itemEntries = subscriptionItemEntries(params.items);
-  const { interval, interval_count } = resolveSubscriptionBillingInterval(itemEntries, finder(ctx));
-  const periodStart = trial ? trial.start : now;
-  const periodEnd = trial ? trial.end : addBillingInterval(now, interval, interval_count);
-  const subId = typeof params.id === 'string' && params.id ? params.id : ctx.mint(SUB);
-  const itemsList = buildSubscriptionItemsList(itemEntries, subId, now, finder(ctx));
-  const itemsData = itemsList.data as Row[];
-  const currency = typeof params.currency === 'string' && params.currency ? params.currency : 'usd';
-
-  // Stripe opens a subscription's first invoice at once (a trialing one has nothing due yet) and, by
-  // payment_behavior (docs.stripe.com/api/subscriptions/create#create_subscription-payment_behavior):
-  // allow_incomplete (the default) charges the default payment method now, and without one, or on a decline,
-  // leaves the subscription incomplete with the invoice open; error_if_incomplete refuses the create instead;
-  // default_incomplete never charges, leaving a PaymentIntent the frontend confirms.
-  const behavior = typeof params.payment_behavior === 'string' ? params.payment_behavior : 'allow_incomplete';
-  const needsFirstInvoice = !trial;
-  const holder = ctx.get('customer', customer) ?? {};
-  const payWith = behavior === 'default_incomplete' ? undefined
-    : (typeof params.default_payment_method === 'string' ? params.default_payment_method : undefined) ?? ((holder.invoice_settings as Row | undefined)?.default_payment_method as string | undefined) ?? undefined;
-  const declined = payWith ? declineFor(finder(ctx), { payment_method: payWith }) : undefined;
-  let subtotal = 0;
-  for (const it of itemsData) {
-    const price = it.price && typeof it.price === 'object' ? (it.price as Row) : undefined;
-    subtotal += priceAmount(price, itemQuantity(it));
-  }
-  const coupon = discounts[0]?.coupon as Row | undefined;
-  const discountAmount = applyCouponDiscount(subtotal, coupon);
-  const invoiceTotal = Math.max(0, subtotal - discountAmount);
-  // a $0 first invoice is paid at once and needs no PaymentIntent
-  const isFree = invoiceTotal <= 0;
-  const pays = needsFirstInvoice && !isFree && !!payWith && !declined;
-  if (needsFirstInvoice && !isFree && !pays && behavior === 'error_if_incomplete') return firstPaymentRefused(ctx, declined);
-  // minted first so the subscription names its latest_invoice in its own create (a trial's $0 invoice too)
-  const invoiceId = needsFirstInvoice ? ctx.mint('invoice') : null;
-  const trialInvoiceId = needsFirstInvoice ? null : ctx.mint('invoice');
-  const piId = needsFirstInvoice && !isFree ? ctx.mint('payment_intent') : null;
-
-  const { coupon: _c, discounts: _ds, trial_period_days: _tpd, trial_end: _te, items: _items, id: _id, ...rest } = params;
-  const sub = await created(ctx, SUB, { ...rest, id: subId }, {
-    status: trial ? 'trialing' : needsFirstInvoice && !isFree && !pays ? 'incomplete' : 'active',
-    livemode: false, currency, collection_method: 'charge_automatically',
-    // a trial's end is the billing anchor: "The `billing_cycle_anchor` will be updated to the `trial_end` value"
-    // (docs.stripe.com/api/subscriptions/create#create_subscription-trial_end)
-    cancel_at_period_end: false, start_date: now, billing_cycle_anchor: trial ? trial.end : now, metadata: {},
-    discounts: discounts.map((d) => ({ ...d, subscription: subId })), billing_schedules: [],
-    ...(trial ? { trial_start: trial.start, trial_end: trial.end } : { trial_start: null, trial_end: null }),
-    current_period_start: periodStart, current_period_end: periodEnd,
-    items: itemsList,
-    latest_invoice: invoiceId ?? trialInvoiceId,
-    automatic_tax: { enabled: false, liability: null },
-    billing_mode: { type: 'classic' },
-    invoice_settings: { issuer: { type: 'self' } },
-  });
-  await storeItems(ctx, subId, itemsData);
-  if (discounts.length) await redeemCoupon(ctx, couponId);
-  // a customer billed for the first time takes the subscription's currency
-  if (!holder.currency) await ctx.write('customer', customer, { currency }, 'customer.update');
-  if (!invoiceId) {
-    // a trial's subscription still opens an invoice at once: "An immediate invoice is still created, but the amount is 0"
-    // (docs.stripe.com/billing/subscriptions/trials/free-trials); finalizing it spends a once coupon (renewals.ts)
-    const trialInvoice = await draftSubscriptionInvoice(ctx, ctx.get(SUB, subId) ?? sub, { start: periodStart, end: periodEnd, reason: 'subscription_create', trial: true, ...(trialInvoiceId ? { id: trialInvoiceId } : {}) });
-    await collectSubscriptionInvoice(ctx, trialInvoice, now, 'api');
-    return ctx.reply(expanded(ctx, SUB, ctx.get(SUB, subId) ?? sub));
-  }
-  // the default payment method pays the first invoice now: its charge (with its ledger entry) comes first
-  const chargeId = pays && piId ? await mintCharge(ctx, piId, { currency, customer, payment_method: payWith, invoice: invoiceId }, invoiceTotal) : null;
-
-  const invoiceLines = itemsData.map((it, i) => {
-    const price = it.price && typeof it.price === 'object' ? (it.price as Row) : undefined;
-    const quantity = itemQuantity(it);
-    return {
-      id: `il_twin_${invoiceId}_${i + 1}`, object: 'line_item', type: 'subscription',
-      amount: priceAmount(price, quantity), currency, quantity, proration: false,
-      price: it.price ?? null, subscription: subId, invoice_item: null, subscription_item: it.id ?? null,
-      period: { start: periodStart, end: periodEnd }, description: null,
-    };
-  });
-  await created(ctx, 'invoice', {
-    id: invoiceId,
-    ...finalizedFields(ctx, { id: invoiceId, customer }, now),
-    status: isFree || pays ? 'paid' : 'open', livemode: false, currency, collection_method: 'charge_automatically',
-    auto_advance: !(isFree || pays), attempt_count: payWith && !isFree ? 1 : 0, attempted: !isFree && behavior !== 'default_incomplete',
-    customer, subscription: subId, billing_reason: 'subscription_create', charge: chargeId,
-    amount_due: invoiceTotal, amount_paid: isFree || pays ? invoiceTotal : 0, amount_remaining: isFree || pays ? 0 : invoiceTotal,
-    amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
-    subtotal, total: invoiceTotal, starting_balance: 0,
-    post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
-    period_start: periodStart, period_end: periodEnd,
-    default_tax_rates: [], discounts: discounts[0] ? [discounts[0]] : [],
-    lines: { object: 'list', data: invoiceLines, has_more: false, total_count: invoiceLines.length, url: `/v1/invoices/${invoiceId}/lines` },
-    automatic_tax: { enabled: false, liability: null, status: null },
-    status_transitions: { finalized_at: now, marked_uncollectible_at: null, paid_at: isFree || pays ? now : null, voided_at: null },
-    issuer: { type: 'self' },
-    payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
-    payment_intent: piId,
-  }, {});
-  if (piId) {
-    // paid by the default payment method, or waiting on one (declined, absent, or collected client-side)
-    await created(ctx, 'payment_intent', { id: piId, amount: invoiceTotal, currency, customer, invoice: invoiceId, ...(payWith ? { payment_method: pays ? payWith : null } : {}) }, {
-      status: pays ? 'succeeded' : 'requires_payment_method', client_secret: mintClientSecret(piId), livemode: false,
-      capture_method: 'automatic', amount_capturable: 0, amount_received: pays ? invoiceTotal : 0, next_action: null,
-      latest_charge: chargeId,
-      last_payment_error: declined ? { type: 'card_error', code: declined.code, decline_code: declined.decline_code ?? null, message: declined.message, payment_method: { id: payWith } } : null,
-      automatic_payment_methods: null, payment_method_types: ['card', 'link'], payment_method_options: {},
-    });
-  }
-  // the first invoice is finalized: the `once` coupon it took is spent (renewals.ts spendOnceCoupon)
-  await spendOnceCoupon(ctx, ctx.get('invoice', invoiceId) ?? {});
-  return ctx.reply(expanded(ctx, SUB, ctx.get(SUB, subId) ?? sub));
-};
+// Stripe's subscriptions operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { type Row } from '../engine/common.ts';
+import { keptAfter } from '../engine/renewals.ts';
+import { asBool, nowUnix, subscriptionCouponParam, subscriptionHasPrice, subscriptionItemEntries } from '../engine/stripe.ts';
+import { pauseCollection, SUB } from '../engine/subscriptions.ts';
+import { resourceView, advanceBilling, applyItemChanges, applyTrialEnd, at, clockNow, collectSubscriptionInvoice, expanded, itemChangesRefused, list, newest, redeemCoupon, replacedDiscounts, subMissing, trialEndBlocked, trialEndRefused, where } from './shared.ts';
+import { deletedDiscount } from '../engine/common.ts';
+import { fail } from './shared.ts';
+// canceling keeps the subscription, now canceled, stamped with when it was canceled and ended
+// (https://docs.stripe.com/api/subscriptions/object#subscription_object-canceled_at, #subscription_object-ended_at)
+export async function DeleteSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'subscription_exposed_id');
+  const sub = resourceView(ctx, SUB, id);
+  if (!sub) return subMissing(ctx, id);
+  const refused = ctx.legal(SUB, 'status', 'DeleteSubscriptionsSubscriptionExposedId', sub.status, undefined, id);
+  if (refused) return ctx.refuse(refused);
+  const now = nowUnix(ctx.occurredAt);
+  // why it was canceled: the request's `cancellation_details` ("Details about why this subscription was cancelled"), and
+  // the reason Stripe records for a cancel asked through the API, as the cancel page's example answers it:
+  // `"reason": "cancellation_requested"` (docs.stripe.com/api/subscriptions/cancel)
+  const given = ctx.params.cancellation_details && typeof ctx.params.cancellation_details === 'object' ? (ctx.params.cancellation_details as Row) : {};
+  const cancellation_details = { comment: given.comment ?? null, feedback: given.feedback ?? null, reason: 'cancellation_requested' };
+  return ctx.reply(ctx.expand(SUB, await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel')));
+}
 
-const listSubscriptions: Semantics = async (ctx) => {
+export async function GetSubscriptions(ctx: HandlerContext): Promise<Response> {
   await advanceBilling(ctx);
   return list(ctx, SUB, where(ctx, newest(ctx, SUB), {
     customer: (s, v) => s.customer === v,
     status: (s, v) => (v === 'all' ? true : s.status === v),
     price: (s, v) => subscriptionHasPrice(s, String(v)),
   }));
-};
-
-const searchSubscriptions: Semantics = async (ctx) => {
-  await advanceBilling(ctx);
-  return search(ctx, SUB);
-};
+}
 
-const retrieveSubscription: Semantics = async (ctx) => {
+export async function GetSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'subscription_exposed_id');
   await advanceBilling(ctx, (sub) => sub.id === id);
-  const sub = ctx.get(SUB, id);
+  const sub = resourceView(ctx, SUB, id);
   return sub ? ctx.reply(expanded(ctx, SUB, sub)) : subMissing(ctx, id);
-};
-
-// pause_collection pauses billing (the subscription stays active; the paused event fires) and
-// clearing it resumes; cancel_at_period_end schedules or withdraws a cancel; a coupon replaces the
-// discount and an empty one clears it
-/** pause_collection pauses billing (the paused event fires) and clearing it resumes
- *  (docs.stripe.com/billing/subscriptions/pause-payment); answers the event, or nothing for a value it does not take. */
-function pauseCollection(pc: unknown, fields: Row): string | undefined {
-  const isClear = pc === '' || pc === null || (typeof pc === 'object' && pc !== null && Object.keys(pc as object).length === 0);
-  if (isClear) {
-    fields.pause_collection = null;
-    return 'customer.subscription.resumed';
-  }
-  if (!pc || typeof pc !== 'object') return undefined;
-  const p = pc as Row;
-  fields.pause_collection = { behavior: typeof p.behavior === 'string' ? p.behavior : 'void', resumes_at: p.resumes_at !== undefined ? Number(p.resumes_at) : null };
-  return 'customer.subscription.paused';
-}
-
-/** A coupon that replaces the subscription's discount, or an empty one that clears it (docs.stripe.com/api/subscriptions/update#update_subscription-discounts). */
-function replacedDiscounts(ctx: SemanticsContext, couponId: string, sub: Row): Row[] | Response {
-  if (couponId === '') return [];
-  const coupon = ctx.get('coupon', couponId);
-  return coupon ? [buildDiscount(coupon, String(sub.customer ?? ''), Number(ctx.now()), { subscription: String(sub.id) })] : fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
-}
-
-/** The longest trial Stripe takes: `trial_end` "Can be at most two years from `billing_cycle_anchor`"
- *  (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end); "The trial period must be 730 days (2 years)
- *  or less" (docs.stripe.com/billing/subscriptions/trials/free-trials). */
-const MAX_TRIAL = 730 * 86400;
-
-/** A `trial_end` Stripe refuses: the parameter is `"now" | timestamp` (docs.stripe.com/api/subscriptions/update), and a
- *  timestamp that is not in the future answers "Invalid timestamp: must be an integer Unix timestamp in the future."
- *  (Stripe's own message, as its SDKs' users report it: github.com/stripe/stripe-dotnet/issues/805,
- *  github.com/stripe/stripe-ruby/issues/682). Where the documentation stops and the twin decides: a value that is no
- *  number at all, and one more than two years on, answer that same message. */
-export function trialEndRefused(ctx: SemanticsContext, value: unknown, now: number): Response | undefined {
-  const t = typeof value === 'number' ? value : typeof value === 'string' && /^\d+$/.test(value.trim()) ? Number(value) : NaN;
-  return value === undefined || value === 'now' || (Number.isInteger(t) && t > now && t <= now + MAX_TRIAL) ? undefined : invalidTrialEnd(ctx);
-}
-
-function invalidTrialEnd(ctx: SemanticsContext): Response {
-  return ctx.refuse({ status: 400, param: 'trial_end', message: 'Invalid timestamp: must be an integer Unix timestamp in the future.' });
-}
-
-/** An update's `trial_end` on the subscription, into `fields`.
- *
- *  `now` on a trialing subscription ends its trial at once: "The special value `now` can be provided to end the customer's
- *  trial immediately" (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end; the trials guide's "To end a
- *  trial early … setting the `trial_end` value to … **now** to end immediately", docs.stripe.com/billing/subscriptions/
- *  trials/free-trials). The update resets the billing date and charges at once: "Switching prices does not normally change
- *  the billing date or generate an immediate charge unless … A trial starts or ends. In these cases, we … immediately
- *  charge the customer using the new price, and reset the billing date" (docs.stripe.com/api/subscriptions/update), and
- *  "Stripe immediately attempts payment when a subscription's billing cycle anchor is reset … When billing is performed
- *  immediately, but the required payment fails, the subscription change request succeeds and the subscription transitions
- *  to `past_due`" (docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment). So a new period starts now,
- *  its invoice is made (`invoice.created`) and charged to the subscription's default payment method, else the
- *  customer's (paid: `invoice.paid`, the subscription `active`; declined or none: the invoice open, `past_due`), and the
- *  subscription's own write sends `customer.subscription.updated`. `payment_behavior` (the same page): `error_if_incomplete`
- *  answers 402 and leaves the subscription as it was, `default_incomplete` leaves the invoice open without an attempt.
- *
- *  A future timestamp moves the trial's end, and the period and billing anchor with it: "The `billing_cycle_anchor` will be
- *  updated to the `trial_end` value" (the same parameter); on a subscription out of its trial it starts a new one ("You can
- *  add a new trial on a non-trialing subscription by updating the subscription while specifying trial_end", and for
- *  classic billing mode "the `trial_start` field remains set to the start of the first trial", docs.stripe.com/billing/
- *  subscriptions/trials/free-trials).
- *
- *  Where the documentation stops and the twin decides: the invoice's billing_reason is `subscription_update` ("A
- *  subscription was updated", docs.stripe.com/api/invoices/object#invoice_object-billing_reason); `now` on a subscription
- *  that is not trialing has no trial to end and changes nothing; the credit Stripe prorates for the unused time when a new
- *  trial starts mid-period is not made (as `proration_behavior=none` would have it); `pending_if_incomplete` answers as
- *  `allow_incomplete` (no pending update is modelled). Answers a refusal, or the invoice to collect once the subscription is written. */
-async function applyTrialEnd(ctx: SemanticsContext, sub: Row, fields: Row, now: number): Promise<{ invoice: string; payer?: string; attempt: boolean } | undefined> {
-  const value = ctx.params.trial_end;
-  delete fields.trial_end;
-  const id = String(sub.id);
-  if (value !== 'now' || sub.status !== 'trialing') return value === 'now' ? undefined : movedTrial(sub, fields, Number(value), now);
-  // the period's invoice bills the items as this update leaves them, under its discount
-  const next: Row = { ...sub, ...fields, items: ctx.get(SUB, id)?.items ?? sub.items };
-  const { interval, interval_count } = resolveSubscriptionBillingInterval(((next.items as { data?: Row[] } | undefined)?.data) ?? [], finder(ctx));
-  const period = { start: now, end: addBillingInterval(now, interval, interval_count) };
-  const invoice = await draftSubscriptionInvoice(ctx, next, { ...period, reason: 'subscription_update' });
-  Object.assign(fields, { trial_end: now, billing_cycle_anchor: now, current_period_start: period.start, current_period_end: period.end, latest_invoice: invoice });
-  const payer = trialPayer(ctx, sub);
-  return { invoice, ...(payer ? { payer } : {}), attempt: ctx.params.payment_behavior !== 'default_incomplete' };
-}
-
-/** A trial moved to end at `end`, or a new one to `end` on a subscription out of its trial (applyTrialEnd). */
-function movedTrial(sub: Row, fields: Row, end: number, now: number): undefined {
-  Object.assign(fields, {
-    status: 'trialing', trial_end: end, trial_start: sub.trial_start ?? now, billing_cycle_anchor: end,
-    current_period_end: end, ...(sub.status !== 'trialing' ? { current_period_start: now } : {}),
-  });
-  return undefined;
-}
-
-/** What ending the trial charges: the update's own default payment method, else the subscription's, else its customer's. */
-function trialPayer(ctx: SemanticsContext, sub: Row): string | undefined {
-  const given = ctx.params.default_payment_method;
-  return typeof given === 'string' && given ? given : payerOf(ctx, sub);
-}
-
-/** What an update's `trial_end` refuses before anything is written: a new trial the machine does not allow from the
- *  subscription's status, or, under `error_if_incomplete`, ending a trial that cannot be paid at once ("If payment fails,
- *  return an HTTP `402` status code and don't update the subscription", docs.stripe.com/api/subscriptions/update). */
-function trialEndBlocked(ctx: SemanticsContext, sub: Row, discounts: Row[] | undefined): Response | undefined {
-  if (ctx.params.trial_end !== 'now') return newTrialRefused(ctx, sub);
-  if (sub.status !== 'trialing') return undefined;
-  const charge = trialEndCharge(ctx, sub, discounts);
-  if (ctx.params.payment_behavior === 'error_if_incomplete' && charge.due > 0 && !charge.pays) return firstPaymentRefused(ctx, charge.declined);
-  // the move ending the trial makes (paid or nothing due: active; else past_due) is the machine's, asked before
-  // anything is written
-  const refused = ctx.legal(SUB, 'status', ctx.call.operation.id, 'trialing', charge.due <= 0 || charge.pays ? 'active' : 'past_due', String(sub.id));
-  return refused ? ctx.refuse(refused) : undefined;
 }
 
-/** A price named by id, or given as an object. */
-function priceRow(ctx: SemanticsContext, price: unknown): Row | undefined {
-  return typeof price === 'string' ? ctx.get('price', price) : price && typeof price === 'object' ? (price as Row) : undefined;
-}
-
-/** One period of the subscription's items as an update's `items` would leave them, before any discount: an entry naming
- *  an item changes its price and quantity (a new price resets the quantity to 1 unless one is given) or deletes it, and
- *  one naming none adds an item (applyItemChanges). */
-function dueAfter(ctx: SemanticsContext, sub: Row, entries: Row[]): number {
-  const lines = new Map<string, { price: Row | undefined; quantity: number }>();
-  for (const it of ((sub.items as { data?: Row[] } | undefined)?.data) ?? []) lines.set(String(it.id), { price: priceRow(ctx, it.price), quantity: itemQuantity(it) });
-  entries.forEach((e, i) => entryAfter(ctx, lines, e, i));
-  return [...lines.values()].reduce((sum, l) => sum + priceAmount(l.price, l.quantity), 0);
-}
-
-/** One entry of an update's `items` on the lines it would leave (dueAfter). */
-function entryAfter(ctx: SemanticsContext, lines: Map<string, { price: Row | undefined; quantity: number }>, e: Row, i: number): void {
-  // an inline price bills as the Price inlinePrice makes of it
-  const d = e.price_data && typeof e.price_data === 'object' ? (e.price_data as Row) : undefined;
-  const inline: Row | undefined = d ? (d.unit_amount_decimal !== undefined ? { unit_amount_decimal: String(d.unit_amount_decimal) } : { unit_amount: Math.trunc(Number(d.unit_amount) || 0) }) : undefined;
-  const price = typeof e.price === 'string' && e.price ? priceRow(ctx, e.price) : inline;
-  const named = typeof e.id === 'string' && e.id;
-  const key = named ? String(e.id) : `new_${i}`;
-  // only a named item is deleted; an entry naming none adds one, as applyItemChanges does
-  if (named && asBool(e.deleted)) { lines.delete(key); return; }
-  const was = lines.get(key);
-  const quantity = e.quantity !== undefined ? Math.max(0, Math.trunc(Number(e.quantity) || 0)) : price && was && price.id !== was.price?.id ? 1 : was?.quantity ?? 1;
-  lines.set(key, { price: price ?? was?.price, quantity });
-}
-
-/** A new trial on a subscription whose status the machine does not let start one. */
-function newTrialRefused(ctx: SemanticsContext, sub: Row): Response | undefined {
-  const refused = sub.status === 'trialing' ? undefined : ctx.legal(SUB, 'status', ctx.call.operation.id, sub.status, 'trialing', String(sub.id));
-  return refused ? ctx.refuse(refused) : undefined;
-}
-
-/** What ending the trial charges, judged before anything is written: the period of the items as this update leaves them
- *  (dueAfter) under the discount it leaves, and whether the payer pays it (an attempt made, a payer, no decline). */
-function trialEndCharge(ctx: SemanticsContext, sub: Row, discounts: Row[] | undefined): { due: number; pays: boolean; declined?: ReturnType<typeof declineFor> } {
-  const subtotal = dueAfter(ctx, sub, subscriptionItemEntries(ctx.params.items));
-  // the discount the subscription carries after this update takes this invoice (renewals.ts draftSubscriptionInvoice)
-  const discount = (discounts ?? (sub.discounts as Row[] | undefined) ?? [])[0];
-  const coupon = discount && typeof discount === 'object' ? (discount.coupon as Row | undefined) : undefined;
-  const due = subtotal - (coupon ? applyCouponDiscount(subtotal, coupon) : 0);
-  const payer = trialPayer(ctx, sub);
-  const attempt = ctx.params.payment_behavior !== 'default_incomplete';
-  const declined = payer && attempt ? declineFor(finder(ctx), { payment_method: payer }) : undefined;
-  return { due, pays: attempt && !!payer && !declined, ...(declined ? { declined } : {}) };
-}
-
-const update: Semantics = async (ctx) => {
+export async function PostSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'subscription_exposed_id');
   // a period that has already ended renews (or a trial that has, ends) before the update applies (renewals.ts)
   await advanceBilling(ctx, (s) => s.id === id);
-  const sub = ctx.get(SUB, id);
+  const sub = resourceView(ctx, SUB, id);
   if (!sub) return subMissing(ctx, id);
   const params = ctx.params;
   const now = clockNow(ctx, sub.customer);
@@ -381,7 +79,7 @@ const update: Semantics = async (ctx) => {
   // scheduled cancel follows a period this update moves
   if ('cancel_at_period_end' in params) {
     fields.cancel_at_period_end = asBool(params.cancel_at_period_end);
-    Object.assign(fields, fields.cancel_at_period_end ? { cancel_at: fields.current_period_end ?? sub.current_period_end ?? null, canceled_at: Number(ctx.now()) } : { cancel_at: null, canceled_at: null });
+    Object.assign(fields, fields.cancel_at_period_end ? { cancel_at: fields.current_period_end ?? sub.current_period_end ?? null, canceled_at: Number(nowUnix(ctx.occurredAt)) } : { cancel_at: null, canceled_at: null });
   } else if (sub.cancel_at_period_end === true && fields.current_period_end !== undefined) fields.cancel_at = fields.current_period_end;
   if (trial?.invoice) {
     // the trial's end is charged at once: paid (or nothing due), the subscription is active; not, past_due
@@ -391,220 +89,19 @@ const update: Semantics = async (ctx) => {
     fields.status = pays ? 'active' : 'past_due';
     if (fields.discounts !== undefined) fields.discounts = keptAfter(fields.discounts as Row[], ctx.get('invoice', trial.invoice) ?? {});
   }
-  return ctx.reply(await ctx.write(SUB, id, fields, op));
-};
-
-/** A new item named with neither `price` nor `price_data`: "One of `price` or `price_data` is required"
- *  (docs.stripe.com/api/subscriptions/update). */
-function noItemPrice(ctx: SemanticsContext): Response {
-  return fail(ctx, 'Missing required param: items[price].', 400, 'parameter_missing');
-}
-
-/** A subscription asked to fail when its first invoice cannot be paid at once (payment_behavior=error_if_incomplete):
- *  the card's decline, or no payment method to charge (docs.stripe.com/api/subscriptions/create#create_subscription-payment_behavior). */
-function firstPaymentRefused(ctx: SemanticsContext, declined: Parameters<typeof cardError>[0] | null | undefined): Response {
-  return declined ? send(ctx, cardError(declined)) : fail(ctx, 'This customer has no attached payment source or default payment method.', 400, 'resource_missing');
-}
-
-/** An update's `items`: "A list of up to 20 subscription items, each with an attached price"
- *  (docs.stripe.com/api/subscriptions/update): an entry naming an item's `id` changes that item (its price, quantity,
- *  metadata) or, with `deleted` ("A flag that, if set to `true`, will delete the specified item"), removes it; "If you
- *  omit `id`, the API adds a new subscription item rather than updating the existing one". Each takes `price` or
- *  `price_data`, "Data used to generate a new Price object inline. One of `price` or `price_data` is required", and
- *  "When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided". An
- *  inline price is made as the manage-prices guide says: "By default, prices created with `price_data` are effectively
- *  archived (they're marked as `active=false`)" (docs.stripe.com/products-prices/manage-prices).
- *  Where the documentation stops and the twin decides: the update is all or nothing, every entry checked before any is
- *  written (Stripe answers one error for the request); the refusals are worded by the twin. */
-async function applyItemChanges(ctx: SemanticsContext, subId: string, entries: Row[]): Promise<Response | undefined> {
-  // every entry is checked first: a refusal leaves the subscription as it was
-  const refused = itemChangesRefused(ctx, subId, entries);
-  if (refused) return refused;
-  return writeItemChanges(ctx, subId, entries);
-}
-
-/** The refusal of an update's `items`, checked entry by entry before any is written (applyItemChanges). */
-function itemChangesRefused(ctx: SemanticsContext, subId: string, entries: Row[]): Response | undefined {
-  for (const entry of entries) {
-    const priceRef = typeof entry.price === 'string' && entry.price ? entry.price : undefined;
-    if (priceRef && !ctx.get('price', priceRef)) return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
-    const inline = !priceRef && entry.price_data && typeof entry.price_data === 'object' ? (entry.price_data as Row) : undefined;
-    if (inline) {
-      const refused = refuseInlinePrice(ctx, inline);
-      if (refused) return refused;
-    }
-    if (typeof entry.id === 'string' && entry.id) {
-      const si = ctx.get('subscription_item', entry.id);
-      if (!si || si.subscription !== subId) return fail(ctx, `No such subscription_item: '${entry.id}'`, 400, 'resource_missing');
-    } else if (!priceRef && !inline) return noItemPrice(ctx);
-  }
-  return undefined;
-}
-
-/** An update's checked `items`, written. */
-async function writeItemChanges(ctx: SemanticsContext, subId: string, entries: Row[]): Promise<undefined> {
-  for (const entry of entries) {
-    const inline = typeof entry.price === 'string' && entry.price ? undefined : entry.price_data && typeof entry.price_data === 'object' ? (entry.price_data as Row) : undefined;
-    const priceRef = typeof entry.price === 'string' && entry.price ? entry.price : inline ? await inlinePrice(ctx, inline) : undefined;
-    // only a price that changes resets the quantity; one naming the item's own price leaves it
-    const was = typeof entry.id === 'string' && entry.id ? ctx.get('subscription_item', entry.id)?.price : undefined;
-    const wasId = typeof was === 'string' ? was : was && typeof was === 'object' ? String((was as Row).id ?? '') : undefined;
-    const quantity = entry.quantity !== undefined ? { quantity: Math.max(0, Math.trunc(Number(entry.quantity) || 0)) } : priceRef && priceRef !== wasId ? { quantity: 1 } : {};
-    const metadata = entry.metadata && typeof entry.metadata === 'object' ? { metadata: entry.metadata } : {};
-    if (typeof entry.id === 'string' && entry.id) {
-      if (asBool(entry.deleted)) { await ctx.write('subscription_item', entry.id, { deleted: true }, 'subscription_item.delete'); continue; }
-      await ctx.write('subscription_item', entry.id, { ...(priceRef ? subscriptionItemPrice(priceRef, finder(ctx)) : {}), ...quantity, ...metadata }, 'subscription_item.update');
-    } else {
-      await created(ctx, 'subscription_item', { subscription: subId, ...subscriptionItemPrice(priceRef, finder(ctx)), quantity: 1, ...quantity, ...metadata }, { livemode: false, metadata: {}, discounts: [], tax_rates: [], billing_thresholds: null });
-    }
-  }
-  await syncItems(ctx, subId);
-  return undefined;
+  return ctx.reply(ctx.expand(SUB, await ctx.write(SUB, id, fields, op)));
 }
 
-/** A subscription item's `price_data` Stripe would refuse: its required `currency`, `product` (an existing one) and
- *  `recurring[interval]`, and "Only one of `unit_amount` and `unit_amount_decimal` can be set". */
-function refuseInlinePrice(ctx: SemanticsContext, d: Row): Response | undefined {
-  for (const name of ['currency', 'product']) if (typeof d[name] !== 'string' || !d[name]) return fail(ctx, `Missing required param: items[price_data][${name}].`, 400, 'parameter_missing');
-  if (!ctx.get('product', String(d.product))) return fail(ctx, `No such product: '${String(d.product)}'`, 400, 'resource_missing');
-  const interval = (d.recurring as Row | undefined)?.interval;
-  if (!['day', 'week', 'month', 'year'].includes(String(interval))) return fail(ctx, 'Missing required param: items[price_data][recurring][interval].', 400, 'parameter_missing');
-  if (d.unit_amount !== undefined && d.unit_amount_decimal !== undefined) return fail(ctx, 'Only one of `unit_amount` and `unit_amount_decimal` can be set.', 400, 'parameter_invalid');
-  return undefined;
-}
 
-/** The inline Price a `price_data` generates: recurring, archived (active=false). Answers its id. */
-async function inlinePrice(ctx: SemanticsContext, d: Row): Promise<string> {
-  const r = d.recurring as Row;
-  const decimal = d.unit_amount_decimal !== undefined ? String(d.unit_amount_decimal) : String(Math.trunc(Number(d.unit_amount) || 0));
-  const price = await created(ctx, 'price', {
-    product: d.product, currency: String(d.currency).toLowerCase(),
-    // a decimal amount that is not a whole number of the smallest unit has no integer unit_amount (as semantics/plans.ts)
-    unit_amount: d.unit_amount_decimal !== undefined ? (Number.isInteger(Number(d.unit_amount_decimal)) ? Number(d.unit_amount_decimal) : null) : Math.trunc(Number(d.unit_amount) || 0), unit_amount_decimal: decimal,
-    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 },
-    tax_behavior: typeof d.tax_behavior === 'string' ? d.tax_behavior : 'unspecified',
-  }, { active: false, livemode: false, billing_scheme: 'per_unit', type: 'recurring', metadata: {}, lookup_key: null, nickname: null });
-  return String(price.id);
-}
 
-const deleteDiscount: Semantics = async (ctx) => {
+export async function DeleteSubscriptionsSubscriptionExposedIdDiscount(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'subscription_exposed_id');
-  const sub = ctx.get(SUB, id);
+  const sub = resourceView(ctx, SUB, id);
   if (!sub) return subMissing(ctx, id);
+  // source: spec:DeleteSubscriptionsSubscriptionExposedIdDiscount "Removes the currently applied discount on a subscription."
   const current = ((sub.discounts as unknown[] | undefined) ?? [])[0] ?? sub.discount;
+  // Where the documentation stops and the twin decides: a subscription with no discount answers its absence as a missing resource.
   if (!current) return fail(ctx, `No active discount for subscription: '${id}'`, 404, 'resource_missing');
   await ctx.write(SUB, id, { discounts: [] }, 'subscription.update');
-  return ctx.reply(deletedDiscount(typeof current === 'string' ? { id: current } : (current as Row), ctx.now()));
-};
-
-// canceling keeps the subscription, now canceled, stamped with when it was canceled and ended
-// (https://docs.stripe.com/api/subscriptions/object#subscription_object-canceled_at, #subscription_object-ended_at)
-const cancel: Semantics = async (ctx) => {
-  const id = at(ctx, 'subscription_exposed_id');
-  const sub = ctx.get(SUB, id);
-  if (!sub) return subMissing(ctx, id);
-  const refused = ctx.legal(SUB, 'status', 'DeleteSubscriptionsSubscriptionExposedId', sub.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  const now = ctx.now();
-  // why it was canceled: the request's `cancellation_details` ("Details about why this subscription was cancelled"), and
-  // the reason Stripe records for a cancel asked through the API, as the cancel page's example answers it:
-  // `"reason": "cancellation_requested"` (docs.stripe.com/api/subscriptions/cancel)
-  const given = ctx.params.cancellation_details && typeof ctx.params.cancellation_details === 'object' ? (ctx.params.cancellation_details as Row) : {};
-  const cancellation_details = { comment: given.comment ?? null, feedback: given.feedback ?? null, reason: 'cancellation_requested' };
-  return ctx.reply(await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel'));
-};
-
-// ── items: each write keeps the parent subscription's items.data in step, rebuilt from the live items ──
-
-/** A new subscription's items, each its own subscription_item as Stripe keeps it (/v1/subscription_items/{id}). */
-export async function storeItems(ctx: SemanticsContext, subId: string, items: Row[]): Promise<void> {
-  for (const item of items) {
-    if (typeof item.id !== 'string' || ctx.get('subscription_item', item.id)) continue;
-    await ctx.write('subscription_item', item.id, { ...item, subscription: subId }, 'subscription_item.create');
-  }
+  return ctx.reply(deletedDiscount(typeof current === 'string' ? { id: current } : { ...(current as Row), subscription: id }, nowUnix(ctx.occurredAt)));
 }
-
-async function syncItems(ctx: SemanticsContext, subId: string): Promise<void> {
-  if (!subId) return;
-  const items = ctx.rows('subscription_item').filter((r) => r.subscription === subId);
-  await ctx.write(SUB, subId, { items: { object: 'list', data: items, has_more: false, total_count: items.length, url: `/v1/subscription_items?subscription=${subId}` } }, 'subscription.items_synced');
-}
-
-/** A subscription item with its billing period: its subscription's (basil moved the period onto the items). */
-const withPeriod = (ctx: SemanticsContext, si: Row): Row => {
-  const sub = ctx.get(SUB, String(si.subscription));
-  return { ...si, current_period_start: si.current_period_start ?? sub?.current_period_start ?? null, current_period_end: si.current_period_end ?? sub?.current_period_end ?? null };
-};
-
-const createItem: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const subId = typeof params.subscription === 'string' ? params.subscription : '';
-  if (!subId) return fail(ctx, 'Missing required param: subscription.', 400, 'parameter_missing');
-  if (!ctx.get(SUB, subId)) return subMissing(ctx, subId);
-  const priceRef = typeof params.price === 'string' ? params.price : '';
-  if (!priceRef && !(params.price_data && typeof params.price_data === 'object')) return fail(ctx, 'Missing required param: price.', 400, 'parameter_missing');
-  if (priceRef && !ctx.get('price', priceRef)) return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
-  const quantity = params.quantity !== undefined ? Math.max(0, Math.trunc(Number(params.quantity) || 0)) : 1;
-  // "metadata: Set of key-value pairs that you can attach to an object" (docs.stripe.com/api/subscription_items/create)
-  const metadata = params.metadata && typeof params.metadata === 'object' ? { metadata: params.metadata } : {};
-  const body = await created(ctx, 'subscription_item', { subscription: subId, ...(priceRef ? subscriptionItemPrice(priceRef, finder(ctx)) : { price: null, plan: null }), quantity, ...metadata }, { livemode: false, metadata: {} });
-  await syncItems(ctx, subId);
-  return ctx.reply(withPeriod(ctx, body));
-};
-
-const listItems: Semantics = async (ctx) => {
-  const subId = typeof ctx.params.subscription === 'string' ? ctx.params.subscription : '';
-  if (!subId) return fail(ctx, 'Missing required param: subscription.', 400, 'parameter_missing');
-  if (!ctx.get(SUB, subId)) return subMissing(ctx, subId);
-  return list(ctx, 'subscription_item', newest(ctx, 'subscription_item').filter((si) => si.subscription === subId).map((si) => withPeriod(ctx, si)));
-};
-
-const ITEM_ATTRIBUTES = new Set(['billing_thresholds', 'discounts', 'metadata', 'price', 'quantity', 'tax_rates']);
-
-const itemMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such subscription_item: '${id}'`, 404, 'resource_missing');
-
-const updateItem: Semantics = async (ctx) => {
-  const id = at(ctx, 'item');
-  const si = ctx.get('subscription_item', id);
-  if (!si) return itemMissing(ctx, id);
-  // only the item's own attributes are kept; the update's instructions (off_session, payment_behavior, price_data,
-  // proration_behavior, proration_date) are not attributes of the Subscription Item object
-  // (docs.stripe.com/api/subscription_items/object lists none of them)
-  const fields: Row = Object.fromEntries(Object.entries(ctx.params).filter(([k]) => ITEM_ATTRIBUTES.has(k)));
-  if (ctx.params.quantity !== undefined) fields.quantity = Math.max(0, Math.trunc(Number(ctx.params.quantity) || 0));
-  if (typeof ctx.params.price === 'string' && ctx.params.price && !ctx.get('price', ctx.params.price)) return fail(ctx, `No such price: '${ctx.params.price}'`, 400, 'resource_missing');
-  // the item carries its Price and plan, as the subscription's own items do (subscriptionItemPrice)
-  if (typeof ctx.params.price === 'string' && ctx.params.price) Object.assign(fields, subscriptionItemPrice(ctx.params.price, finder(ctx)));
-  const out = await ctx.write('subscription_item', id, fields, 'subscription_item.update');
-  await syncItems(ctx, String(si.subscription));
-  return ctx.reply(withPeriod(ctx, out));
-};
-
-const retrieveItem: Semantics = async (ctx) => {
-  const si = ctx.get('subscription_item', at(ctx, 'item'));
-  return si ? ctx.reply(withPeriod(ctx, si)) : itemMissing(ctx, at(ctx, 'item'));
-};
-
-const deleteItem: Semantics = async (ctx) => {
-  const id = at(ctx, 'item');
-  const si = ctx.get('subscription_item', id);
-  if (!si) return itemMissing(ctx, id);
-  await ctx.write('subscription_item', id, { deleted: true }, 'subscription_item.delete');
-  await syncItems(ctx, String(si.subscription));
-  return ctx.reply({ id, object: 'subscription_item', deleted: true });
-};
-
-export const subscriptions: Record<string, Semantics> = {
-  PostSubscriptions: create,
-  GetSubscriptions: listSubscriptions,
-  GetSubscriptionsSearch: searchSubscriptions,
-  GetSubscriptionsSubscriptionExposedId: retrieveSubscription,
-  PostSubscriptionsSubscriptionExposedId: update,
-  DeleteSubscriptionsSubscriptionExposedIdDiscount: deleteDiscount,
-  DeleteSubscriptionsSubscriptionExposedId: cancel,
-  PostSubscriptionItems: createItem,
-  GetSubscriptionItems: listItems,
-  PostSubscriptionItemsItem: updateItem,
-  GetSubscriptionItemsItem: retrieveItem,
-  DeleteSubscriptionItemsItem: deleteItem,
-};