@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/test-fixtures/stripe-known-deviations.json

@@ -0,0 +1,105 @@
+{
+ "_doc": "Declared scope for the Stripe twin: published fields it does NOT emit, each with a reason. The spec-conformance gate (stripe-conformance.ts) treats a missing-required field as a BUG unless it is declared here. Applies across the Stripe objects the twin serves. Stripe is the twin we cannot dual-run live, so the published OpenAPI is the authority \u2014 keeping this list short and reasoned is how we stay honest about the gaps.",
+ "deviations": [
+  {
+   "path": "type",
+   "kind": "missing-required",
+   "reason": "Stripe's price.type (one_time|recurring) collides with the kernel's resource-type discriminator (every twin resource carries an internal `type`, which view() strips before emit). So a vendor `type` field cannot currently be emitted. Known limitation \u2014 a candidate for moving the kernel discriminator to a reserved key. Only `price` declares a required `type`; other served objects do not."
+  },
+  {
+   "path": "_price.type-list-filter",
+   "kind": "list-filter-approximated",
+   "reason": "GET /v1/prices?type=one_time|recurring cannot filter on the (stripped) price.type field for the same reason price.type is a declared missing-required deviation above. It is approximated by the presence of the vendor `recurring` object \u2014 recurring prices carry it, one-time prices do not \u2014 which is faithful for prices the twin itself created. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_invoice.subscription-list-filter",
+   "kind": "list-filter-unmodeled",
+   "reason": "GET /v1/invoices accepts a `subscription` filter param (Stripe documents it) but the twin does not auto-link invoices to subscriptions: invoices are created as standalone drafts, and modern Stripe nests the link under parent.subscription_details.subscription rather than a top-level field (the vendor schema has no top-level invoice.subscription). The filter therefore only matches when a caller has explicitly stored a `subscription` field on the invoice; otherwise it yields no matches. The param is accepted, not rejected \u2014 consistent with Stripe ignoring filters that match nothing. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_dispute.not-auto-created",
+   "kind": "resource-modeled-statefully",
+   "reason": "Disputes are modeled statefully via the action log (create/list/retrieve/update/close), NOT auto-raised from charges: the twin does not simulate an acquirer/cardholder raising a chargeback, so no dispute appears merely because a charge exists. A caller (or seeding) creates one referencing a charge via POST /v1/disputes. All 15 vendor-required dispute fields ARE emitted (amount, balance_transactions, charge, created, currency, enhanced_eligibility_types, evidence, evidence_details, is_charge_refundable, livemode, metadata, reason, status, plus id/object); `amount`/`charge` come from the caller (Stripe disputes always reference a charge). Closing is terminal (status -> lost), matching Stripe. evidence/evidence_details emit Stripe's canonical empty shapes (all-null evidence bag), not fabricated content. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_payout.created-not-settled",
+   "kind": "resource-modeled-statefully",
+   "reason": "Payouts are modeled statefully via the action log (create/list/retrieve/cancel). The twin does not simulate the bank-settlement timeline: a created payout starts `status=pending` and only transitions on an explicit POST /v1/payouts/:id/cancel (-> canceled); it does not auto-advance to in_transit/paid. arrival_date is stamped at creation time rather than a real future settlement date. All vendor-required payout fields are emitted; `amount`/`currency` come from the caller and are validated (positive integer + currency) like charges. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_balance.synthesized-from-ledger",
+   "kind": "resource-synthesized",
+   "reason": "GET /v1/balance is synthesized from the balance_transaction ledger, not stored: settled transactions (status=available) fold into the `available` array and unsettled ones (status=pending) into `pending`, summed by currency over each transaction's `net` (amount minus fee). This mirrors Stripe's available/pending arrays per currency. The per-currency source_types breakdown is approximated as all-`card`. With no ledger the balance is a valid zero (one usd entry). Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_balance_transaction.writable-for-seeding",
+   "kind": "resource-modeled-statefully",
+   "reason": "In real Stripe, balance_transactions are created only as side-effects of money movement (charges, refunds, payouts) and have no create endpoint. The twin exposes POST /v1/balance_transactions so the ledger can be seeded statefully, since the twin does not auto-generate a balance_transaction for every charge/refund/payout. `net` defaults to amount - fee. All vendor-required fields are emitted with faithful enum values (type/status/balance_type/reporting_category). Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_card.declines-test-set-only",
+   "kind": "behavior-modeled-subset",
+   "reason": "Charge/PaymentIntent-confirm card declines are modeled for Stripe's DOCUMENTED TEST CARDS only (PAN 4242\u20264242 + pm_card_visa/tok_visa succeed; 4000\u20260002 generic_decline, 4000\u20269995 insufficient_funds, 4000\u20260069 expired_card, 4000\u20260127 incorrect_cvc, 4000\u20260119 processing_error, plus the matching pm_card_*/tok_* tokens). A known declining card returns the real Stripe card-error envelope (HTTP 402, error.type=card_error, code, decline_code for card_declined, message, param=card, and the charge/payment_intent id) records the attempt as a failed charge (failure_code, failure_message, outcome) that the error names and a confirmed PaymentIntent's latest_charge points at, leaving the intent at status=requires_payment_method with last_payment_error (carrying the declined card) set and no payment_method. ANY card the twin does not recognize (real PANs, unknown test tokens, or no card at all) succeeds, deterministically \u2014 the twin is not a risk/fraud engine and does not simulate issuer behavior beyond Stripe's published test set. Resolution reads card[number]/source[number] (raw PAN) or payment_method/source/card (token id). Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_idempotency.stored-per-root",
+   "kind": "behavior-modeled-statefully",
+   "reason": "The Idempotency-Key request header is honored on POST: the first request with a key executes and its (status + body) response is persisted in the action log as an internal `_idempotency` resource; a replay with the SAME key returns the byte-identical stored response without re-applying the write (verified: two POSTs \u2192 one resource). Simplifications vs real Stripe: the stored response is keyed per twin-root (a fork has its own keyspace) rather than per Stripe account+key; there is no 24h expiry; and the twin does not detect a request-payload mismatch for a reused key (real Stripe 400s when the same key is reused with different params). Every executed POST is stored, including card-decline 402s (Stripe also persists those). `_idempotency` is twin-internal and never served as a Stripe object, so it is exempt from spec conformance. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_event.modeled-shape",
+   "kind": "resource-modeled-statefully",
+   "reason": "The Events API (GET /v1/events, GET /v1/events/:id) is modeled statefully via the action log. The twin separately emits live webhook events on writes (stripe-events.ts); the Events API here serves explicitly-recorded event objects with the faithful vendor shape (type, api_version, created, data.object, livemode, pending_webhooks). pending_webhooks defaults to 0 because the twin delivers webhooks synchronously. data.object defaults to an empty object when the caller does not supply a snapshot. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_checkout.completion-modeled",
+   "kind": "behavior-modeled-statefully",
+   "reason": "Real Stripe completes a Checkout Session when the customer pays on the hosted page (there is no public REST verb to complete a session). The twin serves that page at the session's url (/c/pay/:id, src/screens/checkout.tsx): paying there (only while `open`) completes the session and creates+links a real twin object: a succeeded payment_intent (mode=payment, amount = amount_total) with payment_status\u2192paid, an active subscription (mode=subscription, when a customer is present) with payment_status\u2192paid, or a succeeded setup_intent (mode=setup). POST :id/expire transitions open\u2192expired (terminal). amount_subtotal/amount_total are computed by summing resolved line_items (an existing Price's unit_amount, or inline price_data.unit_amount, \u00d7 quantity). Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_tax.calculation-list-endpoint",
+   "kind": "endpoint-added-for-mirror",
+   "reason": "Real Stripe has NO list endpoint for tax calculations (POST creates a calculation, GET :id retrieves it, GET :id/line_items lists its items). The twin adds GET /v1/tax/calculations as a faithful-shaped list envelope (object:'list', data[]) purely so the dashboard mirror's Tax > Calculations section can render the calculations stored in twin state. Create/retrieve/line_items match Stripe exactly; the list is a twin convenience. The twin also models a DEFAULT 10% exclusive tax rate for calculations (real Stripe derives the rate from the customer's jurisdiction + registrations) so the returned amount_total/tax_amount_exclusive are deterministic and assertable. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_tax_id.flat-list-endpoint",
+   "kind": "list-endpoint-added",
+   "reason": "Real Stripe scopes tax IDs UNDER a customer (POST/GET /v1/customers/:id/tax_ids). The twin also exposes a flat GET /v1/tax_ids list (filterable by customer) so the dashboard mirror can render a Customer Tax IDs section; the canonical per-customer create/retrieve/list/delete are the faithful surface and all enforce 404 on a missing customer/tax_id. Deleted tax IDs (DELETE returns the deleted-object stub) are excluded from both lists. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_customer_balance_transaction.flat-list-endpoint",
+   "kind": "list-endpoint-added",
+   "reason": "Real Stripe scopes customer balance transactions UNDER a customer (POST/GET /v1/customers/:id/balance_transactions). The twin also exposes a flat GET /v1/customer_balance_transactions list so the mirror can render a Customer Balance section. ending_balance is the running balance after each txn (a negative amount is a credit), computed from the prior ledger, and the owning customer.balance is kept in sync. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "_credit_note.single-amount-type",
+   "kind": "field-simplified",
+   "reason": "CreditNotes are modeled in the amount form (the credited cents) referencing a finalized invoice (POST /v1/credit_notes requires invoice (must exist) plus a positive amount); preview (GET /v1/credit_notes/preview), retrieve, /lines, void (terminal: status void) and list all round-trip. Stripe additionally supports per-invoice-line credits and a mixed type; the twin emits a single custom_line_item and picks pre_payment (unpaid invoice) or post_payment (paid invoice) for the vendor type. All 22 vendor-required credit_note fields are emitted. The vendor type field collides with the kernel discriminator and is stashed under the reserved _stripe_type key (restored by view()), like payout/account. Leading underscore marks this as a twin-internal note (not a vendor schema path)."
+  },
+  {
+   "path": "current_period_start",
+   "kind": "extra",
+   "reason": "Real Stripe moved current_period_start off the top-level Subscription object onto subscription ITEMS in the 2025-03-31.basil API version. The vendored stripe-schemas.json fixture is fetched from stripe/openapi@master (always the LATEST published shape), so its subscription schema reflects the post-migration object and has no current_period_start property — hence this shows as a fabricated 'extra' field under the harness's single-snapshot schema. But this twin's own DEFAULT served version when a caller sends no Stripe-Version header is TWIN_API_VERSION ('2024-06-20', see its definition in stripe-twin.ts), which pre-dates that migration; on that version real Stripe DOES emit current_period_start top-level, so emitting it here is faithful to what this twin actually serves by default. Prior to this fix the twin never set this field at all (a real fidelity gap: real Stripe on ANY version always populates a billing period on a subscription). It is now computed (== the create-time billing_cycle_anchor, or trial_start during a trial — see the POST /v1/subscriptions handler and POST /v1/checkout/sessions/:id completion handler). A future improvement would branch by req.apiVersion and additionally/only emit it at the item level for callers explicitly on 2025-03-31.basil+, but the twin does not currently branch response SHAPE by apiVersion anywhere (only the recorded api_version metadata on events does), so that is left as a known follow-up rather than implemented speculatively here."
+  },
+  {
+   "path": "current_period_end",
+   "kind": "extra",
+   "reason": "Same deviation and reasoning as current_period_start immediately above — also computed by the same two create paths as current_period_start + one billing interval (day/week/month/year × interval_count) taken from the subscription's first item's Price.recurring, defaulting to month/1 when no recurring price is resolvable (e.g. an inline price_data item, or — real Stripe would itself reject this — no item at all)."
+  },
+  {
+   "path": "payment_intent",
+   "kind": "extra",
+   "reason": "Real Stripe removed the top-level payment_intent field from Invoice (replaced by the `payments` list + `confirmation_secret`) as part of the multiple-payment-attempts migration on newer API versions. The vendored stripe-schemas.json fixture is fetched from stripe/openapi@master (always the LATEST published shape), so its invoice schema reflects the post-migration object and has no payment_intent property — hence this shows as a fabricated 'extra' field under the harness's single-snapshot schema, same mechanism as current_period_start/_end above. But this twin's own DEFAULT served version when a caller sends no Stripe-Version header is TWIN_API_VERSION ('2024-06-20', see its definition in stripe-twin.ts), which pre-dates that migration; on that version real Stripe DOES emit invoice.payment_intent top-level, so emitting it here is faithful to what this twin actually serves by default. Prior to this fix the field existed in the EXPANDABLE map (expand[]=payment_intent was already wired) but the invoice action handler (POST /v1/invoices/:id/{finalize,pay,send}) never created a PaymentIntent or set it — every expand came back with nothing (PEAK-3102). It is now minted the moment a charge_automatically invoice with a positive balance is finalized (or auto-finalized via send), null for send_invoice / $0 invoices, and set to null explicitly at draft creation so the field round-trips before finalize too."
+  },
+  {
+   "path": "invoice",
+   "kind": "extra",
+   "reason": "Same pre-2025 API-version story as the payment_intent deviation immediately above, on the OTHER two objects of that same reverse link: real Stripe also removed the top-level invoice field from BOTH PaymentIntent and Charge in the same multiple-payment-attempts migration (a payment's invoice is reached via Invoice.payments now, not a back-reference on the payment side), so stripe-schemas.json (LATEST published shape) has no invoice property on payment_intent or charge — 'extra' under the harness's single-snapshot schema. On this twin's default-served TWIN_API_VERSION ('2024-06-20', pre-migration) real Stripe DOES emit both. The twin's own EXPANDABLE map already declared payment_intent.invoice and charge.invoice as expandable before this fix (used by the subscription default_incomplete first-invoice PaymentIntent); this fix (PEAK-3102) is the first path that also sets charge.invoice, when POST /v1/invoices/:id/pay settles the invoice's PaymentIntent and mints a Charge referencing it."
+  },
+  {
+   "path": "price",
+   "kind": "extra",
+   "reason": "PEAK-3102 round 2: POST /v1/invoiceitems now stores the caller-supplied `price` id on the invoiceitem (needed to resolve amount = unit_amount * quantity for PeakHealth's catalog-product order path). Real Stripe replaced the top-level InvoiceItem.price field with a `pricing.price_details` object in a later API-version migration — stripe-schemas.json (LATEST published shape) reflects the post-migration object and has no price property, hence 'extra' under the harness's single-snapshot schema, same mechanism as current_period_start/_end and payment_intent above. This twin's default-served TWIN_API_VERSION ('2024-06-20') pre-dates that migration, where real Stripe DOES emit invoiceitem.price top-level, so emitting it here is faithful to what this twin actually serves by default."
+  }
+ ]
+}

