@fun-xyz/fiat-contract 0.39.0 → 0.40.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.
package/dist/assert.d.ts CHANGED
@@ -23,7 +23,7 @@ export declare function endpointMatches(template: EndpointTemplate, actual: stri
23
23
  export interface EmissionCheck {
24
24
  state: StateKey;
25
25
  issues: readonly string[];
26
- /** True when the docs publish no legal transition set for this state (`FUN_AUTH`). */
26
+ /** True when the docs publish no legal transition set for this state. */
27
27
  unjudgeable: boolean;
28
28
  }
29
29
  /**
@@ -1,5 +1,5 @@
1
1
  // package.json
2
- var version = "0.39.0";
2
+ var version = "0.40.0";
3
3
 
4
4
  // src/table.ts
5
5
  var TABLE_VERSION = version;
@@ -10,6 +10,13 @@ var TERMINAL_ORDER_STATUSES = [
10
10
  "FAILED",
11
11
  "REFUNDED"
12
12
  ];
13
+ var FUN_AUTH_ERROR_CODES = [
14
+ "INVALID_EMAIL",
15
+ "BAD_CODE",
16
+ "CODE_EXPIRED",
17
+ "TOO_MANY_ATTEMPTS",
18
+ "OTP_DISPATCH_THROTTLED"
19
+ ];
13
20
  var KYC_ANY = [
14
21
  "KYC/CAPTURE",
15
22
  "KYC/INPUT_REQUIRED",
@@ -44,12 +51,6 @@ var TRANSITION_TABLE = {
44
51
  when: "returning user, session + KYC valid, order-first rail \u2014 the quote screen doubles as review",
45
52
  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."
46
53
  },
47
- {
48
- id: "continue",
49
- mode: "SUBMIT",
50
- endpoint: "POST /fiat/auth",
51
- when: "no ambient Fun identity (non-fomo surfaces only)"
52
- },
53
54
  {
54
55
  id: "capture",
55
56
  mode: "CLIENT_SURFACE",
@@ -87,12 +88,31 @@ var TRANSITION_TABLE = {
87
88
  key: "FUN_AUTH",
88
89
  kind: "FUN_AUTH",
89
90
  screens: [],
90
- docStatus: "UNSPECIFIED",
91
- allowedTransitions: [],
91
+ docStatus: "SPECIFIED",
92
+ allowedTransitions: [
93
+ { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/auth", when: "phase IDENTIFIER \u2014 inputs { email: TEXT }" },
94
+ {
95
+ id: "verify",
96
+ mode: "SUBMIT",
97
+ endpoint: "POST /fiat/auth/verify",
98
+ when: "phase CODE \u2014 params { verificationRef }, inputs { code: TEXT length 6, regex ^\\d{6}$ }"
99
+ },
100
+ {
101
+ id: "resend",
102
+ mode: "SUBMIT",
103
+ endpoint: "POST /fiat/auth",
104
+ when: "phase CODE, once resendAvailableAtMs has passed \u2014 params { verificationRef }"
105
+ }
106
+ ],
107
+ mayReturn: ["FUN_AUTH"],
92
108
  terminal: false,
93
109
  notes: [
94
- "TODO(open-decision): shape and transitions owned by the auth spike (contract \xA7Auth & ref binding, item 5).",
95
- "Never renders in fomo \u2014 identity is ambient, so the FE doc gives it no screen and no bindings row."
110
+ "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.",
111
+ "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.",
112
+ "Not in the FE doc, so no screen number: the client renders it on its contact and OTP screens.",
113
+ "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.",
114
+ "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.",
115
+ "POST /fiat/auth/refresh and /revoke are called by the SDK session store, never offered as transitions."
96
116
  ]
97
117
  },
98
118
  SESSION_AUTH: {
@@ -455,6 +475,9 @@ var DOCUMENTED_ENDPOINTS = [
455
475
  "GET /fiat/payment-methods",
456
476
  "POST /fiat/quote",
457
477
  "POST /fiat/auth",
478
+ "POST /fiat/auth/verify",
479
+ "POST /fiat/auth/refresh",
480
+ "POST /fiat/auth/revoke",
458
481
  "POST /fiat/payment-session",
459
482
  "POST /fiat/session",
460
483
  "POST /fiat/session/verify",
@@ -478,6 +501,14 @@ var UNOFFERED_ENDPOINTS = [
478
501
  endpoint: "GET /fiat/payment-methods",
479
502
  reason: "Discovery, called before any flow state exists \u2014 there is no state to hang it off."
480
503
  },
504
+ {
505
+ endpoint: "POST /fiat/auth/refresh",
506
+ reason: "SDK session store, not a transition."
507
+ },
508
+ {
509
+ endpoint: "POST /fiat/auth/revoke",
510
+ reason: "SDK session store, not a transition."
511
+ },
481
512
  {
482
513
  endpoint: "POST /fiat/kyc/document",
483
514
  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)."
@@ -498,7 +529,7 @@ var UNOFFERED_ENDPOINTS = [
498
529
  var UNREACHABLE_STATES = [
499
530
  {
500
531
  stateKey: "FUN_AUTH",
501
- 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."
532
+ reason: "Answered to the entry quote request of a Fun-run login with no session, before any state exists; no state returns it."
502
533
  }
503
534
  ];
504
535
  function unofferedEndpoints() {
@@ -562,6 +593,7 @@ function isTerminal(state) {
562
593
  export {
563
594
  TABLE_VERSION,
564
595
  TERMINAL_ORDER_STATUSES,
596
+ FUN_AUTH_ERROR_CODES,
565
597
  TRANSITION_TABLE,
566
598
  STATE_KEYS,
567
599
  DOCUMENTED_ENDPOINTS,
@@ -14,7 +14,8 @@
14
14
  * wire, and the contract has no half-response shape.
15
15
  */
16
16
  import type { StateKey } from '../table';
17
- export type FixtureSource = 'FE_DOC' | 'CONTRACT_DOC' | 'KYC_DOC';
17
+ /** `IDENTITY_DOC` is the Fun identity design that specifies `FUN_AUTH` and the Fun session. */
18
+ export type FixtureSource = 'FE_DOC' | 'CONTRACT_DOC' | 'KYC_DOC' | 'IDENTITY_DOC';
18
19
  export interface FixtureMeta {
19
20
  id: string;
20
21
  file: string;
package/dist/index.js CHANGED
@@ -20,7 +20,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
20
20
  // src/index.ts
21
21
  var index_exports = {};
22
22
  __export(index_exports, {
23
- AuthChallengeSchema: () => AuthChallengeSchema,
24
23
  BlockedReasonSchema: () => BlockedReasonSchema,
25
24
  BlockedStateSchema: () => BlockedStateSchema,
26
25
  COUNTRY_NAMES: () => COUNTRY_NAMES,
@@ -38,10 +37,16 @@ __export(index_exports, {
38
37
  FIELD_SPEC_TYPES: () => FIELD_SPEC_TYPES,
39
38
  FIXTURES: () => FIXTURES,
40
39
  FIXTURE_COVERAGE_GAPS: () => FIXTURE_COVERAGE_GAPS,
40
+ FUN_AUTH_ERROR_CODES: () => FUN_AUTH_ERROR_CODES,
41
41
  FUN_KYC_CONSENT_DOCUMENTS: () => FUN_KYC_CONSENT_DOCUMENTS,
42
42
  FailureReasonSchema: () => FailureReasonSchema,
43
43
  FeeLineSchema: () => FeeLineSchema,
44
44
  FiatAmountSchema: () => FiatAmountSchema,
45
+ FiatAuthRefreshRequestSchema: () => FiatAuthRefreshRequestSchema,
46
+ FiatAuthRefreshResponseSchema: () => FiatAuthRefreshResponseSchema,
47
+ FiatAuthRevokeRequestSchema: () => FiatAuthRevokeRequestSchema,
48
+ FiatAuthStartRequestSchema: () => FiatAuthStartRequestSchema,
49
+ FiatAuthVerifyRequestSchema: () => FiatAuthVerifyRequestSchema,
45
50
  FiatCurrencyCode: () => FiatCurrencyCode,
46
51
  FiatEndpointSchema: () => FiatEndpointSchema,
47
52
  FiatGeoSchema: () => FiatGeoSchema,
@@ -53,6 +58,7 @@ __export(index_exports, {
53
58
  FiatRoutingTableErrorBodySchema: () => FiatRoutingTableErrorBodySchema,
54
59
  FiatRoutingTableRequestSchema: () => FiatRoutingTableRequestSchema,
55
60
  FiatRoutingTableResponseSchema: () => FiatRoutingTableResponseSchema,
61
+ FiatSessionSchema: () => FiatSessionSchema,
56
62
  FiatStepResponseSchema: () => FiatStepResponseSchema,
57
63
  FiatTermsErrorBodySchema: () => FiatTermsErrorBodySchema,
58
64
  FiatTermsRequestSchema: () => FiatTermsRequestSchema,
@@ -891,8 +897,6 @@ var $preparedPayment = obj({
891
897
  transition: $clientSurfaceTransition
892
898
  });
893
899
  var PreparedPaymentSchema = $preparedPayment;
894
- var $authChallenge = import_zod.z.record(import_zod.z.string(), JsonSchema);
895
- var AuthChallengeSchema = $authChallenge;
896
900
  var $quoteState = obj({
897
901
  kind: import_zod.z.literal("QUOTE"),
898
902
  quote: $quote,
@@ -905,10 +909,20 @@ var $quoteState = obj({
905
909
  var QuoteStateSchema = $quoteState;
906
910
  var $funAuthState = obj({
907
911
  kind: import_zod.z.literal("FUN_AUTH"),
908
- challenge: $authChallenge,
912
+ channel: import_zod.z.enum(["EMAIL_OTP", "SMS_OTP"]),
913
+ phase: import_zod.z.enum(["IDENTIFIER", "CODE", "VERIFIED"]),
914
+ expiresAtMs: import_zod.z.number().int().nonnegative().optional(),
915
+ resendAvailableAtMs: import_zod.z.number().int().nonnegative().optional(),
916
+ attemptsRemaining: import_zod.z.number().int().nonnegative().optional(),
909
917
  error: $failureReason.optional()
910
918
  });
911
919
  var FunAuthStateSchema = $funAuthState;
920
+ var $fiatSession = obj({
921
+ accessToken: import_zod.z.string().min(1),
922
+ refreshHandle: import_zod.z.string().min(1),
923
+ expiresAtMs: import_zod.z.number().int().nonnegative()
924
+ });
925
+ var FiatSessionSchema = $fiatSession;
912
926
  var $sessionAuthState = obj({
913
927
  kind: import_zod.z.literal("SESSION_AUTH"),
914
928
  channel: import_zod.z.enum(["EMAIL_OTP", "SMS_OTP", "PROVIDER_RENDERED"]),
@@ -1014,7 +1028,6 @@ var $deliveryState = import_zod.z.discriminatedUnion("state", [
1014
1028
  var DeliveryStateSchema = $deliveryState;
1015
1029
  var $providerBoundFlowState = import_zod.z.union([
1016
1030
  $quoteState,
1017
- $funAuthState,
1018
1031
  $sessionAuthState,
1019
1032
  $kycCaptureState,
1020
1033
  $kycInputRequiredState,
@@ -1026,7 +1039,7 @@ var $providerBoundFlowState = import_zod.z.union([
1026
1039
  $orderCreatedState,
1027
1040
  $deliveryState
1028
1041
  ]);
1029
- var $flowState = import_zod.z.union([$providerBoundFlowState, $blockedState]);
1042
+ var $flowState = import_zod.z.union([$providerBoundFlowState, $funAuthState, $blockedState]);
1030
1043
  var FlowStateSchema = $flowState;
1031
1044
  var $nonBlank = import_zod.z.string().refine((value) => value.trim().length > 0, "must not be blank");
1032
1045
  var $isoInstant = import_zod.z.string().datetime({ offset: true });
@@ -1233,12 +1246,18 @@ var $fiatGeo = obj({ alpha2: import_zod.z.string().regex(/^[A-Z]{2}$/), region:
1233
1246
  var FiatGeoSchema = $fiatGeo;
1234
1247
  var $nextRequest = import_zod.z.object({ provider: $provider, action: $nonBlank, geo: $fiatGeo, destinationAsset: $destinationAsset.optional() }).catchall(import_zod.z.unknown());
1235
1248
  var FiatNextRequestSchema = $nextRequest;
1236
- var $providerBoundStepResponse = obj({
1237
- state: $providerBoundFlowState,
1238
- provider: $provider,
1249
+ var $authStartRequest = import_zod.z.union([obj({ email: $nonBlank }), obj({ verificationRef: $nonBlank })]);
1250
+ var FiatAuthStartRequestSchema = $authStartRequest;
1251
+ var $authVerifyRequest = obj({ verificationRef: $nonBlank, code: import_zod.z.string().regex(/^\d{6}$/, "must be six digits") });
1252
+ var FiatAuthVerifyRequestSchema = $authVerifyRequest;
1253
+ var $authRefreshRequest = obj({ refreshHandle: $nonBlank });
1254
+ var FiatAuthRefreshRequestSchema = $authRefreshRequest;
1255
+ var $authRefreshResponse = obj({ session: $fiatSession });
1256
+ var FiatAuthRefreshResponseSchema = $authRefreshResponse;
1257
+ var $authRevokeRequest = obj({ refreshHandle: $nonBlank });
1258
+ var FiatAuthRevokeRequestSchema = $authRevokeRequest;
1259
+ var $stepResponseBase = {
1239
1260
  transitions: import_zod.z.array($transition),
1240
- preparedPayment: $preparedPayment.optional(),
1241
- handoff: obj({ provider: $provider }).optional(),
1242
1261
  routingSessionRef: import_zod.z.string().optional(),
1243
1262
  providerAuthToken: obj({
1244
1263
  clientSecret: import_zod.z.string(),
@@ -1246,6 +1265,13 @@ var $providerBoundStepResponse = obj({
1246
1265
  }).optional(),
1247
1266
  orderId: import_zod.z.string().optional(),
1248
1267
  refreshLimits: import_zod.z.literal(true).optional()
1268
+ };
1269
+ var $providerBoundStepResponse = obj({
1270
+ ...$stepResponseBase,
1271
+ state: $providerBoundFlowState,
1272
+ provider: $provider,
1273
+ preparedPayment: $preparedPayment.optional(),
1274
+ handoff: obj({ provider: $provider }).optional()
1249
1275
  }).superRefine((response, context) => {
1250
1276
  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
1251
1277
  context.addIssue({
@@ -1277,22 +1303,41 @@ var $providerBoundStepResponse = obj({
1277
1303
  }
1278
1304
  });
1279
1305
  var $blockedStepResponse = obj({
1306
+ ...$stepResponseBase,
1280
1307
  state: $blockedState,
1308
+ provider: $provider.optional()
1309
+ });
1310
+ var FUN_AUTH_TRANSITIONS_BY_PHASE = {
1311
+ IDENTIFIER: ["start"],
1312
+ CODE: ["verify", "resend"],
1313
+ VERIFIED: []
1314
+ };
1315
+ var $funAuthStepResponse = obj({
1316
+ ...$stepResponseBase,
1317
+ state: $funAuthState,
1281
1318
  provider: $provider.optional(),
1282
- transitions: import_zod.z.array($transition),
1283
- routingSessionRef: import_zod.z.string().optional(),
1284
- providerAuthToken: obj({
1285
- clientSecret: import_zod.z.string(),
1286
- expiresAt: import_zod.z.string()
1287
- }).optional(),
1288
- orderId: import_zod.z.string().optional(),
1289
- refreshLimits: import_zod.z.literal(true).optional()
1319
+ session: $fiatSession.optional()
1320
+ }).superRefine((response, context) => {
1321
+ const { phase } = response.state;
1322
+ if (response.session !== void 0 && phase !== "VERIFIED") {
1323
+ context.addIssue({ code: "custom", path: ["session"], message: "only a FUN_AUTH response in phase VERIFIED carries session" });
1324
+ }
1325
+ const allowed = FUN_AUTH_TRANSITIONS_BY_PHASE[phase];
1326
+ response.transitions.forEach((transition, index) => {
1327
+ if (!allowed.includes(transition.id)) {
1328
+ context.addIssue({
1329
+ code: "custom",
1330
+ path: ["transitions", index, "id"],
1331
+ message: `FUN_AUTH phase ${phase} offers ${allowed.join(" or ") || "no transitions"}, not "${transition.id}"`
1332
+ });
1333
+ }
1334
+ });
1290
1335
  });
1291
- var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStepResponse]);
1336
+ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $funAuthStepResponse, $blockedStepResponse]);
1292
1337
  var FiatStepResponseSchema = $stepResponse;
1293
1338
 
1294
1339
  // package.json
1295
- var version = "0.39.0";
1340
+ var version = "0.40.0";
1296
1341
 
1297
1342
  // src/table.ts
1298
1343
  var TABLE_VERSION = version;
@@ -1303,6 +1348,13 @@ var TERMINAL_ORDER_STATUSES = [
1303
1348
  "FAILED",
1304
1349
  "REFUNDED"
1305
1350
  ];
1351
+ var FUN_AUTH_ERROR_CODES = [
1352
+ "INVALID_EMAIL",
1353
+ "BAD_CODE",
1354
+ "CODE_EXPIRED",
1355
+ "TOO_MANY_ATTEMPTS",
1356
+ "OTP_DISPATCH_THROTTLED"
1357
+ ];
1306
1358
  var KYC_ANY = [
1307
1359
  "KYC/CAPTURE",
1308
1360
  "KYC/INPUT_REQUIRED",
@@ -1337,12 +1389,6 @@ var TRANSITION_TABLE = {
1337
1389
  when: "returning user, session + KYC valid, order-first rail \u2014 the quote screen doubles as review",
1338
1390
  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."
1339
1391
  },
1340
- {
1341
- id: "continue",
1342
- mode: "SUBMIT",
1343
- endpoint: "POST /fiat/auth",
1344
- when: "no ambient Fun identity (non-fomo surfaces only)"
1345
- },
1346
1392
  {
1347
1393
  id: "capture",
1348
1394
  mode: "CLIENT_SURFACE",
@@ -1380,12 +1426,31 @@ var TRANSITION_TABLE = {
1380
1426
  key: "FUN_AUTH",
1381
1427
  kind: "FUN_AUTH",
1382
1428
  screens: [],
1383
- docStatus: "UNSPECIFIED",
1384
- allowedTransitions: [],
1429
+ docStatus: "SPECIFIED",
1430
+ allowedTransitions: [
1431
+ { id: "start", mode: "SUBMIT", endpoint: "POST /fiat/auth", when: "phase IDENTIFIER \u2014 inputs { email: TEXT }" },
1432
+ {
1433
+ id: "verify",
1434
+ mode: "SUBMIT",
1435
+ endpoint: "POST /fiat/auth/verify",
1436
+ when: "phase CODE \u2014 params { verificationRef }, inputs { code: TEXT length 6, regex ^\\d{6}$ }"
1437
+ },
1438
+ {
1439
+ id: "resend",
1440
+ mode: "SUBMIT",
1441
+ endpoint: "POST /fiat/auth",
1442
+ when: "phase CODE, once resendAvailableAtMs has passed \u2014 params { verificationRef }"
1443
+ }
1444
+ ],
1445
+ mayReturn: ["FUN_AUTH"],
1385
1446
  terminal: false,
1386
1447
  notes: [
1387
- "TODO(open-decision): shape and transitions owned by the auth spike (contract \xA7Auth & ref binding, item 5).",
1388
- "Never renders in fomo \u2014 identity is ambient, so the FE doc gives it no screen and no bindings row."
1448
+ "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.",
1449
+ "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.",
1450
+ "Not in the FE doc, so no screen number: the client renders it on its contact and OTP screens.",
1451
+ "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.",
1452
+ "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.",
1453
+ "POST /fiat/auth/refresh and /revoke are called by the SDK session store, never offered as transitions."
1389
1454
  ]
1390
1455
  },
1391
1456
  SESSION_AUTH: {
@@ -1748,6 +1813,9 @@ var DOCUMENTED_ENDPOINTS = [
1748
1813
  "GET /fiat/payment-methods",
1749
1814
  "POST /fiat/quote",
1750
1815
  "POST /fiat/auth",
1816
+ "POST /fiat/auth/verify",
1817
+ "POST /fiat/auth/refresh",
1818
+ "POST /fiat/auth/revoke",
1751
1819
  "POST /fiat/payment-session",
1752
1820
  "POST /fiat/session",
1753
1821
  "POST /fiat/session/verify",
@@ -1771,6 +1839,14 @@ var UNOFFERED_ENDPOINTS = [
1771
1839
  endpoint: "GET /fiat/payment-methods",
1772
1840
  reason: "Discovery, called before any flow state exists \u2014 there is no state to hang it off."
1773
1841
  },
1842
+ {
1843
+ endpoint: "POST /fiat/auth/refresh",
1844
+ reason: "SDK session store, not a transition."
1845
+ },
1846
+ {
1847
+ endpoint: "POST /fiat/auth/revoke",
1848
+ reason: "SDK session store, not a transition."
1849
+ },
1774
1850
  {
1775
1851
  endpoint: "POST /fiat/kyc/document",
1776
1852
  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)."
@@ -1791,7 +1867,7 @@ var UNOFFERED_ENDPOINTS = [
1791
1867
  var UNREACHABLE_STATES = [
1792
1868
  {
1793
1869
  stateKey: "FUN_AUTH",
1794
- 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."
1870
+ reason: "Answered to the entry quote request of a Fun-run login with no session, before any state exists; no state returns it."
1795
1871
  }
1796
1872
  ];
1797
1873
  function unofferedEndpoints() {
@@ -1891,6 +1967,79 @@ var FIXTURE_DATA = {
1891
1967
  "provider": "MOONPAY",
1892
1968
  "transitions": []
1893
1969
  },
1970
+ "fun-auth-01-identifier": {
1971
+ "state": {
1972
+ "kind": "FUN_AUTH",
1973
+ "channel": "EMAIL_OTP",
1974
+ "phase": "IDENTIFIER",
1975
+ "error": {
1976
+ "category": "USER_ERROR",
1977
+ "retryable": true,
1978
+ "recovery": "NONE",
1979
+ "code": "INVALID_EMAIL"
1980
+ }
1981
+ },
1982
+ "transitions": [
1983
+ {
1984
+ "id": "start",
1985
+ "mode": "SUBMIT",
1986
+ "endpoint": "POST /fiat/auth",
1987
+ "inputs": {
1988
+ "email": {
1989
+ "type": "TEXT"
1990
+ }
1991
+ }
1992
+ }
1993
+ ]
1994
+ },
1995
+ "fun-auth-02-code": {
1996
+ "state": {
1997
+ "kind": "FUN_AUTH",
1998
+ "channel": "EMAIL_OTP",
1999
+ "phase": "CODE",
2000
+ "expiresAtMs": 17600006e5,
2001
+ "resendAvailableAtMs": 176000006e4,
2002
+ "attemptsRemaining": 3
2003
+ },
2004
+ "transitions": [
2005
+ {
2006
+ "id": "verify",
2007
+ "mode": "SUBMIT",
2008
+ "endpoint": "POST /fiat/auth/verify",
2009
+ "params": {
2010
+ "verificationRef": "vr_7c1"
2011
+ },
2012
+ "inputs": {
2013
+ "code": {
2014
+ "type": "TEXT",
2015
+ "length": 6,
2016
+ "regex": "^\\d{6}$"
2017
+ }
2018
+ }
2019
+ },
2020
+ {
2021
+ "id": "resend",
2022
+ "mode": "SUBMIT",
2023
+ "endpoint": "POST /fiat/auth",
2024
+ "params": {
2025
+ "verificationRef": "vr_7c1"
2026
+ }
2027
+ }
2028
+ ]
2029
+ },
2030
+ "fun-auth-03-verified": {
2031
+ "state": {
2032
+ "kind": "FUN_AUTH",
2033
+ "channel": "EMAIL_OTP",
2034
+ "phase": "VERIFIED"
2035
+ },
2036
+ "transitions": [],
2037
+ "session": {
2038
+ "accessToken": "<access-token>",
2039
+ "refreshHandle": "<refresh-handle>",
2040
+ "expiresAtMs": 176e10
2041
+ }
2042
+ },
1894
2043
  "screen-01-quote": {
1895
2044
  "state": {
1896
2045
  "kind": "QUOTE",
@@ -2718,6 +2867,36 @@ var FIXTURES = [
2718
2867
  screen: 2,
2719
2868
  stateKey: "SESSION_AUTH"
2720
2869
  },
2870
+ {
2871
+ id: "fun-auth-01-identifier",
2872
+ file: "fun-auth-01-identifier.json",
2873
+ source: "IDENTITY_DOC",
2874
+ docRef: "Fiat identity design doc (2026-10-20) \xB7 Contract changes",
2875
+ stateKey: "FUN_AUTH",
2876
+ notes: [
2877
+ "The server re-asks for the email after a start that failed with a user-correctable error. The first IDENTIFIER is entered client-side.",
2878
+ "No provider: FUN_AUTH runs before any provider is chosen."
2879
+ ]
2880
+ },
2881
+ {
2882
+ id: "fun-auth-02-code",
2883
+ file: "fun-auth-02-code.json",
2884
+ source: "IDENTITY_DOC",
2885
+ docRef: "Fiat identity design doc (2026-10-20) \xB7 Contract changes",
2886
+ stateKey: "FUN_AUTH",
2887
+ notes: ["verify and resend carry the same verificationRef; resend is usable once resendAvailableAtMs has passed."]
2888
+ },
2889
+ {
2890
+ id: "fun-auth-03-verified",
2891
+ file: "fun-auth-03-verified.json",
2892
+ source: "IDENTITY_DOC",
2893
+ docRef: "Fiat identity design doc (2026-10-20) \xB7 Contract changes",
2894
+ stateKey: "FUN_AUTH",
2895
+ notes: [
2896
+ "A Fun-run login: the envelope carries the Fun session and no transitions. The SDK then starts the flow at QUOTE with accessToken as Bearer.",
2897
+ "accessToken and refreshHandle are placeholders."
2898
+ ]
2899
+ },
2721
2900
  {
2722
2901
  id: "screen-03-kyc-input-required",
2723
2902
  file: "screen-03-kyc-input-required.json",
@@ -2908,12 +3087,7 @@ var FIXTURES = [
2908
3087
  ]
2909
3088
  }
2910
3089
  ];
2911
- var FIXTURE_COVERAGE_GAPS = [
2912
- {
2913
- stateKey: "FUN_AUTH",
2914
- reason: "No step response 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."
2915
- }
2916
- ];
3090
+ var FIXTURE_COVERAGE_GAPS = [];
2917
3091
  var fixtureMeta = (id) => {
2918
3092
  const meta = FIXTURES.find((f) => f.id === id);
2919
3093
  if (!meta) throw new Error(`unknown fixture: ${id}`);
package/dist/index.mjs CHANGED
@@ -1,6 +1,7 @@
1
1
  import "./chunk-WBQAMGXK.mjs";
2
2
  import {
3
3
  DOCUMENTED_ENDPOINTS,
4
+ FUN_AUTH_ERROR_CODES,
4
5
  STATE_KEYS,
5
6
  TABLE_VERSION,
6
7
  TERMINAL_ORDER_STATUSES,
@@ -12,7 +13,7 @@ import {
12
13
  tableEntry,
13
14
  unofferedEndpoints,
14
15
  unreachableStates
15
- } from "./chunk-LMF4OMUW.mjs";
16
+ } from "./chunk-4Y22UVT4.mjs";
16
17
  import {
17
18
  MOONPAY_ENDPOINTS
18
19
  } from "./chunk-TIEGTTFY.mjs";
@@ -741,8 +742,6 @@ var $preparedPayment = obj({
741
742
  transition: $clientSurfaceTransition
742
743
  });
743
744
  var PreparedPaymentSchema = $preparedPayment;
744
- var $authChallenge = z.record(z.string(), JsonSchema);
745
- var AuthChallengeSchema = $authChallenge;
746
745
  var $quoteState = obj({
747
746
  kind: z.literal("QUOTE"),
748
747
  quote: $quote,
@@ -755,10 +754,20 @@ var $quoteState = obj({
755
754
  var QuoteStateSchema = $quoteState;
756
755
  var $funAuthState = obj({
757
756
  kind: z.literal("FUN_AUTH"),
758
- challenge: $authChallenge,
757
+ channel: z.enum(["EMAIL_OTP", "SMS_OTP"]),
758
+ phase: z.enum(["IDENTIFIER", "CODE", "VERIFIED"]),
759
+ expiresAtMs: z.number().int().nonnegative().optional(),
760
+ resendAvailableAtMs: z.number().int().nonnegative().optional(),
761
+ attemptsRemaining: z.number().int().nonnegative().optional(),
759
762
  error: $failureReason.optional()
760
763
  });
761
764
  var FunAuthStateSchema = $funAuthState;
765
+ var $fiatSession = obj({
766
+ accessToken: z.string().min(1),
767
+ refreshHandle: z.string().min(1),
768
+ expiresAtMs: z.number().int().nonnegative()
769
+ });
770
+ var FiatSessionSchema = $fiatSession;
762
771
  var $sessionAuthState = obj({
763
772
  kind: z.literal("SESSION_AUTH"),
764
773
  channel: z.enum(["EMAIL_OTP", "SMS_OTP", "PROVIDER_RENDERED"]),
@@ -864,7 +873,6 @@ var $deliveryState = z.discriminatedUnion("state", [
864
873
  var DeliveryStateSchema = $deliveryState;
865
874
  var $providerBoundFlowState = z.union([
866
875
  $quoteState,
867
- $funAuthState,
868
876
  $sessionAuthState,
869
877
  $kycCaptureState,
870
878
  $kycInputRequiredState,
@@ -876,7 +884,7 @@ var $providerBoundFlowState = z.union([
876
884
  $orderCreatedState,
877
885
  $deliveryState
878
886
  ]);
879
- var $flowState = z.union([$providerBoundFlowState, $blockedState]);
887
+ var $flowState = z.union([$providerBoundFlowState, $funAuthState, $blockedState]);
880
888
  var FlowStateSchema = $flowState;
881
889
  var $nonBlank = z.string().refine((value) => value.trim().length > 0, "must not be blank");
882
890
  var $isoInstant = z.string().datetime({ offset: true });
@@ -1083,12 +1091,18 @@ var $fiatGeo = obj({ alpha2: z.string().regex(/^[A-Z]{2}$/), region: $nonBlank.o
1083
1091
  var FiatGeoSchema = $fiatGeo;
1084
1092
  var $nextRequest = z.object({ provider: $provider, action: $nonBlank, geo: $fiatGeo, destinationAsset: $destinationAsset.optional() }).catchall(z.unknown());
1085
1093
  var FiatNextRequestSchema = $nextRequest;
1086
- var $providerBoundStepResponse = obj({
1087
- state: $providerBoundFlowState,
1088
- provider: $provider,
1094
+ var $authStartRequest = z.union([obj({ email: $nonBlank }), obj({ verificationRef: $nonBlank })]);
1095
+ var FiatAuthStartRequestSchema = $authStartRequest;
1096
+ var $authVerifyRequest = obj({ verificationRef: $nonBlank, code: z.string().regex(/^\d{6}$/, "must be six digits") });
1097
+ var FiatAuthVerifyRequestSchema = $authVerifyRequest;
1098
+ var $authRefreshRequest = obj({ refreshHandle: $nonBlank });
1099
+ var FiatAuthRefreshRequestSchema = $authRefreshRequest;
1100
+ var $authRefreshResponse = obj({ session: $fiatSession });
1101
+ var FiatAuthRefreshResponseSchema = $authRefreshResponse;
1102
+ var $authRevokeRequest = obj({ refreshHandle: $nonBlank });
1103
+ var FiatAuthRevokeRequestSchema = $authRevokeRequest;
1104
+ var $stepResponseBase = {
1089
1105
  transitions: z.array($transition),
1090
- preparedPayment: $preparedPayment.optional(),
1091
- handoff: obj({ provider: $provider }).optional(),
1092
1106
  routingSessionRef: z.string().optional(),
1093
1107
  providerAuthToken: obj({
1094
1108
  clientSecret: z.string(),
@@ -1096,6 +1110,13 @@ var $providerBoundStepResponse = obj({
1096
1110
  }).optional(),
1097
1111
  orderId: z.string().optional(),
1098
1112
  refreshLimits: z.literal(true).optional()
1113
+ };
1114
+ var $providerBoundStepResponse = obj({
1115
+ ...$stepResponseBase,
1116
+ state: $providerBoundFlowState,
1117
+ provider: $provider,
1118
+ preparedPayment: $preparedPayment.optional(),
1119
+ handoff: obj({ provider: $provider }).optional()
1099
1120
  }).superRefine((response, context) => {
1100
1121
  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
1101
1122
  context.addIssue({
@@ -1127,18 +1148,37 @@ var $providerBoundStepResponse = obj({
1127
1148
  }
1128
1149
  });
1129
1150
  var $blockedStepResponse = obj({
1151
+ ...$stepResponseBase,
1130
1152
  state: $blockedState,
1153
+ provider: $provider.optional()
1154
+ });
1155
+ var FUN_AUTH_TRANSITIONS_BY_PHASE = {
1156
+ IDENTIFIER: ["start"],
1157
+ CODE: ["verify", "resend"],
1158
+ VERIFIED: []
1159
+ };
1160
+ var $funAuthStepResponse = obj({
1161
+ ...$stepResponseBase,
1162
+ state: $funAuthState,
1131
1163
  provider: $provider.optional(),
1132
- transitions: z.array($transition),
1133
- routingSessionRef: z.string().optional(),
1134
- providerAuthToken: obj({
1135
- clientSecret: z.string(),
1136
- expiresAt: z.string()
1137
- }).optional(),
1138
- orderId: z.string().optional(),
1139
- refreshLimits: z.literal(true).optional()
1164
+ session: $fiatSession.optional()
1165
+ }).superRefine((response, context) => {
1166
+ const { phase } = response.state;
1167
+ if (response.session !== void 0 && phase !== "VERIFIED") {
1168
+ context.addIssue({ code: "custom", path: ["session"], message: "only a FUN_AUTH response in phase VERIFIED carries session" });
1169
+ }
1170
+ const allowed = FUN_AUTH_TRANSITIONS_BY_PHASE[phase];
1171
+ response.transitions.forEach((transition, index) => {
1172
+ if (!allowed.includes(transition.id)) {
1173
+ context.addIssue({
1174
+ code: "custom",
1175
+ path: ["transitions", index, "id"],
1176
+ message: `FUN_AUTH phase ${phase} offers ${allowed.join(" or ") || "no transitions"}, not "${transition.id}"`
1177
+ });
1178
+ }
1179
+ });
1140
1180
  });
1141
- var $stepResponse = z.union([$providerBoundStepResponse, $blockedStepResponse]);
1181
+ var $stepResponse = z.union([$providerBoundStepResponse, $funAuthStepResponse, $blockedStepResponse]);
1142
1182
  var FiatStepResponseSchema = $stepResponse;
1143
1183
 
1144
1184
  // src/fixtures/data.ts
@@ -1180,6 +1220,79 @@ var FIXTURE_DATA = {
1180
1220
  "provider": "MOONPAY",
1181
1221
  "transitions": []
1182
1222
  },
1223
+ "fun-auth-01-identifier": {
1224
+ "state": {
1225
+ "kind": "FUN_AUTH",
1226
+ "channel": "EMAIL_OTP",
1227
+ "phase": "IDENTIFIER",
1228
+ "error": {
1229
+ "category": "USER_ERROR",
1230
+ "retryable": true,
1231
+ "recovery": "NONE",
1232
+ "code": "INVALID_EMAIL"
1233
+ }
1234
+ },
1235
+ "transitions": [
1236
+ {
1237
+ "id": "start",
1238
+ "mode": "SUBMIT",
1239
+ "endpoint": "POST /fiat/auth",
1240
+ "inputs": {
1241
+ "email": {
1242
+ "type": "TEXT"
1243
+ }
1244
+ }
1245
+ }
1246
+ ]
1247
+ },
1248
+ "fun-auth-02-code": {
1249
+ "state": {
1250
+ "kind": "FUN_AUTH",
1251
+ "channel": "EMAIL_OTP",
1252
+ "phase": "CODE",
1253
+ "expiresAtMs": 17600006e5,
1254
+ "resendAvailableAtMs": 176000006e4,
1255
+ "attemptsRemaining": 3
1256
+ },
1257
+ "transitions": [
1258
+ {
1259
+ "id": "verify",
1260
+ "mode": "SUBMIT",
1261
+ "endpoint": "POST /fiat/auth/verify",
1262
+ "params": {
1263
+ "verificationRef": "vr_7c1"
1264
+ },
1265
+ "inputs": {
1266
+ "code": {
1267
+ "type": "TEXT",
1268
+ "length": 6,
1269
+ "regex": "^\\d{6}$"
1270
+ }
1271
+ }
1272
+ },
1273
+ {
1274
+ "id": "resend",
1275
+ "mode": "SUBMIT",
1276
+ "endpoint": "POST /fiat/auth",
1277
+ "params": {
1278
+ "verificationRef": "vr_7c1"
1279
+ }
1280
+ }
1281
+ ]
1282
+ },
1283
+ "fun-auth-03-verified": {
1284
+ "state": {
1285
+ "kind": "FUN_AUTH",
1286
+ "channel": "EMAIL_OTP",
1287
+ "phase": "VERIFIED"
1288
+ },
1289
+ "transitions": [],
1290
+ "session": {
1291
+ "accessToken": "<access-token>",
1292
+ "refreshHandle": "<refresh-handle>",
1293
+ "expiresAtMs": 176e10
1294
+ }
1295
+ },
1183
1296
  "screen-01-quote": {
1184
1297
  "state": {
1185
1298
  "kind": "QUOTE",
@@ -2007,6 +2120,36 @@ var FIXTURES = [
2007
2120
  screen: 2,
2008
2121
  stateKey: "SESSION_AUTH"
2009
2122
  },
2123
+ {
2124
+ id: "fun-auth-01-identifier",
2125
+ file: "fun-auth-01-identifier.json",
2126
+ source: "IDENTITY_DOC",
2127
+ docRef: "Fiat identity design doc (2026-10-20) \xB7 Contract changes",
2128
+ stateKey: "FUN_AUTH",
2129
+ notes: [
2130
+ "The server re-asks for the email after a start that failed with a user-correctable error. The first IDENTIFIER is entered client-side.",
2131
+ "No provider: FUN_AUTH runs before any provider is chosen."
2132
+ ]
2133
+ },
2134
+ {
2135
+ id: "fun-auth-02-code",
2136
+ file: "fun-auth-02-code.json",
2137
+ source: "IDENTITY_DOC",
2138
+ docRef: "Fiat identity design doc (2026-10-20) \xB7 Contract changes",
2139
+ stateKey: "FUN_AUTH",
2140
+ notes: ["verify and resend carry the same verificationRef; resend is usable once resendAvailableAtMs has passed."]
2141
+ },
2142
+ {
2143
+ id: "fun-auth-03-verified",
2144
+ file: "fun-auth-03-verified.json",
2145
+ source: "IDENTITY_DOC",
2146
+ docRef: "Fiat identity design doc (2026-10-20) \xB7 Contract changes",
2147
+ stateKey: "FUN_AUTH",
2148
+ notes: [
2149
+ "A Fun-run login: the envelope carries the Fun session and no transitions. The SDK then starts the flow at QUOTE with accessToken as Bearer.",
2150
+ "accessToken and refreshHandle are placeholders."
2151
+ ]
2152
+ },
2010
2153
  {
2011
2154
  id: "screen-03-kyc-input-required",
2012
2155
  file: "screen-03-kyc-input-required.json",
@@ -2197,12 +2340,7 @@ var FIXTURES = [
2197
2340
  ]
2198
2341
  }
2199
2342
  ];
2200
- var FIXTURE_COVERAGE_GAPS = [
2201
- {
2202
- stateKey: "FUN_AUTH",
2203
- reason: "No step response 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."
2204
- }
2205
- ];
2343
+ var FIXTURE_COVERAGE_GAPS = [];
2206
2344
  var fixtureMeta = (id) => {
2207
2345
  const meta = FIXTURES.find((f) => f.id === id);
2208
2346
  if (!meta) throw new Error(`unknown fixture: ${id}`);
@@ -2565,7 +2703,6 @@ var MoonPayFaultSchema = $fault;
2565
2703
  var $errorBody = obj2({ ...$faultFields, errorCode: $nonEmpty, errorMsg: z2.string(), reqId: z2.string().optional() });
2566
2704
  var MoonPayErrorBodySchema = $errorBody;
2567
2705
  export {
2568
- AuthChallengeSchema,
2569
2706
  BlockedReasonSchema,
2570
2707
  BlockedStateSchema,
2571
2708
  COUNTRY_NAMES,
@@ -2583,10 +2720,16 @@ export {
2583
2720
  FIELD_SPEC_TYPES,
2584
2721
  FIXTURES,
2585
2722
  FIXTURE_COVERAGE_GAPS,
2723
+ FUN_AUTH_ERROR_CODES,
2586
2724
  FUN_KYC_CONSENT_DOCUMENTS,
2587
2725
  FailureReasonSchema,
2588
2726
  FeeLineSchema,
2589
2727
  FiatAmountSchema,
2728
+ FiatAuthRefreshRequestSchema,
2729
+ FiatAuthRefreshResponseSchema,
2730
+ FiatAuthRevokeRequestSchema,
2731
+ FiatAuthStartRequestSchema,
2732
+ FiatAuthVerifyRequestSchema,
2590
2733
  FiatCurrencyCode,
2591
2734
  FiatEndpointSchema,
2592
2735
  FiatGeoSchema,
@@ -2598,6 +2741,7 @@ export {
2598
2741
  FiatRoutingTableErrorBodySchema,
2599
2742
  FiatRoutingTableRequestSchema,
2600
2743
  FiatRoutingTableResponseSchema,
2744
+ FiatSessionSchema,
2601
2745
  FiatStepResponseSchema,
2602
2746
  FiatTermsErrorBodySchema,
2603
2747
  FiatTermsRequestSchema,
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.40.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 { code: 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-4Y22UVT4.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
+ };
566
+ /**
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`.
569
+ */
570
+ export type FiatAuthVerifyRequest = {
571
+ verificationRef: string;
572
+ code: string;
573
+ };
540
574
  /**
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).
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`.
547
578
  */
548
- export type AuthChallenge = Record<string, JsonValue>;
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. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fun-xyz/fiat-contract",
3
- "version": "0.39.0",
3
+ "version": "0.40.0",
4
4
  "description": "Published conformance contract for Fun's headless fiat onramp: FlowState/Transition types, zod schemas, the transition table as data, recorded fixtures, assertion helpers.",
5
5
  "license": "MIT",
6
6
  "repository": {