@volter/twin-stripe 2.0.38 → 3.0.1

package/src/semantics/renewals.ts

@@ -1,279 +0,0 @@
-// A subscription's invoices over time: the first one Checkout pays, and each renewal. Time's moves are made
-// as the twin's trial end already made them: caught up to the customer's clock (the World's, or its test
-// clock) whenever the twin is asked anything (../stripe-server.ts), each checked against the machines in
-// ../manifest.ts.
-//
-// - Checkout's subscription session pays the first invoice with the card the customer entered, which becomes the
-//   subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works); nothing is due
-//   on a trial's.
-// - At each period's end Stripe drafts a `subscription_cycle` invoice for the next period and advances the
-//   period; a trial's end is the first such renewal, and the subscription is active from then
-//   (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions,
-//   docs.stripe.com/billing/subscriptions/trials).
-// - About an hour after, Stripe finalizes the draft and charges the subscription's default payment method,
-//   else the customer's (docs.stripe.com/invoicing/integration/workflow-transitions#finalized,
-//   docs.stripe.com/api/subscriptions/object#subscription_object-default_payment_method).
-// - A declined renewal leaves the invoice open with its attempt counted and the subscription past_due
-//   (docs.stripe.com/billing/subscriptions/overview#payment-status); paying the invoice later, through the API
-//   (docs.stripe.com/api/invoices/pay) or on the customer portal (docs.stripe.com/customer-management), makes it
-//   active again.
-//
-// Where the documentation stops and the twin decides: Stripe retries a failed renewal on its Smart Retries
-// schedule and may then cancel or mark the subscription unpaid; the twin makes no retry (next_payment_attempt
-// is null) and leaves it past_due until the invoice is paid. A paused subscription (pause_collection) is not renewed.
-// - One set to cancel at its period's end is canceled when the period ends, with no renewal
-//   (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle).
-import { runAsVendorMove, type SemanticsContext } from '@volter/world-core';
-import { addBillingInterval, applyCouponDiscount, declineFor, mintClientSecret, priceAmount, resolveSubscriptionBillingInterval } from '../stripe-twin.ts';
-import { finalizedFields } from './invoices.ts';
-import { mintCharge } from './payment-intents.ts';
-import { at_, created, finder, type Row } from './shared.ts';
-
-const SUB = 'subscription';
-const INV = 'invoice';
-const HOUR = 3600;
-/** The statuses a subscription renews in. */
-const RENEWING = ['trialing', 'active', 'past_due'];
-
-/** A customer's now: its test clock's frozen time when it is on one (docs.stripe.com/billing/testing/test-clocks), the
- *  World's otherwise. */
-export function clockNow(ctx: SemanticsContext, customer: unknown): number {
-  const clock = typeof customer === 'string' ? ctx.get('customer', customer)?.test_clock : undefined;
-  const frozen = typeof clock === 'string' ? ctx.get('test_helpers.test_clock', clock)?.frozen_time : undefined;
-  return frozen !== undefined ? Number(frozen) : Number(ctx.now());
-}
-
-/** What a subscription's invoices charge: its own default payment method, else its customer's. */
-export function payerOf(ctx: SemanticsContext, sub: Row): string | undefined {
-  return typeof sub.default_payment_method === 'string' && sub.default_payment_method ? sub.default_payment_method : customerDefault(ctx, sub);
-}
-
-/** The customer's default for invoices, charged when the subscription names none of its own. */
-function customerDefault(ctx: SemanticsContext, sub: Row): string | undefined {
-  const customer = typeof sub.customer === 'string' ? ctx.get('customer', sub.customer) : undefined;
-  const settings = customer?.invoice_settings as Row | undefined;
-  return typeof settings?.default_payment_method === 'string' && settings.default_payment_method ? settings.default_payment_method : undefined;
-}
-
-const itemsOf = (sub: Row): Row[] => ((sub.items as { data?: Row[] } | undefined)?.data) ?? [];
-
-/** An item's quantity as it bills: 1 when none is set, and 0 when 0 is (a quantity of 0 bills nothing). */
-export function itemQuantity(it: Row): number {
-  return it.quantity === undefined || it.quantity === null ? 1 : Math.max(0, Math.trunc(Number(it.quantity) || 0));
-}
-
-/** The subscription's discounts with a `once` coupon's spent: "When a subscription uses a coupon with `duration=once`, the
- *  coupon is considered used after the invoice finalizes and is removed from the subscription's `discounts` array"
- *  (docs.stripe.com/billing/subscriptions/coupons#coupon-duration). */
-export function unspentDiscounts(discounts: unknown): Row[] {
-  return ((discounts as Row[] | undefined) ?? []).filter((d) => !(d && typeof d === 'object' && (d.coupon as Row | undefined)?.duration === 'once'));
-}
-
-/** The coupon ids an invoice's discounts name. */
-const couponsOf = (discounts: unknown): Set<string> => new Set(((discounts as Row[] | undefined) ?? []).map((d) => {
-  const c = d && typeof d === 'object' ? d.coupon : undefined;
-  return typeof c === 'string' ? c : c && typeof c === 'object' ? String((c as Row).id ?? '') : '';
-}).filter(Boolean));
-
-/** A subscription whose invoice has just been finalized: the `once` coupon that invoice took is spent, and a once coupon
- *  it did not take (added after it was drafted) stays for the next (unspentDiscounts). */
-export async function spendOnceCoupon(ctx: SemanticsContext, invoice: Row): Promise<void> {
-  const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
-  const sub = subId ? ctx.get(SUB, subId) : undefined;
-  if (!sub || !subId) return;
-  const all = (sub.discounts as Row[] | undefined) ?? [];
-  const kept = keptAfter(all, invoice);
-  if (kept.length !== all.length) await ctx.write(SUB, subId, { discounts: kept }, 'subscription.discount_spent');
-}
-
-/** A subscription's discounts after `invoice` finalizes: less the `once` coupons it took. */
-export function keptAfter(discounts: Row[], invoice: Row): Row[] {
-  const taken = couponsOf(invoice.discounts);
-  return discounts.filter((d) => !(unspentDiscounts([d]).length === 0 && [...couponsOf([d])].some((c) => taken.has(c))));
-}
-
-/** A draft invoice for one period of a subscription, its lines the subscription's items and any one-time lines `once`
- *  gives it (a Checkout session's one-time prices, "on the initial invoice only", docs.stripe.com/api/checkout/sessions/
- *  create#create_checkout_session-line_items), under the subscription's discount. Answers the invoice id. */
-export async function draftSubscriptionInvoice(ctx: SemanticsContext, sub: Row, o: { start: number; end: number; reason: 'subscription_create' | 'subscription_cycle' | 'subscription_update'; trial?: boolean; once?: Row[]; id?: string }): Promise<string> {
-  const id = o.id ?? ctx.mint(INV);
-  const currency = String(sub.currency ?? 'usd');
-  const lines = itemsOf(sub).map((it, i) => {
-    const price = it.price && typeof it.price === 'object' ? (it.price as Row) : ctx.get('price', String(it.price ?? ''));
-    const quantity = itemQuantity(it);
-    return {
-      id: `il_twin_${id}_${i + 1}`, object: 'line_item', type: 'subscription',
-      // a trial's first invoice bills nothing for the trial period (docs.stripe.com/billing/subscriptions/trials)
-      amount: o.trial ? 0 : priceAmount(price, quantity), currency, quantity, proration: false,
-      price: price ?? null, subscription: sub.id, subscription_item: it.id ?? null, invoice_item: null,
-      period: { start: o.start, end: o.end }, description: o.trial ? `Trial period for ${String(ctx.get('product', String(price?.product ?? ''))?.name ?? 'the plan')}` : null,
-    };
-  });
-  if (o.once?.length) lines.push(...oneTimeLines(id, sub, o.once, lines.length, o.start, currency));
-  const subtotal = lines.reduce((s, l) => s + l.amount, 0);
-  // a discount the subscription still carries applies; a `once` coupon is removed once an invoice finalizes
-  // (spendOnceCoupon), so it discounts one invoice (docs.stripe.com/billing/subscriptions/coupons#coupon-duration)
-  const discount = ((sub.discounts as Row[] | undefined) ?? [])[0];
-  const coupon = discount && typeof discount === 'object' ? (discount.coupon as Row | undefined) : undefined;
-  const off = coupon ? applyCouponDiscount(subtotal, coupon) : 0;
-  const total = Math.max(0, subtotal - off);
-  await created(ctx, INV, { id, customer: sub.customer, subscription: sub.id }, {
-    created: o.start, status: 'draft', livemode: false, currency, collection_method: 'charge_automatically',
-    billing_reason: o.reason, auto_advance: true, attempt_count: 0, attempted: false, next_payment_attempt: null,
-    amount_due: total, amount_paid: 0, amount_remaining: total, amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
-    subtotal, total, starting_balance: 0, post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
-    // "The invoice that consumed the coupon still shows the applied discount" (docs.stripe.com/billing/subscriptions/coupons)
-    period_start: o.start, period_end: o.end, default_tax_rates: [], discounts: coupon && discount ? [discount] : [],
-    lines: { object: 'list', data: lines, has_more: false, total_count: lines.length, url: `/v1/invoices/${id}/lines` },
-    automatic_tax: { enabled: false, liability: null, status: null },
-    status_transitions: { finalized_at: null, marked_uncollectible_at: null, paid_at: null, voided_at: null },
-    issuer: { type: 'self' }, payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
-    payment_intent: null, charge: null,
-  });
-  return id;
-}
-
-/** A Checkout session's one-time line items as lines of its subscription's first invoice, numbered after its `after` lines. */
-function oneTimeLines(invoiceId: string, sub: Row, items: Row[], after: number, at: number, currency: string) {
-  return items.map((it, i) => {
-    const price = it.price && typeof it.price === 'object' ? (it.price as Row) : null;
-    const quantity = itemQuantity(it);
-    return {
-      id: `il_twin_${invoiceId}_${after + i + 1}`, object: 'line_item', type: 'subscription',
-      amount: priceAmount(price ?? undefined, quantity), currency, quantity, proration: false,
-      price, subscription: sub.id, subscription_item: null, invoice_item: null,
-      period: { start: at, end: at }, description: typeof it.description === 'string' ? it.description : null,
-    };
-  });
-}
-
-/** Finalize a subscription's draft invoice at `at` and charge what its subscription pays with. The move is time's (a
- *  renewal), the customer's (the Checkout page they paid on) or the API's (an update that ends a trial, which names the
- *  payer, may ask for no attempt, and moves the subscription itself: semantics/subscriptions.ts applyTrialEnd). Answers
- *  whether it was paid. */
-export async function collectSubscriptionInvoice(ctx: SemanticsContext, invoiceId: string, at: number, actor: 'time' | 'external' | 'api', opts: { payer?: string; attempt?: boolean } = {}): Promise<boolean> {
-  const inv = ctx.get(INV, invoiceId);
-  const sub = inv && typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
-  if (!inv || !sub || inv.status !== 'draft') return false;
-  const total = Number(inv.total) || 0;
-  const numbered = { ...finalizedFields(ctx, inv, at), status_transitions: { ...(inv.status_transitions as Row), finalized_at: at } };
-  const op = ctx.call.operation.id;
-  // nothing due (a trial's first invoice) is paid as it is finalized; finalizing spends a `once` coupon
-  if (total <= 0) {
-    if (ctx.legal(INV, 'status', op, 'draft', 'paid', invoiceId, actor)) return false;
-    await spendOnceCoupon(ctx, inv);
-    await ctx.write(INV, invoiceId, { ...numbered, status: 'paid', paid: true, auto_advance: false, status_transitions: { ...numbered.status_transitions, paid_at: at } }, 'invoice.paid');
-    return true;
-  }
-  const payer = actor === 'api' ? opts.payer : payerOf(ctx, sub);
-  // default_incomplete finalizes the invoice without attempting payment (docs.stripe.com/api/subscriptions/update#update_subscription-payment_behavior)
-  const attempt = opts.attempt !== false;
-  const decline = payer && attempt ? declineFor(finder(ctx), { payment_method: payer }) : undefined;
-  const pays = attempt && !!payer && !decline;
-  if (ctx.legal(INV, 'status', op, 'draft', pays ? 'paid' : 'open', invoiceId, actor)) return false;
-  await spendOnceCoupon(ctx, inv);
-  const piId = ctx.mint('payment_intent');
-  const currency = String(inv.currency ?? 'usd');
-  const chargeId = pays ? await mintCharge(ctx, piId, { currency, customer: inv.customer, payment_method: payer, invoice: invoiceId }, total) : null;
-  await created(ctx, 'payment_intent', { id: piId, amount: total, currency, customer: inv.customer, invoice: invoiceId, payment_method: pays ? payer : null }, {
-    status: pays ? 'succeeded' : 'requires_payment_method', client_secret: mintClientSecret(piId), livemode: false,
-    capture_method: 'automatic', amount_capturable: 0, amount_received: pays ? total : 0, next_action: null, latest_charge: chargeId,
-    last_payment_error: decline ? { type: 'card_error', code: decline.code, decline_code: decline.decline_code ?? null, message: decline.message, payment_method: { id: payer } } : null,
-    automatic_payment_methods: null, payment_method_types: ['card'], payment_method_options: {},
-  });
-  await ctx.write(INV, invoiceId, {
-    ...numbered, status: pays ? 'paid' : 'open', paid: pays, attempt_count: attempt ? 1 : 0, attempted: attempt, payment_intent: piId, charge: chargeId,
-    amount_paid: pays ? total : 0, amount_remaining: pays ? 0 : total, auto_advance: attempt && !pays, next_payment_attempt: null,
-    status_transitions: { ...numbered.status_transitions, paid_at: pays ? at : null },
-  }, pays ? 'invoice.paid' : attempt ? 'invoice.payment_failed' : 'invoice.finalized');
-  if (actor !== 'api' && !pays && sub.status !== 'past_due' && !ctx.legal(SUB, 'status', op, sub.status, 'past_due', String(sub.id), 'time')) {
-    await ctx.write(SUB, String(sub.id), { status: 'past_due' }, 'customer.subscription.updated');
-  }
-  return pays;
-}
-
-/** Pay a subscription's open invoice with `paymentMethod` (the customer on the portal, `external`): the charge on the
- *  invoice's PaymentIntent, the invoice paid, a past_due subscription active. Answers the decline, if the card is refused. */
-export async function payOpenInvoice(ctx: SemanticsContext, invoiceId: string, paymentMethod: string): Promise<{ code: string; message: string } | undefined> {
-  const inv = ctx.get(INV, invoiceId);
-  if (!inv || inv.status !== 'open') return { code: 'invoice_not_open', message: 'This invoice is no longer open.' };
-  const decline = declineFor(finder(ctx), { payment_method: paymentMethod });
-  if (decline) return decline;
-  const op = ctx.call.operation.id;
-  const refused = ctx.legal(INV, 'status', op, 'open', 'paid', invoiceId, 'external');
-  if (refused) return { code: refused.code ?? 'invoice_not_open', message: refused.message };
-  const total = Number(inv.amount_remaining ?? inv.total) || 0;
-  const now = Number(ctx.now());
-  const piId = typeof inv.payment_intent === 'string' ? inv.payment_intent : undefined;
-  let chargeId: string | null = null;
-  const pi = piId ? ctx.get('payment_intent', piId) : undefined;
-  if (piId && pi && !ctx.legal('payment_intent', 'status', op, pi.status, 'succeeded', piId, 'external')) {
-    chargeId = await mintCharge(ctx, piId, { ...pi, payment_method: paymentMethod, invoice: invoiceId }, total);
-    await ctx.write('payment_intent', piId, { status: 'succeeded', payment_method: paymentMethod, amount_received: total, last_payment_error: null, latest_charge: chargeId }, 'payment_intent.succeeded');
-  }
-  await ctx.write(INV, invoiceId, {
-    status: 'paid', paid: true, amount_paid: total, amount_remaining: 0, charge: chargeId, auto_advance: false,
-    attempt_count: (Number(inv.attempt_count) || 0) + 1, attempted: true,
-    status_transitions: { ...(inv.status_transitions as Row), paid_at: now },
-  }, 'invoice.paid');
-  const sub = typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
-  if (sub && sub.status === 'past_due' && !ctx.legal(SUB, 'status', op, 'past_due', 'active', String(sub.id), 'external')) {
-    await ctx.write(SUB, String(sub.id), { status: 'active' }, 'customer.subscription.updated');
-  }
-  return undefined;
-}
-
-/** Time's moves on subscriptions, caught up to each customer's clock in the order they fell due, each made at the
- *  moment it was due: a period that ended renews (a trial's end among them) or, set to cancel, cancels; a renewal
- *  drafted an hour or more ago is finalized and charged. */
-export async function advanceBilling(ctx: SemanticsContext, only?: (sub: Row) => boolean): Promise<void> {
-  // the billing clock is the vendor's own move, wherever a handler reaches it: never the request's caller's
-  return runAsVendorMove(() => advanceBillingDue(ctx, only));
-}
-
-async function advanceBillingDue(ctx: SemanticsContext, only?: (sub: Row) => boolean): Promise<void> {
-  const at = at_(ctx);
-  for (let guard = 0; guard < 10_000 && (await billingStep(ctx, at, only)); guard++);
-}
-
-/** The earliest move that has come due, made at its moment; false when none has. */
-async function billingStep(ctx: SemanticsContext, at: (t: number) => Promise<SemanticsContext>, only?: (sub: Row) => boolean): Promise<boolean> {
-    // the earliest move that has come due, of any subscription
-    let next: { t: number; kind: 'period' | 'collect'; id: string } | undefined;
-    for (const sub of ctx.rows(SUB)) {
-      if (only && !only(sub)) continue;
-      if (!RENEWING.includes(String(sub.status)) || typeof sub.current_period_end !== 'number' || sub.pause_collection) continue;
-      if (sub.current_period_end <= clockNow(ctx, sub.customer) && (!next || sub.current_period_end < next.t)) next = { t: sub.current_period_end, kind: 'period', id: String(sub.id) };
-    }
-    for (const inv of ctx.rows(INV)) {
-      if (inv.status !== 'draft' || inv.billing_reason !== 'subscription_cycle' || inv.auto_advance !== true) continue;
-      const sub = typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
-      if (!sub || (only && !only(sub))) continue;
-      const t = Number(inv.created) + HOUR;
-      if (t <= clockNow(ctx, sub.customer) && (!next || t < next.t)) next = { t, kind: 'collect', id: String(inv.id) };
-    }
-    if (!next) return false;
-    const c = await at(next.t);
-    if (next.kind === 'collect') {
-      await collectSubscriptionInvoice(c, next.id, next.t, 'time');
-      return true;
-    }
-    const id = next.id;
-    const sub = c.get(SUB, id)!;
-    const op = c.call.operation.id;
-    // one set to cancel at its period's end is canceled then, with no renewal
-    // (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle)
-    if (sub.cancel_at_period_end === true) {
-      if (c.legal(SUB, 'status', op, sub.status, 'canceled', id, 'time')) return false;
-      await c.write(SUB, id, { status: 'canceled', ended_at: next.t, canceled_at: sub.canceled_at ?? next.t }, 'customer.subscription.deleted');
-      return true;
-    }
-    const start = next.t;
-    const { interval, interval_count } = resolveSubscriptionBillingInterval(itemsOf(sub), finder(c));
-    const end = addBillingInterval(start, interval, interval_count);
-    const trialEnds = sub.status === 'trialing';
-    if (trialEnds && c.legal(SUB, 'status', op, 'trialing', 'active', id, 'time')) return false;
-    const invoiceId = await draftSubscriptionInvoice(c, sub, { start, end, reason: 'subscription_cycle' });
-    await c.write(SUB, id, { current_period_start: start, current_period_end: end, latest_invoice: invoiceId, ...(trialEnds ? { status: 'active' } : {}) }, 'customer.subscription.updated');
-    return true;
-}

