@tokenflight/fiat-client 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,32 @@
+# @tokenflight/fiat-client
+
+Zero-dependency typed client for the standard [`@tokenflight/fiat`](https://www.npmjs.com/package/@tokenflight/fiat) HTTP contract. Works in browsers, workers, and Node ≥ 18; every import from `@tokenflight/fiat` is type-only, so the runtime bundle is a few KB with no dependencies.
+
+```ts
+import { createFiatClient } from "@tokenflight/fiat-client";
+
+const fiat = createFiatClient(); // defaults to https://fiat.hyperstream.dev/v1/fiat
+
+const { quotes, errors } = await fiat.quotes({
+  fiatCurrency: "USD",
+  fiatAmount: "100.00",
+  outputAsset: { chainId: 8453, address: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" },
+  recipient: "0xYourWallet…",
+});
+
+// Pre-open the popup in the click handler's synchronous stack (popup blockers
+// reject window.open after an await), then navigate it once the order lands.
+const popup = window.open("about:blank", "_blank", "popup,width=480,height=720");
+const order = await fiat.createOrder({ quoteId: quotes[0].quoteId });
+if (order.action.type === "wrapper" && popup) popup.location = order.action.url;
+else popup?.close();
+
+const finished = await fiat.waitForOrder(order.orderId, { onOrder: (o) => render(o.progress) });
+console.log(finished.status, finished.transferTxHash);
+```
+
+- `quotesStream()` — async-iterate provider quotes as they settle (NDJSON), so one slow provider never delays a comparison UI.
+- Errors are always a typed `FiatClientError` (`code`, `retryable`, `status`); transport failures map to `NETWORK_ERROR` / `TIMEOUT` / `INVALID_RESPONSE`.
+- Point it at a self-hosted deployment with `createFiatClient({ baseUrl, basePath })`.
+
+© Khalani Labs, Ltd. All rights reserved.

package/dist/client.d.ts

@@ -0,0 +1,52 @@
+import { FiatConfigResponse, FiatCreateOrderRequest, FiatCreateOrderResponse, FiatOrderStatus, FiatQuoteRequest, FiatQuotesResponse, OrderView, QuoteProviderError, QuoteStreamEvent } from '@tokenflight/fiat';
+export declare const DEFAULT_FIAT_BASE_URL = "https://fiat.hyperstream.dev";
+export declare const DEFAULT_FIAT_BASE_PATH = "/v1/fiat";
+/** Statuses after which an order can never change again — stop polling on these. */
+export declare const TERMINAL_FIAT_ORDER_STATUSES: ReadonlySet<FiatOrderStatus>;
+export interface FiatClientOptions {
+    /** Service origin, e.g. `https://fiat.hyperstream.dev` (the default). */
+    baseUrl?: string;
+    /** API prefix under the origin. Must match the server's `basePath`. Default `/v1/fiat`. */
+    basePath?: string;
+    /** Extra headers merged into every request (e.g. `{ authorization: "Bearer …" }`). */
+    headers?: Record<string, string>;
+    /** Custom fetch (tests, SSR, service bindings). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request time budget in ms; elapses → `TIMEOUT`. Default 30 000, `0` disables. */
+    timeoutMs?: number;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+export interface WaitForOrderOptions extends RequestOptions {
+    /** Delay between polls. Default 2 500 ms. */
+    pollIntervalMs?: number;
+    /** Overall budget before giving up with `TIMEOUT`. Default 15 min, `0` disables. */
+    timeoutMs?: number;
+    /** Called after every poll — drive UI progress from this. */
+    onOrder?: (order: OrderView) => void;
+}
+/** `quotes()` normalized result: `errors` is always an array (the wire omits it when empty). */
+export interface FiatQuotesResult {
+    quotes: FiatQuotesResponse["quotes"];
+    errors: QuoteProviderError[];
+}
+export interface FiatClient {
+    /** GET /config — providers (display + capabilities), jump support, enabled features. */
+    config(opts?: RequestOptions): Promise<FiatConfigResponse>;
+    /** POST /quote — one quote per configured provider (pin `provider` for exactly one).
+     *  Providers that could not price the request land in `errors`, never as a throw. */
+    quotes(request: FiatQuoteRequest, opts?: RequestOptions): Promise<FiatQuotesResult>;
+    /** POST /quote?mode=stream — yields each provider's `{quote}` / `{error}` as it settles,
+     *  so one slow provider never delays the rest of a comparison UI. */
+    quotesStream(request: FiatQuoteRequest, opts?: RequestOptions): AsyncGenerator<QuoteStreamEvent>;
+    /** POST /order — commit to a quote. `action` says what the frontend does next
+     *  (`wrapper` → open the URL as a popup). */
+    createOrder(request: FiatCreateOrderRequest, opts?: RequestOptions): Promise<FiatCreateOrderResponse>;
+    /** GET /order/:id — canonical order projection (includes `transferTxHash` once settled). */
+    getOrder(orderId: string, opts?: RequestOptions): Promise<OrderView>;
+    /** Polls `getOrder` until a terminal status and returns the final view. */
+    waitForOrder(orderId: string, opts?: WaitForOrderOptions): Promise<OrderView>;
+}
+export declare function createFiatClient(options?: FiatClientOptions): FiatClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,197 @@
+import { FiatClientError as e } from "./errors.js";
+//#region src/client.ts
+var t = "https://fiat.hyperstream.dev", n = "/v1/fiat", r = /* @__PURE__ */ new Set([
+	"completed",
+	"failed",
+	"canceled",
+	"expired"
+]);
+function i(t = {}) {
+	let n = a(t.baseUrl ?? "https://fiat.hyperstream.dev", t.basePath ?? "/v1/fiat"), i = t.fetch ?? globalThis.fetch.bind(globalThis), l = t.timeoutMs ?? 3e4, h = { ...t.headers };
+	function g(e, t, r, a) {
+		return i(`${n}${t}`, {
+			method: e,
+			headers: {
+				accept: "application/json",
+				...r === void 0 ? {} : { "content-type": "application/json" },
+				...h
+			},
+			...r === void 0 ? {} : { body: JSON.stringify(r) },
+			...a ? { signal: a } : {}
+		});
+	}
+	async function _(t, n, r, i) {
+		let { signal: a, dispose: f } = o(i?.signal, l);
+		try {
+			let i = await g(t, n, r, a);
+			if (!i.ok) throw await s(i, a);
+			try {
+				return await c(i.json(), a);
+			} catch (t) {
+				throw u(t) ? t : new e("INVALID_RESPONSE", "response body is not valid JSON", {
+					status: i.status,
+					cause: t
+				});
+			}
+		} catch (e) {
+			throw d(e, i?.signal);
+		} finally {
+			f();
+		}
+	}
+	let v = {
+		config(e) {
+			return _("GET", "/config", void 0, e);
+		},
+		async quotes(e, t) {
+			let n = await _("POST", "/quote", e, t);
+			return {
+				quotes: n.quotes,
+				errors: n.errors ?? []
+			};
+		},
+		async *quotesStream(t, n) {
+			let { signal: r, dispose: i } = o(n?.signal, l);
+			try {
+				let n = await g("POST", "/quote?mode=stream", t, r);
+				if (!n.ok) throw await s(n, r);
+				if (!n.body) throw new e("INVALID_RESPONSE", "streaming response has no body", { status: n.status });
+				for await (let e of f(n.body, r)) {
+					let t = p(e);
+					t && (yield t);
+				}
+			} catch (e) {
+				throw d(e, n?.signal);
+			} finally {
+				i();
+			}
+		},
+		createOrder(e, t) {
+			return _("POST", "/order", e, t);
+		},
+		getOrder(e, t) {
+			return _("GET", `/order/${encodeURIComponent(e)}`, void 0, t);
+		},
+		async waitForOrder(t, n = {}) {
+			let i = Number.isFinite(n.pollIntervalMs) && n.pollIntervalMs > 0 ? n.pollIntervalMs : 2500, a = Number.isFinite(n.timeoutMs) && n.timeoutMs >= 0 ? n.timeoutMs : 15 * 6e4, o = a > 0 ? Date.now() + a : Infinity;
+			for (;;) {
+				let s = await v.getOrder(t, n.signal ? { signal: n.signal } : {});
+				if (n.onOrder?.(s), s.terminal ?? r.has(s.status)) return s;
+				if (Date.now() + i > o) throw new e("TIMEOUT", `order ${t} did not reach a terminal status within ${a}ms`, { retryable: !0 });
+				await m(i, n.signal);
+			}
+		}
+	};
+	return v;
+}
+function a(e, t) {
+	let n = e;
+	for (; n.endsWith("/");) n = n.slice(0, -1);
+	let r = t;
+	for (; r.endsWith("/");) r = r.slice(0, -1);
+	return r && !r.startsWith("/") && (r = `/${r}`), `${n}${r}`;
+}
+function o(t, n) {
+	if (!Number.isFinite(n) || n <= 0) return t ? {
+		signal: t,
+		dispose: () => {}
+	} : { dispose: () => {} };
+	let r = new AbortController(), i = setTimeout(() => r.abort(new e("TIMEOUT", `request timed out after ${n}ms`, { retryable: !0 })), n), a = () => r.abort(t?.reason);
+	return t && (t.aborted ? a() : t.addEventListener("abort", a, { once: !0 })), {
+		signal: r.signal,
+		dispose: () => {
+			clearTimeout(i), t?.removeEventListener("abort", a);
+		}
+	};
+}
+async function s(t, n) {
+	let r;
+	try {
+		r = await c(t.json(), n);
+	} catch (n) {
+		if (u(n)) throw n;
+		return new e("INVALID_RESPONSE", `HTTP ${t.status} without a JSON error envelope`, { status: t.status });
+	}
+	let i = r?.error;
+	return !i || typeof i.code != "string" || typeof i.message != "string" ? new e("INVALID_RESPONSE", `HTTP ${t.status} without a wire error envelope`, {
+		status: t.status,
+		details: r
+	}) : new e(i.code, i.message, {
+		retryable: i.retryable === !0,
+		status: t.status,
+		...i.details === void 0 ? {} : { details: i.details }
+	});
+}
+function c(e, t) {
+	return t ? t.aborted ? Promise.reject(l(t)) : new Promise((n, r) => {
+		let i = () => r(l(t));
+		t.addEventListener("abort", i, { once: !0 }), e.then((e) => {
+			t.removeEventListener("abort", i), n(e);
+		}, (e) => {
+			t.removeEventListener("abort", i), r(e instanceof Error ? e : Error(String(e)));
+		});
+	}) : e;
+}
+function l(e) {
+	return e.reason instanceof Error ? e.reason : new DOMException("aborted", "AbortError");
+}
+function u(t) {
+	return t instanceof e || t instanceof DOMException && t.name === "AbortError";
+}
+function d(t, n) {
+	return t instanceof e ? t : t instanceof DOMException && t.name === "AbortError" ? n?.aborted ? t : new e("TIMEOUT", "request timed out", {
+		retryable: !0,
+		cause: t
+	}) : t instanceof Error && t.name === "TypeError" ? new e("NETWORK_ERROR", `request failed: ${t.message}`, {
+		retryable: !0,
+		cause: t
+	}) : t;
+}
+async function* f(e, t) {
+	let n = e.getReader(), r = new TextDecoder(), i = "";
+	try {
+		for (;;) {
+			let { done: e, value: a } = await c(n.read(), t);
+			if (e) break;
+			i += r.decode(a, { stream: !0 });
+			let o;
+			for (; (o = i.indexOf("\n")) !== -1;) {
+				let e = i.slice(0, o).trim();
+				i = i.slice(o + 1), e && (yield e);
+			}
+		}
+		let e = (i + r.decode()).trim();
+		e && (yield e);
+	} finally {
+		try {
+			await n.cancel();
+		} catch {}
+		n.releaseLock();
+	}
+}
+function p(t) {
+	let n;
+	try {
+		n = JSON.parse(t);
+	} catch (n) {
+		throw new e("INVALID_RESPONSE", "stream emitted a non-JSON line", {
+			cause: n,
+			details: { line: t }
+		});
+	}
+	return typeof n != "object" || !n || !("quote" in n) && !("error" in n) ? null : n;
+}
+function m(e, t) {
+	return new Promise((n, r) => {
+		if (t?.aborted) return r(t.reason instanceof Error ? t.reason : new DOMException("aborted", "AbortError"));
+		let i = setTimeout(() => {
+			t?.removeEventListener("abort", a), n();
+		}, e);
+		function a() {
+			clearTimeout(i), r(t?.reason instanceof Error ? t.reason : new DOMException("aborted", "AbortError"));
+		}
+		t?.addEventListener("abort", a, { once: !0 });
+	});
+}
+//#endregion
+export { n as DEFAULT_FIAT_BASE_PATH, t as DEFAULT_FIAT_BASE_URL, r as TERMINAL_FIAT_ORDER_STATUSES, i as createFiatClient };

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+import { FiatErrorCode } from '@tokenflight/fiat';
+/** Client-side failure codes, for errors the server never produced. */
+export type FiatClientOnlyErrorCode = "NETWORK_ERROR" | "TIMEOUT" | "INVALID_RESPONSE";
+export type FiatClientErrorCode = FiatErrorCode | FiatClientOnlyErrorCode;
+/** One error type for everything the client throws. `code` is the wire error code when
+ *  the server produced the failure; `status` is present iff an HTTP response arrived. */
+export declare class FiatClientError extends Error {
+    readonly code: FiatClientErrorCode | (string & {});
+    readonly retryable: boolean;
+    readonly status?: number;
+    readonly details?: unknown;
+    constructor(code: FiatClientErrorCode | (string & {}), message: string, options?: {
+        retryable?: boolean;
+        status?: number;
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+export declare function isFiatClientError(value: unknown): value is FiatClientError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,15 @@
+//#region src/errors.ts
+var e = class extends Error {
+	code;
+	retryable;
+	status;
+	details;
+	constructor(e, t, n = {}) {
+		super(t, n.cause === void 0 ? void 0 : { cause: n.cause }), this.name = "FiatClientError", this.code = e, this.retryable = n.retryable ?? !1, n.status !== void 0 && (this.status = n.status), n.details !== void 0 && (this.details = n.details);
+	}
+};
+function t(t) {
+	return t instanceof e;
+}
+//#endregion
+export { e as FiatClientError, t as isFiatClientError };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createFiatClient, DEFAULT_FIAT_BASE_PATH, DEFAULT_FIAT_BASE_URL, TERMINAL_FIAT_ORDER_STATUSES, type FiatClient, type FiatClientOptions, type FiatQuotesResult, type RequestOptions, type WaitForOrderOptions, } from './client.js';
+export { FiatClientError, isFiatClientError, type FiatClientErrorCode, type FiatClientOnlyErrorCode } from './errors.js';
+export type { FiatAssetRef, FiatConfigResponse, FiatCreateOrderRequest, FiatCreateOrderResponse, FiatErrorCode, FiatOrderAction, FiatOrderFailure, FiatOrderStatus, FiatFailureSource, FiatProgress, FiatQuoteRequest, FiatQuoteRequestBase, FiatQuoteResult, FiatQuotesResponse, FiatTokenMetadata, InputMode, OrderView, ProviderCapabilities, ProviderDisplay, QuoteKind, QuoteProviderError, QuoteStreamEvent, SwapStrategy, WireError, } from '@tokenflight/fiat';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+import { FiatClientError as e, isFiatClientError as t } from "./errors.js";
+import { DEFAULT_FIAT_BASE_PATH as n, DEFAULT_FIAT_BASE_URL as r, TERMINAL_FIAT_ORDER_STATUSES as i, createFiatClient as a } from "./client.js";
+export { n as DEFAULT_FIAT_BASE_PATH, r as DEFAULT_FIAT_BASE_URL, e as FiatClientError, i as TERMINAL_FIAT_ORDER_STATUSES, a as createFiatClient, t as isFiatClientError };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@tokenflight/fiat-client",
+  "version": "0.0.1-rc.0",
+  "description": "Typed client for the @tokenflight/fiat HTTP contract — zero runtime dependencies",
+  "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": {
+    "typescript": "^6.0.3",
+    "vite": "^8.1.0",
+    "vite-plugin-dts": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "vite build"
+  }
+}