@fun-xyz/fiat-contract 0.18.0 → 0.20.0

package/README.md

@@ -13,13 +13,14 @@ 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) |
 
-## Four entry points — production vs test-time
+## Five 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: request, response, standing and fault types, and `MOONPAY_ENDPOINTS` | **production frontend** (MoonPay adapter) + 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/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 |
 
 `./table` is not a micro-optimisation. Terminality is table data a **shipped** client must read
@@ -98,18 +99,48 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
 
 A provider can run its own flow instead of the shared step machine. `POST /fiat/quote` still routes
 and prices. When the request's `handoffs` lists the winning provider, the response carries
-`handoff: { provider }` and no transitions, and the client calls that provider's routes under
-`POST /fiat/providers/{provider}/…`. The schema refuses a handoff to a provider other than the
-response's own, and a handoff that still offers transitions.
-
-MoonPay is the first (`./moonpay`). Its routes are `start`, `intent`, `kyc`, and `complete`, in
-`MOONPAY_ENDPOINTS`. Only `intent` decides: it answers with a `MoonPayStanding` (`READY`, `KYC`,
-`PENDING`, or `REFUSED`). `kyc` answers `{ status: 'ACCEPTED' }`, and the client then calls `intent`.
-`complete` answers with the same step response as `GET /fiat/orders/:orderId`. A fault is a 4xx or
-5xx with a `MoonPayErrorBody`: the shared `errorCode`, `errorMsg` and `reqId`, plus `reason`,
-`recovery`, and `fields` on a rejected KYC value. `recovery` is `RETRY` (send the same request),
-`REFRESH` (call `intent` for a new standing, as after a stale form), `REQUOTE`, or `NONE`. The zod
-schemas (`MoonPay*Schema`) are exported from the root only. A handoff appears only on a `QUOTE`.
+`handoff: { provider, terms }` and no transitions, and the client calls that provider's
+`POST /fiat/providers/{provider}/intent`. `terms` lists the `CHECKOUT` documents this login has not
+accepted at the current version; it is empty for a returning buyer. The schema refuses a handoff on
+any state but `QUOTE`, a handoff to a provider other than the response's own, a handoff that still
+offers transitions, and a `terms` entry that is not a unique `CHECKOUT` document.
+
+**Terms (`./terms`).** Every provider records acceptances through the platform `POST /fiat/terms`
+(`FIAT_TERMS_ENDPOINT`), with an `Idempotency-Key`. A `TermsDocument` has an `id`, a `kind`
+(`FUN_TERMS`, `PROVIDER_TERMS`, `FUN_KYC_COLLECTION`, `PROVIDER_KYC_SHARING`), a `stage` (`CHECKOUT` or
+`KYC`), an opaque `version` and `contentDigest`, and at least one `https` link. `FiatTermsRequest` is
+`{ provider, acceptances: [{ documentId, version, contentDigest, acceptedAt }] }`, each document at
+most once; `FiatTermsResponse` is `{ recorded }`, the recorded document ids. A fault is a
+`FiatTermsErrorBody`: the shared `errorCode`, `errorMsg` and `reqId`, plus `reason` (`STALE_TERMS`,
+`IN_PROGRESS`, `IDEMPOTENCY_KEY_REUSED`, `INVALID_REQUEST`, `RATE_LIMITED`) and `recovery`.
+
+**MoonPay (`./moonpay`).** One route, `MOONPAY_ENDPOINTS.intent`. A `MoonPayIntentRequest` is one of
+three kinds:
+
+| `kind` | Carries | `Idempotency-Key` |
+| --- | --- | --- |
+| `observe` | `checkout`, and `credentials` (`customerId`, `accessToken`) once the SDK has them | ignored |
+| `kyc` | `checkout`, `credentials`, `values` keyed by field id (no form id) | required |
+| `order` | `orderId`, `transactionId` | required |
+
+A `MoonPayIntentResponse` says what the backend needs next:
+
+| `status` | Carries | The client then |
+| --- | --- | --- |
+| `TERMS` | `stage`, `documents` (at least one, all at `stage`) | sends `POST /fiat/terms`, then `observe` |
+| `SDK_AUTH` | `sessionToken`, `quoteInput` | runs the MoonPay connection check, then `observe` with credentials |
+| `KYC` | `fields`, `fieldErrors?` (each naming a field in `fields`) | shows the shared form, then sends `kyc` |
+| `PENDING` | `retryAfterMs` (at most 60 s) | sends the same request again after the delay |
+| `READY` | `orderId`, `quoteInput` | mounts Apple Pay, then sends `order` after the charge |
+| `DONE` | `order`, the `GET /fiat/orders/:orderId` response | shows the shared order status |
+| `REFUSED` | `reason` (`NOT_ELIGIBLE`, `DOCUMENTS_REQUIRED`, `FINAL_REJECTION`, `CUSTOMER_MISMATCH`), `recovery: REQUOTE \| NONE` | exits the provider flow |
+
+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`, `IN_PROGRESS`,
+`IDEMPOTENCY_KEY_REUSED`, `INVALID_REQUEST`, `TRANSACTION_MISMATCH`, `WALLET_MISMATCH`) and `recovery`:
+`RETRY` (send the same request, with the same key), `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.
 
 ## KYC SDK hints, results, and client delivery
 
