@coin-voyage/shared 2.3.4 → 2.3.5-beta.0

package/dist/api/client.d.ts

@@ -2,6 +2,9 @@ import { type PayOrder, PayOrderMode } from "../types";
 import type { ClaimFeesRequest, ClaimFeesResponse, CreateWebhookRequest, GetFeeBalancesResponse, OrderStatusSocket, PaymentDetails, PaymentDetailsParams, PayOrderParams, PayOrderQuoteParams, RouteQuote, SwapDataRequest, SwapDataResponse, SwapQuoteRequest, SwapQuoteResponse, UpdateWebhookRequest, WebhookResponse } from "../types/api";
 import { type APIEnvironment } from "./config";
 import { type APIResponse } from "./fetcher";
+type Opts = {
+    headers?: Record<string, string>;
+};
 export declare class ApiClient {
     private readonly apiKey;
     private readonly environment;
@@ -33,6 +36,7 @@ export declare class ApiClient {
      * Creates a PayOrder of type `DEPOSIT` with the provided parameters.
      *
      * @param {PayOrderParams} params - Parameters required to create a deposit PayOrder.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<PayOrder>>} - The PayOrder object wrapped in an API response if the request is successful.
      *
      * @example
@@ -49,7 +53,7 @@ export declare class ApiClient {
      *   console.log('Deposit PayOrder created:', data);
      * }
      */
-    createDepositPayOrder(params: PayOrderParams): Promise<APIResponse<PayOrder>>;
+    createDepositPayOrder(params: PayOrderParams, opts?: Opts): Promise<APIResponse<PayOrder>>;
     /**
      * Creates a `SALE` PayOrder.
      *
@@ -59,6 +63,7 @@ export declare class ApiClient {
      *
      * @param {SalePayOrderParams} params - Params required to create a sale PayOrder.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request.
      * @returns {Promise<APIResponse<PayOrder>>} - A PayOrder object wrapped in an API response if the request was successful.
      *
      * @example
@@ -89,7 +94,7 @@ export declare class ApiClient {
      *   console.log('Sale PayOrder created:', response.data);
      * }
      */
-    createSalePayOrder(params: PayOrderParams, apiSecret: string): Promise<APIResponse<PayOrder>>;
+    createSalePayOrder(params: PayOrderParams, apiSecret: string, opts?: Opts): Promise<APIResponse<PayOrder>>;
     /**
      * Creates a `REFUND` PayOrder.
      *
@@ -100,6 +105,7 @@ export declare class ApiClient {
      * @param {string} payOrderId - The unique identifier of the PayOrder to be refunded.
      * @param {PayOrderParams} params - Params required to create a refund PayOrder.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request.
      * @returns {Promise<APIResponse<PayOrder>>} - A PayOrder object wrapped in an API response if the request was successful.
      *
      * @example
@@ -130,8 +136,8 @@ export declare class ApiClient {
      *   console.log('Refund PayOrder created:', response.data);
      * }
      */
-    createRefundPayOrder(payOrderId: string, params: PayOrderParams, apiSecret: string): Promise<APIResponse<PayOrder>>;
-    createPayOrder(params: PayOrderParams, mode: PayOrderMode, signature?: string): Promise<APIResponse<PayOrder>>;
+    createRefundPayOrder(payOrderId: string, params: PayOrderParams, apiSecret: string, opts?: Opts): Promise<APIResponse<PayOrder>>;
+    createPayOrder(params: PayOrderParams, mode: PayOrderMode, signature?: string, opts?: Opts): Promise<APIResponse<PayOrder>>;
     /**
      * Generates a PayOrder Quote.
      *
@@ -140,6 +146,7 @@ export declare class ApiClient {
      *
      * @param {string} orderId - The unique identifier of the PayOrder for which the quote is requested.
      * @param {PayOrderQuoteParams} quoteParams - Contains `wallet_address`, `chain_type`, `chain_id`.
+     * @param {Opts} [opts] - Optional parameters for the request.
      * @returns {Promise<APIResponse<RouteQuote[]>>} - An array of PayTokens wrapped in an API response if the request was successful.
      *
      * @example
@@ -155,7 +162,7 @@ export declare class ApiClient {
      *   console.log('Available tokens:', response.data);
      * }
      */
-    payOrderQuote(orderId: string, quoteParams: PayOrderQuoteParams): Promise<APIResponse<RouteQuote[]>>;
+    payOrderQuote(orderId: string, quoteParams: PayOrderQuoteParams, opts?: Opts): Promise<APIResponse<RouteQuote[]>>;
     /**
      * Retrieves payment details for a specific PayOrder.
      *
@@ -171,6 +178,7 @@ export declare class ApiClient {
      * @param {CurrencyBase} [params.source_currency] - (Optional) The source currency information.
      * @param {string} params.quote_id - (Optional) The quote ID for the PayOrder.
      * @param {string} params.refund_address - The address where funds will be refunded in case of a failed transaction.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      *
      * @returns {Promise<APIResponse<PaymentDetails>>} - The payment details object wrapped in an API response if the request is successful.
      *
@@ -185,93 +193,76 @@ export declare class ApiClient {
      *   console.log('Payment details:', response.data);
      * }
      */
-    payOrderPaymentDetails(params: PaymentDetailsParams): Promise<APIResponse<PaymentDetails>>;
-    /**
-     * Generates an authorization signature for API requests using HMAC-SHA256.
-     *
-     * ⚠️ **Warning:** This function should only be run on the server.
-     * It uses the API secret, which must remain confidential. Running this
-     * code in a client-side environment risks exposing sensitive information
-     * to end users or malicious actors.
-     *
-     * This function creates a signed authorization string using HMAC-SHA256.
-     * The signature is computed over: method + path + timestamp, using the secret as the HMAC key.
-     *
-     * @param {string} apiSecret - The API secret used as the HMAC key.
-     * @param {string} method - The HTTP method (e.g., "POST", "GET").
-     * @param {string} path - The request path (e.g., "/pay-orders").
-     * @returns {string} - A formatted authorization string in the format:
-     *                     `APIKey=<apiKey>,signature=<signature>,timestamp=<timestamp>`.
-     *
-     * @example
-     * const apiSecret = 'yourApiSecret';
-     * const authSignature = apiClient.generateAuthorizationSignature(apiSecret, 'POST', '/pay-orders');
-     * console.log(authSignature);
-     * // Example output:
-     * // APIKey=yourApiKey,signature=a1b2c3d4...,timestamp=1737106896
-     */
-    generateAuthorizationSignature(apiSecret: string, method: string, path: string): string;
+    payOrderPaymentDetails(params: PaymentDetailsParams, opts?: Opts): Promise<APIResponse<PaymentDetails>>;
     /**
      * Retrieves the claimable fee balances for the authenticated organization.
      *
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<GetFeeBalancesResponse>>} - Fee balances wrapped in an API response.
      */
-    getFeeBalances(apiSecret: string): Promise<APIResponse<GetFeeBalancesResponse>>;
+    getFeeBalances(apiSecret: string, opts?: Opts): Promise<APIResponse<GetFeeBalancesResponse>>;
     /**
      * Claims accrued fees for the authenticated organization.
      *
      * @param {ClaimFeesRequest} params - Parameters for claiming fees.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Options for the request, such as additional headers.
      * @returns {Promise<APIResponse<ClaimFeesResponse>>} - Claim result wrapped in an API response.
      */
-    claimFees(params: ClaimFeesRequest, apiSecret: string): Promise<APIResponse<ClaimFeesResponse>>;
+    claimFees(params: ClaimFeesRequest, apiSecret: string, opts?: Opts): Promise<APIResponse<ClaimFeesResponse>>;
     /**
      * Retrieves all webhooks for the authenticated organization.
      *
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Options for the request, such as additional headers.
      * @returns {Promise<APIResponse<WebhookResponse[]>>} - List of webhooks wrapped in an API response.
      */
-    listWebhooks(apiSecret: string): Promise<APIResponse<WebhookResponse[]>>;
+    listWebhooks(apiSecret: string, opts?: Opts): Promise<APIResponse<WebhookResponse[]>>;
     /**
      * Creates a new webhook for the authenticated organization.
      *
      * @param {CreateWebhookRequest} params - Parameters for creating the webhook.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<WebhookResponse>>} - Created webhook wrapped in an API response.
      */
-    createWebhook(params: CreateWebhookRequest, apiSecret: string): Promise<APIResponse<WebhookResponse>>;
+    createWebhook(params: CreateWebhookRequest, apiSecret: string, opts?: Opts): Promise<APIResponse<WebhookResponse>>;
     /**
      * Updates an existing webhook for the authenticated organization.
      *
      * @param {string} webhookId - The unique identifier of the webhook to update.
      * @param {UpdateWebhookRequest} params - Parameters for updating the webhook.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<WebhookResponse>>} - Updated webhook wrapped in an API response.
      */
-    updateWebhook(webhookId: string, params: UpdateWebhookRequest, apiSecret: string): Promise<APIResponse<WebhookResponse>>;
+    updateWebhook(webhookId: string, params: UpdateWebhookRequest, apiSecret: string, opts?: Opts): Promise<APIResponse<WebhookResponse>>;
     /**
      * Deletes an existing webhook for the authenticated organization.
      *
      * @param {string} webhookId - The unique identifier of the webhook to delete.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<void>>} - Empty response on success.
      */
-    deleteWebhook(webhookId: string, apiSecret: string): Promise<APIResponse<void>>;
+    deleteWebhook(webhookId: string, apiSecret: string, opts?: Opts): Promise<APIResponse<void>>;
     /**
      * Gets a quote for swapping between two currencies.
      *
      * @param {SwapQuoteRequest} params - Parameters for the swap quote.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<SwapQuoteResponse>>} - Swap quote wrapped in an API response.
      */
-    swapQuote(params: SwapQuoteRequest): Promise<APIResponse<SwapQuoteResponse>>;
+    swapQuote(params: SwapQuoteRequest, opts?: Opts): Promise<APIResponse<SwapQuoteResponse>>;
     /**
      * Gets transaction data for executing a swap.
      *
      * @param {SwapDataRequest} params - Parameters for the swap data.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<SwapDataResponse>>} - Swap data wrapped in an API response.
      */
-    swapData(params: SwapDataRequest): Promise<APIResponse<SwapDataResponse>>;
+    swapData(params: SwapDataRequest, opts?: Opts): Promise<APIResponse<SwapDataResponse>>;
     /**
      * Opens a WebSocket connection to receive real-time order status events.
      *
@@ -287,4 +278,30 @@ export declare class ApiClient {
      * @returns {OrderStatusSocket} - Handle for subscribing, receiving messages, and closing the connection.
      */
     subscribeOrderStatus(): OrderStatusSocket;
+    /**
+     * Generates an authorization signature for API requests using HMAC-SHA256.
+     *
+     * ⚠️ **Warning:** This function should only be run on the server.
+     * It uses the API secret, which must remain confidential. Running this
+     * code in a client-side environment risks exposing sensitive information
+     * to end users or malicious actors.
+     *
+     * This function creates a signed authorization string using HMAC-SHA256.
+     * The signature is computed over: method + path + timestamp, using the secret as the HMAC key.
+     *
+     * @param {string} apiSecret - The API secret used as the HMAC key.
+     * @param {string} method - The HTTP method (e.g., "POST", "GET").
+     * @param {string} path - The request path (e.g., "/pay-orders").
+     * @returns {string} - A formatted authorization string in the format:
+     *                     `APIKey=<apiKey>,signature=<signature>,timestamp=<timestamp>`.
+     *
+     * @example
+     * const apiSecret = 'yourApiSecret';
+     * const authSignature = apiClient.generateAuthorizationSignature(apiSecret, 'POST', '/pay-orders');
+     * console.log(authSignature);
+     * // Example output:
+     * // APIKey=yourApiKey,signature=a1b2c3d4...,timestamp=1737106896
+     */
+    generateAuthorizationSignature(apiSecret: string, method: string, path: string): string;
 }
