@volter/twin-stripe 2.0.38 → 3.0.0

package/src/semantics/invoices.ts

@@ -1,166 +1,40 @@
-// Invoice and InvoiceItem semantics. The machine in ../manifest.ts says which moves of an invoice's
-// `status` are legal (finalize, send, pay, mark_uncollectible, void) and what Stripe answers
-// otherwise; these handlers compute each move, keep a draft's lines and totals in step with its
-// items, and mint the PaymentIntent a finalized invoice collects through. The invoice list and the
-// item list are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { addBillingInterval, applyCouponDiscount, asBool, cardError, declineFor, mintClientSecret, paginate, priceAmount, subscriptionItemPairs } from '../stripe-twin.ts';
-import { mintCharge } from './payment-intents.ts';
-import { spendOnceCoupon } from './renewals.ts';
-import { at, created, expanded, fail, finder, list, newest, path, search, send, type Row } from './shared.ts';
+// Stripe's invoices 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 { collectsThroughIntent, draft, INV, linesOf, prorationLines, sumLines, transitions } from '../engine/invoices.ts';
+import { addBillingInterval, applyCouponDiscount, asBool, cardError, declineFor, nowUnix, paginate, priceAmount, subscriptionItemPairs } from '../engine/stripe.ts';
+import { activatedByPayment, at, created, editLines, expanded, fail, finalizedFields, finder, invoiceMissing, invoicesLoad, mintCharge, newest, nothingToPayWith, openPaymentIntent, path, pullPendingItem, search, send, spendOnceCoupon } from './shared.ts';
 
