@fun-xyz/fiat-contract 0.29.0 → 0.30.1
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 +0 -1
- package/dist/{chunk-3SZPKXVL.mjs → chunk-2NZSOZHV.mjs} +0 -1
- package/dist/{chunk-VQTJSULZ.mjs → chunk-3GKD4CGN.mjs} +1 -2
- package/dist/{chunk-XKI5XTUO.mjs → chunk-EFWIJWBC.mjs} +0 -1
- package/dist/{chunk-F4NRKWF5.mjs → chunk-TIEGTTFY.mjs} +0 -1
- package/dist/chunk-WBQAMGXK.mjs +0 -0
- package/dist/codes.d.ts +0 -1
- package/dist/fixtures/data.d.ts +0 -1
- package/dist/fixtures/index.d.ts +0 -1
- package/dist/index.d.ts +0 -1
- package/dist/index.js +13 -5
- package/dist/index.mjs +17 -9
- package/dist/providers/moonpay.d.ts +0 -1
- package/dist/providers/moonpay.js +0 -1
- package/dist/providers/moonpay.mjs +1 -2
- package/dist/providers/moonpay.schemas.d.ts +0 -1
- package/dist/routing.d.ts +0 -1
- package/dist/routing.js +0 -1
- package/dist/routing.mjs +1 -2
- package/dist/schemas.d.ts +2 -2
- package/dist/table.d.ts +0 -1
- package/dist/table.js +1 -2
- package/dist/table.mjs +1 -2
- package/dist/terms.d.ts +0 -1
- package/dist/terms.js +0 -1
- package/dist/terms.mjs +1 -2
- package/dist/types.d.ts +13 -1
- package/dist/types.js +0 -1
- package/dist/types.mjs +1 -2
- package/package.json +2 -4
- package/README.md +0 -653
- package/dist/chunk-KIQOUUEZ.mjs +0 -1
package/dist/assert.d.ts
CHANGED
|
@@ -55,4 +55,3 @@ export interface ValidatedFixture {
|
|
|
55
55
|
export declare function assertFixture(id: string): ValidatedFixture;
|
|
56
56
|
/** Validate every recorded fixture. Throws on the first violation. */
|
|
57
57
|
export declare function assertAllFixtures(): ValidatedFixture[];
|
|
58
|
-
//# sourceMappingURL=assert.d.ts.map
|
|
File without changes
|
package/dist/codes.d.ts
CHANGED
|
@@ -1270,4 +1270,3 @@ export declare const COUNTRY_TO_CURRENCY: { [K in CountryCodeLiteral]: FiatCurre
|
|
|
1270
1270
|
export declare const PAYMENT_METHOD_CATEGORIES: readonly ["card", "apple_pay", "google_pay", "bank_transfer"];
|
|
1271
1271
|
export type PaymentMethodCategory = (typeof PAYMENT_METHOD_CATEGORIES)[number];
|
|
1272
1272
|
export {};
|
|
1273
|
-
//# sourceMappingURL=codes.d.ts.map
|
package/dist/fixtures/data.d.ts
CHANGED
package/dist/fixtures/index.d.ts
CHANGED
package/dist/index.d.ts
CHANGED
|
@@ -15,4 +15,3 @@ export * from './routing';
|
|
|
15
15
|
export * from './providers/moonpay';
|
|
16
16
|
export * from './providers/moonpay.schemas';
|
|
17
17
|
export { FIXTURES, FIXTURE_COVERAGE_GAPS, fixtureMeta, loadFixture, loadFixtures, type FixtureMeta, type FixtureSource, type LoadedFixture, } from './fixtures/index';
|
|
18
|
-
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.js
CHANGED
|
@@ -73,6 +73,7 @@ __export(index_exports, {
|
|
|
73
73
|
KycFieldIdSchema: () => KycFieldIdSchema,
|
|
74
74
|
KycInputRequiredStateSchema: () => KycInputRequiredStateSchema,
|
|
75
75
|
KycNoActionRequiredStateSchema: () => KycNoActionRequiredStateSchema,
|
|
76
|
+
KycReviewDurationSchema: () => KycReviewDurationSchema,
|
|
76
77
|
KycSdkResultReportSchema: () => KycSdkResultReportSchema,
|
|
77
78
|
MOONPAY_ENDPOINTS: () => MOONPAY_ENDPOINTS,
|
|
78
79
|
MoonPayCheckoutSchema: () => MoonPayCheckoutSchema,
|
|
@@ -919,15 +920,23 @@ var $kycInputRequiredState = obj({
|
|
|
919
920
|
error: $failureReason.optional()
|
|
920
921
|
});
|
|
921
922
|
var KycInputRequiredStateSchema = $kycInputRequiredState;
|
|
922
|
-
var $
|
|
923
|
+
var $kycReviewDuration = import_zod.z.discriminatedUnion("duration", [
|
|
924
|
+
obj({ duration: import_zod.z.literal("BRIEF"), holdMs: import_zod.z.number().int().positive().max(6e5) }),
|
|
925
|
+
obj({ duration: import_zod.z.literal("EXTENDED") })
|
|
926
|
+
]);
|
|
927
|
+
var KycReviewDurationSchema = $kycReviewDuration;
|
|
928
|
+
var $kycNoActionRequiredFields = {
|
|
923
929
|
kind: import_zod.z.literal("KYC"),
|
|
924
930
|
phase: import_zod.z.literal("NO_ACTION_REQUIRED"),
|
|
925
931
|
quote: $quote.optional(),
|
|
926
|
-
reason: import_zod.z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
|
|
927
932
|
retryAfter: import_zod.z.string().optional(),
|
|
928
933
|
failureReason: $failureReason.optional(),
|
|
929
934
|
error: $failureReason.optional()
|
|
930
|
-
}
|
|
935
|
+
};
|
|
936
|
+
var $kycNoActionRequiredState = import_zod.z.union([
|
|
937
|
+
obj({ ...$kycNoActionRequiredFields, reason: import_zod.z.literal("IN_REVIEW"), review: $kycReviewDuration.optional() }),
|
|
938
|
+
obj({ ...$kycNoActionRequiredFields, reason: import_zod.z.enum(["ON_HOLD", "REJECTED"]) })
|
|
939
|
+
]);
|
|
931
940
|
var KycNoActionRequiredStateSchema = $kycNoActionRequiredState;
|
|
932
941
|
var $pendingOrderState = obj({
|
|
933
942
|
kind: import_zod.z.literal("PENDING_ORDER"),
|
|
@@ -1233,7 +1242,7 @@ var $stepResponse = import_zod.z.union([$providerBoundStepResponse, $blockedStep
|
|
|
1233
1242
|
var FiatStepResponseSchema = $stepResponse;
|
|
1234
1243
|
|
|
1235
1244
|
// package.json
|
|
1236
|
-
var version = "0.
|
|
1245
|
+
var version = "0.30.1";
|
|
1237
1246
|
|
|
1238
1247
|
// src/table.ts
|
|
1239
1248
|
var TABLE_VERSION = version;
|
|
@@ -2985,4 +2994,3 @@ var $fault = obj2($faultFields);
|
|
|
2985
2994
|
var MoonPayFaultSchema = $fault;
|
|
2986
2995
|
var $errorBody = obj2({ ...$faultFields, errorCode: $nonEmpty, errorMsg: import_zod2.z.string(), reqId: import_zod2.z.string().optional() });
|
|
2987
2996
|
var MoonPayErrorBodySchema = $errorBody;
|
|
2988
|
-
//# sourceMappingURL=index.js.map
|
package/dist/index.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import "./chunk-
|
|
1
|
+
import "./chunk-WBQAMGXK.mjs";
|
|
2
2
|
import {
|
|
3
3
|
DOCUMENTED_ENDPOINTS,
|
|
4
4
|
STATE_KEYS,
|
|
@@ -12,19 +12,19 @@ import {
|
|
|
12
12
|
tableEntry,
|
|
13
13
|
unofferedEndpoints,
|
|
14
14
|
unreachableStates
|
|
15
|
-
} from "./chunk-
|
|
15
|
+
} from "./chunk-3GKD4CGN.mjs";
|
|
16
16
|
import {
|
|
17
17
|
MOONPAY_ENDPOINTS
|
|
18
|
-
} from "./chunk-
|
|
18
|
+
} from "./chunk-TIEGTTFY.mjs";
|
|
19
19
|
import {
|
|
20
20
|
FIAT_TERMS_ENDPOINT,
|
|
21
21
|
FUN_KYC_CONSENT_DOCUMENTS,
|
|
22
22
|
PROVIDER_CHECKOUT_DOCUMENTS,
|
|
23
23
|
PUBLISHED_TERMS_DOCUMENTS
|
|
24
|
-
} from "./chunk-
|
|
24
|
+
} from "./chunk-EFWIJWBC.mjs";
|
|
25
25
|
import {
|
|
26
26
|
ROUTING_ENDPOINTS
|
|
27
|
-
} from "./chunk-
|
|
27
|
+
} from "./chunk-2NZSOZHV.mjs";
|
|
28
28
|
|
|
29
29
|
// src/codes.ts
|
|
30
30
|
var US_STATE_CODES = [
|
|
@@ -782,15 +782,23 @@ var $kycInputRequiredState = obj({
|
|
|
782
782
|
error: $failureReason.optional()
|
|
783
783
|
});
|
|
784
784
|
var KycInputRequiredStateSchema = $kycInputRequiredState;
|
|
785
|
-
var $
|
|
785
|
+
var $kycReviewDuration = z.discriminatedUnion("duration", [
|
|
786
|
+
obj({ duration: z.literal("BRIEF"), holdMs: z.number().int().positive().max(6e5) }),
|
|
787
|
+
obj({ duration: z.literal("EXTENDED") })
|
|
788
|
+
]);
|
|
789
|
+
var KycReviewDurationSchema = $kycReviewDuration;
|
|
790
|
+
var $kycNoActionRequiredFields = {
|
|
786
791
|
kind: z.literal("KYC"),
|
|
787
792
|
phase: z.literal("NO_ACTION_REQUIRED"),
|
|
788
793
|
quote: $quote.optional(),
|
|
789
|
-
reason: z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
|
|
790
794
|
retryAfter: z.string().optional(),
|
|
791
795
|
failureReason: $failureReason.optional(),
|
|
792
796
|
error: $failureReason.optional()
|
|
793
|
-
}
|
|
797
|
+
};
|
|
798
|
+
var $kycNoActionRequiredState = z.union([
|
|
799
|
+
obj({ ...$kycNoActionRequiredFields, reason: z.literal("IN_REVIEW"), review: $kycReviewDuration.optional() }),
|
|
800
|
+
obj({ ...$kycNoActionRequiredFields, reason: z.enum(["ON_HOLD", "REJECTED"]) })
|
|
801
|
+
]);
|
|
794
802
|
var KycNoActionRequiredStateSchema = $kycNoActionRequiredState;
|
|
795
803
|
var $pendingOrderState = obj({
|
|
796
804
|
kind: z.literal("PENDING_ORDER"),
|
|
@@ -2351,6 +2359,7 @@ export {
|
|
|
2351
2359
|
KycFieldIdSchema,
|
|
2352
2360
|
KycInputRequiredStateSchema,
|
|
2353
2361
|
KycNoActionRequiredStateSchema,
|
|
2362
|
+
KycReviewDurationSchema,
|
|
2354
2363
|
KycSdkResultReportSchema,
|
|
2355
2364
|
MOONPAY_ENDPOINTS,
|
|
2356
2365
|
MoonPayCheckoutSchema,
|
|
@@ -2439,4 +2448,3 @@ export {
|
|
|
2439
2448
|
unreachableStates,
|
|
2440
2449
|
walkTable
|
|
2441
2450
|
};
|
|
2442
|
-
//# sourceMappingURL=index.mjs.map
|
package/dist/routing.d.ts
CHANGED
package/dist/routing.js
CHANGED
package/dist/routing.mjs
CHANGED
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, 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, FiatGeo, FiatNextRequest } from './types';
|
|
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, FiatGeo, FiatNextRequest } from './types';
|
|
32
32
|
import type { FiatTermsErrorBody, FiatTermsRequest, FiatTermsResponse, TermsDocument, TermsDocumentAcceptance } from './terms';
|
|
33
33
|
import type { FiatRoutingQuoteErrorBody, FiatRoutingQuoteRequest, FiatRoutingQuoteTerms, FiatRoutingTableErrorBody, FiatRoutingTableQuery, FiatRoutingTableRequest, FiatRoutingTableResponse } from './routing';
|
|
34
34
|
export declare const JsonSchema: z.ZodType<JsonValue>;
|
|
@@ -98,6 +98,7 @@ export declare const FunAuthStateSchema: z.ZodType<State<'FUN_AUTH'>>;
|
|
|
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'>>;
|
|
101
|
+
export declare const KycReviewDurationSchema: z.ZodType<KycReviewDuration>;
|
|
101
102
|
export declare const KycNoActionRequiredStateSchema: z.ZodType<State<'KYC', 'NO_ACTION_REQUIRED'>>;
|
|
102
103
|
export declare const PendingOrderStateSchema: z.ZodType<State<'PENDING_ORDER'>>;
|
|
103
104
|
export declare const BlockedReasonSchema: z.ZodType<BlockedReason>;
|
|
@@ -124,4 +125,3 @@ export declare const FiatGeoSchema: z.ZodType<FiatGeo>;
|
|
|
124
125
|
export declare const FiatNextRequestSchema: z.ZodType<FiatNextRequest>;
|
|
125
126
|
export declare const FiatStepResponseSchema: z.ZodType<FiatStepResponse>;
|
|
126
127
|
export {};
|
|
127
|
-
//# sourceMappingURL=schemas.d.ts.map
|
package/dist/table.d.ts
CHANGED
|
@@ -130,4 +130,3 @@ export declare const tableEntry: (state: FlowState) => TableEntry;
|
|
|
130
130
|
* `ORDER{CREATED}` is terminal when its status is in the entry's `terminalStatuses`.
|
|
131
131
|
*/
|
|
132
132
|
export declare function isTerminal(state: FlowState): boolean;
|
|
133
|
-
//# sourceMappingURL=table.d.ts.map
|
package/dist/table.js
CHANGED
|
@@ -36,7 +36,7 @@ __export(table_exports, {
|
|
|
36
36
|
module.exports = __toCommonJS(table_exports);
|
|
37
37
|
|
|
38
38
|
// package.json
|
|
39
|
-
var version = "0.
|
|
39
|
+
var version = "0.30.1";
|
|
40
40
|
|
|
41
41
|
// src/table.ts
|
|
42
42
|
var TABLE_VERSION = version;
|
|
@@ -536,4 +536,3 @@ function isTerminal(state) {
|
|
|
536
536
|
}
|
|
537
537
|
return entry.terminal;
|
|
538
538
|
}
|
|
539
|
-
//# sourceMappingURL=table.js.map
|
package/dist/table.mjs
CHANGED
|
@@ -11,7 +11,7 @@ import {
|
|
|
11
11
|
tableEntry,
|
|
12
12
|
unofferedEndpoints,
|
|
13
13
|
unreachableStates
|
|
14
|
-
} from "./chunk-
|
|
14
|
+
} from "./chunk-3GKD4CGN.mjs";
|
|
15
15
|
export {
|
|
16
16
|
DOCUMENTED_ENDPOINTS,
|
|
17
17
|
STATE_KEYS,
|
|
@@ -26,4 +26,3 @@ export {
|
|
|
26
26
|
unofferedEndpoints,
|
|
27
27
|
unreachableStates
|
|
28
28
|
};
|
|
29
|
-
//# sourceMappingURL=table.mjs.map
|
package/dist/terms.d.ts
CHANGED
|
@@ -70,4 +70,3 @@ export declare const FUN_KYC_CONSENT_DOCUMENTS: Readonly<Record<FunKycConsentLoc
|
|
|
70
70
|
* backend accepts any entry, so a client that ships an older version can still check out.
|
|
71
71
|
*/
|
|
72
72
|
export declare const PUBLISHED_TERMS_DOCUMENTS: readonly TermsDocument[];
|
|
73
|
-
//# sourceMappingURL=terms.d.ts.map
|
package/dist/terms.js
CHANGED
package/dist/terms.mjs
CHANGED
|
@@ -3,11 +3,10 @@ import {
|
|
|
3
3
|
FUN_KYC_CONSENT_DOCUMENTS,
|
|
4
4
|
PROVIDER_CHECKOUT_DOCUMENTS,
|
|
5
5
|
PUBLISHED_TERMS_DOCUMENTS
|
|
6
|
-
} from "./chunk-
|
|
6
|
+
} from "./chunk-EFWIJWBC.mjs";
|
|
7
7
|
export {
|
|
8
8
|
FIAT_TERMS_ENDPOINT,
|
|
9
9
|
FUN_KYC_CONSENT_DOCUMENTS,
|
|
10
10
|
PROVIDER_CHECKOUT_DOCUMENTS,
|
|
11
11
|
PUBLISHED_TERMS_DOCUMENTS
|
|
12
12
|
};
|
|
13
|
-
//# sourceMappingURL=terms.mjs.map
|
package/dist/types.d.ts
CHANGED
|
@@ -540,6 +540,17 @@ export interface PreparedPayment {
|
|
|
540
540
|
* cheap, adding one back costs a client release (handshake-gated).
|
|
541
541
|
*/
|
|
542
542
|
export type AuthChallenge = Record<string, JsonValue>;
|
|
543
|
+
/**
|
|
544
|
+
* The expected length of a provider's KYC review. `BRIEF`: the client stays on its current screen,
|
|
545
|
+
* polling, for up to `holdMs` (at most 600000), then shows the in-review screen. `EXTENDED`: the
|
|
546
|
+
* client shows the in-review screen at once.
|
|
547
|
+
*/
|
|
548
|
+
export type KycReviewDuration = {
|
|
549
|
+
duration: 'BRIEF';
|
|
550
|
+
holdMs: number;
|
|
551
|
+
} | {
|
|
552
|
+
duration: 'EXTENDED';
|
|
553
|
+
};
|
|
543
554
|
/**
|
|
544
555
|
* The semantic state. Three rules keep this union honest:
|
|
545
556
|
* 1. sub-states are payload discriminants, never new kinds
|
|
@@ -607,6 +618,8 @@ export type FlowState =
|
|
|
607
618
|
*/
|
|
608
619
|
reason: 'IN_REVIEW' | 'ON_HOLD' | 'REJECTED';
|
|
609
620
|
retryAfter?: string;
|
|
621
|
+
/** How long the provider's review is expected to take. Set only with `reason: 'IN_REVIEW'`; absent means EXTENDED. */
|
|
622
|
+
review?: KycReviewDuration;
|
|
610
623
|
/**
|
|
611
624
|
* REJECTED is reserved for an explicit non-retryable outcome and renders in place — it
|
|
612
625
|
* never routes through `ORDER{CREATED, FAILED}`. Correctable outcomes return CAPTURE or
|
|
@@ -744,4 +757,3 @@ export type FiatNextRequest = {
|
|
|
744
757
|
geo: FiatGeo;
|
|
745
758
|
} & Record<string, unknown>;
|
|
746
759
|
export {};
|
|
747
|
-
//# sourceMappingURL=types.d.ts.map
|
package/dist/types.js
CHANGED
package/dist/types.mjs
CHANGED
|
@@ -1,2 +1 @@
|
|
|
1
|
-
import "./chunk-
|
|
2
|
-
//# sourceMappingURL=types.mjs.map
|
|
1
|
+
import "./chunk-WBQAMGXK.mjs";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fun-xyz/fiat-contract",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.30.1",
|
|
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": {
|
|
@@ -56,9 +56,7 @@
|
|
|
56
56
|
"terms.js",
|
|
57
57
|
"terms.d.ts",
|
|
58
58
|
"routing.js",
|
|
59
|
-
"routing.d.ts"
|
|
60
|
-
"README.md",
|
|
61
|
-
"!dist/**/*.map"
|
|
59
|
+
"routing.d.ts"
|
|
62
60
|
],
|
|
63
61
|
"engines": {
|
|
64
62
|
"node": ">=18"
|
package/README.md
DELETED
|
@@ -1,653 +0,0 @@
|
|
|
1
|
-
# fiat-contract
|
|
2
|
-
|
|
3
|
-
The **published contract** between `fun-backend` (emits step responses) and `funkit`/`connect-core`
|
|
4
|
-
(renders them). Both repos test against it; neither owns it.
|
|
5
|
-
|
|
6
|
-
Four things, zero runtime logic beyond validation:
|
|
7
|
-
|
|
8
|
-
| File | What it is |
|
|
9
|
-
| --- | --- |
|
|
10
|
-
| `src/types.ts` | `FlowState` · `Transition` · `FailureReason` · `Surface` · `Instructions` · `FormDescriptor` · `OrderStatus` · `FiatStepResponse` |
|
|
11
|
-
| `src/codes.ts` | Shared country, currency, US subdivision, and payment-method vocabularies |
|
|
12
|
-
| `src/schemas.ts` | zod mirrors of every type — the single runtime validator |
|
|
13
|
-
| `src/table.ts` | the transition table **as data**: per state, its legal transition set, the states any call from it may return, and `terminal: boolean` |
|
|
14
|
-
| `src/assert.ts` + `src/fixtures/` | `assertFiatStepResponse` · `assertLegalEmission` · `assertLegalReturn` · `walkTable` · fixture loader + 18 recorded step responses (inlined as data — no filesystem, so React Native can bundle it) |
|
|
15
|
-
|
|
16
|
-
## Six entry points — production vs test-time
|
|
17
|
-
|
|
18
|
-
| Import | Weight | Contains | Used by |
|
|
19
|
-
| --- | --- | --- | --- |
|
|
20
|
-
| `@fun-xyz/fiat-contract/types` | **0.1 KB** (types erase) | every type; no runtime values | production, both repos |
|
|
21
|
-
| `@fun-xyz/fiat-contract/table` | **13.8 KB**, zero deps | `TRANSITION_TABLE`, `stateKey`, `tableEntry`, `isTerminal`, `walkTable`, `TABLE_VERSION`, `TERMINAL_ORDER_STATUSES`, `DOCUMENTED_ENDPOINTS`, `UNOFFERED_ENDPOINTS`, `UNREACHABLE_STATES`, `unofferedEndpoints`, `unreachableStates` | **production frontend** + backend |
|
|
22
|
-
| `@fun-xyz/fiat-contract/moonpay` | zero deps | the MoonPay flow on `POST /fiat/next`: action requests, next actions, responses, fault types, and `MOONPAY_ENDPOINTS` | **production frontend** (MoonPay adapter) + backend |
|
|
23
|
-
| `@fun-xyz/fiat-contract/terms` | zero deps | the platform terms route: `TermsDocument`, `FiatTermsRequest`, `FiatTermsResponse`, fault types, and `FIAT_TERMS_ENDPOINT` | **production frontend** + backend |
|
|
24
|
-
| `@fun-xyz/fiat-contract/routing` | zero deps | the routing table and routing quote: `FiatRoutingTableQuery`, `FiatRoutingTableResponse`, `FiatRoutingQuoteRequest`, both routes' error bodies, and `ROUTING_ENDPOINTS` | **production frontend** + backend |
|
|
25
|
-
| `@fun-xyz/fiat-contract` | 47.6 KB, needs zod | the above + 77 zod schemas + assertions + 18 fixtures | tests, and backend dev/test guards |
|
|
26
|
-
|
|
27
|
-
`./table` is not a micro-optimisation. Terminality is table data a **shipped** client must read
|
|
28
|
-
(litmus rule 3 — clients never infer it), and Metro has no cross-module tree-shaking on by default,
|
|
29
|
-
so importing `isTerminal` from the root would ship zod and all 18 fixtures into a React Native
|
|
30
|
-
bundle. Two CI jobs hold that line: `consumer` asserts requiring `./table` never loads zod into the
|
|
31
|
-
process, and `metro` bundles `./table` with real Metro — in **both** package-exports modes, since
|
|
32
|
-
Metro before RN 0.79 ignores `exports` entirely — then greps the emitted bundle for zod, fixtures and
|
|
33
|
-
schemas and executes it.
|
|
34
|
-
|
|
35
|
-
Source of truth: [Fiat Client Contract](https://app.notion.com/p/3b9fc3b2a002815eb270fa4c818268cc)
|
|
36
|
-
(§The fiat step response · §Conformance package · §split `InputSpec` — ACCEPTED) and
|
|
37
|
-
[Fiat Frontend — State Machine & Screen Map](https://app.notion.com/p/3bbfc3b2a00281c994c2cebd17b1d6d3)
|
|
38
|
-
(✅ Decisions · per-screen State details · Event bindings per flow state), plus
|
|
39
|
-
[Fiat KYC — User Flow & API Interfaces](https://app.notion.com/p/3cefc3b2a00281c88e7fe771f0c64332)
|
|
40
|
-
for quote-bound KYC states and endpoints, and
|
|
41
|
-
[Fiat Routing Engine — Provider Selection, Ranking & Commit](https://app.notion.com/p/3d1fc3b2a00281f2b604c20869ac420a)
|
|
42
|
-
for quote-screen limits, provider auth channels, and blocked reasons.
|
|
43
|
-
Tracking: [Headless Fiat Onramp](https://linear.app/funxyz/project/headless-fiat-onramp-0147f4102399) ·
|
|
44
|
-
this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
|
|
45
|
-
|
|
46
|
-
## The litmus rules
|
|
47
|
-
|
|
48
|
-
1. **Errors are fields, never states.** Every fallible state carries `error?: FailureReason`.
|
|
49
|
-
Stay-on-screen ⇒ an error field. Change-screen ⇒ a different state (session expiry just returns
|
|
50
|
-
a `SESSION_AUTH` step response — there is no error routing table).
|
|
51
|
-
2. **`params` = server literals · `inputs` = collected specs · `expects` = injected surface
|
|
52
|
-
results.** `body = {…params, …collected(inputs), …injected(expects)}`; a key collision across
|
|
53
|
-
the three is a contract violation, not last-write-wins. zod rejects a `FieldSpec` hiding in
|
|
54
|
-
`params`, so the old double-duty bug is unrepresentable.
|
|
55
|
-
3. **Terminality comes from the table.** `terminal` is enumerated per state entry — never inferred
|
|
56
|
-
from `transitions.length`. `KYC ON_HOLD` carries `transitions: []` and is **not** terminal.
|
|
57
|
-
`ORDER{CREATED}` terminality rides `status ∈ TERMINAL_ORDER_STATUSES`, and a terminal status may
|
|
58
|
-
still carry a recovery CTA (`FAILED` + retryable `failureReason`).
|
|
59
|
-
4. **`SUBMIT` is a user-fired request, not a POST.** The harness parses the verb off the endpoint
|
|
60
|
-
string; `GET /fiat/orders/:id` under `SUBMIT` is legal.
|
|
61
|
-
5. **Fixtures stay synthetic.** `q_8f2`, `o_31c`, `eyJ…`, `"…"` — never paste a real session token,
|
|
62
|
-
bank field, or PII value into a fixture. Redaction applies to fixtures too.
|
|
63
|
-
6. **Surface kind names the renderer; provider selects the adapter.** Sumsub capture is
|
|
64
|
-
`{ kind: 'KYC_SDK', provider: 'SUMSUB' }`. It is not `URL_EMBED`: the client mounts an SDK,
|
|
65
|
-
not a URL or iframe.
|
|
66
|
-
7. **Quote-screen bounds are explicit exact-money strings.** `QUOTE.limits` carries the bounding
|
|
67
|
-
minimum/maximum plus the exact `serviceableRanges` when a routing set has gaps; clients do not
|
|
68
|
-
infer capacity from provider metadata or floating point.
|
|
69
|
-
8. **Provider auth is capability-shaped.** SMS uses `SMS_OTP`; provider-owned auth uses
|
|
70
|
-
`PROVIDER_RENDERED` with an optional `AUTH_COMPONENT` surface rather than provider-specific channels.
|
|
71
|
-
9. **KYC SDK refresh is a transition.** `KYC{CAPTURE}` may offer `refresh_sdk_token` to
|
|
72
|
-
`POST /fiat/kyc/sdk-token`; a transition-following client does not invent an auxiliary endpoint call.
|
|
73
|
-
10. **SDK launch is not eligibility authority.** A `KYC_SDK_RESULT` report injects either
|
|
74
|
-
`{outcome: 'COMPLETED'}` or `{outcome: 'FAILED', errorType}`. `errorType` is opaque, and raw
|
|
75
|
-
messages/errors are excluded. The backend must still read the provider's authoritative state.
|
|
76
|
-
11. **Client-executed delivery is current-session-only.** A provider-owned surface may declare a
|
|
77
|
-
`CLIENT_EXECUTED` delivery with `source: 'CURRENT_SESSION_INPUTS'` and a value-free `allowedFieldIds`
|
|
78
|
-
allowlist. The delivery shape cannot request or contain backend-stored KYC values.
|
|
79
|
-
12. **Capability skew is explicit.** `BLOCKED{reason: 'CLIENT_UPGRADE_REQUIRED'}` means every
|
|
80
|
-
otherwise-viable route needs a client capability absent from the handshake. It is not a provider
|
|
81
|
-
decline and should render an upgrade path rather than generic retry copy.
|
|
82
|
-
13. **Providerless is terminal-routing-only.** `FiatStepResponse.provider` may be absent only for
|
|
83
|
-
`BLOCKED`, including `ALL_PROVIDERS_DECLINED` when routing selected no provider. Every other state
|
|
84
|
-
remains provider-bound and requires `provider`; provider-specific blocked responses may keep it.
|
|
85
|
-
14. **Path commitment is not a quote.** A response may carry `routingSessionRef` while pricing is
|
|
86
|
-
legitimately deferred for provider auth or activation. Transitions echo that opaque reference in
|
|
87
|
-
`params`; clients submit it unchanged. `Quote.quoteRef` remains required whenever a real `Quote`
|
|
88
|
-
is present, and PAY must never be exposed without real current economics.
|
|
89
|
-
15. **KYC may precede pricing.** Provider auth or activation may legitimately defer pricing, so a
|
|
90
|
-
KYC state may omit `quote`. A real `Quote` still requires `quoteRef`, and PAY is never quote-less.
|
|
91
|
-
16. **Correction text never decides retry.** A correctable provider rejection returns
|
|
92
|
-
`KYC{CAPTURE}` and may carry `correctionReason` for display. Clients decide that retry is allowed
|
|
93
|
-
from the state and its transitions; provider-authored text is never a branch key.
|
|
94
|
-
17. **Prepared payment is inert until promotion.** `FiatStepResponse.preparedPayment` may warm a
|
|
95
|
-
provider-owned payment surface while auth or KYC continues, but its `CLIENT_SURFACE` transition
|
|
96
|
-
is not active yet. A client exposes it only after a later response makes the same `quoteRef`
|
|
97
|
-
executable; the prepared surface provider must match the response provider.
|
|
98
|
-
|
|
99
|
-
## Provider-owned flows
|
|
100
|
-
|
|
101
|
-
A provider can run its own flow instead of the shared step machine. `POST /fiat/quote` still routes
|
|
102
|
-
and prices. When the request's `handoffs` lists the winning provider, the response carries
|
|
103
|
-
`handoff: { provider }` and no transitions. The client shows that provider's `CHECKOUT` documents
|
|
104
|
-
from `PROVIDER_CHECKOUT_DOCUMENTS`, records them with `POST /fiat/terms` on Continue, and then calls
|
|
105
|
-
`POST /fiat/next`. The schema refuses a handoff on any state but `QUOTE`, a
|
|
106
|
-
handoff to a provider other than the response's own, and a handoff that still offers transitions.
|
|
107
|
-
|
|
108
|
-
**Terms (`./terms`).** Every provider records acceptances through the platform `POST /fiat/terms`
|
|
109
|
-
(`FIAT_TERMS_ENDPOINT`). A `TermsDocument` has an `id`, a `kind`
|
|
110
|
-
(`PROVIDER_TERMS`, `FUN_KYC_COLLECTION`, `PROVIDER_KYC_SHARING`), a `stage` (`CHECKOUT` or
|
|
111
|
-
`KYC`), an opaque `version` and `contentDigest`, and at least one `https` link. `FiatTermsRequest` is
|
|
112
|
-
`{ provider, acceptances: [{ documentId, version, contentDigest, acceptedAt }] }`, each document at
|
|
113
|
-
most once; `FiatTermsResponse` is `{ recorded }`, the recorded document ids. A fault is a
|
|
114
|
-
`FiatTermsErrorBody`: the shared `errorCode`, `errorMsg` and `reqId`, plus `reason` (`STALE_TERMS`,
|
|
115
|
-
`INVALID_REQUEST`, `RATE_LIMITED`, `PROVIDER_UNAVAILABLE`) and `recovery`.
|
|
116
|
-
|
|
117
|
-
The package publishes every document as a constant, so the client and the backend read the same
|
|
118
|
-
text. `PROVIDER_CHECKOUT_DOCUMENTS` maps each provider to its current `CHECKOUT` documents.
|
|
119
|
-
`FUN_KYC_CONSENT_DOCUMENTS` is Fun's KYC consent, one digest per `FunKycConsentLocale`.
|
|
120
|
-
`PUBLISHED_TERMS_DOCUMENTS` is every version and locale ever published. Every published version
|
|
121
|
-
stays valid: the backend refuses only an unknown version, a wrong digest, or an `acceptedAt` older
|
|
122
|
-
than 5 minutes. A repeat of a version the login already holds writes nothing and returns the ids.
|
|
123
|
-
|
|
124
|
-
**Routing table (`./routing`).** `ROUTING_ENDPOINTS.table` (`POST /fiat/routing/table`) takes a
|
|
125
|
-
`FiatRoutingTableRequest` body and answers,
|
|
126
|
-
for each requested method, every amount interval and its providers best first, each with `next`
|
|
127
|
-
(`READY`, `AUTH`, `DECLARATIVE_KYC`, `DOCUMENTARY_KYC`, `PENDING_REVIEW`) and `visibility`. The
|
|
128
|
-
client shows min, max, provider and the Continue label for an amount with no call. A method with no
|
|
129
|
-
interval may carry `unavailableReason`, which is not the step response's `BlockedReason`:
|
|
130
|
-
`USER_LIMIT`, `KYC_REJECTED`, `PROVIDER_OUTAGE`, or `NOT_SERVED` when every provider was ruled out
|
|
131
|
-
for reasons that depend on neither the buyer nor provider health (it does not offer the corridor,
|
|
132
|
-
currency, method or asset, or config has not enabled it). An empty method carries no reason when the
|
|
133
|
-
cause is unknown. Refetch the table at `expiresAt`, on `refreshLimits: true`, and after auth, KYC or
|
|
134
|
-
a `REQUOTE`. The schemas hold the table's invariants: each method once, sorted, non-overlapping
|
|
135
|
-
intervals, at least one provider each and none twice, and a reason only on an empty method.
|
|
136
|
-
|
|
137
|
-
`ROUTING_ENDPOINTS.table` (`POST /fiat/routing/table`) accepts `FiatRoutingTableRequest`:
|
|
138
|
-
`cryptoCurrencyCode`, `chainId`, `country`, optional `region` (required for US), `methods` (array),
|
|
139
|
-
optional `fiatCurrencyCode` (default `USD`), and optional `providers`.
|
|
140
|
-
See [`FiatRoutingTableMoonPayInputs`](src/routing.ts) for MoonPay credential handling.
|
|
141
|
-
Blank tokens, malformed inputs and unknown keys return 400: omit unavailable credentials and
|
|
142
|
-
deploy backend support before sending new provider keys.
|
|
143
|
-
`GET /fiat/routing/table` is deprecated but still works without provider inputs.
|
|
144
|
-
|
|
145
|
-
`ROUTING_ENDPOINTS.quote` (`POST /fiat/routing/quote`) takes the `POST /fiat/quote` body
|
|
146
|
-
(`FiatRoutingQuoteTerms`), plus one of two forms:
|
|
147
|
-
|
|
148
|
-
- `providers`: the interval's providers, best first. The backend prices them in order, falls
|
|
149
|
-
through on the refusals marked "next provider" below, and answers the first that prices or the
|
|
150
|
-
last provider's refusal.
|
|
151
|
-
- `provider`: one provider only. The client falls through itself.
|
|
152
|
-
|
|
153
|
-
Routing quotes may include `routingOverrides: { providers: [...] }` with the host’s full allowlist.
|
|
154
|
-
The selected `provider` or ordered `providers` must be a subset. The server preserves the allowlist
|
|
155
|
-
through later KYC rerouting; the amount-specific candidate list alone does not restrict rediscovery.
|
|
156
|
-
Omitting the field preserves existing behavior. An empty allowlist permits no quote candidate.
|
|
157
|
-
|
|
158
|
-
It answers the same `FiatStepResponse`, whose `provider` names the one that priced. A refusal is a
|
|
159
|
-
`FiatRoutingQuoteErrorBody`, and it decides whether the next provider may still price:
|
|
160
|
-
|
|
161
|
-
| Status | `errorCode` | Then |
|
|
162
|
-
| --- | --- | --- |
|
|
163
|
-
| 404 | `FiatNoRouteError`, `reason` `NO_CANDIDATE`, `PROVIDER_DECLINED`, `PROVIDER_OUTAGE` or `KYC_REJECTED` | next provider |
|
|
164
|
-
| 400 | `FiatNoRouteError`, `reason: USER_LIMIT`, `code: LIMITS_EXCEEDED`, `recovery: REQUOTE` | next provider |
|
|
165
|
-
| 400 | `FiatAmountBelowMinimumError` (`minFiatAmount`) or `FiatAmountAboveMaximumError` (`maxFiatAmount`) | next provider |
|
|
166
|
-
| 400 | `InvalidParameterError`: a bad request, an asset Fun cannot deliver, or no verified email | stop |
|
|
167
|
-
| 401, 5xx | any other: a missing or invalid identity assertion, or a server error | stop |
|
|
168
|
-
|
|
169
|
-
Every fall-through refusal is that provider's alone, because each attempt prices only one provider:
|
|
170
|
-
`KYC_REJECTED` there means that provider refused the buyer's identity, not every provider. With no
|
|
171
|
-
provider left in the interval, refetch the table. The table route refuses with a
|
|
172
|
-
`FiatRoutingTableErrorBody`: a 429 `TooManyRequestsError` with `retryAfterSeconds` when the
|
|
173
|
-
per-login budget is spent, or a 400 or 5xx as above. The quote route has no rate limit of its own.
|
|
174
|
-
|
|
175
|
-
Both routes take geo under the `POST /fiat/quote` rules: a known `CountryCode`, a `UsStateCode`
|
|
176
|
-
region for a US buyer, and an empty `region` or `ip` read as absent. The quote route's `geo` is the
|
|
177
|
-
Fun geo endpoint's response forwarded as is. The request schemas are strict like every schema here,
|
|
178
|
-
so a client sends only the declared keys and no blank strings. `provider` and each `providers`
|
|
179
|
-
entry are one of the five providers the backend routes (`RoutingProvider`), `providers` with no
|
|
180
|
-
duplicates. The quote route is temporary: `POST /fiat/next` replaces it for each provider that
|
|
181
|
-
moves there.
|
|
182
|
-
|
|
183
|
-
**MoonPay (`./moonpay`).** MoonPay runs on the shared `POST /fiat/next` (`MOONPAY_ENDPOINTS.next`).
|
|
184
|
-
Every `/next` body is a `FiatNextRequest`: `provider`, `geo` (a `FiatGeo`, the geo endpoint's
|
|
185
|
-
response), and the provider's own request, which names its `action`. The orchestrator reads
|
|
186
|
-
`provider` and `geo`; the provider's action schema reads the rest. MoonPay's body is a
|
|
187
|
-
`MoonPayNextRequest`, and every MoonPay request also carries the context `checkout` and, after
|
|
188
|
-
`connect`, `credentials` (`customerId`, `accessToken`).
|
|
189
|
-
|
|
190
|
-
Each `MoonPayAction` has one name. A response names the next action in `next` and carries what the
|
|
191
|
-
client needs; the client's request names it in `action` and carries the result:
|
|
192
|
-
|
|
193
|
-
| Action | Next action carries | Request carries | A repeat |
|
|
194
|
-
| --- | --- | --- | --- |
|
|
195
|
-
| `observe` | no next action of its own: the answer is the current next action | nothing | writes nothing |
|
|
196
|
-
| `consent` | `documents` (at least one, unique ids) | `acceptances`, the `POST /fiat/terms` items | writes nothing new |
|
|
197
|
-
| `connect` | `sessionToken`, `quoteInput`, `resetConnection?` (`true` when the device's MoonPay connection is another buyer's) | `customerId`, `accessToken` | rebinds the same customer |
|
|
198
|
-
| `kyc` | `fields`, `fieldErrors?` (each naming a field in `fields`, with `code?` `PHONE_IN_USE` on `PHONE_NUMBER` or `TAX_ID_IN_USE` on `TAX_IDENTIFIER` when another MoonPay customer holds the value) | `credentials`, `values` keyed by `KycFieldId` (no form id) | drops values MoonPay no longer asks for |
|
|
199
|
-
| `wait` | `retryAfterMs` (at most 60 s) | no request: the client sends `observe` after the delay | |
|
|
200
|
-
| `order` | `orderId`, `quoteInput` | `orderId`, `quotedAmount`, `transactionId?` | returns the recorded order |
|
|
201
|
-
|
|
202
|
-
Every response is the next action, `done`, or `refused` (`MoonPayRefused`), and
|
|
203
|
-
`MoonPayResponseFor` maps each request action to its union. `observe`, `consent`, `connect` and `kyc`
|
|
204
|
-
answer a `MoonPayStepResponse`: any `MoonPayNextAction`, or `refused` with `reason` (`NOT_ELIGIBLE`,
|
|
205
|
-
`DOCUMENTS_REQUIRED`, `FINAL_REJECTION`, `CUSTOMER_MISMATCH`) and `recovery: REQUOTE | NONE`.
|
|
206
|
-
|
|
207
|
-
`order` runs after every charge attempt, a failed one too, and answers a `MoonPayOrderResponse`:
|
|
208
|
-
`done` with `order`, the `GET /fiat/orders/:orderId` response; `order` again while MoonPay does not
|
|
209
|
-
list the transaction yet; or `refused` with `reason` (`CUSTOMER_MISMATCH`, `WALLET_MISMATCH`,
|
|
210
|
-
`UNRECORDABLE`) and `recovery: NONE`. `transactionId` is optional because a failed charge may have
|
|
211
|
-
none; without it the backend records the failed charges MoonPay lists for `orderId`. `quotedAmount`
|
|
212
|
-
is the fiat amount the device quote showed. The order records the body's `geo.alpha2` as its country.
|
|
213
|
-
A failed charge answers `done` with the order in `FAILED`, and the client requotes for a new `orderId`.
|
|
214
|
-
|
|
215
|
-
A first-time buyer goes `observe` → `consent` → `connect` → `kyc` → `wait` → `observe` → `order` →
|
|
216
|
-
`done`; a returning buyer `observe` → `connect` → `order` → `done`. Both walks are recorded in
|
|
217
|
-
`test/fixtures/moonpay-next/`.
|
|
218
|
-
|
|
219
|
-
A fault is a 4xx or 5xx with a `MoonPayErrorBody`: the shared `errorCode`, `errorMsg` and `reqId`,
|
|
220
|
-
plus `reason` and `recovery`. The reasons are `SESSION_BUDGET_SPENT`, `RATE_LIMITED`,
|
|
221
|
-
`PROVIDER_UNAVAILABLE` (MoonPay is down), `KYC_PROVIDER_UNAVAILABLE` (Sumsub is down),
|
|
222
|
-
`SERVICE_UNAVAILABLE` (one of Fun's own stores is down) and `INVALID_REQUEST`. The recoveries are
|
|
223
|
-
`RETRY` (send the same request again), `REQUOTE`, or `NONE`. A field error is a `kyc`
|
|
224
|
-
next action, not a fault. The zod schemas (`MoonPay*Schema`, `FiatGeoSchema`, `FiatNextRequestSchema`,
|
|
225
|
-
`TermsDocumentSchema`, `FiatTerms*Schema`) are exported from the root only.
|
|
226
|
-
|
|
227
|
-
## KYC SDK hints, results, and client delivery
|
|
228
|
-
|
|
229
|
-
`KYC_SDK` is a dedicated `Surface` union member. Its optional
|
|
230
|
-
`preferredDocuments.IDENTITY` contains the exact adapter input needed to bias document capture:
|
|
231
|
-
the identity-vendor `idDocType` plus its ISO alpha-3 `country`. The hint changes presentation only;
|
|
232
|
-
it does not establish that the document is accepted or available.
|
|
233
|
-
|
|
234
|
-
When `report.result` is `{type: 'KYC_SDK_RESULT', bodyKey: 'result'}`, the harness injects a
|
|
235
|
-
`KycSdkResultReport` under that body key. Completion means the SDK launch completed, not that KYC passed.
|
|
236
|
-
Failure exposes only the provider's opaque `errorType` (for example `Unauthorized`), never a raw
|
|
237
|
-
error object or message.
|
|
238
|
-
|
|
239
|
-
`surface.delivery` describes a client-side forwarding boundary on a provider-owned surface, not
|
|
240
|
-
transport mechanics. The selected provider adapter may forward only the declared `allowedFieldIds` that the user entered during the
|
|
241
|
-
current mounted session. The schema fixes the source to `CURRENT_SESSION_INPUTS`, requires a unique
|
|
242
|
-
non-empty field allowlist, and contains no values. Provider-specific submission mechanics remain
|
|
243
|
-
adapter-owned and are intentionally unresolved by this provider-neutral contract.
|
|
244
|
-
|
|
245
|
-
“Declarative KYC collection” means the backend sends a `FormDescriptor` listing canonical field
|
|
246
|
-
IDs, input kinds, labels, validation, and select options. The frontend renders that description,
|
|
247
|
-
collects values, and submits them through the transition's single `FORM_VALUES` input; it does not
|
|
248
|
-
hard-code a separate screen or endpoint for source of funds, occupation, purpose, nationality,
|
|
249
|
-
country of birth, employment status, or phone. Field IDs and type-specific properties are closed
|
|
250
|
-
unions, so misspelled IDs and impossible combinations such as `options` on a `TEXT` field fail
|
|
251
|
-
validation.
|
|
252
|
-
|
|
253
|
-
## Versioning — the package version IS the table version
|
|
254
|
-
|
|
255
|
-
`TABLE_VERSION` (exported from `src/table.ts`) is derived from `package.json#version` at build
|
|
256
|
-
time — a version bump is one edit, in package.json, and the two can never drift. A test asserts
|
|
257
|
-
the wiring still resolves to the package version.
|
|
258
|
-
That version rides the capability handshake (`supportedProviders` / `supportedSurfaces` /
|
|
259
|
-
`supportedStepKinds` + table version), which is how BE↔FE skew stays explicit and designed-for:
|
|
260
|
-
the server never routes a flow into a state kind the installed SDK didn't declare.
|
|
261
|
-
|
|
262
|
-
Starting at **0.1.0**. Bump the minor for additive vocabulary (a new field, a new fixture); bump the
|
|
263
|
-
major when an existing shape changes meaning. Until 1.0 the contract is MVP-beta: renames and
|
|
264
|
-
removals also ride a minor, with no deprecated aliases kept — consumers pin and migrate in one step.
|
|
265
|
-
|
|
266
|
-
## How each repo consumes it
|
|
267
|
-
|
|
268
|
-
**`fun-backend`** — adapters compile their provider's real flow into this state machine.
|
|
269
|
-
|
|
270
|
-
```ts
|
|
271
|
-
import { assertFiatStepResponse, assertLegalEmission, walkTable } from '@fun-xyz/fiat-contract';
|
|
272
|
-
|
|
273
|
-
assertLegalEmission(state, transitions); // per emission: adapter conformance
|
|
274
|
-
assertFiatStepResponse(outgoing); // outgoing step-response validation in dev/test
|
|
275
|
-
const owed = walkTable((entry) => entry.allowedTransitions); // what the adapter must emit
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
Its own suites: adapter conformance (fixture-driven + property-generated states), outgoing step-response
|
|
279
|
-
validation, and the scheduled provider-sandbox drift run diffed against `src/fixtures`.
|
|
280
|
-
|
|
281
|
-
**`connect-core`** — the harness obeys `transitions` for sequencing and owns rendering.
|
|
282
|
-
|
|
283
|
-
```ts
|
|
284
|
-
import { FIXTURES, loadFixture, walkTable } from '@fun-xyz/fiat-contract';
|
|
285
|
-
|
|
286
|
-
walkTable((entry) => expect(computePage(entry.key)).toBeDefined()); // exhaustive resolver walk
|
|
287
|
-
FIXTURES.forEach(({ id }) => renderCold(loadFixture(id))); // stale-rule survival
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
Its own suites: exhaustive `computePage` table-walk, fixture-driven cold-render tests, harness units
|
|
291
|
-
(any-state handling, same-state error re-entry retains form values, one-live-response focus gating,
|
|
292
|
-
idempotency-key reuse).
|
|
293
|
-
|
|
294
|
-
## Usage
|
|
295
|
-
|
|
296
|
-
Everything below is compiled against the packed tarball in CI (`scripts/check-readme-examples.sh`),
|
|
297
|
-
so these examples cannot drift from the API.
|
|
298
|
-
|
|
299
|
-
### Production: a backend route handler
|
|
300
|
-
|
|
301
|
-
The backend *builds* step responses, so its production use is entirely compile-time — the types are the
|
|
302
|
-
verification. Runtime assertions stay behind a dev/test guard.
|
|
303
|
-
|
|
304
|
-
```ts
|
|
305
|
-
import type { FlowState, FiatStepResponse, Transition } from '@fun-xyz/fiat-contract/types';
|
|
306
|
-
|
|
307
|
-
export async function createOrder(quoteRef: string): Promise<FiatStepResponse> {
|
|
308
|
-
const state: FlowState = {
|
|
309
|
-
kind: 'PAYMENT',
|
|
310
|
-
phase: 'INSTRUCT',
|
|
311
|
-
instructions: { kind: 'BANK_FIELDS', fields: await beneficiaryFields(), expiresAt },
|
|
312
|
-
};
|
|
313
|
-
|
|
314
|
-
const transitions: Transition[] = [
|
|
315
|
-
{ id: 'confirm_paid', mode: 'SUBMIT', endpoint: `POST /fiat/orders/${orderId}/confirm-payment` },
|
|
316
|
-
// endpoint is a bounded union: `POST /fiat/orders/${string}/confirm-paymnt` is a compile error,
|
|
317
|
-
// and so is any path outside the documented /fiat/* surface
|
|
318
|
-
];
|
|
319
|
-
|
|
320
|
-
if (!isProduction) {
|
|
321
|
-
const { assertLegalEmission } = await import('@fun-xyz/fiat-contract');
|
|
322
|
-
assertLegalEmission(state, transitions); // dev/test only — never on the hot path
|
|
323
|
-
}
|
|
324
|
-
|
|
325
|
-
return { state, provider: 'TRANSAK', transitions };
|
|
326
|
-
}
|
|
327
|
-
```
|
|
328
|
-
|
|
329
|
-
What the types buy at compile time: a state kind that isn't in the union won't type, a transition
|
|
330
|
-
mode/shape mismatch won't type, and — since `FiatEndpoint` is a bounded union — neither will a
|
|
331
|
-
typo'd endpoint. No runtime cost.
|
|
332
|
-
|
|
333
|
-
### Production: a frontend screen
|
|
334
|
-
|
|
335
|
-
The client narrows on the state and reads terminality from the table. Both imports are
|
|
336
|
-
production-safe: types erase, `./table` is 13.8 KB with no zod.
|
|
337
|
-
|
|
338
|
-
```ts
|
|
339
|
-
import { isTerminal, stateKey } from '@fun-xyz/fiat-contract/table';
|
|
340
|
-
import type { FiatStepResponse } from '@fun-xyz/fiat-contract/types';
|
|
341
|
-
|
|
342
|
-
export function FiatScreen({ stepResponse }: { stepResponse: FiatStepResponse }) {
|
|
343
|
-
const page = computePage(stateKey(stepResponse.state), clientLocal); // client owns state → screen
|
|
344
|
-
const done = isTerminal(stepResponse.state); // table data, never inferred
|
|
345
|
-
|
|
346
|
-
if (stepResponse.state.kind === 'PAYMENT' && stepResponse.state.phase === 'INSTRUCT') {
|
|
347
|
-
return render(page, stepResponse.state.instructions); // narrowed: instructions exists here
|
|
348
|
-
}
|
|
349
|
-
if (stepResponse.state.kind === 'ORDER' && stepResponse.state.phase === 'CREATED') {
|
|
350
|
-
return render(page, { status: stepResponse.state.status, done });
|
|
351
|
-
}
|
|
352
|
-
return render(page, stepResponse.state);
|
|
353
|
-
}
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
`isTerminal` is the whole reason `./table` exists as a runtime entry: `KYC ON_HOLD` carries
|
|
357
|
-
`transitions: []` and is **not** terminal, while `ORDER{CREATED, SETTLED}` is — no client may
|
|
358
|
-
re-derive that rule locally.
|
|
359
|
-
|
|
360
|
-
### Production: the transitions loop
|
|
361
|
-
|
|
362
|
-
```ts
|
|
363
|
-
import type { FiatStepResponse, Transition } from '@fun-xyz/fiat-contract/types';
|
|
364
|
-
|
|
365
|
-
function useTransitions(stepResponse: FiatStepResponse) {
|
|
366
|
-
return {
|
|
367
|
-
ctas: stepResponse.transitions.filter((t) => t.mode === 'SUBMIT'), // render buttons
|
|
368
|
-
poll: stepResponse.transitions.find((t) => t.mode === 'AWAIT'), // harness schedules
|
|
369
|
-
surface: stepResponse.transitions.find((t) => t.mode === 'CLIENT_SURFACE'), // harness mounts
|
|
370
|
-
};
|
|
371
|
-
}
|
|
372
|
-
|
|
373
|
-
function bodyFor(t: Transition, collected: Record<string, unknown>, surface?: Record<string, unknown>) {
|
|
374
|
-
if (t.mode === 'SUBMIT') return { ...t.params, ...collected }; // verb parsed from t.endpoint
|
|
375
|
-
if (t.mode === 'CLIENT_SURFACE') {
|
|
376
|
-
const injected = Object.fromEntries((t.report.expects ?? []).map((k) => [k, surface?.[k]]));
|
|
377
|
-
return { ...t.report.params, ...injected };
|
|
378
|
-
}
|
|
379
|
-
return { ...t.poll.params };
|
|
380
|
-
}
|
|
381
|
-
```
|
|
382
|
-
|
|
383
|
-
Screens never inspect the array themselves; they receive `ctas` and bind labels
|
|
384
|
-
(`label(t.id) ?? t.labelFallback` — the contract carries no display copy). A key colliding across
|
|
385
|
-
`params` / `inputs` / `expects` is a contract violation, not last-write-wins.
|
|
386
|
-
|
|
387
|
-
## Testing against it
|
|
388
|
-
|
|
389
|
-
These import from the root, which carries zod. Test-time only.
|
|
390
|
-
|
|
391
|
-
### Validate a step response at the boundary
|
|
392
|
-
|
|
393
|
-
`assertFiatStepResponse` parses and returns a typed step response, or throws `ContractViolation`
|
|
394
|
-
listing every problem. Use it on the way out of `fun-backend` (dev/test) and on the way in to
|
|
395
|
-
`connect-core` tests.
|
|
396
|
-
|
|
397
|
-
```ts
|
|
398
|
-
import { assertFiatStepResponse, ContractViolation } from '@fun-xyz/fiat-contract';
|
|
399
|
-
|
|
400
|
-
try {
|
|
401
|
-
const stepResponse = assertFiatStepResponse(await res.json());
|
|
402
|
-
// ^? FiatStepResponse — state is a narrowable discriminated union from here on
|
|
403
|
-
if (stepResponse.state.kind === 'PAYMENT' && stepResponse.state.phase === 'INSTRUCT') {
|
|
404
|
-
render(stepResponse.state.instructions); // narrowed: instructions exists, quote does not
|
|
405
|
-
}
|
|
406
|
-
} catch (err) {
|
|
407
|
-
if (err instanceof ContractViolation) console.error(err.issues); // ['state.quote: Required', …]
|
|
408
|
-
throw err;
|
|
409
|
-
}
|
|
410
|
-
```
|
|
411
|
-
|
|
412
|
-
### Assert an emission is legal (backend adapter conformance)
|
|
413
|
-
|
|
414
|
-
Shape validity is not sequence validity. `assertLegalEmission` judges `(state, transitions)` against
|
|
415
|
-
the table: is each transition in this state's legal set, does a terminal state carry none, does a
|
|
416
|
-
`CLIENT_SURFACE` transition have a Surface in state, do `params`/`inputs`/`expects` collide.
|
|
417
|
-
|
|
418
|
-
```ts
|
|
419
|
-
import { assertLegalEmission, checkLegalEmission } from '@fun-xyz/fiat-contract';
|
|
420
|
-
|
|
421
|
-
// Throwing form — use in adapter unit tests
|
|
422
|
-
assertLegalEmission(
|
|
423
|
-
{ kind: 'SESSION_AUTH', channel: 'EMAIL_OTP' },
|
|
424
|
-
[{
|
|
425
|
-
id: 'verify',
|
|
426
|
-
mode: 'SUBMIT',
|
|
427
|
-
endpoint: 'POST /fiat/session/verify',
|
|
428
|
-
params: { quoteRef: 'q_8f2' }, // server literal, spread verbatim
|
|
429
|
-
inputs: { code: { type: 'TEXT', length: 6 } }, // spec the client collects
|
|
430
|
-
}],
|
|
431
|
-
);
|
|
432
|
-
|
|
433
|
-
// Non-throwing form — use when you want to report in bulk across many generated states
|
|
434
|
-
const { issues, unjudgeable } = checkLegalEmission(state, transitions);
|
|
435
|
-
if (!unjudgeable && issues.length) report(issues);
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
`unjudgeable` is `true` only for states the docs publish no transition set for (`FUN_AUTH`) — it
|
|
439
|
-
means "cannot judge", never "passed".
|
|
440
|
-
|
|
441
|
-
### Walk the table exhaustively (frontend resolver coverage)
|
|
442
|
-
|
|
443
|
-
The table is data, so a runtime walk proves every state resolves to a screen — stronger than TS
|
|
444
|
-
exhaustiveness alone, because it also fails when a *new* state is added to the contract.
|
|
445
|
-
|
|
446
|
-
```ts
|
|
447
|
-
import { assertFixture, walkTable, isTerminal, TRANSITION_TABLE } from '@fun-xyz/fiat-contract';
|
|
448
|
-
|
|
449
|
-
it('every contract state resolves to a screen', () => {
|
|
450
|
-
walkTable((entry) => {
|
|
451
|
-
expect(computePage(entry.key)).toBeDefined();
|
|
452
|
-
});
|
|
453
|
-
});
|
|
454
|
-
|
|
455
|
-
// Terminality is table data — never `transitions.length === 0`
|
|
456
|
-
isTerminal(assertFixture('screen-10-kyc-on-hold').stepResponse.state); // false: empty, not over
|
|
457
|
-
isTerminal({ kind: 'ORDER', phase: 'CREATED', status: 'SETTLED' }); // true
|
|
458
|
-
isTerminal({ kind: 'ORDER', phase: 'CREATED', status: 'PROCESSING' }); // false
|
|
459
|
-
|
|
460
|
-
TRANSITION_TABLE['PAYMENT/INSTRUCT'].mayReturn; // ['ORDER/CREATED']
|
|
461
|
-
```
|
|
462
|
-
|
|
463
|
-
### Render every fixture cold (stale-rule survival)
|
|
464
|
-
|
|
465
|
-
Any call may return any state, so every screen must render from a cold step response with no
|
|
466
|
-
prior context. The fixtures are the FE doc's own responses, so this is a test against the spec.
|
|
467
|
-
|
|
468
|
-
```ts
|
|
469
|
-
import { FIXTURES, loadFixture, assertFixture } from '@fun-xyz/fiat-contract';
|
|
470
|
-
|
|
471
|
-
FIXTURES.forEach(({ id, stateKey, docRef }) => {
|
|
472
|
-
it(`${id} renders cold (${docRef})`, () => {
|
|
473
|
-
const { stepResponse } = assertFixture(id); // validated + emission-legality checked
|
|
474
|
-
expect(() => renderCold(stepResponse)).not.toThrow();
|
|
475
|
-
expect(computePage(stateKey)).toBeDefined();
|
|
476
|
-
});
|
|
477
|
-
});
|
|
478
|
-
|
|
479
|
-
loadFixture('screen-10-kyc-on-hold'); // raw JSON, fresh deep copy, `unknown` — validate before use
|
|
480
|
-
```
|
|
481
|
-
|
|
482
|
-
### Use a schema directly
|
|
483
|
-
|
|
484
|
-
All 77 schemas are exported when you need to validate a fragment rather than a whole step response.
|
|
485
|
-
They are typed `z.ZodType<T>`, so you get `.parse` / `.safeParse` / `.optional()` — not `.shape` or
|
|
486
|
-
`.extend`, deliberately.
|
|
487
|
-
|
|
488
|
-
```ts
|
|
489
|
-
import { FlowStateSchema, QuoteSchema, TransitionSchema } from '@fun-xyz/fiat-contract';
|
|
490
|
-
|
|
491
|
-
const quote = QuoteSchema.parse(row.quote_json);
|
|
492
|
-
const result = FlowStateSchema.safeParse(input);
|
|
493
|
-
if (!result.success) log(result.error.issues);
|
|
494
|
-
void TransitionSchema;
|
|
495
|
-
```
|
|
496
|
-
|
|
497
|
-
### Check the handshake version
|
|
498
|
-
|
|
499
|
-
```ts
|
|
500
|
-
import { TABLE_VERSION } from '@fun-xyz/fiat-contract';
|
|
501
|
-
|
|
502
|
-
const handshake = {
|
|
503
|
-
supportedProviders: ['TRANSAK'],
|
|
504
|
-
supportedSurfaces: ['PCI_COMPONENT', 'PAY_SHEET'],
|
|
505
|
-
supportedStepKinds: ['QUOTE', 'SESSION_AUTH', 'KYC', 'PAYMENT', 'ORDER', 'BLOCKED'],
|
|
506
|
-
tableVersion: TABLE_VERSION, // the package version IS the table version
|
|
507
|
-
};
|
|
508
|
-
```
|
|
509
|
-
|
|
510
|
-
## Install
|
|
511
|
-
|
|
512
|
-
```bash
|
|
513
|
-
pnpm add -D @fun-xyz/fiat-contract
|
|
514
|
-
```
|
|
515
|
-
|
|
516
|
-
```ts
|
|
517
|
-
import type { FiatStepResponse } from '@fun-xyz/fiat-contract/types'; // production, 0 KB
|
|
518
|
-
import { isTerminal } from '@fun-xyz/fiat-contract/table'; // production, 13.8 KB, no zod
|
|
519
|
-
import { assertFiatStepResponse } from '@fun-xyz/fiat-contract'; // tests only, pulls zod
|
|
520
|
-
```
|
|
521
|
-
|
|
522
|
-
Public npm — no `.npmrc`, no token, no registry config. Releases fire from a `v*` tag
|
|
523
|
-
(`.github/workflows/release.yml`), which refuses to publish when the tag and `package.json` version
|
|
524
|
-
disagree, and no-ops when that version is already published.
|
|
525
|
-
|
|
526
|
-
Sourcemaps are excluded from the tarball (`"!dist/**/*.map"` in `files`) — unlike the funkit SDK
|
|
527
|
-
packages, which publish theirs on purpose. These declarations carry open-decision commentary that has
|
|
528
|
-
no reason to reach consumers. 50.5 kB, 21 files.
|
|
529
|
-
|
|
530
|
-
## How connect-core consumes this
|
|
531
|
-
|
|
532
|
-
connect-core **bundles `./table` and `./types` into its own `dist`** rather than shipping them as
|
|
533
|
-
resolvable dependencies. One line of build config, not a copy of the code: one authored table, pinned
|
|
534
|
-
in connect-core's lockfile, recompiled into its output every build. Copy-pasting the table into
|
|
535
|
-
`connect-core/src` is not this, and would defeat the package.
|
|
536
|
-
|
|
537
|
-
```js
|
|
538
|
-
// funkit/packages/connect-core/build.config.js — inside the externalize plugin
|
|
539
|
-
const BUNDLED_SPECIFIERS = new Set([
|
|
540
|
-
'@fun-xyz/fiat-contract/table',
|
|
541
|
-
'@fun-xyz/fiat-contract/types',
|
|
542
|
-
]);
|
|
543
|
-
build.onResolve({ filter }, (args) =>
|
|
544
|
-
BUNDLED_SPECIFIERS.has(args.path)
|
|
545
|
-
? undefined // let esbuild bundle it in
|
|
546
|
-
: { external: true, path: args.path }, // everything else stays external
|
|
547
|
-
);
|
|
548
|
-
```
|
|
549
|
-
|
|
550
|
-
Why bundle rather than depend:
|
|
551
|
-
|
|
552
|
-
- **Pins the tested pair.** As a dependency, a partner's install resolves the semver range at *their*
|
|
553
|
-
install time, so an SDK tested against table 0.2.1 could run against 0.3.0 in the field. Bundling
|
|
554
|
-
compiles `TABLE_VERSION` into the release, which is what the handshake then reports.
|
|
555
|
-
- **Metro never sees the subpath**, so the package-exports question (§Packaging) cannot reach a
|
|
556
|
-
partner's bundler.
|
|
557
|
-
|
|
558
|
-
Consequences:
|
|
559
|
-
|
|
560
|
-
- The build exception needs its comment, or it gets deleted as dead config. A test in connect-core
|
|
561
|
-
asserts the table inlines and that zod and the fixtures stay out.
|
|
562
|
-
- `connect` / `connect-rn` should import the table *from connect-core*, not bundle their own copy
|
|
563
|
-
(~14 KB apiece).
|
|
564
|
-
- The shipped table version is not readable from a partner's `node_modules` — read the handshake.
|
|
565
|
-
|
|
566
|
-
The root entry stays a plain `devDependency` in both repos: test-only, so it never reaches a published
|
|
567
|
-
artifact.
|
|
568
|
-
|
|
569
|
-
## Packaging
|
|
570
|
-
|
|
571
|
-
Dual CJS + ESM, same shape as `@funkit/fun-relay`, because the two consumers load it differently:
|
|
572
|
-
|
|
573
|
-
| Requirement | Source | How it's met |
|
|
574
|
-
| --- | --- | --- |
|
|
575
|
-
| `require()` must work | `fun-backend/apps/api-server` compiles `module: commonjs` and runs plain node — no bundler | esbuild emits `dist/index.js` (CJS) + `dist/index.mjs` (ESM); `exports` maps `require`/`import`; no `"type": "module"` |
|
|
576
|
-
| Zero Node builtins | `connect-core` is React Native — Metro cannot resolve `node:fs` | fixtures are inlined as generated TS data (`src/fixtures/data.ts`), so nothing touches the filesystem; `platform: browser`, every bare import external |
|
|
577
|
-
| Subpath imports must resolve without `exports` support | Metro only reads `package.json#exports` from RN 0.79 on, and `@funkit/connect-rn` accepts `react-native: >=0.74` | root compat stubs `table.js` / `types.js` / `moonpay.js` / `terms.js` / `routing.js` (+ `.d.ts`) that re-export `dist/`. Without them Metro fails with *"Unable to resolve module"* — verified, not theorised. Resolvers that do read `exports` never see the stubs |
|
|
578
|
-
| Production code must not pull zod or fixtures | `connect-core` ships to React Native, where Metro does not tree-shake unused exports by default | six entry points: `./types` (erased), `./table` (13.8 KB, zero deps), `./moonpay`, `./terms` and `./routing` (zero deps), root (schemas + fixtures, test-time). CI asserts `require('.../table')`, `require('.../moonpay')`, `require('.../terms')` and `require('.../routing')` never load zod |
|
|
579
|
-
| `.d.ts` must not lock a zod major | Both repos run `skipLibCheck: true`, which turns a broken declaration into a silent `any` | every exported schema is annotated `z.ZodType<T>`, so declarations name only `z.ZodType`; the structural drift checks stay module-private |
|
|
580
|
-
|
|
581
|
-
Declarations come from `tsc --emitDeclarationOnly`; esbuild only emits JS. The fixture `.json` files
|
|
582
|
-
remain the verbatim record — `data.ts` is generated from them and CI fails if it drifts.
|
|
583
|
-
|
|
584
|
-
## Scripts
|
|
585
|
-
|
|
586
|
-
```
|
|
587
|
-
npm run typecheck # tsc --noEmit, strict; includes the schema↔type mirror assertions
|
|
588
|
-
npm test # vitest: fixtures, zod round-trip, table integrity, negative asserts
|
|
589
|
-
npm run generate:fixtures # regenerate src/fixtures/data.ts from the .json record
|
|
590
|
-
npm run build # tsc declarations + esbuild dual CJS/ESM into dist/
|
|
591
|
-
npm run check # typecheck + test
|
|
592
|
-
|
|
593
|
-
./scripts/verify-consumer.sh 3.23.8 pnpm # pack, install, require/import, and typecheck a
|
|
594
|
-
# consumer with skipLibCheck OFF — catches packaging
|
|
595
|
-
# faults the in-repo suite structurally cannot
|
|
596
|
-
./scripts/check-readme-examples.sh # compile every ```ts block in this README against
|
|
597
|
-
# the packed package
|
|
598
|
-
./scripts/verify-metro.sh # bundle ./table with real Metro in both
|
|
599
|
-
# package-exports modes; assert no zod/fixtures reach
|
|
600
|
-
# the bundle, and that it executes
|
|
601
|
-
```
|
|
602
|
-
|
|
603
|
-
## Dependencies
|
|
604
|
-
|
|
605
|
-
zod is an **optional peer**, range `^3.22.0 || ^4.0.0`. Only the root entry needs it; `./table` and
|
|
606
|
-
`./types` have no runtime dependency on zod, so an install that never imports the root entry needs no
|
|
607
|
-
zod at all.
|
|
608
|
-
|
|
609
|
-
| Repo | zod | Notes |
|
|
610
|
-
| --- | --- | --- |
|
|
611
|
-
| `funkit` (pnpm 9.4) | **3.23.8** (`apps/fits`, `apps/frog`) | `connect-core` declares it explicitly — required, see below |
|
|
612
|
-
| `fun-backend` (pnpm 10.16) | **3.25.76** | forced tree-wide by `pnpm.overrides` |
|
|
613
|
-
|
|
614
|
-
Neither repo is on zod 4; the `|| ^4.0.0` arm is verified, not required. CI runs the suite and a
|
|
615
|
-
packed-tarball consumer check on 3.22.4, 3.23.8, 3.25.76 and 4.4.3. (zod `3.25.0` exactly is
|
|
616
|
-
unusable — that release ships no `dist/`; 3.25.1+ is fine.)
|
|
617
|
-
|
|
618
|
-
**A consumer importing the root entry must declare zod itself.** The peer being optional means pnpm
|
|
619
|
-
installs none by default, so a `test/**` import of the root entry fails with a missing module — loud,
|
|
620
|
-
and the reason the peer is optional. When it was a required peer, pnpm instead resolved zod 4 and,
|
|
621
|
-
under `dedupe-peer-dependents`, moved funkit's viem onto it, which `abitype`'s `^3 >=3.22.0` peer
|
|
622
|
-
rejects.
|
|
623
|
-
|
|
624
|
-
Declarations never bake in a zod major: every exported schema is annotated `z.ZodType<T>`. Consumers
|
|
625
|
-
get `.parse` / `.safeParse` / `.optional()`, not `.shape` / `.extend` — a contract you validate
|
|
626
|
-
against, not compose from.
|
|
627
|
-
|
|
628
|
-
## Open decisions — encoded, not resolved
|
|
629
|
-
|
|
630
|
-
Every one of these is marked `// TODO(open-decision): <doc ref>` at the site that encodes it.
|
|
631
|
-
The current documented shape is what ships; none of these are settled here.
|
|
632
|
-
|
|
633
|
-
| Open item | How 0.1.0 encodes it |
|
|
634
|
-
| --- | --- |
|
|
635
|
-
| `orderId` placement | Both: optional on `PAYMENT{INSTRUCT}` (FE doc v0) **and** optional beside `state` (contract worked example). One fixture of each. |
|
|
636
|
-
| `PENDING_ORDER` removal | Kind ships, with the removal proposal flagged on the type, the table entry, and the fixture. Screen 12 stays frozen. |
|
|
637
|
-
| `[OQ7]` failure enumeration | The published `FailureReason` taxonomy only. Expired instructions, partial payment, and per-rail cancel eligibility remain unenumerated; KYC rejection is terminal only for an explicit non-retryable outcome. |
|
|
638
|
-
| Pre-order KYC sequencing | KYC states carry their quote; SDK submission reports to `POST /fiat/kyc/capture`; expired SDK credentials refresh through the explicit `POST /fiat/kyc/sdk-token` transition; pending review polls the quote resource. There is no `GET /fiat/kyc`. |
|
|
639
|
-
| Card capture report target | Both topologies are legal in the table (`POST /fiat/orders` for capture-then-order; `POST /fiat/orders/:id/surface-result` otherwise) pending the Transak answer. |
|
|
640
|
-
| Cancel placement | `cancel` is legal on `PAYMENT{INSTRUCT}` and `ORDER{CREATED}`, marked conditional on the placement decision. |
|
|
641
|
-
| `FUN_AUTH` shape | `challenge: Record<string, JsonValue>`; the table entry is `docStatus: 'UNSPECIFIED'`, so `assertLegalEmission` reports it unjudgeable instead of guessing. |
|
|
642
|
-
| `statusHistory` element shape | The documented minimum (`{status}`) — no invented timestamps. |
|
|
643
|
-
| `QR_IMAGE` instruction | In the union per §The fiat step response, flagged against OQ1's "deliberately not pre-declared". |
|
|
644
|
-
|
|
645
|
-
`FUN_AUTH` is the only fixture gap declared in `FIXTURE_COVERAGE_GAPS`; its shape remains owned by the auth spike. Every other state has a recorded step response.
|
|
646
|
-
|
|
647
|
-
## Not decided here — needs a human
|
|
648
|
-
|
|
649
|
-
- **Whether `PENDING_ORDER` ships in the types** or waits for the removal decision. It ships
|
|
650
|
-
today (flagged everywhere) so the current server shape validates.
|
|
651
|
-
- **Repo hosting / org placement.** The docs recommend a standalone repo (option B) or `fun-backend`
|
|
652
|
-
(option C) — explicitly **not** funkit. Backend sign-off is pending; this repo is standalone,
|
|
653
|
-
which is reversible either way.
|
package/dist/chunk-KIQOUUEZ.mjs
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
//# sourceMappingURL=chunk-KIQOUUEZ.mjs.map
|