@fun-xyz/fiat-contract 0.15.0 → 0.17.0

package/README.md

@@ -85,6 +85,13 @@ 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.
+17. **Prepared payment is inert until promotion.** `FiatStepResponse.preparedPayment` may warm a
+    provider-owned payment surface while auth or KYC continues, but its `CLIENT_SURFACE` transition
+    is not active yet. A client exposes it only after a later response makes the same `quoteRef`
+    executable; the prepared surface provider must match the response provider.
 
 ## KYC SDK hints, results, and client delivery
 

package/dist/{chunk-CXYGWKAG.mjs → chunk-TXRBC2P2.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.15.0";
+var version = "0.17.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -514,4 +514,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-CXYGWKAG.mjs.map
+//# sourceMappingURL=chunk-TXRBC2P2.mjs.map

package/dist/index.js

@@ -67,9 +67,11 @@ __export(index_exports, {
   PAYMENT_METHOD_CATEGORIES: () => PAYMENT_METHOD_CATEGORIES,
   PaymentCaptureStateSchema: () => PaymentCaptureStateSchema,
   PaymentInstructStateSchema: () => PaymentInstructStateSchema,
+  PaymentSurfaceSchema: () => PaymentSurfaceSchema,
   PendingOrderStateSchema: () => PendingOrderStateSchema,
   PollSpecSchema: () => PollSpecSchema,
   PreferredIdentityDocumentSchema: () => PreferredIdentityDocumentSchema,
+  PreparedPaymentSchema: () => PreparedPaymentSchema,
   QuoteLimitRangeSchema: () => QuoteLimitRangeSchema,
   QuoteLimitsSchema: () => QuoteLimitsSchema,
   QuoteSchema: () => QuoteSchema,
@@ -671,6 +673,13 @@ var $surface = import_zod.z.union([
   })
 ]);
 var SurfaceSchema = $surface;
+var $paymentSurface = obj({
+  ...$surfaceBase,
+  kind: import_zod.z.enum(["URL_REDIRECT", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]),
+  provider: $provider,
+  delivery: $clientExecutedDelivery.optional()
+});
+var PaymentSurfaceSchema = $paymentSurface;
 var $instructionField = obj({
   id: import_zod.z.string(),
   labelFallback: import_zod.z.string(),
@@ -798,6 +807,11 @@ var $kycSdkResult = import_zod.z.union([
   obj({ outcome: import_zod.z.literal("FAILED"), errorType: import_zod.z.string().trim().min(1) })
 ]);
 var KycSdkResultReportSchema = $kycSdkResult;
+var $clientSurfaceTransition = obj({
+  id: import_zod.z.string(),
+  mode: import_zod.z.literal("CLIENT_SURFACE"),
+  report: $reportSpec
+});
 var $transition = import_zod.z.union([
   obj({
     id: import_zod.z.string(),
@@ -808,9 +822,15 @@ var $transition = import_zod.z.union([
     labelFallback: import_zod.z.string().optional()
   }),
   obj({ id: import_zod.z.string(), mode: import_zod.z.literal("AWAIT"), poll: $pollSpec }),
-  obj({ id: import_zod.z.string(), mode: import_zod.z.literal("CLIENT_SURFACE"), report: $reportSpec })
+  $clientSurfaceTransition
 ]);
 var TransitionSchema = $transition;
+var $preparedPayment = obj({
+  quoteRef: import_zod.z.string().trim().min(1),
+  surface: $paymentSurface,
+  transition: $clientSurfaceTransition
+});
+var PreparedPaymentSchema = $preparedPayment;
 var $authChallenge = import_zod.z.record(import_zod.z.string(), JsonSchema);
 var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
@@ -841,6 +861,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;
@@ -936,6 +957,7 @@ var $providerBoundStepResponse = obj({
   state: $providerBoundFlowState,
   provider: $provider,
   transitions: import_zod.z.array($transition),
+  preparedPayment: $preparedPayment.optional(),
   routingSessionRef: import_zod.z.string().optional(),
   providerAuthToken: obj({
     clientSecret: import_zod.z.string(),
@@ -943,6 +965,14 @@ var $providerBoundStepResponse = obj({
   }).optional(),
   orderId: import_zod.z.string().optional(),
   refreshLimits: import_zod.z.literal(true).optional()
+}).superRefine((response, context) => {
+  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
+    context.addIssue({
+      code: "custom",
+      path: ["preparedPayment", "surface", "provider"],
+      message: "preparedPayment.surface.provider must match the response provider"
+    });
+  }
 });
 var $blockedStepResponse = obj({
   state: $blockedState,
@@ -960,7 +990,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.15.0";
+var version = "0.17.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -1790,7 +1820,8 @@ var FIXTURE_DATA = {
           }
         },
         "expiresAt": "\u2026"
-      }
+      },
+      "correctionReason": "The image is too blurry. Upload a clearer photo of this document."
     },
     "provider": "TRANSAK",
     "transitions": [
@@ -2254,7 +2285,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-CXYGWKAG.mjs";
+} from "./chunk-TXRBC2P2.mjs";
 
 // src/codes.ts
 var US_STATE_CODES = [
@@ -568,6 +568,13 @@ var $surface = z.union([
   })
 ]);
 var SurfaceSchema = $surface;
+var $paymentSurface = obj({
+  ...$surfaceBase,
+  kind: z.enum(["URL_REDIRECT", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]),
+  provider: $provider,
+  delivery: $clientExecutedDelivery.optional()
+});
+var PaymentSurfaceSchema = $paymentSurface;
 var $instructionField = obj({
   id: z.string(),
   labelFallback: z.string(),
@@ -695,6 +702,11 @@ var $kycSdkResult = z.union([
   obj({ outcome: z.literal("FAILED"), errorType: z.string().trim().min(1) })
 ]);
 var KycSdkResultReportSchema = $kycSdkResult;
+var $clientSurfaceTransition = obj({
+  id: z.string(),
+  mode: z.literal("CLIENT_SURFACE"),
+  report: $reportSpec
+});
 var $transition = z.union([
   obj({
     id: z.string(),
@@ -705,9 +717,15 @@ var $transition = z.union([
     labelFallback: z.string().optional()
   }),
   obj({ id: z.string(), mode: z.literal("AWAIT"), poll: $pollSpec }),
-  obj({ id: z.string(), mode: z.literal("CLIENT_SURFACE"), report: $reportSpec })
+  $clientSurfaceTransition
 ]);
 var TransitionSchema = $transition;
+var $preparedPayment = obj({
+  quoteRef: z.string().trim().min(1),
+  surface: $paymentSurface,
+  transition: $clientSurfaceTransition
+});
+var PreparedPaymentSchema = $preparedPayment;
 var $authChallenge = z.record(z.string(), JsonSchema);
 var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
@@ -738,6 +756,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;
@@ -833,6 +852,7 @@ var $providerBoundStepResponse = obj({
   state: $providerBoundFlowState,
   provider: $provider,
   transitions: z.array($transition),
+  preparedPayment: $preparedPayment.optional(),
   routingSessionRef: z.string().optional(),
   providerAuthToken: obj({
     clientSecret: z.string(),
@@ -840,6 +860,14 @@ var $providerBoundStepResponse = obj({
   }).optional(),
   orderId: z.string().optional(),
   refreshLimits: z.literal(true).optional()
+}).superRefine((response, context) => {
+  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
+    context.addIssue({
+      code: "custom",
+      path: ["preparedPayment", "surface", "provider"],
+      message: "preparedPayment.surface.provider must match the response provider"
+    });
+  }
 });
 var $blockedStepResponse = obj({
   state: $blockedState,
@@ -1185,7 +1213,8 @@ var FIXTURE_DATA = {
           }
         },
         "expiresAt": "\u2026"
-      }
+      },
+      "correctionReason": "The image is too blurry. Upload a clearer photo of this document."
     },
     "provider": "TRANSAK",
     "transitions": [
@@ -1649,7 +1678,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",
@@ -1964,9 +1996,11 @@ export {
   PAYMENT_METHOD_CATEGORIES,
   PaymentCaptureStateSchema,
   PaymentInstructStateSchema,
+  PaymentSurfaceSchema,
   PendingOrderStateSchema,
   PollSpecSchema,
   PreferredIdentityDocumentSchema,
+  PreparedPaymentSchema,
   QuoteLimitRangeSchema,
   QuoteLimitsSchema,
   QuoteSchema,

package/dist/schemas.d.ts

@@ -28,7 +28,7 @@
  */
 import { z } from 'zod';
 import type { UsStateCode } from './codes';
-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';
+import type { BlockedReason, CryptoAmount, FailureReason, FeeLine, FiatAmount, FiatEndpoint, FiatProvider, FiatStepResponse, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, InstructionField, Instructions, Instrument, JsonValue, KYCProvider, OrderRef, OrderStatus, OrderSummary, PollSpec, PreparedPayment, PaymentSurface, 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. */
@@ -59,6 +59,7 @@ export declare const STANDARD_KYC_FIELD_IDS: readonly ["LEGAL_FIRST_NAME", "LEGA
 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 PaymentSurfaceSchema: z.ZodType<PaymentSurface>;
 export declare const InstructionFieldSchema: z.ZodType<InstructionField>;
 export declare const InstructionsSchema: z.ZodType<Instructions>;
 export declare const SelectOptionSchema: z.ZodType<SelectOption>;
@@ -80,6 +81,7 @@ 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 PreparedPaymentSchema: z.ZodType<PreparedPayment>;
 export declare const AuthChallengeSchema: z.ZodType<Record<string, JsonValue>>;
 /** `Extract` keeps each per-state export pinned to the union member it validates. */
 type State<K extends FlowState['kind'], P = never> = [P] extends [never] ? Extract<FlowState, {

package/dist/table.js

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

package/dist/table.mjs

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

package/dist/types.d.ts

@@ -293,6 +293,12 @@ export type Surface = (SurfaceBase & {
     /** Adapter-owned submission mechanics; the shared contract declares only the safe source. */
     delivery?: ClientExecutedDelivery;
 });
+/** Provider-owned surfaces that can execute a payment after the quote becomes executable. */
+export type PaymentSurfaceKind = 'URL_REDIRECT' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT';
+export type PaymentSurface = Surface & {
+    kind: PaymentSurfaceKind;
+    provider: FiatProvider;
+};
 export interface InstructionField {
     id: string;
     labelFallback: string;
@@ -506,6 +512,20 @@ export type Transition = {
     mode: 'CLIENT_SURFACE';
     report: ReportSpec;
 };
+/**
+ * A payment surface prepared ahead of the flow state that may execute it.
+ *
+ * This is inert response metadata, not an active transition. A client may warm the surface while
+ * completing auth or KYC, but must expose or report it only after a later response makes the same
+ * quote executable. `quoteRef` is explicit so that promotion never relies on provider-owned params.
+ */
+export interface PreparedPayment {
+    quoteRef: string;
+    surface: PaymentSurface;
+    transition: Extract<Transition, {
+        mode: 'CLIENT_SURFACE';
+    }>;
+}
 /**
  * TODO(open-decision): shape owned by the auth spike (contract §Auth & ref binding, item 5).
  * `FUN_AUTH` never renders in fomo (identity is ambient), so nothing in either doc constrains
@@ -553,6 +573,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';
@@ -687,6 +712,8 @@ export type FiatStepResponse = (FiatStepResponseBase & {
         kind: 'BLOCKED';
     }>;
     provider: FiatProvider;
+    /** Optional future payment artifact; never one of this response's currently active transitions. */
+    preparedPayment?: PreparedPayment;
 });
 export {};
 //# sourceMappingURL=types.d.ts.map

package/package.json

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