@fun-xyz/fiat-contract 0.16.0 → 0.18.0

package/README.md

@@ -13,12 +13,13 @@ 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) |
 
-## Three entry points — production vs test-time
+## Four 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` | 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
@@ -88,6 +89,27 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
 16. **Correction text never decides retry.** A correctable provider rejection returns
     `KYC{CAPTURE}` and may carry `correctionReason` for display. Clients decide that retry is allowed
     from the state and its transitions; provider-authored text is never a branch key.
+17. **Prepared payment is inert until promotion.** `FiatStepResponse.preparedPayment` may warm a
+    provider-owned payment surface while auth or KYC continues, but its `CLIENT_SURFACE` transition
+    is not active yet. A client exposes it only after a later response makes the same `quoteRef`
+    executable; the prepared surface provider must match the response provider.
+
+## Provider-owned flows
+
+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`.
 
 ## KYC SDK hints, results, and client delivery
 
@@ -440,7 +462,7 @@ 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 | three entry points: `./types` (erased), `./table` (13.8 KB, zero deps), root (schemas + fixtures, test-time). CI asserts `require('.../table')` never loads zod |
+| 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 |
 | `.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-PEJOU52N.mjs → chunk-7KI7DJZ2.mjs}

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

package/dist/chunk-YWKS7MMT.mjs

@@ -0,0 +1,12 @@
+// 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

package/dist/index.d.ts

@@ -10,5 +10,7 @@ export * from './codes';
 export * from './schemas';
 export * from './table';
 export * from './assert';
+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';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -59,6 +59,18 @@ __export(index_exports, {
   KycInputRequiredStateSchema: () => KycInputRequiredStateSchema,
   KycNoActionRequiredStateSchema: () => KycNoActionRequiredStateSchema,
   KycSdkResultReportSchema: () => KycSdkResultReportSchema,
+  MOONPAY_ENDPOINTS: () => MOONPAY_ENDPOINTS,
+  MoonPayCompleteRequestSchema: () => MoonPayCompleteRequestSchema,
+  MoonPayCompleteResponseSchema: () => MoonPayCompleteResponseSchema,
+  MoonPayErrorBodySchema: () => MoonPayErrorBodySchema,
+  MoonPayFaultSchema: () => MoonPayFaultSchema,
+  MoonPayIntentRequestSchema: () => MoonPayIntentRequestSchema,
+  MoonPayIntentResponseSchema: () => MoonPayIntentResponseSchema,
+  MoonPayKycRequestSchema: () => MoonPayKycRequestSchema,
+  MoonPayKycResponseSchema: () => MoonPayKycResponseSchema,
+  MoonPayStandingSchema: () => MoonPayStandingSchema,
+  MoonPayStartRequestSchema: () => MoonPayStartRequestSchema,
+  MoonPayStartResponseSchema: () => MoonPayStartResponseSchema,
   OrderAwaitingConfirmationStateSchema: () => OrderAwaitingConfirmationStateSchema,
   OrderCreatedStateSchema: () => OrderCreatedStateSchema,
   OrderRefSchema: () => OrderRefSchema,
@@ -67,9 +79,11 @@ __export(index_exports, {
   PAYMENT_METHOD_CATEGORIES: () => PAYMENT_METHOD_CATEGORIES,
   PaymentCaptureStateSchema: () => PaymentCaptureStateSchema,
   PaymentInstructStateSchema: () => PaymentInstructStateSchema,
+  PaymentSurfaceSchema: () => PaymentSurfaceSchema,
   PendingOrderStateSchema: () => PendingOrderStateSchema,
   PollSpecSchema: () => PollSpecSchema,
   PreferredIdentityDocumentSchema: () => PreferredIdentityDocumentSchema,
+  PreparedPaymentSchema: () => PreparedPaymentSchema,
   QuoteLimitRangeSchema: () => QuoteLimitRangeSchema,
   QuoteLimitsSchema: () => QuoteLimitsSchema,
   QuoteSchema: () => QuoteSchema,
@@ -671,6 +685,13 @@ var $surface = import_zod.z.union([
   })
 ]);
 var SurfaceSchema = $surface;
