@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/semantics/issuing.js

@@ -0,0 +1,570 @@
+import { emptySpendingControls, normalizeSpendingControls, nextStripeEventId, persistStripeEvent, spendingControlsViolation } from "../stripe-twin.js";
+import { requestAuthorizationDecision, STRIPE_WEBHOOK_FALLBACK_SECRET, stripeEventMatches } from "../stripe-events.js";
+import { at, created, fail, filePurposeRefused, list, newest, send, where } from "./shared.js";
+import { balanceOf } from "./ledger.js";
+const CH = 'issuing.cardholder';
+/** The id of a card's cardholder: the card answers the cardholder in full (the served spec's issuing.card.cardholder is
+ *  the Cardholder object, not an id); its id is read from it for filtering and for the objects that name it by id. */
+export const holderId = (c) => (typeof c.cardholder === 'string' ? c.cardholder : String(c.cardholder?.id ?? ''));
+const CARD = 'issuing.card';
+const AUTH = 'issuing.authorization';
+const TXN = 'issuing.transaction';
+const DSP = 'issuing.dispute';
+const TOK = 'issuing.token';
+const PD = 'issuing.personalization_design';
+// ── cardholders ──
+const createCardholder = async (ctx) => {
+    const params = ctx.params;
+    if (params.name === undefined || params.name === '')
+        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+    const chType = typeof params.type === 'string' ? params.type : '';
+    if (chType !== 'individual' && chType !== 'company')
+        return fail(ctx, "Invalid type: must be one of 'individual' or 'company'.", 400, 'parameter_invalid_string_enum');
+    const billing = params.billing && typeof params.billing === 'object' ? params.billing : undefined;
+    if (!billing || !billing.address || typeof billing.address !== 'object')
+        return fail(ctx, 'Missing required param: billing[address].', 400, 'parameter_missing');
+    const controls = normalizeSpendingControls(params.spending_controls, null);
+    if (controls.error)
+        return send(ctx, controls.error);
+    return ctx.reply(await created(ctx, CH, { ...params, spending_controls: controls.controls ?? emptySpendingControls() }, {
+        status: 'active', livemode: false, metadata: {}, phone_number: params.phone_number ?? null,
+        email: params.email ?? null, requirements: { disabled_reason: null, past_due: [] },
+    }));
+};
+/** A requested move of a state field the machine declares, legal or refused; a value the machine
+ *  does not name is written as given, as the hand-written route did. */
+function requestedMove(ctx, resource, operationId, current, values) {
+    const to = ctx.params.status;
+    if (typeof to !== 'string' || !values.includes(to))
+        return undefined;
+    const refused = ctx.legal(resource, 'status', operationId, current, to);
+    return refused ? ctx.refuse(refused) : undefined;
+}
+const updateCardholder = async (ctx) => {
+    const id = at(ctx, 'cardholder');
+    const ch = ctx.get(CH, id);
+    if (!ch)
+        return fail(ctx, `No such cardholder: '${id}'`, 404, 'resource_missing');
+    const controls = normalizeSpendingControls(ctx.params.spending_controls, null);
+    if (controls.error)
+        return send(ctx, controls.error);
+    const refused = requestedMove(ctx, CH, 'PostIssuingCardholdersCardholder', ch.status, ['active', 'inactive', 'blocked']);
+    if (refused)
+        return refused;
+    const updated = await ctx.write(CH, id, controls.controls ? { ...ctx.params, spending_controls: controls.controls } : ctx.params, 'issuing_cardholder.updated');
+    // each of the cardholder's cards answers it as it now stands
+    for (const card of ctx.rowsRaw(CARD).filter((c) => holderId(c) === id))
+        await ctx.write(CARD, String(card.id), { cardholder: updated }, 'issuing_card.cardholder_synced');
+    return ctx.reply(updated);
+};
+// ── cards: a virtual card is active at once, a physical one inactive until shipped ──
+const createCard = async (ctx) => {
+    const params = ctx.params;
+    const cardholder = typeof params.cardholder === 'string' ? params.cardholder : '';
+    if (!cardholder)
+        return fail(ctx, 'Missing required param: cardholder.', 400, 'parameter_missing');
+    if (!ctx.get(CH, cardholder))
+        return fail(ctx, `No such cardholder: '${cardholder}'`, 400, 'resource_missing');
+    if (params.currency === undefined || params.currency === '')
+        return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
+    const cardType = typeof params.type === 'string' ? params.type : '';
+    if (cardType !== 'virtual' && cardType !== 'physical')
+        return fail(ctx, "Invalid type: must be one of 'virtual' or 'physical'.", 400, 'parameter_invalid_string_enum');
+    const last4 = String(4242 + ctx.rowsRaw(CARD, { withDeleted: true }).length + 1).slice(-4);
+    const controls = normalizeSpendingControls(params.spending_controls, typeof params.currency === 'string' ? params.currency : null);
+    if (controls.error)
+        return send(ctx, controls.error);
+    return ctx.reply(await created(ctx, CARD, { ...params, cardholder: ctx.get(CH, cardholder), spending_controls: controls.controls ?? emptySpendingControls() }, {
+        status: cardType === 'virtual' ? 'active' : 'inactive', livemode: false, metadata: {},
+        brand: 'Visa', last4, exp_month: 12, exp_year: 2030, cancellation_reason: null,
+    }));
+};
+// a card list filters on the cardholder's id, the card answering the cardholder in full
+const listCards = async (ctx) => list(ctx, CARD, where(ctx, newest(ctx, CARD), {
+    cardholder: (c, v) => holderId(c) === v,
+    status: (c, v) => c.status === v,
+    type: (c, v) => c.type === v,
+    last4: (c, v) => c.last4 === v,
+}));
+const updateCard = async (ctx) => {
+    const id = at(ctx, 'card');
+    const card = ctx.get(CARD, id);
+    if (!card)
+        return fail(ctx, `No such card: '${id}'`, 404, 'resource_missing');
+    if (ctx.params.status !== undefined && !['active', 'inactive', 'canceled'].includes(String(ctx.params.status)))
+        return issuingRefusal(ctx, 'card_status');
+    const controls = normalizeSpendingControls(ctx.params.spending_controls, typeof card.currency === 'string' ? card.currency : null);
+    if (controls.error)
+        return send(ctx, controls.error);
+    const refused = requestedMove(ctx, CARD, 'PostIssuingCardsCard', card.status, ['active', 'inactive', 'canceled']);
+    if (refused)
+        return refused;
+    return ctx.reply(await ctx.write(CARD, id, controls.controls ? { ...ctx.params, spending_controls: controls.controls } : ctx.params, 'issuing_card.updated'));
+};
+// ── authorizations ──
+/** An authorization as every egress carries it: its card embedded in full. */
+function withCard(ctx, a) {
+    const out = { ...a };
+    if (typeof out.card === 'string') {
+        const card = ctx.get(CARD, out.card);
+        if (card)
+            out.card = card;
+    }
+    return out;
+}
+const authMissing = (ctx, id) => fail(ctx, `No such authorization: '${id}'`, 404, 'resource_missing');
+const listAuthorizations = async (ctx) => list(ctx, AUTH, where(ctx, newest(ctx, AUTH), {
+    card: (a, v) => a.card === v,
+    cardholder: (a, v) => a.cardholder === v,
+    status: (a, v) => a.status === v,
+}).map((a) => withCard(ctx, a)));
+const retrieveAuthorization = async (ctx) => {
+    const a = ctx.get(AUTH, at(ctx, 'authorization'));
+    return a ? ctx.reply(withCard(ctx, a)) : authMissing(ctx, at(ctx, 'authorization'));
+};
+const updateAuthorization = async (ctx) => {
+    const id = at(ctx, 'authorization');
+    if (!ctx.get(AUTH, id))
+        return authMissing(ctx, id);
+    return ctx.reply(await ctx.write(AUTH, id, ctx.params, 'issuing_authorization.updated'));
+};
+/** One request_history entry; the authorization code is derived from the request time (Stripe's is not unique either). */
+function historyEntry(o) {
+    return {
+        amount: o.amount, amount_details: null, approved: o.approved,
+        authorization_code: o.approved ? `S${String(100000 + (o.createdSec % 900000))}` : null,
+        created: o.createdSec, currency: o.currency,
+        merchant_amount: o.merchantAmount, merchant_currency: o.merchantCurrency,
+        network_risk_score: null, reason: o.reason, reason_message: o.reasonMessage,
+        requested_at: o.createdSec,
+    };
+}
+/** The test helper's default merchant, under any merchant_data the caller gives. */
+function merchantData(param) {
+    const base = {
+        category: 'general', category_code: '5399', city: 'San Francisco', country: 'US',
+        name: 'Twin Test Merchant', network_id: '1234567890', postal_code: '94103', state: 'CA',
+        tax_id: null, terminal_id: null, url: null,
+    };
+    if (param && typeof param === 'object' && !Array.isArray(param))
+        Object.assign(base, param);
+    return base;
+}
+/** A capture: an Issuing transaction (negative: it debits) and the issuing balance's debit. */
+async function capture(ctx, authId, auth, amountCents) {
+    const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+    const bt = await created(ctx, 'balance_transaction', {}, {
+        amount: -amountCents, currency, fee: 0, net: -amountCents, type: 'issuing_transaction',
+        status: 'available', balance_type: 'issuing', reporting_category: 'issuing_transaction',
+        available_on: ctx.now(), fee_details: [],
+    });
+    const txn = await created(ctx, TXN, { authorization: authId, card: auth.card, cardholder: auth.cardholder }, {
+        type: 'capture', amount: -amountCents, currency,
+        merchant_amount: -amountCents, merchant_currency: typeof auth.merchant_currency === 'string' ? auth.merchant_currency : currency,
+        merchant_data: auth.merchant_data ?? merchantData(undefined),
+        livemode: false, metadata: {}, dispute: null, wallet: null, network_data: null,
+        amount_details: null, purchase_details: null, balance_transaction: bt.id,
+    });
+    return { txnId: String(txn.id), btId: String(bt.id) };
+}
+/** The card's stored id (an embedded card answers with its id). */
+const cardId = (auth) => (auth.card && typeof auth.card === 'object' ? auth.card.id : auth.card);
+/** Issuing refusals of a request no story sends: an unknown card status or authorization method, and a capture of an
+ *  authorization that is not approved and pending. */
+function issuingRefusal(ctx, what, auth) {
+    switch (what) {
+        case 'card_status': return fail(ctx, "Invalid status: must be one of 'active', 'inactive', or 'canceled'.", 400, 'parameter_invalid_string_enum');
+        case 'authorization_method': return fail(ctx, "Invalid authorization_method: must be one of 'chip', 'contactless', 'keyed_in', 'online', or 'swipe'.", 400, 'parameter_invalid_string_enum');
+        case 'not_capturable': return fail(ctx, `This authorization cannot be captured because it is not an approved pending authorization (status: ${String(auth?.status)}, approved: ${auth?.approved === true}).`, 400);
+    }
+}
+/** A partial approval's refusal: "You can specify the amount you want to approve by setting the amount in the webhook
+ *  response body or the approve call" only "When an authorization is partially authorized, the is_amount_controllable
+ *  field on the authorization request is set to true" (docs.stripe.com/issuing/purchases/authorizations), and never a
+ *  credit. Answers the refusal, or undefined when the amount may be approved. */
+function partialApprovalRefused(ctx, auth) {
+    if (Math.trunc(Number(ctx.params.amount) || 0) <= 0)
+        return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+    if (auth.pending_request?.is_amount_controllable !== true)
+        return fail(ctx, 'amount may only be provided when the authorization was presented with is_amount_controllable.', 400);
+    return undefined;
+}
+// the (deprecated but real) API decision on a pending authorization: it lands in request_history
+// as the webhook's answer would, consumes the pending request, and an approval captures
+function decide(approved) {
+    return async (ctx) => {
+        const id = at(ctx, 'authorization');
+        const auth = ctx.get(AUTH, id);
+        if (!auth)
+            return authMissing(ctx, id);
+        const finalized = { status: 400, code: 'authorization_already_finalized', message: `This authorization has already been finalized (status ${String(auth.status)}).` };
+        // a webhook-approved authorization is decided, though still pending
+        if (auth.approved === true)
+            return ctx.refuse(finalized);
+        const refused = ctx.legal(AUTH, 'status', approved ? 'PostIssuingAuthorizationsAuthorizationApprove' : 'PostIssuingAuthorizationsAuthorizationDecline', auth.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        // a partial approval only for an amount-controllable presentment, and never a credit
+        const badAmount = approved && ctx.params.amount !== undefined ? partialApprovalRefused(ctx, auth) : undefined;
+        if (badAmount)
+            return badAmount;
+        const decidedAmount = approved && ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : Number(auth.amount) || 0;
+        const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+        const history = Array.isArray(auth.request_history) ? auth.request_history : [];
+        // an approval holds the funds and waits for the merchant's capture; a decline closes it
+        // (docs.stripe.com/issuing/purchases/authorizations, docs.stripe.com/issuing/funding/balance)
+        const hold = approved ? await holdFor(ctx, id, decidedAmount, currency) : null;
+        return ctx.reply(await ctx.write(AUTH, id, {
+            ...(approved ? {} : { status: 'closed' }), approved, pending_request: null,
+            ...(approved && ctx.params.amount !== undefined ? { amount: decidedAmount } : {}),
+            request_history: [...history, historyEntry({
+                    amount: decidedAmount, currency, approved, reason: approved ? 'webhook_approved' : 'webhook_declined', reasonMessage: null,
+                    createdSec: Number(ctx.now()), merchantAmount: Number(auth.merchant_amount) || decidedAmount,
+                    merchantCurrency: typeof auth.merchant_currency === 'string' ? auth.merchant_currency : currency,
+                })],
+            ...(hold ? { balance_transactions: [...(Array.isArray(auth.balance_transactions) ? auth.balance_transactions : []), hold.id] } : {}),
+        }, 'issuing_authorization.updated'));
+    };
+}
+/** The real-time window: "If Stripe doesn't receive your approve or decline response within 2 seconds, the
+ *  Authorization is automatically approved or declined based on your timeout settings"
+ *  (docs.stripe.com/issuing/controls/real-time-authorizations). */
+const REALTIME_WINDOW_SECONDS = 2;
+/** Time's decision on a real-time request no one answered, caught up to the World's clock: once its window has ended,
+ *  a pending authorization whose issuing_authorization.request went unanswered, and that no approve or decline decided,
+ *  is decided automatically, its request_history reason webhook_timeout ("webhook_timeout for all other failure modes",
+ *  the same page, beside webhook_error for a response Stripe cannot process).
+ *  Where the documentation stops and the twin decides: the timeout setting is the Dashboard's, which the API does not
+ *  answer, and the twin's is to decline; the window is measured in World time from the authorization's created. */
+export async function lapseRealtimeRequests(ctx) {
+    const now = Number(ctx.now());
+    const requested = new Set(ctx.rowsRaw('event').filter((e) => e._stripe_type === 'issuing_authorization.request').map((e) => String(e.data?.object?.id ?? '')));
+    for (const a of ctx.rowsRaw(AUTH)) {
+        if (a.status !== 'pending' || a.approved === true || !a.pending_request || !requested.has(String(a.id)))
+            continue;
+        const at = Number(a.created) + REALTIME_WINDOW_SECONDS;
+        if (now < at)
+            continue;
+        const id = String(a.id);
+        const currency = typeof a.currency === 'string' ? a.currency : 'usd';
+        const amount = Number(a.amount) || 0;
+        ctx.legal(AUTH, 'status', ctx.call.operation.id, 'pending', 'closed', id, 'time');
+        await ctx.write(AUTH, id, {
+            status: 'closed', approved: false, pending_request: null,
+            request_history: [...(Array.isArray(a.request_history) ? a.request_history : []), historyEntry({
+                    amount, currency, approved: false, reason: 'webhook_timeout', reasonMessage: null, createdSec: at,
+                    merchantAmount: Number(a.merchant_amount) || amount, merchantCurrency: typeof a.merchant_currency === 'string' ? a.merchant_currency : currency,
+                })],
+        }, 'issuing_authorization.updated');
+    }
+}
+/** An approval's hold: "If you approve the authorization, we deduct the `amount` from your Issuing balance and hold it
+ *  in reserve until the authorization is either captured, voided, or expired without capture"
+ *  (docs.stripe.com/issuing/purchases/authorizations). */
+async function holdFor(ctx, authId, amount, currency) {
+    return created(ctx, 'balance_transaction', {}, {
+        amount: -amount, currency, fee: 0, net: -amount, type: 'issuing_authorization_hold',
+        status: 'available', balance_type: 'issuing', reporting_category: 'issuing_authorization_hold',
+        available_on: ctx.now(), fee_details: [], source: authId,
+    });
+}
+/** An authorization approved as it is presented, its amount held: approved and pending until the merchant captures. */
+async function approvedAtOnce(ctx, subject, fields, held, entry) {
+    const hold = await holdFor(ctx, String(subject.id), held, String(fields.currency ?? 'usd'));
+    return ctx.reply(await created(ctx, AUTH, subject, { ...fields, amount: held, status: 'pending', approved: true, pending_request: null, request_history: [entry], balance_transactions: [hold.id] }));
+}
+/** An authorization as the platform's real-time answer makes it: approved (in part, only when the request was
+ *  amount-controllable), declined, or declined for an answer Stripe cannot read (docs.stripe.com/issuing/controls/
+ *  real-time-authorizations: the response's `approved` and `amount`; webhook_error "if we can't process your response"). */
+async function answeredByEndpoint(ctx, outcome, o) {
+    if (outcome.kind === 'approved') {
+        const held = o.controllable && outcome.amount !== undefined ? outcome.amount : o.amount;
+        return approvedAtOnce(ctx, o.subject, o.fields, held, o.entry({ amount: held, approved: true, reason: 'webhook_approved', reasonMessage: null }));
+    }
+    return outcome.kind === 'declined' ? o.decline('webhook_declined', null) : o.decline('webhook_error', outcome.message);
+}
+const present = async (ctx) => {
+    const params = ctx.params;
+    const card = typeof params.card === 'string' ? params.card : '';
+    if (!card)
+        return fail(ctx, 'Missing required param: card.', 400, 'parameter_missing');
+    const c = ctx.get(CARD, card);
+    if (!c)
+        return fail(ctx, `No such card: '${card}'`, 400, 'resource_missing');
+    if (params.amount === undefined)
+        return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
+    const amount = Math.trunc(Number(params.amount) || 0);
+    const currency = String(params.currency ?? c.currency ?? 'usd');
+    const createdSec = Number(ctx.now());
+    const cardholderId = holderId(c);
+    const merchant = merchantData(params.merchant_data);
+    const isAmountControllable = params.is_amount_controllable === true;
+    const authMethod = typeof params.authorization_method === 'string' ? params.authorization_method : 'online';
+    if (!['chip', 'contactless', 'keyed_in', 'online', 'swipe'].includes(authMethod))
+        return issuingRefusal(ctx, 'authorization_method');
+    const merchantAmount = params.merchant_amount !== undefined ? Math.trunc(Number(params.merchant_amount) || 0) : amount;
+    const merchantCurrency = typeof params.merchant_currency === 'string' ? params.merchant_currency : currency;
+    const authId = ctx.mint(AUTH);
+    const baseFields = {
+        amount, amount_details: null, authorization_method: authMethod,
+        balance_transactions: [], transactions: [],
+        currency, fleet: null, fuel: null, livemode: false,
+        merchant_amount: merchantAmount, merchant_currency: merchantCurrency, merchant_data: merchant,
+        metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
+        network_data: null,
+        verification_data: {
+            address_line1_check: 'not_provided', address_postal_code_check: 'not_provided',
+            authentication_exemption: null, cvc_check: 'match', expiry_check: 'match',
+            postal_code: null, three_d_secure: null,
+        },
+        wallet: null,
+    };
+    const subject = { id: authId, card, cardholder: cardholderId };
+    const entry = (o) => historyEntry({ ...o, currency, createdSec, merchantAmount, merchantCurrency });
+    const decline = async (reason, reasonMessage) => ctx.reply(await created(ctx, AUTH, subject, { ...baseFields, status: 'closed', approved: false, pending_request: null, request_history: [entry({ amount, approved: false, reason, reasonMessage })] }));
+    if (c.status === 'canceled')
+        return decline('card_canceled', 'The card has been canceled.');
+    if (c.status !== 'active')
+        return decline('card_inactive', 'The card is inactive.');
+    // what earlier approved authorizations on the card (or cardholder) already spent, for the limits
+    const prior = (key, value) => ctx.rows(AUTH).filter((a) => a[key] === value && a.approved === true)
+        .map((a) => ({ amount: Number(a.amount) || 0, created: Number(a.created) || 0, category: String(a.merchant_data?.category ?? '') }));
+    const controlsOpts = { amount, category: String(merchant.category ?? ''), country: merchant.country == null ? null : String(merchant.country), nowSec: createdSec };
+    const cardholderRow = cardholderId ? ctx.get(CH, cardholderId) : undefined;
+    const violation = spendingControlsViolation(c.spending_controls, { ...controlsOpts, priorApproved: prior('card', card) }) ??
+        spendingControlsViolation(cardholderRow?.spending_controls, { ...controlsOpts, priorApproved: prior('cardholder', cardholderId) });
+    if (violation)
+        return decline('spending_controls', violation);
+    // an authorization is paid from the Issuing balance, and declined when it cannot cover it
+    // (docs.stripe.com/issuing/funding/balance)
+    if ((balanceOf(ctx).issuing.get(currency) ?? 0) < amount)
+        return decline('insufficient_funds', 'Your Issuing balance does not have enough funds for this authorization.');
+    const pendingRequest = {
+        amount, amount_details: null, currency, is_amount_controllable: isAmountControllable,
+        merchant_amount: merchantAmount, merchant_currency: merchantCurrency, network_risk_score: null,
+    };
+    const endpoint = ctx.rows('webhook_endpoint').find((w) => w.status === 'enabled' && stripeEventMatches(w.enabled_events, 'issuing_authorization.request'));
+    // no real-time enrollment: "If you don't have a real-time authorization webhook, we approve the authorization without
+    // sending the issuing_authorization.request" (docs.stripe.com/issuing/purchases/authorizations), its outcome
+    // card_active, "approved according to your default Issuing settings"
+    if (!endpoint)
+        return approvedAtOnce(ctx, subject, baseFields, amount, entry({ amount, approved: true, reason: 'card_active', reasonMessage: null }));
+    // the request event's authorization carries pending_request, non-null only during the request
+    const requestObject = withCard(ctx, { object: 'issuing.authorization', id: authId, created: createdSec, ...baseFields, card, cardholder: cardholderId, status: 'pending', approved: false, pending_request: pendingRequest, request_history: [] });
+    // the delivered request and the stored event are one event under one id
+    const requestEvent = { id: nextStripeEventId(ctx.root), object: 'event', type: 'issuing_authorization.request', created: createdSec, livemode: false, data: { object: requestObject } };
+    const version = ctx.call.request.headers.get('stripe-version') ?? undefined;
+    await persistStripeEvent('issuing_authorization.request', requestObject, ctx.root, ctx.occurredAt, version, undefined, requestEvent.id);
+    const secret = typeof endpoint.secret === 'string' && endpoint.secret ? endpoint.secret : STRIPE_WEBHOOK_FALLBACK_SECRET;
+    const outcome = await requestAuthorizationDecision(String(endpoint.url), requestEvent, secret);
+    // a request no one answered (the World refused the delivery, it failed, or it timed out) is not a decision: the
+    // authorization stays pending with its request, for the deprecated approve or decline "within the timeout window of
+    // the real-time authorization flow" (the served spec), until lapseRealtimeRequests decides it when the window ends
+    if (outcome.kind === 'timeout')
+        return ctx.reply(await created(ctx, AUTH, subject, { ...baseFields, status: 'pending', approved: false, request_history: [], pending_request: pendingRequest }));
+    return answeredByEndpoint(ctx, outcome, { subject, fields: baseFields, amount, controllable: isAmountControllable, entry, decline });
+};
+// capturing an approved pending authorization, up to what it still holds; it closes unless told not to
+const captureAuthorization = async (ctx) => {
+    const id = at(ctx, 'authorization');
+    const auth = ctx.get(AUTH, id);
+    if (!auth)
+        return authMissing(ctx, id);
+    if (auth.approved !== true || auth.status !== 'pending')
+        return issuingRefusal(ctx, 'not_capturable', auth);
+    const closeAuthorization = ctx.params.close_authorization !== false;
+    const refused = ctx.legal(AUTH, 'status', 'PostTestHelpersIssuingAuthorizationsAuthorizationCapture', auth.status, closeAuthorization ? 'closed' : 'pending');
+    if (refused)
+        return ctx.refuse(refused);
+    const txns = Array.isArray(auth.transactions) ? auth.transactions : [];
+    const capturedSoFar = txns.map((t) => ctx.get(TXN, String(t))).reduce((s, t) => s + Math.abs(Number(t?.amount) || 0), 0);
+    const remaining = (Number(auth.amount) || 0) - capturedSoFar;
+    const captureAmount = ctx.params.capture_amount !== undefined ? Math.trunc(Number(ctx.params.capture_amount) || 0) : remaining;
+    if (captureAmount <= 0 || captureAmount > remaining)
+        return fail(ctx, 'Invalid capture_amount: must be a positive integer no greater than the uncaptured authorized amount.', 400, 'parameter_invalid_integer');
+    // the capture releases what the approval held and debits the transaction
+    const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+    const release = await created(ctx, 'balance_transaction', {}, {
+        amount: captureAmount, currency, fee: 0, net: captureAmount, type: 'issuing_authorization_release',
+        status: 'available', balance_type: 'issuing', reporting_category: 'issuing_authorization_release',
+        available_on: ctx.now(), fee_details: [], source: id,
+    });
+    const captured = await capture(ctx, id, { ...auth, card: cardId(auth) }, captureAmount);
+    return ctx.reply(await ctx.write(AUTH, id, {
+        ...(closeAuthorization ? { status: 'closed' } : {}),
+        transactions: [...txns, captured.txnId],
+        balance_transactions: [...(Array.isArray(auth.balance_transactions) ? auth.balance_transactions : []), release.id, captured.btId],
+    }, 'issuing_authorization.updated'));
+};
+// ── transactions ──
+const updateTransaction = async (ctx) => {
+    const id = at(ctx, 'transaction');
+    if (!ctx.get(TXN, id))
+        return fail(ctx, `No such transaction: '${id}'`, 404, 'resource_missing');
+    return ctx.reply(await ctx.write(TXN, id, ctx.params, 'issuing_transaction.updated'));
+};
+// a settlement with no authorization before it still debits the issuing balance
+const forceCapture = async (ctx) => {
+    const card = typeof ctx.params.card === 'string' ? ctx.params.card : '';
+    if (!card)
+        return fail(ctx, 'Missing required param: card.', 400, 'parameter_missing');
+    const c = ctx.get(CARD, card);
+    if (!c)
+        return fail(ctx, `No such card: '${card}'`, 400, 'resource_missing');
+    if (ctx.params.amount === undefined)
+        return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
+    const amount = Math.trunc(Number(ctx.params.amount) || 0);
+    if (amount <= 0)
+        return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+    const currency = String(ctx.params.currency ?? c.currency ?? 'usd');
+    const bt = await created(ctx, 'balance_transaction', {}, {
+        amount: -amount, currency, fee: 0, net: -amount, type: 'issuing_transaction',
+        status: 'available', balance_type: 'issuing', reporting_category: 'issuing_transaction',
+        available_on: ctx.now(), fee_details: [],
+    });
+    return ctx.reply(await created(ctx, TXN, { card, cardholder: holderId(c) }, {
+        type: 'capture', amount: -amount, currency,
+        merchant_amount: -amount, merchant_currency: typeof ctx.params.merchant_currency === 'string' ? ctx.params.merchant_currency : currency,
+        merchant_data: merchantData(ctx.params.merchant_data),
+        authorization: null, dispute: null, balance_transaction: bt.id,
+        livemode: false, metadata: {}, wallet: null, network_data: null, amount_details: null, purchase_details: null,
+    }));
+};
+// ── disputes: opened against a transaction, unsubmitted until submitted ──
+const disputeMissing = (ctx, id) => fail(ctx, `No such dispute: '${id}'`, 404, 'resource_missing');
+const openDispute = async (ctx) => {
+    const txn = typeof ctx.params.transaction === 'string' ? ctx.params.transaction : '';
+    if (!txn)
+        return fail(ctx, 'Missing required param: transaction.', 400, 'parameter_missing');
+    const t = ctx.get(TXN, txn);
+    if (!t)
+        return fail(ctx, `No such transaction: '${txn}'`, 400, 'resource_missing');
+    const ev = ctx.params.evidence && typeof ctx.params.evidence === 'object' ? ctx.params.evidence : undefined;
+    if (!ev || ev.reason === undefined || ev.reason === '')
+        return fail(ctx, 'Missing required param: evidence[reason].', 400, 'parameter_missing');
+    const amount = ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : Math.abs(Number(t.amount) || 0);
+    return ctx.reply(await created(ctx, DSP, ctx.params, { status: 'unsubmitted', amount, currency: t.currency ?? 'usd', livemode: false, metadata: {}, balance_transactions: null }));
+};
+const submitDispute = async (ctx) => {
+    const id = at(ctx, 'dispute');
+    const d = ctx.get(DSP, id);
+    if (!d)
+        return disputeMissing(ctx, id);
+    const refused = ctx.legal(DSP, 'status', 'PostIssuingDisputesDisputeSubmit', d.status, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    return ctx.reply(await ctx.write(DSP, id, { status: 'submitted' }, 'issuing_dispute.submitted'));
+};
+const updateDispute = async (ctx) => {
+    const id = at(ctx, 'dispute');
+    if (!ctx.get(DSP, id))
+        return disputeMissing(ctx, id);
+    return ctx.reply(await ctx.write(DSP, id, ctx.params, 'issuing_dispute.updated'));
+};
+// ── network tokens: minted by the card network (the twin's mint is a test helper outside Stripe's
+// surface); Stripe lets a token be set active, deleted or suspended ──
+const updateToken = async (ctx) => {
+    const id = at(ctx, 'token');
+    const t = ctx.get(TOK, id);
+    if (!t)
+        return fail(ctx, `No such issuing token: '${id}'`, 404, 'resource_missing');
+    const status = typeof ctx.params.status === 'string' ? ctx.params.status : '';
+    if (!['active', 'deleted', 'suspended'].includes(status))
+        return fail(ctx, 'Invalid status: must be active, deleted, or suspended.', 400, 'parameter_invalid_string_enum');
+    const refused = ctx.legal(TOK, 'status', 'PostIssuingTokensToken', t.status, status);
+    if (refused)
+        return ctx.refuse(refused);
+    return ctx.reply(await ctx.write(TOK, id, { status }, 'issuing_token.updated'));
+};
+// ── personalization designs: in review until Stripe's review (the test helpers in test mode) decides ──
+const designMissing = (ctx, id) => fail(ctx, `No such personalization design: '${id}'`, 404, 'resource_missing');
+/** Stripe's physical bundles are its catalog, not the account's: the twin serves the one its reference publishes
+ *  (docs.stripe.com/api/issuing/physical_bundles: "US Visa Credit White", standard, active, a card logo required and
+ *  carrier text optional). Where the documentation stops and the twin decides: the catalog is that one bundle, and its
+ *  second_line (required by the served spec, absent from the example) is optional. */
+const PHYSICAL_BUNDLES = [
+    { id: 'ics_NLuXJPDYSTjFON', object: 'issuing.physical_bundle', livemode: false, name: 'US Visa Credit White', features: { card_logo: 'required', carrier_text: 'optional', second_line: 'optional' }, status: 'active', type: 'standard' },
+];
+const listBundles = async (ctx) => ctx.reply({ object: 'list', url: '/v1/issuing/physical_bundles', has_more: false, data: PHYSICAL_BUNDLES.filter((b) => (ctx.params.status === undefined || b.status === ctx.params.status) && (ctx.params.type === undefined || b.type === ctx.params.type)) });
+const retrieveBundle = async (ctx) => {
+    const b = PHYSICAL_BUNDLES.find((x) => x.id === at(ctx, 'physical_bundle'));
+    return b ? ctx.reply(b) : fail(ctx, `No such physical bundle: '${at(ctx, 'physical_bundle')}'`, 404, 'resource_missing');
+};
+const createDesign = async (ctx) => {
+    const bundle = typeof ctx.params.physical_bundle === 'string' ? ctx.params.physical_bundle : '';
+    if (!bundle)
+        return fail(ctx, 'Missing required param: physical_bundle.', 400, 'parameter_missing');
+    if (!PHYSICAL_BUNDLES.some((b) => b.id === bundle))
+        return fail(ctx, `No such physical bundle: '${bundle}'`, 400, 'resource_missing');
+    const logo = filePurposeRefused(ctx, 'card_logo', ['issuing_logo']);
+    if (logo)
+        return logo;
+    return ctx.reply(await created(ctx, PD, {}, {
+        livemode: false, status: 'review', physical_bundle: bundle,
+        name: ctx.params.name ?? null, lookup_key: ctx.params.lookup_key ?? null,
+        card_logo: ctx.params.card_logo ?? null, carrier_text: ctx.params.carrier_text ?? null,
+        preferences: { is_default: false, is_platform_default: null },
+        rejection_reasons: { card_logo: [], carrier_text: [] },
+        metadata: ctx.params.metadata && typeof ctx.params.metadata === 'object' ? ctx.params.metadata : {},
+    }));
+};
+const listDesigns = async (ctx) => list(ctx, PD, where(ctx, newest(ctx, PD), {
+    status: (d, v) => d.status === v,
+    lookup_keys: (d, v) => (Array.isArray(v) ? v.map(String).includes(String(d.lookup_key)) : String(d.lookup_key) === String(v)),
+}));
+const updateDesign = async (ctx) => {
+    const id = at(ctx, 'personalization_design');
+    if (!ctx.get(PD, id))
+        return designMissing(ctx, id);
+    const logo = filePurposeRefused(ctx, 'card_logo', ['issuing_logo']);
+    if (logo)
+        return logo;
+    return ctx.reply(await ctx.write(PD, id, ctx.params, 'personalization_design.updated'));
+};
+function review(action, operationId) {
+    return async (ctx) => {
+        const id = at(ctx, 'personalization_design');
+        const d = ctx.get(PD, id);
+        if (!d)
+            return designMissing(ctx, id);
+        const refused = ctx.legal(PD, 'status', operationId, d.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const status = action === 'activate' ? 'active' : action === 'deactivate' ? 'inactive' : 'rejected';
+        // a rejection records its reasons: the reject helper's required rejection_reasons, "The reason(s) the
+        // personalization design was rejected" (the served spec), per card_logo and carrier_text
+        const given = ctx.params.rejection_reasons && typeof ctx.params.rejection_reasons === 'object' ? ctx.params.rejection_reasons : undefined;
+        if (action === 'reject' && !given)
+            return fail(ctx, 'Missing required param: rejection_reasons.', 400, 'parameter_missing');
+        const reasons = action === 'reject' ? { rejection_reasons: { card_logo: Array.isArray(given.card_logo) ? given.card_logo : [], carrier_text: Array.isArray(given.carrier_text) ? given.carrier_text : [] } } : {};
+        return ctx.reply(await ctx.write(PD, id, { status, ...reasons }, `personalization_design.${action}`));
+    };
+}
+export const issuing = {
+    PostIssuingCardholders: createCardholder,
+    PostIssuingCardholdersCardholder: updateCardholder,
+    PostIssuingCards: createCard,
+    GetIssuingCards: listCards,
+    PostIssuingCardsCard: updateCard,
+    GetIssuingAuthorizations: listAuthorizations,
+    GetIssuingAuthorizationsAuthorization: retrieveAuthorization,
+    PostIssuingAuthorizationsAuthorization: updateAuthorization,
+    PostIssuingAuthorizationsAuthorizationApprove: decide(true),
+    PostIssuingAuthorizationsAuthorizationDecline: decide(false),
+    PostTestHelpersIssuingAuthorizations: present,
+    PostTestHelpersIssuingAuthorizationsAuthorizationCapture: captureAuthorization,
+    PostIssuingTransactionsTransaction: updateTransaction,
+    PostTestHelpersIssuingTransactionsCreateForceCapture: forceCapture,
+    PostIssuingDisputes: openDispute,
+    PostIssuingDisputesDisputeSubmit: submitDispute,
+    PostIssuingDisputesDispute: updateDispute,
+    PostIssuingTokensToken: updateToken,
+    GetIssuingPhysicalBundles: listBundles,
+    GetIssuingPhysicalBundlesPhysicalBundle: retrieveBundle,
+    PostIssuingPersonalizationDesigns: createDesign,
+    GetIssuingPersonalizationDesigns: listDesigns,
+    PostIssuingPersonalizationDesignsPersonalizationDesign: updateDesign,
+    PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignActivate: review('activate', 'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignActivate'),
+    PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignDeactivate: review('deactivate', 'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignDeactivate'),
+    PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignReject: review('reject', 'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignReject'),
+};

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

@@ -0,0 +1,54 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** The connected account a request acts for, or undefined for the platform. */
+export declare const actingAccount: (ctx: SemanticsContext) => string | undefined;
+/** A captured charge's credit: its amount less the fee, pending two days unless the card (a number, or a test
+ *  payment method or token named for it) settles at once. The
+ *  caller mints the charge's id first and stores the returned id as the charge's balance_transaction. */
+export declare function settleCharge(ctx: SemanticsContext, chargeId: string, amount: number, currency: string, card?: string): Promise<string>;
+/** A refund's debit, at once, on the acting account's balance unless one is named (null names the platform). */
+export declare function settleRefund(ctx: SemanticsContext, refundId: string, amount: number, currency: string, account?: string | null | undefined): Promise<string>;
+/** What an account had available in a currency at a moment: every entry of its payments balance whose funds had come
+ *  due by then. */
+export declare function availableAt(ctx: SemanticsContext, account: string | undefined, currency: string, at: number): number;
+/** The moments after `from` and up to `until` when funds of an account came due, in order: when a held refund can
+ *  next be covered. */
+export declare function fundsDueBetween(ctx: SemanticsContext, account: string | undefined, currency: string, from: number, until: number): number[];
+/** A dispute's debit, at once: the disputed amount and the dispute fee (the twin's 1500 cents, Stripe's US $15). */
+export declare function settleDispute(ctx: SemanticsContext, disputeId: string, amount: number, currency: string): Promise<string>;
+/** A won dispute's credit, at once: the disputed amount returned (docs.stripe.com/disputes/how-disputes-work). Where the
+ *  documentation stops and the twin decides: the dispute fee is not returned. */
+export declare function settleDisputeWon(ctx: SemanticsContext, disputeId: string, amount: number, currency: string): Promise<string>;
+/** An account's ledger entries an automatic payout has not yet paid out: every entry on its payments balance that no
+ *  automatic payout took (the automatic payouts' own debits excluded), as stored. */
+export declare function unpaidEntries(ctx: SemanticsContext, account: string | undefined): Row[];
+/** An automatic payout's debit at `at`, and the entries it pays out marked with it, so the ledger lists them under
+ *  the payout (docs.stripe.com/api/balance_transactions/list#balance_transaction_list-payout). */
+export declare function settleAutomaticPayout(ctx: SemanticsContext, payoutId: string, amount: number, currency: string, account: string | undefined, at: number, entries: Row[]): Promise<string>;
+/** A payout's debit (negative) or a cancellation's or reversal's credit (positive), at once, on the payout's account. */
+export declare function settlePayout(ctx: SemanticsContext, payoutId: string, amount: number, currency: string, account?: string | null | undefined): Promise<string>;
+/** A transfer's two entries: out of the platform's balance at once, into the destination's when `availableOn` comes
+ *  (a plain transfer's funds are available already). Answers the platform's entry. */
+export declare function settleTransfer(ctx: SemanticsContext, transferId: string, amount: number, currency: string, destination: string, availableOn?: number, fromPending?: boolean): Promise<string>;
+/** A transfer reversal's two entries: back into the platform's balance, out of the destination's. */
+export declare function settleTransferReversal(ctx: SemanticsContext, reversalId: string, amount: number, currency: string, destination: string): Promise<string>;
+/** A direct charge's application fee: out of the connected account's balance, into the platform's. */
+export declare function settleApplicationFee(ctx: SemanticsContext, feeId: string, amount: number, currency: string, account: string): Promise<string>;
+/** A top-up's credit, to the payments balance or, with `destination_balance=issuing`, to Issuing's
+ *  (docs.stripe.com/issuing/funding/balance). Where the documentation stops and the twin decides: a test-mode top-up
+ *  is available at once. */
+export declare function settleTopup(ctx: SemanticsContext, topupId: string, amount: number, currency: string, destination: string): Promise<string>;
+/** Time's settlements, written: each entry on the acting account's balance whose funds came due by the World's clock
+ *  moves pending → available (the clock's move the machine allows), so a settlement is recorded once. A read already
+ *  sees it (asOf); the record is what lets Stripe's balance.available be sent once (stripe-server.ts, the drain).
+ *  Answers the entries that moved. */
+export declare function settleDueEntries(ctx: SemanticsContext): Promise<Row[]>;
+/** An account's balance, by currency: what the clock has made available, what is still pending, and Issuing's own. */
+export declare function balanceOf(ctx: SemanticsContext, account?: string | undefined): {
+    available: Map<string, number>;
+    pending: Map<string, number>;
+    issuing: Map<string, number>;
+};
+/** balance_insufficient when a payout or transfer would take more than the account has available in its currency. */
+export declare function refusePayout(ctx: SemanticsContext, amount: number, currency: string, account?: string | undefined): Response | undefined;
+export declare const ledger: Record<string, Semantics>;