@tokenflight/fiat-testkit 0.0.1-rc.0

package/LICENSE.md

@@ -0,0 +1,52 @@
+# TokenFlight SDK License
+
+Copyright © 2026 Khalani Labs, Ltd. All rights reserved.
+
+This software and its accompanying documentation (the "Software") are the
+proprietary property of Khalani Labs, Ltd. ("Khalani").
+
+## Grant
+
+Subject to the terms below, Khalani grants you a limited, non-exclusive,
+non-transferable, non-sublicensable, revocable license to install and use the
+Software, in unmodified form only, solely to integrate your applications with
+TokenFlight and Hyperstream services operated by or with the authorization of
+Khalani.
+
+## Restrictions
+
+Except as expressly permitted above or required by applicable law, you may not:
+
+- modify, adapt, translate, or create derivative works of the Software;
+- distribute, sublicense, rent, lease, sell, or otherwise transfer the
+  Software or any copy of it, other than as an unmodified dependency bundled
+  into your application;
+- reverse engineer, decompile, or disassemble the Software, except to the
+  extent such restriction is prohibited by applicable law;
+- remove or alter any proprietary notices in the Software;
+- use the Software to build a product or service that competes with
+  TokenFlight or Hyperstream services.
+
+## Ownership
+
+The Software is licensed, not sold. Khalani retains all right, title, and
+interest in and to the Software, including all intellectual property rights.
+
+## Termination
+
+This license terminates automatically if you breach any of its terms. Upon
+termination you must cease use of the Software and destroy all copies in your
+possession. Khalani may discontinue the Software or this license at any time.
+
+## Disclaimer of Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+## Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL KHALANI
+BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OF OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @tokenflight/fiat-testkit
+
+Build and verify `@tokenflight/fiat` extensions without real provider credentials.
+
+- **`mockProvider(options?)`** — a complete reference `FiatProviderAdapter` (quotes, orders, signed webhooks). Use it as the template for a new provider, or to drive full quote → order → webhook flows in your own tests.
+- **`createMockWebhook(secret, event)`** — signed (or deliberately tampered) webhook payloads for idempotency and verification tests.
+- **`runProviderConformance(adapter, options)`** — checks a provider adapter against the contracts the SDK core relies on: RAW-integer quote amounts, future expiry, typed unsupported-asset rejection, action-matches-capabilities, webhook verify never throws / rejects tampered bodies, and more.
+- **`runStateStoreConformance(makeStore)`** — checks a custom state store's concurrency semantics: version CAS conflicts, nonce replay, webhook dedup, job leases, `listOrders` paging.
+
+```ts
+import { runProviderConformance, failedChecks } from "@tokenflight/fiat-testkit";
+
+const results = await runProviderConformance(myProvider(), { asset: { chainId: 8453, address: "0x…" } });
+expect(failedChecks(results)).toEqual([]);
+```
+
+Framework-free: runners return `CheckResult[]` instead of asserting, so they work under vitest, jest, or a plain script.
+
+© Khalani Labs, Ltd. All rights reserved.

package/dist/check.d.ts

@@ -0,0 +1,15 @@
+export interface CheckResult {
+    name: string;
+    group: "provider" | "store";
+    ok: boolean;
+    /** True when the check could not run (missing optional method / fixture). Counts as ok. */
+    skipped?: boolean;
+    detail?: string;
+}
+export declare function runCheck(name: string, group: CheckResult["group"], fn: () => Promise<string | {
+    skip: string;
+} | void>): Promise<CheckResult>;
+export declare function checkAssert(condition: unknown, message: string): asserts condition;
+/** Convenience for test runners: the failed checks (skips count as passing). */
+export declare function failedChecks(results: CheckResult[]): CheckResult[];
+//# sourceMappingURL=check.d.ts.map

package/dist/check.js

@@ -0,0 +1,33 @@
+//#region src/check.ts
+async function e(e, t, n) {
+	try {
+		let r = await n();
+		return r && typeof r == "object" && "skip" in r ? {
+			name: e,
+			group: t,
+			ok: !0,
+			skipped: !0,
+			detail: r.skip
+		} : {
+			name: e,
+			group: t,
+			ok: !0,
+			...typeof r == "string" ? { detail: r } : {}
+		};
+	} catch (n) {
+		return {
+			name: e,
+			group: t,
+			ok: !1,
+			detail: n instanceof Error ? n.message : String(n)
+		};
+	}
+}
+function t(e, t) {
+	if (!e) throw Error(t);
+}
+function n(e) {
+	return e.filter((e) => !e.ok);
+}
+//#endregion
+export { t as checkAssert, n as failedChecks, e as runCheck };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { mockProvider, createMockWebhook, type MockProviderOptions } from './mock-provider.js';
+export { runProviderConformance, type ProviderConformanceOptions, type WebhookSample } from './provider-conformance.js';
+export { runStateStoreConformance, buildTestOrder, type StoreConformanceOptions } from './store-conformance.js';
+export { checkAssert, failedChecks, runCheck, type CheckResult } from './check.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+import { createMockWebhook as e, mockProvider as t } from "./mock-provider.js";
+import { checkAssert as n, failedChecks as r, runCheck as i } from "./check.js";
+import { runProviderConformance as a } from "./provider-conformance.js";
+import { buildTestOrder as o, runStateStoreConformance as s } from "./store-conformance.js";
+export { o as buildTestOrder, n as checkAssert, e as createMockWebhook, r as failedChecks, t as mockProvider, i as runCheck, a as runProviderConformance, s as runStateStoreConformance };

