@fun-xyz/fiat-contract 0.6.0 → 0.8.0

package/README.md

@@ -10,19 +10,19 @@ Four things, zero runtime logic beyond validation:
 | `src/types.ts` | `FlowState` · `Transition` · `FailureReason` · `Surface` · `Instructions` · `FormDescriptor` · `OrderStatus` · `FiatStepResponse` |
 | `src/schemas.ts` | zod mirrors of every type — the single runtime validator |
 | `src/table.ts` | the transition table **as data**: per state, its legal transition set, the states any call from it may return, and `terminal: boolean` |
-| `src/assert.ts` + `src/fixtures/` | `assertFiatStepResponse` · `assertLegalEmission` · `assertLegalReturn` · `walkTable` · fixture loader + 16 recorded step responses (inlined as data — no filesystem, so React Native can bundle it) |
+| `src/assert.ts` + `src/fixtures/` | `assertFiatStepResponse` · `assertLegalEmission` · `assertLegalReturn` · `walkTable` · fixture loader + 18 recorded step responses (inlined as data — no filesystem, so React Native can bundle it) |
 
 ## Three entry points — production vs test-time
 
 | Import | Weight | Contains | Used by |
 | --- | --- | --- | --- |
 | `@fun-xyz/fiat-contract/types` | **0.1 KB** (types erase) | every type; no runtime values | production, both repos |
-| `@fun-xyz/fiat-contract/table` | **13.8 KB**, zero deps | `TRANSITION_TABLE`, `stateKey`, `tableEntry`, `isTerminal`, `walkTable`, `TABLE_VERSION`, `TERMINAL_ORDER_STATUSES`, `DOCUMENTED_ENDPOINTS` | **production frontend** + backend |
-| `@fun-xyz/fiat-contract` | 47.6 KB, needs zod | the above + 46 zod schemas + assertions + 16 fixtures | tests, and backend dev/test guards |
+| `@fun-xyz/fiat-contract/table` | **13.8 KB**, zero deps | `TRANSITION_TABLE`, `stateKey`, `tableEntry`, `isTerminal`, `walkTable`, `TABLE_VERSION`, `TERMINAL_ORDER_STATUSES`, `DOCUMENTED_ENDPOINTS`, `UNOFFERED_ENDPOINTS`, `UNREACHABLE_STATES`, `unofferedEndpoints`, `unreachableStates` | **production frontend** + backend |
+| `@fun-xyz/fiat-contract` | 47.6 KB, needs zod | the above + 46 zod schemas + assertions + 18 fixtures | tests, and backend dev/test guards |
 
 `./table` is not a micro-optimisation. Terminality is table data a **shipped** client must read
 (litmus rule 3 — clients never infer it), and Metro has no cross-module tree-shaking on by default,
-so importing `isTerminal` from the root would ship zod and all 16 fixtures into a React Native
+so importing `isTerminal` from the root would ship zod and all 18 fixtures into a React Native
 bundle. Two CI jobs hold that line: `consumer` asserts requiring `./table` never loads zod into the
 process, and `metro` bundles `./table` with real Metro — in **both** package-exports modes, since
 Metro before RN 0.79 ignores `exports` entirely — then greps the emitted bundle for zod, fixtures and
