@dshtrading/connector-stooq 0.1.0

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,16 @@
+# @dshtrading/connector-stooq
+
+> **状态：未实证（本出口被反爬拒止）**。2026-08-31 实测：Stooq 对无浏览器特征的客户端先下发 JS proof-of-work 挑战页（`/__verify`），清挑战后 CSV 下载仍返回 `Access denied`（stooq.pl：`Odmowa dostępu`），疑似按出口 IP/账户策略拒绝匿名下载——本开发出口**无任何一次成功数据返回**，证据 `spikes/impl-us/REPORT.md`。代码完整、单测绿（夹具为 Stooq 长期稳定的 CSV 格式），**其他出口可能可用**，保留在仓备查。
+>
+> **us 切片已切换到 Yahoo Finance**（`packages/connector-yahoo`，本出口已实证，2026-08-29），本包不再是 us bundle 依赖。换出口复测通过前，不要据此包跑真数据验收。
+
+dsh-trading us 切片市场连接器（原数据源）：经 Stooq 公共 CSV 端点实现 `@dshtrading/api` 的 `MarketDataService` 契约（ctx 键 `tradingUsMarketData`），并提供 `us_get_ticker` / `us_get_klines` / `us_place_order` 三工具（下单三段闸门与 connector-binance 同构）。
+
+## 已知局限（实现时已内置）
+
+- 手册引用的报价端点 `/q/l/` 已 404（stooq.com 与 stooq.pl 均实测），`getTicker` 以最新日 K 收盘价近似，不反映盘前盘后；
+- 反爬挑战页 → `TRADING_RATE_LIMITED`（不做挑战求解/伪装）；`Access denied` → `TRADING_AUTH_FAILED`。
+
+## 合规记录（README 铁律 #5）
+
+Stooq 免费公开 CSV 端点、无 key；个人/非商业使用边界以 stooq.com 条款为准；本仓不缓存、不批量抓取、不再分发行情数据。

package/lib/index.d.ts

