stock-sdk 1.0.0

package/.cursor/worktrees.json

@@ -0,0 +1,5 @@
+{
+  "setup-worktree": [
+    "npm install"
+  ]
+}

package/README.md

@@ -0,0 +1,330 @@
+# Stock SDK
+
+基于腾讯财经 `qt.gtimg.cn` 非官方接口封装的 TypeScript SDK，支持 A 股、港股、美股、公募基金实时行情查询。
+
+## 安装
+
+```bash
+npm install stock-sdk
+# 或
+yarn add stock-sdk
+```
+
+## 快速开始
+
+```typescript
+import StockSDK from 'stock-sdk';
+
+const sdk = new StockSDK();
+
+// A 股全量行情
+const fullQuotes = await sdk.getFullQuotes(['sz000858', 'sh600000']);
+console.log(fullQuotes);
+
+// 简要行情
+const simpleQuotes = await sdk.getSimpleQuotes(['s_sz000858', 's_sh000001']);
+console.log(simpleQuotes);
+```
+
+## API 文档
+
+### `getFullQuotes(codes: string[]): Promise<FullQuote[]>`
+
+获取 A 股 / 指数全量行情数据。
+
+**参数**
+
+- `codes` — 股票代码数组，格式 `<market><code>`，如 `['sz000858', 'sh600000']`
+
+**返回**
+
+```typescript
+interface FullQuote {
+  marketId: string;      // 市场标识
+  name: string;          // 名称
+  code: string;          // 股票代码
+  price: number;         // 最新价
+  prevClose: number;     // 昨收
+  open: number;          // 今开
+  volume: number;        // 成交量(手)
+  outerVolume: number;   // 外盘
+  innerVolume: number;   // 内盘
+  bid: { price: number; volume: number }[];  // 买一~买五
+  ask: { price: number; volume: number }[];  // 卖一~卖五
+  time: string;          // 时间戳 yyyyMMddHHmmss
+  change: number;        // 涨跌额
+  changePercent: number; // 涨跌幅%
+  high: number;          // 最高
+  low: number;           // 最低
+  volume2: number;       // 成交量(手)
+  amount: number;        // 成交额(万)
+  turnoverRate: number | null;  // 换手率%
+  pe: number | null;            // 市盈率
+  circulatingMarketCap: number | null;  // 流通市值(亿)
+  totalMarketCap: number | null;        // 总市值(亿)
+  pb: number | null;            // 市净率
+  limitUp: number | null;       // 涨停价
+  limitDown: number | null;     // 跌停价
+  raw: string[];                // 原始字段数组
+}
+```
+
+**示例**
+
+```typescript
+const quotes = await sdk.getFullQuotes(['sz000858']);
+console.log(quotes[0].name);  // 五 粮 液
+console.log(quotes[0].price); // 111.70
+```
+
+---
+
+### `getSimpleQuotes(codes: string[]): Promise<SimpleQuote[]>`
+
+获取简要行情（股票 / 指数）。
+
+**参数**
+
+- `codes` — 代码数组，格式 `s_<market><code>`，如 `['s_sz000858', 's_sh000001']`
+
+**返回**
+
+```typescript
+interface SimpleQuote {
+  marketId: string;
+  name: string;
+  code: string;
+  price: number;
+  change: number;
+  changePercent: number;
+  volume: number;
+  amount: number;
+  marketCap: number | null;  // 总市值(亿)
+  marketType: string;        // 如 GP-A / ZS
+  raw: string[];
+}
+```
+
+**示例**
+
+```typescript
+const quotes = await sdk.getSimpleQuotes(['s_sh000001']);
+console.log(quotes[0].name);  // 上证指数
+```
+
+---
+
+### `getFundFlow(codes: string[]): Promise<FundFlow[]>`
+
+获取资金流向数据。
+
+**参数**
+
+- `codes` — 代码数组，格式 `ff_<market><code>`，如 `['ff_sz000858']`
+
+**返回**
+
+```typescript
+interface FundFlow {
+  code: string;
+  mainInflow: number;    // 主力流入
+  mainOutflow: number;   // 主力流出
+  mainNet: number;       // 主力净流入
+  mainNetRatio: number;  // 主力净流入占比
+  retailInflow: number;  // 散户流入
+  retailOutflow: number; // 散户流出
+  retailNet: number;     // 散户净流入
+  retailNetRatio: number;// 散户净流入占比
+  totalFlow: number;     // 总资金流
+  name: string;
+  date: string;
+  raw: string[];
+}
+```
+
+**示例**
+
+```typescript
+const flows = await sdk.getFundFlow(['ff_sz000858']);
+console.log(flows[0].mainNet);
+```
+
+---
+
+### `getPanelLargeOrder(codes: string[]): Promise<PanelLargeOrder[]>`
+
+获取盘口大单占比。
+
+**参数**
+
+- `codes` — 代码数组，格式 `s_pk<market><code>`，如 `['s_pksz000858']`
+
+**返回**
+
+```typescript
+interface PanelLargeOrder {
+  buyLargeRatio: number;   // 买盘大单占比
+  buySmallRatio: number;   // 买盘小单占比
+  sellLargeRatio: number;  // 卖盘大单占比
+  sellSmallRatio: number;  // 卖盘小单占比
+  raw: string[];
+}
+```
+
+**示例**
+
+```typescript
+const orders = await sdk.getPanelLargeOrder(['s_pksz000858']);
+console.log(orders[0].buyLargeRatio);
+```
+
+---
+
+### `getHKQuotes(codes: string[]): Promise<HKQuote[]>`
+
+获取港股扩展行情。
+
+**参数**
+
+- `codes` — 代码数组，格式 `r_hk<code>`，如 `['r_hk09988']`
+
+**返回**
+
+```typescript
+interface HKQuote {
+  marketId: string;
+  name: string;
+  code: string;
+  price: number;
+  prevClose: number;
+  open: number;
+  volume: number;
+  time: string;
+  change: number;
+  changePercent: number;
+  high: number;
+  low: number;
+  amount: number;
+  lotSize: number | null;
+  circulatingMarketCap: number | null;
+  totalMarketCap: number | null;
+  currency: string;
+  raw: string[];
+}
+```
+
+**示例**
+
+```typescript
+const quotes = await sdk.getHKQuotes(['r_hk09988']);
+console.log(quotes[0].name);  // 阿里巴巴-W
+```
+
+---
+
+### `getUSQuotes(codes: string[]): Promise<USQuote[]>`
+
+获取美股简要行情。
+
+**参数**
+
+- `codes` — 代码数组，格式 `s_us<code>`，如 `['s_usBABA']`
+
+**返回**
+
+```typescript
+interface USQuote {
+  marketId: string;
+  name: string;
+  code: string;
+  price: number;
+  change: number;
+  changePercent: number;
+  volume: number;
+  amount: number;
+  marketCap: number | null;
+  raw: string[];
+}
+```
+
+**示例**
+
+```typescript
+const quotes = await sdk.getUSQuotes(['s_usBABA']);
+console.log(quotes[0].code);  // BABA.N
+```
+
+---
+
+### `getFundQuotes(codes: string[]): Promise<FundQuote[]>`
+
+获取公募基金行情。
+
+**参数**
+
+- `codes` — 代码数组，格式 `jj<六位代码>`，如 `['jj000001']`
+
+**返回**
+
+```typescript
+interface FundQuote {
+  code: string;
+  name: string;
+  nav: number;       // 最新单位净值
+  accNav: number;    // 累计净值
+  change: number;    // 当日涨跌额
+  navDate: string;   // 净值日期
+  raw: string[];
+}
+```
+
+**示例**
+
+```typescript
+const funds = await sdk.getFundQuotes(['jj000001']);
+console.log(funds[0].name);  // 华夏成长混合
+```
+
+---
+
+### `batchRaw(params: string): Promise<{ key: string; fields: string[] }[]>`
+
+批量混合查询，返回原始解析结果。
+
+**参数**
+
+- `params` — 逗号分隔的多个查询参数，如 `'sz000858,s_sh000001,jj000001'`
+
+**返回**
+
+```typescript
+{ key: string; fields: string[] }[]
+```
+
+**示例**
+
+```typescript
+const raw = await sdk.batchRaw('sz000858,s_sh000001');
+console.log(raw[0].key);    // sz000858
+console.log(raw[0].fields); // ['51', '五 粮 液', '000858', ...]
+```
+
+---
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 运行测试
+npm test
+
+# 构建
+npm run build
+```
+
+## 许可证
+
+ISC
+

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { FullQuote, SimpleQuote, FundFlow, PanelLargeOrder, HKQuote, USQuote, FundQuote } from './types';
+export * from './types';
+export declare class TencentStockSDK {
+    private client;
+    constructor();
+    private fetch;
+    /**
+     * 获取 A 股 / 指数 全量行情
+     * @param codes 如 ['sz000858', 'sh600000']
+     */
+    getFullQuotes(codes: string[]): Promise<FullQuote[]>;
+    private parseFullQuote;
+    /**
+     * 获取简要行情
+     * @param codes 如 ['s_sz000858', 's_sh000001']
+     */
+    getSimpleQuotes(codes: string[]): Promise<SimpleQuote[]>;
+    private parseSimpleQuote;
+    /**
+     * 获取资金流向
+     * @param codes 如 ['ff_sz000858']
+     */
+    getFundFlow(codes: string[]): Promise<FundFlow[]>;
+    private parseFundFlow;
+    /**
+     * 获取盘口大单占比
+     * @param codes 如 ['s_pksz000858']
+     */
+    getPanelLargeOrder(codes: string[]): Promise<PanelLargeOrder[]>;
+    private parsePanelLargeOrder;
+    /**
+     * 获取港股扩展行情
+     * @param codes 如 ['r_hk09988']
+     */
+    getHKQuotes(codes: string[]): Promise<HKQuote[]>;
+    private parseHKQuote;
+    /**
+     * 获取美股简要行情
+     * @param codes 如 ['s_usBABA']
+     */
+    getUSQuotes(codes: string[]): Promise<USQuote[]>;
+    private parseUSQuote;
+    /**
+     * 获取公募基金行情
+     * @param codes 如 ['jj000001']
+     */
+    getFundQuotes(codes: string[]): Promise<FundQuote[]>;
+    private parseFundQuote;
+    /**
+     * 批量混合查询，返回原始解析结果（key + fields）
+     * @param params 如 'sz000858,s_sh000001,jj000001'
+     */
+    batchRaw(params: string): Promise<{
+        key: string;
+        fields: string[];
+    }[]>;
+}
+export default TencentStockSDK;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,SAAS,EACT,WAAW,EACX,QAAQ,EACR,eAAe,EACf,OAAO,EACP,OAAO,EACP,SAAS,EACV,MAAM,SAAS,CAAC;AAEjB,cAAc,SAAS,CAAC;AAqCxB,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAgB;;YAUhB,KAAK;IAOnB;;;OAGG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAK1D,OAAO,CAAC,cAAc;IAwCtB;;;OAGG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAK9D,OAAO,CAAC,gBAAgB;IAiBxB;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKvD,OAAO,CAAC,aAAa;IAmBrB;;;OAGG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAKrE,OAAO,CAAC,oBAAoB;IAW5B;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAKtD,OAAO,CAAC,YAAY;IAwBpB;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAKtD,OAAO,CAAC,YAAY;IAgBpB;;;OAGG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAK1D,OAAO,CAAC,cAAc;IAatB;;;OAGG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CAG7E;AAED,eAAe,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,293 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TencentStockSDK = void 0;
+const axios_1 = __importDefault(require("axios"));
+const iconv = __importStar(require("iconv-lite"));
+__exportStar(require("./types"), exports);
+const BASE_URL = 'http://qt.gtimg.cn';
+function safeNumber(val) {
+    if (!val || val === '')
+        return 0;
+    const n = parseFloat(val);
+    return Number.isNaN(n) ? 0 : n;
+}
+function safeNumberOrNull(val) {
+    if (!val || val === '')
+        return null;
+    const n = parseFloat(val);
+    return Number.isNaN(n) ? null : n;
+}
+/**
+ * 解析响应文本，按 `;` 拆行，提取 `v_xxx="..."` 里的内容，返回 { key, fields }[]
+ */
+function parseResponse(text) {
+    const lines = text.split(';').map((l) => l.trim()).filter(Boolean);
+    const results = [];
+    for (const line of lines) {
+        const eqIdx = line.indexOf('=');
+        if (eqIdx < 0)
+            continue;
+        let key = line.slice(0, eqIdx).trim();
+        if (key.startsWith('v_'))
+            key = key.slice(2);
+        let raw = line.slice(eqIdx + 1).trim();
+        if (raw.startsWith('"') && raw.endsWith('"')) {
+            raw = raw.slice(1, -1);
+        }
+        const fields = raw.split('~');
+        results.push({ key, fields });
+    }
+    return results;
+}
+class TencentStockSDK {
+    constructor() {
+        this.client = axios_1.default.create({
+            baseURL: BASE_URL,
+            responseType: 'arraybuffer',
+            timeout: 10000,
+        });
+    }
+    async fetch(params) {
+        const resp = await this.client.get('/', { params: { q: params } });
+        const text = iconv.decode(Buffer.from(resp.data), 'gbk');
+        return parseResponse(text);
+    }
+    // ---------- 实时全量行情 ----------
+    /**
+     * 获取 A 股 / 指数 全量行情
+     * @param codes 如 ['sz000858', 'sh600000']
+     */
+    async getFullQuotes(codes) {
+        const data = await this.fetch(codes.join(','));
+        return data.map((d) => this.parseFullQuote(d.fields));
+    }
+    parseFullQuote(f) {
+        const bid = [];
+        for (let i = 0; i < 5; i++) {
+            bid.push({ price: safeNumber(f[9 + i * 2]), volume: safeNumber(f[10 + i * 2]) });
+        }
+        const ask = [];
+        for (let i = 0; i < 5; i++) {
+            ask.push({ price: safeNumber(f[19 + i * 2]), volume: safeNumber(f[20 + i * 2]) });
+        }
+        return {
+            marketId: f[0] ?? '',
+            name: f[1] ?? '',
+            code: f[2] ?? '',
+            price: safeNumber(f[3]),
+            prevClose: safeNumber(f[4]),
+            open: safeNumber(f[5]),
+            volume: safeNumber(f[6]),
+            outerVolume: safeNumber(f[7]),
+            innerVolume: safeNumber(f[8]),
+            bid,
+            ask,
+            time: f[30] ?? '',
+            change: safeNumber(f[31]),
+            changePercent: safeNumber(f[32]),
+            high: safeNumber(f[33]),
+            low: safeNumber(f[34]),
+            volume2: safeNumber(f[36]),
+            amount: safeNumber(f[37]),
+            turnoverRate: safeNumberOrNull(f[38]),
+            pe: safeNumberOrNull(f[39]),
+            circulatingMarketCap: safeNumberOrNull(f[44]),
+            totalMarketCap: safeNumberOrNull(f[45]),
+            pb: safeNumberOrNull(f[46]),
+            limitUp: safeNumberOrNull(f[47]),
+            limitDown: safeNumberOrNull(f[48]),
+            raw: f,
+        };
+    }
+    // ---------- 简要行情 ----------
+    /**
+     * 获取简要行情
+     * @param codes 如 ['s_sz000858', 's_sh000001']
+     */
+    async getSimpleQuotes(codes) {
+        const data = await this.fetch(codes.join(','));
+        return data.map((d) => this.parseSimpleQuote(d.fields));
+    }
+    parseSimpleQuote(f) {
+        return {
+            marketId: f[0] ?? '',
+            name: f[1] ?? '',
+            code: f[2] ?? '',
+            price: safeNumber(f[3]),
+            change: safeNumber(f[4]),
+            changePercent: safeNumber(f[5]),
+            volume: safeNumber(f[6]),
+            amount: safeNumber(f[7]),
+            marketCap: safeNumberOrNull(f[9]),
+            marketType: f[10] ?? '',
+            raw: f,
+        };
+    }
+    // ---------- 资金流向 ----------
+    /**
+     * 获取资金流向
+     * @param codes 如 ['ff_sz000858']
+     */
+    async getFundFlow(codes) {
+        const data = await this.fetch(codes.join(','));
+        return data.map((d) => this.parseFundFlow(d.fields));
+    }
+    parseFundFlow(f) {
+        return {
+            code: f[0] ?? '',
+            mainInflow: safeNumber(f[1]),
+            mainOutflow: safeNumber(f[2]),
+            mainNet: safeNumber(f[3]),
+            mainNetRatio: safeNumber(f[4]),
+            retailInflow: safeNumber(f[5]),
+            retailOutflow: safeNumber(f[6]),
+            retailNet: safeNumber(f[7]),
+            retailNetRatio: safeNumber(f[8]),
+            totalFlow: safeNumber(f[9]),
+            name: f[12] ?? '',
+            date: f[13] ?? '',
+            raw: f,
+        };
+    }
+    // ---------- 盘口大单占比 ----------
+    /**
+     * 获取盘口大单占比
+     * @param codes 如 ['s_pksz000858']
+     */
+    async getPanelLargeOrder(codes) {
+        const data = await this.fetch(codes.join(','));
+        return data.map((d) => this.parsePanelLargeOrder(d.fields));
+    }
+    parsePanelLargeOrder(f) {
+        return {
+            buyLargeRatio: safeNumber(f[0]),
+            buySmallRatio: safeNumber(f[1]),
+            sellLargeRatio: safeNumber(f[2]),
+            sellSmallRatio: safeNumber(f[3]),
+            raw: f,
+        };
+    }
+    // ---------- 港股扩展行情 ----------
+    /**
+     * 获取港股扩展行情
+     * @param codes 如 ['r_hk09988']
+     */
+    async getHKQuotes(codes) {
+        const data = await this.fetch(codes.join(','));
+        return data.map((d) => this.parseHKQuote(d.fields));
+    }
+    parseHKQuote(f) {
+        return {
+            marketId: f[0] ?? '',
+            name: f[1] ?? '',
+            code: f[2] ?? '',
+            price: safeNumber(f[3]),
+            prevClose: safeNumber(f[4]),
+            open: safeNumber(f[5]),
+            volume: safeNumber(f[6]),
+            time: f[30] ?? '',
+            change: safeNumber(f[31]),
+            changePercent: safeNumber(f[32]),
+            high: safeNumber(f[33]),
+            low: safeNumber(f[34]),
+            amount: safeNumber(f[36]),
+            lotSize: safeNumberOrNull(f[40]),
+            circulatingMarketCap: safeNumberOrNull(f[46]),
+            totalMarketCap: safeNumberOrNull(f[47]),
+            currency: f[f.length - 3] ?? '',
+            raw: f,
+        };
+    }
+    // ---------- 美股简要行情 ----------
+    /**
+     * 获取美股简要行情
+     * @param codes 如 ['s_usBABA']
+     */
+    async getUSQuotes(codes) {
+        const data = await this.fetch(codes.join(','));
+        return data.map((d) => this.parseUSQuote(d.fields));
+    }
+    parseUSQuote(f) {
+        return {
+            marketId: f[0] ?? '',
+            name: f[1] ?? '',
+            code: f[2] ?? '',
+            price: safeNumber(f[3]),
+            change: safeNumber(f[4]),
+            changePercent: safeNumber(f[5]),
+            volume: safeNumber(f[6]),
+            amount: safeNumber(f[7]),
+            marketCap: safeNumberOrNull(f[8]),
+            raw: f,
+        };
+    }
+    // ---------- 公募基金行情 ----------
+    /**
+     * 获取公募基金行情
+     * @param codes 如 ['jj000001']
+     */
+    async getFundQuotes(codes) {
+        const data = await this.fetch(codes.join(','));
+        return data.map((d) => this.parseFundQuote(d.fields));
+    }
+    parseFundQuote(f) {
+        return {
+            code: f[0] ?? '',
+            name: f[1] ?? '',
+            nav: safeNumber(f[5]),
+            accNav: safeNumber(f[6]),
+            change: safeNumber(f[7]),
+            navDate: f[8] ?? '',
+            raw: f,
+        };
+    }
+    // ---------- 批量混合查询 ----------
+    /**
+     * 批量混合查询，返回原始解析结果（key + fields）
+     * @param params 如 'sz000858,s_sh000001,jj000001'
+     */
+    async batchRaw(params) {
+        return this.fetch(params);
+    }
+}
+exports.TencentStockSDK = TencentStockSDK;
+exports.default = TencentStockSDK;