@@ -31,7 +31,9 @@ schemas and executes it.
 Source of truth: [Fiat Client Contract](https://app.notion.com/p/3b9fc3b2a002815eb270fa4c818268cc)
 (§The fiat step response · §Conformance package · §split `InputSpec` — ACCEPTED) and
 [Fiat Frontend — State Machine & Screen Map](https://app.notion.com/p/3bbfc3b2a00281c994c2cebd17b1d6d3)
-(✅ Decisions · per-screen State details · Event bindings per flow state).
+(✅ Decisions · per-screen State details · Event bindings per flow state), plus
+[Fiat KYC — User Flow & API Interfaces](https://app.notion.com/p/3cefc3b2a00281c88e7fe771f0c64332)
+for quote-bound KYC states and endpoints.
 Tracking: [Headless Fiat Onramp](https://linear.app/funxyz/project/headless-fiat-onramp-0147f4102399) ·
 this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
 
@@ -52,6 +54,9 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
    string; `GET /fiat/orders/:id` under `SUBMIT` is legal.
 5. **Fixtures stay synthetic.** `q_8f2`, `o_31c`, `eyJ…`, `"…"` — never paste a real session token,
    bank field, or PII value into a fixture. Redaction applies to fixtures too.
+6. **Surface kind names the renderer; provider selects the adapter.** Sumsub capture is
+   `{ kind: 'KYC_SDK', provider: 'SUMSUB' }`. It is not `URL_EMBED`: the client mounts an SDK,
+   not a URL or iframe.
 
 ## Versioning — the package version IS the table version
 
@@ -247,7 +252,7 @@ The table is data, so a runtime walk proves every state resolves to a screen —
 exhaustiveness alone, because it also fails when a *new* state is added to the contract.
 
 ```ts
-import { walkTable, isTerminal, TRANSITION_TABLE } from '@fun-xyz/fiat-contract';
+import { assertFixture, walkTable, isTerminal, TRANSITION_TABLE } from '@fun-xyz/fiat-contract';
 
 it('every contract state resolves to a screen', () => {
   walkTable((entry) => {
@@ -256,7 +261,7 @@ it('every contract state resolves to a screen', () => {
 });
 
 // Terminality is table data — never `transitions.length === 0`
-isTerminal({ kind: 'KYC', phase: 'NO_ACTION_REQUIRED', reason: 'ON_HOLD' }); // false: empty, not over
+isTerminal(assertFixture('screen-10-kyc-on-hold').stepResponse.state);       // false: empty, not over
 isTerminal({ kind: 'ORDER', phase: 'CREATED', status: 'SETTLED' });          // true
 isTerminal({ kind: 'ORDER', phase: 'CREATED', status: 'PROCESSING' });       // false
 
@@ -437,17 +442,15 @@ The current documented shape is what ships; none of these are settled here.
 | --- | --- |
 | `orderId` placement | Both: optional on `PAYMENT{INSTRUCT}` (FE doc v0) **and** optional beside `state` (contract worked example). One fixture of each. |
 | `PENDING_ORDER` removal | Kind ships, with the removal proposal flagged on the type, the table entry, and the fixture. Screen 12 stays frozen. |
-| `[OQ7]` failure enumeration | The published `FailureReason` taxonomy only. Expired instructions, partial payment, per-rail cancel eligibility, and terminal-vs-escalating rejections are flagged unenumerated. |
-| Screen 11 escalation trigger | Encoded as published (`SUBMIT GET /fiat/kyc` + `params: {tier}`) with the doc's own warning that a GET carrying params is not a real shape. |
+| `[OQ7]` failure enumeration | The published `FailureReason` taxonomy only. Expired instructions, partial payment, and per-rail cancel eligibility remain unenumerated; KYC rejection is terminal only for an explicit non-retryable outcome. |
+| Pre-order KYC sequencing | KYC states carry their quote; SDK submission reports to `POST /fiat/kyc/capture`; pending review polls the quote resource. There is no `GET /fiat/kyc`. |
 | Card capture report target | Both topologies are legal in the table (`POST /fiat/orders` for capture-then-order; `POST /fiat/orders/:id/surface-result` otherwise) pending the Transak answer. |
 | Cancel placement | `cancel` is legal on `PAYMENT{INSTRUCT}` and `ORDER{CREATED}`, marked conditional on the placement decision. |
 | `FUN_AUTH` shape | `challenge: Record<string, JsonValue>`; the table entry is `docStatus: 'UNSPECIFIED'`, so `assertLegalEmission` reports it unjudgeable instead of guessing. |
 | `statusHistory` element shape | The documented minimum (`{status}`) — no invented timestamps. |
 | `QR_IMAGE` instruction | In the union per §The fiat step response, flagged against OQ1's "deliberately not pre-declared". |
 
-Two fixture gaps are declared in `FIXTURE_COVERAGE_GAPS` rather than filled with invented step responses:
-`FUN_AUTH` (shape owned by the auth spike) and `KYC/CAPTURE` (Screen 8 tombstone, dropped from v1).
-Every other state has a recorded step response.
+`FUN_AUTH` is the only fixture gap declared in `FIXTURE_COVERAGE_GAPS`; its shape remains owned by the auth spike. Every other state has a recorded step response.
 
 ## Not decided here — needs a human
 

package/dist/{chunk-EHYDQU4T.mjs → chunk-LVVQ46YG.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.6.0";
+var version = "0.8.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -30,22 +30,46 @@ var TRANSITION_TABLE = {
         endpoint: "POST /fiat/session",
         when: "no valid provider session token (own-tables check)"
       },
+      {
+        id: "open_session",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/payment-session",
+        when: "returning user, session + KYC valid, capture-first rail \u2014 the method authorises before any order exists",
+        note: "Returns PAYMENT{CAPTURE} carrying the Surface. Without this entry the capture-first rail has no legal way in: a transition-following client takes POST /fiat/orders instead, and the backend refuses that when the provider declares the capture-first capability and no authorisation is present. Named open_session per the Fiat Contract 0.7 doc, which adds quote-time-minted surface rows beside it."
+      },
       {
         id: "continue",
         mode: "SUBMIT",
         endpoint: "POST /fiat/orders",
-        when: "returning user, session + KYC valid \u2014 the quote screen doubles as review"
+        when: "returning user, session + KYC valid, order-first rail \u2014 the quote screen doubles as review",
+        note: "Narrowed to the order-first rail: on a capture-first method the order cannot be created before the payment is authorised, so the sibling payment-session entry is the one that applies."
       },
       {
         id: "continue",
         mode: "SUBMIT",
         endpoint: "POST /fiat/auth",
         when: "no ambient Fun identity (non-fomo surfaces only)"
+      },
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders",
+        when: "capture-then-order rail whose session is minted at quote time (inline pay sheet)",
+        note: "The 0.7 row that makes the single-screen Apple Pay design legal: the surface rides QUOTE, the provider component IS the primary CTA, and its result creates the order. Apple policy forbids a visible step between an Apple-branded tap and the sheet, and TransakApplePay exposes no programmatic trigger, so a two-step via payment-session cannot serve this rail. Requires state.surface (\u03942)."
+      },
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders/:id/surface-result",
+        when: "order-then-capture rail whose provider order was created with the quote-time session",
+        note: "Same quote-time placement, other topology: the order already exists, so the surface reports against it rather than creating one."
       }
     ],
     mayReturn: [
       "SESSION_AUTH",
       ...KYC_ANY,
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "PENDING_ORDER",
       "ORDER/AWAITING_CONFIRMATION",
       "ORDER/CREATED",
@@ -53,8 +77,10 @@ var TRANSITION_TABLE = {
     ],
     terminal: false,
     notes: [
-      "Re-quote on amount change is a client-local event, not a transition.",
-      'If the PENDING_ORDER removal lands, QUOTE additionally returns PAYMENT{INSTRUCT} / ORDER{CREATED} directly. TODO(open-decision): contract \xA7"Proposal: remove PENDING_ORDER".'
+      "Re-quote on amount change is a client-local event, not a transition. A new quote carries a new surface; the client remounts the adapter rather than reusing the old session.",
+      "A surface on QUOTE and a SUBMIT to the same endpoint may not coexist \u2014 two paths to one order. assertLegalEmission enforces it; the server picks one per rail.",
+      `Both PAYMENT states are reachable directly from QUOTE: the FE doc canvas draws S1 \u2192 S5 (card, capture-first) and S1 \u2192 S6 (bank). This entry was first ported from the FE doc's bindings table, whose "May receive back" column omits both \u2014 the canvas is the correct source of the two.`,
+      'TODO(open-decision): contract \xA7"Proposal: remove PENDING_ORDER" would additionally have QUOTE return ORDER{CREATED} for an active order. That decision does not gate the PAYMENT edges above.'
     ]
   },
   FUN_AUTH: {
@@ -99,21 +125,23 @@ var TRANSITION_TABLE = {
       {
         id: "capture",
         mode: "CLIENT_SURFACE",
-        endpoint: "GET /fiat/kyc",
-        note: 'report target per FE bindings ("POST surface report \u2192 GET /fiat/kyc") and contract Flow C.'
+        endpoint: "POST /fiat/kyc/capture",
+        note: "Reports SDK submission; provider eligibility is re-evaluated through quote orchestration."
       }
     ],
     mayReturn: [
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
-    notes: [
-      "Dropped from v1 (no UK headless-module coverage) \u2014 FE Screen 8 is a tombstone. Kind retained as vocabulary; the handshake (supportedStepKinds) keeps the backend from routing v1 SDKs here."
-    ]
+    notes: ["Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter."]
   },
   "KYC/INPUT_REQUIRED": {
     key: "KYC/INPUT_REQUIRED",
@@ -125,16 +153,20 @@ var TRANSITION_TABLE = {
       { id: "submit_round", mode: "SUBMIT", endpoint: "POST /fiat/kyc/form" }
     ],
     mayReturn: [
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
     notes: [
       "One POST per round; conditional requirements may open another round.",
-      "FILE fields stream to POST /fiat/kyc/document \u2014 an upload path the harness owns, not a transition.",
+      "FILE fields use POST /fiat/kyc/document to obtain or report a direct provider/vendor upload; document bytes never transit Fun. The harness owns this auxiliary path, not a transition.",
       "Hosted KYC links arrive as HOSTED_LINK form fields, not as a Surface."
     ]
   },
@@ -145,12 +177,16 @@ var TRANSITION_TABLE = {
     reason: "IN_REVIEW",
     screens: [9],
     docStatus: "SPECIFIED",
-    allowedTransitions: [{ id: "poll", mode: "AWAIT", endpoint: "GET /fiat/kyc" }],
+    allowedTransitions: [{ id: "poll", mode: "AWAIT", endpoint: "GET /fiat/quotes/:quoteRef" }],
     mayReturn: [
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
@@ -180,20 +216,11 @@ var TRANSITION_TABLE = {
     reason: "REJECTED",
     screens: [11],
     docStatus: "SPECIFIED",
-    allowedTransitions: [
-      {
-        id: "escalate",
-        mode: "SUBMIT",
-        endpoint: "GET /fiat/kyc",
-        when: "an escalation round is offered",
-        note: "TODO(open-decision): placeholder shape \u2014 the FE doc flags that a GET carrying params is not a real request shape, and OQ7 owns which rejections escalate. FE doc open question 7."
-      }
-    ],
-    mayReturn: KYC_ANY,
-    terminal: false,
+    allowedTransitions: [],
+    mayReturn: [],
+    terminal: true,
     notes: [
-      "Terminal *variant*: failureReason {KYC_REJECTED, retryable: false, recovery: CONTACT_SUPPORT} + transitions [] \u2014 renders in place, never routes through ORDER{CREATED, FAILED}. Because escalation is also legal here, the entry is not flatly terminal.",
-      "TODO(open-decision): contract OQ7 \u2014 terminal vs escalating rejections are not enumerated."
+      "Only explicit non-retryable outcomes reach REJECTED. Correctable failures return CAPTURE or INPUT_REQUIRED; provider-specific declines re-route before becoming user rejection."
     ]
   },
   PENDING_ORDER: {
@@ -352,10 +379,13 @@ var DOCUMENTED_ENDPOINTS = [
   "GET /fiat/payment-methods",
   "POST /fiat/quote",
   "POST /fiat/auth",
+  "POST /fiat/payment-session",
   "POST /fiat/session",
   "POST /fiat/session/verify",
-  "GET /fiat/kyc",
+  "GET /fiat/quotes/:quoteRef",
   "POST /fiat/kyc/form",
+  "POST /fiat/kyc/capture",
+  "POST /fiat/kyc/sdk-token",
   "POST /fiat/kyc/document",
   "POST /fiat/instruments",
   "POST /fiat/orders",
@@ -366,6 +396,58 @@ var DOCUMENTED_ENDPOINTS = [
   "POST /fiat/orders/:id/cancel",
   "POST /fiat/orders/:id/surface-result"
 ];
+var UNOFFERED_ENDPOINTS = [
+  {
+    endpoint: "POST /fiat/kyc/sdk-token",
+    reason: "SDK token refresh is adapter-driven rather than a flow transition."
+  },
+  {
+    endpoint: "GET /fiat/payment-methods",
+    reason: "Discovery, called before any flow state exists \u2014 there is no state to hang it off."
+  },
+  {
+    endpoint: "POST /fiat/kyc/document",
+    reason: "FILE fields use it for a direct provider/vendor upload handshake and completion report; the harness owns that auxiliary path and it is not a transition (see KYC/INPUT_REQUIRED notes)."
+  },
+  {
+    endpoint: "POST /fiat/instruments",
+    reason: "No state offers it and no published doc explains why. TODO(open-decision): saved instruments may simply be unreached in v1 \u2014 confirm, or wire it to the state that should offer it."
+  },
+  {
+    endpoint: "GET /fiat/orders/:id/instructions",
+    reason: "PAYMENT{INSTRUCT} carries its instructions in state and offers no fetch. TODO(open-decision): that state also notes no re-issue endpoint exists, which sits oddly beside this one being published \u2014 confirm or retire it."
+  },
+  {
+    endpoint: "POST /fiat/orders/:id/reference",
+    reason: "The bank-reference submission is offered by no state. TODO(open-decision): PAYMENT{INSTRUCT} is the plausible home \u2014 confirm or wire it."
+  }
+];
+var UNREACHABLE_STATES = [
+  {
+    stateKey: "FUN_AUTH",
+    reason: "No bindings row published (docStatus UNSPECIFIED) and never rendered in fomo, where identity is ambient. Entered out-of-band, not by a mayReturn edge."
+  }
+];
+function unofferedEndpoints() {
+  const offered = /* @__PURE__ */ new Set();
+  for (const key of STATE_KEYS) {
+    for (const allowed of TRANSITION_TABLE[key].allowedTransitions) offered.add(allowed.endpoint);
+  }
+  return DOCUMENTED_ENDPOINTS.filter((endpoint) => !offered.has(endpoint));
+}
+function unreachableStates(from = "QUOTE") {
+  const seen = /* @__PURE__ */ new Set([from]);
+  const queue = [from];
+  while (queue.length > 0) {
+    for (const target of TRANSITION_TABLE[queue.pop()].mayReturn ?? []) {
+      if (!seen.has(target)) {
+        seen.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  return STATE_KEYS.filter((key) => !seen.has(key));
+}
 function stateKey(state) {
   switch (state.kind) {
     case "QUOTE":
@@ -408,8 +490,12 @@ export {
   TRANSITION_TABLE,
   STATE_KEYS,
   DOCUMENTED_ENDPOINTS,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
+  unofferedEndpoints,
+  unreachableStates,
   stateKey,
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-EHYDQU4T.mjs.map
+//# sourceMappingURL=chunk-LVVQ46YG.mjs.map

package/dist/fixtures/index.d.ts

@@ -1,9 +1,8 @@
 /**
  * fiat-contract — recorded fixtures + loader.
  *
- * Every `.json` file in this directory is a step response copied **verbatim** from the docs — the
- * FE doc's per-screen "State details" responses plus the contract doc's worked example. The one
- * exception is `screen-04-order-review.json`, whose payload the doc publishes *by reference*
+ * Every `.json` file in this directory records a step response from the source named in its
+ * metadata. `screen-04-order-review.json` is the one payload published *by reference*
  * ("quote: <same shape as Screen 1, refreshed>"): its quote is Screen 1's payload verbatim.
  * They are
  * already synthetic (`q_8f2`, `o_31c`, `eyJ…`, `"…"` placeholders); the redaction rule applies to
@@ -15,7 +14,7 @@
  * wire, and the contract has no half-response shape.
  */
 import type { StateKey } from '../table';
-export type FixtureSource = 'FE_DOC' | 'CONTRACT_DOC';
+export type FixtureSource = 'FE_DOC' | 'CONTRACT_DOC' | 'KYC_DOC';
 export interface FixtureMeta {
     id: string;
     file: string;