@dshtrading/connector-alpaca 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,34 @@
+# @dshtrading/connector-template
+
+**本包是脚手架源，不是可安装的连接器**：不入任何 bundle 依赖，仅在 `pnpm -r build/test`
+基线内保证可编译、冒烟测试绿。真实接入用生成器：
+
+```sh
+node scripts/new-connector.mjs --slug bybit --title Bybit --market crypto
+```
+
+生成后按 [docs/connector-playbook.md](../../docs/connector-playbook.md) 的填写顺序
+（src/rest.ts 头部清单 7 项）实现 TODO。每个 TODO 的参照段都在 connector-okx
+（packages/connector-okx/），它是本仓第一个真实 TradeService 连接器。
+
+## 结构
+
+- `src/rest.ts` —— 错误载体（TradingServiceError）+ 通用请求管线（超时/错误映射/
+  模拟盘头/注入 fetch）直接可用；签名与端点 TODO。
+- `src/index.ts` —— Config（enabled/env/dryRun/liveTrading + 三 ref 凭证组）、
+  闸门三态判定、凭证解析（BYOK + 环境变量回落）、MarketDataService/TradeService 骨架、
+  7 个市场前缀工具注册（duplicate-safe）、apply（enabled=false 静默退出）。
+- `test/template.test.ts` —— 结构冒烟 7 用例。
+
+## Token
+
+`alpaca`（slug）/ `Alpaca`（title）/ `ALPACA`（ref 前缀）/
+`us`（工具前缀）/ `Us`（服务键 infix）。token 未展开也可编译；
+生成器保证全部替换。
+
+## 注意（勿改的坑）
+
+- 服务类用 TS 编译期 `private`（禁 ECMAScript `#`，realm 代理会炸）。
+- 工具名 = 市场前缀 + 语义词（不带交易所名）——base 闸门正则只认市场前缀。
+- 行 id = `dsh-trading-<market>-connector-<slug>`，全仓唯一（insert-only 铁律 #1）。
+- 凭证只进 ref，绝不内置/落日志（铁律 #3/#5）。

package/lib/dataplane.d.ts

@@ -0,0 +1,7 @@
+import { Config } from "./index.js";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/dataplane.d.ts
+declare const inject: string[];
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { apply, inject };

package/lib/dataplane.js

@@ -0,0 +1,47 @@
+import { AlpacaMarketDataService, AlpacaTradeService, TRADING_US_MARKET_DATA_KEY, TRADING_US_TRADE_KEY, credentialRefsFor, resolveCredentials } from "./index.js";
+//#region src/dataplane.ts
+const inject = [];
+/** 解析注册表服务；老部署（base/router 未升级）返回 undefined → 调用方回退直接 provide。 */
+function resolveMarketDataRegistry(ctx) {
+	const candidate = ctx.get?.("tradingMarketDataRegistry", false);
+	return candidate !== void 0 ? candidate : void 0;
+}
+/** 解析交易注册表服务（issue #40）；老部署返回 undefined → 跳过。 */
+function resolveTradeRegistry(ctx) {
+	const candidate = ctx.get?.("tradingTradeRegistry", false);
+	return candidate !== void 0 ? candidate : void 0;
+}
+/** 本连接器的路由 provider slug（路由层词汇 = 交易所 slug，docs/exchange-routing.md §2.2）。 */
+const ROUTER_PROVIDER = "alpaca";
+/** 市场短前缀。 */
+const MARKET = "us";
+function apply(ctx, config) {
+	if (!config.enabled) return;
+	const registry = resolveMarketDataRegistry(ctx);
+	if (registry === void 0) {
+		new AlpacaMarketDataService(ctx);
+		return;
+	}
+	const inner = ctx.isolate(TRADING_US_MARKET_DATA_KEY);
+	const service = new AlpacaMarketDataService(inner, {}, () => {
+		const refs = credentialRefsFor(config);
+		return resolveCredentials(ctx, refs, config.env);
+	});
+	ctx.effect(() => registry.register(MARKET, ROUTER_PROVIDER, service));
+	const tradeRegistry = resolveTradeRegistry(ctx);
+	if (tradeRegistry !== void 0) {
+		const tradeInner = ctx.isolate(TRADING_US_TRADE_KEY);
+		const trade = new AlpacaTradeService(tradeInner, {
+			config,
+			env: config.env
+		}, async () => {
+			const refs = credentialRefsFor(config);
+			const creds = await resolveCredentials(ctx, refs, config.env);
+			if (!creds) throw new Error("Alpaca credentials missing");
+			return creds;
+		});
+		ctx.effect(() => tradeRegistry.register(MARKET, ROUTER_PROVIDER, trade));
+	}
+}
+//#endregion
+export { apply, inject };

package/lib/index.d.ts

