@volter/twin-stripe 0.1.1 → 2.0.0

package/dist/src/semantics/subscriptions.js

@@ -0,0 +1,605 @@
+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) => {
+    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) => {
+    const id = at(ctx, 'subscription_exposed_id');
+    await advanceBilling(ctx, (sub) => sub.id === id);
+    const sub = ctx.get(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) => {
+    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);
+    if (!sub)
+        return subMissing(ctx, id);
+    const params = ctx.params;
+    const now = clockNow(ctx, sub.customer);
+    const badTrial = trialEndRefused(ctx, params.trial_end, now);
+    if (badTrial)
+        return badTrial;
+    // the update's instructions are no attributes of the subscription (docs.stripe.com/api/subscriptions/object lists none)
+    const { payment_behavior: _pb, proration_behavior: _prb, proration_date: _pd, trial_from_plan: _tfp, ...attributes } = params;
+    const fields = { ...attributes };
+    let op = 'subscription.update';
+    if ('pause_collection' in params)
+        op = pauseCollection(params.pause_collection, fields) ?? op;
+    const couponId = subscriptionCouponParam(params);
+    const discounts = couponId !== undefined ? replacedDiscounts(ctx, couponId, sub) : undefined;
+    if (discounts instanceof Response)
+        return discounts;
+    // `items` changes the subscription's items, never replaces the list with the request (applyItemChanges); every
+    // entry is checked before a trial's end is judged payable
+    const itemsRefused = 'items' in params ? itemChangesRefused(ctx, id, subscriptionItemEntries(params.items)) : undefined;
+    if (itemsRefused)
+        return itemsRefused;
+    const blocked = 'trial_end' in params ? trialEndBlocked(ctx, sub, discounts) : undefined;
+    if (blocked)
+        return blocked;
+    if ('items' in params) {
+        await applyItemChanges(ctx, id, subscriptionItemEntries(params.items));
+        delete fields.items;
+    }
+    if (discounts)
+        fields.discounts = discounts;
+    if (discounts && discounts.length)
+        await redeemCoupon(ctx, couponId);
+    delete fields.coupon;
+    // `trial_end`: the trial ended now (its period's invoice made, to collect below) or moved (applyTrialEnd)
+    const trial = 'trial_end' in params ? await applyTrialEnd(ctx, sub, fields, now) : undefined;
+    // scheduling a cancel at the period's end sets when it will be canceled (the period's end as this update leaves it),
+    // and withdrawing it clears that (docs.stripe.com/api/subscriptions/object#subscription_object-cancel_at); a
+    // 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 });
+    }
+    else if (sub.cancel_at_period_end === true && fields.current_period_end !== undefined)
+        fields.cancel_at = fields.current_period_end;
+    if (trial?.invoice) {
+        // the trial's end is charged at once: paid (or nothing due), the subscription is active; not, past_due
+        // (applyTrialEnd; the move was asked in trialEndBlocked). Finalizing the invoice spends a `once` coupon, this
+        // update's own among them.
+        const pays = await collectSubscriptionInvoice(ctx, trial.invoice, now, 'api', { ...(trial.payer ? { payer: trial.payer } : {}), attempt: trial.attempt });
+        fields.status = pays ? 'active' : 'past_due';
+        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);
+}
+const deleteDiscount = async (ctx) => {
+    const id = at(ctx, 'subscription_exposed_id');
+    const sub = ctx.get(SUB, id);
+    if (!sub)
+        return subMissing(ctx, id);
+    const current = (sub.discounts ?? [])[0] ?? sub.discount;
+    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');
+    }
+}
+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/tax.d.ts

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