@volter/twin-stripe 0.1.1 → 2.0.0

package/src/semantics/invoices.ts

@@ -0,0 +1,541 @@
+// 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';
+
+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)' });
+}
+
+/** 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);
+}
+
+// ── 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 };
+}
+
+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) => {
+  const params = ctx.params;
+  const now = Number(ctx.now());
+  // 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
+  // email and name are its own "Until the invoice is finalized, this field will equal customer.email" (served spec,
+  // invoice.customer_email; .customer_name likewise)
+  const days = Number(params.days_until_due);
+  const due = params.collection_method === 'send_invoice' && params.due_date === undefined && Number.isFinite(days) && days > 0 ? { due_date: now + days * 86_400 } : {};
+  const holder = typeof params.customer === 'string' ? ctx.get('customer', params.customer) : undefined;
+  const snapshot = holder ? { customer_email: holder.email ?? null, customer_name: holder.name ?? null } : {};
+  const inv = await created(ctx, INV, { ...params, id: newId }, { ...draft(now), ...due, ...snapshot, lines: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/invoices/${newId}/lines` } });
+  if (params.pending_invoice_items_behavior !== 'include') return ctx.reply(inv);
+  const invoiceId = String(inv.id);
+  const customerId = typeof inv.customer === 'string' ? inv.customer : '';
+  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, {
+    status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
+    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) => {
+  const params = ctx.params;
+  const prorationDate = (params.subscription_details as Row | undefined)?.proration_date;
+  const now = Number(ctx.now());
+  let subId = typeof params.subscription === 'string' ? params.subscription : '';
+  let customer = typeof params.customer === 'string' ? params.customer : '';
+  let sub: Row | undefined;
+  if (subId) {
+    sub = ctx.get('subscription', subId);
+    if (!sub) return fail(ctx, `No such subscription: '${subId}'`, 404, 'resource_missing');
+    customer = customer || String(sub.customer ?? '');
+  } else if (customer) {
+    // no subscription named: the customer's first live one
+    sub = newest(ctx, 'subscription').find((s) => s.customer === customer && s.status !== 'canceled');
+    subId = sub ? String(sub.id) : '';
+  }
+  if (!customer) return fail(ctx, 'Missing required param: customer (or subscription).', 400, 'parameter_missing');
+  if (!ctx.get('customer', customer)) return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
+  const currency = String((sub?.currency as string) ?? 'usd');
+  // the upcoming invoice bills the subscription's next period, its "subscription renewal charges"
+  // (docs.stripe.com/api/invoices/create_preview): from the current period's end, one billing interval long
+  const renewsAt = sub && Number(sub.current_period_end) > 0 ? Number(sub.current_period_end) : now;
+  const itemRows = sub ? ctx.rows('subscription_item').filter((r) => r.subscription === subId) : [];
+  const out: Row[] = [];
+  let subtotal = 0;
+  let period = now + 30 * 24 * 3600;
+  if (sub) {
+    for (const { price: priceId, quantity } of subscriptionItemPairs(sub)) {
+      const price = ctx.get('price', priceId);
+      const amount = priceAmount(price, quantity);
+      const recurring = (price?.recurring as Row | undefined) ?? {};
+      period = recurring.interval ? addBillingInterval(renewsAt, recurring.interval as Parameters<typeof addBillingInterval>[1], Number(recurring.interval_count) || 1) : period;
+      const item = itemRows.find((r) => (typeof r.price === 'string' ? r.price : (r.price as Row | undefined)?.id) === priceId);
+      subtotal += amount;
+      out.push({
+        id: `il_twin_${priceId}`, object: 'line_item', type: 'subscription', amount, currency,
+        quantity, proration: false, price: price ?? priceId, subscription: subId || null, subscription_item: item?.id ?? null,
+        period: { start: renewsAt, end: period }, description: `${quantity} × ${(price?.nickname as string) ?? priceId}`,
+      });
+    }
+    if (prorationDate !== undefined && subtotal > 0) prorationLines(out, subtotal, currency, now, period);
+  }
+  for (const ii of newest(ctx, 'invoiceitem', 'date')) {
+    if (ii.customer !== customer || ii.invoice) continue;
+    out.push({ id: `il_${String(ii.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(ii.amount) || 0, currency, quantity: Number(ii.quantity) || 1, proration: false, invoice_item: ii.id, period: ii.period ?? { start: now, end: now }, description: (ii.description as string) ?? null });
+  }
+  subtotal = sumLines(out);
+  const subDiscount = Array.isArray(sub?.discounts) && sub!.discounts.length ? (sub!.discounts as Row[])[0] : undefined;
+  const coupon = subDiscount && typeof subDiscount.coupon === 'object' ? (subDiscount.coupon as Row) : undefined;
+  const discountAmount = applyCouponDiscount(Math.max(0, subtotal), coupon);
+  const total = Math.max(0, subtotal - discountAmount);
+  return ctx.reply({
+    ...draft(now),
+    // "For preview invoices created using the create preview endpoint, this id will be prefixed with `upcoming_in`"
+    // (served spec, invoice.id; the create preview page's example answers "upcoming_in_1MtHbELkdIwHu7ixl4OzzPMv"). Where
+    // the documentation stops and the twin decides: the rest of the id is a fresh invoice id's, minted for the preview.
+    object: 'invoice', id: `upcoming_${ctx.mint(INV)}`, customer, subscription: subId || null, currency,
+    billing_reason: subId ? 'upcoming' : 'manual',
+    created: now, period_start: now, period_end: period,
+    subtotal, total, amount_due: total, amount_paid: 0, amount_remaining: total,
+    starting_balance: 0, ending_balance: null,
+    discounts: discountAmount > 0 && subDiscount ? [subDiscount] : [],
+    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 },
+  };
+}
+
+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);
+};
+
+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');
+};
+
+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,
+};