@n1xyz/nord-ts 0.2.0 → 0.3.1

package/dist/nord/client/Nord.js

@@ -0,0 +1,747 @@
+"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.Nord = void 0;
+const proton_1 = require("@n1xyz/proton");
+const web3_js_1 = require("@solana/web3.js");
+const events_1 = require("events");
+const openapi_fetch_1 = __importDefault(require("openapi-fetch"));
+const proto = __importStar(require("../../gen/nord_pb"));
+const types_1 = require("../../types");
+const utils = __importStar(require("../../utils"));
+const core = __importStar(require("../api/core"));
+const metrics = __importStar(require("../api/metrics"));
+const NordError_1 = require("../utils/NordError");
+/**
+ * Main Nord client class for interacting with the Nord API
+ */
+class Nord {
+    /**
+     * Create a new Nord client
+     *
+     * @param config - Configuration options for the Nord client
+     * @param config.webServerUrl - Base URL for the Nord web server
+     * @param config.solanaUrl - Solana cluster URL
+     * @throws {Error} If required configuration is missing
+     */
+    constructor({ solanaUrl, webServerUrl, protonClient, }) {
+        /** Available markets */
+        this.markets = [];
+        /** Available tokens */
+        this.tokens = [];
+        /** Map of symbol to market_id */
+        this.symbolToMarketId = new Map();
+        this.webServerUrl = webServerUrl;
+        this.solanaUrl = solanaUrl;
+        this.protonClient = protonClient;
+        this.client = (0, openapi_fetch_1.default)({ baseUrl: webServerUrl });
+    }
+    /**
+     * Create a WebSocket client with specific subscriptions
+     *
+     * @param options - Subscription options that specify which data streams to subscribe to
+     * @returns A new WebSocket client with the requested subscriptions
+     * @throws {NordError} If invalid subscription options are provided
+     *
+     * @example
+     * // Create a client for trades and deltas from one market and an account
+     * const wsClient = nord.createWebSocketClient({
+     *   trades: ["BTCUSDC"],
+     *   deltas: ["BTCUSDC"],
+     *   accounts: [123]
+     * });
+     *
+     * @example
+     * // Create a client for trades from multiple markets
+     * const tradesClient = nord.createWebSocketClient({
+     *   trades: ["BTCUSDC", "ETHUSDC"]
+     * });
+     */
+    createWebSocketClient(options) {
+        const subscriptions = [];
+        // Add trade subscriptions
+        if (options.trades && options.trades.length > 0) {
+            options.trades.forEach((symbol) => {
+                subscriptions.push(`trades@${symbol}`);
+            });
+        }
+        // Add delta subscriptions
+        if (options.deltas && options.deltas.length > 0) {
+            options.deltas.forEach((symbol) => {
+                subscriptions.push(`deltas@${symbol}`);
+            });
+        }
+        // Add account subscriptions
+        if (options.accounts && options.accounts.length > 0) {
+            options.accounts.forEach((accountId) => {
+                if (isNaN(accountId) || accountId <= 0) {
+                    throw new NordError_1.NordError(`Invalid account ID: ${accountId}. Must be a positive number.`);
+                }
+                subscriptions.push(`account@${accountId}`);
+            });
+        }
+        // Validate that at least one subscription was provided
+        if (subscriptions.length === 0) {
+            throw new NordError_1.NordError("At least one subscription must be provided");
+        }
+        // Create and return a new WebSocket client
+        return core.initWebSocketClient(this.webServerUrl, subscriptions);
+    }
+    async GET(path, options) {
+        const r = await this.client.GET(path, options);
+        if (r.error) {
+            throw new NordError_1.NordError(`failed to GET ${path}`, { cause: r.error });
+        }
+        if (r.data === undefined) {
+            // this should never happen, but the type checker seems unhappy.
+            // if we catch this we'll need to debug accordingly.
+            throw new NordError_1.NordError("internal assertion violation", { cause: r });
+        }
+        return r.data;
+    }
+    /**
+     * Get the current timestamp from the Nord server
+     *
+     * @returns Current timestamp as a bigint
+     * @throws {NordError} If the request fails
+     */
+    async getTimestamp() {
+        return BigInt(await this.GET("/timestamp", {}));
+    }
+    /**
+     * Get the last event nonce from the Nord server
+     *
+     * @returns Next action nonce
+     * @throws {NordError} If the request fails
+     */
+    async getActionNonce() {
+        return await this.GET("/event/last-acked-nonce", {});
+    }
+    /**
+     * Fetch information about Nord markets and tokens
+     *
+     * @throws {NordError} If the request fails
+     */
+    async fetchNordInfo() {
+        try {
+            const info = await this.GET("/info", {});
+            this.markets = info.markets;
+            this.tokens = info.tokens;
+            // Populate the symbolToMarketId map
+            this.symbolToMarketId.clear();
+            info.markets.forEach((market) => {
+                this.symbolToMarketId.set(market.symbol, market.marketId);
+            });
+        }
+        catch (error) {
+            throw new NordError_1.NordError("Failed to fetch Nord info", { cause: error });
+        }
+    }
+    /**
+     * Initialize a new Nord client
+     *
+     * @param nordConfig - Configuration options for the Nord client
+     * @param nordConfig.webServerUrl - Base URL for the Nord web server
+     * @param nordConfig.app - App address
+     * @param nordConfig.solanaUrl - Solana cluster URL
+     * @returns Initialized Nord client
+     * @throws {NordError} If initialization fails
+     */
+    static async initNord({ app, solanaUrl, webServerUrl, protonUrl, }) {
+        // TODO: we should parametrize the connectionn not have it done here.
+        // this is a dogshit api, only here to be compatible with the shitty
+        // vibecoded code and not break zero one team's workflow.
+        const connection = new web3_js_1.Connection(solanaUrl, { commitment: "confirmed" });
+        const protonClient = await proton_1.ProtonClient.init({
+            protonUrl: protonUrl ?? webServerUrl,
+            app: new web3_js_1.PublicKey(app),
+            solConn: connection,
+        });
+        const nord = new Nord({
+            protonClient,
+            solanaUrl,
+            webServerUrl,
+        });
+        await nord.init();
+        return nord;
+    }
+    /**
+     * Initialize the Nord client
+     * @private
+     */
+    async init() {
+        await this.fetchNordInfo();
+    }
+    /**
+     * Query a specific action
+     *
+     * @param query - Action query parameters
+     * @returns Action response
+     * @throws {NordError} If the request fails
+     */
+    async queryAction({ action_id, }) {
+        return ((await this.queryRecentActions({
+            from: action_id,
+            to: action_id,
+        }))[0] ?? null);
+    }
+    /**
+     * Query recent actions
+     *
+     * @param from - Starting action index
+     * @param to - Ending action index
+     * @returns Actions response
+     * @throws {NordError} If the request fails
+     */
+    async queryRecentActions(query) {
+        const xs = await this.GET("/action", {
+            params: {
+                query,
+            },
+        });
+        return xs.map((x) => ({
+            actionId: x.actionId,
+            action: utils.decodeLengthDelimited(Buffer.from(x.payload, "base64"), proto.ActionSchema),
+            physicalExecTime: new Date(x.physicalTime),
+        }));
+    }
+    /**
+     * Get the last action ID
+     *
+     * @returns Last action ID
+     * @throws {NordError} If the request fails
+     */
+    async getLastActionId() {
+        return await this.GET("/action/last-executed-id", {});
+    }
+    /**
+     * Fetch aggregate metrics from the Nord API
+     *
+     * @param txPeakTpsPeriod - Period for peak TPS calculation
+     * @param txPeakTpsPeriodUnit - Unit for peak TPS period
+     * @returns Aggregate metrics
+     * @throws {NordError} If the request fails
+     */
+    async aggregateMetrics(txPeakTpsPeriod = 1, txPeakTpsPeriodUnit = types_1.PeakTpsPeriodUnit.Day) {
+        return metrics.aggregateMetrics(this.webServerUrl, txPeakTpsPeriod, txPeakTpsPeriodUnit);
+    }
+    /**
+     * Get current transactions per second
+     *
+     * @param period - Time period for the query
+     * @returns Current TPS value
+     * @throws {NordError} If the request fails
+     */
+    async getCurrentTps(period = "1m") {
+        return metrics.getCurrentTps(this.webServerUrl, period);
+    }
+    /**
+     * Get peak transactions per second
+     *
+     * @param period - Time period for the query
+     * @returns Peak TPS value
+     * @throws {NordError} If the request fails
+     */
+    async getPeakTps(period = "24h") {
+        return metrics.getPeakTps(this.webServerUrl, period);
+    }
+    /**
+     * Get median transaction latency
+     *
+     * @param period - Time period for the query
+     * @returns Median latency in milliseconds
+     * @throws {NordError} If the request fails
+     */
+    async getMedianLatency(period = "1m") {
+        return metrics.getMedianLatency(this.webServerUrl, period);
+    }
+    /**
+     * Get total transaction count
+     *
+     * @returns Total transaction count
+     * @throws {NordError} If the request fails
+     */
+    async getTotalTransactions() {
+        return metrics.getTotalTransactions(this.webServerUrl);
+    }
+    /**
+     * Query Prometheus metrics
+     *
+     * @param params - Prometheus query parameters
+     * @returns Query result as a number
+     * @throws {NordError} If the request fails
+     */
+    async queryPrometheus(params) {
+        return metrics.queryPrometheus(this.webServerUrl, params);
+    }
+    /**
+     * Subscribe to orderbook updates for a market
+     *
+     * @param symbol - Market symbol
+     * @returns Orderbook subscription
+     * @throws {NordError} If symbol is invalid
+     */
+    subscribeOrderbook(symbol) {
+        if (!symbol || typeof symbol !== "string") {
+            throw new NordError_1.NordError("Invalid market symbol");
+        }
+        const subscription = new events_1.EventEmitter();
+        const wsClient = this.createWebSocketClient({
+            deltas: [symbol],
+        });
+        const handleDelta = (update) => {
+            if (update.symbol !== symbol) {
+                return;
+            }
+            subscription.emit("message", update);
+        };
+        wsClient.on("delta", handleDelta);
+        subscription.close = () => {
+            wsClient.removeListener("delta", handleDelta);
+            subscription.removeAllListeners();
+        };
+        return subscription;
+    }
+    /**
+     * Subscribe to trade updates for a market
+     *
+     * @param symbol - Market symbol
+     * @returns Trade subscription
+     * @throws {NordError} If symbol is invalid
+     */
+    subscribeTrades(symbol) {
+        if (!symbol || typeof symbol !== "string") {
+            throw new NordError_1.NordError("Invalid market symbol");
+        }
+        const subscription = new events_1.EventEmitter();
+        const wsClient = this.createWebSocketClient({
+            trades: [symbol],
+        });
+        const handleTrade = (update) => {
+            if (update.symbol !== symbol) {
+                return;
+            }
+            subscription.emit("message", update);
+        };
+        wsClient.on("trades", handleTrade);
+        subscription.close = () => {
+            wsClient.removeListener("trades", handleTrade);
+            subscription.removeAllListeners();
+        };
+        return subscription;
+    }
+    /**
+     * Subscribe to account updates
+     *
+     * @param accountId - Account ID to subscribe to
+     * @returns User subscription
+     * @throws {NordError} If accountId is invalid
+     */
+    subscribeAccount(accountId) {
+        if (isNaN(accountId) || accountId <= 0) {
+            throw new NordError_1.NordError("Invalid account ID");
+        }
+        const subscription = new events_1.EventEmitter();
+        const wsClient = this.createWebSocketClient({
+            accounts: [accountId],
+        });
+        const handleAccountUpdate = (update) => {
+            if (update.account_id !== accountId) {
+                return;
+            }
+            subscription.emit("message", update);
+        };
+        wsClient.on("account", handleAccountUpdate);
+        subscription.close = () => {
+            wsClient.removeListener("account", handleAccountUpdate);
+            subscription.removeAllListeners();
+        };
+        return subscription;
+    }
+    /**
+     * Get trades for a market
+     *
+     * @param query - Trades query parameters
+     * @returns Trades response
+     * @throws {NordError} If the request fails
+     */
+    async getTrades(query) {
+        if (query.sinceRcf3339 && !utils.isRfc3339(query.sinceRcf3339)) {
+            throw new NordError_1.NordError(`Invalid RFC3339 timestamp: ${query.sinceRcf3339}`);
+        }
+        if (query.untilRfc3339 && !utils.isRfc3339(query.untilRfc3339)) {
+            throw new NordError_1.NordError(`Invalid RFC3339 timestamp: ${query.untilRfc3339}`);
+        }
+        return await this.GET("/trades", {
+            params: {
+                query: {
+                    takerId: query.takerId,
+                    makerId: query.makerId,
+                    marketId: query.marketId,
+                    pageSize: query.pageSize,
+                    takerSide: query.takerSide,
+                    since: query.sinceRcf3339,
+                    until: query.untilRfc3339,
+                    startInclusive: query.pageId,
+                },
+            },
+        });
+    }
+    /**
+     * Get user account IDs
+     *
+     * @param query - User account IDs query parameters
+     * @returns User account IDs response
+     * @throws {NordError} If the request fails
+     */
+    async getUser(query) {
+        const r = await this.client.GET("/user/{pubkey}", {
+            params: {
+                path: { pubkey: query.pubkey.toString() },
+            },
+        });
+        if (r.response.status === 404) {
+            return null;
+        }
+        return r.data;
+    }
+    /**
+     * Get orderbook for a market
+     *
+     * @param query - Orderbook query parameters (either market_id or symbol must be provided)
+     * @returns Orderbook response
+     * @throws {NordError} If the request fails or if the market symbol is unknown
+     * @remarks It's recommended to initialize the Nord client using the static `initNord` method
+     * to ensure market information is properly loaded before calling this method.
+     */
+    async getOrderbook(query) {
+        // If only symbol is provided, convert it to market_id
+        let marketId;
+        if (query.symbol && query.market_id === undefined) {
+            // If the map is empty, try to fetch market information first
+            if (this.symbolToMarketId.size === 0) {
+                await this.fetchNordInfo();
+            }
+            const id = this.symbolToMarketId.get(query.symbol);
+            if (id === undefined) {
+                throw new NordError_1.NordError(`Unknown market symbol: ${query.symbol}`);
+            }
+            marketId = id;
+        }
+        else if (query.market_id !== undefined) {
+            marketId = query.market_id;
+        }
+        else {
+            throw new NordError_1.NordError("Either symbol or market_id must be provided for orderbook query");
+        }
+        return await this.GET("/market/{market_id}/orderbook", {
+            params: {
+                path: { market_id: marketId },
+            },
+        });
+    }
+    /**
+     * Get information about the Nord server
+     *
+     * @returns Information about markets and tokens
+     * @throws {NordError} If the request fails
+     */
+    async getInfo() {
+        return await this.GET("/info", {});
+    }
+    /**
+     * Fetch the current fee tier brackets configured on Nord.
+     *
+     * @returns Array of fee tier identifiers paired with their configuration
+     * @throws {NordError} If the request fails
+     */
+    async getFeeBrackets() {
+        return await this.GET("/fee/brackets/info", {});
+    }
+    /**
+     * Retrieve the fee tier assigned to a specific account.
+     *
+     * @param accountId - Account identifier to query
+     * @returns Fee tier details for the requested account
+     * @throws {NordError} If the request fails
+     */
+    async getAccountFeeTier(accountId) {
+        return await this.GET("/account/{account_id}/fee/tier", {
+            params: {
+                path: { account_id: accountId },
+            },
+        });
+    }
+    /**
+     * Get account information
+     *
+     * @param accountId - Account ID to get information for
+     * @returns Account information
+     * @throws {NordError} If the request fails
+     */
+    async getAccount(accountId) {
+        return await this.GET("/account/{account_id}", {
+            params: {
+                path: { account_id: accountId },
+            },
+        });
+    }
+    /**
+     * Get the public key associated with an account id.
+     *
+     * @param accountId - Account id to query
+     * @returns Base58-encoded account public key
+     * @throws {NordError} If the request fails
+     */
+    async getAccountPubkey(accountId) {
+        return await this.GET("/account/{account_id}/pubkey", {
+            params: {
+                path: { account_id: accountId },
+            },
+        });
+    }
+    /**
+     * Get the withdrawal fee charged for an account.
+     *
+     * @param accountId - Account id to query
+     * @returns Withdrawal fee quoted in quote token units
+     * @throws {NordError} If the request fails
+     */
+    async getAccountWithdrawalFee(accountId) {
+        return await this.GET("/account/{account_id}/fees/withdrawal", {
+            params: {
+                path: { account_id: accountId },
+            },
+        });
+    }
+    /**
+     * Get open orders for an account.
+     *
+     * @param accountId - Account id to query
+     * @param query - Optional pagination parameters
+     * @returns Page of orders keyed by client order id
+     * @throws {NordError} If the request fails
+     */
+    async getAccountOrders(accountId, query) {
+        return await this.GET("/account/{account_id}/orders", {
+            params: {
+                path: { account_id: accountId },
+                query: {
+                    startInclusive: query?.startInclusive,
+                    pageSize: query?.pageSize,
+                },
+            },
+        });
+    }
+    /**
+     * List account fee tiers with pagination support.
+     */
+    async getAccountsFeeTiers(query) {
+        return await this.GET("/accounts/fee-tiers", {
+            params: {
+                query: {
+                    startInclusive: query?.startInclusive ?? undefined,
+                    pageSize: query?.pageSize ?? undefined,
+                },
+            },
+        });
+    }
+    /**
+     * Get profit and loss history for an account
+     *
+     * @param accountId - Account ID to query
+     * @param query - Optional time and pagination filters
+     * @returns Page of PnL entries ordered from latest to oldest
+     * @throws {NordError} If the request fails
+     */
+    async getAccountPnl(accountId, query) {
+        return await this.GET("/account/{account_id}/pnl", {
+            params: {
+                path: { account_id: accountId },
+                query: {
+                    since: query?.since,
+                    until: query?.until,
+                    startInclusive: query?.startInclusive,
+                    pageSize: query?.pageSize,
+                },
+            },
+        });
+    }
+    /**
+     * Get market statistics (alias for marketsStats for backward compatibility)
+     *
+     * @returns Market statistics response
+     */
+    async getMarketStats({ marketId, }) {
+        return await this.GET("/market/{market_id}/stats", {
+            params: {
+                path: { market_id: marketId },
+            },
+        });
+    }
+    /**
+     * Fetch the per-market fee quote for an account.
+     *
+     * @param params - Market id, fee kind, and account id to quote
+     * @returns Fee in quote token units (negative means fee is charged)
+     * @throws {NordError} If the request fails
+     */
+    async getMarketFee({ marketId, feeKind, accountId, }) {
+        return await this.GET("/market/{market_id}/fees/{fee_kind}/{account_id}", {
+            params: {
+                path: {
+                    market_id: marketId,
+                    fee_kind: feeKind,
+                    account_id: accountId,
+                },
+            },
+        });
+    }
+    /**
+     * Fetch token statistics such as index price and oracle metadata.
+     *
+     * @param tokenId - Token identifier
+     * @returns Token stats
+     * @throws {NordError} If the request fails
+     */
+    async getTokenStats(tokenId) {
+        return await this.GET("/tokens/{token_id}/stats", {
+            params: {
+                path: { token_id: tokenId },
+            },
+        });
+    }
+    /**
+     * Get order summary by order id.
+     *
+     * @param orderId - Order identifier
+     * @returns Order information
+     * @throws {NordError} If the request fails
+     */
+    async getOrder(orderId) {
+        return await this.GET("/order/{order_id}", {
+            params: {
+                path: { order_id: orderId },
+            },
+        });
+    }
+    /**
+     * Get trade history for a specific order.
+     *
+     * @param orderId - Order identifier
+     * @param query - Optional pagination parameters
+     * @returns Page of trades associated with the order
+     * @throws {NordError} If the request fails
+     */
+    async getOrderTrades(orderId, query) {
+        return await this.GET("/order/{order_id}/trades", {
+            params: {
+                path: { order_id: orderId },
+                query: {
+                    startInclusive: query?.startInclusive,
+                    pageSize: query?.pageSize,
+                },
+            },
+        });
+    }
+    /**
+     * Check if an account exists for the given address
+     *
+     * @param address - The public key address to check
+     * @returns True if the account exists, false otherwise
+     * @deprecated use getUser instead
+     */
+    async accountExists(pubkey) {
+        return !!(await this.getUser({ pubkey }));
+    }
+    /**
+     * Fetch active triggers for an account.
+     *
+     * @param params Optional parameters containing an explicit account id.
+     * @throws {NordError} If no account can be resolved or the request fails.
+     */
+    async getAccountTriggers(params) {
+        const accountId = params?.accountId;
+        if (accountId == null) {
+            throw new NordError_1.NordError("Account ID is undefined. Make sure to call updateAccountId() before requesting triggers.");
+        }
+        try {
+            const triggers = await this.GET("/account/{account_id}/triggers", {
+                params: {
+                    path: { account_id: accountId },
+                },
+            });
+            return triggers ?? [];
+        }
+        catch (error) {
+            throw new NordError_1.NordError("Failed to fetch account triggers", { cause: error });
+        }
+    }
+    /**
+     * Fetch trigger history for an account.
+     *
+     * @param params Optional parameters with account id and history query filters.
+     * @throws {NordError} If no account can be resolved or the request fails.
+     */
+    async getAccountTriggerHistory(params) {
+        const accountId = params?.accountId;
+        if (accountId == null) {
+            throw new NordError_1.NordError("Account ID is undefined. Make sure to call updateAccountId() before requesting trigger history.");
+        }
+        const { accountId: _, ...query } = params;
+        try {
+            return await this.GET("/account/{account_id}/triggers/history", {
+                params: {
+                    path: { account_id: accountId },
+                    query: {
+                        since: query.since,
+                        until: query.until,
+                        pageSize: query.pageSize,
+                        startInclusive: query.startInclusive,
+                    },
+                },
+            });
+        }
+        catch (error) {
+            throw new NordError_1.NordError("Failed to fetch account trigger history", {
+                cause: error,
+            });
+        }
+    }
+}
+exports.Nord = Nord;