@ravnexchange/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { useRavnQuote } from "./useRavnQuote";
+export type { UseRavnQuoteResult } from "./useRavnQuote";
+export { useRavnExecute } from "./useRavnExecute";
+export type { UseRavnExecuteResult } from "./useRavnExecute";
+export { useRavnStatus } from "./useRavnStatus";
+export type { UseRavnStatusResult } from "./useRavnStatus";
+export { isPollingTerminal, msUntilExpiry } from "./polling";

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.msUntilExpiry = exports.isPollingTerminal = exports.useRavnStatus = exports.useRavnExecute = exports.useRavnQuote = void 0;
+var useRavnQuote_1 = require("./useRavnQuote");
+Object.defineProperty(exports, "useRavnQuote", { enumerable: true, get: function () { return useRavnQuote_1.useRavnQuote; } });
+var useRavnExecute_1 = require("./useRavnExecute");
+Object.defineProperty(exports, "useRavnExecute", { enumerable: true, get: function () { return useRavnExecute_1.useRavnExecute; } });
+var useRavnStatus_1 = require("./useRavnStatus");
+Object.defineProperty(exports, "useRavnStatus", { enumerable: true, get: function () { return useRavnStatus_1.useRavnStatus; } });
+var polling_1 = require("./polling");
+Object.defineProperty(exports, "isPollingTerminal", { enumerable: true, get: function () { return polling_1.isPollingTerminal; } });
+Object.defineProperty(exports, "msUntilExpiry", { enumerable: true, get: function () { return polling_1.msUntilExpiry; } });

package/dist/polling.d.ts

@@ -0,0 +1,3 @@
+export { isPollingTerminal } from "@ravnexchange/sdk";
+/** Milliseconds until a quote's expiresAt, clamped to 0 (never negative). */
+export declare function msUntilExpiry(expiresAt: number, now?: number): number;

package/dist/polling.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPollingTerminal = void 0;
+exports.msUntilExpiry = msUntilExpiry;
+// isPollingTerminal lives in @ravnexchange/sdk (core) — executeAndTrack needs it too and core
+// can't depend on this React package. Re-exported here so existing @ravnexchange/react imports
+// don't break.
+var sdk_1 = require("@ravnexchange/sdk");
+Object.defineProperty(exports, "isPollingTerminal", { enumerable: true, get: function () { return sdk_1.isPollingTerminal; } });
+/** Milliseconds until a quote's expiresAt, clamped to 0 (never negative). */
+function msUntilExpiry(expiresAt, now = Date.now()) {
+    return Math.max(0, expiresAt - now);
+}

package/dist/useRavnExecute.d.ts

@@ -0,0 +1,13 @@
+import type { ExecuteParams, ExecutionDTO, RavnClient } from "@ravnexchange/sdk";
+export interface UseRavnExecuteResult {
+    execute: (params: ExecuteParams) => Promise<ExecutionDTO>;
+    data: ExecutionDTO | null;
+    isLoading: boolean;
+    error: unknown;
+}
+/**
+ * Thin state wrapper around client.execute(). Deliberately does NOT sign or send anything —
+ * this package has no opinion on wallets. Branch on the returned executionType and hand it to
+ * whatever signer the integrator already has (wagmi, ethers, a hardware wallet, ...).
+ */
+export declare function useRavnExecute(client: RavnClient): UseRavnExecuteResult;

package/dist/useRavnExecute.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRavnExecute = useRavnExecute;
+const react_1 = require("react");
+/**
+ * Thin state wrapper around client.execute(). Deliberately does NOT sign or send anything —
+ * this package has no opinion on wallets. Branch on the returned executionType and hand it to
+ * whatever signer the integrator already has (wagmi, ethers, a hardware wallet, ...).
+ */
+function useRavnExecute(client) {
+    const [data, setData] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const execute = (0, react_1.useCallback)(async (params) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const result = await client.execute(params);
+            setData(result);
+            return result;
+        }
+        catch (err) {
+            setError(err);
+            throw err;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client]);
+    return { execute, data, isLoading, error };
+}

package/dist/useRavnQuote.d.ts

@@ -0,0 +1,16 @@
+import type { GetQuoteParams, QuoteDTO, RavnClient } from "@ravnexchange/sdk";
+export interface UseRavnQuoteResult {
+    quote: QuoteDTO | null;
+    isLoading: boolean;
+    error: unknown;
+    /** True once quote.expiresAt has passed — stop letting the user sign, call refetch(). */
+    isExpired: boolean;
+    refetch: () => void;
+}
+/**
+ * Fetches a quote and flips `isExpired` on its own timer when expiresAt passes — no polling,
+ * just one setTimeout per quote. Pass `params: null` to skip fetching (e.g. amount not entered
+ * yet). Does not auto-refetch on expiry: that's a UX choice (silently re-pricing behind a user's
+ * back is worse than telling them to ask again), left to the caller.
+ */
+export declare function useRavnQuote(client: RavnClient, params: GetQuoteParams | null): UseRavnQuoteResult;

