@n1xyz/nord-ts 0.0.1 → 0.0.5

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

@@ -0,0 +1,81 @@
+import { ActionQuery, ActionResponse, ActionsResponse, BlockQuery, BlockResponse, BlockSummaryResponse, RollmanActionResponse, RollmanActionsResponse, RollmanBlockResponse } from "../../types";
+/**
+ * Query a specific block
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param query - Block query parameters
+ * @returns Block response
+ * @throws {NordError} If the request fails
+ */
+export declare function queryBlock(webServerUrl: string, query: BlockQuery): Promise<BlockResponse>;
+/**
+ * Query the last N blocks
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @returns Block response for the last N blocks
+ * @throws {NordError} If the request fails
+ */
+export declare function queryLastNBlocks(webServerUrl: string): Promise<BlockResponse>;
+/**
+ * Query recent blocks
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param last_n - Number of recent blocks to query
+ * @returns Block summary response
+ * @throws {NordError} If the request fails
+ */
+export declare function queryRecentBlocks(webServerUrl: string, last_n: number): Promise<BlockSummaryResponse>;
+/**
+ * Query a specific action
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param query - Action query parameters
+ * @returns Action response
+ * @throws {NordError} If the request fails
+ */
+export declare function queryAction(webServerUrl: string, query: ActionQuery): Promise<ActionResponse>;
+/**
+ * Query recent actions
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param last_n - Number of recent actions to query
+ * @returns Actions response
+ * @throws {NordError} If the request fails
+ */
+export declare function queryRecentActions(webServerUrl: string, last_n: number): Promise<ActionsResponse>;
+/**
+ * Query a block from Rollman
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param query - Block query parameters
+ * @returns Rollman block response
+ * @throws {NordError} If the request fails
+ */
+export declare function blockQueryRollman(webServerUrl: string, query: BlockQuery): Promise<RollmanBlockResponse>;
+/**
+ * Query block summaries from Rollman
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param last_n - Number of recent blocks to query
+ * @returns Block summary response
+ * @throws {NordError} If the request fails
+ */
+export declare function blockSummaryQueryRollman(webServerUrl: string, last_n: number): Promise<BlockSummaryResponse>;
+/**
+ * Query an action from Rollman
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param query - Action query parameters
+ * @returns Rollman action response
+ * @throws {NordError} If the request fails
+ */
+export declare function actionQueryRollman(webServerUrl: string, query: ActionQuery): Promise<RollmanActionResponse>;
+/**
+ * Query actions from Rollman
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param last_n - Number of recent actions to query
+ * @returns Rollman actions response
+ * @throws {NordError} If the request fails
+ */
+export declare function actionsQueryRollman(webServerUrl: string, last_n: number): Promise<RollmanActionsResponse>;

