@fun-xyz/fiat-contract 0.2.1

package/dist/index.mjs

@@ -0,0 +1,1253 @@
+import "./chunk-KIQOUUEZ.mjs";
+import {
+  DOCUMENTED_ENDPOINTS,
+  STATE_KEYS,
+  TABLE_VERSION,
+  TERMINAL_ORDER_STATUSES,
+  TRANSITION_TABLE,
+  isTerminal,
+  stateKey,
+  tableEntry
+} from "./chunk-IUYT5BR2.mjs";
+
+// src/schemas.ts
+import { z } from "zod";
+var obj = (shape) => z.object(shape).strict();
+var JsonSchema = z.lazy(
+  () => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonSchema),
+    z.record(z.string(), JsonSchema)
+  ])
+);
+var HTTP_VERBS = ["GET", "POST"];
+var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
+var $endpoint = z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
+var FiatEndpointSchema = $endpoint;
+var $provider = z.enum(["TRANSAK", "SWAPPED"]);
+var FiatProviderSchema = $provider;
+var $orderStatus = z.enum([
+  "CREATING",
+  "AWAITING_PAYMENT",
+  "PAYMENT_VERIFYING",
+  "PROCESSING",
+  "PENDING_DELIVERY",
+  "ON_HOLD",
+  "CRYPTO_SENT",
+  "SETTLED",
+  "EXPIRED",
+  "CANCELLED",
+  "FAILED",
+  "REFUNDED",
+  "CAPTURE_ORPHANED"
+]);
+var OrderStatusSchema = $orderStatus;
+var $recovery = z.enum(["REQUOTE", "RETRY_PAYMENT", "CONTACT_SUPPORT", "NONE"]);
+var RecoverySchema = $recovery;
+var $failureReason = z.union([
+  obj({
+    category: z.enum([
+      "PAYMENT_DECLINED",
+      "KYC_REJECTED",
+      "PROVIDER_OUTAGE",
+      "USER_ERROR",
+      "CANCELLED"
+    ]),
+    retryable: z.boolean(),
+    recovery: $recovery,
+    code: z.string().optional()
+  }),
+  obj({
+    category: z.literal("EXPIRED"),
+    which: z.enum(["QUOTE", "PAYMENT_WINDOW", "INSTRUCTIONS"]),
+    retryable: z.boolean(),
+    recovery: $recovery,
+    code: z.string().optional()
+  })
+]);
+var FailureReasonSchema = $failureReason;
+var $money = obj({ currency: z.string(), amount: z.string() });
+var FiatAmountSchema = $money;
+var $cryptoAmount = obj({
+  currency: z.string(),
+  network: z.string(),
+  amount: z.string()
+});
+var CryptoAmountSchema = $cryptoAmount;
+var $feeLine = obj({ id: z.string(), labelFallback: z.string(), amount: z.string() });
+var FeeLineSchema = $feeLine;
+var $quote = obj({
+  quoteRef: z.string(),
+  fiat: $money,
+  crypto: $cryptoAmount,
+  rate: z.string(),
+  totalFee: z.string(),
+  feeBreakdown: z.array($feeLine),
+  paymentMethod: z.string(),
+  expiresAt: z.string()
+});
+var QuoteSchema = $quote;
+var $instrument = obj({ brandLabel: z.string(), last4: z.string() });
+var InstrumentSchema = $instrument;
+var $orderRef = obj({
+  orderId: z.string(),
+  fiat: $money,
+  crypto: $cryptoAmount,
+  method: z.string(),
+  createdAt: z.string(),
+  status: $orderStatus
+});
+var OrderRefSchema = $orderRef;
+var $orderSummary = obj({
+  orderId: z.string(),
+  fiat: $money,
+  crypto: $cryptoAmount.optional(),
+  method: z.string(),
+  createdAt: z.string(),
+  instrument: $instrument.optional()
+});
+var OrderSummarySchema = $orderSummary;
+var $statusHistoryEntry = obj({ status: $orderStatus });
+var StatusHistoryEntrySchema = $statusHistoryEntry;
+var $tx = obj({ chainId: z.number(), hash: z.string() });
+var TxSchema = $tx;
+var $refund = obj({
+  currency: z.string(),
+  amount: z.string(),
+  expectedBy: z.string()
+});
+var RefundSchema = $refund;
+var $surface = z.union([
+  obj({ kind: z.literal("URL_REDIRECT"), url: z.string() }),
+  obj({ kind: z.literal("URL_EMBED"), url: z.string() }),
+  obj({ kind: z.literal("PCI_COMPONENT"), session: z.string() }),
+  obj({ kind: z.literal("PAY_SHEET"), session: z.string() }),
+  obj({ kind: z.literal("ACH_COMPONENT"), session: z.string() })
+]);
+var SurfaceSchema = $surface;
+var $instructionField = obj({
+  id: z.string(),
+  labelFallback: z.string(),
+  value: z.string()
+});
+var InstructionFieldSchema = $instructionField;
+var $instructions = z.union([
+  obj({ kind: z.literal("DEEPLINK"), url: z.string(), appVariants: z.array(z.string()) }),
+  obj({ kind: z.literal("QR_IMAGE"), url: z.string() }),
+  obj({
+    kind: z.literal("BANK_FIELDS"),
+    fields: z.array($instructionField),
+    expiresAt: z.string().optional()
+  }),
+  obj({ kind: z.literal("REFERENCE"), code: z.string(), expiresAt: z.string() })
+]);
+var InstructionsSchema = $instructions;
+var $selectOption = obj({ id: z.string(), labelFallback: z.string() });
+var SelectOptionSchema = $selectOption;
+var $formFieldType = z.enum(["TEXT", "DATE", "SELECT", "COUNTRY", "FILE", "HOSTED_LINK"]);
+var FormFieldTypeSchema = $formFieldType;
+var $formField = obj({
+  id: z.string(),
+  type: $formFieldType,
+  labelFallback: z.string(),
+  required: z.boolean(),
+  regex: z.string().optional(),
+  options: z.array($selectOption).optional(),
+  url: z.string().optional()
+});
+var FormFieldSchema = $formField;
+var $formDescriptor = obj({ formId: z.string(), fields: z.array($formField) });
+var FormDescriptorSchema = $formDescriptor;
+var FIELD_SPEC_TYPES = [
+  "TEXT",
+  "DATE",
+  "COUNTRY",
+  "FILE",
+  "SELECT",
+  "HOSTED_LINK",
+  "FORM_VALUES"
+];
+var $fieldSpec = z.union([
+  obj({
+    type: z.literal("TEXT"),
+    length: z.number().optional(),
+    regex: z.string().optional(),
+    labelFallback: z.string().optional()
+  }),
+  obj({ type: z.literal("DATE"), labelFallback: z.string().optional() }),
+  obj({ type: z.literal("COUNTRY"), labelFallback: z.string().optional() }),
+  obj({ type: z.literal("FILE"), labelFallback: z.string().optional() }),
+  obj({
+    type: z.literal("SELECT"),
+    options: z.array($selectOption).optional(),
+    labelFallback: z.string().optional()
+  }),
+  obj({ type: z.literal("HOSTED_LINK"), url: z.string(), labelFallback: z.string().optional() }),
+  obj({ type: z.literal("FORM_VALUES") })
+]);
+var FieldSpecSchema = $fieldSpec;
+var looksLikeFieldSpec = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.type === "string" && FIELD_SPEC_TYPES.includes(value.type);
+var $params = z.record(z.string(), JsonSchema).superRefine((params, ctx) => {
+  for (const [key, value] of Object.entries(params)) {
+    if (looksLikeFieldSpec(value)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [key],
+        message: `params.${key} is FieldSpec-shaped ({type: "\u2026"}). params carry server literals the client spreads verbatim; a spec the client must collect belongs in inputs.`
+      });
+    }
+  }
+});
+var TransitionParamsSchema = $params;
+var $inputs = z.record(z.string(), $fieldSpec);
+var TransitionInputsSchema = $inputs;
+var $pollSpec = obj({
+  endpoint: $endpoint,
+  params: $params.optional(),
+  intervalMs: z.number(),
+  backoffFactor: z.number().optional(),
+  maxIntervalMs: z.number().optional(),
+  giveUpAfterMs: z.number().optional()
+});
+var PollSpecSchema = $pollSpec;
+var $reportSpec = obj({
+  endpoint: $endpoint,
+  params: $params.optional(),
+  expects: z.array(z.string()).optional()
+});
+var ReportSpecSchema = $reportSpec;
+var $transition = z.union([
+  obj({
+    id: z.string(),
+    mode: z.literal("SUBMIT"),
+    endpoint: $endpoint,
+    params: $params.optional(),
+    inputs: $inputs.optional(),
+    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 })
+]);
+var TransitionSchema = $transition;
+var $authChallenge = z.record(z.string(), JsonSchema);
+var AuthChallengeSchema = $authChallenge;
+var $quoteState = obj({
+  kind: z.literal("QUOTE"),
+  quote: $quote,
+  error: $failureReason.optional()
+});
+var QuoteStateSchema = $quoteState;
+var $funAuthState = obj({
+  kind: z.literal("FUN_AUTH"),
+  challenge: $authChallenge,
+  error: $failureReason.optional()
+});
+var FunAuthStateSchema = $funAuthState;
+var $sessionAuthState = obj({
+  kind: z.literal("SESSION_AUTH"),
+  channel: z.literal("EMAIL_OTP"),
+  error: $failureReason.optional()
+});
+var SessionAuthStateSchema = $sessionAuthState;
+var $kycCaptureState = obj({
+  kind: z.literal("KYC"),
+  phase: z.literal("CAPTURE"),
+  surface: $surface,
+  error: $failureReason.optional()
+});
+var KycCaptureStateSchema = $kycCaptureState;
+var $kycInputRequiredState = obj({
+  kind: z.literal("KYC"),
+  phase: z.literal("INPUT_REQUIRED"),
+  form: $formDescriptor,
+  error: $failureReason.optional()
+});
+var KycInputRequiredStateSchema = $kycInputRequiredState;
+var $kycNoActionRequiredState = obj({
+  kind: z.literal("KYC"),
+  phase: z.literal("NO_ACTION_REQUIRED"),
+  reason: z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
+  retryAfter: z.string().optional(),
+  failureReason: $failureReason.optional(),
+  error: $failureReason.optional()
+});
+var KycNoActionRequiredStateSchema = $kycNoActionRequiredState;
+var $pendingOrderState = obj({
+  kind: z.literal("PENDING_ORDER"),
+  order: $orderRef,
+  error: $failureReason.optional()
+});
+var PendingOrderStateSchema = $pendingOrderState;
+var $blockedState = obj({
+  kind: z.literal("BLOCKED"),
+  reason: z.string(),
+  retryAfter: z.string().nullable().optional(),
+  error: $failureReason.optional()
+});
+var BlockedStateSchema = $blockedState;
+var $paymentCaptureState = obj({
+  kind: z.literal("PAYMENT"),
+  phase: z.literal("CAPTURE"),
+  surface: $surface,
+  error: $failureReason.optional()
+});
+var PaymentCaptureStateSchema = $paymentCaptureState;
+var $paymentInstructState = obj({
+  kind: z.literal("PAYMENT"),
+  phase: z.literal("INSTRUCT"),
+  orderId: z.string().optional(),
+  instructions: $instructions,
+  error: $failureReason.optional()
+});
+var PaymentInstructStateSchema = $paymentInstructState;
+var $orderAwaitingConfirmationState = obj({
+  kind: z.literal("ORDER"),
+  phase: z.literal("AWAITING_CONFIRMATION"),
+  quote: $quote,
+  error: $failureReason.optional()
+});
+var OrderAwaitingConfirmationStateSchema = $orderAwaitingConfirmationState;
+var $orderCreatedState = obj({
+  kind: z.literal("ORDER"),
+  phase: z.literal("CREATED"),
+  order: $orderSummary.optional(),
+  status: $orderStatus,
+  statusHistory: z.array($statusHistoryEntry).optional(),
+  tx: $tx.optional(),
+  refund: $refund.optional(),
+  failureReason: $failureReason.optional(),
+  error: $failureReason.optional()
+});
+var OrderCreatedStateSchema = $orderCreatedState;
+var $flowState = z.union([
+  $quoteState,
+  $funAuthState,
+  $sessionAuthState,
+  $kycCaptureState,
+  $kycInputRequiredState,
+  $kycNoActionRequiredState,
+  $pendingOrderState,
+  $blockedState,
+  $paymentCaptureState,
+  $paymentInstructState,
+  $orderAwaitingConfirmationState,
+  $orderCreatedState
+]);
+var FlowStateSchema = $flowState;
+var $stepResponse = obj({
+  state: $flowState,
+  provider: $provider,
+  transitions: z.array($transition),
+  orderId: z.string().optional()
+});
+var StepResponseSchema = $stepResponse;
+var $stepResponseFragment = obj({
+  state: $flowState,
+  provider: $provider.optional(),
+  transitions: z.array($transition),
+  orderId: z.string().optional()
+});
+var StepResponseFragmentSchema = $stepResponseFragment;
+var EnvelopeSchema = StepResponseSchema;
+
+// src/fixtures/data.ts
+var FIXTURE_DATA = {
+  "screen-01-quote": {
+    "state": {
+      "kind": "QUOTE",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.09"
+          },
+          {
+            "id": "network_fee",
+            "labelFallback": "Network fee",
+            "amount": "0.50"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "continue",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/session",
+        "params": {
+          "quoteRef": "q_8f2"
+        }
+      }
+    ]
+  },
+  "screen-02-session-auth": {
+    "state": {
+      "kind": "SESSION_AUTH",
+      "channel": "EMAIL_OTP"
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "verify",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/session/verify",
+        "params": {
+          "quoteRef": "q_8f2"
+        },
+        "inputs": {
+          "code": {
+            "type": "TEXT",
+            "length": 6
+          }
+        }
+      }
+    ]
+  },
+  "screen-03-kyc-input-required": {
+    "state": {
+      "kind": "KYC",
+      "phase": "INPUT_REQUIRED",
+      "form": {
+        "formId": "personal_details",
+        "fields": [
+          {
+            "id": "firstName",
+            "type": "TEXT",
+            "labelFallback": "First name",
+            "required": true
+          },
+          {
+            "id": "dob",
+            "type": "DATE",
+            "labelFallback": "Date of birth",
+            "required": true
+          },
+          {
+            "id": "country",
+            "type": "COUNTRY",
+            "labelFallback": "Country",
+            "required": true
+          },
+          {
+            "id": "sourceOfFunds",
+            "type": "SELECT",
+            "labelFallback": "Source of funds",
+            "required": true,
+            "options": [
+              {
+                "id": "salary",
+                "labelFallback": "Salary"
+              }
+            ]
+          },
+          {
+            "id": "idProof",
+            "type": "HOSTED_LINK",
+            "labelFallback": "Verify your ID",
+            "required": true,
+            "url": "\u2026"
+          }
+        ]
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "submit_round",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/kyc/form",
+        "params": {
+          "formId": "personal_details"
+        },
+        "inputs": {
+          "values": {
+            "type": "FORM_VALUES"
+          }
+        }
+      }
+    ]
+  },
+  "screen-04-order-review": {
+    "state": {
+      "kind": "ORDER",
+      "phase": "AWAITING_CONFIRMATION",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.09"
+          },
+          {
+            "id": "network_fee",
+            "labelFallback": "Network fee",
+            "amount": "0.50"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "confirm",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/orders",
+        "params": {
+          "quoteRef": "q_8f2"
+        }
+      }
+    ]
+  },
+  "screen-05-payment-capture": {
+    "state": {
+      "kind": "PAYMENT",
+      "phase": "CAPTURE",
+      "surface": {
+        "kind": "PCI_COMPONENT",
+        "session": "eyJ\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "capture",
+        "mode": "CLIENT_SURFACE",
+        "report": {
+          "endpoint": "POST /fiat/orders",
+          "params": {
+            "quoteRef": "q_8f2"
+          },
+          "expects": [
+            "requestId"
+          ]
+        }
+      }
+    ]
+  },
+  "screen-09-kyc-in-review": {
+    "state": {
+      "kind": "KYC",
+      "phase": "NO_ACTION_REQUIRED",
+      "reason": "IN_REVIEW"
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "poll",
+        "mode": "AWAIT",
+        "poll": {
+          "endpoint": "GET /fiat/kyc",
+          "params": {
+            "quoteRef": "q_8f2"
+          },
+          "intervalMs": 3e3,
+          "backoffFactor": 1.5,
+          "maxIntervalMs": 1e4,
+          "giveUpAfterMs": 9e4
+        }
+      }
+    ]
+  },
+  "screen-10-kyc-on-hold": {
+    "state": {
+      "kind": "KYC",
+      "phase": "NO_ACTION_REQUIRED",
+      "reason": "ON_HOLD",
+      "retryAfter": "2026-08-20T09:00:00Z"
+    },
+    "provider": "TRANSAK",
+    "transitions": []
+  },
+  "screen-11-kyc-rejected-escalation": {
+    "state": {
+      "kind": "KYC",
+      "phase": "NO_ACTION_REQUIRED",
+      "reason": "REJECTED"
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "escalate",
+        "mode": "SUBMIT",
+        "endpoint": "GET /fiat/kyc",
+        "params": {
+          "tier": "escalated"
+        }
+      }
+    ]
+  },
+  "screen-12-pending-order": {
+    "state": {
+      "kind": "PENDING_ORDER",
+      "order": {
+        "orderId": "o_31c",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "method": "bank_transfer",
+        "createdAt": "\u2026",
+        "status": "AWAITING_PAYMENT"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "resume",
+        "mode": "SUBMIT",
+        "endpoint": "GET /fiat/orders/o_31c"
+      },
+      {
+        "id": "cancel",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/orders/o_31c/cancel"
+      }
+    ]
+  },
+  "screen-13-order-settled": {
+    "state": {
+      "kind": "ORDER",
+      "phase": "CREATED",
+      "order": {
+        "orderId": "o_31c",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "method": "card",
+        "instrument": {
+          "brandLabel": "Chase Debit",
+          "last4": "4021"
+        },
+        "createdAt": "\u2026"
+      },
+      "status": "SETTLED",
+      "tx": {
+        "chainId": 137,
+        "hash": "0x\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": []
+  },
+  "screen-14-order-failed": {
+    "state": {
+      "kind": "ORDER",
+      "phase": "CREATED",
+      "order": {
+        "orderId": "o_31c",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "method": "card",
+        "createdAt": "\u2026"
+      },
+      "status": "FAILED",
+      "failureReason": {
+        "category": "PAYMENT_DECLINED",
+        "retryable": true,
+        "recovery": "RETRY_PAYMENT"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "retry_payment",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/orders",
+        "params": {
+          "quoteRef": "q_8f2"
+        }
+      }
+    ]
+  },
+  "screen-15-order-refunded": {
+    "state": {
+      "kind": "ORDER",
+      "phase": "CREATED",
+      "order": {
+        "orderId": "o_31c",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "method": "bank_transfer",
+        "createdAt": "\u2026"
+      },
+      "status": "REFUNDED",
+      "refund": {
+        "currency": "GBP",
+        "amount": "100.00",
+        "expectedBy": "\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": []
+  },
+  "screen-16-blocked": {
+    "state": {
+      "kind": "BLOCKED",
+      "reason": "REGION_UNSUPPORTED",
+      "retryAfter": null
+    },
+    "provider": "TRANSAK",
+    "transitions": []
+  },
+  "worked-example-01-quote": {
+    "state": {
+      "kind": "QUOTE",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.09"
+          },
+          {
+            "id": "network_fee",
+            "labelFallback": "Network fee",
+            "amount": "0.50"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "2026-08-11T21:33:00Z"
+      }
+    },
+    "transitions": [
+      {
+        "id": "continue",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/session",
+        "params": {
+          "quoteRef": "q_8f2"
+        },
+        "inputs": {
+          "email": {
+            "type": "TEXT"
+          }
+        }
+      }
+    ]
+  },
+  "worked-example-02-session-auth": {
+    "state": {
+      "kind": "SESSION_AUTH",
+      "channel": "EMAIL_OTP"
+    },
+    "transitions": [
+      {
+        "id": "verify",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/session/verify",
+        "params": {
+          "quoteRef": "q_8f2"
+        },
+        "inputs": {
+          "code": {
+            "type": "TEXT",
+            "length": 6
+          }
+        }
+      }
+    ]
+  },
+  "worked-example-04-payment-instruct": {
+    "orderId": "o_3d1",
+    "state": {
+      "kind": "PAYMENT",
+      "phase": "INSTRUCT",
+      "instructions": {
+        "kind": "BANK_FIELDS",
+        "fields": [
+          {
+            "id": "beneficiary",
+            "labelFallback": "Beneficiary",
+            "value": "Transak"
+          },
+          {
+            "id": "sort_code",
+            "labelFallback": "Sort code",
+            "value": "04-00-04"
+          },
+          {
+            "id": "account_number",
+            "labelFallback": "Account number",
+            "value": "12345678"
+          },
+          {
+            "id": "reference",
+            "labelFallback": "Reference",
+            "value": "o_3d1"
+          }
+        ],
+        "expiresAt": "\u2026"
+      }
+    },
+    "transitions": [
+      {
+        "id": "confirm_paid",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/orders/o_3d1/confirm-payment"
+      }
+    ]
+  }
+};
+
+// src/fixtures/index.ts
+var FIXTURES = [
+  {
+    id: "screen-01-quote",
+    file: "screen-01-quote.json",
+    source: "FE_DOC",
+    docRef: "Screen 1 \xB7 Quote / review",
+    screen: 1,
+    stateKey: "QUOTE",
+    complete: true
+  },
+  {
+    id: "screen-02-session-auth",
+    file: "screen-02-session-auth.json",
+    source: "FE_DOC",
+    docRef: "Screen 2 \xB7 Verification code (OTP)",
+    screen: 2,
+    stateKey: "SESSION_AUTH",
+    complete: true
+  },
+  {
+    id: "screen-03-kyc-input-required",
+    file: "screen-03-kyc-input-required.json",
+    source: "FE_DOC",
+    docRef: "Screen 3 \xB7 Identity form (KYC)",
+    screen: 3,
+    stateKey: "KYC/INPUT_REQUIRED",
+    complete: true,
+    notes: ["Carries the FORM_VALUES input spec \u2014 the no-double-carry case of the accepted split."]
+  },
+  {
+    id: "screen-04-order-review",
+    file: "screen-04-order-review.json",
+    source: "FE_DOC",
+    docRef: "Screen 4 \xB7 Order review (bank rail)",
+    screen: 4,
+    stateKey: "ORDER/AWAITING_CONFIRMATION",
+    complete: true,
+    notes: [
+      `The screen card publishes this payload by reference \u2014 "quote: <same shape as Screen 1, refreshed>" \u2014 so the quote here is Screen 1's payload verbatim. The numbers are not re-published as refreshed values, so they are unchanged; only the shape is contractual.`
+    ]
+  },
+  {
+    id: "screen-05-payment-capture",
+    file: "screen-05-payment-capture.json",
+    source: "FE_DOC",
+    docRef: "Screen 5 \xB7 Card payment",
+    screen: 5,
+    stateKey: "PAYMENT/CAPTURE",
+    complete: true,
+    notes: [
+      "Capture-then-order topology (report \u2192 POST /fiat/orders, expects requestId).",
+      "TODO(open-decision): report target per card topology is a Transak ask (contract Flow A)."
+    ]
+  },
+  {
+    id: "screen-09-kyc-in-review",
+    file: "screen-09-kyc-in-review.json",
+    source: "FE_DOC",
+    docRef: "Screen 9 \xB7 Verifying identity",
+    screen: 9,
+    stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+    complete: true
+  },
+  {
+    id: "screen-10-kyc-on-hold",
+    file: "screen-10-kyc-on-hold.json",
+    source: "FE_DOC",
+    docRef: "Screen 10 \xB7 Verification on hold",
+    screen: 10,
+    stateKey: "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+    complete: true,
+    notes: ["transitions: [] and NOT terminal \u2014 the fixture that proves terminality is table data."]
+  },
+  {
+    id: "screen-11-kyc-rejected-escalation",
+    file: "screen-11-kyc-rejected-escalation.json",
+    source: "FE_DOC",
+    docRef: "Screen 11 \xB7 Verification unsuccessful",
+    screen: 11,
+    stateKey: "KYC/NO_ACTION_REQUIRED:REJECTED",
+    complete: true,
+    notes: [
+      "TODO(open-decision): the escalation transition is a flagged placeholder \u2014 a GET carrying params is not a real request shape (FE doc Screen 11 + open question 7).",
+      "The terminal REJECTED variant (failureReason + transitions []) is described in prose, not published as JSON \u2014 no fixture."
+    ]
+  },
+  {
+    id: "screen-12-pending-order",
+    file: "screen-12-pending-order.json",
+    source: "FE_DOC",
+    docRef: "Screen 12 \xB7 Order in progress",
+    screen: 12,
+    stateKey: "PENDING_ORDER",
+    complete: true,
+    notes: [
+      "TODO(open-decision): PENDING_ORDER removal proposed; Screen 12 frozen. Kept so 0.1.0 can validate the current shape."
+    ]
+  },
+  {
+    id: "screen-13-order-settled",
+    file: "screen-13-order-settled.json",
+    source: "FE_DOC",
+    docRef: "Screen 13 \xB7 Success",
+    screen: 13,
+    stateKey: "ORDER/CREATED",
+    complete: true
+  },
+  {
+    id: "screen-14-order-failed",
+    file: "screen-14-order-failed.json",
+    source: "FE_DOC",
+    docRef: "Screen 14 \xB7 Something went wrong",
+    screen: 14,
+    stateKey: "ORDER/CREATED",
+    complete: true,
+    notes: ["Terminal status (FAILED) still carrying a recovery transition \u2014 retryable failureReason."]
+  },
+  {
+    id: "screen-15-order-refunded",
+    file: "screen-15-order-refunded.json",
+    source: "FE_DOC",
+    docRef: "Screen 15 \xB7 Refund on the way",
+    screen: 15,
+    stateKey: "ORDER/CREATED",
+    complete: true
+  },
+  {
+    id: "screen-16-blocked",
+    file: "screen-16-blocked.json",
+    source: "FE_DOC",
+    docRef: "Screen 16 \xB7 Not available",
+    screen: 16,
+    stateKey: "BLOCKED",
+    complete: true,
+    notes: ["The only flatly terminal state entry in the table."]
+  },
+  {
+    id: "worked-example-01-quote",
+    file: "worked-example-01-quote.json",
+    source: "CONTRACT_DOC",
+    docRef: "\xA7Worked example, step 1 (method selection)",
+    stateKey: "QUOTE",
+    complete: false,
+    notes: ["Carries inputs {email: {type: TEXT}} \u2014 the collected-spec half of the split."]
+  },
+  {
+    id: "worked-example-02-session-auth",
+    file: "worked-example-02-session-auth.json",
+    source: "CONTRACT_DOC",
+    docRef: "\xA7Worked example, step 2 (session challenge)",
+    stateKey: "SESSION_AUTH",
+    complete: false
+  },
+  {
+    id: "worked-example-04-payment-instruct",
+    file: "worked-example-04-payment-instruct.json",
+    source: "CONTRACT_DOC",
+    docRef: "\xA7Worked example, steps 4\u20135 (order + bank instructions)",
+    stateKey: "PAYMENT/INSTRUCT",
+    complete: false,
+    notes: [
+      "The envelope-sibling `orderId` case. TODO(open-decision): orderId placement (envelope sibling here vs inside state in the FE doc v0)."
+    ]
+  }
+];
+var FIXTURE_COVERAGE_GAPS = [
+  {
+    stateKey: "FUN_AUTH",
+    reason: "No envelope exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
+  },
+  {
+    stateKey: "KYC/CAPTURE",
+    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no envelope was ever published. Kind retained as handshake-gated vocabulary."
+  }
+];
+var fixtureMeta = (id) => {
+  const meta = FIXTURES.find((f) => f.id === id);
+  if (!meta) throw new Error(`unknown fixture: ${id}`);
+  return meta;
+};
+function loadFixture(id) {
+  const meta = fixtureMeta(id);
+  const data = FIXTURE_DATA[meta.id];
+  if (data === void 0) throw new Error(`fixture data missing for ${meta.id} \u2014 run npm run generate:fixtures`);
+  return JSON.parse(JSON.stringify(data));
+}
+function loadFixtures() {
+  return FIXTURES.map((meta) => ({ meta, json: loadFixture(meta.id) }));
+}
+
+// src/assert.ts
+var ContractViolation = class extends Error {
+  issues;
+  constructor(message, issues = []) {
+    super(issues.length ? `${message}
+  - ${issues.join("\n  - ")}` : message);
+    this.name = "ContractViolation";
+    this.issues = issues;
+  }
+};
+var formatIssues = (error) => {
+  const issues = error.issues;
+  if (!issues) return [String(error)];
+  return issues.map((issue) => {
+    const path = (issue.path ?? []).join(".");
+    return path ? `${path}: ${issue.message ?? "invalid"}` : issue.message ?? "invalid";
+  });
+};
+function assertEnvelope(json) {
+  const result = StepResponseSchema.safeParse(json);
+  if (!result.success) throw new ContractViolation("invalid envelope", formatIssues(result.error));
+  return result.data;
+}
+function assertEnvelopeFragment(json) {
+  const result = StepResponseFragmentSchema.safeParse(json);
+  if (!result.success)
+    throw new ContractViolation("invalid envelope fragment", formatIssues(result.error));
+  return result.data;
+}
+function endpointMatches(template, actual) {
+  const pattern = template.split("/").map((segment) => segment.startsWith(":") ? "[^/]+" : escapeRegExp(segment)).join("/");
+  return new RegExp(`^${pattern}$`).test(actual);
+}
+var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var transitionEndpoint = (transition) => {
+  switch (transition.mode) {
+    case "SUBMIT":
+      return transition.endpoint;
+    case "AWAIT":
+      return transition.poll.endpoint;
+    case "CLIENT_SURFACE":
+      return transition.report.endpoint;
+  }
+};
+var matchesAllowed = (transition, allowed) => allowed.mode === transition.mode && endpointMatches(allowed.endpoint, transitionEndpoint(transition));
+function bodyKeyIssues(transition) {
+  const issues = [];
+  const collide = (a, b, left, right) => {
+    for (const key of a) {
+      if (b.includes(key)) issues.push(`transition "${transition.id}": key "${key}" is in both ${left} and ${right}`);
+    }
+  };
+  if (transition.mode === "SUBMIT") {
+    const params = Object.keys(transition.params ?? {});
+    const inputs = Object.keys(transition.inputs ?? {});
+    collide(params, inputs, "params", "inputs");
+    for (const [key, value] of Object.entries(transition.params ?? {})) {
+      if (looksLikeFieldSpec(value)) {
+        issues.push(
+          `transition "${transition.id}": params.${key} is FieldSpec-shaped \u2014 a spec the client must collect belongs in inputs`
+        );
+      }
+    }
+  }
+  if (transition.mode === "CLIENT_SURFACE") {
+    const params = Object.keys(transition.report.params ?? {});
+    collide(params, transition.report.expects ?? [], "report.params", "report.expects");
+  }
+  return issues;
+}
+function checkLegalEmission(state, transitions) {
+  const entry = tableEntry(state);
+  const issues = [];
+  if (entry.terminal && transitions.length > 0) {
+    issues.push(
+      `${entry.key} is terminal (table) and must carry transitions: [] \u2014 got ${transitions.length}`
+    );
+  }
+  for (const transition of transitions) {
+    issues.push(...bodyKeyIssues(transition));
+    if (transition.mode === "CLIENT_SURFACE" && !("surface" in state)) {
+      issues.push(
+        `transition "${transition.id}": CLIENT_SURFACE requires the Surface in state (\u03942 single-carry) \u2014 ${entry.key} carries none`
+      );
+    }
+    if (transition.mode === "SUBMIT" && Object.values(transition.inputs ?? {}).some((spec) => spec.type === "FORM_VALUES") && !("form" in state)) {
+      issues.push(
+        `transition "${transition.id}": inputs {type: FORM_VALUES} collects state.form \u2014 ${entry.key} carries no form`
+      );
+    }
+    if (entry.docStatus === "SPECIFIED" && !entry.allowedTransitions.some((a) => matchesAllowed(transition, a))) {
+      issues.push(
+        `transition "${transition.id}": ${transition.mode} ${transitionEndpoint(transition)} is not in ${entry.key}'s legal set (${entry.allowedTransitions.map((a) => `${a.mode} ${a.endpoint}`).join(" | ") || "none"})`
+      );
+    }
+  }
+  return {
+    state: entry.key,
+    issues,
+    unjudgeable: entry.docStatus === "UNSPECIFIED"
+  };
+}
+function assertLegalEmission(state, transitions) {
+  const { issues, state: key } = checkLegalEmission(state, transitions);
+  if (issues.length) throw new ContractViolation(`illegal emission for ${key}`, issues);
+}
+function assertLegalReturn(from, to) {
+  const entry = tableEntry(from);
+  const target = stateKey(to);
+  if (!entry.mayReturn) return;
+  if (!entry.mayReturn.includes(target)) {
+    throw new ContractViolation(
+      `illegal return: ${entry.key} \u2192 ${target}`,
+      [`${entry.key} may receive back: ${entry.mayReturn.join(" \xB7 ") || "nothing (terminal)"}`]
+    );
+  }
+}
+function walkTable(fn) {
+  return STATE_KEYS.map((key) => fn(TRANSITION_TABLE[key], key));
+}
+function assertFixture(id) {
+  const meta = fixtureMeta(id);
+  const json = loadFixture(id);
+  const envelope = meta.complete ? assertEnvelope(json) : assertEnvelopeFragment(json);
+  if (stateKey(envelope.state) !== meta.stateKey) {
+    throw new ContractViolation(
+      `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
+    );
+  }
+  assertLegalEmission(envelope.state, envelope.transitions);
+  return { meta, envelope };
+}
+function assertAllFixtures() {
+  return FIXTURES.map((meta) => assertFixture(meta.id));
+}
+export {
+  AuthChallengeSchema,
+  BlockedStateSchema,
+  ContractViolation,
+  CryptoAmountSchema,
+  DOCUMENTED_ENDPOINTS,
+  ENDPOINT_PATTERN,
+  EnvelopeSchema,
+  FIELD_SPEC_TYPES,
+  FIXTURES,
+  FIXTURE_COVERAGE_GAPS,
+  FailureReasonSchema,
+  FeeLineSchema,
+  FiatAmountSchema,
+  FiatEndpointSchema,
+  FiatProviderSchema,
+  FieldSpecSchema,
+  FlowStateSchema,
+  FormDescriptorSchema,
+  FormFieldSchema,
+  FormFieldTypeSchema,
+  FunAuthStateSchema,
+  HTTP_VERBS,
+  InstructionFieldSchema,
+  InstructionsSchema,
+  InstrumentSchema,
+  JsonSchema,
+  KycCaptureStateSchema,
+  KycInputRequiredStateSchema,
+  KycNoActionRequiredStateSchema,
+  OrderAwaitingConfirmationStateSchema,
+  OrderCreatedStateSchema,
+  OrderRefSchema,
+  OrderStatusSchema,
+  OrderSummarySchema,
+  PaymentCaptureStateSchema,
+  PaymentInstructStateSchema,
+  PendingOrderStateSchema,
+  PollSpecSchema,
+  QuoteSchema,
+  QuoteStateSchema,
+  RecoverySchema,
+  RefundSchema,
+  ReportSpecSchema,
+  STATE_KEYS,
+  SelectOptionSchema,
+  SessionAuthStateSchema,
+  StatusHistoryEntrySchema,
+  StepResponseFragmentSchema,
+  StepResponseSchema,
+  SurfaceSchema,
+  TABLE_VERSION,
+  TERMINAL_ORDER_STATUSES,
+  TRANSITION_TABLE,
+  TransitionInputsSchema,
+  TransitionParamsSchema,
+  TransitionSchema,
+  TxSchema,
+  assertAllFixtures,
+  assertEnvelope,
+  assertEnvelopeFragment,
+  assertFixture,
+  assertLegalEmission,
+  assertLegalReturn,
+  checkLegalEmission,
+  endpointMatches,
+  fixtureMeta,
+  isTerminal,
+  loadFixture,
+  loadFixtures,
+  looksLikeFieldSpec,
+  stateKey,
+  tableEntry,
+  walkTable
+};
+//# sourceMappingURL=index.mjs.map