+var $paymentSurface = obj({
+  ...$surfaceBase,
+  kind: import_zod.z.enum(["URL_REDIRECT", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]),
+  provider: $provider,
+  delivery: $clientExecutedDelivery.optional()
+});
+var PaymentSurfaceSchema = $paymentSurface;
 var $instructionField = obj({
   id: import_zod.z.string(),
   labelFallback: import_zod.z.string(),
@@ -798,6 +819,11 @@ var $kycSdkResult = import_zod.z.union([
   obj({ outcome: import_zod.z.literal("FAILED"), errorType: import_zod.z.string().trim().min(1) })
 ]);
 var KycSdkResultReportSchema = $kycSdkResult;
+var $clientSurfaceTransition = obj({
+  id: import_zod.z.string(),
+  mode: import_zod.z.literal("CLIENT_SURFACE"),
+  report: $reportSpec
+});
 var $transition = import_zod.z.union([
   obj({
     id: import_zod.z.string(),
@@ -808,9 +834,15 @@ var $transition = import_zod.z.union([
     labelFallback: import_zod.z.string().optional()
   }),
   obj({ id: import_zod.z.string(), mode: import_zod.z.literal("AWAIT"), poll: $pollSpec }),
-  obj({ id: import_zod.z.string(), mode: import_zod.z.literal("CLIENT_SURFACE"), report: $reportSpec })
+  $clientSurfaceTransition
 ]);
 var TransitionSchema = $transition;
+var $preparedPayment = obj({
+  quoteRef: import_zod.z.string().trim().min(1),
+  surface: $paymentSurface,
+  transition: $clientSurfaceTransition
+});
+var PreparedPaymentSchema = $preparedPayment;
 var $authChallenge = import_zod.z.record(import_zod.z.string(), JsonSchema);
 var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
@@ -937,6 +969,8 @@ var $providerBoundStepResponse = obj({
   state: $providerBoundFlowState,
   provider: $provider,
   transitions: import_zod.z.array($transition),
+  preparedPayment: $preparedPayment.optional(),
+  handoff: obj({ provider: $provider }).optional(),
   routingSessionRef: import_zod.z.string().optional(),
   providerAuthToken: obj({
     clientSecret: import_zod.z.string(),
@@ -944,6 +978,35 @@ var $providerBoundStepResponse = obj({
   }).optional(),
   orderId: import_zod.z.string().optional(),
   refreshLimits: import_zod.z.literal(true).optional()
+}).superRefine((response, context) => {
+  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
+    context.addIssue({
+      code: "custom",
+      path: ["preparedPayment", "surface", "provider"],
+      message: "preparedPayment.surface.provider must match the response provider"
+    });
+  }
+  if (response.handoff !== void 0 && response.handoff.provider !== response.provider) {
+    context.addIssue({
+      code: "custom",
+      path: ["handoff", "provider"],
+      message: "handoff.provider must match the response provider"
+    });
+  }
+  if (response.handoff !== void 0 && response.state.kind !== "QUOTE") {
+    context.addIssue({
+      code: "custom",
+      path: ["handoff"],
+      message: "only a QUOTE response hands off to a provider"
+    });
+  }
+  if (response.handoff !== void 0 && response.transitions.length > 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["transitions"],
+      message: "a handoff response carries no transitions"
+    });
+  }
 });
 var $blockedStepResponse = obj({
   state: $blockedState,
@@ -961,7 +1024,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.16.0";
+var version = "0.18.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -2526,4 +2589,75 @@ function assertFixture(id) {
 function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));
 }
+
+// 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"
+};
+
+// src/providers/moonpay.schemas.ts
+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({
+  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 }) })
+});
+var MoonPayStartRequestSchema = $startRequest;
+var $quoteInput = obj2({
+  source: obj2({ asset: obj2({ code: import_zod2.z.enum(FIAT_CURRENCY_CODES2) }), amount: $nonEmpty }),
+  destination: obj2({ asset: obj2({ code: $nonEmpty }) }),
+  wallet: obj2({ address: $nonEmpty }),
+  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 }),
+  obj2({ status: import_zod2.z.literal("PENDING"), retryAfterMs: import_zod2.z.number().int().positive().max(6e4) }),
+  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 $faultFields = {
+  reason: import_zod2.z.enum([
+    "NOT_ELIGIBLE",
+    "SESSION_BUDGET_SPENT",
+    "PROVIDER_UNAVAILABLE",
+    "INVALID_VALUE",
+    "STALE_FORM",
+    "TRANSACTION_NOT_VISIBLE",
+    "WALLET_MISMATCH"
+  ]),
+  recovery: import_zod2.z.enum(["RETRY", "REFRESH", "REQUOTE", "NONE"]),
+  fields: import_zod2.z.array($fieldError).min(1).optional()
+};
+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 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 MoonPayErrorBodySchema = $errorBody;
 //# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -12,7 +12,10 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-PEJOU52N.mjs";