@@ -461,8 +492,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` (+ `.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 | four entry points: `./types` (erased), `./table` (13.8 KB, zero deps), `./moonpay` (zero deps), root (schemas + fixtures, test-time). CI asserts `require('.../table')` and `require('.../moonpay')` 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` (+ `.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 |
 | `.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-QXJ54JWX.mjs

@@ -0,0 +1,7 @@
+// src/terms.ts
+var FIAT_TERMS_ENDPOINT = "POST /fiat/terms";
+
+export {
+  FIAT_TERMS_ENDPOINT
+};
+//# sourceMappingURL=chunk-QXJ54JWX.mjs.map

package/dist/{chunk-7KI7DJZ2.mjs → chunk-TV6IWKTB.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.18.0";
+var version = "0.20.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -514,4 +514,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-7KI7DJZ2.mjs.map
+//# sourceMappingURL=chunk-TV6IWKTB.mjs.map

package/dist/chunk-UN3WTIMI.mjs

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

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './codes';
 export * from './schemas';
 export * from './table';
 export * from './assert';
+export * from './terms';
 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';

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   DOCUMENTED_ENDPOINTS: () => DOCUMENTED_ENDPOINTS,
   ENDPOINT_PATTERN: () => ENDPOINT_PATTERN,
   FIAT_CURRENCY_NAMES: () => FIAT_CURRENCY_NAMES,
+  FIAT_TERMS_ENDPOINT: () => FIAT_TERMS_ENDPOINT,
   FIELD_SPEC_TYPES: () => FIELD_SPEC_TYPES,
   FIXTURES: () => FIXTURES,
   FIXTURE_COVERAGE_GAPS: () => FIXTURE_COVERAGE_GAPS,
@@ -42,6 +43,9 @@ __export(index_exports, {
   FiatEndpointSchema: () => FiatEndpointSchema,
   FiatProviderSchema: () => FiatProviderSchema,
   FiatStepResponseSchema: () => FiatStepResponseSchema,
+  FiatTermsErrorBodySchema: () => FiatTermsErrorBodySchema,
+  FiatTermsRequestSchema: () => FiatTermsRequestSchema,
+  FiatTermsResponseSchema: () => FiatTermsResponseSchema,
   FieldSpecSchema: () => FieldSpecSchema,
   FlowStateSchema: () => FlowStateSchema,
   FormDescriptorSchema: () => FormDescriptorSchema,
@@ -60,17 +64,13 @@ __export(index_exports, {
   KycNoActionRequiredStateSchema: () => KycNoActionRequiredStateSchema,
   KycSdkResultReportSchema: () => KycSdkResultReportSchema,
   MOONPAY_ENDPOINTS: () => MOONPAY_ENDPOINTS,
-  MoonPayCompleteRequestSchema: () => MoonPayCompleteRequestSchema,
-  MoonPayCompleteResponseSchema: () => MoonPayCompleteResponseSchema,
+  MoonPayCheckoutSchema: () => MoonPayCheckoutSchema,
   MoonPayErrorBodySchema: () => MoonPayErrorBodySchema,
   MoonPayFaultSchema: () => MoonPayFaultSchema,
   MoonPayIntentRequestSchema: () => MoonPayIntentRequestSchema,
   MoonPayIntentResponseSchema: () => MoonPayIntentResponseSchema,
-  MoonPayKycRequestSchema: () => MoonPayKycRequestSchema,
-  MoonPayKycResponseSchema: () => MoonPayKycResponseSchema,
-  MoonPayStandingSchema: () => MoonPayStandingSchema,
-  MoonPayStartRequestSchema: () => MoonPayStartRequestSchema,
-  MoonPayStartResponseSchema: () => MoonPayStartResponseSchema,
+  MoonPayQuoteInputSchema: () => MoonPayQuoteInputSchema,
+  MoonPaySdkCredentialsSchema: () => MoonPaySdkCredentialsSchema,
   OrderAwaitingConfirmationStateSchema: () => OrderAwaitingConfirmationStateSchema,
   OrderCreatedStateSchema: () => OrderCreatedStateSchema,
   OrderRefSchema: () => OrderRefSchema,
@@ -103,6 +103,8 @@ __export(index_exports, {
   TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE: () => TRANSITION_TABLE,
   TermsAcceptanceSchema: () => TermsAcceptanceSchema,
+  TermsDocumentAcceptanceSchema: () => TermsDocumentAcceptanceSchema,
+  TermsDocumentSchema: () => TermsDocumentSchema,
   TransitionInputsSchema: () => TransitionInputsSchema,
   TransitionParamsSchema: () => TransitionParamsSchema,
   TransitionSchema: () => TransitionSchema,
@@ -965,12 +967,50 @@ var $providerBoundFlowState = import_zod.z.union([
 ]);
 var $flowState = import_zod.z.union([$providerBoundFlowState, $blockedState]);
 var FlowStateSchema = $flowState;
+var $nonBlank = import_zod.z.string().refine((value) => value.trim().length > 0, "must not be blank");
+var $termsStage = import_zod.z.enum(["CHECKOUT", "KYC"]);
+var $termsDocument = obj({
+  id: $nonBlank,
+  kind: import_zod.z.enum(["FUN_TERMS", "PROVIDER_TERMS", "FUN_KYC_COLLECTION", "PROVIDER_KYC_SHARING"]),
+  stage: $termsStage,
+  version: $nonBlank,
+  contentDigest: $nonBlank,
+  links: import_zod.z.array(obj({ label: $nonBlank, url: import_zod.z.string().regex(/^https:\/\/\S+$/, "must be an https URL") })).min(1)
+});
+var TermsDocumentSchema = $termsDocument;
+var hasUniqueIds = (ids) => new Set(ids).size === ids.length;
+var $termsDocuments = (stage) => import_zod.z.array($termsDocument).refine((documents) => hasUniqueIds(documents.map((document) => document.id)), "document ids must be unique").refine(
+  (documents) => stage === void 0 || documents.every((document) => document.stage === stage),
+  `every document must be at stage ${stage}`
+);
+var $termsAcceptance = obj({
+  documentId: $nonBlank,
+  version: $nonBlank,
+  contentDigest: $nonBlank,
+  acceptedAt: import_zod.z.string().datetime({ offset: true })
+});
+var TermsDocumentAcceptanceSchema = $termsAcceptance;
+var $termsRequest = obj({
+  provider: $provider,
+  acceptances: import_zod.z.array($termsAcceptance).min(1).refine((acceptances) => hasUniqueIds(acceptances.map((acceptance) => acceptance.documentId)), "each document is accepted once")
+});
+var FiatTermsRequestSchema = $termsRequest;
+var $termsResponse = obj({ recorded: import_zod.z.array($nonBlank) });
+var FiatTermsResponseSchema = $termsResponse;
+var $termsErrorBody = obj({
+  errorCode: $nonBlank,
+  errorMsg: import_zod.z.string(),
+  reqId: import_zod.z.string().optional(),
+  reason: import_zod.z.enum(["STALE_TERMS", "IN_PROGRESS", "IDEMPOTENCY_KEY_REUSED", "INVALID_REQUEST", "RATE_LIMITED"]),
+  recovery: import_zod.z.enum(["RETRY", "REQUOTE", "NONE"])
+});
+var FiatTermsErrorBodySchema = $termsErrorBody;
 var $providerBoundStepResponse = obj({
   state: $providerBoundFlowState,
   provider: $provider,
   transitions: import_zod.z.array($transition),
   preparedPayment: $preparedPayment.optional(),
-  handoff: obj({ provider: $provider }).optional(),
+  handoff: obj({ provider: $provider, terms: $termsDocuments("CHECKOUT") }).optional(),
   routingSessionRef: import_zod.z.string().optional(),
   providerAuthToken: obj({
     clientSecret: import_zod.z.string(),
@@ -1024,7 +1064,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.18.0";
+var version = "0.20.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -2590,12 +2630,12 @@ function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));
 }
 
+// src/terms.ts
+var FIAT_TERMS_ENDPOINT = "POST /fiat/terms";
+
 // src/providers/moonpay.ts
 var MOONPAY_ENDPOINTS = {
-  start: "POST /fiat/providers/moonpay/start",
-  intent: "POST /fiat/providers/moonpay/intent",
-  kyc: "POST /fiat/providers/moonpay/kyc",
-  complete: "POST /fiat/providers/moonpay/complete"
+  intent: "POST /fiat/providers/moonpay/intent"
 };
 
 // src/providers/moonpay.schemas.ts
@@ -2603,14 +2643,27 @@ var import_zod2 = require("zod");
 var FIAT_CURRENCY_CODES2 = Object.keys(FIAT_CURRENCY_NAMES);
 var obj2 = (shape) => import_zod2.z.object(shape).strict();
 var $nonEmpty = import_zod2.z.string().refine((value) => value.trim().length > 0, "must not be blank");
-var $startRequest = obj2({
+var hasUniqueIds2 = (ids) => new Set(ids).size === ids.length;
+var $checkout = obj2({
   amount: FiatAmountSchema,
   destination: obj2({ asset: $nonEmpty, network: $nonEmpty }),
   paymentMethod: import_zod2.z.literal("apple_pay"),
-  geo: obj2({ alpha2: import_zod2.z.string().regex(/^[A-Z]{2}$/), region: $nonEmpty.optional(), ip: $nonEmpty.optional() }),
-  termsAcceptance: obj2({ version: $nonEmpty, acceptedAt: import_zod2.z.string().datetime({ offset: true }) })
+  geo: obj2({ alpha2: import_zod2.z.string().regex(/^[A-Z]{2}$/), region: $nonEmpty.optional(), ip: $nonEmpty.optional() })
 });
-var MoonPayStartRequestSchema = $startRequest;
+var MoonPayCheckoutSchema = $checkout;
+var $credentials = obj2({ customerId: $nonEmpty, accessToken: $nonEmpty });
+var MoonPaySdkCredentialsSchema = $credentials;
+var $intentRequest = import_zod2.z.discriminatedUnion("kind", [
+  obj2({ kind: import_zod2.z.literal("observe"), checkout: $checkout, credentials: $credentials.optional() }),
+  obj2({
+    kind: import_zod2.z.literal("kyc"),
+    checkout: $checkout,
+    credentials: $credentials,
+    values: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()).refine((values) => Object.keys(values).length > 0, "values must not be empty")
+  }),
+  obj2({ kind: import_zod2.z.literal("order"), orderId: $nonEmpty, transactionId: $nonEmpty })
+]);
+var MoonPayIntentRequestSchema = $intentRequest;
 var $quoteInput = obj2({
   source: obj2({ asset: obj2({ code: import_zod2.z.enum(FIAT_CURRENCY_CODES2) }), amount: $nonEmpty }),
   destination: obj2({ asset: obj2({ code: $nonEmpty }) }),
@@ -2618,46 +2671,53 @@ var $quoteInput = obj2({
   paymentMethod: obj2({ type: import_zod2.z.literal("apple_pay") }),
   feeBehavior: import_zod2.z.literal("inclusive")
 });
-var $startResponse = obj2({ sessionToken: $nonEmpty, quoteInput: $quoteInput });
-var MoonPayStartResponseSchema = $startResponse;
-var $intentRequest = obj2({ customerId: $nonEmpty, accessToken: $nonEmpty });
-var MoonPayIntentRequestSchema = $intentRequest;
-var $refusal = import_zod2.z.enum(["DOCUMENTS_REQUIRED", "FINAL_REJECTION", "CUSTOMER_MISMATCH"]);
-var $standing = import_zod2.z.discriminatedUnion("status", [
-  obj2({ status: import_zod2.z.literal("READY"), orderId: $nonEmpty }),
-  obj2({ status: import_zod2.z.literal("KYC"), form: FormDescriptorSchema }),
+var MoonPayQuoteInputSchema = $quoteInput;
+var $refusal = import_zod2.z.enum(["NOT_ELIGIBLE", "DOCUMENTS_REQUIRED", "FINAL_REJECTION", "CUSTOMER_MISMATCH"]);
+var $fieldError = obj2({ fieldId: $nonEmpty, message: $nonEmpty });
+var $intentStatus = import_zod2.z.discriminatedUnion("status", [
+  obj2({ status: import_zod2.z.literal("TERMS"), stage: import_zod2.z.enum(["CHECKOUT", "KYC"]), documents: import_zod2.z.array(TermsDocumentSchema).min(1) }),
+  obj2({ status: import_zod2.z.literal("SDK_AUTH"), sessionToken: $nonEmpty, quoteInput: $quoteInput }),
+  obj2({ status: import_zod2.z.literal("KYC"), fields: import_zod2.z.array(FormFieldSchema).min(1), fieldErrors: import_zod2.z.array($fieldError).min(1).optional() }),
   obj2({ status: import_zod2.z.literal("PENDING"), retryAfterMs: import_zod2.z.number().int().positive().max(6e4) }),
+  obj2({ status: import_zod2.z.literal("READY"), orderId: $nonEmpty, quoteInput: $quoteInput }),
+  obj2({ status: import_zod2.z.literal("DONE"), order: FiatStepResponseSchema }),
   obj2({ status: import_zod2.z.literal("REFUSED"), reason: $refusal, recovery: import_zod2.z.enum(["REQUOTE", "NONE"]) })
 ]);
-var MoonPayStandingSchema = $standing;
-var MoonPayIntentResponseSchema = $standing;
-var $kycRequest = obj2({ formId: $nonEmpty, values: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()) });
-var MoonPayKycRequestSchema = $kycRequest;
-var $kycResponse = obj2({ status: import_zod2.z.literal("ACCEPTED") });
-var MoonPayKycResponseSchema = $kycResponse;
-var $completeRequest = obj2({ orderId: $nonEmpty, transactionId: $nonEmpty });
-var MoonPayCompleteRequestSchema = $completeRequest;
-var MoonPayCompleteResponseSchema = FiatStepResponseSchema;
-var $fieldError = obj2({ fieldId: $nonEmpty, message: $nonEmpty });
+var $intentResponse = $intentStatus.superRefine((response, context) => {
+  if (response.status === "TERMS") {
+    if (!hasUniqueIds2(response.documents.map((document) => document.id))) {
+      context.addIssue({ code: "custom", path: ["documents"], message: "document ids must be unique" });
+    }
+    if (response.documents.some((document) => document.stage !== response.stage)) {
+      context.addIssue({ code: "custom", path: ["documents"], message: "every document must be at the response stage" });
+    }
+  }
+  if (response.status === "KYC") {
+    const fieldIds = response.fields.map((field) => field.id);
+    if (!hasUniqueIds2(fieldIds)) {
+      context.addIssue({ code: "custom", path: ["fields"], message: "field ids must be unique" });
+    }
+    if (response.fieldErrors?.some((error) => !fieldIds.includes(error.fieldId))) {
+      context.addIssue({ code: "custom", path: ["fieldErrors"], message: "a field error must name a field in this response" });
+    }
+  }
+});
+var MoonPayIntentResponseSchema = $intentResponse;
 var $faultFields = {
   reason: import_zod2.z.enum([
-    "NOT_ELIGIBLE",
     "SESSION_BUDGET_SPENT",
+    "RATE_LIMITED",
     "PROVIDER_UNAVAILABLE",
-    "INVALID_VALUE",
-    "STALE_FORM",
-    "TRANSACTION_NOT_VISIBLE",
+    "IN_PROGRESS",
+    "IDEMPOTENCY_KEY_REUSED",
+    "INVALID_REQUEST",
+    "TRANSACTION_MISMATCH",
     "WALLET_MISMATCH"
   ]),
-  recovery: import_zod2.z.enum(["RETRY", "REFRESH", "REQUOTE", "NONE"]),
-  fields: import_zod2.z.array($fieldError).min(1).optional()
+  recovery: import_zod2.z.enum(["RETRY", "REQUOTE", "NONE"])
 };
-var fieldsOnlyOnInvalidValue = (fault) => fault.reason === "INVALID_VALUE" === (fault.fields !== void 0);
-var $fault = obj2($faultFields).refine(fieldsOnlyOnInvalidValue, "fields is present exactly when reason is INVALID_VALUE");
+var $fault = obj2($faultFields);
 var MoonPayFaultSchema = $fault;
-var $errorBody = obj2({ ...$faultFields, errorCode: $nonEmpty, errorMsg: import_zod2.z.string(), reqId: import_zod2.z.string().optional() }).refine(
-  fieldsOnlyOnInvalidValue,
-  "fields is present exactly when reason is INVALID_VALUE"
-);
+var $errorBody = obj2({ ...$faultFields, errorCode: $nonEmpty, errorMsg: import_zod2.z.string(), reqId: import_zod2.z.string().optional() });
 var MoonPayErrorBodySchema = $errorBody;
 //# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -12,10 +12,13 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-7KI7DJZ2.mjs";
+} from "./chunk-TV6IWKTB.mjs";
 import {
   MOONPAY_ENDPOINTS
-} from "./chunk-YWKS7MMT.mjs";
+} from "./chunk-UN3WTIMI.mjs";
+import {
+  FIAT_TERMS_ENDPOINT
+} from "./chunk-QXJ54JWX.mjs";
 
 // src/codes.ts
 var US_STATE_CODES = [
@@ -851,12 +854,50 @@ var $providerBoundFlowState = z.union([
 ]);
 var $flowState = z.union([$providerBoundFlowState, $blockedState]);
 var FlowStateSchema = $flowState;
+var $nonBlank = z.string().refine((value) => value.trim().length > 0, "must not be blank");
+var $termsStage = z.enum(["CHECKOUT", "KYC"]);
+var $termsDocument = obj({
+  id: $nonBlank,
+  kind: z.enum(["FUN_TERMS", "PROVIDER_TERMS", "FUN_KYC_COLLECTION", "PROVIDER_KYC_SHARING"]),
+  stage: $termsStage,
+  version: $nonBlank,
+  contentDigest: $nonBlank,
+  links: z.array(obj({ label: $nonBlank, url: z.string().regex(/^https:\/\/\S+$/, "must be an https URL") })).min(1)
+});
+var TermsDocumentSchema = $termsDocument;
+var hasUniqueIds = (ids) => new Set(ids).size === ids.length;
+var $termsDocuments = (stage) => z.array($termsDocument).refine((documents) => hasUniqueIds(documents.map((document) => document.id)), "document ids must be unique").refine(
+  (documents) => stage === void 0 || documents.every((document) => document.stage === stage),
+  `every document must be at stage ${stage}`
+);
+var $termsAcceptance = obj({
+  documentId: $nonBlank,
+  version: $nonBlank,
+  contentDigest: $nonBlank,
+  acceptedAt: z.string().datetime({ offset: true })
+});
+var TermsDocumentAcceptanceSchema = $termsAcceptance;
+var $termsRequest = obj({
+  provider: $provider,
+  acceptances: z.array($termsAcceptance).min(1).refine((acceptances) => hasUniqueIds(acceptances.map((acceptance) => acceptance.documentId)), "each document is accepted once")
+});
+var FiatTermsRequestSchema = $termsRequest;
+var $termsResponse = obj({ recorded: z.array($nonBlank) });
+var FiatTermsResponseSchema = $termsResponse;
+var $termsErrorBody = obj({
+  errorCode: $nonBlank,
+  errorMsg: z.string(),
+  reqId: z.string().optional(),
+  reason: z.enum(["STALE_TERMS", "IN_PROGRESS", "IDEMPOTENCY_KEY_REUSED", "INVALID_REQUEST", "RATE_LIMITED"]),
+  recovery: z.enum(["RETRY", "REQUOTE", "NONE"])
+});
+var FiatTermsErrorBodySchema = $termsErrorBody;
 var $providerBoundStepResponse = obj({
   state: $providerBoundFlowState,
   provider: $provider,
   transitions: z.array($transition),
   preparedPayment: $preparedPayment.optional(),
-  handoff: obj({ provider: $provider }).optional(),
+  handoff: obj({ provider: $provider, terms: $termsDocuments("CHECKOUT") }).optional(),
   routingSessionRef: z.string().optional(),
   providerAuthToken: obj({
     clientSecret: z.string(),
@@ -1979,14 +2020,27 @@ import { z as z2 } from "zod";
 var FIAT_CURRENCY_CODES2 = Object.keys(FIAT_CURRENCY_NAMES);
 var obj2 = (shape) => z2.object(shape).strict();
 var $nonEmpty = z2.string().refine((value) => value.trim().length > 0, "must not be blank");
-var $startRequest = obj2({
+var hasUniqueIds2 = (ids) => new Set(ids).size === ids.length;
+var $checkout = obj2({
   amount: FiatAmountSchema,
   destination: obj2({ asset: $nonEmpty, network: $nonEmpty }),
   paymentMethod: z2.literal("apple_pay"),
-  geo: obj2({ alpha2: z2.string().regex(/^[A-Z]{2}$/), region: $nonEmpty.optional(), ip: $nonEmpty.optional() }),
-  termsAcceptance: obj2({ version: $nonEmpty, acceptedAt: z2.string().datetime({ offset: true }) })
+  geo: obj2({ alpha2: z2.string().regex(/^[A-Z]{2}$/), region: $nonEmpty.optional(), ip: $nonEmpty.optional() })
 });
-var MoonPayStartRequestSchema = $startRequest;
+var MoonPayCheckoutSchema = $checkout;
+var $credentials = obj2({ customerId: $nonEmpty, accessToken: $nonEmpty });
+var MoonPaySdkCredentialsSchema = $credentials;
+var $intentRequest = z2.discriminatedUnion("kind", [
+  obj2({ kind: z2.literal("observe"), checkout: $checkout, credentials: $credentials.optional() }),
+  obj2({
+    kind: z2.literal("kyc"),
+    checkout: $checkout,
+    credentials: $credentials,
+    values: z2.record(z2.string(), z2.string()).refine((values) => Object.keys(values).length > 0, "values must not be empty")
+  }),
+  obj2({ kind: z2.literal("order"), orderId: $nonEmpty, transactionId: $nonEmpty })
+]);
+var MoonPayIntentRequestSchema = $intentRequest;
 var $quoteInput = obj2({
   source: obj2({ asset: obj2({ code: z2.enum(FIAT_CURRENCY_CODES2) }), amount: $nonEmpty }),
   destination: obj2({ asset: obj2({ code: $nonEmpty }) }),
@@ -1994,47 +2048,54 @@ var $quoteInput = obj2({
   paymentMethod: obj2({ type: z2.literal("apple_pay") }),
   feeBehavior: z2.literal("inclusive")
 });
-var $startResponse = obj2({ sessionToken: $nonEmpty, quoteInput: $quoteInput });
-var MoonPayStartResponseSchema = $startResponse;
-var $intentRequest = obj2({ customerId: $nonEmpty, accessToken: $nonEmpty });
-var MoonPayIntentRequestSchema = $intentRequest;
-var $refusal = z2.enum(["DOCUMENTS_REQUIRED", "FINAL_REJECTION", "CUSTOMER_MISMATCH"]);
-var $standing = z2.discriminatedUnion("status", [
-  obj2({ status: z2.literal("READY"), orderId: $nonEmpty }),
-  obj2({ status: z2.literal("KYC"), form: FormDescriptorSchema }),
+var MoonPayQuoteInputSchema = $quoteInput;
+var $refusal = z2.enum(["NOT_ELIGIBLE", "DOCUMENTS_REQUIRED", "FINAL_REJECTION", "CUSTOMER_MISMATCH"]);
+var $fieldError = obj2({ fieldId: $nonEmpty, message: $nonEmpty });
+var $intentStatus = z2.discriminatedUnion("status", [
+  obj2({ status: z2.literal("TERMS"), stage: z2.enum(["CHECKOUT", "KYC"]), documents: z2.array(TermsDocumentSchema).min(1) }),
+  obj2({ status: z2.literal("SDK_AUTH"), sessionToken: $nonEmpty, quoteInput: $quoteInput }),
+  obj2({ status: z2.literal("KYC"), fields: z2.array(FormFieldSchema).min(1), fieldErrors: z2.array($fieldError).min(1).optional() }),
   obj2({ status: z2.literal("PENDING"), retryAfterMs: z2.number().int().positive().max(6e4) }),
+  obj2({ status: z2.literal("READY"), orderId: $nonEmpty, quoteInput: $quoteInput }),
+  obj2({ status: z2.literal("DONE"), order: FiatStepResponseSchema }),
   obj2({ status: z2.literal("REFUSED"), reason: $refusal, recovery: z2.enum(["REQUOTE", "NONE"]) })
 ]);
-var MoonPayStandingSchema = $standing;
-var MoonPayIntentResponseSchema = $standing;
-var $kycRequest = obj2({ formId: $nonEmpty, values: z2.record(z2.string(), z2.string()) });
-var MoonPayKycRequestSchema = $kycRequest;
-var $kycResponse = obj2({ status: z2.literal("ACCEPTED") });
-var MoonPayKycResponseSchema = $kycResponse;
-var $completeRequest = obj2({ orderId: $nonEmpty, transactionId: $nonEmpty });
-var MoonPayCompleteRequestSchema = $completeRequest;
-var MoonPayCompleteResponseSchema = FiatStepResponseSchema;
-var $fieldError = obj2({ fieldId: $nonEmpty, message: $nonEmpty });
+var $intentResponse = $intentStatus.superRefine((response, context) => {
+  if (response.status === "TERMS") {
+    if (!hasUniqueIds2(response.documents.map((document) => document.id))) {
+      context.addIssue({ code: "custom", path: ["documents"], message: "document ids must be unique" });
+    }
+    if (response.documents.some((document) => document.stage !== response.stage)) {
+      context.addIssue({ code: "custom", path: ["documents"], message: "every document must be at the response stage" });
+    }
+  }
+  if (response.status === "KYC") {
+    const fieldIds = response.fields.map((field) => field.id);
+    if (!hasUniqueIds2(fieldIds)) {
+      context.addIssue({ code: "custom", path: ["fields"], message: "field ids must be unique" });
+    }
+    if (response.fieldErrors?.some((error) => !fieldIds.includes(error.fieldId))) {
+      context.addIssue({ code: "custom", path: ["fieldErrors"], message: "a field error must name a field in this response" });
+    }
+  }
+});
+var MoonPayIntentResponseSchema = $intentResponse;
 var $faultFields = {
   reason: z2.enum([
-    "NOT_ELIGIBLE",
     "SESSION_BUDGET_SPENT",
+    "RATE_LIMITED",
     "PROVIDER_UNAVAILABLE",
-    "INVALID_VALUE",
-    "STALE_FORM",
-    "TRANSACTION_NOT_VISIBLE",
+    "IN_PROGRESS",
+    "IDEMPOTENCY_KEY_REUSED",
+    "INVALID_REQUEST",
+    "TRANSACTION_MISMATCH",
     "WALLET_MISMATCH"
   ]),
-  recovery: z2.enum(["RETRY", "REFRESH", "REQUOTE", "NONE"]),
-  fields: z2.array($fieldError).min(1).optional()
+  recovery: z2.enum(["RETRY", "REQUOTE", "NONE"])
 };
-var fieldsOnlyOnInvalidValue = (fault) => fault.reason === "INVALID_VALUE" === (fault.fields !== void 0);
-var $fault = obj2($faultFields).refine(fieldsOnlyOnInvalidValue, "fields is present exactly when reason is INVALID_VALUE");
+var $fault = obj2($faultFields);
 var MoonPayFaultSchema = $fault;
-var $errorBody = obj2({ ...$faultFields, errorCode: $nonEmpty, errorMsg: z2.string(), reqId: z2.string().optional() }).refine(
-  fieldsOnlyOnInvalidValue,
-  "fields is present exactly when reason is INVALID_VALUE"
-);
+var $errorBody = obj2({ ...$faultFields, errorCode: $nonEmpty, errorMsg: z2.string(), reqId: z2.string().optional() });
 var MoonPayErrorBodySchema = $errorBody;
 export {
   AuthChallengeSchema,
@@ -2049,6 +2110,7 @@ export {
   DOCUMENTED_ENDPOINTS,
   ENDPOINT_PATTERN,
   FIAT_CURRENCY_NAMES,
+  FIAT_TERMS_ENDPOINT,
   FIELD_SPEC_TYPES,
   FIXTURES,
   FIXTURE_COVERAGE_GAPS,
@@ -2059,6 +2121,9 @@ export {
   FiatEndpointSchema,
   FiatProviderSchema,
   FiatStepResponseSchema,
+  FiatTermsErrorBodySchema,
+  FiatTermsRequestSchema,
+  FiatTermsResponseSchema,
   FieldSpecSchema,
   FlowStateSchema,
   FormDescriptorSchema,
@@ -2077,17 +2142,13 @@ export {
   KycNoActionRequiredStateSchema,
   KycSdkResultReportSchema,
   MOONPAY_ENDPOINTS,
-  MoonPayCompleteRequestSchema,
-  MoonPayCompleteResponseSchema,
+  MoonPayCheckoutSchema,
   MoonPayErrorBodySchema,
   MoonPayFaultSchema,
   MoonPayIntentRequestSchema,
   MoonPayIntentResponseSchema,
-  MoonPayKycRequestSchema,
-  MoonPayKycResponseSchema,
-  MoonPayStandingSchema,
-  MoonPayStartRequestSchema,
-  MoonPayStartResponseSchema,
+  MoonPayQuoteInputSchema,
+  MoonPaySdkCredentialsSchema,
   OrderAwaitingConfirmationStateSchema,
   OrderCreatedStateSchema,
   OrderRefSchema,
@@ -2120,6 +2181,8 @@ export {
   TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE,
   TermsAcceptanceSchema,
+  TermsDocumentAcceptanceSchema,
+  TermsDocumentSchema,
   TransitionInputsSchema,
   TransitionParamsSchema,
   TransitionSchema,

package/dist/providers/moonpay.d.ts

@@ -1,25 +1,28 @@
 /**
- * The MoonPay provider-owned flow: `POST /fiat/providers/moonpay/{start,intent,kyc,complete}`.
+ * The MoonPay provider-owned flow: one route, `POST /fiat/providers/moonpay/intent`.
  *
- * Only `intent` decides what happens next. `kyc` confirms a write or rejects it with field errors,
- * and the client then calls `intent` again. Identity and the deposit wallet always come from the
+ * Each request carries evidence or a user action (`kind`), and each response says what the backend
+ * needs next (`status`). The client repeats until `DONE` or `REFUSED`. Terms and consents go through
+ * the platform `POST /fiat/terms` (`./terms`). Identity and the deposit wallet always come from the
  * verified partner assertion, never from a request body.
  *
- * A fault is a 4xx/5xx whose body is the shared error body plus `MoonPayFault`. A decision the user
- * can act on is a 200 `MoonPayStanding`.
+ * `kyc` and `order` require an `Idempotency-Key` header; `observe` ignores it. A repeated key skips
+ * the effect and still returns the current response.
+ *
+ * A fault is a 4xx/5xx whose body is `MoonPayErrorBody`. Anything the user can act on is a 200
+ * `MoonPayIntentResponse`.
  *
  * Zero runtime dependencies, so production React Native code can import it. The zod schemas are in
  * `./moonpay.schemas`, exported from the package root.
  */
 import type { FiatCurrencyCode } from '../codes';
-import type { FiatAmount, FiatStepResponse, FormDescriptor, TermsAcceptance } from '../types';
+import type { TermsDocument, TermsStage } from '../terms';
+import type { FiatAmount, FiatStepResponse, FormField } from '../types';
 export declare const MOONPAY_ENDPOINTS: {
-    readonly start: "POST /fiat/providers/moonpay/start";
     readonly intent: "POST /fiat/providers/moonpay/intent";
-    readonly kyc: "POST /fiat/providers/moonpay/kyc";
-    readonly complete: "POST /fiat/providers/moonpay/complete";
 };
-export interface MoonPayStartRequest {
+/** The checkout terms. The client holds them and sends them on every `observe` and `kyc`. */
+export interface MoonPayCheckout {
     amount: FiatAmount;
     /** The quote's `crypto.currency` and `crypto.network`, unchanged. */
     destination: {
@@ -33,9 +36,33 @@ export interface MoonPayStartRequest {
         region?: string;
         ip?: string;
     };
-    /** The MoonPay terms notice on the amount screen; the tap is the acceptance. */
-    termsAcceptance: TermsAcceptance;
 }
+/** From the SDK's `active` connection. `accessToken` is a credential: the backend never logs it. */
+export interface MoonPaySdkCredentials {
+    customerId: string;
+    accessToken: string;
+}
+export type MoonPayIntentRequest = 
+/** No effect. Without credentials, the answer past the gates is `SDK_AUTH`. */
+{
+    kind: 'observe';
+    checkout: MoonPayCheckout;
+    credentials?: MoonPaySdkCredentials;
+}
+/** Only after a `KYC` response. `values` is keyed by field id; there is no form id. */
+ | {
+    kind: 'kyc';
+    checkout: MoonPayCheckout;
+    credentials: MoonPaySdkCredentials;
+    values: Record<string, string>;
+}
+/** After the Apple Pay sheet. `transactionId` is from the Apple Pay completion event. */
+ | {
+    kind: 'order';
+    orderId: string;
+    transactionId: string;
+};
+export type MoonPayIntentKind = MoonPayIntentRequest['kind'];
 /**
  * The parameters for the device `client.getQuote`, not a quote. The backend builds them because the
  * wallet must be the verified one and MoonPay's currency codes differ by environment.
@@ -60,69 +87,71 @@ export interface MoonPayQuoteInput {
     };
     feeBehavior: 'inclusive';
 }
-export interface MoonPayStartResponse {
-    /** The one SDK session, for the connection check, the auth frames, and the Apple Pay button. */
+export type MoonPayRefusal = 'NOT_ELIGIBLE' | 'DOCUMENTS_REQUIRED' | 'FINAL_REJECTION' | 'CUSTOMER_MISMATCH';
+/** A reason on one field of a `KYC` response. `fieldId` names a field in that response. */
+export interface MoonPayFieldError {
+    fieldId: string;
+    message: string;
+}
+export type MoonPayIntentResponse = 
+/** Show `documents` (every one at `stage`), send `POST /fiat/terms`, then `observe`. */
+{
+    status: 'TERMS';
+    stage: TermsStage;
+    documents: TermsDocument[];
+}
+/** Run the MoonPay connection check with `sessionToken`, then `observe` with the credentials. */
+ | {
+    status: 'SDK_AUTH';
     sessionToken: string;
     quoteInput: MoonPayQuoteInput;
 }
-export interface MoonPayIntentRequest {
-    /** From the SDK's `active` connection. */
-    customerId: string;
-    /** From the SDK's `active` connection. A credential: the backend strips it from every log. */
-    accessToken: string;
-}
-export type MoonPayRefusal = 'DOCUMENTS_REQUIRED' | 'FINAL_REJECTION' | 'CUSTOMER_MISMATCH';
-export type MoonPayStanding = 
-/** `orderId` is the `externalTransactionId` for the Apple Pay button. */
-{
-    status: 'READY';
-    orderId: string;
-} | {
+/** Show the shared form, then send `kyc`. */
+ | {
     status: 'KYC';
-    form: FormDescriptor;
-} | {
+    fields: FormField[];
+    fieldErrors?: MoonPayFieldError[];
+}
+/** Send the same request again after the delay. */
+ | {
     status: 'PENDING';
     retryAfterMs: number;
-} | {
+}
+/** Mount Apple Pay with `externalTransactionId = orderId`, then send `order` after the charge. */
+ | {
+    status: 'READY';
+    orderId: string;
+    quoteInput: MoonPayQuoteInput;
+}
+/** The `GET /fiat/orders/:orderId` response; the shared order screen renders it. */
+ | {
+    status: 'DONE';
+    order: FiatStepResponse;
+}
+/** Exit the provider flow. `REQUOTE` goes back to `POST /fiat/quote`; `NONE` ends the flow. */
+ | {
     status: 'REFUSED';
     reason: MoonPayRefusal;
     recovery: 'REQUOTE' | 'NONE';
 };
-export type MoonPayIntentResponse = MoonPayStanding;
-export interface MoonPayKycRequest {
-    /** From the `KYC` standing. A stale one is a 409 `STALE_FORM` with recovery `REFRESH`. */
-    formId: string;
-    /** One string per form field id. */
-    values: Record<string, string>;
-}
-/** The write landed. The client calls `intent` next. */
-export interface MoonPayKycResponse {
-    status: 'ACCEPTED';
-}
-export interface MoonPayCompleteRequest {
-    orderId: string;
-    /** From the Apple Pay completion event. */
-    transactionId: string;
-}
-/** The same response as `GET /fiat/orders/:orderId`, so the shared order screen renders it. */
-export type MoonPayCompleteResponse = FiatStepResponse;
+export type MoonPayIntentStatus = MoonPayIntentResponse['status'];
+/** `RETRY` sends the same request again, with the same key. `REQUOTE` goes back to `POST /fiat/quote`. `NONE` ends the flow. */
+export type MoonPayRecovery = 'RETRY' | 'REQUOTE' | 'NONE';
 /**
- * `RETRY` sends the same request again. `REFRESH` calls `intent` for a new standing. `REQUOTE` goes
- * back to `POST /fiat/quote`. `NONE` ends the flow.
+ * `SESSION_BUDGET_SPENT`: the per-login SDK session mint budget (429). `RATE_LIMITED`: the kind's
+ * request budget (429). `PROVIDER_UNAVAILABLE`: MoonPay or Sumsub is down, or a charge cannot be
+ * recorded. `IN_PROGRESS`: the same key is still running (409). `IDEMPOTENCY_KEY_REUSED`: the same
+ * key with a different body (422). `INVALID_REQUEST`: a bad body or a missing key (400).
+ * `TRANSACTION_MISMATCH`: the transaction is not this buyer's (400). `WALLET_MISMATCH`: the
+ * transaction pays another wallet.
  */
-export type MoonPayRecovery = 'RETRY' | 'REFRESH' | 'REQUOTE' | 'NONE';
-export type MoonPayFaultReason = 'NOT_ELIGIBLE' | 'SESSION_BUDGET_SPENT' | 'PROVIDER_UNAVAILABLE' | 'INVALID_VALUE' | 'STALE_FORM' | 'TRANSACTION_NOT_VISIBLE' | 'WALLET_MISMATCH';
-export interface MoonPayFieldError {
-    fieldId: string;
-    message: string;
-}
-/** The fields a MoonPay route adds to the shared error body. `fields` is only on `INVALID_VALUE`. */
+export type MoonPayFaultReason = 'SESSION_BUDGET_SPENT' | 'RATE_LIMITED' | 'PROVIDER_UNAVAILABLE' | 'IN_PROGRESS' | 'IDEMPOTENCY_KEY_REUSED' | 'INVALID_REQUEST' | 'TRANSACTION_MISMATCH' | 'WALLET_MISMATCH';
+/** The fields a MoonPay fault adds to the shared error body. */
 export interface MoonPayFault {
     reason: MoonPayFaultReason;
     recovery: MoonPayRecovery;
-    fields?: MoonPayFieldError[];
 }
-/** A MoonPay route's 4xx/5xx body: the shared error body plus `MoonPayFault`. */
+/** The route's 4xx/5xx body: the shared error body plus `MoonPayFault`. */
 export type MoonPayErrorBody = MoonPayFault & {
     errorCode: string;
     errorMsg: string;

package/dist/providers/moonpay.js

@@ -24,9 +24,6 @@ __export(moonpay_exports, {
 });
 module.exports = __toCommonJS(moonpay_exports);
 var MOONPAY_ENDPOINTS = {
-  start: "POST /fiat/providers/moonpay/start",
-  intent: "POST /fiat/providers/moonpay/intent",
-  kyc: "POST /fiat/providers/moonpay/kyc",
-  complete: "POST /fiat/providers/moonpay/complete"
+  intent: "POST /fiat/providers/moonpay/intent"
 };
 //# sourceMappingURL=moonpay.js.map

package/dist/providers/moonpay.mjs

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

package/dist/providers/moonpay.schemas.d.ts

@@ -3,16 +3,12 @@
  * the package root, never from `./moonpay`, so the production entry stays free of zod.
  */
 import { z } from 'zod';
-import type { MoonPayCompleteRequest, MoonPayCompleteResponse, MoonPayErrorBody, MoonPayFault, MoonPayIntentRequest, MoonPayIntentResponse, MoonPayKycRequest, MoonPayKycResponse, MoonPayStanding, MoonPayStartRequest, MoonPayStartResponse } from './moonpay';
-export declare const MoonPayStartRequestSchema: z.ZodType<MoonPayStartRequest>;
-export declare const MoonPayStartResponseSchema: z.ZodType<MoonPayStartResponse>;
+import type { MoonPayCheckout, MoonPayErrorBody, MoonPayFault, MoonPayIntentRequest, MoonPayIntentResponse, MoonPayQuoteInput, MoonPaySdkCredentials } from './moonpay';
+export declare const MoonPayCheckoutSchema: z.ZodType<MoonPayCheckout>;
+export declare const MoonPaySdkCredentialsSchema: z.ZodType<MoonPaySdkCredentials>;
 export declare const MoonPayIntentRequestSchema: z.ZodType<MoonPayIntentRequest>;
-export declare const MoonPayStandingSchema: z.ZodType<MoonPayStanding>;
+export declare const MoonPayQuoteInputSchema: z.ZodType<MoonPayQuoteInput>;
 export declare const MoonPayIntentResponseSchema: z.ZodType<MoonPayIntentResponse>;
-export declare const MoonPayKycRequestSchema: z.ZodType<MoonPayKycRequest>;
-export declare const MoonPayKycResponseSchema: z.ZodType<MoonPayKycResponse>;
-export declare const MoonPayCompleteRequestSchema: z.ZodType<MoonPayCompleteRequest>;
-export declare const MoonPayCompleteResponseSchema: z.ZodType<MoonPayCompleteResponse>;
 export declare const MoonPayFaultSchema: z.ZodType<MoonPayFault>;
 export declare const MoonPayErrorBodySchema: z.ZodType<MoonPayErrorBody>;
 //# sourceMappingURL=moonpay.schemas.d.ts.map

package/dist/schemas.d.ts

@@ -29,6 +29,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, ClientExecutedDelivery, KycSdkResultReport, SurfaceKind, SurfaceProvider, TermsAcceptance, Transition, TransitionInputs, TransitionParams, Tx } from './types';
+import type { FiatTermsErrorBody, FiatTermsRequest, FiatTermsResponse, TermsDocument, TermsDocumentAcceptance } from './terms';
 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. */
@@ -104,6 +105,11 @@ export declare const PaymentInstructStateSchema: z.ZodType<State<'PAYMENT', 'INS
 export declare const OrderAwaitingConfirmationStateSchema: z.ZodType<State<'ORDER', 'AWAITING_CONFIRMATION'>>;
 export declare const OrderCreatedStateSchema: z.ZodType<State<'ORDER', 'CREATED'>>;
 export declare const FlowStateSchema: z.ZodType<FlowState>;
+export declare const TermsDocumentSchema: z.ZodType<TermsDocument>;
+export declare const TermsDocumentAcceptanceSchema: z.ZodType<TermsDocumentAcceptance>;
+export declare const FiatTermsRequestSchema: z.ZodType<FiatTermsRequest>;
+export declare const FiatTermsResponseSchema: z.ZodType<FiatTermsResponse>;
+export declare const FiatTermsErrorBodySchema: z.ZodType<FiatTermsErrorBody>;
 export declare const FiatStepResponseSchema: z.ZodType<FiatStepResponse>;
 export {};
 //# sourceMappingURL=schemas.d.ts.map

package/dist/table.js

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

package/dist/table.mjs

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

package/dist/terms.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The platform terms route: `POST /fiat/terms`, shared by every provider.
+ *
+ * A checkout shows the user documents to accept. `CHECKOUT` documents arrive in `handoff.terms` on
+ * a `QUOTE`; `KYC` documents arrive in a provider flow's `TERMS` response. The user's Continue tap
+ * is the acceptance, and the client records it here, with an `Idempotency-Key`, before the next
+ * provider call.
+ *
+ * Zero runtime dependencies, so production React Native code can import it. The zod schemas are
+ * exported from the package root.
+ */
+import type { FiatProvider } from './types';
+export declare const FIAT_TERMS_ENDPOINT: "POST /fiat/terms";
+export type TermsDocumentKind = 'FUN_TERMS' | 'PROVIDER_TERMS' | 'FUN_KYC_COLLECTION' | 'PROVIDER_KYC_SHARING';
+/** `CHECKOUT` documents gate the provider session; `KYC` documents gate the first KYC write. */
+export type TermsStage = 'CHECKOUT' | 'KYC';
+export interface TermsDocument {
+    id: string;
+    kind: TermsDocumentKind;
+    stage: TermsStage;
+    /** Opaque to the client; echoed in the acceptance. */
+    version: string;
+    /** Opaque to the client; echoed in the acceptance, so a dispute names the text the user saw. */
+    contentDigest: string;
+    /** What the screen links to. At least one, each an `https` URL. */
+    links: {
+        label: string;
+        url: string;
+    }[];
+}
+export interface TermsDocumentAcceptance {
+    documentId: string;
+    version: string;
+    contentDigest: string;
+    /** ISO-8601 with an offset, stamped by the client at the tap. The backend refuses one older than 5 minutes. */
+    acceptedAt: string;
+}
+export interface FiatTermsRequest {
+    provider: FiatProvider;
+    /** One per document the screen showed, each document at most once. */
+    acceptances: TermsDocumentAcceptance[];
+}
+/** The recorded document ids. The client then calls the provider's `intent`. */
+export interface FiatTermsResponse {
+    recorded: string[];
+}
+/**
+ * `STALE_TERMS`: a version, digest, or `acceptedAt` the backend no longer accepts; the client
+ * fetches the documents again. `IN_PROGRESS`: the same key is still running (409).
+ * `IDEMPOTENCY_KEY_REUSED`: the same key with a different body (422). `INVALID_REQUEST`: a bad body
+ * or a missing key (400). `RATE_LIMITED`: the per-login terms budget is spent (429).
+ */
+export type FiatTermsFaultReason = 'STALE_TERMS' | 'IN_PROGRESS' | 'IDEMPOTENCY_KEY_REUSED' | 'INVALID_REQUEST' | 'RATE_LIMITED';
+/** `RETRY` sends the same request, with the same key. `REQUOTE` goes back to `POST /fiat/quote`. `NONE` ends the flow. */
+export type FiatTermsRecovery = 'RETRY' | 'REQUOTE' | 'NONE';
+/** The 4xx/5xx body of `POST /fiat/terms`: the shared error body plus `reason` and `recovery`. */
+export interface FiatTermsErrorBody {
+    errorCode: string;
+    errorMsg: string;
+    reqId?: string;
+    reason: FiatTermsFaultReason;
+    recovery: FiatTermsRecovery;
+}
+//# sourceMappingURL=terms.d.ts.map

package/dist/terms.js

@@ -0,0 +1,27 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/terms.ts
+var terms_exports = {};
+__export(terms_exports, {
+  FIAT_TERMS_ENDPOINT: () => FIAT_TERMS_ENDPOINT
+});
+module.exports = __toCommonJS(terms_exports);
+var FIAT_TERMS_ENDPOINT = "POST /fiat/terms";
+//# sourceMappingURL=terms.js.map

package/dist/terms.mjs

@@ -0,0 +1,7 @@
+import {
+  FIAT_TERMS_ENDPOINT
+} from "./chunk-QXJ54JWX.mjs";
+export {
+  FIAT_TERMS_ENDPOINT
+};
+//# sourceMappingURL=terms.mjs.map

package/dist/types.d.ts

@@ -19,6 +19,7 @@
  *  - terminality comes from the table (`src/table.ts`), never from `transitions.length`
  */
 import type { FiatCurrencyCode, PaymentMethodCategory } from './codes';
+import type { TermsDocument } from './terms';
 /**
  * JSON value. `params` carry these — opaque literals the client spreads verbatim.
  * Named `JsonValue` rather than `Json` because this package's surface is re-exported wholesale;
@@ -715,11 +716,17 @@ export type FiatStepResponse = (FiatStepResponseBase & {
     /** Optional future payment artifact; never one of this response's currently active transitions. */
     preparedPayment?: PreparedPayment;
     /**
-     * The provider runs its own flow from here (`POST /fiat/providers/{provider}/…`). Present only
-     * when the request's `handoffs` named this provider; the response then carries no transitions.
+     * The provider runs its own flow from here (`POST /fiat/providers/{provider}/intent`). Present
+     * only on a `QUOTE`, when the request's `handoffs` named this provider; the response then
+     * carries no transitions.
      */
     handoff?: {
         provider: FiatProvider;
+        /**
+         * The `CHECKOUT` documents this login has not accepted at the current version, shown next to
+         * Continue and recorded with `POST /fiat/terms` on the tap. Empty for a returning buyer.
+         */
+        terms: TermsDocument[];
     };
 });
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fun-xyz/fiat-contract",
-  "version": "0.18.0",
+  "version": "0.20.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": {
@@ -33,6 +33,11 @@
       "import": "./dist/providers/moonpay.mjs",
       "require": "./dist/providers/moonpay.js"
     },
+    "./terms": {
+      "types": "./dist/terms.d.ts",
+      "import": "./dist/terms.mjs",
+      "require": "./dist/terms.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -43,6 +48,8 @@
     "types.d.ts",
     "moonpay.js",
     "moonpay.d.ts",
+    "terms.js",
+    "terms.d.ts",
     "README.md",
     "!dist/**/*.map"
   ],
@@ -85,6 +92,9 @@
       ],
       "moonpay": [
         "./dist/providers/moonpay.d.ts"
+      ],
+      "terms": [
+        "./dist/terms.d.ts"
       ]
     }
   }

package/terms.d.ts

@@ -0,0 +1 @@
+export * from './dist/terms';

package/terms.js

@@ -0,0 +1,2 @@
+// Compat stub — see table.js. Metro before RN 0.79 resolves `@fun-xyz/fiat-contract/terms` by path.
+module.exports = require('./dist/terms.js');

package/dist/chunk-YWKS7MMT.mjs

@@ -1,12 +0,0 @@
-// src/providers/moonpay.ts
-var MOONPAY_ENDPOINTS = {
-  start: "POST /fiat/providers/moonpay/start",
-  intent: "POST /fiat/providers/moonpay/intent",
-  kyc: "POST /fiat/providers/moonpay/kyc",
-  complete: "POST /fiat/providers/moonpay/complete"
-};
-
-export {
-  MOONPAY_ENDPOINTS
-};
-//# sourceMappingURL=chunk-YWKS7MMT.mjs.map