@fun-xyz/fiat-contract 0.7.0 → 0.9.0

package/dist/table.js

@@ -36,7 +36,7 @@ __export(table_exports, {
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.7.0";
+var version = "0.9.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -142,6 +142,8 @@ var TRANSITION_TABLE = {
     ],
     mayReturn: [
       "SESSION_AUTH",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
       ...KYC_ANY,
       "ORDER/AWAITING_CONFIRMATION",
       "PENDING_ORDER"
@@ -162,21 +164,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",
@@ -188,16 +192,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."
     ]
   },
@@ -208,12 +216,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,
@@ -243,20 +255,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: {
@@ -418,8 +421,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",
@@ -431,13 +436,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",

package/dist/table.mjs

@@ -11,7 +11,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-OGNYHIOE.mjs";
+} from "./chunk-5QGVY5Z4.mjs";
 export {
   DOCUMENTED_ENDPOINTS,
   STATE_KEYS,

package/dist/types.d.ts

@@ -56,19 +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.
- * `BANXA` added at 0.7 (Provider Landscape: Tier 1). A vendor name here is a routing key only —
- * it never decides which fields exist, which is what keeps provider churn out of this package.
+ * Routing metadata, not sequencing policy. Reserved values may be emitted only after their adapter
+ * and conformance fixture land.
  */
-export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA';
+export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA' | 'MOONPAY' | 'STRIPE' | 'COINBASE' | 'CROSSMINT';
 /**
  * The order status vocabulary. Monotonic ranks, no backwards moves. Terminal outcomes are
  * OrderStatus, never FlowState kinds.
@@ -158,6 +151,11 @@ export interface Quote {
     paymentMethod: PaymentMethodCategory;
     expiresAt: string;
 }
+/** Input bounds for the quote screen. Decimal strings in the quote currency. */
+export interface QuoteLimits {
+    min: string;
+    max: string;
+}
 /** Deferred to the credit-card iteration (FE doc port ledger) — optional wherever it appears. */
 export interface Instrument {
     brandLabel: string;
@@ -202,7 +200,7 @@ export interface Refund {
     expectedBy: string;
 }
 /** What the user sees, and therefore where it can be placed. */
-export type SurfaceKind = 'URL_REDIRECT' | 'URL_EMBED' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT';
+export type SurfaceKind = 'URL_REDIRECT' | 'KYC_SDK' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT' | 'AUTH_COMPONENT';
 /**
  * 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.
@@ -431,6 +429,8 @@ export type FlowState =
 {
     kind: 'QUOTE';
     quote: Quote;
+    limits: QuoteLimits;
+    helper?: string;
     surface?: Surface;
     error?: FailureReason;
 } | {
@@ -439,23 +439,27 @@ export type FlowState =
     error?: FailureReason;
 } | {
     kind: 'SESSION_AUTH';
-    channel: 'EMAIL_OTP';
+    channel: 'EMAIL_OTP' | 'SMS_OTP' | 'PROVIDER_RENDERED';
+    surface?: Surface;
     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
@@ -470,10 +474,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;
@@ -490,11 +493,7 @@ export type FlowState =
     error?: FailureReason;
 } | {
     kind: 'BLOCKED';
-    /**
-     * Observed value: `REGION_UNSUPPORTED` (FE doc Screen 16). The contract types this as
-     * `string`; no enum is published, so none is invented here.
-     */
-    reason: string;
+    reason: BlockedReason;
     /** `null` renders "no comeback date" (FE doc Screen 16 emits it explicitly). */
     retryAfter?: string | null;
     error?: FailureReason;
@@ -532,6 +531,7 @@ export type FlowState =
     error?: FailureReason;
 };
 export type FlowStateKind = FlowState['kind'];
+export type BlockedReason = 'REGION_UNSUPPORTED' | 'ASSET_UNSUPPORTED' | 'ALL_PROVIDERS_DECLINED' | 'AMOUNT_UNSERVABLE';
 /**
  * Every `/fiat/*` response. `transitions: []` = nothing the wizard can do; whether the *flow*
  * is over is read from the table (`terminal`), never from array emptiness (ON_HOLD is the proof).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fun-xyz/fiat-contract",
-  "version": "0.7.0",
+  "version": "0.9.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": {