@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/semantics/charges.js

@@ -1,209 +1,12 @@
-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) => {
+import { at, chargeBody, chargeMissing, expanded, list, newest, where } from "./shared.js";
+export async function GetCharges(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) => {
+}
+export async function GetChargesCharge(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

@@ -1,20 +1,3 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** Metadata passed on to what a session makes (payment_intent_data[metadata], subscription_data[metadata]) as a
- *  create's own is kept: "Individual keys can be unset by posting an empty value to them. All keys can be unset by
- *  posting an empty value to `metadata`" (every metadata parameter, docs.stripe.com/api/metadata), so a key posted
- *  empty is not set, and metadata posted empty is {} (stripe-server.ts createMetadata, the top-level case). */
-export declare function nestedMetadata(given: unknown): Row | undefined;
-/** 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>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetCheckoutSessionsSessionLineItems(ctx: HandlerContext): Promise<Response>;
+export declare function PostCheckoutSessions(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/checkout.js

@@ -1,89 +1,16 @@
-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 });
-}
-/** The payment method types a session takes: the list a caller pinned to an earlier version gives as
- *  payment_method_types ("A list of the types of payment methods (e.g., `card`) this Checkout Session can accept", the
- *  parameter the served version's allowed_payment_method_types is described against: "Unlike `payment_method_types`,
- *  this acts as a filter on the dynamically computed set of eligible payment methods", docs.stripe.com/api/checkout/
- *  sessions/create), else the allowed_payment_method_types of the served one, else card. Where the documentation stops
- *  and the twin decides: an allowed list is answered whole (the twin does not compute eligibility), and without one the
- *  session takes card (the account's enabled methods are not modelled). */
-function sessionMethodTypes(params) {
-    const given = Array.isArray(params.payment_method_types) ? params.payment_method_types : params.allowed_payment_method_types;
-    return Array.isArray(given) && given.length ? given.map(String) : ['card'];
-}
-/** Metadata passed on to what a session makes (payment_intent_data[metadata], subscription_data[metadata]) as a
- *  create's own is kept: "Individual keys can be unset by posting an empty value to them. All keys can be unset by
- *  posting an empty value to `metadata`" (every metadata parameter, docs.stripe.com/api/metadata), so a key posted
- *  empty is not set, and metadata posted empty is {} (stripe-server.ts createMetadata, the top-level case). */
-export function nestedMetadata(given) {
-    if (given === '')
-        return {};
-    if (!given || typeof given !== 'object' || Array.isArray(given))
-        return undefined;
-    return Object.fromEntries(Object.entries(given).filter(([, v]) => v !== ''));
+import { CS, sessionMethodTypes } from "../engine/checkout.js";
+import { applyCouponDiscount, lineItemEntries, nowUnix, paginate, resolveLineItem } from "../engine/stripe.js";
+import { actingAccount, at, checkoutNoDestination, created, discountOf, fail, finder, noLineItems, path, sessionMissing, sessionTrialRefused } from "./shared.js";
+export async function GetCheckoutSessionsSessionLineItems(ctx) {
+    const s = ctx.get(CS, at(ctx, 'session'));
+    if (!s)
+        return sessionMissing(ctx, at(ctx, 'session'));
+    // source: spec:GetCheckoutSessionsSessionLineItems "There is also a URL where you can retrieve the full (paginated) list of line items."
+    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 create = async (ctx) => {
+export async function PostCheckoutSessions(ctx) {
     const params = ctx.params;
     const mode = typeof params.mode === 'string' ? params.mode : 'payment';
     if (!['payment', 'subscription', 'setup'].includes(mode))
@@ -91,8 +18,9 @@ const create = async (ctx) => {
     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 === '')
+    // source: spec:/paths/~1v1~1checkout~1sessions/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/ui_mode "The UI mode of the Session."
+    const custom = params.ui_mode === 'custom';
+    if (!custom && (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)));
@@ -100,7 +28,7 @@ const create = async (ctx) => {
     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 now = Number(nowUnix(ctx.occurredAt));
     const trialRefused = sessionTrialRefused(ctx, params.subscription_data, now);
     if (trialRefused)
         return trialRefused;
@@ -114,7 +42,10 @@ const create = async (ctx) => {
     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,
+        ui_mode: custom ? 'custom' : 'hosted',
+        ...(custom ? { client_secret: `${id}_secret_${await ctx.secret(`checkout-secret:${id}`)}`, return_url: params.return_url ?? null } : {}),
+        allow_promotion_codes: params.allow_promotion_codes === true || params.allow_promotion_codes === 'true',
+        url: custom ? null : `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
@@ -149,191 +80,10 @@ const create = async (ctx) => {
     if (pid && mode === 'payment') {
         const destination = pid.transfer_data?.destination;
         if (destination !== undefined && (typeof destination !== 'string' || !ctx.get('account', destination)))
-            return noDestination(ctx, destination);
+            return checkoutNoDestination(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 } : {}),
-            ...(nestedMetadata(pid.metadata) ? { metadata: nestedMetadata(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: Array.isArray(existing.payment_method_types) ? existing.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 = nestedMetadata(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/clock.d.ts

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

package/dist/src/semantics/clock.js

@@ -0,0 +1,15 @@
+import { advanceBilling, advancePayouts, lapseCoupons, lapseRealtimeRequests, settleBankDebits, settleHeldRefunds } from "./shared.js";
+export async function clock(ctx) {
+    // a subscription renews at its period's end, its renewal charged an hour later
+    await advanceBilling(ctx);
+    // a submitted bank debit settles (in test mode at once)
+    await settleBankDebits(ctx);
+    // a coupon past its redeem_by is no longer valid
+    await lapseCoupons(ctx);
+    // a real-time authorization request no one answered is decided when its window ends
+    await lapseRealtimeRequests(ctx);
+    // a refund held for want of balance is made when funds cover it, before any payout takes them
+    await settleHeldRefunds(ctx);
+    // each account's automatic payouts
+    await advancePayouts(ctx);
+}

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

@@ -1,6 +1,2 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-/** Time's lapsing of coupons, caught up to the World's clock: a valid coupon whose redeem_by has passed is no longer
- *  valid from that moment (manifest.ts). Where the documentation stops and the twin decides: the lapse sends no event
- *  (the events page names none for it). */
-export declare function lapseCoupons(ctx: SemanticsContext): Promise<void>;
-export declare const coupons: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function PostCoupons(ctx: HandlerContext): Promise<Response>;