@volter/twin-stripe 2.0.38 → 3.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/twin-stripe",
-  "version": "2.0.38",
-  "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.1",
+  "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,21 @@
   },
   "files": [
     "src",
-    "client",
-    "test-fixtures",
+    "journeys",
+    "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 +48,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.37",
+    "@volter/world-ui": "^1.0.38",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.37"
+    "@volter/world-core": "^3.0.38"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.37",
-    "@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,18 @@
+# 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/engine/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`.
+- **Published examples from Stripe's pages:** `doc-examples.json`, the requests and rules Stripe's documentation pages
+  publish (its testing page's cards, the payment lifecycle's states, each reference page's stated rule), each with its
+  page's URL and the page's words for what it does, read with twin-standard's `read-page`. **Read by:**
+  `bun scripts/vendor-examples.ts stripe`.

package/spec/doc-examples.json

@@ -0,0 +1,445 @@
+[
+  {
+    "title": "Generic decline",
+    "source": "https://docs.stripe.com/testing",
+    "operation": "PostPaymentIntentsIntentConfirm",
+    "input": {
+      "payment_method_data": {
+        "type": "card",
+        "card": {
+          "number": "4000000000000002",
+          "exp_month": 12,
+          "exp_year": 2030,
+          "cvc": "123"
+        }
+      }
+    },
+    "means": "Generic decline 4000 0000 0000 0002 card_declined generic_decline",
+    "status": 402
+  },
+  {
+    "title": "Always authenticate",
+    "source": "https://docs.stripe.com/testing",
+    "operation": "PostPaymentIntentsIntentConfirm",
+    "input": {
+      "payment_method_data": {
+        "type": "card",
+        "card": {
+          "number": "4000002760003184",
+          "exp_month": 12,
+          "exp_year": 2030,
+          "cvc": "123"
+        }
+      }
+    },
+    "output": {
+      "status": "requires_action"
+    },
+    "means": "Always authenticate 4000 0027 6000 3184 This card requires authentication on all transactions, regardless of how the card is set up.",
+    "status": 200
+  },
+  {
+    "title": "rule: a publishable key retrieves a payment with its client secret",
+    "source": "https://docs.stripe.com/api/payment_intents/retrieve",
+    "operation": "GetPaymentIntentsIntent",
+    "means": "client_secret string Required if you use a publishable key. The client secret of the PaymentIntent. We require it if you use a publishable key to retrieve the source.",
+    "status": 400
+  },
+  {
+    "title": "a payment given its method waits for confirmation",
+    "source": "https://docs.stripe.com/payments/paymentintents/lifecycle",
+    "operation": "PostPaymentIntents",
+    "input": {
+      "payment_method": "pm_1EXUPv2eZvKYlo2CUkqZASBe"
+    },
+    "output": {
+      "status": "requires_confirmation"
+    },
+    "means": "After your customer provides payment information, the PaymentIntent enters the requires_confirmation status and is ready to confirm."
+  },
+  {
+    "title": "a payment authorized and captured separately waits for its capture",
+    "source": "https://docs.stripe.com/payments/paymentintents/lifecycle",
+    "operation": "PostPaymentIntentsIntentConfirm",
+    "output": {
+      "status": "requires_capture"
+    },
+    "means": "If you’re separately authorizing and capturing funds, your PaymentIntent can instead move to requires_capture."
+  },
+  {
+    "title": "rule: a payment that succeeded is not canceled",
+    "source": "https://docs.stripe.com/payments/paymentintents/lifecycle",
+    "operation": "PostPaymentIntentsIntentCancel",
+    "means": "You can cancel a PaymentIntent before it reaches a processing or succeeded state.",
+    "status": 400
+  },
+  {
+    "title": "rule: only an open session can be expired",
+    "source": "https://docs.stripe.com/api/checkout/sessions/expire",
+    "operation": "PostCheckoutSessionsSessionExpire",
+    "means": "A Checkout Session can be expired when it is in one of these statuses: open",
+    "status": 400
+  },
+  {
+    "title": "rule: only a finalized invoice is voided",
+    "source": "https://docs.stripe.com/api/invoices/void",
+    "operation": "PostInvoicesInvoiceVoid",
+    "means": "Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to deletion , however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found.",
+    "status": 400
+  },
+  {
+    "title": "rule: an invoice no longer a draft is not deleted",
+    "source": "https://docs.stripe.com/api/invoices/delete",
+    "operation": "DeleteInvoicesInvoice",
+    "means": "Attempts to delete invoices that are no longer in a draft state will fail; once an invoice has been finalized or if an invoice is for a subscription, it must be voided .",
+    "status": 400
+  },
+  {
+    "title": "rule: only a draft is finalized",
+    "source": "https://docs.stripe.com/api/invoices/finalize",
+    "operation": "PostInvoicesInvoiceFinalize",
+    "means": "Stripe automatically finalizes drafts before sending and attempting payment on invoices. However, if you’d like to finalize a draft invoice manually, you can do so using this method.",
+    "status": 400
+  },
+  {
+    "title": "Test account numbers: pm_usBankAccount_success",
+    "source": "https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment",
+    "operation": "PostPaymentIntents",
+    "input": {
+      "payment_method": "pm_usBankAccount_success"
+    },
+    "output": {
+      "status": "processing"
+    },
+    "means": "000123456789 pm_usBankAccount_success 110000000 The payment succeeds."
+  },
+  {
+    "title": "Generic decline",
+    "source": "https://docs.stripe.com/testing",
+    "operation": "PostPaymentIntents",
+    "input": {
+      "payment_method_data": {
+        "type": "card",
+        "card": {
+          "number": "4000000000000002",
+          "exp_month": 12,
+          "exp_year": 2030,
+          "cvc": "123"
+        }
+      },
+      "confirm": true
+    },
+    "means": "Generic decline 4000 0000 0000 0002 card_declined generic_decline",
+    "status": 402
+  },
+  {
+    "title": "Always authenticate",
+    "source": "https://docs.stripe.com/testing",
+    "operation": "PostPaymentIntents",
+    "input": {
+      "payment_method_data": {
+        "type": "card",
+        "card": {
+          "number": "4000002760003184",
+          "exp_month": 12,
+          "exp_year": 2030,
+          "cvc": "123"
+        }
+      },
+      "confirm": true
+    },
+    "output": {
+      "status": "requires_action"
+    },
+    "means": "Always authenticate 4000 0027 6000 3184 This card requires authentication on all transactions, regardless of how the card is set up."
+  },
+  {
+    "title": "Test account numbers: pm_usBankAccount_success",
+    "source": "https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment",
+    "operation": "PostPaymentIntentsIntentConfirm",
+    "input": {
+      "payment_method": "pm_usBankAccount_success"
+    },
+    "output": {
+      "status": "processing"
+    },
+    "means": "000123456789 pm_usBankAccount_success 110000000 The payment succeeds."
+  },
+  {
+    "title": "a setup given its method waits for confirmation",
+    "source": "https://docs.stripe.com/payments/paymentintents/lifecycle",
+    "operation": "PostSetupIntents",
+    "input": {
+      "payment_method": "pm_1EXUPv2eZvKYlo2CUkqZASBe"
+    },
+    "output": {
+      "status": "requires_confirmation"
+    },
+    "means": "After your customer provides payment information, the SetupIntent enters the requires_confirmation status and is ready to confirm."
+  },
+  {
+    "title": "microdeposit verification",
+    "source": "https://docs.stripe.com/payments/ach-direct-debit/set-up-payment",
+    "operation": "PostSetupIntentsIntentConfirm",
+    "input": {
+      "payment_method_data": {
+        "type": "us_bank_account"
+      }
+    },
+    "output": {
+      "status": "requires_action"
+    },
+    "means": "If the customer opts for microdeposit verification, Stripe automatically sends two small deposits to the provided bank account."
+  },
+  {
+    "title": "payment_intent_unexpected_state",
+    "source": "https://docs.stripe.com/error-codes",
+    "operation": "PostPaymentIntentsIntentConfirm",
+    "means": "payment_intent_unexpected_state The PaymentIntent’s state was incompatible with the operation you were trying to perform.",
+    "status": 400
+  },
+  {
+    "title": "setup_intent_unexpected_state",
+    "source": "https://docs.stripe.com/error-codes",
+    "operation": "PostSetupIntentsIntentConfirm",
+    "means": "setup_intent_unexpected_state The SetupIntent’s state was incompatible with the operation you were trying to perform.",
+    "status": 400
+  },
+  {
+    "title": "rule: sending a draft finalizes it",
+    "source": "https://docs.stripe.com/invoicing/integration",
+    "operation": "PostInvoicesInvoiceSend",
+    "output": {
+      "status": "open"
+    },
+    "means": "To finalize a draft invoice, use the Dashboard, send it to the customer, or pay it."
+  },
+  {
+    "title": "rule: only an active or not-started schedule is released",
+    "source": "https://docs.stripe.com/api/subscription_schedules/release",
+    "operation": "PostSubscriptionSchedulesScheduleRelease",
+    "means": "A schedule can only be released if its status is not_started or active .",
+    "status": 400
+  },
+  {
+    "title": "close_authorization false",
+    "source": "https://docs.stripe.com/api/issuing/authorizations/test_mode_capture",
+    "operation": "PostTestHelpersIssuingAuthorizationsAuthorizationCapture",
+    "input": {
+      "close_authorization": false
+    },
+    "output": {
+      "status": "pending"
+    },
+    "means": "close_authorization boolean Whether to close the authorization after capture. Defaults to true. Set to false to enable multi-capture flows."
+  },
+  {
+    "title": "To end a trial early",
+    "source": "https://docs.stripe.com/billing/subscriptions/trials/free-trials",
+    "operation": "PostSubscriptionsSubscriptionExposedId",
+    "input": {
+      "trial_end": "now"
+    },
+    "means": "To end a trial early, make an update subscription API call, setting the trial_end value to a new timestamp, or now to end immediately"
+  },
+  {
+    "title": "a trial period on an existing subscription",
+    "source": "https://docs.stripe.com/billing/subscriptions/trials/free-trials",
+    "operation": "PostSubscriptionsSubscriptionExposedId",
+    "input": {
+      "trial_end": 1805760000
+    },
+    "output": {
+      "status": "trialing"
+    },
+    "means": "Trial periods are normally applied at the start of a subscription, but you can also use a trial period on an existing subscription to change the subscription’s billing period (cycle) ."
+  },
+  {
+    "title": "rule: a canceled subscription is largely immutable",
+    "source": "https://docs.stripe.com/api/subscriptions/cancel",
+    "operation": "PostSubscriptionsSubscriptionExposedId",
+    "input": {
+      "trial_end": 1805760000
+    },
+    "means": "After it’s canceled, the subscription is largely immutable. You can still update its metadata and cancellation_details .",
+    "status": 400
+  },
+  {
+    "title": "active: a product no longer for sale",
+    "source": "https://docs.stripe.com/api/products/update",
+    "operation": "PostProductsId",
+    "input": {
+      "active": false
+    },
+    "output": {
+      "active": false
+    },
+    "means": "active boolean Whether the product is available for purchase."
+  },
+  {
+    "title": "active: a product for sale again",
+    "source": "https://docs.stripe.com/api/products/update",
+    "operation": "PostProductsId",
+    "input": {
+      "active": true
+    },
+    "output": {
+      "active": true
+    },
+    "means": "active boolean Whether the product is available for purchase."
+  },
+  {
+    "title": "active: a price no longer for new purchases",
+    "source": "https://docs.stripe.com/api/prices/update",
+    "operation": "PostPricesPrice",
+    "input": {
+      "active": false
+    },
+    "output": {
+      "active": false
+    },
+    "means": "active boolean Whether the price can be used for new purchases. Defaults to true ."
+  },
+  {
+    "title": "active: a price for new purchases again",
+    "source": "https://docs.stripe.com/api/prices/update",
+    "operation": "PostPricesPrice",
+    "input": {
+      "active": true
+    },
+    "output": {
+      "active": true
+    },
+    "means": "active boolean Whether the price can be used for new purchases. Defaults to true ."
+  },
+  {
+    "title": "active: a configuration switched off",
+    "source": "https://docs.stripe.com/api/customer_portal/configurations/update",
+    "operation": "PostBillingPortalConfigurationsConfiguration",
+    "input": {
+      "active": false
+    },
+    "output": {
+      "active": false
+    },
+    "means": "active boolean Whether the configuration is active and can be used to create portal sessions."
+  },
+  {
+    "title": "active: a configuration switched on again",
+    "source": "https://docs.stripe.com/api/customer_portal/configurations/update",
+    "operation": "PostBillingPortalConfigurationsConfiguration",
+    "input": {
+      "active": true
+    },
+    "output": {
+      "active": true
+    },
+    "means": "active boolean Whether the configuration is active and can be used to create portal sessions."
+  },
+  {
+    "title": "Create a Custom connected account",
+    "source": "https://docs.stripe.com/connect/custom-accounts",
+    "operation": "PostAccounts",
+    "input": {
+      "country": "US",
+      "type": "custom",
+      "capabilities": {
+        "card_payments": {
+          "requested": true
+        },
+        "transfers": {
+          "requested": true
+        }
+      }
+    },
+    "output": {
+      "type": "custom"
+    },
+    "means": "The basic process to create and connect a Custom connected account is to call the account creation endpoint, setting type to custom and providing a country and the appropriate capabilities ."
+  },
+  {
+    "title": "rule: a voided invoice cannot be undone",
+    "source": "https://docs.stripe.com/api/invoices/void",
+    "operation": "PostInvoicesInvoicePay",
+    "means": "Mark a finalized invoice as void. This cannot be undone.",
+    "status": 400
+  },
+  {
+    "title": "a bank transfer waits for its funds",
+    "source": "https://docs.stripe.com/payments/bank-transfers/accept-a-payment",
+    "operation": "PostPaymentIntents",
+    "input": {
+      "payment_method_types": [
+        "customer_balance"
+      ],
+      "payment_method_data": {
+        "type": "customer_balance"
+      },
+      "confirm": true
+    },
+    "output": {
+      "status": "requires_action"
+    },
+    "means": "The PaymentIntent stays in a requires_action status until funds arrive in the bank account."
+  },
+  {
+    "title": "rule: a product with prices is not deleted",
+    "source": "https://docs.stripe.com/api/products/delete",
+    "operation": "DeleteProductsId",
+    "means": "Delete a product. Deleting a product is only possible if it has no prices associated with it.",
+    "status": 400
+  },
+  {
+    "title": "rule: both capabilities are disabled while either is inactive",
+    "source": "https://docs.stripe.com/connect/account-capabilities",
+    "operation": "PostTransfers",
+    "means": "If a connected account has both card_payments and transfers , and the status of either one is inactive , then both capabilities are disabled.",
+    "status": 400
+  },
+  {
+    "title": "rule: a payout the balance does not cover is refused",
+    "source": "https://docs.stripe.com/api/payouts/create",
+    "operation": "PostPayouts",
+    "means": "Your Stripe balance must cover the payout amount. If it doesn’t, you receive an “Insufficient Funds” error.",
+    "status": 400
+  },
+  {
+    "title": "rule: a transfer from a charge succeeds before its funds are available",
+    "source": "https://docs.stripe.com/connect/separate-charges-and-transfers",
+    "operation": "PostTransfers",
+    "input": {
+      "source_transaction": "ch_1EXUPv2eZvKYlo2CStIqOmbY"
+    },
+    "means": "When you specify the associated charge as the transfer’s source_transaction , the transfer request automatically succeeds. However, we don’t execute the transfer until the funds from that charge are available in the platform account."
+  },
+  {
+    "title": "rule: a refund names one of the documented reasons",
+    "source": "https://docs.stripe.com/api/refunds/create",
+    "operation": "PostRefunds",
+    "input": {
+      "reason": "outage"
+    },
+    "means": "String indicating the reason for the refund. If set, possible values are duplicate , fraudulent , and requested_by_customer .",
+    "status": 400
+  },
+  {
+    "title": "amount_off",
+    "source": "https://docs.stripe.com/api/coupons/create",
+    "operation": "PostCoupons",
+    "input": {
+      "amount_off": 500,
+      "currency": "usd"
+    },
+    "means": "amount_off integer A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed)."
+  },
+  {
+    "title": "error_if_incomplete",
+    "source": "https://docs.stripe.com/api/subscriptions/create",
+    "operation": "PostSubscriptions",
+    "input": {
+      "payment_behavior": "error_if_incomplete"
+    },
+    "means": "error_if_incomplete If payment fails, return an HTTP 402 status code and don’t create the subscription.",
+    "status": 402
+  }
+]

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`."
+      }
+    }
+  ]
+}