-const INV = 'invoice';
-const invoiceMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such invoice: '${id}'`, 404, 'resource_missing');
-const linesOf = (inv: Row): Row[] => (inv.lines as { data?: Row[] } | undefined)?.data ?? [];
-const sumLines = (lines: Row[]): number => lines.reduce((s, l) => s + (Number(l.amount) || 0), 0);
-
-/** Write a draft's line list and the totals derived from it. */
-async function writeLines(ctx: SemanticsContext, invoiceId: string, next: Row[]): Promise<Row> {
-  const subtotal = sumLines(next);
-  const lines = { object: 'list', data: next, has_more: false, total_count: next.length, url: `/v1/invoices/${invoiceId}/lines` };
-  return ctx.write(INV, invoiceId, { lines, subtotal, total: subtotal, amount_due: subtotal, amount_remaining: subtotal }, 'invoice.update');
-}
-
-/** Paying an invoice with nothing to pay it: "If not set, defaults to the subscription's default payment method, if any,
- *  or to the default payment method in the customer's invoice settings" (docs.stripe.com/api/invoices/object,
- *  default_payment_method), and none of them is set. */
-function nothingToPayWith(ctx: SemanticsContext): Response {
-  return fail(ctx, 'This customer has no attached payment source or default payment method. Please consider adding a default payment method.', 400, 'missing');
-}
-
-/** A subscription waiting on the invoice paid through the invoice's own pay (incomplete on its first, past_due on a
- *  failed renewal) is active again. */
-async function activatedByPayment(ctx: SemanticsContext, subId: string): Promise<void> {
-  await ctx.write('subscription', subId, { status: 'active' }, 'subscription.update');
-}
-
-/** A draft's line no invoice item made (a subscription's) stays as it is when an item changes. */
-function unlinkedLine(line: Row): Row {
-  return line;
-}
-
-/** A preview's proration for a change at proration_date. Where the documentation stops and the twin decides: half the
- *  period's charge credited as unused time and half charged as remaining time. */
-function prorationLines(out: Row[], subtotal: number, currency: string, now: number, period: number): void {
-  const half = Math.round(subtotal / 2);
-  out.unshift({ id: 'il_twin_proration_unused', object: 'line_item', type: 'invoiceitem', amount: -half, currency, proration: true, period: { start: now, end: period }, description: 'Unused time (proration credit)' });
-  out.push({ id: 'il_twin_proration_remaining', object: 'line_item', type: 'invoiceitem', amount: half, currency, proration: true, period: { start: now, end: period }, description: 'Remaining time (proration charge)' });
+// only a draft is deleted; a finalized invoice is voided instead
+export async function DeleteInvoicesInvoice(ctx: HandlerContext): Promise<Response> {
+  const loaded = invoicesLoad(ctx, 'DeleteInvoicesInvoice');
+  if ('answer' in loaded) return loaded.answer;
+  const id = String(loaded.inv.id);
+  await ctx.write(INV, id, { deleted: true }, 'invoice.deleted');
+  return ctx.reply({ id, object: 'invoice', deleted: true });
 }
 
-/** Re-derive a draft's lines from the items still on it: an item that changed or was deleted moves the invoice with it. */
-async function resyncDraftLines(ctx: SemanticsContext, invoiceId: string): Promise<void> {
-  const inv = ctx.get(INV, invoiceId);
-  if (!inv || inv.status !== 'draft') return;
-  const next: Row[] = [];
-  for (const line of linesOf(inv)) {
-    const itemId = typeof line.invoice_item === 'string' ? line.invoice_item : '';
-    if (!itemId) next.push(unlinkedLine(line));
-    const item = itemId ? ctx.get('invoiceitem', itemId) : undefined;
-    if (item) next.push({ ...line, amount: Number(item.amount) || 0, description: (item.description as string) ?? null });
-  }
-  await writeLines(ctx, invoiceId, next);
+export async function GetInvoicesInvoice(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'invoice');
+  const inv = ctx.get(INV, id);
+  return inv ? ctx.reply(expanded(ctx, INV, inv)) : invoiceMissing(ctx, id);
 }
 
-// ── invoice items: a price-based item takes its amount from the price; one naming a draft invoice
-// lands on its lines at once ──
-
-/** An item priced by a Price: its unit amount times the quantity, in its currency (docs.stripe.com/api/invoiceitems/create#create_invoiceitem-pricing). */
-function pricedItem(ctx: SemanticsContext, priceRef: string, qty: number): { amount: number; currency: string | undefined } | Response {
-  const price = ctx.get('price', priceRef);
-  if (!price) return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
-  return { amount: priceAmount(price, qty), currency: typeof price.currency === 'string' ? price.currency : undefined };
+// the invoice's lines, a page at a time
+export async function GetInvoicesInvoiceLines(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'invoice');
+  const inv = ctx.get(INV, id);
+  if (!inv) return invoiceMissing(ctx, id);
+  const { page, hasMore } = paginate(linesOf(inv), ctx.params);
+  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page.map((l) => ({ invoice: id, ...l })) });
 }
 
-const createItem: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const now = Number(ctx.now());
-  const qty = Number(params.quantity) || 1;
-  // the served version names the price in `pricing[price]` ("The pricing information for the invoice item", the served
-  // spec); an older version sends `price`. It is kept as the item's price, which the answer renders as `pricing`
-  // (stripe-version.ts)
-  const { pricing: pricingParam, ...stored } = params;
-  const given = (pricingParam as Row | undefined)?.price;
-  const priceRef = typeof given === 'string' && given ? given : typeof params.price === 'string' ? params.price : '';
-  const priced = priceRef ? pricedItem(ctx, priceRef, qty) : undefined;
-  if (priced instanceof Response) return priced;
-  const resolvedAmount = priced?.amount;
-  let resolvedCurrency = priced?.currency;
-  // only a draft invoice takes new items
-  const invoiceRef = typeof params.invoice === 'string' ? params.invoice : '';
-  let target: Row | undefined;
-  if (invoiceRef) {
-    target = ctx.get(INV, invoiceRef);
-    if (!target) return invoiceMissing(ctx, invoiceRef);
-    if (target.status !== 'draft') return fail(ctx, `This invoice cannot have invoice items added because it has status ${String(target.status)}.`, 400, 'invoice_not_editable');
-    if (resolvedCurrency === undefined && typeof target.currency === 'string') resolvedCurrency = target.currency;
-  }
-  // an invoice item is dated by `date`, not `created`; its currency is the price's, else the invoice's
-  const item = await created(ctx, 'invoiceitem', { ...stored, ...(priceRef ? { price: priceRef } : {}) }, {
-    livemode: false, discountable: true, proration: false, quantity: qty, quantity_decimal: String(qty),
-    period: { start: now, end: now }, currency: resolvedCurrency ?? 'usd',
-    ...(resolvedAmount !== undefined ? { amount: resolvedAmount } : {}),
-  }, { timeField: 'date' });
-  if (target) {
-    await writeLines(ctx, invoiceRef, [...linesOf(target), {
-      id: `il_${String(item.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(item.amount) || 0, currency: String(target.currency ?? item.currency ?? 'usd'),
-      quantity: qty, proration: false, invoice_item: item.id, price: item.price ?? null,
-      period: item.period ?? { start: now, end: now }, description: (item.description as string) ?? null,
-    }]);
-  }
-  return ctx.reply(item);
-};
-
-const itemMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such invoiceitem: '${id}'`, 404, 'resource_missing');
-
-const retrieveItem: Semantics = async (ctx) => {
-  const it = ctx.get('invoiceitem', at(ctx, 'invoiceitem'));
-  return it ? ctx.reply(it) : itemMissing(ctx, at(ctx, 'invoiceitem'));
-};
-
-const updateItem: Semantics = async (ctx) => {
-  const id = at(ctx, 'invoiceitem');
-  const it = ctx.get('invoiceitem', id);
-  if (!it) return itemMissing(ctx, id);
-  const updated = await ctx.write('invoiceitem', id, ctx.params, 'invoiceitem.update');
-  if (typeof it.invoice === 'string') await resyncDraftLines(ctx, it.invoice);
-  return ctx.reply(updated);
-};
-
-// an item is deleted only while its invoice is still editable
-const deleteItem: Semantics = async (ctx) => {
-  const id = at(ctx, 'invoiceitem');
-  const it = ctx.get('invoiceitem', id);
-  if (!it) return itemMissing(ctx, id);
-  const onInvoice = typeof it.invoice === 'string' ? ctx.get(INV, it.invoice) : undefined;
-  if (onInvoice && onInvoice.status !== 'draft') return fail(ctx, 'You cannot delete an invoice item that is attached to an invoice that is no longer editable.', 400, 'invoice_not_editable');
-  await ctx.write('invoiceitem', id, { deleted: true }, 'invoiceitem.delete');
-  if (typeof it.invoice === 'string') await resyncDraftLines(ctx, it.invoice);
-  return ctx.reply({ id, object: 'invoiceitem', deleted: true });
-};
-
-// ── invoices ──
-
-/** A draft invoice's fields before anything is on it: what a new invoice and a preview start from. */
-const draft = (now: number): Row => ({
-  status: 'draft', livemode: false, currency: 'usd', collection_method: 'charge_automatically',
-  auto_advance: false, attempt_count: 0, attempted: false,
-  amount_due: 0, amount_paid: 0, amount_remaining: 0, amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
-  subtotal: 0, total: 0, starting_balance: 0, post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
-  period_start: now, period_end: now, default_tax_rates: [], discounts: [],
-  lines: { object: 'list', data: [], has_more: false, total_count: 0 },
-  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 },
-  // a draft has no PaymentIntent: finalize mints it
-  payment_intent: null,
-});
-
 // a new invoice pulls in the customer's pending items only when asked: pending_invoice_items_behavior "Defaults to
 // `exclude` if the parameter is omitted" (docs.stripe.com/api/invoices/create)
-const create: Semantics = async (ctx) => {
+export async function PostInvoices(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
-  const now = Number(ctx.now());
+  const now = Number(nowUnix(ctx.occurredAt));
   // the lines list names where it can be read, "The URL where this list can be accessed" (served spec, invoice.lines.url)
   const newId = ctx.mint(INV);
   // a send_invoice invoice is due `days_until_due` days "from when the invoice is created" (the same page); the customer's
@@ -177,254 +51,18 @@ const create: Semantics = async (ctx) => {
   const pending = customerId ? newest(ctx, 'invoiceitem', 'date').filter((it) => it.customer === customerId && !it.invoice).reverse() : [];
   for (const item of pending) await pullPendingItem(ctx, invoiceId, inv, item, now);
   return ctx.reply(pending.length > 0 ? (ctx.get(INV, invoiceId) ?? inv) : inv);
-};
-
-/** A draft invoice another object makes (an accepted quote): its customer's, with an invoice item per line the
- *  object gives, and the object named as its parent. Answers the invoice's id. */
-export async function draftInvoiceFor(ctx: SemanticsContext, customer: string, currency: string, parent: Row, lines: Array<{ price: unknown; quantity: number; amount: number; description: unknown }>): Promise<string> {
-  const now = Number(ctx.now());
-  const id = ctx.mint(INV);
-  const holder = ctx.get('customer', customer);
-  const inv = await created(ctx, INV, { id, customer, currency, parent }, { ...draft(now), currency, customer_email: holder?.email ?? null, customer_name: holder?.name ?? null, lines: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/invoices/${id}/lines` } });
-  for (const l of lines) {
-    const price = typeof l.price === 'string' ? l.price : l.price && typeof l.price === 'object' ? String((l.price as Row).id) : null;
-    const item = await created(ctx, 'invoiceitem', { customer, currency, amount: l.amount, quantity: l.quantity, ...(price ? { price } : {}), description: l.description ?? null }, { date: now, livemode: false, metadata: {}, discountable: true, proration: false, period: { start: now, end: now } });
-    await pullPendingItem(ctx, id, inv, item, now);
-  }
-  return id;
-}
-
-/** A customer's pending invoice item, made before the invoice, pulled onto it (docs.stripe.com/api/invoices/create#create_invoice-pending_invoice_items_behavior). */
-async function pullPendingItem(ctx: SemanticsContext, invoiceId: string, inv: Row, item: Row, now: number): Promise<void> {
-  const current = ctx.get(INV, invoiceId) ?? inv;
-  await writeLines(ctx, invoiceId, [...linesOf(current), {
-    id: `il_${String(item.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(item.amount) || 0, currency: String(current.currency ?? item.currency ?? 'usd'),
-    quantity: Number(item.quantity) || 1, proration: false, invoice_item: item.id, price: item.price ?? null,
-    period: item.period ?? { start: now, end: now }, description: (item.description as string) ?? null,
-    discountable: item.discountable ?? true, discounts: [], livemode: false, metadata: item.metadata ?? {}, tax_amounts: [], tax_rates: [],
-  }]);
-  await ctx.write('invoiceitem', String(item.id), { invoice: invoiceId }, 'invoiceitem.update');
-}
-
-/** The invoice the path names, and the machine's refusal when this operation may not move it. */
-function load(ctx: SemanticsContext, operationId: string): { inv: Row } | { answer: Response } {
-  const id = at(ctx, 'invoice');
-  const inv = ctx.get(INV, id);
-  if (!inv) return { answer: invoiceMissing(ctx, id) };
-  const refused = ctx.legal(INV, 'status', operationId, inv.status, undefined, id);
-  return refused ? { answer: ctx.refuse(refused) } : { inv };
-}
-
-/** The PaymentIntent a charge_automatically invoice with a balance gets when it is finalized; it
- *  waits for confirmation when the invoice already names a default payment method. */
-async function openPaymentIntent(ctx: SemanticsContext, piId: string, inv: Row, invoiceId: string): Promise<void> {
-  const defaultPaymentMethod = typeof inv.default_payment_method === 'string' ? inv.default_payment_method : undefined;
-  await created(ctx, 'payment_intent', {
-    id: piId, amount: Number(inv.amount_due) || 0, currency: String(inv.currency ?? 'usd'), customer: inv.customer, invoice: invoiceId,
-    ...(defaultPaymentMethod ? { payment_method: defaultPaymentMethod } : {}),
-  }, {
-    status: defaultPaymentMethod ? 'requires_confirmation' : 'requires_payment_method',
-    client_secret: mintClientSecret(piId), livemode: false,
-    capture_method: 'automatic', amount_capturable: 0, amount_received: 0, next_action: null,
-    automatic_payment_methods: null, payment_method_types: ['card', 'link'], payment_method_options: {},
-  });
-}
-
-/** Whether leaving draft mints a PaymentIntent: only a charge_automatically invoice with a balance. */
-// "Finalizing an invoice does the following: ... It creates an incomplete payment intent for the invoice"
-// (docs.stripe.com/invoicing/integration/workflow-transitions), whichever its collection method
-const collectsThroughIntent = (inv: Row): boolean => inv.status === 'draft' && (Number(inv.amount_due) || 0) > 0;
-
-const transitions = (inv: Row): object => (inv.status_transitions as object) ?? {};
-
-/** What finalizing assigns: the invoice's `number`, the customer's invoice_prefix and a sequence
- *  (https://docs.stripe.com/api/invoices/object#invoice_object-number), and for send_invoice a
- *  `due_date` days_until_due after finalization (#invoice_object-due_date). */
-/** A customer's invoice_prefix, "The prefix for the customer used to generate unique invoice numbers"
- *  (docs.stripe.com/api/customers/object): the twin's, from the customer's id. */
-export const invoicePrefix = (customerId: string): string => customerId.replace(/[^a-z0-9]/gi, '').slice(-8).toUpperCase() || 'TWIN';
-
-export function finalizedFields(ctx: SemanticsContext, inv: Row, now: number): Row {
-  const customerId = typeof inv.customer === 'string' ? inv.customer : '';
-  const customer = customerId ? ctx.get('customer', customerId) : undefined;
-  const prefix = typeof customer?.invoice_prefix === 'string' && customer.invoice_prefix
-    ? customer.invoice_prefix
-    : invoicePrefix(customerId);
-  const numbered = ctx.rows(INV).filter((i) => i.customer === customerId && typeof i.number === 'string' && i.id !== inv.id).length;
-  const fields: Row = { number: typeof inv.number === 'string' && inv.number ? inv.number : `${prefix}-${String(numbered + 1).padStart(4, '0')}` };
-  const days = Number(inv.days_until_due);
-  if (inv.collection_method === 'send_invoice' && inv.due_date == null && Number.isFinite(days) && days > 0) fields.due_date = now + days * 86400;
-  return fields;
-}
-
-const finalize: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostInvoicesInvoiceFinalize');
-  if ('answer' in loaded) return loaded.answer;
-  const inv = loaded.inv;
-  const id = String(inv.id);
-  const piId = collectsThroughIntent(inv) ? ctx.mint('payment_intent') : null;
-  const body = await ctx.write(INV, id, { ...finalizedFields(ctx, inv, Number(ctx.now())), status: 'open', status_transitions: { ...transitions(inv), finalized_at: ctx.now() }, payment_intent: piId }, 'invoice.finalize');
-  // the customer's next_invoice_sequence, "The suffix of the customer's next invoice number" (docs.stripe.com/api/customers/object)
-  const customerId = typeof inv.customer === 'string' ? inv.customer : '';
-  if (customerId && ctx.get('customer', customerId)) await ctx.write('customer', customerId, { next_invoice_sequence: ctx.rows(INV).filter((i) => i.customer === customerId && typeof i.number === 'string').length + 1 }, 'customer.invoice_sequence');
-  if (piId) await openPaymentIntent(ctx, piId, inv, id);
-  // a subscription's invoice finalized spends the once coupon it took (renewals.ts spendOnceCoupon)
-  await spendOnceCoupon(ctx, inv);
-  return ctx.reply(expanded(ctx, INV, body));
-};
-
-// sending a draft finalizes it; any other invoice keeps its status and records the send
-const sendInvoice: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostInvoicesInvoiceSend');
-  if ('answer' in loaded) return loaded.answer;
-  const inv = loaded.inv;
-  const id = String(inv.id);
-  const becameOpen = inv.status === 'draft';
-  const piId = collectsThroughIntent(inv) ? ctx.mint('payment_intent') : null;
-  const now = ctx.now();
-  const body = await ctx.write(INV, id, {
-    status: becameOpen ? 'open' : (inv.status as string), _sent: true, _sent_at: now,
-    status_transitions: { ...transitions(inv), ...(becameOpen ? { finalized_at: now } : {}) },
-    ...(becameOpen ? { payment_intent: piId } : {}),
-  }, 'invoice.sent');
-  if (piId) await openPaymentIntent(ctx, piId, inv, id);
-  if (becameOpen) await spendOnceCoupon(ctx, inv);
-  return ctx.reply(expanded(ctx, INV, body));
-};
-
-// paying charges a payment method (the one passed, the invoice's default, or the customer's) unless
-// the payment is recorded out of band; a declining card answers 402 and leaves the invoice open. A
-// paid invoice settles the PaymentIntent finalize opened, and names the charge that took the money.
-const pay: Semantics = async (ctx) => {
-  const id = at(ctx, 'invoice');
-  const inv = ctx.get(INV, id);
-  if (!inv) return invoiceMissing(ctx, id);
-  const refused = ctx.legal(INV, 'status', 'PostInvoicesInvoicePay', inv.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  const params = ctx.params;
-  const paidOutOfBand = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
-  const payer = ctx.get('customer', String(inv.customer ?? ''));
-  const customerDefault = (payer?.invoice_settings as Row | undefined)?.default_payment_method || payer?.default_source;
-  if (!paidOutOfBand && !params.payment_method && !params.source && !inv.default_payment_method && !inv.default_source && !customerDefault) return nothingToPayWith(ctx);
-  // what it charges: the method passed, else the invoice's default, its subscription's, then its customer's
-  // (docs.stripe.com/api/invoices/pay#pay_invoice-payment_method)
-  const subscription = typeof inv.subscription === 'string' ? ctx.get('subscription', inv.subscription) : undefined;
-  const decline = declineFor(finder(ctx), params, { payment_method: inv.default_payment_method ?? subscription?.default_payment_method ?? customerDefault });
-  const intent = typeof inv.payment_intent === 'string' ? ctx.get('payment_intent', inv.payment_intent) : undefined;
-  if (decline) return send(ctx, cardError(decline, intent ? { payment_intent: intent } : {}));
-  const amountPaid = Number(inv.total ?? inv.amount_due) || 0;
-  let body = await ctx.write(INV, id, {
-    // paid outside Stripe, the invoice counts it as such: `amount_paid_off_stripe`, "Amount, in cents (or local
-    // equivalent), that was paid on the invoice outside of Stripe" (served spec, invoice), the only place the served
-    // version shows it now that basil renders no `paid_out_of_band` (stripe-version.ts)
-    status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
-    ...(paidOutOfBand ? { amount_paid_off_stripe: amountPaid } : {}),
-    status_transitions: { ...transitions(inv), paid_at: ctx.now() },
-  }, 'invoice.pay');
-  if (!paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {
-    const pi = ctx.get('payment_intent', inv.payment_intent);
-    if (pi && pi.status !== 'succeeded' && !ctx.legal('payment_intent', 'status', 'PostInvoicesInvoicePay', pi.status)) {
-      const chargeId = await mintCharge(ctx, inv.payment_intent, { ...pi, invoice: id, ...(typeof params.payment_method === 'string' ? { payment_method: params.payment_method } : {}) }, amountPaid);
-      await ctx.write('payment_intent', inv.payment_intent, { status: 'succeeded', amount_received: amountPaid, amount_capturable: 0, next_action: null, latest_charge: chargeId }, 'payment_intent.succeeded');
-      body = await ctx.write(INV, id, { charge: chargeId }, 'invoice.update');
-    }
-  }
-  // a subscription waiting on this invoice (incomplete on its first, past_due on a failed renewal) is active once it is paid
-  const subId = typeof inv.subscription === 'string' ? inv.subscription : undefined;
-  const sub = subId ? ctx.get('subscription', subId) : undefined;
-  if (subId && sub && (sub.status === 'incomplete' || sub.status === 'past_due') && !ctx.legal('subscription', 'status', 'PostInvoicesInvoicePay', sub.status, 'active', subId)) await activatedByPayment(ctx, subId);
-  return ctx.reply(expanded(ctx, INV, body));
-};
-
-// only a draft is deleted; a finalized invoice is voided instead
-const deleteDraft: Semantics = async (ctx) => {
-  const id = at(ctx, 'invoice');
-  const inv = ctx.get(INV, id);
-  if (!inv) return invoiceMissing(ctx, id);
-  if (inv.status !== 'draft') return fail(ctx, 'You can only delete draft invoices.', 400, 'invoice_not_editable');
-  await ctx.write(INV, id, { deleted: true }, 'invoice.deleted');
-  return ctx.reply({ id, object: 'invoice', deleted: true });
-};
-
-const markUncollectible: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostInvoicesInvoiceMarkUncollectible');
-  if ('answer' in loaded) return loaded.answer;
-  const inv = loaded.inv;
-  const body = await ctx.write(INV, String(inv.id), { status: 'uncollectible', status_transitions: { ...transitions(inv), marked_uncollectible_at: ctx.now() } }, 'invoice.marked_uncollectible');
-  return ctx.reply(expanded(ctx, INV, body));
-};
-
-const voidInvoice: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostInvoicesInvoiceVoid');
-  if ('answer' in loaded) return loaded.answer;
-  const inv = loaded.inv;
-  const body = await ctx.write(INV, String(inv.id), { status: 'void', status_transitions: { ...transitions(inv), voided_at: ctx.now() } }, 'invoice.void');
-  return ctx.reply(expanded(ctx, INV, body));
-};
-
-// the invoice's lines, a page at a time
-const lines: Semantics = async (ctx) => {
-  const id = at(ctx, 'invoice');
-  const inv = ctx.get(INV, id);
-  if (!inv) return invoiceMissing(ctx, id);
-  const { page, hasMore } = paginate(linesOf(inv), ctx.params);
-  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page.map((l) => ({ invoice: id, ...l })) });
-};
-
-// add_lines, update_lines and remove_lines edit a draft's lines in bulk and re-derive its totals
-function editLines(kind: 'add' | 'update' | 'remove'): Semantics {
-  return async (ctx) => {
-    const id = at(ctx, 'invoice');
-    const inv = ctx.get(INV, id);
-    if (!inv) return invoiceMissing(ctx, id);
-    if (inv.status !== 'draft') return fail(ctx, `You can only add/update/remove lines on a draft invoice (this one is ${String(inv.status)}).`, 400, 'invoice_not_editable');
-    const cur = linesOf(inv);
-    let next = [...cur];
-    const raw = ctx.params.lines;
-    const entries = Array.isArray(raw) ? (raw as Row[]) : raw && typeof raw === 'object' ? [raw as Row] : [];
-    if (entries.length === 0) return fail(ctx, 'Missing required param: lines.', 400, 'parameter_missing');
-    const currency = String(inv.currency ?? 'usd');
-    if (kind === 'add') {
-      for (let i = 0; i < entries.length; i++) {
-        const e = entries[i]!;
-        const priceRef = typeof e.price === 'string' ? e.price : '';
-        const price = priceRef ? ctx.get('price', priceRef) : undefined;
-        if (priceRef && !price) return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
-        const quantity = e.quantity !== undefined ? Math.max(1, Math.trunc(Number(e.quantity) || 1)) : 1;
-        const unit = Math.trunc(Number(e.amount) || 0);
-        next.push({ id: `il_twin_${id}_${cur.length + i + 1}`, object: 'line_item', amount: price ? priceAmount(price, quantity) : unit, currency, quantity, price: price ?? (priceRef || null), description: typeof e.description === 'string' ? e.description : null, proration: false });
-      }
-    } else if (kind === 'update') {
-      for (const e of entries) {
-        const lid = typeof e.id === 'string' ? e.id : '';
-        next = next.map((l) => (l.id === lid ? { ...l, ...(e.amount !== undefined ? { amount: Math.trunc(Number(e.amount) || 0) } : {}), ...(e.quantity !== undefined ? { quantity: Math.max(1, Math.trunc(Number(e.quantity) || 1)) } : {}), ...(e.description !== undefined ? { description: e.description } : {}) } : l));
-      }
-    } else {
-      const remove = new Set(entries.map((e) => (typeof e.id === 'string' ? e.id : '')).filter(Boolean));
-      next = next.filter((l) => !remove.has(String(l.id)));
-    }
-    return ctx.reply(await writeLines(ctx, id, next));
-  };
 }
 
-const searchInvoices: Semantics = async (ctx) => search(ctx, INV);
-
-const retrieve: Semantics = async (ctx) => {
-  const id = at(ctx, 'invoice');
-  const inv = ctx.get(INV, id);
-  return inv ? ctx.reply(expanded(ctx, INV, inv)) : invoiceMissing(ctx, id);
-};
-
 /**
  * A preview of the next invoice for a customer or subscription (create_preview), computed and never
  * stored: the subscription's items at their prices, the customer's pending items, the subscription's
  * discount, and with `subscription_details.proration_date` a credit for the unused period against a
  * charge for the new one (split evenly: there is no clock here to measure the remaining fraction).
  */
-const createPreview: Semantics = async (ctx) => {
+export async function PostInvoicesCreatePreview(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
   const prorationDate = (params.subscription_details as Row | undefined)?.proration_date;
-  const now = Number(ctx.now());
+  const now = Number(nowUnix(ctx.occurredAt));
   let subId = typeof params.subscription === 'string' ? params.subscription : '';
   let customer = typeof params.customer === 'string' ? params.customer : '';
   let sub: Row | undefined;
@@ -486,60 +124,88 @@ const createPreview: Semantics = async (ctx) => {
     total_discount_amounts: discountAmount > 0 ? [{ amount: discountAmount, discount: subDiscount?.id ?? null }] : [],
     lines: { object: 'list', url: '/v1/invoices/create_preview/lines', has_more: false, total_count: out.length, data: out },
   });
-};
+}
 
-/** An invoice's payment as Stripe answers it (docs.stripe.com/api/invoice-payment/object): the PaymentIntent that
- *  collects the invoice, open until the invoice is paid. Where the documentation stops and the twin decides: an
- *  invoice has one payment, its default, and the payment's id is the invoice's with `inpay_`. */
-function invoicePayment(inv: Row): Row | undefined {
-  if (typeof inv.payment_intent !== 'string') return undefined;
-  const paid = inv.status === 'paid';
-  const transitions = (inv.status_transitions as Row | undefined) ?? {};
-  return {
-    id: `inpay_${String(inv.id).replace(/^in_/, '')}`, object: 'invoice_payment', invoice: inv.id, is_default: true, livemode: false,
-    amount_requested: Number(inv.amount_due ?? 0), amount_paid: paid ? Number(inv.amount_paid ?? inv.amount_due ?? 0) : null, currency: inv.currency,
-    created: inv.created, payment: { type: 'payment_intent', payment_intent: inv.payment_intent },
-    status: paid ? 'paid' : inv.status === 'void' ? 'canceled' : 'open',
-    status_transitions: { paid_at: paid ? (transitions.paid_at ?? null) : null, canceled_at: inv.status === 'void' ? (transitions.voided_at ?? null) : null },
-  };
+export async function PostInvoicesInvoiceFinalize(ctx: HandlerContext): Promise<Response> {
+  const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceFinalize');
+  if ('answer' in loaded) return loaded.answer;
+  const inv = loaded.inv;
+  const id = String(inv.id);
+  const piId = collectsThroughIntent(inv) ? ctx.mint('payment_intent') : null;
+  const body = await ctx.write(INV, id, { ...finalizedFields(ctx, inv, Number(nowUnix(ctx.occurredAt))), status: 'open', status_transitions: { ...transitions(inv), finalized_at: nowUnix(ctx.occurredAt) }, payment_intent: piId }, 'invoice.finalize');
+  if (piId) await openPaymentIntent(ctx, piId, inv, id);
+  // a subscription's invoice finalized spends the once coupon it took (renewals.ts spendOnceCoupon)
+  await spendOnceCoupon(ctx, inv);
+  return ctx.reply(expanded(ctx, INV, body));
 }
 
-const invoicePayments: Semantics = async (ctx) => {
-  const p = ctx.params;
-  const wanted = (p.payment as Row | undefined)?.payment_intent;
-  const items = newest(ctx, INV)
-    .filter((inv) => typeof p.invoice !== 'string' || inv.id === p.invoice)
-    .map(invoicePayment).filter((x): x is Row => !!x)
-    .filter((x) => typeof wanted !== 'string' || (x.payment as Row).payment_intent === wanted)
-    .filter((x) => typeof p.status !== 'string' || x.status === p.status);
-  return list(ctx, 'invoice_payment', items);
-};
+// paying charges a payment method (the one passed, the invoice's default, or the customer's) unless
+// the payment is recorded out of band; a declining card answers 402 and leaves the invoice open. A
+// paid invoice settles the PaymentIntent finalize opened, and names the charge that took the money.
+export async function PostInvoicesInvoicePay(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'invoice');
+  const inv = ctx.get(INV, id);
+  if (!inv) return invoiceMissing(ctx, id);
+  const refused = ctx.legal(INV, 'status', 'PostInvoicesInvoicePay', inv.status, undefined, id);
+  if (refused) return ctx.refuse(refused);
+  const params = ctx.params;
+  const paidOutOfBand = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
+  const payer = ctx.get('customer', String(inv.customer ?? ''));
+  const customerDefault = (payer?.invoice_settings as Row | undefined)?.default_payment_method || payer?.default_source;
+  if (!paidOutOfBand && !params.payment_method && !params.source && !inv.default_payment_method && !inv.default_source && !customerDefault) return nothingToPayWith(ctx);
+  // what it charges: the method passed, else the invoice's default, its subscription's, then its customer's
+  // (docs.stripe.com/api/invoices/pay#pay_invoice-payment_method)
+  const subscription = typeof inv.subscription === 'string' ? ctx.get('subscription', inv.subscription) : undefined;
+  const decline = declineFor(finder(ctx), params, { payment_method: inv.default_payment_method ?? subscription?.default_payment_method ?? customerDefault });
+  const intent = typeof inv.payment_intent === 'string' ? ctx.get('payment_intent', inv.payment_intent) : undefined;
+  if (decline) return send(ctx, cardError(decline, intent ? { payment_intent: intent } : {}));
+  const amountPaid = Number(inv.total ?? inv.amount_due) || 0;
+  let body = await ctx.write(INV, id, {
+    // paid outside Stripe, the invoice counts it as such: `amount_paid_off_stripe`, "Amount, in cents (or local
+    // equivalent), that was paid on the invoice outside of Stripe" (served spec, invoice), the only place the served
+    // version shows it now that basil renders no `paid_out_of_band` (../engine/version.ts)
+    status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
+    ...(paidOutOfBand ? { amount_paid_off_stripe: amountPaid } : {}),
+    status_transitions: { ...transitions(inv), paid_at: nowUnix(ctx.occurredAt) },
+  }, 'invoice.pay');
+  if (!paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {
+    const pi = ctx.get('payment_intent', inv.payment_intent);
+    if (pi && pi.status !== 'succeeded' && !ctx.legal('payment_intent', 'status', 'PostInvoicesInvoicePay', pi.status)) {
+      const chargeId = await mintCharge(ctx, inv.payment_intent, { ...pi, invoice: id, ...(typeof params.payment_method === 'string' ? { payment_method: params.payment_method } : {}) }, amountPaid);
+      await ctx.write('payment_intent', inv.payment_intent, { status: 'succeeded', amount_received: amountPaid, amount_capturable: 0, next_action: null, latest_charge: chargeId }, 'payment_intent.succeeded');
+      body = await ctx.write(INV, id, { charge: chargeId }, 'invoice.update');
+    }
+  }
+  // a subscription waiting on this invoice (incomplete on its first, past_due on a failed renewal) is active once it is paid
+  const subId = typeof inv.subscription === 'string' ? inv.subscription : undefined;
+  const sub = subId ? ctx.get('subscription', subId) : undefined;
+  if (subId && sub && (sub.status === 'incomplete' || sub.status === 'past_due') && !ctx.legal('subscription', 'status', 'PostInvoicesInvoicePay', sub.status, 'active', subId)) await activatedByPayment(ctx, subId);
+  return ctx.reply(expanded(ctx, INV, body));
+}
 
-const invoicePaymentOne: Semantics = async (ctx) => {
-  const id = at(ctx, 'invoice_payment');
-  const found = newest(ctx, INV).map(invoicePayment).find((x) => x?.id === id);
-  return found ? ctx.reply(found) : fail(ctx, `No such invoice payment: '${id}'`, 404, 'resource_missing');
-};
+// sending a draft finalizes it; any other invoice keeps its status and records the send
+export async function PostInvoicesInvoiceSend(ctx: HandlerContext): Promise<Response> {
+  const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceSend');
+  if ('answer' in loaded) return loaded.answer;
+  const inv = loaded.inv;
+  const id = String(inv.id);
+  const becameOpen = inv.status === 'draft';
+  const piId = collectsThroughIntent(inv) ? ctx.mint('payment_intent') : null;
+  const now = nowUnix(ctx.occurredAt);
+  const body = await ctx.write(INV, id, {
+    status: becameOpen ? 'open' : (inv.status as string), _sent: true, _sent_at: now,
+    status_transitions: { ...transitions(inv), ...(becameOpen ? { finalized_at: now } : {}) },
+    ...(becameOpen ? { payment_intent: piId } : {}),
+  }, 'invoice.sent');
+  if (piId) await openPaymentIntent(ctx, piId, inv, id);
+  if (becameOpen) await spendOnceCoupon(ctx, inv);
+  return ctx.reply(expanded(ctx, INV, body));
+}
 
-export const invoices: Record<string, Semantics> = {
-  GetInvoicePayments: invoicePayments,
-  GetInvoicePaymentsInvoicePayment: invoicePaymentOne,
-  PostInvoiceitems: createItem,
-  GetInvoiceitemsInvoiceitem: retrieveItem,
-  PostInvoiceitemsInvoiceitem: updateItem,
-  DeleteInvoiceitemsInvoiceitem: deleteItem,
-  PostInvoices: create,
-  PostInvoicesCreatePreview: createPreview,
-  PostInvoicesInvoiceFinalize: finalize,
-  PostInvoicesInvoiceSend: sendInvoice,
-  PostInvoicesInvoicePay: pay,
-  PostInvoicesInvoiceMarkUncollectible: markUncollectible,
-  PostInvoicesInvoiceVoid: voidInvoice,
-  DeleteInvoicesInvoice: deleteDraft,
-  GetInvoicesInvoiceLines: lines,
-  PostInvoicesInvoiceAddLines: editLines('add'),
-  PostInvoicesInvoiceUpdateLines: editLines('update'),
-  PostInvoicesInvoiceRemoveLines: editLines('remove'),
-  GetInvoicesSearch: searchInvoices,
-  GetInvoicesInvoice: retrieve,
-};
+export async function PostInvoicesInvoiceVoid(ctx: HandlerContext): Promise<Response> {
+  const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceVoid');
+  if ('answer' in loaded) return loaded.answer;
+  const inv = loaded.inv;
+  const body = await ctx.write(INV, String(inv.id), { status: 'void', status_transitions: { ...transitions(inv), voided_at: nowUnix(ctx.occurredAt) } }, 'invoice.void');
+  return ctx.reply(expanded(ctx, INV, body));
+}