@volter/twin-stripe 0.1.2 → 2.0.1

package/dist/src/semantics/renewals.js

@@ -0,0 +1,251 @@
+import { addBillingInterval, applyCouponDiscount, declineFor, mintClientSecret, priceAmount, resolveSubscriptionBillingInterval } from "../stripe-twin.js";
+import { finalizedFields } from "./invoices.js";
+import { mintCharge } from "./payment-intents.js";
+import { at_, created, finder } from "./shared.js";
+const SUB = 'subscription';
+const INV = 'invoice';
+const HOUR = 3600;
+/** The statuses a subscription renews in. */
+const RENEWING = ['trialing', 'active', 'past_due'];
+/** A customer's now: its test clock's frozen time when it is on one (docs.stripe.com/billing/testing/test-clocks), the
+ *  World's otherwise. */
+export function clockNow(ctx, customer) {
+    const clock = typeof customer === 'string' ? ctx.get('customer', customer)?.test_clock : undefined;
+    const frozen = typeof clock === 'string' ? ctx.get('test_helpers.test_clock', clock)?.frozen_time : undefined;
+    return frozen !== undefined ? Number(frozen) : Number(ctx.now());
+}
+/** What a subscription's invoices charge: its own default payment method, else its customer's. */
+export function payerOf(ctx, sub) {
+    return typeof sub.default_payment_method === 'string' && sub.default_payment_method ? sub.default_payment_method : customerDefault(ctx, sub);
+}
+/** The customer's default for invoices, charged when the subscription names none of its own. */
+function customerDefault(ctx, sub) {
+    const customer = typeof sub.customer === 'string' ? ctx.get('customer', sub.customer) : undefined;
+    const settings = customer?.invoice_settings;
+    return typeof settings?.default_payment_method === 'string' && settings.default_payment_method ? settings.default_payment_method : undefined;
+}
+const itemsOf = (sub) => (sub.items?.data) ?? [];
+/** An item's quantity as it bills: 1 when none is set, and 0 when 0 is (a quantity of 0 bills nothing). */
+export function itemQuantity(it) {
+    return it.quantity === undefined || it.quantity === null ? 1 : Math.max(0, Math.trunc(Number(it.quantity) || 0));
+}
+/** The subscription's discounts with a `once` coupon's spent: "When a subscription uses a coupon with `duration=once`, the
+ *  coupon is considered used after the invoice finalizes and is removed from the subscription's `discounts` array"
+ *  (docs.stripe.com/billing/subscriptions/coupons#coupon-duration). */
+export function unspentDiscounts(discounts) {
+    return (discounts ?? []).filter((d) => !(d && typeof d === 'object' && d.coupon?.duration === 'once'));
+}
+/** The coupon ids an invoice's discounts name. */
+const couponsOf = (discounts) => new Set((discounts ?? []).map((d) => {
+    const c = d && typeof d === 'object' ? d.coupon : undefined;
+    return typeof c === 'string' ? c : c && typeof c === 'object' ? String(c.id ?? '') : '';
+}).filter(Boolean));
+/** A subscription whose invoice has just been finalized: the `once` coupon that invoice took is spent, and a once coupon
+ *  it did not take (added after it was drafted) stays for the next (unspentDiscounts). */
+export async function spendOnceCoupon(ctx, invoice) {
+    const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
+    const sub = subId ? ctx.get(SUB, subId) : undefined;
+    if (!sub || !subId)
+        return;
+    const all = sub.discounts ?? [];
+    const kept = keptAfter(all, invoice);
+    if (kept.length !== all.length)
+        await ctx.write(SUB, subId, { discounts: kept }, 'subscription.discount_spent');
+}
+/** A subscription's discounts after `invoice` finalizes: less the `once` coupons it took. */
+export function keptAfter(discounts, invoice) {
+    const taken = couponsOf(invoice.discounts);
+    return discounts.filter((d) => !(unspentDiscounts([d]).length === 0 && [...couponsOf([d])].some((c) => taken.has(c))));
+}
+/** A draft invoice for one period of a subscription, its lines the subscription's items and any one-time lines `once`
+ *  gives it (a Checkout session's one-time prices, "on the initial invoice only", docs.stripe.com/api/checkout/sessions/
+ *  create#create_checkout_session-line_items), under the subscription's discount. Answers the invoice id. */
+export async function draftSubscriptionInvoice(ctx, sub, o) {
+    const id = o.id ?? ctx.mint(INV);
+    const currency = String(sub.currency ?? 'usd');
+    const lines = itemsOf(sub).map((it, i) => {
+        const price = it.price && typeof it.price === 'object' ? it.price : ctx.get('price', String(it.price ?? ''));
+        const quantity = itemQuantity(it);
+        return {
+            id: `il_twin_${id}_${i + 1}`, object: 'line_item', type: 'subscription',
+            // a trial's first invoice bills nothing for the trial period (docs.stripe.com/billing/subscriptions/trials)
+            amount: o.trial ? 0 : priceAmount(price, quantity), currency, quantity, proration: false,
+            price: price ?? null, subscription: sub.id, subscription_item: it.id ?? null, invoice_item: null,
+            period: { start: o.start, end: o.end }, description: o.trial ? `Trial period for ${String(ctx.get('product', String(price?.product ?? ''))?.name ?? 'the plan')}` : null,
+        };
+    });
+    if (o.once?.length)
+        lines.push(...oneTimeLines(id, sub, o.once, lines.length, o.start, currency));
+    const subtotal = lines.reduce((s, l) => s + l.amount, 0);
+    // a discount the subscription still carries applies; a `once` coupon is removed once an invoice finalizes
+    // (spendOnceCoupon), so it discounts one invoice (docs.stripe.com/billing/subscriptions/coupons#coupon-duration)
+    const discount = (sub.discounts ?? [])[0];
+    const coupon = discount && typeof discount === 'object' ? discount.coupon : undefined;
+    const off = coupon ? applyCouponDiscount(subtotal, coupon) : 0;
+    const total = Math.max(0, subtotal - off);
+    await created(ctx, INV, { id, customer: sub.customer, subscription: sub.id }, {
+        created: o.start, status: 'draft', livemode: false, currency, collection_method: 'charge_automatically',
+        billing_reason: o.reason, auto_advance: true, attempt_count: 0, attempted: false, next_payment_attempt: null,
+        amount_due: total, amount_paid: 0, amount_remaining: total, amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
+        subtotal, total, starting_balance: 0, post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
+        // "The invoice that consumed the coupon still shows the applied discount" (docs.stripe.com/billing/subscriptions/coupons)
+        period_start: o.start, period_end: o.end, default_tax_rates: [], discounts: coupon && discount ? [discount] : [],
+        lines: { object: 'list', data: lines, has_more: false, total_count: lines.length, url: `/v1/invoices/${id}/lines` },
+        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 },
+        payment_intent: null, charge: null,
+    });
+    return id;
+}
+/** A Checkout session's one-time line items as lines of its subscription's first invoice, numbered after its `after` lines. */
+function oneTimeLines(invoiceId, sub, items, after, at, currency) {
+    return items.map((it, i) => {
+        const price = it.price && typeof it.price === 'object' ? it.price : null;
+        const quantity = itemQuantity(it);
+        return {
+            id: `il_twin_${invoiceId}_${after + i + 1}`, object: 'line_item', type: 'subscription',
+            amount: priceAmount(price ?? undefined, quantity), currency, quantity, proration: false,
+            price, subscription: sub.id, subscription_item: null, invoice_item: null,
+            period: { start: at, end: at }, description: typeof it.description === 'string' ? it.description : null,
+        };
+    });
+}
+/** Finalize a subscription's draft invoice at `at` and charge what its subscription pays with. The move is time's (a
+ *  renewal), the customer's (the Checkout page they paid on) or the API's (an update that ends a trial, which names the
+ *  payer, may ask for no attempt, and moves the subscription itself: semantics/subscriptions.ts applyTrialEnd). Answers
+ *  whether it was paid. */
+export async function collectSubscriptionInvoice(ctx, invoiceId, at, actor, opts = {}) {
+    const inv = ctx.get(INV, invoiceId);
+    const sub = inv && typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
+    if (!inv || !sub || inv.status !== 'draft')
+        return false;
+    const total = Number(inv.total) || 0;
+    const numbered = { ...finalizedFields(ctx, inv, at), status_transitions: { ...inv.status_transitions, finalized_at: at } };
+    const op = ctx.call.operation.id;
+    // nothing due (a trial's first invoice) is paid as it is finalized; finalizing spends a `once` coupon
+    if (total <= 0) {
+        if (ctx.legal(INV, 'status', op, 'draft', 'paid', invoiceId, actor))
+            return false;
+        await spendOnceCoupon(ctx, inv);
+        await ctx.write(INV, invoiceId, { ...numbered, status: 'paid', paid: true, auto_advance: false, status_transitions: { ...numbered.status_transitions, paid_at: at } }, 'invoice.paid');
+        return true;
+    }
+    const payer = actor === 'api' ? opts.payer : payerOf(ctx, sub);
+    // default_incomplete finalizes the invoice without attempting payment (docs.stripe.com/api/subscriptions/update#update_subscription-payment_behavior)
+    const attempt = opts.attempt !== false;
+    const decline = payer && attempt ? declineFor(finder(ctx), { payment_method: payer }) : undefined;
+    const pays = attempt && !!payer && !decline;
+    if (ctx.legal(INV, 'status', op, 'draft', pays ? 'paid' : 'open', invoiceId, actor))
+        return false;
+    await spendOnceCoupon(ctx, inv);
+    const piId = ctx.mint('payment_intent');
+    const currency = String(inv.currency ?? 'usd');
+    const chargeId = pays ? await mintCharge(ctx, piId, { currency, customer: inv.customer, payment_method: payer, invoice: invoiceId }, total) : null;
+    await created(ctx, 'payment_intent', { id: piId, amount: total, currency, customer: inv.customer, invoice: invoiceId, payment_method: pays ? payer : null }, {
+        status: pays ? 'succeeded' : 'requires_payment_method', client_secret: mintClientSecret(piId), livemode: false,
+        capture_method: 'automatic', amount_capturable: 0, amount_received: pays ? total : 0, next_action: null, latest_charge: chargeId,
+        last_payment_error: decline ? { type: 'card_error', code: decline.code, decline_code: decline.decline_code ?? null, message: decline.message, payment_method: { id: payer } } : null,
+        automatic_payment_methods: null, payment_method_types: ['card'], payment_method_options: {},
+    });
+    await ctx.write(INV, invoiceId, {
+        ...numbered, status: pays ? 'paid' : 'open', paid: pays, attempt_count: attempt ? 1 : 0, attempted: attempt, payment_intent: piId, charge: chargeId,
+        amount_paid: pays ? total : 0, amount_remaining: pays ? 0 : total, auto_advance: attempt && !pays, next_payment_attempt: null,
+        status_transitions: { ...numbered.status_transitions, paid_at: pays ? at : null },
+    }, pays ? 'invoice.paid' : attempt ? 'invoice.payment_failed' : 'invoice.finalized');
+    if (actor !== 'api' && !pays && sub.status !== 'past_due' && !ctx.legal(SUB, 'status', op, sub.status, 'past_due', String(sub.id), 'time')) {
+        await ctx.write(SUB, String(sub.id), { status: 'past_due' }, 'customer.subscription.updated');
+    }
+    return pays;
+}
+/** Pay a subscription's open invoice with `paymentMethod` (the customer on the portal, `external`): the charge on the
+ *  invoice's PaymentIntent, the invoice paid, a past_due subscription active. Answers the decline, if the card is refused. */
+export async function payOpenInvoice(ctx, invoiceId, paymentMethod) {
+    const inv = ctx.get(INV, invoiceId);
+    if (!inv || inv.status !== 'open')
+        return { code: 'invoice_not_open', message: 'This invoice is no longer open.' };
+    const decline = declineFor(finder(ctx), { payment_method: paymentMethod });
+    if (decline)
+        return decline;
+    const op = ctx.call.operation.id;
+    const refused = ctx.legal(INV, 'status', op, 'open', 'paid', invoiceId, 'external');
+    if (refused)
+        return { code: refused.code ?? 'invoice_not_open', message: refused.message };
+    const total = Number(inv.amount_remaining ?? inv.total) || 0;
+    const now = Number(ctx.now());
+    const piId = typeof inv.payment_intent === 'string' ? inv.payment_intent : undefined;
+    let chargeId = null;
+    const pi = piId ? ctx.get('payment_intent', piId) : undefined;
+    if (piId && pi && !ctx.legal('payment_intent', 'status', op, pi.status, 'succeeded', piId, 'external')) {
+        chargeId = await mintCharge(ctx, piId, { ...pi, payment_method: paymentMethod, invoice: invoiceId }, total);
+        await ctx.write('payment_intent', piId, { status: 'succeeded', payment_method: paymentMethod, amount_received: total, last_payment_error: null, latest_charge: chargeId }, 'payment_intent.succeeded');
+    }
+    await ctx.write(INV, invoiceId, {
+        status: 'paid', paid: true, amount_paid: total, amount_remaining: 0, charge: chargeId, auto_advance: false,
+        attempt_count: (Number(inv.attempt_count) || 0) + 1, attempted: true,
+        status_transitions: { ...inv.status_transitions, paid_at: now },
+    }, 'invoice.paid');
+    const sub = typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
+    if (sub && sub.status === 'past_due' && !ctx.legal(SUB, 'status', op, 'past_due', 'active', String(sub.id), 'external')) {
+        await ctx.write(SUB, String(sub.id), { status: 'active' }, 'customer.subscription.updated');
+    }
+    return undefined;
+}
+/** Time's moves on subscriptions, caught up to each customer's clock in the order they fell due, each made at the
+ *  moment it was due: a period that ended renews (a trial's end among them) or, set to cancel, cancels; a renewal
+ *  drafted an hour or more ago is finalized and charged. */
+export async function advanceBilling(ctx, only) {
+    const at = at_(ctx);
+    for (let guard = 0; guard < 10_000 && (await billingStep(ctx, at, only)); guard++)
+        ;
+}
+/** The earliest move that has come due, made at its moment; false when none has. */
+async function billingStep(ctx, at, only) {
+    // the earliest move that has come due, of any subscription
+    let next;
+    for (const sub of ctx.rows(SUB)) {
+        if (only && !only(sub))
+            continue;
+        if (!RENEWING.includes(String(sub.status)) || typeof sub.current_period_end !== 'number' || sub.pause_collection)
+            continue;
+        if (sub.current_period_end <= clockNow(ctx, sub.customer) && (!next || sub.current_period_end < next.t))
+            next = { t: sub.current_period_end, kind: 'period', id: String(sub.id) };
+    }
+    for (const inv of ctx.rows(INV)) {
+        if (inv.status !== 'draft' || inv.billing_reason !== 'subscription_cycle' || inv.auto_advance !== true)
+            continue;
+        const sub = typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
+        if (!sub || (only && !only(sub)))
+            continue;
+        const t = Number(inv.created) + HOUR;
+        if (t <= clockNow(ctx, sub.customer) && (!next || t < next.t))
+            next = { t, kind: 'collect', id: String(inv.id) };
+    }
+    if (!next)
+        return false;
+    const c = await at(next.t);
+    if (next.kind === 'collect') {
+        await collectSubscriptionInvoice(c, next.id, next.t, 'time');
+        return true;
+    }
+    const id = next.id;
+    const sub = c.get(SUB, id);
+    const op = c.call.operation.id;
+    // one set to cancel at its period's end is canceled then, with no renewal
+    // (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle)
+    if (sub.cancel_at_period_end === true) {
+        if (c.legal(SUB, 'status', op, sub.status, 'canceled', id, 'time'))
+            return false;
+        await c.write(SUB, id, { status: 'canceled', ended_at: next.t, canceled_at: sub.canceled_at ?? next.t }, 'customer.subscription.deleted');
+        return true;
+    }
+    const start = next.t;
+    const { interval, interval_count } = resolveSubscriptionBillingInterval(itemsOf(sub), finder(c));
+    const end = addBillingInterval(start, interval, interval_count);
+    const trialEnds = sub.status === 'trialing';
+    if (trialEnds && c.legal(SUB, 'status', op, 'trialing', 'active', id, 'time'))
+        return false;
+    const invoiceId = await draftSubscriptionInvoice(c, sub, { start, end, reason: 'subscription_cycle' });
+    await c.write(SUB, id, { current_period_start: start, current_period_end: end, latest_invoice: invoiceId, ...(trialEnds ? { status: 'active' } : {}) }, 'customer.subscription.updated');
+    return true;
+}

