@reachv2/sdk 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @reachv2/sdk
 
-Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer SDK（crm 域，18 资源）与 aiops-saas SDK（social 域，5 资源）合并而来（P2.4）。一个客户端覆盖客服 / 销售引导、社群维护与社媒运营全部资源。
+Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer SDK（crm 域，18 资源）与 aiops-saas SDK（social 域，5 资源）合并而来（P2.4），现统一为 **27 个资源类 / 203 个资源方法**。一个客户端覆盖客服 / 销售引导、社群维护与社媒运营全部资源（含效果追踪、SEO/GEO、内容规则与数据源）。
 
 - 运行时：Node.js >= 18（ESM）
 - 类型：完整 TypeScript 类型定义（自带 `dist/index.d.ts`）
@@ -8,7 +8,7 @@ Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer
 
 ## 文档
 
-- **[API Reference](docs/API-REFERENCE.md)**（P2.6，v0.2.0 扩展统一租户）：全部 27 个资源类 + `ReachClient` 共 **203 个资源方法**（另含 `ReachClient.setToken` / `request`）的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 `sdk/src` 源码一一对应。
+- **[API Reference](docs/API-REFERENCE.md)**（P2.6，v0.3.0 补 P-REACH 四域）：全部 27 个资源类 + `ReachClient` 共 **203 个资源方法**（另含 `ReachClient.setToken` / `request`）的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 `sdk/src` 源码一一对应。
 
 ## 安装
 
