@fun-xyz/fiat-contract 0.24.0 → 0.27.0

package/README.md

@@ -133,31 +133,43 @@ cause is unknown. Refetch the table at `expiresAt`, on `refreshLimits: true`, an
 a `REQUOTE`. The schemas hold the table's invariants: each method once, sorted, non-overlapping
 intervals, at least one provider each and none twice, and a reason only on an empty method.
 
-`ROUTING_ENDPOINTS.quote` (`POST /fiat/routing/quote`) takes the `POST /fiat/quote` body plus the
-interval's first `provider`, never `routingOverrides`, and answers the same `FiatStepResponse`. A
-refusal is a `FiatRoutingQuoteErrorBody`, and it decides whether to quote the interval's next
-provider:
+`ROUTING_ENDPOINTS.quote` (`POST /fiat/routing/quote`) takes the `POST /fiat/quote` body
+(`FiatRoutingQuoteTerms`), plus one of two forms:
+
+- `providers`: the interval's providers, best first. The backend prices them in order, falls
+  through on the refusals marked "next provider" below, and answers the first that prices or the
+  last provider's refusal.
+- `provider`: one provider only. The client falls through itself.
+
+Routing quotes may include `routingOverrides: { providers: [...] }` with the host’s full allowlist.
+The selected `provider` or ordered `providers` must be a subset. The server preserves the allowlist
+through later KYC rerouting; the amount-specific candidate list alone does not restrict rediscovery.
+Omitting the field preserves existing behavior. An empty allowlist permits no quote candidate.
+
+It answers the same `FiatStepResponse`, whose `provider` names the one that priced. A refusal is a
+`FiatRoutingQuoteErrorBody`, and it decides whether the next provider may still price:
 
 | Status | `errorCode` | Then |
 | --- | --- | --- |
-| 404 | `FiatNoRouteError`, `reason` `NO_CANDIDATE`, `PROVIDER_DECLINED`, `PROVIDER_OUTAGE` or `KYC_REJECTED` | quote the next provider |
-| 400 | `FiatNoRouteError`, `reason: USER_LIMIT`, `code: LIMITS_EXCEEDED`, `recovery: REQUOTE` | quote the next provider |
-| 400 | `FiatAmountBelowMinimumError` (`minFiatAmount`) or `FiatAmountAboveMaximumError` (`maxFiatAmount`) | quote the next provider |
+| 404 | `FiatNoRouteError`, `reason` `NO_CANDIDATE`, `PROVIDER_DECLINED`, `PROVIDER_OUTAGE` or `KYC_REJECTED` | next provider |
+| 400 | `FiatNoRouteError`, `reason: USER_LIMIT`, `code: LIMITS_EXCEEDED`, `recovery: REQUOTE` | next provider |
+| 400 | `FiatAmountBelowMinimumError` (`minFiatAmount`) or `FiatAmountAboveMaximumError` (`maxFiatAmount`) | next provider |
 | 400 | `InvalidParameterError`: a bad request, an asset Fun cannot deliver, or no verified email | stop |
 | 401, 5xx | any other: a missing or invalid identity assertion, or a server error | stop |
 
-Every fall-through refusal is the named provider's alone, because the route prices only that
-provider: `KYC_REJECTED` there means that provider refused the buyer's identity, not every provider.
-With no provider left in the interval, refetch the table. The table route refuses with a
+Every fall-through refusal is that provider's alone, because each attempt prices only one provider:
+`KYC_REJECTED` there means that provider refused the buyer's identity, not every provider. With no
+provider left in the interval, refetch the table. The table route refuses with a
 `FiatRoutingTableErrorBody`: a 429 `TooManyRequestsError` with `retryAfterSeconds` when the
 per-login budget is spent, or a 400 or 5xx as above. The quote route has no rate limit of its own.
 
 Both routes take geo under the `POST /fiat/quote` rules: a known `CountryCode`, a `UsStateCode`
 region for a US buyer, and an empty `region` or `ip` read as absent. The quote route's `geo` is the
 Fun geo endpoint's response forwarded as is. The request schemas are strict like every schema here,
