@acosmi/sdk-ts 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to `@acosmi/sdk-ts` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+---
+
+## [1.3.2] — 2026-05-20
+
+> 生产闭环实施计划（`Acosmi-Compliance-SDK-Csign-PC-CrabCode-生产闭环实施计划-2026-05-20`）
+> Phase 1 / Phase 5 / Phase 7 的 SDK 侧收口版本。
+
+### Added
+
+- **`ScopeComplianceReportsWrite`（`compliance:reports:write`）** — 新增第 13 个
+  细粒度 compliance scope，专用于创建出证报告。`complianceScopes()` 已包含该 scope，
+  字面量与 Go `DesktopOAuthScopes` / `ScopesSupported`、Java `ComplianceScopes`
+  三端一致。
+- **Compliance 方法状态分级** — `docs/compliance.md` 新增「Method Status」一节，
+  把每个 `client.compliance.*` 方法标注为 `production-ready` / `gated` /
+  `draft contract` / `internal-only` 四档；`gated`（`publishReport` / `signEnvelope` /
+  `createH5SigningUrl` / `approveSealApproval`）在服务端 step-up / 闸门未闭合前会
+  一致 fail-closed，SDK 不重试、不伪成功。`internal-only`（distribution billing /
+  provider raw / callback / CFCA 材料）不在 SDK 调用面。
+
+### Changed
+
+- **创建出证报告需要新 scope** — `client.compliance.createReport` 对应的服务端
+  scope 从 `compliance:reports:read` 切换到独立的写 scope
+  `compliance:reports:write`。调用 `createReport` 的应用必须在 `login()` 时申请
+  `ScopeComplianceReportsWrite`；在该 scope 发布前签发的旧 token 不含此 scope，
+  存量用户需重新走一次 OAuth 授权流程才能继续创建报告。`getReport` /
+  `downloadReport` 继续用 `compliance:reports:read`，`publishReport` 继续用
+  `compliance:reports:publish` + step-up（发布闸门不变）。
+- **`verifyEvidencePublic` 可匿名调用** — 公开验真不再要求先 `login()`：未持有
+  token 时 SDK 直接发匿名请求，不再抛 `not authorized, call login() first`；已持有
+  token 时附带 `Authorization` 以保留审计上下文。public 端点收到 `401` 不触发
+  `forceRefresh`、不做 refresh replay。
+
+### Safety
+
+- 公开验真匿名链路与认证写链路边界保持不变：写方法仍不自动 retry、401 不刷新重放；
+  匿名 public verify 不复用 `/api/v4`，走 `client.complianceURL(path)`。
+
+---
+
 ## [1.3.1] — 2026-05-20
 
 ### Changed

package/README.md

