@fun-xyz/fiat-contract 0.38.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.38.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 });
@@ -1159,7 +1172,8 @@ var $routingTableMethod = obj({
1159
1172
  });
1160
1173
  var $routingTableResponse = obj({
1161
1174
  expiresAt: $isoInstant,
1162
- methods: import_zod.z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once")
1175
+ methods: import_zod.z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once"),
1176
+ feeSubsidy: obj({ subsidized: import_zod.z.boolean() }).optional()
1163
1177
  });
1164
1178
  var FiatRoutingTableResponseSchema = $routingTableResponse;
1165
1179
  var $routingQuoteTermsShape = {
@@ -1232,28 +1246,33 @@ var $fiatGeo = obj({ alpha2: import_zod.z.string().regex(/^[A-Z]{2}$/), region:
1232
1246
  var FiatGeoSchema = $fiatGeo;
1233
1247
  var $nextRequest = import_zod.z.object({ provider: $provider, action: $nonBlank, geo: $fiatGeo, destinationAsset: $destinationAsset.optional() }).catchall(import_zod.z.unknown());
1234
1248
  var FiatNextRequestSchema = $nextRequest;
1235
- var $providerBoundStepResponse = obj({
1236
- state: $providerBoundFlowState,
1237
- 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 = {
1238
1260
  transitions: import_zod.z.array($transition),
1239
- preparedPayment: $preparedPayment.optional(),
1240
- handoff: obj({ provider: $provider }).optional(),
1241
1261
  routingSessionRef: import_zod.z.string().optional(),
1242
1262
  providerAuthToken: obj({
1243
1263
  clientSecret: import_zod.z.string(),
1244
1264
  expiresAt: import_zod.z.string()
1245
1265
  }).optional(),
1246
1266
  orderId: import_zod.z.string().optional(),
1247
- refreshLimits: import_zod.z.literal(true).optional(),
1248
- feeSubsidy: obj({ estimatedFee: $money.optional() }).optional()
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
- if (response.feeSubsidy !== void 0 && "quote" in response.state && response.state.quote?.feeSubsidy !== void 0) {
1251
- context.addIssue({
1252
- code: "custom",
1253
- path: ["feeSubsidy"],
1254
- message: "a priced quote carries quote.feeSubsidy instead"
1255
- });
1256
- }
1257
1276
  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
1258
1277
  context.addIssue({
1259
1278
  code: "custom",
@@ -1284,22 +1303,41 @@ var $providerBoundStepResponse = obj({
1284
1303
  }
1285
1304
  });
1286
1305
  var $blockedStepResponse = obj({
1306
+ ...$stepResponseBase,
1287
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,
1288
1318
  provider: $provider.optional(),
1289
- transitions: import_zod.z.array($transition),
1290
- routingSessionRef: import_zod.z.string().optional(),
1291
- providerAuthToken: obj({
1292
- clientSecret: import_zod.z.string(),
1293
- expiresAt: import_zod.z.string()
1294
- }).optional(),
1295
- orderId: import_zod.z.string().optional(),
1296
- 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
+ });
1297
1335
  });
1298
- var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStepResponse]);
1336
+ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $funAuthStepResponse, $blockedStepResponse]);
1299
1337
  var FiatStepResponseSchema = $stepResponse;
1300
1338
 
1301
1339
  // package.json
1302
- var version = "0.38.0";
1340
+ var version = "0.40.0";
1303
1341
 
1304
1342
  // src/table.ts
1305
1343
  var TABLE_VERSION = version;
@@ -1310,6 +1348,13 @@ var TERMINAL_ORDER_STATUSES = [
1310
1348
  "FAILED",
1311
1349
  "REFUNDED"
1312
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
+ ];
1313
1358
  var KYC_ANY = [
1314
1359
  "KYC/CAPTURE",
1315
1360
  "KYC/INPUT_REQUIRED",
@@ -1344,12 +1389,6 @@ var TRANSITION_TABLE = {
1344
1389
  when: "returning user, session + KYC valid, order-first rail \u2014 the quote screen doubles as review",
1345
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."
1346
1391
  },
1347
- {
1348
- id: "continue",
1349
- mode: "SUBMIT",
1350
- endpoint: "POST /fiat/auth",
1351
- when: "no ambient Fun identity (non-fomo surfaces only)"
1352
- },
1353
1392
  {
1354
1393
  id: "capture",
1355
1394
  mode: "CLIENT_SURFACE",
@@ -1387,12 +1426,31 @@ var TRANSITION_TABLE = {
1387
1426
  key: "FUN_AUTH",
1388
1427
  kind: "FUN_AUTH",
1389
1428
  screens: [],
1390
- docStatus: "UNSPECIFIED",
1391
- 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"],
1392
1446
  terminal: false,
1393
1447
  notes: [
1394
- "TODO(open-decision): shape and transitions owned by the auth spike (contract \xA7Auth & ref binding, item 5).",
1395
- "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."
1396
1454
  ]
1397
1455
  },
1398
1456
  SESSION_AUTH: {
@@ -1755,6 +1813,9 @@ var DOCUMENTED_ENDPOINTS = [
1755
1813
  "GET /fiat/payment-methods",
1756
1814
  "POST /fiat/quote",
1757
1815
  "POST /fiat/auth",
1816
+ "POST /fiat/auth/verify",
1817
+ "POST /fiat/auth/refresh",
1818
+ "POST /fiat/auth/revoke",
1758
1819
  "POST /fiat/payment-session",
1759
1820
  "POST /fiat/session",
1760
1821
  "POST /fiat/session/verify",
@@ -1778,6 +1839,14 @@ var UNOFFERED_ENDPOINTS = [
1778
1839
  endpoint: "GET /fiat/payment-methods",
1779
1840
  reason: "Discovery, called before any flow state exists \u2014 there is no state to hang it off."
1780
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
+ },
1781
1850
  {
1782
1851
  endpoint: "POST /fiat/kyc/document",
1783
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)."
@@ -1798,7 +1867,7 @@ var UNOFFERED_ENDPOINTS = [
1798
1867
  var UNREACHABLE_STATES = [
1799
1868
  {
1800
1869
  stateKey: "FUN_AUTH",
1801
- 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."
1802
1871
  }
1803
1872
  ];
1804
1873
  function unofferedEndpoints() {
@@ -1898,6 +1967,79 @@ var FIXTURE_DATA = {
1898
1967
  "provider": "MOONPAY",
1899
1968
  "transitions": []
1900
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
+ },
1901
2043
  "screen-01-quote": {
1902
2044
  "state": {
1903
2045
  "kind": "QUOTE",
@@ -2725,6 +2867,36 @@ var FIXTURES = [
2725
2867
  screen: 2,
2726
2868
  stateKey: "SESSION_AUTH"
2727
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
+ },
2728
2900
  {
2729
2901
  id: "screen-03-kyc-input-required",
2730
2902
  file: "screen-03-kyc-input-required.json",
@@ -2915,12 +3087,7 @@ var FIXTURES = [
2915
3087
  ]
2916
3088
  }
2917
3089
  ];
2918
- var FIXTURE_COVERAGE_GAPS = [
2919
- {
2920
- stateKey: "FUN_AUTH",
2921
- 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."
2922
- }
2923
- ];
3090
+ var FIXTURE_COVERAGE_GAPS = [];
2924
3091
  var fixtureMeta = (id) => {
2925
3092
  const meta = FIXTURES.find((f) => f.id === id);
2926
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-QVBSAAXU.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 });
@@ -1009,7 +1017,8 @@ var $routingTableMethod = obj({
1009
1017
  });
1010
1018
  var $routingTableResponse = obj({
1011
1019
  expiresAt: $isoInstant,
1012
- methods: z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once")
1020
+ methods: z.array($routingTableMethod).refine((methods) => hasUniqueIds(methods.map((entry) => entry.method)), "each method is listed once"),
1021
+ feeSubsidy: obj({ subsidized: z.boolean() }).optional()
1013
1022
  });
1014
1023
  var FiatRoutingTableResponseSchema = $routingTableResponse;
1015
1024
  var $routingQuoteTermsShape = {
@@ -1082,28 +1091,33 @@ var $fiatGeo = obj({ alpha2: z.string().regex(/^[A-Z]{2}$/), region: $nonBlank.o
1082
1091
  var FiatGeoSchema = $fiatGeo;
1083
1092
  var $nextRequest = z.object({ provider: $provider, action: $nonBlank, geo: $fiatGeo, destinationAsset: $destinationAsset.optional() }).catchall(z.unknown());
1084
1093
  var FiatNextRequestSchema = $nextRequest;
1085
- var $providerBoundStepResponse = obj({
1086
- state: $providerBoundFlowState,
1087
- 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 = {
1088
1105
  transitions: z.array($transition),
1089
- preparedPayment: $preparedPayment.optional(),
1090
- handoff: obj({ provider: $provider }).optional(),
1091
1106
  routingSessionRef: z.string().optional(),
1092
1107
  providerAuthToken: obj({
1093
1108
  clientSecret: z.string(),
1094
1109
  expiresAt: z.string()
1095
1110
  }).optional(),
1096
1111
  orderId: z.string().optional(),
1097
- refreshLimits: z.literal(true).optional(),
1098
- feeSubsidy: obj({ estimatedFee: $money.optional() }).optional()
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
- if (response.feeSubsidy !== void 0 && "quote" in response.state && response.state.quote?.feeSubsidy !== void 0) {
1101
- context.addIssue({
1102
- code: "custom",
1103
- path: ["feeSubsidy"],
1104
- message: "a priced quote carries quote.feeSubsidy instead"
1105
- });
1106
- }
1107
1121
  if (response.preparedPayment !== void 0 && response.preparedPayment.surface.provider !== response.provider) {
1108
1122
  context.addIssue({
1109
1123
  code: "custom",
@@ -1134,18 +1148,37 @@ var $providerBoundStepResponse = obj({
1134
1148
  }
1135
1149
  });
1136
1150
  var $blockedStepResponse = obj({
1151
+ ...$stepResponseBase,
1137
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,
1138
1163
  provider: $provider.optional(),
1139
- transitions: z.array($transition),
1140
- routingSessionRef: z.string().optional(),
1141
- providerAuthToken: obj({
1142
- clientSecret: z.string(),
1143
- expiresAt: z.string()
1144
- }).optional(),
1145
- orderId: z.string().optional(),
1146
- 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
+ });
1147
1180
  });
1148
- var $stepResponse = z.union([$providerBoundStepResponse, $blockedStepResponse]);
1181
+ var $stepResponse = z.union([$providerBoundStepResponse, $funAuthStepResponse, $blockedStepResponse]);
1149
1182
  var FiatStepResponseSchema = $stepResponse;
1150
1183
 
1151
1184
  // src/fixtures/data.ts
@@ -1187,6 +1220,79 @@ var FIXTURE_DATA = {
1187
1220
  "provider": "MOONPAY",
1188
1221
  "transitions": []
1189
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
+ },
1190
1296
  "screen-01-quote": {
1191
1297
  "state": {
1192
1298
  "kind": "QUOTE",
@@ -2014,6 +2120,36 @@ var FIXTURES = [
2014
2120
  screen: 2,
2015
2121
  stateKey: "SESSION_AUTH"
2016
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
+ },
2017
2153
  {
2018
2154
  id: "screen-03-kyc-input-required",
2019
2155
  file: "screen-03-kyc-input-required.json",
@@ -2204,12 +2340,7 @@ var FIXTURES = [
2204
2340
  ]
2205
2341
  }
2206
2342
  ];
2207
- var FIXTURE_COVERAGE_GAPS = [
2208
- {
2209
- stateKey: "FUN_AUTH",
2210
- 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."
2211
- }
2212
- ];
2343
+ var FIXTURE_COVERAGE_GAPS = [];
2213
2344
  var fixtureMeta = (id) => {
2214
2345
  const meta = FIXTURES.find((f) => f.id === id);
2215
2346
  if (!meta) throw new Error(`unknown fixture: ${id}`);
@@ -2572,7 +2703,6 @@ var MoonPayFaultSchema = $fault;
2572
2703
  var $errorBody = obj2({ ...$faultFields, errorCode: $nonEmpty, errorMsg: z2.string(), reqId: z2.string().optional() });
2573
2704
  var MoonPayErrorBodySchema = $errorBody;
2574
2705
  export {
2575
- AuthChallengeSchema,
2576
2706
  BlockedReasonSchema,
2577
2707
  BlockedStateSchema,
2578
2708
  COUNTRY_NAMES,
@@ -2590,10 +2720,16 @@ export {
2590
2720
  FIELD_SPEC_TYPES,
2591
2721
  FIXTURES,
2592
2722
  FIXTURE_COVERAGE_GAPS,
2723
+ FUN_AUTH_ERROR_CODES,
2593
2724
  FUN_KYC_CONSENT_DOCUMENTS,
2594
2725
  FailureReasonSchema,
2595
2726
  FeeLineSchema,
2596
2727
  FiatAmountSchema,
2728
+ FiatAuthRefreshRequestSchema,
2729
+ FiatAuthRefreshResponseSchema,
2730
+ FiatAuthRevokeRequestSchema,
2731
+ FiatAuthStartRequestSchema,
2732
+ FiatAuthVerifyRequestSchema,
2597
2733
  FiatCurrencyCode,
2598
2734
  FiatEndpointSchema,
2599
2735
  FiatGeoSchema,
@@ -2605,6 +2741,7 @@ export {
2605
2741
  FiatRoutingTableErrorBodySchema,
2606
2742
  FiatRoutingTableRequestSchema,
2607
2743
  FiatRoutingTableResponseSchema,
2744
+ FiatSessionSchema,
2608
2745
  FiatStepResponseSchema,
2609
2746
  FiatTermsErrorBodySchema,
2610
2747
  FiatTermsRequestSchema,
package/dist/routing.d.ts CHANGED
@@ -108,6 +108,15 @@ export interface FiatRoutingTableResponse {
108
108
  expiresAt: string;
109
109
  /** In request order, duplicates removed. */
110
110
  methods: RoutingTableMethod[];
111
+ /**
112
+ * Whether this buyer's next order in the table's corridor has its fee reimbursed: show the fee as FREE
113
+ * when `subsidized`, before and after an amount is entered. A priced `Quote.feeSubsidy` is the exact
114
+ * amount and wins. Absent when the backend could not decide: treat it as not subsidized. A prediction:
115
+ * settlement decides again.
116
+ */
117
+ feeSubsidy?: {
118
+ subsidized: boolean;
119
+ };
111
120
  }
112
121
  /** The purchase terms and optional host restriction, independent of the current ordered candidates. */
113
122
  export interface FiatRoutingQuoteTerms {
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.38.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-QVBSAAXU.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.
@@ -162,17 +162,6 @@ export interface Quote {
162
162
  */
163
163
  feeSubsidy?: FiatAmount;
164
164
  }
165
- /**
166
- * The fee is predicted to be reimbursed after settlement: render it as FREE. Settlement decides again.
167
- * Carried before any provider price exists; a priced `Quote` carries `Quote.feeSubsidy` instead.
168
- */
169
- export interface FeeSubsidy {
170
- /**
171
- * The fee being waived, estimated from the provider's published schedule. Absent when the provider
172
- * or the delivered target has no reliable estimate: show FREE without a number, never a guess.
173
- */
174
- estimatedFee?: FiatAmount;
175
- }
176
165
  /** One inclusive amount interval the current routing set can actually serve. */
177
166
  export interface QuoteLimitRange {
178
167
  min: string;
@@ -548,15 +537,56 @@ export interface PreparedPayment {
548
537
  mode: 'CLIENT_SURFACE';
549
538
  }>;
550
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
551
  /**
552
- * TODO(open-decision): shape owned by the auth spike (contract §Auth & ref binding, item 5).
553
- * `FUN_AUTH` never renders in fomo (identity is ambient), so nothing in either doc constrains
554
- * this beyond the key name. Charles's review (2026-08-14) questions whether the kind is needed at
555
- * all, pending the Transak Auth Reliance answer — if reliance lands, provider-side session auth is
556
- * unreachable for fomo users and this kind may go with it. Kept for now: removing a kind is
557
- * cheap, adding one back costs a client release (handshake-gated).
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`.
558
569
  */
559
- export type AuthChallenge = Record<string, JsonValue>;
570
+ export type FiatAuthVerifyRequest = {
571
+ verificationRef: string;
572
+ code: 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
+ };
560
590
  /**
561
591
  * The expected length of a provider's KYC review. `BRIEF`: the client stays on its current screen,
562
592
  * polling, for up to `holdMs` (at most 600000), then shows the in-review screen. `EXTENDED`: the
@@ -587,9 +617,24 @@ export type FlowState =
587
617
  helper?: string;
588
618
  surface?: Surface;
589
619
  error?: FailureReason;
590
- } | {
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
+ | {
591
627
  kind: 'FUN_AUTH';
592
- 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;
593
638
  error?: FailureReason;
594
639
  } | {
595
640
  kind: 'SESSION_AUTH';
@@ -757,8 +802,9 @@ type FiatStepResponseBase = {
757
802
  };
758
803
  /**
759
804
  * Provider is absent only when routing ended before a provider could be selected. A BLOCKED response
760
- * may still name a provider for compatibility with provider-specific terminal decisions; every other
761
- * 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.
762
808
  */
763
809
  export type FiatStepResponse = (FiatStepResponseBase & {
764
810
  state: Extract<FlowState, {
@@ -766,16 +812,20 @@ export type FiatStepResponse = (FiatStepResponseBase & {
766
812
  }>;
767
813
  provider?: FiatProvider;
768
814
  }) | (FiatStepResponseBase & {
769
- state: Exclude<FlowState, {
770
- kind: 'BLOCKED';
815
+ state: Extract<FlowState, {
816
+ kind: 'FUN_AUTH';
771
817
  }>;
772
- provider: FiatProvider;
818
+ provider?: FiatProvider;
773
819
  /**
774
- * Sent only on the response that answers a quote request, before a price: never beside a
775
- * `Quote.feeSubsidy`. Keep it by the `quoteRef` this response's transitions carry; later steps of
776
- * that ref omit it, and a ref with no prediction is not subsidized.
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).
777
822
  */
778
- feeSubsidy?: FeeSubsidy;
823
+ session?: FiatSession;
824
+ }) | (FiatStepResponseBase & {
825
+ state: Exclude<FlowState, {
826
+ kind: 'BLOCKED' | 'FUN_AUTH';
827
+ }>;
828
+ provider: FiatProvider;
779
829
  /** Optional future payment artifact; never one of this response's currently active transitions. */
780
830
  preparedPayment?: PreparedPayment;
781
831
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fun-xyz/fiat-contract",
3
- "version": "0.38.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": {