-so a client sends only the declared keys and no blank strings. `provider` is one of the five
-providers the backend routes (`RoutingProvider`). The quote route is temporary: `POST /fiat/next`
-replaces it for each provider that moves there.
+so a client sends only the declared keys and no blank strings. `provider` and each `providers`
+entry are one of the five providers the backend routes (`RoutingProvider`), `providers` with no
+duplicates. The quote route is temporary: `POST /fiat/next` replaces it for each provider that
+moves there.
 
 **MoonPay (`./moonpay`).** MoonPay runs on the shared `POST /fiat/next` (`MOONPAY_ENDPOINTS.next`).
 Every `/next` body is a `FiatNextRequest`: `provider`, `geo` (a `FiatGeo`, the geo endpoint's
@@ -196,8 +208,9 @@ A first-time buyer goes `observe` → `consent` → `connect` → `kyc` → `wai
 `test/fixtures/moonpay-next/`.
 
 A fault is a 4xx or 5xx with a `MoonPayErrorBody`: the shared `errorCode`, `errorMsg` and `reqId`,
-plus `reason` (`SESSION_BUDGET_SPENT`, `RATE_LIMITED`, `PROVIDER_UNAVAILABLE`, `INVALID_REQUEST`)
-and `recovery`:
+plus `reason` and `recovery`. The reasons are `SESSION_BUDGET_SPENT`, `RATE_LIMITED`,
+`PROVIDER_UNAVAILABLE` (MoonPay is down), `KYC_PROVIDER_UNAVAILABLE` (Sumsub is down),
+`SERVICE_UNAVAILABLE` (one of Fun's own stores is down) and `INVALID_REQUEST`. The recoveries are
 `RETRY` (send the same request again), `REQUOTE`, or `NONE`. A field error is a `kyc`
 prompt, not a fault. The zod schemas (`MoonPay*Schema`, `FiatGeoSchema`, `FiatNextRequestSchema`,
 `TermsDocumentSchema`, `FiatTerms*Schema`) are exported from the root only.

package/dist/{chunk-5UEPWL7B.mjs → chunk-7ZIZANFX.mjs}

@@ -8,4 +8,4 @@ var ROUTING_ENDPOINTS = {
 export {
   ROUTING_ENDPOINTS
 };
-//# sourceMappingURL=chunk-5UEPWL7B.mjs.map
+//# sourceMappingURL=chunk-7ZIZANFX.mjs.map

package/dist/{chunk-IPOPANXS.mjs → chunk-K573F2ON.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.24.0";
+var version = "0.27.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -514,4 +514,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-IPOPANXS.mjs.map
+//# sourceMappingURL=chunk-K573F2ON.mjs.map

package/dist/{chunk-T5JAYOWY.mjs → chunk-W5HOOK34.mjs}

@@ -6,4 +6,4 @@ var MOONPAY_ENDPOINTS = {
 export {
   MOONPAY_ENDPOINTS
 };
-//# sourceMappingURL=chunk-T5JAYOWY.mjs.map
+//# sourceMappingURL=chunk-W5HOOK34.mjs.map

package/dist/index.js

@@ -47,6 +47,7 @@ __export(index_exports, {
   FiatProviderSchema: () => FiatProviderSchema,
   FiatRoutingQuoteErrorBodySchema: () => FiatRoutingQuoteErrorBodySchema,
   FiatRoutingQuoteRequestSchema: () => FiatRoutingQuoteRequestSchema,
+  FiatRoutingQuoteTermsSchema: () => FiatRoutingQuoteTermsSchema,
   FiatRoutingTableErrorBodySchema: () => FiatRoutingTableErrorBodySchema,
   FiatRoutingTableQuerySchema: () => FiatRoutingTableQuerySchema,
   FiatRoutingTableResponseSchema: () => FiatRoutingTableResponseSchema,
@@ -1088,8 +1089,7 @@ var $routingTableResponse = obj({
   methods: import_zod.z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once")
 });
 var FiatRoutingTableResponseSchema = $routingTableResponse;
-var $routingQuoteRequest = obj({
-  provider: $routingProvider,
+var $routingQuoteTermsShape = {
   fiatCurrency: import_zod.z.enum(FIAT_CURRENCY_CODES),
   fiatAmount: $decimalAmount.refine((amount) => Number(amount) > 0, "must be positive"),
   cryptoCurrencyCode: $nonBlank,
@@ -1099,8 +1099,25 @@ var $routingQuoteRequest = obj({
     (geo) => hasUsRegion(geo.alpha2, geo.region),
     { message: US_REGION_REQUIRED, path: ["region"] }
   ),
-  prepareSessionAuth: import_zod.z.boolean().optional()
-});
+  prepareSessionAuth: import_zod.z.boolean().optional(),
+  routingOverrides: obj({ providers: import_zod.z.array($routingProvider) }).optional()
+};
+var $routingQuoteTerms = obj($routingQuoteTermsShape);
+var FiatRoutingQuoteTermsSchema = $routingQuoteTerms;
+var $routingQuoteRequest = import_zod.z.union([
+  obj({
+    ...$routingQuoteTermsShape,
+    providers: import_zod.z.array($routingProvider).min(1).refine((providers) => hasUniqueIds(providers), "each provider is listed once")
+  }),
+  obj({ ...$routingQuoteTermsShape, provider: $routingProvider })
+]).refine(
+  (request) => {
+    const allowed = request.routingOverrides?.providers;
+    const selected = "providers" in request ? request.providers : [request.provider];
+    return allowed === void 0 || selected.every((provider) => allowed.includes(provider));
+  },
+  { message: "requested providers must be allowed by routingOverrides", path: ["routingOverrides"] }
+);
 var FiatRoutingQuoteRequestSchema = $routingQuoteRequest;
 var $routingServiceableRange = obj({ min: $money, max: $money, userMax: $money.nullable().optional() });
 var $noRouteFields = {
@@ -1200,7 +1217,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.24.0";
+var version = "0.27.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -2938,7 +2955,14 @@ var MoonPayResponseSchemaFor = {
   order: MoonPayOrderResponseSchema
 };
 var $faultFields = {
-  reason: import_zod2.z.enum(["SESSION_BUDGET_SPENT", "RATE_LIMITED", "PROVIDER_UNAVAILABLE", "INVALID_REQUEST"]),
+  reason: import_zod2.z.enum([
+    "SESSION_BUDGET_SPENT",
+    "RATE_LIMITED",
+    "PROVIDER_UNAVAILABLE",
+    "KYC_PROVIDER_UNAVAILABLE",
+    "SERVICE_UNAVAILABLE",
+    "INVALID_REQUEST"
+  ]),
   recovery: import_zod2.z.enum(["RETRY", "REQUOTE", "NONE"])
 };
 var $fault = obj2($faultFields);

package/dist/index.mjs

@@ -12,10 +12,10 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-IPOPANXS.mjs";
+} from "./chunk-K573F2ON.mjs";
 import {
   MOONPAY_ENDPOINTS
-} from "./chunk-T5JAYOWY.mjs";
+} from "./chunk-W5HOOK34.mjs";
 import {
   FIAT_TERMS_ENDPOINT,
   FUN_KYC_CONSENT_DOCUMENTS,
@@ -24,7 +24,7 @@ import {
 } from "./chunk-CRNKRIKR.mjs";
 import {
   ROUTING_ENDPOINTS
-} from "./chunk-5UEPWL7B.mjs";
+} from "./chunk-7ZIZANFX.mjs";
 
 // src/codes.ts
 var US_STATE_CODES = [
@@ -953,8 +953,7 @@ var $routingTableResponse = obj({
   methods: z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once")
 });
 var FiatRoutingTableResponseSchema = $routingTableResponse;
-var $routingQuoteRequest = obj({
-  provider: $routingProvider,
+var $routingQuoteTermsShape = {
   fiatCurrency: z.enum(FIAT_CURRENCY_CODES),
   fiatAmount: $decimalAmount.refine((amount) => Number(amount) > 0, "must be positive"),
   cryptoCurrencyCode: $nonBlank,
@@ -964,8 +963,25 @@ var $routingQuoteRequest = obj({
     (geo) => hasUsRegion(geo.alpha2, geo.region),
     { message: US_REGION_REQUIRED, path: ["region"] }
   ),
-  prepareSessionAuth: z.boolean().optional()
-});
+  prepareSessionAuth: z.boolean().optional(),
+  routingOverrides: obj({ providers: z.array($routingProvider) }).optional()
+};
+var $routingQuoteTerms = obj($routingQuoteTermsShape);
+var FiatRoutingQuoteTermsSchema = $routingQuoteTerms;
+var $routingQuoteRequest = z.union([
+  obj({
+    ...$routingQuoteTermsShape,
+    providers: z.array($routingProvider).min(1).refine((providers) => hasUniqueIds(providers), "each provider is listed once")
+  }),
+  obj({ ...$routingQuoteTermsShape, provider: $routingProvider })
+]).refine(
+  (request) => {
+    const allowed = request.routingOverrides?.providers;
+    const selected = "providers" in request ? request.providers : [request.provider];
+    return allowed === void 0 || selected.every((provider) => allowed.includes(provider));
+  },
+  { message: "requested providers must be allowed by routingOverrides", path: ["routingOverrides"] }
+);
 var FiatRoutingQuoteRequestSchema = $routingQuoteRequest;
 var $routingServiceableRange = obj({ min: $money, max: $money, userMax: $money.nullable().optional() });
 var $noRouteFields = {
@@ -2252,7 +2268,14 @@ var MoonPayResponseSchemaFor = {
   order: MoonPayOrderResponseSchema
 };
 var $faultFields = {
-  reason: z2.enum(["SESSION_BUDGET_SPENT", "RATE_LIMITED", "PROVIDER_UNAVAILABLE", "INVALID_REQUEST"]),
+  reason: z2.enum([
+    "SESSION_BUDGET_SPENT",
+    "RATE_LIMITED",
+    "PROVIDER_UNAVAILABLE",
+    "KYC_PROVIDER_UNAVAILABLE",
+    "SERVICE_UNAVAILABLE",
+    "INVALID_REQUEST"
+  ]),
   recovery: z2.enum(["RETRY", "REQUOTE", "NONE"])
 };
 var $fault = obj2($faultFields);
@@ -2287,6 +2310,7 @@ export {
   FiatProviderSchema,
   FiatRoutingQuoteErrorBodySchema,
   FiatRoutingQuoteRequestSchema,
+  FiatRoutingQuoteTermsSchema,
   FiatRoutingTableErrorBodySchema,
   FiatRoutingTableQuerySchema,
   FiatRoutingTableResponseSchema,

package/dist/providers/moonpay.d.ts

@@ -188,10 +188,11 @@ export type MoonPayResponseFor = {
 export type MoonPayRecovery = 'RETRY' | 'REQUOTE' | 'NONE';
 /**
  * `SESSION_BUDGET_SPENT`: the per-login SDK session mint budget (429). `RATE_LIMITED`: the action's
- * request budget (429). `PROVIDER_UNAVAILABLE`: MoonPay or Sumsub is down. `INVALID_REQUEST`: a bad
- * body (400).
+ * request budget (429). `PROVIDER_UNAVAILABLE`: MoonPay is down (503). `KYC_PROVIDER_UNAVAILABLE`:
+ * the KYC provider (Sumsub) is down (503). `SERVICE_UNAVAILABLE`: one of Fun's own stores is down
+ * (503). `INVALID_REQUEST`: a bad body (400).
  */
-export type MoonPayFaultReason = 'SESSION_BUDGET_SPENT' | 'RATE_LIMITED' | 'PROVIDER_UNAVAILABLE' | 'INVALID_REQUEST';
+export type MoonPayFaultReason = 'SESSION_BUDGET_SPENT' | 'RATE_LIMITED' | 'PROVIDER_UNAVAILABLE' | 'KYC_PROVIDER_UNAVAILABLE' | 'SERVICE_UNAVAILABLE' | 'INVALID_REQUEST';
 /** The fields a MoonPay fault adds to the shared error body. */
 export interface MoonPayFault {
     reason: MoonPayFaultReason;

package/dist/providers/moonpay.mjs

@@ -1,6 +1,6 @@
 import {
   MOONPAY_ENDPOINTS
-} from "../chunk-T5JAYOWY.mjs";
+} from "../chunk-W5HOOK34.mjs";
 export {
   MOONPAY_ENDPOINTS
 };

package/dist/routing.d.ts

@@ -82,13 +82,8 @@ export interface FiatRoutingTableResponse {
     /** In request order, duplicates removed. */
     methods: RoutingTableMethod[];
 }
-/**
- * The `POST /fiat/quote` body plus the one `provider` to price, which is the interval's first
- * provider, and never `routingOverrides`. The response is the same `FiatStepResponse` as
- * `POST /fiat/quote`; a refusal is a `FiatRoutingQuoteErrorBody`.
- */
-export interface FiatRoutingQuoteRequest {
-    provider: RoutingProvider;
+/** The purchase terms and optional host restriction, independent of the current ordered candidates. */
+export interface FiatRoutingQuoteTerms {
     fiatCurrency: FiatCurrencyCode;
     /** A positive decimal string with no leading zero, exponent or sign (`"20"`, `"20.5"`). */
     fiatAmount: string;
@@ -106,7 +101,30 @@ export interface FiatRoutingQuoteRequest {
         city?: string;
     };
     prepareSessionAuth?: boolean;
+    /** Host allowlist, retained for later KYC rerouting. Omitted allows every eligible provider. */
+    routingOverrides?: {
+        providers: RoutingProvider[];
+    };
 }
+/**
+ * `POST /fiat/routing/quote`: the terms plus which providers to price, in one of two forms.
+ *
+ * - `providers`: the interval's providers, best first. The backend prices the first, and falls
+ *   through to the next on a refusal that is that provider's alone (a `FiatNoRouteError` of any
+ *   `reason`, or either amount error), as the client did before. It answers the first provider that
+ *   prices, or the last provider's refusal. Any other refusal stops at once.
+ * - `provider`: one provider only, with no fall-through. Kept for clients that fall through themselves.
+ *
+ * The response is the same `FiatStepResponse` as `POST /fiat/quote`, and its `provider` names the
+ * one that priced. A refusal is a `FiatRoutingQuoteErrorBody`.
+ */
+export type FiatRoutingQuoteRequest = FiatRoutingQuoteTerms & ({
+    providers: RoutingProvider[];
+    provider?: never;
+} | {
+    provider: RoutingProvider;
+    providers?: never;
+});
 /** One serviceable range of the named provider. `userMax` is this buyer's own ceiling inside it, `null` when unmeasured. */
 export interface RoutingServiceableRange {
     min: FiatAmount;
@@ -160,8 +178,9 @@ export type RoutingFaultErrorBody = ErrorBodyFields & {
 export type FiatRoutingTableErrorBody = RoutingRateLimitedErrorBody | RoutingFaultErrorBody;
 /**
  * `POST /fiat/routing/quote` refusals. A `FiatNoRouteError` (any `reason`) or either amount error is
- * the named provider's alone: quote the interval's next provider. Anything else stops the fall-through:
- * a validation or auth refusal, a 5xx, or no provider left to try.
+ * the named provider's alone, so the next provider may still price: with `providers` the backend
+ * tries it, with `provider` the client does. Anything else stops the fall-through: a validation or
+ * auth refusal, a 5xx, or no provider left to try.
  */
 export type FiatRoutingQuoteErrorBody = RoutingNoRouteErrorBody | RoutingAmountErrorBody | RoutingFaultErrorBody;
 export {};

package/dist/routing.mjs

@@ -1,6 +1,6 @@
 import {
   ROUTING_ENDPOINTS
-} from "./chunk-5UEPWL7B.mjs";
+} from "./chunk-7ZIZANFX.mjs";
 export {
   ROUTING_ENDPOINTS
 };

package/dist/schemas.d.ts

@@ -30,7 +30,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, PreparedPayment, PaymentSurface, Quote, QuoteLimitRange, QuoteLimits, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, Surface, PreferredIdentityDocument, KycFieldId, ClientExecutedDelivery, KycSdkResultReport, SurfaceKind, SurfaceProvider, TermsAcceptance, Transition, TransitionInputs, TransitionParams, Tx, FiatGeo, FiatNextRequest } from './types';
 import type { FiatTermsErrorBody, FiatTermsRequest, FiatTermsResponse, TermsDocument, TermsDocumentAcceptance } from './terms';
-import type { FiatRoutingQuoteErrorBody, FiatRoutingQuoteRequest, FiatRoutingTableErrorBody, FiatRoutingTableQuery, FiatRoutingTableResponse } from './routing';
+import type { FiatRoutingQuoteErrorBody, FiatRoutingQuoteRequest, FiatRoutingQuoteTerms, FiatRoutingTableErrorBody, FiatRoutingTableQuery, FiatRoutingTableResponse } from './routing';
 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. */
@@ -114,6 +114,7 @@ export declare const FiatTermsResponseSchema: z.ZodType<FiatTermsResponse>;
 export declare const FiatTermsErrorBodySchema: z.ZodType<FiatTermsErrorBody>;
 export declare const FiatRoutingTableQuerySchema: z.ZodType<FiatRoutingTableQuery>;
 export declare const FiatRoutingTableResponseSchema: z.ZodType<FiatRoutingTableResponse>;
+export declare const FiatRoutingQuoteTermsSchema: z.ZodType<FiatRoutingQuoteTerms>;
 export declare const FiatRoutingQuoteRequestSchema: z.ZodType<FiatRoutingQuoteRequest>;
 export declare const FiatRoutingTableErrorBodySchema: z.ZodType<FiatRoutingTableErrorBody>;
 export declare const FiatRoutingQuoteErrorBodySchema: z.ZodType<FiatRoutingQuoteErrorBody>;

package/dist/table.js

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

package/dist/table.mjs

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

package/package.json

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