+} from "./chunk-7KI7DJZ2.mjs";
+import {
+  MOONPAY_ENDPOINTS
+} from "./chunk-YWKS7MMT.mjs";
 
 // src/codes.ts
 var US_STATE_CODES = [
@@ -568,6 +571,13 @@ var $surface = z.union([
   })
 ]);
 var SurfaceSchema = $surface;
+var $paymentSurface = obj({
+  ...$surfaceBase,
+  kind: z.enum(["URL_REDIRECT", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]),
+  provider: $provider,
+  delivery: $clientExecutedDelivery.optional()
+});
+var PaymentSurfaceSchema = $paymentSurface;
 var $instructionField = obj({
   id: z.string(),
   labelFallback: z.string(),
@@ -695,6 +705,11 @@ var $kycSdkResult = z.union([
   obj({ outcome: z.literal("FAILED"), errorType: z.string().trim().min(1) })
 ]);
 var KycSdkResultReportSchema = $kycSdkResult;
+var $clientSurfaceTransition = obj({
+  id: z.string(),
+  mode: z.literal("CLIENT_SURFACE"),
+  report: $reportSpec
+});
 var $transition = z.union([
   obj({
     id: z.string(),
@@ -705,9 +720,15 @@ var $transition = z.union([
     labelFallback: z.string().optional()
   }),
   obj({ id: z.string(), mode: z.literal("AWAIT"), poll: $pollSpec }),
-  obj({ id: z.string(), mode: z.literal("CLIENT_SURFACE"), report: $reportSpec })
+  $clientSurfaceTransition
 ]);
 var TransitionSchema = $transition;
+var $preparedPayment = obj({
+  quoteRef: z.string().trim().min(1),
+  surface: $paymentSurface,
+  transition: $clientSurfaceTransition
+});
+var PreparedPaymentSchema = $preparedPayment;
 var $authChallenge = z.record(z.string(), JsonSchema);
 var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
@@ -834,6 +855,8 @@ var $providerBoundStepResponse = obj({
   state: $providerBoundFlowState,
   provider: $provider,
   transitions: z.array($transition),
+  preparedPayment: $preparedPayment.optional(),
+  handoff: obj({ provider: $provider }).optional(),
   routingSessionRef: z.string().optional(),
   providerAuthToken: obj({
     clientSecret: z.string(),
@@ -841,6 +864,35 @@ var $providerBoundStepResponse = obj({
   }).optional(),
   orderId: z.string().optional(),
   refreshLimits: z.literal(true).optional()
+}).superRefine((response, context) => {
+  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
+    context.addIssue({
+      code: "custom",
+      path: ["preparedPayment", "surface", "provider"],
+      message: "preparedPayment.surface.provider must match the response provider"
+    });
+  }
+  if (response.handoff !== void 0 && response.handoff.provider !== response.provider) {
+    context.addIssue({
+      code: "custom",
+      path: ["handoff", "provider"],
+      message: "handoff.provider must match the response provider"
+    });
+  }
+  if (response.handoff !== void 0 && response.state.kind !== "QUOTE") {
+    context.addIssue({
+      code: "custom",
+      path: ["handoff"],
+      message: "only a QUOTE response hands off to a provider"
+    });
+  }
+  if (response.handoff !== void 0 && response.transitions.length > 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["transitions"],
+      message: "a handoff response carries no transitions"
+    });
+  }
 });
 var $blockedStepResponse = obj({
   state: $blockedState,
@@ -1921,6 +1973,69 @@ function assertFixture(id) {
 function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));
 }
+
+// src/providers/moonpay.schemas.ts
+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({
+  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 }) })
+});
+var MoonPayStartRequestSchema = $startRequest;
+var $quoteInput = obj2({
+  source: obj2({ asset: obj2({ code: z2.enum(FIAT_CURRENCY_CODES2) }), amount: $nonEmpty }),
+  destination: obj2({ asset: obj2({ code: $nonEmpty }) }),
+  wallet: obj2({ address: $nonEmpty }),
+  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 }),
+  obj2({ status: z2.literal("PENDING"), retryAfterMs: z2.number().int().positive().max(6e4) }),
+  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 $faultFields = {
+  reason: z2.enum([
+    "NOT_ELIGIBLE",
+    "SESSION_BUDGET_SPENT",
+    "PROVIDER_UNAVAILABLE",
+    "INVALID_VALUE",
+    "STALE_FORM",
+    "TRANSACTION_NOT_VISIBLE",
+    "WALLET_MISMATCH"
+  ]),
+  recovery: z2.enum(["RETRY", "REFRESH", "REQUOTE", "NONE"]),
+  fields: z2.array($fieldError).min(1).optional()
+};
+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 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 MoonPayErrorBodySchema = $errorBody;
 export {
   AuthChallengeSchema,
   BlockedReasonSchema,
@@ -1961,6 +2076,18 @@ export {
   KycInputRequiredStateSchema,
   KycNoActionRequiredStateSchema,
   KycSdkResultReportSchema,
+  MOONPAY_ENDPOINTS,
+  MoonPayCompleteRequestSchema,
+  MoonPayCompleteResponseSchema,
+  MoonPayErrorBodySchema,
+  MoonPayFaultSchema,
+  MoonPayIntentRequestSchema,
+  MoonPayIntentResponseSchema,
+  MoonPayKycRequestSchema,
+  MoonPayKycResponseSchema,
+  MoonPayStandingSchema,
+  MoonPayStartRequestSchema,
+  MoonPayStartResponseSchema,
   OrderAwaitingConfirmationStateSchema,
   OrderCreatedStateSchema,
   OrderRefSchema,
@@ -1969,9 +2096,11 @@ export {
   PAYMENT_METHOD_CATEGORIES,
   PaymentCaptureStateSchema,
   PaymentInstructStateSchema,
+  PaymentSurfaceSchema,
   PendingOrderStateSchema,
   PollSpecSchema,
   PreferredIdentityDocumentSchema,
+  PreparedPaymentSchema,
   QuoteLimitRangeSchema,
   QuoteLimitsSchema,
   QuoteSchema,

package/dist/providers/moonpay.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The MoonPay provider-owned flow: `POST /fiat/providers/moonpay/{start,intent,kyc,complete}`.
+ *
+ * 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
+ * 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`.
+ *
+ * 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';
+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 {
+    amount: FiatAmount;
+    /** The quote's `crypto.currency` and `crypto.network`, unchanged. */
+    destination: {
+        asset: string;
+        network: string;
+    };
+    paymentMethod: 'apple_pay';
+    /** The geo endpoint's response, as sent to `POST /fiat/quote`. `alpha2` is ISO 3166-1 alpha-2. */
+    geo: {
+        alpha2: string;
+        region?: string;
+        ip?: string;
+    };
+    /** The MoonPay terms notice on the amount screen; the tap is the acceptance. */
+    termsAcceptance: TermsAcceptance;
+}
+/**
+ * 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.
+ */
+export interface MoonPayQuoteInput {
+    source: {
+        asset: {
+            code: FiatCurrencyCode;
+        };
+        amount: string;
+    };
+    destination: {
+        asset: {
+            code: string;
+        };
+    };
+    wallet: {
+        address: string;
+    };
+    paymentMethod: {
+        type: 'apple_pay';
+    };
+    feeBehavior: 'inclusive';
+}
+export interface MoonPayStartResponse {
+    /** The one SDK session, for the connection check, the auth frames, and the Apple Pay button. */
+    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;
+} | {
+    status: 'KYC';
+    form: FormDescriptor;
+} | {
+    status: 'PENDING';
+    retryAfterMs: number;
+} | {
+    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;
+/**
+ * `RETRY` sends the same request again. `REFRESH` calls `intent` for a new standing. `REQUOTE` goes
+ * back to `POST /fiat/quote`. `NONE` ends the flow.
+ */
+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 interface MoonPayFault {
+    reason: MoonPayFaultReason;
+    recovery: MoonPayRecovery;
+    fields?: MoonPayFieldError[];
+}
+/** A MoonPay route's 4xx/5xx body: the shared error body plus `MoonPayFault`. */
+export type MoonPayErrorBody = MoonPayFault & {
+    errorCode: string;
+    errorMsg: string;
+    reqId?: string;
+};
+//# sourceMappingURL=moonpay.d.ts.map

package/dist/providers/moonpay.js

@@ -0,0 +1,32 @@
+"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/providers/moonpay.ts
+var moonpay_exports = {};
+__export(moonpay_exports, {
+  MOONPAY_ENDPOINTS: () => MOONPAY_ENDPOINTS
+});
+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"
+};
+//# sourceMappingURL=moonpay.js.map

package/dist/providers/moonpay.mjs

@@ -0,0 +1,7 @@
+import {
+  MOONPAY_ENDPOINTS
+} from "../chunk-YWKS7MMT.mjs";
+export {
+  MOONPAY_ENDPOINTS
+};
+//# sourceMappingURL=moonpay.mjs.map

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

@@ -0,0 +1,18 @@
+/**
+ * zod schemas for the MoonPay provider-owned flow. Test-time and backend-boundary only: exported from
+ * 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>;
+export declare const MoonPayIntentRequestSchema: z.ZodType<MoonPayIntentRequest>;
+export declare const MoonPayStandingSchema: z.ZodType<MoonPayStanding>;
+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

@@ -28,7 +28,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, Quote, QuoteLimitRange, QuoteLimits, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, Surface, PreferredIdentityDocument, ClientExecutedDelivery, KycSdkResultReport, SurfaceKind, SurfaceProvider, TermsAcceptance, Transition, TransitionInputs, TransitionParams, Tx } from './types';
+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';
 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. */
@@ -59,6 +59,7 @@ export declare const STANDARD_KYC_FIELD_IDS: readonly ["LEGAL_FIRST_NAME", "LEGA
 export declare const KYC_ACKNOWLEDGEMENT_FIELD_IDS: readonly ["RISK_ACKNOWLEDGEMENT", "COOLING_OFF_ACKNOWLEDGEMENT", "TERMS_ACCEPTANCE"];
 export declare const ClientExecutedDeliverySchema: z.ZodType<ClientExecutedDelivery>;
 export declare const SurfaceSchema: z.ZodType<Surface>;
+export declare const PaymentSurfaceSchema: z.ZodType<PaymentSurface>;
 export declare const InstructionFieldSchema: z.ZodType<InstructionField>;
 export declare const InstructionsSchema: z.ZodType<Instructions>;
 export declare const SelectOptionSchema: z.ZodType<SelectOption>;
@@ -80,6 +81,7 @@ export declare const PollSpecSchema: z.ZodType<PollSpec>;
 export declare const ReportSpecSchema: z.ZodType<ReportSpec>;
 export declare const KycSdkResultReportSchema: z.ZodType<KycSdkResultReport>;
 export declare const TransitionSchema: z.ZodType<Transition>;
+export declare const PreparedPaymentSchema: z.ZodType<PreparedPayment>;
 export declare const AuthChallengeSchema: z.ZodType<Record<string, JsonValue>>;
 /** `Extract` keeps each per-state export pinned to the union member it validates. */
 type State<K extends FlowState['kind'], P = never> = [P] extends [never] ? Extract<FlowState, {

package/dist/table.js

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

package/dist/table.mjs

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

package/dist/types.d.ts

@@ -293,6 +293,12 @@ export type Surface = (SurfaceBase & {
     /** Adapter-owned submission mechanics; the shared contract declares only the safe source. */
     delivery?: ClientExecutedDelivery;
 });
+/** Provider-owned surfaces that can execute a payment after the quote becomes executable. */
+export type PaymentSurfaceKind = 'URL_REDIRECT' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT';
+export type PaymentSurface = Surface & {
+    kind: PaymentSurfaceKind;
+    provider: FiatProvider;
+};
 export interface InstructionField {
     id: string;
     labelFallback: string;
@@ -506,6 +512,20 @@ export type Transition = {
     mode: 'CLIENT_SURFACE';
     report: ReportSpec;
 };
+/**
+ * A payment surface prepared ahead of the flow state that may execute it.
+ *
+ * This is inert response metadata, not an active transition. A client may warm the surface while
+ * completing auth or KYC, but must expose or report it only after a later response makes the same
+ * quote executable. `quoteRef` is explicit so that promotion never relies on provider-owned params.
+ */
+export interface PreparedPayment {
+    quoteRef: string;
+    surface: PaymentSurface;
+    transition: Extract<Transition, {
+        mode: 'CLIENT_SURFACE';
+    }>;
+}
 /**
  * TODO(open-decision): shape owned by the auth spike (contract §Auth & ref binding, item 5).
  * `FUN_AUTH` never renders in fomo (identity is ambient), so nothing in either doc constrains
@@ -692,6 +712,15 @@ export type FiatStepResponse = (FiatStepResponseBase & {
         kind: 'BLOCKED';
     }>;
     provider: FiatProvider;
+    /** 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.
+     */
+    handoff?: {
+        provider: FiatProvider;
+    };
 });
 export {};
 //# sourceMappingURL=types.d.ts.map

package/moonpay.d.ts

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

package/moonpay.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fun-xyz/fiat-contract",
-  "version": "0.16.0",
+  "version": "0.18.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": {
@@ -28,6 +28,11 @@
       "import": "./dist/table.mjs",
       "require": "./dist/table.js"
     },
+    "./moonpay": {
+      "types": "./dist/providers/moonpay.d.ts",
+      "import": "./dist/providers/moonpay.mjs",
+      "require": "./dist/providers/moonpay.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -36,6 +41,8 @@
     "table.d.ts",
     "types.js",
     "types.d.ts",
+    "moonpay.js",
+    "moonpay.d.ts",
     "README.md",
     "!dist/**/*.map"
   ],
@@ -75,6 +82,9 @@
       ],
       "table": [
         "./dist/table.d.ts"
+      ],
+      "moonpay": [
+        "./dist/providers/moonpay.d.ts"
       ]
     }
   }