@fun-xyz/fiat-contract 0.22.2 → 0.24.0

package/README.md

@@ -13,15 +13,16 @@ Four things, zero runtime logic beyond validation:
 | `src/table.ts` | the transition table **as data**: per state, its legal transition set, the states any call from it may return, and `terminal: boolean` |
 | `src/assert.ts` + `src/fixtures/` | `assertFiatStepResponse` · `assertLegalEmission` · `assertLegalReturn` · `walkTable` · fixture loader + 18 recorded step responses (inlined as data — no filesystem, so React Native can bundle it) |
 
-## Five entry points — production vs test-time
+## Six entry points — production vs test-time
 
 | Import | Weight | Contains | Used by |
 | --- | --- | --- | --- |
 | `@fun-xyz/fiat-contract/types` | **0.1 KB** (types erase) | every type; no runtime values | production, both repos |
 | `@fun-xyz/fiat-contract/table` | **13.8 KB**, zero deps | `TRANSITION_TABLE`, `stateKey`, `tableEntry`, `isTerminal`, `walkTable`, `TABLE_VERSION`, `TERMINAL_ORDER_STATUSES`, `DOCUMENTED_ENDPOINTS`, `UNOFFERED_ENDPOINTS`, `UNREACHABLE_STATES`, `unofferedEndpoints`, `unreachableStates` | **production frontend** + backend |
-| `@fun-xyz/fiat-contract/moonpay` | zero deps | the MoonPay provider-owned flow: `intent` request kinds, response statuses and fault types, and `MOONPAY_ENDPOINTS` | **production frontend** (MoonPay adapter) + backend |
+| `@fun-xyz/fiat-contract/moonpay` | zero deps | the MoonPay flow on `POST /fiat/next`: action requests, prompts, responses, fault types, and `MOONPAY_ENDPOINTS` | **production frontend** (MoonPay adapter) + backend |
 | `@fun-xyz/fiat-contract/terms` | zero deps | the platform terms route: `TermsDocument`, `FiatTermsRequest`, `FiatTermsResponse`, fault types, and `FIAT_TERMS_ENDPOINT` | **production frontend** + backend |
-| `@fun-xyz/fiat-contract` | 47.6 KB, needs zod | the above + 46 zod schemas + assertions + 18 fixtures | tests, and backend dev/test guards |
+| `@fun-xyz/fiat-contract/routing` | zero deps | the routing table and routing quote: `FiatRoutingTableQuery`, `FiatRoutingTableResponse`, `FiatRoutingQuoteRequest`, both routes' error bodies, and `ROUTING_ENDPOINTS` | **production frontend** + backend |
+| `@fun-xyz/fiat-contract` | 47.6 KB, needs zod | the above + 77 zod schemas + assertions + 18 fixtures | tests, and backend dev/test guards |
 
 `./table` is not a micro-optimisation. Terminality is table data a **shipped** client must read
 (litmus rule 3 — clients never infer it), and Metro has no cross-module tree-shaking on by default,
