@fun-xyz/fiat-contract 0.6.0 → 0.8.0

package/dist/table.js

@@ -25,14 +25,18 @@ __export(table_exports, {
   TABLE_VERSION: () => TABLE_VERSION,
   TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE: () => TRANSITION_TABLE,
+  UNOFFERED_ENDPOINTS: () => UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES: () => UNREACHABLE_STATES,
   isTerminal: () => isTerminal,
   stateKey: () => stateKey,
-  tableEntry: () => tableEntry
+  tableEntry: () => tableEntry,
+  unofferedEndpoints: () => unofferedEndpoints,
+  unreachableStates: () => unreachableStates
 });
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.6.0";
+var version = "0.8.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -63,22 +67,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",
@@ -86,8 +114,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: {
@@ -132,21 +162,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",
@@ -158,16 +190,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."
     ]
   },
@@ -178,12 +214,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,
@@ -213,20 +253,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: {
@@ -385,10 +416,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",
@@ -399,6 +433,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":

package/dist/table.mjs

@@ -4,18 +4,26 @@ import {
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
   isTerminal,
   stateKey,
-  tableEntry
-} from "./chunk-EHYDQU4T.mjs";
+  tableEntry,
+  unofferedEndpoints,
+  unreachableStates
+} from "./chunk-LVVQ46YG.mjs";
 export {
   DOCUMENTED_ENDPOINTS,
   STATE_KEYS,
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
   isTerminal,
   stateKey,
-  tableEntry
+  tableEntry,
+  unofferedEndpoints,
+  unreachableStates
 };
 //# sourceMappingURL=table.mjs.map

package/dist/types.d.ts

@@ -56,17 +56,12 @@ export type HttpVerb = 'GET' | 'POST';
  * cannot express "no slash", so `GET /fiat/orders/${string}` also admits sub-paths. Precision at
  * that level is the table's job (`allowedTransitions` + `endpointMatches`), not the type's.
  */
-export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | 'GET /fiat/kyc' | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
+export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | `GET /fiat/quotes/${string}` | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/capture' | 'POST /fiat/kyc/sdk-token' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
 /**
- * FiatProvider is metadata: it selects the embedded provider SDK for CLIENT_SURFACE steps and
- * feeds analytics. It never drives sequencing (contract §The fiat step response).
- * TODO(open-decision): the docs name only Transak as a v1 provider for the headless flow
- * (contract §Decisions 3; Swapped-headless does not exist yet, Banxa is Tradeoff #4).
- * `SWAPPED` added at fun-backend's request (2026-08-17) so its legacy fops payment-provider id
- * has one shared vocabulary instead of a second fun-backend-local enum — it never appears as a
- * `FiatStepResponse.provider` value since Swapped's fops flow doesn't emit this response.
+ * Routing metadata, not sequencing policy. Reserved values may be emitted only after their adapter
+ * and conformance fixture land.
  */
-export type FiatProvider = 'TRANSAK' | 'SWAPPED';
+export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA' | 'MOONPAY' | 'STRIPE';
 /**
  * The order status vocabulary. Monotonic ranks, no backwards moves. Terminal outcomes are
  * OrderStatus, never FlowState kinds.
@@ -199,27 +194,45 @@ export interface Refund {
     amount: string;
     expectedBy: string;
 }
+/** What the user sees, and therefore where it can be placed. */
+export type SurfaceKind = 'URL_REDIRECT' | 'KYC_SDK' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT';
 /**
- * Carried as *data* in CAPTURE phases only (`PAYMENT{CAPTURE}` · `KYC{CAPTURE}`).
- * Δ2: the CLIENT_SURFACE transition carries just `report` — single-carry, no duplication.
- * `session` values are secrets: never log them (FE doc §Decisions, redaction).
+ * Identity vendors Fun verifies into. Its own axis rather than a `FiatProvider` value, because
+ * Fun is the KYC-of-record in its own tenant — an identity surface is never the onramp's to mint.
+ * `SUMSUB` alone at 0.7; adding a value later is additive, and a vendor with no installed adapter
+ * lands on the client's existing unsupported screen.
  */