package/dist/mock-provider.d.ts

@@ -0,0 +1,37 @@
+import { FiatAssetRef, FiatProviderAdapter } from '@tokenflight/fiat';
+export interface MockProviderOptions {
+    /** Provider id (default "mock") — lets a test register several distinct mock providers. */
+    id?: string;
+    /** Human-facing display name; unset exercises the SDK's id fallback. */
+    displayName?: string;
+    webhookSecret?: string;
+    usdPerToken?: number;
+    jumpOnlyAssets?: FiatAssetRef[];
+    /** Assets the provider rejects outright with ProviderUnsupportedAssetError. */
+    unsupportedAssets?: FiatAssetRef[];
+    decimals?: number;
+    widgetOrigin?: string;
+    settles?: boolean;
+    /** Widget/session lifetime in seconds (negative = already expired). Default 3600. */
+    widgetExpiresInSeconds?: number;
+    /** Delivery tx hash reported on polled delivered statuses (webhooks carry their own). */
+    transferTxHash?: string;
+    /** Artificial quote latency, for exercising fan-out timeouts. */
+    quoteDelayMs?: number;
+}
+export declare function mockProvider(options?: MockProviderOptions): FiatProviderAdapter;
+export declare function createMockWebhook(secret: string | undefined, body: {
+    partnerOrderId: string;
+    providerOrderId?: string;
+    status: string;
+    eventId?: string;
+    deliveredAmount?: string;
+    providerCryptoAmount?: string;
+    transferTxHash?: string;
+    reason?: string;
+    walletAddress?: string;
+}): Promise<{
+    rawBody: string;
+    headers: Record<string, string>;
+}>;
+//# sourceMappingURL=mock-provider.d.ts.map

package/dist/mock-provider.js

