@fun-xyz/fiat-contract 0.2.1

package/dist/schemas.d.ts

@@ -0,0 +1,98 @@
+/**
+ * fiat-contract — zod schemas
+ *
+ * zod is the single runtime validator: TypeScript cannot validate at the boundary, and the
+ * table (`src/table.ts`) cannot reject a *malformed* envelope — only an illegal *sequence*.
+ *
+ * Every object schema is `.strict()`: an undeclared key is a contract violation, not extra data.
+ *
+ * The accepted params/inputs/expects split is enforced structurally here — `params` values are
+ * `JsonValue` literals and are *rejected* if they carry a `FieldSpec`-shaped `type`, while `inputs`
+ * values must be `FieldSpec` objects. The old double-duty bug is unrepresentable, not discouraged.
+ *
+ * ## Why every export is annotated `z.ZodType<T>`
+ *
+ * Left un-annotated, tsc bakes the *structural* zod type into the emitted `.d.ts`
+ * (`ZodObject<…, $strip>`, `z.core.$ZodEnum<…>`, object-form `ZodEnum`). Those internals differ
+ * between zod majors, so declarations built against zod 4 resolve to errors — or, under the
+ * `skipLibCheck: true` that both consumer repos use, silently to `any` — for a consumer on zod 3.
+ * Annotating with `z.ZodType<T>` makes the declarations name nothing but `z.ZodType`, which exists
+ * with the same 1-argument form in every supported major.
+ *
+ * The cost: consumers get `.parse` / `.safeParse` / `.optional()`, not `.shape` / `.extend`. That
+ * is deliberate — this is a contract to validate against, not a base to compose from.
+ *
+ * The internal `$`-prefixed consts keep their inferred structural types so the mirror assertions at
+ * the bottom of this file still prove the schemas match the hand-written types in `types.ts`.
+ * They are module-private, so none of it reaches the published declarations.
+ */
+import { z } from 'zod';
+import type { CryptoAmount, FailureReason, FeeLine, FiatEndpoint, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, Instructions, InstructionField, Instrument, JsonValue, FiatAmount, OrderRef, OrderStatus, OrderSummary, PollSpec, FiatProvider, Quote, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, StepResponse, Surface, Transition, TransitionInputs, TransitionParams, Tx } from './types';
+/** The envelope as doc excerpts show it: `provider` elided. Never valid on the wire. */
+export type EnvelopeFragment = Omit<StepResponse, 'provider'> & {
+    provider?: FiatProvider;
+};
+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. */
+export declare const ENDPOINT_PATTERN: RegExp;
+export declare const FiatEndpointSchema: z.ZodType<FiatEndpoint>;
+export declare const FiatProviderSchema: z.ZodType<FiatProvider>;
+export declare const OrderStatusSchema: z.ZodType<OrderStatus>;
+export declare const RecoverySchema: z.ZodType<Recovery>;
+export declare const FailureReasonSchema: z.ZodType<FailureReason>;
+export declare const FiatAmountSchema: z.ZodType<FiatAmount>;
+export declare const CryptoAmountSchema: z.ZodType<CryptoAmount>;
+export declare const FeeLineSchema: z.ZodType<FeeLine>;
+export declare const QuoteSchema: z.ZodType<Quote>;
+export declare const InstrumentSchema: z.ZodType<Instrument>;
+export declare const OrderRefSchema: z.ZodType<OrderRef>;
+export declare const OrderSummarySchema: z.ZodType<OrderSummary>;
+export declare const StatusHistoryEntrySchema: z.ZodType<StatusHistoryEntry>;
+export declare const TxSchema: z.ZodType<Tx>;
+export declare const RefundSchema: z.ZodType<Refund>;
+export declare const SurfaceSchema: z.ZodType<Surface>;
+export declare const InstructionFieldSchema: z.ZodType<InstructionField>;
+export declare const InstructionsSchema: z.ZodType<Instructions>;
+export declare const SelectOptionSchema: z.ZodType<SelectOption>;
+export declare const FormFieldTypeSchema: z.ZodType<FormFieldType>;
+export declare const FormFieldSchema: z.ZodType<FormField>;
+export declare const FormDescriptorSchema: z.ZodType<FormDescriptor>;
+export declare const FIELD_SPEC_TYPES: readonly ["TEXT", "DATE", "COUNTRY", "FILE", "SELECT", "HOSTED_LINK", "FORM_VALUES"];
+export declare const FieldSpecSchema: z.ZodType<FieldSpec>;
+/**
+ * True when a `params` value is wearing a `FieldSpec`'s clothes — i.e. the exact defect the
+ * accepted split exists to kill (a spec object spread into a request body as if it were a value).
+ */
+export declare const looksLikeFieldSpec: (value: unknown) => boolean;
+export declare const TransitionParamsSchema: z.ZodType<TransitionParams>;
+export declare const TransitionInputsSchema: z.ZodType<TransitionInputs>;
+export declare const PollSpecSchema: z.ZodType<PollSpec>;
+export declare const ReportSpecSchema: z.ZodType<ReportSpec>;
+export declare const TransitionSchema: z.ZodType<Transition>;
+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, {
+    kind: K;
+}> : Extract<FlowState, {
+    kind: K;
+    phase: P;
+}>;
+export declare const QuoteStateSchema: z.ZodType<State<'QUOTE'>>;
+export declare const FunAuthStateSchema: z.ZodType<State<'FUN_AUTH'>>;
+export declare const SessionAuthStateSchema: z.ZodType<State<'SESSION_AUTH'>>;
+export declare const KycCaptureStateSchema: z.ZodType<State<'KYC', 'CAPTURE'>>;
+export declare const KycInputRequiredStateSchema: z.ZodType<State<'KYC', 'INPUT_REQUIRED'>>;
+export declare const KycNoActionRequiredStateSchema: z.ZodType<State<'KYC', 'NO_ACTION_REQUIRED'>>;
+export declare const PendingOrderStateSchema: z.ZodType<State<'PENDING_ORDER'>>;
+export declare const BlockedStateSchema: z.ZodType<State<'BLOCKED'>>;
+export declare const PaymentCaptureStateSchema: z.ZodType<State<'PAYMENT', 'CAPTURE'>>;
+export declare const PaymentInstructStateSchema: z.ZodType<State<'PAYMENT', 'INSTRUCT'>>;
+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 StepResponseSchema: z.ZodType<StepResponse>;
+export declare const StepResponseFragmentSchema: z.ZodType<EnvelopeFragment>;
+export declare const EnvelopeSchema: z.ZodType<StepResponse>;
+export {};
+//# sourceMappingURL=schemas.d.ts.map

