@volter/twin-stripe 2.0.37 → 3.0.0

package/src/semantics/subscriptions.ts

@@ -1,34 +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';
+// 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 { deletedDiscount, type Row } from '../engine/common.ts';
+import { itemQuantity, keptAfter } from '../engine/renewals.ts';
+import { addBillingInterval, applyCouponDiscount, asBool, buildDiscount, buildSubscriptionItemsList, declineFor, mintClientSecret, nowUnix, priceAmount, resolveSubscriptionBillingInterval, resolveTrial, subscriptionCouponParam, subscriptionHasPrice, subscriptionItemEntries } from '../engine/stripe.ts';
+import { pauseCollection, SUB } from '../engine/subscriptions.ts';
+import { advanceBilling, applyItemChanges, applyTrialEnd, at, clockNow, collectSubscriptionInvoice, created, draftSubscriptionInvoice, expanded, fail, finalizedFields, finder, firstPaymentRefused, itemChangesRefused, list, mintCharge, newest, redeemCoupon, replacedDiscounts, search, spendOnceCoupon, storeItems, subMissing, trialEndBlocked, trialEndRefused, where } from './shared.ts';
 
-const SUB = 'subscription';
-const subMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such subscription: '${id}'`, 404, 'resource_missing');
+// 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 = 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 = 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(await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel'));
+}
+
+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)),
+  }));
+}
+
+export async function GetSubscriptionsSearch(ctx: HandlerContext): Promise<Response> {
+  await advanceBilling(ctx);
+  return search(ctx, SUB);
+}
+
+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);
+  return sub ? ctx.reply(expanded(ctx, SUB, sub)) : subMissing(ctx, id);
+}
 
-const create: Semantics = async (ctx) => {
+export async function PostSubscriptions(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
   const customer = typeof params.customer === 'string' ? params.customer : '';
   if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
@@ -146,7 +163,7 @@ const create: Semantics = async (ctx) => {
   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,
+      status: pays ? 'succeeded' : 'requires_payment_method', client_secret: mintClientSecret(piId, await ctx.secret(`client-secret:${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,
@@ -156,194 +173,9 @@ const create: Semantics = async (ctx) => {
   // 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));
-};
-
-const listSubscriptions: Semantics = async (ctx) => {
-  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) => {
-  const id = at(ctx, 'subscription_exposed_id');
-  await advanceBilling(ctx, (sub) => sub.id === id);
-  const sub = ctx.get(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);
@@ -381,7 +213,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
@@ -392,219 +224,4 @@ const update: Semantics = async (ctx) => {
     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;
-}
-
-/** 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) => {
-  const id = at(ctx, 'subscription_exposed_id');
-  const sub = ctx.get(SUB, id);
-  if (!sub) return subMissing(ctx, id);
-  const current = ((sub.discounts as unknown[] | undefined) ?? [])[0] ?? sub.discount;
-  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');
-  }
-}
-
-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,
-};

package/src/semantics/{test-clocks.ts → test_helpers.ts}

@@ -1,27 +1,21 @@
-// Test clock semantics. A test clock is Stripe's own door for a transition no API verb makes: the
-// passage of time. Advancing it moves the subscriptions of the clock's customers as a real clock tick does:
-// trials that ended end, and periods that ended renew (./renewals.ts advanceBilling). List, retrieve and delete are
-// the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { at, created, fail } from './shared.ts';
-import { advanceBilling } from './renewals.ts';
-
-const CLOCK = 'test_helpers.test_clock';
-
-const create: Semantics = async (ctx) => {
-  if (ctx.params.frozen_time === undefined) return fail(ctx, 'Missing required param: frozen_time.', 400, 'parameter_missing');
-  const frozen = Math.trunc(Number(ctx.params.frozen_time) || 0);
-  // "Simulations are automatically deleted 30 days after you create them" (docs.stripe.com/billing/testing/test-clocks/
-  // api-advanced-usage): from its creation on the account's clock, not its frozen time
-  return ctx.reply(await created(ctx, CLOCK, { name: ctx.params.name ?? null }, { frozen_time: frozen, status: 'ready', status_details: {}, livemode: false, deletes_after: Number(ctx.now()) + 30 * 24 * 3600 }));
-};
+// Stripe's test_helpers 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 { AUTH, CARD, cardId, CH, historyEntry, holderId, merchantData, TXN } from '../engine/issuing.ts';
+import { isValidApiVersion, nowUnix, spendingControlsViolation, TWIN_API_VERSION } from '../engine/stripe.ts';
+import { READER } from '../engine/terminal.ts';
+import { CLOCK } from '../engine/test-clocks.ts';
+import { FA, TX } from '../engine/treasury.ts';
+import { stripeEventMatches } from '../engine/webhooks.ts';
+import { answeredByEndpoint, approvedAtOnce, askForAuthorization, at, authMissing, balanceOf, capture, cashBalance, created, customerMissing, fail, holdForCapture, issuingRefusal, mintCharge, nothingToPresent, readerMissing, received, reconcile, review, withCard } from './shared.ts';
 
 /** A test clock deleted with what lives on it: "Deleting the simulation also deletes the test customers associated
  *  with the clock and cancels their subscriptions" (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). */
-const remove: Semantics = async (ctx) => {
+export async function DeleteTestHelpersTestClocksTestClock(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'test_clock');
   if (!ctx.get(CLOCK, id)) return fail(ctx, `No such test clock: '${id}'`, 404, 'resource_missing');
-  const now = Number(ctx.now());
+  const now = Number(nowUnix(ctx.occurredAt));
   for (const c of ctx.rows('customer').filter((c) => c.test_clock === id)) {
     for (const sub of ctx.rows('subscription').filter((s) => s.customer === c.id && s.status !== 'canceled')) {
       ctx.legal('subscription', 'status', 'DeleteTestHelpersTestClocksTestClock', String(sub.status), 'canceled', String(sub.id));
@@ -31,9 +25,17 @@ const remove: Semantics = async (ctx) => {
   }
   await ctx.write(CLOCK, id, { deleted: true }, 'test_clock.deleted');
   return ctx.reply({ id, object: 'test_helpers.test_clock', deleted: true });
-};
+}
+
+export async function PostTestHelpersTestClocks(ctx: HandlerContext): Promise<Response> {
+  if (ctx.params.frozen_time === undefined) return fail(ctx, 'Missing required param: frozen_time.', 400, 'parameter_missing');
+  const frozen = Math.trunc(Number(ctx.params.frozen_time) || 0);
+  // "Simulations are automatically deleted 30 days after you create them" (docs.stripe.com/billing/testing/test-clocks/
+  // api-advanced-usage): from its creation on the account's clock, not its frozen time
+  return ctx.reply(await created(ctx, CLOCK, { name: ctx.params.name ?? null }, { frozen_time: frozen, status: 'ready', status_details: {}, livemode: false, deletes_after: Number(nowUnix(ctx.occurredAt)) + 30 * 24 * 3600 }));
+}
 
-const advance: Semantics = async (ctx) => {
+export async function PostTestHelpersTestClocksTestClockAdvance(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'test_clock');
   const clock = ctx.get(CLOCK, id);
   if (!clock) return fail(ctx, `No such test clock: '${id}'`, 404, 'resource_missing');
@@ -47,31 +49,5 @@ const advance: Semantics = async (ctx) => {
   // and finishClockAdvances completes it ADVANCE_SECONDS of World time later; an advance asked meanwhile is refused
   // test_clock_not_ready (the machine's refusal).
   return ctx.reply(await ctx.write(CLOCK, id, { status: 'advancing', status_details: { advancing: { target_frozen_time: to } } }, 'test_clock.advancing'));
-};
-
-/** How long an advance takes: "it takes a few seconds to advance to the specified time"
- *  (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). Where the documentation stops and the twin decides:
- *  five seconds of World time from the advance. */
-const ADVANCE_SECONDS = 5;
-
-/** Each advancing clock whose advance has taken its time reaches its target, caught up before anything is answered:
- *  its frozen_time moves, it is ready, and its customers' trials and periods that ended by then end
- *  (./renewals.ts advanceBilling). The advance's own write is when it began (the kernel's updatedAt). */
-export async function finishClockAdvances(ctx: SemanticsContext): Promise<void> {
-  const now = Number(ctx.now());
-  for (const clock of ctx.rowsRaw(CLOCK)) {
-    if (clock.status !== 'advancing') continue;
-    if (Date.parse(String(clock.updatedAt)) / 1000 + ADVANCE_SECONDS > now) continue;
-    const id = String(clock.id);
-    const target = Number((clock.status_details as { advancing?: { target_frozen_time?: number } } | undefined)?.advancing?.target_frozen_time);
-    ctx.legal(CLOCK, 'status', ctx.call.operation.id, 'advancing', 'ready', id, 'vendor');
-    await ctx.write(CLOCK, id, { frozen_time: target, status: 'ready', status_details: {} }, 'test_clock.ready');
-    await advanceBilling(ctx, (sub) => typeof sub.customer === 'string' && ctx.get('customer', sub.customer)?.test_clock === id);
-  }
 }
 
-export const testClocks: Record<string, Semantics> = {
-  PostTestHelpersTestClocks: create,
-  PostTestHelpersTestClocksTestClockAdvance: advance,
-  DeleteTestHelpersTestClocksTestClock: remove,
-};