@ravnexchange/sdk 0.2.0 → 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;

package/dist/client.js

@@ -57,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) {

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

@@ -189,8 +189,9 @@ export declare function depositFeePayment(execution: ExecutionDTO): DepositFeePa
  * 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. A failed API call is retried where repeating it is safe (status polls and
- * submitTransaction on a 429, 5xx or no response; execute and submitSignature only when rate
- * limited), waiting the API's retryAfterSec. Once anything
+ * 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.
  */

package/dist/execute-and-track.js

@@ -35,6 +35,9 @@ 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)
@@ -61,6 +64,11 @@ const transient = (err) => err instanceof types_1.RavnApiError && (err.code ===
 // 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) => {
@@ -96,8 +104,9 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
  * 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. A failed API call is retried where repeating it is safe (status polls and
- * submitTransaction on a 429, 5xx or no response; execute and submitSignature only when rate
- * limited), waiting the API's retryAfterSec. Once anything
+ * 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.
  */
@@ -135,14 +144,14 @@ async function executeAndTrack(client, params, handlers, options = {}) {
             throw stop.signal.reason;
     };
     // Calls `call` until it succeeds, fails in a way `retryable` says repeating can't fix, or
-    // MAX_ATTEMPTS: waiting the API's retryAfterSec, else an interval doubling from pollIntervalMs.
-    const withRetries = async (call, retryable) => {
+    // `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 >= MAX_ATTEMPTS || !retryable(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);
@@ -151,9 +160,11 @@ async function executeAndTrack(client, params, handlers, options = {}) {
     };
     const run = async () => {
         checkpoint();
-        // Only a rate limit: a BUILD_FAILED wants a fresh quote, and a repeat can open a second order
-        // at the venue (a NEAR deposit address, a Houdini or Garden order).
-        const execution = await withRetries(() => orAbort(client.execute(params), stop.signal), rateLimited);
+        // 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) => {

package/dist/types.d.ts

@@ -151,6 +151,8 @@ export type ExecutionDTO = {
     /** 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).
@@ -191,6 +193,8 @@ export type ExecutionDTO = {
     /** 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;
@@ -206,6 +210,8 @@ export type ExecutionDTO = {
     /** 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
@@ -334,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;
@@ -353,7 +364,7 @@ export interface ErrorMeta {
 /** 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" | "ORDER_REJECTED" | "INTERNAL" | "NETWORK_ERROR";
+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 {
@@ -363,7 +374,7 @@ export declare class RavnApiError extends Error {
     /** 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 and VENUE_RATE_LIMITED). */
+     * sent with RATE_LIMITED, VENUE_RATE_LIMITED and UNAVAILABLE). */
     readonly retryAfterSec?: number;
     /** NETWORK_ERROR: the fetch error underneath. */
     readonly cause?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ravnexchange/sdk",
-  "version": "0.2.0",
+  "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",