@volter/twin-stripe 0.1.2 → 2.0.1

package/dist/src/semantics/invoices.js

@@ -0,0 +1,545 @@
+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) {
+    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;
+}
+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) => {
+    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?.default_payment_method || payer?.default_source;
+    if (!paidOutOfBand && !params.payment_method && !params.source && !inv.default_payment_method && !inv.default_source && !customerDefault)
+        return nothingToPayWith(ctx);
+    // what it charges: the method passed, else the invoice's default, its subscription's, then its customer's
+    // (docs.stripe.com/api/invoices/pay#pay_invoice-payment_method)
+    const subscription = typeof inv.subscription === 'string' ? ctx.get('subscription', inv.subscription) : undefined;
+    const decline = declineFor(finder(ctx), params, { payment_method: inv.default_payment_method ?? subscription?.default_payment_method ?? customerDefault });
+    const intent = typeof inv.payment_intent === 'string' ? ctx.get('payment_intent', inv.payment_intent) : undefined;
+    if (decline)
+        return send(ctx, cardError(decline, intent ? { payment_intent: intent } : {}));
+    const amountPaid = Number(inv.total ?? inv.amount_due) || 0;
+    let body = await ctx.write(INV, id, {
+        // paid outside Stripe, the invoice counts it as such: `amount_paid_off_stripe`, "Amount, in cents (or local
+        // equivalent), that was paid on the invoice outside of Stripe" (served spec, invoice), the only place the served
+        // version shows it now that basil renders no `paid_out_of_band` (stripe-version.ts)
+        status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
+        ...(paidOutOfBand ? { amount_paid_off_stripe: amountPaid } : {}),
+        status_transitions: { ...transitions(inv), paid_at: ctx.now() },
+    }, 'invoice.pay');
+    if (!paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {
+        const pi = ctx.get('payment_intent', inv.payment_intent);
+        if (pi && pi.status !== 'succeeded' && !ctx.legal('payment_intent', 'status', 'PostInvoicesInvoicePay', pi.status)) {
+            const chargeId = await mintCharge(ctx, inv.payment_intent, { ...pi, invoice: id, ...(typeof params.payment_method === 'string' ? { payment_method: params.payment_method } : {}) }, amountPaid);
+            await ctx.write('payment_intent', inv.payment_intent, { status: 'succeeded', amount_received: amountPaid, amount_capturable: 0, next_action: null, latest_charge: chargeId }, 'payment_intent.succeeded');
+            body = await ctx.write(INV, id, { charge: chargeId }, 'invoice.update');
+        }
+    }
+    // a subscription waiting on this invoice (incomplete on its first, past_due on a failed renewal) is active once it is paid
+    const subId = typeof inv.subscription === 'string' ? inv.subscription : undefined;
+    const sub = subId ? ctx.get('subscription', subId) : undefined;
+    if (subId && sub && (sub.status === 'incomplete' || sub.status === 'past_due') && !ctx.legal('subscription', 'status', 'PostInvoicesInvoicePay', sub.status, 'active', subId))
+        await activatedByPayment(ctx, subId);
+    return ctx.reply(expanded(ctx, INV, body));
+};
+// only a draft is deleted; a finalized invoice is voided instead
+const deleteDraft = 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');
+    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 = 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));
+    };
+}
+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).
+ */
+const createPreview = async (ctx) => {
+    const params = ctx.params;
+    const prorationDate = params.subscription_details?.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;
+    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 ?? '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 = [];
+    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 ?? {};
+            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);
+            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 ?? 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);
+    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) {
+    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,
+};

package/dist/src/semantics/issuing.d.ts

@@ -0,0 +1,13 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** The id of a card's cardholder: the card answers the cardholder in full (the served spec's issuing.card.cardholder is
+ *  the Cardholder object, not an id); its id is read from it for filtering and for the objects that name it by id. */
+export declare const holderId: (c: Row) => string;
+/** Time's decision on a real-time request no one answered, caught up to the World's clock: once its window has ended,
+ *  a pending authorization whose issuing_authorization.request went unanswered, and that no approve or decline decided,
+ *  is decided automatically, its request_history reason webhook_timeout ("webhook_timeout for all other failure modes",
+ *  the same page, beside webhook_error for a response Stripe cannot process).
+ *  Where the documentation stops and the twin decides: the timeout setting is the Dashboard's, which the API does not
+ *  answer, and the twin's is to decline; the window is measured in World time from the authorization's created. */
+export declare function lapseRealtimeRequests(ctx: SemanticsContext): Promise<void>;
+export declare const issuing: Record<string, Semantics>;