@ravnexchange/sdk 0.1.6 → 0.1.8

package/dist/client.d.ts

@@ -21,7 +21,9 @@ export declare class RavnClient {
     submitSignature(params: SubmitSignatureParams): Promise<{
         statusRef: string;
     }>;
-    /** GET /v1/status: `ref` is the DEPOSIT address or the statusRef from submitSignature. */
+    /** POST /v1/status: pass the quoteToken execute() returned (not the quote's own), and as `ref`
+     * 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. */
     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[]>;

package/dist/client.js

@@ -51,10 +51,14 @@ class RavnClient {
             body: JSON.stringify(params),
         });
     }
-    /** GET /v1/status: `ref` is the DEPOSIT address or the statusRef from submitSignature. */
+    /** POST /v1/status: pass the quoteToken execute() returned (not the quote's own), and as `ref`
+     * 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. */
     getStatus(quoteToken, ref) {
-        const qs = new URLSearchParams({ quoteToken, ref }).toString();
-        return this.request(`/status?${qs}`, { method: "GET" });
+        return this.request("/status", {
+            method: "POST",
+            body: JSON.stringify({ quoteToken, ref }),
+        });
     }
     /** GET /v1/tokens: RAVN's listed token registry for one chain. Not a per-pair routability guarantee. */
     getTokens(chainId) {

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

@@ -37,7 +37,11 @@ export interface ExecuteAndTrackResult {
     execution: ExecutionDTO;
     approvalTxHash?: string;
     txHash?: string;
-    /** Pass to client.getStatus(quoteToken, ref): same value as txHash for TRANSACTION. */
+    /** Pass to client.getStatus(quoteToken, statusRef). Same as `execution.quoteToken`, NOT the
+     * quote's own token: on compose (2-hop) quotes execute rebinds hop 1 onto hop 2's deposit. */
+    quoteToken: string;
+    /** Pass to client.getStatus(quoteToken, statusRef). For TRANSACTION, the execution's own
+     * statusRef when it has one (compose, Garden, Relay), else txHash: not always a tx hash. */
     statusRef?: string;
     /** Set once pollUntilTerminal reaches a terminal status. Absent for DEPOSIT (see below) or when polling is turned off. */
     finalStatus?: StatusDTO;

package/dist/execute-and-track.js

@@ -11,11 +11,12 @@ const polling_1 = require("./polling");
 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) => {
         if (!pollUntilTerminal)
             return undefined;
         for (;;) {
-            const status = await client.getStatus(params.quoteToken, ref);
+            const status = await client.getStatus(quoteToken, ref);
             if ((0, polling_1.isPollingTerminal)(status.status))
                 return status;
             await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
@@ -35,7 +36,8 @@ async function executeAndTrack(client, params, handlers, options = {}) {
     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) };
+        const statusRef = execution.statusRef ?? txHash;
+        return { execution, quoteToken, approvalTxHash, txHash, statusRef, finalStatus: await pollStatus(statusRef) };
     }
     if (execution.executionType === "SIGNATURE") {
         if (!handlers.signTypedData) {
@@ -54,11 +56,11 @@ async function executeAndTrack(client, params, handlers, options = {}) {
             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) };
+        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.
-    return { execution, statusRef: execution.statusRef };
+    return { execution, quoteToken, statusRef: execution.statusRef };
 }

package/dist/types.d.ts

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * its own and can't depend on the app's internal source tree. The app type-checks this copy
+ * against its own DTOs (dto-sdk-parity.ts), so a change on either side that isn't mirrored here
+ * fails the app's build.
  */
 export interface TokenDTO {
     symbol: string;
@@ -40,11 +40,7 @@ export interface QuoteDTO {
     };
     /** 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;
+    slippage: SlippageDTO | null;
     gas: {
         native: string;
         nativeSymbol: string;
@@ -57,6 +53,12 @@ export interface QuoteDTO {
     estimatedTimeSeconds: number;
     estimatedTimeIsGuess: boolean;
     expiresAt: number;
+    /** Present on 2-hop (`venue.id === "compose"`) and Relay dest-call quotes. Sign hop 1; hop 2 is
+     * a unique deposit, not a second wallet tx. */
+    hops?: {
+        id: string;
+        name: string;
+    }[];
     /** Every other venue that raced and produced a usable quote, best output first. */
     alternatives: AlternativeQuoteDTO[];
 }
@@ -69,14 +71,37 @@ export interface AlternativeQuoteDTO {
     /** Pass to execute() to run THIS route instead of the primary quote. */
     quoteToken: string;
     outputAmount: string;
+    /** `amount` is in `token`'s base units: the output token everywhere except Fly Trade and
+     * Mayan, which deduct their fee from the input token. */
     fee: {
         bps: number;
         amount: string;
+        token: TokenDTO;
         supported: boolean;
     };
     executable: boolean;
     estimatedTimeSeconds: number;
     estimatedTimeIsGuess: boolean;
+    hops?: {
+        id: string;
+        name: string;
+    }[];
+    /** Same as QuoteDTO.slippage: an alternative can be executed, so it needs the same warning. */
+    slippage: SlippageDTO | null;
+}
+/**
+ * The slippage protection on a quote. `isFirm`: a firm RFQ price, no slippage possible.
+ * `guaranteedMin`: the minimum output in the output token's base units, when the venue exposes it.
+ *
+ * `noMinimum: true` means the venue enforces NO minimum output (Rift: it fills at its own best
+ * rate once the deposit lands), so `bps` is not a protection and the user can receive more or
+ * less than the quoted output. Show that to the user before they send funds.
+ */
+export interface SlippageDTO {
+    bps: number;
+    isFirm: boolean;
+    guaranteedMin: string | null;
+    noMinimum: boolean;
 }
 export interface ChainDTO {
     chainId: number;
@@ -101,6 +126,11 @@ export interface ApprovalDTO {
 }
 export type ExecutionDTO = {
     executionType: "TRANSACTION";
+    /** 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).
+     * Poll getStatus with this when present; otherwise use the origin tx hash. */
+    statusRef?: string;
     approval?: ApprovalDTO;
     transaction: {
         to?: string;
@@ -111,6 +141,9 @@ export type ExecutionDTO = {
     };
 } | {
     executionType: "SIGNATURE";
+    /** Pass this, not the quote's own token, to submitSignature and getStatus. */
+    quoteToken: string;
+    statusRef?: string;
     approval?: ApprovalDTO;
     typedData?: Record<string, unknown>;
     approvalData?: Record<string, unknown>;
@@ -120,11 +153,17 @@ export type ExecutionDTO = {
     };
 } | {
     executionType: "DEPOSIT";
+    /** 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
+     * the origin chain) by. A later deposit lands at an expired order. */
     deposit: {
         address: string;
         amount: string;
         chainId?: number;
+        expiresAt?: string;
     };
+    /** Poll getStatus with this, not `deposit.address`. */
     statusRef: string;
 };
 export type SettlementStatus = "pending" | "processing" | "expired" | "success" | "refunded" | "failed" | "not_found" | "unknown";
@@ -153,14 +192,28 @@ export interface GetQuoteParams {
     rankingMode?: "best_output" | "fastest";
     /** Drop specific venues from this race, e.g. a risk objection to one of them. */
     excludeVenues?: string[];
+    /** Settle privately: the race narrows to NEAR Intents (Confidential Intents) and Houdini Swap,
+     * and NO_LIQUIDITY replaces a public fill if neither can quote. Houdini is sent the request's IP,
+     * user-agent and clientTimezone for compliance screening; its terms bar US persons and
+     * sanctioned jurisdictions, and you own your users' eligibility (excludeVenues: ["houdini"]). */
+    confidential?: boolean;
+    /** Your end user's IANA timezone (e.g. "Europe/Berlin"), forwarded only to Houdini. Default UTC. */
+    clientTimezone?: string;
+    /** Optional analytics handle: send the same value while re-pricing one swap so it counts as one
+     * intent. Never affects pricing, routing or fees. Max 64 chars. */
+    quoteSessionId?: string;
     /** Test quote -> execute -> status with no real funds and no live venue settlement. See
      * the API's own sandbox field description for per-venue/per-route exceptions. */
     sandbox?: boolean;
 }
 export interface ExecuteParams {
     quoteToken: string;
+    /** Only venues that bind the recipient at execute (Chainflip, Houdini Swap, Layerswap, Mayan,
+     * NEAR Intents, Rift) accept a new one; elsewhere a different address is INVALID_REQUEST. */
     destinationAddress?: string;
     refundAddress?: string;
+    /** Your end user's IANA timezone, forwarded only to Houdini. Default UTC. */
+    clientTimezone?: string;
 }
 export interface SubmitSignatureParams {
     quoteToken: string;

package/dist/types.js

@@ -2,9 +2,9 @@
 /**
  * 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.
+ * its own and can't depend on the app's internal source tree. The app type-checks this copy
+ * against its own DTOs (dto-sdk-parity.ts), so a change on either side that isn't mirrored here
+ * fails the app's build.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RavnApiError = void 0;

package/package.json

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