@fun-xyz/fiat-contract 0.39.0 → 0.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,220 @@
1
+ /**
2
+ * The Coinbase flow on `POST /fiat/next`.
3
+ *
4
+ * A response names the next action in `next`; the client's request names it in `action`. `observe` answers the
5
+ * current next action. `wait` has no request: send `observe` after it. `pay` and `orderPending` are answered by `order`.
6
+ * Identity and the deposit wallet come from the verified partner assertion, never from a request body.
7
+ *
8
+ * A retry sends the same request and gets the current response. A fault is a 4xx/5xx whose body is
9
+ * `CoinbaseErrorBody`; anything the buyer can act on is a 200.
10
+ *
11
+ * Zero runtime dependencies, so production React Native code can import it. The zod schemas are in
12
+ * `./coinbase.schemas`, exported from the package root only.
13
+ */
14
+ import type { FiatTermsRequest, TermsDocument } from '../terms';
15
+ import type { DestinationAsset, FeeLine, FiatAmount, FiatGeo, FiatStepResponse, FormField, KycFieldId } from '../types';
16
+ export declare const COINBASE_ENDPOINTS: {
17
+ readonly next: "POST /fiat/next";
18
+ };
19
+ /** The checkout terms, sent on every request. No routing quote: the backend mints the order id on `placeOrder`. */
20
+ export interface CoinbaseCheckout {
21
+ /** Coinbase serves USD only. */
22
+ amount: FiatAmount & {
23
+ currency: 'USD';
24
+ };
25
+ /** The asset and its network, as the routing table or `/fiat/quote` named them. */
26
+ destination: {
27
+ asset: string;
28
+ network: string;
29
+ };
30
+ paymentMethod: 'apple_pay';
31
+ }
32
+ /**
33
+ * On every request. `destinationAsset` is the asset the user receives at the end, as on every `FiatNextRequest`;
34
+ * `checkout.destination` stays the asset Coinbase delivers.
35
+ */
36
+ export type CoinbaseRequestContext = {
37
+ checkout: CoinbaseCheckout;
38
+ destinationAsset?: DestinationAsset;
39
+ };
40
+ /** No next action of its own: the answer is the current next action. Writes nothing. */
41
+ export type CoinbaseObserveRequest = {
42
+ action: 'observe';
43
+ };
44
+ /** Coinbase's terms first. Later, before the first `kyc`, Fun's KYC consent if the buyer has not accepted it. */
45
+ export type CoinbaseConsentNextAction = {
46
+ next: 'consent';
47
+ documents: TermsDocument[];
48
+ };
49
+ /** The `POST /fiat/terms` items, recorded under the same rules. */
50
+ export type CoinbaseConsentRequest = {
51
+ action: 'consent';
52
+ acceptances: FiatTermsRequest['acceptances'];
53
+ };
54
+ /** Ask for the buyer's phone. `CODE_EXPIRED`: the last code's ten minutes ran out, or five wrong codes ended it. */
55
+ export type CoinbaseSessionNextAction = {
56
+ next: 'session';
57
+ error: 'CODE_EXPIRED' | null;
58
+ };
59
+ /** Text a code to `phoneNumber` (E.164), or send a new code to the phone of the live challenge `resend` names. */
60
+ export type CoinbaseSessionRequest = {
61
+ action: 'session';
62
+ phoneNumber: string;
63
+ } | {
64
+ action: 'session';
65
+ resend: string;
66
+ };
67
+ /** Ask for the code Coinbase texted. `expiresAt` is ISO-8601. `CODE_INVALID`: the last code sent was wrong. */
68
+ export type CoinbaseOtpNextAction = {
69
+ next: 'otp';
70
+ verificationRef: string;
71
+ expiresAt: string;
72
+ error: 'CODE_INVALID' | null;
73
+ };
74
+ /** `otpCode` is six digits. Named so request logs redact it. */
75
+ export type CoinbaseOtpRequest = {
76
+ action: 'otp';
77
+ verificationRef: string;
78
+ otpCode: string;
79
+ };
80
+ /** A reason on one field of a `kyc` next action. `fieldId` names a field in that next action. */
81
+ export interface CoinbaseFieldError {
82
+ fieldId: string;
83
+ message: string;
84
+ }
85
+ /** Why a re-ask asks again. Treat an unknown code like `null`: adding a code is a minor contract change. */
86
+ export type CoinbaseReaskReason = 'REJECTED';
87
+ /** Fields of the `kyc` form the buyer gave before that Coinbase asks for again. `requirements` is never empty. */
88
+ export type CoinbaseReask = {
89
+ requirements: KycFieldId[];
90
+ reason: CoinbaseReaskReason | null;
91
+ };
92
+ /** Show the shared form for Coinbase's limit upgrade. */
93
+ export type CoinbaseKycNextAction = {
94
+ next: 'kyc';
95
+ fields: FormField[];
96
+ fieldErrors?: CoinbaseFieldError[];
97
+ reask: CoinbaseReask | null;
98
+ };
99
+ /** Keyed by the ids of the next action's fields. */
100
+ export type CoinbaseKycRequest = {
101
+ action: 'kyc';
102
+ values: Partial<Record<KycFieldId, string>>;
103
+ };
104
+ /** Coinbase is reviewing, or cannot be read right now. No request of its own: send `observe` after the delay. */
105
+ export type CoinbaseWaitNextAction = {
106
+ next: 'wait';
107
+ retryAfterMs: number;
108
+ };
109
+ /** The order's price: Coinbase's own totals, never Fun's. */
110
+ export interface CoinbasePrice {
111
+ total: FiatAmount;
112
+ fees: FeeLine[];
113
+ cryptoAmount: string;
114
+ }
115
+ /**
116
+ * Coinbase priced the checkout. `orderId` is minted for this answer: send it back on `placeOrder`, and on every
117
+ * `order` after it. A retry with the same `orderId` places nothing new.
118
+ */
119
+ export type CoinbasePlaceOrderNextAction = {
120
+ next: 'placeOrder';
121
+ price: CoinbasePrice;
122
+ orderId: string;
123
+ };
124
+ /** Creates the Coinbase order under `orderId` and answers `pay`. */
125
+ export type CoinbasePlaceOrderRequest = {
126
+ action: 'placeOrder';
127
+ orderId: string;
128
+ };
129
+ /** Open `paymentLink`, then send `order`. The link is a credential: never stored, never logged, never sent twice. */
130
+ export type CoinbasePayNextAction = {
131
+ next: 'pay';
132
+ orderId: string;
133
+ price: CoinbasePrice;
134
+ paymentLink: {
135
+ url: string;
136
+ };
137
+ environment: 'sandbox' | 'production';
138
+ };
139
+ /** Reads Coinbase and moves the order `orderId` forward. */
140
+ export type CoinbaseOrderRequest = {
141
+ action: 'order';
142
+ orderId: string;
143
+ };
144
+ /**
145
+ * The order exists and is not terminal. `order` is its current body, or `null` before the order is recorded.
146
+ * Do not open a payment link. After `retryAfterMs`, send `order`.
147
+ */
148
+ export type CoinbaseOrderPendingNextAction = {
149
+ next: 'orderPending';
150
+ orderId: string;
151
+ retryAfterMs: number;
152
+ order: FiatStepResponse | null;
153
+ };
154
+ export type CoinbaseRequest = CoinbaseRequestContext & (CoinbaseObserveRequest | CoinbaseConsentRequest | CoinbaseSessionRequest | CoinbaseOtpRequest | CoinbaseKycRequest | CoinbasePlaceOrderRequest | CoinbaseOrderRequest);
155
+ /**
156
+ * Every `action` a Coinbase request names, derived from the requests. Unlike `MoonPayAction` it leaves out `wait`:
157
+ * `wait` is a next action the client answers by sending `observe` again, never a request action.
158
+ */
159
+ export type CoinbaseAction = CoinbaseRequest['action'];
160
+ /** The wire body. The orchestrator reads `provider` and `geo`; Coinbase's action schemas read the rest. */
161
+ export type CoinbaseNextRequest = {
162
+ provider: 'COINBASE';
163
+ geo: FiatGeo;
164
+ } & CoinbaseRequest;
165
+ export type CoinbaseNextAction = CoinbaseConsentNextAction | CoinbaseSessionNextAction | CoinbaseOtpNextAction | CoinbaseKycNextAction | CoinbaseWaitNextAction | CoinbasePlaceOrderNextAction | CoinbasePayNextAction | CoinbaseOrderPendingNextAction;
166
+ /** The order is terminal. `order` is its body, which the shared order screen renders. */
167
+ export type CoinbaseDone = {
168
+ next: 'done';
169
+ order: FiatStepResponse;
170
+ };
171
+ /**
172
+ * Read `recovery`, never derive it from the reason. `REQUOTE` goes back to routing; `NONE` ends the flow.
173
+ * `LIMITS_EXCEEDED` carries the cap that refused as `maxAmount` when that cap is an amount.
174
+ */
175
+ export type CoinbaseStepRefusal = 'NOT_ELIGIBLE' | 'KYC_UPGRADE_REJECTED' | 'FINAL_REJECTION' | 'TOTAL_MISMATCH';
176
+ export type CoinbaseRefused = {
177
+ next: 'refused';
178
+ reason: CoinbaseStepRefusal;
179
+ recovery: 'REQUOTE' | 'NONE';
180
+ } | {
181
+ next: 'refused';
182
+ reason: 'LIMITS_EXCEEDED';
183
+ recovery: 'REQUOTE';
184
+ maxAmount: FiatAmount | null;
185
+ };
186
+ /** Every action but `order`. An open order answers `orderPending` and a terminal one `done`, whichever action asked. */
187
+ export type CoinbaseStepResponse = CoinbaseNextAction | CoinbaseDone | CoinbaseRefused;
188
+ /** `order` never refuses: it runs after the buyer may have paid. */
189
+ export type CoinbaseOrderResponse = CoinbaseDone | CoinbaseOrderPendingNextAction;
190
+ export type CoinbaseResponseFor = {
191
+ observe: CoinbaseStepResponse;
192
+ consent: CoinbaseStepResponse;
193
+ session: CoinbaseStepResponse;
194
+ otp: CoinbaseStepResponse;
195
+ kyc: CoinbaseStepResponse;
196
+ placeOrder: CoinbaseStepResponse;
197
+ order: CoinbaseOrderResponse;
198
+ };
199
+ /** `RETRY` sends the same request again. `REQUOTE` goes back to routing. `NONE` ends the flow. */
200
+ export type CoinbaseRecovery = 'RETRY' | 'REQUOTE' | 'NONE';
201
+ /**
202
+ * `SESSION_BUDGET_SPENT`: the per-login code budget `session` spends (429). `RATE_LIMITED`: the action's request
203
+ * budget (429). `PROVIDER_UNAVAILABLE`: Coinbase is down (503). `KYC_PROVIDER_UNAVAILABLE`: the KYC provider is down
204
+ * (503). `SERVICE_UNAVAILABLE`: one of Fun's own stores is down (503). `INVALID_REQUEST`: a bad body (400).
205
+ */
206
+ export type CoinbaseFaultReason = 'SESSION_BUDGET_SPENT' | 'RATE_LIMITED' | 'PROVIDER_UNAVAILABLE' | 'KYC_PROVIDER_UNAVAILABLE' | 'SERVICE_UNAVAILABLE' | 'INVALID_REQUEST';
207
+ /** The fields a Coinbase fault adds to the shared error body. */
208
+ export interface CoinbaseFault {
209
+ reason: CoinbaseFaultReason;
210
+ recovery: CoinbaseRecovery;
211
+ }
212
+ /** The route's 4xx/5xx body: the shared error body plus `CoinbaseFault`. A 429 adds `retryAfterSeconds`. */
213
+ export type CoinbaseErrorBody = CoinbaseFault & {
214
+ errorCode: string;
215
+ errorMsg: string;
216
+ reqId?: string;
217
+ retryAfterSeconds?: number;
218
+ };
219
+ /** Coinbase's user agreement, the version the legacy flow records under `COINBASE`. */
220
+ export declare const COINBASE_TERMS: TermsDocument;
@@ -0,0 +1,37 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+
20
+ // src/providers/coinbase.ts
21
+ var coinbase_exports = {};
22
+ __export(coinbase_exports, {
23
+ COINBASE_ENDPOINTS: () => COINBASE_ENDPOINTS,
24
+ COINBASE_TERMS: () => COINBASE_TERMS
25
+ });
26
+ module.exports = __toCommonJS(coinbase_exports);
27
+ var COINBASE_ENDPOINTS = {
28
+ next: "POST /fiat/next"
29
+ };
30
+ var COINBASE_TERMS = {
31
+ id: "COINBASE_TERMS",
32
+ kind: "PROVIDER_TERMS",
33
+ stage: "CHECKOUT",
34
+ version: "2026-01",
35
+ contentDigest: "22db1a8292d9ecd60b53adf640c8748ad8477646c26a31971a83f7a43457f1fe",
36
+ links: [{ label: "Coinbase User Agreement", url: "https://www.coinbase.com/legal/user_agreement" }]
37
+ };
@@ -0,0 +1,8 @@
1
+ import {
2
+ COINBASE_ENDPOINTS,
3
+ COINBASE_TERMS
4
+ } from "../chunk-SFR4SCDU.mjs";
5
+ export {
6
+ COINBASE_ENDPOINTS,
7
+ COINBASE_TERMS
8
+ };
@@ -0,0 +1,38 @@
1
+ /**
2
+ * zod schemas for the Coinbase flow on `POST /fiat/next`. Test-time and backend-boundary only:
3
+ * exported from the package root, never from `./coinbase`, so the production entry stays free of zod.
4
+ */
5
+ import { z } from 'zod';
6
+ import type { CoinbaseCheckout, CoinbaseConsentNextAction, CoinbaseConsentRequest, CoinbaseDone, CoinbaseErrorBody, CoinbaseFault, CoinbaseKycNextAction, CoinbaseKycRequest, CoinbaseNextAction, CoinbaseNextRequest, CoinbaseObserveRequest, CoinbaseOrderPendingNextAction, CoinbaseOrderRequest, CoinbaseOrderResponse, CoinbaseOtpNextAction, CoinbaseOtpRequest, CoinbasePayNextAction, CoinbasePlaceOrderNextAction, CoinbasePlaceOrderRequest, CoinbasePrice, CoinbaseReask, CoinbaseRefused, CoinbaseRequest, CoinbaseRequestContext, CoinbaseResponseFor, CoinbaseSessionNextAction, CoinbaseSessionRequest, CoinbaseStepResponse, CoinbaseWaitNextAction } from './coinbase';
7
+ export declare const CoinbaseCheckoutSchema: z.ZodType<CoinbaseCheckout>;
8
+ export declare const CoinbaseRequestContextSchema: z.ZodType<CoinbaseRequestContext>;
9
+ export declare const CoinbaseObserveRequestSchema: z.ZodType<CoinbaseRequestContext & CoinbaseObserveRequest>;
10
+ export declare const CoinbaseConsentRequestSchema: z.ZodType<CoinbaseRequestContext & CoinbaseConsentRequest>;
11
+ export declare const CoinbaseSessionRequestSchema: z.ZodType<CoinbaseRequestContext & CoinbaseSessionRequest>;
12
+ export declare const CoinbaseOtpRequestSchema: z.ZodType<CoinbaseRequestContext & CoinbaseOtpRequest>;
13
+ export declare const CoinbaseKycRequestSchema: z.ZodType<CoinbaseRequestContext & CoinbaseKycRequest>;
14
+ export declare const CoinbasePlaceOrderRequestSchema: z.ZodType<CoinbaseRequestContext & CoinbasePlaceOrderRequest>;
15
+ export declare const CoinbaseOrderRequestSchema: z.ZodType<CoinbaseRequestContext & CoinbaseOrderRequest>;
16
+ export declare const CoinbaseRequestSchema: z.ZodType<CoinbaseRequest>;
17
+ export declare const CoinbaseNextRequestSchema: z.ZodType<CoinbaseNextRequest>;
18
+ export declare const CoinbasePriceSchema: z.ZodType<CoinbasePrice>;
19
+ export declare const CoinbaseReaskSchema: z.ZodType<CoinbaseReask>;
20
+ export declare const CoinbaseConsentNextActionSchema: z.ZodType<CoinbaseConsentNextAction>;
21
+ export declare const CoinbaseSessionNextActionSchema: z.ZodType<CoinbaseSessionNextAction>;
22
+ export declare const CoinbaseOtpNextActionSchema: z.ZodType<CoinbaseOtpNextAction>;
23
+ export declare const CoinbaseKycNextActionSchema: z.ZodType<CoinbaseKycNextAction>;
24
+ export declare const CoinbaseWaitNextActionSchema: z.ZodType<CoinbaseWaitNextAction>;
25
+ export declare const CoinbasePlaceOrderNextActionSchema: z.ZodType<CoinbasePlaceOrderNextAction>;
26
+ export declare const CoinbasePayNextActionSchema: z.ZodType<CoinbasePayNextAction>;
27
+ export declare const CoinbaseOrderPendingNextActionSchema: z.ZodType<CoinbaseOrderPendingNextAction>;
28
+ export declare const CoinbaseNextActionSchema: z.ZodType<CoinbaseNextAction>;
29
+ export declare const CoinbaseDoneSchema: z.ZodType<CoinbaseDone>;
30
+ export declare const CoinbaseRefusedSchema: z.ZodType<CoinbaseRefused>;
31
+ export declare const CoinbaseStepResponseSchema: z.ZodType<CoinbaseStepResponse>;
32
+ export declare const CoinbaseOrderResponseSchema: z.ZodType<CoinbaseOrderResponse>;
33
+ /** The response schema for each request action, as `CoinbaseResponseFor` types it. */
34
+ export declare const CoinbaseResponseSchemaFor: {
35
+ readonly [A in keyof CoinbaseResponseFor]: z.ZodType<CoinbaseResponseFor[A]>;
36
+ };
37
+ export declare const CoinbaseFaultSchema: z.ZodType<CoinbaseFault>;
38
+ export declare const CoinbaseErrorBodySchema: z.ZodType<CoinbaseErrorBody>;
package/dist/schemas.d.ts CHANGED
@@ -28,7 +28,7 @@
28
28
  */