@@ -0,0 +1,171 @@
+import { ProviderUnsupportedAssetError as e, fromRaw as t, isSameAsset as n, toRaw as r } from "@tokenflight/fiat";
+//#region src/mock-provider.ts
+var i = new TextEncoder();
+function a(e) {
+	let t = "";
+	for (let n of e) t += n.toString(16).padStart(2, "0");
+	return t;
+}
+async function o(e, t) {
+	let n = await crypto.subtle.importKey("raw", i.encode(e), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, !1, ["sign"]), r = await crypto.subtle.sign("HMAC", n, i.encode(t));
+	return a(new Uint8Array(r));
+}
+async function s(e) {
+	let t = await crypto.subtle.digest("SHA-256", i.encode(e));
+	return a(new Uint8Array(t));
+}
+function c(e, t) {
+	if (e.length !== t.length) return !1;
+	let n = 0;
+	for (let r = 0; r < e.length; r++) n |= e.charCodeAt(r) ^ t.charCodeAt(r);
+	return n === 0;
+}
+async function l(e, t, n) {
+	return c(await o(e, t), n);
+}
+var u = {
+	PENDING: "pending",
+	PROCESSING: "processing",
+	COMPLETED: "delivered",
+	FAILED: "failed",
+	CANCELLED: "canceled",
+	EXPIRED: "expired",
+	REFUNDED: "refunded"
+};
+function d(i = {}) {
+	let a = i.id ?? "mock", o = i.usdPerToken ?? 1, c = i.decimals ?? 6, d = i.settles ?? !0, f = i.widgetOrigin ?? "https://mock.widget.test", p = i.widgetExpiresInSeconds ?? 3600;
+	function m(e) {
+		return r(e, c);
+	}
+	function h(e) {
+		return t(e, c);
+	}
+	let g = {
+		quoteKinds: ["estimate", "firm"],
+		orderActions: ["wrapper"],
+		supportsWebhook: !0,
+		supportsStatusPolling: !0,
+		supportedFiatCurrencies: ["USD", "EUR"],
+		supportedPaymentMethods: ["credit_debit_card"],
+		supportedAssets: { mode: "dynamic" },
+		requirements: {
+			origin: "optional",
+			endUserIp: "optional"
+		}
+	}, _ = {
+		allowedOrigins: [f],
+		connectSrcDomains: [new URL(f).host],
+		permissionsFeatures: ["payment"]
+	};
+	function v(e, t) {
+		return {
+			providerOrderId: e,
+			...t ? { partnerOrderId: t } : {},
+			state: "delivered",
+			rawStatus: "COMPLETED",
+			...i.transferTxHash ? { transferTxHash: i.transferTxHash } : {}
+		};
+	}
+	return {
+		id: a,
+		...i.displayName ? { display: { name: i.displayName } } : {},
+		getCapabilities: () => Promise.resolve(g),
+		widgetProfile: () => _,
+		canBuyAsset(e) {
+			let t = i.unsupportedAssets?.some((t) => n(t, e)) ?? !1, r = i.jumpOnlyAssets?.some((t) => n(t, e)) ?? !1;
+			return Promise.resolve(!t && !r);
+		},
+		async quote(t) {
+			if (i.unsupportedAssets?.some((e) => n(e, t.asset))) throw new e({
+				provider: a,
+				asset: t.asset
+			});
+			i.quoteDelayMs && await new Promise((e) => setTimeout(e, i.quoteDelayMs));
+			let r, s;
+			if (t.fiatAmount !== void 0) {
+				let e = Number(t.fiatAmount);
+				r = e.toFixed(2), s = m(e / o);
+			} else t.cryptoAmount === void 0 ? (r = "0.00", s = "0") : (r = (h(t.cryptoAmount) * o).toFixed(2), s = t.cryptoAmount);
+			return {
+				provider: a,
+				kind: t.kind,
+				fiatCurrency: t.fiatCurrency,
+				fiatAmount: r,
+				totalFee: "0.00",
+				cryptoAmount: s,
+				asset: t.asset,
+				expiresAt: Math.floor(Date.now() / 1e3) + 300,
+				paymentMethods: [{
+					id: "credit_debit_card",
+					name: "Credit/Debit Card"
+				}],
+				...t.kind === "firm" ? { providerQuoteId: `mockq_${s}` } : {}
+			};
+		},
+		createOrder(e) {
+			let t = `mock_${e.orderId}`, n = `${f}/checkout?order=${encodeURIComponent(e.orderId)}`;
+			return Promise.resolve({
+				action: {
+					type: "wrapper",
+					url: n
+				},
+				widgetUrl: n,
+				allowedProviderOrigins: [f],
+				references: [{
+					provider: a,
+					type: "partner_order_id",
+					value: e.orderId
+				}, ...d ? [{
+					provider: a,
+					type: "order_id",
+					value: t
+				}] : []],
+				expiresAt: Math.floor(Date.now() / 1e3) + p
+			});
+		},
+		getOrderStatus(e) {
+			return Promise.resolve(d ? v(e) : null);
+		},
+		getOrderStatusByPartnerOrderId(e) {
+			return Promise.resolve(d ? v(`mock_${e}`, e) : null);
+		},
+		async verifyWebhook(e) {
+			if (i.webhookSecret) {
+				let t = e.headers["x-mock-signature"];
+				if (!t || !await l(i.webhookSecret, e.rawBody, t)) return null;
+			}
+			let t;
+			try {
+				t = JSON.parse(e.rawBody);
+			} catch {
+				return null;
+			}
+			let n = u[t.status];
+			return n ? {
+				providerOrderId: t.providerOrderId ?? `mock_${t.partnerOrderId}`,
+				partnerOrderId: t.partnerOrderId,
+				state: n,
+				rawStatus: t.status,
+				eventType: `MOCK_${t.status}`,
+				eventId: t.eventId ?? await s(e.rawBody),
+				...t.deliveredAmount === void 0 ? {} : { deliveredAmount: t.deliveredAmount },
+				...t.providerCryptoAmount === void 0 ? {} : { providerCryptoAmount: t.providerCryptoAmount },
+				...t.transferTxHash === void 0 ? {} : { transferTxHash: t.transferTxHash },
+				...t.reason === void 0 ? {} : { reason: t.reason },
+				...t.walletAddress === void 0 ? {} : { walletAddress: t.walletAddress }
+			} : "ignore";
+		}
+	};
+}
+async function f(e, t) {
+	let n = JSON.stringify(t), r = { "content-type": "application/json" };
+	return e && (r["x-mock-signature"] = await o(e, n)), {
+		rawBody: n,
+		headers: r
+	};
+}
+//#endregion
+export { f as createMockWebhook, d as mockProvider };

package/dist/provider-conformance.d.ts

