@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/semantics/test_helpers.js

@@ -0,0 +1,125 @@
+import { AUTH, CARD, cardId, CH, historyEntry, holderId, merchantData, TXN } from "../engine/issuing.js";
+import { isValidApiVersion, nowUnix, spendingControlsViolation, TWIN_API_VERSION } from "../engine/stripe.js";
+import { stripeEventMatches } from "../engine/webhooks.js";
+import { answeredByEndpoint, approvedAtOnce, askForAuthorization, at, authMissing, balanceOf, capture, created, fail, issuingRefusal, withCard } from "./shared.js";
+export async function PostTestHelpersIssuingAuthorizations(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(nowUnix(ctx.occurredAt));
+    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(withCard(ctx, 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.');
+    // source: https://docs.stripe.com/api/issuing/cards/create "Defaults to inactive"
+    // source: spec:/components/schemas/issuing_authorization_request/properties/reason/enum "card_inactive"
+    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 request asked of the endpoint and the stored event are one event under one id
+    const pinned = ctx.call.request.headers.get('stripe-version');
+    const requestEvent = {
+        id: ctx.mint('event'), object: 'event', api_version: pinned && isValidApiVersion(pinned) ? pinned : TWIN_API_VERSION, created: createdSec,
+        data: { object: requestObject }, livemode: false, pending_webhooks: 1, request: { id: null, idempotency_key: null }, type: 'issuing_authorization.request',
+    };
+    await ctx.write('event', requestEvent.id, requestEvent, 'event.record');
+    const outcome = await askForAuthorization(ctx, String(endpoint.url), requestEvent, String(endpoint.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(withCard(ctx, 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 });
+}
+export async function PostTestHelpersIssuingAuthorizationsAuthorizationCapture(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: nowUnix(ctx.occurredAt), fee_details: [], source: id,
+    });
+    const captured = await capture(ctx, id, { ...auth, card: cardId(auth) }, captureAmount);
+    return ctx.reply(withCard(ctx, await ctx.write(AUTH, id, {
+        status: closeAuthorization ? 'closed' : 'pending',
+        transactions: [...txns, captured.txnId],
+        balance_transactions: [...(Array.isArray(auth.balance_transactions) ? auth.balance_transactions : []), release.id, captured.btId],
+    }, 'issuing_authorization.updated')));
+}

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

@@ -1,2 +1,2 @@
-import type { Semantics } from '@volter/world-core';
-export declare const transfers: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function PostTransfers(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/transfers.js

@@ -1,13 +1,7 @@
-import { validateMoney } from "../stripe-twin.js";
-import { refusePayout, settleTransfer, settleTransferReversal } from "./ledger.js";
-import { at, created, fail, list, newest, send } from "./shared.js";
-const transferMissing = (ctx, id) => fail(ctx, `No such transfer: '${id}'`, 404, 'resource_missing');
-const emptyList = (url) => ({ object: 'list', data: [], has_more: false, total_count: 0, url });
-/** A transfer to an account whose transfers capability is not active. */
-function transfersInactive(ctx) {
-    return ctx.refuse({ status: 400, code: 'insufficient_capabilities_for_transfer', param: 'destination', message: 'Your destination account needs to have at least one of the following capabilities enabled: transfers, crypto_transfers, legacy_payments' });
-}
-const create = async (ctx) => {
+import { nowUnix, validateMoney } from "../engine/stripe.js";
+import { emptyList } from "../engine/transfers.js";
+import { created, fail, refusePayout, send, settledSourceRefused, settleTransfer, transfersInactive } from "./shared.js";
+export async function PostTransfers(ctx) {
     const bad = validateMoney(ctx.params);
     if (bad)
         return send(ctx, bad);
@@ -40,10 +34,10 @@ const create = async (ctx) => {
             return fail(ctx, `The transfers from source_transaction ${sourceId} would exceed its amount (${String(charge.amount)}).`, 400, 'invalid_request_error');
         const bt = typeof charge.balance_transaction === 'string' ? ctx.get('balance_transaction', charge.balance_transaction) : undefined;
         // a charge that has settled waives nothing: the transfer comes out of what is available
-        const settledRefusal = bt && Number(bt.available_on) <= Number(ctx.now()) ? settledSourceRefused(ctx, amount, currency) : undefined;
+        const settledRefusal = bt && Number(bt.available_on) <= Number(nowUnix(ctx.occurredAt)) ? settledSourceRefused(ctx, amount, currency) : undefined;
         if (settledRefusal)
             return settledRefusal;
-        availableOn = Math.max(Number(ctx.now()), Number(bt?.available_on) || 0);
+        availableOn = Math.max(Number(nowUnix(ctx.occurredAt)), Number(bt?.available_on) || 0);
         group = typeof charge.transfer_group === 'string' ? charge.transfer_group : typeof charge.payment_intent === 'string' ? `group_${charge.payment_intent}` : undefined;
         // the generated group is the charge's too
         if (group && charge.transfer_group !== group)
@@ -62,93 +56,4 @@ const create = async (ctx) => {
         reversals: emptyList(`/v1/transfers/${id}/reversals`),
         destination_payment: `py_${id.replace(/^tr_/, '')}`,
     }));
-};
-/** A transfer from a charge whose funds have settled: "With a source_transaction, the transfer request returns success
- *  regardless of your available balance if the related charge hasn't settled yet" (docs.stripe.com/connect/separate-
- *  charges-and-transfers), so a settled one comes out of the available balance. */
-function settledSourceRefused(ctx, amount, currency) {
-    return refusePayout(ctx, amount, currency, undefined);
-}
-/** An application fee refunded to its whole through its own refunds endpoint: the fee machine's move, or its refusal. */
-function feeFullyRefunded(ctx, resource, flag, id) {
-    const refused = ctx.legal(resource, flag, ctx.call.operation.id, 'false', 'true', id);
-    return refused ? ctx.refuse(refused) : undefined;
-}
-/** Take `amount` (the remainder by default) back out of a parent's total, as a child row appended to its list. */
-async function giveBack(ctx, o) {
-    const id = String(o.parent.id);
-    const total = Number(o.parent.amount ?? 0);
-    const already = Number(o.parent[o.doneField] ?? 0);
-    const remaining = total - already;
-    const amount = ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : remaining;
-    if (amount <= 0 || amount > remaining)
-        return fail(ctx, o.tooLarge(remaining), 400, 'amount_too_large');
-    const done = already + amount;
-    // a fee refunded in full is `refunded`: the application fee machine's move (a transfer's `reversed` is no state)
-    const feeRefusal = o.parentResource === 'application_fee' && done >= total && o.parent[o.flag] !== true ? feeFullyRefunded(ctx, o.parentResource, o.flag, id) : undefined;
-    if (feeRefusal)
-        return feeRefusal;
-    // the `metadata` a reversal or a fee refund is created with is its own ("Set of key-value pairs that you can attach to
-    // an object", docs.stripe.com/api/transfer_reversals/create, docs.stripe.com/api/fee_refunds/create)
-    const metadata = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? { metadata: ctx.params.metadata } : {};
-    const child = await created(ctx, o.child, { ...o.childFields(amount), ...metadata }, o.childDefaults);
-    if (o.settle)
-        await o.settle(child, amount);
-    const existing = o.parent[o.flag === 'reversed' ? 'reversals' : 'refunds'] ?? { object: 'list', data: [], has_more: false, total_count: 0 };
-    const data = [...(existing.data ?? []), child];
-    await ctx.write(o.parentResource, id, {
-        [o.doneField]: done, [o.flag]: done >= total,
-        [o.flag === 'reversed' ? 'reversals' : 'refunds']: { ...existing, data, total_count: data.length, url: o.listUrl },
-    }, o.op);
-    return ctx.reply(child);
 }
-const reverse = async (ctx) => {
-    const id = at(ctx, 'id');
-    const tr = ctx.get('transfer', id);
-    if (!tr)
-        return transferMissing(ctx, id);
-    return giveBack(ctx, {
-        parent: tr, parentResource: 'transfer', child: 'transfer_reversal',
-        childFields: (amount) => ({ amount, currency: tr.currency ?? 'usd', transfer: id }),
-        childDefaults: { balance_transaction: null, destination_payment_refund: null, source_refund: null, metadata: {} },
-        doneField: 'amount_reversed', flag: 'reversed', listUrl: `/v1/transfers/${id}/reversals`, op: 'transfer.reversed',
-        tooLarge: (remaining) => `Transfer ${id} can only be reversed up to ${remaining}.`,
-        settle: async (child, amount) => {
-            const bt = await settleTransferReversal(ctx, String(child.id), amount, String(tr.currency ?? 'usd'), String(tr.destination));
-            await ctx.write('transfer_reversal', String(child.id), { balance_transaction: bt }, 'transfer_reversal.updated');
-        },
-    });
-};
-const reversals = async (ctx) => {
-    const id = at(ctx, 'id');
-    if (!ctx.get('transfer', id))
-        return transferMissing(ctx, id);
-    return list(ctx, 'transfer_reversal', newest(ctx, 'transfer_reversal').filter((r) => r.transfer === id));
-};
-const feeMissing = (ctx, id) => fail(ctx, `No such application fee: '${id}'`, 404, 'resource_missing');
-const refundFee = async (ctx) => {
-    const id = at(ctx, 'id');
-    const fee = ctx.get('application_fee', id);
-    if (!fee)
-        return feeMissing(ctx, id);
-    return giveBack(ctx, {
-        parent: fee, parentResource: 'application_fee', child: 'fee_refund',
-        childFields: (amount) => ({ amount, currency: fee.currency ?? 'usd', fee: id }),
-        childDefaults: { balance_transaction: null, metadata: {} },
-        doneField: 'amount_refunded', flag: 'refunded', listUrl: `/v1/application_fees/${id}/refunds`, op: 'application_fee.refunded',
-        tooLarge: (remaining) => `Application fee ${id} can only be refunded up to ${remaining}.`,
-    });
-};
-const feeRefunds = async (ctx) => {
-    const id = at(ctx, 'id');
-    if (!ctx.get('application_fee', id))
-        return feeMissing(ctx, id);
-    return list(ctx, 'fee_refund', newest(ctx, 'fee_refund').filter((r) => r.fee === id));
-};
-export const transfers = {
-    PostTransfers: create,
-    PostTransfersIdReversals: reverse,
-    GetTransfersIdReversals: reversals,
-    PostApplicationFeesIdRefunds: refundFee,
-    GetApplicationFeesIdRefunds: feeRefunds,
-};

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

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

package/dist/src/semantics/webhook_endpoints.js

@@ -0,0 +1,26 @@
+import { asBool } from "../engine/stripe.js";
+import { WE } from "../engine/webhook-endpoints.js";
+import { created, fail } from "./shared.js";
+// an endpoint is enabled at once and signs each event with a secret of its own, answered by this create alone (the
+// around answers no other read of it)
+export async function PostWebhookEndpoints(ctx) {
+    const params = ctx.params;
+    // source: spec:PostWebhookEndpoints "The URL of the webhook endpoint."
+    if (typeof params.url !== 'string' || params.url === '')
+        return fail(ctx, 'Missing required param: url.', 400, 'parameter_missing');
+    // source: spec:PostWebhookEndpoints "The list of events to enable for this endpoint."
+    if (params.enabled_events === undefined || params.enabled_events === '' || (Array.isArray(params.enabled_events) && !params.enabled_events.length))
+        return fail(ctx, 'Missing required param: enabled_events.', 400, 'parameter_missing');
+    const id = ctx.mint(WE);
+    // source: spec:/components/schemas/webhook_endpoint/properties/secret/description "The endpoint's secret, used to generate"
+    const secret = `whsec_${(await ctx.secret(`webhook-endpoint-secret:${id}`)).replace(/[^A-Za-z0-9]/g, '').slice(0, 32)}`;
+    return ctx.reply(await created(ctx, WE, { ...params, id }, {
+        url: params.url, enabled_events: Array.isArray(params.enabled_events) ? params.enabled_events.map(String) : [String(params.enabled_events)],
+        // source: spec:/components/schemas/webhook_endpoint/properties/status/description "The status of the webhook."
+        status: 'enabled', livemode: false, metadata: {}, application: null,
+        api_version: typeof params.api_version === 'string' ? params.api_version : null,
+        description: typeof params.description === 'string' ? params.description : null,
+        // source: spec:PostWebhookEndpoints "Whether this endpoint should receive events from connected accounts"
+        connect: asBool(params.connect), secret,
+    }));
+}

package/dist/src/server.d.ts

@@ -0,0 +1,7 @@
+import { type PackFetchOptions } from '@volter/world-core';
+export declare function createStripeTwinServer(options?: PackFetchOptions & {
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/server.js

@@ -0,0 +1,7 @@
+// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
+import { serveHttp } from '@volter/world-core';
+import { createStripeFetch } from "./fetch.js";
+export async function createStripeTwinServer(options = {}) {
+    const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createStripeFetch(options) });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/generated/pack-facts.json

@@ -0,0 +1,94 @@
+{
+  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
+  "packs": {
+    "stripe": {
+      "adoption": {
+        "pypi": [
+          "stripe"
+        ],
+        "sdks": [
+          "stripe"
+        ],
+        "envStems": [
+          "STRIPE",
+          "NEXTPRIVATESTRIPE"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "api.stripe.com"
+        },
+        {
+          "host": "checkout.stripe.com",
+          "pathPattern": "^/c/pay/"
+        },
+        {
+          "host": "billing.stripe.com",
+          "pathPattern": "^/p/session/"
+        },
+        {
+          "host": "connect.stripe.com",
+          "pathPattern": "^/setup/"
+        },
+        {
+          "host": "dashboard.stripe.com",
+          "pathPattern": "^/radar/lists(?:/[^/]+)?/?$|^/test/issuing/balance/?$|^/settings/public/?$"
+        },
+        {
+          "host": "verify.stripe.com",
+          "pathPattern": "^/start/"
+        },
+        {
+          "host": "js.stripe.com",
+          "pathPattern": "^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "charge",
+        "customer",
+        "payment_intent",
+        "setup_intent",
+        "payment_method",
+        "subscription",
+        "price",
+        "product",
+        "invoice",
+        "invoiceitem",
+        "refund",
+        "event"
+      ],
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "fill": {
+          "STRIPE_SECRET_KEY": "secret_key",
+          "STRIPE_API_KEY": "secret_key",
+          "STRIPE_PRIVATE_KEY": "secret_key",
+          "BILLING_STRIPE_API_KEY": "secret_key",
+          "STRIPE_PUBLISHABLE_KEY": "publishable_key",
+          "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY": "publishable_key",
+          "NEXT_PUBLIC_STRIPE_PUBLIC_KEY": "publishable_key",
+          "NEXT_PUBLIC_STRIPE_KEY": "publishable_key",
+          "STRIPE_WEBHOOK_SECRET": "webhook_secret",
+          "STRIPE_WEBHOOK_SIGNING_SECRET": "webhook_secret",
+          "STRIPE_ENDPOINT_SECRET": "webhook_secret",
+          "STRIPE_WEBHOOK_SECRET_KEY": "webhook_secret",
+          "NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET": "webhook_secret",
+          "BILLING_STRIPE_WEBHOOK_SECRET": "webhook_secret",
+          "STRIPE_CONNECT_WEBHOOK_SECRET": "connect_webhook_secret",
+          "STRIPE_WEBHOOK_SECRET_CONNECT": "connect_webhook_secret",
+          "STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET": "connect_webhook_secret"
+        }
+      },
+      "serveExport": "createStripeTwinServer"
+    }
+  },
+  "undeclared": []
+}