29
29
  import { z } from 'zod';
30
30
  import type { UsStateCode } from './codes';
31
- import type { BlockedReason, CryptoAmount, FailureReason, FeeLine, FiatAmount, FiatEndpoint, FiatProvider, FiatStepResponse, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, InstructionField, Instructions, Instrument, JsonValue, KYCProvider, KycReviewDuration, OrderRef, OrderStatus, OrderSummary, PollSpec, PreparedPayment, PaymentSurface, Quote, QuoteLimitRange, QuoteLimits, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, Surface, PreferredIdentityDocument, KycFieldId, ClientExecutedDelivery, KycSdkResultReport, SurfaceKind, SurfaceProvider, TermsAcceptance, Transition, TransitionInputs, TransitionParams, Tx, DestinationAsset, FiatGeo, FiatNextRequest } from './types';
31
+ import type { BlockedReason, CryptoAmount, FailureReason, FeeLine, FiatAmount, FiatEndpoint, FiatProvider, FiatAuthRefreshRequest, FiatAuthRefreshResponse, FiatAuthRevokeRequest, FiatAuthStartRequest, FiatAuthVerifyRequest, FiatSession, FiatStepResponse, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, InstructionField, Instructions, Instrument, JsonValue, KYCProvider, KycReviewDuration, OrderRef, OrderStatus, OrderSummary, PollSpec, PreparedPayment, PaymentSurface, Quote, QuoteLimitRange, QuoteLimits, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, Surface, PreferredIdentityDocument, KycFieldId, ClientExecutedDelivery, KycSdkResultReport, SurfaceKind, SurfaceProvider, TermsAcceptance, Transition, TransitionInputs, TransitionParams, Tx, DestinationAsset, FiatGeo, FiatNextRequest } from './types';
32
32
  import type { FiatTermsErrorBody, FiatTermsRequest, FiatTermsResponse, TermsDocument, TermsDocumentAcceptance } from './terms';