@@ -0,0 +1,83 @@
+import { INTERVAL_VOCABULARY, StooqRestClient, StooqRestOptions, TradingServiceError, easternWallTimeToEpochMs, isSupportedInterval, normalizeStooqSymbol } from "./rest.js";
+import { Context, Service } from "@deepseek-ai/cordis";
+import Schema from "@deepseek-ai/schemastery";
+import { Disposable, Interval, Kline, MarketDataService, Ticker } from "@dshtrading/api";
+//#region src/index.d.ts
+/**
+ * Cordis 插件名 = patch 行 id（TEMPLATES §8）：`dsh-trading-us-*` 市场命名空间，
+ * 全仓唯一（insert-only 铁律 #1）。
+ */
+declare const name = "dsh-trading-us-connector-stooq";
+interface Config {
+  /** 交易安全闸门（铁律 #3）：true 时下单类工具强制 dry-run。 */
+  dryRun: boolean;
+  /** 实盘总闸门：默认 false；false 时无论 dryRun 与否都拒绝实盘下单 [S4]。 */
+  liveTrading: boolean;
+}
+declare const Config: Schema<Config>;
+/** 需要宿主提供的 Cordis 服务。 */
+declare const inject: string[];
+/** ctx 服务键：与 @dshtrading/api 的 Context 模块增强一致（市场命名空间）。 */
+declare const TRADING_US_MARKET_DATA_KEY = "tradingUsMarketData";
+interface SubscribeTickerOptions {
+  /** 轮询间隔（ms）。subscribeTicker 以日 K 轮询实现（Stooq 无推送面）。 */
+  readonly intervalMs?: number;
+}
+declare class StooqMarketDataService extends Service implements MarketDataService {
+  private readonly client;
+  constructor(ctx: Context, options?: StooqRestOptions, name?: string);
+  getTicker(symbol: string): Promise<Ticker>;
+  getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
+  subscribeTicker(symbol: string, cb: (ticker: Ticker) => void, options?: SubscribeTickerOptions): Disposable;
+}
+/** us_place_order 参数契约（美股词汇，dryRun 缺省 true）。 */
+interface PlaceOrderArgs {
+  /** 股票代码，如 `AAPL` 或 `aapl.us`（执行前归一化为 Stooq 小写形态）。 */
+  readonly symbol: string;
+  readonly side: 'BUY' | 'SELL';
+  readonly type: 'MARKET' | 'LIMIT';
+  /** 股数（整股），必须 > 0。 */
+  readonly quantity: number;
+  /** LIMIT 单必填（schema 无法条件必填，execute 内校验），必须 > 0。 */
+  readonly price?: number;
+  /** 缺省视为 true：仅模拟。显式 false 即实盘意图，进入闸门 ①/③。 */
+  readonly dryRun?: boolean;
+}
+/**
+ * 闸门判定结果（三条路径与裁决顺序与 crypto 同构，见 connector-binance evaluateOrderGate）。
+ */
+type OrderGateVerdict = {
+  action: 'reject';
+  code: 'TRADING_LIVE_TRADING_DISABLED';
+  message: string;
+} | {
+  action: 'simulate';
+} | {
+  action: 'live';
+};
+declare function evaluateOrderGate(config: Config, args: PlaceOrderArgs): OrderGateVerdict;
+/** DRY-RUN 回执：模拟成交 + Stooq 最新收盘参照（参照取不到不阻断模拟本身）。 */
+interface DryRunReference {
+  source: 'stooq-daily-close';
+  price?: number;
+  volume?: number;
+  timestamp?: number;
+  unavailable?: string;
+}
+declare function buildDryRunReceipt(args: PlaceOrderArgs, marketData: Pick<MarketDataService, 'getTicker'>): Promise<string>;
+interface PlaceOrderToolDeps {
+  /** 行情服务（dry-run 回执的市价参照），按接口取用，不直连 HTTP。 */
+  readonly marketData: Pick<MarketDataService, 'getTicker'>;
+  /** 插件配置（dryRun 强制模拟 / liveTrading 总闸门）。 */
+  readonly config: Config;
+}
+/**
+ * us_place_order 工具工厂（独立导出便于单测三条闸门路径）。
+ *
+ * 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+ * `tools/pre-execute` waterfall 统一 ask（S4：headless 下 ask=deny，fail-closed）。
+ */
+declare function createPlaceOrderTool(deps: PlaceOrderToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { Config, DryRunReference, INTERVAL_VOCABULARY, OrderGateVerdict, PlaceOrderArgs, PlaceOrderToolDeps, StooqMarketDataService, StooqRestClient, StooqRestOptions, SubscribeTickerOptions, TRADING_US_MARKET_DATA_KEY, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, easternWallTimeToEpochMs, evaluateOrderGate, inject, isSupportedInterval, name, normalizeStooqSymbol };

package/lib/index.js

@@ -0,0 +1,235 @@
+import { INTERVAL_VOCABULARY, StooqRestClient, TradingServiceError, easternWallTimeToEpochMs, isSupportedInterval, normalizeStooqSymbol } from "./rest.js";
+import { Service } from "@deepseek-ai/cordis";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import Schema from "@deepseek-ai/schemastery";
+//#region src/index.ts
+/**
+* Cordis 插件名 = patch 行 id（TEMPLATES §8）：`dsh-trading-us-*` 市场命名空间，
+* 全仓唯一（insert-only 铁律 #1）。
+*/
+const name = "dsh-trading-us-connector-stooq";
+const Config = Schema.object({
+	dryRun: Schema.boolean().default(true),
+	liveTrading: Schema.boolean().default(false)
+});
+/** 需要宿主提供的 Cordis 服务。 */
+const inject = ["tools"];
+/** ctx 服务键：与 @dshtrading/api 的 Context 模块增强一致（市场命名空间）。 */
+const TRADING_US_MARKET_DATA_KEY = "tradingUsMarketData";
+const SUBSCRIBE_MIN_MS = 250;
+const SUBSCRIBE_DEFAULT_MS = 5e3;
+var StooqMarketDataService = class extends Service {
+	client;
+	constructor(ctx, options = {}, name = TRADING_US_MARKET_DATA_KEY) {
+		super(ctx, name);
+		this.client = new StooqRestClient(options);
+	}
+	getTicker(symbol) {
+		return this.client.getTicker(symbol);
+	}
+	getKlines(symbol, interval, limit) {
+		return this.client.getHistorical(symbol, interval).then((all) => typeof limit === "number" && Number.isInteger(limit) && limit > 0 ? all.slice(-limit) : all);
+	}
+	subscribeTicker(symbol, cb, options) {
+		const ms = Math.max(options?.intervalMs ?? SUBSCRIBE_DEFAULT_MS, SUBSCRIBE_MIN_MS);
+		const tick = () => {
+			this.client.getTicker(symbol).then(cb, () => {});
+		};
+		tick();
+		const timer = setInterval(tick, ms);
+		return { dispose: () => clearInterval(timer) };
+	}
+};
+function evaluateOrderGate(config, args) {
+	const requestedDryRun = args.dryRun ?? true;
+	if (!requestedDryRun && !config.liveTrading) return {
+		action: "reject",
+		code: "TRADING_LIVE_TRADING_DISABLED",
+		message: `us_place_order rejected: the call requests real execution (dryRun=${String(args.dryRun)}) but live trading is disabled (liveTrading=false). Ask the user to enable liveTrading explicitly after confirmation, or keep dryRun=true for a simulated fill.`
+	};
+	if (requestedDryRun || config.dryRun) return { action: "simulate" };
+	return { action: "live" };
+}
+/** 参数校验（模型调用问题抛普通 Error，与 crypto 先例一致；服务故障才用错误词汇）。 */
+function validatePlaceOrderArgs(args) {
+	if (typeof args.symbol !== "string" || !args.symbol.trim()) throw new Error("us_place_order: invalid symbol — expected a US ticker like AAPL or aapl.us");
+	try {
+		normalizeStooqSymbol(args.symbol);
+	} catch (cause) {
+		throw new Error(`us_place_order: invalid symbol ${JSON.stringify(args.symbol)} — expected a US ticker like AAPL`, { cause });
+	}
+	if (args.side !== "BUY" && args.side !== "SELL") throw new Error(`us_place_order: invalid side ${JSON.stringify(args.side)} — expected BUY or SELL`);
+	if (args.type !== "MARKET" && args.type !== "LIMIT") throw new Error(`us_place_order: invalid type ${JSON.stringify(args.type)} — expected MARKET or LIMIT`);
+	if (typeof args.quantity !== "number" || !Number.isFinite(args.quantity) || args.quantity <= 0) throw new Error(`us_place_order: invalid quantity ${JSON.stringify(args.quantity)} — expected a positive number`);
+	if (args.type === "LIMIT" && (typeof args.price !== "number" || !Number.isFinite(args.price) || args.price <= 0)) throw new Error("us_place_order: LIMIT orders require a positive price");
+}
+function normalizePlaceOrderArgs(raw) {
+	const args = raw ?? {};
+	const symbol = typeof args.symbol === "string" ? args.symbol.trim() : void 0;
+	return {
+		...args,
+		symbol
+	};
+}
+async function buildDryRunReceipt(args, marketData) {
+	const symbol = normalizeStooqSymbol(args.symbol);
+	let reference;
+	try {
+		const ticker = await marketData.getTicker(symbol);
+		reference = {
+			source: "stooq-daily-close",
+			price: ticker.price,
+			volume: ticker.volume,
+			timestamp: ticker.timestamp
+		};
+	} catch (error) {
+		reference = {
+			source: "stooq-daily-close",
+			unavailable: error instanceof Error ? error.message : String(error)
+		};
+	}
+	return JSON.stringify({
+		status: "filled",
+		dryRun: true,
+		note: "DRY-RUN — simulated fill; no order was sent to any broker. Stooq is a data source only (no trading API); the reference price is the latest daily close, which does not reflect pre/post-market moves.",
+		id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+		symbol: symbol.toUpperCase(),
+		side: args.side.toLowerCase(),
+		type: args.type.toLowerCase(),
+		quantity: args.quantity,
+		...args.type === "LIMIT" ? { price: args.price } : {},
+		reference,
+		timestamp: Date.now()
+	});
+}
+/**
+* us_place_order 工具工厂（独立导出便于单测三条闸门路径）。
+*
+* 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+* `tools/pre-execute` waterfall 统一 ask（S4：headless 下 ask=deny，fail-closed）。
+*/
+function createPlaceOrderTool(deps) {
+	return defineTool({
+		name: "us_place_order",
+		description: "Place a US stock order, or simulate one. dryRun defaults to true and returns a DRY-RUN simulated fill receipt referencing the latest Stooq daily close. Real execution (dryRun=false) requires the plugin liveTrading switch plus user approval, and is not implemented yet in this slice (Stooq has no trading API).",
+		parameters: {
+			symbol: {
+				type: "string",
+				required: true,
+				description: "US stock ticker, e.g. AAPL or aapl.us"
+			},
+			side: {
+				type: "string",
+				enum: ["BUY", "SELL"],
+				required: true,
+				description: "Order side"
+			},
+			type: {
+				type: "string",
+				enum: ["MARKET", "LIMIT"],
+				required: true,
+				description: "Order type"
+			},
+			quantity: {
+				type: "number",
+				required: true,
+				description: "Share quantity (whole shares), must be > 0"
+			},
+			price: {
+				type: "number",
+				description: "Limit price; required when type=LIMIT"
+			},
+			dryRun: {
+				type: "boolean",
+				description: "true (default) = simulate only and return a DRY-RUN receipt; false = request real execution (gated by liveTrading and user approval)",
+				default: true
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = normalizePlaceOrderArgs(raw);
+			validatePlaceOrderArgs(args);
+			const verdict = evaluateOrderGate(deps.config, args);
+			if (verdict.action === "reject") return JSON.stringify({
+				status: "rejected",
+				code: verdict.code,
+				message: verdict.message
+			});
+			if (verdict.action === "simulate") return buildDryRunReceipt(args, deps.marketData);
+			throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", "us_place_order: live order execution is not implemented in this slice — Stooq provides market data only; a broker API (e.g. Alpaca/IBKR) is a follow-up. Keep dryRun=true for simulated fills.");
+		}
+	});
+}
+function apply(ctx, config) {
+	new StooqMarketDataService(ctx);
+	ctx.inject(["tradingUsMarketData"], (ctx) => {
+		const marketData = ctx.tradingUsMarketData;
+		ctx.tools.register(defineTool({
+			name: "us_get_ticker",
+			description: "Get the latest market snapshot for a US stock via the Stooq public CSV endpoint. NOTE: the original Stooq quote endpoint is gone, so this returns the latest DAILY close (price, volume, close time) — it does not reflect intraday or pre/post-market moves. No credentials required; personal/non-commercial use per stooq.com terms.",
+			parameters: { symbol: {
+				type: "string",
+				required: true,
+				description: "US stock ticker, e.g. AAPL or aapl.us (normalized internally)"
+			} },
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const ticker = await marketData.getTicker(args.symbol);
+				return JSON.stringify(ticker);
+			}
+		}));
+		ctx.tools.register(defineTool({
+			name: "us_get_klines",
+			description: "Get recent OHLCV candles for a US stock via the Stooq public CSV endpoint. Supported intervals: 1/5/15/30 minute (intraday availability depends on Stooq policy), 1h, 1d, 1w, 1M. No credentials required; personal/non-commercial use per stooq.com terms.",
+			parameters: {
+				symbol: {
+					type: "string",
+					required: true,
+					description: "US stock ticker, e.g. AAPL or aapl.us (normalized internally)"
+				},
+				interval: {
+					type: "string",
+					enum: INTERVAL_VOCABULARY,
+					description: "Kline interval (Stooq-supported subset)",
+					default: "1d"
+				},
+				limit: {
+					type: "integer",
+					description: "Number of most recent candles to return (1-1000; Stooq returns full history and the tool trims)",
+					default: 100
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const interval = args.interval ?? "1d";
+				const limit = args.limit ?? 100;
+				const klines = await marketData.getKlines(args.symbol, interval, limit);
+				return JSON.stringify(klines);
+			}
+		}));
+		ctx.tools.register(createPlaceOrderTool({
+			marketData,
+			config
+		}));
+	});
+}
+//#endregion
+export { Config, INTERVAL_VOCABULARY, StooqMarketDataService, StooqRestClient, TRADING_US_MARKET_DATA_KEY, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, easternWallTimeToEpochMs, evaluateOrderGate, inject, isSupportedInterval, name, normalizeStooqSymbol };

package/lib/rest.d.ts

@@ -0,0 +1,36 @@
+import { Interval, Kline, Ticker, TradingErrorCode } from "@dshtrading/api";
+//#region src/rest.d.ts
+/** api 包 TradingError 契约的运行时 Error 实现。 */
+declare class TradingServiceError extends Error {
+  readonly code: TradingErrorCode;
+  constructor(code: TradingErrorCode, message: string, cause?: unknown);
+}
+/** 规范化并校验符号：接受 `AAPL` / `aapl.us`，统一为小写；无后缀补 `.us`。 */
+declare function normalizeStooqSymbol(symbol: string): string;
+/** 工具 parameters enum 用：受支持 interval 词汇（api Interval 的 Stooq 子集）。 */
+declare const INTERVAL_VOCABULARY: readonly string[];
+declare function isSupportedInterval(value: Interval): boolean;
+/** 美东墙钟时间 `YYYY-MM-DD HH:MM` → epoch ms（Stooq 分钟级时间戳为交易所当地时区）。 */
+declare function easternWallTimeToEpochMs(value: string): number;
+interface StooqRestOptions {
+  /** 覆盖站点 base（测试/反代用；stooq.pl 镜像同路径），末尾不带斜杠。 */
+  readonly baseUrl?: string;
+  /** 单请求超时（ms），默认 10s。 */
+  readonly timeoutMs?: number;
+  /** 注入 fetch 实现；缺省用全局 fetch（Node 22+ 内置）。 */
+  readonly fetchImpl?: typeof fetch;
+}
+declare class StooqRestClient {
+  #private;
+  constructor(options?: StooqRestOptions);
+  /** 拉取并解析 K 线 CSV（全量历史/可用窗口），行序为旧→新。 */
+  getHistorical(symbol: string, interval: Interval): Promise<Kline[]>;
+  /**
+   * 最新行情快照。原报价端点 /q/l/ 已 404（手册引用失真，2026-08-31 实测）——
+   * 以最新日 K 收盘价近似：price=close、volume=当日量；timestamp=该日收盘时刻。
+   * 盘前盘后不反映，工具描述必须向模型说明该局限。
+   */
+  getTicker(symbol: string): Promise<Ticker>;
+}
+//#endregion
+export { INTERVAL_VOCABULARY, StooqRestClient, StooqRestOptions, TradingServiceError, easternWallTimeToEpochMs, isSupportedInterval, normalizeStooqSymbol };

package/lib/rest.js

@@ -0,0 +1,191 @@
+//#region src/rest.ts
+/** api 包 TradingError 契约的运行时 Error 实现。 */
+var TradingServiceError = class extends Error {
+	code;
+	constructor(code, message, cause) {
+		super(message);
+		this.name = "TradingServiceError";
+		this.code = code;
+		if (cause !== void 0) this.cause = cause;
+	}
+};
+/** Stooq 符号：小写字母/数字，可选 `.xx` 国家/交易所后缀（美股固定 `.us`；jp/uk/de/hk… 亦存在）。 */
+const STOOQ_SYMBOL_PATTERN = /^[a-z0-9]{1,10}(?:\.[a-z]{1,3})?$/;
+/** 规范化并校验符号：接受 `AAPL` / `aapl.us`，统一为小写；无后缀补 `.us`。 */
+function normalizeStooqSymbol(symbol) {
+	if (typeof symbol !== "string" || !symbol.trim()) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", "Symbol must be a non-empty string, e.g. AAPL or aapl.us");
+	const lower = symbol.trim().toLowerCase();
+	const normalized = lower.includes(".") ? lower : `${lower}.us`;
+	if (!STOOQ_SYMBOL_PATTERN.test(normalized)) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Symbol ${JSON.stringify(symbol)} is not a valid Stooq symbol (expected like AAPL / aapl.us)`);
+	return normalized;
+}
+/** api Interval 词汇的受支持子集 → Stooq `i=` 值（分钟级数字；d/w/m 日/周/月）。 */
+const INTERVAL_TO_STOOQ = /* @__PURE__ */ new Map([
+	["1m", "1"],
+	["5m", "5"],
+	["15m", "15"],
+	["30m", "30"],
+	["1h", "60"],
+	["1d", "d"],
+	["1w", "w"],
+	["1M", "m"]
+]);
+/** 工具 parameters enum 用：受支持 interval 词汇（api Interval 的 Stooq 子集）。 */
+const INTERVAL_VOCABULARY = [...INTERVAL_TO_STOOQ.keys()];
+function isSupportedInterval(value) {
+	return INTERVAL_TO_STOOQ.has(value);
+}
+/** 日线行 `YYYY-MM-DD` → epoch ms（UTC 当日零点，行情日界语义，非交易时段语义）。 */
+function dailyDateToEpochMs(date) {
+	const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+	if (!m) throw new Error(`invalid stooq daily date ${JSON.stringify(date)}`);
+	return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+}
+/**
+* 日线收盘时刻 = 当日 UTC 零点 + 1 天 − 1ms（K 线 closeTime 语义，与 Binance 映射同构）。
+*/
+const DAY_MS = 864e5;
+/** 美东墙钟时间 `YYYY-MM-DD HH:MM` → epoch ms（Stooq 分钟级时间戳为交易所当地时区）。 */
+function easternWallTimeToEpochMs(value) {
+	const m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value);
+	if (!m) throw new Error(`invalid stooq intraday timestamp ${JSON.stringify(value)}`);
+	const [, y, mo, d, h, mi, s] = m;
+	const guess = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s ?? 0));
+	const offsetMs = (date) => {
+		const parts = new Intl.DateTimeFormat("en-US", {
+			timeZone: "America/New_York",
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+			hour12: false
+		}).formatToParts(new Date(date));
+		const get = (type) => Number(parts.find((p) => p.type === type)?.value ?? "0");
+		const hour = get("hour") % 24;
+		return Date.UTC(get("year"), get("month") - 1, get("day"), hour, get("minute"), get("second")) - date;
+	};
+	return guess - offsetMs(guess);
+}
+/** 解析单行 CSV（RFC4180 子集：双引号包裹 + `""` 转义）。 */
+function splitCsvLine(line) {
+	const fields = [];
+	let current = "";
+	let inQuotes = false;
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (inQuotes) {
+			if (ch === "\"") {
+				if (line[i + 1] === "\"") {
+					current += "\"";
+					i++;
+				} else inQuotes = false;
+			} else current += ch;
+		} else if (ch === "\"") inQuotes = true;
+		else if (ch === ",") {
+			fields.push(current);
+			current = "";
+		} else current += ch;
+	}
+	fields.push(current);
+	return fields;
+}
+/** 宽松转 number（非有限值返回 undefined）。 */
+function num(value) {
+	const n = Number(value);
+	return Number.isFinite(n) ? n : void 0;
+}
+const DEFAULT_BASE_URL = "https://stooq.com";
+const DEFAULT_TIMEOUT_MS = 1e4;
+var StooqRestClient = class {
+	#baseUrl;
+	#timeoutMs;
+	#fetchImpl;
+	constructor(options = {}) {
+		this.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.#fetchImpl = options.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
+	}
+	async #requestCsv(path, params) {
+		const query = new URLSearchParams(params).toString();
+		const target = `${this.#baseUrl}${path}?${query}`;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new DOMException(`request timed out after ${this.#timeoutMs}ms`, "TimeoutError")), this.#timeoutMs);
+		let res;
+		try {
+			res = await this.#fetchImpl(target, {
+				signal: controller.signal,
+				headers: { accept: "text/csv,text/html,*/*" }
+			});
+		} catch (cause) {
+			const timedOut = controller.signal.aborted;
+			throw new TradingServiceError("TRADING_NETWORK", timedOut ? `Stooq ${path}: request timed out after ${this.#timeoutMs}ms` : `Stooq ${path}: network error`, cause);
+		} finally {
+			clearTimeout(timer);
+		}
+		const text = await res.text().catch(() => "");
+		if (text.includes("__verify") || text.includes("requires JavaScript to verify")) throw new TradingServiceError("TRADING_RATE_LIMITED", `Stooq ${path}: the endpoint served an anti-bot JavaScript challenge instead of CSV data. Open stooq.com once in a normal browser (or use a different egress) so the session clears its check, then retry.`);
+		const trimmed = text.trim();
+		if (trimmed === "Access denied" || trimmed === "Odmowa dostępu" || trimmed === "Przekroczony dzienny limit wywołań") throw new TradingServiceError("TRADING_AUTH_FAILED", `Stooq ${path}: upstream denied anonymous data access ("${trimmed}"). Stooq restricts CSV downloads by egress/account policy — personal non-commercial use boundary is governed by stooq.com terms.`);
+		if (!res.ok) throw new TradingServiceError(res.status === 429 ? "TRADING_RATE_LIMITED" : "TRADING_EXCHANGE_ERROR", `Stooq ${path}: HTTP ${res.status} ${res.statusText}`);
+		if (!trimmed) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Stooq ${path}: empty response`);
+		return text;
+	}
+	/** 拉取并解析 K 线 CSV（全量历史/可用窗口），行序为旧→新。 */
+	async getHistorical(symbol, interval) {
+		const sym = normalizeStooqSymbol(symbol);
+		const i = INTERVAL_TO_STOOQ.get(interval);
+		if (i === void 0) throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `Stooq klines: unsupported interval ${String(interval)} — supported: ${INTERVAL_VOCABULARY.join("/")}`);
+		const lines = (await this.#requestCsv("/q/d/l/", {
+			s: sym,
+			i
+		})).trim().split(/\r?\n/);
+		if (lines[0] !== "Date,Open,High,Low,Close,Volume") throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Stooq klines for ${sym}: unexpected payload (expected "Date,Open,High,Low,Close,Volume" header)`);
+		const intraday = i !== "d" && i !== "w" && i !== "m";
+		const klines = [];
+		for (const line of lines.slice(1)) {
+			if (!line.trim()) continue;
+			const f = splitCsvLine(line);
+			if (f.length < 6) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Stooq klines for ${sym}: malformed row ${JSON.stringify(line)}`);
+			const [dateField, o, h, l, c, v] = f;
+			const open = num(o);
+			const high = num(h);
+			const low = num(l);
+			const close = num(c);
+			const volume = num(v);
+			if (open === void 0 || high === void 0 || low === void 0 || close === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Stooq klines for ${sym}: malformed row values ${JSON.stringify(line)}`);
+			const openTime = intraday ? easternWallTimeToEpochMs(dateField) : dailyDateToEpochMs(dateField);
+			klines.push({
+				openTime,
+				open,
+				high,
+				low,
+				close,
+				volume: volume ?? 0,
+				closeTime: intraday ? openTime + 6e4 * Number(i) - 1 : openTime + DAY_MS - 1
+			});
+		}
+		if (klines.length === 0) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Stooq klines for ${sym}: no data rows (unknown/delisted symbol?)`);
+		return klines;
+	}
+	/**
+	* 最新行情快照。原报价端点 /q/l/ 已 404（手册引用失真，2026-08-31 实测）——
+	* 以最新日 K 收盘价近似：price=close、volume=当日量；timestamp=该日收盘时刻。
+	* 盘前盘后不反映，工具描述必须向模型说明该局限。
+	*/
+	async getTicker(symbol) {
+		const sym = normalizeStooqSymbol(symbol);
+		const klines = await this.getHistorical(sym, "1d");
+		const last = klines[klines.length - 1];
+		if (!last) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Stooq ticker for ${sym}: no data rows`);
+		return {
+			symbol: sym.toUpperCase().replace(/\.US$/, ""),
+			price: last.close,
+			volume: last.volume,
+			timestamp: last.closeTime
+		};
+	}
+};
+//#endregion
+export { INTERVAL_VOCABULARY, StooqRestClient, TradingServiceError, easternWallTimeToEpochMs, isSupportedInterval, normalizeStooqSymbol };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@dshtrading/connector-stooq",
+  "description": "US market connector plugin for dsh-trading: public market data from Stooq CSV endpoints implementing the @dshtrading/api contracts (no key; personal/non-commercial use per stooq.com terms)",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@dshtrading/api": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-alpha.1",
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}