+export {};

package/dist/api/client.js

@@ -46,6 +46,7 @@ export class ApiClient {
      * Creates a PayOrder of type `DEPOSIT` with the provided parameters.
      *
      * @param {PayOrderParams} params - Parameters required to create a deposit PayOrder.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<PayOrder>>} - The PayOrder object wrapped in an API response if the request is successful.
      *
      * @example
@@ -62,9 +63,9 @@ export class ApiClient {
      *   console.log('Deposit PayOrder created:', data);
      * }
      */
-    async createDepositPayOrder(params) {
+    async createDepositPayOrder(params, opts) {
         try {
-            return this.createPayOrder(params, PayOrderMode.DEPOSIT);
+            return this.createPayOrder(params, PayOrderMode.DEPOSIT, undefined, opts);
         }
         catch (error) {
             return {
@@ -86,6 +87,7 @@ export class ApiClient {
      *
      * @param {SalePayOrderParams} params - Params required to create a sale PayOrder.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request.
      * @returns {Promise<APIResponse<PayOrder>>} - A PayOrder object wrapped in an API response if the request was successful.
      *
      * @example
@@ -116,10 +118,10 @@ export class ApiClient {
      *   console.log('Sale PayOrder created:', response.data);
      * }
      */
-    async createSalePayOrder(params, apiSecret) {
+    async createSalePayOrder(params, apiSecret, opts) {
         try {
             const signature = this.generateAuthorizationSignature(apiSecret, "POST", "/pay-orders");
-            return this.createPayOrder(params, PayOrderMode.SALE, signature);
+            return this.createPayOrder(params, PayOrderMode.SALE, signature, opts);
         }
         catch (error) {
             return {
@@ -142,6 +144,7 @@ export class ApiClient {
      * @param {string} payOrderId - The unique identifier of the PayOrder to be refunded.
      * @param {PayOrderParams} params - Params required to create a refund PayOrder.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request.
      * @returns {Promise<APIResponse<PayOrder>>} - A PayOrder object wrapped in an API response if the request was successful.
      *
      * @example
@@ -172,7 +175,7 @@ export class ApiClient {
      *   console.log('Refund PayOrder created:', response.data);
      * }
      */
-    async createRefundPayOrder(payOrderId, params, apiSecret) {
+    async createRefundPayOrder(payOrderId, params, apiSecret, opts) {
         try {
             const result = zPayOrder.safeParse(params);
             if (!result.success) {
@@ -191,7 +194,7 @@ export class ApiClient {
                 options: {
                     method: "POST",
                     body: JSON.stringify({ ...params }),
-                    headers: { Authorization: signature },
+                    headers: { Authorization: signature, ...opts?.headers },
                 },
             });
         }
@@ -206,7 +209,7 @@ export class ApiClient {
             };
         }
     }
-    async createPayOrder(params, mode, signature) {
+    async createPayOrder(params, mode, signature, opts) {
         const result = zPayOrder.safeParse(params);
         if (!result.success) {
             throw new Error(result.error.issues.map((e) => e.message).join(", "));
@@ -225,7 +228,7 @@ export class ApiClient {
             options: {
                 method: "POST",
                 body: JSON.stringify({ mode, ...params }),
-                headers: signature ? { Authorization: signature } : {},
+                headers: { ...(signature ? { Authorization: signature } : {}), ...opts?.headers },
             },
         });
     }
@@ -237,6 +240,7 @@ export class ApiClient {
      *
      * @param {string} orderId - The unique identifier of the PayOrder for which the quote is requested.
      * @param {PayOrderQuoteParams} quoteParams - Contains `wallet_address`, `chain_type`, `chain_id`.
+     * @param {Opts} [opts] - Optional parameters for the request.
      * @returns {Promise<APIResponse<RouteQuote[]>>} - An array of PayTokens wrapped in an API response if the request was successful.
      *
      * @example
@@ -252,12 +256,13 @@ export class ApiClient {
      *   console.log('Available tokens:', response.data);
      * }
      */
-    async payOrderQuote(orderId, quoteParams) {
+    async payOrderQuote(orderId, quoteParams, opts) {
         return this.request({
             path: `/pay-orders/${orderId}/quote`,
             options: {
                 method: "POST",
                 body: JSON.stringify(quoteParams),
+                headers: opts?.headers,
             },
         });
     }
@@ -276,6 +281,7 @@ export class ApiClient {
      * @param {CurrencyBase} [params.source_currency] - (Optional) The source currency information.
      * @param {string} params.quote_id - (Optional) The quote ID for the PayOrder.
      * @param {string} params.refund_address - The address where funds will be refunded in case of a failed transaction.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      *
      * @returns {Promise<APIResponse<PaymentDetails>>} - The payment details object wrapped in an API response if the request is successful.
      *
@@ -290,47 +296,17 @@ export class ApiClient {
      *   console.log('Payment details:', response.data);
      * }
      */
-    async payOrderPaymentDetails(params) {
+    async payOrderPaymentDetails(params, opts) {
         const { payorder_id, ...rest } = params;
         return this.request({
             path: `/pay-orders/${payorder_id}/payment-details`,
             options: {
                 method: "POST",
                 body: JSON.stringify({ ...rest }),
+                headers: opts?.headers,
             },
         });
     }
-    /**
-     * Generates an authorization signature for API requests using HMAC-SHA256.
-     *
-     * ⚠️ **Warning:** This function should only be run on the server.
-     * It uses the API secret, which must remain confidential. Running this
-     * code in a client-side environment risks exposing sensitive information
-     * to end users or malicious actors.
-     *
-     * This function creates a signed authorization string using HMAC-SHA256.
-     * The signature is computed over: method + path + timestamp, using the secret as the HMAC key.
-     *
-     * @param {string} apiSecret - The API secret used as the HMAC key.
-     * @param {string} method - The HTTP method (e.g., "POST", "GET").
-     * @param {string} path - The request path (e.g., "/pay-orders").
-     * @returns {string} - A formatted authorization string in the format:
-     *                     `APIKey=<apiKey>,signature=<signature>,timestamp=<timestamp>`.
-     *
-     * @example
-     * const apiSecret = 'yourApiSecret';
-     * const authSignature = apiClient.generateAuthorizationSignature(apiSecret, 'POST', '/pay-orders');
-     * console.log(authSignature);
-     * // Example output:
-     * // APIKey=yourApiKey,signature=a1b2c3d4...,timestamp=1737106896
-     */
-    generateAuthorizationSignature(apiSecret, method, path) {
-        const timestamp = now();
-        // Create HMAC-SHA256 signature over: method + path + timestamp
-        const data = `${method}${path}${timestamp}`;
-        const signature = createHmac("sha256", apiSecret).update(data).digest("hex");
-        return `APIKey=${this.apiKey},signature=${signature},timestamp=${timestamp}`;
-    }
     // ===================
     // Fee endpoints
     // ===================
@@ -338,15 +314,16 @@ export class ApiClient {
      * Retrieves the claimable fee balances for the authenticated organization.
      *
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<GetFeeBalancesResponse>>} - Fee balances wrapped in an API response.
      */
-    async getFeeBalances(apiSecret) {
+    async getFeeBalances(apiSecret, opts) {
         const signature = this.generateAuthorizationSignature(apiSecret, "GET", "/fees/balance");
         return this.request({
             path: "/fees/balance",
             options: {
                 method: "GET",
-                headers: { Authorization: signature },
+                headers: { Authorization: signature, ...opts?.headers },
             },
         });
     }
@@ -355,16 +332,17 @@ export class ApiClient {
      *
      * @param {ClaimFeesRequest} params - Parameters for claiming fees.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Options for the request, such as additional headers.
      * @returns {Promise<APIResponse<ClaimFeesResponse>>} - Claim result wrapped in an API response.
      */
-    async claimFees(params, apiSecret) {
+    async claimFees(params, apiSecret, opts) {
         const signature = this.generateAuthorizationSignature(apiSecret, "POST", "/fees/claim");
         return this.request({
             path: "/fees/claim",
             options: {
                 method: "POST",
                 body: JSON.stringify(params),
-                headers: { Authorization: signature },
+                headers: { Authorization: signature, ...opts?.headers },
             },
         });
     }
@@ -375,15 +353,16 @@ export class ApiClient {
      * Retrieves all webhooks for the authenticated organization.
      *
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Options for the request, such as additional headers.
      * @returns {Promise<APIResponse<WebhookResponse[]>>} - List of webhooks wrapped in an API response.
      */
-    async listWebhooks(apiSecret) {
+    async listWebhooks(apiSecret, opts) {
         const signature = this.generateAuthorizationSignature(apiSecret, "GET", "/organizations/webhooks");
         return this.request({
             path: "/webhooks",
             options: {
                 method: "GET",
-                headers: { Authorization: signature },
+                headers: { Authorization: signature, ...opts?.headers },
             },
         });
     }
@@ -392,16 +371,17 @@ export class ApiClient {
      *
      * @param {CreateWebhookRequest} params - Parameters for creating the webhook.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<WebhookResponse>>} - Created webhook wrapped in an API response.
      */
-    async createWebhook(params, apiSecret) {
+    async createWebhook(params, apiSecret, opts) {
         const signature = this.generateAuthorizationSignature(apiSecret, "POST", "/webhooks");
         return this.request({
             path: "/webhooks",
             options: {
                 method: "POST",
                 body: JSON.stringify(params),
-                headers: { Authorization: signature },
+                headers: { Authorization: signature, ...opts?.headers },
             },
         });
     }
@@ -411,16 +391,17 @@ export class ApiClient {
      * @param {string} webhookId - The unique identifier of the webhook to update.
      * @param {UpdateWebhookRequest} params - Parameters for updating the webhook.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<WebhookResponse>>} - Updated webhook wrapped in an API response.
      */
-    async updateWebhook(webhookId, params, apiSecret) {
+    async updateWebhook(webhookId, params, apiSecret, opts) {
         const signature = this.generateAuthorizationSignature(apiSecret, "PUT", `/webhooks/${webhookId}`);
         return this.request({
             path: `/webhooks/${webhookId}`,
             options: {
                 method: "PUT",
                 body: JSON.stringify(params),
-                headers: { Authorization: signature },
+                headers: { Authorization: signature, ...opts?.headers },
             },
         });
     }
@@ -429,15 +410,16 @@ export class ApiClient {
      *
      * @param {string} webhookId - The unique identifier of the webhook to delete.
      * @param {string} apiSecret - API secret used to generate the authorization signature.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<void>>} - Empty response on success.
      */
-    async deleteWebhook(webhookId, apiSecret) {
+    async deleteWebhook(webhookId, apiSecret, opts) {
         const signature = this.generateAuthorizationSignature(apiSecret, "DELETE", `/webhooks/${webhookId}`);
         return this.request({
             path: `/webhooks/${webhookId}`,
             options: {
                 method: "DELETE",
-                headers: { Authorization: signature },
+                headers: { Authorization: signature, ...opts?.headers },
             },
         });
     }
@@ -448,14 +430,16 @@ export class ApiClient {
      * Gets a quote for swapping between two currencies.
      *
      * @param {SwapQuoteRequest} params - Parameters for the swap quote.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<SwapQuoteResponse>>} - Swap quote wrapped in an API response.
      */
-    async swapQuote(params) {
+    async swapQuote(params, opts) {
         return this.request({
             path: "/swap/quote",
             options: {
                 method: "POST",
                 body: JSON.stringify(params),
+                headers: opts?.headers,
             },
         });
     }
@@ -463,14 +447,16 @@ export class ApiClient {
      * Gets transaction data for executing a swap.
      *
      * @param {SwapDataRequest} params - Parameters for the swap data.
+     * @param {Opts} [opts] - Optional parameters for the request, such as additional headers.
      * @returns {Promise<APIResponse<SwapDataResponse>>} - Swap data wrapped in an API response.
      */
-    async swapData(params) {
+    async swapData(params, opts) {
         return this.request({
             path: "/swap/data",
             options: {
                 method: "POST",
                 body: JSON.stringify(params),
+                headers: opts?.headers,
             },
         });
     }
@@ -552,4 +538,38 @@ export class ApiClient {
             },
         };
     }
+    // ===================
+    // Authentication
+    // ===================
+    /**
+     * Generates an authorization signature for API requests using HMAC-SHA256.
+     *
+     * ⚠️ **Warning:** This function should only be run on the server.
+     * It uses the API secret, which must remain confidential. Running this
+     * code in a client-side environment risks exposing sensitive information
+     * to end users or malicious actors.
+     *
+     * This function creates a signed authorization string using HMAC-SHA256.
+     * The signature is computed over: method + path + timestamp, using the secret as the HMAC key.
+     *
+     * @param {string} apiSecret - The API secret used as the HMAC key.
+     * @param {string} method - The HTTP method (e.g., "POST", "GET").
+     * @param {string} path - The request path (e.g., "/pay-orders").
+     * @returns {string} - A formatted authorization string in the format:
+     *                     `APIKey=<apiKey>,signature=<signature>,timestamp=<timestamp>`.
+     *
+     * @example
+     * const apiSecret = 'yourApiSecret';
+     * const authSignature = apiClient.generateAuthorizationSignature(apiSecret, 'POST', '/pay-orders');
+     * console.log(authSignature);
+     * // Example output:
+     * // APIKey=yourApiKey,signature=a1b2c3d4...,timestamp=1737106896
+     */
+    generateAuthorizationSignature(apiSecret, method, path) {
+        const timestamp = now();
+        // Create HMAC-SHA256 signature over: method + path + timestamp
+        const data = `${method}${path}${timestamp}`;
+        const signature = createHmac("sha256", apiSecret).update(data).digest("hex");
+        return `APIKey=${this.apiKey},signature=${signature},timestamp=${timestamp}`;
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coin-voyage/shared",
   "description": "Shared utilities for Coin Voyage",
-  "version": "2.3.4",
+  "version": "2.3.5-beta.0",
   "private": false,
   "sideEffects": false,
   "exports": {