@ravnexchange/sdk 0.1.15 → 0.2.1

package/dist/client.d.ts

@@ -17,7 +17,7 @@ export declare class RavnClient {
     /** 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>;
+    execute({ idempotencyKey, ...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;
@@ -32,8 +32,10 @@ export declare class RavnClient {
      * the execution's statusRef, submitSignature's statusRef, or the origin tx hash. POST, not GET:
      * a 2-hop quoteToken in a query string can exceed header limits and fail with 431. `txHash`:
      * a two-hop route's hop-1 transaction, or the fee payment a DEPOSIT's `fee.transaction` asked
-     * for; it's how RAVN proves the fee your share is paid from. */
-    getStatus(quoteToken: string, ref: string, txHash?: string): Promise<StatusDTO>;
+     * for; it's how RAVN proves the fee your share is paid from. `signal` aborts the request. */
+    getStatus(quoteToken: string, ref: string, txHash?: string, options?: {
+        signal?: AbortSignal;
+    }): 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. */

package/dist/client.js

@@ -16,26 +16,39 @@ class RavnClient {
         // Called unbound, never as this.fetchImpl(...): a browser's own fetch (the default, or one
         // passed in) throws "Illegal invocation" when `this` is the client, failing every call.
         const fetchImpl = this.fetchImpl;
-        const res = await fetchImpl(`${this.baseUrl}${path}`, {
-            ...init,
-            headers: {
-                "content-type": "application/json",
-                ...(this.apiKey ? { "x-api-key": this.apiKey } : {}),
-                ...init.headers,
-            },
-        });
+        let res;
+        try {
+            res = await fetchImpl(`${this.baseUrl}${path}`, {
+                ...init,
+                headers: {
+                    "content-type": "application/json",
+                    ...(this.apiKey ? { "x-api-key": this.apiKey } : {}),
+                    ...init.headers,
+                },
+            });
+        }
+        catch (err) {
+            // The caller's own abort is theirs, as is; anything else is the one error type this client
+            // promises, never a raw fetch TypeError.
+            if (init.signal?.aborted)
+                throw err;
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new types_1.RavnApiError("NETWORK_ERROR", `No response from ${path}: ${reason}`, undefined, undefined, { cause: err });
+        }
         let body;
         try {
             body = (await res.json());
         }
-        catch {
+        catch (err) {
+            if (init.signal?.aborted)
+                throw err;
             // 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);
+            throw new types_1.RavnApiError("INTERNAL", `HTTP ${res.status}: response was not valid JSON`, undefined, undefined, { status: res.status });
         }
         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);
+            throw new types_1.RavnApiError(err.code, err.message, err.details, body.meta, { status: res.status });
         }
         return body.data;
     }
@@ -44,8 +57,16 @@ class RavnClient {
         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) });
