@acosmi/sdk-ts 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.13.0] - 2026-08-01 — 邀请奖励窗口重置券 (window-reset credits)
+
+邀请奖励从"送 token"改为**送窗口重置次数**：被邀请人激活并达到用量门槛后给邀请人发一张重置券，每张可清空一次滚动窗口已用量（只动窗口用量原语，**月度额度池零触碰**）。SDK 加性新增总览查询与核销两个客户端方法，核销支持 `clientRequestId` 幂等键。全部加性，既有调用零改动。
+
+### Added
+
+- **`Client.getWindowResetSummary(signal?)`** — 查询当前用户窗口重置券总览（`GET /entitlements/window-reset/summary`）；返回 `WindowResetSummary`。`userId` 由网关从鉴权态解析，客户端永不传。用于个人中心邀请栏与 429 窗口限额弹窗展示「还剩几张券 + 最近到期时间 + 邀请进度」。
+- **`Client.redeemWindowReset({ clientRequestId?, signal? })`** — 消费一张重置券清空当前滚动窗口已用量（`POST /entitlements/window-reset/redeem`），返回 `{ remaining }`（扣减后剩余张数）。**幂等键语义**：同一 `clientRequestId` 重放不二次扣券（网关按该键返回首次结果），网络重试 / 用户连点必须复用同一 ID，换 ID = 换一次真实扣券；不传则不幂等。业务错按 SDK 惯例抛 `BusinessError`（message 含机器码）：`NO_AVAILABLE_CREDIT`（无可用券）/ `NO_WINDOW_USAGE`（当前窗口无已用量，不扣券）。
+- **`WindowResetSummary`（类型）** — `{ availableCount, nextExpireAt: string | null, totalGranted, totalUsed, qualifiedInvites, pendingInvites }`：可用券张数、可用券中最早到期时间（无券为 `null`）、累计发放 / 已用张数，以及邀请已达标 / 待达标数。
+
+## [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 一直解析为空的历史缺口。

package/README.md

@@ -582,6 +582,7 @@ const client = new Client({ serverURL: process.env.ACOSMI_SERVER_URL!, store: ne
 | **Tools**    | `listTools`, `getTool`                                                               |
 | **Wallet**   | `getWalletStats`, `getWalletTransactions`                                            |
 | **Entitlements** | `getBalance`, `getBalanceDetail`, `listEntitlements`, `listConsumeRecords`, `claimMonthlyFree`, `getByModel`, `listBuckets`, `listCoefficients`, `invalidateCoefficientCache` |
+| **Entitlements — 窗口重置券**（v2.13.0+） | `getWindowResetSummary`（邀请奖励券总览）, `redeemWindowReset`（核销一张券清空当前窗口已用量；`clientRequestId` 为幂等键） |
 | **Packages** | `listTokenPackages`, `getTokenPackageDetail`, `buyTokenPackage`, `getOrderStatus`, `listMyOrders`, `waitForPayment` |
 | **Notifications** | `listNotifications`, `getUnreadCount`, `markNotificationRead`, `markAllNotificationsRead`, `deleteNotification`, `registerDevice`, `unregisterDevice`, `listNotificationPreferences`, `updateNotificationPreference` |
 | **Notifications — WebSocket** | `connect`, `disconnect`, `isConnected` (实时推送订阅；浏览器走原生 WebSocket，Node 18-21 需自装 `ws`，Node 22+ 用原生) |

package/dist/browser/index.mjs

@@ -105,6 +105,19 @@ function isWindowLimitStreamError(err) {
   }
   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"() {
@@ -158,6 +171,12 @@ var init_errors = __esm({
       windowKind;
       /** 窗口限额场景: 预计恢复时间 (ISO-8601 UTC); 缺失为 undefined */
       windowResetAt;
+      /**
+       * [W1 2026-07-11 软限额] 窗口限额场景: 该 429 可否被用户「继续」开关豁免 —
+       * true = 5 小时软限额严格模式 (客户端可提示「继续任务」以消耗周配额继续);
+       * false/缺失 = 周窗/显式禁止/灰度关 (硬等待, 无豁免路径, 老网关不返回时为 undefined)。
+       */
+      windowOverridable;
       constructor(statusCode, opts = {}) {
         let msg;
         if (opts.type) {
@@ -178,6 +197,7 @@ var init_errors = __esm({
         this.errorCode = opts.errorCode;
         this.windowKind = opts.windowKind;
         this.windowResetAt = opts.windowResetAt;
+        this.windowOverridable = opts.windowOverridable;
       }
     };
     NetworkError = class extends Error {
@@ -1958,6 +1978,7 @@ function parseHTTPErrorWithHeader(statusCode, body, header) {
   let errorCode;
   let windowKind;
   let windowResetAt;
+  let windowOverridable;
   try {
     const obj = JSON.parse(bodyStr);
     if (obj && typeof obj === "object") {
@@ -1973,10 +1994,20 @@ function parseHTTPErrorWithHeader(statusCode, body, header) {
       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, errorCode, windowKind, windowResetAt });
+  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);
@@ -2765,6 +2796,64 @@ 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 };
+  }
+  /**
+   * [W-MEMBERSHIP 2026-08-01 邀请奖励] 查询当前用户窗口重置券总览 (v2.13+)。
+   *
+   * 重置券由邀请奖励发放 (被邀请人激活并达到用量门槛后计一次), 每张可清空一次滚动窗口已用量
+   * (见 redeemWindowReset)。userId 由网关从鉴权态解析, 客户端永不传。
+   * 用于个人中心邀请栏与 429 窗口限额弹窗展示"还剩几张券 + 最近到期时间 + 邀请进度"。
+   *
+   * @returns 券余量 / 最近到期 / 累计发放与使用 / 邀请已达标与待达标数。
+   */
+  async getWindowResetSummary(signal) {
+    const resp = await this.doJSON(
+      "GET",
+      "/entitlements/window-reset/summary",
+      null,
+      signal
+    );
+    return resp.data;
+  }
+  /**
+   * [W-MEMBERSHIP 2026-08-01 邀请奖励] 消费一张窗口重置券, 清空当前滚动窗口已用量 (v2.13+)。
+   *
+   * **幂等键语义**: 传 `clientRequestId` 时同一 ID 重放**不会二次扣券** — 网关按该键返回首次
+   * 结果 (`remaining` 与首次一致)。网络重试 / 用户连点必须**复用同一 ID**; 换 ID = 换一次真实
+   * 扣券。不传则不幂等, 每次调用都是一次真实扣券。
+   *
+   * 业务错 (信封 `code != 0`) 按 SDK 惯例抛 `BusinessError` (message 含机器码), 常见两种:
+   *   - `NO_AVAILABLE_CREDIT` — 无可用券 (未发放 / 已用尽 / 已过期)
+   *   - `NO_WINDOW_USAGE` — 当前窗口无已用量, 无可重置 (不扣券)
+   *
+   * @returns 扣减后剩余可用券张数 { remaining }。
+   */
+  async redeemWindowReset(opts) {
+    const resp = await this.doJSON(
+      "POST",
+      "/entitlements/window-reset/redeem",
+      { clientRequestId: opts?.clientRequestId },
+      opts?.signal
+    );
+    return { remaining: resp.data.remaining };
+  }
   /**
    * 查询单个模型的能力矩阵
    * 优先从 listModels 缓存读取, miss 时调用 listModels 刷新
@@ -7590,6 +7679,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, 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 };
+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