@volter/twin-stripe 2.0.38 → 3.0.0

package/dist/src/semantics/renewals.js

@@ -1,281 +0,0 @@
-// A subscription's invoices over time: the first one Checkout pays, and each renewal. Time's moves are made
-// as the twin's trial end already made them: caught up to the customer's clock (the World's, or its test
-// clock) whenever the twin is asked anything (../stripe-server.ts), each checked against the machines in
-// ../manifest.ts.
-//
-// - Checkout's subscription session pays the first invoice with the card the customer entered, which becomes the
-//   subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works); nothing is due
-//   on a trial's.
-// - At each period's end Stripe drafts a `subscription_cycle` invoice for the next period and advances the
-//   period; a trial's end is the first such renewal, and the subscription is active from then
-//   (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions,
-//   docs.stripe.com/billing/subscriptions/trials).
-// - About an hour after, Stripe finalizes the draft and charges the subscription's default payment method,
-//   else the customer's (docs.stripe.com/invoicing/integration/workflow-transitions#finalized,
-//   docs.stripe.com/api/subscriptions/object#subscription_object-default_payment_method).
-// - A declined renewal leaves the invoice open with its attempt counted and the subscription past_due
-//   (docs.stripe.com/billing/subscriptions/overview#payment-status); paying the invoice later, through the API
-//   (docs.stripe.com/api/invoices/pay) or on the customer portal (docs.stripe.com/customer-management), makes it
-//   active again.
-//
-// Where the documentation stops and the twin decides: Stripe retries a failed renewal on its Smart Retries
-// schedule and may then cancel or mark the subscription unpaid; the twin makes no retry (next_payment_attempt
-// is null) and leaves it past_due until the invoice is paid. A paused subscription (pause_collection) is not renewed.
-// - One set to cancel at its period's end is canceled when the period ends, with no renewal
-//   (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle).
-import { runAsVendorMove } from '@volter/world-core';
-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) {
-    // the billing clock is the vendor's own move, wherever a handler reaches it: never the request's caller's
-    return runAsVendorMove(() => advanceBillingDue(ctx, only));
-}
-async function advanceBillingDue(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

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

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

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

package/dist/src/semantics/subscription-schedules.js

@@ -1,119 +0,0 @@
-import { addBillingInterval, buildSubscriptionItemsList } from "../stripe-twin.js";
-import { at, created, fail, finder } from "./shared.js";
-import { storeItems } from "./subscriptions.js";
-const SS = 'subscription_schedule';
-const scheduleMissing = (ctx, id) => fail(ctx, `No such subscription_schedule: '${id}'`, 404, 'resource_missing');
-/** A schedule's phases as Stripe answers them (the served spec's subscription_schedule_phase_configuration): each
- *  starts where the last ended (the first at the schedule's start_date, "now" or a timestamp), and ends at its
- *  end_date or after its duration ("duration: interval, interval_count", the served spec's phases[] parameter) on the
- *  calendar; its currency is its first price's, each item carries its price, quantity and (empty) discounts. Where the
- *  documentation stops and the twin decides: a phase with neither lasts one interval of its first price. */
-function phasesOf(ctx, given, start) {
-    let cursor = start;
-    return given.map((p) => {
-        const items = (Array.isArray(p.items) ? p.items : []).map((it) => ({ price: it.price ?? null, quantity: Math.max(1, Math.trunc(Number(it.quantity) || 1)), discounts: [], metadata: {}, tax_rates: [], billing_thresholds: null }));
-        const price = typeof items[0]?.price === 'string' ? ctx.get('price', items[0].price) : undefined;
-        const recurring = price?.recurring ?? {};
-        const d = p.duration && typeof p.duration === 'object' ? p.duration : undefined;
-        const startDate = cursor;
-        const end = p.end_date !== undefined && p.end_date !== 'now' ? Number(p.end_date)
-            : d ? addBillingInterval(startDate, String(d.interval), Math.max(1, Number(d.interval_count) || 1))
-                : addBillingInterval(startDate, String(recurring.interval ?? 'month'), Math.max(1, Number(recurring.interval_count) || 1));
-        cursor = end;
-        return {
-            add_invoice_items: [], application_fee_percent: null, automatic_tax: { enabled: false, liability: null, disabled_reason: null }, billing_cycle_anchor: null,
-            billing_thresholds: null, collection_method: null, currency: String(price?.currency ?? 'usd'), default_payment_method: null, default_tax_rates: [],
-            description: null, discounts: [], end_date: end, invoice_settings: null, items, metadata: p.metadata && typeof p.metadata === 'object' ? p.metadata : {},
-            on_behalf_of: null, proration_behavior: typeof p.proration_behavior === 'string' ? p.proration_behavior : 'create_prorations', start_date: startDate,
-            transfer_data: null, trial_end: null,
-        };
-    });
-}
-// a schedule starts from a customer or from an existing subscription
-const create = async (ctx) => {
-    const params = ctx.params;
-    const customer = typeof params.customer === 'string' ? params.customer : '';
-    const fromSub = typeof params.from_subscription === 'string' ? params.from_subscription : '';
-    if (!customer && !fromSub)
-        return fail(ctx, 'Missing required param: customer (or from_subscription).', 400, 'parameter_missing');
-    if (customer && !ctx.get('customer', customer))
-        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-    if (fromSub && !ctx.get('subscription', fromSub))
-        return fail(ctx, `No such subscription: '${fromSub}'`, 404, 'resource_missing');
-    // start_date is an instruction ("now" or when), not a field of the schedule
-    const start = params.start_date !== undefined && params.start_date !== 'now' ? Number(params.start_date) : Number(ctx.now());
-    const phases = phasesOf(ctx, Array.isArray(params.phases) ? params.phases : [], start);
-    const { phases: _p, start_date: _s, default_settings: givenDefaults, ...rest } = params;
-    const defaults = givenDefaults && typeof givenDefaults === 'object' ? givenDefaults : {};
-    const schedId = ctx.mint(SS);
-    // a schedule for a customer whose first phase starts now starts its subscription at once, on that phase's items
-    // (docs.stripe.com/billing/subscriptions/subscription-schedules#managing)
-    let subscription = fromSub || null;
-    if (!fromSub && phases.length) {
-        const now = Number(ctx.now());
-        const subId = ctx.mint('subscription');
-        const items = buildSubscriptionItemsList(phases[0].items, subId, now, finder(ctx));
-        await created(ctx, 'subscription', { customer, id: subId }, {
-            status: 'active', livemode: false, currency: 'usd', collection_method: String(params.default_settings?.collection_method ?? 'charge_automatically'),
-            cancel_at_period_end: false, start_date: now, billing_cycle_anchor: now, metadata: {}, discounts: [], billing_schedules: [],
-            trial_start: null, trial_end: null, current_period_start: now, current_period_end: phases[0].end_date, items, schedule: schedId,
-            automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' }, invoice_settings: { issuer: { type: 'self' } },
-        });
-        await storeItems(ctx, subId, items.data ?? []);
-        subscription = subId;
-    }
-    return ctx.reply(await created(ctx, SS, { ...rest, id: schedId }, {
-        status: 'active', livemode: false, phases, current_phase: phases.length ? { start_date: phases[0].start_date, end_date: phases[0].end_date } : null,
-        subscription, released_subscription: null, released_at: null,
-        canceled_at: null, completed_at: null, end_behavior: params.end_behavior ?? 'release',
-        renewal_interval: null, metadata: {}, billing_mode: { type: 'classic' },
-        // "billing_cycle_anchor: Possible values are phase_start or automatic" and invoice_settings are required (the
-        // served spec's default settings); the rest answer what the request set, else null
-        default_settings: {
-            application_fee_percent: defaults.application_fee_percent ?? null, automatic_tax: { enabled: false, liability: null, disabled_reason: null },
-            billing_cycle_anchor: typeof defaults.billing_cycle_anchor === 'string' ? defaults.billing_cycle_anchor : 'automatic', billing_thresholds: null,
-            collection_method: typeof defaults.collection_method === 'string' ? defaults.collection_method : 'charge_automatically', default_payment_method: defaults.default_payment_method ?? null,
-            description: defaults.description ?? null, invoice_settings: { account_tax_ids: null, days_until_due: null, issuer: { type: 'self' } }, on_behalf_of: null, transfer_data: null,
-        },
-        // a schedule made from a subscription is its customer's
-        customer: customer || String(ctx.get('subscription', fromSub)?.customer ?? ''),
-    }));
-};
-function end(kind) {
-    return async (ctx) => {
-        const id = at(ctx, 'schedule');
-        const sched = ctx.get(SS, id);
-        if (!sched)
-            return scheduleMissing(ctx, id);
-        const refused = ctx.legal(SS, 'status', kind === 'cancel' ? 'PostSubscriptionSchedulesScheduleCancel' : 'PostSubscriptionSchedulesScheduleRelease', sched.status, undefined, id);
-        if (refused)
-            return ctx.refuse(refused);
-        const now = ctx.now();
-        const subId = typeof sched.subscription === 'string' ? sched.subscription : undefined;
-        const sub = subId ? ctx.get('subscription', subId) : undefined;
-        // "Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an
-        // active subscription)" (docs.stripe.com/api/subscription_schedules/cancel); releasing "will remove its subscription
-        // property and set the subscription's ID to the released_subscription property", leaving the subscription in place
-        // (docs.stripe.com/api/subscription_schedules/release)
-        if (kind === 'cancel' && subId && sub && sub.status !== 'canceled') {
-            ctx.legal('subscription', 'status', 'PostSubscriptionSchedulesScheduleCancel', String(sub.status), 'canceled', subId);
-            await ctx.write('subscription', subId, { status: 'canceled', canceled_at: now, ended_at: now }, 'subscription.cancel');
-        }
-        if (kind === 'release' && subId && sub)
-            await ctx.write('subscription', subId, { schedule: null }, 'subscription.update');
-        const fields = kind === 'cancel'
-            ? { status: 'canceled', canceled_at: now, current_phase: null }
-            : { status: 'released', released_at: now, released_subscription: subId ?? null, subscription: null, current_phase: null };
-        return ctx.reply(await ctx.write(SS, id, fields, `subscription_schedule.${kind}`));
-    };
-}
-const retrieve = async (ctx) => {
-    const s = ctx.get(SS, at(ctx, 'schedule'));
-    return s ? ctx.reply(s) : scheduleMissing(ctx, at(ctx, 'schedule'));
-};
-export const subscriptionSchedules = {
-    PostSubscriptionSchedules: create,
-    PostSubscriptionSchedulesScheduleCancel: end('cancel'),
-    PostSubscriptionSchedulesScheduleRelease: end('release'),
-    GetSubscriptionSchedulesSchedule: retrieve,
-};

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

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

package/dist/src/semantics/tax.js

@@ -1,197 +0,0 @@
-import { asBool, lineItemEntries, paginate } from "../stripe-twin.js";
-import { at, created, fail, list, newest, path, where } from "./shared.js";
-const TWIN_TAX_RATE_PCT = 10;
-const createRate = async (ctx) => {
-    const params = ctx.params;
-    if (params.display_name === undefined || params.display_name === '')
-        return fail(ctx, 'Missing required param: display_name.', 400, 'parameter_missing');
-    if (params.percentage === undefined)
-        return fail(ctx, 'Missing required param: percentage.', 400, 'parameter_missing');
-    if (params.inclusive === undefined)
-        return fail(ctx, 'Missing required param: inclusive.', 400, 'parameter_missing');
-    return ctx.reply(await created(ctx, 'tax_rate', { ...params, inclusive: asBool(params.inclusive), percentage: Number(params.percentage) }, {
-        active: true, livemode: false, metadata: {},
-        country: null, state: null, jurisdiction: typeof params.jurisdiction === 'string' ? params.jurisdiction : null,
-        jurisdiction_level: null, description: params.description ?? null, display_name: params.display_name,
-        tax_type: null,
-    }));
-};
-const listRates = async (ctx) => list(ctx, 'tax_rate', where(ctx, newest(ctx, 'tax_rate'), {
-    active: (t, v) => asBool(t.active) === asBool(v),
-    inclusive: (t, v) => asBool(t.inclusive) === asBool(v),
-}));
-// percentage and inclusive are fixed once created
-const updateRate = async (ctx) => {
-    const id = at(ctx, 'tax_rate');
-    if (!ctx.get('tax_rate', id))
-        return ctx.notFound('tax_rate', id);
-    const { percentage: _p, inclusive: _i, ...rest } = ctx.params;
-    return ctx.reply(await ctx.write('tax_rate', id, { ...rest, ...('active' in rest ? { active: asBool(rest.active) } : {}) }, 'tax_rate.update'));
-};
-// ── settings: active once a head office is set; the answer has no id ──
-// the defaults' provider: "The tax calculation provider this account uses. Defaults to `stripe` when not using a
-// third-party provider" (the served spec's tax settings defaults); the head office's address answers each line, the
-// lines not given null (the served spec's address: each "(string, nullable)"; the settings page's example answers
-// line2 null)
-const ADDRESS_LINES = ['city', 'country', 'line1', 'line2', 'postal_code', 'state'];
-function settingsBody(stored) {
-    const given = (stored?.head_office ?? null);
-    const address = given && typeof given.address === 'object' && given.address ? given.address : undefined;
-    const headOffice = given ? { ...given, ...(address ? { address: Object.fromEntries(ADDRESS_LINES.map((k) => [k, address[k] ?? null])) } : {}) } : null;
-    const active = !!headOffice;
-    return {
-        object: 'tax.settings', livemode: false,
-        defaults: { provider: 'stripe', ...(stored?.defaults ?? { tax_behavior: null, tax_code: null }) }, head_office: headOffice,
-        status: active ? 'active' : 'pending',
-        status_details: active ? { active: {} } : { pending: { missing_fields: ['head_office'] } },
-    };
-}
-const getSettings = async (ctx) => ctx.reply(settingsBody(ctx.rows('tax.settings')[0]));
-const updateSettings = async (ctx) => {
-    const existing = ctx.rows('tax.settings')[0];
-    const cur = existing ?? {};
-    const defaults = ctx.params.defaults && typeof ctx.params.defaults === 'object' ? ctx.params.defaults : {};
-    const curDefaults = cur.defaults ?? {};
-    const headOffice = ctx.params.head_office && typeof ctx.params.head_office === 'object' ? ctx.params.head_office : undefined;
-    const fields = {
-        defaults: {
-            tax_behavior: typeof defaults.tax_behavior === 'string' ? defaults.tax_behavior : (curDefaults.tax_behavior ?? null),
-            tax_code: typeof defaults.tax_code === 'string' ? defaults.tax_code : (curDefaults.tax_code ?? null),
-        },
-        head_office: headOffice ?? cur.head_office ?? null,
-        livemode: false,
-    };
-    const body = await ctx.write('tax.settings', existing ? String(existing.id) : 'taxset_twin_1', fields, existing ? 'tax_settings.update' : 'tax_settings.create');
-    return ctx.reply(settingsBody(body));
-};
-// ── calculations: each line's tax on top of its amount; no `created`, a tax_date instead ──
-const calcMissing = (ctx, id) => fail(ctx, `No such tax calculation: '${id}'`, 404, 'resource_missing');
-const calculate = async (ctx) => {
-    const params = ctx.params;
-    if (params.currency === undefined || params.currency === '')
-        return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
-    const entries = lineItemEntries(params);
-    if (entries.length === 0)
-        return fail(ctx, 'Missing required param: line_items.', 400, 'parameter_missing');
-    const now = Number(ctx.now());
-    const id = ctx.mint('tax.calculation');
-    const items = entries.map((e, i) => {
-        const amount = Math.max(0, Math.trunc(Number(e.amount) || 0));
-        return {
-            object: 'tax.calculation_line_item', id: `tax_li_${id}_${i + 1}`,
-            amount, amount_tax: Math.round((amount * TWIN_TAX_RATE_PCT) / 100), reference: typeof e.reference === 'string' ? e.reference : null,
-            tax_behavior: 'exclusive', tax_code: typeof e.tax_code === 'string' ? e.tax_code : 'txcd_99999999',
-            quantity: e.quantity === undefined ? 1 : Math.max(1, Math.trunc(Number(e.quantity) || 1)), livemode: false,
-        };
-    });
-    const amountSubtotal = items.reduce((s, it) => s + it.amount, 0);
-    const taxExclusive = items.reduce((s, it) => s + it.amount_tax, 0);
-    const cd = params.customer_details && typeof params.customer_details === 'object' ? params.customer_details : {};
-    return ctx.reply(await created(ctx, 'tax.calculation', {
-        id, currency: String(params.currency), amount_total: amountSubtotal + taxExclusive, tax_amount_exclusive: taxExclusive, tax_amount_inclusive: 0,
-        customer: typeof params.customer === 'string' ? params.customer : null,
-        customer_details: {
-            address: cd.address ?? null, address_source: cd.address_source ?? 'shipping', ip_address: cd.ip_address ?? null,
-            tax_ids: Array.isArray(cd.tax_ids) ? cd.tax_ids : [], taxability_override: cd.taxability_override ?? 'none',
-        },
-        line_items: { object: 'list', data: items, has_more: false, url: `/v1/tax/calculations/${id}/line_items` },
-        shipping_cost: null, tax_date: now,
-        tax_breakdown: taxExclusive > 0 ? [{
-                amount: taxExclusive, inclusive: false, taxability_reason: 'standard_rated', taxable_amount: amountSubtotal,
-                tax_rate_details: { country: null, percentage_decimal: String(TWIN_TAX_RATE_PCT), state: null, tax_type: 'sales_tax' },
-            }] : [],
-        expires_at: now + 90 * 24 * 3600, livemode: false,
-    }, {}, { timeField: 'tax_date' }));
-};
-/** A page of the line items a stored object carries. */
-function linePage(ctx, holder) {
-    const li = holder.line_items;
-    const { page, hasMore } = paginate(Array.isArray(li?.data) ? li.data : [], ctx.params);
-    return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
-}
-const calculationLines = async (ctx) => {
-    const c = ctx.get('tax.calculation', at(ctx, 'calculation'));
-    return c ? linePage(ctx, c) : calcMissing(ctx, at(ctx, 'calculation'));
-};
-// ── registrations ──
-const register = async (ctx) => {
-    const params = ctx.params;
-    if (params.country === undefined || params.country === '')
-        return fail(ctx, 'Missing required param: country.', 400, 'parameter_missing');
-    if (params.active_from === undefined)
-        return fail(ctx, 'Missing required param: active_from.', 400, 'parameter_missing');
-    const now = Number(ctx.now());
-    const activeFrom = params.active_from === 'now' ? now : Number(params.active_from) || now;
-    return ctx.reply(await created(ctx, 'tax.registration', { ...params, active_from: activeFrom }, {
-        status: 'active', expires_at: null, livemode: false,
-        country_options: params.country_options && typeof params.country_options === 'object' ? params.country_options : {},
-    }));
-};
-// ── transactions: committing a calculation, or reversing a transaction with negated amounts ──
-const TX = 'tax.transaction';
-const txMissing = (ctx, id, status = 404) => fail(ctx, `No such tax transaction: '${id}'`, status, 'resource_missing');
-const txLine = (id, i, l, sign, reversal, type) => ({
-    object: 'tax.transaction_line_item', id: `tax_li_${id}_${i + 1}`,
-    amount: sign === 1 ? l.amount : -(Number(l.amount) || 0), amount_tax: sign === 1 ? l.amount_tax : -(Number(l.amount_tax) || 0),
-    reference: l.reference ?? null, tax_behavior: l.tax_behavior ?? 'exclusive', tax_code: l.tax_code ?? 'txcd_99999999',
-    quantity: l.quantity ?? 1, reversal, type, livemode: false, metadata: {},
-});
-const linesOf = (holder) => holder.line_items?.data ?? [];
-const fromCalculation = async (ctx) => {
-    const calcId = typeof ctx.params.calculation === 'string' ? ctx.params.calculation : '';
-    if (!calcId)
-        return fail(ctx, 'Missing required param: calculation.', 400, 'parameter_missing');
-    if (ctx.params.reference === undefined || ctx.params.reference === '')
-        return fail(ctx, 'Missing required param: reference.', 400, 'parameter_missing');
-    const calc = ctx.get('tax.calculation', calcId);
-    if (!calc)
-        return fail(ctx, `No such tax calculation: '${calcId}'`, 400, 'resource_missing');
-    const id = ctx.mint(TX);
-    const now = ctx.now();
-    return ctx.reply(await created(ctx, TX, {
-        id, _stripe_type: 'transaction', reference: ctx.params.reference, currency: calc.currency,
-        customer: calc.customer ?? null, customer_details: calc.customer_details ?? {},
-        tax_date: now, livemode: false, posted_at: now,
-        line_items: { object: 'list', data: linesOf(calc).map((l, i) => txLine(id, i, l, 1, null, 'transaction')), has_more: false, url: `/v1/tax/transactions/${id}/line_items` },
-        shipping_cost: calc.shipping_cost ?? null, reversal: null, calculation: calcId, metadata: {},
-    }, {}));
-};
-const reversal = async (ctx) => {
-    const original = typeof ctx.params.original_transaction === 'string' ? ctx.params.original_transaction : '';
-    if (!original)
-        return fail(ctx, 'Missing required param: original_transaction.', 400, 'parameter_missing');
-    if (ctx.params.reference === undefined || ctx.params.reference === '')
-        return fail(ctx, 'Missing required param: reference.', 400, 'parameter_missing');
-    const mode = typeof ctx.params.mode === 'string' ? ctx.params.mode : '';
-    if (mode !== 'full' && mode !== 'partial')
-        return fail(ctx, 'Missing required param: mode (full or partial).', 400, 'parameter_missing');
-    const orig = ctx.get(TX, original);
-    if (!orig)
-        return txMissing(ctx, original, 400);
-    const id = ctx.mint(TX);
-    const now = ctx.now();
-    return ctx.reply(await created(ctx, TX, {
-        id, _stripe_type: 'reversal', reference: ctx.params.reference, currency: orig.currency,
-        customer: orig.customer ?? null, customer_details: orig.customer_details ?? {},
-        tax_date: now, livemode: false, posted_at: now,
-        line_items: { object: 'list', data: linesOf(orig).map((l, i) => txLine(id, i, l, -1, { original_line_item: l.id }, 'reversal')), has_more: false, url: `/v1/tax/transactions/${id}/line_items` },
-        shipping_cost: null, reversal: { original_transaction: original, mode }, metadata: {},
-    }, {}));
-};
-const transactionLines = async (ctx) => {
-    const t = ctx.get(TX, at(ctx, 'transaction'));
-    return t ? linePage(ctx, t) : txMissing(ctx, at(ctx, 'transaction'));
-};
-export const tax = {
-    PostTaxRates: createRate,
-    GetTaxRates: listRates,
-    PostTaxRatesTaxRate: updateRate,
-    GetTaxSettings: getSettings,
-    PostTaxSettings: updateSettings,
-    PostTaxCalculations: calculate,
-    GetTaxCalculationsCalculationLineItems: calculationLines,
-    PostTaxRegistrations: register,
-    PostTaxTransactionsCreateFromCalculation: fromCalculation,
-    PostTaxTransactionsCreateReversal: reversal,
-    GetTaxTransactionsTransactionLineItems: transactionLines,
-};

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

@@ -1,5 +0,0 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-/** Time's settling of top-ups, caught up to the World's clock: a pending top-up succeeds on its expected_availability_date,
- *  its funds entered then in the balance it names. */
-export declare function settleTopups(ctx: SemanticsContext): Promise<void>;
-export declare const terminal: Record<string, Semantics>;