@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/semantics/payment-intents.js

@@ -1,452 +0,0 @@
-import { asBool, cardError, chargeDefaults, declineFor, microdepositsNextAction, mintClientSecret, requiresAuthentication, requiresMicrodeposits, threeDsNextAction, validateMoney, verifyMicrodeposits, } from "../stripe-twin.js";
-import { afterCharge, mintMandate } from "./after-payment.js";
-import { cancelAuthorization, captureAuthorization } from "./charges.js";
-import { settleCharge } from "./ledger.js";
-import { materializeTestMethod, methodFromData, microdepositsAsked, paymentMethodDetails } from "./payment-methods.js";
-import { at_, confirmOnly, created, fail, finder, search } from "./shared.js";
-const PI = 'payment_intent';
-/** Bookkeeping: the intents whose caller named the methods (payment_method_types, allowed_payment_method_types) on
- *  create. The twin's default list (['card']) stands for Stripe's choice and restricts nothing, so only a named list
- *  refuses a confirm with a method of another type. Kept apart from the intent: a `_` subject is never pushed
- *  (world-core isTwinBookkeeping). */
-const TYPES_GIVEN = '_payment_intent_types_given';
-/** Whether the intent's caller named its methods: on create (TYPES_GIVEN), or by an update that set its
- *  payment_method_types ("Alternatively, update the allowed payment_method_types for this PaymentIntent",
- *  methodNotAllowed below), which the generic update writes as given, so the intent's history holds it. */
-const typesGiven = (ctx, id) => ctx.tree().some((r) => r.type === TYPES_GIVEN && r.id === id)
-    || ctx.history(PI, id).some((e) => e.operation !== 'payment_intent.create' && Array.isArray(e.fields?.payment_method_types));
-const send = (ctx, r) => ctx.reply(r.body, r.status);
-// ── THE MONEY MODEL, continued: a succeeded intent has a Charge ──
-//
-// Real Stripe always materializes a Charge when a PaymentIntent succeeds and points the intent's
-// `latest_charge` at it: the charge is what a refund lands on, so an intent that succeeds without
-// one cannot answer "refund this payment" at all. Idempotent against a repeated confirm: an intent
-// that already names a successful charge keeps it (a second one would double the money collected); a
-// declined attempt's failed charge is history, and the payment that succeeds makes its own. The id is
-// returned so the caller folds `latest_charge` into the same intent write (one write, one event). The
-// charge is written as the event Stripe sends for it, `charge.succeeded` ("Occurs whenever a charge is
-// successful", docs.stripe.com/api/events/types); Stripe has no `charge.created`.
-/** What every charge an intent makes carries of it: its transfer_group, which "identifies the resulting payment as part
- *  of a group" (docs.stripe.com/api/payment_intents/object), its description and its metadata. */
-function intentCarries(pi) {
-    return {
-        ...(typeof pi.transfer_group === 'string' ? { transfer_group: pi.transfer_group } : {}),
-        ...(typeof pi.description === 'string' ? { description: pi.description } : {}),
-        // "When a PaymentIntent creates a Charge, the metadata copies to the Charge in a one-time snapshot"
-        // (docs.stripe.com/metadata, "Copy metadata to another object")
-        ...(pi.metadata && typeof pi.metadata === 'object' ? { metadata: { ...pi.metadata } } : {}),
-    };
-}
-export async function mintCharge(ctx, piId, pi, amount) {
-    const already = ctx.get(PI, piId)?.latest_charge;
-    if (typeof already === 'string' && ctx.get('charge', already)?.status === 'succeeded')
-        return already;
-    const chargeId = ctx.mint('charge');
-    const bt = await settleCharge(ctx, chargeId, amount, String(pi.currency ?? 'usd'), typeof pi.payment_method === 'string' ? pi.payment_method : undefined);
-    await created(ctx, 'charge', {
-        id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
-        ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
-        ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
-        ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
-        ...intentCarries(pi),
-    }, { ...chargeDefaults(chargeId, amount, true, ctx.occurredAt), balance_transaction: bt, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
-    await afterCharge(ctx, chargeId, { amount, currency: String(pi.currency ?? 'usd'), payment_intent: piId, application_fee_amount: pi.application_fee_amount, destination: pi.transfer_data?.destination }, pi.payment_method);
-    return chargeId;
-}
-/** A manual-capture intent's authorization: "Separate payment authorization and capture to create a charge now, but
- *  capture funds later", and on capture "A partial capture automatically releases the remaining amount"
- *  (docs.stripe.com/payments/place-a-hold-on-a-payment-method). The charge succeeded and is not captured, holding the
- *  amount until capture_before, with nothing on the balance yet. Written as
- *  charge.succeeded, as a charge made with capture=false is (charges.ts); its capture writes charge.captured
- *  (captureAuthorization). Where the documentation stops and the twin decides: the events page names no event for an
- *  authorization of its own, so the authorized charge sends charge.succeeded, its status being succeeded. */
-export async function authorizeCharge(ctx, piId, pi, amount) {
-    const chargeId = ctx.mint('charge');
-    await created(ctx, 'charge', {
-        id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
-        ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
-        ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
-        ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
-        ...intentCarries(pi),
-    }, { ...chargeDefaults(chargeId, amount, false, ctx.occurredAt), balance_transaction: null, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
-    return chargeId;
-}
-/**
- * An intent an invoice collects through succeeded (the default_incomplete subscription flow: create
- * now, confirm client-side): its invoice is paid and, when it is a subscription's first, the
- * subscription leaves incomplete for active. Both are moves the invoice and subscription machines
- * declare under the confirming operation. No-op when the intent names no invoice, or the invoice is
- * already paid (a duplicate confirm) or void (voiding ends what it collects).
- */
-async function payInvoiceOf(ctx, pi, operationId, actor) {
-    const invoiceId = typeof pi.invoice === 'string' ? pi.invoice : undefined;
-    const invoice = invoiceId ? ctx.get('invoice', invoiceId) : undefined;
-    if (!invoiceId || !invoice || invoice.status === 'paid' || invoice.status === 'void')
-        return;
-    if (ctx.legal('invoice', 'status', operationId, invoice.status, 'paid', invoiceId, actor))
-        return;
-    const amount = Number(invoice.total ?? invoice.amount_due) || 0;
-    // `invoice.pay` is the event the standalone pay action sends: invoice.paid
-    await ctx.write('invoice', invoiceId, {
-        status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0,
-        status_transitions: { ...(invoice.status_transitions ?? {}), paid_at: ctx.now() },
-    }, 'invoice.pay');
-    const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
-    const sub = subId ? ctx.get('subscription', subId) : undefined;
-    if (subId && sub && sub.status === 'incomplete' && !ctx.legal('subscription', 'status', operationId, sub.status, 'active', subId, actor)) {
-        await ctx.write('subscription', subId, { status: 'active' }, 'subscription.update');
-    }
-}
-/** The intent the path names, and the machine's refusal when this operation may not move it. */
-function load(ctx, operationId) {
-    const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
-    if (!pi)
-        return { answer: ctx.notFound(PI, String(ctx.id)) };
-    const refusal = ctx.legal(PI, 'status', operationId, pi.status);
-    return refusal ? { answer: ctx.refuse(refusal) } : { pi };
-}
-const create = async (ctx) => {
-    const params = ctx.params;
-    const bad = validateMoney(params);
-    if (bad)
-        return send(ctx, bad);
-    // what describes a confirmation needs one: error_on_requires_action, mandate, mandate_data, off_session and return_url
-    // are each, in the served spec, a parameter that "can only be used with `confirm=true`" (shared.ts confirmOnly)
-    const unconfirmed = confirmOnly(ctx, ['error_on_requires_action', 'mandate', 'mandate_data', 'off_session', 'return_url'], asBool(params.confirm));
-    if (unconfirmed)
-        return unconfirmed;
-    // automatic_payment_methods: when enabled, Stripe selects eligible methods and answers the
-    // normalized { enabled, allow_redirects } object
-    const apmIn = params.automatic_payment_methods;
-    const apmEnabled = apmIn && typeof apmIn === 'object' ? asBool(apmIn.enabled) : false;
-    const automatic_payment_methods = apmEnabled ? { enabled: true, allow_redirects: apmIn.allow_redirects ?? 'always' } : null;
-    // the methods it may be paid with: allowed_payment_method_types in the served version, payment_method_types for a
-    // caller pinned to an earlier one (docs.stripe.com/api/payment_intents/create)
-    const given = Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types : params.payment_method_types;
-    const payment_method_types = Array.isArray(given) ? given.map(String) : ['card'];
-    // `confirm` is an instruction, not a field: `confirm=true` attempts to confirm the intent at once
-    // (https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm)
-    const { automatic_payment_methods: _a, payment_method_types: _p, allowed_payment_method_types: _ap, id: provided, expand: _e, confirm: confirmNow, payment_method_data: data, mandate_data: _mandate, ...rest } = params;
-    // a create's payment_method_data makes its method, as a confirm's does (payment-methods.ts methodFromData)
-    const made = await methodFromData(ctx, data);
-    if (made)
-        rest.payment_method = made;
-    // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
-    const id = typeof provided === 'string' && provided ? provided : ctx.mint(PI);
-    // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
-    const hasMethod = typeof rest.payment_method === 'string' && rest.payment_method !== '';
-    if (hasMethod)
-        ctx.legal(PI, 'status', 'PostPaymentIntents', 'requires_payment_method', 'requires_confirmation', id);
-    const body = await ctx.write(PI, id, {
-        object: 'payment_intent',
-        created: ctx.now(),
-        status: hasMethod ? 'requires_confirmation' : 'requires_payment_method',
-        client_secret: mintClientSecret(id),
-        livemode: false,
-        capture_method: 'automatic',
-        amount_capturable: 0,
-        amount_received: 0,
-        next_action: null,
-        automatic_payment_methods,
-        payment_method_types,
-        ...(Array.isArray(params.allowed_payment_method_types) ? { allowed_payment_method_types: payment_method_types } : {}),
-        payment_method_options: params.payment_method_options ?? {},
-        ...rest,
-    }, 'payment_intent.create');
-    if (Array.isArray(given))
-        await ctx.record(TYPES_GIVEN, { payment_intent: id }, id);
-    if (asBool(confirmNow))
-        return confirmIntent(ctx, body, {});
-    return ctx.reply(ctx.expand(PI, body));
-};
-const confirm = async (ctx) => {
-    const loaded = load(ctx, 'PostPaymentIntentsIntentConfirm');
-    if ('answer' in loaded)
-        return loaded.answer;
-    const { expand: _e, payment_method_data: data, mandate_data: _mandate, ...params } = ctx.params;
-    // a confirm's payment_method_data makes the method it pays with; neither it nor mandate_data is a field of the intent
-    const made = await methodFromData(ctx, data);
-    return confirmIntent(ctx, loaded.pi, made ? { ...params, payment_method: made } : params);
-};
-/** The type of the payment method an intent is paid with: its PaymentMethod's, or a documented test name's (pm_card_*,
- *  tok_* a card; pm_usBankAccount_* a US bank account), else unknown. */
-function methodType(ctx, method) {
-    if (typeof method !== 'string' || !method)
-        return undefined;
-    const row = ctx.get('payment_method', method);
-    if (row)
-        return typeof row.type === 'string' ? row.type : undefined;
-    if (/^pm_us_?bank_?account/i.test(method))
-        return 'us_bank_account';
-    if (/^(pm_card_|tok_)/.test(method))
-        return 'card';
-    return undefined;
-}
-/** A confirm with a payment method of a type the intent's caller did not allow, refused as Stripe refuses it: "The
- *  PaymentMethod provided (card_present) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of
- *  the following types: card. Alternatively, update the allowed payment_method_types for this PaymentIntent to include
- *  "card_present"" (a real answer quoted in github.com/stripe/stripe-terminal-react-native/issues/745, an intent made
- *  with payment_method_types ['card']). Only a list the caller gave restricts: without one Stripe offers the methods
- *  the account enables, which the twin does not model. Where the evidence stops: that answer's code is not quoted; the
- *  twin answers payment_intent_invalid_parameter ("One or more provided parameters wasn't allowed for the given
- *  operation on the PaymentIntent", docs.stripe.com/error-codes), param payment_method. */
-function methodNotAllowed(ctx, existing, params) {
-    const types = Array.isArray(params.payment_method_types) ? params.payment_method_types.map(String)
-        : Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types.map(String)
-            : typesGiven(ctx, String(existing.id)) && Array.isArray(existing.payment_method_types) ? existing.payment_method_types.map(String) : undefined;
-    if (!types)
-        return undefined;
-    const type = methodType(ctx, params.payment_method ?? existing.payment_method);
-    if (!type || types.includes(type))
-        return undefined;
-    return ctx.refuse({ status: 400, code: 'payment_intent_invalid_parameter', param: 'payment_method', message: `The PaymentMethod provided (${type}) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types: ${types.join(', ')}. Alternatively, update the allowed payment_method_types for this PaymentIntent to include "${type}"` });
-}
-/** Confirm an intent the confirm machine allows to move: the confirm action, and a create with `confirm=true`. */
-async function confirmIntent(ctx, existing, params) {
-    const id = String(existing.id);
-    // a payment names a mandate only an active one authorizes: an inactive mandate "was rejected, revoked, or previously
-    // used, and may not be used to initiate future payments" (docs.stripe.com/api/mandates/object), refused as
-    // payment_intent_mandate_invalid, "The provided mandate is invalid and can't be used for the payment intent"
-    // (docs.stripe.com/error-codes)
-    const named = typeof params.mandate === 'string' ? params.mandate : typeof existing.mandate === 'string' ? existing.mandate : undefined;
-    if (named && ctx.get('mandate', named)?.status !== 'active')
-        return fail(ctx, 'The provided mandate is invalid and can\'t be used for the payment intent.', 400, 'payment_intent_mandate_invalid');
-    const notAllowed = methodNotAllowed(ctx, existing, params);
-    if (notAllowed)
-        return notAllowed;
-    // a declining test card leaves the intent needing a payment method, with the error on it and a 402
-    const decline = declineFor(finder(ctx), params, existing);
-    if (decline) {
-        // Stripe records the attempt: a failed charge the intent's latest_charge names, the declined card on
-        // last_payment_error (a test name made a real PaymentMethod), and no payment_method left on the intent
-        // (docs.stripe.com/payments/paymentintents/lifecycle, docs.stripe.com/declines)
-        const ref = params.payment_method ?? existing.payment_method;
-        let pmId = typeof ref === 'string' ? ref : undefined;
-        if (pmId && !ctx.get('payment_method', pmId) && pmId.startsWith('pm_card_'))
-            pmId = String((await materializeTestMethod(ctx, pmId, typeof existing.customer === 'string' ? existing.customer : null)).id);
-        const pm = pmId ? ctx.get('payment_method', pmId) : undefined;
-        const amount = Number(params.amount ?? existing.amount) || 0;
-        const chargeId = ctx.mint('charge');
-        await created(ctx, 'charge', {
-            id: chargeId, amount, currency: existing.currency ?? 'usd', payment_intent: id,
-            ...(typeof existing.customer === 'string' ? { customer: existing.customer } : {}),
-            ...(pmId ? { payment_method: pmId } : {}),
-            ...intentCarries({ ...existing, ...params }),
-        }, {
-            ...chargeDefaults(chargeId, 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: pmId ? paymentMethodDetails(ctx, pmId) ?? null : null,
-        }, { operation: 'charge.failed' }); // "Occurs whenever a failed charge attempt occurs." (docs.stripe.com/api/events/types)
-        const { payment_method: _pm, ...rest } = params;
-        const last_payment_error = { type: 'card_error', code: decline.code, ...(decline.decline_code ? { decline_code: decline.decline_code } : {}), message: decline.message, param: 'card', charge: chargeId, payment_method: pm ?? null };
-        const failed = await ctx.write(PI, id, { ...rest, payment_method: null, latest_charge: chargeId, status: 'requires_payment_method', last_payment_error }, 'payment_intent.payment_failed');
-        return send(ctx, cardError(decline, { payment_intent: failed, charge: chargeId }));
-    }
-    // a bank debit that needs micro-deposit verification waits in requires_action
-    const method = typeof params.payment_method === 'string' ? params.payment_method : typeof existing.payment_method === 'string' ? existing.payment_method : undefined;
-    // a bank transfer is paid from the customer's cash balance, or waits for the transfer (fundFromCashBalance)
-    if (method && ctx.get('payment_method', method)?.type === 'customer_balance')
-        return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, { ...existing, ...params }, params)));
-    if (requiresMicrodeposits(params, existing) || microdepositsAsked(ctx, params, existing, method)) {
-        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: microdepositsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
-    }
-    // 3DS: the first confirm asks for authentication; a second one completes it
-    if (existing.status !== 'requires_action' && requiresAuthentication(params, existing)) {
-        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: threeDsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
-    }
-    // manual capture authorizes and waits for /capture: the authorization is a charge, succeeded and not captured, the
-    // intent's latest_charge
-    if ((params.capture_method ?? existing.capture_method) === 'manual') {
-        const amount = Number(existing.amount ?? params.amount ?? 0);
-        const charge = await authorizeCharge(ctx, id, { ...existing, ...params }, amount);
-        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_capture', amount_capturable: amount, amount_received: 0, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.amount_capturable_updated')));
-    }
-    // a bank debit is submitted and settles later (beginBankDebit)
-    if (isBankDebit(ctx, method))
-        return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, id, params)));
-    const amount = Number(existing.amount ?? params.amount ?? 0);
-    // a succeeded intent has a Charge, and latest_charge names it: what a refund of it lands on
-    const charge = await mintCharge(ctx, id, { ...existing, ...params }, amount);
-    const body = await ctx.write(PI, id, { ...params, status: 'succeeded', amount_received: amount, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.confirm');
-    await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentConfirm');
-    return ctx.reply(ctx.expand(PI, body));
-}
-const capture = async (ctx) => {
-    const loaded = load(ctx, 'PostPaymentIntentsIntentCapture');
-    if ('answer' in loaded)
-        return loaded.answer;
-    const pi = loaded.pi;
-    const authorized = Number(pi.amount_capturable ?? pi.amount ?? 0);
-    // amount_to_capture lowers the captured amount (a partial capture); it never raises it
-    const asked = ctx.params.amount_to_capture !== undefined ? Math.max(0, Math.trunc(Number(ctx.params.amount_to_capture) || 0)) : authorized;
-    const captured = Math.min(asked, authorized);
-    // the authorization confirm made is captured; an intent authorized before it was kept is charged as before
-    const auth = typeof pi.latest_charge === 'string' ? ctx.get('charge', pi.latest_charge) : undefined;
-    const held = auth && auth.status === 'succeeded' && auth.captured === false ? auth : undefined;
-    if (held) {
-        const refused = ctx.legal('charge', 'captured', 'PostPaymentIntentsIntentCapture', 'false', 'true', String(held.id));
-        if (refused)
-            return ctx.refuse(refused);
-        await captureAuthorization(ctx, held, captured, 'PostPaymentIntentsIntentCapture');
-        await afterCharge(ctx, String(held.id), { amount: captured, currency: String(pi.currency ?? 'usd'), payment_intent: String(pi.id), application_fee_amount: pi.application_fee_amount, destination: pi.transfer_data?.destination }, pi.payment_method);
-    }
-    const charge = held ? String(held.id) : await mintCharge(ctx, String(pi.id), pi, captured);
-    const body = await ctx.write(PI, String(pi.id), { status: 'succeeded', amount_received: captured, amount_capturable: 0, latest_charge: charge }, 'payment_intent.succeeded');
-    await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentCapture');
-    return ctx.reply(ctx.expand(PI, body));
-};
-/** An increment that does not raise the authorization. */
-function incrementTooSmall(ctx) {
-    return ctx.refuse({ status: 400, code: 'parameter_invalid_integer', message: 'The new amount must be greater than the current amount of the PaymentIntent.' });
-}
-const incrementAuthorization = async (ctx) => {
-    const loaded = load(ctx, 'PostPaymentIntentsIntentIncrementAuthorization');
-    if ('answer' in loaded)
-        return loaded.answer;
-    const pi = loaded.pi;
-    if (ctx.params.amount === undefined)
-        return ctx.refuse({ status: 400, code: 'parameter_missing', message: 'Missing required param: amount.' });
-    const amount = Math.trunc(Number(ctx.params.amount) || 0);
-    if (!Number.isInteger(amount) || amount <= Number(pi.amount ?? 0))
-        return incrementTooSmall(ctx);
-    // the authorization the charge holds grows with it: "If the incremental authorization fails ... no other fields on
-    // the PaymentIntent or Charge update" (docs.stripe.com/api/payment_intents/increment_authorization), so on success the
-    // charge's amount is the new authorized amount. Where the documentation stops and the twin decides: the charge's
-    // update sends no event of its own (the events page names none for it).
-    const held = typeof pi.latest_charge === 'string' ? ctx.get('charge', pi.latest_charge) : undefined;
-    if (held && held.captured === false)
-        await ctx.write('charge', String(held.id), { amount }, 'charge.authorization_incremented');
-    return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(pi.id), { amount, amount_capturable: amount }, 'payment_intent.amount_capturable_updated')));
-};
-const cancel = async (ctx) => {
-    const loaded = load(ctx, 'PostPaymentIntentsIntentCancel');
-    if ('answer' in loaded)
-        return loaded.answer;
-    const cancellation_reason = typeof ctx.params.cancellation_reason === 'string' ? ctx.params.cancellation_reason : 'requested_by_customer';
-    // "For PaymentIntents with a `status` of `requires_capture`, the remaining `amount_capturable` is automatically
-    // refunded" (docs.stripe.com/api/payment_intents/cancel): the authorization is released (charges.ts)
-    const held = loaded.pi.status === 'requires_capture' && typeof loaded.pi.latest_charge === 'string' ? ctx.get('charge', loaded.pi.latest_charge) : undefined;
-    if (held && held.captured === false && held.refunded !== true)
-        await cancelAuthorization(ctx, held);
-    return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(loaded.pi.id), { status: 'canceled', cancellation_reason, amount_capturable: 0 }, 'payment_intent.canceled')));
-};
-const verifyMicrodepositsHandler = async (ctx) => {
-    const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
-    if (!pi)
-        return ctx.notFound(PI, String(ctx.id));
-    // the deposit amounts are checked before the intent's state, as Stripe does
-    const wrong = verifyMicrodeposits(ctx.params, pi);
-    if (wrong)
-        return send(ctx, wrong);
-    const refusal = ctx.legal(PI, 'status', 'PostPaymentIntentsIntentVerifyMicrodeposits', pi.status);
-    if (refusal)
-        return ctx.refuse(refusal);
-    const amount = Number(pi.amount) || 0;
-    // a debit saved for reuse ("If you want to reuse the payment method in the future, provide the setup_future_usage
-    // parameter with the value of off_session", the ACH page) is authorized for many payments (multi_use, "Represents
-    // permission given for multiple payments"); else for this one (single_use, "a one-time permission given for a single
-    // payment", docs.stripe.com/api/mandates/object)
-    const reuse = pi.setup_future_usage === 'off_session' || pi.setup_future_usage === 'on_session';
-    const mandate = reuse ? await mintMandate(ctx, pi.payment_method, 'multi_use') : await mintMandate(ctx, pi.payment_method, 'single_use', amount, String(pi.currency ?? 'usd'));
-    // "When the bank account is successfully verified, Stripe returns the PaymentIntent object with a status of
-    // `processing`" (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api)
-    return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, String(pi.id), { mandate })));
-};
-// ── a bank debit is submitted, and settles ──
-//
-// ACH Direct Debit "is a delayed notification payment method ... The PaymentIntent you create initially has a status
-// of `processing`. After the payment has succeeded, the PaymentIntent status is updated from `processing` to
-// `succeeded`"; verification by micro-deposits returns "a status of `processing`, and sends a payment_intent.processing
-// webhook event"; and, the twin being a test-mode account: "Test transactions settle instantly and are added to your
-// available test balance. This behavior differs from live mode, where transactions can take multiple days to settle"
-// (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api). A confirm answers processing; the
-// debit succeeds at that same instant of the World's clock, caught up before the next request is answered (as
-// renewals and payouts are). The page's test accounts give each debit its outcome: pm_usBankAccount_success
-// (000123456789) "The payment succeeds"; pm_usBankAccount_processing (000000000009) "The payment stays in processing
-// indefinitely". Where the documentation stops and the twin decides: its Charge is made when it succeeds (the page
-// names none while it processes); the failing test accounts (closed, no account, insufficient funds, debit not
-// authorized, invalid currency, dispute, weekly limit, Radar block) are not modelled and succeed.
-/** Whether the method an intent is confirmed with is a bank debit: a us_bank_account PaymentMethod, or one of Stripe's
- *  test bank accounts named as one (pm_usBankAccount_*, pm_us_bank_account). */
-export function isBankDebit(ctx, method) {
-    if (typeof method !== 'string')
-        return false;
-    return ctx.get('payment_method', method)?.type === 'us_bank_account' || /^pm_us_?bank_?account/i.test(method);
-}
-/** Whether a bank debit stays processing: the page's pm_usBankAccount_processing, or its account 000000000009. */
-function staysProcessing(ctx, method) {
-    if (method === 'pm_usBankAccount_processing')
-        return true;
-    const bank = typeof method === 'string' ? ctx.get('payment_method', method)?.us_bank_account : undefined;
-    return bank?.last4 === '0009';
-}
-/** A bank debit submitted: the intent processes, nothing received yet, sent as payment_intent.processing; it is due to
- *  settle at this instant, unless its test account stays processing. */
-async function beginBankDebit(ctx, id, fields) {
-    const method = fields.payment_method ?? ctx.get(PI, id)?.payment_method;
-    return ctx.write(PI, id, { ...fields, status: 'processing', amount_received: 0, next_action: null, last_payment_error: null, _settles_at: staysProcessing(ctx, method) ? null : Number(ctx.now()) }, 'payment_intent.processing');
-}
-/** Time's settling of bank debits, caught up to the World's clock: each processing debit whose moment has come succeeds
- *  then, its Charge made (naming the mandate it ran under) and the invoice it collects for paid. */
-export async function settleBankDebits(ctx) {
-    const now = Number(ctx.now());
-    const due = ctx.rowsRaw(PI).filter((p) => p.status === 'processing' && typeof p._settles_at === 'number' && p._settles_at <= now).sort((a, b) => Number(a._settles_at) - Number(b._settles_at));
-    for (const pi of due) {
-        const id = String(pi.id);
-        const c = await at_(ctx)(Number(pi._settles_at));
-        c.legal(PI, 'status', ctx.call.operation.id, 'processing', 'succeeded', id, 'vendor');
-        const amount = Number(pi.amount) || 0;
-        const charge = await mintCharge(c, id, pi, amount);
-        // the charge names the mandate its bank debit ran under (payment_method_details.us_bank_account.mandate)
-        const details = (c.get('charge', charge)?.payment_method_details ?? null);
-        const kind = typeof details?.type === 'string' ? details.type : undefined;
-        if (details && kind && typeof pi.mandate === 'string')
-            await c.write('charge', charge, { payment_method_details: { ...details, [kind]: { ...(details[kind] ?? {}), mandate: pi.mandate } } }, 'charge.mandate');
-        const body = await c.write(PI, id, { status: 'succeeded', amount_received: amount, latest_charge: charge, _settles_at: null }, 'payment_intent.succeeded');
-        // a single-use mandate is spent by its payment: "previously used, and may not be used to initiate future payments"
-        const used = typeof pi.mandate === 'string' ? c.get('mandate', pi.mandate) : undefined;
-        if (used && used.type === 'single_use' && used.status === 'active') {
-            c.legal('mandate', 'status', ctx.call.operation.id, 'active', 'inactive', String(used.id), 'vendor');
-            await c.write('mandate', String(used.id), { status: 'inactive' }, 'mandate.updated');
-        }
-        await payInvoiceOf(c, body, ctx.call.operation.id, 'vendor');
-    }
-}
-/** A customer_balance intent funded from the customer's cash balance: paid when the balance covers it ("If the customer
- *  already has a balance high enough to cover the payment amount, the PaymentIntent immediately succeeds"), else
- *  waiting for a transfer: "If the customer balance isn’t high enough to cover the request amount, the PaymentIntent
- *  shows a requires_action status ... next_action ... display_bank_transfer_instructions" with the amount_remaining
- *  (docs.stripe.com/payments/bank-transfers/accept-a-payment). Answers the intent as written. */
-async function fundFromCashBalance(ctx, pi, fields = {}) {
-    const customer = typeof pi.customer === 'string' ? pi.customer : '';
-    const currency = String(pi.currency ?? 'usd');
-    // what the customer's funded cash balance holds in this currency, from its ledger
-    const available = customer ? ctx.rows('customer_cash_balance_transaction').filter((t) => t.customer === customer && String(t.currency) === currency).reduce((n, t) => n + (Number(t.net_amount) || 0), 0) : 0;
-    const amount = Number(pi.amount) || 0;
-    if (available >= amount) {
-        // the balance pays the intent: its ledger records what was applied
-        await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'applied_to_payment', net_amount: -amount, ending_balance: available - amount, applied_to_payment: { payment_intent: String(pi.id) }, livemode: false });
-        const charge = await mintCharge(ctx, String(pi.id), { ...pi, ...fields }, amount);
-        return ctx.write(PI, String(pi.id), { ...fields, status: 'succeeded', next_action: null, amount_received: amount, last_payment_error: null, latest_charge: charge }, 'payment_intent.succeeded');
-    }
-    // not enough yet: the intent waits for the rest, with the instructions to send it
-    const next_action = { type: 'display_bank_transfer_instructions', display_bank_transfer_instructions: { amount_remaining: amount - available, currency, type: 'us_bank_transfer' } };
-    return ctx.write(PI, String(pi.id), { ...fields, status: 'requires_action', next_action }, 'payment_intent.requires_action');
-}
-const applyCustomerBalance = async (ctx) => {
-    const loaded = load(ctx, 'PostPaymentIntentsIntentApplyCustomerBalance');
-    if ('answer' in loaded)
-        return loaded.answer;
-    return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, loaded.pi)));
-};
-export const paymentIntents = {
-    PostPaymentIntents: create,
-    GetPaymentIntentsSearch: async (ctx) => search(ctx, PI),
-    PostPaymentIntentsIntentConfirm: confirm,
-    PostPaymentIntentsIntentCapture: capture,
-    PostPaymentIntentsIntentIncrementAuthorization: incrementAuthorization,
-    PostPaymentIntentsIntentCancel: cancel,
-    PostPaymentIntentsIntentVerifyMicrodeposits: verifyMicrodepositsHandler,
-    PostPaymentIntentsIntentApplyCustomerBalance: applyCustomerBalance,
-};

