@ravnexchange/sdk 0.1.1

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+import type { ChainDTO, ExecuteParams, ExecutionDTO, GetQuoteParams, QuoteDTO, StatusDTO, SubmitSignatureParams, TokenDTO } from "./types";
+export interface RavnClientConfig {
+    /** Self-serve or enterprise key. Omit for the anonymous tier (works immediately, lower rate limit). */
+    apiKey?: string;
+    /** Default: https://ravn.exchange/api/v1 */
+    baseUrl?: string;
+    /** Swap in your own fetch (e.g. for React Native, or a test double). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+export declare class RavnClient {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(config?: RavnClientConfig);
+    private request;
+    /** POST /v1/quote — omitting destinationAddress/refundAddress returns a preview-only quote (see QuoteDTO.executable). */
+    getQuote(params: GetQuoteParams): Promise<QuoteDTO>;
+    /** POST /v1/execute — branch on the returned executionType (TRANSACTION / SIGNATURE / DEPOSIT). */
+    execute(params: ExecuteParams): Promise<ExecutionDTO>;
+    /** POST /v1/submit-signature — for SIGNATURE-type executions only. Returns the ref to poll getStatus with. */
+    submitSignature(params: SubmitSignatureParams): Promise<{
+        statusRef: string;
+    }>;
+    /** GET /v1/status — `ref` is the DEPOSIT address or the statusRef from submitSignature. */
+    getStatus(quoteToken: string, ref: string): Promise<StatusDTO>;
+    /** GET /v1/tokens — RAVN's listed token registry for one chain. Not a per-pair routability guarantee. */
+    getTokens(chainId: number): Promise<TokenDTO[]>;
+    /** GET /v1/chains — every chain RAVN lists tokens for. Static; safe to cache client-side. */
+    getChains(): Promise<ChainDTO[]>;
+}

