@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/semantics/issuing.js

@@ -1,575 +0,0 @@
-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; a capture that closes the authorization
-    // releases ALL it still holds, the uncaptured rest included: the amount is held "until the authorization is either
-    // captured, voided, or expired without capture" (docs.stripe.com/issuing/purchases/authorizations), and a closed
-    // authorization can be captured no further (close_authorization "Defaults to true. Set to false to enable
-    // multi-capture flows", the served spec). A capture that keeps it open releases only what it captured.
-    const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
-    const released = closeAuthorization ? remaining : captureAmount;
-    const release = await created(ctx, 'balance_transaction', {}, {
-        amount: released, currency, fee: 0, net: released, 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

@@ -1,59 +0,0 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** Whether a charge's funds go straight to the available balance: a bypass card as a raw number, a test name (pm_card_*
- *  or tok_*), or a stored PaymentMethod made from one (which records it as what follows its success, after-payment.ts);
- *  or a US bank account, stored or one of Stripe's test bank accounts named as one (pm_usBankAccount_*). */
-export declare function bypassesPending(ctx: SemanticsContext, card: string | undefined): boolean;
-/** 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 bypasses the pending
- *  balance (bypassesPending), when it is due 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 `fromCharge` (its
- *  charge's funds' availability) comes (a plain transfer, with no `fromCharge`, moves funds available already).
- *  Answers the platform's entry. */
-export declare function settleTransfer(ctx: SemanticsContext, transferId: string, amount: number, currency: string, destination: string, fromCharge?: 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).
- *  Funds that were available at once and not yet sent are taken too, and marked sent. Answers the entries taken. */
-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>;