@@ -7,7 +7,7 @@
 ## 状态
 
 - 端口源：[acosmi-sdk-go](https://github.com/acosmi/acosmi-sdk-go) v1.0.0（与 Go SDK 联动稳定测试版）
-- 当前版本：**1.3.1**（修订 npm 包介绍与搜索关键词；`1.3.0` 新增 `client.compliance`、`complianceBaseURL`、合规域 types/errors/status/scopes、示例与文档；详见 [CHANGELOG](./CHANGELOG.md)）
+- 当前版本：**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`)
 - 包链接：[npm](https://www.npmjs.com/package/@acosmi/sdk-ts) · [GitHub Releases](https://github.com/acosmi/sdk-ts/releases)
 
@@ -382,6 +382,13 @@ const result = await client.compliance.verifyEvidencePublic({ evidenceNo: 'EV-00
 console.log(result.manifestOfflineVerify);
 ```
 
+### 公开 verify 匿名语义
+
+`verifyEvidencePublic` 可匿名调用：未 `login()` 时 SDK 直接发匿名请求，不会抛
+`not authorized, call login() first`。客户端已持有 token 时请求会附带 `Authorization`，
+便于后端保留审计上下文。与认证 GET 读不同，public verify 收到 `401` 不会触发
+`forceRefresh`、不做 refresh replay。
+
 ### 写操作幂等与 401 策略
 
 合规域写操作有别于普通 API：
@@ -418,7 +425,7 @@ client.compliance.waitForTimestampVerified(id, opts?)
 
 client.compliance.buildEvidencePackage(assetId, timestampTokenId?, options?)
 
-client.compliance.createReport(req, options?)
+client.compliance.createReport(req, options?)    // 需 compliance:reports:write
 client.compliance.getReport(id, signal?)
 client.compliance.publishReport(id, options?)    // step-up
 client.compliance.downloadReport(id, signal?)    // 离线复核 hash 视图
@@ -482,7 +489,8 @@ npm run build
 
 | 版本 | 状态 | 概要 |
 | --- | --- | --- |
-| 1.3.1 | 当前稳定版 | 修订 npm 包短介绍与搜索关键词，明确模型网关、Agent Run Gateway 与 Compliance 统一客户端定位。 |
+| 1.3.2 | 当前稳定版 | `verifyEvidencePublic` 匿名公开验真链路收口（未登录不抛 `not authorized`）；新增第 13 个 compliance scope `compliance:reports:write`（创建出证报告改用写 scope）；`docs/compliance.md` 新增方法状态四档分级（production-ready / gated / draft contract / internal-only）。 |
+| 1.3.1 | 稳定版 | 修订 npm 包短介绍与搜索关键词，明确模型网关、Agent Run Gateway 与 Compliance 统一客户端定位。 |
 | 1.3.0 | 稳定版 | 新增 compliance SDK client、base URL、types/errors/status/scopes、docs/examples/tests，并明确 idempotency/no-retry/no-401-replay 与 provider material 安全边界。 |
 | 1.2.0 | 稳定版 | 新增 `ManagedModel.inputModalities`、桌面视觉理解 sidecar capability 与 4 个 catalog helpers。 |
 | 1.1.0 | 稳定版 | 新增 SDK-facing `agentRuns` 网关客户端，覆盖 create/stream/cancel/get/artifacts/local-tool-result，并提供本地只读工具桥协议。 |

package/dist/browser/index.mjs

@@ -1439,6 +1439,7 @@ var ScopeComplianceSealApprovalRequest = "compliance:seal_approval:request";
 var ScopeComplianceSealApprovalApprove = "compliance:seal_approval:approve";
 var ScopeComplianceSealUseExecute = "compliance:seal_use:execute";
 var ScopeComplianceReportsRead = "compliance:reports:read";
+var ScopeComplianceReportsWrite = "compliance:reports:write";
 var ScopeComplianceReportsPublish = "compliance:reports:publish";
 function allScopes() {
   return [ScopeAI, ScopeSkills, ScopeAccount];
@@ -1456,6 +1457,7 @@ function complianceScopes() {
     ScopeComplianceSealApprovalApprove,
     ScopeComplianceSealUseExecute,
     ScopeComplianceReportsRead,
+    ScopeComplianceReportsWrite,
     ScopeComplianceReportsPublish
   ];
 }
@@ -3326,17 +3328,20 @@ var ComplianceClient = class {
   }
   /**
    * 公开 verify。隐私边界：返回字段不含 PII / 合同原文 / storage / provider raw。
-   * 服务端不要求 compliance scope（公开端点）；但 SDK 仍带上 token 以便审计。
+   *
+   * 匿名可调用：未 login 时走匿名请求，不会抛 `not authorized, call login() first`。
+   * 已 login / 已持有 token 时附带 `Authorization` 以保留审计上下文。public 端点不
+   * 应要求认证 — 收到 401 直接抛 HTTPError，不触发 `forceRefresh`，也不做 refresh
+   * replay。
    */
   verifyEvidencePublic(params, signal) {
     const q = new URLSearchParams();
     if (params.evidenceNo) q.set("evidenceNo", params.evidenceNo);
     if (params.publicVerifyCode) q.set("publicVerifyCode", params.publicVerifyCode);
     const qs = q.toString();
-    return this.read(
+    return this.publicRead(
       "GET",
       `/compliance/evidence/verify${qs ? "?" + qs : ""}`,
-      null,
       signal
     );
   }
@@ -3420,9 +3425,10 @@ var ComplianceClient = class {
   /**
    * 发布报告（写，step-up 必须）。
    *
-   * 缺少 step-up 时服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`（数值码
-   * 1031000013）。SDK 不会自动重试；调用方需要引导用户重新做 OAuth introspection 或
-   * 重新登录后再次调用本方法（使用同一 idempotency-key）。
+   * `@status gated` — step-up 闸门未闭合前服务端会一致返回
+   * `COMPLIANCE_STEP_UP_REQUIRED`（数值码 1031000013）。SDK 不会自动重试、不伪成功；
+   * 调用方需要引导用户重新做 OAuth introspection 或重新登录后再次调用本方法
+   *（使用同一 idempotency-key）。方法状态分级见 `docs/compliance.md` Method Status。
    */
   publishReport(id, opts = {}) {
     return this.write(
@@ -3469,7 +3475,7 @@ var ComplianceClient = class {
   /**
    * 正式签署（写，step-up 必须）。
    *
-   * 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
+   * `@status gated` — 服务端闸门关闭时会一致返回 `ENVELOPE_GATE_CLOSED` (1031004004)。
    * SDK 不重试、不伪成功；调用方应该将该错误展示为"功能未开放"。
    */
   signEnvelope(envelopeId, req, opts = {}) {
@@ -3483,7 +3489,7 @@ var ComplianceClient = class {
   /**
    * 创建 H5 签署短链（写，step-up 必须）。
    *
-   * 同上：服务端闸门关闭时 SDK 不重试。
+   * `@status gated` — 同 {@link signEnvelope}：服务端闸门关闭时 SDK 不重试、不伪成功。
    */
   createH5SigningUrl(envelopeId, req, opts = {}) {
     return this.write(
@@ -3505,6 +3511,13 @@ var ComplianceClient = class {
   // =========================================================================
   // Seal Approval
   // =========================================================================
+  /**
+   * 提交用印审批申请（写）。
+   *
+   * `@status production-ready` — 服务端以 `Idempotency-Key` + 业务请求指纹做重放保护：
+   * 同 key + 同请求 → 返回原审批 id；同 key + 不同请求 → 拒绝复用幂等键。强烈建议调用方
+   * 持久化 `idempotencyKey`，网络重试 / 任务恢复时复用，避免重复创建审批单。
+   */
   submitSealApproval(req, opts = {}) {
     return this.write(
       "POST",
@@ -3513,6 +3526,12 @@ var ComplianceClient = class {
       writeCtx(opts)
     );
   }
+  /**
+   * 审批通过用印申请（写，step-up 必须）。
+   *
+   * `@status gated` — step-up 未闭合前服务端会返回 `COMPLIANCE_STEP_UP_REQUIRED`。
+   * SDK 不重试、不伪成功。方法状态分级见 `docs/compliance.md` Method Status。
+   */
   approveSealApproval(id, query, opts = {}) {
     const q = new URLSearchParams();
     if (query.expiresAt) q.set("expiresAt", query.expiresAt);
@@ -3610,6 +3629,38 @@ var ComplianceClient = class {
       extraHeaders
     });
   }
+  /**
+   * 公开读路径：public verify。
+   *
+   * 与 {@link read} 的区别 — public 端点不应要求认证：
+   *   - 无 token 时匿名请求：ensureToken 抛 `not authorized` 会被吞掉，继续匿名发送。
+   *   - 有 token 时附带 `Authorization`，保留后端审计上下文。
+   *   - 不做 401 refresh replay：401 直接抛 HTTPError，不触发 `forceRefresh`。
+   *
+   * URL 仍走 `client.complianceURL(path)`，不复用 `/api/v4`；底层复用
+   * `client.doRequest`，不新增 fetch/axios 直连。
+   */
+  async publicRead(method, path, signal) {
+    let token = "";
+    try {
+      token = await this.client.ensureToken(signal);
+    } catch {
+    }
+    const url = this.client.complianceURL(path);
+    const headers = { Accept: "application/json" };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const resp = await this.client.doRequest({ method, url, headers }, signal);
+    if (resp.status < 200 || resp.status >= 300) {
+      const bodyBytes = resp.body ? await readLimited(resp.body, maxErrorBodySize) : new Uint8Array();
+      throw parseHTTPErrorWithHeader(resp.status, bodyBytes, resp.headers);
+    }
+    const text = await resp.text();
+    if (!text) return void 0;
+    const parsed = JSON.parse(text);
+    const bizErr = apiResponseBusinessError(parsed);
+    if (bizErr) throw bizErr;
+    return parsed.data;
+  }
   /**
    * 写路径：POST。
    * - 发送前 ensureToken 一次确保 token fresh。
@@ -5318,6 +5369,6 @@ Client.prototype.getBugReport = async function(bugID, signal) {
   return resp.data;
 };
 
-export { AgentRunStreamError, AgentRunsClient, AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, ComplianceClient, CompliancePollError, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OpenAIAdapter, OrderTerminalError, ProviderFormat, RateLimitError, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, classifyComplianceError, commerceScopes, complianceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, getAdapter, getAdapterForModel, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
+export { AgentRunStreamError, AgentRunsClient, AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, ComplianceClient, CompliancePollError, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OpenAIAdapter, OrderTerminalError, ProviderFormat, RateLimitError, ScopeAI, ScopeAccount, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, classifyComplianceError, commerceScopes, complianceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, getAdapter, getAdapterForModel, isBillingConfirmable, isComplianceBusinessError, isComplianceTerminalError, isSSLError, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map