@coin-voyage/shared 2.2.4 → 2.2.5-beta.1

package/dist/api/client.d.ts

@@ -1,10 +1,10 @@
 import { type PayOrder, PayOrderMode } from "../types";
-import type { ClaimFeesRequest, ClaimFeesResponse, CreateWebhookRequest, GetFeeBalancesResponse, PaymentDetails, PaymentDetailsParams, PayOrderParams, PayOrderQuoteParams, QuoteWithBalance, SwapDataRequest, SwapDataResponse, SwapQuoteRequest, UpdateWebhookRequest, WebhookResponse } from "../types/api";
+import type { ClaimFeesRequest, ClaimFeesResponse, CreateWebhookRequest, GetFeeBalancesResponse, OrderStatusSocket, PaymentDetails, PaymentDetailsParams, PayOrderParams, PayOrderQuoteParams, QuoteWithBalance, SwapDataRequest, SwapDataResponse, SwapQuoteRequest, UpdateWebhookRequest, WebhookResponse } from "../types/api";
 import { type APIEnvironment } from "./config";
 import { type APIResponse } from "./fetcher";
 export declare class ApiClient {
     private readonly apiKey;
-    private readonly environment?;
+    private readonly environment;
     private readonly sessionId?;
     private readonly version?;
     constructor({ apiKey, sessionId, environment, version, }: {
@@ -272,4 +272,19 @@ export declare class ApiClient {
      * @returns {Promise<APIResponse<SwapDataResponse>>} - Swap data wrapped in an API response.
      */
     swapData(params: SwapDataRequest): Promise<APIResponse<SwapDataResponse>>;
+    /**
+     * Opens a WebSocket connection to receive real-time order status events.
+     *
+     * Subscribe to an order's events after the connection is open:
+     * ```ts
+     * const socket = apiClient.subscribeOrderStatus()
+     * socket.onOpen(() => socket.subscribe(orderId)) // omit orderId to subscribe to all org orders
+     * socket.onMessage((msg) => {
+     *   if (msg.type === 'event') console.log(msg.data)
+     * })
+     * ```
+     *
+     * @returns {OrderStatusSocket} - Handle for subscribing, receiving messages, and closing the connection.
+     */
+    subscribeOrderStatus(): OrderStatusSocket;
 }

package/dist/api/client.js

@@ -1,6 +1,7 @@
 import { createHmac } from "crypto";
 import { now, zPayOrder, zPayOrderMetadata } from "../common";
 import { PayOrderMode } from "../types";
+import { WS_URL } from "./config";
 import { fetchApi } from "./fetcher";
 export class ApiClient {
     constructor({ apiKey, sessionId, environment = "production", version, }) {
@@ -461,4 +462,82 @@ export class ApiClient {
             },
         });
     }
+    // ===================
+    // WebSocket
+    // ===================
+    /**
+     * Opens a WebSocket connection to receive real-time order status events.
+     *
+     * Subscribe to an order's events after the connection is open:
+     * ```ts
+     * const socket = apiClient.subscribeOrderStatus()
+     * socket.onOpen(() => socket.subscribe(orderId)) // omit orderId to subscribe to all org orders
+     * socket.onMessage((msg) => {
+     *   if (msg.type === 'event') console.log(msg.data)
+     * })
+     * ```
+     *
+     * @returns {OrderStatusSocket} - Handle for subscribing, receiving messages, and closing the connection.
+     */
+    subscribeOrderStatus() {
+        const ws = new WebSocket(WS_URL[this.environment]);
+        const messageListeners = [];
+        const pendingMessages = [];
+        ws.addEventListener("open", () => {
+            ws.send(JSON.stringify({ type: "connect", data: { api_key: this.apiKey } }));
+        });
+        ws.addEventListener("message", (event) => {
+            try {
+                const msg = JSON.parse(event.data);
+                if (msg.type === "connected") {
+                    for (const pending of pendingMessages)
+                        ws.send(pending);
+                    pendingMessages.length = 0;
+                }
+                for (const listener of messageListeners)
+                    listener(msg);
+            }
+            catch {
+                // ignore malformed messages
+            }
+        });
+        const send = (msg) => {
+            const data = JSON.stringify(msg);
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(data);
+            }
+            else {
+                pendingMessages.push(data);
+            }
+        };
+        return {
+            subscribe(orderId) {
+                send({ type: "subscribe", data: { order_id: orderId } });
+            },
+            subscribeOrg() {
+                send({ type: "subscribe", data: {} });
+            },
+            unsubscribe(orderId) {
+                send({ type: "unsubscribe", data: orderId ? { order_id: orderId } : {} });
+            },
+            unsubscribeOrg() {
+                send({ type: "unsubscribe", data: {} });
+            },
+            onMessage(callback) {
+                messageListeners.push(callback);
+            },
+            onOpen(callback) {
+                ws.addEventListener("open", callback);
+            },
+            onClose(callback) {
+                ws.addEventListener("close", callback);
+            },
+            onError(callback) {
+                ws.addEventListener("error", callback);
+            },
+            close() {
+                ws.close();
+            },
+        };
+    }
 }

