@volter/twin-stripe 0.1.2 → 2.0.1

package/dist/src/semantics/charges.js

@@ -0,0 +1,209 @@
+import { asBool, cardError, chargeDefaults, declineFor, searchOver, validateMoney } from "../stripe-twin.js";
+import { afterCharge } from "./after-payment.js";
+import { settleCharge } from "./ledger.js";
+import { paymentMethodDetails } from "./payment-methods.js";
+import { refundCharge } from "./refunds.js";
+import { at, created, expanded, fail, finder, list, newest, path, refundDestination, send, where } from "./shared.js";
+const chargeMissing = (ctx, id) => fail(ctx, `No such charge: '${id}'`, 404, 'resource_missing');
+/** Every egress of a charge carries its refunds, derived from the refund rows in list order. */
+export function chargeBody(ctx, c) {
+    const data = newest(ctx, 'refund').filter((r) => r.charge === c.id);
+    return { ...c, refunds: { object: 'list', data, has_more: false, total_count: data.length, url: `/v1/charges/${String(c.id)}/refunds` } };
+}
+// A charge is written as the event Stripe sends for it (docs.stripe.com/api/events/types; Stripe has no
+// `charge.created`): charge.succeeded, "Occurs whenever a charge is successful", for one made or authorized
+// (capture=false: its status is succeeded, captured false), and charge.failed, "Occurs whenever a failed charge attempt
+// occurs", for a declined attempt. The twin makes no pending charge (charge.pending, "Occurs whenever a pending charge is
+// created"): its charges settle when made.
+/** The create's parameters as the charge keeps them: without `card`, the request's card details ("A token, like the ones
+ *  returned by Stripe.js", or a hash of the number, expiry and CVC). The Charge object has no `card` property (served
+ *  spec, charge); the card it was made with is its payment_method_details. Kept, it answered the card's full number and
+ *  CVC back on every read of the charge. */
+function withoutCard(params) {
+    const { card: _card, ...rest } = params;
+    return rest;
+}
+/** A Charges-API charge a declining test card refuses: a 402 card_error naming the failed charge Stripe records for the
+ *  attempt (docs.stripe.com/declines). */
+async function declinedCharge(ctx, decline) {
+    const params = ctx.params;
+    const failedId = ctx.mint('charge');
+    const amount = Number(params.amount) || 0;
+    await created(ctx, 'charge', { ...withoutCard(params), id: failedId }, {
+        ...chargeDefaults(failedId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
+        failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
+        outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
+        payment_method_details: paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card) ?? null,
+    }, { operation: 'charge.failed' });
+    return send(ctx, cardError(decline, { charge: failedId }));
+}
+/** A charge's fraud report: "user_report … Assessments reported by you. If set, possible values of are `safe` and
+ *  `fraudulent`" (docs.stripe.com/api/charges/object, fraud_details). */
+function fraudReport(ctx, existing, fd) {
+    const report = String(fd.user_report);
+    if (report !== 'safe' && report !== 'fraudulent')
+        return fail(ctx, "Invalid fraud_details[user_report]: must be 'safe' or 'fraudulent'.", 400, 'parameter_invalid_string_enum');
+    const prior = existing.fraud_details && typeof existing.fraud_details === 'object' ? existing.fraud_details : {};
+    return { user_report: report, stripe_report: prior.stripe_report ?? null };
+}
+const create = async (ctx) => {
+    const params = ctx.params;
+    const bad = validateMoney(params);
+    if (bad)
+        return send(ctx, bad);
+    // a declining test card answers a 402 card_error naming the failed charge Stripe records for the attempt
+    const decline = declineFor(finder(ctx), params);
+    if (decline)
+        return declinedCharge(ctx, decline);
+    // capture=false authorizes only: succeeded and paid, but not captured, with a capture deadline
+    const captured = !(params.capture !== undefined && !asBool(params.capture));
+    // the id comes first so the charge's own `refunds` list can carry its URL
+    const id = typeof params.id === 'string' && params.id ? params.id : ctx.mint('charge');
+    const amount = Number(params.amount) || 0;
+    // a captured charge credits the balance; an authorization does when it is captured
+    const card = String(params.source ?? params.payment_method ?? params.card?.number ?? '');
+    const bt = captured ? await settleCharge(ctx, id, amount, String(params.currency ?? 'usd'), card) : null;
+    const details = paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card);
+    await created(ctx, 'charge', { ...withoutCard(params), id }, { ...chargeDefaults(id, amount, captured, ctx.occurredAt), balance_transaction: bt, payment_method_details: details ?? null }, { operation: 'charge.succeeded' });
+    await afterCharge(ctx, id, { amount, currency: String(params.currency ?? 'usd'), application_fee_amount: params.application_fee_amount, destination: params.transfer_data?.destination }, params.payment_method ?? params.source ?? params.card);
+    return ctx.reply(chargeBody(ctx, ctx.get('charge', id)));
+};
+// capture takes `amount` (the whole authorization by default; docs.stripe.com/api/charges/capture); the rest of a
+// partial capture is released with no Refund (captureAuthorization). `amount_to_capture` is the
+// PaymentIntent capture's parameter, which a charge's capture does not know.
+const capture = async (ctx) => {
+    const id = at(ctx, 'charge');
+    const ch = ctx.get('charge', id);
+    if (!ch)
+        return chargeMissing(ctx, id);
+    const refused = ctx.legal('charge', 'captured', 'PostChargesChargeCapture', ch.captured === true ? 'true' : 'false', undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    // "Capturing a charge will always succeed, unless the charge is already refunded, expired, captured, or an invalid
+    // capture amount is specified" (docs.stripe.com/api/charges/capture): a released authorization is refunded
+    if (ch.refunded === true)
+        return fail(ctx, `Charge ${id} has already been refunded.`, 400, 'charge_already_refunded');
+    // a canceled PaymentIntent's authorization is released: "After it's canceled, no additional charges are made by the
+    // PaymentIntent and any operations on the PaymentIntent fail with an error" (docs.stripe.com/api/payment_intents/cancel).
+    // Where the documentation stops and the twin decides: its charge's capture answers payment_intent_unexpected_state
+    // ("The PaymentIntent's state was incompatible with the operation", docs.stripe.com/error-codes), in the twin's words.
+    const intent = typeof ch.payment_intent === 'string' ? ctx.get('payment_intent', ch.payment_intent) : undefined;
+    if (intent?.status === 'canceled')
+        return fail(ctx, `Charge ${id} belongs to PaymentIntent ${String(intent.id)}, which is canceled; its authorization was released.`, 400, 'payment_intent_unexpected_state');
+    const full = Number(ch.amount) || 0;
+    const toCapture = ctx.params.amount !== undefined ? Math.min(full, Math.max(0, Math.trunc(Number(ctx.params.amount) || 0))) : full;
+    return ctx.reply(chargeBody(ctx, await captureAuthorization(ctx, ch, toCapture, 'PostChargesChargeCapture')));
+};
+/** A capture=false charge refunded while uncaptured: its authorization is released by the refund, as it would be
+ *  "automatically refunded if uncaptured" (spec/openapi.json.gz, `capture_before`). The charge stays uncaptured and
+ *  becomes refunded in full, a Refund records the release, and no money moves: none was ever received. Written as
+ *  charge.refunded. Where the documentation stops and the twin decides: Stripe's basil change ("Partially capturing or
+ *  canceling payments no longer creates a Refund", docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-
+ *  capture-and-payment-cancellation-flow) names partial capture and cancellation, not a refund asked for, so a refund
+ *  still makes one; its reason is null and it has no balance transaction. Answers the Refund. */
+export async function releaseAuthorization(ctx, ch, operationId, given = {}) {
+    const id = String(ch.id);
+    const full = Number(ch.amount) || 0;
+    if (ch.refunded !== true)
+        ctx.legal('charge', 'refunded', operationId, 'false', 'true', id);
+    const refund = await created(ctx, 'refund', { ...given, charge: id, amount: full - (Number(ch.amount_refunded) || 0), currency: String(ch.currency ?? 'usd') }, {
+        status: 'succeeded', metadata: {}, reason: null, receipt_number: null,
+        balance_transaction: null, source_transfer_reversal: null, transfer_reversal: null, ...refundDestination(ch, 'reversal'),
+        ...(typeof ch.payment_intent === 'string' ? { payment_intent: ch.payment_intent } : {}),
+    });
+    await ctx.write('charge', id, { amount_refunded: full, refunded: true }, 'charge.refunded');
+    return refund;
+}
+/** A PaymentIntent's authorization released by its cancel: "For PaymentIntents with a `status` of `requires_capture`, the
+ *  remaining `amount_capturable` is automatically refunded" (docs.stripe.com/api/payment_intents/cancel), and since basil
+ *  a cancellation makes no Refund: "`amount_captured` will be 0 instead of `nil` in payment cancellation flows",
+ *  "`amount_refunded` will no longer be updated by these actions", "`refunded` will no longer be `true` for payment
+ *  cancellation flows", and no charge.refunded is sent (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-
+ *  partial-capture-and-payment-cancellation-flow). The charge stays uncaptured; nothing is written as an event. */
+export async function cancelAuthorization(ctx, ch) {
+    return ctx.write('charge', String(ch.id), { amount_captured: 0 }, 'charge.authorization_released');
+}
+/** An authorized charge captured, by the charge's capture or its PaymentIntent's: what is captured credits the balance.
+ *  Written as charge.captured, "Occurs whenever a previously uncaptured charge is captured" (docs.stripe.com/api/events/types).
+ *  A partial capture releases the rest with no Refund and leaves amount_refunded and refunded as they were: "The following
+ *  flows no longer result in a `Refund` object created and linked to the payment: Partial capture", "`amount_refunded`
+ *  will no longer be updated by these actions", and "There will only be a single balance transaction for partial captures"
+ *  (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-capture-and-payment-cancellation-flow).
+ *  The caller has asked the machine whether it may capture. */
+export async function captureAuthorization(ctx, ch, toCapture, _operationId) {
+    const id = String(ch.id);
+    const bt = toCapture > 0 ? await settleCharge(ctx, id, toCapture, String(ch.currency ?? 'usd'), String(ch.source ?? ch.payment_method ?? '')) : null;
+    return ctx.write('charge', id, { captured: true, amount_captured: toCapture, balance_transaction: bt }, 'charge.captured');
+}
+const listCharges = async (ctx) => {
+    const items = where(ctx, newest(ctx, 'charge'), {
+        customer: (c, v) => c.customer === v,
+        payment_intent: (c, v) => c.payment_intent === v,
+    });
+    return list(ctx, 'charge', items.map((c) => chargeBody(ctx, c)));
+};
+const searchCharges = async (ctx) => {
+    const found = searchOver(newest(ctx, 'charge'), ctx.params, path(ctx));
+    const body = found.body;
+    if (found.status === 200 && Array.isArray(body.data))
+        body.data = body.data.map((c) => chargeBody(ctx, c));
+    return send(ctx, found);
+};
+const retrieve = async (ctx) => {
+    const c = ctx.get('charge', at(ctx, 'charge'));
+    return c ? ctx.reply(expanded(ctx, 'charge', chargeBody(ctx, c))) : chargeMissing(ctx, at(ctx, 'charge'));
+};
+// fraud_details[user_report] marks a charge safe or fraudulent; Stripe keeps its own stripe_report
+const update = async (ctx) => {
+    const id = at(ctx, 'charge');
+    const existing = ctx.get('charge', id);
+    if (!existing)
+        return chargeMissing(ctx, id);
+    const fields = { ...ctx.params };
+    const fd = ctx.params.fraud_details;
+    const fraud = fd && typeof fd === 'object' && 'user_report' in fd ? fraudReport(ctx, existing, fd) : undefined;
+    if (fraud instanceof Response)
+        return fraud;
+    if (fraud)
+        fields.fraud_details = fraud;
+    return ctx.reply(chargeBody(ctx, await ctx.write('charge', id, fields, 'charge.update')));
+};
+// ── the charge's own refunds: listed, created and read through it; another charge's refund is not found ──
+const refunds = async (ctx) => {
+    const id = at(ctx, 'charge');
+    if (!ctx.get('charge', id))
+        return chargeMissing(ctx, id);
+    return list(ctx, 'refund', newest(ctx, 'refund').filter((r) => r.charge === id));
+};
+const createRefund = async (ctx) => {
+    const ch = ctx.get('charge', at(ctx, 'charge'));
+    if (!ch)
+        return chargeMissing(ctx, at(ctx, 'charge'));
+    return refundCharge(ctx, ch, ctx.params);
+};
+const chargeRefund = (ctx) => {
+    if (!ctx.get('charge', at(ctx, 'charge')))
+        return chargeMissing(ctx, at(ctx, 'charge'));
+    const r = ctx.get('refund', at(ctx, 'refund'));
+    return r && r.charge === at(ctx, 'charge') ? r : fail(ctx, `No such refund: '${at(ctx, 'refund')}'`, 404, 'resource_missing');
+};
+const refund = async (ctx) => {
+    const r = chargeRefund(ctx);
+    return r instanceof Response ? r : ctx.reply(r);
+};
+const updateRefund = async (ctx) => {
+    const r = chargeRefund(ctx);
+    return r instanceof Response ? r : ctx.reply(await ctx.write('refund', at(ctx, 'refund'), ctx.params, 'refund.update'));
+};
+export const charges = {
+    PostCharges: create,
+    PostChargesChargeCapture: capture,
+    GetCharges: listCharges,
+    GetChargesSearch: searchCharges,
+    GetChargesCharge: retrieve,
+    PostChargesCharge: update,
+    GetChargesChargeRefunds: refunds,
+    PostChargesChargeRefunds: createRefund,
+    GetChargesChargeRefundsRefund: refund,
+    PostChargesChargeRefundsRefund: updateRefund,
+};

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

@@ -0,0 +1,15 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** The card the customer entered on the page. */
+export type EnteredCard = {
+    number: string;
+    exp_month: number;
+    exp_year: number;
+};
+/** A line item of a one-time Price: a stored Price, or an inline `price_data`, without `recurring` ("Line items with
+ *  one-time Prices will be on the initial invoice only", docs.stripe.com/api/checkout/sessions/create). */
+export declare function isOneTime(item: Row, priceData?: Row | null): boolean;
+/** The customer paying on the hosted page (src/screens/checkout.tsx): the external actor's move on the
+ *  session's machine, then what the payment made, linked, and the session stored complete. */
+export declare function completeSession(ctx: SemanticsContext, id: string, existing: Row, details?: Row, card?: EnteredCard): Promise<Row | Response>;
+export declare const checkout: Record<string, Semantics>;

package/dist/src/semantics/checkout.js

@@ -0,0 +1,316 @@
+import { addBillingInterval, applyCouponDiscount, buildDiscount, buildSubscriptionItemsList, declineFor, lineItemEntries, mintClientSecret, paginate, paymentMethodSubObject, resolveLineItem, resolveSubscriptionBillingInterval, resolveTrial } from "../stripe-twin.js";
+import { afterSuccessOf } from "./after-payment.js";
+import { actingAccount } from "./ledger.js";
+import { mintCharge } from "./payment-intents.js";
+import { collectSubscriptionInvoice, draftSubscriptionInvoice } from "./renewals.js";
+import { storeItems } from "./subscriptions.js";
+import { at, created, fail, finder, path, redeemCoupon } from "./shared.js";
+const CS = 'checkout.session';
+const sessionMissing = (ctx, id) => fail(ctx, `No such checkout.session: '${id}'`, 404, 'resource_missing');
+// Stripe normalizes the create input into the Session: line_items become the list envelope, and
+// subscription_data (create-only) is kept aside for completion to copy onto the subscription
+/** The discount a session is created with (discounts[0][promotion_code] or [coupon]), or Stripe's refusal: an unknown
+ *  code or coupon, and one that has expired or been deactivated, are refused at create
+ *  (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-discounts, docs.stripe.com/error-codes#coupon-expired).
+ *  Where the documentation stops and the twin decides: the refusals' wording. */
+function discountOf(ctx, params, now) {
+    const first = Array.isArray(params.discounts) ? params.discounts[0] : undefined;
+    if (!first || typeof first !== 'object')
+        return undefined;
+    const expired = (what) => ctx.refuse({ status: 400, code: 'coupon_expired', param: 'discounts', message: `This ${what} has expired.` });
+    let promotion;
+    let couponId = typeof first.coupon === 'string' ? first.coupon : undefined;
+    if (typeof first.promotion_code === 'string') {
+        const pc = ctx.get('promotion_code', first.promotion_code);
+        if (!pc)
+            return ctx.refuse({ status: 400, code: 'resource_missing', param: 'discounts[0][promotion_code]', message: `No such promotion code: '${first.promotion_code}'` });
+        if (typeof pc.expires_at === 'number' && pc.expires_at <= now)
+            return expired('promotion code');
+        if (pc.active === false)
+            return ctx.refuse({ status: 400, param: 'discounts[0][promotion_code]', message: 'This promotion code is inactive.' });
+        promotion = String(pc.id);
+        couponId = typeof pc.coupon === 'string' ? pc.coupon : String(pc.coupon?.id ?? '');
+    }
+    const coupon = couponId ? ctx.get('coupon', couponId) : undefined;
+    if (!coupon)
+        return ctx.refuse({ status: 400, code: 'resource_missing', param: 'discounts[0][coupon]', message: `No such coupon: '${couponId ?? ''}'` });
+    if (coupon.valid === false || (typeof coupon.redeem_by === 'number' && coupon.redeem_by <= now))
+        return expired('coupon');
+    return { coupon, ...(promotion ? { promotion } : {}) };
+}
+/** A payment or subscription session with nothing to sell (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-line_items). */
+function noLineItems(ctx) {
+    return fail(ctx, 'You must provide at least one recurring price in `subscription` mode when not using `line_items[].price_data` or a Price with `recurring`, and at least one `line_items` for `payment` mode.', 400, 'parameter_missing');
+}
+/** A destination charge to an account the platform does not have (docs.stripe.com/connect/destination-charges). */
+function noDestination(ctx, destination) {
+    return ctx.refuse({ status: 400, code: 'resource_missing', param: 'payment_intent_data[transfer_data][destination]', message: `No such destination: '${String(destination)}'` });
+}
+/** A session's trial Stripe refuses: `subscription_data.trial_end` "Has to be at least 48 hours in the future", and
+ *  `subscription_data.trial_period_days` "Has to be at least 1" (docs.stripe.com/api/checkout/sessions/create). Where the
+ *  documentation stops and the twin decides: the refusals' wording. */
+function sessionTrialRefused(ctx, data, now) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    const { trial_end: end, trial_period_days: days } = data;
+    const endRefused = end !== undefined && !(Number.isInteger(Number(end)) && Number(end) >= now + 48 * 3600);
+    const daysRefused = days !== undefined && !(Number.isInteger(Number(days)) && Number(days) >= 1);
+    return endRefused || daysRefused ? sessionTrialRefusal(ctx, endRefused ? 'trial_end' : 'trial_period_days') : undefined;
+}
+function sessionTrialRefusal(ctx, param) {
+    const message = param === 'trial_end' ? 'The `subscription_data[trial_end]` timestamp has to be at least 48 hours in the future.' : 'The `subscription_data[trial_period_days]` has to be at least 1.';
+    return ctx.refuse({ status: 400, param: `subscription_data[${param}]`, message });
+}
+const create = async (ctx) => {
+    const params = ctx.params;
+    const mode = typeof params.mode === 'string' ? params.mode : 'payment';
+    if (!['payment', 'subscription', 'setup'].includes(mode))
+        return fail(ctx, 'Invalid mode: must be one of payment, subscription, or setup.', 400, 'parameter_invalid_string_enum');
+    const entries = lineItemEntries(params);
+    if (mode !== 'setup' && entries.length === 0)
+        return noLineItems(ctx);
+    // hosted Checkout (the only ui_mode the twin models) needs success_url
+    if (params.success_url === undefined || params.success_url === '')
+        return fail(ctx, 'Missing required param: success_url.', 400, 'parameter_missing');
+    const sessionCurrency = typeof params.currency === 'string' ? params.currency : 'usd';
+    const resolved = entries.map((e, i) => resolveLineItem(e, i, sessionCurrency, finder(ctx)));
+    const missing = resolved.find((r) => r.priceMissing);
+    if (missing)
+        return fail(ctx, `No such price: '${missing.priceMissing}'`, 400, 'resource_missing');
+    const items = resolved.map((r) => r.item);
+    const now = Number(ctx.now());
+    const trialRefused = sessionTrialRefused(ctx, params.subscription_data, now);
+    if (trialRefused)
+        return trialRefused;
+    const discount = discountOf(ctx, params, now);
+    if (discount instanceof Response)
+        return discount;
+    const subtotal = items.reduce((n, it) => n + it.amount_subtotal, 0);
+    const off = discount ? applyCouponDiscount(subtotal, discount.coupon) : 0;
+    // the hosted page is at Stripe's own host (the World routes it to src/screens/checkout.tsx)
+    const id = ctx.mint(CS);
+    const fields = {
+        mode, status: 'open',
+        payment_status: mode === 'setup' ? 'no_payment_required' : 'unpaid',
+        url: `https://checkout.stripe.com/c/pay/${id}`, success_url: params.success_url ?? null, cancel_url: params.cancel_url ?? null,
+        customer: params.customer ?? null, client_reference_id: params.client_reference_id ?? null,
+        customer_email: params.customer_email ?? null,
+        // whether paying makes a customer: in payment mode only when asked (`always`), `if_required` by default
+        customer_creation: mode === 'payment' ? (params.customer_creation === 'always' ? 'always' : 'if_required') : null,
+        amount_subtotal: entries.length ? items.reduce((s, it) => s + it.amount_subtotal, 0) : null,
+        amount_total: entries.length ? items.reduce((s, it) => s + it.amount_total, 0) - off : null,
+        currency: items[0]?.currency ?? (entries.length ? sessionCurrency : null), line_items: { object: 'list', data: items, has_more: false, url: `/v1/checkout/sessions/${id}/line_items` }, payment_intent: null, subscription: null, setup_intent: null, invoice: null, payment_method_types: ['card'], expires_at: now + 24 * 3600, custom_fields: [], shipping_options: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null }, automatic_tax: { enabled: false, liability: null, status: null, provider: null }, total_details: { amount_discount: off, amount_shipping: 0, amount_tax: 0 },
+        discounts: discount ? [{ coupon: String(discount.coupon.id), promotion_code: discount.promotion ?? null }] : [],
+        metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {}, livemode: false,
+        // "Details on the state of phone number collection for the session" (docs.stripe.com/api/checkout/sessions/object),
+        // off unless the create enables it
+        phone_number_collection: { enabled: params.phone_number_collection?.enabled === true || params.phone_number_collection?.enabled === 'true' },
+    };
+    if (params.subscription_data && typeof params.subscription_data === 'object')
+        fields._subscription_data = params.subscription_data;
+    // each line's inline price_data, kept for what the session's line cannot carry: whether it recurs (isOneTime) and the
+    // Price a subscription's item is made from at completion (sessionPrices)
+    if (mode === 'subscription' && entries.some((e) => e.price_data && typeof e.price_data === 'object'))
+        fields._price_data = entries.map((e) => (e.price_data && typeof e.price_data === 'object' ? e.price_data : null));
+    // the hosted page's brand name for this session (screens/checkout.tsx, merchantOf), and the account the session was
+    // made on (Stripe-Account: a direct charge), whose name the page shows. Kept apart from `_account`, the books a row is
+    // kept on: paying on the hosted page still makes the PaymentIntent and charge on the platform's books (a gap of the
+    // twin's direct-charge Checkout), so the session's events stay with them.
+    if (params.branding_settings && typeof params.branding_settings === 'object')
+        fields._branding_settings = params.branding_settings;
+    if (actingAccount(ctx))
+        fields._brand_account = actingAccount(ctx);
+    // a payment session's payment_intent_data shapes the PaymentIntent paying makes: a destination charge's transfer and
+    // the platform's application fee (docs.stripe.com/connect/destination-charges?platform=web&ui=stripe-hosted)
+    const pid = params.payment_intent_data && typeof params.payment_intent_data === 'object' ? params.payment_intent_data : undefined;
+    if (pid && mode === 'payment') {
+        const destination = pid.transfer_data?.destination;
+        if (destination !== undefined && (typeof destination !== 'string' || !ctx.get('account', destination)))
+            return noDestination(ctx, destination);
+        fields._payment_intent_data = pid;
+    }
+    if (discount)
+        fields._discount = { coupon: String(discount.coupon.id), promotion_code: discount.promotion ?? null };
+    return ctx.reply(await created(ctx, CS, { id, ...fields }, {}));
+};
+// the session's items, a page at a time
+const lineItems = async (ctx) => {
+    const s = ctx.get(CS, at(ctx, 'session'));
+    if (!s)
+        return sessionMissing(ctx, at(ctx, 'session'));
+    const li = s.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 expire = async (ctx) => {
+    const id = at(ctx, 'session');
+    const s = ctx.get(CS, id);
+    if (!s)
+        return sessionMissing(ctx, id);
+    const refused = ctx.legal(CS, 'status', 'PostCheckoutSessionsSessionExpire', s.status, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    return ctx.reply(await ctx.write(CS, id, { status: 'expired', url: null }, 'checkout.session.expire'));
+};
+/** What completing a session makes, by its mode, as the fields that link it: a payment is a PaymentIntent paid with
+ *  the entered card, its charge in the ledger as any payment's is. */
+async function complete(ctx, id, existing, card) {
+    const link = { status: 'complete' };
+    const customer = typeof existing.customer === 'string' ? existing.customer : undefined;
+    const currency = typeof existing.currency === 'string' ? existing.currency : 'usd';
+    // the entered card becomes a PaymentMethod carrying what a later charge to it answers and what Stripe does after it
+    // succeeds (docs.stripe.com/testing#declined-payments, #disputes)
+    const made = card ? await created(ctx, 'payment_method', {}, { type: 'card', customer: null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null, ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}) }) : undefined;
+    // and Checkout attaches it to the customer when it saves it: a subscription's card ("If your Checkout Session uses
+    // subscription mode, Stripe saves the payment method by default", docs.stripe.com/payments/checkout/how-checkout-works),
+    // a setup session's (it exists to save one), and a payment's only under payment_intent_data.setup_future_usage ("to have
+    // Checkout automatically attach the payment method to the Customer you pass in", docs.stripe.com/api/checkout/sessions/
+    // create#create_checkout_session-customer). Attaching is its own write, so payment_method.attached is delivered ("Occurs
+    // whenever a new payment method is attached to a customer", docs.stripe.com/api/events/types) before what the card then
+    // pays for. Where the documentation stops and the twin decides: the order of the events, which Stripe does not
+    // guarantee (docs.stripe.com/webhooks#event-ordering). A gap: the customer's own opt-in to save a payment's card
+    // (saved_payment_method_options.payment_method_save) is not modelled; the page offers no such box.
+    const saves = existing.mode !== 'payment' || !!(ctx.row(CS, id)?._payment_intent_data ?? {}).setup_future_usage;
+    const pm = made && customer && saves ? await ctx.write('payment_method', String(made.id), { customer }, 'payment_method.attach') : made;
+    if (existing.mode === 'payment') {
+        const amount = Number(existing.amount_total) || 0;
+        const piId = ctx.mint('payment_intent');
+        const pid = (ctx.row(CS, id)?._payment_intent_data ?? {});
+        const connect = {
+            ...(pid.application_fee_amount !== undefined ? { application_fee_amount: Math.trunc(Number(pid.application_fee_amount) || 0) } : {}),
+            ...(pid.transfer_data && typeof pid.transfer_data === 'object' ? { transfer_data: { destination: pid.transfer_data.destination } } : {}),
+            ...(typeof pid.description === 'string' ? { description: pid.description } : {}),
+            // the session's setup_future_usage is its PaymentIntent's (payment_intent_data: "A subset of parameters to be passed to PaymentIntent creation")
+            ...(typeof pid.setup_future_usage === 'string' ? { setup_future_usage: pid.setup_future_usage } : {}),
+            ...(pid.metadata && typeof pid.metadata === 'object' ? { metadata: pid.metadata } : {}),
+        };
+        const fields = { amount, currency, id: piId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}), ...connect };
+        await created(ctx, 'payment_intent', fields, { status: 'succeeded', amount_received: amount, client_secret: mintClientSecret(piId), livemode: false, payment_method_types: ['card'] });
+        const charge = await mintCharge(ctx, piId, fields, amount);
+        await ctx.write('payment_intent', piId, { latest_charge: charge }, 'payment_intent.succeeded');
+        link.payment_intent = piId;
+        link.payment_status = 'paid';
+    }
+    else if (existing.mode === 'subscription') {
+        if (customer) {
+            // the subscription bills the session's own (already resolved) line items, and takes the
+            // session's subscription_data: metadata, description, and a trial as its first period
+            const now = Number(ctx.now());
+            // "Line items with one-time Prices will be on the initial invoice only" (docs.stripe.com/api/checkout/sessions/
+            // create#create_checkout_session-line_items): the subscription's items are the recurring ones
+            const inline = ctx.row(CS, id)?._price_data ?? [];
+            const lines = existing.line_items?.data ?? [];
+            const allLineItems = inline.some(Boolean) ? await sessionPrices(ctx, lines, inline) : lines;
+            const sessionLineItems = allLineItems.filter((it) => !isOneTime(it));
+            const oneTime = allLineItems.filter((it) => isOneTime(it));
+            const { interval, interval_count } = resolveSubscriptionBillingInterval(sessionLineItems, finder(ctx));
+            const subId = ctx.mint('subscription');
+            // the session's view never carries its create-only subscription_data: read the stored row
+            const raw = ctx.row(CS, id)?._subscription_data;
+            const subData = (raw && typeof raw === 'object' ? raw : {});
+            const subMetadata = subData.metadata && typeof subData.metadata === 'object' ? subData.metadata : {};
+            // a trial of `trial_period_days` from now, or to `trial_end` (docs.stripe.com/payments/checkout/free-trials)
+            const trialEnd = resolveTrial(subData, now)?.end ?? null;
+            const sub = await created(ctx, 'subscription', { customer, id: subId }, {
+                status: trialEnd === null ? 'active' : 'trialing', livemode: false, currency, collection_method: 'charge_automatically',
+                // a trial's end is the billing anchor (docs.stripe.com/api/subscriptions/create#create_subscription-trial_end)
+                cancel_at_period_end: false, start_date: now, billing_cycle_anchor: trialEnd ?? now, metadata: subMetadata,
+                description: typeof subData.description === 'string' ? subData.description : null,
+                // the session's discount is the subscription's (docs.stripe.com/payments/checkout/discounts)
+                discounts: sessionDiscount(ctx, id, customer, now), billing_schedules: [],
+                trial_start: trialEnd === null ? null : now, trial_end: trialEnd,
+                current_period_start: now, current_period_end: trialEnd ?? addBillingInterval(now, interval, interval_count),
+                // Checkout saves the card as the subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works)
+                default_payment_method: pm?.id ?? null,
+                items: buildSubscriptionItemsList(sessionLineItems, subId, now, finder(ctx)),
+                automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' },
+                invoice_settings: { issuer: { type: 'self' } },
+            });
+            await storeItems(ctx, subId, sub.items?.data ?? []);
+            // its first invoice, paid on the page by the card just entered (nothing is due on a trial's)
+            // (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions)
+            const invoice = await draftSubscriptionInvoice(ctx, sub, { start: now, end: Number(sub.current_period_end), reason: 'subscription_create', trial: trialEnd !== null, once: oneTime });
+            await collectSubscriptionInvoice(ctx, invoice, now, 'external');
+            await ctx.write('subscription', subId, { latest_invoice: invoice }, 'subscription.update');
+            link.subscription = sub.id;
+            link.invoice = invoice;
+        }
+        link.payment_status = 'paid';
+    }
+    else
+        link.setup_intent = await completeSetup(ctx, customer, pm);
+    return link;
+}
+/** A line item of a one-time Price: a stored Price, or an inline `price_data`, without `recurring` ("Line items with
+ *  one-time Prices will be on the initial invoice only", docs.stripe.com/api/checkout/sessions/create). */
+export function isOneTime(item, priceData) {
+    if (priceData)
+        return !priceData.recurring;
+    return !!item.price && typeof item.price === 'object' && !item.price.recurring;
+}
+/** A subscription session's lines at completion, each inline `price_data` made the Price it generates ("Data used to
+ *  generate a new Price object inline", the same page), under the product it names or one made from its product_data,
+ *  so the subscription's items bill it. Where the documentation stops and the twin decides: such a Price is archived
+ *  (active=false), as a subscription item's price_data makes one (docs.stripe.com/products-prices/manage-prices). */
+async function sessionPrices(ctx, lines, inline) {
+    const out = [];
+    for (const [i, line] of lines.entries()) {
+        const d = inline[i];
+        if (!d) {
+            out.push(line);
+            continue;
+        }
+        const pd = d.product_data && typeof d.product_data === 'object' ? d.product_data : undefined;
+        const product = typeof d.product === 'string' ? d.product : String((await created(ctx, 'product', { name: pd?.name ?? 'Item' }, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: ctx.now() })).id);
+        const r = d.recurring && typeof d.recurring === 'object' ? d.recurring : undefined;
+        const price = await created(ctx, 'price', {
+            product, currency: String(d.currency ?? line.currency ?? 'usd').toLowerCase(),
+            unit_amount: d.unit_amount_decimal !== undefined ? null : Math.trunc(Number(d.unit_amount) || 0),
+            unit_amount_decimal: d.unit_amount_decimal !== undefined ? String(d.unit_amount_decimal) : String(Math.trunc(Number(d.unit_amount) || 0)),
+            ...(r ? { 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 } } : { recurring: null }),
+        }, { active: false, livemode: false, billing_scheme: 'per_unit', type: r ? 'recurring' : 'one_time', metadata: {}, lookup_key: null, nickname: null, tax_behavior: 'unspecified' });
+        out.push({ ...line, price });
+    }
+    return out;
+}
+/** A setup session saves the card through a succeeded SetupIntent (docs.stripe.com/payments/save-and-reuse?platform=checkout). */
+async function completeSetup(ctx, customer, pm) {
+    const siId = ctx.mint('setup_intent');
+    const si = await created(ctx, 'setup_intent', { id: siId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}) }, { status: 'succeeded', usage: 'off_session', client_secret: mintClientSecret(siId), payment_method_types: ['card'], livemode: false });
+    return si.id;
+}
+/** The discount a completed subscription session gives its subscription. */
+function sessionDiscount(ctx, id, customer, now) {
+    const d = ctx.row(CS, id)?._discount;
+    const coupon = d && typeof d.coupon === 'string' ? ctx.get('coupon', d.coupon) : undefined;
+    return coupon ? [{ ...buildDiscount(coupon, customer, now), promotion_code: d?.promotion_code ?? null, checkout_session: id }] : [];
+}
+/** The customer paying on the hosted page (src/screens/checkout.tsx): the external actor's move on the
+ *  session's machine, then what the payment made, linked, and the session stored complete. */
+export async function completeSession(ctx, id, existing, details = {}, card) {
+    const refused = ctx.legal(CS, 'status', 'PostCheckoutSessionsSession', existing.status, 'complete', id, 'external');
+    if (refused)
+        return ctx.refuse(refused);
+    const link = await complete(ctx, id, existing, card);
+    // the discount the buyer took is redeemed (shared.ts redeemCoupon)
+    const d = ctx.row(CS, id)?._discount;
+    if (d)
+        await redeemCoupon(ctx, d.coupon, d.promotion_code);
+    // the session's url "is only present when the session is active" (docs.stripe.com/api/checkout/sessions/object)
+    return ctx.write(CS, id, { ...details, ...link, url: null }, 'checkout.session.completed');
+}
+const update = async (ctx) => {
+    const id = at(ctx, 'session');
+    const existing = ctx.get(CS, id);
+    if (!existing)
+        return sessionMissing(ctx, id);
+    // a session completes only when its customer pays on the hosted page (src/screens/checkout.tsx); the API takes no
+    // status, which the parameter check refuses as Stripe does (../stripe-params.ts)
+    return ctx.reply(await ctx.write(CS, id, ctx.params, 'checkout.session.update'));
+};
+export const checkout = {
+    PostCheckoutSessions: create,
+    GetCheckoutSessionsSessionLineItems: lineItems,
+    PostCheckoutSessionsSessionExpire: expire,
+    PostCheckoutSessionsSession: update,
+};

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

@@ -0,0 +1,5 @@
+import type { Semantics } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** The platform's own account as Stripe's default has it, before anything is written to it. */
+export declare const platformAccountDefault: () => Row;
+export declare const connect: Record<string, Semantics>;