package/dist/table.d.ts

@@ -0,0 +1,97 @@
+/**
+ * fiat-contract — the transition table, as data. **This file IS the published contract.**
+ *
+ * Per state entry:
+ *   (a) `allowedTransitions` — the legal transition set the state may carry
+ *   (b) `mayReturn` — the legal states any call from it may return
+ *       (source: FE doc §"Event bindings per flow state", column 4 "May receive back")
+ *   (c) `terminal` — enumerated, never inferred. Empty transitions ≠ terminal: `KYC ON_HOLD`
+ *       carries `transitions: []` and is NOT terminal.
+ *
+ * Rules the entries obey:
+ *   - Terminality of `ORDER{CREATED}` rides `status`, because terminal outcomes are OrderStatus,
+ *     never kinds (contract §The envelope). The set is enumerated below as
+ *     `TERMINAL_ORDER_STATUSES` — clients read it, they never derive it.
+ *   - A terminal *state* carries no transitions. A terminal *status* still can: `FAILED` with a
+ *     retryable `failureReason` carries the recovery CTA (FE doc Screen 14).
+ *   - The stale rule means any call may return any state. `mayReturn` is the conformance
+ *     assertion on the *typical* server sequence — the client never uses it to gate rendering.
+ */
+import type { FiatEndpoint, FlowState, OrderStatus, TransitionMode } from './types';
+/**
+ * The package version IS the capability handshake's table version (contract §Conformance
+ * package → Versioning). Must equal `package.json#version` — asserted in the test suite.
+ */
+export declare const TABLE_VERSION = "0.2.1";
+/**
+ * State identity = kind + phase + the state's named discriminant (FE doc §Decisions).
+ * The table keys on kind + phase (+ `reason` for KYC, whose three reasons differ in terminality
+ * and in what they may carry).
+ */
+export type StateKey = 'QUOTE' | 'FUN_AUTH' | 'SESSION_AUTH' | 'KYC/CAPTURE' | 'KYC/INPUT_REQUIRED' | 'KYC/NO_ACTION_REQUIRED:IN_REVIEW' | 'KYC/NO_ACTION_REQUIRED:ON_HOLD' | 'KYC/NO_ACTION_REQUIRED:REJECTED' | 'PENDING_ORDER' | 'BLOCKED' | 'PAYMENT/CAPTURE' | 'PAYMENT/INSTRUCT' | 'ORDER/AWAITING_CONFIRMATION' | 'ORDER/CREATED';
+/**
+ * Terminal per the OrderStatus machine's monotonic ranks (contract §The envelope).
+ *
+ * `CAPTURE_ORPHANED` is deliberately absent — see the TODO(open-decision) on the value itself.
+ * Non-terminal is the safe default for an unknown status: a client that wrongly believes the flow
+ * is over stops polling and the order silently strands, whereas one that keeps polling lets the
+ * reconciler resolve it. Revisit when the backend publishes its rank map.
+ */
+export declare const TERMINAL_ORDER_STATUSES: readonly ["SETTLED", "EXPIRED", "CANCELLED", "FAILED", "REFUNDED"];
+export type TerminalOrderStatus = (typeof TERMINAL_ORDER_STATUSES)[number];
+/**
+ * Endpoint template as written in the docs — `:id` stands for an order id, so
+ * `"POST /fiat/orders/:id/cancel"` matches the emitted `"POST /fiat/orders/o_31c/cancel"`.
+ */
+export type EndpointTemplate = FiatEndpoint;
+export interface AllowedTransition {
+    /**
+     * The id observed in the docs' envelopes. Informational: ids are localization keys and the
+     * docs explicitly allow unknown ids (the client falls back to `labelFallback`), so
+     * `assertLegalEmission` matches on `mode` + `endpoint`, not on `id`.
+     */
+    id: string;
+    mode: TransitionMode;
+    endpoint: EndpointTemplate;
+    /** When this entry is emitted, if it is conditional. */
+    when?: string;
+    note?: string;
+}
+export interface TableEntry {
+    key: StateKey;
+    kind: FlowState['kind'];
+    phase?: string;
+    /** KYC `NO_ACTION_REQUIRED` only. */
+    reason?: 'IN_REVIEW' | 'ON_HOLD' | 'REJECTED';
+    /** FE doc screen numbers that render this state. */
+    screens: readonly number[];
+    /**
+     * `SPECIFIED` — the docs enumerate this state's legal transitions.
+     * `UNSPECIFIED` — they do not; `assertLegalEmission` cannot judge emissions here and says so.
+     */
+    docStatus: 'SPECIFIED' | 'UNSPECIFIED';
+    allowedTransitions: readonly AllowedTransition[];
+    /** Absent when the docs publish no bindings row for this state. */
+    mayReturn?: readonly StateKey[];
+    /** Flow-terminal. Enumerated here so no SDK infers it. */
+    terminal: boolean;
+    /** `ORDER{CREATED}` only: the statuses that end the flow. */
+    terminalStatuses?: readonly OrderStatus[];
+    notes?: readonly string[];
+}
+export declare const TRANSITION_TABLE: Readonly<Record<StateKey, TableEntry>>;
+export declare const STATE_KEYS: StateKey[];
+/**
+ * The `/fiat/*` surface as enumerated in contract §Endpoints. Informational data — emissions are
+ * checked against each state's `allowedTransitions`, not against this list.
+ */
+export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/kyc", "POST /fiat/kyc/form", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
+/** State → its table key. The one place kind/phase/reason is flattened. */
+export declare function stateKey(state: FlowState): StateKey;
+export declare const tableEntry: (state: FlowState) => TableEntry;
+/**
+ * Flow-terminal, read from the table — never inferred from `transitions.length`.
+ * `ORDER{CREATED}` is terminal when its status is in the entry's `terminalStatuses`.
+ */
+export declare function isTerminal(state: FlowState): boolean;
+//# sourceMappingURL=table.d.ts.map

