@fun-xyz/fiat-contract 0.9.0 → 0.11.0

package/README.md

@@ -59,10 +59,51 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
 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.
-7. **Quote-screen bounds are explicit exact-money strings.** `QUOTE.limits` carries the minimum and
-   current routing maximum; clients do not infer either from provider metadata or floating point.
+7. **Quote-screen bounds are explicit exact-money strings.** `QUOTE.limits` carries the bounding
+   minimum/maximum plus the exact `serviceableRanges` when a routing set has gaps; clients do not
+   infer capacity from provider metadata or floating point.
 8. **Provider auth is capability-shaped.** SMS uses `SMS_OTP`; provider-owned auth uses
    `PROVIDER_RENDERED` with an optional `AUTH_COMPONENT` surface rather than provider-specific channels.
+9. **KYC SDK refresh is a transition.** `KYC{CAPTURE}` may offer `refresh_sdk_token` to
+   `POST /fiat/kyc/sdk-token`; a transition-following client does not invent an auxiliary endpoint call.
+10. **SDK launch is not eligibility authority.** A `KYC_SDK_RESULT` report injects either
+    `{outcome: 'COMPLETED'}` or `{outcome: 'FAILED', errorType}`. `errorType` is opaque, and raw
+    messages/errors are excluded. The backend must still read the provider's authoritative state.
+11. **Client-executed delivery is current-session-only.** A provider-owned surface may declare a
+    `CLIENT_EXECUTED` delivery with `source: 'CURRENT_SESSION_INPUTS'` and a value-free `allowedFieldIds`
+    allowlist. The delivery shape cannot request or contain backend-stored KYC values.
+12. **Capability skew is explicit.** `BLOCKED{reason: 'CLIENT_UPGRADE_REQUIRED'}` means every
+    otherwise-viable route needs a client capability absent from the handshake. It is not a provider
+    decline and should render an upgrade path rather than generic retry copy.
+13. **Providerless is terminal-routing-only.** `FiatStepResponse.provider` may be absent only for
+    `BLOCKED`, including `ALL_PROVIDERS_DECLINED` when routing selected no provider. Every other state
+    remains provider-bound and requires `provider`; provider-specific blocked responses may keep it.
+
+## KYC SDK hints, results, and client delivery
+
+`KYC_SDK` is a dedicated `Surface` union member. Its optional
+`preferredDocuments.IDENTITY` contains the exact adapter input needed to bias document capture:
+the identity-vendor `idDocType` plus its ISO alpha-3 `country`. The hint changes presentation only;
+it does not establish that the document is accepted or available.
+
+When `report.result` is `{type: 'KYC_SDK_RESULT', bodyKey: 'result'}`, the harness injects a
+`KycSdkResultReport` under that body key. Completion means the SDK launch completed, not that KYC passed.
+Failure exposes only the provider's opaque `errorType` (for example `Unauthorized`), never a raw
+error object or message.
+
+`surface.delivery` describes a client-side forwarding boundary on a provider-owned surface, not
+transport mechanics. The selected provider adapter may forward only the declared `allowedFieldIds` that the user entered during the
+current mounted session. The schema fixes the source to `CURRENT_SESSION_INPUTS`, requires a unique
+non-empty field allowlist, and contains no values. Provider-specific submission mechanics remain
+adapter-owned and are intentionally unresolved by this provider-neutral contract.
+
+“Declarative KYC collection” means the backend sends a `FormDescriptor` listing canonical field
+IDs, input kinds, labels, validation, and select options. The frontend renders that description,
+collects values, and submits them through the transition's single `FORM_VALUES` input; it does not
+hard-code a separate screen or endpoint for source of funds, occupation, purpose, nationality,
+country of birth, employment status, or phone. Field IDs and type-specific properties are closed
+unions, so misspelled IDs and impossible combinations such as `options` on a `TEXT` field fail
+validation.
 
 ## Versioning — the package version IS the table version
 
