infoway-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Low-level HTTP client with retry and error handling.
+ * Uses native fetch (Node 18+).
+ */
+declare class HttpClient {
+    private readonly _apiKey;
+    private readonly _baseUrl;
+    private readonly _timeout;
+    private readonly _maxRetries;
+    constructor(options?: {
+        apiKey?: string;
+        baseUrl?: string;
+        timeout?: number;
+        maxRetries?: number;
+    });
+    /** Expose apiKey for testing. */
+    get apiKey(): string;
+    get(path: string, params?: Record<string, string | number | undefined>): Promise<unknown>;
+    post(path: string, body?: Record<string, unknown>): Promise<unknown>;
+    private _buildUrl;
+    private _request;
+    private _handleResponse;
+    private _sleep;
+}
+
+/**
+ * Shared market data methods for trade/depth/kline.
+ * Base class for StockClient, CryptoClient, JapanClient, IndiaClient, CommonClient.
+ */
+
+declare abstract class MarketDataClient {
+    protected abstract readonly _prefix: string;
+    protected readonly _http: HttpClient;
+    constructor(http: HttpClient);
+    /**
+     * Get real-time trade data.
+     * @param codes - Comma-separated symbol codes (e.g. "AAPL.US" or "AAPL.US,TSLA.US")
+     */
+    getTrade(codes: string): Promise<unknown>;
+    /**
+     * Get real-time order book depth.
+     * @param codes - Comma-separated symbol codes
+     */
+    getDepth(codes: string): Promise<unknown>;
+    /**
+     * Get candlestick/K-line data.
+     * @param codes - Comma-separated symbol codes
+     * @param klineType - K-line interval (use KlineType enum or number 1-12)
+     * @param count - Number of candles to return
+     */
+    getKline(codes: string, klineType: number, count: number): Promise<unknown>;
+}
+
+/** Stock market data client (HK, US, CN). */
+
+declare class StockClient extends MarketDataClient {
+    protected readonly _prefix = "stock";
+}
+
+/** Crypto market data client. */
+
+declare class CryptoClient extends MarketDataClient {
+    protected readonly _prefix = "crypto";
+}
+
+/** Japan market data client. */
+
+declare class JapanClient extends MarketDataClient {
+    protected readonly _prefix = "japan";
+}
+
+/** India market data client. */
+
+declare class IndiaClient extends MarketDataClient {
+    protected readonly _prefix = "india";
+}
+
+/** Common market data client. */
+
+declare class CommonClient extends MarketDataClient {
+    protected readonly _prefix = "common";
+}
+
+/** Basic information client (symbols, trading days, hours). */
+
+declare class BasicClient {
+    private readonly _http;
+    constructor(http: HttpClient);
+    getSymbols(market?: string): Promise<unknown>;
+    getSymbolInfo(codes: string): Promise<unknown>;
+    getAdjustmentFactors(codes: string): Promise<unknown>;
+    getTradingDays(market: string): Promise<unknown>;
+    getTradingHours(market?: string): Promise<unknown>;
+}
+
+/** Market overview client (temperature, breadth, indexes, leaders). */
+
+declare class MarketClient {
+    private readonly _http;
+    constructor(http: HttpClient);
+    getTemperature(market?: string): Promise<unknown>;
+    getBreadth(market: string): Promise<unknown>;
+    getIndexes(): Promise<unknown>;
+    getLeaders(market: string, limit?: number): Promise<unknown>;
+    getRankConfig(market: string): Promise<unknown>;
+}
+
+/** Plate (sector) data client. */
+
+declare class PlateClient {
+    private readonly _http;
+    constructor(http: HttpClient);
+    getIndustry(market: string, limit?: number): Promise<unknown>;
+    getConcept(market: string, limit?: number): Promise<unknown>;
+    getMembers(plateSymbol: string, offset?: number, limit?: number): Promise<unknown>;
+    getIntro(plateSymbol: string): Promise<unknown>;
+    getChart(market: string, limit?: number): Promise<unknown>;
+}
+
+/** Stock fundamental data client. */
+
+declare class StockInfoClient {
+    private readonly _http;
+    constructor(http: HttpClient);
+    getValuation(symbol: string): Promise<unknown>;
+    getRatings(symbol: string): Promise<unknown>;
+    getCompany(symbol: string): Promise<unknown>;
+    getPanorama(symbol: string): Promise<unknown>;
+    getConcepts(symbol: string): Promise<unknown>;
+    getEvents(symbol: string, limit?: number): Promise<unknown>;
+    getDrivers(symbol: string): Promise<unknown>;
+}
+
+/**
+ * Shared type definitions and enums for the Infoway SDK.
+ */
+/** K-line (candlestick) interval types. */
+declare enum KlineType {
+    MIN_1 = 1,
+    MIN_5 = 2,
+    MIN_15 = 3,
+    MIN_30 = 4,
+    HOUR_1 = 5,
+    HOUR_2 = 6,
+    HOUR_4 = 7,
+    DAY = 8,
+    WEEK = 9,
+    MONTH = 10,
+    QUARTER = 11,
+    YEAR = 12
+}
+/** Business types for WebSocket connections. */
+declare const Business: {
+    readonly STOCK: "stock";
+    readonly JAPAN: "japan";
+    readonly INDIA: "india";
+    readonly CRYPTO: "crypto";
+    readonly COMMON: "common";
+};
+type Business = (typeof Business)[keyof typeof Business];
+/** WebSocket message codes. */
+declare enum WsCode {
+    SUB_TRADE = 10000,
+    PUSH_TRADE = 10001,
+    UNSUB_TRADE = 10002,
+    SUB_DEPTH = 10003,
+    PUSH_DEPTH = 10004,
+    UNSUB_DEPTH = 10005,
+    SUB_KLINE = 10006,
+    PUSH_KLINE = 10007,
+    UNSUB_KLINE = 10008,
+    HEARTBEAT = 10010
+}
+/** Options for creating an InfowayClient. */
+interface InfowayClientOptions {
+    /** Your Infoway API key. Falls back to INFOWAY_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for REST API. Default: https://data.infoway.io */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 15000 */
+    timeout?: number;
+    /** Max retry attempts for failed requests. Default: 3 */
+    maxRetries?: number;
+}
+/** Options for creating an InfowayWebSocket. */
+interface InfowayWebSocketOptions {
+    /** Your Infoway API key. */
+    apiKey: string;
+    /** Business type (stock, crypto, japan, india, common). */
+    business: Business;
+    /** Base WebSocket URL. Default: wss://data.infoway.io/ws */
+    baseUrl?: string;
+    /** Maximum reconnect attempts. Unlimited if not set. */
+    maxReconnectAttempts?: number;
+}
+/** Standard API response envelope. */
+interface ApiResponse<T = unknown> {
+    ret: number;
+    /** Some endpoints return `code` instead of `ret`. */
+    code?: number;
+    msg: string;
+    traceId?: string;
+    data: T;
+}
+/** WebSocket message structure. */
+interface WsMessage {
+    code: number;
+    trace: string;
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Main entry point for the Infoway SDK.
+ */
+
+/**
+ * Infoway API client.
+ *
+ * @example
+ * ```ts
+ * import { InfowayClient } from "infoway-sdk";
+ *
+ * const client = new InfowayClient({ apiKey: "YOUR_API_KEY" });
+ * const trades = await client.stock.getTrade("AAPL.US");
+ * const klines = await client.crypto.getKline("BTCUSDT", 8, 100);
+ * const temp = await client.market.getTemperature("HK,US");
+ * ```
+ */
+declare class InfowayClient {
+    /** @internal */
+    readonly _http: HttpClient;
+    readonly stock: StockClient;
+    readonly crypto: CryptoClient;
+    readonly japan: JapanClient;
+    readonly india: IndiaClient;
+    readonly common: CommonClient;
+    readonly basic: BasicClient;
+    readonly market: MarketClient;
+    readonly plate: PlateClient;
+    readonly stockInfo: StockInfoClient;
+    constructor(options?: InfowayClientOptions);
+}
+
+/**
+ * WebSocket client with auto-reconnect, heartbeat, and subscription management.
+ */
+
+type MessageHandler = (msg: Record<string, unknown>) => void;
+type ErrorHandler = (err: Error) => void;
+type VoidHandler = () => void;
+declare class InfowayWebSocket {
+    /** @internal */
+    readonly _url: string;
+    private readonly _maxReconnect;
+    private _ws;
+    /** @internal */
+    readonly _subscriptions: Set<string>;
+    private _running;
+    private _backoff;
+    private _heartbeatTimer;
+    /** Called when a trade push message is received. */
+    onTrade: MessageHandler | null;
+    /** Called when a depth push message is received. */
+    onDepth: MessageHandler | null;
+    /** Called when a kline push message is received. */
+    onKline: MessageHandler | null;
+    /** Called when an error occurs. */
+    onError: ErrorHandler | null;
+    /** Called after a successful reconnection. */
+    onReconnect: VoidHandler | null;
+    /** Called when the connection is lost. */
+    onDisconnect: VoidHandler | null;
+    constructor(options: InfowayWebSocketOptions);
+    /**
+     * Build a WebSocket message JSON string.
+     * @internal
+     */
+    _buildMessage(code: WsCode | number, codes?: string): string;
+    /**
+     * Connect and start listening. Returns a Promise that resolves
+     * when the connection is closed intentionally or max reconnects exceeded.
+     */
+    connect(): Promise<void>;
+    private _connectOnce;
+    private _startHeartbeat;
+    private _stopHeartbeat;
+    private _resubscribe;
+    subscribeTrade(codes: string): Promise<void>;
+    subscribeDepth(codes: string): Promise<void>;
+    subscribeKline(codes: string): Promise<void>;
+    unsubscribeTrade(codes: string): Promise<void>;
+    unsubscribeDepth(codes: string): Promise<void>;
+    unsubscribeKline(codes: string): Promise<void>;
+    close(): Promise<void>;
+    private _sleep;
+}
+
+/**
+ * Infoway SDK exception types.
+ */
+/** Raised when a request times out. */
+declare class InfowayTimeoutError extends Error {
+    constructor(message?: string);
+}
+/** Raised when the API returns a non-success response. */
+declare class InfowayAPIError extends Error {
+    readonly ret: number;
+    readonly msg: string;
+    readonly traceId?: string;
+    constructor(ret: number, msg: string, traceId?: string);
+}
+/** Raised on 401 Unauthorized. */
+declare class InfowayAuthError extends InfowayAPIError {
+    constructor(msg?: string);
+}
+
+export { type ApiResponse, BasicClient, Business, CommonClient, CryptoClient, HttpClient, IndiaClient, InfowayAPIError, InfowayAuthError, InfowayClient, type InfowayClientOptions, InfowayTimeoutError, InfowayWebSocket, type InfowayWebSocketOptions, JapanClient, KlineType, MarketClient, PlateClient, StockClient, StockInfoClient, WsCode, type WsMessage };