@fun-xyz/fiat-contract 0.7.0 → 0.9.0

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-OGNYHIOE.mjs";
+} from "./chunk-5QGVY5Z4.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -295,7 +295,15 @@ var HTTP_VERBS = ["GET", "POST"];
 var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
 var $endpoint = z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
 var FiatEndpointSchema = $endpoint;
-var $provider = z.enum(["TRANSAK", "SWAPPED", "BANXA"]);
+var $provider = z.enum([
+  "TRANSAK",
+  "SWAPPED",
+  "BANXA",
+  "MOONPAY",
+  "STRIPE",
+  "COINBASE",
+  "CROSSMINT"
+]);
 var FiatProviderSchema = $provider;
 var $kycProvider = z.enum(["SUMSUB"]);
 var KYCProviderSchema = $kycProvider;
@@ -362,6 +370,8 @@ var $quote = obj({
   expiresAt: z.string()
 });
 var QuoteSchema = $quote;
+var $quoteLimits = obj({ min: z.string(), max: z.string() });
+var QuoteLimitsSchema = $quoteLimits;
 var $instrument = obj({ brandLabel: z.string(), last4: z.string() });
 var InstrumentSchema = $instrument;
 var $orderRef = obj({
@@ -392,7 +402,14 @@ var $refund = obj({
   expectedBy: z.string()
 });
 var RefundSchema = $refund;
-var $surfaceKind = z.enum(["URL_REDIRECT", "URL_EMBED", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]);
+var $surfaceKind = z.enum([
+  "URL_REDIRECT",
+  "KYC_SDK",
+  "PCI_COMPONENT",
+  "PAY_SHEET",
+  "ACH_COMPONENT",
+  "AUTH_COMPONENT"
+]);
 var SurfaceKindSchema = $surfaceKind;
 var $surface = obj({
   kind: $surfaceKind,
@@ -537,6 +554,8 @@ var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
   kind: z.literal("QUOTE"),
   quote: $quote,
+  limits: $quoteLimits,
+  helper: z.string().optional(),
   /** Present when the provider's component is the primary CTA, inline on the entry screen. */
   surface: $surface.optional(),
   error: $failureReason.optional()
@@ -550,13 +569,15 @@ var $funAuthState = obj({
 var FunAuthStateSchema = $funAuthState;
 var $sessionAuthState = obj({
   kind: z.literal("SESSION_AUTH"),
-  channel: z.literal("EMAIL_OTP"),
+  channel: z.enum(["EMAIL_OTP", "SMS_OTP", "PROVIDER_RENDERED"]),
+  surface: $surface.optional(),
   error: $failureReason.optional()
 });
 var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("CAPTURE"),
+  quote: $quote,
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -564,6 +585,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("INPUT_REQUIRED"),
+  quote: $quote,
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -571,6 +593,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("NO_ACTION_REQUIRED"),
+  quote: $quote,
   reason: z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -583,9 +606,16 @@ var $pendingOrderState = obj({
   error: $failureReason.optional()
 });
 var PendingOrderStateSchema = $pendingOrderState;
+var $blockedReason = z.enum([
+  "REGION_UNSUPPORTED",
+  "ASSET_UNSUPPORTED",
+  "ALL_PROVIDERS_DECLINED",
+  "AMOUNT_UNSERVABLE"
+]);
+var BlockedReasonSchema = $blockedReason;
 var $blockedState = obj({
   kind: z.literal("BLOCKED"),
-  reason: z.string(),
+  reason: $blockedReason,
   retryAfter: z.string().nullable().optional(),
   error: $failureReason.optional()
 });
@@ -652,6 +682,10 @@ var FIXTURE_DATA = {
   "screen-01-quote": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00"
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {
@@ -696,6 +730,10 @@ var FIXTURE_DATA = {
   "screen-01b-quote-with-pay-sheet": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00"
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {
@@ -778,45 +816,43 @@ var FIXTURE_DATA = {
     "state": {
       "kind": "KYC",
       "phase": "INPUT_REQUIRED",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
       "form": {
-        "formId": "personal_details",
+        "formId": "kyc_q_8f2_1",
         "fields": [
           {
-            "id": "firstName",
+            "id": "tin",
             "type": "TEXT",
-            "labelFallback": "First name",
-            "required": true
-          },
-          {
-            "id": "dob",
-            "type": "DATE",
-            "labelFallback": "Date of birth",
+            "labelFallback": "Tax ID",
             "required": true
           },
           {
-            "id": "country",
-            "type": "COUNTRY",
-            "labelFallback": "Country",
+            "id": "address",
+            "type": "TEXT",
+            "labelFallback": "Home address",
             "required": true
-          },
-          {
-            "id": "sourceOfFunds",
-            "type": "SELECT",
-            "labelFallback": "Source of funds",
-            "required": true,
-            "options": [
-              {
-                "id": "salary",
-                "labelFallback": "Salary"
-              }
-            ]
-          },
-          {
-            "id": "idProof",
-            "type": "HOSTED_LINK",
-            "labelFallback": "Verify your ID",
-            "required": true,
-            "url": "\u2026"
           }
         ]
       }
@@ -828,7 +864,8 @@ var FIXTURE_DATA = {
         "mode": "SUBMIT",
         "endpoint": "POST /fiat/kyc/form",
         "params": {
-          "formId": "personal_details"
+          "quoteRef": "q_8f2",
+          "formId": "kyc_q_8f2_1"
         },
         "inputs": {
           "values": {
@@ -913,11 +950,84 @@ var FIXTURE_DATA = {
       }
     ]
   },
+  "screen-08-kyc-capture": {
+    "state": {
+      "kind": "KYC",
+      "phase": "CAPTURE",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
+      "surface": {
+        "kind": "KYC_SDK",
+        "provider": "SUMSUB",
+        "params": {
+          "accessToken": "eyJ\u2026"
+        },
+        "expiresAt": "\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "capture",
+        "mode": "CLIENT_SURFACE",
+        "report": {
+          "endpoint": "POST /fiat/kyc/capture",
+          "params": {
+            "quoteRef": "q_8f2"
+          }
+        }
+      }
+    ]
+  },
   "screen-09-kyc-in-review": {
     "state": {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
-      "reason": "IN_REVIEW"
+      "reason": "IN_REVIEW",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      }
     },
     "provider": "TRANSAK",
     "transitions": [
@@ -925,10 +1035,7 @@ var FIXTURE_DATA = {
         "id": "poll",
         "mode": "AWAIT",
         "poll": {
-          "endpoint": "GET /fiat/kyc",
-          "params": {
-            "quoteRef": "q_8f2"
-          },
+          "endpoint": "GET /fiat/quotes/q_8f2",
           "intervalMs": 3e3,
           "backoffFactor": 1.5,
           "maxIntervalMs": 1e4,
@@ -942,28 +1049,70 @@ var FIXTURE_DATA = {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
       "reason": "ON_HOLD",
-      "retryAfter": "2026-08-20T09:00:00Z"
+      "retryAfter": "2026-08-20T09:00:00Z",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      }
     },
     "provider": "TRANSAK",
     "transitions": []
   },
-  "screen-11-kyc-rejected-escalation": {
+  "screen-11-kyc-rejected": {
     "state": {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
-      "reason": "REJECTED"
+      "reason": "REJECTED",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
+      "failureReason": {
+        "category": "KYC_REJECTED",
+        "retryable": false,
+        "recovery": "CONTACT_SUPPORT"
+      }
     },
     "provider": "TRANSAK",
-    "transitions": [
-      {
-        "id": "escalate",
-        "mode": "SUBMIT",
-        "endpoint": "GET /fiat/kyc",
-        "params": {
-          "tier": "escalated"
-        }
-      }
-    ]
+    "transitions": []
   },
   "screen-12-pending-order": {
     "state": {
@@ -1096,6 +1245,10 @@ var FIXTURE_DATA = {
   "worked-example-01-quote": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00"
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {
@@ -1241,8 +1394,8 @@ var FIXTURES = [
   {
     id: "screen-03-kyc-input-required",
     file: "screen-03-kyc-input-required.json",
-    source: "FE_DOC",
-    docRef: "Screen 3 \xB7 Identity form (KYC)",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 L1 input round",
     screen: 3,
     stateKey: "KYC/INPUT_REQUIRED",
     notes: ["Carries the FORM_VALUES input spec \u2014 the no-double-carry case of the accepted split."]
@@ -1270,34 +1423,40 @@ var FIXTURES = [
       "TODO(open-decision): report target per card topology is a Transak ask (contract Flow A)."
     ]
   },
+  {
+    id: "screen-08-kyc-capture",
+    file: "screen-08-kyc-capture.json",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 embedded Sumsub WebSDK",
+    screen: 8,
+    stateKey: "KYC/CAPTURE",
+    notes: ["The client mounts the Sumsub adapter; no URL or iframe is emitted."]
+  },
   {
     id: "screen-09-kyc-in-review",
     file: "screen-09-kyc-in-review.json",
-    source: "FE_DOC",
-    docRef: "Screen 9 \xB7 Verifying identity",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 pending quote",
     screen: 9,
     stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW"
   },
   {
     id: "screen-10-kyc-on-hold",
     file: "screen-10-kyc-on-hold.json",
-    source: "FE_DOC",
-    docRef: "Screen 10 \xB7 Verification on hold",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 verification on hold",
     screen: 10,
     stateKey: "KYC/NO_ACTION_REQUIRED:ON_HOLD",
     notes: ["transitions: [] and NOT terminal \u2014 the fixture that proves terminality is table data."]
   },
   {
-    id: "screen-11-kyc-rejected-escalation",
-    file: "screen-11-kyc-rejected-escalation.json",
-    source: "FE_DOC",
-    docRef: "Screen 11 \xB7 Verification unsuccessful",
+    id: "screen-11-kyc-rejected",
+    file: "screen-11-kyc-rejected.json",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 non-retryable rejection",
     screen: 11,
     stateKey: "KYC/NO_ACTION_REQUIRED:REJECTED",
-    notes: [
-      "TODO(open-decision): the escalation transition is a flagged placeholder \u2014 a GET carrying params is not a real request shape (FE doc Screen 11 + open question 7).",
-      "The terminal REJECTED variant (failureReason + transitions []) is described in prose, not published as JSON \u2014 no fixture."
-    ]
+    notes: ["Only an explicit non-retryable provider or identity-vendor outcome reaches this state."]
   },
   {
     id: "screen-12-pending-order",
@@ -1342,7 +1501,7 @@ var FIXTURES = [
     docRef: "Screen 16 \xB7 Not available",
     screen: 16,
     stateKey: "BLOCKED",
-    notes: ["The only flatly terminal state entry in the table."]
+    notes: ["A flatly terminal availability state; explicit non-retryable KYC rejection is terminal too."]
   },
   {
     id: "worked-example-01-quote",
@@ -1374,10 +1533,6 @@ var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
     reason: "No step response exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
-  },
-  {
-    stateKey: "KYC/CAPTURE",
-    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no step response was ever published. Kind retained as handshake-gated vocabulary."
   }
 ];
 var fixtureMeta = (id) => {
@@ -1536,6 +1691,7 @@ function assertAllFixtures() {
 }
 export {
   AuthChallengeSchema,
+  BlockedReasonSchema,
   BlockedStateSchema,
   COUNTRY_NAMES,
   COUNTRY_TO_CURRENCY,
@@ -1580,6 +1736,7 @@ export {
   PaymentInstructStateSchema,
   PendingOrderStateSchema,
   PollSpecSchema,
+  QuoteLimitsSchema,
   QuoteSchema,
   QuoteStateSchema,
   RecoverySchema,

package/dist/schemas.d.ts

@@ -27,7 +27,7 @@
  * They are module-private, so none of it reaches the published declarations.
  */
 import { z } from 'zod';
-import type { CryptoAmount, FailureReason, FeeLine, FiatEndpoint, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, Instructions, InstructionField, Instrument, JsonValue, FiatAmount, OrderRef, OrderStatus, OrderSummary, PollSpec, FiatProvider, Quote, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, FiatStepResponse, Surface, SurfaceKind, SurfaceProvider, KYCProvider, Transition, TransitionInputs, TransitionParams, Tx } from './types';
+import type { BlockedReason, CryptoAmount, FailureReason, FeeLine, FiatEndpoint, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, Instructions, InstructionField, Instrument, JsonValue, FiatAmount, OrderRef, OrderStatus, OrderSummary, PollSpec, FiatProvider, Quote, QuoteLimits, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, FiatStepResponse, Surface, SurfaceKind, SurfaceProvider, KYCProvider, Transition, TransitionInputs, TransitionParams, Tx } from './types';
 export declare const JsonSchema: z.ZodType<JsonValue>;
 export declare const HTTP_VERBS: readonly ["GET", "POST"];
 /** `"POST /fiat/session/verify"`, `"GET /fiat/orders/o_31c"` — the verb rides the string. */
@@ -43,6 +43,7 @@ export declare const FiatAmountSchema: z.ZodType<FiatAmount>;
 export declare const CryptoAmountSchema: z.ZodType<CryptoAmount>;
 export declare const FeeLineSchema: z.ZodType<FeeLine>;
 export declare const QuoteSchema: z.ZodType<Quote>;
+export declare const QuoteLimitsSchema: z.ZodType<QuoteLimits>;
 export declare const InstrumentSchema: z.ZodType<Instrument>;
 export declare const OrderRefSchema: z.ZodType<OrderRef>;
 export declare const OrderSummarySchema: z.ZodType<OrderSummary>;
@@ -84,6 +85,7 @@ export declare const KycCaptureStateSchema: z.ZodType<State<'KYC', 'CAPTURE'>>;
 export declare const KycInputRequiredStateSchema: z.ZodType<State<'KYC', 'INPUT_REQUIRED'>>;
 export declare const KycNoActionRequiredStateSchema: z.ZodType<State<'KYC', 'NO_ACTION_REQUIRED'>>;
 export declare const PendingOrderStateSchema: z.ZodType<State<'PENDING_ORDER'>>;
+export declare const BlockedReasonSchema: z.ZodType<BlockedReason>;
 export declare const BlockedStateSchema: z.ZodType<State<'BLOCKED'>>;
 export declare const PaymentCaptureStateSchema: z.ZodType<State<'PAYMENT', 'CAPTURE'>>;
 export declare const PaymentInstructStateSchema: z.ZodType<State<'PAYMENT', 'INSTRUCT'>>;

package/dist/table.d.ts

@@ -42,8 +42,7 @@ export type StateKey = 'QUOTE' | 'FUN_AUTH' | 'SESSION_AUTH' | 'KYC/CAPTURE' | '
 export declare const TERMINAL_ORDER_STATUSES: readonly ["SETTLED", "EXPIRED", "CANCELLED", "FAILED", "REFUNDED"];
 export type TerminalOrderStatus = (typeof TERMINAL_ORDER_STATUSES)[number];
 /**
- * Endpoint template as written in the docs — `:id` stands for an order id, so
- * `"POST /fiat/orders/:id/cancel"` matches the emitted `"POST /fiat/orders/o_31c/cancel"`.
+ * Endpoint template as written in the docs. Named `:` segments match one emitted path segment.
  */
 export type EndpointTemplate = FiatEndpoint;
 export interface AllowedTransition {
@@ -91,7 +90,7 @@ export declare const STATE_KEYS: StateKey[];
  * named by the table (QUOTE's capture-first entry) while the doc's endpoint table still lists no
  * session-minting call for that rail.
  */
-export declare const DOCUMENTED_ENDPOINTS: readonly ["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/:id", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
+export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/payment-session", "POST /fiat/session", "POST /fiat/session/verify", "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", "GET /fiat/orders/:id", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
 /**
  * Documented endpoints no flow state offers, and why. Declared so an endpoint nothing can reach is
  * visible instead of silent — the table test asserts the unoffered set equals exactly these.