@fun-xyz/fiat-contract 0.24.0 → 0.25.0

package/README.md

@@ -133,31 +133,38 @@ 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`), never `routingOverrides`, 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.
+
+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

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

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

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

@@ -8,4 +8,4 @@ var ROUTING_ENDPOINTS = {
 export {
   ROUTING_ENDPOINTS
 };
-//# sourceMappingURL=chunk-5UEPWL7B.mjs.map
+//# sourceMappingURL=chunk-WEXD7UEE.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,
@@ -1100,7 +1100,16 @@ var $routingQuoteRequest = obj({
     { message: US_REGION_REQUIRED, path: ["region"] }
   ),
   prepareSessionAuth: import_zod.z.boolean().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 })
+]);
 var FiatRoutingQuoteRequestSchema = $routingQuoteRequest;
 var $routingServiceableRange = obj({ min: $money, max: $money, userMax: $money.nullable().optional() });
 var $noRouteFields = {
@@ -1200,7 +1209,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.24.0";
+var version = "0.25.0";
 
 // src/table.ts
 var TABLE_VERSION = version;

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-IPOPANXS.mjs";
+} from "./chunk-LHCED3AP.mjs";
 import {
   MOONPAY_ENDPOINTS
 } from "./chunk-T5JAYOWY.mjs";
@@ -24,7 +24,7 @@ import {
 } from "./chunk-CRNKRIKR.mjs";
 import {
   ROUTING_ENDPOINTS
-} from "./chunk-5UEPWL7B.mjs";
+} from "./chunk-WEXD7UEE.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,
@@ -965,7 +964,16 @@ var $routingQuoteRequest = obj({
     { message: US_REGION_REQUIRED, path: ["region"] }
   ),
   prepareSessionAuth: z.boolean().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 })
+]);
 var FiatRoutingQuoteRequestSchema = $routingQuoteRequest;
 var $routingServiceableRange = obj({ min: $money, max: $money, userMax: $money.nullable().optional() });
 var $noRouteFields = {
@@ -2287,6 +2295,7 @@ export {
   FiatProviderSchema,
   FiatRoutingQuoteErrorBodySchema,
   FiatRoutingQuoteRequestSchema,
+  FiatRoutingQuoteTermsSchema,
   FiatRoutingTableErrorBodySchema,
   FiatRoutingTableQuerySchema,
   FiatRoutingTableResponseSchema,

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 `POST /fiat/quote` body without `routingOverrides`: everything but which providers to price. */
+export interface FiatRoutingQuoteTerms {
     fiatCurrency: FiatCurrencyCode;
     /** A positive decimal string with no leading zero, exponent or sign (`"20"`, `"20.5"`). */
     fiatAmount: string;
@@ -107,6 +102,25 @@ export interface FiatRoutingQuoteRequest {
     };
     prepareSessionAuth?: boolean;
 }
+/**
+ * `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 +174,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-WEXD7UEE.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.25.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-LHCED3AP.mjs";
 export {
   DOCUMENTED_ENDPOINTS,
   STATE_KEYS,

package/package.json

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