33
33
  import type { FiatRoutingQuoteErrorBody, FiatRoutingQuoteRequest, FiatRoutingQuoteTerms, FiatRoutingTableErrorBody, FiatRoutingTableRequest, FiatRoutingTableResponse } from './routing';
34
34
  export declare const JsonSchema: z.ZodType<JsonValue>;
@@ -85,7 +85,6 @@ export declare const ReportSpecSchema: z.ZodType<ReportSpec>;
85
85
  export declare const KycSdkResultReportSchema: z.ZodType<KycSdkResultReport>;
86
86
  export declare const TransitionSchema: z.ZodType<Transition>;
87
87
  export declare const PreparedPaymentSchema: z.ZodType<PreparedPayment>;
88
- export declare const AuthChallengeSchema: z.ZodType<Record<string, JsonValue>>;
89
88
  /** `Extract` keeps each per-state export pinned to the union member it validates. */
90
89
  type State<K extends FlowState['kind'], P = never> = [P] extends [never] ? Extract<FlowState, {
91
90
  kind: K;
@@ -95,6 +94,7 @@ type State<K extends FlowState['kind'], P = never> = [P] extends [never] ? Extra
95
94
  }>;
96
95
  export declare const QuoteStateSchema: z.ZodType<State<'QUOTE'>>;
