@volter/twin-stripe 2.0.38 → 3.0.1

package/src/semantics/invoices.ts

@@ -1,306 +1,31 @@
-// 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 } {
+// 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 { INV, transitions } from '../engine/invoices.ts';
+import { asBool, cardError, declineFor, nowUnix } from '../engine/stripe.ts';
+import { resourceView, activatedByPayment, at, expanded, finalizeForPayment, finder, invoiceMissing, invoicesLoad, mintCharge, nothingToPayWith, send } from './shared.ts';
+import { draft, prorationLines, sumLines } from '../engine/invoices.ts';
+import { addBillingInterval, applyCouponDiscount, priceAmount } from '../engine/stripe.ts';
+import { created, fail, newest, pendingPreviewLines, pullPendingItem } from './shared.ts';
+export async function GetInvoicesInvoice(ctx: HandlerContext): Promise<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;
+  return inv ? ctx.reply(expanded(ctx, INV, inv)) : invoiceMissing(ctx, id);
 }
 
-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) => {
+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);
+  const found = ctx.get(INV, id);
+  if (!found) return invoiceMissing(ctx, id);
+  const refused = ctx.legal(INV, 'status', 'PostInvoicesInvoicePay', found.status, undefined, id);
   if (refused) return ctx.refuse(refused);
+  // paying a draft finalizes it first, as its finalize does (its number, and the PaymentIntent it collects through)
+  // source: https://docs.stripe.com/invoicing/integration "To finalize a draft invoice, use the Dashboard, send it to the customer, or pay it."
+  const inv = found.status === 'draft' ? await finalizeForPayment(ctx, found, id) : found;
   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 ?? ''));
@@ -308,7 +33,7 @@ const pay: Semantics = async (ctx) => {
   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 subscription = typeof inv.subscription === 'string' ? resourceView(ctx, '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 } : {}));
@@ -316,10 +41,10 @@ const pay: Semantics = async (ctx) => {
   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)
+    // 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: ctx.now() },
+    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);
@@ -331,105 +56,63 @@ const pay: Semantics = async (ctx) => {
   }
   // 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;
+  const sub = subId ? resourceView(ctx, '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));
-};
+  return ctx.reply(expanded(ctx, INV, ctx.get(INV, id) ?? 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 });
-};
+// sending a draft finalizes it; any other invoice keeps its status and records the send
 
-const markUncollectible: Semantics = async (ctx) => {
-  const loaded = load(ctx, 'PostInvoicesInvoiceMarkUncollectible');
+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: 'uncollectible', status_transitions: { ...transitions(inv), marked_uncollectible_at: ctx.now() } }, 'invoice.marked_uncollectible');
+  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));
-};
+}
+
 
-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));
-  };
+// 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)
+export async function PostInvoices(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  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
+  // 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);
 }
 
-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).
+ * discount, and an update's unused-time credit and remaining-time charge at the old and new prices.
  */
