@fun-xyz/fiat-contract 0.14.0 → 0.16.0

package/README.md

@@ -85,6 +85,9 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
     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.
+16. **Correction text never decides retry.** A correctable provider rejection returns
+    `KYC{CAPTURE}` and may carry `correctionReason` for display. Clients decide that retry is allowed
+    from the state and its transitions; provider-authored text is never a branch key.
 
 ## KYC SDK hints, results, and client delivery
 

package/dist/{chunk-BQELSEYH.mjs → chunk-PEJOU52N.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.14.0";
+var version = "0.16.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -514,4 +514,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-BQELSEYH.mjs.map
+//# sourceMappingURL=chunk-PEJOU52N.mjs.map

package/dist/index.js

@@ -841,6 +841,7 @@ var $kycCaptureState = obj({
   phase: import_zod.z.literal("CAPTURE"),
   quote: $quote.optional(),
   surface: $surface,
+  correctionReason: import_zod.z.string().min(1).max(1024).optional(),
   error: $failureReason.optional()
 });
 var KycCaptureStateSchema = $kycCaptureState;
@@ -941,7 +942,8 @@ var $providerBoundStepResponse = obj({
     clientSecret: import_zod.z.string(),
     expiresAt: import_zod.z.string()
   }).optional(),
-  orderId: import_zod.z.string().optional()
+  orderId: import_zod.z.string().optional(),
+  refreshLimits: import_zod.z.literal(true).optional()
 });
 var $blockedStepResponse = obj({
   state: $blockedState,
@@ -952,13 +954,14 @@ var $blockedStepResponse = obj({
     clientSecret: import_zod.z.string(),
     expiresAt: import_zod.z.string()
   }).optional(),
-  orderId: import_zod.z.string().optional()
+  orderId: import_zod.z.string().optional(),
+  refreshLimits: import_zod.z.literal(true).optional()
 });
 var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStepResponse]);
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.14.0";
+var version = "0.16.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -1788,7 +1791,8 @@ var FIXTURE_DATA = {
           }
         },
         "expiresAt": "\u2026"
-      }
+      },
+      "correctionReason": "The image is too blurry. Upload a clearer photo of this document."
     },
     "provider": "TRANSAK",
     "transitions": [
@@ -2252,7 +2256,10 @@ var FIXTURES = [
     docRef: "Fiat KYC \xB7 embedded Sumsub WebSDK",
     screen: 8,
     stateKey: "KYC/CAPTURE",
-    notes: ["The client mounts the Sumsub adapter; no URL or iframe is emitted."]
+    notes: [
+      "The client mounts the Sumsub adapter; no URL or iframe is emitted.",
+      "A retry may carry provider-authored correctionReason display text; clients never branch on it."
+    ]
   },
   {
     id: "screen-09-kyc-in-review",

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-BQELSEYH.mjs";
+} from "./chunk-PEJOU52N.mjs";
 
 // src/codes.ts
 var US_STATE_CODES = [
@@ -738,6 +738,7 @@ var $kycCaptureState = obj({
   phase: z.literal("CAPTURE"),
   quote: $quote.optional(),
   surface: $surface,
+  correctionReason: z.string().min(1).max(1024).optional(),
   error: $failureReason.optional()
 });
 var KycCaptureStateSchema = $kycCaptureState;
@@ -838,7 +839,8 @@ var $providerBoundStepResponse = obj({
     clientSecret: z.string(),
     expiresAt: z.string()
   }).optional(),
-  orderId: z.string().optional()
+  orderId: z.string().optional(),
+  refreshLimits: z.literal(true).optional()
 });
 var $blockedStepResponse = obj({
   state: $blockedState,
@@ -849,7 +851,8 @@ var $blockedStepResponse = obj({
     clientSecret: z.string(),
     expiresAt: z.string()
   }).optional(),
-  orderId: z.string().optional()
+  orderId: z.string().optional(),
+  refreshLimits: z.literal(true).optional()
 });
 var $stepResponse = z.union([$providerBoundStepResponse, $blockedStepResponse]);
 var FiatStepResponseSchema = $stepResponse;
@@ -1183,7 +1186,8 @@ var FIXTURE_DATA = {
           }
         },
         "expiresAt": "\u2026"
-      }
+      },
+      "correctionReason": "The image is too blurry. Upload a clearer photo of this document."
     },
     "provider": "TRANSAK",
     "transitions": [
@@ -1647,7 +1651,10 @@ var FIXTURES = [
     docRef: "Fiat KYC \xB7 embedded Sumsub WebSDK",
     screen: 8,
     stateKey: "KYC/CAPTURE",
-    notes: ["The client mounts the Sumsub adapter; no URL or iframe is emitted."]
+    notes: [
+      "The client mounts the Sumsub adapter; no URL or iframe is emitted.",
+      "A retry may carry provider-authored correctionReason display text; clients never branch on it."
+    ]
   },
   {
     id: "screen-09-kyc-in-review",

package/dist/table.js

@@ -36,7 +36,7 @@ __export(table_exports, {
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.14.0";
+var version = "0.16.0";
 
 // src/table.ts
 var TABLE_VERSION = version;

package/dist/table.mjs

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

package/dist/types.d.ts

@@ -553,6 +553,11 @@ export type FlowState =
     phase: 'CAPTURE';
     quote?: Quote;
     surface: Surface;
+    /**
+     * Provider-authored guidance for correcting the previous verification attempt. Display-only:
+     * clients must use the state and transitions, never this text, to decide whether retry is allowed.
+     */
+    correctionReason?: string;
     error?: FailureReason;
 } | {
     kind: 'KYC';
@@ -662,6 +667,15 @@ type FiatStepResponseBase = {
     };
     /** TODO(open-decision): `orderId` placement — see `PAYMENT{INSTRUCT}.orderId` above. */
     orderId?: string;
+    /**
+     * Best-effort: what this response did may have changed what the buyer can spend, so a cached
+     * discovery ceiling is no longer trusted. Absent is not a promise that nothing changed, only
+     * that this response is not reporting one, so a client must still tolerate a stale ceiling.
+     *
+     * Never `false`. A widened or dropped ceiling costs one discovery call; one left too low
+     * refuses a purchase the backend would have served, so the uncertain direction is to send it.
+     */
+    refreshLimits?: true;
 };
 /**
  * Provider is absent only when routing ended before a provider could be selected. A BLOCKED response

package/package.json

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