@acosmi/sdk-ts 1.4.0 → 1.4.2

package/CHANGELOG.md

@@ -9,6 +9,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.4.2] — 2026-05-22
+
+> `src/` 目录按业务域重组（实施计划 `docs/audit/sdk-ts-directory-restructure-plan-2026-05-22`）。
+> **纯内部重组 + 开发工具 + 文档**——公共导出符号集合（295 个标识符）、`package.json`
+> `exports`、`dist/` 产物路径全部一字未变；`typecheck` / `lint` / `vitest`(140) / `build` /
+> `test:pack`（消费者视角 packed 产物）全绿。下游 `crabcode` / `crabclaw` / `csign` 零感知。
+
+### Changed
+
+- `src/` 从扁平 36 文件重组为按业务域分文件夹结构（`core/`、`shared/`、`auth/`、
+  `models/`、`billing/`、`skills/`、`notifications/`、`agent-runs/`、`compliance/`、
+  `support/`）；每域一个 barrel `index.ts`，根 `index.ts` 改为只从各域 barrel re-export。
+  `types.ts`（1341 行）、`scopes.ts`、`compliance-*.ts` 按域拆分。为后续平台控制面能力
+  预留 `apiClients/`、`tenant/`、`iam/`、`audit/`、`operations/`、`mcp/`、`gateway/`、
+  `certification/` 占位目录。
+
+### Added
+
+- TypeDoc API 参考文档：`npm run docs` 生成 `docs/api/`（Markdown）；接入 `release.yml`。
+- `examples/` 补 core / auth / agent-runs 三个示例（此前仅 compliance 三例）。
+
+### Removed
+
+- 死入口 `src/node.ts`——它既非 `tsup` 构建 entry 也不在 `package.json` `exports`，
+  从未被打包发布，删除对所有外部消费者零可观测影响。
+
+---
+
+## [1.4.1] — 2026-05-22
+
+### Added
+
+- **`Config.browserRefreshMode?: 'direct' | 'server-proxy' | 'none'`** 与
+  `refreshProxyURL` — 浏览器 Web OAuth token 刷新策略。默认 `direct` 保持既有行为；
+  `server-proxy` 可把刷新收口到同源 Route Handler，规避 OAuth issuer CORS 403；
+  `none` 用于产品自行处理过期登录态。新增错误码常量
+  `ErrOAuthCORSBlocked`、`ErrRefreshProxyFailed`、`ErrTokenExpired`。
+
+---
+
 ## [1.4.0] — 2026-05-21
 
 > csign `/login` Web OAuth 接入复核审计（`docs/audit/csign-login-oauth-audit-result-2026-05-21`）

package/README.md

@@ -6,9 +6,10 @@
 
 ## 状态
 
-- 端口源：[acosmi-sdk-go](https://github.com/acosmi/acosmi-sdk-go) v1.0.0（与 Go SDK 联动稳定测试版）
+- 主实现 / 事实标准：本 TS SDK 现为 Acosmi SDK 的主力实现。Go SDK [acosmi-sdk-go](https://github.com/acosmi/acosmi-sdk-go) 已暂停维护，待 TS 稳定后再从 TS 反向翻译补齐
 - 当前版本：**1.3.2**（`verifyEvidencePublic` 匿名公开验真收口、新增 `compliance:reports:write` scope、compliance 方法状态四档分级；`1.3.0` 新增 `client.compliance`、`complianceBaseURL`、合规域 types/errors/status/scopes、示例与文档；详见 [CHANGELOG](./CHANGELOG.md)）
 - 测试：发布前需通过 typecheck/lint/vitest/build/packed-tarball smoke (`npm run test:pack`)
+- API 参考文档：`npm run docs` 经 TypeDoc 生成到 `docs/api/`
 - 包链接：[npm](https://www.npmjs.com/package/@acosmi/sdk-ts) · [GitHub Releases](https://github.com/acosmi/sdk-ts/releases)
 
 ## 安装
@@ -76,7 +77,7 @@ for await (const ev of stream) {
 }
 ```
 
-`chatStreamWithUsage()` 返回带 usage/error/sources 标签的 AsyncIterable，便于聚合统计（详见 `src/client.ts`）。
+`chatStreamWithUsage()` 返回带 usage/error/sources 标签的 AsyncIterable，便于聚合统计（详见 `src/core/client.ts`）。
 
 ## Agent Runs
 
@@ -449,8 +450,11 @@ client.compliance.waitForProviderRequestTerminal(id, opts?)
 
 ### 示例
 
-`examples/` 下提供 3 份可直接运行的端到端示例，并随 npm 包一起发布：
+`examples/` 下提供可直接运行的端到端示例，并随 npm 包一起发布：
 
+- `examples/core-chat.ts` — Client 构造 / 配置 / 模型列举 / 同步与流式 chat
+- `examples/auth-oauth-flow.ts` — 手动 OAuth 2.1 PKCE 流程（discover / register / authorize / exchangeCode / refreshToken / token store）
+- `examples/agent-runs-stream.ts` — Agent Run Gateway 创建 / 流式消费 / 本地工具桥 / 产物下载
 - `examples/compliance-read.ts` — 只读 / public verify 流程
 - `examples/compliance-evidence-timestamp.ts` — hash-only evidence + timestamp + package 链路
 - `examples/compliance-envelope.ts` — envelope 创建 / 错误正确处理（step-up / gate closed）
@@ -481,6 +485,7 @@ npm run typecheck
 npm run lint
 npm test
 npm run build
+npm run docs    # 经 TypeDoc 生成 API 参考到 docs/api/
 ```
 
 ## 更新历史