@fun-xyz/fiat-contract 0.2.1

package/dist/chunk-IUYT5BR2.mjs

@@ -0,0 +1,412 @@
+// src/table.ts
+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;
+}
+
+export {
+  TABLE_VERSION,
+  TERMINAL_ORDER_STATUSES,
+  TRANSITION_TABLE,
+  STATE_KEYS,
+  DOCUMENTED_ENDPOINTS,
+  stateKey,
+  tableEntry,
+  isTerminal
+};
+//# sourceMappingURL=chunk-IUYT5BR2.mjs.map

package/dist/chunk-KIQOUUEZ.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-KIQOUUEZ.mjs.map

package/dist/fixtures/data.d.ts

@@ -0,0 +1,8 @@
+/**
+ * GENERATED — do not edit. Run `npm run generate:fixtures` after changing any fixture .json.
+ *
+ * The .json files in this directory remain the verbatim record copied from the docs; this module
+ * inlines them so the package never touches the filesystem (React Native, browsers, CJS output).
+ */
+export declare const FIXTURE_DATA: Readonly<Record<string, unknown>>;
+//# sourceMappingURL=data.d.ts.map

package/dist/fixtures/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * fiat-contract — recorded fixtures + loader.
+ *
+ * Every `.json` file in this directory is an envelope copied **verbatim** from the docs — the FE
+ * doc's per-screen "State details" envelopes plus the contract doc's worked example. The one
+ * exception is `screen-04-order-review.json`, whose payload the doc publishes *by reference*
+ * ("quote: <same shape as Screen 1, refreshed>"): its quote is Screen 1's payload verbatim.
+ * They are
+ * already synthetic (`q_8f2`, `o_31c`, `eyJ…`, `"…"` placeholders); the redaction rule applies to
+ * fixtures too, so never replace a fake session token, bank field, or PII value with a real one.
+ *
+ * Two fixture shapes exist:
+ *  - `complete: true`  — a full envelope (`state` + `provider` + `transitions`) ⇒ `assertEnvelope`
+ *  - `complete: false` — a doc excerpt that omits `provider` ⇒ `assertEnvelopeFragment`
+ *    (`provider` is always present on the wire; the contract doc's worked example just elides it)
+ */
+import type { StateKey } from '../table';
+export type FixtureSource = 'FE_DOC' | 'CONTRACT_DOC';
+export interface FixtureMeta {
+    id: string;
+    file: string;
+    source: FixtureSource;
+    /** Where in the source doc this envelope is published. */
+    docRef: string;
+    /** FE doc screen number, when the fixture comes from a screen card. */
+    screen?: number;
+    stateKey: StateKey;
+    /** `false` ⇒ the doc excerpt omits `provider`; validate as a fragment. */
+    complete: boolean;
+    notes?: readonly string[];
+}
+export declare const FIXTURES: readonly FixtureMeta[];
+/**
+ * State entries with no published envelope to record. Declared so missing coverage is visible
+ * instead of silent — the fixture test asserts coverage equals (all state keys − these).
+ */
+export declare const FIXTURE_COVERAGE_GAPS: readonly {
+    stateKey: StateKey;
+    reason: string;
+}[];
+export declare const fixtureMeta: (id: string) => FixtureMeta;
+/**
+ * Raw envelope — deliberately `unknown`, so callers validate before use.
+ *
+ * Reads from the generated `data.ts`: no filesystem, so this works under React Native, in a
+ * browser, and in both CJS and ESM output. A fresh deep copy each call, so a consumer mutating a
+ * fixture in one test cannot poison another.
+ */
+export declare function loadFixture(id: string): unknown;
+export interface LoadedFixture {
+    meta: FixtureMeta;
+    json: unknown;
+}
+export declare function loadFixtures(): LoadedFixture[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * fiat-contract — the published contract between `fun-backend` (emits envelopes) and
+ * `funkit`/`connect-core` (renders them). Types + zod schemas + the transition table as data +
+ * recorded fixtures + assertion helpers. No runtime logic beyond validation and assertion.
+ *
+ * The package version IS the capability handshake's table version (`TABLE_VERSION`).
+ */
+export * from './types';
+export * from './schemas';
+export * from './table';
+export * from './assert';
+export { FIXTURES, FIXTURE_COVERAGE_GAPS, fixtureMeta, loadFixture, loadFixtures, type FixtureMeta, type FixtureSource, type LoadedFixture, } from './fixtures/index';
+//# sourceMappingURL=index.d.ts.map