@acosmi/sdk-ts 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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).
 
+## [2.12.0] - 2026-07-11 — 5 小时窗口软限额 (windowOverridable + 继续开关)
+
+后端把 5 小时窗口改为**软限额**：默认开启（到达 5h 仅提醒、自动继续消耗周配额），用户可关成严格模式（到达即等待恢复）；周窗维持硬限。429 响应体加性新增 `windowOverridable`（5h 严格模式=true，可续跑；周窗/显式禁止/灰度关=false，硬等待），额度总览加 `windowFiveHourContinueEnabled` 与 `WindowLimitStatus.overridable`，并新增设置「继续」开关的客户端方法。全部加性，向后兼容——旧字段/旧调用零改动，老网关不返回新字段时按硬等待处理。
+
+### Added
+
+- **`HTTPError.windowOverridable`** — 窗口限额 429 可否被用户「继续」开关豁免；`parseHTTPError` 解析顶层 `windowOverridable`。缺失（老网关）为 `undefined`，按硬等待处理。构造 options 加性扩展。
+- **`isContinuableWindowLimitError(err)`** — `HTTPError` type guard：`isWindowLimitError(err) && err.windowOverridable === true`，即 5 小时软限额严格模式（可通过 `setWindowContinuePreference(true)` 后重发放行）。周窗/显式禁止/灰度关/老网关均为 false。
+- **`getWindowLimitStreamDetails(err)`** — 从流式窗口限额产物（`StreamError` / `AgentRunStreamError` / 裸 payload）结构化读取 `{ windowKind, windowResetAt, windowOverridable }`；非窗口限额返回 null。
+- **`AgentRunErrorPayload.windowOverridable`** — agent-run SSE error 事件可选可豁免性字段（`omitempty`，false/缺失=硬等待）。
+- **`QuotaSummary.windowFiveHourContinueEnabled`（`boolean`）** — 用户 5h「继续」开关现值（true=软限额/默认；false=严格模式）；仅后端启用窗口限额时下发。
+- **`WindowLimitStatus.overridable`（`boolean`）** — 该窗此刻可否被开关豁免（5h 软限=true，周窗恒 false）。
+- **`Client.setWindowContinuePreference(enabled, { source?, signal? })`** — 设置当前用户 5h 软限额「继续」开关（`POST /entitlements/window-continue-pref`）；`userId` 由网关从鉴权态解析，客户端只传 `enabled` + 可选 `source`（web / crabcode-gui / crabcode-tui / dialog 审计用）。用于个人中心开关与 429 严格模式续跑。
+
+## [2.11.0] - 2026-07-09 — 窗口限额 (WINDOW_LIMIT_EXCEEDED) 结构化承接
+
+后端新增 5 小时 / 7 天滚动窗口 credit 限额：hold 失败返回 429 + 顶层 `errorCode:"WINDOW_LIMIT_EXCEEDED"` + `windowKind` / `windowResetAt`（`/chat` OpenAI 网关扁平形态与 `/anthropic` Anthropic 形态皆有），agent-run SSE error 事件与额度总览同步扩展。SDK 把机器码与窗口字段结构化透传，并顺带修复 `/chat` 网关错误形态 message 一直解析为空的历史缺口。
+
+### Added
+
+- **`HTTPError.errorCode` / `windowKind` / `windowResetAt`** — 后端业务机器码（响应体顶层 `errorCode`）与窗口限额字段（档位 `'FIVE_HOUR' | 'WEEKLY'`、预计恢复时间 ISO-8601 UTC）结构化上提；`parseHTTPError` 在任一错误形态下透传。构造 options 加性扩展，既有调用零改动。
+- **`isWindowLimitError(err)` / `isWindowLimitStreamError(err)`** — 窗口限额识别：前者是 `HTTPError` type guard（结构化 `errorCode` 优先，message/body 含 `WINDOW_LIMIT_EXCEEDED` 子串防御兜底，覆盖后端部署版本错位期）；后者面向流式产物（`StreamError` / `AgentRunStreamError` / 裸 error payload，`code === 'window_limit_exceeded'` 优先 + 同样的子串兜底）。普通 429 rate limit 不误判。
+- **`AgentRunErrorPayload.windowKind` / `windowResetAt`** — agent-run SSE error 事件可选窗口字段，事件解析（`normalizeError` 白名单 pick）透传，camelCase 契约主拼写 + snake_case 兼容兜底。
+- **`QuotaSummary.windowLimits`（`WindowLimitStatus[]`）** — 额度总览新增滚动窗口限额状态：`{ kind: 'FIVE_HOUR' | 'WEEKLY', limitCredits, usedCredits, resetAt?: string | null }`；后端未启用窗口限额时字段整个缺失，向后兼容。
+
+### Fixed
+
+- **`/chat` OpenAI 网关错误形态 message 丢失** — `parseHTTPError` 此前只解析嵌套 `{error:{type,message}}` 形态；网关顶层扁平形态 `{code:429,message:"..."}` 的 message 恒为空、机器码只存活在 body 原串。现补顶层 `message` 解析（该形态无 error.type 来源，`type` 留空），非 JSON body / 空 body 行为逐字节不变。
+
 ## [2.10.0] - 2026-06-20 — 多模态向量 / 重排序 (qwen3-vl-embedding / qwen3-vl-rerank)
 
 向量与重排序端点扩展为**多模态**（text / image / **video**），对接 DashScope `qwen3-vl-embedding`（多模态向量端点）与 `qwen3-vl-rerank`（原生 rerank 端点 + 多模态 content）。面向自建搜索引擎的图文 / 视频检索场景。计费口径不变（`total_tokens` 套 input 费率），上游模型名仍由管理员后台自填，不在 SDK / 网关硬编码。