@@ -0,0 +1,94 @@
+import { AccountBalance, AlpacaCredentials, AlpacaRestClient, AlpacaRestOptions, INTERVAL_TO_ALPACA, INTERVAL_VOCABULARY, Interval, Kline, Order, Orderbook, Position, Ticker, TradeFill, TradingServiceError, normalizeUsSymbol } from "./rest.js";
+import { Context, Service } from "@deepseek-ai/cordis";
+import Schema from "@deepseek-ai/schemastery";
+import { AccountBalance as AccountBalance$1, Disposable, Interval as Interval$1, Kline as Kline$1, MarketDataService, Order as Order$1, OrderRequest, Orderbook as Orderbook$1, Position as Position$1, Ticker as Ticker$1, TradeFill as TradeFill$1, TradeService } from "@dshtrading/api";
+//#region src/index.d.ts
+declare const name = "dsh-trading-us-connector-alpaca";
+interface Config {
+  enabled: boolean;
+  env: 'demo' | 'live';
+  dryRun: boolean;
+  liveTrading: boolean;
+  apiKeyRef: string;
+  secretRef: string;
+  demoApiKeyRef: string;
+  demoSecretRef: string;
+}
+declare const Config: Schema<Config>;
+declare const inject: string[];
+declare const TRADING_US_MARKET_DATA_KEY = "tradingUsMarketData";
+declare const TRADING_US_TRADE_KEY = "tradingUsTrade";
+interface CredentialResolverLike {
+  resolve(ref: string): Promise<{
+    value: string;
+  } | undefined>;
+}
+interface CredentialsContext {
+  get(name: string): unknown;
+}
+interface ResolvedCredentialRefs {
+  readonly apiKeyRef: string;
+  readonly secretRef: string;
+}
+declare function credentialRefsFor(config: Config, env?: 'demo' | 'live'): ResolvedCredentialRefs;
+declare function resolveCredentials(ctx: CredentialsContext, refs: ResolvedCredentialRefs, env: 'demo' | 'live'): Promise<AlpacaCredentials | undefined>;
+declare class AlpacaMarketDataService extends Service implements MarketDataService {
+  private readonly client;
+  private readonly getCredentials;
+  constructor(ctx: Context, options?: AlpacaRestOptions, getCredentials?: () => Promise<AlpacaCredentials | undefined>, serviceName?: string);
+  getTicker(symbol: string): Promise<Ticker$1>;
+  getKlines(symbol: string, interval: Interval$1, limit?: number): Promise<Kline$1[]>;
+  listInstruments(): Promise<Array<{
+    symbol: string;
+    name?: string;
+  }>>;
+  getOrderbook(symbol: string): Promise<Orderbook$1>;
+  subscribeTicker(symbol: string, cb: (ticker: Ticker$1) => void, options?: {
+    intervalMs?: number;
+  }): Disposable;
+}
+declare class AlpacaTradeService extends Service implements TradeService {
+  private readonly client;
+  /** 插件配置（服务缝闸门 P0：dryRun 强制模拟 / liveTrading 总闸门）。 */
+  private readonly config;
+  private readonly getCredentials;
+  constructor(ctx: Context, options: AlpacaRestOptions & {
+    config: Config;
+  }, getCredentials: () => Promise<AlpacaCredentials>, serviceName?: string);
+  getBalance(): Promise<AccountBalance$1>;
+  getBalances(): Promise<AccountBalance$1[]>;
+  placeOrder(order: OrderRequest): Promise<Order$1>;
+  cancelOrder(orderId: string, _symbol?: string): Promise<void>;
+  getOrder(_symbol: string, id: string): Promise<Order$1>;
+  getPositions(): Promise<Position$1[]>;
+  listOpenOrders(symbol?: string): Promise<Order$1[]>;
+  listTradeFills(symbol?: string, limit?: number): Promise<TradeFill$1[]>;
+}
+interface PlaceOrderArgs {
+  readonly symbol: string;
+  readonly side: 'BUY' | 'SELL';
+  readonly type: 'MARKET' | 'LIMIT';
+  readonly quantity: number;
+  readonly price?: number;
+  readonly dryRun?: boolean;
+}
+type OrderGateVerdict = {
+  action: 'reject';
+  code: 'TRADING_LIVE_TRADING_DISABLED';
+  message: string;
+} | {
+  action: 'simulate';
+} | {
+  action: 'live';
+};
+declare function evaluateOrderGate(config: Config, args: PlaceOrderArgs): OrderGateVerdict;
+declare function createPlaceOrderTool(deps: {
+  marketData: Pick<MarketDataService, 'getTicker'>;
+  trade?: TradeService;
+  config: Config;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare const ROUTER_PROVIDER = "alpaca";
+declare function routeAllows(ctx: Context, config: Config, market: string): boolean;
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { type AccountBalance, AlpacaCredentials, AlpacaMarketDataService, AlpacaRestClient, AlpacaRestOptions, AlpacaTradeService, Config, CredentialResolverLike, CredentialsContext, INTERVAL_TO_ALPACA, INTERVAL_VOCABULARY, type Interval, type Kline, type Order, OrderGateVerdict, type Orderbook, PlaceOrderArgs, type Position, ROUTER_PROVIDER, ResolvedCredentialRefs, TRADING_US_MARKET_DATA_KEY, TRADING_US_TRADE_KEY, type Ticker, type TradeFill, TradingServiceError, apply, createPlaceOrderTool, credentialRefsFor, evaluateOrderGate, inject, name, normalizeUsSymbol, resolveCredentials, routeAllows };

package/lib/index.js

@@ -0,0 +1,352 @@
+import { AlpacaRestClient, INTERVAL_TO_ALPACA, INTERVAL_VOCABULARY, TradingServiceError, normalizeUsSymbol } 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
+const name = "dsh-trading-us-connector-alpaca";
+const Config = Schema.object({
+	enabled: Schema.boolean().default(false),
+	env: Schema.union(["demo", "live"]).default("demo"),
+	dryRun: Schema.boolean().default(true),
+	liveTrading: Schema.boolean().default(false),
+	apiKeyRef: Schema.string().default("ALPACA_API_KEY"),
+	secretRef: Schema.string().default("ALPACA_SECRET_KEY"),
+	demoApiKeyRef: Schema.string().default("ALPACA_PAPER_API_KEY"),
+	demoSecretRef: Schema.string().default("ALPACA_PAPER_SECRET_KEY")
+});
+const inject = ["tools"];
+const TRADING_US_MARKET_DATA_KEY = "tradingUsMarketData";
+const TRADING_US_TRADE_KEY = "tradingUsTrade";
+const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function credentialRefsFor(config, env = config.env) {
+	return env === "demo" ? {
+		apiKeyRef: config.demoApiKeyRef,
+		secretRef: config.demoSecretRef
+	} : {
+		apiKeyRef: config.apiKeyRef,
+		secretRef: config.secretRef
+	};
+}
+async function resolveCredentials(ctx, refs, env) {
+	const entries = [["apiKey", refs.apiKeyRef], ["secret", refs.secretRef]];
+	const routerCreds = (ctx.get("tradingMarketRouter") ?? void 0)?.getCredential?.("alpaca");
+	if (routerCreds?.apiKey && (routerCreds?.secretKey || routerCreds?.secret)) return {
+		key: routerCreds.apiKey,
+		secret: routerCreds.secretKey || routerCreds.secret
+	};
+	for (const [field, ref] of entries) if (!CREDENTIAL_REF_PATTERN.test(ref)) throw new TradingServiceError("TRADING_CREDENTIALS_MISSING", `Alpaca ${env} credentials invalid: ${field} ref ${JSON.stringify(ref)} must match ^[A-Za-z_][A-Za-z0-9_]*$`);
+	const resolver = ctx.get("credentials");
+	const resolved = await Promise.all(entries.map(async ([field, ref]) => {
+		if (resolver !== void 0) try {
+			const res = await resolver.resolve(ref);
+			if (res?.value) return {
+				field,
+				value: res.value
+			};
+		} catch {}
+		const envVal = process.env[ref];
+		if (envVal) return {
+			field,
+			value: envVal
+		};
+		return {
+			field,
+			value: void 0
+		};
+	}));
+	if (resolved.filter((r) => !r.value).map((r) => r.field).length > 0) return;
+	const [apiKey, secret] = resolved.map((r) => r.value);
+	return {
+		key: apiKey,
+		secret
+	};
+}
+var AlpacaMarketDataService = class extends Service {
+	client;
+	getCredentials;
+	constructor(ctx, options = {}, getCredentials = async () => void 0, serviceName = TRADING_US_MARKET_DATA_KEY) {
+		super(ctx, serviceName);
+		this.client = new AlpacaRestClient(options);
+		this.getCredentials = getCredentials;
+	}
+	async getTicker(symbol) {
+		const creds = await this.getCredentials();
+		return this.client.getTicker(symbol, creds);
+	}
+	async getKlines(symbol, interval, limit) {
+		const creds = await this.getCredentials();
+		return this.client.getKlines(symbol, interval, limit, creds);
+	}
+	async listInstruments() {
+		const creds = await this.getCredentials();
+		return this.client.listInstruments(creds);
+	}
+	async getOrderbook(symbol) {
+		const creds = await this.getCredentials();
+		return this.client.getOrderbook(symbol, creds);
+	}
+	subscribeTicker(symbol, cb, options) {
+		const ms = Math.max(options?.intervalMs ?? 5e3, 500);
+		const tick = () => {
+			this.getTicker(symbol).then(cb, () => {});
+		};
+		tick();
+		const timer = setInterval(tick, ms);
+		return { dispose: () => clearInterval(timer) };
+	}
+};
+var AlpacaTradeService = class extends Service {
+	client;
+	/** 插件配置（服务缝闸门 P0：dryRun 强制模拟 / liveTrading 总闸门）。 */
+	config;
+	getCredentials;
+	constructor(ctx, options, getCredentials, serviceName = TRADING_US_TRADE_KEY) {
+		super(ctx, serviceName);
+		this.client = new AlpacaRestClient(options);
+		this.config = options.config;
+		this.getCredentials = getCredentials;
+	}
+	async getBalance() {
+		const creds = await this.getCredentials();
+		return this.client.getBalance(creds);
+	}
+	async getBalances() {
+		const creds = await this.getCredentials();
+		return [await this.client.getBalance(creds)];
+	}
+	async placeOrder(order) {
+		const requestedDryRun = order.dryRun ?? true;
+		if (!requestedDryRun && !this.config.liveTrading) throw new TradingServiceError("TRADING_LIVE_TRADING_DISABLED", `Alpaca TradeService.placeOrder rejected: the request asks for real execution (dryRun=${String(order.dryRun)}) but liveTrading=false — enable liveTrading explicitly or keep dryRun=true for a simulated fill.`);
+		if (requestedDryRun || this.config.dryRun) return {
+			id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+			symbol: order.symbol,
+			side: order.side,
+			type: order.type,
+			status: "filled",
+			...order.price !== void 0 ? { price: order.price } : {},
+			quantity: order.quantity,
+			dryRun: true,
+			timestamp: Date.now()
+		};
+		const creds = await this.getCredentials();
+		return this.client.placeOrder(creds, {
+			symbol: order.symbol,
+			side: order.side.toUpperCase(),
+			type: order.type.toUpperCase(),
+			quantity: order.quantity,
+			price: order.price
+		});
+	}
+	async cancelOrder(orderId, _symbol) {
+		if (!this.config.liveTrading || this.config.dryRun) throw new TradingServiceError("TRADING_LIVE_TRADING_DISABLED", "Alpaca TradeService.cancelOrder rejected at the service seam: cancel is a live action and requires liveTrading=true with dryRun=false.");
+		const creds = await this.getCredentials();
+		await this.client.cancelOrder(creds, orderId);
+	}
+	async getOrder(_symbol, id) {
+		const creds = await this.getCredentials();
+		return this.client.getOrder(creds, id);
+	}
+	async getPositions() {
+		try {
+			const creds = await this.getCredentials();
+			return await this.client.getPositions(creds);
+		} catch {
+			return [];
+		}
+	}
+	async listOpenOrders(symbol) {
+		try {
+			const creds = await this.getCredentials();
+			return await this.client.listOpenOrders(creds, symbol);
+		} catch {
+			return [];
+		}
+	}
+	async listTradeFills(symbol, limit) {
+		try {
+			const creds = await this.getCredentials();
+			return await this.client.listTradeFills(creds, symbol, limit);
+		} catch {
+			return [];
+		}
+	}
+};
+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: real execution requested (dryRun=${String(args.dryRun)}) but live trading is disabled (liveTrading=false). Enable liveTrading explicitly or keep dryRun=true.`
+	};
+	if (requestedDryRun || config.dryRun) return { action: "simulate" };
+	return { action: "live" };
+}
+function createPlaceOrderTool(deps) {
+	return defineTool({
+		name: "us_place_order",
+		description: "Place or simulate a US stock order via Alpaca. dryRun defaults to true for simulated execution.",
+		parameters: {
+			symbol: {
+				type: "string",
+				required: true,
+				description: "US stock symbol, e.g. AAPL"
+			},
+			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: "Number of shares (> 0)"
+			},
+			price: {
+				type: "number",
+				description: "Limit price; required when type=LIMIT"
+			},
+			dryRun: {
+				type: "boolean",
+				default: true,
+				description: "Simulate order only (default true)"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = raw;
+			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" || !deps.trade) {
+				let referencePrice;
+				try {
+					referencePrice = (await deps.marketData.getTicker(args.symbol)).price;
+				} catch {}
+				return JSON.stringify({
+					status: "filled",
+					dryRun: true,
+					id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+					symbol: args.symbol.toUpperCase(),
+					side: args.side.toLowerCase(),
+					type: args.type.toLowerCase(),
+					quantity: args.quantity,
+					...args.price ? { price: args.price } : {},
+					referencePrice,
+					timestamp: Date.now()
+				});
+			}
+			const order = await deps.trade.placeOrder({
+				symbol: args.symbol,
+				side: args.side,
+				type: args.type,
+				quantity: args.quantity,
+				price: args.price
+			});
+			return JSON.stringify(order);
+		}
+	});
+}
+const ROUTER_PROVIDER = "alpaca";
+function routeAllows(ctx, config, market) {
+	if (!config.enabled) return false;
+	const router = ctx.get?.("tradingMarketRouter", false);
+	if (router === void 0) return true;
+	return router.activeProvider(market) === ROUTER_PROVIDER;
+}
+function apply(ctx, config) {
+	if (!config.enabled) return;
+	if (!routeAllows(ctx, config, "us")) return;
+	const credRefs = credentialRefsFor(config);
+	const getCreds = () => resolveCredentials(ctx, credRefs, config.env);
+	const requireCreds = async () => {
+		const creds = await getCreds();
+		if (!creds) throw new TradingServiceError("TRADING_CREDENTIALS_MISSING", `Alpaca credentials missing for ${config.env}. Set ${credRefs.apiKeyRef} and ${credRefs.secretRef}.`);
+		return creds;
+	};
+	const marketData = new AlpacaMarketDataService(ctx, { env: config.env }, getCreds);
+	const trade = new AlpacaTradeService(ctx, {
+		env: config.env,
+		config
+	}, requireCreds);
+	ctx.inject(["tools"], (ctx) => {
+		const tools = ctx.tools;
+		const register = (t) => {
+			if (tools.get(t.name) === void 0) tools.register(t);
+		};
+		register(defineTool({
+			name: "us_get_ticker",
+			description: "Get the latest trade price and quote for a US stock via Alpaca API.",
+			parameters: { symbol: {
+				type: "string",
+				required: true,
+				description: "US stock symbol, e.g. AAPL"
+			} },
+			output: {
+				schema: { type: "string" },
+				render: (_a, v) => [{
+					type: "text",
+					text: v
+				}]
+			},
+			async execute(args) {
+				return JSON.stringify(await marketData.getTicker(args.symbol));
+			}
+		}));
+		register(defineTool({
+			name: "us_get_klines",
+			description: "Get recent public klines for a US stock via Alpaca API. Supports 5m/15m/30m/1h/1d/1w/1M.",
+			parameters: {
+				symbol: {
+					type: "string",
+					required: true,
+					description: "US stock symbol, e.g. AAPL"
+				},
+				interval: {
+					type: "string",
+					enum: INTERVAL_VOCABULARY,
+					default: "1d",
+					description: "Interval"
+				},
+				limit: {
+					type: "integer",
+					default: 100,
+					description: "Limit"
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_a, v) => [{
+					type: "text",
+					text: v
+				}]
+			},
+			async execute(args) {
+				const klines = await marketData.getKlines(args.symbol, args.interval ?? "1d", args.limit);
+				return JSON.stringify(klines);
+			}
+		}));
+		register(createPlaceOrderTool({
+			marketData,
+			trade,
+			config
+		}));
+	});
+}
+//#endregion
+export { AlpacaMarketDataService, AlpacaRestClient, AlpacaTradeService, Config, INTERVAL_TO_ALPACA, INTERVAL_VOCABULARY, ROUTER_PROVIDER, TRADING_US_MARKET_DATA_KEY, TRADING_US_TRADE_KEY, TradingServiceError, apply, createPlaceOrderTool, credentialRefsFor, evaluateOrderGate, inject, name, normalizeUsSymbol, resolveCredentials, routeAllows };

package/lib/rest.d.ts

@@ -0,0 +1,51 @@
+import { AccountBalance as AccountBalance$1, Interval as Interval$1, Kline as Kline$1, Order as Order$1, Orderbook as Orderbook$1, Position as Position$1, Ticker as Ticker$1, TradeFill as TradeFill$1, TradingErrorCode } from "@dshtrading/api";
+//#region src/rest.d.ts
+declare class TradingServiceError extends Error {
+  readonly code: TradingErrorCode;
+  constructor(code: TradingErrorCode, message: string, cause?: unknown);
+}
+interface AlpacaRestOptions {
+  dataBaseUrl?: string;
+  tradingBaseUrl?: string;
+  env?: 'demo' | 'live';
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+interface AlpacaCredentials {
+  readonly key: string;
+  readonly secret: string;
+}
+declare const INTERVAL_TO_ALPACA: Record<Interval$1, string>;
+declare const INTERVAL_VOCABULARY: Interval$1[];
+declare function normalizeUsSymbol(raw: string): string;
+declare class AlpacaRestClient {
+  private readonly dataBaseUrl;
+  private readonly tradingBaseUrl;
+  private readonly fetchImpl;
+  private readonly timeoutMs;
+  constructor(options?: AlpacaRestOptions);
+  private buildHeaders;
+  private request;
+  getTicker(symbol: string, credentials?: AlpacaCredentials): Promise<Ticker$1>;
+  getKlines(symbol: string, interval: Interval$1, limit?: number, credentials?: AlpacaCredentials): Promise<Kline$1[]>;
+  listInstruments(credentials?: AlpacaCredentials): Promise<Array<{
+    symbol: string;
+    name?: string;
+  }>>;
+  getOrderbook(symbol: string, credentials?: AlpacaCredentials): Promise<Orderbook$1>;
+  getBalance(credentials: AlpacaCredentials): Promise<AccountBalance$1>;
+  getPositions(credentials: AlpacaCredentials): Promise<Position$1[]>;
+  listOpenOrders(credentials: AlpacaCredentials, symbol?: string): Promise<Order$1[]>;
+  listTradeFills(credentials: AlpacaCredentials, symbol?: string, limit?: number): Promise<TradeFill$1[]>;
+  placeOrder(credentials: AlpacaCredentials, req: {
+    symbol: string;
+    side: 'BUY' | 'SELL';
+    type: 'MARKET' | 'LIMIT';
+    quantity: number;
+    price?: number;
+  }): Promise<Order$1>;
+  cancelOrder(credentials: AlpacaCredentials, orderId: string): Promise<void>;
+  getOrder(credentials: AlpacaCredentials, orderId: string): Promise<Order$1>;
+}
+//#endregion
+export { type AccountBalance$1 as AccountBalance, AlpacaCredentials, AlpacaRestClient, AlpacaRestOptions, INTERVAL_TO_ALPACA, INTERVAL_VOCABULARY, type Interval$1 as Interval, type Kline$1 as Kline, type Order$1 as Order, type Orderbook$1 as Orderbook, type Position$1 as Position, type Ticker$1 as Ticker, type TradeFill$1 as TradeFill, TradingServiceError, normalizeUsSymbol };

package/lib/rest.js

@@ -0,0 +1,296 @@
+//#region src/rest.ts
+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;
+	}
+};
+const INTERVAL_TO_ALPACA = {
+	"1m": "1Min",
+	"5m": "5Min",
+	"15m": "15Min",
+	"30m": "30Min",
+	"1h": "1Hour",
+	"4h": "4Hour",
+	"1d": "1Day",
+	"1w": "1Week",
+	"1M": "1Month"
+};
+const INTERVAL_MS = {
+	"1m": 6e4,
+	"5m": 3e5,
+	"15m": 9e5,
+	"30m": 18e5,
+	"1h": 36e5,
+	"4h": 144e5,
+	"1d": 864e5,
+	"1w": 1008e4,
+	"1M": 432e5
+};
+const INTERVAL_VOCABULARY = Object.keys(INTERVAL_TO_ALPACA);
+function normalizeUsSymbol(raw) {
+	const s = raw.trim().toUpperCase();
+	if (!/^[A-Z]{1,10}(\.[A-Z]{1,4})?$/.test(s)) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Alpaca: malformed US symbol ${JSON.stringify(raw)}`);
+	return s;
+}
+var AlpacaRestClient = class {
+	dataBaseUrl;
+	tradingBaseUrl;
+	fetchImpl;
+	timeoutMs;
+	constructor(options = {}) {
+		this.dataBaseUrl = (options.dataBaseUrl ?? "https://data.alpaca.markets/v2").replace(/\/+$/, "");
+		const defaultTrading = options.env === "live" ? "https://api.alpaca.markets/v2" : "https://paper-api.alpaca.markets/v2";
+		this.tradingBaseUrl = (options.tradingBaseUrl ?? defaultTrading).replace(/\/+$/, "");
+		this.fetchImpl = options.fetchImpl ?? fetch;
+		this.timeoutMs = options.timeoutMs ?? 1e4;
+	}
+	buildHeaders(credentials) {
+		const headers = { accept: "application/json" };
+		if (credentials?.key && credentials?.secret) {
+			headers["APCA-API-KEY-ID"] = credentials.key;
+			headers["APCA-API-SECRET-KEY"] = credentials.secret;
+		}
+		return headers;
+	}
+	async request(baseUrl, path, init = {}, credentials) {
+		const url = baseUrl + (path.startsWith("/") ? path : "/" + path);
+		const headers = {
+			...this.buildHeaders(credentials),
+			...init.headers
+		};
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`request timed out after ${this.timeoutMs}ms`)), this.timeoutMs);
+		try {
+			const res = await this.fetchImpl(url, {
+				...init,
+				headers,
+				signal: controller.signal
+			});
+			if (!res.ok) {
+				let errBody;
+				try {
+					errBody = await res.json();
+				} catch {
+					errBody = await res.text().catch(() => "");
+				}
+				const msg = typeof errBody === "object" && errBody !== null && "message" in errBody ? String(errBody.message) : String(errBody ?? res.statusText);
+				if (res.status === 401 || res.status === 403) throw new TradingServiceError("TRADING_AUTH_FAILED", `Alpaca auth failed (${res.status}): ${msg}`);
+				if (res.status === 429) throw new TradingServiceError("TRADING_RATE_LIMITED", `Alpaca rate limited (429): ${msg}`);
+				if (res.status === 404) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Alpaca not found (404): ${msg}`);
+				if (res.status === 422) {
+					if (/insufficient|buying power|balance/i.test(msg)) throw new TradingServiceError("TRADING_INSUFFICIENT_BALANCE", `Alpaca balance error (422): ${msg}`);
+					throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Alpaca invalid parameters (422): ${msg}`);
+				}
+				throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Alpaca HTTP ${res.status}: ${msg}`);
+			}
+			return await res.json();
+		} catch (error) {
+			if (error instanceof TradingServiceError) throw error;
+			throw new TradingServiceError("TRADING_NETWORK", error instanceof Error ? error.message : String(error), error);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	async getTicker(symbol, credentials) {
+		const sym = normalizeUsSymbol(symbol);
+		const [tradeRes, quoteRes] = await Promise.allSettled([this.request(this.dataBaseUrl, `/stocks/${sym}/trades/latest?feed=iex`, { method: "GET" }, credentials), this.request(this.dataBaseUrl, `/stocks/${sym}/quotes/latest?feed=iex`, { method: "GET" }, credentials)]);
+		if (tradeRes.status === "rejected" && quoteRes.status === "rejected") throw tradeRes.reason;
+		let price = 0;
+		let timestamp = Date.now();
+		if (tradeRes.status === "fulfilled") {
+			const data = tradeRes.value;
+			if (typeof data?.trade?.p === "number") price = data.trade.p;
+			if (typeof data?.trade?.t === "string") timestamp = new Date(data.trade.t).getTime();
+		}
+		let bid;
+		let ask;
+		if (quoteRes.status === "fulfilled") {
+			const data = quoteRes.value;
+			if (typeof data?.quote?.bp === "number" && data.quote.bp > 0) bid = data.quote.bp;
+			if (typeof data?.quote?.ap === "number" && data.quote.ap > 0) ask = data.quote.ap;
+			if (price === 0 && bid !== void 0 && ask !== void 0) {
+				price = (bid + ask) / 2;
+				if (typeof data?.quote?.t === "string") timestamp = new Date(data.quote.t).getTime();
+			}
+		}
+		return {
+			symbol: sym,
+			price,
+			timestamp,
+			...bid !== void 0 ? { bid } : {},
+			...ask !== void 0 ? { ask } : {}
+		};
+	}
+	async getKlines(symbol, interval, limit = 100, credentials) {
+		const sym = normalizeUsSymbol(symbol);
+		const tf = INTERVAL_TO_ALPACA[interval];
+		if (!tf) throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `Alpaca: unsupported interval ${String(interval)}`);
+		const path = `/stocks/bars?symbols=${sym}&timeframe=${tf}&limit=${Math.min(Math.max(Number(limit) || 100, 1), 1e3)}&feed=iex&adjustment=split`;
+		const rawBars = (await this.request(this.dataBaseUrl, path, { method: "GET" }, credentials))?.bars?.[sym] ?? [];
+		const duration = INTERVAL_MS[interval] ?? 864e5;
+		return rawBars.map((bar) => {
+			const openTime = new Date(bar.t).getTime();
+			return {
+				openTime,
+				open: Number(bar.o),
+				high: Number(bar.h),
+				low: Number(bar.l),
+				close: Number(bar.c),
+				volume: Number(bar.v),
+				closeTime: openTime + duration - 1
+			};
+		});
+	}
+	async listInstruments(credentials) {
+		const body = await this.request(this.tradingBaseUrl, "/assets?status=active&asset_class=us_equity", { method: "GET" }, credentials);
+		if (!Array.isArray(body)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", "Alpaca assets: invalid response shape");
+		const result = [];
+		for (const item of body) if (item && item.tradable && typeof item.symbol === "string" && item.symbol) result.push({
+			symbol: item.symbol,
+			...item.name ? { name: String(item.name) } : {}
+		});
+		return result;
+	}
+	async getOrderbook(symbol, credentials) {
+		const sym = normalizeUsSymbol(symbol);
+		const q = (await this.request(this.dataBaseUrl, `/stocks/${sym}/quotes/latest?feed=iex`, { method: "GET" }, credentials))?.quote;
+		const bids = [];
+		const asks = [];
+		if (typeof q?.bp === "number" && q.bp > 0) bids.push({
+			price: q.bp,
+			amount: Number(q.bs ?? 100)
+		});
+		if (typeof q?.ap === "number" && q.ap > 0) asks.push({
+			price: q.ap,
+			amount: Number(q.as ?? 100)
+		});
+		return {
+			symbol: sym,
+			bids,
+			asks,
+			timestamp: q?.t ? new Date(q.t).getTime() : Date.now()
+		};
+	}
+	async getBalance(credentials) {
+		const data = await this.request(this.tradingBaseUrl, "/account", { method: "GET" }, credentials);
+		const cash = Number(data.cash ?? data.buying_power ?? 0);
+		const total = Number(data.portfolio_value ?? cash);
+		return {
+			asset: String(data.currency ?? "USD"),
+			free: cash,
+			locked: Math.max(total - cash, 0)
+		};
+	}
+	async getPositions(credentials) {
+		const body = await this.request(this.tradingBaseUrl, "/positions", { method: "GET" }, credentials);
+		if (!Array.isArray(body)) return [];
+		return body.map((item) => {
+			const qty = Number(item.qty ?? 0);
+			return {
+				symbol: normalizeUsSymbol(String(item.symbol ?? "")),
+				side: qty >= 0 ? "long" : "short",
+				size: Math.abs(qty),
+				entryPrice: Number(item.avg_entry_price ?? 0),
+				markPrice: Number(item.current_price ?? 0),
+				unrealizedPnl: Number(item.unrealized_pl ?? 0),
+				timestamp: Date.now()
+			};
+		});
+	}
+	async listOpenOrders(credentials, symbol) {
+		const symQuery = symbol ? `&symbols=${normalizeUsSymbol(symbol)}` : "";
+		const body = await this.request(this.tradingBaseUrl, `/orders?status=open${symQuery}`, { method: "GET" }, credentials);
+		if (!Array.isArray(body)) return [];
+		return body.map((data) => {
+			const status = String(data.status ?? "new").toLowerCase() === "partially_filled" ? "partially_filled" : "new";
+			return {
+				id: String(data.id ?? ""),
+				symbol: normalizeUsSymbol(String(data.symbol ?? "")),
+				side: String(data.side ?? "buy").toLowerCase() === "sell" ? "sell" : "buy",
+				type: String(data.type ?? "market").toLowerCase() === "limit" ? "limit" : "market",
+				status,
+				price: data.limit_price !== void 0 ? Number(data.limit_price) : void 0,
+				quantity: Number(data.qty ?? 0),
+				filledQuantity: Number(data.filled_qty ?? 0),
+				dryRun: false,
+				timestamp: data.created_at ? new Date(String(data.created_at)).getTime() : Date.now()
+			};
+		});
+	}
+	async listTradeFills(credentials, symbol, limit = 50) {
+		const body = await this.request(this.tradingBaseUrl, `/account/activities/FILL?page_size=${Math.min(limit, 100)}`, { method: "GET" }, credentials);
+		if (!Array.isArray(body)) return [];
+		const sym = symbol ? normalizeUsSymbol(symbol) : void 0;
+		const fills = [];
+		for (const data of body) {
+			const itemSym = normalizeUsSymbol(String(data.symbol ?? ""));
+			if (sym && itemSym !== sym) continue;
+			fills.push({
+				id: String(data.id ?? ""),
+				symbol: itemSym,
+				side: String(data.side ?? "buy").toLowerCase() === "sell" ? "sell" : "buy",
+				price: Number(data.price ?? 0),
+				amount: Number(data.qty ?? 0),
+				timestamp: data.transaction_time ? new Date(String(data.transaction_time)).getTime() : Date.now()
+			});
+		}
+		return fills;
+	}
+	async placeOrder(credentials, req) {
+		const sym = normalizeUsSymbol(req.symbol);
+		const body = {
+			symbol: sym,
+			qty: String(req.quantity),
+			side: req.side.toLowerCase(),
+			type: req.type.toLowerCase(),
+			time_in_force: "gtc"
+		};
+		if (req.type === "LIMIT" && req.price !== void 0) body.limit_price = String(req.price);
+		const data = await this.request(this.tradingBaseUrl, "/orders", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		}, credentials);
+		return {
+			id: String(data.id ?? `alpaca-${Date.now()}`),
+			symbol: sym,
+			side: req.side.toLowerCase() === "sell" ? "sell" : "buy",
+			type: req.type.toLowerCase() === "limit" ? "limit" : "market",
+			quantity: req.quantity,
+			price: req.price,
+			status: String(data.status ?? "pending"),
+			dryRun: false,
+			timestamp: Date.now()
+		};
+	}
+	async cancelOrder(credentials, orderId) {
+		try {
+			await this.request(this.tradingBaseUrl, `/orders/${orderId}`, { method: "DELETE" }, credentials);
+		} catch (err) {
+			if (err instanceof TradingServiceError && err.code === "TRADING_UNSUPPORTED_SYMBOL") return;
+		}
+	}
+	async getOrder(credentials, orderId) {
+		const data = await this.request(this.tradingBaseUrl, `/orders/${orderId}`, { method: "GET" }, credentials);
+		const rawStatus = String(data.status ?? "new").toLowerCase();
+		const status = rawStatus === "filled" ? "filled" : rawStatus === "canceled" ? "canceled" : rawStatus === "partially_filled" ? "partially_filled" : "new";
+		return {
+			id: String(data.id ?? orderId),
+			symbol: normalizeUsSymbol(String(data.symbol ?? "")),
+			side: String(data.side ?? "buy").toLowerCase() === "sell" ? "sell" : "buy",
+			type: String(data.type ?? "market").toLowerCase() === "limit" ? "limit" : "market",
+			status,
+			price: data.limit_price !== void 0 ? Number(data.limit_price) : void 0,
+			quantity: Number(data.qty ?? 0),
+			filledQuantity: Number(data.filled_qty ?? 0),
+			dryRun: false,
+			timestamp: data.created_at ? new Date(String(data.created_at)).getTime() : Date.now()
+		};
+	}
+};
+//#endregion
+export { AlpacaRestClient, INTERVAL_TO_ALPACA, INTERVAL_VOCABULARY, TradingServiceError, normalizeUsSymbol };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dshtrading/connector-alpaca",
+  "description": "【模板】交易所连接器插件脚手架：Alpaca（alpaca）v2 插件骨架 —— 市场数据服务 + 交易服务 + 三态闸门 + BYOK 凭证 ref。生成器：node scripts/new-connector.mjs --slug <exchange>",
+  "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"
+    },
+    "./dataplane": {
+      "types": "./lib/dataplane.d.ts",
+      "default": "./lib/dataplane.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"
+  }
+}