-export type Surface = {
-    kind: 'URL_REDIRECT';
-    url: string;
-} | {
-    kind: 'URL_EMBED';
-    url: string;
-} | {
-    kind: 'PCI_COMPONENT';
-    session: string;
-} | {
-    kind: 'PAY_SHEET';
-    session: string;
-} | {
-    kind: 'ACH_COMPONENT';
-    session: string;
-};
+export type KYCProvider = 'SUMSUB';
+/**
+ * Which adapter renders the surface. Can differ from `FiatStepResponse.provider`: an identity
+ * surface is Fun's to mint, not the onramp's.
+ *
+ * A routing key only — it never narrows the shape of `params`.
+ */
+export type SurfaceProvider = FiatProvider | KYCProvider;
+/**
+ * Carried as data in `QUOTE` (inline in the entry screen's primary slot) and in the CAPTURE
+ * phases (a screen of its own). Δ2 unchanged: the CLIENT_SURFACE transition carries only
+ * `report`, so a surface is never described twice.
+ *
+ * `params` is the adapter's vocabulary — opaque here, narrowed at the adapter boundary, and
+ * honoured verbatim. A provider's own `environment` value lives here and is never normalised:
+ * Transak's is `LOCAL | DEVELOPMENT | STAGING | PRODUCTION`, Banxa's is `sandbox | production`,
+ * and URL surfaces carry none, so a Fun-owned enum could only be lossy.
+ *
+ * `params` values are secrets by default. Client redaction defaults every key closed and opens
+ * only names that are safe under *any* provider's vocabulary.
+ */
+export interface Surface {
+    kind: SurfaceKind;
+    provider: SurfaceProvider;
+    params: Record<string, JsonValue>;
+    /**
+     * When the provider stops honouring the session, if it says so. Lets a client re-quote before
+     * the button goes dead; absent, the surface lives as long as the quote that carried it.
+     */
+    expiresAt?: string;
+}
 export interface InstructionField {
     id: string;
     labelFallback: string;
@@ -402,9 +415,16 @@ export type AuthChallenge = Record<string, JsonValue>;
  *   2. terminal outcomes are OrderStatus, never kinds
  *   3. every fallible state carries `error?: FailureReason`
  */
-export type FlowState = {
+export type FlowState = 
+/**
+ * `surface` present means the provider's own component IS the primary CTA, inline on the entry
+ * screen — the placement Apple policy forces for a pay sheet, since no visible step may sit
+ * between the Apple-branded tap and the sheet. Absent, the quote's SUBMITs drive our button.
+ */
+{
     kind: 'QUOTE';
     quote: Quote;
+    surface?: Surface;
     error?: FailureReason;
 } | {
     kind: 'FUN_AUTH';
@@ -415,20 +435,23 @@ export type FlowState = {
     channel: 'EMAIL_OTP';
     error?: FailureReason;
 }
-/** Dropped from v1 (no UK module coverage) — kind retained, handshake-gated. */
+/** Pre-order KYC states carry the routed quote so the entry screen can keep price visible. */
  | {
     kind: 'KYC';
     phase: 'CAPTURE';
+    quote: Quote;
     surface: Surface;
     error?: FailureReason;
 } | {
     kind: 'KYC';
     phase: 'INPUT_REQUIRED';
+    quote: Quote;
     form: FormDescriptor;
     error?: FailureReason;
 } | {
     kind: 'KYC';
     phase: 'NO_ACTION_REQUIRED';
+    quote: Quote;
     /**
      * Note the deliberate name collision (Charles's nit, review 2026-08-14): `ON_HOLD` appears
      * here as a KYC reason *and* in `OrderStatus`. They are different things and both names come
@@ -443,10 +466,9 @@ export type FlowState = {
     reason: 'IN_REVIEW' | 'ON_HOLD' | 'REJECTED';
     retryAfter?: string;
     /**
-     * Terminal REJECTED variant carries this (FE doc Screen 11: `KYC_REJECTED`,
-     * `retryable: false`, `recovery: CONTACT_SUPPORT`) and renders in place — it never routes
-     * through `ORDER{CREATED, FAILED}`.
-     * TODO(open-decision): contract OQ7 — which rejections escalate vs terminate.
+     * REJECTED is reserved for an explicit non-retryable outcome and renders in place — it
+     * never routes through `ORDER{CREATED, FAILED}`. Correctable outcomes return CAPTURE or
+     * INPUT_REQUIRED; a provider-specific decline is handled by quote rerouting first.
      */
     failureReason?: FailureReason;
     error?: FailureReason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fun-xyz/fiat-contract",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Published conformance contract for Fun's headless fiat onramp: FlowState/Transition types, zod schemas, the transition table as data, recorded fixtures, assertion helpers.",
   "license": "MIT",
   "repository": {
@@ -78,4 +78,4 @@
       ]
     }
   }
-}
+}