@fun-xyz/fiat-contract 0.7.0 → 0.8.0

package/dist/index.js

@@ -387,7 +387,7 @@ var HTTP_VERBS = ["GET", "POST"];
 var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
 var $endpoint = import_zod.z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
 var FiatEndpointSchema = $endpoint;
-var $provider = import_zod.z.enum(["TRANSAK", "SWAPPED", "BANXA"]);
+var $provider = import_zod.z.enum(["TRANSAK", "SWAPPED", "BANXA", "MOONPAY", "STRIPE"]);
 var FiatProviderSchema = $provider;
 var $kycProvider = import_zod.z.enum(["SUMSUB"]);
 var KYCProviderSchema = $kycProvider;
@@ -484,7 +484,7 @@ var $refund = obj({
   expectedBy: import_zod.z.string()
 });
 var RefundSchema = $refund;
-var $surfaceKind = import_zod.z.enum(["URL_REDIRECT", "URL_EMBED", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]);
+var $surfaceKind = import_zod.z.enum(["URL_REDIRECT", "KYC_SDK", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]);
 var SurfaceKindSchema = $surfaceKind;
 var $surface = obj({
   kind: $surfaceKind,
@@ -649,6 +649,7 @@ var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("CAPTURE"),
+  quote: $quote,
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -656,6 +657,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("INPUT_REQUIRED"),
+  quote: $quote,
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -663,6 +665,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("NO_ACTION_REQUIRED"),
+  quote: $quote,
   reason: import_zod.z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: import_zod.z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -740,7 +743,7 @@ var $stepResponse = obj({
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.7.0";
+var version = "0.8.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -866,21 +869,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",
@@ -892,16 +897,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."
     ]
   },
@@ -912,12 +921,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,
@@ -947,20 +960,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: {
@@ -1122,8 +1126,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",
@@ -1135,13 +1141,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",
@@ -1349,45 +1359,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",
+            "labelFallback": "Tax ID",
             "required": true
           },
           {
-            "id": "dob",
-            "type": "DATE",
-            "labelFallback": "Date of birth",
-            "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"
           }
         ]
       }
@@ -1399,7 +1407,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": {
@@ -1484,11 +1493,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": [
@@ -1496,10 +1578,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,
@@ -1513,28 +1592,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": {
@@ -1812,8 +1933,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."]
@@ -1841,34 +1962,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",
@@ -1913,7 +2040,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",
@@ -1945,10 +2072,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) => {