package/dist/src/semantics/setup-intents.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const setupIntents: Record<string, Semantics>;

package/dist/src/semantics/setup-intents.js

@@ -0,0 +1,84 @@
+import { asBool, microdepositsNextAction, mintClientSecret, requiresMicrodeposits, verifyMicrodeposits } from "../stripe-twin.js";
+import { mintMandate } from "./after-payment.js";
+import { attachable, attachPaymentMethod, methodFromData, microdepositsAsked } from "./payment-methods.js";
+import { at, confirmOnly, created, fail, mergeUpdate, send } from "./shared.js";
+const SI = 'setup_intent';
+/** The intent the path names, and the machine's refusal when this operation may not move it. */
+function load(ctx, operationId) {
+    const id = at(ctx, 'intent');
+    const si = ctx.get(SI, id);
+    if (!si)
+        return { answer: fail(ctx, `No such setup_intent: '${id}'`, 404, 'resource_missing') };
+    const refused = ctx.legal(SI, 'status', operationId, si.status, undefined, id);
+    return refused ? { answer: ctx.refuse(refused) } : { si };
+}
+const create = async (ctx) => {
+    // mandate_data and return_url each "can only be used with `confirm=true`" (the served spec; shared.ts confirmOnly)
+    const unconfirmed = confirmOnly(ctx, ['mandate_data', 'return_url'], asBool(ctx.params.confirm));
+    if (unconfirmed)
+        return unconfirmed;
+    // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
+    const id = typeof ctx.params.id === 'string' && ctx.params.id ? ctx.params.id : ctx.mint(SI);
+    // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
+    const hasMethod = typeof ctx.params.payment_method === 'string' && ctx.params.payment_method !== '';
+    if (hasMethod)
+        ctx.legal(SI, 'status', 'PostSetupIntents', 'requires_payment_method', 'requires_confirmation', id);
+    return ctx.reply(
+    // allowed_payment_method_types in the served version names the methods (docs.stripe.com/api/setup_intents/create)
+    await created(ctx, SI, { ...ctx.params, ...(Array.isArray(ctx.params.allowed_payment_method_types) ? { payment_method_types: ctx.params.allowed_payment_method_types.map(String) } : {}), id }, {
+        status: hasMethod ? 'requires_confirmation' : 'requires_payment_method', usage: 'off_session', client_secret: mintClientSecret(id), payment_method_types: ['card'],
+        next_action: null, latest_attempt: null, last_setup_error: null, livemode: false,
+    }));
+};
+// a bank account that needs micro-deposit verification waits in requires_action; anything else succeeds. The confirm's
+// payment_method_data and mandate_data are instructions, not fields of the SetupIntent.
+const confirm = async (ctx) => {
+    const loaded = load(ctx, 'PostSetupIntentsIntentConfirm');
+    if ('answer' in loaded)
+        return loaded.answer;
+    const si = loaded.si;
+    const id = String(si.id);
+    const { payment_method_data: data, mandate_data: _mandate, ...fields } = ctx.params;
+    const made = await methodFromData(ctx, data);
+    const pm = made ?? (typeof ctx.params.payment_method === 'string' ? ctx.params.payment_method : typeof si.payment_method === 'string' ? si.payment_method : undefined);
+    if (si.status !== 'requires_action' && (requiresMicrodeposits(ctx.params, si) || microdepositsAsked(ctx, ctx.params, si, pm))) {
+        return ctx.reply(await ctx.write(SI, id, mergeUpdate(ctx, SI, id, { ...fields, ...(pm ? { payment_method: pm } : {}), status: 'requires_action', next_action: microdepositsNextAction() }), 'setup_intent.requires_action'));
+    }
+    // a setup for a customer saves the method to them (docs.stripe.com/payments/save-and-reuse): its payment method is attached
+    const customer = typeof si.customer === 'string' ? si.customer : undefined;
+    const saved = pm && customer && attachable(ctx, pm) && ctx.get('payment_method', pm)?.customer !== customer ? String((await attachPaymentMethod(ctx, pm, customer)).id) : pm;
+    return ctx.reply(await ctx.write(SI, id, mergeUpdate(ctx, SI, id, { ...fields, ...(saved ? { payment_method: saved } : {}), status: 'succeeded' }), 'setup_intent.confirm'));
+};
+const cancel = async (ctx) => {
+    const loaded = load(ctx, 'PostSetupIntentsIntentCancel');
+    if ('answer' in loaded)
+        return loaded.answer;
+    const cancellation_reason = typeof ctx.params.cancellation_reason === 'string' ? ctx.params.cancellation_reason : 'abandoned';
+    return ctx.reply(await ctx.write(SI, String(loaded.si.id), { status: 'canceled', cancellation_reason }, 'setup_intent.canceled'));
+};
+const verify = async (ctx) => {
+    const id = at(ctx, 'intent');
+    const si = ctx.get(SI, id);
+    if (!si)
+        return fail(ctx, `No such setup_intent: '${id}'`, 404, 'resource_missing');
+    // the deposit amounts are checked before the intent's state, as Stripe does
+    const wrong = verifyMicrodeposits(ctx.params, si);
+    if (wrong)
+        return send(ctx, wrong);
+    const refused = ctx.legal(SI, 'status', 'PostSetupIntentsIntentVerifyMicrodeposits', si.status, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    const mandate = await mintMandate(ctx, si.payment_method, 'multi_use');
+    // verified, the bank account is saved to the setup's customer, as a confirmed setup's method is
+    const pm = typeof si.payment_method === 'string' ? si.payment_method : undefined;
+    const customer = typeof si.customer === 'string' ? si.customer : undefined;
+    if (pm && customer && attachable(ctx, pm) && ctx.get('payment_method', pm)?.customer !== customer)
+        await attachPaymentMethod(ctx, pm, customer);
+    return ctx.reply(await ctx.write(SI, id, { status: 'succeeded', next_action: null, last_setup_error: null, mandate }, 'setup_intent.succeeded'));
+};
+export const setupIntents = {
+    PostSetupIntents: create,
+    PostSetupIntentsIntentConfirm: confirm,
+    PostSetupIntentsIntentCancel: cancel,
+    PostSetupIntentsIntentVerifyMicrodeposits: verify,
+};

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

@@ -0,0 +1,82 @@
+import type { SemanticsContext } from '@volter/world-core';
+import { type StripeResponse } from '../stripe-twin.js';
+export type Row = Record<string, unknown>;
+export declare const send: (ctx: SemanticsContext, r: StripeResponse) => Response;
+/** Stripe's error body: an invalid_request_error with the message, and the code when there is one. */
+export declare const fail: (ctx: SemanticsContext, message: string, status?: number, code?: string) => Response;
+/** A file parameter whose description requires a purpose refuses a file of another one. The served spec requires it
+ *  on every such parameter ("Must have a `purpose` value of `issuing_logo`", personalization designs' card_logo;
+ *  "The file's `purpose` must be one of the following: …", file links' file). Where the documentation stops and the
+ *  twin decides: Stripe documents no error for it (docs.stripe.com/error-codes names none), so the twin answers the
+ *  400 invalid_request_error it answers for an unknown file, naming the parameter and the purposes allowed. */
+export declare function filePurposeRefused(ctx: SemanticsContext, param: string, allowed: readonly string[]): Response | undefined;
+/** The request's path, as the list envelope's `url` carries it. */
+export declare const path: (ctx: SemanticsContext) => string;
+/** A path parameter, by the name the spec gives it. */
+export declare const at: (ctx: SemanticsContext, name: string) => string;
+/** An update's fields laid over what is stored, as the derived core does: a nested hash is merged into the stored one,
+ *  not put in its place (Stripe updates only the keys a request names; docs.stripe.com/api/metadata and each update
+ *  reference), and an empty string unsets a key. */
+export declare function mergeUpdate(ctx: SemanticsContext, resource: string, id: string, fields: Row): Row;
+/** The tree's type for a resource: what its rows are stored under. */
+export declare const stored: (resource: string) => string;
+/** A resource's rows in Stripe's list order: newest first by `timeField`, ties by mint order (as the derived core breaks them). */
+/** A subject's bookkeeping field (`_…`): kept on the stored row, never in the wire view ctx.get and ctx.rows answer. */
+export declare const kept: (ctx: SemanticsContext, resource: string, row: Row, key: string) => unknown;
+/** A removed discount as Stripe answers it: the discount, marked deleted (docs.stripe.com/api/discounts/delete). */
+export declare function deletedDiscount(d: Row, now: unknown): Row;
+/** A create's parameter that describes a confirmation, sent without confirm=true: the served spec gives each "This
+ *  parameter can only be used with `confirm=true`" (off_session: "can only be used when confirm=true"); the message's
+ *  wording is the twin's. Answers the refusal, or undefined. */
+export declare function confirmOnly(ctx: SemanticsContext, names: string[], confirm: boolean): Response | undefined;
+/** A coupon applied (and the promotion code it came by): its times_redeemed, "Number of times this coupon has been
+ *  applied to a customer" (the served spec's coupon), counts it, as the code's "Number of times this promotion code
+ *  has been used" (its promotion_code). Where the documentation stops and the twin decides: reaching max_redemptions
+ *  does not yet lapse the coupon. */
+export declare function redeemCoupon(ctx: SemanticsContext, couponId: unknown, promotionCode?: unknown): Promise<void>;
+export declare function newest(ctx: SemanticsContext, resource: string, timeField?: string): Row[];
+/** Keep the rows whose field equals the request's parameter of the same name, for each name given. */
+/** A list's range filter on a unix time (`created[gte]=…&created[lt]=…`, or one exact time). */
+export declare function inRange(t: unknown, v: unknown): boolean;
+/** A context at the moment Stripe would have made a move time makes (a renewal, a payout on its schedule), so what
+ *  the move writes carries that moment (its events' occurredAt, `created`, a charge's funds' available_on), not the
+ *  moment a later request caught it up. */
+export declare function at_(ctx: SemanticsContext): (t: number) => Promise<SemanticsContext>;
+export declare function where(ctx: SemanticsContext, items: Row[], spec: Record<string, (item: Row, value: unknown) => boolean>): Row[];
+/** A balance transaction as the clock reads it: available once its available_on has passed, the clock's move,
+ *  asked of the machine as a write asks it (semantics/ledger.ts). */
+export declare function asOf(ctx: SemanticsContext, t: Row): Row;
+/** Stripe's expand walk: each dotted path replaces an id with the resource the manifest says it
+ *  holds, one segment at a time; an id the tree lacks stays an id. A balance transaction reads as the clock has it
+ *  (asOf), as its own retrieve does. */
+export declare function expandRow(ctx: SemanticsContext, resource: string, body: Row, paths: string[][]): Row;
+/** One resource with the request's `expand[]` applied. */
+export declare const expanded: (ctx: SemanticsContext, resource: string, body: Row) => Row;
+/** Stripe's list envelope over rows already in list order: a page, `has_more`, and `expand[]=data.*`. */
+export declare function list(ctx: SemanticsContext, resource: string, items: Row[]): Response;
+/** Stripe's search over a resource's rows (`query` in its search language). */
+export declare const search: (ctx: SemanticsContext, resource: string, timeField?: string) => Response;
+/** A create as Stripe stamps it: the caller's id when it gave one (seeding uses real ids), else a
+ *  minted one; `object`, the creation time, the defaults, then the request's own fields. An object
+ *  Stripe gives no creation time keeps the twin's as `_created`, for ordering. (A request parameter the
+ *  object has no field for stays on the row, where the rules read it; the wire answer leaves it out,
+ *  stripe-version.ts.) */
+export declare function created(ctx: SemanticsContext, resource: string, params: Row, defaults: Row, opts?: {
+    timeField?: string;
+    operation?: string;
+}): Promise<Row>;
+/** A stored subject of any stored type, tombstones included, in the pack's view: what the pack's
+ *  shared helpers look a price, a payment method or a card up by, read from the context's tree. */
+export type Find = (storedType: string, id: string) => Row | undefined;
+export declare const finder: (ctx: SemanticsContext) => Find;
+/** A refund's destination_details for a card charge: "If this is a `card` refund, this hash contains the transaction
+ *  specific details" and its `type` "can be `refund`, `reversal`, or `pending`" — a reversal, where "The original charge
+ *  will drop off the bank statement altogether", for an authorization released uncaptured, else a refund, "a credit entry
+ *  on the bank statement" (docs.stripe.com/api/refunds/object). The network's reference number the twin never has. A
+ *  charge not paid by card answers none. */
+export declare function refundDestination(charge: Row, type: 'refund' | 'reversal'): Row;
+/** An account's external_accounts, "External accounts (bank accounts and debit cards) currently attached to this
+ *  account" (docs.stripe.com/api/accounts/object), as the list its example answers. */
+export declare const externalList: (account: string, data: Row[]) => Row;
+/** The account's external_accounts list, rewritten from its external accounts after one is added or removed. */
+export declare function syncExternals(ctx: SemanticsContext, account: string): Promise<void>;

package/dist/src/semantics/shared.js

@@ -0,0 +1,203 @@
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { OBJECT_NAME, paginate, searchOver, stashVendorType, view } from "../stripe-twin.js";
+export const send = (ctx, r) => ctx.reply(r.body, r.status);
+/** Stripe's error body: an invalid_request_error with the message, and the code when there is one. */
+export const fail = (ctx, message, status = 404, code) => ctx.refuse({ status, message, ...(code ? { code } : {}) });
+/** A file parameter whose description requires a purpose refuses a file of another one. The served spec requires it
+ *  on every such parameter ("Must have a `purpose` value of `issuing_logo`", personalization designs' card_logo;
+ *  "The file's `purpose` must be one of the following: …", file links' file). Where the documentation stops and the
+ *  twin decides: Stripe documents no error for it (docs.stripe.com/error-codes names none), so the twin answers the
+ *  400 invalid_request_error it answers for an unknown file, naming the parameter and the purposes allowed. */
+export function filePurposeRefused(ctx, param, allowed) {
+    const given = ctx.params[param];
+    if (given === undefined || given === '')
+        return undefined;
+    const file = ctx.get('file', String(given));
+    if (!file)
+        return fail(ctx, `No such file upload: '${String(given)}'`, 400, 'resource_missing');
+    if (allowed.includes(String(file.purpose)))
+        return undefined;
+    const need = allowed.length === 1 ? `a \`purpose\` value of \`${allowed[0]}\`` : `a \`purpose\` of one of: ${allowed.map((a) => `\`${a}\``).join(', ')}`;
+    return fail(ctx, `Invalid ${param}: the file '${String(given)}' has a \`purpose\` of \`${String(file.purpose)}\`, but it must have ${need}.`, 400);
+}
+/** The request's path, as the list envelope's `url` carries it. */
+export const path = (ctx) => new URL(ctx.call.request.url).pathname.replace(/\/+$/, '') || '/';
+/** A path parameter, by the name the spec gives it. */
+export const at = (ctx, name) => ctx.call.params[name] ?? '';
+/** An update's fields laid over what is stored, as the derived core does: a nested hash is merged into the stored one,
+ *  not put in its place (Stripe updates only the keys a request names; docs.stripe.com/api/metadata and each update
+ *  reference), and an empty string unsets a key. */
+export function mergeUpdate(ctx, resource, id, fields) {
+    const current = ctx.get(resource, id) ?? {};
+    const out = {};
+    for (const [k, v] of Object.entries(fields)) {
+        const prior = current[k];
+        out[k] = v && typeof v === 'object' && !Array.isArray(v) && prior && typeof prior === 'object' && !Array.isArray(prior)
+            ? Object.fromEntries(Object.entries({ ...prior, ...v }).filter(([, x]) => x !== ''))
+            : v;
+    }
+    return out;
+}
+/** The tree's type for a resource: what its rows are stored under. */
+export const stored = (resource) => manifest.resources[resource]?.storedAs ?? resource;
+/** A resource's rows in Stripe's list order: newest first by `timeField`, ties by mint order (as the derived core breaks them). */
+/** A subject's bookkeeping field (`_…`): kept on the stored row, never in the wire view ctx.get and ctx.rows answer. */
+export const kept = (ctx, resource, row, key) => ctx.row(resource, String(row.id), { withDeleted: true })?.[key];
+/** A removed discount as Stripe answers it: the discount, marked deleted (docs.stripe.com/api/discounts/delete). */
+export function deletedDiscount(d, now) {
+    const coupon = d.coupon && typeof d.coupon === 'object' ? String(d.coupon.id) : typeof d.coupon === 'string' ? d.coupon : null;
+    return {
+        id: d.id ?? `di_${coupon ?? 'twin'}`, object: 'discount', deleted: true, checkout_session: d.checkout_session ?? null, customer: d.customer ?? null,
+        invoice: d.invoice ?? null, invoice_item: d.invoice_item ?? null, promotion_code: d.promotion_code ?? null, subscription: d.subscription ?? null,
+        subscription_item: d.subscription_item ?? null, source: d.source ?? { type: 'coupon', coupon }, start: d.start ?? now,
+    };
+}
+/** A create's parameter that describes a confirmation, sent without confirm=true: the served spec gives each "This
+ *  parameter can only be used with `confirm=true`" (off_session: "can only be used when confirm=true"); the message's
+ *  wording is the twin's. Answers the refusal, or undefined. */
+export function confirmOnly(ctx, names, confirm) {
+    const sent = confirm ? undefined : names.find((n) => ctx.params[n] !== undefined);
+    return sent ? fail(ctx, `\`${sent}\` can only be used when \`confirm\` is set to \`true\`.`, 400, 'parameter_invalid') : undefined;
+}
+/** A coupon applied (and the promotion code it came by): its times_redeemed, "Number of times this coupon has been
+ *  applied to a customer" (the served spec's coupon), counts it, as the code's "Number of times this promotion code
+ *  has been used" (its promotion_code). Where the documentation stops and the twin decides: reaching max_redemptions
+ *  does not yet lapse the coupon. */
+export async function redeemCoupon(ctx, couponId, promotionCode) {
+    const coupon = typeof couponId === 'string' ? ctx.get('coupon', couponId) : undefined;
+    if (coupon)
+        await ctx.write('coupon', couponId, { times_redeemed: (Number(coupon.times_redeemed) || 0) + 1 }, 'coupon.redeemed');
+    const code = typeof promotionCode === 'string' ? ctx.get('promotion_code', promotionCode) : undefined;
+    if (code)
+        await ctx.write('promotion_code', promotionCode, { times_redeemed: (Number(code.times_redeemed) || 0) + 1 }, 'promotion_code.redeemed');
+}
+export function newest(ctx, resource, timeField = 'created') {
+    // an object Stripe gives no creation time is ordered by the one the twin keeps for it
+    const raw = new Map(ctx.rowsRaw(resource).map((r) => [String(r.id), r]));
+    const when = (r) => Number(r[timeField] ?? raw.get(String(r.id))?._created ?? 0);
+    return ctx.rows(resource).sort((a, b) => {
+        const ta = when(a), tb = when(b);
+        if (tb !== ta)
+            return tb - ta;
+        return String(b.id).localeCompare(String(a.id), undefined, { numeric: true });
+    });
+}
+/** Keep the rows whose field equals the request's parameter of the same name, for each name given. */
+/** A list's range filter on a unix time (`created[gte]=…&created[lt]=…`, or one exact time). */
+export function inRange(t, v) {
+    const at = Number(t);
+    const r = (v && typeof v === 'object' ? v : { gte: v, lte: v });
+    return (r.gt === undefined || at > Number(r.gt)) && (r.gte === undefined || at >= Number(r.gte)) && (r.lt === undefined || at < Number(r.lt)) && (r.lte === undefined || at <= Number(r.lte));
+}
+/** A context at the moment Stripe would have made a move time makes (a renewal, a payout on its schedule), so what
+ *  the move writes carries that moment (its events' occurredAt, `created`, a charge's funds' available_on), not the
+ *  moment a later request caught it up. */
+export function at_(ctx) {
+    return (t) => ctx.at(new Date(t * 1000).toISOString());
+}
+export function where(ctx, items, spec) {
+    let out = items;
+    for (const [key, pred] of Object.entries(spec)) {
+        const value = ctx.params[key];
+        if (value !== undefined)
+            out = out.filter((item) => pred(item, value));
+    }
+    return out;
+}
+function expandPaths(ctx) {
+    const expand = ctx.params.expand;
+    return Array.isArray(expand) ? expand.map((p) => String(p).split('.')) : [];
+}
+/** A balance transaction as the clock reads it: available once its available_on has passed, the clock's move,
+ *  asked of the machine as a write asks it (semantics/ledger.ts). */
+export function asOf(ctx, t) {
+    const due = Number(t.available_on);
+    if (t.status !== 'pending' || !Number.isFinite(due) || due > Number(ctx.now()))
+        return t;
+    ctx.legal('balance_transaction', 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time');
+    return { ...t, status: 'available' };
+}
+/** Stripe's expand walk: each dotted path replaces an id with the resource the manifest says it
+ *  holds, one segment at a time; an id the tree lacks stays an id. A balance transaction reads as the clock has it
+ *  (asOf), as its own retrieve does. */
+export function expandRow(ctx, resource, body, paths) {
+    const embeds = manifest.resources[resource]?.embeds;
+    if (!embeds || paths.length === 0)
+        return body;
+    let out = body;
+    const byHead = new Map();
+    for (const p of paths) {
+        if (p.length === 0)
+            continue;
+        const list = byHead.get(p[0]) ?? [];
+        list.push(p.slice(1));
+        byHead.set(p[0], list);
+    }
+    for (const [head, tails] of byHead) {
+        const target = embeds[head];
+        if (!target)
+            continue;
+        const cur = out[head];
+        const found = typeof cur === 'string' && cur ? ctx.get(target, cur) : cur && typeof cur === 'object' && !Array.isArray(cur) ? cur : undefined;
+        if (!found)
+            continue;
+        const sub = target === 'balance_transaction' ? asOf(ctx, found) : found;
+        const deeper = tails.filter((t) => t.length > 0);
+        out = { ...out, [head]: deeper.length ? expandRow(ctx, target, sub, deeper) : sub };
+    }
+    return out;
+}
+/** One resource with the request's `expand[]` applied. */
+export const expanded = (ctx, resource, body) => expandRow(ctx, resource, body, expandPaths(ctx));
+/** Stripe's list envelope over rows already in list order: a page, `has_more`, and `expand[]=data.*`. */
+export function list(ctx, resource, items) {
+    const { page, hasMore } = paginate(items, ctx.params);
+    const paths = expandPaths(ctx).filter((p) => p[0] === 'data').map((p) => p.slice(1)).filter((p) => p.length > 0);
+    return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: paths.length ? page.map((r) => expandRow(ctx, resource, r, paths)) : page });
+}
+/** Stripe's search over a resource's rows (`query` in its search language). */
+export const search = (ctx, resource, timeField = 'created') => send(ctx, searchOver(newest(ctx, resource, timeField), ctx.params, path(ctx)));
+const SPEC_FIELDS = new Map(surface.resources.map((r) => [r.name, new Set(r.fields.map((f) => f.name))]));
+/** A create as Stripe stamps it: the caller's id when it gave one (seeding uses real ids), else a
+ *  minted one; `object`, the creation time, the defaults, then the request's own fields. An object
+ *  Stripe gives no creation time keeps the twin's as `_created`, for ordering. (A request parameter the
+ *  object has no field for stays on the row, where the rules read it; the wire answer leaves it out,
+ *  stripe-version.ts.) */
+export async function created(ctx, resource, params, defaults, opts = {}) {
+    const { id: provided, ...rest } = params;
+    const type = stored(resource);
+    const id = typeof provided === 'string' && provided ? provided : ctx.mint(resource);
+    const known = SPEC_FIELDS.get(resource);
+    const timeField = opts.timeField ?? 'created';
+    const stamped = !known || known.has(timeField) || timeField in defaults || timeField in rest ? timeField : '_created';
+    const fields = stashVendorType(type, { object: OBJECT_NAME[type] ?? type, [stamped]: ctx.now(), ...defaults, ...rest });
+    return ctx.write(resource, id, fields, opts.operation ?? `${type}.create`);
+}
+export const finder = (ctx) => {
+    const tree = ctx.tree();
+    return (storedType, id) => {
+        const r = tree.find((x) => x.type === storedType && x.id === id);
+        return r ? view(storedType, r) : undefined;
+    };
+};
+/** A refund's destination_details for a card charge: "If this is a `card` refund, this hash contains the transaction
+ *  specific details" and its `type` "can be `refund`, `reversal`, or `pending`" — a reversal, where "The original charge
+ *  will drop off the bank statement altogether", for an authorization released uncaptured, else a refund, "a credit entry
+ *  on the bank statement" (docs.stripe.com/api/refunds/object). The network's reference number the twin never has. A
+ *  charge not paid by card answers none. */
+export function refundDestination(charge, type) {
+    const pmd = charge.payment_method_details;
+    if (pmd && pmd.type !== 'card')
+        return {};
+    return { destination_details: { type: 'card', card: { reference: null, reference_status: null, reference_type: null, type } } };
+}
+/** An account's external_accounts, "External accounts (bank accounts and debit cards) currently attached to this
+ *  account" (docs.stripe.com/api/accounts/object), as the list its example answers. */
+export const externalList = (account, data) => ({ object: 'list', data, has_more: false, total_count: data.length, url: `/v1/accounts/${account}/external_accounts` });
+/** The account's external_accounts list, rewritten from its external accounts after one is added or removed. */
+export async function syncExternals(ctx, account) {
+    if (!ctx.get('account', account))
+        return;
+    await ctx.write('account', account, { external_accounts: externalList(account, newest(ctx, 'external_account').filter((e) => e.account === account)) }, 'account.external_accounts');
+}

package/dist/src/semantics/subscription-schedules.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const subscriptionSchedules: Record<string, Semantics>;