@@ -101,7 +102,7 @@ A provider can run its own flow instead of the shared step machine. `POST /fiat/
 and prices. When the request's `handoffs` lists the winning provider, the response carries
 `handoff: { provider }` and no transitions. The client shows that provider's `CHECKOUT` documents
 from `PROVIDER_CHECKOUT_DOCUMENTS`, records them with `POST /fiat/terms` on Continue, and then calls
-`POST /fiat/providers/{provider}/intent`. The schema refuses a handoff on any state but `QUOTE`, a
+`POST /fiat/next`. The schema refuses a handoff on any state but `QUOTE`, a
 handoff to a provider other than the response's own, and a handoff that still offers transitions.
 
 **Terms (`./terms`).** Every provider records acceptances through the platform `POST /fiat/terms`
@@ -120,48 +121,86 @@ text. `PROVIDER_CHECKOUT_DOCUMENTS` maps each provider to its current `CHECKOUT`
 stays valid: the backend refuses only an unknown version, a wrong digest, or an `acceptedAt` older
 than 5 minutes. A repeat of a version the login already holds writes nothing and returns the ids.
 
-**MoonPay (`./moonpay`).** One route, `MOONPAY_ENDPOINTS.intent`. A `MoonPayIntentRequest` is one of
-three kinds:
-
-| `kind` | Carries | A repeat |
-| --- | --- | --- |
-| `observe` | `checkout`, and `credentials` (`customerId`, `accessToken`) once the SDK has them | writes nothing new |
-| `kyc` | `checkout`, `credentials`, `values` keyed by `KycFieldId` (no form id) | drops values MoonPay no longer asks for |
-| `order` | `orderId`, `transactionId?`, `quotedAmount`, `geo?` (the checkout's) | returns the recorded order |
-
-`observe` and `kyc` answer a `MoonPayStepResponse`, which says what the backend needs next:
-
-| `status` | Carries | The client then |
+**Routing table (`./routing`).** `ROUTING_ENDPOINTS.table` (`GET /fiat/routing/table`) answers,
+for each requested method, every amount interval and its providers best first, each with `next`
+(`READY`, `AUTH`, `DECLARATIVE_KYC`, `DOCUMENTARY_KYC`, `PENDING_REVIEW`) and `visibility`. The
+client shows min, max, provider and the Continue label for an amount with no call. A method with no
+interval may carry `unavailableReason`, which is not the step response's `BlockedReason`:
+`USER_LIMIT`, `KYC_REJECTED`, `PROVIDER_OUTAGE`, or `NOT_SERVED` when every provider was ruled out
+for reasons that depend on neither the buyer nor provider health (it does not offer the corridor,
+currency, method or asset, or config has not enabled it). An empty method carries no reason when the
+cause is unknown. Refetch the table at `expiresAt`, on `refreshLimits: true`, and after auth, KYC or
+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:
+
+| Status | `errorCode` | Then |
 | --- | --- | --- |
-| `TERMS` | `stage`, `documents` (at least one, all at `stage`) | sends `POST /fiat/terms`, then `observe` |
-| `SDK_AUTH` | `sessionToken`, `quoteInput`, `resetConnection?` (`true` when the device's MoonPay connection is another buyer's) | resets the connection when asked, runs the MoonPay connection check, then `observe` with credentials |
-| `KYC` | `fields`, `fieldErrors?` (each naming a field in `fields`, with `code?` `PHONE_IN_USE` on `PHONE_NUMBER` or `TAX_ID_IN_USE` on `TAX_IDENTIFIER` when another MoonPay customer holds the value) | shows the shared form, then sends `kyc` |
-| `PENDING` | `retryAfterMs` (at most 60 s) | sends `observe` after the delay, never `kyc` again |
-| `READY` | `orderId`, `quoteInput` | mounts Apple Pay, then sends `order` after the charge |
-| `REFUSED` | `reason` (`NOT_ELIGIBLE`, `DOCUMENTS_REQUIRED`, `FINAL_REJECTION`, `CUSTOMER_MISMATCH`), `recovery: REQUOTE \| NONE` | exits the provider flow |
-
-`order` runs after every charge attempt, a failed one too, and answers a `MoonPayOrderResponse`.
-`transactionId` is optional because a failed charge may have none; without it the backend records the
-failed charges MoonPay lists for `orderId`. `quotedAmount` is the fiat amount the quote showed.
-`geo` is the same object `observe` sends in `checkout`; the order records its `alpha2` as its
-country, and no country without it. A
-failed charge answers `DONE` with the order in `FAILED`, and the client requotes for a new `orderId`.
-After a failed charge with no `transactionId`, the client caps its `PENDING` polls.
-
-| `status` | Carries | The client then |
-| --- | --- | --- |
-| `DONE` | `order`, the `GET /fiat/orders/:orderId` response | shows the shared order status |
-| `PENDING` | `retryAfterMs` (at most 60 s) | sends the same `order` after the delay |
-| `REFUSED` | `reason` (`CUSTOMER_MISMATCH`, `WALLET_MISMATCH`, `UNRECORDABLE`), `recovery: NONE` | exits the provider flow |
-
-`MoonPayIntentResponseFor` maps each `kind` to its union, and `MoonPayIntentResponse` is both.
+| 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 |
+| 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
+`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.
+
+**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
+response), and the provider's own request, which names its `action`. The orchestrator reads
+`provider` and `geo`; the provider's action schema reads the rest. MoonPay's body is a
+`MoonPayNextRequest`, and every MoonPay request also carries the context `checkout` and, after
+`connect`, `credentials` (`customerId`, `accessToken`).
+
+Each `MoonPayAction` has one name. A response's prompt names it in `next` and carries what the
+client needs; the client's request names it in `action` and carries the result:
+
+| Action | Prompt carries | Request carries | A repeat |
+| --- | --- | --- | --- |
+| `observe` | no prompt: the answer is the current prompt | nothing | writes nothing |
+| `consent` | `documents` (at least one, unique ids) | `acceptances`, the `POST /fiat/terms` items | writes nothing new |
+| `connect` | `sessionToken`, `quoteInput`, `resetConnection?` (`true` when the device's MoonPay connection is another buyer's) | `customerId`, `accessToken` | rebinds the same customer |
+| `kyc` | `fields`, `fieldErrors?` (each naming a field in `fields`, with `code?` `PHONE_IN_USE` on `PHONE_NUMBER` or `TAX_ID_IN_USE` on `TAX_IDENTIFIER` when another MoonPay customer holds the value) | `credentials`, `values` keyed by `KycFieldId` (no form id) | drops values MoonPay no longer asks for |
+| `wait` | `retryAfterMs` (at most 60 s) | no request: the client sends `observe` after the delay | |
+| `order` | `orderId`, `quoteInput` | `orderId`, `quotedAmount`, `transactionId?` | returns the recorded order |
+
+Every response is the next prompt, `done`, or `refused` (`MoonPayRefused`), and
+`MoonPayResponseFor` maps each request action to its union. `observe`, `consent`, `connect` and `kyc`
+answer a `MoonPayStepResponse`: any `MoonPayPrompt`, or `refused` with `reason` (`NOT_ELIGIBLE`,
+`DOCUMENTS_REQUIRED`, `FINAL_REJECTION`, `CUSTOMER_MISMATCH`) and `recovery: REQUOTE | NONE`.
+
+`order` runs after every charge attempt, a failed one too, and answers a `MoonPayOrderResponse`:
+`done` with `order`, the `GET /fiat/orders/:orderId` response; `order` again while MoonPay does not
+list the transaction yet; or `refused` with `reason` (`CUSTOMER_MISMATCH`, `WALLET_MISMATCH`,
+`UNRECORDABLE`) and `recovery: NONE`. `transactionId` is optional because a failed charge may have
+none; without it the backend records the failed charges MoonPay lists for `orderId`. `quotedAmount`
+is the fiat amount the device quote showed. The order records the body's `geo.alpha2` as its country.
+A failed charge answers `done` with the order in `FAILED`, and the client requotes for a new `orderId`.
+
+A first-time buyer goes `observe` → `consent` → `connect` → `kyc` → `wait` → `observe` → `order` →
+`done`; a returning buyer `observe` → `connect` → `order` → `done`. Both walks are recorded in
+`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`:
-`RETRY` (send the same request again), `REQUOTE`, or `NONE`. A field error is a `KYC`
-response, not a fault. The zod schemas (`MoonPay*Schema`, `TermsDocumentSchema`, `FiatTerms*Schema`)
-are exported from the root only.
+`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.
 
 ## KYC SDK hints, results, and client delivery
 
@@ -420,7 +459,7 @@ loadFixture('screen-10-kyc-on-hold'); // raw JSON, fresh deep copy, `unknown`
 
 ### Use a schema directly
 
-All 46 schemas are exported when you need to validate a fragment rather than a whole step response.
+All 77 schemas are exported when you need to validate a fragment rather than a whole step response.
 They are typed `z.ZodType<T>`, so you get `.parse` / `.safeParse` / `.optional()` — not `.shape` or
 `.extend`, deliberately.
 
@@ -513,8 +552,8 @@ Dual CJS + ESM, same shape as `@funkit/fun-relay`, because the two consumers loa
 | --- | --- | --- |
 | `require()` must work | `fun-backend/apps/api-server` compiles `module: commonjs` and runs plain node — no bundler | esbuild emits `dist/index.js` (CJS) + `dist/index.mjs` (ESM); `exports` maps `require`/`import`; no `"type": "module"` |
 | Zero Node builtins | `connect-core` is React Native — Metro cannot resolve `node:fs` | fixtures are inlined as generated TS data (`src/fixtures/data.ts`), so nothing touches the filesystem; `platform: browser`, every bare import external |
-| Subpath imports must resolve without `exports` support | Metro only reads `package.json#exports` from RN 0.79 on, and `@funkit/connect-rn` accepts `react-native: >=0.74` | root compat stubs `table.js` / `types.js` / `moonpay.js` / `terms.js` (+ `.d.ts`) that re-export `dist/`. Without them Metro fails with *"Unable to resolve module"* — verified, not theorised. Resolvers that do read `exports` never see the stubs |
-| Production code must not pull zod or fixtures | `connect-core` ships to React Native, where Metro does not tree-shake unused exports by default | five entry points: `./types` (erased), `./table` (13.8 KB, zero deps), `./moonpay` and `./terms` (zero deps), root (schemas + fixtures, test-time). CI asserts `require('.../table')`, `require('.../moonpay')` and `require('.../terms')` never load zod |
+| Subpath imports must resolve without `exports` support | Metro only reads `package.json#exports` from RN 0.79 on, and `@funkit/connect-rn` accepts `react-native: >=0.74` | root compat stubs `table.js` / `types.js` / `moonpay.js` / `terms.js` / `routing.js` (+ `.d.ts`) that re-export `dist/`. Without them Metro fails with *"Unable to resolve module"* — verified, not theorised. Resolvers that do read `exports` never see the stubs |
+| Production code must not pull zod or fixtures | `connect-core` ships to React Native, where Metro does not tree-shake unused exports by default | six entry points: `./types` (erased), `./table` (13.8 KB, zero deps), `./moonpay`, `./terms` and `./routing` (zero deps), root (schemas + fixtures, test-time). CI asserts `require('.../table')`, `require('.../moonpay')`, `require('.../terms')` and `require('.../routing')` never load zod |
 | `.d.ts` must not lock a zod major | Both repos run `skipLibCheck: true`, which turns a broken declaration into a silent `any` | every exported schema is annotated `z.ZodType<T>`, so declarations name only `z.ZodType`; the structural drift checks stay module-private |
 
 Declarations come from `tsc --emitDeclarationOnly`; esbuild only emits JS. The fixture `.json` files

