@coin-voyage/shared 2.2.3 → 2.2.5-beta.0

package/dist/api/client.d.ts

@@ -1,5 +1,5 @@
 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 {
@@ -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(payorderId))
+     * 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,76 @@ 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(payorderId))
+     * 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 ?? "production"]);
+        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(payorderId) {
+                send({ type: "subscribe", data: { payorder_id: payorderId } });
+            },
+            unsubscribe(payorderId) {
+                send({ type: "unsubscribe", data: { payorder_id: payorderId } });
+            },
+            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/types/api.d.ts

@@ -1,6 +1,7 @@
 import { FiatCurrency } from "../common/currencies";
 import { ChainId, ChainType, PayOrderStatus } from "./enums";
-import { Currency, CurrencyAmount, CurrencyBase, CurrencyWithAmount, PaymentData, PayOrderMetadataInput, QuoteWithCurrency } from "./model";
+import { PayOrderEvent } from "./events";
+import { Currency, CurrencyAmount, CurrencyBase, CurrencyWithAmount, PaymentData, PayOrderMetadata, QuoteWithCurrency } from "./model";
 export type PayOrderParams = {
     /**
      * Intent of the order.
@@ -9,7 +10,7 @@ export type PayOrderParams = {
     /**
      * Metadata to attach to the payOrder.
      */
-    metadata?: PayOrderMetadataInput;
+    metadata?: PayOrderMetadata;
 };
 export type PayOrderQuoteParams = {
     wallet_address: string;
@@ -127,3 +128,43 @@ 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: {
+        payorder_id: string;
+        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: (payorderId: string) => void;
+    unsubscribe: (payorderId: string) => 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/dist/types/events.d.ts

@@ -1,4 +1,4 @@
-import { PayOrderMetadata } from "./model";
+import { ParsedPayOrderMetadata } from "./model";
 import { Hex } from "./crypto";
 import { PaymentData } from "./model";
 export type PayOrderCreationErrorEvent = {
@@ -7,7 +7,7 @@ export type PayOrderCreationErrorEvent = {
 };
 type EventBase = {
     payorder_id: string;
-    metadata?: PayOrderMetadata;
+    metadata?: ParsedPayOrderMetadata;
 };
 export type PayOrderCreatedEvent = EventBase & {
     type: "payorder_created";

package/dist/types/index.d.ts

@@ -3,3 +3,4 @@ export * from "./crypto";
 export * from "./enums";
 export * from "./events";
 export * from "./model";
+export * from "./webhooks";

package/dist/types/index.js

@@ -3,3 +3,4 @@ export * from "./crypto";
 export * from "./enums";
 export * from "./events";
 export * from "./model";
+export * from "./webhooks";

package/dist/types/model.d.ts

@@ -1,30 +1,23 @@
 import { z } from "zod";
-import { zPayOrderMetadata } from "../common";
+import { zPayOrderMetadata } from "../common/validation";
 import { FiatCurrency } from "../common/currencies";
-import { ChainId, PayOrderMode, PayOrderStatus, ProviderStatus, WebhookEventType } from "./enums";
-import { PayOrderEvent } from "./events";
+import { ChainId, PayOrderMode, PayOrderStatus, ProviderStatus } from "./enums";
 export type PayOrder = {
     id: string;
     mode: PayOrderMode;
     status: PayOrderStatus;
-    metadata?: PayOrderMetadata;
+    metadata?: ParsedPayOrderMetadata;
     deposit_tx_hash?: string;
     receiving_tx_hash?: string;
     refund_tx_hash?: string;
     fulfillment: FulfillmentData;
     payment?: PaymentData;
 };
-export type PayOrderMetadata = z.infer<typeof zPayOrderMetadata> & {
-    [key: string]: string | number | boolean | any[] | {
-        [x: string]: any;
-    };
-};
-export type PayOrderMetadataInput = {
-    items?: z.input<typeof zPayOrderMetadata.shape.items>;
-    refund?: z.input<typeof zPayOrderMetadata.shape.refund>;
-} & Record<string, string | number | boolean | any[] | {
+type MetadataExtraFields = Record<string, string | number | boolean | any[] | {
     [x: string]: any;
-}>;
+} | undefined>;
+export type ParsedPayOrderMetadata = z.output<typeof zPayOrderMetadata> & MetadataExtraFields;
+export type PayOrderMetadata = z.input<typeof zPayOrderMetadata> & MetadataExtraFields;
 export interface Currency extends CurrencyBase {
     id?: string;
     name: string;
@@ -114,32 +107,8 @@ export type ExecutionStep = {
     fee_error?: unknown;
     price_impact?: string;
 };
-export interface WebhookEndpoint {
-    id: string;
-    organization_id: string;
-    active: boolean;
-    url: string;
-    webhook_secret: string;
-    subscription_events: WebhookEventType[];
-    created_at: Date;
-}
-export interface WebhookEvent {
-    id: string;
-    endpoint: WebhookEndpoint;
-    payload: PayOrderEvent;
-    webhook_id: string;
-    status: WebhookEventType;
-    deliveries: WebhookDelivery[];
-    created_at: Date;
-}
-export interface WebhookDelivery {
-    id: string;
-    event_id: string;
-    http_status: number;
-    body: string | null;
-    created_at: Date;
-}
 export interface FeePlan extends CurrencyWithAmount {
     fee_bps?: number;
 }
 export type BigIntStr = `${bigint}`;
+export {};

package/dist/types/webhooks.d.ts

@@ -0,0 +1,27 @@
+import { WebhookEventType } from "./enums";
+import { PayOrderEvent } from "./events";
+export interface WebhookEndpoint {
+    id: string;
+    organization_id: string;
+    active: boolean;
+    url: string;
+    webhook_secret: string;
+    subscription_events: WebhookEventType[];
+    created_at: Date;
+}
+export interface WebhookEvent {
+    id: string;
+    endpoint: WebhookEndpoint;
+    payload: PayOrderEvent;
+    webhook_id: string;
+    status: WebhookEventType;
+    deliveries: WebhookDelivery[];
+    created_at: Date;
+}
+export interface WebhookDelivery {
+    id: string;
+    event_id: string;
+    http_status: number;
+    body: string | null;
+    created_at: Date;
+}

package/dist/types/webhooks.js

@@ -0,0 +1 @@
+export {};

package/package.json

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