@@ -0,0 +1,28 @@
+import { FiatProviderAdapter, FiatAssetRef, FiatRequestContext, ProviderOrderState } from '@tokenflight/fiat';
+import { CheckResult } from './check.js';
+export interface WebhookSample {
+    rawBody: string;
+    headers: Record<string, string>;
+}
+export interface ProviderConformanceOptions {
+    /** An asset the adapter can price. */
+    supportedAsset: FiatAssetRef;
+    /** Delivery wallet used for quotes/orders. */
+    recipient: string;
+    /** An asset the adapter must reject (skips the rejection check when omitted). */
+    unsupportedAsset?: FiatAssetRef;
+    /** Request context (origin / endUserIp / country) satisfying the adapter's requirements. */
+    request?: FiatRequestContext;
+    fiatCurrency?: string;
+    fiatAmount?: string;
+    /** Set false to skip order-creation checks (e.g. against credentials that create real sessions). */
+    createOrders?: boolean;
+    /** Signed webhook samples: `valid` must parse; `tampered` must be rejected with null. */
+    webhook?: {
+        valid: WebhookSample;
+        expectState?: ProviderOrderState;
+        tampered?: WebhookSample;
+    };
+}
+export declare function runProviderConformance(adapter: FiatProviderAdapter, options: ProviderConformanceOptions): Promise<CheckResult[]>;
+//# sourceMappingURL=provider-conformance.d.ts.map

package/dist/provider-conformance.js