package/dist/test-fixtures/stripe-openapi-operations.SOURCE.md

@@ -0,0 +1,14 @@
+# stripe-openapi-operations.json — provenance
+
+The operation-inventory denominator for `../stripe-spec-census.json`: a scope-filtered subset of
+the vendor's published spec, enumerated by `deriveFromOpenAPI` (`packages/world-tooling/src/derive.ts`).
+
+- **Upstream:** https://github.com/stripe/openapi — `openapi/spec3.json`.
+- **How it was built:** `bun scripts/spec-census-bootstrap.ts --vendor stripe --from-file <openapi/spec3.json> --scope-paths /v1/account,/v1/account_links,/v1/account_sessions,/v1/accounts,/v1/application_fees,/v1/balance,/v1/balance_transactions,/v1/billing,/v1/billing_portal,/v1/charges,/v1/checkout,/v1/climate,/v1/coupons,/v1/credit_notes,/v1/crypto,/v1/customer_balance_transactions,/v1/customers,/v1/disputes,/v1/entitlements,/v1/ephemeral_keys,/v1/events,/v1/file_links,/v1/files,/v1/financial_connections,/v1/forwarding,/v1/identity,/v1/invoiceitems,/v1/invoices,/v1/mandates,/v1/payment_intents,/v1/payment_links,/v1/payment_methods,/v1/payouts,/v1/prices,/v1/products,/v1/promotion_codes,/v1/quotes,/v1/radar,/v1/refunds,/v1/reporting,/v1/reviews,/v1/setup_intents,/v1/sources,/v1/subscription_items,/v1/subscription_schedules,/v1/subscriptions,/v1/tax,/v1/tax_ids,/v1/tax_rates,/v1/test_helpers,/v1/tokens,/v1/topups,/v1/transfers,/v1/treasury,/v1/webhook_endpoints --apply`
+  over a copy of the upstream file fetched 2026-09-01; operation metadata only (operationId, summary, tags), schemas and response codes dropped. The gate never fetches — refreshing the fixture is
+  `bun scripts/spec-refresh.ts --vendor stripe --from-file <newer spec> --apply` over a newly fetched copy.
+- **Scope (475 of 594 upstream operations):** every operation whose path starts with one of
+  `/v1/account`, `/v1/account_links`, `/v1/account_sessions`, `/v1/accounts`, `/v1/application_fees`, `/v1/balance`, `/v1/balance_transactions`, `/v1/billing`, `/v1/billing_portal`, `/v1/charges`, `/v1/checkout`, `/v1/climate`, `/v1/coupons`, `/v1/credit_notes`, `/v1/crypto`, `/v1/customer_balance_transactions`, `/v1/customers`, `/v1/disputes`, `/v1/entitlements`, `/v1/ephemeral_keys`, `/v1/events`, `/v1/file_links`, `/v1/files`, `/v1/financial_connections`, `/v1/forwarding`, `/v1/identity`, `/v1/invoiceitems`, `/v1/invoices`, `/v1/mandates`, `/v1/payment_intents`, `/v1/payment_links`, `/v1/payment_methods`, `/v1/payouts`, `/v1/prices`, `/v1/products`, `/v1/promotion_codes`, `/v1/quotes`, `/v1/radar`, `/v1/refunds`, `/v1/reporting`, `/v1/reviews`, `/v1/setup_intents`, `/v1/sources`, `/v1/subscription_items`, `/v1/subscription_schedules`, `/v1/subscriptions`, `/v1/tax`, `/v1/tax_ids`, `/v1/tax_rates`, `/v1/test_helpers`, `/v1/tokens`, `/v1/topups`, `/v1/transfers`, `/v1/treasury`, `/v1/webhook_endpoints`.
+- **Mapping:** 418 operations mapped to capability ids by segment match at birth and reviewed by
+  hand; 57 left `unmapped` (the ratchet baseline). Every later ruling (a `$ruled` marker, a
+  remap) is an edit to the census, never to this fixture.