@n1xyz/nord-ts 0.2.0 → 0.3.1

package/dist/nord/api/metrics.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricPeriod = void 0;
+exports.aggregateMetrics = aggregateMetrics;
+exports.getCurrentTps = getCurrentTps;
+exports.getPeakTps = getPeakTps;
+exports.getMedianLatency = getMedianLatency;
+exports.getTotalTransactions = getTotalTransactions;
+exports.queryPrometheus = queryPrometheus;
+const types_1 = require("../../types");
+const utils_1 = require("../../utils");
+const NordError_1 = require("../utils/NordError");
+/**
+ * Time periods for metrics queries
+ */
+var MetricPeriod;
+(function (MetricPeriod) {
+    MetricPeriod["ONE_MINUTE"] = "1m";
+    MetricPeriod["FIVE_MINUTES"] = "5m";
+    MetricPeriod["FIFTEEN_MINUTES"] = "15m";
+    MetricPeriod["ONE_HOUR"] = "1h";
+    MetricPeriod["FOUR_HOURS"] = "4h";
+    MetricPeriod["ONE_DAY"] = "24h";
+    MetricPeriod["ONE_WEEK"] = "7d";
+})(MetricPeriod || (exports.MetricPeriod = MetricPeriod = {}));
+/**
+ * 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
+ */
+async function aggregateMetrics(webServerUrl, txPeakTpsPeriod = 1, txPeakTpsPeriodUnit = types_1.PeakTpsPeriodUnit.Day) {
+    try {
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/metrics?tx_peak_tps_period=${txPeakTpsPeriod}&tx_peak_tps_period_unit=${txPeakTpsPeriodUnit}`);
+        // Get the raw text response (Prometheus format)
+        const text = await response.text();
+        // Parse the Prometheus-formatted metrics text into an AggregateMetrics object
+        const metrics = {
+            blocks_total: 0,
+            tx_total: extractMetricValue(text, "nord_requests_ok_count"),
+            tx_tps: calculateTps(text),
+            tx_tps_peak: calculatePeakTps(text),
+            request_latency_average: extractLatency(text),
+        };
+        return metrics;
+    }
+    catch (error) {
+        throw new NordError_1.NordError("Failed to fetch aggregate metrics", { cause: error });
+    }
+}
+/**
+ * Extract a metric value from Prometheus-formatted text
+ *
+ * @param text - Prometheus-formatted metrics text
+ * @param metricName - Name of the metric to extract
+ * @returns The metric value as a number, or 0 if not found
+ */
+function extractMetricValue(text, metricName) {
+    const regex = new RegExp(`^${metricName}\\s+([\\d.]+)`, "m");
+    const match = text.match(regex);
+    return match ? parseFloat(match[1]) : 0;
+}
+/**
+ * Calculate TPS from Prometheus metrics
+ *
+ * @param text - Prometheus-formatted metrics text
+ * @returns Calculated TPS value
+ */
+function calculateTps(text) {
+    // Use the request count and latency to estimate TPS
+    const requestCount = extractMetricValue(text, "nord_requests_ok_count");
+    const latencySum = extractSummaryValue(text, "nord_requests_ok_latency_sum");
+    const latencyCount = extractSummaryValue(text, "nord_requests_ok_latency_count");
+    if (latencySum > 0 && latencyCount > 0) {
+        // Average latency in seconds
+        const avgLatency = latencySum / latencyCount;
+        // If we have valid latency data, estimate TPS as requests per second
+        return avgLatency > 0 ? requestCount / (latencyCount * avgLatency) : 0;
+    }
+    // Fallback: just return a small fraction of the total request count
+    return requestCount > 0 ? requestCount / 100 : 0;
+}
+/**
+ * Calculate peak TPS from Prometheus metrics
+ *
+ * @param text - Prometheus-formatted metrics text
+ * @returns Calculated peak TPS value
+ */
+function calculatePeakTps(text) {
+    // For peak TPS, we'll use a simple heuristic: 2x the current TPS estimate
+    // TODO: fix this
+    return calculateTps(text) * 2;
+}
+/**
+ * Extract latency from Prometheus metrics
+ *
+ * @param text - Prometheus-formatted metrics text
+ * @returns Average latency in seconds
+ */
+function extractLatency(text) {
+    // TODO: fix - using average for latency is kinda wack. ok to merge for now but should change.
+    const latencySum = extractSummaryValue(text, "nord_requests_ok_latency_sum");
+    const latencyCount = extractSummaryValue(text, "nord_requests_ok_latency_count");
+    return latencyCount > 0 ? latencySum / latencyCount : 0;
+}
+/**
+ * Extract a summary value from Prometheus-formatted text
+ *
+ * @param text - Prometheus-formatted metrics text
+ * @param metricName - Name of the metric to extract
+ * @returns The metric value as a number, or 0 if not found
+ */
+function extractSummaryValue(text, metricName) {
+    const regex = new RegExp(`^${metricName}\\s+([\\d.]+)`, "m");
+    const match = text.match(regex);
+    return match ? parseFloat(match[1]) : 0;
+}
+/**
+ * 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
+ */
+async function getCurrentTps(webServerUrl, period = "1m") {
+    try {
+        // nord_tx_count doesn't exist in the metrics, use nord_requests_ok_count instead
+        return await queryPrometheus(webServerUrl, `sum(rate(nord_requests_ok_count[${period}]))`);
+    }
+    catch (error) {
+        throw new NordError_1.NordError(`Failed to get current TPS for period ${period}`, {
+            cause: error,
+        });
+    }
+}
+/**
+ * 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
+ */
+async function getPeakTps(webServerUrl, period = "24h") {
+    try {
+        // nord_tx_count doesn't exist in the metrics, use nord_requests_ok_count instead
+        return await queryPrometheus(webServerUrl, `max_over_time(sum(rate(nord_requests_ok_count[1m]))[${period}:])`);
+    }
+    catch (error) {
+        throw new NordError_1.NordError(`Failed to get peak TPS for period ${period}`, {
+            cause: error,
+        });
+    }
+}
+/**
+ * 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
+ */
+async function getMedianLatency(webServerUrl, period = "1m") {
+    try {
+        // nord_tx_latency_ms doesn't exist, use nord_requests_ok_latency instead
+        // which contains the latency data in the summary metric
+        return await queryPrometheus(webServerUrl, `quantile_over_time(0.5, nord_requests_ok_latency[${period}]) * 1000`);
+    }
+    catch (error) {
+        throw new NordError_1.NordError(`Failed to get median latency for period ${period}`, {
+            cause: error,
+        });
+    }
+}
+/**
+ * Get total transaction count
+ *
+ * @param webServerUrl - Base URL for the Nord web server
+ * @returns Total transaction count
+ * @throws {NordError} If the request fails
+ */
+async function getTotalTransactions(webServerUrl) {
+    try {
+        // nord_tx_count doesn't exist, use nord_requests_ok_count instead
+        return await queryPrometheus(webServerUrl, "sum(nord_requests_ok_count)");
+    }
+    catch (error) {
+        throw new NordError_1.NordError("Failed to get total transactions", { cause: error });
+    }
+}
+/**
+ * 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
+ */
+async function queryPrometheus(webServerUrl, params) {
+    try {
+        const response = await (0, utils_1.checkedFetch)(`${webServerUrl}/prometheus?query=${encodeURIComponent(params)}`);
+        // Handle raw text response
+        const text = await response.text();
+        try {
+            // Try to parse as JSON first
+            const data = JSON.parse(text);
+            return data.data.result[0]?.value[1] || 0;
+        }
+        catch (error) {
+            console.log("Prometheus query failed:", error);
+            // Try to find a number in the response
+            const numberMatch = text.match(/[\d.]+/);
+            if (numberMatch) {
+                return parseFloat(numberMatch[0]);
+            }
+            // Return 0 if no number is found
+            return 0;
+        }
+    }
+    catch (error) {
+        throw new NordError_1.NordError(`Failed to query Prometheus: ${params}`, {
+            cause: error,
+        });
+    }
+}

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

@@ -0,0 +1,7 @@
+import { components } from "../../gen/openapi";
+type AccountTriggerInfo = components["schemas"]["AccountTriggerInfo"];
+type TriggerHistoryPage = components["schemas"]["PageResult_for_uint64_and_HistoryTriggerInfo"];
+type HistoryTriggerQuery = components["schemas"]["AccountTriggersQuery"];
+export type { AccountTriggerInfo, TriggerHistoryPage, HistoryTriggerQuery };
+export declare function fetchAccountTriggers(serverUrl: string, accountId: number): Promise<AccountTriggerInfo[]>;
+export declare function fetchAccountTriggerHistory(serverUrl: string, accountId: number, options: HistoryTriggerQuery): Promise<TriggerHistoryPage>;

package/dist/nord/api/triggers.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchAccountTriggers = fetchAccountTriggers;
+exports.fetchAccountTriggerHistory = fetchAccountTriggerHistory;
+const openapi_fetch_1 = __importDefault(require("openapi-fetch"));
+async function fetchAccountTriggers(serverUrl, accountId) {
+    const client = (0, openapi_fetch_1.default)({ baseUrl: serverUrl });
+    const response = await client.GET("/account/{account_id}/triggers", {
+        params: {
+            path: { account_id: accountId },
+        },
+    });
+    if (response.data === undefined) {
+        throw new Error(`Failed to fetch triggers for account ${accountId}: HTTP ${response.response.status}`);
+    }
+    return response.data ?? [];
+}
+async function fetchAccountTriggerHistory(serverUrl, accountId, options) {
+    const client = (0, openapi_fetch_1.default)({ baseUrl: serverUrl });
+    const response = await client.GET("/account/{account_id}/triggers/history", {
+        params: {
+            path: { account_id: accountId },
+            query: {
+                since: options.since,
+                until: options.until,
+                pageSize: options.pageSize,
+                startInclusive: options.startInclusive,
+            },
+        },
+    });
+    if (!response.data) {
+        throw new Error(`Failed to fetch trigger history for account ${accountId}: HTTP ${response.response.status}`);
+    }
+    return response.data;
+}

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

@@ -0,0 +1,387 @@
+import { ProtonClient } from "@n1xyz/proton";
+import { PublicKey } from "@solana/web3.js";
+import { EventEmitter } from "events";
+import { Client } from "openapi-fetch";
+import type { paths } from "../../gen/openapi.ts";
+import { Account, AccountPnlPage, AccountPnlQuery, ActionResponse, AggregateMetrics, MarketsInfo, Market, MarketStats, NordConfig, OrderbookQuery, OrderbookResponse, FeeTierConfig, PeakTpsPeriodUnit, Token, TradesResponse, User, AccountTriggerInfo, HistoryTriggerQuery, TriggerHistoryPage, FeeTierId, AccountFeeTierPage, PageResultStringOrderInfo, PageResultStringTrade, OrderInfoFromApi, TokenStats, FillRole } from "../../types";
+import { NordWebSocketClient } from "../../websocket/index";
+import { OrderbookSubscription, TradeSubscription } from "../models/Subscriber";
+/**
+ * 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 RPC URL */
+    readonly solanaUrl: string;
+    /** Available markets */
+    markets: Market[];
+    /** Available tokens */
+    tokens: Token[];
+    /** Map of symbol to market_id */
+    private symbolToMarketId;
+    /** Proton client for proton related operations */
+    protonClient: ProtonClient;
+    /** Shared HTTP client */
+    readonly client: Client<paths>;
+    /**
+     * 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
+     */
+    private constructor();
+    /**
+     * 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: Readonly<{
+        trades?: string[];
+        deltas?: string[];
+        accounts?: number[];
+    }>): NordWebSocketClient;
+    private GET;
+    /**
+     * 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 last event 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.app - App address
+     * @param nordConfig.solanaUrl - Solana cluster URL
+     * @returns Initialized Nord client
+     * @throws {NordError} If initialization fails
+     */
+    static initNord({ app, solanaUrl, webServerUrl, protonUrl, }: Readonly<NordConfig>): Promise<Nord>;
+    /**
+     * Initialize the Nord client
+     * @private
+     */
+    private init;
+    /**
+     * Query a specific action
+     *
+     * @param query - Action query parameters
+     * @returns Action response
+     * @throws {NordError} If the request fails
+     */
+    queryAction({ action_id, }: {
+        action_id: number;
+    }): Promise<ActionResponse | null>;
+    /**
+     * Query recent actions
+     *
+     * @param from - Starting action index
+     * @param to - Ending action index
+     * @returns Actions response
+     * @throws {NordError} If the request fails
+     */
+    queryRecentActions(query: {
+        from: number;
+        to: number;
+    }): Promise<ActionResponse[]>;
+    /**
+     * Get the last action ID
+     *
+     * @returns Last action ID
+     * @throws {NordError} If the request fails
+     */
+    getLastActionId(): Promise<number>;
+    /**
+     * 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 Prometheus metrics
+     *
+     * @param params - Prometheus query parameters
+     * @returns Query result as a number
+     * @throws {NordError} If the request fails
+     */
+    queryPrometheus(params: string): Promise<number>;
+    /**
+     * Subscribe to orderbook updates for a market
+     *
+     * @param symbol - Market symbol
+     * @returns Orderbook subscription
+     * @throws {NordError} If symbol is invalid
+     */
+    subscribeOrderbook(symbol: string): OrderbookSubscription;
+    /**
+     * Subscribe to trade updates for a market
+     *
+     * @param symbol - Market symbol
+     * @returns Trade subscription
+     * @throws {NordError} If symbol is invalid
+     */
+    subscribeTrades(symbol: string): TradeSubscription;
+    /**
+     * Subscribe to account updates
+     *
+     * @param accountId - Account ID to subscribe to
+     * @returns User subscription
+     * @throws {NordError} If accountId is invalid
+     */
+    subscribeAccount(accountId: number): EventEmitter<[never]> & {
+        close: () => void;
+    };
+    /**
+     * Get trades for a market
+     *
+     * @param query - Trades query parameters
+     * @returns Trades response
+     * @throws {NordError} If the request fails
+     */
+    getTrades(query: Readonly<{
+        marketId?: number;
+        takerId?: number;
+        makerId?: number;
+        takerSide?: "bid" | "ask";
+        pageSize?: number;
+        sinceRcf3339?: string;
+        untilRfc3339?: string;
+        pageId?: string;
+    }>): Promise<TradesResponse>;
+    /**
+     * Get user account IDs
+     *
+     * @param query - User account IDs query parameters
+     * @returns User account IDs response
+     * @throws {NordError} If the request fails
+     */
+    getUser(query: {
+        pubkey: string | PublicKey;
+    }): Promise<User | null>;
+    /**
+     * 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<MarketsInfo>;
+    /**
+     * 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
+     */
+    getFeeBrackets(): Promise<Array<[FeeTierId, FeeTierConfig]>>;
+    /**
+     * 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
+     */
+    getAccountFeeTier(accountId: number): Promise<FeeTierId>;
+    /**
+     * 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 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
+     */
+    getAccountPubkey(accountId: number): Promise<string>;
+    /**
+     * 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
+     */
+    getAccountWithdrawalFee(accountId: number): Promise<number>;
+    /**
+     * 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
+     */
+    getAccountOrders(accountId: number, query?: {
+        startInclusive?: string | null;
+        pageSize?: number | null;
+    }): Promise<PageResultStringOrderInfo>;
+    /**
+     * List account fee tiers with pagination support.
+     */
+    getAccountsFeeTiers(query?: {
+        startInclusive?: number | null;
+        pageSize?: number | null;
+    }): Promise<AccountFeeTierPage>;
+    /**
+     * 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
+     */
+    getAccountPnl(accountId: number, query?: Partial<AccountPnlQuery>): Promise<AccountPnlPage>;
+    /**
+     * Get market statistics (alias for marketsStats for backward compatibility)
+     *
+     * @returns Market statistics response
+     */
+    getMarketStats({ marketId, }: {
+        marketId: number;
+    }): Promise<MarketStats>;
+    /**
+     * 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
+     */
+    getMarketFee({ marketId, feeKind, accountId, }: {
+        marketId: number;
+        feeKind: FillRole;
+        accountId: number;
+    }): Promise<number>;
+    /**
+     * Fetch token statistics such as index price and oracle metadata.
+     *
+     * @param tokenId - Token identifier
+     * @returns Token stats
+     * @throws {NordError} If the request fails
+     */
+    getTokenStats(tokenId: number): Promise<TokenStats>;
+    /**
+     * Get order summary by order id.
+     *
+     * @param orderId - Order identifier
+     * @returns Order information
+     * @throws {NordError} If the request fails
+     */
+    getOrder(orderId: string): Promise<OrderInfoFromApi>;
+    /**
+     * 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
+     */
+    getOrderTrades(orderId: string, query?: {
+        startInclusive?: string | null;
+        pageSize?: number | null;
+    }): Promise<PageResultStringTrade>;
+    /**
+     * 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
+     */
+    accountExists(pubkey: string | PublicKey): Promise<boolean>;
+    /**
+     * 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.
+     */
+    getAccountTriggers(params?: {
+        accountId?: number;
+    }): Promise<AccountTriggerInfo[]>;
+    /**
+     * 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.
+     */
+    getAccountTriggerHistory(params: HistoryTriggerQuery & {
+        accountId?: number;
+    }): Promise<TriggerHistoryPage>;
+}