@fun-xyz/fiat-contract 0.7.0 → 0.8.0

package/README.md

@@ -10,7 +10,7 @@ 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
 
@@ -18,11 +18,11 @@ Four things, zero runtime logic beyond validation:
 | --- | --- | --- | --- |
 | `@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`, `UNOFFERED_ENDPOINTS`, `UNREACHABLE_STATES`, `unofferedEndpoints`, `unreachableStates` | **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` | 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-OGNYHIOE.mjs → chunk-LVVQ46YG.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.7.0";
+var version = "0.8.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -125,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",
@@ -151,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."
     ]
   },
@@ -171,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,
@@ -206,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: {
@@ -381,8 +382,10 @@ var DOCUMENTED_ENDPOINTS = [
   "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",
@@ -394,13 +397,17 @@ var DOCUMENTED_ENDPOINTS = [
   "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 stream to it directly; the harness owns that upload path and it is not a transition (see KYC/INPUT_REQUIRED notes)."
+    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",
@@ -491,4 +498,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-OGNYHIOE.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;