97
96
  export declare const FunAuthStateSchema: z.ZodType<State<'FUN_AUTH'>>;
97
+ export declare const FiatSessionSchema: z.ZodType<FiatSession>;
98
98
  export declare const SessionAuthStateSchema: z.ZodType<State<'SESSION_AUTH'>>;
99
99
  export declare const KycCaptureStateSchema: z.ZodType<State<'KYC', 'CAPTURE'>>;
100
100
  export declare const KycInputRequiredStateSchema: z.ZodType<State<'KYC', 'INPUT_REQUIRED'>>;
@@ -123,5 +123,10 @@ export declare const FiatRoutingTableErrorBodySchema: z.ZodType<FiatRoutingTable
123
123
  export declare const FiatRoutingQuoteErrorBodySchema: z.ZodType<FiatRoutingQuoteErrorBody>;
124
124
  export declare const FiatGeoSchema: z.ZodType<FiatGeo>;
125
125
  export declare const FiatNextRequestSchema: z.ZodType<FiatNextRequest>;
126
+ export declare const FiatAuthStartRequestSchema: z.ZodType<FiatAuthStartRequest>;
127
+ export declare const FiatAuthVerifyRequestSchema: z.ZodType<FiatAuthVerifyRequest>;
128
+ export declare const FiatAuthRefreshRequestSchema: z.ZodType<FiatAuthRefreshRequest>;
129
+ export declare const FiatAuthRefreshResponseSchema: z.ZodType<FiatAuthRefreshResponse>;
130
+ export declare const FiatAuthRevokeRequestSchema: z.ZodType<FiatAuthRevokeRequest>;
126
131
  export declare const FiatStepResponseSchema: z.ZodType<FiatStepResponse>;