package/dist/table.js

@@ -0,0 +1,432 @@
+"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/table.ts
+var table_exports = {};
+__export(table_exports, {
+  DOCUMENTED_ENDPOINTS: () => DOCUMENTED_ENDPOINTS,
+  STATE_KEYS: () => STATE_KEYS,
+  TABLE_VERSION: () => TABLE_VERSION,
+  TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
+  TRANSITION_TABLE: () => TRANSITION_TABLE,
+  isTerminal: () => isTerminal,
+  stateKey: () => stateKey,
+  tableEntry: () => tableEntry
+});
+module.exports = __toCommonJS(table_exports);
+var TABLE_VERSION = "0.2.1";
+var TERMINAL_ORDER_STATUSES = [
+  "SETTLED",
+  "EXPIRED",
+  "CANCELLED",
+  "FAILED",
+  "REFUNDED"
+];
+var KYC_ANY = [
+  "KYC/CAPTURE",
+  "KYC/INPUT_REQUIRED",
+  "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+  "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+  "KYC/NO_ACTION_REQUIRED:REJECTED"
+];
+var TRANSITION_TABLE = {
+  QUOTE: {
+    key: "QUOTE",
+    kind: "QUOTE",
+    screens: [1],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "continue",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/session",
+        when: "no valid provider session token (own-tables check)"
+      },
+      {
+        id: "continue",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders",
+        when: "returning user, session + KYC valid \u2014 the quote screen doubles as review"
+      },
+      {
+        id: "continue",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/auth",
+        when: "no ambient Fun identity (non-fomo surfaces only)"
+      }
+    ],
+    mayReturn: [
+      "SESSION_AUTH",
+      ...KYC_ANY,
+      "PENDING_ORDER",
+      "ORDER/AWAITING_CONFIRMATION",
+      "ORDER/CREATED",
+      "BLOCKED"
+    ],
+    terminal: false,
+    notes: [
+      "Re-quote on amount change is a client-local event, not a transition.",
+      'If the PENDING_ORDER removal lands, QUOTE additionally returns PAYMENT{INSTRUCT} / ORDER{CREATED} directly. TODO(open-decision): contract \xA7"Proposal: remove PENDING_ORDER".'
+    ]
+  },
+  FUN_AUTH: {
+    key: "FUN_AUTH",
+    kind: "FUN_AUTH",
+    screens: [],
+    docStatus: "UNSPECIFIED",
+    allowedTransitions: [],
+    terminal: false,
+    notes: [
+      "TODO(open-decision): shape and transitions owned by the auth spike (contract \xA7Auth & ref binding, item 5).",
+      "Never renders in fomo \u2014 identity is ambient, so the FE doc gives it no screen and no bindings row."
+    ]
+  },
+  SESSION_AUTH: {
+    key: "SESSION_AUTH",
+    kind: "SESSION_AUTH",
+    screens: [2],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" }
+    ],
+    mayReturn: [
+      "SESSION_AUTH",
+      ...KYC_ANY,
+      "ORDER/AWAITING_CONFIRMATION",
+      "PENDING_ORDER"
+    ],
+    terminal: false,
+    notes: [
+      "A bad code re-enters this same state with error {category: USER_ERROR, code: BAD_CODE} \u2014 banner, not a screen change.",
+      "No resend affordance is specified in either doc (known gap, FE doc Screen 2)."
+    ]
+  },
+  "KYC/CAPTURE": {
+    key: "KYC/CAPTURE",
+    kind: "KYC",
+    phase: "CAPTURE",
+    screens: [8],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "GET /fiat/kyc",
+        note: 'report target per FE bindings ("POST surface report \u2192 GET /fiat/kyc") and contract Flow C.'
+      }
+    ],
+    mayReturn: [
+      "KYC/INPUT_REQUIRED",
+      "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+      "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "ORDER/AWAITING_CONFIRMATION"
+    ],
+    terminal: false,
+    notes: [
+      "Dropped from v1 (no UK headless-module coverage) \u2014 FE Screen 8 is a tombstone. Kind retained as vocabulary; the handshake (supportedStepKinds) keeps the backend from routing v1 SDKs here."
+    ]
+  },
+  "KYC/INPUT_REQUIRED": {
+    key: "KYC/INPUT_REQUIRED",
+    kind: "KYC",
+    phase: "INPUT_REQUIRED",
+    screens: [3],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      { id: "submit_round", mode: "SUBMIT", endpoint: "POST /fiat/kyc/form" }
+    ],
+    mayReturn: [
+      "KYC/INPUT_REQUIRED",
+      "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+      "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "ORDER/AWAITING_CONFIRMATION"
+    ],
+    terminal: false,
+    notes: [
+      "One POST per round; conditional requirements may open another round.",
+      "FILE fields stream to POST /fiat/kyc/document \u2014 an upload path the harness owns, not a transition.",
+      "Hosted KYC links arrive as HOSTED_LINK form fields, not as a Surface."
+    ]
+  },
+  "KYC/NO_ACTION_REQUIRED:IN_REVIEW": {
+    key: "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+    kind: "KYC",
+    phase: "NO_ACTION_REQUIRED",
+    reason: "IN_REVIEW",
+    screens: [9],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [{ id: "poll", mode: "AWAIT", endpoint: "GET /fiat/kyc" }],
+    mayReturn: [
+      "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/INPUT_REQUIRED",
+      "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+      "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "ORDER/AWAITING_CONFIRMATION"
+    ],
+    terminal: false,
+    notes: [
+      "Documented poll shape: intervalMs 3000, backoffFactor 1.5, maxIntervalMs 10000, giveUpAfterMs 90000.",
+      "Pre-order giveUp destination is a design gap (FE doc Screen 9) \u2014 client-local, no contract impact."
+    ]
+  },
+  "KYC/NO_ACTION_REQUIRED:ON_HOLD": {
+    key: "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+    kind: "KYC",
+    phase: "NO_ACTION_REQUIRED",
+    reason: "ON_HOLD",
+    screens: [10],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [],
+    mayReturn: KYC_ANY,
+    terminal: false,
+    notes: [
+      "THE proof that terminality is not array emptiness: transitions [] and NOT terminal. Re-entry after retryAfter re-derives."
+    ]
+  },
+  "KYC/NO_ACTION_REQUIRED:REJECTED": {
+    key: "KYC/NO_ACTION_REQUIRED:REJECTED",
+    kind: "KYC",
+    phase: "NO_ACTION_REQUIRED",
+    reason: "REJECTED",
+    screens: [11],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "escalate",
+        mode: "SUBMIT",
+        endpoint: "GET /fiat/kyc",
+        when: "an escalation round is offered",
+        note: "TODO(open-decision): placeholder shape \u2014 the FE doc flags that a GET carrying params is not a real request shape, and OQ7 owns which rejections escalate. FE doc open question 7."
+      }
+    ],
+    mayReturn: KYC_ANY,
+    terminal: false,
+    notes: [
+      "Terminal *variant*: failureReason {KYC_REJECTED, retryable: false, recovery: CONTACT_SUPPORT} + transitions [] \u2014 renders in place, never routes through ORDER{CREATED, FAILED}. Because escalation is also legal here, the entry is not flatly terminal.",
+      "TODO(open-decision): contract OQ7 \u2014 terminal vs escalating rejections are not enumerated."
+    ]
+  },
+  PENDING_ORDER: {
+    key: "PENDING_ORDER",
+    kind: "PENDING_ORDER",
+    screens: [12],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      { id: "resume", mode: "SUBMIT", endpoint: "GET /fiat/orders/:id" },
+      { id: "cancel", mode: "SUBMIT", endpoint: "POST /fiat/orders/:id/cancel" }
+    ],
+    mayReturn: ["ORDER/CREATED", "QUOTE"],
+    terminal: false,
+    notes: [
+      'TODO(open-decision): removal proposed (contract \xA7"Proposal: remove PENDING_ORDER"); FE Screen 12 is frozen until it lands. The two-call resume-or-cancel shape is why transitions is an array.',
+      "SUBMIT is a user-fired request, not a POST: GET /fiat/orders/:id under SUBMIT is legal."
+    ]
+  },
+  BLOCKED: {
+    key: "BLOCKED",
+    kind: "BLOCKED",
+    screens: [16],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [],
+    mayReturn: [],
+    terminal: true,
+    notes: [
+      "Region/compliance block \u2014 fires from anywhere (contract \xA7Global transitions). retryAfter renders a dated comeback; null = none.",
+      "TODO(open-decision): v1 scope assumed yes for FCA/UK \u2014 product confirm (FE doc open question 4)."
+    ]
+  },
+  "PAYMENT/CAPTURE": {
+    key: "PAYMENT/CAPTURE",
+    kind: "PAYMENT",
+    phase: "CAPTURE",
+    screens: [5],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders",
+        when: "capture-then-order topology (Transak headless cards: the component yields requestId, an input to createOrder)",
+        note: 'TODO(open-decision): report target per card topology \u2014 Transak ask (contract Flow A: "confirm before freeze").'
+      },
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders/:id/surface-result",
+        when: "the order already exists (order-then-capture topology)",
+        note: 'Endpoint per contract \xA7Endpoints ("client reports CLIENT_SURFACE outcome; backend reconciles vs webhooks").'
+      }
+    ],
+    mayReturn: ["ORDER/CREATED", "PAYMENT/CAPTURE", "QUOTE"],
+    terminal: false,
+    notes: [
+      "Decline re-entry: same state, fresh surface.session, error {category: PAYMENT_DECLINED, retryable: true, recovery: RETRY_PAYMENT}.",
+      "The Surface is carried in state, never in the transition (\u03942, single-carry)."
+    ]
+  },
+  "PAYMENT/INSTRUCT": {
+    key: "PAYMENT/INSTRUCT",
+    kind: "PAYMENT",
+    phase: "INSTRUCT",
+    screens: [6],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "confirm_paid",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders/:id/confirm-payment"
+      },
+      {
+        id: "cancel",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders/:id/cancel",
+        when: "in-wizard cancel placement wins",
+        note: "TODO(open-decision): cancel placement \u2014 in-wizard vs an out-of-wizard pending-orders surface (FE doc open questions 1+2). Per-rail cancel eligibility is contract OQ7."
+      }
+    ],
+    mayReturn: ["ORDER/CREATED"],
+    terminal: false,
+    notes: [
+      "No instructions re-issue endpoint exists; expired-instructions recovery is unenumerated. TODO(open-decision): contract OQ7.",
+      "Async instructions (PREPARING) are deliberately not in v1 \u2014 Transak returns bank details synchronously."
+    ]
+  },
+  "ORDER/AWAITING_CONFIRMATION": {
+    key: "ORDER/AWAITING_CONFIRMATION",
+    kind: "ORDER",
+    phase: "AWAITING_CONFIRMATION",
+    screens: [4],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [{ id: "confirm", mode: "SUBMIT", endpoint: "POST /fiat/orders" }],
+    mayReturn: [
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
+      "ORDER/CREATED",
+      "QUOTE",
+      "PENDING_ORDER"
+    ],
+    terminal: false,
+    notes: [
+      "Bank rails only \u2014 card rails skip it, the pay sheet was the confirmation.",
+      "Carries a refreshed quote: the price may have drifted during KYC."
+    ]
+  },
+  "ORDER/CREATED": {
+    key: "ORDER/CREATED",
+    kind: "ORDER",
+    phase: "CREATED",
+    screens: [7, 13, 14, 15],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "poll",
+        mode: "AWAIT",
+        endpoint: "GET /fiat/orders/:id",
+        when: "status is non-terminal",
+        note: "Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
+      },
+      {
+        id: "retry_payment",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders",
+        when: "failureReason.recovery === RETRY_PAYMENT"
+      },
+      {
+        id: "requote",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/quote",
+        when: "failureReason.recovery === REQUOTE"
+      },
+      {
+        id: "cancel",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders/:id/cancel",
+        when: "in-wizard cancel placement wins and the rail allows it",
+        note: "TODO(open-decision): cancel placement (FE doc open questions 1+2); per-rail eligibility is contract OQ7."
+      }
+    ],
+    mayReturn: ["ORDER/CREATED"],
+    terminal: false,
+    terminalStatuses: TERMINAL_ORDER_STATUSES,
+    notes: [
+      "Flow-terminality here rides status \u2208 terminalStatuses, not the state kind and not array emptiness.",
+      "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
+      "ON_HOLD is a non-terminal status (resolves to PROCESSING or REFUNDED) \u2014 and is NOT the same thing as the KYC ON_HOLD reason; see the note on that field.",
+      "CAPTURE_ORPHANED is non-terminal pending the backend rank map (added from review 2026-08-14).",
+      "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
+    ]
+  }
+};
+var STATE_KEYS = Object.keys(TRANSITION_TABLE);
+var DOCUMENTED_ENDPOINTS = [
+  "GET /fiat/payment-methods",
+  "POST /fiat/quote",
+  "POST /fiat/auth",
+  "POST /fiat/session",
+  "POST /fiat/session/verify",
+  "GET /fiat/kyc",
+  "POST /fiat/kyc/form",
+  "POST /fiat/kyc/document",
+  "POST /fiat/instruments",
+  "POST /fiat/orders",
+  "GET /fiat/orders/:id",
+  "GET /fiat/orders/:id/instructions",
+  "POST /fiat/orders/:id/confirm-payment",
+  "POST /fiat/orders/:id/reference",
+  "POST /fiat/orders/:id/cancel",
+  "POST /fiat/orders/:id/surface-result"
+];
+function stateKey(state) {
+  switch (state.kind) {
+    case "QUOTE":
+      return "QUOTE";
+    case "FUN_AUTH":
+      return "FUN_AUTH";
+    case "SESSION_AUTH":
+      return "SESSION_AUTH";
+    case "PENDING_ORDER":
+      return "PENDING_ORDER";
+    case "BLOCKED":
+      return "BLOCKED";
+    case "KYC": {
+      if (state.phase === "CAPTURE") return "KYC/CAPTURE";
+      if (state.phase === "INPUT_REQUIRED") return "KYC/INPUT_REQUIRED";
+      return `KYC/NO_ACTION_REQUIRED:${state.reason}`;
+    }
+    case "PAYMENT":
+      return state.phase === "CAPTURE" ? "PAYMENT/CAPTURE" : "PAYMENT/INSTRUCT";
+    case "ORDER":
+      return state.phase === "AWAITING_CONFIRMATION" ? "ORDER/AWAITING_CONFIRMATION" : "ORDER/CREATED";
+    default: {
+      const exhaustive = state;
+      throw new Error(`unknown FlowState: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+var tableEntry = (state) => TRANSITION_TABLE[stateKey(state)];
+function isTerminal(state) {
+  const entry = tableEntry(state);
+  if (entry.terminalStatuses && state.kind === "ORDER" && state.phase === "CREATED") {
+    return entry.terminalStatuses.includes(state.status);
+  }
+  return entry.terminal;
+}
+//# sourceMappingURL=table.js.map

package/dist/table.mjs

@@ -0,0 +1,21 @@
+import {
+  DOCUMENTED_ENDPOINTS,
+  STATE_KEYS,
+  TABLE_VERSION,
+  TERMINAL_ORDER_STATUSES,
+  TRANSITION_TABLE,
+  isTerminal,
+  stateKey,
+  tableEntry
+} from "./chunk-IUYT5BR2.mjs";
+export {
+  DOCUMENTED_ENDPOINTS,
+  STATE_KEYS,
+  TABLE_VERSION,
+  TERMINAL_ORDER_STATUSES,
+  TRANSITION_TABLE,
+  isTerminal,
+  stateKey,
+  tableEntry
+};
+//# sourceMappingURL=table.mjs.map