@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/semantics/invoices.js

@@ -1,297 +1,28 @@
-import { addBillingInterval, applyCouponDiscount, asBool, cardError, declineFor, mintClientSecret, paginate, priceAmount, subscriptionItemPairs } from "../stripe-twin.js";
-import { mintCharge } from "./payment-intents.js";
-import { spendOnceCoupon } from "./renewals.js";
-import { at, created, expanded, fail, finder, list, newest, path, search, send } from "./shared.js";
-const INV = 'invoice';
-const invoiceMissing = (ctx, id) => fail(ctx, `No such invoice: '${id}'`, 404, 'resource_missing');
-const linesOf = (inv) => inv.lines?.data ?? [];
-const sumLines = (lines) => 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, invoiceId, next) {
-    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) {
-    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, subId) {
-    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) {
-    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, subtotal, currency, now, period) {
-    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, invoiceId) {
-    const inv = ctx.get(INV, invoiceId);
-    if (!inv || inv.status !== 'draft')
-        return;
-    const next = [];
-    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 ?? 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, priceRef, qty) {
-    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 = 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?.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;
-    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 ?? null,
-            }]);
-    }
-    return ctx.reply(item);
-};
-const itemMissing = (ctx, id) => fail(ctx, `No such invoiceitem: '${id}'`, 404, 'resource_missing');
-const retrieveItem = async (ctx) => {
-    const it = ctx.get('invoiceitem', at(ctx, 'invoiceitem'));
-    return it ? ctx.reply(it) : itemMissing(ctx, at(ctx, 'invoiceitem'));
-};
-const updateItem = 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 = 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) => ({
-    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 = 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, customer, currency, parent, lines) {
-    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.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, invoiceId, inv, item, now) {
-    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 ?? 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, operationId) {
+import { INV, transitions } from "../engine/invoices.js";
+import { asBool, cardError, declineFor, nowUnix } from "../engine/stripe.js";
+import { resourceView, activatedByPayment, at, expanded, finalizeForPayment, finder, invoiceMissing, invoicesLoad, mintCharge, nothingToPayWith, send } from "./shared.js";
+import { draft, prorationLines, sumLines } from "../engine/invoices.js";
+import { addBillingInterval, applyCouponDiscount, priceAmount } from "../engine/stripe.js";
+import { created, fail, newest, pendingPreviewLines, pullPendingItem } from "./shared.js";
+export async function GetInvoicesInvoice(ctx) {
     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, piId, inv, invoiceId) {
-    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) => inv.status === 'draft' && (Number(inv.amount_due) || 0) > 0;
-const transitions = (inv) => inv.status_transitions ?? {};
-/** 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) => customerId.replace(/[^a-z0-9]/gi, '').slice(-8).toUpperCase() || 'TWIN';
-export function finalizedFields(ctx, inv, now) {
-    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 = { 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 = 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 = 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, _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 = async (ctx) => {
+export async function PostInvoicesInvoicePay(ctx) {
     const id = at(ctx, 'invoice');
-    const inv = ctx.get(INV, id);
-    if (!inv)
+    const found = ctx.get(INV, id);
+    if (!found)
         return invoiceMissing(ctx, id);
-    const refused = ctx.legal(INV, 'status', 'PostInvoicesInvoicePay', inv.status, undefined, 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 ?? ''));
@@ -300,7 +31,7 @@ const pay = async (ctx) => {
         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)
@@ -309,10 +40,10 @@ const pay = 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);
@@ -324,109 +55,58 @@ const pay = 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));
-};
-// only a draft is deleted; a finalized invoice is voided instead
-const deleteDraft = 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 = 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 = async (ctx) => {
-    const loaded = load(ctx, 'PostInvoicesInvoiceVoid');
+    return ctx.reply(expanded(ctx, INV, ctx.get(INV, id) ?? body));
+}
+// sending a draft finalizes it; any other invoice keeps its status and records the send
+export async function PostInvoicesInvoiceVoid(ctx) {
+    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: ctx.now() } }, 'invoice.void');
+    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));
-};
+}
 // the invoice's lines, a page at a time
-const lines = 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) {
-    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 : raw && typeof raw === 'object' ? [raw] : [];
-        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) {
+    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 = async (ctx) => search(ctx, INV);
-const retrieve = 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 = async (ctx) => {
+export async function PostInvoicesCreatePreview(ctx) {
     const params = ctx.params;
-    const prorationDate = params.subscription_details?.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;
     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 ?? '');
@@ -444,17 +124,58 @@ const createPreview = 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;
+    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) {
+            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?.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 = [];
     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?.id ?? '');
+            const quantity = Number(previewItem.quantity) || 0;
             const price = ctx.get('price', priceId);
             const amount = priceAmount(price, quantity);
             const recurring = price?.recurring ?? {};
             period = recurring.interval ? addBillingInterval(renewsAt, recurring.interval, Number(recurring.interval_count) || 1) : period;
-            const item = itemRows.find((r) => (typeof r.price === 'string' ? r.price : r.price?.id) === priceId);
+            const item = previewItem;
             subtotal += amount;
             out.push({
                 id: `il_twin_${priceId}`, object: 'line_item', type: 'subscription', amount, currency,
@@ -462,19 +183,32 @@ const createPreview = async (ctx) => {
                 period: { start: renewsAt, end: period }, description: `${quantity} × ${price?.nickname ?? 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 ?? null });
     }
-    subtotal = sumLines(out);
     const subDiscount = Array.isArray(sub?.discounts) && sub.discounts.length ? sub.discounts[0] : undefined;
     const coupon = subDiscount && typeof subDiscount.coupon === 'object' ? subDiscount.coupon : 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.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`"
@@ -483,63 +217,10 @@ const createPreview = 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) {
-    if (typeof inv.payment_intent !== 'string')
-        return undefined;
-    const paid = inv.status === 'paid';
-    const transitions = inv.status_transitions ?? {};
-    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 = async (ctx) => {
-    const p = ctx.params;
-    const wanted = p.payment?.payment_intent;
-    const items = newest(ctx, INV)
-        .filter((inv) => typeof p.invoice !== 'string' || inv.id === p.invoice)
-        .map(invoicePayment).filter((x) => !!x)
-        .filter((x) => typeof wanted !== 'string' || x.payment.payment_intent === wanted)
-        .filter((x) => typeof p.status !== 'string' || x.status === p.status);
-    return list(ctx, 'invoice_payment', items);
-};
-const invoicePaymentOne = 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 = {
-    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,
-};