127
132
  export {};
package/dist/table.d.ts CHANGED
@@ -43,6 +43,8 @@ export type StateKey = 'QUOTE' | 'FUN_AUTH' | 'SESSION_AUTH' | 'KYC/CAPTURE' | '
43
43
  */
44
44
  export declare const TERMINAL_ORDER_STATUSES: readonly ["SETTLED", "EXPIRED", "CANCELLED", "FAILED", "REFUNDED"];
45
45
  export type TerminalOrderStatus = (typeof TERMINAL_ORDER_STATUSES)[number];
46
+ /** Every `FunAuthErrorCode`, as data. Each rides `FailureReason.code` with `category: 'USER_ERROR'`. */
47
+ export declare const FUN_AUTH_ERROR_CODES: readonly ["INVALID_EMAIL", "BAD_CODE", "CODE_EXPIRED", "TOO_MANY_ATTEMPTS", "OTP_DISPATCH_THROTTLED"];
46
48
  /**
47
49
  * Endpoint template as written in the docs. Named `:` segments match one emitted path segment.
48
50
  */
@@ -92,9 +94,10 @@ export declare const STATE_KEYS: StateKey[];
92
94
  *
93
95
  * Sourced from contract §Endpoints, with one deliberate divergence: `POST /fiat/payment-session` is
