@fun-xyz/fiat-contract 0.8.0 → 0.10.0

package/README.md

@@ -33,7 +33,9 @@ Source of truth: [Fiat Client Contract](https://app.notion.com/p/3b9fc3b2a002815
 [Fiat Frontend — State Machine & Screen Map](https://app.notion.com/p/3bbfc3b2a00281c994c2cebd17b1d6d3)
 (✅ Decisions · per-screen State details · Event bindings per flow state), plus
 [Fiat KYC — User Flow & API Interfaces](https://app.notion.com/p/3cefc3b2a00281c88e7fe771f0c64332)
-for quote-bound KYC states and endpoints.
+for quote-bound KYC states and endpoints, and
+[Fiat Routing Engine — Provider Selection, Ranking & Commit](https://app.notion.com/p/3d1fc3b2a00281f2b604c20869ac420a)
+for quote-screen limits, provider auth channels, and blocked reasons.
 Tracking: [Headless Fiat Onramp](https://linear.app/funxyz/project/headless-fiat-onramp-0147f4102399) ·
 this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
 
@@ -57,6 +59,11 @@ 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 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.
 
 ## Versioning — the package version IS the table version
 

package/dist/{chunk-LVVQ46YG.mjs → chunk-BAGIBS54.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.8.0";
+var version = "0.10.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -105,6 +105,8 @@ var TRANSITION_TABLE = {
     ],
     mayReturn: [
       "SESSION_AUTH",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
       ...KYC_ANY,
       "ORDER/AWAITING_CONFIRMATION",
       "PENDING_ORDER"
@@ -498,4 +500,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-LVVQ46YG.mjs.map
+//# sourceMappingURL=chunk-BAGIBS54.mjs.map

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthChallengeSchema: () => AuthChallengeSchema,
+  BlockedReasonSchema: () => BlockedReasonSchema,
   BlockedStateSchema: () => BlockedStateSchema,
   COUNTRY_NAMES: () => COUNTRY_NAMES,
   COUNTRY_TO_CURRENCY: () => COUNTRY_TO_CURRENCY,
@@ -65,6 +66,8 @@ __export(index_exports, {
   PaymentInstructStateSchema: () => PaymentInstructStateSchema,
   PendingOrderStateSchema: () => PendingOrderStateSchema,
   PollSpecSchema: () => PollSpecSchema,
+  QuoteLimitRangeSchema: () => QuoteLimitRangeSchema,
+  QuoteLimitsSchema: () => QuoteLimitsSchema,
   QuoteSchema: () => QuoteSchema,
   QuoteStateSchema: () => QuoteStateSchema,
   RecoverySchema: () => RecoverySchema,
@@ -387,7 +390,15 @@ var HTTP_VERBS = ["GET", "POST"];
 var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
 var $endpoint = import_zod.z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
 var FiatEndpointSchema = $endpoint;
-var $provider = import_zod.z.enum(["TRANSAK", "SWAPPED", "BANXA", "MOONPAY", "STRIPE"]);
+var $provider = import_zod.z.enum([
+  "TRANSAK",
+  "SWAPPED",
+  "BANXA",
+  "MOONPAY",
+  "STRIPE",
+  "COINBASE",
+  "CROSSMINT"
+]);
 var FiatProviderSchema = $provider;
 var $kycProvider = import_zod.z.enum(["SUMSUB"]);
 var KYCProviderSchema = $kycProvider;
@@ -454,6 +465,14 @@ var $quote = obj({
   expiresAt: import_zod.z.string()
 });
 var QuoteSchema = $quote;
+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;
 var $orderRef = obj({
@@ -484,7 +503,14 @@ var $refund = obj({
   expectedBy: import_zod.z.string()
 });
 var RefundSchema = $refund;
-var $surfaceKind = import_zod.z.enum(["URL_REDIRECT", "KYC_SDK", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]);
+var $surfaceKind = import_zod.z.enum([
+  "URL_REDIRECT",
+  "KYC_SDK",
+  "PCI_COMPONENT",
+  "PAY_SHEET",
+  "ACH_COMPONENT",
+  "AUTH_COMPONENT"
+]);
 var SurfaceKindSchema = $surfaceKind;
 var $surface = obj({
   kind: $surfaceKind,
@@ -629,6 +655,8 @@ var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
   kind: import_zod.z.literal("QUOTE"),
   quote: $quote,
+  limits: $quoteLimits,
+  helper: import_zod.z.string().optional(),
   /** Present when the provider's component is the primary CTA, inline on the entry screen. */
   surface: $surface.optional(),
   error: $failureReason.optional()
@@ -642,7 +670,8 @@ var $funAuthState = obj({
 var FunAuthStateSchema = $funAuthState;
 var $sessionAuthState = obj({
   kind: import_zod.z.literal("SESSION_AUTH"),
-  channel: import_zod.z.literal("EMAIL_OTP"),
+  channel: import_zod.z.enum(["EMAIL_OTP", "SMS_OTP", "PROVIDER_RENDERED"]),
+  surface: $surface.optional(),
   error: $failureReason.optional()
 });
 var SessionAuthStateSchema = $sessionAuthState;
@@ -678,9 +707,16 @@ var $pendingOrderState = obj({
   error: $failureReason.optional()
 });
 var PendingOrderStateSchema = $pendingOrderState;
+var $blockedReason = import_zod.z.enum([
+  "REGION_UNSUPPORTED",
+  "ASSET_UNSUPPORTED",
+  "ALL_PROVIDERS_DECLINED",
+  "AMOUNT_UNSERVABLE"
+]);
+var BlockedReasonSchema = $blockedReason;
 var $blockedState = obj({
   kind: import_zod.z.literal("BLOCKED"),
-  reason: import_zod.z.string(),
+  reason: $blockedReason,
   retryAfter: import_zod.z.string().nullable().optional(),
   error: $failureReason.optional()
 });
@@ -743,7 +779,7 @@ var $stepResponse = obj({
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.8.0";
+var version = "0.10.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -849,6 +885,8 @@ var TRANSITION_TABLE = {
     ],
     mayReturn: [
       "SESSION_AUTH",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
       ...KYC_ANY,
       "ORDER/AWAITING_CONFIRMATION",
       "PENDING_ORDER"
@@ -1233,6 +1271,20 @@ var FIXTURE_DATA = {
   "screen-01-quote": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "500.00"
+          },
+          {
+            "min": "1000.00",
+            "max": "3000.00"
+          }
+        ]
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {
@@ -1277,6 +1329,16 @@ var FIXTURE_DATA = {
   "screen-01b-quote-with-pay-sheet": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "3000.00"
+          }
+        ]
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {
@@ -1788,6 +1850,16 @@ var FIXTURE_DATA = {
   "worked-example-01-quote": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "3000.00"
+          }
+        ]
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-LVVQ46YG.mjs";
+} from "./chunk-BAGIBS54.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -295,7 +295,15 @@ var HTTP_VERBS = ["GET", "POST"];
 var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
 var $endpoint = z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
 var FiatEndpointSchema = $endpoint;
-var $provider = z.enum(["TRANSAK", "SWAPPED", "BANXA", "MOONPAY", "STRIPE"]);
+var $provider = z.enum([
+  "TRANSAK",
+  "SWAPPED",
+  "BANXA",
+  "MOONPAY",
+  "STRIPE",
+  "COINBASE",
+  "CROSSMINT"
+]);
 var FiatProviderSchema = $provider;
 var $kycProvider = z.enum(["SUMSUB"]);
 var KYCProviderSchema = $kycProvider;
@@ -362,6 +370,14 @@ var $quote = obj({
   expiresAt: z.string()
 });
 var QuoteSchema = $quote;
+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;
 var $orderRef = obj({
@@ -392,7 +408,14 @@ var $refund = obj({
   expectedBy: z.string()
 });
 var RefundSchema = $refund;
-var $surfaceKind = z.enum(["URL_REDIRECT", "KYC_SDK", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]);
+var $surfaceKind = z.enum([
+  "URL_REDIRECT",
+  "KYC_SDK",
+  "PCI_COMPONENT",
+  "PAY_SHEET",
+  "ACH_COMPONENT",
+  "AUTH_COMPONENT"
+]);
 var SurfaceKindSchema = $surfaceKind;
 var $surface = obj({
   kind: $surfaceKind,
@@ -537,6 +560,8 @@ var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
   kind: z.literal("QUOTE"),
   quote: $quote,
+  limits: $quoteLimits,
+  helper: z.string().optional(),
   /** Present when the provider's component is the primary CTA, inline on the entry screen. */
   surface: $surface.optional(),
   error: $failureReason.optional()
@@ -550,7 +575,8 @@ var $funAuthState = obj({
 var FunAuthStateSchema = $funAuthState;
 var $sessionAuthState = obj({
   kind: z.literal("SESSION_AUTH"),
-  channel: z.literal("EMAIL_OTP"),
+  channel: z.enum(["EMAIL_OTP", "SMS_OTP", "PROVIDER_RENDERED"]),
+  surface: $surface.optional(),
   error: $failureReason.optional()
 });
 var SessionAuthStateSchema = $sessionAuthState;
@@ -586,9 +612,16 @@ var $pendingOrderState = obj({
   error: $failureReason.optional()
 });
 var PendingOrderStateSchema = $pendingOrderState;
+var $blockedReason = z.enum([
+  "REGION_UNSUPPORTED",
+  "ASSET_UNSUPPORTED",
+  "ALL_PROVIDERS_DECLINED",
+  "AMOUNT_UNSERVABLE"
+]);
+var BlockedReasonSchema = $blockedReason;
 var $blockedState = obj({
   kind: z.literal("BLOCKED"),
-  reason: z.string(),
+  reason: $blockedReason,
   retryAfter: z.string().nullable().optional(),
   error: $failureReason.optional()
 });
@@ -655,6 +688,20 @@ var FIXTURE_DATA = {
   "screen-01-quote": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "500.00"
+          },
+          {
+            "min": "1000.00",
+            "max": "3000.00"
+          }
+        ]
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {
@@ -699,6 +746,16 @@ var FIXTURE_DATA = {
   "screen-01b-quote-with-pay-sheet": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "3000.00"
+          }
+        ]
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {
@@ -1210,6 +1267,16 @@ var FIXTURE_DATA = {
   "worked-example-01-quote": {
     "state": {
       "kind": "QUOTE",
+      "limits": {
+        "min": "1.00",
+        "max": "3000.00",
+        "serviceableRanges": [
+          {
+            "min": "1.00",
+            "max": "3000.00"
+          }
+        ]
+      },
       "quote": {
         "quoteRef": "q_8f2",
         "fiat": {
@@ -1652,6 +1719,7 @@ function assertAllFixtures() {
 }
 export {
   AuthChallengeSchema,
+  BlockedReasonSchema,
   BlockedStateSchema,
   COUNTRY_NAMES,
   COUNTRY_TO_CURRENCY,
@@ -1696,6 +1764,8 @@ export {
   PaymentInstructStateSchema,
   PendingOrderStateSchema,
   PollSpecSchema,
+  QuoteLimitRangeSchema,
+  QuoteLimitsSchema,
   QuoteSchema,
   QuoteStateSchema,
   RecoverySchema,

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 { CryptoAmount, FailureReason, FeeLine, FiatEndpoint, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, Instructions, InstructionField, Instrument, JsonValue, FiatAmount, OrderRef, OrderStatus, OrderSummary, PollSpec, FiatProvider, Quote, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, FiatStepResponse, Surface, SurfaceKind, SurfaceProvider, KYCProvider, Transition, TransitionInputs, TransitionParams, Tx } from './types';
+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';
 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,8 @@ 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>;
 export declare const OrderSummarySchema: z.ZodType<OrderSummary>;
@@ -84,6 +86,7 @@ export declare const KycCaptureStateSchema: z.ZodType<State<'KYC', 'CAPTURE'>>;
 export declare const KycInputRequiredStateSchema: z.ZodType<State<'KYC', 'INPUT_REQUIRED'>>;
 export declare const KycNoActionRequiredStateSchema: z.ZodType<State<'KYC', 'NO_ACTION_REQUIRED'>>;
 export declare const PendingOrderStateSchema: z.ZodType<State<'PENDING_ORDER'>>;
+export declare const BlockedReasonSchema: z.ZodType<BlockedReason>;
 export declare const BlockedStateSchema: z.ZodType<State<'BLOCKED'>>;
 export declare const PaymentCaptureStateSchema: z.ZodType<State<'PAYMENT', 'CAPTURE'>>;
 export declare const PaymentInstructStateSchema: z.ZodType<State<'PAYMENT', 'INSTRUCT'>>;

package/dist/table.js

@@ -36,7 +36,7 @@ __export(table_exports, {
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.8.0";
+var version = "0.10.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -142,6 +142,8 @@ var TRANSITION_TABLE = {
     ],
     mayReturn: [
       "SESSION_AUTH",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
       ...KYC_ANY,
       "ORDER/AWAITING_CONFIRMATION",
       "PENDING_ORDER"

package/dist/table.mjs

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

package/dist/types.d.ts

@@ -61,7 +61,7 @@ export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'P
  * Routing metadata, not sequencing policy. Reserved values may be emitted only after their adapter
  * and conformance fixture land.
  */
-export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA' | 'MOONPAY' | 'STRIPE';
+export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA' | 'MOONPAY' | 'STRIPE' | 'COINBASE' | 'CROSSMINT';
 /**
  * The order status vocabulary. Monotonic ranks, no backwards moves. Terminal outcomes are
  * OrderStatus, never FlowState kinds.
@@ -151,6 +151,24 @@ export interface Quote {
     paymentMethod: PaymentMethodCategory;
     expiresAt: string;
 }
+/** 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 {
     brandLabel: string;
@@ -195,7 +213,7 @@ export interface Refund {
     expectedBy: string;
 }
 /** What the user sees, and therefore where it can be placed. */
-export type SurfaceKind = 'URL_REDIRECT' | 'KYC_SDK' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT';
+export type SurfaceKind = 'URL_REDIRECT' | 'KYC_SDK' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT' | 'AUTH_COMPONENT';
 /**
  * Identity vendors Fun verifies into. Its own axis rather than a `FiatProvider` value, because
  * Fun is the KYC-of-record in its own tenant — an identity surface is never the onramp's to mint.
@@ -424,6 +442,8 @@ export type FlowState =
 {
     kind: 'QUOTE';
     quote: Quote;
+    limits: QuoteLimits;
+    helper?: string;
     surface?: Surface;
     error?: FailureReason;
 } | {
@@ -432,7 +452,8 @@ export type FlowState =
     error?: FailureReason;
 } | {
     kind: 'SESSION_AUTH';
-    channel: 'EMAIL_OTP';
+    channel: 'EMAIL_OTP' | 'SMS_OTP' | 'PROVIDER_RENDERED';
+    surface?: Surface;
     error?: FailureReason;
 }
 /** Pre-order KYC states carry the routed quote so the entry screen can keep price visible. */
@@ -485,11 +506,7 @@ export type FlowState =
     error?: FailureReason;
 } | {
     kind: 'BLOCKED';
-    /**
-     * Observed value: `REGION_UNSUPPORTED` (FE doc Screen 16). The contract types this as
-     * `string`; no enum is published, so none is invented here.
-     */
-    reason: string;
+    reason: BlockedReason;
     /** `null` renders "no comeback date" (FE doc Screen 16 emits it explicitly). */
     retryAfter?: string | null;
     error?: FailureReason;
@@ -527,6 +544,7 @@ export type FlowState =
     error?: FailureReason;
 };
 export type FlowStateKind = FlowState['kind'];
+export type BlockedReason = 'REGION_UNSUPPORTED' | 'ASSET_UNSUPPORTED' | 'ALL_PROVIDERS_DECLINED' | 'AMOUNT_UNSERVABLE';
 /**
  * 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).

package/package.json

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