infoway-sdk 0.1.0

package/README.md

@@ -0,0 +1,214 @@
+# Infoway SDK for Node.js / TypeScript
+
+[![npm version](https://img.shields.io/npm/v/infoway-sdk.svg)](https://www.npmjs.com/package/infoway-sdk)
+[![Node.js](https://img.shields.io/node/v/infoway-sdk.svg)](https://www.npmjs.com/package/infoway-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**English** | [中文](README_CN.md)
+
+Official Node.js/TypeScript SDK for the [Infoway](https://infoway.io) real-time financial data API.
+
+[API Documentation](https://docs.infoway.io) | [Get API Key](https://infoway.io)
+
+> Get your free API key at [infoway.io](https://infoway.io) -- 7-day free trial
+
+## Installation
+
+```bash
+npm install infoway-sdk
+# or
+yarn add infoway-sdk
+# or
+pnpm add infoway-sdk
+```
+
+**Requirements:** Node.js >= 18.0.0
+
+## Quick Start
+
+### REST API
+
+```typescript
+import { InfowayClient, KlineType } from "infoway-sdk";
+
+const client = new InfowayClient({ apiKey: "YOUR_API_KEY" });
+
+// Stock trade data
+const trades = await client.stock.getTrade("AAPL.US");
+console.log(trades);
+
+// Multiple symbols
+const multiTrades = await client.stock.getTrade("AAPL.US,TSLA.US,GOOGL.US");
+
+// Order book depth
+const depth = await client.stock.getDepth("AAPL.US");
+
+// K-line data
+const klines = await client.stock.getKline("AAPL.US", KlineType.DAY, 100);
+
+// Crypto data
+const btc = await client.crypto.getTrade("BTCUSDT");
+const ethKline = await client.crypto.getKline("ETHUSDT", KlineType.HOUR_1, 50);
+
+// Market temperature
+const temp = await client.market.getTemperature("HK,US");
+
+// Market breadth
+const breadth = await client.market.getBreadth("US");
+
+// Stock fundamentals
+const valuation = await client.stockInfo.getValuation("AAPL.US");
+const ratings = await client.stockInfo.getRatings("AAPL.US");
+
+// Plate/sector data
+const industries = await client.plate.getIndustry("HK");
+const concepts = await client.plate.getConcept("HK");
+
+// Basic info
+const symbols = await client.basic.getSymbols("US");
+const tradingDays = await client.basic.getTradingDays("US");
+```
+
+### Environment Variable
+
+You can set `INFOWAY_API_KEY` instead of passing it directly:
+
+```bash
+export INFOWAY_API_KEY=your_api_key
+```
+
+```typescript
+const client = new InfowayClient(); // reads from INFOWAY_API_KEY
+```
+
+### WebSocket Real-time Data
+
+```typescript
+import { InfowayWebSocket, Business } from "infoway-sdk";
+
+const ws = new InfowayWebSocket({
+  apiKey: "YOUR_API_KEY",
+  business: Business.STOCK,
+});
+
+ws.onTrade = (msg) => {
+  console.log("Trade:", msg);
+};
+
+ws.onDepth = (msg) => {
+  console.log("Depth:", msg);
+};
+
+ws.onKline = (msg) => {
+  console.log("Kline:", msg);
+};
+
+ws.onDisconnect = () => {
+  console.log("Disconnected, reconnecting...");
+};
+
+ws.onReconnect = () => {
+  console.log("Reconnected!");
+};
+
+// Subscribe after connection is established
+await ws.subscribeTrade("AAPL.US,TSLA.US");
+await ws.subscribeDepth("AAPL.US");
+
+// Start receiving data
+await ws.connect();
+
+// To close:
+// await ws.close();
+```
+
+### Crypto WebSocket
+
+```typescript
+const ws = new InfowayWebSocket({
+  apiKey: "YOUR_API_KEY",
+  business: Business.CRYPTO,
+});
+
+ws.onTrade = (msg) => console.log("Crypto trade:", msg);
+await ws.subscribeTrade("BTCUSDT,ETHUSDT");
+await ws.connect();
+```
+
+## API Reference
+
+### REST Clients
+
+| Client | Prefix | Description |
+|--------|--------|-------------|
+| `client.stock` | `stock` | HK, US, CN stock market data |
+| `client.crypto` | `crypto` | Cryptocurrency data |
+| `client.japan` | `japan` | Japan stock market data |
+| `client.india` | `india` | India stock market data |
+| `client.common` | `common` | Common market data |
+| `client.basic` | -- | Symbols, trading days, hours |
+| `client.market` | -- | Temperature, breadth, indexes |
+| `client.plate` | -- | Industry/concept sectors |
+| `client.stockInfo` | -- | Valuation, ratings, company info |
+
+### Market Data Methods (stock/crypto/japan/india/common)
+
+| Method | HTTP | Endpoint |
+|--------|------|----------|
+| `getTrade(codes)` | GET | `/{prefix}/batch_trade/{codes}` |
+| `getDepth(codes)` | GET | `/{prefix}/batch_depth/{codes}` |
+| `getKline(codes, klineType, count)` | POST | `/{prefix}/v2/batch_kline` |
+
+### KlineType Enum
+
+| Value | Interval |
+|-------|----------|
+| `KlineType.MIN_1` (1) | 1 minute |
+| `KlineType.MIN_5` (2) | 5 minutes |
+| `KlineType.MIN_15` (3) | 15 minutes |
+| `KlineType.MIN_30` (4) | 30 minutes |
+| `KlineType.HOUR_1` (5) | 1 hour |
+| `KlineType.HOUR_2` (6) | 2 hours |
+| `KlineType.HOUR_4` (7) | 4 hours |
+| `KlineType.DAY` (8) | 1 day |
+| `KlineType.WEEK` (9) | 1 week |
+| `KlineType.MONTH` (10) | 1 month |
+| `KlineType.QUARTER` (11) | 1 quarter |
+| `KlineType.YEAR` (12) | 1 year |
+
+### WebSocket Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| 10000 | `SUB_TRADE` | Subscribe to trade data |
+| 10001 | `PUSH_TRADE` | Push trade data |
+| 10002 | `UNSUB_TRADE` | Unsubscribe trade data |
+| 10003 | `SUB_DEPTH` | Subscribe to depth data |
+| 10004 | `PUSH_DEPTH` | Push depth data |
+| 10005 | `UNSUB_DEPTH` | Unsubscribe depth data |
+| 10006 | `SUB_KLINE` | Subscribe to K-line data |
+| 10007 | `PUSH_KLINE` | Push K-line data |
+| 10008 | `UNSUB_KLINE` | Unsubscribe K-line data |
+| 10010 | `HEARTBEAT` | Heartbeat keepalive |
+
+### Error Handling
+
+```typescript
+import { InfowayAPIError, InfowayAuthError, InfowayTimeoutError } from "infoway-sdk";
+
+try {
+  const data = await client.stock.getTrade("AAPL.US");
+} catch (err) {
+  if (err instanceof InfowayAuthError) {
+    console.error("Authentication failed. Check your API key.");
+  } else if (err instanceof InfowayTimeoutError) {
+    console.error("Request timed out.");
+  } else if (err instanceof InfowayAPIError) {
+    console.error(`API error [${err.ret}]: ${err.msg}`);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };