@volter/twin-stripe 2.0.38 → 3.0.1

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

@@ -1,11 +1,6 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** A `trial_end` Stripe refuses: the parameter is `"now" | timestamp` (docs.stripe.com/api/subscriptions/update), and a
- *  timestamp that is not in the future answers "Invalid timestamp: must be an integer Unix timestamp in the future."
- *  (Stripe's own message, as its SDKs' users report it: github.com/stripe/stripe-dotnet/issues/805,
- *  github.com/stripe/stripe-ruby/issues/682). Where the documentation stops and the twin decides: a value that is no
- *  number at all, and one more than two years on, answer that same message. */
-export declare function trialEndRefused(ctx: SemanticsContext, value: unknown, now: number): Response | undefined;
-/** A new subscription's items, each its own subscription_item as Stripe keeps it (/v1/subscription_items/{id}). */
-export declare function storeItems(ctx: SemanticsContext, subId: string, items: Row[]): Promise<void>;
-export declare const subscriptions: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function DeleteSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response>;
+export declare function GetSubscriptions(ctx: HandlerContext): Promise<Response>;
+export declare function GetSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response>;
+export declare function PostSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response>;
+export declare function DeleteSubscriptionsSubscriptionExposedIdDiscount(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/subscriptions.js

@@ -1,326 +1,46 @@
-import { addBillingInterval, applyCouponDiscount, asBool, buildDiscount, buildSubscriptionItemsList, cardError, declineFor, mintClientSecret, priceAmount, resolveSubscriptionBillingInterval, resolveTrial, subscriptionCouponParam, subscriptionHasPrice, subscriptionItemEntries, subscriptionItemPrice, } from "../stripe-twin.js";
-import { finalizedFields } from "./invoices.js";
-import { mintCharge } from "./payment-intents.js";
-import { advanceBilling, clockNow, collectSubscriptionInvoice, draftSubscriptionInvoice, itemQuantity, keptAfter, payerOf, spendOnceCoupon } from "./renewals.js";
-import { at, created, deletedDiscount, expanded, fail, finder, list, newest, redeemCoupon, search, send, where } from "./shared.js";
-const SUB = 'subscription';
-const subMissing = (ctx, id) => fail(ctx, `No such subscription: '${id}'`, 404, 'resource_missing');
-const create = async (ctx) => {
-    const params = ctx.params;
-    const customer = typeof params.customer === 'string' ? params.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-    if (!ctx.get('customer', customer))
-        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-    const now = clockNow(ctx, customer);
-    const badTrial = trialEndRefused(ctx, params.trial_end, now);
-    if (badTrial)
-        return badTrial;
-    // a coupon (or discounts[0][coupon]) must exist; it becomes the subscription's discount
-    const couponId = subscriptionCouponParam(params);
-    let discounts = [];
-    if (couponId) {
-        const coupon = ctx.get('coupon', couponId);
-        if (!coupon)
-            return fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
-        discounts = [buildDiscount(coupon, customer, now)];
-    }
-    // a trial is the current period; otherwise one billing interval of the first item's price. The
-    // period sits top-level: this twin's default API version predates basil moving it onto items.
-    const trial = resolveTrial(params, now);
-    const itemEntries = subscriptionItemEntries(params.items);
-    const { interval, interval_count } = resolveSubscriptionBillingInterval(itemEntries, finder(ctx));
-    const periodStart = trial ? trial.start : now;
-    const periodEnd = trial ? trial.end : addBillingInterval(now, interval, interval_count);
-    const subId = typeof params.id === 'string' && params.id ? params.id : ctx.mint(SUB);
-    const itemsList = buildSubscriptionItemsList(itemEntries, subId, now, finder(ctx));
-    const itemsData = itemsList.data;
-    const currency = typeof params.currency === 'string' && params.currency ? params.currency : 'usd';
-    // Stripe opens a subscription's first invoice at once (a trialing one has nothing due yet) and, by
-    // payment_behavior (docs.stripe.com/api/subscriptions/create#create_subscription-payment_behavior):
-    // allow_incomplete (the default) charges the default payment method now, and without one, or on a decline,
-    // leaves the subscription incomplete with the invoice open; error_if_incomplete refuses the create instead;
-    // default_incomplete never charges, leaving a PaymentIntent the frontend confirms.
-    const behavior = typeof params.payment_behavior === 'string' ? params.payment_behavior : 'allow_incomplete';
-    const needsFirstInvoice = !trial;
-    const holder = ctx.get('customer', customer) ?? {};
-    const payWith = behavior === 'default_incomplete' ? undefined
-        : (typeof params.default_payment_method === 'string' ? params.default_payment_method : undefined) ?? holder.invoice_settings?.default_payment_method ?? undefined;
-    const declined = payWith ? declineFor(finder(ctx), { payment_method: payWith }) : undefined;
-    let subtotal = 0;
-    for (const it of itemsData) {
-        const price = it.price && typeof it.price === 'object' ? it.price : undefined;
-        subtotal += priceAmount(price, itemQuantity(it));
-    }
-    const coupon = discounts[0]?.coupon;
-    const discountAmount = applyCouponDiscount(subtotal, coupon);
-    const invoiceTotal = Math.max(0, subtotal - discountAmount);
-    // a $0 first invoice is paid at once and needs no PaymentIntent
-    const isFree = invoiceTotal <= 0;
-    const pays = needsFirstInvoice && !isFree && !!payWith && !declined;
-    if (needsFirstInvoice && !isFree && !pays && behavior === 'error_if_incomplete')
-        return firstPaymentRefused(ctx, declined);
-    // minted first so the subscription names its latest_invoice in its own create (a trial's $0 invoice too)
-    const invoiceId = needsFirstInvoice ? ctx.mint('invoice') : null;
-    const trialInvoiceId = needsFirstInvoice ? null : ctx.mint('invoice');
-    const piId = needsFirstInvoice && !isFree ? ctx.mint('payment_intent') : null;
-    const { coupon: _c, discounts: _ds, trial_period_days: _tpd, trial_end: _te, items: _items, id: _id, ...rest } = params;
-    const sub = await created(ctx, SUB, { ...rest, id: subId }, {
-        status: trial ? 'trialing' : needsFirstInvoice && !isFree && !pays ? 'incomplete' : 'active',
-        livemode: false, currency, collection_method: 'charge_automatically',
-        // a trial's end is the billing anchor: "The `billing_cycle_anchor` will be updated to the `trial_end` value"
-        // (docs.stripe.com/api/subscriptions/create#create_subscription-trial_end)
-        cancel_at_period_end: false, start_date: now, billing_cycle_anchor: trial ? trial.end : now, metadata: {},
-        discounts: discounts.map((d) => ({ ...d, subscription: subId })), billing_schedules: [],
-        ...(trial ? { trial_start: trial.start, trial_end: trial.end } : { trial_start: null, trial_end: null }),
-        current_period_start: periodStart, current_period_end: periodEnd,
-        items: itemsList,
-        latest_invoice: invoiceId ?? trialInvoiceId,
-        automatic_tax: { enabled: false, liability: null },
-        billing_mode: { type: 'classic' },
-        invoice_settings: { issuer: { type: 'self' } },
-    });
-    await storeItems(ctx, subId, itemsData);
-    if (discounts.length)
-        await redeemCoupon(ctx, couponId);
-    // a customer billed for the first time takes the subscription's currency
-    if (!holder.currency)
-        await ctx.write('customer', customer, { currency }, 'customer.update');
-    if (!invoiceId) {
-        // a trial's subscription still opens an invoice at once: "An immediate invoice is still created, but the amount is 0"
-        // (docs.stripe.com/billing/subscriptions/trials/free-trials); finalizing it spends a once coupon (renewals.ts)
-        const trialInvoice = await draftSubscriptionInvoice(ctx, ctx.get(SUB, subId) ?? sub, { start: periodStart, end: periodEnd, reason: 'subscription_create', trial: true, ...(trialInvoiceId ? { id: trialInvoiceId } : {}) });
-        await collectSubscriptionInvoice(ctx, trialInvoice, now, 'api');
-        return ctx.reply(expanded(ctx, SUB, ctx.get(SUB, subId) ?? sub));
-    }
-    // the default payment method pays the first invoice now: its charge (with its ledger entry) comes first
-    const chargeId = pays && piId ? await mintCharge(ctx, piId, { currency, customer, payment_method: payWith, invoice: invoiceId }, invoiceTotal) : null;
-    const invoiceLines = itemsData.map((it, i) => {
-        const price = it.price && typeof it.price === 'object' ? it.price : undefined;
-        const quantity = itemQuantity(it);
-        return {
-            id: `il_twin_${invoiceId}_${i + 1}`, object: 'line_item', type: 'subscription',
-            amount: priceAmount(price, quantity), currency, quantity, proration: false,
-            price: it.price ?? null, subscription: subId, invoice_item: null, subscription_item: it.id ?? null,
-            period: { start: periodStart, end: periodEnd }, description: null,
-        };
-    });
-    await created(ctx, 'invoice', {
-        id: invoiceId,
-        ...finalizedFields(ctx, { id: invoiceId, customer }, now),
-        status: isFree || pays ? 'paid' : 'open', livemode: false, currency, collection_method: 'charge_automatically',
-        auto_advance: !(isFree || pays), attempt_count: payWith && !isFree ? 1 : 0, attempted: !isFree && behavior !== 'default_incomplete',
-        customer, subscription: subId, billing_reason: 'subscription_create', charge: chargeId,
-        amount_due: invoiceTotal, amount_paid: isFree || pays ? invoiceTotal : 0, amount_remaining: isFree || pays ? 0 : invoiceTotal,
-        amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
-        subtotal, total: invoiceTotal, starting_balance: 0,
-        post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
-        period_start: periodStart, period_end: periodEnd,
-        default_tax_rates: [], discounts: discounts[0] ? [discounts[0]] : [],
-        lines: { object: 'list', data: invoiceLines, has_more: false, total_count: invoiceLines.length, url: `/v1/invoices/${invoiceId}/lines` },
-        automatic_tax: { enabled: false, liability: null, status: null },
-        status_transitions: { finalized_at: now, marked_uncollectible_at: null, paid_at: isFree || pays ? now : null, voided_at: null },
-        issuer: { type: 'self' },
-        payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
-        payment_intent: piId,
-    }, {});
-    if (piId) {
-        // paid by the default payment method, or waiting on one (declined, absent, or collected client-side)
-        await created(ctx, 'payment_intent', { id: piId, amount: invoiceTotal, currency, customer, invoice: invoiceId, ...(payWith ? { payment_method: pays ? payWith : null } : {}) }, {
-            status: pays ? 'succeeded' : 'requires_payment_method', client_secret: mintClientSecret(piId), livemode: false,
-            capture_method: 'automatic', amount_capturable: 0, amount_received: pays ? invoiceTotal : 0, next_action: null,
-            latest_charge: chargeId,
-            last_payment_error: declined ? { type: 'card_error', code: declined.code, decline_code: declined.decline_code ?? null, message: declined.message, payment_method: { id: payWith } } : null,
-            automatic_payment_methods: null, payment_method_types: ['card', 'link'], payment_method_options: {},
-        });
-    }
-    // the first invoice is finalized: the `once` coupon it took is spent (renewals.ts spendOnceCoupon)
-    await spendOnceCoupon(ctx, ctx.get('invoice', invoiceId) ?? {});
-    return ctx.reply(expanded(ctx, SUB, ctx.get(SUB, subId) ?? sub));
-};
-const listSubscriptions = async (ctx) => {
+import { keptAfter } from "../engine/renewals.js";
+import { asBool, nowUnix, subscriptionCouponParam, subscriptionHasPrice, subscriptionItemEntries } from "../engine/stripe.js";
+import { pauseCollection, SUB } from "../engine/subscriptions.js";
+import { resourceView, advanceBilling, applyItemChanges, applyTrialEnd, at, clockNow, collectSubscriptionInvoice, expanded, itemChangesRefused, list, newest, redeemCoupon, replacedDiscounts, subMissing, trialEndBlocked, trialEndRefused, where } from "./shared.js";
+import { deletedDiscount } from "../engine/common.js";
+import { fail } from "./shared.js";
+// canceling keeps the subscription, now canceled, stamped with when it was canceled and ended
+// (https://docs.stripe.com/api/subscriptions/object#subscription_object-canceled_at, #subscription_object-ended_at)
+export async function DeleteSubscriptionsSubscriptionExposedId(ctx) {
+    const id = at(ctx, 'subscription_exposed_id');
+    const sub = resourceView(ctx, SUB, id);
+    if (!sub)
+        return subMissing(ctx, id);
+    const refused = ctx.legal(SUB, 'status', 'DeleteSubscriptionsSubscriptionExposedId', sub.status, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    const now = nowUnix(ctx.occurredAt);
+    // why it was canceled: the request's `cancellation_details` ("Details about why this subscription was cancelled"), and
+    // the reason Stripe records for a cancel asked through the API, as the cancel page's example answers it:
+    // `"reason": "cancellation_requested"` (docs.stripe.com/api/subscriptions/cancel)
+    const given = ctx.params.cancellation_details && typeof ctx.params.cancellation_details === 'object' ? ctx.params.cancellation_details : {};
+    const cancellation_details = { comment: given.comment ?? null, feedback: given.feedback ?? null, reason: 'cancellation_requested' };
+    return ctx.reply(ctx.expand(SUB, await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel')));
+}
+export async function GetSubscriptions(ctx) {
     await advanceBilling(ctx);
     return list(ctx, SUB, where(ctx, newest(ctx, SUB), {
         customer: (s, v) => s.customer === v,
         status: (s, v) => (v === 'all' ? true : s.status === v),
         price: (s, v) => subscriptionHasPrice(s, String(v)),
     }));
-};
-const searchSubscriptions = async (ctx) => {
-    await advanceBilling(ctx);
-    return search(ctx, SUB);
-};
-const retrieveSubscription = async (ctx) => {
+}
+export async function GetSubscriptionsSubscriptionExposedId(ctx) {
     const id = at(ctx, 'subscription_exposed_id');
     await advanceBilling(ctx, (sub) => sub.id === id);
-    const sub = ctx.get(SUB, id);
+    const sub = resourceView(ctx, SUB, id);
     return sub ? ctx.reply(expanded(ctx, SUB, sub)) : subMissing(ctx, id);
-};
-// pause_collection pauses billing (the subscription stays active; the paused event fires) and
-// clearing it resumes; cancel_at_period_end schedules or withdraws a cancel; a coupon replaces the
-// discount and an empty one clears it
-/** pause_collection pauses billing (the paused event fires) and clearing it resumes
- *  (docs.stripe.com/billing/subscriptions/pause-payment); answers the event, or nothing for a value it does not take. */
-function pauseCollection(pc, fields) {
-    const isClear = pc === '' || pc === null || (typeof pc === 'object' && pc !== null && Object.keys(pc).length === 0);
-    if (isClear) {
-        fields.pause_collection = null;
-        return 'customer.subscription.resumed';
-    }
-    if (!pc || typeof pc !== 'object')
-        return undefined;
-    const p = pc;
-    fields.pause_collection = { behavior: typeof p.behavior === 'string' ? p.behavior : 'void', resumes_at: p.resumes_at !== undefined ? Number(p.resumes_at) : null };
-    return 'customer.subscription.paused';
-}
-/** A coupon that replaces the subscription's discount, or an empty one that clears it (docs.stripe.com/api/subscriptions/update#update_subscription-discounts). */
-function replacedDiscounts(ctx, couponId, sub) {
-    if (couponId === '')
-        return [];
-    const coupon = ctx.get('coupon', couponId);
-    return coupon ? [buildDiscount(coupon, String(sub.customer ?? ''), Number(ctx.now()), { subscription: String(sub.id) })] : fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
-}
-/** The longest trial Stripe takes: `trial_end` "Can be at most two years from `billing_cycle_anchor`"
- *  (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end); "The trial period must be 730 days (2 years)
- *  or less" (docs.stripe.com/billing/subscriptions/trials/free-trials). */
-const MAX_TRIAL = 730 * 86400;
-/** A `trial_end` Stripe refuses: the parameter is `"now" | timestamp` (docs.stripe.com/api/subscriptions/update), and a
- *  timestamp that is not in the future answers "Invalid timestamp: must be an integer Unix timestamp in the future."
- *  (Stripe's own message, as its SDKs' users report it: github.com/stripe/stripe-dotnet/issues/805,
- *  github.com/stripe/stripe-ruby/issues/682). Where the documentation stops and the twin decides: a value that is no
- *  number at all, and one more than two years on, answer that same message. */
-export function trialEndRefused(ctx, value, now) {
-    const t = typeof value === 'number' ? value : typeof value === 'string' && /^\d+$/.test(value.trim()) ? Number(value) : NaN;
-    return value === undefined || value === 'now' || (Number.isInteger(t) && t > now && t <= now + MAX_TRIAL) ? undefined : invalidTrialEnd(ctx);
-}
-function invalidTrialEnd(ctx) {
-    return ctx.refuse({ status: 400, param: 'trial_end', message: 'Invalid timestamp: must be an integer Unix timestamp in the future.' });
-}
-/** An update's `trial_end` on the subscription, into `fields`.
- *
- *  `now` on a trialing subscription ends its trial at once: "The special value `now` can be provided to end the customer's
- *  trial immediately" (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end; the trials guide's "To end a
- *  trial early … setting the `trial_end` value to … **now** to end immediately", docs.stripe.com/billing/subscriptions/
- *  trials/free-trials). The update resets the billing date and charges at once: "Switching prices does not normally change
- *  the billing date or generate an immediate charge unless … A trial starts or ends. In these cases, we … immediately
- *  charge the customer using the new price, and reset the billing date" (docs.stripe.com/api/subscriptions/update), and
- *  "Stripe immediately attempts payment when a subscription's billing cycle anchor is reset … When billing is performed
- *  immediately, but the required payment fails, the subscription change request succeeds and the subscription transitions
- *  to `past_due`" (docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment). So a new period starts now,
- *  its invoice is made (`invoice.created`) and charged to the subscription's default payment method, else the
- *  customer's (paid: `invoice.paid`, the subscription `active`; declined or none: the invoice open, `past_due`), and the
- *  subscription's own write sends `customer.subscription.updated`. `payment_behavior` (the same page): `error_if_incomplete`
- *  answers 402 and leaves the subscription as it was, `default_incomplete` leaves the invoice open without an attempt.
- *
- *  A future timestamp moves the trial's end, and the period and billing anchor with it: "The `billing_cycle_anchor` will be
- *  updated to the `trial_end` value" (the same parameter); on a subscription out of its trial it starts a new one ("You can
- *  add a new trial on a non-trialing subscription by updating the subscription while specifying trial_end", and for
- *  classic billing mode "the `trial_start` field remains set to the start of the first trial", docs.stripe.com/billing/
- *  subscriptions/trials/free-trials).
- *
- *  Where the documentation stops and the twin decides: the invoice's billing_reason is `subscription_update` ("A
- *  subscription was updated", docs.stripe.com/api/invoices/object#invoice_object-billing_reason); `now` on a subscription
- *  that is not trialing has no trial to end and changes nothing; the credit Stripe prorates for the unused time when a new
- *  trial starts mid-period is not made (as `proration_behavior=none` would have it); `pending_if_incomplete` answers as
- *  `allow_incomplete` (no pending update is modelled). Answers a refusal, or the invoice to collect once the subscription is written. */
-async function applyTrialEnd(ctx, sub, fields, now) {
-    const value = ctx.params.trial_end;
-    delete fields.trial_end;
-    const id = String(sub.id);
-    if (value !== 'now' || sub.status !== 'trialing')
-        return value === 'now' ? undefined : movedTrial(sub, fields, Number(value), now);
-    // the period's invoice bills the items as this update leaves them, under its discount
-    const next = { ...sub, ...fields, items: ctx.get(SUB, id)?.items ?? sub.items };
-    const { interval, interval_count } = resolveSubscriptionBillingInterval((next.items?.data) ?? [], finder(ctx));
-    const period = { start: now, end: addBillingInterval(now, interval, interval_count) };
-    const invoice = await draftSubscriptionInvoice(ctx, next, { ...period, reason: 'subscription_update' });
-    Object.assign(fields, { trial_end: now, billing_cycle_anchor: now, current_period_start: period.start, current_period_end: period.end, latest_invoice: invoice });
-    const payer = trialPayer(ctx, sub);
-    return { invoice, ...(payer ? { payer } : {}), attempt: ctx.params.payment_behavior !== 'default_incomplete' };
-}
-/** A trial moved to end at `end`, or a new one to `end` on a subscription out of its trial (applyTrialEnd). */
-function movedTrial(sub, fields, end, now) {
-    Object.assign(fields, {
-        status: 'trialing', trial_end: end, trial_start: sub.trial_start ?? now, billing_cycle_anchor: end,
-        current_period_end: end, ...(sub.status !== 'trialing' ? { current_period_start: now } : {}),
-    });
-    return undefined;
-}
-/** What ending the trial charges: the update's own default payment method, else the subscription's, else its customer's. */
-function trialPayer(ctx, sub) {
-    const given = ctx.params.default_payment_method;
-    return typeof given === 'string' && given ? given : payerOf(ctx, sub);
 }
-/** What an update's `trial_end` refuses before anything is written: a new trial the machine does not allow from the
- *  subscription's status, or, under `error_if_incomplete`, ending a trial that cannot be paid at once ("If payment fails,
- *  return an HTTP `402` status code and don't update the subscription", docs.stripe.com/api/subscriptions/update). */
-function trialEndBlocked(ctx, sub, discounts) {
-    if (ctx.params.trial_end !== 'now')
-        return newTrialRefused(ctx, sub);
-    if (sub.status !== 'trialing')
-        return undefined;
-    const charge = trialEndCharge(ctx, sub, discounts);
-    if (ctx.params.payment_behavior === 'error_if_incomplete' && charge.due > 0 && !charge.pays)
-        return firstPaymentRefused(ctx, charge.declined);
-    // the move ending the trial makes (paid or nothing due: active; else past_due) is the machine's, asked before
-    // anything is written
-    const refused = ctx.legal(SUB, 'status', ctx.call.operation.id, 'trialing', charge.due <= 0 || charge.pays ? 'active' : 'past_due', String(sub.id));
-    return refused ? ctx.refuse(refused) : undefined;
-}
-/** A price named by id, or given as an object. */
-function priceRow(ctx, price) {
-    return typeof price === 'string' ? ctx.get('price', price) : price && typeof price === 'object' ? price : undefined;
-}
-/** One period of the subscription's items as an update's `items` would leave them, before any discount: an entry naming
- *  an item changes its price and quantity (a new price resets the quantity to 1 unless one is given) or deletes it, and
- *  one naming none adds an item (applyItemChanges). */
-function dueAfter(ctx, sub, entries) {
-    const lines = new Map();
-    for (const it of (sub.items?.data) ?? [])
-        lines.set(String(it.id), { price: priceRow(ctx, it.price), quantity: itemQuantity(it) });
-    entries.forEach((e, i) => entryAfter(ctx, lines, e, i));
-    return [...lines.values()].reduce((sum, l) => sum + priceAmount(l.price, l.quantity), 0);
-}
-/** One entry of an update's `items` on the lines it would leave (dueAfter). */
-function entryAfter(ctx, lines, e, i) {
-    // an inline price bills as the Price inlinePrice makes of it
-    const d = e.price_data && typeof e.price_data === 'object' ? e.price_data : undefined;
-    const inline = d ? (d.unit_amount_decimal !== undefined ? { unit_amount_decimal: String(d.unit_amount_decimal) } : { unit_amount: Math.trunc(Number(d.unit_amount) || 0) }) : undefined;
-    const price = typeof e.price === 'string' && e.price ? priceRow(ctx, e.price) : inline;
-    const named = typeof e.id === 'string' && e.id;
-    const key = named ? String(e.id) : `new_${i}`;
-    // only a named item is deleted; an entry naming none adds one, as applyItemChanges does
-    if (named && asBool(e.deleted)) {
-        lines.delete(key);
-        return;
-    }
-    const was = lines.get(key);
-    const quantity = e.quantity !== undefined ? Math.max(0, Math.trunc(Number(e.quantity) || 0)) : price && was && price.id !== was.price?.id ? 1 : was?.quantity ?? 1;
-    lines.set(key, { price: price ?? was?.price, quantity });
-}
-/** A new trial on a subscription whose status the machine does not let start one. */
-function newTrialRefused(ctx, sub) {
-    const refused = sub.status === 'trialing' ? undefined : ctx.legal(SUB, 'status', ctx.call.operation.id, sub.status, 'trialing', String(sub.id));
-    return refused ? ctx.refuse(refused) : undefined;
-}
-/** What ending the trial charges, judged before anything is written: the period of the items as this update leaves them
- *  (dueAfter) under the discount it leaves, and whether the payer pays it (an attempt made, a payer, no decline). */
-function trialEndCharge(ctx, sub, discounts) {
-    const subtotal = dueAfter(ctx, sub, subscriptionItemEntries(ctx.params.items));
-    // the discount the subscription carries after this update takes this invoice (renewals.ts draftSubscriptionInvoice)
-    const discount = (discounts ?? sub.discounts ?? [])[0];
-    const coupon = discount && typeof discount === 'object' ? discount.coupon : undefined;
-    const due = subtotal - (coupon ? applyCouponDiscount(subtotal, coupon) : 0);
-    const payer = trialPayer(ctx, sub);
-    const attempt = ctx.params.payment_behavior !== 'default_incomplete';
-    const declined = payer && attempt ? declineFor(finder(ctx), { payment_method: payer }) : undefined;
-    return { due, pays: attempt && !!payer && !declined, ...(declined ? { declined } : {}) };
-}
-const update = async (ctx) => {
+export async function PostSubscriptionsSubscriptionExposedId(ctx) {
     const id = at(ctx, 'subscription_exposed_id');
     // a period that has already ended renews (or a trial that has, ends) before the update applies (renewals.ts)
     await advanceBilling(ctx, (s) => s.id === id);
-    const sub = ctx.get(SUB, id);
+    const sub = resourceView(ctx, SUB, id);
     if (!sub)
         return subMissing(ctx, id);
     const params = ctx.params;
@@ -362,7 +82,7 @@ const update = async (ctx) => {
     // scheduled cancel follows a period this update moves
     if ('cancel_at_period_end' in params) {
         fields.cancel_at_period_end = asBool(params.cancel_at_period_end);
-        Object.assign(fields, fields.cancel_at_period_end ? { cancel_at: fields.current_period_end ?? sub.current_period_end ?? null, canceled_at: Number(ctx.now()) } : { cancel_at: null, canceled_at: null });
+        Object.assign(fields, fields.cancel_at_period_end ? { cancel_at: fields.current_period_end ?? sub.current_period_end ?? null, canceled_at: Number(nowUnix(ctx.occurredAt)) } : { cancel_at: null, canceled_at: null });
     }
     else if (sub.cancel_at_period_end === true && fields.current_period_end !== undefined)
         fields.cancel_at = fields.current_period_end;
@@ -375,231 +95,18 @@ const update = async (ctx) => {
         if (fields.discounts !== undefined)
             fields.discounts = keptAfter(fields.discounts, ctx.get('invoice', trial.invoice) ?? {});
     }
-    return ctx.reply(await ctx.write(SUB, id, fields, op));
-};
-/** A new item named with neither `price` nor `price_data`: "One of `price` or `price_data` is required"
- *  (docs.stripe.com/api/subscriptions/update). */
-function noItemPrice(ctx) {
-    return fail(ctx, 'Missing required param: items[price].', 400, 'parameter_missing');
-}
-/** A subscription asked to fail when its first invoice cannot be paid at once (payment_behavior=error_if_incomplete):
- *  the card's decline, or no payment method to charge (docs.stripe.com/api/subscriptions/create#create_subscription-payment_behavior). */
-function firstPaymentRefused(ctx, declined) {
-    return declined ? send(ctx, cardError(declined)) : fail(ctx, 'This customer has no attached payment source or default payment method.', 400, 'resource_missing');
-}
-/** An update's `items`: "A list of up to 20 subscription items, each with an attached price"
- *  (docs.stripe.com/api/subscriptions/update): an entry naming an item's `id` changes that item (its price, quantity,
- *  metadata) or, with `deleted` ("A flag that, if set to `true`, will delete the specified item"), removes it; "If you
- *  omit `id`, the API adds a new subscription item rather than updating the existing one". Each takes `price` or
- *  `price_data`, "Data used to generate a new Price object inline. One of `price` or `price_data` is required", and
- *  "When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided". An
- *  inline price is made as the manage-prices guide says: "By default, prices created with `price_data` are effectively
- *  archived (they're marked as `active=false`)" (docs.stripe.com/products-prices/manage-prices).
- *  Where the documentation stops and the twin decides: the update is all or nothing, every entry checked before any is
- *  written (Stripe answers one error for the request); the refusals are worded by the twin. */
-async function applyItemChanges(ctx, subId, entries) {
-    // every entry is checked first: a refusal leaves the subscription as it was
-    const refused = itemChangesRefused(ctx, subId, entries);
-    if (refused)
-        return refused;
-    return writeItemChanges(ctx, subId, entries);
-}
-/** The refusal of an update's `items`, checked entry by entry before any is written (applyItemChanges). */
-function itemChangesRefused(ctx, subId, entries) {
-    for (const entry of entries) {
-        const priceRef = typeof entry.price === 'string' && entry.price ? entry.price : undefined;
-        if (priceRef && !ctx.get('price', priceRef))
-            return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
-        const inline = !priceRef && entry.price_data && typeof entry.price_data === 'object' ? entry.price_data : undefined;
-        if (inline) {
-            const refused = refuseInlinePrice(ctx, inline);
-            if (refused)
-                return refused;
-        }
-        if (typeof entry.id === 'string' && entry.id) {
-            const si = ctx.get('subscription_item', entry.id);
-            if (!si || si.subscription !== subId)
-                return fail(ctx, `No such subscription_item: '${entry.id}'`, 400, 'resource_missing');
-        }
-        else if (!priceRef && !inline)
-            return noItemPrice(ctx);
-    }
-    return undefined;
-}
-/** An update's checked `items`, written. */
-async function writeItemChanges(ctx, subId, entries) {
-    for (const entry of entries) {
-        const inline = typeof entry.price === 'string' && entry.price ? undefined : entry.price_data && typeof entry.price_data === 'object' ? entry.price_data : undefined;
-        const priceRef = typeof entry.price === 'string' && entry.price ? entry.price : inline ? await inlinePrice(ctx, inline) : undefined;
-        // only a price that changes resets the quantity; one naming the item's own price leaves it
-        const was = typeof entry.id === 'string' && entry.id ? ctx.get('subscription_item', entry.id)?.price : undefined;
-        const wasId = typeof was === 'string' ? was : was && typeof was === 'object' ? String(was.id ?? '') : undefined;
-        const quantity = entry.quantity !== undefined ? { quantity: Math.max(0, Math.trunc(Number(entry.quantity) || 0)) } : priceRef && priceRef !== wasId ? { quantity: 1 } : {};
-        const metadata = entry.metadata && typeof entry.metadata === 'object' ? { metadata: entry.metadata } : {};
-        if (typeof entry.id === 'string' && entry.id) {
-            if (asBool(entry.deleted)) {
-                await ctx.write('subscription_item', entry.id, { deleted: true }, 'subscription_item.delete');
-                continue;
-            }
-            await ctx.write('subscription_item', entry.id, { ...(priceRef ? subscriptionItemPrice(priceRef, finder(ctx)) : {}), ...quantity, ...metadata }, 'subscription_item.update');
-        }
-        else {
-            await created(ctx, 'subscription_item', { subscription: subId, ...subscriptionItemPrice(priceRef, finder(ctx)), quantity: 1, ...quantity, ...metadata }, { livemode: false, metadata: {}, discounts: [], tax_rates: [], billing_thresholds: null });
-        }
-    }
-    await syncItems(ctx, subId);
-    return undefined;
-}
-/** A subscription item's `price_data` Stripe would refuse: its required `currency`, `product` (an existing one) and
- *  `recurring[interval]`, and "Only one of `unit_amount` and `unit_amount_decimal` can be set". */
-function refuseInlinePrice(ctx, d) {
-    for (const name of ['currency', 'product'])
-        if (typeof d[name] !== 'string' || !d[name])
-            return fail(ctx, `Missing required param: items[price_data][${name}].`, 400, 'parameter_missing');
-    if (!ctx.get('product', String(d.product)))
-        return fail(ctx, `No such product: '${String(d.product)}'`, 400, 'resource_missing');
-    const interval = d.recurring?.interval;
-    if (!['day', 'week', 'month', 'year'].includes(String(interval)))
-        return fail(ctx, 'Missing required param: items[price_data][recurring][interval].', 400, 'parameter_missing');
-    if (d.unit_amount !== undefined && d.unit_amount_decimal !== undefined)
-        return fail(ctx, 'Only one of `unit_amount` and `unit_amount_decimal` can be set.', 400, 'parameter_invalid');
-    return undefined;
-}
-/** The inline Price a `price_data` generates: recurring, archived (active=false). Answers its id. */
-async function inlinePrice(ctx, d) {
-    const r = d.recurring;
-    const decimal = d.unit_amount_decimal !== undefined ? String(d.unit_amount_decimal) : String(Math.trunc(Number(d.unit_amount) || 0));
-    const price = await created(ctx, 'price', {
-        product: d.product, currency: String(d.currency).toLowerCase(),
-        // a decimal amount that is not a whole number of the smallest unit has no integer unit_amount (as semantics/plans.ts)
-        unit_amount: d.unit_amount_decimal !== undefined ? (Number.isInteger(Number(d.unit_amount_decimal)) ? Number(d.unit_amount_decimal) : null) : Math.trunc(Number(d.unit_amount) || 0), unit_amount_decimal: decimal,
-        recurring: { interval: r.interval, interval_count: Math.max(1, Math.trunc(Number(r.interval_count ?? 1)) || 1), usage_type: 'licensed', trial_period_days: null, meter: null },
-        tax_behavior: typeof d.tax_behavior === 'string' ? d.tax_behavior : 'unspecified',
-    }, { active: false, livemode: false, billing_scheme: 'per_unit', type: 'recurring', metadata: {}, lookup_key: null, nickname: null });
-    return String(price.id);
+    return ctx.reply(ctx.expand(SUB, await ctx.write(SUB, id, fields, op)));
 }
-const deleteDiscount = async (ctx) => {
+export async function DeleteSubscriptionsSubscriptionExposedIdDiscount(ctx) {
     const id = at(ctx, 'subscription_exposed_id');
-    const sub = ctx.get(SUB, id);
+    const sub = resourceView(ctx, SUB, id);
     if (!sub)
         return subMissing(ctx, id);
+    // source: spec:DeleteSubscriptionsSubscriptionExposedIdDiscount "Removes the currently applied discount on a subscription."
     const current = (sub.discounts ?? [])[0] ?? sub.discount;
+    // Where the documentation stops and the twin decides: a subscription with no discount answers its absence as a missing resource.
     if (!current)
         return fail(ctx, `No active discount for subscription: '${id}'`, 404, 'resource_missing');
     await ctx.write(SUB, id, { discounts: [] }, 'subscription.update');
-    return ctx.reply(deletedDiscount(typeof current === 'string' ? { id: current } : current, ctx.now()));
-};
-// canceling keeps the subscription, now canceled, stamped with when it was canceled and ended
-// (https://docs.stripe.com/api/subscriptions/object#subscription_object-canceled_at, #subscription_object-ended_at)
-const cancel = async (ctx) => {
-    const id = at(ctx, 'subscription_exposed_id');
-    const sub = ctx.get(SUB, id);
-    if (!sub)
-        return subMissing(ctx, id);
-    const refused = ctx.legal(SUB, 'status', 'DeleteSubscriptionsSubscriptionExposedId', sub.status, undefined, id);
-    if (refused)
-        return ctx.refuse(refused);
-    const now = ctx.now();
-    // why it was canceled: the request's `cancellation_details` ("Details about why this subscription was cancelled"), and
-    // the reason Stripe records for a cancel asked through the API, as the cancel page's example answers it:
-    // `"reason": "cancellation_requested"` (docs.stripe.com/api/subscriptions/cancel)
-    const given = ctx.params.cancellation_details && typeof ctx.params.cancellation_details === 'object' ? ctx.params.cancellation_details : {};
-    const cancellation_details = { comment: given.comment ?? null, feedback: given.feedback ?? null, reason: 'cancellation_requested' };
-    return ctx.reply(await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel'));
-};
-// ── items: each write keeps the parent subscription's items.data in step, rebuilt from the live items ──
-/** A new subscription's items, each its own subscription_item as Stripe keeps it (/v1/subscription_items/{id}). */
-export async function storeItems(ctx, subId, items) {
-    for (const item of items) {
-        if (typeof item.id !== 'string' || ctx.get('subscription_item', item.id))
-            continue;
-        await ctx.write('subscription_item', item.id, { ...item, subscription: subId }, 'subscription_item.create');
-    }
+    return ctx.reply(deletedDiscount(typeof current === 'string' ? { id: current } : { ...current, subscription: id }, nowUnix(ctx.occurredAt)));
 }
-async function syncItems(ctx, subId) {
-    if (!subId)
-        return;
-    const items = ctx.rows('subscription_item').filter((r) => r.subscription === subId);
-    await ctx.write(SUB, subId, { items: { object: 'list', data: items, has_more: false, total_count: items.length, url: `/v1/subscription_items?subscription=${subId}` } }, 'subscription.items_synced');
-}
-/** A subscription item with its billing period: its subscription's (basil moved the period onto the items). */
-const withPeriod = (ctx, si) => {
-    const sub = ctx.get(SUB, String(si.subscription));
-    return { ...si, current_period_start: si.current_period_start ?? sub?.current_period_start ?? null, current_period_end: si.current_period_end ?? sub?.current_period_end ?? null };
-};
-const createItem = async (ctx) => {
-    const params = ctx.params;
-    const subId = typeof params.subscription === 'string' ? params.subscription : '';
-    if (!subId)
-        return fail(ctx, 'Missing required param: subscription.', 400, 'parameter_missing');
-    if (!ctx.get(SUB, subId))
-        return subMissing(ctx, subId);
-    const priceRef = typeof params.price === 'string' ? params.price : '';
-    if (!priceRef && !(params.price_data && typeof params.price_data === 'object'))
-        return fail(ctx, 'Missing required param: price.', 400, 'parameter_missing');
-    if (priceRef && !ctx.get('price', priceRef))
-        return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
-    const quantity = params.quantity !== undefined ? Math.max(0, Math.trunc(Number(params.quantity) || 0)) : 1;
-    // "metadata: Set of key-value pairs that you can attach to an object" (docs.stripe.com/api/subscription_items/create)
-    const metadata = params.metadata && typeof params.metadata === 'object' ? { metadata: params.metadata } : {};
-    const body = await created(ctx, 'subscription_item', { subscription: subId, ...(priceRef ? subscriptionItemPrice(priceRef, finder(ctx)) : { price: null, plan: null }), quantity, ...metadata }, { livemode: false, metadata: {} });
-    await syncItems(ctx, subId);
-    return ctx.reply(withPeriod(ctx, body));
-};
-const listItems = async (ctx) => {
-    const subId = typeof ctx.params.subscription === 'string' ? ctx.params.subscription : '';
-    if (!subId)
-        return fail(ctx, 'Missing required param: subscription.', 400, 'parameter_missing');
-    if (!ctx.get(SUB, subId))
-        return subMissing(ctx, subId);
-    return list(ctx, 'subscription_item', newest(ctx, 'subscription_item').filter((si) => si.subscription === subId).map((si) => withPeriod(ctx, si)));
-};
-const ITEM_ATTRIBUTES = new Set(['billing_thresholds', 'discounts', 'metadata', 'price', 'quantity', 'tax_rates']);
-const itemMissing = (ctx, id) => fail(ctx, `No such subscription_item: '${id}'`, 404, 'resource_missing');
-const updateItem = async (ctx) => {
-    const id = at(ctx, 'item');
-    const si = ctx.get('subscription_item', id);
-    if (!si)
-        return itemMissing(ctx, id);
-    // only the item's own attributes are kept; the update's instructions (off_session, payment_behavior, price_data,
-    // proration_behavior, proration_date) are not attributes of the Subscription Item object
-    // (docs.stripe.com/api/subscription_items/object lists none of them)
-    const fields = Object.fromEntries(Object.entries(ctx.params).filter(([k]) => ITEM_ATTRIBUTES.has(k)));
-    if (ctx.params.quantity !== undefined)
-        fields.quantity = Math.max(0, Math.trunc(Number(ctx.params.quantity) || 0));
-    if (typeof ctx.params.price === 'string' && ctx.params.price && !ctx.get('price', ctx.params.price))
-        return fail(ctx, `No such price: '${ctx.params.price}'`, 400, 'resource_missing');
-    // the item carries its Price and plan, as the subscription's own items do (subscriptionItemPrice)
-    if (typeof ctx.params.price === 'string' && ctx.params.price)
-        Object.assign(fields, subscriptionItemPrice(ctx.params.price, finder(ctx)));
-    const out = await ctx.write('subscription_item', id, fields, 'subscription_item.update');
-    await syncItems(ctx, String(si.subscription));
-    return ctx.reply(withPeriod(ctx, out));
-};
-const retrieveItem = async (ctx) => {
-    const si = ctx.get('subscription_item', at(ctx, 'item'));
-    return si ? ctx.reply(withPeriod(ctx, si)) : itemMissing(ctx, at(ctx, 'item'));
-};
-const deleteItem = async (ctx) => {
-    const id = at(ctx, 'item');
-    const si = ctx.get('subscription_item', id);
-    if (!si)
-        return itemMissing(ctx, id);
-    await ctx.write('subscription_item', id, { deleted: true }, 'subscription_item.delete');
-    await syncItems(ctx, String(si.subscription));
-    return ctx.reply({ id, object: 'subscription_item', deleted: true });
-};
-export const subscriptions = {
-    PostSubscriptions: create,
-    GetSubscriptions: listSubscriptions,
-    GetSubscriptionsSearch: searchSubscriptions,
-    GetSubscriptionsSubscriptionExposedId: retrieveSubscription,
-    PostSubscriptionsSubscriptionExposedId: update,
-    DeleteSubscriptionsSubscriptionExposedIdDiscount: deleteDiscount,
-    DeleteSubscriptionsSubscriptionExposedId: cancel,
-    PostSubscriptionItems: createItem,
-    GetSubscriptionItems: listItems,
-    PostSubscriptionItemsItem: updateItem,
-    GetSubscriptionItemsItem: retrieveItem,
-    DeleteSubscriptionItemsItem: deleteItem,
-};

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

@@ -0,0 +1,3 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function PostTestHelpersIssuingAuthorizations(ctx: HandlerContext): Promise<Response>;
+export declare function PostTestHelpersIssuingAuthorizationsAuthorizationCapture(ctx: HandlerContext): Promise<Response>;