package/dist/api/config.d.ts

@@ -1,2 +1,3 @@
 export declare const API_URL: Record<string, string>;
+export declare const WS_URL: Record<string, string>;
 export type APIEnvironment = keyof typeof API_URL;

package/dist/api/config.js

@@ -3,3 +3,8 @@ export const API_URL = {
     development: "https://acc-api.coinvoyage.io/v2",
     local: "http://localhost:8000/v2",
 };
+export const WS_URL = {
+    production: "wss://api.coinvoyage.io/v2/ws",
+    development: "wss://acc-api.coinvoyage.io/v2/ws",
+    local: "ws://localhost:8000/v2/ws",
+};

package/dist/api/fetcher.js

@@ -1,7 +1,7 @@
 import { API_URL } from "./config";
 export async function fetchApi(opts) {
     try {
-        const baseUrl = API_URL[opts.environment ?? "production"];
+        const baseUrl = API_URL[opts.environment || "production"];
         const response = await fetch(`${baseUrl}${opts.path}`, {
             ...opts.options,
             headers: {

package/dist/types/api.d.ts

@@ -1,5 +1,6 @@
 import { FiatCurrency } from "../common/currencies";
 import { ChainId, ChainType, PayOrderStatus } from "./enums";
+import { PayOrderEvent } from "./events";
 import { Currency, CurrencyAmount, CurrencyBase, CurrencyWithAmount, PaymentData, PayOrderMetadata, QuoteWithCurrency } from "./model";
 export type PayOrderParams = {
     /**
@@ -127,3 +128,46 @@ export type SwapDataResponse = {
     refund_address: string;
     expires_at: string;
 };
+declare enum WsMessageType {
+    Connected = "connected",
+    Subscription = "subscription",
+    Event = "event",
+    Error = "error"
+}
+export type WsConnectedMessage = {
+    type: WsMessageType.Connected;
+    data: {
+        status: "authenticated";
+    };
+};
+export type WsSubscriptionMessage = {
+    type: WsMessageType.Subscription;
+    data: {
+        order_id?: string;
+        scope: "order" | "organization";
+        status: "subscribed" | "unsubscribed";
+    };
+};
+export type WsEventMessage = {
+    type: WsMessageType.Event;
+    data: PayOrderEvent;
+};
+export type WsErrorMessage = {
+    type: WsMessageType.Error;
+    data: {
+        message: string;
+    };
+};
+export type WsServerMessage = WsConnectedMessage | WsSubscriptionMessage | WsEventMessage | WsErrorMessage;
+export type OrderStatusSocket = {
+    subscribe: (orderId: string) => void;
+    subscribeOrg: () => void;
+    unsubscribe: (orderId?: string) => void;
+    unsubscribeOrg: () => void;
+    onMessage: (callback: (msg: WsServerMessage) => void) => void;
+    onOpen: (callback: () => void) => void;
+    onClose: (callback: (event: CloseEvent) => void) => void;
+    onError: (callback: (event: Event) => void) => void;
+    close: () => void;
+};
+export {};

package/dist/types/api.js

@@ -1 +1,9 @@
+// ======== WebSocket ========
+var WsMessageType;
+(function (WsMessageType) {
+    WsMessageType["Connected"] = "connected";
+    WsMessageType["Subscription"] = "subscription";
+    WsMessageType["Event"] = "event";
+    WsMessageType["Error"] = "error";
+})(WsMessageType || (WsMessageType = {}));
 export {};

package/package.json

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