@volter/twin-stripe 2.0.38 → 3.0.1

package/src/semantics/payment-intents.ts

@@ -1,463 +0,0 @@
-// PaymentIntent 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; search is Stripe's query language over the intents.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import {
-  asBool,
-  cardError,
-  chargeDefaults,
-  declineFor,
-  microdepositsNextAction,
-  mintClientSecret,
-  requiresAuthentication,
-  requiresMicrodeposits,
-  threeDsNextAction,
-  validateMoney,
-  verifyMicrodeposits,
-  type StripeResponse,
-} from '../stripe-twin.ts';
-import { afterCharge, mintMandate } from './after-payment.ts';
-import { cancelAuthorization, captureAuthorization } from './charges.ts';
-import { settleCharge } from './ledger.ts';
-import { materializeTestMethod, methodFromData, microdepositsAsked, paymentMethodDetails } from './payment-methods.ts';
-import { at_, confirmOnly, created, fail, finder, search, type Row } from './shared.ts';
-
-const PI = 'payment_intent';
-/** Bookkeeping: the intents whose caller named the methods (payment_method_types, allowed_payment_method_types) on
- *  create. The twin's default list (['card']) stands for Stripe's choice and restricts nothing, so only a named list
- *  refuses a confirm with a method of another type. Kept apart from the intent: a `_` subject is never pushed
- *  (world-core isTwinBookkeeping). */
-const TYPES_GIVEN = '_payment_intent_types_given';
-/** Whether the intent's caller named its methods: on create (TYPES_GIVEN), or by an update that set its
- *  payment_method_types ("Alternatively, update the allowed payment_method_types for this PaymentIntent",
- *  methodNotAllowed below), which the generic update writes as given, so the intent's history holds it. */
-const typesGiven = (ctx: SemanticsContext, id: string): boolean =>
-  ctx.tree().some((r) => r.type === TYPES_GIVEN && r.id === id)
-  || ctx.history(PI, id).some((e) => e.operation !== 'payment_intent.create' && Array.isArray(e.fields?.payment_method_types));
-
-const send = (ctx: SemanticsContext, r: StripeResponse): Response => ctx.reply(r.body, r.status);
-
-// ── THE MONEY MODEL, continued: a succeeded intent has a Charge ──
-//
-// Real Stripe always materializes a Charge when a PaymentIntent succeeds and points the intent's
-// `latest_charge` at it: the charge is what a refund lands on, so an intent that succeeds without
-// one cannot answer "refund this payment" at all. Idempotent against a repeated confirm: an intent
-// that already names a successful charge keeps it (a second one would double the money collected); a
-// declined attempt's failed charge is history, and the payment that succeeds makes its own. The id is
-// returned so the caller folds `latest_charge` into the same intent write (one write, one event). The
-// charge is written as the event Stripe sends for it, `charge.succeeded` ("Occurs whenever a charge is
-// successful", docs.stripe.com/api/events/types); Stripe has no `charge.created`.
-/** What every charge an intent makes carries of it: its transfer_group, which "identifies the resulting payment as part
- *  of a group" (docs.stripe.com/api/payment_intents/object), its description and its metadata. */
-function intentCarries(pi: Row): Row {
-  return {
-    ...(typeof pi.transfer_group === 'string' ? { transfer_group: pi.transfer_group } : {}),
-    ...(typeof pi.description === 'string' ? { description: pi.description } : {}),
-    // "When a PaymentIntent creates a Charge, the metadata copies to the Charge in a one-time snapshot"
-    // (docs.stripe.com/metadata, "Copy metadata to another object")
-    ...(pi.metadata && typeof pi.metadata === 'object' ? { metadata: { ...(pi.metadata as Row) } } : {}),
-  };
-}
-
-export async function mintCharge(ctx: SemanticsContext, piId: string, pi: Row, amount: number): Promise<string> {
-  const already = ctx.get(PI, piId)?.latest_charge;
-  if (typeof already === 'string' && ctx.get('charge', already)?.status === 'succeeded') return already;
-  const chargeId = ctx.mint('charge');
-  const bt = await settleCharge(ctx, chargeId, amount, String(pi.currency ?? 'usd'), typeof pi.payment_method === 'string' ? pi.payment_method : undefined);
-  await created(ctx, 'charge', {
-    id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
-    ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
-    ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
-    ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
-    ...intentCarries(pi),
-  }, { ...chargeDefaults(chargeId, amount, true, ctx.occurredAt), balance_transaction: bt, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
-  await afterCharge(ctx, chargeId, { amount, currency: String(pi.currency ?? 'usd'), payment_intent: piId, application_fee_amount: pi.application_fee_amount, destination: (pi.transfer_data as Row | undefined)?.destination }, pi.payment_method);
-  return chargeId;
-}
-
-/** A manual-capture intent's authorization: "Separate payment authorization and capture to create a charge now, but
- *  capture funds later", and on capture "A partial capture automatically releases the remaining amount"
- *  (docs.stripe.com/payments/place-a-hold-on-a-payment-method). The charge succeeded and is not captured, holding the
- *  amount until capture_before, with nothing on the balance yet. Written as
- *  charge.succeeded, as a charge made with capture=false is (charges.ts); its capture writes charge.captured
- *  (captureAuthorization). Where the documentation stops and the twin decides: the events page names no event for an
- *  authorization of its own, so the authorized charge sends charge.succeeded, its status being succeeded. */
-export async function authorizeCharge(ctx: SemanticsContext, piId: string, pi: Row, amount: number): Promise<string> {
-  const chargeId = ctx.mint('charge');
-  await created(ctx, 'charge', {
-    id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
-    ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
-    ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
-    ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
-    ...intentCarries(pi),
-  }, { ...chargeDefaults(chargeId, amount, false, ctx.occurredAt), balance_transaction: null, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
-  return chargeId;
-}
-
-/**
- * An intent an invoice collects through succeeded (the default_incomplete subscription flow: create
- * now, confirm client-side): its invoice is paid and, when it is a subscription's first, the
- * subscription leaves incomplete for active. Both are moves the invoice and subscription machines
- * declare under the confirming operation. No-op when the intent names no invoice, or the invoice is
- * already paid (a duplicate confirm) or void (voiding ends what it collects).
- */
-async function payInvoiceOf(ctx: SemanticsContext, pi: Row, operationId: string, actor?: 'vendor'): Promise<void> {
-  const invoiceId = typeof pi.invoice === 'string' ? pi.invoice : undefined;
-  const invoice = invoiceId ? ctx.get('invoice', invoiceId) : undefined;
-  if (!invoiceId || !invoice || invoice.status === 'paid' || invoice.status === 'void') return;
-  if (ctx.legal('invoice', 'status', operationId, invoice.status, 'paid', invoiceId, actor)) return;
-  const amount = Number(invoice.total ?? invoice.amount_due) || 0;
-  // `invoice.pay` is the event the standalone pay action sends: invoice.paid
-  await ctx.write('invoice', invoiceId, {
-    status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0,
-    status_transitions: { ...((invoice.status_transitions as object) ?? {}), paid_at: ctx.now() },
-  }, 'invoice.pay');
-  const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
-  const sub = subId ? ctx.get('subscription', subId) : undefined;
-  if (subId && sub && sub.status === 'incomplete' && !ctx.legal('subscription', 'status', operationId, sub.status, 'active', subId, actor)) {
-    await ctx.write('subscription', subId, { status: 'active' }, 'subscription.update');
-  }
-}
-
-/** The intent the path names, and the machine's refusal when this operation may not move it. */
-function load(ctx: SemanticsContext, operationId: string): { pi: Record<string, unknown> } | { answer: Response } {
-  const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
-  if (!pi) return { answer: ctx.notFound(PI, String(ctx.id)) };
-  const refusal = ctx.legal(PI, 'status', operationId, pi.status);
-  return refusal ? { answer: ctx.refuse(refusal) } : { pi };
-}
-
-const create: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const bad = validateMoney(params);
-  if (bad) return send(ctx, bad);
-  // what describes a confirmation needs one: error_on_requires_action, mandate, mandate_data, off_session and return_url
-  // are each, in the served spec, a parameter that "can only be used with `confirm=true`" (shared.ts confirmOnly)
-  const unconfirmed = confirmOnly(ctx, ['error_on_requires_action', 'mandate', 'mandate_data', 'off_session', 'return_url'], asBool(params.confirm));
-  if (unconfirmed) return unconfirmed;
-  // automatic_payment_methods: when enabled, Stripe selects eligible methods and answers the
-  // normalized { enabled, allow_redirects } object
-  const apmIn = params.automatic_payment_methods;
-  const apmEnabled = apmIn && typeof apmIn === 'object' ? asBool((apmIn as Record<string, unknown>).enabled) : false;
-  const automatic_payment_methods = apmEnabled ? { enabled: true, allow_redirects: ((apmIn as Record<string, unknown>).allow_redirects as string) ?? 'always' } : null;
-  // the methods it may be paid with: allowed_payment_method_types in the served version, payment_method_types for a
-  // caller pinned to an earlier one (docs.stripe.com/api/payment_intents/create)
-  const given = Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types : params.payment_method_types;
-  const payment_method_types = Array.isArray(given) ? given.map(String) : ['card'];
-  // `confirm` is an instruction, not a field: `confirm=true` attempts to confirm the intent at once
-  // (https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm)
-  const { automatic_payment_methods: _a, payment_method_types: _p, allowed_payment_method_types: _ap, id: provided, expand: _e, confirm: confirmNow, payment_method_data: data, mandate_data: _mandate, ...rest } = params;
-  // a create's payment_method_data makes its method, as a confirm's does (payment-methods.ts methodFromData)
-  const made = await methodFromData(ctx, data);
-  if (made) rest.payment_method = made;
-  // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
-  const id = typeof provided === 'string' && provided ? provided : ctx.mint(PI);
-  // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
-  const hasMethod = typeof rest.payment_method === 'string' && rest.payment_method !== '';
-  if (hasMethod) ctx.legal(PI, 'status', 'PostPaymentIntents', 'requires_payment_method', 'requires_confirmation', id);
-  const body = await ctx.write(
-    PI,
-    id,
-    {
-      object: 'payment_intent',
-      created: ctx.now(),
-      status: hasMethod ? 'requires_confirmation' : 'requires_payment_method',
-      client_secret: mintClientSecret(id),
-      livemode: false,
-      capture_method: 'automatic',
-      amount_capturable: 0,
-      amount_received: 0,
-      next_action: null,
-      automatic_payment_methods,
-      payment_method_types,
-      ...(Array.isArray(params.allowed_payment_method_types) ? { allowed_payment_method_types: payment_method_types } : {}),
-      payment_method_options: (params.payment_method_options as object) ?? {},
-      ...rest,
-    },
-    'payment_intent.create',
-  );
-  if (Array.isArray(given)) await ctx.record(TYPES_GIVEN, { payment_intent: id }, id);
-  if (asBool(confirmNow)) return confirmIntent(ctx, body, {});
-  return ctx.reply(ctx.expand(PI, body));
-};
-
-const confirm: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostPaymentIntentsIntentConfirm');
-  if ('answer' in loaded) return loaded.answer;
-  const { expand: _e, payment_method_data: data, mandate_data: _mandate, ...params } = ctx.params;
-  // a confirm's payment_method_data makes the method it pays with; neither it nor mandate_data is a field of the intent
-  const made = await methodFromData(ctx, data);
-  return confirmIntent(ctx, loaded.pi, made ? { ...params, payment_method: made } : params);
-};
-
-/** The type of the payment method an intent is paid with: its PaymentMethod's, or a documented test name's (pm_card_*,
- *  tok_* a card; pm_usBankAccount_* a US bank account), else unknown. */
-function methodType(ctx: SemanticsContext, method: unknown): string | undefined {
-  if (typeof method !== 'string' || !method) return undefined;
-  const row = ctx.get('payment_method', method);
-  if (row) return typeof row.type === 'string' ? row.type : undefined;
-  if (/^pm_us_?bank_?account/i.test(method)) return 'us_bank_account';
-  if (/^(pm_card_|tok_)/.test(method)) return 'card';
-  return undefined;
-}
-
-/** A confirm with a payment method of a type the intent's caller did not allow, refused as Stripe refuses it: "The
- *  PaymentMethod provided (card_present) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of
- *  the following types: card. Alternatively, update the allowed payment_method_types for this PaymentIntent to include
- *  "card_present"" (a real answer quoted in github.com/stripe/stripe-terminal-react-native/issues/745, an intent made
- *  with payment_method_types ['card']). Only a list the caller gave restricts: without one Stripe offers the methods
- *  the account enables, which the twin does not model. Where the evidence stops: that answer's code is not quoted; the
- *  twin answers payment_intent_invalid_parameter ("One or more provided parameters wasn't allowed for the given
- *  operation on the PaymentIntent", docs.stripe.com/error-codes), param payment_method. */
-function methodNotAllowed(ctx: SemanticsContext, existing: Row, params: Row): Response | undefined {
-  const types = Array.isArray(params.payment_method_types) ? params.payment_method_types.map(String)
-    : Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types.map(String)
-    : typesGiven(ctx, String(existing.id)) && Array.isArray(existing.payment_method_types) ? (existing.payment_method_types as unknown[]).map(String) : undefined;
-  if (!types) return undefined;
-  const type = methodType(ctx, params.payment_method ?? existing.payment_method);
-  if (!type || types.includes(type)) return undefined;
-  return ctx.refuse({ status: 400, code: 'payment_intent_invalid_parameter', param: 'payment_method', message: `The PaymentMethod provided (${type}) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types: ${types.join(', ')}. Alternatively, update the allowed payment_method_types for this PaymentIntent to include "${type}"` });
-}
-
-/** Confirm an intent the confirm machine allows to move: the confirm action, and a create with `confirm=true`. */
-async function confirmIntent(ctx: SemanticsContext, existing: Record<string, unknown>, params: Record<string, unknown>): Promise<Response> {
-  const id = String(existing.id);
-  // a payment names a mandate only an active one authorizes: an inactive mandate "was rejected, revoked, or previously
-  // used, and may not be used to initiate future payments" (docs.stripe.com/api/mandates/object), refused as
-  // payment_intent_mandate_invalid, "The provided mandate is invalid and can't be used for the payment intent"
-  // (docs.stripe.com/error-codes)
-  const named = typeof params.mandate === 'string' ? params.mandate : typeof existing.mandate === 'string' ? existing.mandate : undefined;
-  if (named && ctx.get('mandate', named)?.status !== 'active') return fail(ctx, 'The provided mandate is invalid and can\'t be used for the payment intent.', 400, 'payment_intent_mandate_invalid');
-  const notAllowed = methodNotAllowed(ctx, existing, params);
-  if (notAllowed) return notAllowed;
-  // a declining test card leaves the intent needing a payment method, with the error on it and a 402
-  const decline = declineFor(finder(ctx), params, existing);
-  if (decline) {
-    // Stripe records the attempt: a failed charge the intent's latest_charge names, the declined card on
-    // last_payment_error (a test name made a real PaymentMethod), and no payment_method left on the intent
-    // (docs.stripe.com/payments/paymentintents/lifecycle, docs.stripe.com/declines)
-    const ref = params.payment_method ?? existing.payment_method;
-    let pmId = typeof ref === 'string' ? ref : undefined;
-    if (pmId && !ctx.get('payment_method', pmId) && pmId.startsWith('pm_card_')) pmId = String((await materializeTestMethod(ctx, pmId, typeof existing.customer === 'string' ? existing.customer : null)).id);
-    const pm = pmId ? ctx.get('payment_method', pmId) : undefined;
-    const amount = Number(params.amount ?? existing.amount) || 0;
-    const chargeId = ctx.mint('charge');
-    await created(ctx, 'charge', {
-      id: chargeId, amount, currency: existing.currency ?? 'usd', payment_intent: id,
-      ...(typeof existing.customer === 'string' ? { customer: existing.customer } : {}),
-      ...(pmId ? { payment_method: pmId } : {}),
-      ...intentCarries({ ...existing, ...params }),
-    }, {
-      ...chargeDefaults(chargeId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
-      failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
-      outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
-      payment_method_details: pmId ? paymentMethodDetails(ctx, pmId) ?? null : null,
-    }, { operation: 'charge.failed' }); // "Occurs whenever a failed charge attempt occurs." (docs.stripe.com/api/events/types)
-    const { payment_method: _pm, ...rest } = params;
-    const last_payment_error = { type: 'card_error', code: decline.code, ...(decline.decline_code ? { decline_code: decline.decline_code } : {}), message: decline.message, param: 'card', charge: chargeId, payment_method: pm ?? null };
-    const failed = await ctx.write(PI, id, { ...rest, payment_method: null, latest_charge: chargeId, status: 'requires_payment_method', last_payment_error }, 'payment_intent.payment_failed');
-    return send(ctx, cardError(decline, { payment_intent: failed, charge: chargeId }));
-  }
-  // a bank debit that needs micro-deposit verification waits in requires_action
-  const method = typeof params.payment_method === 'string' ? params.payment_method : typeof existing.payment_method === 'string' ? existing.payment_method : undefined;
-  // a bank transfer is paid from the customer's cash balance, or waits for the transfer (fundFromCashBalance)
-  if (method && ctx.get('payment_method', method)?.type === 'customer_balance') return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, { ...existing, ...params }, params)));
-  if (requiresMicrodeposits(params, existing) || microdepositsAsked(ctx, params, existing, method)) {
-    return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: microdepositsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
-  }
-  // 3DS: the first confirm asks for authentication; a second one completes it
-  if (existing.status !== 'requires_action' && requiresAuthentication(params, existing)) {
-    return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: threeDsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
-  }
-  // manual capture authorizes and waits for /capture: the authorization is a charge, succeeded and not captured, the
-  // intent's latest_charge
-  if ((params.capture_method ?? existing.capture_method) === 'manual') {
-    const amount = Number(existing.amount ?? params.amount ?? 0);
-    const charge = await authorizeCharge(ctx, id, { ...existing, ...params }, amount);
-    return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_capture', amount_capturable: amount, amount_received: 0, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.amount_capturable_updated')));
-  }
-  // a bank debit is submitted and settles later (beginBankDebit)
-  if (isBankDebit(ctx, method)) return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, id, params)));
-  const amount = Number(existing.amount ?? params.amount ?? 0);
-  // a succeeded intent has a Charge, and latest_charge names it: what a refund of it lands on
-  const charge = await mintCharge(ctx, id, { ...existing, ...params }, amount);
-  const body = await ctx.write(PI, id, { ...params, status: 'succeeded', amount_received: amount, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.confirm');
-  await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentConfirm');
-  return ctx.reply(ctx.expand(PI, body));
-}
-
-const capture: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostPaymentIntentsIntentCapture');
-  if ('answer' in loaded) return loaded.answer;
-  const pi = loaded.pi;
-  const authorized = Number(pi.amount_capturable ?? pi.amount ?? 0);
-  // amount_to_capture lowers the captured amount (a partial capture); it never raises it
-  const asked = ctx.params.amount_to_capture !== undefined ? Math.max(0, Math.trunc(Number(ctx.params.amount_to_capture) || 0)) : authorized;
-  const captured = Math.min(asked, authorized);
-  // the authorization confirm made is captured; an intent authorized before it was kept is charged as before
-  const auth = typeof pi.latest_charge === 'string' ? ctx.get('charge', pi.latest_charge) : undefined;
-  const held = auth && auth.status === 'succeeded' && auth.captured === false ? auth : undefined;
-  if (held) {
-    const refused = ctx.legal('charge', 'captured', 'PostPaymentIntentsIntentCapture', 'false', 'true', String(held.id));
-    if (refused) return ctx.refuse(refused);
-    await captureAuthorization(ctx, held, captured, 'PostPaymentIntentsIntentCapture');
-    await afterCharge(ctx, String(held.id), { amount: captured, currency: String(pi.currency ?? 'usd'), payment_intent: String(pi.id), application_fee_amount: pi.application_fee_amount, destination: (pi.transfer_data as Row | undefined)?.destination }, pi.payment_method);
-  }
-  const charge = held ? String(held.id) : await mintCharge(ctx, String(pi.id), pi, captured);
-  const body = await ctx.write(PI, String(pi.id), { status: 'succeeded', amount_received: captured, amount_capturable: 0, latest_charge: charge }, 'payment_intent.succeeded');
-  await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentCapture');
-  return ctx.reply(ctx.expand(PI, body));
-};
-
-/** An increment that does not raise the authorization. */
-function incrementTooSmall(ctx: SemanticsContext): Response {
-  return ctx.refuse({ status: 400, code: 'parameter_invalid_integer', message: 'The new amount must be greater than the current amount of the PaymentIntent.' });
-}
-
-const incrementAuthorization: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostPaymentIntentsIntentIncrementAuthorization');
-  if ('answer' in loaded) return loaded.answer;
-  const pi = loaded.pi;
-  if (ctx.params.amount === undefined) return ctx.refuse({ status: 400, code: 'parameter_missing', message: 'Missing required param: amount.' });
-  const amount = Math.trunc(Number(ctx.params.amount) || 0);
-  if (!Number.isInteger(amount) || amount <= Number(pi.amount ?? 0)) return incrementTooSmall(ctx);
-  // the authorization the charge holds grows with it: "If the incremental authorization fails ... no other fields on
-  // the PaymentIntent or Charge update" (docs.stripe.com/api/payment_intents/increment_authorization), so on success the
-  // charge's amount is the new authorized amount. Where the documentation stops and the twin decides: the charge's
-  // update sends no event of its own (the events page names none for it).
-  const held = typeof pi.latest_charge === 'string' ? ctx.get('charge', pi.latest_charge) : undefined;
-  if (held && held.captured === false) await ctx.write('charge', String(held.id), { amount }, 'charge.authorization_incremented');
-  return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(pi.id), { amount, amount_capturable: amount }, 'payment_intent.amount_capturable_updated')));
-};
-
-const cancel: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostPaymentIntentsIntentCancel');
-  if ('answer' in loaded) return loaded.answer;
-  const cancellation_reason = typeof ctx.params.cancellation_reason === 'string' ? ctx.params.cancellation_reason : 'requested_by_customer';
-  // "For PaymentIntents with a `status` of `requires_capture`, the remaining `amount_capturable` is automatically
-  // refunded" (docs.stripe.com/api/payment_intents/cancel): the authorization is released (charges.ts)
-  const held = loaded.pi.status === 'requires_capture' && typeof loaded.pi.latest_charge === 'string' ? ctx.get('charge', loaded.pi.latest_charge) : undefined;
-  if (held && held.captured === false && held.refunded !== true) await cancelAuthorization(ctx, held);
-  return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(loaded.pi.id), { status: 'canceled', cancellation_reason, amount_capturable: 0 }, 'payment_intent.canceled')));
-};
-
-const verifyMicrodepositsHandler: Semantics = async (ctx) => {
-  const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
-  if (!pi) return ctx.notFound(PI, String(ctx.id));
-  // the deposit amounts are checked before the intent's state, as Stripe does
-  const wrong = verifyMicrodeposits(ctx.params, pi);
-  if (wrong) return send(ctx, wrong);
-  const refusal = ctx.legal(PI, 'status', 'PostPaymentIntentsIntentVerifyMicrodeposits', pi.status);
-  if (refusal) return ctx.refuse(refusal);
-  const amount = Number(pi.amount) || 0;
-  // a debit saved for reuse ("If you want to reuse the payment method in the future, provide the setup_future_usage
-  // parameter with the value of off_session", the ACH page) is authorized for many payments (multi_use, "Represents
-  // permission given for multiple payments"); else for this one (single_use, "a one-time permission given for a single
-  // payment", docs.stripe.com/api/mandates/object)
-  const reuse = pi.setup_future_usage === 'off_session' || pi.setup_future_usage === 'on_session';
-  const mandate = reuse ? await mintMandate(ctx, pi.payment_method, 'multi_use') : await mintMandate(ctx, pi.payment_method, 'single_use', amount, String(pi.currency ?? 'usd'));
-  // "When the bank account is successfully verified, Stripe returns the PaymentIntent object with a status of
-  // `processing`" (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api)
-  return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, String(pi.id), { mandate })));
-};
-
-// ── a bank debit is submitted, and settles ──
-//
-// ACH Direct Debit "is a delayed notification payment method ... The PaymentIntent you create initially has a status
-// of `processing`. After the payment has succeeded, the PaymentIntent status is updated from `processing` to
-// `succeeded`"; verification by micro-deposits returns "a status of `processing`, and sends a payment_intent.processing
-// webhook event"; and, the twin being a test-mode account: "Test transactions settle instantly and are added to your
-// available test balance. This behavior differs from live mode, where transactions can take multiple days to settle"
-// (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api). A confirm answers processing; the
-// debit succeeds at that same instant of the World's clock, caught up before the next request is answered (as
-// renewals and payouts are). The page's test accounts give each debit its outcome: pm_usBankAccount_success
-// (000123456789) "The payment succeeds"; pm_usBankAccount_processing (000000000009) "The payment stays in processing
-// indefinitely". Where the documentation stops and the twin decides: its Charge is made when it succeeds (the page
-// names none while it processes); the failing test accounts (closed, no account, insufficient funds, debit not
-// authorized, invalid currency, dispute, weekly limit, Radar block) are not modelled and succeed.
-
-/** Whether the method an intent is confirmed with is a bank debit: a us_bank_account PaymentMethod, or one of Stripe's
- *  test bank accounts named as one (pm_usBankAccount_*, pm_us_bank_account). */
-export function isBankDebit(ctx: SemanticsContext, method: unknown): boolean {
-  if (typeof method !== 'string') return false;
-  return ctx.get('payment_method', method)?.type === 'us_bank_account' || /^pm_us_?bank_?account/i.test(method);
-}
-
-/** Whether a bank debit stays processing: the page's pm_usBankAccount_processing, or its account 000000000009. */
-function staysProcessing(ctx: SemanticsContext, method: unknown): boolean {
-  if (method === 'pm_usBankAccount_processing') return true;
-  const bank = typeof method === 'string' ? (ctx.get('payment_method', method)?.us_bank_account as Row | undefined) : undefined;
-  return bank?.last4 === '0009';
-}
-
-/** A bank debit submitted: the intent processes, nothing received yet, sent as payment_intent.processing; it is due to
- *  settle at this instant, unless its test account stays processing. */
-async function beginBankDebit(ctx: SemanticsContext, id: string, fields: Row): Promise<Row> {
-  const method = fields.payment_method ?? ctx.get(PI, id)?.payment_method;
-  return ctx.write(PI, id, { ...fields, status: 'processing', amount_received: 0, next_action: null, last_payment_error: null, _settles_at: staysProcessing(ctx, method) ? null : Number(ctx.now()) }, 'payment_intent.processing');
-}
-
-/** Time's settling of bank debits, caught up to the World's clock: each processing debit whose moment has come succeeds
- *  then, its Charge made (naming the mandate it ran under) and the invoice it collects for paid. */
-export async function settleBankDebits(ctx: SemanticsContext): Promise<void> {
-  const now = Number(ctx.now());
-  const due = ctx.rowsRaw(PI).filter((p) => p.status === 'processing' && typeof p._settles_at === 'number' && p._settles_at <= now).sort((a, b) => Number(a._settles_at) - Number(b._settles_at));
-  for (const pi of due) {
-    const id = String(pi.id);
-    const c = await at_(ctx)(Number(pi._settles_at));
-    c.legal(PI, 'status', ctx.call.operation.id, 'processing', 'succeeded', id, 'vendor');
-    const amount = Number(pi.amount) || 0;
-    const charge = await mintCharge(c, id, pi, amount);
-    // the charge names the mandate its bank debit ran under (payment_method_details.us_bank_account.mandate)
-    const details = (c.get('charge', charge)?.payment_method_details ?? null) as Row | null;
-    const kind = typeof details?.type === 'string' ? details.type : undefined;
-    if (details && kind && typeof pi.mandate === 'string') await c.write('charge', charge, { payment_method_details: { ...details, [kind]: { ...((details[kind] as Row | undefined) ?? {}), mandate: pi.mandate } } }, 'charge.mandate');
-    const body = await c.write(PI, id, { status: 'succeeded', amount_received: amount, latest_charge: charge, _settles_at: null }, 'payment_intent.succeeded');
-    // a single-use mandate is spent by its payment: "previously used, and may not be used to initiate future payments"
-    const used = typeof pi.mandate === 'string' ? c.get('mandate', pi.mandate) : undefined;
-    if (used && used.type === 'single_use' && used.status === 'active') {
-      c.legal('mandate', 'status', ctx.call.operation.id, 'active', 'inactive', String(used.id), 'vendor');
-      await c.write('mandate', String(used.id), { status: 'inactive' }, 'mandate.updated');
-    }
-    await payInvoiceOf(c, body, ctx.call.operation.id, 'vendor');
-  }
-}
-
-/** A customer_balance intent funded from the customer's cash balance: paid when the balance covers it ("If the customer
- *  already has a balance high enough to cover the payment amount, the PaymentIntent immediately succeeds"), else
- *  waiting for a transfer: "If the customer balance isn’t high enough to cover the request amount, the PaymentIntent
- *  shows a requires_action status ... next_action ... display_bank_transfer_instructions" with the amount_remaining
- *  (docs.stripe.com/payments/bank-transfers/accept-a-payment). Answers the intent as written. */
-async function fundFromCashBalance(ctx: SemanticsContext, pi: Row, fields: Row = {}): Promise<Row> {
-  const customer = typeof pi.customer === 'string' ? pi.customer : '';
-  const currency = String(pi.currency ?? 'usd');
-  // what the customer's funded cash balance holds in this currency, from its ledger
-  const available = customer ? ctx.rows('customer_cash_balance_transaction').filter((t) => t.customer === customer && String(t.currency) === currency).reduce((n, t) => n + (Number(t.net_amount) || 0), 0) : 0;
-  const amount = Number(pi.amount) || 0;
-  if (available >= amount) {
-    // the balance pays the intent: its ledger records what was applied
-    await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'applied_to_payment', net_amount: -amount, ending_balance: available - amount, applied_to_payment: { payment_intent: String(pi.id) }, livemode: false });
-    const charge = await mintCharge(ctx, String(pi.id), { ...pi, ...fields }, amount);
-    return ctx.write(PI, String(pi.id), { ...fields, status: 'succeeded', next_action: null, amount_received: amount, last_payment_error: null, latest_charge: charge }, 'payment_intent.succeeded');
-  }
-  // not enough yet: the intent waits for the rest, with the instructions to send it
-  const next_action = { type: 'display_bank_transfer_instructions', display_bank_transfer_instructions: { amount_remaining: amount - available, currency, type: 'us_bank_transfer' } };
-  return ctx.write(PI, String(pi.id), { ...fields, status: 'requires_action', next_action }, 'payment_intent.requires_action');
-}
-
-const applyCustomerBalance: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostPaymentIntentsIntentApplyCustomerBalance');
-  if ('answer' in loaded) return loaded.answer;
-  return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, loaded.pi)));
-};
-
-export const paymentIntents: Record<string, Semantics> = {
-  PostPaymentIntents: create,
-  GetPaymentIntentsSearch: async (ctx) => search(ctx, PI),
-  PostPaymentIntentsIntentConfirm: confirm,
-  PostPaymentIntentsIntentCapture: capture,
-  PostPaymentIntentsIntentIncrementAuthorization: incrementAuthorization,
-  PostPaymentIntentsIntentCancel: cancel,
-  PostPaymentIntentsIntentVerifyMicrodeposits: verifyMicrodepositsHandler,
-  PostPaymentIntentsIntentApplyCustomerBalance: applyCustomerBalance,
-};

