@tier0/sdk-v2 0.9.8 → 0.9.9

package/CHANGELOG.md

@@ -1,12 +1,18 @@
 # Changelog
 
-## 0.9.8 (unreleased candidate)
+## 0.9.9 (2026-11-04)
+
+- Clarify workspace Agent/Personal versus App credential query permissions. Keep `namespace()` on OpenAPI; document `dataAppContext` followed by `recordFind` for App keys, with a typed example and 403 troubleshooting. No runtime authorization changes.
+
+- Add `client.uns.metadataPurge` for explicit archived Collection IDs. Preserve the asynchronous `accepted` / `jobId` receipt; use `jobs` to inspect completion and per-item results. Preview remains optional.
+- Document Collection deletion with retained records/samples and configuration references, followed by restore or permanent deletion.
+- Preserve App collection directories and Source lifecycle behavior, and pin the combined contract to Backend commit `064cdcdb688b18fb73295ac986380d84daa08188`.
+
+## 0.9.8 (2026-11-02)
 
 - Add `directoryPath` to App collection declarations and preserve it through compilation and first-use ensure. New collections use actual business directories; existing aliases retain their location.
 - Validate and freeze paths, and document known ISA-95 scopes, shared ancestors, and App/module directories within those scopes without forcing five levels.
-- Preserve the Source lifecycle changes from 0.9.7 and pin their combined contract with App collection directories to Backend commit `5c77d6f21e6332cb09e3212df9203eb01bf7f129`.
-
-This candidate is not published to npm; install the verified tarball for integration testing against that backend contract.
+- Preserve the Source lifecycle changes from the unpublished 0.9.7 candidate and pin their combined contract with App collection directories to Backend commit `5c77d6f21e6332cb09e3212df9203eb01bf7f129`.
 
 ## 0.9.7 (unreleased candidate)
 

package/README.md

@@ -2,7 +2,11 @@
 
 Tier0 云端统一 TypeScript / JavaScript SDK，数据管理与 App Stream 交互均使用 `@tier0/sdk-v2`。旧 SDK 不再作为依赖。
 
-`0.9.8` 候选版新增 App 集合业务目录声明 `directoryPath`，按已知业务范围创建或复用目录，已有集合保持位置。保留 `0.9.7` 的 Source 生命周期简化：创建后可直接使用，删除后停止后续使用；移除 `client.source.state.update`、启停能力与 `desiredState`。名称和描述修改无需影响确认，连接配置变更或删除存在引用时仍须确认；运行中的 Stream 可直接删除。该版本尚未发布 npm，验收使用下方安装包。
+`0.9.9` 新增 `client.uns.metadataPurge`，通过明确的已归档 Collection ID 提交永久删除，返回 `accepted` / `jobId` 并通过现有 `jobs` 查询逐项完成结果；`dryRun` 可选。集合删除保留 Record/Sample，支持恢复或继续永久清理。
+
+本版同时补齐 Agent / App 凭证的查询说明及 App 读取示例：`namespace()` 仍走 OpenAPI，App Key 使用 `dataAppContext` 和集合数据接口，服务端授权规则保持不变。
+
+保留 `0.9.8` 的 App 集合业务目录声明 `directoryPath`，按已知业务范围创建或复用目录，已有集合保持位置。Source 创建后可直接使用，删除后停止后续使用；不再提供 `client.source.state.update`、启停能力与 `desiredState`。名称和描述修改无需影响确认，连接配置变更或删除存在引用时仍须确认；运行中的 Stream 可直接删除。
 
 `0.9.3` 同步集合授权合同：授予既有集合访问权限时无需提供别名，并更新生成类型与使用说明。集合声明的 `name` / `alias` 要求保持不变。
 
@@ -22,13 +26,13 @@ Collection 声明必须同时提供业务名称 `name`（例如「生产工单
 
 ## 安装与初始化
 
-维护者发布前在本仓库运行 `npm ci`、`npm run check`，并验证生成的 `.tgz`。本分支的功能应使用检查通过的 `tier0-sdk-v2-0.9.8.tgz` 在业务项目中验证：
+安装正式版本：
 
 ```sh
-npm install /path/to/tier0-sdk-v2-0.9.8.tgz
+npm install @tier0/sdk-v2@0.9.9
 ```
 
-`0.9.8` 正式发布后再使用 `npm install @tier0/sdk-v2@0.9.8`。发布前，npm 的既有版本和 `next` 标签不代表本分支的完整功能。
+维护者发布前在本仓库运行 `npm ci`、`npm run check`，并验证生成的 `.tgz`。
 
 ```ts
 import { createClient } from '@tier0/sdk-v2';
@@ -74,6 +78,12 @@ const user = await tier0.system.whoami();
 
 不保留 UNS v1、旧 Flow、`getCurrentProjectId()`、project 成员查询或 `/gw/reload`。Workspace 成员不等于能使用某个 App 的成员，不可用前者在客户端猜测 App 权限。
 
+## SDK 方法与凭证权限
+
+同一 SDK 支持工作空间集成和 App 运行时，方法存在不代表当前凭证可调用。`client.uns.namespace()` 调用的是 `POST /openapi/v2/uns/namespace/query`，属于 OpenAPI；有相应权限且未绑定 App 的 Agent / Personal Key 可以使用，App Key 当前不能使用。App 应通过 `client.uns.dataAppContext({})` 获取可访问集合及结构，再用 `recordFind` 读取记录。`appCollectionsList` 也是管理接口，不能作为 App Key 的替代入口。
+
+SDK 不从 Key 前缀推断权限，也不在 403 后换凭证或回退内部接口。Agent 程序、SDK、MCP 都不能扩大所持凭证的权限。身份区别和排错见[命名空间查询与凭证](skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/namespace.md)，App 读取示例见[查询集合与记录](skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/read.md)。
+
 ## 本次接口退役
 
 HTTP 调用统一使用 `/openapi/v2`。21 个重复 UNS 公共入口及生成方法直接移除，没有旧路由回退；升级 SDK 时需同时部署对应后端。

package/dist/cjs/openapi/types.generated.d.ts

@@ -1018,7 +1018,7 @@ export interface components {
             /** @description 人读显示名（接替废弃的 source），≤100字符 */
             name?: string;
             /**
-             * @description 枚举 app/other/system，缺省 other；system=平台内部服务，usage_type=internal 的 API key 可用；工作区系统 Key 须同时声明 sender.id=uns-agent；其他情况 400，建信归 workspace 分组（System tab）
+             * @description 枚举 app/other/system，缺省 other；system 仅平台内部发送方（如 UNS Agent）可用；App 凭证不能使用 system，sender.type=app 时 sender.id 以凭证绑定的 App 为准；建信归 workspace 分组（System tab）
              * @default other
              * @enum {string}
              */