@n1xyz/nord-ts 0.2.0 → 0.3.1

package/dist/nord/api/actions.d.ts

@@ -0,0 +1,128 @@
+import Decimal from "decimal.js";
+import * as proto from "../../gen/nord_pb";
+import { paths } from "../../gen/openapi";
+import { Client } from "openapi-fetch";
+import { FillMode, Side, QuoteSize, TriggerKind } from "../../types";
+import { BigIntValue } from "../../utils";
+type ReceiptKind = NonNullable<proto.Receipt["kind"]>;
+type ExtractReceiptKind<K extends ReceiptKind["case"]> = Extract<ReceiptKind, {
+    case: K;
+}>;
+export declare function formatReceiptError(receipt: proto.Receipt): string;
+export declare function expectReceiptKind<K extends ReceiptKind["case"]>(receipt: proto.Receipt, expected: K, action: string): asserts receipt is proto.Receipt & {
+    kind: ExtractReceiptKind<K>;
+};
+export declare function createAction(currentTimestamp: bigint, nonce: number, kind: proto.Action["kind"]): proto.Action;
+export declare function sendAction(serverUrl: string, makeSignedMessage: (message: Uint8Array) => Promise<Uint8Array>, action: proto.Action, client?: Client<paths>): Promise<proto.Receipt>;
+export declare function prepareAction(action: proto.Action, makeSignedMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<Uint8Array<ArrayBufferLike>>;
+export declare function createSession(serverUrl: string, walletSignFn: (x: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    userPubkey: Uint8Array;
+    sessionPubkey: Uint8Array;
+    expiryTimestamp?: bigint;
+}, client?: Client<paths>): Promise<{
+    actionId: bigint;
+    sessionId: bigint;
+}>;
+export declare function revokeSession(serverUrl: string, walletSignFn: (message: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    sessionId: BigIntValue;
+}, client?: Client<paths>): Promise<{
+    actionId: bigint;
+}>;
+export declare function withdraw(serverUrl: string, signFn: (message: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    sizeDecimals: number;
+    sessionId: BigIntValue;
+    tokenId: number;
+    amount: Decimal.Value;
+}): Promise<{
+    actionId: bigint;
+} & proto.Receipt_WithdrawResult>;
+export declare function placeOrder(serverUrl: string, signFn: (message: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    sessionId: BigIntValue;
+    senderId?: number;
+    sizeDecimals: number;
+    priceDecimals: number;
+    marketId: number;
+    side: Side;
+    fillMode: FillMode;
+    isReduceOnly: boolean;
+    size?: Decimal.Value;
+    price?: Decimal.Value;
+    quoteSize?: QuoteSize;
+    liquidateeId?: number;
+    clientOrderId?: BigIntValue;
+}): Promise<{
+    actionId: bigint;
+    orderId?: bigint;
+    fills: proto.Receipt_Trade[];
+}>;
+export declare function cancelOrder(serverUrl: string, signFn: (message: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    sessionId: BigIntValue;
+    senderId?: number;
+    orderId: BigIntValue;
+    liquidateeId?: number;
+}): Promise<{
+    actionId: bigint;
+    orderId: bigint;
+    accountId: number;
+}>;
+export declare function transfer(serverUrl: string, signFn: (message: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    sessionId: BigIntValue;
+    fromAccountId: number;
+    toAccountId?: number;
+    tokenId: number;
+    tokenDecimals: number;
+    amount: Decimal.Value;
+}): Promise<{
+    actionId: bigint;
+    fromAccountId: number;
+    toAccountId?: number;
+    tokenId: number;
+    amount: bigint;
+    accountCreated: boolean;
+}>;
+export declare function addTrigger(serverUrl: string, signFn: (message: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    sessionId: BigIntValue;
+    marketId: number;
+    side: Side;
+    kind: TriggerKind;
+    priceDecimals: number;
+    triggerPrice: Decimal.Value;
+    limitPrice?: Decimal.Value;
+    accountId?: number;
+}): Promise<{
+    actionId: bigint;
+}>;
+export declare function removeTrigger(serverUrl: string, signFn: (message: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    sessionId: BigIntValue;
+    marketId: number;
+    side: Side;
+    kind: TriggerKind;
+    accountId?: number;
+}): Promise<{
+    actionId: bigint;
+}>;
+export type AtomicSubaction = {
+    kind: "place";
+    marketId: number;
+    side: Side;
+    fillMode: FillMode;
+    isReduceOnly: boolean;
+    sizeDecimals: number;
+    priceDecimals: number;
+    size?: Decimal.Value;
+    price?: Decimal.Value;
+    quoteSize?: QuoteSize;
+    clientOrderId?: BigIntValue;
+} | {
+    kind: "cancel";
+    orderId: BigIntValue;
+};
+export declare function atomic(serverUrl: string, signFn: (message: Uint8Array) => Promise<Uint8Array>, currentTimestamp: bigint, nonce: number, params: {
+    sessionId: BigIntValue;
+    accountId?: number;
+    actions: AtomicSubaction[];
+}, client?: Client<paths>): Promise<{
+    actionId: bigint;
+    results: proto.Receipt_AtomicSubactionResultKind[];
+}>;
+export {};

package/dist/nord/api/actions.js

@@ -0,0 +1,396 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatReceiptError = formatReceiptError;
+exports.expectReceiptKind = expectReceiptKind;
+exports.createAction = createAction;
+exports.sendAction = sendAction;
+exports.prepareAction = prepareAction;
+exports.createSession = createSession;
+exports.revokeSession = revokeSession;
+exports.withdraw = withdraw;
+exports.placeOrder = placeOrder;
+exports.cancelOrder = cancelOrder;
+exports.transfer = transfer;
+exports.addTrigger = addTrigger;
+exports.removeTrigger = removeTrigger;
+exports.atomic = atomic;
+const proto = __importStar(require("../../gen/nord_pb"));
+const openapi_fetch_1 = __importDefault(require("openapi-fetch"));
+const protobuf_1 = require("@bufbuild/protobuf");
+const types_1 = require("../../types");
+const utils_1 = require("../../utils");
+const wire_1 = require("@bufbuild/protobuf/wire");
+const NordError_1 = require("../utils/NordError");
+function formatReceiptError(receipt) {
+    if (receipt.kind?.case === "err") {
+        const err = receipt.kind.value;
+        return proto.Error[err] ?? err.toString();
+    }
+    return receipt.kind?.case ?? "unknown";
+}
+function expectReceiptKind(receipt, expected, action) {
+    if (receipt.kind?.case !== expected) {
+        const label = formatReceiptError(receipt);
+        throw new NordError_1.NordError(`Failed to ${action}: ${label}`);
+    }
+}
+async function sessionSign(signFn, message) {
+    const signature = await signFn(message);
+    return new Uint8Array([...message, ...signature]);
+}
+async function walletSign(walletSignFn, message) {
+    const signature = await walletSignFn(message);
+    return new Uint8Array([...message, ...signature]);
+}
+// Helper to create an action with common fields
+function createAction(currentTimestamp, nonce, kind) {
+    return (0, protobuf_1.create)(proto.ActionSchema, {
+        currentTimestamp,
+        nonce,
+        kind,
+    });
+}
+async function sendAction(serverUrl, makeSignedMessage, action, client) {
+    const body = await prepareAction(action, makeSignedMessage);
+    const httpClient = client ?? (0, openapi_fetch_1.default)({ baseUrl: serverUrl });
+    const response = await httpClient.POST("/action", {
+        params: {
+            header: {
+                "content-type": "application/octet-stream",
+            },
+        },
+        body: body,
+        // NOTE: openapi-fetch ignores headers and types/const headers in schema, and always assume all things are JSON
+        // to handle multi type bodies, need these overrides and later adhoc parsing
+        bodySerializer: (body) => body,
+        parseAs: "stream",
+    });
+    if (response.error) {
+        throw new Error(`Failed to ${action.kind.case}, HTTP status ${JSON.stringify(response.error)}`);
+    }
+    const rawResp = new Uint8Array(await response.response.bytes());
+    const resp = (0, utils_1.decodeLengthDelimited)(rawResp, proto.ReceiptSchema);
+    if (resp.kind?.case === "err") {
+        throw new Error(`Could not execute ${action.kind.case}, reason: ${proto.Error[resp.kind.value]}`);
+    }
+    return resp;
+}
+// Given action and signature function, prepare the signed message to send to server as `body`.
+// `makeSignedMessage` must include the original message and signature.
+async function prepareAction(action, makeSignedMessage) {
+    const encoded = (0, wire_1.sizeDelimitedEncode)(proto.ActionSchema, action);
+    // NOTE(agent): keep in sync with MAX_ENCODED_ACTION_SIZE in Rust code
+    const MAX_ENCODED_ACTION_SIZE = 1024;
+    if (encoded.byteLength > MAX_ENCODED_ACTION_SIZE) {
+        console.warn("Encoded message:", encoded);
+        throw new Error(`Encoded message size (${encoded.byteLength} bytes) is greater than max payload size (${MAX_ENCODED_ACTION_SIZE} bytes).`);
+    }
+    const body = await makeSignedMessage(encoded);
+    if (body.byteLength > MAX_ENCODED_ACTION_SIZE) {
+        console.warn("Encoded length:", encoded.byteLength);
+        throw new Error(`Signed message size (${body.byteLength} bytes) is greater than max payload size (${MAX_ENCODED_ACTION_SIZE} bytes).`);
+    }
+    return body;
+}
+async function createSession(serverUrl, walletSignFn, currentTimestamp, nonce, params, client) {
+    (0, utils_1.checkPubKeyLength)(types_1.KeyType.Ed25519, params.userPubkey.length);
+    (0, utils_1.checkPubKeyLength)(types_1.KeyType.Ed25519, params.sessionPubkey.length);
+    let expiry = 0n;
+    if (params.expiryTimestamp !== undefined) {
+        expiry = params.expiryTimestamp;
+        (0, utils_1.assert)(expiry > currentTimestamp, "Cannot set expiry timestamp in the past");
+    }
+    else {
+        expiry = currentTimestamp + utils_1.SESSION_TTL;
+    }
+    const action = createAction(currentTimestamp, nonce, {
+        case: "createSession",
+        value: (0, protobuf_1.create)(proto.Action_CreateSessionSchema, {
+            userPubkey: params.userPubkey,
+            blstPubkey: params.sessionPubkey,
+            expiryTimestamp: expiry,
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => walletSign(walletSignFn, m), action, client);
+    if (resp.kind?.case === "createSessionResult") {
+        return {
+            actionId: resp.actionId,
+            sessionId: resp.kind.value.sessionId,
+        };
+    }
+    else {
+        throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+    }
+}
+async function revokeSession(serverUrl, walletSignFn, currentTimestamp, nonce, params, client) {
+    const action = createAction(currentTimestamp, nonce, {
+        case: "revokeSession",
+        value: (0, protobuf_1.create)(proto.Action_RevokeSessionSchema, {
+            sessionId: BigInt(params.sessionId),
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => walletSign(walletSignFn, m), action, client);
+    return { actionId: resp.actionId };
+}
+async function withdraw(serverUrl, signFn, currentTimestamp, nonce, params) {
+    const amount = (0, utils_1.toScaledU64)(params.amount, params.sizeDecimals);
+    if (amount <= 0) {
+        throw new Error("Withdraw amount must be positive");
+    }
+    const action = createAction(currentTimestamp, nonce, {
+        case: "withdraw",
+        value: (0, protobuf_1.create)(proto.Action_WithdrawSchema, {
+            sessionId: BigInt(params.sessionId),
+            tokenId: params.tokenId,
+            amount,
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => sessionSign(signFn, m), action);
+    if (resp.kind?.case === "withdrawResult") {
+        return { actionId: resp.actionId, ...resp.kind.value };
+    }
+    else {
+        throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+    }
+}
+async function placeOrder(serverUrl, signFn, currentTimestamp, nonce, params) {
+    const price = (0, utils_1.toScaledU64)(params.price ?? 0, params.priceDecimals);
+    const size = (0, utils_1.toScaledU64)(params.size ?? 0, params.sizeDecimals);
+    const scaledQuote = params.quoteSize
+        ? params.quoteSize.toWire(params.priceDecimals, params.sizeDecimals)
+        : undefined;
+    (0, utils_1.assert)(price > 0n || size > 0n || scaledQuote !== undefined, "OrderLimit must include at least one of: size, price, or quoteSize");
+    const action = createAction(currentTimestamp, nonce, {
+        case: "placeOrder",
+        value: (0, protobuf_1.create)(proto.Action_PlaceOrderSchema, {
+            sessionId: BigInt(params.sessionId),
+            senderAccountId: params.senderId,
+            marketId: params.marketId,
+            side: params.side === types_1.Side.Bid ? proto.Side.BID : proto.Side.ASK,
+            fillMode: (0, types_1.fillModeToProtoFillMode)(params.fillMode),
+            isReduceOnly: params.isReduceOnly,
+            price,
+            size,
+            quoteSize: scaledQuote === undefined
+                ? undefined
+                : (0, protobuf_1.create)(proto.QuoteSizeSchema, {
+                    size: scaledQuote.size,
+                    price: scaledQuote.price,
+                }),
+            clientOrderId: params.clientOrderId === undefined
+                ? undefined
+                : BigInt(params.clientOrderId),
+            delegatorAccountId: params.liquidateeId,
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => sessionSign(signFn, m), action);
+    if (resp.kind?.case === "placeOrderResult") {
+        return {
+            actionId: resp.actionId,
+            orderId: resp.kind.value.posted?.orderId,
+            fills: resp.kind.value.fills,
+        };
+    }
+    else {
+        throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+    }
+}
+async function cancelOrder(serverUrl, signFn, currentTimestamp, nonce, params) {
+    const action = createAction(currentTimestamp, nonce, {
+        case: "cancelOrderById",
+        value: (0, protobuf_1.create)(proto.Action_CancelOrderByIdSchema, {
+            orderId: BigInt(params.orderId),
+            sessionId: BigInt(params.sessionId),
+            senderAccountId: params.senderId,
+            delegatorAccountId: params.liquidateeId,
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => sessionSign(signFn, m), action);
+    if (resp.kind?.case === "cancelOrderResult") {
+        return {
+            actionId: resp.actionId,
+            orderId: resp.kind.value.orderId,
+            accountId: resp.kind.value.accountId,
+        };
+    }
+    else {
+        throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+    }
+}
+async function transfer(serverUrl, signFn, currentTimestamp, nonce, params) {
+    const action = createAction(currentTimestamp, nonce, {
+        case: "transfer",
+        value: (0, protobuf_1.create)(proto.Action_TransferSchema, {
+            sessionId: BigInt(params.sessionId),
+            fromAccountId: params.fromAccountId,
+            toAccountId: params.toAccountId,
+            tokenId: params.tokenId,
+            amount: (0, utils_1.toScaledU64)(params.amount ?? 0, params.tokenDecimals),
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => sessionSign(signFn, m), action);
+    if (resp.kind?.case === "transferred") {
+        return {
+            actionId: resp.actionId,
+            fromAccountId: resp.kind.value.fromAccountId,
+            toAccountId: resp.kind.value.toUserAccount,
+            tokenId: resp.kind.value.tokenId,
+            amount: resp.kind.value.amount,
+            accountCreated: resp.kind.value.accountCreated,
+        };
+    }
+    else {
+        throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+    }
+}
+async function addTrigger(serverUrl, signFn, currentTimestamp, nonce, params) {
+    const triggerPrice = (0, utils_1.toScaledU64)(params.triggerPrice, params.priceDecimals);
+    (0, utils_1.assert)(triggerPrice > 0n, "Trigger price must be positive");
+    const limitPrice = params.limitPrice === undefined
+        ? undefined
+        : (0, utils_1.toScaledU64)(params.limitPrice, params.priceDecimals);
+    if (limitPrice !== undefined) {
+        (0, utils_1.assert)(limitPrice > 0n, "Limit price must be positive");
+    }
+    const key = (0, protobuf_1.create)(proto.TriggerKeySchema, {
+        kind: params.kind === types_1.TriggerKind.StopLoss
+            ? proto.TriggerKind.STOP_LOSS
+            : proto.TriggerKind.TAKE_PROFIT,
+        side: params.side === types_1.Side.Bid ? proto.Side.BID : proto.Side.ASK,
+    });
+    const prices = (0, protobuf_1.create)(proto.Action_TriggerPricesSchema, {
+        triggerPrice,
+        limitPrice,
+    });
+    const action = createAction(currentTimestamp, nonce, {
+        case: "addTrigger",
+        value: (0, protobuf_1.create)(proto.Action_AddTriggerSchema, {
+            sessionId: BigInt(params.sessionId),
+            marketId: params.marketId,
+            key,
+            prices,
+            accountId: params.accountId,
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => sessionSign(signFn, m), action);
+    if (resp.kind?.case === "triggerAdded") {
+        return { actionId: resp.actionId };
+    }
+    throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+}
+async function removeTrigger(serverUrl, signFn, currentTimestamp, nonce, params) {
+    const key = (0, protobuf_1.create)(proto.TriggerKeySchema, {
+        kind: params.kind === types_1.TriggerKind.StopLoss
+            ? proto.TriggerKind.STOP_LOSS
+            : proto.TriggerKind.TAKE_PROFIT,
+        side: params.side === types_1.Side.Bid ? proto.Side.BID : proto.Side.ASK,
+    });
+    const action = createAction(currentTimestamp, nonce, {
+        case: "removeTrigger",
+        value: (0, protobuf_1.create)(proto.Action_RemoveTriggerSchema, {
+            sessionId: BigInt(params.sessionId),
+            marketId: params.marketId,
+            key,
+            accountId: params.accountId,
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => sessionSign(signFn, m), action);
+    if (resp.kind?.case === "triggerRemoved") {
+        return { actionId: resp.actionId };
+    }
+    throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+}
+async function atomic(serverUrl, signFn, currentTimestamp, nonce, params, client) {
+    (0, utils_1.assert)(params.actions.length > 0 && params.actions.length <= 4, "Atomic action must contain between 1 and 4 sub-actions");
+    const subactions = params.actions.map((a) => {
+        if (a.kind === "place") {
+            const price = (0, utils_1.toScaledU64)(a.price ?? 0, a.priceDecimals);
+            const size = (0, utils_1.toScaledU64)(a.size ?? 0, a.sizeDecimals);
+            const scaledQuote = a.quoteSize
+                ? a.quoteSize.toWire(a.priceDecimals, a.sizeDecimals)
+                : undefined;
+            // Require at least one limit to be set (non-zero size, non-zero price, or quoteSize)
+            (0, utils_1.assert)(price > 0n || size > 0n || scaledQuote !== undefined, "OrderLimit must include at least one of: size, price, or quoteSize");
+            const tradeOrPlace = (0, protobuf_1.create)(proto.TradeOrPlaceSchema, {
+                marketId: a.marketId,
+                orderType: (0, protobuf_1.create)(proto.OrderTypeSchema, {
+                    side: a.side === types_1.Side.Bid ? proto.Side.BID : proto.Side.ASK,
+                    fillMode: (0, types_1.fillModeToProtoFillMode)(a.fillMode),
+                    isReduceOnly: a.isReduceOnly,
+                }),
+                limit: (0, protobuf_1.create)(proto.OrderLimitSchema, {
+                    price,
+                    size,
+                    quoteSize: scaledQuote === undefined
+                        ? undefined
+                        : (0, protobuf_1.create)(proto.QuoteSizeSchema, {
+                            size: scaledQuote.size,
+                            price: scaledQuote.price,
+                        }),
+                }),
+                clientOrderId: a.clientOrderId === undefined ? undefined : BigInt(a.clientOrderId),
+            });
+            return (0, protobuf_1.create)(proto.AtomicSubactionKindSchema, {
+                inner: { case: "tradeOrPlace", value: tradeOrPlace },
+            });
+        }
+        return (0, protobuf_1.create)(proto.AtomicSubactionKindSchema, {
+            inner: {
+                case: "cancelOrder",
+                value: (0, protobuf_1.create)(proto.CancelOrderSchema, { orderId: BigInt(a.orderId) }),
+            },
+        });
+    });
+    const action = createAction(currentTimestamp, nonce, {
+        case: "atomic",
+        value: (0, protobuf_1.create)(proto.AtomicSchema, {
+            sessionId: BigInt(params.sessionId),
+            accountId: params.accountId, // optional
+            actions: subactions,
+        }),
+    });
+    const resp = await sendAction(serverUrl, (m) => sessionSign(signFn, m), action, client);
+    if (resp.kind?.case === "atomic") {
+        return {
+            actionId: resp.actionId,
+            results: resp.kind.value.results,
+        };
+    }
+    throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+}

package/dist/nord/api/core.d.ts

@@ -0,0 +1,16 @@
+import { SubscriptionPattern } from "../../types";
+import { NordWebSocketClient } from "../../websocket/index";
+/**
+ * Initialize a WebSocket client for Nord
+ *
+ * Connects to the Nord WebSocket endpoint with support for multiple subscription types:
+ * - trades@SYMBOL - For trade updates
+ * - deltas@SYMBOL - For orderbook delta updates
+ * - account@ACCOUNT_ID - For user-specific updates
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param subscriptions - Array of subscriptions (e.g., ["trades@BTCUSDC", "deltas@BTCUSDC", "account@42"])
+ * @returns WebSocket client
+ * @throws {NordError} If initialization fails or invalid subscription is provided
+ */
+export declare function initWebSocketClient(webServerUrl: string, subscriptions?: SubscriptionPattern[] | "trades" | "delta" | "account"): NordWebSocketClient;

package/dist/nord/api/core.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initWebSocketClient = initWebSocketClient;
+const index_1 = require("../../websocket/index");
+const NordError_1 = require("../utils/NordError");
+/**
+ * Initialize a WebSocket client for Nord
+ *
+ * Connects to the Nord WebSocket endpoint with support for multiple subscription types:
+ * - trades@SYMBOL - For trade updates
+ * - deltas@SYMBOL - For orderbook delta updates
+ * - account@ACCOUNT_ID - For user-specific updates
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param subscriptions - Array of subscriptions (e.g., ["trades@BTCUSDC", "deltas@BTCUSDC", "account@42"])
+ * @returns WebSocket client
+ * @throws {NordError} If initialization fails or invalid subscription is provided
+ */
+function initWebSocketClient(webServerUrl, subscriptions) {
+    try {
+        // Determine URL and subscriptions based on parameters
+        let wsUrl = webServerUrl.replace(/^http/, "ws") + `/ws`;
+        // Validate subscriptions parameter
+        if (typeof subscriptions === "string") {
+            // Legacy mode - handle endpoint string
+            if (subscriptions === "trades" ||
+                subscriptions === "delta" ||
+                subscriptions === "account") {
+                wsUrl += `/${subscriptions}`;
+            }
+            else {
+                throw new NordError_1.NordError(`Invalid endpoint: ${subscriptions}. Must be "trades", "deltas", or "account".`);
+            }
+        }
+        else if (Array.isArray(subscriptions) && subscriptions.length > 0) {
+            // New mode - validate and combine subscriptions in URL
+            subscriptions.forEach(validateSubscription);
+            wsUrl += `/${subscriptions.join("&")}`;
+        }
+        else {
+            // Default to trades endpoint if no subscriptions specified
+            wsUrl += `/trades`;
+        }
+        console.log(`Initializing WebSocket client with URL: ${wsUrl}`);
+        // Create and connect the WebSocket client
+        const ws = new index_1.NordWebSocketClient(wsUrl);
+        // Add error handler
+        ws.on("error", (error) => {
+            console.error("Nord WebSocket error:", error);
+        });
+        // Add connected handler for debugging
+        ws.on("connected", () => {
+            console.log("Nord WebSocket connected successfully");
+        });
+        // Connect the WebSocket
+        ws.connect();
+        return ws;
+    }
+    catch (error) {
+        console.error("Failed to initialize WebSocket client:", error);
+        throw new NordError_1.NordError("Failed to initialize WebSocket client", {
+            cause: error,
+        });
+    }
+}
+/**
+ * Validates a subscription string follows the correct format
+ *
+ * @param subscription - The subscription to validate
+ * @throws {NordError} If the subscription format is invalid
+ */
+function validateSubscription(subscription) {
+    const [type, param] = subscription.split("@");
+    if (!type || !param || !["trades", "deltas", "account"].includes(type)) {
+        throw new NordError_1.NordError(`Invalid subscription format: ${subscription}. Expected format: "trades@SYMBOL", "deltas@SYMBOL", or "account@ID"`);
+    }
+    // Additional validation for account subscriptions
+    if (type === "account" && isNaN(Number(param))) {
+        throw new NordError_1.NordError(`Invalid account ID in subscription: ${subscription}. Account ID must be a number.`);
+    }
+}

package/dist/nord/api/metrics.d.ts

@@ -0,0 +1,67 @@
+import { AggregateMetrics, PeakTpsPeriodUnit } from "../../types";
+/**
+ * Time periods for metrics queries
+ */
+export declare enum MetricPeriod {
+    ONE_MINUTE = "1m",
+    FIVE_MINUTES = "5m",
+    FIFTEEN_MINUTES = "15m",
+    ONE_HOUR = "1h",
+    FOUR_HOURS = "4h",
+    ONE_DAY = "24h",
+    ONE_WEEK = "7d"
+}
+/**
+ * Fetch aggregate metrics from the Nord API
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param txPeakTpsPeriod - Period for peak TPS calculation
+ * @param txPeakTpsPeriodUnit - Unit for peak TPS period
+ * @returns Aggregate metrics
+ * @throws {NordError} If the request fails
+ */
+export declare function aggregateMetrics(webServerUrl: string, txPeakTpsPeriod?: number, txPeakTpsPeriodUnit?: PeakTpsPeriodUnit): Promise<AggregateMetrics>;
+/**
+ * Get current transactions per second
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param period - Time period for the query
+ * @returns Current TPS value
+ * @throws {NordError} If the request fails
+ */
+export declare function getCurrentTps(webServerUrl: string, period?: string): Promise<number>;
+/**
+ * Get peak transactions per second
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param period - Time period for the query
+ * @returns Peak TPS value
+ * @throws {NordError} If the request fails
+ */
+export declare function getPeakTps(webServerUrl: string, period?: string): Promise<number>;
+/**
+ * Get median transaction latency
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param period - Time period for the query
+ * @returns Median latency in milliseconds
+ * @throws {NordError} If the request fails
+ */
+export declare function getMedianLatency(webServerUrl: string, period?: string): Promise<number>;
+/**
+ * Get total transaction count
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @returns Total transaction count
+ * @throws {NordError} If the request fails
+ */
+export declare function getTotalTransactions(webServerUrl: string): Promise<number>;
+/**
+ * Query Prometheus metrics
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param params - Prometheus query parameters
+ * @returns Query result as a number
+ * @throws {NordError} If the request fails
+ */
+export declare function queryPrometheus(webServerUrl: string, params: string): Promise<number>;