@@ -42,21 +42,25 @@ const { reply, transaction } = await client.agents.chat("bot-xxx", {
 const post = await client.content.generate("AI trends", "twitter", "professional");
 ```
 
-### 方式二：JWT 登录（需数学验证码）
+### 方式二：JWT 登录（邮箱 + 密码，图形验证码可选）
 
 ```ts
 const client = new ReachClient({ baseUrl: "https://reach.codes", apiKey: "reach-xxx" });
 
-const { token, svg } = await client.auth.getCaptcha();
-const svgText = Buffer.from(svg.replace(/^data:image\/svg\+xml;base64,/, ""), "base64").toString("utf-8");
-const m = svgText.match(/(\d+)\s*([+-])\s*(\d+)/)!;
+// 1) 取图形验证码（算式图）：{ captchaId, image, expiresIn }，image 为 data:image/svg+xml;base64
+const { captchaId, image } = await client.auth.getCaptcha();
+const svg = Buffer.from(image.replace(/^data:image\/svg\+xml;base64,/, ""), "base64").toString("utf-8");
+const m = svg.match(/(\d+)\s*([+-])\s*(\d+)/)!;
 const answer = m[2] === "+" ? Number(m[1]) + Number(m[3]) : Number(m[1]) - Number(m[3]);
 
-const { token: jwt } = await client.auth.login("username", "password", { token, answer });
-client.setToken(jwt); // SDK 不会自动接线，需手动 setToken 切换为 JWT 模式
+// 2) 登录：返回 { accessToken, refreshToken, account }
+const { accessToken } = await client.auth.login("user@example.com", "password", { token: captchaId, answer });
+client.setToken(accessToken); // SDK 不会自动接线，需手动 setToken 切换为 JWT 模式
 ```
 
-> **JWT 续期约定**：`login` 签发 7 天有效 JWT 且无 refresh 机制，请提前 1 天重新登录并 `setToken`。
+> **JWT 续期**：`accessToken` 默认 2h（`JWT_ACCESS_TTL`），`refreshToken` 30d（`JWT_REFRESH_TTL_SEC`）。
+> SDK 未封装 refresh；过期后用 `await client.request("POST", "/api/auth/refresh", { refreshToken })` 轮换并 `setToken`。
+> 启用 MFA 的账户 `login` 返回 `{ mfaRequired: true, account }`（不带 token），需携带 `mfaCode`（TOTP/恢复码）重试。
 
 ## 认证方式
 
@@ -73,10 +77,12 @@ client.setToken(jwt); // SDK 不会自动接线，需手动 setToken 切换为 J
 Reach 将自身能力以 **MCP（Model Context Protocol）** 形式对外开放（Streamable HTTP，路径 `/mcp`），
 让支持 MCP 的客户端（Claude Desktop / Cursor / 自研 Agent）可直接调用 crm + social 域工具。
 
-- 端点：`https://reach.codes/mcp`（探活：`GET https://reach.codes/mcp/health`）
-- 鉴权：`X-API-Key: reach-xxx` 或 `Authorization: Bearer sk-xxx`（复用 REST API Key，租户隔离由此 Key 决定）
-- 权限：MCP 工具调用为写操作，API Key 需含 `write` / `all` scope
-- 工具域：按平台配置白名单裁剪（当前 `crm` / `social`），`tools/list` 返回实际可用集合
+- 端点：`https://reach.codes/mcp`（探活：`GET https://reach.codes/mcp/health`，返回 `{ status, tools, publicMode, domains }`）
+- 鉴权：`X-API-Key: reach-xxx` 或 `Authorization: Bearer <key>`（复用 REST API Key，租户隔离由此 Key 决定）
+- 权限（读 / 写门禁）：只读 Key（scope 不含 `write` / `all` / `*`）**只能调用读工具**（工具名按 `_` 分词命中
+  `list` / `get` / `status` / `query` / `summary` / `check` / `history` / `usage` … 即视为读，未命中一律按写拒绝）；
+  写工具需 `write` / `all` / `*` scope，否则 `tools/call` 返回 JSON-RPC `-32001 requires a write-scoped API key`
+- 工具规模：**269**（crm 87 + social 182），按域白名单裁剪（当前 `crm` / `social`），`tools/list` 返回实际可用集合
 
 会话按 MCP Streamable HTTP 规范：先 `initialize` 取得 `mcp-session-id`，
 再发 `notifications/initialized`，之后 `tools/call`，结束时 `DELETE` 会话。
@@ -158,7 +164,7 @@ const client = new ReachClient({
 | `client.tts` | 文本转语音（synthesize/voices/history） | Server |
 | `client.accounts` | 社媒账号矩阵（list/connect） | Server |
 
-### social 域 — P-REACH（效果 / SEO-GEO / 内容规则 / 数据源，v0.2.0 新增）
+### social 域 — P-REACH（效果 / SEO-GEO / 内容规则 / 数据源，v0.3.0 新增）
 
 | 资源 | 主要能力 | API 域 |
 |------|----------|--------|
@@ -185,18 +191,25 @@ const client = new ReachClient({
 ```bash
 cd sdk
 npm install
-npm run build     # tsc → dist
-npm test          # node --test test/（冒烟：导出 + 资源方法面）
+npm run build     # clean + tsc → dist
+npm test          # node --test，覆盖 test/*.test.mjs
 ```
 
+| 测试文件 | 覆盖 |
+|----------|------|
+| `test/client.test.mjs` | ReachClient 核心行为：构造校验（`MISSING_AUTH`）、认证 Header、双 base 路由、body 序列化、错误语义 |
+| `test/resources.test.mjs` | **全量** 27 资源类 203 方法的 method / path / body 断言（要求每个方法至少被一条用例覆盖） |
+| `test/smoke.test.mjs` | 导出面 + 资源方法面快照 |
+
+> 测试跑 **`dist/` 产物**，改完 `src/` 必须先 `npm run build`。
+
 ## 发布流程（维护者）
 
 ```bash
 cd sdk
 npm version <minor> --no-git-tag-version   # 小版本递增，紧贴 API 变更
-npm run build                              # tsc → dist
-npm pack                                   # 本地验证发布产物（含 dist + README）
-npm publish                                # token 在 ~/.npmrc（reachv2 组织）
+npm publish                                # prepublishOnly 自动执行 build + test；产物仅含 dist（package.json files 字段）
+# 可选：npm pack 本地检查 tarball 内容
 cd .. && git add sdk/package.json sdk/package-lock.json
 git commit -m "chore(sdk): 发布 @reachv2/sdk@<version>"
 ```

package/dist/index.d.ts

@@ -27,5 +27,5 @@ export { DataSourcesResource } from "./resources/data-sources.js";
 export { HealthResource } from "./resources/health.js";
 export { TenantsResource } from "./resources/tenants.js";
 export { TeamResource } from "./resources/team.js";
-export type { ReachClientConfig, BotType, AgentType, BotStatus, ChannelType, ChannelStatus, KnowledgeStatus, Pagination, PaginatedResponse, Project, ProjectCreateParams, ProjectUpdateParams, TransactionBotConfig, Bot, BotStats, BotCreateParams, BotUpdateParams, KnowledgeDoc, KnowledgeRecommendation, Channel, ChannelConfigureParams, Conversation, Message, ChatParams, ChatResponse, ChatToolDefinition, ChatToolFunction, DashboardData, BotMetrics, TxIntent, TxStep, PreparedTransaction, ContractInfo, ContractMethod, SimulationResult, DecodedCalldata, ProtocolSummary, ProtocolRegistryEntry, ChainDeployment, ProtocolAction, ParamHint, WalletChallenge, WalletLoginParams, AuthResult, CaptchaResponse, CaptchaAnswer, AgentXAgent, AgentXAgentDetail, AgentXMarketplaceResult, AgentXSubscriptionPlans, AgentXSubscriptionCheck, AgentXAgentContext, AgentXPublishParams, AgentXPublishResult, AgentXSkill, AgentXSkillCreateParams, AgentXAgentStatus, AgentXAgentUsage, AgentXSubscriptionDetail, AgentXSubscriptionList, ServerChatParams, ServerChatResponse, ChatUsage, ChatUsageSummary, AgentSummary, AgentListResult, AgentListParams, AgentChainInfo, AgentActionType, AgentCapabilities, AgentChatParams, AgentChatResult, LightRAGKeyInfo, LightRAGDocumentParams, LightRAGQueryParams, LightRAGQueryResult, LightRAGBatchItem, LightRAGBatchError, LightRAGBatchResult, GlobalAnalytics, AdminDashboard, AdminMerchant, AdminMerchantDetail, AdminBillingRecord, AdminCreateBillingParams, LlmSettings, LlmUpdateParams, ConversationTask, ConversationTaskStatus, ConversationSession, ConversationCapabilities, ConversationMessage, OrchestrationTaskParams, OrchestrateParams, OrchestratedTaskResult, OrchestrateResult, ScheduledTask, ScheduledTaskStatus, ScheduledTaskTriggerType, MonitorConnectorKind, EnterpriseDoc, MonitorConnector, MonitorEvent, MerchantAbi, MerchantAbiCreateParams, SimpleResult, TenantType, TenantMemberRole, TenantMemberStatus, Tenant, TenantMemberInfo, TenantInvite, PublicInviteInfo, InviteAcceptResult, MemberRoleUpdateResult, TransferOwnerResult, TeamMemberItem, TeamInviteResult, HealthInfo, } from "./types.js";
+export type { ReachClientConfig, BotType, AgentType, BotStatus, ChannelType, ChannelStatus, KnowledgeStatus, Pagination, PaginatedResponse, Project, ProjectCreateParams, ProjectUpdateParams, TransactionBotConfig, Bot, BotStats, BotCreateParams, BotUpdateParams, KnowledgeDoc, KnowledgeRecommendation, Channel, ChannelConfigureParams, Conversation, Message, ChatParams, ChatResponse, ChatToolDefinition, ChatToolFunction, DashboardData, BotMetrics, TxIntent, TxStep, PreparedTransaction, ContractInfo, ContractMethod, SimulationResult, DecodedCalldata, ProtocolSummary, ProtocolRegistryEntry, ChainDeployment, ProtocolAction, ParamHint, WalletNonce, WalletLoginParams, AuthAccount, AuthResult, MfaRequiredResult, CaptchaResponse, CaptchaAnswer, AgentXAgent, AgentXAgentDetail, AgentXMarketplaceResult, AgentXSubscriptionPlans, AgentXSubscriptionCheck, AgentXAgentContext, AgentXPublishParams, AgentXPublishResult, AgentXSkill, AgentXSkillCreateParams, AgentXAgentStatus, AgentXAgentUsage, AgentXSubscriptionDetail, AgentXSubscriptionList, ServerChatParams, ServerChatResponse, ChatUsage, ChatUsageSummary, AgentSummary, AgentListResult, AgentListParams, AgentChainInfo, AgentActionType, AgentCapabilities, AgentChatParams, AgentChatResult, LightRAGKeyInfo, LightRAGDocumentParams, LightRAGQueryParams, LightRAGQueryResult, LightRAGBatchItem, LightRAGBatchError, LightRAGBatchResult, GlobalAnalytics, AdminDashboard, AdminMerchant, AdminMerchantDetail, AdminBillingRecord, AdminCreateBillingParams, LlmSettings, LlmUpdateParams, ConversationTask, ConversationTaskStatus, ConversationSession, ConversationCapabilities, ConversationMessage, OrchestrationTaskParams, OrchestrateParams, OrchestratedTaskResult, OrchestrateResult, ScheduledTask, ScheduledTaskStatus, ScheduledTaskTriggerType, MonitorConnectorKind, EnterpriseDoc, MonitorConnector, MonitorEvent, MerchantAbi, MerchantAbiCreateParams, SimpleResult, TenantType, TenantMemberRole, TenantMemberStatus, Tenant, TenantMemberInfo, TenantInvite, PublicInviteInfo, InviteAcceptResult, MemberRoleUpdateResult, TransferOwnerResult, TeamMemberItem, TeamInviteResult, HealthInfo, } from "./types.js";
 export type { ApiKeyInfo, ApiKeyCreated } from "./resources/api-key.js";

package/dist/resources/auth.d.ts

@@ -1,11 +1,14 @@
-import { RequestMethod, WalletChallenge, WalletLoginParams, AuthResult, CaptchaResponse, CaptchaAnswer } from "../types.js";
+import { RequestMethod, WalletNonce, WalletLoginParams, AuthResult, CaptchaResponse, CaptchaAnswer } from "../types.js";
 type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
 export declare class AuthResource {
     private request;
     constructor(request: RequestFn);
-    /** 获取钱包签名挑战 */
-    getChallenge(walletAddress: string): Promise<WalletChallenge>;
-    /** 钱包签名登录，返回 token + user */
+    /**
+     * 获取钱包签名挑战（nonce）。
+     * 服务端签发后存 Redis 10 分钟一次性；签名对象即返回的 nonce 字符串本体。
+     */
+    getChallenge(wallet: string): Promise<WalletNonce>;
+    /** 钱包签名登录（server 契约：{ wallet, nonce, signature }） */
     walletLogin(params: WalletLoginParams): Promise<AuthResult>;
     /**
      * 获取图形验证码（login/register 前置，可选）。

package/dist/resources/auth.js

@@ -2,11 +2,14 @@ export class AuthResource {
     constructor(request) {
         this.request = request;
     }
-    /** 获取钱包签名挑战 */
-    getChallenge(walletAddress) {
-        return this.request("POST", "/api/auth/wallet-challenge", { address: walletAddress });
+    /**
+     * 获取钱包签名挑战（nonce）。
+     * 服务端签发后存 Redis 10 分钟一次性；签名对象即返回的 nonce 字符串本体。
+     */
+    getChallenge(wallet) {
+        return this.request("POST", "/api/auth/wallet-nonce", { wallet });
     }
-    /** 钱包签名登录，返回 token + user */
+    /** 钱包签名登录（server 契约：{ wallet, nonce, signature }） */
     walletLogin(params) {
         return this.request("POST", "/api/auth/wallet-login", params);
     }

package/dist/types.d.ts

@@ -270,27 +270,34 @@ export interface ParamHint {
     source: "user_input" | "derived" | "user_address" | "computed";
     computeHint?: string;
 }
-export interface WalletChallenge {
-    challenge: string;
-    timestamp: number;
+/** 钱包登录 nonce（10 分钟一次性；签名对象即该 nonce 字符串本体） */
+export interface WalletNonce {
     nonce: string;
 }
+/** 钱包签名登录入参（server 契约：签名对象为 nonce） */
 export interface WalletLoginParams {
-    walletAddress: string;
-    signature: string;
-    timestamp: number;
+    wallet: string;
     nonce: string;
+    signature: string;
+}
+/** 账户公开信息（server `publicAccount` 投影） */
+export interface AuthAccount {
+    id: string;
+    email: string | null;
+    wallet: string | null;
+    mfaEnabled: boolean;
+    status: string;
 }
+/** 登录 / 注册 / 钱包登录成功：server 统一返回 { accessToken, refreshToken, account } */
 export interface AuthResult {
-    token: string;
-    user: {
-        id: string;
-        username: string;
-        role: string;
-        name: string;
-        email: string;
-        walletAddress?: string;
-    };
+    accessToken: string;
+    refreshToken: string;
+    account: AuthAccount;
+}
+/** MFA 账户未携带 mfaCode 时的响应（不签发 token，校验后重调原端点） */
+export interface MfaRequiredResult {
+    mfaRequired: true;
+    account: AuthAccount;
 }
 /** 图形验证码（login/register 前置，可选）：image 为 data URI，算式恒为非负结果 */
 export interface CaptchaResponse {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reachv2/sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Reach unified REST API client library for TypeScript — crm 域（AgentApi/Project/Bot/Knowledge/Channel/Conversation/Transaction/Auth/Chat/ApiKey/LightRAG/Orchestration/ScheduledTasks/Internal/Abis/Admin）+ social 域（Content/Tts/Accounts/Effect 效果追踪/SeoGeo SEO-GEO 矩阵/ContentRules 内容规则引擎/DataSources 数据源）+ 统一 DashboardApi（crm/social 看板）+ 统一租户成员模型（Tenants/Team/Health，G-1~G-3）",
   "type": "module",
   "main": "./dist/index.js",