-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;
   if (subId) {
-    sub = ctx.get('subscription', subId);
+    sub = resourceView(ctx, 'subscription', subId);
     if (!sub) return fail(ctx, `No such subscription: '${subId}'`, 404, 'resource_missing');
     customer = customer || String(sub.customer ?? '');
   } else if (customer) {
@@ -443,17 +126,48 @@ const createPreview: Semantics = async (ctx) => {
   // 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) : [];
+  let itemRows = sub ? ctx.rows('subscription_item').filter((r) => r.subscription === subId) : [];
+  const details = params.subscription_details as Row | undefined;
+  const previousItems = itemRows;
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "The default value is"
+  const behavior = details?.proration_behavior ?? 'create_prorations';
+  // source: https://docs.stripe.com/billing/subscriptions/prorations "The prorated amount is calculated as soon as the API updates the subscription."
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "forces the proration to be calculated as though the update was done at the specified time."
+  const prorationTime = details?.proration_date === undefined ? now : Number(details.proration_date);
+  const periodStart = Number(sub?.current_period_start ?? now);
+  const periodEnd = Number(sub?.current_period_end ?? now);
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "The time given must be within the current subscription period"
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "cannot be set to"
+  if (details?.proration_date !== undefined && (behavior === 'none' || !sub || !Array.isArray(details.items) || prorationTime < periodStart || prorationTime > periodEnd)) return fail(ctx, 'Invalid subscription_details[proration_date] for this subscription preview.', 400, 'parameter_invalid_integer');
+  // source: spec:/paths/~1v1~1invoices~1create_preview/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/subscription_details/description "The subscription creation or modification params to apply as a preview."
+  // Preview changes are local to this calculation: the subscription and its stored items are never changed.
+  if (Array.isArray(details?.items)) {
+    itemRows = itemRows.map(item => ({ ...item }));
+    for (const change of details.items as Row[]) {
+      const index = change.id ? itemRows.findIndex(item => item.id === change.id) : -1;
+      if (change.id && index < 0) return fail(ctx, `No such subscription_item: '${change.id}'`, 400, 'resource_missing');
+      if (asBool(change.deleted)) { if (index >= 0) itemRows.splice(index, 1); continue; }
+      const previous = index >= 0 ? itemRows[index]! : {};
+      const priceId = typeof change.price === 'string' ? change.price : typeof previous.price === 'string' ? previous.price : (previous.price as Row | undefined)?.id;
+      const price = typeof priceId === 'string' ? ctx.get('price', priceId) : undefined;
+      if (!price) return fail(ctx, `No such price: '${priceId ?? ''}'`, 400, 'resource_missing');
+      const quantity = change.quantity === undefined ? Number(previous.quantity ?? 1) : Number(change.quantity);
+      const previewItem = { ...previous, price, quantity };
+      if (index >= 0) itemRows[index] = previewItem; else itemRows.push(previewItem);
+    }
+  }
   const out: Row[] = [];
   let subtotal = 0;
   let period = now + 30 * 24 * 3600;
   if (sub) {
-    for (const { price: priceId, quantity } of subscriptionItemPairs(sub)) {
+    for (const previewItem of itemRows) {
+      const priceId = typeof previewItem.price === 'string' ? previewItem.price : String((previewItem.price as Row | undefined)?.id ?? '');
+      const quantity = Number(previewItem.quantity) || 0;
       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);
+      const item = previewItem;
       subtotal += amount;
       out.push({
         id: `il_twin_${priceId}`, object: 'line_item', type: 'subscription', amount, currency,
@@ -461,17 +175,30 @@ const createPreview: Semantics = async (ctx) => {
         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);
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "Disable creating prorations in this request."
+  // source: https://docs.stripe.com/billing/subscriptions/prorations "creates a non-proration debit, even when the debit covers a partial billing period."
+  if (sub && Array.isArray(details?.items) && behavior !== 'none' && sub.status !== 'trialing') {
+    const before = previousItems.map(item => {
+      const priceId = typeof item.price === 'string' ? item.price : String((item.price as Row).id);
+      const price = ctx.get('price', priceId);
+      return { id: `il_twin_${priceId}`, object: 'line_item', type: 'subscription', amount: priceAmount(price, Number(item.quantity ?? 1)), currency,
+        price: price ?? priceId, quantity: Number(item.quantity ?? 1), subscription: subId, subscription_item: item.id,
+        period: { start: item.current_period_start ?? periodStart, end: item.current_period_end ?? periodEnd } };
+    });
+    const after = out.map(line => ({ ...line, period: { start: periodStart, end: periodEnd } }));
+    const prorations = prorationLines(before, after, prorationTime, periodStart, periodEnd, coupon);
+    // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "Always invoice immediately for prorations."
+    if (behavior === 'always_invoice' && prorations.length) out.splice(0, out.length, ...prorations);
+    else out.unshift(...prorations);
+  }
+  out.push(...pendingPreviewLines(ctx, customer, currency, now));
+  subtotal = sumLines(out);
+  // source: https://docs.stripe.com/billing/subscriptions/prorations "no additional discounts are applied to the proration line items themselves"
+  const discountAmount = applyCouponDiscount(Math.max(0, sumLines(out.filter(line => !line.proration))), coupon);
+  const total = subtotal - discountAmount;
   return ctx.reply({
     ...draft(now),
     // "For preview invoices created using the create preview endpoint, this id will be prefixed with `upcoming_in`"
@@ -480,66 +207,10 @@ const createPreview: Semantics = async (ctx) => {
     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,
+    subtotal, total, amount_due: Math.max(0, total), amount_paid: 0, amount_remaining: Math.max(0, 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,
-};