package/src/semantics/setup-intents.ts

@@ -1,87 +0,0 @@
-// SetupIntent semantics. The machine in ../manifest.ts says which moves of `status` are legal and
-// what Stripe answers otherwise; these handlers compute what each move does. List, retrieve and
-// update are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { asBool, microdepositsNextAction, mintClientSecret, requiresMicrodeposits, verifyMicrodeposits } from '../stripe-twin.ts';
-import { mintMandate } from './after-payment.ts';
-import { attachable, attachPaymentMethod, methodFromData, microdepositsAsked } from './payment-methods.ts';
-import { at, confirmOnly, created, fail, mergeUpdate, send, type Row } from './shared.ts';
-
-const SI = 'setup_intent';
-
-/** The intent the path names, and the machine's refusal when this operation may not move it. */
-function load(ctx: SemanticsContext, operationId: string): { si: Row } | { answer: Response } {
-  const id = at(ctx, 'intent');
-  const si = ctx.get(SI, id);
-  if (!si) return { answer: fail(ctx, `No such setup_intent: '${id}'`, 404, 'resource_missing') };
-  const refused = ctx.legal(SI, 'status', operationId, si.status, undefined, id);
-  return refused ? { answer: ctx.refuse(refused) } : { si };
-}
-
-const create: Semantics = async (ctx) => {
-  // mandate_data and return_url each "can only be used with `confirm=true`" (the served spec; shared.ts confirmOnly)
-  const unconfirmed = confirmOnly(ctx, ['mandate_data', 'return_url'], asBool(ctx.params.confirm));
-  if (unconfirmed) return unconfirmed;
-  // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
-  const id = typeof ctx.params.id === 'string' && ctx.params.id ? ctx.params.id : ctx.mint(SI);
-  // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
-  const hasMethod = typeof ctx.params.payment_method === 'string' && ctx.params.payment_method !== '';
-  if (hasMethod) ctx.legal(SI, 'status', 'PostSetupIntents', 'requires_payment_method', 'requires_confirmation', id);
-  return ctx.reply(
-    // allowed_payment_method_types in the served version names the methods (docs.stripe.com/api/setup_intents/create)
-    await created(ctx, SI, { ...ctx.params, ...(Array.isArray(ctx.params.allowed_payment_method_types) ? { payment_method_types: ctx.params.allowed_payment_method_types.map(String) } : {}), id }, {
-      status: hasMethod ? 'requires_confirmation' : 'requires_payment_method', usage: 'off_session', client_secret: mintClientSecret(id), payment_method_types: ['card'],
-      next_action: null, latest_attempt: null, last_setup_error: null, livemode: false,
-    }),
-  );
-};
-
-// a bank account that needs micro-deposit verification waits in requires_action; anything else succeeds. The confirm's
-// payment_method_data and mandate_data are instructions, not fields of the SetupIntent.
-const confirm: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostSetupIntentsIntentConfirm');
-  if ('answer' in loaded) return loaded.answer;
-  const si = loaded.si;
-  const id = String(si.id);
-  const { payment_method_data: data, mandate_data: _mandate, ...fields } = ctx.params;
-  const made = await methodFromData(ctx, data);
-  const pm = made ?? (typeof ctx.params.payment_method === 'string' ? ctx.params.payment_method : typeof si.payment_method === 'string' ? si.payment_method : undefined);
-  if (si.status !== 'requires_action' && (requiresMicrodeposits(ctx.params, si) || microdepositsAsked(ctx, ctx.params, si, pm))) {
-    return ctx.reply(await ctx.write(SI, id, mergeUpdate(ctx, SI, id, { ...fields, ...(pm ? { payment_method: pm } : {}), status: 'requires_action', next_action: microdepositsNextAction() }), 'setup_intent.requires_action'));
-  }
-  // a setup for a customer saves the method to them (docs.stripe.com/payments/save-and-reuse): its payment method is attached
-  const customer = typeof si.customer === 'string' ? si.customer : undefined;
-  const saved = pm && customer && attachable(ctx, pm) && ctx.get('payment_method', pm)?.customer !== customer ? String((await attachPaymentMethod(ctx, pm, customer)).id) : pm;
-  return ctx.reply(await ctx.write(SI, id, mergeUpdate(ctx, SI, id, { ...fields, ...(saved ? { payment_method: saved } : {}), status: 'succeeded' }), 'setup_intent.confirm'));
-};
-
-const cancel: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostSetupIntentsIntentCancel');
-  if ('answer' in loaded) return loaded.answer;
-  const cancellation_reason = typeof ctx.params.cancellation_reason === 'string' ? ctx.params.cancellation_reason : 'abandoned';
-  return ctx.reply(await ctx.write(SI, String(loaded.si.id), { status: 'canceled', cancellation_reason }, 'setup_intent.canceled'));
-};
-
-const verify: Semantics = async (ctx) => {
-  const id = at(ctx, 'intent');
-  const si = ctx.get(SI, id);
-  if (!si) return fail(ctx, `No such setup_intent: '${id}'`, 404, 'resource_missing');
-  // the deposit amounts are checked before the intent's state, as Stripe does
-  const wrong = verifyMicrodeposits(ctx.params, si);
-  if (wrong) return send(ctx, wrong);
-  const refused = ctx.legal(SI, 'status', 'PostSetupIntentsIntentVerifyMicrodeposits', si.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  const mandate = await mintMandate(ctx, si.payment_method, 'multi_use');
-  // verified, the bank account is saved to the setup's customer, as a confirmed setup's method is
-  const pm = typeof si.payment_method === 'string' ? si.payment_method : undefined;
-  const customer = typeof si.customer === 'string' ? si.customer : undefined;
-  if (pm && customer && attachable(ctx, pm) && ctx.get('payment_method', pm)?.customer !== customer) await attachPaymentMethod(ctx, pm, customer);
-  return ctx.reply(await ctx.write(SI, id, { status: 'succeeded', next_action: null, last_setup_error: null, mandate }, 'setup_intent.succeeded'));
-};
-
-export const setupIntents: Record<string, Semantics> = {
-  PostSetupIntents: create,
-  PostSetupIntentsIntentConfirm: confirm,
-  PostSetupIntentsIntentCancel: cancel,
-  PostSetupIntentsIntentVerifyMicrodeposits: verify,
-};

package/src/semantics/subscription-schedules.ts

@@ -1,129 +0,0 @@
-// Subscription schedule semantics: a schedule drives a subscription through phases (items for a
-// duration). One made for a customer starts its subscription at once on the first phase's items. Cancel and
-// release end it, the machine's moves in ../manifest.ts. List and update are the derived core's.
-//
-// Where the documentation stops and the twin decides: the subscription a schedule starts raises no first invoice.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { addBillingInterval, buildSubscriptionItemsList } from '../stripe-twin.ts';
-import { at, created, fail, finder, type Row } from './shared.ts';
-import { storeItems } from './subscriptions.ts';
-
-const SS = 'subscription_schedule';
-const scheduleMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such subscription_schedule: '${id}'`, 404, 'resource_missing');
-
-type Interval = Parameters<typeof addBillingInterval>[1];
-
-/** A schedule's phases as Stripe answers them (the served spec's subscription_schedule_phase_configuration): each
- *  starts where the last ended (the first at the schedule's start_date, "now" or a timestamp), and ends at its
- *  end_date or after its duration ("duration: interval, interval_count", the served spec's phases[] parameter) on the
- *  calendar; its currency is its first price's, each item carries its price, quantity and (empty) discounts. Where the
- *  documentation stops and the twin decides: a phase with neither lasts one interval of its first price. */
-function phasesOf(ctx: SemanticsContext, given: Row[], start: number): Row[] {
-  let cursor = start;
-  return given.map((p) => {
-    const items = (Array.isArray(p.items) ? (p.items as Row[]) : []).map((it) => ({ price: it.price ?? null, quantity: Math.max(1, Math.trunc(Number(it.quantity) || 1)), discounts: [], metadata: {}, tax_rates: [], billing_thresholds: null }));
-    const price = typeof items[0]?.price === 'string' ? ctx.get('price', items[0]!.price as string) : undefined;
-    const recurring = (price?.recurring as Row | undefined) ?? {};
-    const d = p.duration && typeof p.duration === 'object' ? (p.duration as Row) : undefined;
-    const startDate = cursor;
-    const end = p.end_date !== undefined && p.end_date !== 'now' ? Number(p.end_date)
-      : d ? addBillingInterval(startDate, String(d.interval) as Interval, Math.max(1, Number(d.interval_count) || 1))
-      : addBillingInterval(startDate, String(recurring.interval ?? 'month') as Interval, Math.max(1, Number(recurring.interval_count) || 1));
-    cursor = end;
-    return {
-      add_invoice_items: [], application_fee_percent: null, automatic_tax: { enabled: false, liability: null, disabled_reason: null }, billing_cycle_anchor: null,
-      billing_thresholds: null, collection_method: null, currency: String(price?.currency ?? 'usd'), default_payment_method: null, default_tax_rates: [],
-      description: null, discounts: [], end_date: end, invoice_settings: null, items, metadata: p.metadata && typeof p.metadata === 'object' ? p.metadata : {},
-      on_behalf_of: null, proration_behavior: typeof p.proration_behavior === 'string' ? p.proration_behavior : 'create_prorations', start_date: startDate,
-      transfer_data: null, trial_end: null,
-    };
-  });
-}
-
-// a schedule starts from a customer or from an existing subscription
-const create: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const customer = typeof params.customer === 'string' ? params.customer : '';
-  const fromSub = typeof params.from_subscription === 'string' ? params.from_subscription : '';
-  if (!customer && !fromSub) return fail(ctx, 'Missing required param: customer (or from_subscription).', 400, 'parameter_missing');
-  if (customer && !ctx.get('customer', customer)) return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-  if (fromSub && !ctx.get('subscription', fromSub)) return fail(ctx, `No such subscription: '${fromSub}'`, 404, 'resource_missing');
-  // start_date is an instruction ("now" or when), not a field of the schedule
-  const start = params.start_date !== undefined && params.start_date !== 'now' ? Number(params.start_date) : Number(ctx.now());
-  const phases = phasesOf(ctx, Array.isArray(params.phases) ? (params.phases as Row[]) : [], start);
-  const { phases: _p, start_date: _s, default_settings: givenDefaults, ...rest } = params;
-  const defaults = givenDefaults && typeof givenDefaults === 'object' ? (givenDefaults as Row) : {};
-  const schedId = ctx.mint(SS);
-  // a schedule for a customer whose first phase starts now starts its subscription at once, on that phase's items
-  // (docs.stripe.com/billing/subscriptions/subscription-schedules#managing)
-  let subscription = fromSub || null;
-  if (!fromSub && phases.length) {
-    const now = Number(ctx.now());
-    const subId = ctx.mint('subscription');
-    const items = buildSubscriptionItemsList(phases[0]!.items as Row[], subId, now, finder(ctx));
-    await created(ctx, 'subscription', { customer, id: subId }, {
-      status: 'active', livemode: false, currency: 'usd', collection_method: String((params.default_settings as Row | undefined)?.collection_method ?? 'charge_automatically'),
-      cancel_at_period_end: false, start_date: now, billing_cycle_anchor: now, metadata: {}, discounts: [], billing_schedules: [],
-      trial_start: null, trial_end: null, current_period_start: now, current_period_end: phases[0]!.end_date, items, schedule: schedId,
-      automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' }, invoice_settings: { issuer: { type: 'self' } },
-    });
-    await storeItems(ctx, subId, (items.data as Row[]) ?? []);
-    subscription = subId;
-  }
-  return ctx.reply(
-    await created(ctx, SS, { ...rest, id: schedId }, {
-      status: 'active', livemode: false, phases, current_phase: phases.length ? { start_date: phases[0]!.start_date, end_date: phases[0]!.end_date } : null,
-      subscription, released_subscription: null, released_at: null,
-      canceled_at: null, completed_at: null, end_behavior: (params.end_behavior as string) ?? 'release',
-      renewal_interval: null, metadata: {}, billing_mode: { type: 'classic' },
-      // "billing_cycle_anchor: Possible values are phase_start or automatic" and invoice_settings are required (the
-      // served spec's default settings); the rest answer what the request set, else null
-      default_settings: {
-        application_fee_percent: defaults.application_fee_percent ?? null, automatic_tax: { enabled: false, liability: null, disabled_reason: null },
-        billing_cycle_anchor: typeof defaults.billing_cycle_anchor === 'string' ? defaults.billing_cycle_anchor : 'automatic', billing_thresholds: null,
-        collection_method: typeof defaults.collection_method === 'string' ? defaults.collection_method : 'charge_automatically', default_payment_method: defaults.default_payment_method ?? null,
-        description: defaults.description ?? null, invoice_settings: { account_tax_ids: null, days_until_due: null, issuer: { type: 'self' } }, on_behalf_of: null, transfer_data: null,
-      },
-      // a schedule made from a subscription is its customer's
-      customer: customer || String(ctx.get('subscription', fromSub)?.customer ?? ''),
-    }),
-  );
-};
-
-function end(kind: 'cancel' | 'release'): Semantics {
-  return async (ctx) => {
-    const id = at(ctx, 'schedule');
-    const sched = ctx.get(SS, id);
-    if (!sched) return scheduleMissing(ctx, id);
-    const refused = ctx.legal(SS, 'status', kind === 'cancel' ? 'PostSubscriptionSchedulesScheduleCancel' : 'PostSubscriptionSchedulesScheduleRelease', sched.status, undefined, id);
-    if (refused) return ctx.refuse(refused);
-    const now = ctx.now();
-    const subId = typeof sched.subscription === 'string' ? sched.subscription : undefined;
-    const sub = subId ? ctx.get('subscription', subId) : undefined;
-    // "Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an
-    // active subscription)" (docs.stripe.com/api/subscription_schedules/cancel); releasing "will remove its subscription
-    // property and set the subscription's ID to the released_subscription property", leaving the subscription in place
-    // (docs.stripe.com/api/subscription_schedules/release)
-    if (kind === 'cancel' && subId && sub && sub.status !== 'canceled') {
-      ctx.legal('subscription', 'status', 'PostSubscriptionSchedulesScheduleCancel', String(sub.status), 'canceled', subId);
-      await ctx.write('subscription', subId, { status: 'canceled', canceled_at: now, ended_at: now }, 'subscription.cancel');
-    }
-    if (kind === 'release' && subId && sub) await ctx.write('subscription', subId, { schedule: null }, 'subscription.update');
-    const fields = kind === 'cancel'
-      ? { status: 'canceled', canceled_at: now, current_phase: null }
-      : { status: 'released', released_at: now, released_subscription: subId ?? null, subscription: null, current_phase: null };
-    return ctx.reply(await ctx.write(SS, id, fields, `subscription_schedule.${kind}`));
-  };
-}
-
-const retrieve: Semantics = async (ctx) => {
-  const s = ctx.get(SS, at(ctx, 'schedule'));
-  return s ? ctx.reply(s) : scheduleMissing(ctx, at(ctx, 'schedule'));
-};
-
-export const subscriptionSchedules: Record<string, Semantics> = {
-  PostSubscriptionSchedules: create,
-  PostSubscriptionSchedulesScheduleCancel: end('cancel'),
-  PostSubscriptionSchedulesScheduleRelease: end('release'),
-  GetSubscriptionSchedulesSchedule: retrieve,
-};