94
96
  * named by the table (QUOTE's capture-first entry) while the doc's endpoint table still lists no
95
- * session-minting call for that rail.
97
+ * session-minting call for that rail. The `/fiat/auth/*` routes come from the Fun identity design
98
+ * that specifies `FUN_AUTH`.
96
99
  */
97
- export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/payment-session", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/quotes/:quoteRef", "POST /fiat/kyc/form", "POST /fiat/kyc/capture", "POST /fiat/kyc/sdk-token", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/delivery/:deliveryId", "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"];
100
+ export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/auth/verify", "POST /fiat/auth/refresh", "POST /fiat/auth/revoke", "POST /fiat/payment-session", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/quotes/:quoteRef", "POST /fiat/kyc/form", "POST /fiat/kyc/capture", "POST /fiat/kyc/sdk-token", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/delivery/:deliveryId", "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"];
98
101
  /**
99
102
  * Documented endpoints no flow state offers, and why. Declared so an endpoint nothing can reach is
100
103
  * visible instead of silent — the table test asserts the unoffered set equals exactly these.
package/dist/table.js CHANGED
@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
21
21
  var table_exports = {};
22
22
  __export(table_exports, {
23
23
  DOCUMENTED_ENDPOINTS: () => DOCUMENTED_ENDPOINTS,
24
+ FUN_AUTH_ERROR_CODES: () => FUN_AUTH_ERROR_CODES,
24
25
  STATE_KEYS: () => STATE_KEYS,
25
26
  TABLE_VERSION: () => TABLE_VERSION,
26
27
  TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
@@ -36,7 +37,7 @@ __export(table_exports, {
36
37
  module.exports = __toCommonJS(table_exports);
37
38
 
38
39
  // package.json
39
- var version = "0.39.0";
40
+ var version = "0.42.0";
40
41
 
41
42
  // src/table.ts
42
43
  var TABLE_VERSION = version;
@@ -47,6 +48,13 @@ var TERMINAL_ORDER_STATUSES = [
47
48
  "FAILED",
48
49
  "REFUNDED"
49
50
  ];
51
+ var FUN_AUTH_ERROR_CODES = [
52
+ "INVALID_EMAIL",
53
+ "BAD_CODE",
54
+ "CODE_EXPIRED",
55
+ "TOO_MANY_ATTEMPTS",
56
+ "OTP_DISPATCH_THROTTLED"
57
+ ];
50
58
  var KYC_ANY = [
51
59
  "KYC/CAPTURE",
52
60
  "KYC/INPUT_REQUIRED",
@@ -81,12 +89,6 @@ var TRANSITION_TABLE = {
81
89
  when: "returning user, session + KYC valid, order-first rail \u2014 the quote screen doubles as review",
82
90
  note: "Narrowed to the order-first rail: on a capture-first method the order cannot be created before the payment is authorised, so the sibling payment-session entry is the one that applies."
83
91
  },
84
- {
85
- id: "continue",
86
- mode: "SUBMIT",
87
- endpoint: "POST /fiat/auth",
88
- when: "no ambient Fun identity (non-fomo surfaces only)"
89
- },
90
92
  {
91
93
  id: "capture",
92
94
  mode: "CLIENT_SURFACE",
@@ -124,12 +126,31 @@ var TRANSITION_TABLE = {
124
126
  key: "FUN_AUTH",
125
127
  kind: "FUN_AUTH",
126
128
  screens: [],
127
- docStatus: "UNSPECIFIED",
128
- allowedTransitions: [],
129
+ docStatus: "SPECIFIED",
130
+ allowedTransitions: [
131
+ { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/auth", when: "phase IDENTIFIER \u2014 inputs { email: TEXT }" },
132
+ {
133
+ id: "verify",
134
+ mode: "SUBMIT",
135
+ endpoint: "POST /fiat/auth/verify",
136
+ when: "phase CODE \u2014 params { verificationRef }, inputs { otpCode: TEXT length 6, regex ^\\d{6}$ }"
137
+ },
138
+ {
139
+ id: "resend",
140
+ mode: "SUBMIT",
141
+ endpoint: "POST /fiat/auth",
142
+ when: "phase CODE, once resendAvailableAtMs has passed \u2014 params { verificationRef }"
143
+ }
144
+ ],
145
+ mayReturn: ["FUN_AUTH"],
129
146
  terminal: false,
130
147
  notes: [
131
- "TODO(open-decision): shape and transitions owned by the auth spike (contract \xA7Auth & ref binding, item 5).",
132
- "Never renders in fomo \u2014 identity is ambient, so the FE doc gives it no screen and no bindings row."
148
+ "Answered, in phase IDENTIFIER with the start transition, to the entry quote request (POST /fiat/routing/quote or POST /fiat/quote) of a Fun-run login that holds no session; no state returns it, and a customer-asserted identity never sees it.",
149
+ "VERIFIED carries no transitions. A Fun-run login also carries `session` on the envelope; the SDK then starts the flow at QUOTE with `accessToken` as Bearer.",
150
+ "Not in the FE doc, so no screen number: the client renders it on its contact and OTP screens.",
151
+ "Every FUN_AUTH error is category USER_ERROR with a code from FUN_AUTH_ERROR_CODES. A wrong code re-enters CODE with BAD_CODE and a lower attemptsRemaining; TOO_MANY_ATTEMPTS and CODE_EXPIRED drop the challenge and offer resend; OTP_DISPATCH_THROTTLED re-enters with resendAvailableAtMs set.",
152
+ "resend carries the verificationRef the client holds, even one the server has dropped (expired, too many attempts); the server starts a fresh challenge for the same email while it still remembers the challenge (its code expiry plus a short grace); once it is forgotten the answer is IDENTIFIER with CODE_EXPIRED.",
153
+ "POST /fiat/auth/refresh and /revoke are called by the SDK session store, never offered as transitions."
133
154
  ]
134
155
  },
135
156
  SESSION_AUTH: {
@@ -492,6 +513,9 @@ var DOCUMENTED_ENDPOINTS = [
492
513
  "GET /fiat/payment-methods",
493
514
  "POST /fiat/quote",
494
515
  "POST /fiat/auth",
516
+ "POST /fiat/auth/verify",
517
+ "POST /fiat/auth/refresh",
518
+ "POST /fiat/auth/revoke",
495
519
  "POST /fiat/payment-session",
496
520
  "POST /fiat/session",
497
521
  "POST /fiat/session/verify",
@@ -515,6 +539,14 @@ var UNOFFERED_ENDPOINTS = [
515
539
  endpoint: "GET /fiat/payment-methods",
516
540
  reason: "Discovery, called before any flow state exists \u2014 there is no state to hang it off."
517
541
  },
542
+ {
543
+ endpoint: "POST /fiat/auth/refresh",
544
+ reason: "SDK session store, not a transition."
545
+ },
546
+ {
547
+ endpoint: "POST /fiat/auth/revoke",
548
+ reason: "SDK session store, not a transition."
549
+ },
518
550
  {
519
551
  endpoint: "POST /fiat/kyc/document",
520
552
  reason: "FILE fields use it for a direct provider/vendor upload handshake and completion report; the harness owns that auxiliary path and it is not a transition (see KYC/INPUT_REQUIRED notes)."
@@ -535,7 +567,7 @@ var UNOFFERED_ENDPOINTS = [
535
567
  var UNREACHABLE_STATES = [
536
568
  {
537
569
  stateKey: "FUN_AUTH",
538
- reason: "No bindings row published (docStatus UNSPECIFIED) and never rendered in fomo, where identity is ambient. Entered out-of-band, not by a mayReturn edge."
570
+ reason: "Answered to the entry quote request of a Fun-run login with no session, before any state exists; no state returns it."
539
571
  }
540
572
  ];
541
573
  function unofferedEndpoints() {
package/dist/table.mjs CHANGED
@@ -1,5 +1,6 @@
1
1
  import {
2
2
  DOCUMENTED_ENDPOINTS,
3
+ FUN_AUTH_ERROR_CODES,
3
4
  STATE_KEYS,
4
5
  TABLE_VERSION,
5
6
  TERMINAL_ORDER_STATUSES,
@@ -11,9 +12,10 @@ import {
11
12
  tableEntry,
12
13
  unofferedEndpoints,
13
14
  unreachableStates
14
- } from "./chunk-LMF4OMUW.mjs";
15
+ } from "./chunk-RGQE53YP.mjs";
15
16
  export {
16
17
  DOCUMENTED_ENDPOINTS,
18
+ FUN_AUTH_ERROR_CODES,
17
19
  STATE_KEYS,
18
20
  TABLE_VERSION,
19
21
  TERMINAL_ORDER_STATUSES,
package/dist/types.d.ts CHANGED
@@ -56,7 +56,7 @@ export type HttpVerb = 'GET' | 'POST';
56
56
  * cannot express "no slash", so `GET /fiat/orders/${string}` also admits sub-paths. Precision at
57
57
  * that level is the table's job (`allowedTransitions` + `endpointMatches`), not the type's.
58
58
  */
59
- export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | `GET /fiat/quotes/${string}` | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/capture' | 'POST /fiat/kyc/sdk-token' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/delivery/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
59
+ export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/auth/verify' | 'POST /fiat/auth/refresh' | 'POST /fiat/auth/revoke' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | `GET /fiat/quotes/${string}` | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/capture' | 'POST /fiat/kyc/sdk-token' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/delivery/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
60
60
  /**
61
61
  * Routing metadata, not sequencing policy. Reserved values may be emitted only after their adapter
62
62
  * and conformance fixture land.
@@ -537,15 +537,56 @@ export interface PreparedPayment {
537
537
  mode: 'CLIENT_SURFACE';
538
538
  }>;
539
539
  }
540
+ /** Copy keys a `FUN_AUTH` error may carry in `FailureReason.code`. Every one is `category: 'USER_ERROR'`. */
541
+ export type FunAuthErrorCode = 'INVALID_EMAIL' | 'BAD_CODE' | 'CODE_EXPIRED' | 'TOO_MANY_ATTEMPTS' | 'OTP_DISPATCH_THROTTLED';
542
+ /** Fun-issued login for a FUN_AUTH user. The SDK never inspects `refreshHandle`. */
543
+ export type FiatSession = {
544
+ /** Bearer for every fiat call; verified by the backend by public key. Lifetime ≈ 1 h. */
545
+ accessToken: string;
546
+ /** Opaque; only the backend understands it. Rotates on every refresh. */
547
+ refreshHandle: string;
548
+ /** When `accessToken` stops being accepted (server clock, ms). */
549
+ expiresAtMs: number;
550
+ };
551
+ /**
552
+ * Body of `POST /fiat/auth`: an `email` from the `start` transition, or a `verificationRef` from
553
+ * `resend`. `resend` carries the `verificationRef` the client holds, even one the server has dropped
554
+ * (expired, too many attempts); the server starts a fresh challenge for the same email while it
555
+ * still remembers the challenge (code expiry plus a short grace), and answers `IDENTIFIER` with
556
+ * `CODE_EXPIRED` once it is forgotten.
557
+ * Transitions carry `params.verificationRef`; the client merges params and inputs into one body.
558
+ * Returns a `FiatStepResponse`: `FUN_AUTH` in phase `CODE`, or phase `IDENTIFIER` with `error` when
559
+ * the start failed with a user-correctable error.
560
+ */
561
+ export type FiatAuthStartRequest = {
562
+ email: string;
563
+ } | {
564
+ verificationRef: string;
565
+ };
540
566
  /**
541
- * TODO(open-decision): shape owned by the auth spike (contract §Auth & ref binding, item 5).
542
- * `FUN_AUTH` never renders in fomo (identity is ambient), so nothing in either doc constrains
543
- * this beyond the key name. Charles's review (2026-08-14) questions whether the kind is needed at
544
- * all, pending the Transak Auth Reliance answer — if reliance lands, provider-side session auth is
545
- * unreachable for fomo users and this kind may go with it. Kept for now: removing a kind is
546
- * cheap, adding one back costs a client release (handshake-gated).
567
+ * Body of `POST /fiat/auth/verify`. Returns a `FiatStepResponse`: `FUN_AUTH` in phase `VERIFIED`
568
+ * with `session` for a Fun-run login, or phase `CODE` with `error`.
547
569
  */
548
- export type AuthChallenge = Record<string, JsonValue>;
570
+ export type FiatAuthVerifyRequest = {
571
+ verificationRef: string;
572
+ otpCode: string;
573
+ };
574
+ /**
575
+ * Body of `POST /fiat/auth/refresh`. Returns 200 `FiatAuthRefreshResponse` with a rotated handle, or
576
+ * 401 when the session is revoked, expired or unknown; the SDK then clears its store and re-enters
577
+ * `FUN_AUTH`.
578
+ */
579
+ export type FiatAuthRefreshRequest = {
580
+ refreshHandle: string;
581
+ };
582
+ /** 200 body of `POST /fiat/auth/refresh`. */
583
+ export type FiatAuthRefreshResponse = {
584
+ session: FiatSession;
585
+ };
586
+ /** Body of `POST /fiat/auth/revoke`. Returns 204, and is idempotent. */
587
+ export type FiatAuthRevokeRequest = {
588
+ refreshHandle: string;
589
+ };
549
590
  /**
550
591
  * The expected length of a provider's KYC review. `BRIEF`: the client stays on its current screen,
551
592
  * polling, for up to `holdMs` (at most 600000), then shows the in-review screen. `EXTENDED`: the
@@ -576,9 +617,24 @@ export type FlowState =
576
617
  helper?: string;
577
618
  surface?: Surface;
578
619
  error?: FailureReason;
579
- } | {
620
+ }
621
+ /**
622
+ * Fun's own email one-time code, for a customer that sends no identity assertion. Entered
623
+ * when the entry quote request (`POST /fiat/routing/quote` or `POST /fiat/quote`) of a Fun-run login carries no session: the server answers it in
624
+ * phase IDENTIFIER with the `start` transition, whose `email` input the SDK collects.
625
+ */
626
+ | {
580
627
  kind: 'FUN_AUTH';
581
- challenge: AuthChallenge;
628
+ /** Which code the user is asked for. SMS_OTP arrives with phone verification; email-only today. */
629
+ channel: 'EMAIL_OTP' | 'SMS_OTP';
630
+ /** IDENTIFIER collects the email (or phone); CODE collects the code; VERIFIED closes the step. */
631
+ phase: 'IDENTIFIER' | 'CODE' | 'VERIFIED';
632
+ /** CODE: when the outstanding code stops being accepted (server clock, ms). */
633
+ expiresAtMs?: number;
634
+ /** CODE: when `resend` becomes available (server clock, ms). Absent = available now. */
635
+ resendAvailableAtMs?: number;
636
+ /** CODE: wrong codes still accepted before the challenge is dropped. */
637
+ attemptsRemaining?: number;
582
638
  error?: FailureReason;
583
639
  } | {
584
640
  kind: 'SESSION_AUTH';
@@ -746,17 +802,28 @@ type FiatStepResponseBase = {
746
802
  };
747
803
  /**
748
804
  * Provider is absent only when routing ended before a provider could be selected. A BLOCKED response
749
- * may still name a provider for compatibility with provider-specific terminal decisions; every other
750
- * state is provider-bound and therefore requires one.
805
+ * may still name a provider for compatibility with provider-specific terminal decisions. `FUN_AUTH`
806
+ * runs before any provider is chosen, so it may omit one too. Every other state is provider-bound
807
+ * and therefore requires one.
751
808
  */
752
809
  export type FiatStepResponse = (FiatStepResponseBase & {
753
810
  state: Extract<FlowState, {
754
811
  kind: 'BLOCKED';
755
812
  }>;
756
813
  provider?: FiatProvider;
814
+ }) | (FiatStepResponseBase & {
815
+ state: Extract<FlowState, {
816
+ kind: 'FUN_AUTH';
817
+ }>;
818
+ provider?: FiatProvider;
819
+ /**
820
+ * Present on a Fun-run login's VERIFIED response. Absent when the user already holds a customer
821
+ * identity assertion and FUN_AUTH only verified an attribute (phone verification, later phase).
822
+ */
823
+ session?: FiatSession;
757
824
  }) | (FiatStepResponseBase & {
758
825
  state: Exclude<FlowState, {
759
- kind: 'BLOCKED';
826
+ kind: 'BLOCKED' | 'FUN_AUTH';
760
827
  }>;
761
828
  provider: FiatProvider;
762
829
  /** Optional future payment artifact; never one of this response's currently active transitions. */