+    execute({ idempotencyKey, ...params }) {
+        // The API's own rule: anything else fetch refuses to send (a reported NETWORK_ERROR) or RAVN answers 400.
+        if (idempotencyKey !== undefined && !/^[\x21-\x7e]{1,255}$/.test(idempotencyKey)) {
+            return Promise.reject(new types_1.RavnApiError("INVALID_REQUEST", "idempotencyKey must be 1–255 printable ASCII characters, no spaces", undefined, undefined));
+        }
+        return this.request("/execute", {
+            method: "POST",
+            body: JSON.stringify(params),
+            ...(idempotencyKey ? { headers: { "Idempotency-Key": idempotencyKey } } : {}),
+        });
     }
     /** POST /v1/submit-signature: for SIGNATURE-type executions only. Returns the ref to poll getStatus with. */
     submitSignature(params) {
@@ -67,11 +88,12 @@ class RavnClient {
      * the execution's statusRef, submitSignature's statusRef, or the origin tx hash. POST, not GET:
      * a 2-hop quoteToken in a query string can exceed header limits and fail with 431. `txHash`:
      * a two-hop route's hop-1 transaction, or the fee payment a DEPOSIT's `fee.transaction` asked
-     * for; it's how RAVN proves the fee your share is paid from. */
-    getStatus(quoteToken, ref, txHash) {
+     * for; it's how RAVN proves the fee your share is paid from. `signal` aborts the request. */
+    getStatus(quoteToken, ref, txHash, options = {}) {
         return this.request("/status", {
             method: "POST",
             body: JSON.stringify({ quoteToken, ref, ...(txHash ? { txHash } : {}) }),
+            signal: options.signal,
         });
     }
     /** GET /v1/tokens: RAVN's listed token registry for one chain. Not a per-pair routability guarantee. */

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

@@ -7,27 +7,41 @@ type TxLike = {
     chainId?: number;
     serialized?: string;
 };
+/**
+ * The parts of a transaction receipt executeAndTrack reads. viem's and wagmi's
+ * `waitForTransactionReceipt`, ethers v5 and v6 (`tx.wait()`, `provider.waitForTransaction`) and
+ * web3.js receipts all fit as they are.
+ */
+export type TransactionReceiptLike = {
+    status?: unknown;
+    transactionHash: string;
+} | {
+    status?: unknown;
+    hash: string;
+};
 export interface ExecuteAndTrackHandlers {
     /** Broadcast a transaction (an approval, the main swap tx, or RAVN's fee) 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. Also called on the swap before RAVN's fee is sent on its own
-     * (`fee.transaction`): resolve to the receipt itself (viem's `waitForTransactionReceipt`,
-     * ethers' `wait()`), as the fee is only sent when it says success AND is this hash's own (a
-     * cancelled or replaced swap resolves with another transaction's). Resolving to nothing, or
-     * anything else, sends no fee: a fee on a swap that didn't run is the user's money lost.
+     * Wait for a transaction hash to confirm and resolve to its receipt. 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. Also called on the swap before RAVN's fee
+     * is sent on its own (`fee.transaction`): the fee is only sent when the receipt says success AND
+     * is this hash's own (a cancelled or replaced swap resolves with another transaction's). A
+     * handler resolving to nothing doesn't compile: it would never get the fee sent. `null` (ethers
+     * with 0 confirmations) sends no fee: a fee on a swap that didn't run is the user's money lost.
      */
-    waitForReceipt(hash: string, chainId?: number): Promise<unknown>;
+    waitForReceipt(hash: string, chainId?: number): Promise<TransactionReceiptLike | null>;
     /**
      * Optional: send several calls in ONE wallet confirmation that succeeds or fails as a whole
      * (EIP-5792 `wallet_sendCalls` with `atomicRequired: true`, a smart account) and resolve, once
      * they have landed, to the on-chain hash of the transaction that carried each call, in order
-     * (the same hash repeated for one transaction). Not a batch id or a 4337 userOpHash: RAVN
-     * proves its fee from that transaction. When given, a token-paid RAVN fee rides in the swap's
-     * own confirmation; a native-coin fee is always a plain transaction of its own. Reject only when
-     * nothing was sent: a rejection loses the swap's hash.
+     * (the same hash repeated, or just one, for one transaction). Not a batch id or a 4337
+     * userOpHash: RAVN proves its fee from that transaction. When given, a token-paid RAVN fee rides
+     * in the swap's own confirmation, and so does the swap's approval when it needs one; a
+     * native-coin fee is always a plain transaction of its own. The batch's gas limit is your
+     * wallet's (EIP-5792 carries none): give it headroom, as a wallet estimating it tight reverts
+     * the whole batch. Reject only when nothing was sent: a rejection loses the swap's hash.
      */
     sendCalls?(txs: TxLike[]): Promise<string[]>;
     /** Sign an EIP-712 typed-data payload. Only called for SIGNATURE executions. */
@@ -47,14 +61,42 @@ export interface ExecuteAndTrackHandlers {
      */
     hasAllowance?(approval: ApprovalDTO): Promise<boolean>;
 }
+/** What just happened: a transaction's hash is known (sent, not yet confirmed), a swap was signed
+ * for RAVN to submit (`signedTransaction` for a Solana swap, `signature` for an order), or a status
+ * poll answered. */
+export type ExecuteAndTrackStage = "reset_sent" | "approval_sent" | "swap_signed" | "swap_sent" | "fee_sent" | "status";
+export interface ExecuteAndTrackProgress {
+    stage: ExecuteAndTrackStage;
+    /** Everything known so far. Persist it: it's all you need to keep tracking the swap if this
+     * call never returns (a closed tab, a crash). "swap_sent" carries `statusRef`. */
+    partial: ExecuteAndTrackPartial;
+}
 export interface ExecuteAndTrackOptions {
     /** Default true. Set false to get a ref back once the swap (and RAVN's fee, when one is sent) is
      * out, and poll getStatus yourself with `statusTxHash`. */
     pollUntilTerminal?: boolean;
+    /** Default 4000. Also where the backoff after a failed call starts (doubling, up to a minute). */
     pollIntervalMs?: number;
+    /** How often to poll a swap that's `expired`: a refund is due and can take hours (Across returns
+     * it in a later settlement bundle). Default 60000. */
+    expiredPollIntervalMs?: number;
+    /** Stop polling this long after the first status poll, rejecting with an ExecuteAndTrackError
+     * ("TIMEOUT") that carries every hash: keep polling getStatus with them yourself. Default: no
+     * limit (a swap may sit `expired` for hours). */
+    maxWaitMs?: number;
+    /** Stop: nothing more goes to the wallet and polling ends, rejecting with an
+     * ExecuteAndTrackError ("ABORTED"). A wallet prompt already open isn't withdrawn; whatever it
+     * sends is in the error's `partial`. A submitSignature or submitTransaction call already under
+     * way is awaited first: its answer is the swap's only handle. */
+    signal?: AbortSignal;
+    /** Called with every hash the moment it exists (approval, swap with its statusRef, fee) and with
+     * every status poll. An error it throws is ignored: it never stops a swap that's out. */
+    onProgress?(progress: ExecuteAndTrackProgress): void;
 }
 export interface ExecuteAndTrackResult {
     execution: ExecutionDTO;
+    /** The `approval.reset` (approve to 0) sent before the approval, when the token needed one. */
+    resetTxHash?: string;
     approvalTxHash?: string;
     txHash?: string;
     /** Pass to client.getStatus(quoteToken, statusRef). Same as `execution.quoteToken`, NOT the
@@ -81,6 +123,34 @@ export interface ExecuteAndTrackResult {
     /** Set once pollUntilTerminal reaches a terminal status. Absent for DEPOSIT (see below) or when polling is turned off. */
     finalStatus?: StatusDTO;
 }
+/** What executeAndTrack knew when it reported progress or stopped: every hash sent so far, and the
+ * last status it saw. `signedTransaction` (broadcastViaRavn): the signed Solana swap handed to
+ * submitTransaction; post it again with the same quoteToken (RAVN never sends it twice) to learn
+ * whether it landed, before signing anything new. `signature` (SIGNATURE): the signed order handed
+ * to submitSignature; "swap_signed" with no "swap_sent" after it means the call failed or got no
+ * answer, and the venue may still have taken the order: check before signing a new one. */
+export type ExecuteAndTrackPartial = Partial<ExecuteAndTrackResult> & {
+    lastStatus?: StatusDTO;
+    signedTransaction?: string;
+    signature?: `0x${string}`;
+};
+/**
+ * How executeAndTrack rejects once anything has been sent or signed (an approval, the swap, a
+ * signature handed to RAVN), and on any abort or timeout: `partial` carries every hash, so the
+ * swap is never lost. Keep polling getStatus(partial.quoteToken, partial.statusRef,
+ * partial.statusTxHash). Before anything is sent, errors come as they are (a RavnApiError from
+ * execute, the wallet's own rejection).
+ */
+export declare class ExecuteAndTrackError extends Error {
+    /** "ABORTED": your signal. "TIMEOUT": maxWaitMs passed. "FAILED": anything else; see `cause`. */
+    readonly code: "ABORTED" | "TIMEOUT" | "FAILED";
+    readonly partial: ExecuteAndTrackPartial;
+    /** What failed underneath: a RavnApiError, the wallet's error, or your signal's reason. */
+    readonly cause?: unknown;
+    constructor(message: string, 
+    /** "ABORTED": your signal. "TIMEOUT": maxWaitMs passed. "FAILED": anything else; see `cause`. */
+    code: "ABORTED" | "TIMEOUT" | "FAILED", partial: ExecuteAndTrackPartial, cause?: unknown);
+}
 /** How to pay a DEPOSIT's `fee`, so it's proven against this swap. See DepositFeeDTO. Either way,
  * poll RAVN's getStatus until a terminal status even when the venue's own tracker (e.g. Rift's API)
  * already says delivered: RAVN books the fee on its own status polls. */
@@ -118,7 +188,12 @@ export declare function depositFeePayment(execution: ExecutionDTO): DepositFeePa
  * payment (if any) → 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.
+ * has confirmed. A failed API call is retried where repeating it is safe (status polls and
+ * submitTransaction on a 429, 5xx or no response; execute, sent with an Idempotency-Key, also when its
+ * answer was lost or is still being built, up to 4 tries; submitSignature only when rate limited),
+ * waiting the API's retryAfterSec. Once anything
+ * is sent, it rejects only with an ExecuteAndTrackError carrying every hash; `onProgress` hears
+ * each one first.
  */
 export declare function executeAndTrack(client: RavnClient, params: ExecuteParams, handlers: ExecuteAndTrackHandlers, options?: ExecuteAndTrackOptions): Promise<ExecuteAndTrackResult>;
 export {};

package/dist/execute-and-track.js

@@ -1,11 +1,43 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecuteAndTrackError = void 0;
 exports.depositFeePayment = depositFeePayment;
 exports.executeAndTrack = executeAndTrack;
+const types_1 = require("./types");
 const polling_1 = require("./polling");
+/**
+ * How executeAndTrack rejects once anything has been sent or signed (an approval, the swap, a
+ * signature handed to RAVN), and on any abort or timeout: `partial` carries every hash, so the
+ * swap is never lost. Keep polling getStatus(partial.quoteToken, partial.statusRef,
+ * partial.statusTxHash). Before anything is sent, errors come as they are (a RavnApiError from
+ * execute, the wallet's own rejection).
+ */
+class ExecuteAndTrackError extends Error {
+    constructor(message, 
+    /** "ABORTED": your signal. "TIMEOUT": maxWaitMs passed. "FAILED": anything else; see `cause`. */
+    code, partial, cause) {
+        super(message);
+        this.code = code;
+        this.partial = partial;
+        this.name = "ExecuteAndTrackError";
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+exports.ExecuteAndTrackError = ExecuteAndTrackError;
 const BITCOIN_CHAIN_ID = -1;
 const SOLANA_CHAIN_ID = -2;
 const EVM_TX_HASH = /^0x[0-9a-fA-F]{64}$/;
+// What a sandbox status poll is sent as ref when there's no tx hash: RAVN doesn't read it.
+const SANDBOX_REF = "sandbox";
+const EXPIRED_POLL_INTERVAL_MS = 60000;
+const MAX_BACKOFF_MS = 60000;
+// ponytail: a fixed cap, ~4 min of backoff at the default interval; past it the call rejects with
+// every hash to resume from. Make it an option if integrators need to ride out longer outages.
+const MAX_ATTEMPTS = 8;
+// An execute asked again with its Idempotency-Key: ~30 s at the default interval, so a call that
+// can't get through fails in about that rather than four minutes.
+const EXECUTE_ATTEMPTS = 4;
 /** The fee payment a DEPOSIT execution asks for beside its deposit; undefined when it has none. */
 function depositFeePayment(execution) {
     if (execution.executionType !== "DEPOSIT" || !execution.fee)
@@ -21,145 +53,339 @@ function depositFeePayment(execution) {
 }
 // Only a receipt that says success (viem "success", ethers 1; web3.js 1n/true, so == on purpose) and
 // is `hash`'s own (viem/ethers v5 transactionHash, ethers v6 hash): viem resolves a cancelled swap
-// with the replacement's successful receipt.
+// with the replacement's successful receipt. Typed unknown: JS callers can still hand it anything.
 const receiptSucceeded = (receipt, hash) => {
     const r = receipt;
     const own = r?.transactionHash ?? r?.hash;
     return (r?.status === "success" || r?.status == 1) && (typeof own !== "string" || own.toLowerCase() === hash.toLowerCase());
 };
+// The same call can succeed later: no response at all, a 429, or a 5xx.
+const transient = (err) => err instanceof types_1.RavnApiError && (err.code === "NETWORK_ERROR" || err.status === 429 || (err.status ?? 0) >= 500);
+// Refused before anything was done, so safe to repeat even a call that isn't safe to repeat after
+// a BUILD_FAILED (submit-signature: the venue may have taken the order).
+const rateLimited = (err) => err instanceof types_1.RavnApiError && (err.code === "RATE_LIMITED" || err.code === "VENUE_RATE_LIMITED" || err.status === 429);
+// An execute sent with an Idempotency-Key answers a repeat with its first answer, so one whose answer
+// was lost (no response, a gateway timeout) or is still being built (UNAVAILABLE) can be asked again.
+// Never a BUILD_FAILED (re-quote) or an unexpected error, which may have half-built an order.
+const answerLost = (err) => rateLimited(err) ||
+    (err instanceof types_1.RavnApiError && (err.code === "NETWORK_ERROR" || err.code === "UNAVAILABLE" || err.status === 504));
+// `promise`, or the signal's reason as soon as it aborts: a wallet or custom fetch may ignore the
+// signal. `promise` is always handled, so one that rejects after the abort is never unhandled.
+const orAbort = (promise, signal) => new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    // Promise.resolve: a JS handler may hand back the value itself rather than a promise.
+    Promise.resolve(promise).then((value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+    }, (err) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(err);
+    });
+    if (signal.aborted)
+        return onAbort();
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(signal.reason);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+});
 /**
  * Sequences execute() → approval (if any) → wait for its receipt → main tx/signature → RAVN's fee
  * payment (if any) → 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.
+ * has confirmed. A failed API call is retried where repeating it is safe (status polls and
+ * submitTransaction on a 429, 5xx or no response; execute, sent with an Idempotency-Key, also when its
+ * answer was lost or is still being built, up to 4 tries; submitSignature only when rate limited),
+ * waiting the API's retryAfterSec. Once anything
+ * is sent, it rejects only with an ExecuteAndTrackError carrying every hash; `onProgress` hears
+ * each one first.
  */
 async function executeAndTrack(client, params, handlers, options = {}) {
-    const { pollUntilTerminal = true, pollIntervalMs = 4000 } = options;
-    const execution = await client.execute(params);
-    const { quoteToken } = execution;
-    const pollStatus = async (ref, txHash, feeSent = false) => {
-        if (!pollUntilTerminal)
-            return undefined;
-        // A success answered before RAVN's node sees the fee tx proves nothing, and the row is then
-        // left to a cron that books no fee: one more poll after it.
-        // ponytail: one re-poll covers a block of lag; the real fix is /v1/status staying non-terminal
-        // while a given fee tx is unproven.
-        for (let recheck = feeSent;;) {
-            const status = await client.getStatus(quoteToken, ref, txHash);
-            if ((0, polling_1.isPollingTerminal)(status.status)) {
-                if (!recheck || status.status !== "success")
-                    return status;
-                recheck = false;
-            }
-            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    const { pollUntilTerminal = true, pollIntervalMs = 4000, expiredPollIntervalMs = EXPIRED_POLL_INTERVAL_MS, maxWaitMs } = options;
+    const partial = {};
+    let sent = false;
+    const report = (stage, fields) => {
+        Object.assign(partial, fields);
+        try {
+            // An async hook (a database write) may reject: handled here too, never unhandled.
+            Promise.resolve(options.onProgress?.({ stage, partial: { ...partial } })).catch(() => { });
+        }
+        catch {
+            // The swap is out either way: a failing progress hook must not stop its fee or tracking.
         }
     };
-    // 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;
+    // One signal for everything that waits: the caller's abort, or maxWaitMs once polling starts.
+    const stop = new AbortController();
+    let stopCode;
+    const halt = (code, reason) => {
+        if (stop.signal.aborted)
+            return;
+        stopCode = code;
+        stop.abort(reason);
     };
-    if (execution.executionType === "TRANSACTION" && execution.submit) {
-        // Never broadcast this one ourselves: a payment Layerswap can't match sits at Layerswap, and
-        // RAVN's check before sending is what catches it.
-        if (!handlers.signSolanaTransaction) {
-            throw new Error("executeAndTrack: this execution must be submitted through RAVN and requires signSolanaTransaction, none was provided");
-        }
-        if (!execution.transaction.serialized) {
-            throw new Error("executeAndTrack: TRANSACTION execution with submit is missing transaction.serialized");
+    const onAbort = () => halt("ABORTED", options.signal?.reason);
+    if (options.signal?.aborted)
+        onAbort();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    let deadline;
+    // Before each step that asks the wallet for something: never send once stopped.
+    const checkpoint = () => {
+        if (stop.signal.aborted)
+            throw stop.signal.reason;
+    };
+    // Calls `call` until it succeeds, fails in a way `retryable` says repeating can't fix, or
+    // `attempts`: waiting the API's retryAfterSec, else an interval doubling from pollIntervalMs.
+    const withRetries = async (call, retryable, attempts = MAX_ATTEMPTS) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await call();
+            }
+            catch (err) {
+                if (attempt >= attempts || !retryable(err))
+                    throw err;
+                const askedMs = (err.retryAfterSec ?? 0) * 1000;
+                await sleep(Math.max(askedMs, Math.min(pollIntervalMs * 2 ** (attempt - 1), MAX_BACKOFF_MS)), stop.signal);
+            }
         }
-        const signedTransaction = await handlers.signSolanaTransaction(execution.transaction.serialized);
-        const { txHash } = await client.submitTransaction({ quoteToken, signedTransaction });
-        const statusRef = execution.statusRef ?? txHash;
-        return { execution, quoteToken, txHash, statusRef, finalStatus: await pollStatus(statusRef) };
-    }
-    if (execution.executionType === "TRANSACTION") {
-        const approvalTxHash = await maybeSendApproval(execution.approval);
-        // RAVN's fee, when the route has none of its own (Eco, Layerswap, Mayan plain MCTP). From
-        // Solana there's nothing to send: it's a transfer inside transaction.serialized.
-        const feeTx = execution.fee?.transaction;
-        let txHash;
-        let feeTxHash;
-        let feeError;
-        if (feeTx && BigInt(feeTx.value) === 0n && handlers.sendCalls) {
-            // A token fee may ride in the swap's own confirmation: atomic, so it never outlives a swap
-            // that reverted. One hash back means one transaction carried both.
-            const [swapHash, feeHash = swapHash] = await handlers.sendCalls([execution.transaction, feeTx]);
-            if (!swapHash)
-                throw new Error("executeAndTrack: sendCalls returned no transaction hash");
-            txHash = swapHash;
-            feeTxHash = feeHash;
+    };
+    const run = async () => {
+        checkpoint();
+        // One Idempotency-Key for every try, so a repeat can't open a second order at the venue (a NEAR
+        // deposit address, a Houdini or Garden order). Without one (no crypto.randomUUID), only a rate
+        // limit is repeated. A BUILD_FAILED wants a fresh quote either way.
+        const key = params.idempotencyKey ?? globalThis.crypto?.randomUUID?.();
+        const execution = await withRetries(() => orAbort(client.execute({ ...params, ...(key ? { idempotencyKey: key } : {}) }), stop.signal), key ? answerLost : rateLimited, key ? EXECUTE_ATTEMPTS : MAX_ATTEMPTS);
+        const { quoteToken } = execution;
+        Object.assign(partial, { execution, quoteToken, statusRef: execution.statusRef });
+        const pollStatus = async (ref, txHash, feeSent = false) => {
+            if (!pollUntilTerminal)
+                return undefined;
+            if (maxWaitMs !== undefined) {
+                deadline = setTimeout(() => halt("TIMEOUT", new Error(`executeAndTrack: no terminal status within maxWaitMs (${maxWaitMs} ms)`)), maxWaitMs);
+            }
+            // A success answered before RAVN's node sees the fee tx proves nothing, and the row is then
+            // left to a cron that books no fee: one more poll after it.
+            // ponytail: one re-poll covers a block of lag; /v1/status also stays "processing" while a
+            // reported fee tx is unreadable (ravn-mvp #411).
+            for (let recheck = feeSent;;) {
+                checkpoint();
+                const status = await withRetries(() => orAbort(client.getStatus(quoteToken, ref, txHash, { signal: stop.signal }), stop.signal), transient);
+                report("status", { lastStatus: status });
+                if ((0, polling_1.isPollingTerminal)(status.status)) {
+                    if (!recheck || status.status !== "success")
+                        return status;
+                    recheck = false;
+                }
+                await sleep(status.status === "expired" ? expiredPollIntervalMs : pollIntervalMs, stop.signal);
+            }
+        };
+        // A sandbox execution is never real, but a venue with no sandbox stand-in returns its live
+        // payload: nothing in it is signed or sent (a signed order or Solana payment is a live
+        // instrument even though RAVN drops it). RAVN answers its status synthetically, for any ref.
+        if (execution.sandbox && execution.executionType !== "DEPOSIT") {
+            const statusRef = execution.statusRef ?? SANDBOX_REF;
+            return { execution, quoteToken, statusRef, finalStatus: await pollStatus(statusRef) };
         }
-        else {
-            txHash = await handlers.sendTransaction(execution.transaction);
-            if (feeTx) {
-                // On its own, only once the swap has confirmed: a reverted, dropped or replaced one pays
-                // no fee. Declined or failed, the swap still runs and is tracked; no fee is owed on it.
+        // The approval to send, if any: none when the caller already knows it's covered (see
+        // ExecuteAndTrackHandlers.hasAllowance).
+        const neededApproval = async (approval) => approval && !(handlers.hasAllowance && (await orAbort(handlers.hasAllowance(approval), stop.signal))) ? approval : undefined;
+        // Sends and confirms it, after its reset (approve to 0) when the token needs one first.
+        const maybeSendApproval = async (approval) => {
+            const needed = await neededApproval(approval);
+            if (!needed)
+                return undefined;
+            let hash = "";
+            for (const tx of needed.reset ? [{ ...needed.reset, chainId: needed.chainId }, needed] : [needed]) {
+                checkpoint();
+                hash = await handlers.sendTransaction(tx);
+                sent = true;
+                if (tx === needed)
+                    report("approval_sent", { approvalTxHash: hash });
+                else
+                    report("reset_sent", { resetTxHash: hash });
+                await orAbort(handlers.waitForReceipt(hash, needed.chainId), stop.signal);
+            }
+            return hash;
+        };
+        if (execution.executionType === "TRANSACTION" && execution.submit) {
+            // Never broadcast this one ourselves: a payment Layerswap can't match sits at Layerswap, and
+            // RAVN's check before sending is what catches it.
+            if (!handlers.signSolanaTransaction) {
+                throw new Error("executeAndTrack: this execution must be submitted through RAVN and requires signSolanaTransaction, none was provided");
+            }
+            if (!execution.transaction.serialized) {
+                throw new Error("executeAndTrack: TRANSACTION execution with submit is missing transaction.serialized");
+            }
+            const serialized = execution.transaction.serialized;
+            checkpoint();
+            const signedTransaction = await handlers.signSolanaTransaction(serialized);
+            checkpoint();
+            // From here RAVN may have sent it, even on a failed call. A retry with the same signed
+            // transaction never sends it twice, so retrying is how to find out; a failure that names
+            // the signature (BUILD_FAILED's details.txHash) is kept too.
+            sent = true;
+            report("swap_signed", { signedTransaction });
+            const submit = async () => {
                 try {
-                    if (!receiptSucceeded(await handlers.waitForReceipt(txHash, execution.transaction.chainId), txHash)) {
-                        throw new Error("executeAndTrack: no successful receipt for the swap transaction itself, so RAVN's fee was not sent");
-                    }
-                    feeTxHash = await handlers.sendTransaction(feeTx);
-                    // Confirmed before polling starts: a swap that fills first would otherwise end the
-                    // polling on the one poll that had to prove the fee.
-                    await handlers.waitForReceipt(feeTxHash, feeTx.chainId);
+                    return await client.submitTransaction({ quoteToken, signedTransaction });
                 }
                 catch (err) {
-                    feeError = err;
+                    const named = err instanceof types_1.RavnApiError ? err.details?.txHash : undefined;
+                    if (typeof named === "string")
+                        Object.assign(partial, { txHash: named, statusRef: execution.statusRef ?? named });
+                    throw err;
                 }
-            }
+            };
+            const { txHash } = await withRetries(submit, transient);
+            const statusRef = execution.statusRef ?? txHash;
+            report("swap_sent", { txHash, statusRef });
+            return { execution, quoteToken, txHash, statusRef, finalStatus: await pollStatus(statusRef) };
         }
-        const statusRef = execution.statusRef ?? txHash;
-        // What proves the fee, from the first poll on: its own transaction, else (a statusRef: a
-        // two-hop route) hop 1's. Only an EVM tx hash: /v1/status refuses anything else (a Solana
-        // signature, a batch id) on every poll.
-        const proof = feeTxHash ?? (execution.statusRef ? txHash : undefined);
-        const statusTxHash = proof && EVM_TX_HASH.test(proof) ? proof : undefined;
-        if (feeTxHash && !statusTxHash) {
-            feeError ?? (feeError = new Error(`executeAndTrack: ${feeTxHash} is not an on-chain transaction hash, so RAVN can't prove the fee`));
+        if (execution.executionType === "TRANSACTION") {
+            // RAVN's fee, when the route has none of its own (Eco, Layerswap, Mayan plain MCTP). From
+            // Solana there's nothing to send: it's a transfer inside transaction.serialized.
+            const { approval, transaction } = execution;
+            const feeTx = execution.fee?.transaction;
+            // What proves the fee, from the first poll on: its own transaction, else (a statusRef: a
+            // two-hop route) hop 1's. Only an EVM tx hash: /v1/status refuses anything else (a Solana
+            // signature, a batch id) on every poll.
+            const proof = (swapHash, feeHash) => {
+                const hash = feeHash ?? (execution.statusRef ? swapHash : undefined);
+                return hash && EVM_TX_HASH.test(hash) ? hash : undefined;
+            };
+            let txHash;
+            let feeTxHash;
+            let feeError;
+            if (feeTx && BigInt(feeTx.value) === 0n && handlers.sendCalls) {
+                // A token fee may ride in the swap's own confirmation, and the swap's approval with it:
+                // atomic, so neither outlives a swap that reverted. Only here: ExecutionDTO doesn't name
+                // its venue, and the first-party app never batches THORChain (Bifrost ignores a router
+                // deposit whose tx.to is the user's own 7702 account) or Bebop (its settlement needs gas
+                // headroom a batch leaves to the wallet); fee-beside routes are neither.
+                const batchApproval = await neededApproval(approval);
+                const reset = batchApproval?.reset && { ...batchApproval.reset, chainId: batchApproval.chainId };
+                const approvals = batchApproval ? [...(reset ? [reset] : []), batchApproval] : [];
+                checkpoint();
+                const hashes = await handlers.sendCalls([...approvals, transaction, feeTx]);
+                // The wallet resolved, so something may be out: from here an error carries what's known.
+                sent = true;
+                // Fewer hashes back than calls: the last one carried the rest.
+                const carrier = (i) => hashes[Math.min(i, hashes.length - 1)];
+                if (!carrier(0))
+                    throw new Error("executeAndTrack: sendCalls returned no transaction hash");
+                txHash = carrier(approvals.length);
+                feeTxHash = carrier(approvals.length + 1);
+                if (reset)
+                    report("reset_sent", { resetTxHash: carrier(0) });
+                if (batchApproval)
+                    report("approval_sent", { approvalTxHash: carrier(approvals.length - 1) });
+                report("swap_sent", { txHash, statusRef: execution.statusRef ?? txHash, statusTxHash: proof(txHash) });
+                report("fee_sent", { feeTxHash, statusTxHash: proof(txHash, feeTxHash) });
+            }
+            else {
+                await maybeSendApproval(approval);
+                checkpoint();
+                txHash = await handlers.sendTransaction(transaction);
+                sent = true;
+                report("swap_sent", { txHash, statusRef: execution.statusRef ?? txHash, statusTxHash: proof(txHash) });
+                if (feeTx) {
+                    // On its own, only once the swap has confirmed: a reverted, dropped or replaced one pays
+                    // no fee. Declined or failed (or stopped first), the swap still runs and is tracked; no
+                    // fee is owed on it.
+                    try {
+                        if (!receiptSucceeded(await orAbort(handlers.waitForReceipt(txHash, transaction.chainId), stop.signal), txHash)) {
+                            throw new Error("executeAndTrack: no successful receipt for the swap transaction itself, so RAVN's fee was not sent");
+                        }
+                        checkpoint();
+                        feeTxHash = await handlers.sendTransaction(feeTx);
+                        report("fee_sent", { feeTxHash, statusTxHash: proof(txHash, feeTxHash) });
+                        // Confirmed before polling starts: a swap that fills first would otherwise end the
+                        // polling on the one poll that had to prove the fee.
+                        await orAbort(handlers.waitForReceipt(feeTxHash, feeTx.chainId), stop.signal);
+                    }
+                    catch (err) {
+                        feeError = err;
+                    }
+                }
+            }
+            // Stopped before or during the fee: say so, even with polling off (no fee was sent on it).
+            checkpoint();
+            const statusRef = execution.statusRef ?? txHash;
+            const statusTxHash = proof(txHash, feeTxHash);
+            if (feeTxHash && !statusTxHash) {
+                feeError ?? (feeError = new Error(`executeAndTrack: ${feeTxHash} is not an on-chain transaction hash, so RAVN can't prove the fee`));
+            }
+            partial.feeError = feeError;
+            return {
+                execution, quoteToken, resetTxHash: partial.resetTxHash, approvalTxHash: partial.approvalTxHash, txHash, statusRef, statusTxHash, feeTxHash, feeError,
+                finalStatus: await pollStatus(statusRef, statusTxHash, !!feeTxHash && !!statusTxHash),
+            };
         }
-        return {
-            execution, quoteToken, approvalTxHash, txHash, statusRef, statusTxHash, feeTxHash, feeError,
-            finalStatus: await pollStatus(statusRef, statusTxHash, !!feeTxHash && !!statusTxHash),
-        };
-    }
-    if (execution.executionType === "SIGNATURE") {
-        if (!handlers.signTypedData) {
-            throw new Error("executeAndTrack: this execution requires signTypedData, none was provided");
+        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);
+            checkpoint();
+            // Called as methods: a class-instance wallet needs its `this`.
+            const approvalSignature = execution.approvalData ? await handlers.signTypedData(execution.approvalData) : undefined;
+            checkpoint();
+            const signature = await handlers.signTypedData(execution.typedData);
+            checkpoint();
+            // From here the venue may take the order even when the call fails (BUILD_FAILED, no answer),
+            // so only a rate limit, refused before anything was placed, is retried.
+            sent = true;
+            report("swap_signed", { signature });
+            const { statusRef } = await withRetries(() => client.submitSignature({ quoteToken, signature, approvalSignature }), rateLimited);
+            report("swap_sent", { statusRef });
+            return { execution, quoteToken, resetTxHash: partial.resetTxHash, approvalTxHash, statusRef, finalStatus: await pollStatus(statusRef) };
         }
-        if (!execution.typedData) {
-            throw new Error("executeAndTrack: SIGNATURE execution is missing typedData");
+        // 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. Pay
+        // `feePayment` as it says, pass an EVM fee transaction's hash as getStatus's `txHash`, and poll
+        // RAVN to a terminal status even if the venue's own tracker says delivered first.
+        // A fee it can't describe never stops the deposit, which fills without it.
+        checkpoint();
+        try {
+            return { execution, quoteToken, statusRef: execution.statusRef, feePayment: depositFeePayment(execution) };
         }
-        // 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);
+        catch (feeError) {
+            return { execution, quoteToken, statusRef: execution.statusRef, feeError };
         }
-        const signature = await handlers.signTypedData(execution.typedData);
-        const { statusRef } = await client.submitSignature({ quoteToken, signature, approvalSignature });
-        return { execution, quoteToken, 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. Pay
-    // `feePayment` as it says, pass an EVM fee transaction's hash as getStatus's `txHash`, and poll
-    // RAVN to a terminal status even if the venue's own tracker says delivered first.
-    // A fee it can't describe never stops the deposit, which fills without it.
+    };
     try {
-        return { execution, quoteToken, statusRef: execution.statusRef, feePayment: depositFeePayment(execution) };
+        return await run();
+    }
+    catch (err) {
+        if (stopCode) {
+            const why = stopCode === "ABORTED" ? "aborted" : `no terminal status within maxWaitMs (${maxWaitMs} ms)`;
+            throw new ExecuteAndTrackError(`executeAndTrack: ${why}`, stopCode, { ...partial }, stop.signal.reason);
+        }
+        if (!sent)
+            throw err;
+        const why = err instanceof Error ? err.message : String(err);
+        throw new ExecuteAndTrackError(`executeAndTrack: ${why}`, "FAILED", { ...partial }, err);
     }
-    catch (feeError) {
-        return { execution, quoteToken, statusRef: execution.statusRef, feeError };
+    finally {
+        clearTimeout(deadline);
+        options.signal?.removeEventListener("abort", onAbort);
     }
 }

package/dist/index.d.ts

@@ -2,5 +2,5 @@ export { RavnClient } from "./client";
 export type { RavnClientConfig } from "./client";
 export * from "./types";
 export { isPollingTerminal } from "./polling";
-export { depositFeePayment, executeAndTrack } from "./execute-and-track";
-export type { ExecuteAndTrackHandlers, ExecuteAndTrackOptions, ExecuteAndTrackResult, DepositFeePayment, } from "./execute-and-track";
+export { depositFeePayment, executeAndTrack, ExecuteAndTrackError } from "./execute-and-track";
+export type { ExecuteAndTrackHandlers, ExecuteAndTrackOptions, ExecuteAndTrackPartial, ExecuteAndTrackProgress, ExecuteAndTrackResult, ExecuteAndTrackStage, DepositFeePayment, TransactionReceiptLike, } from "./execute-and-track";

package/dist/index.js

@@ -14,7 +14,7 @@ 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.depositFeePayment = exports.isPollingTerminal = exports.RavnClient = void 0;
+exports.ExecuteAndTrackError = exports.executeAndTrack = exports.depositFeePayment = 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);
@@ -23,3 +23,4 @@ Object.defineProperty(exports, "isPollingTerminal", { enumerable: true, get: fun
 var execute_and_track_1 = require("./execute-and-track");
 Object.defineProperty(exports, "depositFeePayment", { enumerable: true, get: function () { return execute_and_track_1.depositFeePayment; } });
 Object.defineProperty(exports, "executeAndTrack", { enumerable: true, get: function () { return execute_and_track_1.executeAndTrack; } });
+Object.defineProperty(exports, "ExecuteAndTrackError", { enumerable: true, get: function () { return execute_and_track_1.ExecuteAndTrackError; } });

package/dist/polling.d.ts

@@ -1,7 +1,12 @@
 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.
+ * Whether a status is done changing: "success", "refunded" and "failed", RAVN's own final states,
+ * plus "unknown", which isn't a real outcome but means the venue has no live tracker (see
+ * StatusDTO.tracking), so it will never change and polling forever would just spin. Everything
+ * else keeps polling: "expired" means the deal lapsed and a refund is due but hasn't landed
+ * (Across returns it in a later settlement bundle, hours on; poll it on a longer interval), and
+ * "not_found" that the venue has no record of this swap: brief right after sending (Relay indexes
+ * seconds behind the chain), otherwise permanent (the fill found isn't this quote's swap). RAVN
+ * keeps watching both; bound your own polling (executeAndTrack's maxWaitMs or signal).
  */
 export declare function isPollingTerminal(status: SettlementStatus): boolean;

package/dist/polling.js

@@ -2,10 +2,15 @@
 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.
+ * Whether a status is done changing: "success", "refunded" and "failed", RAVN's own final states,
+ * plus "unknown", which isn't a real outcome but means the venue has no live tracker (see
+ * StatusDTO.tracking), so it will never change and polling forever would just spin. Everything
+ * else keeps polling: "expired" means the deal lapsed and a refund is due but hasn't landed
+ * (Across returns it in a later settlement bundle, hours on; poll it on a longer interval), and
+ * "not_found" that the venue has no record of this swap: brief right after sending (Relay indexes
+ * seconds behind the chain), otherwise permanent (the fill found isn't this quote's swap). RAVN
+ * keeps watching both; bound your own polling (executeAndTrack's maxWaitMs or signal).
  */
 function isPollingTerminal(status) {
-    return status !== "pending" && status !== "processing";
+    return status === "success" || status === "refunded" || status === "failed" || status === "unknown";
 }

package/dist/types.d.ts

@@ -31,7 +31,12 @@ export interface QuoteDTO {
         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. */
+     * way); distinct from `supported: true, bps: 0`, a real, intentional zero fee. On NEAR Intents
+     * `bps`/`amount` include 1Click's own fee, taken from the input on every swap with or without
+     * yours (the output already reflects it): 20 bps with no fee set (1 bp when both tokens are
+     * USDC, USDT or DAI, or the same asset), with yours half of it plus the larger of that half and
+     * 20 (1) bps, and its 20 (1) bps on top of RAVN's own fee beside a private swap: NEAR never
+     * shows `bps: 0`. */
     fee: {
         bps: number;
         amount: string;
@@ -132,9 +137,22 @@ export interface ApprovalDTO {
     spender?: string;
     amount: string;
     unlimitedRecommended?: boolean;
+    /** Send this first and wait for it to be mined, then the approval: `approve(spender, 0)`. Only on
+     * a token whose approve reverts on a change from one non-zero allowance to another (Ethereum
+     * USDT) when the sender holds a partial one. executeAndTrack does this. */
+    reset?: {
+        to: string;
+        data: string;
+        value: string;
+    };
 }
 export type ExecutionDTO = {
     executionType: "TRANSACTION";
+    /** True for a sandbox quote: nothing here is real (see GetQuoteParams.sandbox); never send
+     * it. executeAndTrack broadcasts nothing for one. */
+    sandbox?: true;
+    /** This swap's id in RAVN's ledger: settlement webhooks name it (`swapId`). Absent on a sandbox quote. */
+    swapId?: string;
     /** Pass this, not the quote's own token, to getStatus. Compose: the post-bind token. */
     quoteToken: string;
     /** The venue's own tracking key (compose hop-2 handle, Garden order id, Relay request id).
@@ -172,6 +190,11 @@ export type ExecutionDTO = {
     fee?: DepositFeeDTO;
 } | {
     executionType: "SIGNATURE";
+    /** True for a sandbox quote: nothing here is real (see GetQuoteParams.sandbox); never send
+     * it. executeAndTrack broadcasts nothing for one. */
+    sandbox?: true;
+    /** This swap's id in RAVN's ledger: settlement webhooks name it (`swapId`). Absent on a sandbox quote. */
+    swapId?: string;
     /** Pass this, not the quote's own token, to submitSignature and getStatus. */
     quoteToken: string;
     statusRef?: string;
@@ -184,6 +207,11 @@ export type ExecutionDTO = {
     };
 } | {
     executionType: "DEPOSIT";
+    /** True for a sandbox quote: nothing here is real (see GetQuoteParams.sandbox); never send
+     * it. executeAndTrack broadcasts nothing for one. */
+    sandbox?: true;
+    /** This swap's id in RAVN's ledger: settlement webhooks name it (`swapId`). Absent on a sandbox quote. */
+    swapId?: string;
     /** Pass this, not the quote's own token, to getStatus. */
     quoteToken: string;
     /** `expiresAt` (ISO 8601), when set, is when the deposit must have ARRIVED (confirmed on
@@ -268,6 +296,11 @@ export interface GetQuoteParams {
      * carry slippage.noMinimum: true and guaranteedMin: null; slippageBps does not protect them. */
     allowNoMinimum?: boolean;
     rankingMode?: "best_output" | "fastest";
+    /** The race's time limit in ms, counted from its start: once it has passed and some venue has
+     * priced the swap, slower venues are left out (with none priced yet, the first price ends the
+     * wait; a quote with slippage.noMinimum counts only 2000 ms past the limit). A positive integer;
+     * default 6000, clamped to 1000–15000. An API that predates it ignores it. */
+    timeoutMs?: number;
     /** Drop specific venues from this race, e.g. a risk objection to one of them. */
     excludeVenues?: string[];
     /** Race only these venues, e.g. ["bebop"] for an RFQ-only race. Every other venue is left
@@ -307,6 +340,11 @@ export interface ExecuteParams {
     refundAddress?: string;
     /** Your end user's IANA timezone, forwarded only to Houdini. Default UTC. */
     clientTimezone?: string;
+    /** Sent as the Idempotency-Key header: any unique value per swap attempt (e.g. a UUID), 1–255
+     * printable ASCII characters, no spaces (execute throws INVALID_REQUEST otherwise). Calling execute again with the same key and request (quoteToken and any addresses) within a day
+     * returns the first answer instead of building again (at a deposit venue, a second deposit
+     * address). executeAndTrack sends one itself when you don't. */
+    idempotencyKey?: string;
 }
 export interface SubmitSignatureParams {
     quoteToken: string;
@@ -323,10 +361,25 @@ export interface ErrorMeta {
     requestId: string;
     version: string;
 }
-/** Thrown for every non-2xx response. `code` is the stable, machine-readable string from the API. */
+/** Every `code` the API sends (see the API's Errors page), plus NETWORK_ERROR: no response came
+ * back at all (offline, DNS, CORS, a dropped connection). New codes can appear: compare against
+ * these, don't switch on them exhaustively. */
+export type RavnErrorCode = "INVALID_REQUEST" | "UNSUPPORTED_TOKEN" | "UNSUPPORTED_CHAIN" | "NO_LIQUIDITY" | "QUOTE_EXPIRED" | "QUOTE_INVALID" | "QUOTE_NOT_EXECUTABLE" | "RATE_LIMITED" | "UNAUTHORIZED" | "NOT_CONFIGURED" | "NOT_FOUND" | "BUILD_FAILED" | "VENUE_RATE_LIMITED" | "UNAVAILABLE" | "ORDER_REJECTED" | "INTERNAL" | "NETWORK_ERROR";
+/** Thrown for every failed call: a non-2xx response, or none at all (NETWORK_ERROR). `code` is the
+ * stable, machine-readable string from the API. */
 export declare class RavnApiError extends Error {
-    readonly code: string;
+    readonly code: RavnErrorCode | (string & {});
     readonly details: unknown;
     readonly meta: ErrorMeta | undefined;
-    constructor(code: string, message: string, details: unknown, meta: ErrorMeta | undefined);
+    /** The HTTP status; undefined when no response came back (NETWORK_ERROR). */
+    readonly status?: number;
+    /** Seconds the API asked you to wait before trying the same call again (`details.retryAfterSec`,
+     * sent with RATE_LIMITED, VENUE_RATE_LIMITED and UNAVAILABLE). */
+    readonly retryAfterSec?: number;
+    /** NETWORK_ERROR: the fetch error underneath. */
+    readonly cause?: unknown;
+    constructor(code: RavnErrorCode | (string & {}), message: string, details: unknown, meta: ErrorMeta | undefined, init?: {
+        status?: number;
+        cause?: unknown;
+    });
 }

package/dist/types.js

@@ -8,14 +8,20 @@
  */
 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. */
+/** Thrown for every failed call: a non-2xx response, or none at all (NETWORK_ERROR). `code` is the
+ * stable, machine-readable string from the API. */
 class RavnApiError extends Error {
-    constructor(code, message, details, meta) {
+    constructor(code, message, details, meta, init = {}) {
         super(message);
         this.code = code;
         this.details = details;
         this.meta = meta;
         this.name = "RavnApiError";
+        this.status = init.status;
+        const retryAfterSec = details?.retryAfterSec;
+        this.retryAfterSec = typeof retryAfterSec === "number" ? retryAfterSec : undefined;
+        if (init.cause !== undefined)
+            this.cause = init.cause;
     }
 }
 exports.RavnApiError = RavnApiError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ravnexchange/sdk",
-  "version": "0.1.15",
+  "version": "0.2.1",
   "description": "Typed client for the RAVN integrator API (/api/v1): quote, execute, submit-signature, status.",
   "keywords": ["ravn", "cross-chain", "swap", "swap-api", "dex-aggregator", "bitcoin", "native-btc", "solana", "evm", "crypto", "defi", "typescript", "sdk", "api-client"],
   "main": "./dist/index.js",