@@ -449,7 +490,7 @@ 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, 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`. |
+| Pre-order KYC sequencing | KYC states carry their quote; SDK submission reports to `POST /fiat/kyc/capture`; expired SDK credentials refresh through the explicit `POST /fiat/kyc/sdk-token` transition; 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. |

package/dist/{chunk-5QGVY5Z4.mjs → chunk-GKKBF7QB.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.9.0";
+var version = "0.11.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -114,7 +114,8 @@ var TRANSITION_TABLE = {
     terminal: false,
     notes: [
       "A bad code re-enters this same state with error {category: USER_ERROR, code: BAD_CODE} \u2014 banner, not a screen change.",
-      "No resend affordance is specified in either doc (known gap, FE doc Screen 2)."
+      "No resend affordance is specified in either doc (known gap, FE doc Screen 2).",
+      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only."
     ]
   },
   "KYC/CAPTURE": {
@@ -124,6 +125,12 @@ var TRANSITION_TABLE = {
     screens: [8],
     docStatus: "SPECIFIED",
     allowedTransitions: [
+      {
+        id: "refresh_sdk_token",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/kyc/sdk-token",
+        note: "Refreshes an expired SDK credential and returns a new KYC/CAPTURE state."
+      },
       {
         id: "capture",
         mode: "CLIENT_SURFACE",
@@ -143,7 +150,10 @@ var TRANSITION_TABLE = {
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
-    notes: ["Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter."]
+    notes: [
+      "Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter.",
+      "SDK completion or failure is only a launch report; eligibility is re-read authoritatively by the backend."
+    ]
   },
   "KYC/INPUT_REQUIRED": {
     key: "KYC/INPUT_REQUIRED",
@@ -399,10 +409,6 @@ 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."
@@ -500,4 +506,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-5QGVY5Z4.mjs.map
+//# sourceMappingURL=chunk-GKKBF7QB.mjs.map

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   BlockedStateSchema: () => BlockedStateSchema,
   COUNTRY_NAMES: () => COUNTRY_NAMES,
   COUNTRY_TO_CURRENCY: () => COUNTRY_TO_CURRENCY,
+  ClientExecutedDeliverySchema: () => ClientExecutedDeliverySchema,
   ContractViolation: () => ContractViolation,
   CountryCode: () => CountryCode,
   CryptoAmountSchema: () => CryptoAmountSchema,
@@ -53,9 +54,11 @@ __export(index_exports, {
   InstrumentSchema: () => InstrumentSchema,
   JsonSchema: () => JsonSchema,
   KYCProviderSchema: () => KYCProviderSchema,
+  KYC_ACKNOWLEDGEMENT_FIELD_IDS: () => KYC_ACKNOWLEDGEMENT_FIELD_IDS,
   KycCaptureStateSchema: () => KycCaptureStateSchema,
   KycInputRequiredStateSchema: () => KycInputRequiredStateSchema,
   KycNoActionRequiredStateSchema: () => KycNoActionRequiredStateSchema,
+  KycSdkResultReportSchema: () => KycSdkResultReportSchema,
   OrderAwaitingConfirmationStateSchema: () => OrderAwaitingConfirmationStateSchema,
   OrderCreatedStateSchema: () => OrderCreatedStateSchema,
   OrderRefSchema: () => OrderRefSchema,
@@ -66,12 +69,15 @@ __export(index_exports, {
   PaymentInstructStateSchema: () => PaymentInstructStateSchema,
   PendingOrderStateSchema: () => PendingOrderStateSchema,
   PollSpecSchema: () => PollSpecSchema,
+  PreferredIdentityDocumentSchema: () => PreferredIdentityDocumentSchema,
+  QuoteLimitRangeSchema: () => QuoteLimitRangeSchema,
   QuoteLimitsSchema: () => QuoteLimitsSchema,
   QuoteSchema: () => QuoteSchema,
   QuoteStateSchema: () => QuoteStateSchema,
   RecoverySchema: () => RecoverySchema,
   RefundSchema: () => RefundSchema,
   ReportSpecSchema: () => ReportSpecSchema,
+  STANDARD_KYC_FIELD_IDS: () => STANDARD_KYC_FIELD_IDS,
   STATE_KEYS: () => STATE_KEYS,
   SelectOptionSchema: () => SelectOptionSchema,
   SessionAuthStateSchema: () => SessionAuthStateSchema,
@@ -82,6 +88,7 @@ __export(index_exports, {
   TABLE_VERSION: () => TABLE_VERSION,
   TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE: () => TRANSITION_TABLE,
+  TermsAcceptanceSchema: () => TermsAcceptanceSchema,
   TransitionInputsSchema: () => TransitionInputsSchema,
   TransitionParamsSchema: () => TransitionParamsSchema,
   TransitionSchema: () => TransitionSchema,
@@ -464,7 +471,13 @@ var $quote = obj({
   expiresAt: import_zod.z.string()
 });
 var QuoteSchema = $quote;
-var $quoteLimits = obj({ min: import_zod.z.string(), max: import_zod.z.string() });
+var $quoteLimitRange = obj({ min: import_zod.z.string(), max: import_zod.z.string() });
+var QuoteLimitRangeSchema = $quoteLimitRange;
+var $quoteLimits = obj({
+  min: import_zod.z.string(),
+  max: import_zod.z.string(),
+  serviceableRanges: import_zod.z.array($quoteLimitRange).min(1).optional()
+});
 var QuoteLimitsSchema = $quoteLimits;
 var $instrument = obj({ brandLabel: import_zod.z.string(), last4: import_zod.z.string() });
 var InstrumentSchema = $instrument;
@@ -505,8 +518,7 @@ var $surfaceKind = import_zod.z.enum([
   "AUTH_COMPONENT"
 ]);
 var SurfaceKindSchema = $surfaceKind;
-var $surface = obj({
-  kind: $surfaceKind,
+var $surfaceBase = {
   provider: $surfaceProvider,
   /**
    * The one deliberate non-strict leaf in the contract. Provider inputs are the adapter's
@@ -518,7 +530,84 @@ var $surface = obj({
    */
   params: import_zod.z.record(import_zod.z.string(), JsonSchema),
   expiresAt: import_zod.z.string().optional()
+};
+var $preferredIdentityDocument = obj({
+  idDocType: import_zod.z.enum(["PASSPORT", "ID_CARD", "DRIVERS", "RESIDENCE_PERMIT", "VISA"]),
+  country: import_zod.z.string().regex(/^[A-Z]{3}$/)
 });
+var PreferredIdentityDocumentSchema = $preferredIdentityDocument;
+var STANDARD_KYC_FIELD_IDS = [
+  "LEGAL_FIRST_NAME",
+  "LEGAL_MIDDLE_NAME",
+  "LEGAL_LAST_NAME",
+  "DATE_OF_BIRTH",
+  "COUNTRY_OF_BIRTH",
+  "CITY_OF_BIRTH",
+  "NATIONALITY",
+  "EMAIL_ADDRESS",
+  "EMAIL_OWNERSHIP_VERIFICATION",
+  "PHONE_NUMBER",
+  "PHONE_OWNERSHIP_VERIFICATION",
+  "RESIDENTIAL_ADDRESS_LINE_1",
+  "RESIDENTIAL_ADDRESS_LINE_2",
+  "RESIDENTIAL_ADDRESS_CITY",
+  "RESIDENTIAL_ADDRESS_REGION",
+  "RESIDENTIAL_ADDRESS_POSTAL_CODE",
+  "RESIDENTIAL_ADDRESS_COUNTRY",
+  "TAX_IDENTIFIER",
+  "TAX_RESIDENCE_COUNTRY",
+  "EMPLOYMENT_STATUS",
+  "OCCUPATION_INDUSTRY",
+  "OCCUPATION_TITLE",
+  "SOURCE_OF_FUNDS_DECLARATION",
+  "SOURCE_OF_INCOME_DECLARATION",
+  "SOURCE_OF_WEALTH_DECLARATION",
+  "PURPOSE_OF_SERVICE",
+  "PURPOSE_OF_TRANSACTION",
+  "CUSTOMER_CATEGORY"
+];
+var KYC_ACKNOWLEDGEMENT_FIELD_IDS = [
+  "RISK_ACKNOWLEDGEMENT",
+  "COOLING_OFF_ACKNOWLEDGEMENT",
+  "TERMS_ACCEPTANCE"
+];
+var $questionnaireKycFieldId = import_zod.z.custom(
+  (value) => typeof value === "string" && /^QUESTIONNAIRE_RESPONSE:[^:]+:[^:]+$/.test(value),
+  "Questionnaire field ids must identify exactly one policy and question"
+);
+var $kycFieldId = import_zod.z.union([
+  import_zod.z.enum(STANDARD_KYC_FIELD_IDS),
+  import_zod.z.enum(KYC_ACKNOWLEDGEMENT_FIELD_IDS),
+  $questionnaireKycFieldId
+]);
+var $clientExecutedDelivery = obj({
+  channel: import_zod.z.literal("CLIENT_EXECUTED"),
+  source: import_zod.z.literal("CURRENT_SESSION_INPUTS"),
+  allowedFieldIds: import_zod.z.array($kycFieldId).min(1)
+}).superRefine((delivery, context) => {
+  if (new Set(delivery.allowedFieldIds).size !== delivery.allowedFieldIds.length) {
+    context.addIssue({
+      code: "custom",
+      path: ["allowedFieldIds"],
+      message: "allowedFieldIds must be unique"
+    });
+  }
+});
+var ClientExecutedDeliverySchema = $clientExecutedDelivery;
+var $surface = import_zod.z.union([
+  obj({
+    ...$surfaceBase,
+    kind: import_zod.z.literal("KYC_SDK"),
+    provider: $kycProvider,
+    preferredDocuments: obj({ IDENTITY: $preferredIdentityDocument }).optional()
+  }),
+  obj({
+    ...$surfaceBase,
+    kind: import_zod.z.enum(["URL_REDIRECT", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT", "AUTH_COMPONENT"]),
+    provider: $provider,
+    delivery: $clientExecutedDelivery.optional()
+  })
+]);
 var SurfaceSchema = $surface;
 var $instructionField = obj({
   id: import_zod.z.string(),
@@ -541,15 +630,15 @@ var $selectOption = obj({ id: import_zod.z.string(), labelFallback: import_zod.z
 var SelectOptionSchema = $selectOption;
 var $formFieldType = import_zod.z.enum(["TEXT", "DATE", "SELECT", "COUNTRY", "FILE", "HOSTED_LINK"]);
 var FormFieldTypeSchema = $formFieldType;
-var $formField = obj({
-  id: import_zod.z.string(),
-  type: $formFieldType,
-  labelFallback: import_zod.z.string(),
-  required: import_zod.z.boolean(),
-  regex: import_zod.z.string().optional(),
-  options: import_zod.z.array($selectOption).optional(),
-  url: import_zod.z.string().optional()
-});
+var $formFieldBase = { id: $kycFieldId, labelFallback: import_zod.z.string(), required: import_zod.z.boolean() };
+var $formField = import_zod.z.union([
+  obj({ ...$formFieldBase, type: import_zod.z.literal("TEXT"), regex: import_zod.z.string().optional() }),
+  obj({ ...$formFieldBase, type: import_zod.z.literal("DATE") }),
+  obj({ ...$formFieldBase, type: import_zod.z.literal("SELECT"), options: import_zod.z.array($selectOption) }),
+  obj({ ...$formFieldBase, type: import_zod.z.literal("COUNTRY") }),
+  obj({ ...$formFieldBase, type: import_zod.z.literal("FILE") }),
+  obj({ ...$formFieldBase, type: import_zod.z.literal("HOSTED_LINK"), url: import_zod.z.string() })
+]);
 var FormFieldSchema = $formField;
 var $formDescriptor = obj({ formId: import_zod.z.string(), fields: import_zod.z.array($formField) });
 var FormDescriptorSchema = $formDescriptor;
@@ -560,7 +649,8 @@ var FIELD_SPEC_TYPES = [
   "FILE",
   "SELECT",
   "HOSTED_LINK",
-  "FORM_VALUES"
+  "FORM_VALUES",
+  "TERMS_ACCEPTANCE"
 ];
 var $fieldSpec = import_zod.z.union([
   obj({
@@ -578,9 +668,19 @@ var $fieldSpec = import_zod.z.union([
     labelFallback: import_zod.z.string().optional()
   }),
   obj({ type: import_zod.z.literal("HOSTED_LINK"), url: import_zod.z.string(), labelFallback: import_zod.z.string().optional() }),
-  obj({ type: import_zod.z.literal("FORM_VALUES") })
+  obj({ type: import_zod.z.literal("FORM_VALUES") }),
+  obj({
+    type: import_zod.z.literal("TERMS_ACCEPTANCE"),
+    documentUrl: import_zod.z.string(),
+    version: import_zod.z.string(),
+    labelFallback: import_zod.z.string().optional()
+  })
 ]);
 var FieldSpecSchema = $fieldSpec;
+var TermsAcceptanceSchema = obj({
+  version: import_zod.z.string(),
+  acceptedAt: import_zod.z.string()
+});
 var looksLikeFieldSpec = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.type === "string" && FIELD_SPEC_TYPES.includes(value.type);
 var $params = import_zod.z.record(import_zod.z.string(), JsonSchema).superRefine((params, ctx) => {
   for (const [key, value] of Object.entries(params)) {
@@ -627,9 +727,15 @@ var PollSpecSchema = $pollSpec;
 var $reportSpec = obj({
   endpoint: $endpoint,
   params: $params.optional(),
-  expects: import_zod.z.array(import_zod.z.string()).optional()
+  expects: import_zod.z.array(import_zod.z.string()).optional(),
+  result: obj({ type: import_zod.z.literal("KYC_SDK_RESULT"), bodyKey: import_zod.z.string().trim().min(1) }).optional()
 });
 var ReportSpecSchema = $reportSpec;
+var $kycSdkResult = import_zod.z.union([
+  obj({ outcome: import_zod.z.literal("COMPLETED") }),
+  obj({ outcome: import_zod.z.literal("FAILED"), errorType: import_zod.z.string().trim().min(1) })
+]);
+var KycSdkResultReportSchema = $kycSdkResult;
 var $transition = import_zod.z.union([
   obj({
     id: import_zod.z.string(),
@@ -704,7 +810,8 @@ var $blockedReason = import_zod.z.enum([
   "REGION_UNSUPPORTED",
   "ASSET_UNSUPPORTED",
   "ALL_PROVIDERS_DECLINED",
-  "AMOUNT_UNSERVABLE"
+  "AMOUNT_UNSERVABLE",
+  "CLIENT_UPGRADE_REQUIRED"
 ]);
 var BlockedReasonSchema = $blockedReason;
 var $blockedState = obj({
@@ -748,7 +855,7 @@ var $orderCreatedState = obj({
   error: $failureReason.optional()
 });
 var OrderCreatedStateSchema = $orderCreatedState;
-var $flowState = import_zod.z.union([
+var $providerBoundFlowState = import_zod.z.union([
   $quoteState,
   $funAuthState,
   $sessionAuthState,
@@ -756,23 +863,30 @@ var $flowState = import_zod.z.union([
   $kycInputRequiredState,
   $kycNoActionRequiredState,
   $pendingOrderState,
-  $blockedState,
   $paymentCaptureState,
   $paymentInstructState,
   $orderAwaitingConfirmationState,
   $orderCreatedState
 ]);
+var $flowState = import_zod.z.union([$providerBoundFlowState, $blockedState]);
 var FlowStateSchema = $flowState;
-var $stepResponse = obj({
-  state: $flowState,
+var $providerBoundStepResponse = obj({
+  state: $providerBoundFlowState,
   provider: $provider,
   transitions: import_zod.z.array($transition),
   orderId: import_zod.z.string().optional()
 });
+var $blockedStepResponse = obj({
+  state: $blockedState,
+  provider: $provider.optional(),
+  transitions: import_zod.z.array($transition),
+  orderId: import_zod.z.string().optional()
+});
+var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStepResponse]);
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.9.0";
+var version = "0.11.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -887,7 +1001,8 @@ var TRANSITION_TABLE = {
     terminal: false,
     notes: [
       "A bad code re-enters this same state with error {category: USER_ERROR, code: BAD_CODE} \u2014 banner, not a screen change.",
-      "No resend affordance is specified in either doc (known gap, FE doc Screen 2)."
+      "No resend affordance is specified in either doc (known gap, FE doc Screen 2).",
+      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only."
     ]
   },
   "KYC/CAPTURE": {
@@ -897,6 +1012,12 @@ var TRANSITION_TABLE = {
     screens: [8],
     docStatus: "SPECIFIED",
     allowedTransitions: [
+      {
+        id: "refresh_sdk_token",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/kyc/sdk-token",
+        note: "Refreshes an expired SDK credential and returns a new KYC/CAPTURE state."
+      },
       {
         id: "capture",
         mode: "CLIENT_SURFACE",
@@ -916,7 +1037,10 @@ var TRANSITION_TABLE = {
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
-    notes: ["Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter."]
+    notes: [
+      "Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter.",
+      "SDK completion or failure is only a launch report; eligibility is re-read authoritatively by the backend."
+    ]
   },
   "KYC/INPUT_REQUIRED": {
     key: "KYC/INPUT_REQUIRED",
@@ -1172,10 +1296,6 @@ 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."
@@ -1266,7 +1386,17 @@ var FIXTURE_DATA = {
       "kind": "QUOTE",
       "limits": {
         "min": "1.00",
-        "max": "3000.00"
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "500.00"
+          },
+          {
+            "min": "1000.00",
+            "max": "3000.00"
+          }
+        ]
       },
       "quote": {
         "quoteRef": "q_8f2",
@@ -1314,7 +1444,13 @@ var FIXTURE_DATA = {
       "kind": "QUOTE",
       "limits": {
         "min": "1.00",
-        "max": "3000.00"
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "3000.00"
+          }
+        ]
       },
       "quote": {
         "quoteRef": "q_8f2",
@@ -1425,13 +1561,13 @@ var FIXTURE_DATA = {
         "formId": "kyc_q_8f2_1",
         "fields": [
           {
-            "id": "tin",
+            "id": "TAX_IDENTIFIER",
             "type": "TEXT",
             "labelFallback": "Tax ID",
             "required": true
           },
           {
-            "id": "address",
+            "id": "RESIDENTIAL_ADDRESS_LINE_1",
             "type": "TEXT",
             "labelFallback": "Home address",
             "required": true
@@ -1565,11 +1701,26 @@ var FIXTURE_DATA = {
         "params": {
           "accessToken": "eyJ\u2026"
         },
+        "preferredDocuments": {
+          "IDENTITY": {
+            "idDocType": "PASSPORT",
+            "country": "GBR"
+          }
+        },
         "expiresAt": "\u2026"
       }
     },
     "provider": "TRANSAK",
     "transitions": [
+      {
+        "id": "refresh_sdk_token",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/kyc/sdk-token",
+        "params": {
+          "quoteRef": "q_8f2"
+        },
+        "labelFallback": "Retry verification"
+      },
       {
         "id": "capture",
         "mode": "CLIENT_SURFACE",
@@ -1577,6 +1728,10 @@ var FIXTURE_DATA = {
           "endpoint": "POST /fiat/kyc/capture",
           "params": {
             "quoteRef": "q_8f2"
+          },
+          "result": {
+            "type": "KYC_SDK_RESULT",
+            "bodyKey": "result"
           }
         }
       }
@@ -1821,7 +1976,6 @@ var FIXTURE_DATA = {
       "reason": "REGION_UNSUPPORTED",
       "retryAfter": null
     },
-    "provider": "TRANSAK",
     "transitions": []
   },
   "worked-example-01-quote": {
@@ -1829,7 +1983,13 @@ var FIXTURE_DATA = {
       "kind": "QUOTE",
       "limits": {
         "min": "1.00",
-        "max": "3000.00"
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "3000.00"
+          }
+        ]
       },
       "quote": {
         "quoteRef": "q_8f2",
@@ -2193,6 +2353,9 @@ function bodyKeyIssues(transition) {
   if (transition.mode === "CLIENT_SURFACE") {
     const params = Object.keys(transition.report.params ?? {});
     collide(params, transition.report.expects ?? [], "report.params", "report.expects");
+    const resultKeys = transition.report.result ? [transition.report.result.bodyKey] : [];
+    collide(params, resultKeys, "report.params", "report.result");
+    collide(transition.report.expects ?? [], resultKeys, "report.expects", "report.result");
   }
   return issues;
 }
@@ -2221,6 +2384,11 @@ function checkLegalEmission(state, transitions) {
         `transition "${transition.id}": CLIENT_SURFACE requires the Surface in state (\u03942 single-carry) \u2014 ${entry.key} carries none`
       );
     }
+    if (transition.mode === "CLIENT_SURFACE" && transition.report.result?.type === "KYC_SDK_RESULT" && (!("surface" in state) || state.surface?.kind !== "KYC_SDK")) {
+      issues.push(
+        `transition "${transition.id}": KYC_SDK_RESULT requires a KYC_SDK surface in state`
+      );
+    }
     if (transition.mode === "SUBMIT" && Object.values(transition.inputs ?? {}).some((spec) => spec.type === "FORM_VALUES") && !("form" in state)) {
       issues.push(
         `transition "${transition.id}": inputs {type: FORM_VALUES} collects state.form \u2014 ${entry.key} carries no form`

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-5QGVY5Z4.mjs";
+} from "./chunk-GKKBF7QB.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -370,7 +370,13 @@ var $quote = obj({
   expiresAt: z.string()
 });
 var QuoteSchema = $quote;
-var $quoteLimits = obj({ min: z.string(), max: z.string() });
+var $quoteLimitRange = obj({ min: z.string(), max: z.string() });
+var QuoteLimitRangeSchema = $quoteLimitRange;
+var $quoteLimits = obj({
+  min: z.string(),
+  max: z.string(),
+  serviceableRanges: z.array($quoteLimitRange).min(1).optional()
+});
 var QuoteLimitsSchema = $quoteLimits;
 var $instrument = obj({ brandLabel: z.string(), last4: z.string() });
 var InstrumentSchema = $instrument;
@@ -411,8 +417,7 @@ var $surfaceKind = z.enum([
   "AUTH_COMPONENT"
 ]);
 var SurfaceKindSchema = $surfaceKind;
-var $surface = obj({
-  kind: $surfaceKind,
+var $surfaceBase = {
   provider: $surfaceProvider,
   /**
    * The one deliberate non-strict leaf in the contract. Provider inputs are the adapter's
@@ -424,7 +429,84 @@ var $surface = obj({
    */
   params: z.record(z.string(), JsonSchema),
   expiresAt: z.string().optional()
+};
+var $preferredIdentityDocument = obj({
+  idDocType: z.enum(["PASSPORT", "ID_CARD", "DRIVERS", "RESIDENCE_PERMIT", "VISA"]),
+  country: z.string().regex(/^[A-Z]{3}$/)
 });
+var PreferredIdentityDocumentSchema = $preferredIdentityDocument;
+var STANDARD_KYC_FIELD_IDS = [
+  "LEGAL_FIRST_NAME",
+  "LEGAL_MIDDLE_NAME",
+  "LEGAL_LAST_NAME",
+  "DATE_OF_BIRTH",
+  "COUNTRY_OF_BIRTH",
+  "CITY_OF_BIRTH",
+  "NATIONALITY",
+  "EMAIL_ADDRESS",
+  "EMAIL_OWNERSHIP_VERIFICATION",
+  "PHONE_NUMBER",
+  "PHONE_OWNERSHIP_VERIFICATION",
+  "RESIDENTIAL_ADDRESS_LINE_1",
+  "RESIDENTIAL_ADDRESS_LINE_2",
+  "RESIDENTIAL_ADDRESS_CITY",
+  "RESIDENTIAL_ADDRESS_REGION",
+  "RESIDENTIAL_ADDRESS_POSTAL_CODE",
+  "RESIDENTIAL_ADDRESS_COUNTRY",
+  "TAX_IDENTIFIER",
+  "TAX_RESIDENCE_COUNTRY",
+  "EMPLOYMENT_STATUS",
+  "OCCUPATION_INDUSTRY",
+  "OCCUPATION_TITLE",
+  "SOURCE_OF_FUNDS_DECLARATION",
+  "SOURCE_OF_INCOME_DECLARATION",
+  "SOURCE_OF_WEALTH_DECLARATION",
+  "PURPOSE_OF_SERVICE",
+  "PURPOSE_OF_TRANSACTION",
+  "CUSTOMER_CATEGORY"
+];
+var KYC_ACKNOWLEDGEMENT_FIELD_IDS = [
+  "RISK_ACKNOWLEDGEMENT",
+  "COOLING_OFF_ACKNOWLEDGEMENT",
+  "TERMS_ACCEPTANCE"
+];
+var $questionnaireKycFieldId = z.custom(
+  (value) => typeof value === "string" && /^QUESTIONNAIRE_RESPONSE:[^:]+:[^:]+$/.test(value),
+  "Questionnaire field ids must identify exactly one policy and question"
+);
+var $kycFieldId = z.union([
+  z.enum(STANDARD_KYC_FIELD_IDS),
+  z.enum(KYC_ACKNOWLEDGEMENT_FIELD_IDS),
+  $questionnaireKycFieldId
+]);
+var $clientExecutedDelivery = obj({
+  channel: z.literal("CLIENT_EXECUTED"),
+  source: z.literal("CURRENT_SESSION_INPUTS"),
+  allowedFieldIds: z.array($kycFieldId).min(1)
+}).superRefine((delivery, context) => {
+  if (new Set(delivery.allowedFieldIds).size !== delivery.allowedFieldIds.length) {
+    context.addIssue({
+      code: "custom",
+      path: ["allowedFieldIds"],
+      message: "allowedFieldIds must be unique"
+    });
+  }
+});
+var ClientExecutedDeliverySchema = $clientExecutedDelivery;
+var $surface = z.union([
+  obj({
+    ...$surfaceBase,
+    kind: z.literal("KYC_SDK"),
+    provider: $kycProvider,
+    preferredDocuments: obj({ IDENTITY: $preferredIdentityDocument }).optional()
+  }),
+  obj({
+    ...$surfaceBase,
+    kind: z.enum(["URL_REDIRECT", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT", "AUTH_COMPONENT"]),
+    provider: $provider,
+    delivery: $clientExecutedDelivery.optional()
+  })
+]);
 var SurfaceSchema = $surface;
 var $instructionField = obj({
   id: z.string(),
@@ -447,15 +529,15 @@ var $selectOption = obj({ id: z.string(), labelFallback: z.string() });
 var SelectOptionSchema = $selectOption;
 var $formFieldType = z.enum(["TEXT", "DATE", "SELECT", "COUNTRY", "FILE", "HOSTED_LINK"]);
 var FormFieldTypeSchema = $formFieldType;
-var $formField = obj({
-  id: z.string(),
-  type: $formFieldType,
-  labelFallback: z.string(),
-  required: z.boolean(),
-  regex: z.string().optional(),
-  options: z.array($selectOption).optional(),
-  url: z.string().optional()
-});
+var $formFieldBase = { id: $kycFieldId, labelFallback: z.string(), required: z.boolean() };
+var $formField = z.union([
+  obj({ ...$formFieldBase, type: z.literal("TEXT"), regex: z.string().optional() }),
+  obj({ ...$formFieldBase, type: z.literal("DATE") }),
+  obj({ ...$formFieldBase, type: z.literal("SELECT"), options: z.array($selectOption) }),
+  obj({ ...$formFieldBase, type: z.literal("COUNTRY") }),
+  obj({ ...$formFieldBase, type: z.literal("FILE") }),
+  obj({ ...$formFieldBase, type: z.literal("HOSTED_LINK"), url: z.string() })
+]);
 var FormFieldSchema = $formField;
 var $formDescriptor = obj({ formId: z.string(), fields: z.array($formField) });
 var FormDescriptorSchema = $formDescriptor;
@@ -466,7 +548,8 @@ var FIELD_SPEC_TYPES = [
   "FILE",
   "SELECT",
   "HOSTED_LINK",
-  "FORM_VALUES"
+  "FORM_VALUES",
+  "TERMS_ACCEPTANCE"
 ];
 var $fieldSpec = z.union([
   obj({
@@ -484,9 +567,19 @@ var $fieldSpec = z.union([
     labelFallback: z.string().optional()
   }),
   obj({ type: z.literal("HOSTED_LINK"), url: z.string(), labelFallback: z.string().optional() }),
-  obj({ type: z.literal("FORM_VALUES") })
+  obj({ type: z.literal("FORM_VALUES") }),
+  obj({
+    type: z.literal("TERMS_ACCEPTANCE"),
+    documentUrl: z.string(),
+    version: z.string(),
+    labelFallback: z.string().optional()
+  })
 ]);
 var FieldSpecSchema = $fieldSpec;
+var TermsAcceptanceSchema = obj({
+  version: z.string(),
+  acceptedAt: z.string()
+});
 var looksLikeFieldSpec = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.type === "string" && FIELD_SPEC_TYPES.includes(value.type);
 var $params = z.record(z.string(), JsonSchema).superRefine((params, ctx) => {
   for (const [key, value] of Object.entries(params)) {
@@ -533,9 +626,15 @@ var PollSpecSchema = $pollSpec;
 var $reportSpec = obj({
   endpoint: $endpoint,
   params: $params.optional(),
-  expects: z.array(z.string()).optional()
+  expects: z.array(z.string()).optional(),
+  result: obj({ type: z.literal("KYC_SDK_RESULT"), bodyKey: z.string().trim().min(1) }).optional()
 });
 var ReportSpecSchema = $reportSpec;
+var $kycSdkResult = z.union([
+  obj({ outcome: z.literal("COMPLETED") }),
+  obj({ outcome: z.literal("FAILED"), errorType: z.string().trim().min(1) })
+]);
+var KycSdkResultReportSchema = $kycSdkResult;
 var $transition = z.union([
   obj({
     id: z.string(),
@@ -610,7 +709,8 @@ var $blockedReason = z.enum([
   "REGION_UNSUPPORTED",
   "ASSET_UNSUPPORTED",
   "ALL_PROVIDERS_DECLINED",
-  "AMOUNT_UNSERVABLE"
+  "AMOUNT_UNSERVABLE",
+  "CLIENT_UPGRADE_REQUIRED"
 ]);
 var BlockedReasonSchema = $blockedReason;
 var $blockedState = obj({
@@ -654,7 +754,7 @@ var $orderCreatedState = obj({
   error: $failureReason.optional()
 });
 var OrderCreatedStateSchema = $orderCreatedState;
-var $flowState = z.union([
+var $providerBoundFlowState = z.union([
   $quoteState,
   $funAuthState,
   $sessionAuthState,
@@ -662,19 +762,26 @@ var $flowState = z.union([
   $kycInputRequiredState,
   $kycNoActionRequiredState,
   $pendingOrderState,
-  $blockedState,
   $paymentCaptureState,
   $paymentInstructState,
   $orderAwaitingConfirmationState,
   $orderCreatedState
 ]);
+var $flowState = z.union([$providerBoundFlowState, $blockedState]);
 var FlowStateSchema = $flowState;
-var $stepResponse = obj({
-  state: $flowState,
+var $providerBoundStepResponse = obj({
+  state: $providerBoundFlowState,
   provider: $provider,
   transitions: z.array($transition),
   orderId: z.string().optional()
 });
+var $blockedStepResponse = obj({
+  state: $blockedState,
+  provider: $provider.optional(),
+  transitions: z.array($transition),
+  orderId: z.string().optional()
+});
+var $stepResponse = z.union([$providerBoundStepResponse, $blockedStepResponse]);
 var FiatStepResponseSchema = $stepResponse;
 
 // src/fixtures/data.ts
@@ -684,7 +791,17 @@ var FIXTURE_DATA = {
       "kind": "QUOTE",
       "limits": {
         "min": "1.00",
-        "max": "3000.00"
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "500.00"
+          },
+          {
+            "min": "1000.00",
+            "max": "3000.00"
+          }
+        ]
       },
       "quote": {
         "quoteRef": "q_8f2",
@@ -732,7 +849,13 @@ var FIXTURE_DATA = {
       "kind": "QUOTE",
       "limits": {
         "min": "1.00",
-        "max": "3000.00"
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "3000.00"
+          }
+        ]
       },
       "quote": {
         "quoteRef": "q_8f2",
@@ -843,13 +966,13 @@ var FIXTURE_DATA = {
         "formId": "kyc_q_8f2_1",
         "fields": [
           {
-            "id": "tin",
+            "id": "TAX_IDENTIFIER",
             "type": "TEXT",
             "labelFallback": "Tax ID",
             "required": true
           },
           {
-            "id": "address",
+            "id": "RESIDENTIAL_ADDRESS_LINE_1",
             "type": "TEXT",
             "labelFallback": "Home address",
             "required": true
@@ -983,11 +1106,26 @@ var FIXTURE_DATA = {
         "params": {
           "accessToken": "eyJ\u2026"
         },
+        "preferredDocuments": {
+          "IDENTITY": {
+            "idDocType": "PASSPORT",
+            "country": "GBR"
+          }
+        },
         "expiresAt": "\u2026"
       }
     },
     "provider": "TRANSAK",
     "transitions": [
+      {
+        "id": "refresh_sdk_token",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/kyc/sdk-token",
+        "params": {
+          "quoteRef": "q_8f2"
+        },
+        "labelFallback": "Retry verification"
+      },
       {
         "id": "capture",
         "mode": "CLIENT_SURFACE",
@@ -995,6 +1133,10 @@ var FIXTURE_DATA = {
           "endpoint": "POST /fiat/kyc/capture",
           "params": {
             "quoteRef": "q_8f2"
+          },
+          "result": {
+            "type": "KYC_SDK_RESULT",
+            "bodyKey": "result"
           }
         }
       }
@@ -1239,7 +1381,6 @@ var FIXTURE_DATA = {
       "reason": "REGION_UNSUPPORTED",
       "retryAfter": null
     },
-    "provider": "TRANSAK",
     "transitions": []
   },
   "worked-example-01-quote": {
@@ -1247,7 +1388,13 @@ var FIXTURE_DATA = {
       "kind": "QUOTE",
       "limits": {
         "min": "1.00",
-        "max": "3000.00"
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "3000.00"
+          }
+        ]
       },
       "quote": {
         "quoteRef": "q_8f2",
@@ -1611,6 +1758,9 @@ function bodyKeyIssues(transition) {
   if (transition.mode === "CLIENT_SURFACE") {
     const params = Object.keys(transition.report.params ?? {});
     collide(params, transition.report.expects ?? [], "report.params", "report.expects");
+    const resultKeys = transition.report.result ? [transition.report.result.bodyKey] : [];
+    collide(params, resultKeys, "report.params", "report.result");
+    collide(transition.report.expects ?? [], resultKeys, "report.expects", "report.result");
   }
   return issues;
 }
@@ -1639,6 +1789,11 @@ function checkLegalEmission(state, transitions) {
         `transition "${transition.id}": CLIENT_SURFACE requires the Surface in state (\u03942 single-carry) \u2014 ${entry.key} carries none`
       );
     }
+    if (transition.mode === "CLIENT_SURFACE" && transition.report.result?.type === "KYC_SDK_RESULT" && (!("surface" in state) || state.surface?.kind !== "KYC_SDK")) {
+      issues.push(
+        `transition "${transition.id}": KYC_SDK_RESULT requires a KYC_SDK surface in state`
+      );
+    }
     if (transition.mode === "SUBMIT" && Object.values(transition.inputs ?? {}).some((spec) => spec.type === "FORM_VALUES") && !("form" in state)) {
       issues.push(
         `transition "${transition.id}": inputs {type: FORM_VALUES} collects state.form \u2014 ${entry.key} carries no form`
@@ -1695,6 +1850,7 @@ export {
   BlockedStateSchema,
   COUNTRY_NAMES,
   COUNTRY_TO_CURRENCY,
+  ClientExecutedDeliverySchema,
   ContractViolation,
   CountryCode,
   CryptoAmountSchema,
@@ -1723,9 +1879,11 @@ export {
   InstrumentSchema,
   JsonSchema,
   KYCProviderSchema,
+  KYC_ACKNOWLEDGEMENT_FIELD_IDS,
   KycCaptureStateSchema,
   KycInputRequiredStateSchema,
   KycNoActionRequiredStateSchema,
+  KycSdkResultReportSchema,
   OrderAwaitingConfirmationStateSchema,
   OrderCreatedStateSchema,
   OrderRefSchema,
@@ -1736,12 +1894,15 @@ export {
   PaymentInstructStateSchema,
   PendingOrderStateSchema,
   PollSpecSchema,
+  PreferredIdentityDocumentSchema,
+  QuoteLimitRangeSchema,
   QuoteLimitsSchema,
   QuoteSchema,
   QuoteStateSchema,
   RecoverySchema,
   RefundSchema,
   ReportSpecSchema,
+  STANDARD_KYC_FIELD_IDS,
   STATE_KEYS,
   SelectOptionSchema,
   SessionAuthStateSchema,
@@ -1752,6 +1913,7 @@ export {
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE,
+  TermsAcceptanceSchema,
   TransitionInputsSchema,
   TransitionParamsSchema,
   TransitionSchema,

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 { 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';
+import type { BlockedReason, CryptoAmount, FailureReason, FeeLine, FiatAmount, FiatEndpoint, FiatProvider, FiatStepResponse, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, InstructionField, Instructions, Instrument, JsonValue, KYCProvider, OrderRef, OrderStatus, OrderSummary, PollSpec, Quote, QuoteLimitRange, QuoteLimits, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, Surface, PreferredIdentityDocument, ClientExecutedDelivery, KycSdkResultReport, SurfaceKind, SurfaceProvider, TermsAcceptance, 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 QuoteLimitRangeSchema: z.ZodType<QuoteLimitRange>;
 export declare const QuoteLimitsSchema: z.ZodType<QuoteLimits>;
 export declare const InstrumentSchema: z.ZodType<Instrument>;
 export declare const OrderRefSchema: z.ZodType<OrderRef>;
@@ -51,6 +52,10 @@ export declare const StatusHistoryEntrySchema: z.ZodType<StatusHistoryEntry>;
 export declare const TxSchema: z.ZodType<Tx>;
 export declare const RefundSchema: z.ZodType<Refund>;
 export declare const SurfaceKindSchema: z.ZodType<SurfaceKind>;
+export declare const PreferredIdentityDocumentSchema: z.ZodType<PreferredIdentityDocument>;
+export declare const STANDARD_KYC_FIELD_IDS: readonly ["LEGAL_FIRST_NAME", "LEGAL_MIDDLE_NAME", "LEGAL_LAST_NAME", "DATE_OF_BIRTH", "COUNTRY_OF_BIRTH", "CITY_OF_BIRTH", "NATIONALITY", "EMAIL_ADDRESS", "EMAIL_OWNERSHIP_VERIFICATION", "PHONE_NUMBER", "PHONE_OWNERSHIP_VERIFICATION", "RESIDENTIAL_ADDRESS_LINE_1", "RESIDENTIAL_ADDRESS_LINE_2", "RESIDENTIAL_ADDRESS_CITY", "RESIDENTIAL_ADDRESS_REGION", "RESIDENTIAL_ADDRESS_POSTAL_CODE", "RESIDENTIAL_ADDRESS_COUNTRY", "TAX_IDENTIFIER", "TAX_RESIDENCE_COUNTRY", "EMPLOYMENT_STATUS", "OCCUPATION_INDUSTRY", "OCCUPATION_TITLE", "SOURCE_OF_FUNDS_DECLARATION", "SOURCE_OF_INCOME_DECLARATION", "SOURCE_OF_WEALTH_DECLARATION", "PURPOSE_OF_SERVICE", "PURPOSE_OF_TRANSACTION", "CUSTOMER_CATEGORY"];
+export declare const KYC_ACKNOWLEDGEMENT_FIELD_IDS: readonly ["RISK_ACKNOWLEDGEMENT", "COOLING_OFF_ACKNOWLEDGEMENT", "TERMS_ACCEPTANCE"];
+export declare const ClientExecutedDeliverySchema: z.ZodType<ClientExecutedDelivery>;
 export declare const SurfaceSchema: z.ZodType<Surface>;
 export declare const InstructionFieldSchema: z.ZodType<InstructionField>;
 export declare const InstructionsSchema: z.ZodType<Instructions>;
@@ -58,8 +63,10 @@ export declare const SelectOptionSchema: z.ZodType<SelectOption>;
 export declare const FormFieldTypeSchema: z.ZodType<FormFieldType>;
 export declare const FormFieldSchema: z.ZodType<FormField>;
 export declare const FormDescriptorSchema: z.ZodType<FormDescriptor>;
-export declare const FIELD_SPEC_TYPES: readonly ["TEXT", "DATE", "COUNTRY", "FILE", "SELECT", "HOSTED_LINK", "FORM_VALUES"];
+export declare const FIELD_SPEC_TYPES: readonly ["TEXT", "DATE", "COUNTRY", "FILE", "SELECT", "HOSTED_LINK", "FORM_VALUES", "TERMS_ACCEPTANCE"];
 export declare const FieldSpecSchema: z.ZodType<FieldSpec>;
+/** The value a `TERMS_ACCEPTANCE` input yields. */
+export declare const TermsAcceptanceSchema: z.ZodType<TermsAcceptance>;
 /**
  * True when a `params` value is wearing a `FieldSpec`'s clothes — i.e. the exact defect the
  * accepted split exists to kill (a spec object spread into a request body as if it were a value).
@@ -69,6 +76,7 @@ export declare const TransitionParamsSchema: z.ZodType<TransitionParams>;
 export declare const TransitionInputsSchema: z.ZodType<TransitionInputs>;
 export declare const PollSpecSchema: z.ZodType<PollSpec>;
 export declare const ReportSpecSchema: z.ZodType<ReportSpec>;
+export declare const KycSdkResultReportSchema: z.ZodType<KycSdkResultReport>;
 export declare const TransitionSchema: z.ZodType<Transition>;
 export declare const AuthChallengeSchema: z.ZodType<Record<string, JsonValue>>;
 /** `Extract` keeps each per-state export pinned to the union member it validates. */

package/dist/table.js

@@ -36,7 +36,7 @@ __export(table_exports, {
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.9.0";
+var version = "0.11.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -151,7 +151,8 @@ var TRANSITION_TABLE = {
     terminal: false,
     notes: [
       "A bad code re-enters this same state with error {category: USER_ERROR, code: BAD_CODE} \u2014 banner, not a screen change.",
-      "No resend affordance is specified in either doc (known gap, FE doc Screen 2)."
+      "No resend affordance is specified in either doc (known gap, FE doc Screen 2).",
+      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only."
     ]
   },
   "KYC/CAPTURE": {
@@ -161,6 +162,12 @@ var TRANSITION_TABLE = {
     screens: [8],
     docStatus: "SPECIFIED",
     allowedTransitions: [
+      {
+        id: "refresh_sdk_token",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/kyc/sdk-token",
+        note: "Refreshes an expired SDK credential and returns a new KYC/CAPTURE state."
+      },
       {
         id: "capture",
         mode: "CLIENT_SURFACE",
@@ -180,7 +187,10 @@ var TRANSITION_TABLE = {
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
-    notes: ["Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter."]
+    notes: [
+      "Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter.",
+      "SDK completion or failure is only a launch report; eligibility is re-read authoritatively by the backend."
+    ]
   },
   "KYC/INPUT_REQUIRED": {
     key: "KYC/INPUT_REQUIRED",
@@ -436,10 +446,6 @@ 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."

package/dist/table.mjs

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

package/dist/types.d.ts

@@ -151,10 +151,23 @@ export interface Quote {
     paymentMethod: PaymentMethodCategory;
     expiresAt: string;
 }
-/** Input bounds for the quote screen. Decimal strings in the quote currency. */
+/** One inclusive amount interval the current routing set can actually serve. */
+export interface QuoteLimitRange {
+    min: string;
+    max: string;
+}
+/**
+ * Input bounds for the quote screen. Decimal strings in the quote currency.
+ *
+ * `min`/`max` remain the bounding envelope for clients on contract <=0.9. A routing set can have
+ * gaps (one path serves a low interval and another a higher interval), so new emitters also carry
+ * the exact sorted, non-overlapping intervals in `serviceableRanges`. The field is optional only so
+ * an upgraded client can cold-render an older recorded response during a rolling deployment.
+ */
 export interface QuoteLimits {
     min: string;
     max: string;
+    serviceableRanges?: QuoteLimitRange[];
 }
 /** Deferred to the credit-card iteration (FE doc port ledger) — optional wherever it appears. */
 export interface Instrument {
@@ -228,8 +241,7 @@ export type SurfaceProvider = FiatProvider | KYCProvider;
  * `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;