package/dist/nord/api/queries.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryBlock = queryBlock;
+exports.queryLastNBlocks = queryLastNBlocks;
+exports.queryRecentBlocks = queryRecentBlocks;
+exports.queryAction = queryAction;
+exports.queryRecentActions = queryRecentActions;
+exports.blockQueryRollman = blockQueryRollman;
+exports.blockSummaryQueryRollman = blockSummaryQueryRollman;
+exports.actionQueryRollman = actionQueryRollman;
+exports.actionsQueryRollman = actionsQueryRollman;
+const utils_1 = require("../../utils");
+const NordError_1 = require("../utils/NordError");
+/**
+ * Query a specific block
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param query - Block query parameters
+ * @returns Block response
+ * @throws {NordError} If the request fails
+ */
+async function queryBlock(webServerUrl, query) {
+    try {
+        const params = new URLSearchParams();
+        if (query.block_number !== undefined) {
+            params.append("block_height", query.block_number.toString());
+        }
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/block?${params.toString()}`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError("Failed to query block", { cause: error });
+    }
+}
+/**
+ * Query the last N blocks
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @returns Block response for the last N blocks
+ * @throws {NordError} If the request fails
+ */
+async function queryLastNBlocks(webServerUrl) {
+    try {
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/blocks`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError("Failed to query last N blocks", { cause: error });
+    }
+}
+/**
+ * Query recent blocks
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param last_n - Number of recent blocks to query
+ * @returns Block summary response
+ * @throws {NordError} If the request fails
+ */
+async function queryRecentBlocks(webServerUrl, last_n) {
+    try {
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/blocks_summary?last_n=${last_n}`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError(`Failed to query recent blocks (last ${last_n})`, {
+            cause: error,
+        });
+    }
+}
+/**
+ * Query a specific action
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param query - Action query parameters
+ * @returns Action response
+ * @throws {NordError} If the request fails
+ */
+async function queryAction(webServerUrl, query) {
+    try {
+        const params = new URLSearchParams();
+        if (query.action_id !== undefined) {
+            params.append("action_id", query.action_id.toString());
+        }
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/action?${params.toString()}`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError("Failed to query action", { cause: error });
+    }
+}
+/**
+ * Query recent actions
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param last_n - Number of recent actions to query
+ * @returns Actions response
+ * @throws {NordError} If the request fails
+ */
+async function queryRecentActions(webServerUrl, last_n) {
+    try {
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/actions?last_n=${last_n}`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError(`Failed to query recent actions (last ${last_n})`, {
+            cause: error,
+        });
+    }
+}
+/**
+ * Query a block from Rollman
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param query - Block query parameters
+ * @returns Rollman block response
+ * @throws {NordError} If the request fails
+ */
+async function blockQueryRollman(webServerUrl, query) {
+    try {
+        const params = new URLSearchParams();
+        if (query.block_number !== undefined) {
+            params.append("block_height", query.block_number.toString());
+        }
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/rollman/block?${params.toString()}`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError("Failed to query Rollman block", { cause: error });
+    }
+}
+/**
+ * Query block summaries from Rollman
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param last_n - Number of recent blocks to query
+ * @returns Block summary response
+ * @throws {NordError} If the request fails
+ */
+async function blockSummaryQueryRollman(webServerUrl, last_n) {
+    try {
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/rollman/blocks_summary?last_n=${last_n}`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError(`Failed to query Rollman block summaries (last ${last_n})`, { cause: error });
+    }
+}
+/**
+ * Query an action from Rollman
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param query - Action query parameters
+ * @returns Rollman action response
+ * @throws {NordError} If the request fails
+ */
+async function actionQueryRollman(webServerUrl, query) {
+    try {
+        const params = new URLSearchParams();
+        if (query.action_id !== undefined) {
+            params.append("action_id", query.action_id.toString());
+        }
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/rollman/action?${params.toString()}`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError("Failed to query Rollman action", { cause: error });
+    }
+}
+/**
+ * Query actions from Rollman
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @param last_n - Number of recent actions to query
+ * @returns Rollman actions response
+ * @throws {NordError} If the request fails
+ */
+async function actionsQueryRollman(webServerUrl, last_n) {
+    try {
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/rollman/actions?last_n=${last_n}`);
+        return await response.json();
+    }
+    catch (error) {
+        throw new NordError_1.NordError(`Failed to query Rollman actions (last ${last_n})`, {
+            cause: error,
+        });
+    }
+}

package/dist/nord/client/Nord.d.ts

@@ -0,0 +1,335 @@
+import { EventEmitter } from "events";
+import { Account, ActionQuery, ActionResponse, ActionsResponse, AggregateMetrics, BlockQuery, BlockResponse, BlockSummaryResponse, Info, Market, MarketsStatsResponse, NordConfig, OrderbookQuery, OrderbookResponse, PeakTpsPeriodUnit, RollmanActionResponse, RollmanActionsResponse, RollmanBlockResponse, Token, TradesQuery, TradesResponse, UserAccountIdsQuery, UserAccountIdsResponse } from "../../types";
+import { NordWebSocketClient } from "../../websocket/index";
+import { OrderbookSubscription, TradeSubscription } from "../models/Subscriber";
+/**
+ * User subscription interface
+ */
+export interface UserSubscription extends EventEmitter {
+    close: () => void;
+}
+/**
+ * Main Nord client class for interacting with the Nord API
+ */
+export declare class Nord {
+    /** Base URL for the Nord web server */
+    readonly webServerUrl: string;
+    /** Solana program ID */
+    readonly solanaProgramId: string;
+    /** Solana RPC URL */
+    readonly solanaUrl: string;
+    /** Available markets */
+    markets: Market[];
+    /** Available tokens */
+    tokens: Token[];
+    /** Map of symbol to market_id */
+    private symbolToMarketId;
+    /**
+     * WebSocket client for trades
+     * @private
+     */
+    private tradesWs;
+    /**
+     * WebSocket client for orderbook deltas
+     * @private
+     */
+    private deltasWs;
+    /**
+     * WebSocket client for user updates
+     * @private
+     */
+    private userWs;
+    /**
+     * Initial subscriptions for the trades WebSocket
+     * @private
+     */
+    private tradesSubscriptions?;
+    /**
+     * Initial subscriptions for the deltas WebSocket
+     * @private
+     */
+    private deltasSubscriptions?;
+    /**
+     * 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.solanaProgramId - Solana program ID
+     * @param config.solanaUrl - Solana cluster URL
+     * @param config.initWebSockets - Whether to initialize WebSockets on creation, defaults to true
+     * @param config.tradesSubscriptions - Optional array of trades subscriptions to initialize with (e.g., ["trades@BTCUSDC"])
+     * @param config.deltasSubscriptions - Optional array of deltas subscriptions to initialize with (e.g., ["deltas@BTCUSDC"])
+     * @throws {Error} If required configuration is missing
+     */
+    constructor({ webServerUrl, solanaProgramId, solanaUrl, initWebSockets, tradesSubscriptions, deltasSubscriptions, }: NordConfig);
+    /**
+     * Initialize WebSocket clients for trades and deltas
+     *
+     * This method can be called manually if websockets were not initialized during construction
+     * (i.e., if initWebSockets was set to false in the constructor).
+     *
+     * It initializes the trades and deltas WebSocket clients. The user WebSocket client
+     * is initialized on demand when needed.
+     *
+     * @param tradesSubscriptions - Optional array of trades subscriptions to initialize with
+     * @param deltasSubscriptions - Optional array of deltas subscriptions to initialize with
+     */
+    initializeWebSockets(tradesSubscriptions?: string[], deltasSubscriptions?: string[]): void;
+    /**
+     * Get the current timestamp from the Nord server
+     *
+     * @returns Current timestamp as a bigint
+     * @throws {NordError} If the request fails
+     */
+    getTimestamp(): Promise<bigint>;
+    /**
+     * Get the next action nonce from the Nord server
+     *
+     * @returns Next action nonce
+     * @throws {NordError} If the request fails
+     */
+    getActionNonce(): Promise<number>;
+    /**
+     * Fetch information about Nord markets and tokens
+     *
+     * @throws {NordError} If the request fails
+     */
+    fetchNordInfo(): Promise<void>;
+    /**
+     * 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.solanaProgramId - Solana program ID
+     * @param nordConfig.solanaUrl - Solana cluster URL
+     * @param nordConfig.initWebSockets - Whether to initialize WebSockets on creation, defaults to true
+     * @param nordConfig.tradesSubscriptions - Optional array of trades subscriptions (e.g., ["trades@BTCUSDC"])
+     * @param nordConfig.deltasSubscriptions - Optional array of deltas subscriptions (e.g., ["deltas@BTCUSDC"])
+     * @returns Initialized Nord client
+     * @throws {NordError} If initialization fails
+     */
+    static initNord(nordConfig: NordConfig): Promise<Nord>;
+    /**
+     * Get market statistics
+     *
+     * @returns Market statistics response
+     * @throws {NordError} If the request fails
+     */
+    marketsStats(): Promise<MarketsStatsResponse>;
+    /**
+     * Query a specific block
+     *
+     * @param query - Block query parameters
+     * @returns Block response
+     * @throws {NordError} If the request fails
+     */
+    queryBlock(query: BlockQuery): Promise<BlockResponse>;
+    /**
+     * Query the last N blocks
+     *
+     * @returns Block response for the last N blocks
+     * @throws {NordError} If the request fails
+     */
+    queryLastNBlocks(): Promise<BlockResponse>;
+    /**
+     * Query recent blocks
+     *
+     * @param last_n - Number of recent blocks to query
+     * @returns Block summary response
+     * @throws {NordError} If the request fails
+     */
+    queryRecentBlocks(last_n: number): Promise<BlockSummaryResponse>;
+    /**
+     * Query a specific action
+     *
+     * @param query - Action query parameters
+     * @returns Action response
+     * @throws {NordError} If the request fails
+     */
+    queryAction(query: ActionQuery): Promise<ActionResponse>;
+    /**
+     * Query recent actions
+     *
+     * @param last_n - Number of recent actions to query
+     * @returns Actions response
+     * @throws {NordError} If the request fails
+     */
+    queryRecentActions(last_n: number): Promise<ActionsResponse>;
+    /**
+     * 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
+     */
+    aggregateMetrics(txPeakTpsPeriod?: number, txPeakTpsPeriodUnit?: PeakTpsPeriodUnit): Promise<AggregateMetrics>;
+    /**
+     * Get current transactions per second
+     *
+     * @param period - Time period for the query
+     * @returns Current TPS value
+     * @throws {NordError} If the request fails
+     */
+    getCurrentTps(period?: string): Promise<number>;
+    /**
+     * Get peak transactions per second
+     *
+     * @param period - Time period for the query
+     * @returns Peak TPS value
+     * @throws {NordError} If the request fails
+     */
+    getPeakTps(period?: string): Promise<number>;
+    /**
+     * Get median transaction latency
+     *
+     * @param period - Time period for the query
+     * @returns Median latency in milliseconds
+     * @throws {NordError} If the request fails
+     */
+    getMedianLatency(period?: string): Promise<number>;
+    /**
+     * Get total transaction count
+     *
+     * @returns Total transaction count
+     * @throws {NordError} If the request fails
+     */
+    getTotalTransactions(): Promise<number>;
+    /**
+     * Query a block from Rollman
+     *
+     * @param query - Block query parameters
+     * @returns Rollman block response
+     * @throws {NordError} If the request fails
+     */
+    blockQueryRollman(query: BlockQuery): Promise<RollmanBlockResponse>;
+    /**
+     * Query block summaries from Rollman
+     *
+     * @param last_n - Number of recent blocks to query
+     * @returns Block summary response
+     * @throws {NordError} If the request fails
+     */
+    blockSummaryQueryRollman(last_n: number): Promise<BlockSummaryResponse>;
+    /**
+     * Query an action from Rollman
+     *
+     * @param query - Action query parameters
+     * @returns Rollman action response
+     * @throws {NordError} If the request fails
+     */
+    actionQueryRollman(query: ActionQuery): Promise<RollmanActionResponse>;
+    /**
+     * Query actions from Rollman
+     *
+     * @param last_n - Number of recent actions to query
+     * @returns Rollman actions response
+     * @throws {NordError} If the request fails
+     */
+    actionsQueryRollman(last_n: number): Promise<RollmanActionsResponse>;
+    /**
+     * Query Prometheus metrics
+     *
+     * @param params - Prometheus query parameters
+     * @returns Query result as a number
+     * @throws {NordError} If the request fails
+     */
+    queryPrometheus(params: string): Promise<number>;
+    /**
+     * Get the trades WebSocket client (default)
+     * If not already initialized, it will be created
+     *
+     * @returns WebSocket client for trades
+     */
+    getWebSocketClient(): NordWebSocketClient;
+    /**
+     * Get the trades WebSocket client
+     * If not already initialized, it will be created
+     *
+     * @returns WebSocket client for trades
+     */
+    getTradesWebSocketClient(): NordWebSocketClient;
+    /**
+     * Get the deltas WebSocket client
+     * If not already initialized, it will be created
+     *
+     * @returns WebSocket client for orderbook deltas
+     */
+    getDeltasWebSocketClient(): NordWebSocketClient;
+    /**
+     * Get the user WebSocket client
+     * If not already initialized, it will be created
+     *
+     * @returns WebSocket client for user updates
+     */
+    getUserWebSocketClient(): NordWebSocketClient;
+    /**
+     * Subscribe to orderbook updates for a market
+     *
+     * @param symbol - Market symbol
+     * @returns Orderbook subscription
+     */
+    subscribeOrderbook(symbol: string): OrderbookSubscription;
+    /**
+     * Subscribe to trade updates for a market
+     *
+     * @param symbol - Market symbol
+     * @returns Trade subscription
+     */
+    subscribeTrades(symbol: string): TradeSubscription;
+    /**
+     * Get trades for a market
+     *
+     * @param query - Trades query parameters
+     * @returns Trades response
+     * @throws {NordError} If the request fails
+     */
+    getTrades(query: TradesQuery): Promise<TradesResponse>;
+    /**
+     * Get user account IDs
+     *
+     * @param query - User account IDs query parameters
+     * @returns User account IDs response
+     * @throws {NordError} If the request fails
+     */
+    getUserAccountIds(query: UserAccountIdsQuery): Promise<UserAccountIdsResponse>;
+    /**
+     * 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.
+     */
+    getOrderbook(query: OrderbookQuery): Promise<OrderbookResponse>;
+    /**
+     * Get information about the Nord server
+     *
+     * @returns Information about markets and tokens
+     * @throws {NordError} If the request fails
+     */
+    getInfo(): Promise<Info>;
+    /**
+     * Get account information
+     *
+     * @param accountId - Account ID to get information for
+     * @returns Account information
+     * @throws {NordError} If the request fails
+     */
+    getAccount(accountId: number): Promise<Account>;
+    /**
+     * Get market statistics (alias for marketsStats for backward compatibility)
+     *
+     * @deprecated Use marketsStats instead
+     * @returns Market statistics response
+     */
+    getMarketStats(): Promise<MarketsStatsResponse>;
+    /**
+     * 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
+     */
+    accountExists(address: string): Promise<boolean>;
+}