package/dist/src/semantics/payment-links.d.ts

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

package/dist/src/semantics/payment-links.js

@@ -1,133 +0,0 @@
-import { asBool, lineItemEntries, paginate, resolveLineItem } from "../stripe-twin.js";
-import { draftInvoiceFor } from "./invoices.js";
-import { at, created, fail, finder, list, newest, path, where } from "./shared.js";
-/** The request's line items resolved against their prices, or the refusal for a missing price. */
-function resolved(ctx) {
-    const entries = lineItemEntries(ctx.params);
-    const items = [];
-    for (let i = 0; i < entries.length; i++) {
-        const { item, priceMissing } = resolveLineItem(entries[i], i, 'usd', finder(ctx));
-        if (priceMissing)
-            return fail(ctx, `No such price: '${priceMissing}'`, 400, 'resource_missing');
-        items.push(item);
-    }
-    return items;
-}
-/** A page of the line items a stored object carries. */
-function linePage(ctx, holder) {
-    const li = holder.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 PL = 'payment_link';
-const linkMissing = (ctx, id) => fail(ctx, `No such payment link: '${id}'`, 404, 'resource_missing');
-const createLink = async (ctx) => {
-    if (lineItemEntries(ctx.params).length === 0)
-        return fail(ctx, 'Missing required param: line_items.', 400, 'parameter_missing');
-    const items = resolved(ctx);
-    if (items instanceof Response)
-        return items;
-    const id = ctx.mint(PL);
-    const { line_items: _li, ...rest } = ctx.params;
-    return ctx.reply(await created(ctx, PL, { ...rest, id }, {
-        active: ctx.params.active !== undefined ? asBool(ctx.params.active) : true,
-        url: `https://buy.twin.local/${id}`, livemode: false, metadata: {},
-        // Stripe's defaults for what the link was not given (docs.stripe.com/api/payment-link/create)
-        allow_promotion_codes: false, automatic_tax: { enabled: false, liability: null }, billing_address_collection: 'auto',
-        custom_fields: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null },
-        customer_creation: 'if_required', payment_method_collection: 'always', phone_number_collection: { enabled: false },
-        shipping_options: [], submit_type: 'auto', tax_id_collection: { enabled: false, required: 'never' },
-        line_items: { object: 'list', data: items, has_more: false, url: `/v1/payment_links/${id}/line_items` },
-        currency: items[0]?.currency ?? 'usd',
-        after_completion: { type: 'redirect', redirect: typeof ctx.params.after_completion === 'object' ? ctx.params.after_completion : null },
-    }));
-};
-const listLinks = async (ctx) => list(ctx, PL, where(ctx, newest(ctx, PL), { active: (p, v) => asBool(p.active) === asBool(v) }));
-const linkLines = async (ctx) => {
-    const p = ctx.get(PL, at(ctx, 'payment_link'));
-    return p ? linePage(ctx, p) : linkMissing(ctx, at(ctx, 'payment_link'));
-};
-// ── quotes ──
-const quoteMissing = (ctx, id) => fail(ctx, `No such quote: '${id}'`, 404, 'resource_missing');
-const createQuote = async (ctx) => {
-    const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-    if (!ctx.row('customer', customer, { withDeleted: true }))
-        return fail(ctx, `No such customer: '${customer}'`, 400, 'resource_missing');
-    const items = resolved(ctx);
-    if (items instanceof Response)
-        return items;
-    const subtotal = items.reduce((s, it) => s + it.amount_subtotal, 0);
-    const id = ctx.mint('quote');
-    const { line_items: _li, ...rest } = ctx.params;
-    return ctx.reply(await created(ctx, 'quote', { ...rest, id }, {
-        status: 'draft', customer, currency: items[0]?.currency ?? 'usd', livemode: false, metadata: {},
-        amount_subtotal: subtotal, amount_total: subtotal,
-        // Stripe's defaults (docs.stripe.com/api/quotes/create); what is paid up front is the whole quote, and the twin bills in classic mode
-        automatic_tax: { enabled: false, liability: null, provider: null, status: null }, collection_method: 'charge_automatically', discounts: [],
-        invoice_settings: { days_until_due: null, issuer: { type: 'self' } },
-        subscription_data: { billing_mode: { type: 'classic' }, description: null, effective_date: null, metadata: null, trial_period_days: null },
-        computed: { recurring: null, upfront: { amount_subtotal: subtotal, amount_total: subtotal, total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 } } },
-        line_items: { object: 'list', data: items, has_more: false, url: `/v1/quotes/${id}/line_items` },
-        total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 },
-        expires_at: Number(ctx.now()) + 30 * 24 * 3600,
-        number: null, invoice: null, subscription: null,
-        status_transitions: { accepted_at: null, canceled_at: null, finalized_at: null },
-    }));
-};
-const quoteLines = async (ctx) => {
-    const q = ctx.get('quote', at(ctx, 'quote'));
-    return q ? linePage(ctx, q) : quoteMissing(ctx, at(ctx, 'quote'));
-};
-// Stripe streams the PDF; the twin answers a stable reference to it
-const pdf = async (ctx) => {
-    const id = at(ctx, 'quote');
-    if (!ctx.get('quote', id))
-        return quoteMissing(ctx, id);
-    return ctx.reply({ object: 'quote_pdf', url: `https://files.twin.local/quotes/${id}.pdf` });
-};
-function move(action, operationId) {
-    return async (ctx) => {
-        const id = at(ctx, 'quote');
-        const q = ctx.get('quote', id);
-        if (!q)
-            return quoteMissing(ctx, id);
-        const refused = ctx.legal('quote', 'status', operationId, q.status, undefined, id);
-        if (refused)
-            return ctx.refuse(refused);
-        const now = ctx.now();
-        const stamp = action === 'finalize' ? { finalized_at: now } : action === 'accept' ? { accepted_at: now } : { canceled_at: now };
-        // "Accepted quotes automatically generate an invoice, subscription, or subscription schedule"; "Quotes without
-        // recurring prices: A draft invoice is created with auto_advance set to false" (docs.stripe.com/quotes/overview),
-        // the quote its parent ("Details about the quote that generated this invoice", the served spec). Where the
-        // documentation stops and the twin decides: a quote with recurring prices makes no subscription yet.
-        let made = {};
-        if (action === 'accept') {
-            const lines = q.line_items?.data ?? [];
-            const recurring = lines.some((l) => l.price && typeof l.price === 'object' && l.price.recurring);
-            if (!recurring && typeof q.customer === 'string') {
-                const invoice = await draftInvoiceFor(ctx, q.customer, String(q.currency ?? 'usd'), { type: 'quote_details', quote_details: { quote: id }, subscription_details: null }, lines.map((l) => ({ price: l.price, quantity: Number(l.quantity) || 1, amount: Number(l.amount_subtotal ?? l.amount_total) || 0, description: l.description })));
-                made = { invoice };
-            }
-        }
-        return ctx.reply(await ctx.write('quote', id, {
-            status: action === 'finalize' ? 'open' : action === 'accept' ? 'accepted' : 'canceled',
-            status_transitions: { ...(q.status_transitions ?? {}), ...stamp },
-            ...(action === 'finalize' ? { number: `QT-${id.toUpperCase()}` } : {}),
-            ...made,
-        }, `quote.${action}`));
-    };
-}
-export const paymentLinks = {
-    PostPaymentLinks: createLink,
-    GetPaymentLinks: listLinks,
-    GetPaymentLinksPaymentLinkLineItems: linkLines,
-    PostQuotes: createQuote,
-    GetQuotesQuoteLineItems: quoteLines,
-    GetQuotesQuoteComputedUpfrontLineItems: quoteLines,
-    GetQuotesQuotePdf: pdf,
-    PostQuotesQuoteFinalize: move('finalize', 'PostQuotesQuoteFinalize'),
-    PostQuotesQuoteAccept: move('accept', 'PostQuotesQuoteAccept'),
-    PostQuotesQuoteCancel: move('cancel', 'PostQuotesQuoteCancel'),
-};