+interface SurfaceBase {
     provider: SurfaceProvider;
     params: Record<string, JsonValue>;
     /**
@@ -238,6 +250,49 @@ export interface Surface {
      */
     expiresAt?: string;
 }
+/**
+ * Identity-document kinds the Sumsub adapter may prefer for the `IDENTITY` step.
+ *
+ * These are the Sumsub identity spellings understood by the capture adapter. Adding a new kind is
+ * a contract change: the client adapter must know how to pass it to the identity SDK and every
+ * relying provider must either map or explicitly decline it.
+ */
+export type KycIdentityDocumentType = 'PASSPORT' | 'ID_CARD' | 'DRIVERS' | 'RESIDENCE_PERMIT' | 'VISA';
+/** Provider-native document definition understood by the selected KYC adapter. */
+export interface PreferredIdentityDocument {
+    idDocType: KycIdentityDocumentType;
+    /** ISO 3166-1 alpha-3 country code expected by the identity-vendor SDK. */
+    country: string;
+}
+/** Canonical KYC values a declarative form or current-session delivery may name. */
+export type StandardKycFieldId = 'LEGAL_FIRST_NAME' | 'LEGAL_MIDDLE_NAME' | 'LEGAL_LAST_NAME' | 'DATE_OF_BIRTH' | 'COUNTRY_OF_BIRTH' | 'CITY_OF_BIRTH' | 'NATIONALITY' | 'EMAIL_ADDRESS' | 'EMAIL_OWNERSHIP_VERIFICATION' | 'PHONE_NUMBER' | 'PHONE_OWNERSHIP_VERIFICATION' | 'RESIDENTIAL_ADDRESS_LINE_1' | 'RESIDENTIAL_ADDRESS_LINE_2' | 'RESIDENTIAL_ADDRESS_CITY' | 'RESIDENTIAL_ADDRESS_REGION' | 'RESIDENTIAL_ADDRESS_POSTAL_CODE' | 'RESIDENTIAL_ADDRESS_COUNTRY' | 'TAX_IDENTIFIER' | 'TAX_RESIDENCE_COUNTRY' | 'EMPLOYMENT_STATUS' | 'OCCUPATION_INDUSTRY' | 'OCCUPATION_TITLE' | 'SOURCE_OF_FUNDS_DECLARATION' | 'SOURCE_OF_INCOME_DECLARATION' | 'SOURCE_OF_WEALTH_DECLARATION' | 'PURPOSE_OF_SERVICE' | 'PURPOSE_OF_TRANSACTION' | 'CUSTOMER_CATEGORY';
+export type KycAcknowledgementFieldId = 'RISK_ACKNOWLEDGEMENT' | 'COOLING_OFF_ACKNOWLEDGEMENT' | 'TERMS_ACCEPTANCE';
+export type QuestionnaireKycFieldId = `QUESTIONNAIRE_RESPONSE:${string}:${string}`;
+export type KycFieldId = StandardKycFieldId | KycAcknowledgementFieldId | QuestionnaireKycFieldId;
+export interface ClientExecutedDelivery {
+    channel: 'CLIENT_EXECUTED';
+    /**
+     * A hard security boundary: only values entered during this mounted session may be selected.
+     * Backend-stored KYC values are never returned to the client through this contract.
+     */
+    source: 'CURRENT_SESSION_INPUTS';
+    /** Server-declared canonical field ids the adapter may select; this carries no field values. */
+    allowedFieldIds: KycFieldId[];
+}
+export type Surface = (SurfaceBase & {
+    kind: 'KYC_SDK';
+    provider: KYCProvider;
+    /** Credentials and adapter configuration only; never backend-stored KYC field values. */
+    params: Record<string, JsonValue>;
+    preferredDocuments?: {
+        IDENTITY: PreferredIdentityDocument;
+    };
+}) | (SurfaceBase & {
+    kind: Exclude<SurfaceKind, 'KYC_SDK'>;
+    provider: FiatProvider;
+    /** Adapter-owned submission mechanics; the shared contract declares only the safe source. */
+    delivery?: ClientExecutedDelivery;
+});
 export interface InstructionField {
     id: string;
     labelFallback: string;
@@ -275,17 +330,28 @@ export interface SelectOption {
 }
 /** Field types inside a KYC form round. A new field TYPE is a client release (handshake-gated). */
 export type FormFieldType = 'TEXT' | 'DATE' | 'SELECT' | 'COUNTRY' | 'FILE' | 'HOSTED_LINK';
-export interface FormField {
-    id: string;
-    type: FormFieldType;
+interface FormFieldBase {
+    id: KycFieldId;
     labelFallback: string;
     required: boolean;
-    regex?: string;
-    /** SELECT only. */
-    options?: SelectOption[];
-    /** HOSTED_LINK only. */
-    url?: string;
 }
+/** Invalid property combinations (for example `options` on TEXT) are unrepresentable. */
+export type FormField = (FormFieldBase & {
+    type: 'TEXT';
+    regex?: string;
+}) | (FormFieldBase & {
+    type: 'DATE';
+}) | (FormFieldBase & {
+    type: 'SELECT';
+    options: SelectOption[];
+}) | (FormFieldBase & {
+    type: 'COUNTRY';
+}) | (FormFieldBase & {
+    type: 'FILE';
+}) | (FormFieldBase & {
+    type: 'HOSTED_LINK';
+    url: string;
+});
 /** Payload of `KYC{INPUT_REQUIRED}`. One uniform renderer walks `fields`. */
 export interface FormDescriptor {
     formId: string;
@@ -297,7 +363,7 @@ export interface FormDescriptor {
  * transition never re-carries the descriptor (the double-carry disease Δ2 killed).
  *
  * Note: the contract's illustrative list reads `'TEXT' | 'NUMBER' | …`; the conformance-package
- * spec closes the set at the seven below, so `NUMBER` is not declared here.
+ * spec closes the set at the eight below, so `NUMBER` is not declared here.
  */
 export type FieldSpec = {
     type: 'TEXT';
@@ -323,8 +389,28 @@ export type FieldSpec = {
     labelFallback?: string;
 } | {
     type: 'FORM_VALUES';
+} | {
+    type: 'TERMS_ACCEPTANCE';
+    /** The document being accepted. The client shows it; the user cannot accept what they cannot read. */
+    documentUrl: string;
+    /**
+     * Which revision of that document. Opaque to the client and echoed back verbatim, so a later
+     * dispute names the text the user saw rather than whatever is at `documentUrl` today.
+     */
+    version: string;
+    labelFallback?: string;
 };
 export type FieldSpecType = FieldSpec['type'];
+/**
+ * What a `TERMS_ACCEPTANCE` input collects. A bare timestamp answers "when" and nothing else; the
+ * version is what ties the moment to the words, which is the only part a dispute turns on.
+ */
+export interface TermsAcceptance {
+    /** Echoed from the `FieldSpec`, unmodified. */
+    version: string;
+    /** ISO-8601, stamped by the client when the user accepted. Never defaulted server-side. */
+    acceptedAt: string;
+}
 /** Server literals — spread into the body verbatim, opaque to the client. */
 export type TransitionParams = Record<string, JsonValue>;
 /** Client-collected specs — the harness renders + locally validates, then merges values in. */
@@ -378,7 +464,22 @@ export interface ReportSpec {
      * Declared so conformance can assert the surface actually yields them.
      */
     expects?: string[];
+    /** Typed SDK result injected under `bodyKey`; mutually exclusive outcome shapes are below. */
+    result?: {
+        type: 'KYC_SDK_RESULT';
+        bodyKey: string;
+    };
 }
+/**
+ * Client report for a KYC SDK launch. This reports SDK completion, not KYC eligibility: only the
+ * backend's authoritative provider read can advance eligibility.
+ */
+export type KycSdkResultReport = {
+    outcome: 'COMPLETED';
+} | {
+    outcome: 'FAILED';
+    errorType: string;
+};
 export type TransitionMode = 'SUBMIT' | 'AWAIT' | 'CLIENT_SURFACE';
 /**
  * Body assembly, harness-owned, one rule:
@@ -531,16 +632,33 @@ export type FlowState =
     error?: FailureReason;
 };
 export type FlowStateKind = FlowState['kind'];
-export type BlockedReason = 'REGION_UNSUPPORTED' | 'ASSET_UNSUPPORTED' | 'ALL_PROVIDERS_DECLINED' | 'AMOUNT_UNSERVABLE';
+export type BlockedReason = 'REGION_UNSUPPORTED' | 'ASSET_UNSUPPORTED' | 'ALL_PROVIDERS_DECLINED' | 'AMOUNT_UNSERVABLE'
+/** The installed client did not declare a capability required by every otherwise-viable route. */
+ | 'CLIENT_UPGRADE_REQUIRED';
 /**
  * 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).
  */
-export interface FiatStepResponse {
-    state: FlowState;
-    provider: FiatProvider;
+type FiatStepResponseBase = {
     transitions: Transition[];
     /** TODO(open-decision): `orderId` placement — see `PAYMENT{INSTRUCT}.orderId` above. */
     orderId?: string;
-}
+};
+/**
+ * Provider is absent only when routing ended before a provider could be selected. A BLOCKED response
+ * may still name a provider for compatibility with provider-specific terminal decisions; every other
+ * state is provider-bound and therefore requires one.
+ */
+export type FiatStepResponse = (FiatStepResponseBase & {
+    state: Extract<FlowState, {
+        kind: 'BLOCKED';
+    }>;
+    provider?: FiatProvider;
+}) | (FiatStepResponseBase & {
+    state: Exclude<FlowState, {
+        kind: 'BLOCKED';
+    }>;
+    provider: FiatProvider;
+});
+export {};
 //# sourceMappingURL=types.d.ts.map

package/package.json

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