用途：帮助在 @alpacahq/alpaca-ts-alpha 这个 TypeScript SDK 上集成与开发，对接 Alpaca 的交易（Trading）与行情（Market Data）API。该资料是心智模型与惯用法地图，不替代完整 API 参考；具体方法名、参数、响应字段需查 README 的 ## API reference 或源码。
主要能力：客户端为两层门面。生成层 alpaca.<group>.<resource>.<method>(...) 始终可用，如 alpaca.trading.assets.getV2Assets()；人体工学层在其上叠加订单构建器、归一化行情访问器、分页与工作流助手，原始方法仍可调用。
使用方式：用 new Alpaca({ keyId, secret, paper: true }) 初始化，凭据可省略并从 APCA_API_KEY_ID、APCA_API_SECRET_KEY、APCA_API_OAUTH_TOKEN 解析。不要传单个 apiKey 字符串，需用 accessToken 或 auth.apiKeyAuth({ keyId, secret })。金额与数量是数字字符串，用 values 助手转换，精确计算保留字符串。时间周期用 TimeFrame.Day 或 timeFrame(15, TimeFrameUnit.Minute) 构建。订单优先用 alpaca.trading.orders 的 market、limit、stop、stopLimit、trailingStop、bracket、oco、oto 构建器。分页用 iterate* 惰性遍历、collect* 立即收集。REST 与流式共享同一 Bar/Trade/Quote 形状。错误为类型化 ApiError 及子类，需记录 err.requestId。
流式：WebSocket 客户端是类型化 EventEmitter，注册监听后 connect()，自动认证、退避重连与重订阅，如 alpaca.marketData.stockStream({ feed: "iex" })。OAuth-only 客户端无法开流。
限制：REST-only 构建从 @alpacahq/alpaca-ts-alpha/rest 导入，流工厂与 submitAndWait 在该入口抛错；边缘/浏览器运行时流式不可用。ESM 与 CJS 双包，勿在同一进程混用 import 与 require 以免 instanceof 比较到两份类。测试用 @alpacahq/alpaca-ts-alpha/testing 的 createMockAlpaca([...]) 做无网络测试。