@fun-xyz/fiat-contract 0.10.0 → 0.11.1

package/README.md

@@ -64,6 +64,46 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
    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
 
@@ -450,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-BAGIBS54.mjs → chunk-TXI4KLBL.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.10.0";
+var version = "0.11.1";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -101,6 +101,7 @@ var TRANSITION_TABLE = {
     screens: [2],
     docStatus: "SPECIFIED",
     allowedTransitions: [
+      { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/session" },
       { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" }
     ],
     mayReturn: [
@@ -114,7 +115,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 +126,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 +151,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 +410,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 +507,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-BAGIBS54.mjs.map
+//# sourceMappingURL=chunk-TXI4KLBL.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,6 +69,7 @@ __export(index_exports, {
   PaymentInstructStateSchema: () => PaymentInstructStateSchema,
   PendingOrderStateSchema: () => PendingOrderStateSchema,
   PollSpecSchema: () => PollSpecSchema,
+  PreferredIdentityDocumentSchema: () => PreferredIdentityDocumentSchema,
   QuoteLimitRangeSchema: () => QuoteLimitRangeSchema,
   QuoteLimitsSchema: () => QuoteLimitsSchema,
   QuoteSchema: () => QuoteSchema,
@@ -73,6 +77,7 @@ __export(index_exports, {
   RecoverySchema: () => RecoverySchema,
   RefundSchema: () => RefundSchema,
   ReportSpecSchema: () => ReportSpecSchema,
+  STANDARD_KYC_FIELD_IDS: () => STANDARD_KYC_FIELD_IDS,
   STATE_KEYS: () => STATE_KEYS,
   SelectOptionSchema: () => SelectOptionSchema,
   SessionAuthStateSchema: () => SessionAuthStateSchema,
@@ -83,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,
@@ -512,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
@@ -525,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(),
@@ -548,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;
@@ -567,7 +649,8 @@ var FIELD_SPEC_TYPES = [
   "FILE",
   "SELECT",
   "HOSTED_LINK",
-  "FORM_VALUES"
+  "FORM_VALUES",
+  "TERMS_ACCEPTANCE"
 ];
 var $fieldSpec = import_zod.z.union([
   obj({
@@ -585,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)) {
@@ -634,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(),
@@ -711,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({
@@ -755,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,
@@ -763,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.10.0";
+var version = "0.11.1";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -881,6 +988,7 @@ var TRANSITION_TABLE = {
     screens: [2],
     docStatus: "SPECIFIED",
     allowedTransitions: [
+      { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/session" },
       { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" }
     ],
     mayReturn: [
@@ -894,7 +1002,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": {
@@ -904,6 +1013,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",
@@ -923,7 +1038,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",
@@ -1179,10 +1297,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."
@@ -1448,13 +1562,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
@@ -1588,11 +1702,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",
@@ -1600,6 +1729,10 @@ var FIXTURE_DATA = {
           "endpoint": "POST /fiat/kyc/capture",
           "params": {
             "quoteRef": "q_8f2"
+          },
+          "result": {
+            "type": "KYC_SDK_RESULT",
+            "bodyKey": "result"
           }
         }
       }
@@ -1844,7 +1977,6 @@ var FIXTURE_DATA = {
       "reason": "REGION_UNSUPPORTED",
       "retryAfter": null
     },
-    "provider": "TRANSAK",
     "transitions": []
   },
   "worked-example-01-quote": {
@@ -2222,6 +2354,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;
 }
@@ -2250,6 +2385,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-BAGIBS54.mjs";
+} from "./chunk-TXI4KLBL.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -417,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
@@ -430,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(),
@@ -453,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;
@@ -472,7 +548,8 @@ var FIELD_SPEC_TYPES = [
   "FILE",
   "SELECT",
   "HOSTED_LINK",
-  "FORM_VALUES"
+  "FORM_VALUES",
+  "TERMS_ACCEPTANCE"
 ];
 var $fieldSpec = z.union([
   obj({
@@ -490,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)) {
@@ -539,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(),
@@ -616,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({
@@ -660,7 +754,7 @@ var $orderCreatedState = obj({
   error: $failureReason.optional()
 });
 var OrderCreatedStateSchema = $orderCreatedState;
-var $flowState = z.union([
+var $providerBoundFlowState = z.union([
   $quoteState,
   $funAuthState,
   $sessionAuthState,
@@ -668,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
@@ -865,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
@@ -1005,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",
@@ -1017,6 +1133,10 @@ var FIXTURE_DATA = {
           "endpoint": "POST /fiat/kyc/capture",
           "params": {
             "quoteRef": "q_8f2"
+          },
+          "result": {
+            "type": "KYC_SDK_RESULT",
+            "bodyKey": "result"
           }
         }
       }
@@ -1261,7 +1381,6 @@ var FIXTURE_DATA = {
       "reason": "REGION_UNSUPPORTED",
       "retryAfter": null
     },
-    "provider": "TRANSAK",
     "transitions": []
   },
   "worked-example-01-quote": {
@@ -1639,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;
 }
@@ -1667,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`
@@ -1723,6 +1850,7 @@ export {
   BlockedStateSchema,
   COUNTRY_NAMES,
   COUNTRY_TO_CURRENCY,
+  ClientExecutedDeliverySchema,
   ContractViolation,
   CountryCode,
   CryptoAmountSchema,
@@ -1751,9 +1879,11 @@ export {
   InstrumentSchema,
   JsonSchema,
   KYCProviderSchema,
+  KYC_ACKNOWLEDGEMENT_FIELD_IDS,
   KycCaptureStateSchema,
   KycInputRequiredStateSchema,
   KycNoActionRequiredStateSchema,
+  KycSdkResultReportSchema,
   OrderAwaitingConfirmationStateSchema,
   OrderCreatedStateSchema,
   OrderRefSchema,
@@ -1764,6 +1894,7 @@ export {
   PaymentInstructStateSchema,
   PendingOrderStateSchema,
   PollSpecSchema,
+  PreferredIdentityDocumentSchema,
   QuoteLimitRangeSchema,
   QuoteLimitsSchema,
   QuoteSchema,
@@ -1771,6 +1902,7 @@ export {
   RecoverySchema,
   RefundSchema,
   ReportSpecSchema,
+  STANDARD_KYC_FIELD_IDS,
   STATE_KEYS,
   SelectOptionSchema,
   SessionAuthStateSchema,
@@ -1781,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, QuoteLimitRange, 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. */
@@ -52,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>;
@@ -59,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).
@@ -70,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.10.0";
+var version = "0.11.1";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -138,6 +138,7 @@ var TRANSITION_TABLE = {
     screens: [2],
     docStatus: "SPECIFIED",
     allowedTransitions: [
+      { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/session" },
       { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" }
     ],
     mayReturn: [
@@ -151,7 +152,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 +163,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 +188,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 +447,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-BAGIBS54.mjs";
+} from "./chunk-TXI4KLBL.mjs";
 export {
   DOCUMENTED_ENDPOINTS,
   STATE_KEYS,

package/dist/types.d.ts

@@ -241,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>;
     /**
@@ -251,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;
@@ -288,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;
@@ -310,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';
@@ -336,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. */
@@ -391,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:
@@ -544,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.10.0",
+  "version": "0.11.1",
   "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": {