@@ -0,0 +1,128 @@
+import { checkAssert as e, runCheck as t } from "./check.js";
+//#region src/provider-conformance.ts
+var n = /* @__PURE__ */ new Set([
+	"pending",
+	"processing",
+	"delivered",
+	"failed",
+	"canceled",
+	"expired",
+	"refunded"
+]);
+function r(e) {
+	return /^\d+$/.test(e);
+}
+async function i(i, o) {
+	let s = o.request ?? {
+		origin: "https://conformance.test",
+		endUserIp: "192.0.2.1"
+	}, c = {
+		request: s,
+		now: Date.now()
+	}, l = o.fiatCurrency ?? "USD", u = o.fiatAmount ?? "100", d = [], f = async (e, n) => {
+		d.push(await t(e, "provider", n));
+	};
+	await f("capabilities are well-formed", async () => {
+		let t = await i.getCapabilities(c);
+		return e(t.quoteKinds.length > 0, "quoteKinds must be non-empty"), e(t.supportedFiatCurrencies.length > 0, "supportedFiatCurrencies must be non-empty"), e([
+			"static",
+			"dynamic",
+			"hybrid"
+		].includes(t.supportedAssets.mode), `unknown supportedAssets.mode ${t.supportedAssets.mode}`), `kinds=[${t.quoteKinds.join(",")}], assets=${t.supportedAssets.mode}`;
+	}), await f("widget profile origins are absolute", async () => {
+		let t = i.widgetProfile();
+		e(t.allowedOrigins.length > 0, "allowedOrigins must be non-empty");
+		for (let n of t.allowedOrigins) e(new URL(n).origin === n, `allowedOrigins entry "${n}" is not a bare origin`);
+	}), await f("adapter declares display metadata", async () => i.display?.name ? `display.name=${i.display.name}` : { skip: "no display — quotes will fall back to the provider id (recommended: set display.name)" }), await f("canBuyAsset accepts the supported asset", async () => {
+		e(await i.canBuyAsset(o.supportedAsset, c), "canBuyAsset returned false for the declared supported asset");
+	}), await f("fiat-input quote returns RAW base units and a future expiry", async () => {
+		let t = await i.quote({
+			kind: "firm",
+			inputMode: "fiat",
+			fiatCurrency: l,
+			fiatAmount: u,
+			asset: o.supportedAsset,
+			recipient: o.recipient
+		}, c);
+		return e(t.provider === i.id, `quote.provider (${t.provider}) must echo the adapter id (${i.id})`), e(r(t.cryptoAmount), `cryptoAmount "${t.cryptoAmount}" must be RAW base units (base-10 integer string)`), e(BigInt(t.cryptoAmount) > 0n, "cryptoAmount must be positive"), e(!Number.isNaN(Number(t.fiatAmount)), `fiatAmount "${t.fiatAmount}" must be a decimal string`), e(t.expiresAt * 1e3 > c.now, "expiresAt (epoch seconds) must be in the future"), `cryptoAmount=${t.cryptoAmount}`;
+	}), await f("crypto-input quote round-trips RAW base units", async () => {
+		let t = await i.quote({
+			kind: "firm",
+			inputMode: "fiat",
+			fiatCurrency: l,
+			fiatAmount: u,
+			asset: o.supportedAsset,
+			recipient: o.recipient
+		}, c), n = await i.quote({
+			kind: "firm",
+			inputMode: "crypto",
+			fiatCurrency: l,
+			cryptoAmount: t.cryptoAmount,
+			asset: o.supportedAsset,
+			recipient: o.recipient
+		}, c);
+		e(r(n.cryptoAmount), `cryptoAmount "${n.cryptoAmount}" must be RAW base units`), e(!Number.isNaN(Number(n.fiatAmount)), `fiatAmount "${n.fiatAmount}" must be a decimal string`);
+	}), await f("unsupported asset is rejected with a typed error", async () => {
+		if (!o.unsupportedAsset) return { skip: "no unsupportedAsset fixture provided" };
+		try {
+			await i.quote({
+				kind: "firm",
+				inputMode: "fiat",
+				fiatCurrency: l,
+				fiatAmount: u,
+				asset: o.unsupportedAsset,
+				recipient: o.recipient
+			}, c);
+		} catch (t) {
+			let n = t.name ?? "", r = t.code ?? "";
+			e(n === "ProviderUnsupportedAssetError" || r === "UNSUPPORTED_ASSET", `expected ProviderUnsupportedAssetError/UNSUPPORTED_ASSET, got ${n || r || String(t)}`);
+			return;
+		}
+		throw Error("quote for the unsupported asset did not throw");
+	});
+	let p = `tk_order_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`;
+	return o.createOrders === !1 ? d.push({
+		name: "createOrder returns a well-formed action",
+		group: "provider",
+		ok: !0,
+		skipped: !0,
+		detail: "createOrders=false"
+	}) : (await f("createOrder returns a well-formed action", async () => {
+		let t = await i.getCapabilities(c), n = await i.createOrder({
+			orderId: p,
+			inputMode: "fiat",
+			fiatCurrency: l,
+			fiatAmount: u,
+			asset: o.supportedAsset,
+			recipient: o.recipient,
+			referrerDomain: new URL(s.origin ?? "https://conformance.test").host
+		}, c);
+		return e(t.orderActions.includes(n.action.type), `action.type ${n.action.type} is not in capabilities.orderActions`), e(Array.isArray(n.references), "references must be an array"), n.action.type === "wrapper" && e(!!n.widgetUrl, "a wrapper action must carry widgetUrl (the SDK wrapper iframes it)"), n.expiresAt !== void 0 && e(n.expiresAt * 1e3 > c.now, "expiresAt (epoch seconds) must be in the future"), `action=${n.action.type}`;
+	}), await f("getOrderStatusByPartnerOrderId echoes the requested partner id", async () => {
+		let t = await i.getOrderStatusByPartnerOrderId(p, { notOlderThan: new Date(c.now).toISOString() }, c);
+		return t ? (e(t.partnerOrderId === void 0 || t.partnerOrderId === p, "status.partnerOrderId must echo the requested id"), e(n.has(t.state), `unknown provider state ${t.state}`), e(t.providerOrderId.length > 0, "providerOrderId must be non-empty"), `state=${t.state}`) : { skip: "no provider order discoverable yet (acceptable right after creation)" };
+	})), await f("verifyWebhook never throws on garbage and rejects it", async () => {
+		let t = await i.verifyWebhook({
+			rawBody: "not json / not signed",
+			headers: {}
+		}, c);
+		e(t === null || t === "ignore", "garbage body must resolve to null (reject) or 'ignore', not a parsed event");
+	}), await f("verifyWebhook parses a valid signed sample", async () => {
+		if (!o.webhook) return { skip: "no webhook samples provided" };
+		let t = await i.verifyWebhook(o.webhook.valid, c);
+		return e(t !== null, "the valid sample was rejected"), e(t !== "ignore", "the valid sample was ignored"), e(t.providerOrderId.length > 0, "parsed event must carry providerOrderId"), e(n.has(t.state), `unknown provider state ${t.state}`), o.webhook.expectState && e(t.state === o.webhook.expectState, `expected state ${o.webhook.expectState}, got ${t.state}`), `state=${t.state}`;
+	}), await f("verifyWebhook rejects a tampered sample", async () => {
+		if (!o.webhook) return { skip: "no webhook samples provided" };
+		let t = o.webhook.tampered ?? {
+			...o.webhook.valid,
+			rawBody: a(o.webhook.valid.rawBody)
+		};
+		e(await i.verifyWebhook(t, c) === null, "a tampered body must be rejected with null (HTTP 401), not parsed or ignored");
+	}), d;
+}
+function a(e) {
+	let t = Math.floor(e.length / 2), n = e[t] === "0" ? "1" : "0";
+	return e.slice(0, t) + n + e.slice(t + 1);
+}
+//#endregion
+export { i as runProviderConformance };

package/dist/store-conformance.d.ts

