@volter/twin-stripe 2.0.37 → 3.0.0

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/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/|^/oauth/(authorize|token|deauthorize)/?$"
+        },
+        {
+          "host": "dashboard.stripe.com",
+          "pathPattern": "^/settings/public/?$|^/(test/)?settings/connect(/onboarding-options/oauth)?/?$"
+        },
+        {
+          "host": "verify.stripe.com",
+          "pathPattern": "^/start/"
+        },
+        {
+          "host": "js.stripe.com",
+          "pathPattern": "^/v3/financial-connections/|^/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": []
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/twin-stripe",
-  "version": "2.0.37",
-  "description": "Local Stripe twin — a faithful, stateful local Stripe API your real `stripe` SDK talks to unmodified. Mirror, simulate, and fork. Built on @volter/world-core.",
+  "version": "3.0.0",
+  "description": "Local Stripe twin — a faithful, stateful local Stripe API your real `stripe` SDK talks to unmodified, its hosted pages and Stripe.js. Built on @volter/world-core.",
   "keywords": [
     "twin",
     "local",
@@ -23,21 +23,20 @@
   },
   "files": [
     "src",
-    "client",
-    "test-fixtures",
+    "spec",
     "README.md",
     "LICENSE",
-    "!test-fixtures/*.SOURCE.md",
     "!**/*.test.ts",
     "!**/*.test.tsx",
-    "dist"
+    "dist",
+    "generated"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/volter-ai/twin.git",
-    "directory": "packages/twin/stripe"
+    "url": "git+https://github.com/volter-ai/twin-packs-p3.git",
+    "directory": "stripe"
   },
-  "homepage": "https://world.volter.ai/twins/stripe",
+  "homepage": "https://github.com/volter-ai/twin-packs-p3/tree/main/stripe#readme",
   "type": "module",
   "exports": {
     ".": {
@@ -48,24 +47,15 @@
   "bin": {
     "world-stripe": "dist/src/cli.js"
   },
-  "scripts": {
-    "test": "bun test src/*.test.ts",
-    "typecheck": "tsc --noEmit",
-    "build": "node ../../../scripts/publish/build.mjs",
-    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
-    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
-  },
   "dependencies": {
-    "@volter/world-ui": "0.1.36",
+    "@volter/world-ui": "^1.0.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.36"
+    "@volter/world-core": "^3.0.1"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.36",
-    "@volter/world-tooling": "0.1.0",
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.17",

package/spec/SOURCE.md

@@ -0,0 +1,14 @@
+# stripe spec — provenance
+
+- **File:** `openapi.json.gz`, gzip of Stripe's published OpenAPI document.
+- **Upstream:** https://github.com/stripe/openapi, `openapi/spec3.json` on `master`.
+- **Spec version:** `2026-09-30.endive` (`info.version`).
+- **SHA-256 of the uncompressed document:** `6b4680299e7b7743811c41537e828b0eae363a11cea44441511013b55e52f7ad`.
+- **Read by:** `bun scripts/derive-pack.ts stripe`, which writes `../src/generated/surface.gen.json`.
+
+The pack serves this document's version (`SERVED_VERSION` in `src/stripe-version.ts`).
+
+- **Published examples:** `fixtures3.json.gz`, gzip of Stripe's `openapi/fixtures3.json` (one sample object per resource,
+  the objects Stripe's API reference shows), from commit `0d98342fc985dc7710a44be25e8528dd8e099bc2` (2026-09-23).
+  SHA-256 of the uncompressed file: `e6822f7ee6fd71bdde6228537368aafcfb7191109340fe119d9aca27c6e9396d`.
+  **Read by:** `bun scripts/vendor-examples.ts stripe`.

package/spec/patches.json

@@ -0,0 +1,34 @@
+{
+  "patches": [
+    {
+      "op": "add",
+      "path": "/components/schemas/invoiceitem/properties/net_amount/nullable",
+      "value": true,
+      "why": "The spec types an invoice item's net_amount as a bare integer, yet its own description says the field answers null for every discountable item, so the field is nullable.",
+      "source": {
+        "spec": "/components/schemas/invoiceitem/properties/net_amount/description",
+        "quote": "This field is `null` for `discountable=true` items."
+      }
+    },
+    {
+      "op": "add",
+      "path": "/components/schemas/file/properties/purpose/enum/-",
+      "value": "issuing_logo",
+      "why": "The spec's personalization-design card_logo says \"Must have a `purpose` value of `issuing_logo`\", yet neither the File object's purpose nor the file upload's purpose lists it; Stripe's own guide uploads the logo with that purpose (https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code), so issuing_logo is a purpose a file has.",
+      "source": {
+        "url": "https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code",
+        "quote": "Use the [Files API](https://docs.stripe.com/api/files/create.md) to upload a .PNG file of your card logo, and specify the purpose as `issuing_logo`."
+      }
+    },
+    {
+      "op": "add",
+      "path": "/paths/~1v1~1files/post/requestBody/content/multipart~1form-data/schema/properties/purpose/enum/-",
+      "value": "issuing_logo",
+      "why": "The spec's personalization-design card_logo says \"Must have a `purpose` value of `issuing_logo`\", yet neither the File object's purpose nor the file upload's purpose lists it; Stripe's own guide uploads the logo with that purpose (https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code), so issuing_logo is a purpose a file has.",
+      "source": {
+        "url": "https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code",
+        "quote": "Use the [Files API](https://docs.stripe.com/api/files/create.md) to upload a .PNG file of your card logo, and specify the purpose as `issuing_logo`."
+      }
+    }
+  ]
+}