package/dist/client.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RavnClient = void 0;
+const types_1 = require("./types");
+const DEFAULT_BASE_URL = "https://ravn.exchange/api/v1";
+class RavnClient {
+    constructor(config = {}) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.fetchImpl = config.fetch ?? globalThis.fetch;
+    }
+    async request(path, init) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                "content-type": "application/json",
+                ...(this.apiKey ? { "x-api-key": this.apiKey } : {}),
+                ...init.headers,
+            },
+        });
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            // A non-JSON body (an intermediary's HTML error page, an empty 204/502/504) must still
+            // surface as the one error type this client promises — never a raw SyntaxError.
+            throw new types_1.RavnApiError("INTERNAL", `HTTP ${res.status}: response was not valid JSON`, undefined, undefined);
+        }
+        if (!res.ok || body.error) {
+            const err = body.error ?? { code: "INTERNAL", message: `HTTP ${res.status}` };
+            throw new types_1.RavnApiError(err.code, err.message, err.details, body.meta);
+        }
+        return body.data;
+    }
+    /** POST /v1/quote — omitting destinationAddress/refundAddress returns a preview-only quote (see QuoteDTO.executable). */
+    getQuote(params) {
+        return this.request("/quote", { method: "POST", body: JSON.stringify(params) });
+    }
+    /** POST /v1/execute — branch on the returned executionType (TRANSACTION / SIGNATURE / DEPOSIT). */
+    execute(params) {
+        return this.request("/execute", { method: "POST", body: JSON.stringify(params) });
+    }
+    /** POST /v1/submit-signature — for SIGNATURE-type executions only. Returns the ref to poll getStatus with. */
+    submitSignature(params) {
+        return this.request("/submit-signature", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    /** GET /v1/status — `ref` is the DEPOSIT address or the statusRef from submitSignature. */
+    getStatus(quoteToken, ref) {
+        const qs = new URLSearchParams({ quoteToken, ref }).toString();
+        return this.request(`/status?${qs}`, { method: "GET" });
+    }
+    /** GET /v1/tokens — RAVN's listed token registry for one chain. Not a per-pair routability guarantee. */
+    getTokens(chainId) {
+        const qs = new URLSearchParams({ chainId: String(chainId) }).toString();
+        return this.request(`/tokens?${qs}`, { method: "GET" });
+    }
+    /** GET /v1/chains — every chain RAVN lists tokens for. Static; safe to cache client-side. */
+    getChains() {
+        return this.request("/chains", { method: "GET" });
+    }
+}
+exports.RavnClient = RavnClient;

package/dist/execute-and-track.d.ts

@@ -0,0 +1,52 @@
+import type { RavnClient } from "./client";
+import type { ApprovalDTO, ExecuteParams, ExecutionDTO, StatusDTO } from "./types";
+type TxLike = {
+    to?: string;
+    data?: string;
+    value?: string;
+    chainId?: number;
+    serialized?: string;
+};
+export interface ExecuteAndTrackHandlers {
+    /** Broadcast a transaction (an approval, or the main swap tx) and return its hash. */
+    sendTransaction(tx: TxLike): Promise<string>;
+    /**
+     * Wait for a transaction hash to confirm. Called on the approval before the main tx is ever
+     * sent — sending both back-to-back races the allowance and is the most common integration bug
+     * this helper exists to prevent.
+     */
+    waitForReceipt(hash: string, chainId?: number): Promise<void>;
+    /** Sign an EIP-712 typed-data payload. Only called for SIGNATURE executions. */
+    signTypedData?(typedData: Record<string, unknown>): Promise<`0x${string}`>;
+    /**
+     * The API sends `approval` whenever the venue generically needs an allowance — it deliberately
+     * never reads the chain to check whether the caller already has one (that's an RPC round-trip
+     * on every execute). Without this handler, that approval tx is sent unconditionally, even when
+     * unnecessary — the caller pays gas for a redundant approve on every swap of the same
+     * token/spender. Supply this (an allowance read against your own RPC) to skip it when already
+     * sufficient, same as the first-party app's own ensureErc20Allowance does.
+     */
+    hasAllowance?(approval: ApprovalDTO): Promise<boolean>;
+}
+export interface ExecuteAndTrackOptions {
+    /** Default true. Set false to get a ref back immediately and poll getStatus yourself. */
+    pollUntilTerminal?: boolean;
+    pollIntervalMs?: number;
+}
+export interface ExecuteAndTrackResult {
+    execution: ExecutionDTO;
+    approvalTxHash?: string;
+    txHash?: string;
+    /** Pass to client.getStatus(quoteToken, ref) — same value as txHash for TRANSACTION. */
+    statusRef?: string;
+    /** Set once pollUntilTerminal reaches a terminal status. Absent for DEPOSIT (see below) or when polling is turned off. */
+    finalStatus?: StatusDTO;
+}
+/**
+ * Sequences execute() → approval (if any) → wait for its receipt → main tx/signature → status
+ * polling, using caller-supplied signing/sending functions. The SDK stays wallet-agnostic (no
+ * RPC dependency) — this just gets the ORDER right, which quickstart's own docs flag as the
+ * most common integration failure: sending the main tx before the approval has confirmed.
+ */
+export declare function executeAndTrack(client: RavnClient, params: ExecuteParams, handlers: ExecuteAndTrackHandlers, options?: ExecuteAndTrackOptions): Promise<ExecuteAndTrackResult>;
+export {};

package/dist/execute-and-track.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAndTrack = executeAndTrack;
+const polling_1 = require("./polling");
+/**
+ * Sequences execute() → approval (if any) → wait for its receipt → main tx/signature → status
+ * polling, using caller-supplied signing/sending functions. The SDK stays wallet-agnostic (no
+ * RPC dependency) — this just gets the ORDER right, which quickstart's own docs flag as the
+ * most common integration failure: sending the main tx before the approval has confirmed.
+ */
+async function executeAndTrack(client, params, handlers, options = {}) {
+    const { pollUntilTerminal = true, pollIntervalMs = 4000 } = options;
+    const execution = await client.execute(params);
+    const pollStatus = async (ref) => {
+        if (!pollUntilTerminal)
+            return undefined;
+        for (;;) {
+            const status = await client.getStatus(params.quoteToken, ref);
+            if ((0, polling_1.isPollingTerminal)(status.status))
+                return status;
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+    };
+    // Sends and confirms an approval unless the caller already knows it's covered — see
+    // ExecuteAndTrackHandlers.hasAllowance's doc comment for why the API can't decide this itself.
+    const maybeSendApproval = async (approval) => {
+        if (!approval)
+            return undefined;
+        if (await handlers.hasAllowance?.(approval))
+            return undefined;
+        const hash = await handlers.sendTransaction(approval);
+        await handlers.waitForReceipt(hash, approval.chainId);
+        return hash;
+    };
+    if (execution.executionType === "TRANSACTION") {
+        const approvalTxHash = await maybeSendApproval(execution.approval);
+        const txHash = await handlers.sendTransaction(execution.transaction);
+        return { execution, approvalTxHash, txHash, statusRef: txHash, finalStatus: await pollStatus(txHash) };
+    }
+    if (execution.executionType === "SIGNATURE") {
+        if (!handlers.signTypedData) {
+            throw new Error("executeAndTrack: this execution requires signTypedData, none was provided");
+        }
+        if (!execution.typedData) {
+            throw new Error("executeAndTrack: SIGNATURE execution is missing typedData");
+        }
+        // A signed order isn't allowance-free: CoW's vault relayer and Bebop/0x's Permit2 still pull
+        // the sell token with transferFrom, so this on-chain allowance (separate from approvalData's
+        // gasless per-trade signature) must be confirmed before signing — otherwise the order is
+        // accepted and simply never fills, with no error to explain why.
+        const approvalTxHash = await maybeSendApproval(execution.approval);
+        let approvalSignature;
+        if (execution.approvalData) {
+            approvalSignature = await handlers.signTypedData(execution.approvalData);
+        }
+        const signature = await handlers.signTypedData(execution.typedData);
+        const { statusRef } = await client.submitSignature({ quoteToken: params.quoteToken, signature, approvalSignature });
+        return { execution, approvalTxHash, statusRef, finalStatus: await pollStatus(statusRef) };
+    }
+    // DEPOSIT: nothing to sign or send from here — the user moves funds to execution.deposit.address
+    // out-of-band, and this helper has no way to know when that happens. Returned without polling;
+    // start polling yourself (getStatus / useRavnStatus) once the deposit is actually sent.
+    return { execution, statusRef: execution.statusRef };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { RavnClient } from "./client";
+export type { RavnClientConfig } from "./client";
+export * from "./types";
+export { isPollingTerminal } from "./polling";
+export { executeAndTrack } from "./execute-and-track";
+export type { ExecuteAndTrackHandlers, ExecuteAndTrackOptions, ExecuteAndTrackResult, } from "./execute-and-track";

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAndTrack = exports.isPollingTerminal = exports.RavnClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "RavnClient", { enumerable: true, get: function () { return client_1.RavnClient; } });
+__exportStar(require("./types"), exports);
+var polling_1 = require("./polling");
+Object.defineProperty(exports, "isPollingTerminal", { enumerable: true, get: function () { return polling_1.isPollingTerminal; } });
+var execute_and_track_1 = require("./execute-and-track");
+Object.defineProperty(exports, "executeAndTrack", { enumerable: true, get: function () { return execute_and_track_1.executeAndTrack; } });

package/dist/polling.d.ts

@@ -0,0 +1,7 @@
+import type { SettlementStatus } from "./types";
+/**
+ * Whether a status is done changing. "unknown" counts as terminal even though it isn't a real
+ * outcome — it means the venue has no live tracker (see StatusDTO.tracking), so it will never
+ * change and polling forever would just spin. Only "pending"/"processing" keep polling.
+ */
+export declare function isPollingTerminal(status: SettlementStatus): boolean;

package/dist/polling.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPollingTerminal = isPollingTerminal;
+/**
+ * Whether a status is done changing. "unknown" counts as terminal even though it isn't a real
+ * outcome — it means the venue has no live tracker (see StatusDTO.tracking), so it will never
+ * change and polling forever would just spin. Only "pending"/"processing" keep polling.
+ */
+function isPollingTerminal(status) {
+    return status !== "pending" && status !== "processing";
+}

package/dist/types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Wire types for RAVN's public /api/v1 surface. Deliberately a standalone mirror of
+ * src/lib/api/v1/dto.ts's public DTOs, not an import from it — this package ships to npm on
+ * its own and can't depend on the app's internal source tree. Keep these two in sync by hand
+ * when the API's public contract changes; that file's own comment already promises the shape
+ * is frozen for third parties, so drift should be rare.
+ */
+export interface TokenDTO {
+    symbol: string;
+    name: string;
+    address: string;
+    decimals: number;
+    chainId: number;
+    isNative: boolean;
+    logoUrl?: string;
+}
+export interface QuoteDTO {
+    /** Opaque handle — pass back to execute() verbatim. Do not parse. */
+    quoteToken: string;
+    venue: {
+        id: string;
+        name: string;
+    };
+    routeType: string;
+    input: {
+        token: TokenDTO;
+        amount: string;
+    };
+    output: {
+        token: TokenDTO;
+        amount: string;
+    };
+    /** `supported: false` means the venue has no fee mechanism at all (bps will be 0 either
+     * way) — distinct from `supported: true, bps: 0`, a real, intentional zero fee. */
+    fee: {
+        bps: number;
+        amount: string;
+        token: TokenDTO;
+        supported: boolean;
+    };
+    /** False means this is a preview-only price — see RavnClient.getQuote's destinationAddress note. */
+    executable: boolean;
+    slippage: {
+        bps: number;
+        isFirm: boolean;
+        guaranteedMin: string | null;
+    } | null;
+    gas: {
+        native: string;
+        nativeSymbol: string;
+        usd: string | null;
+        estimated: boolean;
+    } | null;
+    /** Same price source as `gas.usd`. Null when the token can't be priced. */
+    inputUsd: string | null;
+    outputUsd: string | null;
+    estimatedTimeSeconds: number;
+    estimatedTimeIsGuess: boolean;
+    expiresAt: number;
+    /** Every other venue that raced and produced a usable quote, best output first. */
+    alternatives: AlternativeQuoteDTO[];
+}
+export interface AlternativeQuoteDTO {
+    venue: {
+        id: string;
+        name: string;
+    };
+    routeType: string;
+    /** Pass to execute() to run THIS route instead of the primary quote. */
+    quoteToken: string;
+    outputAmount: string;
+    fee: {
+        bps: number;
+        amount: string;
+        supported: boolean;
+    };
+    executable: boolean;
+    estimatedTimeSeconds: number;
+    estimatedTimeIsGuess: boolean;
+}
+export interface ChainDTO {
+    chainId: number;
+    name: string;
+    shortName: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    explorerUrl: string;
+    logoUrl?: string;
+}
+export interface ApprovalDTO {
+    to: string;
+    data: string;
+    value: string;
+    chainId?: number;
+    spender?: string;
+    amount: string;
+    unlimitedRecommended?: boolean;
+}
+export type ExecutionDTO = {
+    executionType: "TRANSACTION";
+    approval?: ApprovalDTO;
+    transaction: {
+        to?: string;
+        data?: string;
+        value?: string;
+        chainId?: number;
+        serialized?: string;
+    };
+} | {
+    executionType: "SIGNATURE";
+    approval?: ApprovalDTO;
+    typedData?: Record<string, unknown>;
+    approvalData?: Record<string, unknown>;
+    submit: {
+        url: string;
+        payload?: Record<string, unknown>;
+    };
+} | {
+    executionType: "DEPOSIT";
+    deposit: {
+        address: string;
+        amount: string;
+        chainId?: number;
+    };
+    statusRef: string;
+};
+export type SettlementStatus = "pending" | "processing" | "expired" | "success" | "refunded" | "failed" | "not_found" | "unknown";
+export interface StatusDTO {
+    status: SettlementStatus;
+    venue: string;
+    venueStatus?: unknown;
+    tracking?: "unavailable";
+    /** Actual delivered output in the output token's base units, when the venue exposes it. */
+    deliveredAmount?: string | null;
+    /** The destination-chain tx that paid the user out, when the venue names one. */
+    txHash?: string | null;
+}
+export interface GetQuoteParams {
+    inputChainId: number;
+    outputChainId: number;
+    inputToken: string;
+    outputToken: string;
+    /** Positive integer string, in the token's smallest unit (no decimals). */
+    inputAmount: string;
+    userAddress: string;
+    /** Omitting this yields a preview-only quote — see QuoteDTO.executable. */
+    destinationAddress?: string;
+    refundAddress?: string;
+    slippageBps?: number;
+    rankingMode?: "best_output" | "fastest";
+    /** Drop specific venues from this race — e.g. a risk objection to one of them. */
+    excludeVenues?: string[];
+}
+export interface ExecuteParams {
+    quoteToken: string;
+    destinationAddress?: string;
+    refundAddress?: string;
+}
+export interface SubmitSignatureParams {
+    quoteToken: string;
+    signature: `0x${string}`;
+    approvalSignature?: `0x${string}`;
+}
+export interface ErrorMeta {
+    requestId: string;
+    version: string;
+}
+/** Thrown for every non-2xx response. `code` is the stable, machine-readable string from the API. */
+export declare class RavnApiError extends Error {
+    readonly code: string;
+    readonly details: unknown;
+    readonly meta: ErrorMeta | undefined;
+    constructor(code: string, message: string, details: unknown, meta: ErrorMeta | undefined);
+}

package/dist/types.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Wire types for RAVN's public /api/v1 surface. Deliberately a standalone mirror of
+ * src/lib/api/v1/dto.ts's public DTOs, not an import from it — this package ships to npm on
+ * its own and can't depend on the app's internal source tree. Keep these two in sync by hand
+ * when the API's public contract changes; that file's own comment already promises the shape
+ * is frozen for third parties, so drift should be rare.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RavnApiError = void 0;
+/** Thrown for every non-2xx response. `code` is the stable, machine-readable string from the API. */
+class RavnApiError extends Error {
+    constructor(code, message, details, meta) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.meta = meta;
+        this.name = "RavnApiError";
+    }
+}
+exports.RavnApiError = RavnApiError;

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@ravnexchange/sdk",
+  "version": "0.1.1",
+  "description": "Typed client for the RAVN integrator API (/api/v1) — quote, execute, submit-signature, status.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}