package/dist/src/semantics/payment-methods.d.ts

@@ -1,20 +0,0 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** The card a charge was paid with, as its payment_method_details reports it
- *  (docs.stripe.com/api/charges/object#charge_object-payment_method_details): a stored PaymentMethod's card, a
- *  documented test name (pm_card_* or tok_*, the same cards), or a raw card; undefined for anything else. */
-export declare function paymentMethodDetails(ctx: SemanticsContext, ref: unknown): Row | undefined;
-/** Whether a payment method can be attached: a stored one, or a documented test name that attaching mints. */
-export declare const attachable: (ctx: SemanticsContext, id: string) => boolean;
-export declare function attachPaymentMethod(ctx: SemanticsContext, id: string, customer: string): Promise<Row>;
-/** A documented test name (pm_card_visa, pm_card_visa_chargeDeclined, …) made a real PaymentMethod, as Stripe
- *  does when one is used: the brand and number it stands for (docs.stripe.com/testing#cards) and its outcome. */
-export declare function materializeTestMethod(ctx: SemanticsContext, id: string, customer: string | null): Promise<Row>;
-export declare const paymentMethods: Record<string, Semantics>;
-/** A PaymentMethod made from a confirm's `payment_method_data` ("If provided, this hash will be used to create a
- *  PaymentMethod", docs.stripe.com/api/setup_intents/confirm, docs.stripe.com/api/payment_intents/confirm), or none. */
-export declare function methodFromData(ctx: SemanticsContext, data: unknown): Promise<string | undefined>;
-/** Whether an intent sets up or pays with a bank account by micro-deposits because it asks for them:
- *  payment_method_options[us_bank_account][verification_method]=microdeposits with a us_bank_account method
- *  ("Microdeposit only verification", docs.stripe.com/payments/ach-direct-debit/set-up-payment). */
-export declare function microdepositsAsked(ctx: SemanticsContext, params: Row, intent: Row, pm: string | undefined): boolean;