package/dist/useRavnQuote.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRavnQuote = useRavnQuote;
+const react_1 = require("react");
+const polling_1 = require("./polling");
+/**
+ * Fetches a quote and flips `isExpired` on its own timer when expiresAt passes — no polling,
+ * just one setTimeout per quote. Pass `params: null` to skip fetching (e.g. amount not entered
+ * yet). Does not auto-refetch on expiry: that's a UX choice (silently re-pricing behind a user's
+ * back is worse than telling them to ask again), left to the caller.
+ */
+function useRavnQuote(client, params) {
+    const [quote, setQuote] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [isExpired, setIsExpired] = (0, react_1.useState)(false);
+    const [generation, setGeneration] = (0, react_1.useState)(0);
+    const paramsKey = params ? JSON.stringify(params) : null;
+    const refetch = (0, react_1.useCallback)(() => setGeneration((g) => g + 1), []);
+    (0, react_1.useEffect)(() => {
+        if (!params) {
+            setQuote(null);
+            setIsExpired(false);
+            return;
+        }
+        let cancelled = false;
+        setIsLoading(true);
+        setError(null);
+        setIsExpired(false);
+        client
+            .getQuote(params)
+            .then((q) => {
+            if (cancelled)
+                return;
+            setQuote(q);
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setError(err);
+        })
+            .finally(() => {
+            if (!cancelled)
+                setIsLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // paramsKey (not params) drives refetch — a fresh object with the same fields shouldn't refire.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, paramsKey, generation]);
+    const expiresAt = quote?.expiresAt;
+    (0, react_1.useEffect)(() => {
+        if (!expiresAt)
+            return;
+        const timer = setTimeout(() => setIsExpired(true), (0, polling_1.msUntilExpiry)(expiresAt));
+        return () => clearTimeout(timer);
+    }, [expiresAt]);
+    return { quote, isLoading, error, isExpired, refetch };
+}

package/dist/useRavnStatus.d.ts

@@ -0,0 +1,16 @@
+import { type RavnClient, type StatusDTO } from "@ravnexchange/sdk";
+export interface UseRavnStatusResult {
+    status: StatusDTO | null;
+    isLoading: boolean;
+    error: unknown;
+}
+export declare function isPermanentError(err: unknown): boolean;
+/**
+ * Polls GET /v1/status until it reaches a terminal state (see isPollingTerminal — "unknown"
+ * counts as terminal, it means the venue has no live tracker and never will for this swap).
+ * Pass `params: null` to not poll at all (e.g. before execution has produced a ref).
+ */
+export declare function useRavnStatus(client: RavnClient, params: {
+    quoteToken: string;
+    ref: string;
+} | null, intervalMs?: number): UseRavnStatusResult;

package/dist/useRavnStatus.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPermanentError = isPermanentError;
+exports.useRavnStatus = useRavnStatus;
+const react_1 = require("react");
+const sdk_1 = require("@ravnexchange/sdk");
+const polling_1 = require("./polling");
+// Codes the API itself defines as request-shaped, not transient — retrying with the exact same
+// arguments can never turn one of these into success. Anything else (RATE_LIMITED, INTERNAL, a
+// network failure) is worth retrying through.
+const PERMANENT_ERROR_CODES = new Set(["UNAUTHORIZED", "INVALID_REQUEST", "QUOTE_INVALID", "NOT_FOUND"]);
+function isPermanentError(err) {
+    return err instanceof sdk_1.RavnApiError && PERMANENT_ERROR_CODES.has(err.code);
+}
+/**
+ * Polls GET /v1/status until it reaches a terminal state (see isPollingTerminal — "unknown"
+ * counts as terminal, it means the venue has no live tracker and never will for this swap).
+ * Pass `params: null` to not poll at all (e.g. before execution has produced a ref).
+ */
+function useRavnStatus(client, params, intervalMs = 4000) {
+    const [status, setStatus] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!params) {
+            setStatus(null);
+            return;
+        }
+        let cancelled = false;
+        let timer;
+        const poll = () => {
+            setIsLoading(true);
+            client
+                .getStatus(params.quoteToken, params.ref)
+                .then((s) => {
+                if (cancelled)
+                    return;
+                setStatus(s);
+                setError(null);
+                if (!(0, polling_1.isPollingTerminal)(s.status)) {
+                    timer = setTimeout(poll, intervalMs);
+                }
+            })
+                .catch((err) => {
+                if (cancelled)
+                    return;
+                setError(err);
+                // Keep polling through a transient network/5xx error rather than giving up on the
+                // swap's status forever — but a permanent error (bad API key, invalid ref) can never
+                // resolve by asking again with the same arguments, so stop rather than spam the API
+                // for as long as the component happens to stay mounted.
+                if (!isPermanentError(err)) {
+                    timer = setTimeout(poll, intervalMs);
+                }
+            })
+                .finally(() => {
+                if (!cancelled)
+                    setIsLoading(false);
+            });
+        };
+        poll();
+        return () => {
+            cancelled = true;
+            if (timer)
+                clearTimeout(timer);
+        };
+    }, [client, params?.quoteToken, params?.ref, intervalMs]);
+    return { status, isLoading, error };
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@ravnexchange/react",
+  "version": "0.1.0",
+  "description": "React hooks for @ravnexchange/sdk — quote/execute/status state management. Bring your own wallet.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "peerDependencies": {
+    "@ravnexchange/sdk": "*",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@ravnexchange/sdk": "*",
+    "@types/react": "^18.3.0",
+    "typescript": "^5.7.0"
+  }
+}