@fun-xyz/fiat-contract 0.11.1 → 0.11.3

package/README.md

@@ -78,6 +78,12 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
 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.
+14. **Path commitment is not a quote.** A response may carry `routingSessionRef` while pricing is
+    legitimately deferred for provider auth or activation. Transitions echo that opaque reference in
+    `params`; clients submit it unchanged. `Quote.quoteRef` remains required whenever a real `Quote`
+    is present, and PAY must never be exposed without real current economics.
+15. **KYC may precede pricing.** Provider auth or activation may legitimately defer pricing, so a
+    KYC state may omit `quote`. A real `Quote` still requires `quoteRef`, and PAY is never quote-less.
 
 ## KYC SDK hints, results, and client delivery
 

package/dist/{chunk-TXI4KLBL.mjs → chunk-EXLSD4UP.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.11.1";
+var version = "0.11.3";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -102,7 +102,13 @@ var TRANSITION_TABLE = {
     docStatus: "SPECIFIED",
     allowedTransitions: [
       { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/session" },
-      { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" }
+      { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" },
+      {
+        id: "report_auth_result",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/session/verify",
+        note: "Reports a provider-owned authentication surface result; the backend alone reassesses and selects the next state."
+      }
     ],
     mayReturn: [
       "SESSION_AUTH",
@@ -116,7 +122,8 @@ var TRANSITION_TABLE = {
     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).",
-      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only."
+      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only.",
+      "A provider-owned authentication surface reports through CLIENT_SURFACE; it is not a user-entered OTP submission."
     ]
   },
   "KYC/CAPTURE": {
@@ -507,4 +514,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-TXI4KLBL.mjs.map
+//# sourceMappingURL=chunk-EXLSD4UP.mjs.map

package/dist/index.js

@@ -777,7 +777,7 @@ var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("CAPTURE"),
-  quote: $quote,
+  quote: $quote.optional(),
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -785,7 +785,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("INPUT_REQUIRED"),
-  quote: $quote,
+  quote: $quote.optional(),
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -793,7 +793,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("NO_ACTION_REQUIRED"),
-  quote: $quote,
+  quote: $quote.optional(),
   reason: import_zod.z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: import_zod.z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -874,19 +874,21 @@ var $providerBoundStepResponse = obj({
   state: $providerBoundFlowState,
   provider: $provider,
   transitions: import_zod.z.array($transition),
+  routingSessionRef: import_zod.z.string().optional(),
   orderId: import_zod.z.string().optional()
 });
 var $blockedStepResponse = obj({
   state: $blockedState,
   provider: $provider.optional(),
   transitions: import_zod.z.array($transition),
+  routingSessionRef: import_zod.z.string().optional(),
   orderId: import_zod.z.string().optional()
 });
 var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStepResponse]);
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.11.1";
+var version = "0.11.3";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -989,7 +991,13 @@ var TRANSITION_TABLE = {
     docStatus: "SPECIFIED",
     allowedTransitions: [
       { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/session" },
-      { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" }
+      { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" },
+      {
+        id: "report_auth_result",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/session/verify",
+        note: "Reports a provider-owned authentication surface result; the backend alone reassesses and selects the next state."
+      }
     ],
     mayReturn: [
       "SESSION_AUTH",
@@ -1003,7 +1011,8 @@ var TRANSITION_TABLE = {
     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).",
-      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only."
+      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only.",
+      "A provider-owned authentication surface reports through CLIENT_SURFACE; it is not a user-entered OTP submission."
     ]
   },
   "KYC/CAPTURE": {

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-TXI4KLBL.mjs";
+} from "./chunk-EXLSD4UP.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -676,7 +676,7 @@ var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("CAPTURE"),
-  quote: $quote,
+  quote: $quote.optional(),
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -684,7 +684,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("INPUT_REQUIRED"),
-  quote: $quote,
+  quote: $quote.optional(),
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -692,7 +692,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("NO_ACTION_REQUIRED"),
-  quote: $quote,
+  quote: $quote.optional(),
   reason: z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -773,12 +773,14 @@ var $providerBoundStepResponse = obj({
   state: $providerBoundFlowState,
   provider: $provider,
   transitions: z.array($transition),
+  routingSessionRef: z.string().optional(),
   orderId: z.string().optional()
 });
 var $blockedStepResponse = obj({
   state: $blockedState,
   provider: $provider.optional(),
   transitions: z.array($transition),
+  routingSessionRef: z.string().optional(),
   orderId: z.string().optional()
 });
 var $stepResponse = z.union([$providerBoundStepResponse, $blockedStepResponse]);

package/dist/table.js

@@ -36,7 +36,7 @@ __export(table_exports, {
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.11.1";
+var version = "0.11.3";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -139,7 +139,13 @@ var TRANSITION_TABLE = {
     docStatus: "SPECIFIED",
     allowedTransitions: [
       { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/session" },
-      { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" }
+      { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" },
+      {
+        id: "report_auth_result",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/session/verify",
+        note: "Reports a provider-owned authentication surface result; the backend alone reassesses and selects the next state."
+      }
     ],
     mayReturn: [
       "SESSION_AUTH",
@@ -153,7 +159,8 @@ var TRANSITION_TABLE = {
     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).",
-      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only."
+      "A provider-owned surface may declare client-executed delivery from allowlisted CURRENT_SESSION_INPUTS only.",
+      "A provider-owned authentication surface reports through CLIENT_SURFACE; it is not a user-entered OTP submission."
     ]
   },
   "KYC/CAPTURE": {

package/dist/table.mjs

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

package/dist/types.d.ts

@@ -544,23 +544,26 @@ export type FlowState =
     surface?: Surface;
     error?: FailureReason;
 }
-/** Pre-order KYC states carry the routed quote so the entry screen can keep price visible. */
+/**
+ * Pre-order KYC normally carries the routed quote so the entry screen can keep price visible.
+ * `quote` may be absent when provider auth or activation gates pricing.
+ */
  | {
     kind: 'KYC';
     phase: 'CAPTURE';
-    quote: Quote;
+    quote?: Quote;
     surface: Surface;
     error?: FailureReason;
 } | {
     kind: 'KYC';
     phase: 'INPUT_REQUIRED';
-    quote: Quote;
+    quote?: Quote;
     form: FormDescriptor;
     error?: FailureReason;
 } | {
     kind: 'KYC';
     phase: 'NO_ACTION_REQUIRED';
-    quote: Quote;
+    quote?: Quote;
     /**
      * Note the deliberate name collision (Charles's nit, review 2026-08-14): `ON_HOLD` appears
      * here as a KYC reason *and* in `OrderStatus`. They are different things and both names come
@@ -641,6 +644,14 @@ export type BlockedReason = 'REGION_UNSUPPORTED' | 'ASSET_UNSUPPORTED' | 'ALL_PR
  */
 type FiatStepResponseBase = {
     transitions: Transition[];
+    /**
+     * Stable identity for a routing continuation before provider pricing is observable.
+     *
+     * A quote-less CONTINUE/PENDING response carries this instead of fabricating a `Quote` or
+     * `quoteRef`. It may remain present after a real quote is promoted so the backend can preserve
+     * the committed provider path independently from the quote binding.
+     */
+    routingSessionRef?: string;
     /** TODO(open-decision): `orderId` placement — see `PAYMENT{INSTRUCT}.orderId` above. */
     orderId?: string;
 };

package/package.json

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