package/dist/chunk-5UEPWL7B.mjs

@@ -0,0 +1,11 @@
+// src/routing.ts
+var ROUTING_ENDPOINTS = {
+  table: "GET /fiat/routing/table",
+  /** Temporary: `POST /fiat/next` replaces it for each provider that moves there. */
+  quote: "POST /fiat/routing/quote"
+};
+
+export {
+  ROUTING_ENDPOINTS
+};
+//# sourceMappingURL=chunk-5UEPWL7B.mjs.map

package/dist/{chunk-5GRPYE2U.mjs → chunk-CRNKRIKR.mjs}

@@ -41,4 +41,4 @@ export {
   FUN_KYC_CONSENT_DOCUMENTS,
   PUBLISHED_TERMS_DOCUMENTS
 };
-//# sourceMappingURL=chunk-5GRPYE2U.mjs.map
+//# sourceMappingURL=chunk-CRNKRIKR.mjs.map

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

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

package/dist/chunk-T5JAYOWY.mjs

@@ -0,0 +1,9 @@
+// src/providers/moonpay.ts
+var MOONPAY_ENDPOINTS = {
+  next: "POST /fiat/next"
+};
+
+export {
+  MOONPAY_ENDPOINTS
+};
+//# sourceMappingURL=chunk-T5JAYOWY.mjs.map

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from './schemas';
 export * from './table';
 export * from './assert';
 export * from './terms';
+export * from './routing';
 export * from './providers/moonpay';
 export * from './providers/moonpay.schemas';
 export { FIXTURES, FIXTURE_COVERAGE_GAPS, fixtureMeta, loadFixture, loadFixtures, type FixtureMeta, type FixtureSource, type LoadedFixture, } from './fixtures/index';