package/dist/browser/index.mjs

@@ -91,7 +91,34 @@ var init_types = __esm({
 });
 
 // src/shared/errors.ts
-var RateLimitError, BusinessError, OrderTerminalError, ModelNotFoundError, HTTPError, NetworkError, StreamError;
+function isWindowLimitError(err) {
+  if (!(err instanceof HTTPError)) return false;
+  if (err.errorCode === windowLimitErrorCode) return true;
+  return err.message.includes(windowLimitErrorCode) || err.body.includes(windowLimitErrorCode);
+}
+function isWindowLimitStreamError(err) {
+  if (err == null || typeof err !== "object") return false;
+  const e = err;
+  if (e.code === windowLimitStreamCode) return true;
+  for (const field of [e.message, e.userMessage, e.rawError]) {
+    if (typeof field === "string" && field.includes(windowLimitErrorCode)) return true;
+  }
+  return false;
+}
+function isContinuableWindowLimitError(err) {
+  return isWindowLimitError(err) && err.windowOverridable === true;
+}
+function getWindowLimitStreamDetails(err) {
+  if (!isWindowLimitStreamError(err)) return null;
+  const e = err ?? {};
+  const kind = e.windowKind === "FIVE_HOUR" || e.windowKind === "WEEKLY" ? e.windowKind : void 0;
+  return {
+    windowKind: kind,
+    windowResetAt: typeof e.windowResetAt === "string" ? e.windowResetAt : void 0,
+    windowOverridable: typeof e.windowOverridable === "boolean" ? e.windowOverridable : void 0
+  };
+}
+var RateLimitError, BusinessError, OrderTerminalError, ModelNotFoundError, HTTPError, NetworkError, StreamError, windowLimitErrorCode, windowLimitStreamCode;
 var init_errors = __esm({
   "src/shared/errors.ts"() {
     RateLimitError = class extends Error {
@@ -138,6 +165,18 @@ var init_errors = __esm({
       retryAfter;
       /** 原始响应体 (截断到 maxErrorBodySize) */
       body;
+      /** 后端业务机器码 (响应体顶层 errorCode, e.g. "WINDOW_LIMIT_EXCEEDED"); 缺失为 undefined */
+      errorCode;
+      /** 窗口限额场景: 触发的滚动窗口档位 (FIVE_HOUR = 5 小时 / WEEKLY = 7 天); 缺失为 undefined */
+      windowKind;
+      /** 窗口限额场景: 预计恢复时间 (ISO-8601 UTC); 缺失为 undefined */
+      windowResetAt;
+      /**
+       * [W1 2026-07-11 软限额] 窗口限额场景: 该 429 可否被用户「继续」开关豁免 —
+       * true = 5 小时软限额严格模式 (客户端可提示「继续任务」以消耗周配额继续);
+       * false/缺失 = 周窗/显式禁止/灰度关 (硬等待, 无豁免路径, 老网关不返回时为 undefined)。
+       */
+      windowOverridable;
       constructor(statusCode, opts = {}) {
         let msg;
         if (opts.type) {
@@ -155,6 +194,10 @@ var init_errors = __esm({
         this.type = opts.type ?? "";
         this.retryAfter = opts.retryAfter ?? 0;
         this.body = opts.body ?? "";
+        this.errorCode = opts.errorCode;
+        this.windowKind = opts.windowKind;
+        this.windowResetAt = opts.windowResetAt;
+        this.windowOverridable = opts.windowOverridable;
       }
     };
     NetworkError = class extends Error {
@@ -210,6 +253,8 @@ var init_errors = __esm({
         this.retryable = retryable;
       }
     };
+    windowLimitErrorCode = "WINDOW_LIMIT_EXCEEDED";
+    windowLimitStreamCode = "window_limit_exceeded";
   }
 });
 
@@ -1930,19 +1975,39 @@ function parseHTTPErrorWithHeader(statusCode, body, header) {
   }
   let type = "";
   let message = "";
+  let errorCode;
+  let windowKind;
+  let windowResetAt;
+  let windowOverridable;
   try {
     const obj = JSON.parse(bodyStr);
     if (obj && typeof obj === "object") {
-      const errObj = obj.error;
+      const top = obj;
+      const errObj = top.error;
       if (errObj && typeof errObj === "object") {
         const e = errObj;
         if (typeof e.message === "string") message = e.message;
         if (typeof e.type === "string") type = e.type;
+      } else if (typeof top.message === "string") {
+        message = top.message;
       }
+      if (typeof top.errorCode === "string") errorCode = top.errorCode;
+      if (top.windowKind === "FIVE_HOUR" || top.windowKind === "WEEKLY") windowKind = top.windowKind;
+      if (typeof top.windowResetAt === "string") windowResetAt = top.windowResetAt;
+      if (typeof top.windowOverridable === "boolean") windowOverridable = top.windowOverridable;
     }
   } catch {
   }
-  return new HTTPError(statusCode, { type, message, retryAfter, body: bodyStr });
+  return new HTTPError(statusCode, {
+    type,
+    message,
+    retryAfter,
+    body: bodyStr,
+    errorCode,
+    windowKind,
+    windowResetAt,
+    windowOverridable
+  });
 }
 function classifyTransport(op, urlStr, err) {
   const ne = new NetworkError(op, urlStr, err);
@@ -2731,6 +2796,24 @@ var Client = class _Client {
     );
     return resp.data;
   }
+  /**
+   * [W1 2026-07-11 软限额] 设置当前用户 5 小时窗口软限额「继续」开关 (v2.12+)。
+   *
+   * enabled=true = 软限额 (到达 5h 后继续消耗周配额, 默认); false = 严格模式 (到达即等待逐步恢复)。
+   * userId 由网关从鉴权态解析 (客户端永不传), 故只需 enabled + 可选 source (审计: web /
+   * crabcode-gui / crabcode-tui / dialog)。用于个人中心开关、429 严格模式「重新开启继续」续跑。
+   *
+   * @returns 网关回显的新状态 { enabled }。
+   */
+  async setWindowContinuePreference(enabled, opts) {
+    const resp = await this.doJSON(
+      "POST",
+      "/entitlements/window-continue-pref",
+      { enabled, source: opts?.source },
+      opts?.signal
+    );
+    return { enabled: resp.data.enabled };
+  }
   /**
    * 查询单个模型的能力矩阵
    * 优先从 listModels 缓存读取, miss 时调用 listModels 刷新
@@ -5636,6 +5719,9 @@ function normalizeError(value) {
     message: stringField(value, "message", "error") || "agent run failed",
     stage: optionalStringField(value, "stage"),
     retryable: typeof value.retryable === "boolean" ? value.retryable : void 0,
+    // 窗口限额扩展 (code="window_limit_exceeded"): 契约 wire 为 camelCase, 蛇形兼容兜底。
+    windowKind: optionalStringField(value, "windowKind", "window_kind"),
+    windowResetAt: optionalStringField(value, "windowResetAt", "window_reset_at"),
     raw: value
   };
 }
@@ -7553,6 +7639,6 @@ function brandCredential(c) {
   return c;
 }
 
-export { AGENT_RUN_META_TITLE, AGENT_RUN_META_WORKSPACE, ALL_INTEGRATION_STATUS, ALL_PLATFORMS, ALL_REGIONS, AgentRunStreamError, AgentRunsClient, AnthropicAdapter, AudienceEnum, BillingModeEnum, BucketClassCommercial, BucketClassGeneric, BusinessError, ChatBridgeClient, Client, ComplianceClient, CompliancePollError, CrabCodeByokClient, DEFAULT_API_TIMEOUT_MS, DEFAULT_GATEWAY_BASE_URL, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrOAuthCORSBlocked, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRefreshProxyFailed, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, ErrTokenExpired, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, IdempotencyKeyHeader, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OAuthTokenEndpointError, OpenAIAdapter, OrderTerminalError, ProductFamilyEnum, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, RegionScopeEnum, ScopeAI, ScopeAccount, ScopeChatBridge, ScopeChatBridgeRead, ScopeChatBridgeRotate, ScopeChatBridgeWrite, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeRemoteControl, ScopeRemoteControlAgentRun, ScopeRemoteControlPermissionResponse, ScopeRemoteControlSessionControl, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, asCredentialRef, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, chatBridgeScopes, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, isBillingConfirmable, isChannelInboundEvent, isComplianceBusinessError, isComplianceTerminalError, isIntegrationStatus, isInvalidGrantError, isPlatform, isRegion, isSSECommentLine, isSSLError, isTerminalRemoteEvent, isValidTokenSet, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, normalizeGatewayBaseURL, normalizeOverrideBaseURL, parseNotificationEvent, parseRemoteControlEvent, parseSettlement, parseSourcesEvent, refreshToken, register, registerWebOAuthClient, remoteControlScopes, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge, validateEndUserId };
+export { AGENT_RUN_META_TITLE, AGENT_RUN_META_WORKSPACE, ALL_INTEGRATION_STATUS, ALL_PLATFORMS, ALL_REGIONS, AgentRunStreamError, AgentRunsClient, AnthropicAdapter, AudienceEnum, BillingModeEnum, BucketClassCommercial, BucketClassGeneric, BusinessError, ChatBridgeClient, Client, ComplianceClient, CompliancePollError, CrabCodeByokClient, DEFAULT_API_TIMEOUT_MS, DEFAULT_GATEWAY_BASE_URL, LocalStorageTokenStore as DefaultBrowserTokenStore, DefaultRetryPolicy, ErrAuthDenied, ErrBillingCallbackCannotCommit, ErrBillingCommitRequiresLocalVerify, ErrBillingS2sForbidden, ErrBrowserOpen, ErrComplianceStepUpRequired, ErrDiscovery, ErrEnvelopeGateClosed, ErrOAuthCORSBlocked, ErrProviderNotConfigured, ErrProviderUnknownNoRetry, ErrRefreshProxyFailed, ErrRegistration, ErrSSLProxy, ErrSealApprovalContractHashMismatch, ErrSealApprovalExpired, ErrSealApprovalLocationMismatch, ErrSealApprovalNonceUsed, ErrSealApprovalNotApproved, ErrSealApprovalSealMismatch, ErrSealApprovalTransactorMismatch, ErrSealUseAlreadyConsumed, ErrStateMismatch, ErrTimeout, ErrTokenExchange, ErrTokenExpired, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, IdempotencyKeyHeader, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OAuthTokenEndpointError, OpenAIAdapter, OrderTerminalError, ProductFamilyEnum, ProviderFormat, RETRY_ADVICE_REASONS, RateLimitError, RegionScopeEnum, ScopeAI, ScopeAccount, ScopeChatBridge, ScopeChatBridgeRead, ScopeChatBridgeRotate, ScopeChatBridgeWrite, ScopeComplianceContractSigningRead, ScopeComplianceContractSigningWrite, ScopeComplianceContractTemplateRead, ScopeComplianceContractTemplateWrite, ScopeComplianceEvidenceRead, ScopeComplianceEvidenceWrite, ScopeComplianceReportsPublish, ScopeComplianceReportsRead, ScopeComplianceReportsWrite, ScopeComplianceSealApprovalApprove, ScopeComplianceSealApprovalRequest, ScopeComplianceSealManage, ScopeComplianceSealUseExecute, ScopeComplianceTimestampIssue, ScopeComplianceTimestampVerify, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeRemoteControl, ScopeRemoteControlAgentRun, ScopeRemoteControlPermissionResponse, ScopeRemoteControlSessionControl, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, asCredentialRef, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, chatBridgeScopes, classifyComplianceError, commerceScopes, completeWebAuthorizationRequest, complianceErrorToRetryAdvice, complianceScopes, computeBackoff, createWebAuthorizationRequest, defaultRetryable, defaultSafeToRetry, discover, discoverWebOAuthMetadata, discoverWithProfile, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, findDesktopVisualUnderstandingModel, findFirstModelByInputModality, generateState, getAdapter, getAdapterForModel, getWindowLimitStreamDetails, isBillingConfirmable, isChannelInboundEvent, isComplianceBusinessError, isComplianceTerminalError, isContinuableWindowLimitError, isIntegrationStatus, isInvalidGrantError, isPlatform, isRegion, isSSECommentLine, isSSLError, isTerminalRemoteEvent, isValidTokenSet, isWindowLimitError, isWindowLimitStreamError, maxEndUserIdLength, modelScopes, modelSupportsImageInput, modelSupportsInputModality, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, normalizeGatewayBaseURL, normalizeOverrideBaseURL, parseNotificationEvent, parseRemoteControlEvent, parseSettlement, parseSourcesEvent, refreshToken, register, registerWebOAuthClient, remoteControlScopes, retryReasonForComplianceKey, retryReasonForOAuthError, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge, validateEndUserId };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map