@@ -0,0 +1,13 @@
+import { FiatOrderRecord, FiatOrderWidget, FiatStateStore } from '@tokenflight/fiat';
+import { CheckResult } from './check.js';
+export interface StoreConformanceOptions {
+    /** Base timestamp for job scheduling (default Date.now()). */
+    now?: number;
+}
+/** A minimal valid order + widget pair; ids are lexicographically increasing. */
+export declare function buildTestOrder(overrides?: Partial<FiatOrderRecord>): {
+    order: FiatOrderRecord;
+    orderWidget: FiatOrderWidget;
+};
+export declare function runStateStoreConformance(store: FiatStateStore, options?: StoreConformanceOptions): Promise<CheckResult[]>;
+//# sourceMappingURL=store-conformance.d.ts.map

package/dist/store-conformance.js

@@ -0,0 +1,318 @@
+import { checkAssert as e, runCheck as t } from "./check.js";
+import { FiatStateConflictError as n } from "@tokenflight/fiat";
+//#region src/store-conformance.ts
+var r = 0;
+function i(e) {
+	return r += 1, `${e}${String(r).padStart(6, "0")}`;
+}
+function a(e = {}) {
+	let t = e.orderId ?? i("fiat_order_tk"), n = e.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(), r = {
+		orderId: t,
+		version: 0,
+		status: "pending",
+		provider: "mock",
+		swapStrategy: "direct",
+		inputMode: "fiat",
+		fiatCurrency: "USD",
+		fiatAmount: "100.00",
+		outputAsset: {
+			chainId: 8453,
+			address: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
+		},
+		recipient: "0x1111111111111111111111111111111111111111",
+		providerReferences: [{
+			provider: "mock",
+			type: "partner_order_id",
+			value: t
+		}, {
+			provider: "mock",
+			type: "order_id",
+			value: `mock_${t}`
+		}],
+		createdAt: n,
+		updatedAt: n,
+		...e
+	};
+	return {
+		order: r,
+		orderWidget: {
+			orderId: t,
+			provider: r.provider,
+			action: {
+				type: "wrapper",
+				url: `https://host/v1/fiat/widget/${t}`
+			},
+			allowedProviderOrigins: ["https://mock.widget.test"],
+			widgetUrl: `https://mock.widget.test/checkout?order=${t}`,
+			expiresAt: new Date(Date.parse(n) + 36e5).toISOString()
+		}
+	};
+}
+async function o(e, t, n = {}) {
+	let r = a(n);
+	return e.createOrderFromQuote({
+		quoteNonce: t,
+		reservedOrderId: r.order.orderId,
+		build: () => Promise.resolve({
+			...r,
+			jobs: []
+		})
+	});
+}
+async function s(r, s = {}) {
+	let u = s.now ?? Date.now(), d = [], f = async (e, n) => {
+		d.push(await t(e, "store", n));
+	};
+	return await f("createOrderFromQuote persists the order and its widget", async () => {
+		let t = await o(r, i("nonce_"));
+		e(!t.existing, "first creation must report existing=false");
+		let n = await r.getOrder(t.order.orderId);
+		e(n !== null, "getOrder must return the created order"), e(n.orderId === t.order.orderId && n.status === "pending", "persisted order must round-trip core fields"), e((await r.getOrderWidget(t.order.orderId))?.widgetUrl === t.orderWidget.widgetUrl, "getOrderWidget must round-trip the widget");
+	}), await f("a reused quote nonce returns the existing order without re-building", async () => {
+		let t = i("nonce_"), n = await o(r, t), s = !1, c = await r.createOrderFromQuote({
+			quoteNonce: t,
+			reservedOrderId: i("fiat_order_tk"),
+			build: () => (s = !0, Promise.resolve({
+				...a(),
+				jobs: []
+			}))
+		});
+		e(c.existing, "nonce replay must report existing=true"), e(c.order.orderId === n.order.orderId, "nonce replay must return the original order"), e(!s, "nonce replay must not invoke build() (no second provider session)");
+	}), await f("a reused reservedOrderId returns the existing order", async () => {
+		let t = await o(r, i("nonce_")), n = await r.createOrderFromQuote({
+			quoteNonce: i("nonce_"),
+			reservedOrderId: t.order.orderId,
+			build: () => Promise.resolve({
+				...a({ orderId: t.order.orderId }),
+				jobs: []
+			})
+		});
+		e(n.existing, "orderId replay must report existing=true"), e(n.order.orderId === t.order.orderId, "orderId replay must return the original order");
+	}), await f("updateOrder persists a patch and bumps the version", async () => {
+		let { order: t } = await o(r, i("nonce_"));
+		e((await r.updateOrder({
+			orderId: t.orderId,
+			expectedVersion: t.version,
+			next: {
+				...t,
+				status: "completed",
+				outputAmount: "990000",
+				transferTxHash: "0xfill"
+			}
+		})).version !== t.version, "version must change on update");
+		let n = await r.getOrder(t.orderId);
+		e(n?.status === "completed" && n.outputAmount === "990000", "patched fields must persist"), e(n.transferTxHash === "0xfill", "transferTxHash must persist through updateOrder");
+	}), await f("every FiatOrderRecord field round-trips through create, getOrder and updateOrder", async () => {
+		let t = await o(r, i("nonce_"), c), n = await r.getOrder(t.order.orderId);
+		e(n !== null, "getOrder returned null for the created order");
+		let a = l(t.order, n);
+		e(a.length === 0, `create/getOrder dropped or altered: ${a.join(", ")}`);
+		let s = {
+			...n,
+			providerCryptoAmount: "1.010000",
+			requestedCryptoAmount: "990005",
+			providerStatusReason: "kyc_cleared",
+			metadata: {
+				integratorOrderId: "io_2",
+				note: "patched"
+			}
+		}, u = await r.updateOrder({
+			orderId: n.orderId,
+			expectedVersion: n.version,
+			next: s
+		}), d = await r.getOrder(n.orderId);
+		e(d !== null, "getOrder returned null after update");
+		let f = l({
+			...s,
+			version: u.version
+		}, d);
+		e(f.length === 0, `updateOrder dropped or altered: ${f.join(", ")}`);
+	}), await f("updateOrder is a CAS: a stale version throws FiatStateConflictError", async () => {
+		let { order: t } = await o(r, i("nonce_"));
+		await r.updateOrder({
+			orderId: t.orderId,
+			expectedVersion: t.version,
+			next: {
+				...t,
+				status: "processing"
+			}
+		});
+		try {
+			await r.updateOrder({
+				orderId: t.orderId,
+				expectedVersion: t.version,
+				next: {
+					...t,
+					status: "failed"
+				}
+			});
+		} catch (t) {
+			e(t instanceof n || t.code === "STATE_CONFLICT", `expected FiatStateConflictError, got ${String(t)}`);
+			return;
+		}
+		throw Error("stale-version update did not throw");
+	}), await f("findOrderByProviderReference resolves typed references", async () => {
+		let { order: t } = await o(r, i("nonce_"));
+		e((await r.findOrderByProviderReference({
+			provider: "mock",
+			type: "order_id",
+			value: `mock_${t.orderId}`
+		}))?.orderId === t.orderId, "order_id reference must resolve"), e(await r.findOrderByProviderReference({
+			provider: "mock",
+			type: "order_id",
+			value: "mock_does_not_exist"
+		}) === null, "an unknown reference must resolve to null");
+	}), await f("recordWebhookReceipt deduplicates", async () => {
+		let t = i("dedupe_");
+		e((await r.recordWebhookReceipt({
+			dedupeKey: t,
+			provider: "mock",
+			receivedAt: new Date(u).toISOString(),
+			rawBodyHash: "h"
+		})).inserted, "first receipt must insert"), e(!(await r.recordWebhookReceipt({
+			dedupeKey: t,
+			provider: "mock",
+			receivedAt: new Date(u).toISOString(),
+			rawBodyHash: "h"
+		})).inserted, "a replayed receipt must report inserted=false");
+	}), await f("claimDueJobs leases without double-claiming; finishJob(retry) re-arms", async () => {
+		if (!r.enqueueJobs || !r.claimDueJobs || !r.finishJob) return { skip: "store does not implement the cron job methods" };
+		let { order: t } = await o(r, i("nonce_"));
+		await r.enqueueJobs({
+			orderId: t.orderId,
+			jobs: [{
+				kind: "poll_provider_status",
+				runAt: u
+			}]
+		});
+		let n = (await r.claimDueJobs({
+			limit: 10,
+			now: u + 1,
+			leaseSeconds: 60,
+			owner: "tk-a"
+		})).filter((e) => e.orderId === t.orderId);
+		e(n.length === 1, `expected exactly one claim for the order, got ${n.length}`);
+		let a = n[0];
+		e(!(await r.claimDueJobs({
+			limit: 10,
+			now: u + 2,
+			leaseSeconds: 60,
+			owner: "tk-b"
+		})).some((e) => e.jobId === a.jobId), "a leased job must not be claimable within its lease"), await r.finishJob({
+			jobId: a.jobId,
+			outcome: {
+				type: "retry",
+				nextRunAt: u + 1e4,
+				reason: "conformance"
+			}
+		}), e(!(await r.claimDueJobs({
+			limit: 10,
+			now: u + 5e3,
+			leaseSeconds: 60,
+			owner: "tk-c"
+		})).some((e) => e.jobId === a.jobId), "a retried job must not run before nextRunAt");
+		let s = (await r.claimDueJobs({
+			limit: 10,
+			now: u + 11e3,
+			leaseSeconds: 60,
+			owner: "tk-d"
+		})).find((e) => e.jobId === a.jobId);
+		e(!!s, "a retried job must become claimable at nextRunAt"), e(s.attempt === a.attempt + 1, "retry must increment the attempt counter"), await r.finishJob({
+			jobId: a.jobId,
+			outcome: { type: "done" }
+		}), e(!(await r.claimDueJobs({
+			limit: 10,
+			now: u + 12e4,
+			leaseSeconds: 60,
+			owner: "tk-e"
+		})).some((e) => e.jobId === a.jobId), "a done job must never be claimed again");
+	}), await f("an expired lease is stolen by the next claimer", async () => {
+		if (!r.enqueueJobs || !r.claimDueJobs || !r.finishJob) return { skip: "store does not implement the cron job methods" };
+		let { order: t } = await o(r, i("nonce_"));
+		await r.enqueueJobs({
+			orderId: t.orderId,
+			jobs: [{
+				kind: "reconcile_oda",
+				runAt: u
+			}]
+		});
+		let n = (await r.claimDueJobs({
+			kinds: ["reconcile_oda"],
+			limit: 10,
+			now: u + 1,
+			leaseSeconds: 30,
+			owner: "tk-crash"
+		})).find((e) => e.orderId === t.orderId);
+		e(!!n, "the enqueued job must be claimable"), e((await r.claimDueJobs({
+			kinds: ["reconcile_oda"],
+			limit: 10,
+			now: u + 31e3,
+			leaseSeconds: 30,
+			owner: "tk-recover"
+		})).some((e) => e.jobId === n.jobId), "a job whose lease expired (crashed worker) must be claimable again"), await r.finishJob({
+			jobId: n.jobId,
+			outcome: { type: "done" }
+		});
+	}), await f("listOrders pages newest-first with a status filter", async () => {
+		if (!r.listOrders) return { skip: "store does not implement listOrders" };
+		let t = await o(r, i("nonce_")), n = await o(r, i("nonce_"));
+		await r.updateOrder({
+			orderId: n.order.orderId,
+			expectedVersion: n.order.version,
+			next: {
+				...n.order,
+				status: "completed"
+			}
+		});
+		let a = await r.listOrders({ limit: 1 });
+		e(a.orders.length === 1, "limit must bound the page size"), e(a.cursor !== void 0, "a full page must return a cursor"), e(!(await r.listOrders({
+			limit: 100,
+			cursor: a.cursor
+		})).orders.some((e) => e.orderId === a.orders[0].orderId), "the cursor page must not repeat prior rows");
+		let s = await r.listOrders({
+			status: ["completed"],
+			limit: 100
+		});
+		e(s.orders.some((e) => e.orderId === n.order.orderId), "the status filter must include the matching order"), e(!s.orders.some((e) => e.orderId === t.order.orderId), "the status filter must exclude non-matching orders");
+	}), d;
+}
+var c = {
+	refundTo: "0x2222222222222222222222222222222222222222",
+	integratorId: "itg_conformance",
+	tenantId: "tenant_conformance",
+	quotedCryptoAmount: "990001",
+	expectedOutputAmount: "990002",
+	minOutputAmount: "980000",
+	outputAmount: "990003",
+	transferTxHash: "0xffff000000000000000000000000000000000000000000000000000000000001",
+	providerCryptoAmount: "0.990004",
+	requestedCryptoAmount: "990005",
+	hyperstreamQuoteId: "hq_conformance",
+	selectedRouteId: "route_conformance",
+	odaDepositAddress: "0x3333333333333333333333333333333333333333",
+	odaRefundAddress: "0x4444444444444444444444444444444444444444",
+	odaIntentId: "intent_conformance",
+	odaDepositTxHash: "0xffff000000000000000000000000000000000000000000000000000000000002",
+	providerStatusRaw: "PROCESSING",
+	providerStatusReason: "kyc_pending",
+	providerPayload: { conformance: !0 },
+	failure: {
+		reason: "conformance_probe",
+		source: "fiat_provider",
+		message: "not a real failure"
+	},
+	metadata: {
+		integratorOrderId: "io_conformance",
+		note: "full-field fixture"
+	}
+};
+function l(e, t) {
+	let n = /* @__PURE__ */ new Set([...Object.keys(e), ...Object.keys(t)]), r = [];
+	for (let i of n) {
+		let n = JSON.stringify(e[i]), a = JSON.stringify(t[i]);
+		n !== a && r.push(`${i} (expected ${n}, got ${a})`);
+	}
+	return r;
+}
+//#endregion
+export { a as buildTestOrder, s as runStateStoreConformance };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tokenflight/fiat-testkit",
+  "version": "0.0.1-rc.0",
+  "description": "Mock provider and conformance suites for @tokenflight/fiat providers and state stores",
+  "homepage": "https://fiat.hyperstream.dev/docs",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Khalani Labs, Ltd. (https://khalani.network)",
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tokenflight/fiat": "^0.0.1-rc.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260626.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.0",
+    "vite-plugin-dts": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "vite build"
+  }
+}