@fun-xyz/fiat-contract 0.12.0 → 0.14.0

package/README.md

@@ -8,6 +8,7 @@ Four things, zero runtime logic beyond validation:
 | File | What it is |
 | --- | --- |
 | `src/types.ts` | `FlowState` · `Transition` · `FailureReason` · `Surface` · `Instructions` · `FormDescriptor` · `OrderStatus` · `FiatStepResponse` |
+| `src/codes.ts` | Shared country, currency, US subdivision, and payment-method vocabularies |
 | `src/schemas.ts` | zod mirrors of every type — the single runtime validator |
 | `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) |
@@ -82,6 +83,8 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
     legitimately deferred for provider auth or activation. Transitions echo that opaque reference in
     `params`; clients submit it unchanged. `Quote.quoteRef` remains required whenever a real `Quote`
     is present, and PAY must never be exposed without real current economics.
+15. **KYC may precede pricing.** Provider auth or activation may legitimately defer pricing, so a
+    KYC state may omit `quote`. A real `Quote` still requires `quoteRef`, and PAY is never quote-less.
 
 ## KYC SDK hints, results, and client delivery
 

package/dist/{chunk-PHLBEDMK.mjs → chunk-BQELSEYH.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.12.0";
+var version = "0.14.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -514,4 +514,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-PHLBEDMK.mjs.map
+//# sourceMappingURL=chunk-BQELSEYH.mjs.map

package/dist/codes.d.ts

@@ -3,6 +3,9 @@
  * (circulating fiat only, no precious-metal/SDR codes); `paymentMethod` is fun-backend/provider
  * vocabulary, not a standard. `COUNTRY_CURRENCY_LIST` is the source of truth; everything below derives from it.
  */
+/** ISO 3166-2:US subdivision codes for the 50 states, DC, and five inhabited territories. */
+export declare const US_STATE_CODES: readonly ["AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "GU", "MP", "PR", "VI"];
+export type UsStateCode = (typeof US_STATE_CODES)[number];
 declare const COUNTRY_CURRENCY_LIST: readonly [{
     readonly country: "AD";
     readonly countryName: "Andorra";

package/dist/index.js

@@ -95,6 +95,8 @@ __export(index_exports, {
   TxSchema: () => TxSchema,
   UNOFFERED_ENDPOINTS: () => UNOFFERED_ENDPOINTS,
   UNREACHABLE_STATES: () => UNREACHABLE_STATES,
+  US_STATE_CODES: () => US_STATE_CODES,
+  UsStateCodeSchema: () => UsStateCodeSchema,
   assertAllFixtures: () => assertAllFixtures,
   assertFiatStepResponse: () => assertFiatStepResponse,
   assertFixture: () => assertFixture,
@@ -116,6 +118,64 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/codes.ts
+var US_STATE_CODES = [
+  "AL",
+  "AK",
+  "AZ",
+  "AR",
+  "CA",
+  "CO",
+  "CT",
+  "DE",
+  "DC",
+  "FL",
+  "GA",
+  "HI",
+  "ID",
+  "IL",
+  "IN",
+  "IA",
+  "KS",
+  "KY",
+  "LA",
+  "ME",
+  "MD",
+  "MA",
+  "MI",
+  "MN",
+  "MS",
+  "MO",
+  "MT",
+  "NE",
+  "NV",
+  "NH",
+  "NJ",
+  "NM",
+  "NY",
+  "NC",
+  "ND",
+  "OH",
+  "OK",
+  "OR",
+  "PA",
+  "RI",
+  "SC",
+  "SD",
+  "TN",
+  "TX",
+  "UT",
+  "VT",
+  "VA",
+  "WA",
+  "WV",
+  "WI",
+  "WY",
+  "AS",
+  "GU",
+  "MP",
+  "PR",
+  "VI"
+];
 var COUNTRY_CURRENCY_LIST = [
   { country: "AD", countryName: "Andorra", currency: "EUR", currencyName: "Euro" },
   { country: "AE", countryName: "United Arab Emirates", currency: "AED", currencyName: "UAE Dirham" },
@@ -396,6 +456,7 @@ var HTTP_VERBS = ["GET", "POST"];
 var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
 var $endpoint = import_zod.z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
 var FiatEndpointSchema = $endpoint;
+var UsStateCodeSchema = import_zod.z.enum(US_STATE_CODES);
 var $provider = import_zod.z.enum([
   "TRANSAK",
   "SWAPPED",
@@ -555,6 +616,7 @@ var STANDARD_KYC_FIELD_IDS = [
   "RESIDENTIAL_ADDRESS_POSTAL_CODE",
   "RESIDENTIAL_ADDRESS_COUNTRY",
   "TAX_IDENTIFIER",
+  "US_SSN_LAST_FOUR",
   "TAX_RESIDENCE_COUNTRY",
   "EMPLOYMENT_STATUS",
   "OCCUPATION_INDUSTRY",
@@ -777,7 +839,7 @@ var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("CAPTURE"),
-  quote: $quote,
+  quote: $quote.optional(),
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -785,7 +847,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("INPUT_REQUIRED"),
-  quote: $quote,
+  quote: $quote.optional(),
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -793,7 +855,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("NO_ACTION_REQUIRED"),
-  quote: $quote,
+  quote: $quote.optional(),
   reason: import_zod.z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: import_zod.z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -875,6 +937,10 @@ var $providerBoundStepResponse = obj({
   provider: $provider,
   transitions: import_zod.z.array($transition),
   routingSessionRef: import_zod.z.string().optional(),
+  providerAuthToken: obj({
+    clientSecret: import_zod.z.string(),
+    expiresAt: import_zod.z.string()
+  }).optional(),
   orderId: import_zod.z.string().optional()
 });
 var $blockedStepResponse = obj({
@@ -882,13 +948,17 @@ var $blockedStepResponse = obj({
   provider: $provider.optional(),
   transitions: import_zod.z.array($transition),
   routingSessionRef: import_zod.z.string().optional(),
+  providerAuthToken: obj({
+    clientSecret: import_zod.z.string(),
+    expiresAt: import_zod.z.string()
+  }).optional(),
   orderId: import_zod.z.string().optional()
 });
 var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStepResponse]);
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.12.0";
+var version = "0.14.0";
 
 // src/table.ts
 var TABLE_VERSION = version;

package/dist/index.mjs

@@ -12,9 +12,67 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-PHLBEDMK.mjs";
+} from "./chunk-BQELSEYH.mjs";
 
 // src/codes.ts
+var US_STATE_CODES = [
+  "AL",
+  "AK",
+  "AZ",
+  "AR",
+  "CA",
+  "CO",
+  "CT",
+  "DE",
+  "DC",
+  "FL",
+  "GA",
+  "HI",
+  "ID",
+  "IL",
+  "IN",
+  "IA",
+  "KS",
+  "KY",
+  "LA",
+  "ME",
+  "MD",
+  "MA",
+  "MI",
+  "MN",
+  "MS",
+  "MO",
+  "MT",
+  "NE",
+  "NV",
+  "NH",
+  "NJ",
+  "NM",
+  "NY",
+  "NC",
+  "ND",
+  "OH",
+  "OK",
+  "OR",
+  "PA",
+  "RI",
+  "SC",
+  "SD",
+  "TN",
+  "TX",
+  "UT",
+  "VT",
+  "VA",
+  "WA",
+  "WV",
+  "WI",
+  "WY",
+  "AS",
+  "GU",
+  "MP",
+  "PR",
+  "VI"
+];
 var COUNTRY_CURRENCY_LIST = [
   { country: "AD", countryName: "Andorra", currency: "EUR", currencyName: "Euro" },
   { country: "AE", countryName: "United Arab Emirates", currency: "AED", currencyName: "UAE Dirham" },
@@ -295,6 +353,7 @@ 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 UsStateCodeSchema = z.enum(US_STATE_CODES);
 var $provider = z.enum([
   "TRANSAK",
   "SWAPPED",
@@ -454,6 +513,7 @@ var STANDARD_KYC_FIELD_IDS = [
   "RESIDENTIAL_ADDRESS_POSTAL_CODE",
   "RESIDENTIAL_ADDRESS_COUNTRY",
   "TAX_IDENTIFIER",
+  "US_SSN_LAST_FOUR",
   "TAX_RESIDENCE_COUNTRY",
   "EMPLOYMENT_STATUS",
   "OCCUPATION_INDUSTRY",
@@ -676,7 +736,7 @@ var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("CAPTURE"),
-  quote: $quote,
+  quote: $quote.optional(),
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -684,7 +744,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("INPUT_REQUIRED"),
-  quote: $quote,
+  quote: $quote.optional(),
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -692,7 +752,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("NO_ACTION_REQUIRED"),
-  quote: $quote,
+  quote: $quote.optional(),
   reason: z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -774,6 +834,10 @@ var $providerBoundStepResponse = obj({
   provider: $provider,
   transitions: z.array($transition),
   routingSessionRef: z.string().optional(),
+  providerAuthToken: obj({
+    clientSecret: z.string(),
+    expiresAt: z.string()
+  }).optional(),
   orderId: z.string().optional()
 });
 var $blockedStepResponse = obj({
@@ -781,6 +845,10 @@ var $blockedStepResponse = obj({
   provider: $provider.optional(),
   transitions: z.array($transition),
   routingSessionRef: z.string().optional(),
+  providerAuthToken: obj({
+    clientSecret: z.string(),
+    expiresAt: z.string()
+  }).optional(),
   orderId: z.string().optional()
 });
 var $stepResponse = z.union([$providerBoundStepResponse, $blockedStepResponse]);
@@ -1922,6 +1990,8 @@ export {
   TxSchema,
   UNOFFERED_ENDPOINTS,
   UNREACHABLE_STATES,
+  US_STATE_CODES,
+  UsStateCodeSchema,
   assertAllFixtures,
   assertFiatStepResponse,
   assertFixture,

package/dist/schemas.d.ts

@@ -27,12 +27,14 @@
  * They are module-private, so none of it reaches the published declarations.
  */
 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';
 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 UsStateCodeSchema: z.ZodType<UsStateCode>;
 export declare const FiatProviderSchema: z.ZodType<FiatProvider>;
 export declare const KYCProviderSchema: z.ZodType<KYCProvider>;
 export declare const SurfaceProviderSchema: z.ZodType<SurfaceProvider>;
@@ -53,7 +55,7 @@ export declare const TxSchema: z.ZodType<Tx>;
 export declare const RefundSchema: z.ZodType<Refund>;
 export declare const SurfaceKindSchema: z.ZodType<SurfaceKind>;
 export declare const PreferredIdentityDocumentSchema: z.ZodType<PreferredIdentityDocument>;
-export declare const STANDARD_KYC_FIELD_IDS: readonly ["LEGAL_FIRST_NAME", "LEGAL_MIDDLE_NAME", "LEGAL_LAST_NAME", "DATE_OF_BIRTH", "COUNTRY_OF_BIRTH", "CITY_OF_BIRTH", "NATIONALITY", "EMAIL_ADDRESS", "EMAIL_OWNERSHIP_VERIFICATION", "PHONE_NUMBER", "PHONE_OWNERSHIP_VERIFICATION", "RESIDENTIAL_ADDRESS_LINE_1", "RESIDENTIAL_ADDRESS_LINE_2", "RESIDENTIAL_ADDRESS_CITY", "RESIDENTIAL_ADDRESS_REGION", "RESIDENTIAL_ADDRESS_POSTAL_CODE", "RESIDENTIAL_ADDRESS_COUNTRY", "TAX_IDENTIFIER", "TAX_RESIDENCE_COUNTRY", "EMPLOYMENT_STATUS", "OCCUPATION_INDUSTRY", "OCCUPATION_TITLE", "SOURCE_OF_FUNDS_DECLARATION", "SOURCE_OF_INCOME_DECLARATION", "SOURCE_OF_WEALTH_DECLARATION", "PURPOSE_OF_SERVICE", "PURPOSE_OF_TRANSACTION", "CUSTOMER_CATEGORY"];
+export declare const STANDARD_KYC_FIELD_IDS: readonly ["LEGAL_FIRST_NAME", "LEGAL_MIDDLE_NAME", "LEGAL_LAST_NAME", "DATE_OF_BIRTH", "COUNTRY_OF_BIRTH", "CITY_OF_BIRTH", "NATIONALITY", "EMAIL_ADDRESS", "EMAIL_OWNERSHIP_VERIFICATION", "PHONE_NUMBER", "PHONE_OWNERSHIP_VERIFICATION", "RESIDENTIAL_ADDRESS_LINE_1", "RESIDENTIAL_ADDRESS_LINE_2", "RESIDENTIAL_ADDRESS_CITY", "RESIDENTIAL_ADDRESS_REGION", "RESIDENTIAL_ADDRESS_POSTAL_CODE", "RESIDENTIAL_ADDRESS_COUNTRY", "TAX_IDENTIFIER", "US_SSN_LAST_FOUR", "TAX_RESIDENCE_COUNTRY", "EMPLOYMENT_STATUS", "OCCUPATION_INDUSTRY", "OCCUPATION_TITLE", "SOURCE_OF_FUNDS_DECLARATION", "SOURCE_OF_INCOME_DECLARATION", "SOURCE_OF_WEALTH_DECLARATION", "PURPOSE_OF_SERVICE", "PURPOSE_OF_TRANSACTION", "CUSTOMER_CATEGORY"];
 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>;

package/dist/table.js

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

package/dist/table.mjs

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

package/dist/types.d.ts

@@ -265,7 +265,7 @@ export interface PreferredIdentityDocument {
     country: string;
 }
 /** Canonical KYC values a declarative form or current-session delivery may name. */
-export type StandardKycFieldId = 'LEGAL_FIRST_NAME' | 'LEGAL_MIDDLE_NAME' | 'LEGAL_LAST_NAME' | 'DATE_OF_BIRTH' | 'COUNTRY_OF_BIRTH' | 'CITY_OF_BIRTH' | 'NATIONALITY' | 'EMAIL_ADDRESS' | 'EMAIL_OWNERSHIP_VERIFICATION' | 'PHONE_NUMBER' | 'PHONE_OWNERSHIP_VERIFICATION' | 'RESIDENTIAL_ADDRESS_LINE_1' | 'RESIDENTIAL_ADDRESS_LINE_2' | 'RESIDENTIAL_ADDRESS_CITY' | 'RESIDENTIAL_ADDRESS_REGION' | 'RESIDENTIAL_ADDRESS_POSTAL_CODE' | 'RESIDENTIAL_ADDRESS_COUNTRY' | 'TAX_IDENTIFIER' | 'TAX_RESIDENCE_COUNTRY' | 'EMPLOYMENT_STATUS' | 'OCCUPATION_INDUSTRY' | 'OCCUPATION_TITLE' | 'SOURCE_OF_FUNDS_DECLARATION' | 'SOURCE_OF_INCOME_DECLARATION' | 'SOURCE_OF_WEALTH_DECLARATION' | 'PURPOSE_OF_SERVICE' | 'PURPOSE_OF_TRANSACTION' | 'CUSTOMER_CATEGORY';
+export type StandardKycFieldId = 'LEGAL_FIRST_NAME' | 'LEGAL_MIDDLE_NAME' | 'LEGAL_LAST_NAME' | 'DATE_OF_BIRTH' | 'COUNTRY_OF_BIRTH' | 'CITY_OF_BIRTH' | 'NATIONALITY' | 'EMAIL_ADDRESS' | 'EMAIL_OWNERSHIP_VERIFICATION' | 'PHONE_NUMBER' | 'PHONE_OWNERSHIP_VERIFICATION' | 'RESIDENTIAL_ADDRESS_LINE_1' | 'RESIDENTIAL_ADDRESS_LINE_2' | 'RESIDENTIAL_ADDRESS_CITY' | 'RESIDENTIAL_ADDRESS_REGION' | 'RESIDENTIAL_ADDRESS_POSTAL_CODE' | 'RESIDENTIAL_ADDRESS_COUNTRY' | 'TAX_IDENTIFIER' | 'US_SSN_LAST_FOUR' | 'TAX_RESIDENCE_COUNTRY' | 'EMPLOYMENT_STATUS' | 'OCCUPATION_INDUSTRY' | 'OCCUPATION_TITLE' | 'SOURCE_OF_FUNDS_DECLARATION' | 'SOURCE_OF_INCOME_DECLARATION' | 'SOURCE_OF_WEALTH_DECLARATION' | 'PURPOSE_OF_SERVICE' | 'PURPOSE_OF_TRANSACTION' | 'CUSTOMER_CATEGORY';
 export type KycAcknowledgementFieldId = 'RISK_ACKNOWLEDGEMENT' | 'COOLING_OFF_ACKNOWLEDGEMENT' | 'TERMS_ACCEPTANCE';
 export type QuestionnaireKycFieldId = `QUESTIONNAIRE_RESPONSE:${string}:${string}`;
 export type KycFieldId = StandardKycFieldId | KycAcknowledgementFieldId | QuestionnaireKycFieldId;
@@ -544,23 +544,26 @@ export type FlowState =
     surface?: Surface;
     error?: FailureReason;
 }
-/** Pre-order KYC states carry the routed quote so the entry screen can keep price visible. */
+/**
+ * Pre-order KYC normally carries the routed quote so the entry screen can keep price visible.
+ * `quote` may be absent when provider auth or activation gates pricing.
+ */
  | {
     kind: 'KYC';
     phase: 'CAPTURE';
-    quote: Quote;
+    quote?: Quote;
     surface: Surface;
     error?: FailureReason;
 } | {
     kind: 'KYC';
     phase: 'INPUT_REQUIRED';
-    quote: Quote;
+    quote?: Quote;
     form: FormDescriptor;
     error?: FailureReason;
 } | {
     kind: 'KYC';
     phase: 'NO_ACTION_REQUIRED';
-    quote: Quote;
+    quote?: Quote;
     /**
      * Note the deliberate name collision (Charles's nit, review 2026-08-14): `ON_HOLD` appears
      * here as a KYC reason *and* in `OrderStatus`. They are different things and both names come
@@ -649,6 +652,14 @@ type FiatStepResponseBase = {
      * the committed provider path independently from the quote binding.
      */
     routingSessionRef?: string;
+    /**
+     * Short-lived provider credential the client redeems for a silent sign-in before it renders the
+     * state. Absent means no silent path; the interactive `SESSION_AUTH` flow still applies.
+     */
+    providerAuthToken?: {
+        clientSecret: string;
+        expiresAt: string;
+    };
     /** TODO(open-decision): `orderId` placement — see `PAYMENT{INSTRUCT}.orderId` above. */
     orderId?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fun-xyz/fiat-contract",
-  "version": "0.12.0",
+  "version": "0.14.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": {