package/src/semantics/payment-links.ts

@@ -1,148 +0,0 @@
-// Payment Link and Quote semantics. Both carry line items resolved from existing prices. A payment
-// link is a reusable hosted-checkout URL, active until switched off; a quote moves draft → open
-// (finalize) → accepted or canceled, the machine in ../manifest.ts. Link retrieve and update
-// (`active`, its machine), quote retrieve and the quote list are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { asBool, lineItemEntries, paginate, resolveLineItem, type CheckoutItem } from '../stripe-twin.ts';
-import { draftInvoiceFor } from './invoices.ts';
-import { at, created, fail, finder, list, newest, path, where, type Row } from './shared.ts';
-
-/** The request's line items resolved against their prices, or the refusal for a missing price. */
-function resolved(ctx: SemanticsContext): CheckoutItem[] | Response {
-  const entries = lineItemEntries(ctx.params);
-  const items: CheckoutItem[] = [];
-  for (let i = 0; i < entries.length; i++) {
-    const { item, priceMissing } = resolveLineItem(entries[i]!, i, 'usd', finder(ctx));
-    if (priceMissing) return fail(ctx, `No such price: '${priceMissing}'`, 400, 'resource_missing');
-    items.push(item);
-  }
-  return items;
-}
-
-/** A page of the line items a stored object carries. */
-function linePage(ctx: SemanticsContext, holder: Row): Response {
-  const li = holder.line_items as { data?: Row[] } | undefined;
-  const { page, hasMore } = paginate(Array.isArray(li?.data) ? li!.data! : [], ctx.params);
-  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
-}
-
-const PL = 'payment_link';
-const linkMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such payment link: '${id}'`, 404, 'resource_missing');
-
-const createLink: Semantics = async (ctx) => {
-  if (lineItemEntries(ctx.params).length === 0) return fail(ctx, 'Missing required param: line_items.', 400, 'parameter_missing');
-  const items = resolved(ctx);
-  if (items instanceof Response) return items;
-  const id = ctx.mint(PL);
-  const { line_items: _li, ...rest } = ctx.params;
-  return ctx.reply(
-    await created(ctx, PL, { ...rest, id }, {
-      active: ctx.params.active !== undefined ? asBool(ctx.params.active) : true,
-      url: `https://buy.twin.local/${id}`, livemode: false, metadata: {},
-      // Stripe's defaults for what the link was not given (docs.stripe.com/api/payment-link/create)
-      allow_promotion_codes: false, automatic_tax: { enabled: false, liability: null }, billing_address_collection: 'auto',
-      custom_fields: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null },
-      customer_creation: 'if_required', payment_method_collection: 'always', phone_number_collection: { enabled: false },
-      shipping_options: [], submit_type: 'auto', tax_id_collection: { enabled: false, required: 'never' },
-      line_items: { object: 'list', data: items, has_more: false, url: `/v1/payment_links/${id}/line_items` },
-      currency: items[0]?.currency ?? 'usd',
-      after_completion: { type: 'redirect', redirect: typeof ctx.params.after_completion === 'object' ? ctx.params.after_completion : null },
-    }),
-  );
-};
-
-const listLinks: Semantics = async (ctx) => list(ctx, PL, where(ctx, newest(ctx, PL), { active: (p, v) => asBool(p.active) === asBool(v) }));
-
-const linkLines: Semantics = async (ctx) => {
-  const p = ctx.get(PL, at(ctx, 'payment_link'));
-  return p ? linePage(ctx, p) : linkMissing(ctx, at(ctx, 'payment_link'));
-};
-
-// ── quotes ──
-
-const quoteMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such quote: '${id}'`, 404, 'resource_missing');
-
-const createQuote: Semantics = async (ctx) => {
-  const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
-  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-  if (!ctx.row('customer', customer, { withDeleted: true })) return fail(ctx, `No such customer: '${customer}'`, 400, 'resource_missing');
-  const items = resolved(ctx);
-  if (items instanceof Response) return items;
-  const subtotal = items.reduce((s, it) => s + it.amount_subtotal, 0);
-  const id = ctx.mint('quote');
-  const { line_items: _li, ...rest } = ctx.params;
-  return ctx.reply(
-    await created(ctx, 'quote', { ...rest, id }, {
-      status: 'draft', customer, currency: items[0]?.currency ?? 'usd', livemode: false, metadata: {},
-      amount_subtotal: subtotal, amount_total: subtotal,
-      // Stripe's defaults (docs.stripe.com/api/quotes/create); what is paid up front is the whole quote, and the twin bills in classic mode
-      automatic_tax: { enabled: false, liability: null, provider: null, status: null }, collection_method: 'charge_automatically', discounts: [],
-      invoice_settings: { days_until_due: null, issuer: { type: 'self' } },
-      subscription_data: { billing_mode: { type: 'classic' }, description: null, effective_date: null, metadata: null, trial_period_days: null },
-      computed: { recurring: null, upfront: { amount_subtotal: subtotal, amount_total: subtotal, total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 } } },
-      line_items: { object: 'list', data: items, has_more: false, url: `/v1/quotes/${id}/line_items` },
-      total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 },
-      expires_at: Number(ctx.now()) + 30 * 24 * 3600,
-      number: null, invoice: null, subscription: null,
-      status_transitions: { accepted_at: null, canceled_at: null, finalized_at: null },
-    }),
-  );
-};
-
-const quoteLines: Semantics = async (ctx) => {
-  const q = ctx.get('quote', at(ctx, 'quote'));
-  return q ? linePage(ctx, q) : quoteMissing(ctx, at(ctx, 'quote'));
-};
-
-// Stripe streams the PDF; the twin answers a stable reference to it
-const pdf: Semantics = async (ctx) => {
-  const id = at(ctx, 'quote');
-  if (!ctx.get('quote', id)) return quoteMissing(ctx, id);
-  return ctx.reply({ object: 'quote_pdf', url: `https://files.twin.local/quotes/${id}.pdf` });
-};
-
-function move(action: 'finalize' | 'accept' | 'cancel', operationId: string): Semantics {
-  return async (ctx) => {
-    const id = at(ctx, 'quote');
-    const q = ctx.get('quote', id);
-    if (!q) return quoteMissing(ctx, id);
-    const refused = ctx.legal('quote', 'status', operationId, q.status, undefined, id);
-    if (refused) return ctx.refuse(refused);
-    const now = ctx.now();
-    const stamp = action === 'finalize' ? { finalized_at: now } : action === 'accept' ? { accepted_at: now } : { canceled_at: now };
-    // "Accepted quotes automatically generate an invoice, subscription, or subscription schedule"; "Quotes without
-    // recurring prices: A draft invoice is created with auto_advance set to false" (docs.stripe.com/quotes/overview),
-    // the quote its parent ("Details about the quote that generated this invoice", the served spec). Where the
-    // documentation stops and the twin decides: a quote with recurring prices makes no subscription yet.
-    let made: Row = {};
-    if (action === 'accept') {
-      const lines = ((q.line_items as Row | undefined)?.data as Row[] | undefined) ?? [];
-      const recurring = lines.some((l) => l.price && typeof l.price === 'object' && (l.price as Row).recurring);
-      if (!recurring && typeof q.customer === 'string') {
-        const invoice = await draftInvoiceFor(ctx, q.customer, String(q.currency ?? 'usd'), { type: 'quote_details', quote_details: { quote: id }, subscription_details: null }, lines.map((l) => ({ price: l.price, quantity: Number(l.quantity) || 1, amount: Number(l.amount_subtotal ?? l.amount_total) || 0, description: l.description })));
-        made = { invoice };
-      }
-    }
-    return ctx.reply(
-      await ctx.write('quote', id, {
-        status: action === 'finalize' ? 'open' : action === 'accept' ? 'accepted' : 'canceled',
-        status_transitions: { ...((q.status_transitions as Row) ?? {}), ...stamp },
-        ...(action === 'finalize' ? { number: `QT-${id.toUpperCase()}` } : {}),
-        ...made,
-      }, `quote.${action}`),
-    );
-  };
-}
-
-export const paymentLinks: Record<string, Semantics> = {
-  PostPaymentLinks: createLink,
-  GetPaymentLinks: listLinks,
-  GetPaymentLinksPaymentLinkLineItems: linkLines,
-  PostQuotes: createQuote,
-  GetQuotesQuoteLineItems: quoteLines,
-  GetQuotesQuoteComputedUpfrontLineItems: quoteLines,
-  GetQuotesQuotePdf: pdf,
-  PostQuotesQuoteFinalize: move('finalize', 'PostQuotesQuoteFinalize'),
-  PostQuotesQuoteAccept: move('accept', 'PostQuotesQuoteAccept'),
-  PostQuotesQuoteCancel: move('cancel', 'PostQuotesQuoteCancel'),
-};