@reachv2/sdk 0.1.0 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@ Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer
 
 ## 文档
 
-- **[API Reference](docs/API-REFERENCE.md)**（P2.6）：全部 20 个资源类 + `ReachClient` 共 **120 个方法**的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 `sdk/src` 源码一一对应。
+- **[API Reference](docs/API-REFERENCE.md)**（P2.6，v0.2.0 扩展统一租户）：全部 23 个资源类 + `ReachClient` 共 **136 个方法**的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 `sdk/src` 源码一一对应。
 
 ## 安装
 
@@ -68,6 +68,38 @@ client.setToken(jwt); // SDK 不会自动接线，需手动 setToken 切换为 J
 
 > `setToken()` 是全局切换，调用后所有资源请求优先使用 JWT。
 
+## MCP 接入（Phase 5 P5.2）
+
+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` 返回实际可用集合
+
+会话按 MCP Streamable HTTP 规范：先 `initialize` 取得 `mcp-session-id`，
+再发 `notifications/initialized`，之后 `tools/call`，结束时 `DELETE` 会话。
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const transport = new StreamableHTTPClientTransport(
+  new URL("https://reach.codes/mcp"),
+  { requestInit: { headers: { "X-API-Key": "reach-xxx" } } }
+);
+const client = new Client({ name: "my-agent", version: "1.0.0" });
+await client.connect(transport);
+
+const { tools } = await client.listTools();              // 实际可用的域白名单工具
+const res = await client.callTool({ name: "social_accounts_list", arguments: {} });
+await transport.close();                                  // 释放会话
+```
+
+> 平台内部闭环（reach server → mcp，`/api/bridge/mcp/discover|call`）走 `x-reach-internal-token`，
+> 不对外暴露；外部集成一律使用 API Key。
+
 ## 统一网关（A.2.4）
 
 合并后 Reach 采用**单后端 + 统一网关层**：`@reachv2/sdk` 只走网关。默认 `serverBaseUrl` 省略时等于 `baseUrl`，全部请求经统一网关；`serverBaseUrl` 仅作内部调试 override。
@@ -93,6 +125,14 @@ const client = new ReachClient({
 | `client.dashboard` | **统一看板**（DashboardApi）：crm 客服指标 + social 社媒运营看板 | 双域 |
 | `client.orchestration` | 对话编排（多 task × 多 agent） | Server |
 
+### 统一租户成员模型（G-1~G-3，v0.2.0 新增）
+
+| 资源 | 主要能力 | API 域 |
+|------|----------|--------|
+| `client.tenants` | **统一租户（TenantsResource）**：清单/建 org/成员列表/直加/邀请(意图记录)/接受/撤销/改派/移除/owner 转让（shared.tenant_members 权威面） | Server |
+| `client.team` | **社媒团队薄适配（TeamResource）**：/api/team/*（web 社媒后台 Team tab 契约；同表同 token 与 tenants 互通） | Server |
+| `client.health` | **存活探活（HealthResource）**：GET /api/health（匿名 200） | Server |
+
 ### crm 域（源自 aiservicer）
 
 | 资源 | 主要能力 | API 域 |

package/dist/client.d.ts

@@ -19,6 +19,9 @@ import { ContentResource } from "./resources/content.js";
 import { TtsResource } from "./resources/tts.js";
 import { AccountsResource } from "./resources/accounts.js";
 import { DashboardApi } from "./resources/dashboard-api.js";
+import { HealthResource } from "./resources/health.js";
+import { TenantsResource } from "./resources/tenants.js";
+import { TeamResource } from "./resources/team.js";
 export declare class ReachClient {
     private apiKey?;
     private token?;
@@ -45,6 +48,9 @@ export declare class ReachClient {
     content: ContentResource;
     tts: TtsResource;
     accounts: AccountsResource;
+    tenants: TenantsResource;
+    team: TeamResource;
+    health: HealthResource;
     constructor(config: ReachClientConfig);
     /** Set token after wallet login */
     setToken(token: string): void;

package/dist/client.js

@@ -19,6 +19,9 @@ import { ContentResource } from "./resources/content.js";
 import { TtsResource } from "./resources/tts.js";
 import { AccountsResource } from "./resources/accounts.js";
 import { DashboardApi } from "./resources/dashboard-api.js";
+import { HealthResource } from "./resources/health.js";
+import { TenantsResource } from "./resources/tenants.js";
+import { TeamResource } from "./resources/team.js";
 export class ReachClient {
     constructor(config) {
         if (!config.apiKey && !config.token) {
@@ -50,6 +53,9 @@ export class ReachClient {
         this.content = new ContentResource(this.requestServer.bind(this));
         this.tts = new TtsResource(this.requestServer.bind(this));
         this.accounts = new AccountsResource(this.requestServer.bind(this));
+        this.tenants = new TenantsResource(this.requestServer.bind(this));
+        this.team = new TeamResource(this.requestServer.bind(this));
+        this.health = new HealthResource(this.requestServer.bind(this));
     }
     /** Set token after wallet login */
     setToken(token) {

package/dist/index.d.ts

@@ -20,5 +20,8 @@ export { AbiResource } from "./resources/abis.js";
 export { ContentResource } from "./resources/content.js";
 export { TtsResource } from "./resources/tts.js";
 export { AccountsResource } from "./resources/accounts.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, } from "./types.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 { ApiKeyInfo, ApiKeyCreated } from "./resources/api-key.js";

package/dist/index.js

@@ -20,3 +20,6 @@ export { AbiResource } from "./resources/abis.js";
 export { ContentResource } from "./resources/content.js";
 export { TtsResource } from "./resources/tts.js";
 export { AccountsResource } from "./resources/accounts.js";
+export { HealthResource } from "./resources/health.js";
+export { TenantsResource } from "./resources/tenants.js";
+export { TeamResource } from "./resources/team.js";

package/dist/resources/auth.d.ts

@@ -8,14 +8,15 @@ export declare class AuthResource {
     /** 钱包签名登录，返回 token + user */
     walletLogin(params: WalletLoginParams): Promise<AuthResult>;
     /**
-     * 获取数学验证码（login/register 前置）。
-     * svg 为 `data:image/svg+xml;base64,...`，算式形如 "7 + 5 = ?"，结果恒为非负。
+     * 获取图形验证码（login/register 前置，可选）。
+     * image 为 `data:image/svg+xml;base64,...`，算式形如 "7 + 5 = ?"，结果恒为非负。
+     * 服务端校验码存 Redis 5 分钟一次性（reach:captcha:*）。
      */
     getCaptcha(): Promise<CaptchaResponse>;
-    /** 用户名密码登录（服务端强制要求验证码，必须传 captcha） */
-    login(username: string, password: string, captcha?: CaptchaAnswer): Promise<AuthResult>;
-    /** 用户名密码注册（服务端强制要求验证码，必须传 captcha） */
-    register(username: string, password: string, opts?: {
+    /** 邮箱密码登录（server 契约：email+password；captcha 可选，传 captchaToken+captchaAnswer 时服务端强校验） */
+    login(email: string, password: string, captcha?: CaptchaAnswer): Promise<AuthResult>;
+    /** 邮箱密码注册（server 契约：email+password；captcha 可选） */
+    register(email: string, password: string, opts?: {
         name?: string;
         email?: string;
         captcha?: CaptchaAnswer;

package/dist/resources/auth.js

@@ -11,28 +11,28 @@ export class AuthResource {
         return this.request("POST", "/api/auth/wallet-login", params);
     }
     /**
-     * 获取数学验证码（login/register 前置）。
-     * svg 为 `data:image/svg+xml;base64,...`，算式形如 "7 + 5 = ?"，结果恒为非负。
+     * 获取图形验证码（login/register 前置，可选）。
+     * image 为 `data:image/svg+xml;base64,...`，算式形如 "7 + 5 = ?"，结果恒为非负。
+     * 服务端校验码存 Redis 5 分钟一次性（reach:captcha:*）。
      */
     getCaptcha() {
         return this.request("POST", "/api/auth/captcha");
     }
-    /** 用户名密码登录（服务端强制要求验证码，必须传 captcha） */
-    login(username, password, captcha) {
+    /** 邮箱密码登录（server 契约：email+password；captcha 可选，传 captchaToken+captchaAnswer 时服务端强校验） */
+    login(email, password, captcha) {
         return this.request("POST", "/api/auth/login", {
-            username,
+            email,
             password,
             captchaToken: captcha?.token,
             captchaAnswer: captcha?.answer,
         });
     }
-    /** 用户名密码注册（服务端强制要求验证码，必须传 captcha） */
-    register(username, password, opts) {
+    /** 邮箱密码注册（server 契约：email+password；captcha 可选） */
+    register(email, password, opts) {
         return this.request("POST", "/api/auth/register", {
-            username,
+            email,
             password,
             name: opts?.name,
-            email: opts?.email,
             captchaToken: opts?.captcha?.token,
             captchaAnswer: opts?.captcha?.answer,
         });

package/dist/resources/health.d.ts

@@ -0,0 +1,13 @@
+import { RequestMethod, HealthInfo } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/**
+ * Health 资源 — 平台存活探活（REQ-4）。
+ * GET /api/health 匿名 200（无需鉴权头，但 SDK 构造仍需 apiKey/token 任一）。
+ */
+export declare class HealthResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 存活探活 */
+    check(): Promise<HealthInfo>;
+}
+export {};

package/dist/resources/health.js

@@ -0,0 +1,13 @@
+/**
+ * Health 资源 — 平台存活探活（REQ-4）。
+ * GET /api/health 匿名 200（无需鉴权头，但 SDK 构造仍需 apiKey/token 任一）。
+ */
+export class HealthResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 存活探活 */
+    check() {
+        return this.request("GET", "/api/health");
+    }
+}

package/dist/resources/team.d.ts

@@ -0,0 +1,34 @@
+import { RequestMethod, TenantMemberRole, TeamMemberItem, TeamInviteResult, SimpleResult } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/**
+ * Team 资源 — 社媒团队面（/api/team/*，web 社媒后台 Settings Team tab 契约的薄适配层）。
+ *
+ * P4.6 后为统一租户成员模型（shared.tenant_members）的适配层：邀请为意图记录
+ * （accountId 可空，不预建占位账户），受邀者经统一 POST /invites/:token/accept 激活
+ * （可用 tenants.acceptInvite(token)）。角色 GRANTABLE=admin/editor/member/viewer，
+ * owner 仅经 tenants.transferOwner 产生；PUT/DELETE 纪律对齐 G-3。
+ *
+ * 鉴权：JWT（Bearer token）。社媒上下文租户 = 账号默认（最早加入）active 租户；
+ * 明确租户作用域的成员管理请用 Tenants 资源（path 内显式 tenantId）。
+ */
+export declare class TeamResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 当前上下文租户成员列表（受邀未接受行 userId=null；{items,total} 契约） */
+    members(): Promise<{
+        items: TeamMemberItem[];
+        total: number;
+    }>;
+    /** 邀请成员（email 必填；role 缺省 editor；未注册邮箱亦有效，接受时绑定） */
+    invite(params: {
+        email: string;
+        role?: TenantMemberRole;
+    }): Promise<TeamInviteResult>;
+    /** 改派成员角色（id = TenantMember.id 行 id，来自 members() 的 item.id） */
+    updateMemberRole(memberRowId: string, params: {
+        role: TenantMemberRole;
+    }): Promise<TeamMemberItem>;
+    /** 移除/撤销成员（id = TenantMember.id 行 id；撤销待接受邀请复用本方法） */
+    removeMember(memberRowId: string): Promise<SimpleResult>;
+}
+export {};

package/dist/resources/team.js

@@ -0,0 +1,35 @@
+/**
+ * Team 资源 — 社媒团队面（/api/team/*，web 社媒后台 Settings Team tab 契约的薄适配层）。
+ *
+ * P4.6 后为统一租户成员模型（shared.tenant_members）的适配层：邀请为意图记录
+ * （accountId 可空，不预建占位账户），受邀者经统一 POST /invites/:token/accept 激活
+ * （可用 tenants.acceptInvite(token)）。角色 GRANTABLE=admin/editor/member/viewer，
+ * owner 仅经 tenants.transferOwner 产生；PUT/DELETE 纪律对齐 G-3。
+ *
+ * 鉴权：JWT（Bearer token）。社媒上下文租户 = 账号默认（最早加入）active 租户；
+ * 明确租户作用域的成员管理请用 Tenants 资源（path 内显式 tenantId）。
+ */
+export class TeamResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 当前上下文租户成员列表（受邀未接受行 userId=null；{items,total} 契约） */
+    members() {
+        return this.request("GET", "/api/team/members");
+    }
+    /** 邀请成员（email 必填；role 缺省 editor；未注册邮箱亦有效，接受时绑定） */
+    invite(params) {
+        return this.request("POST", "/api/team/invite", {
+            email: params.email,
+            role: params.role || "editor",
+        });
+    }
+    /** 改派成员角色（id = TenantMember.id 行 id，来自 members() 的 item.id） */
+    updateMemberRole(memberRowId, params) {
+        return this.request("PUT", `/api/team/members/${encodeURIComponent(memberRowId)}`, { role: params.role });
+    }
+    /** 移除/撤销成员（id = TenantMember.id 行 id；撤销待接受邀请复用本方法） */
+    removeMember(memberRowId) {
+        return this.request("DELETE", `/api/team/members/${encodeURIComponent(memberRowId)}`);
+    }
+}

package/dist/resources/tenants.d.ts

@@ -0,0 +1,52 @@
+import { RequestMethod, Tenant, TenantMemberRole, TenantMemberInfo, TenantInvite, PublicInviteInfo, InviteAcceptResult, SimpleResult, MemberRoleUpdateResult, TransferOwnerResult } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/**
+ * Tenants 资源 — 平台统一租户成员模型（G-1~G-3，/api/shared/tenants）。
+ *
+ * 模型：注册即自动建 personal 个人租户（owner）；可显式创建 org 企业租户（owner）；
+ * 成员档位 owner(唯一,转让制) > admin > editor > member/viewer（GRANTABLE=admin/editor/member/viewer，
+ * owner 仅经 transferOwner 产生）；未注册邮箱走 invite 意图记录（不预建占位账户），
+ * 受邀者注册/登录后经 acceptInvite 绑定身份激活（邮箱匹配防冒领）。
+ *
+ * 鉴权：除 getInvite(token) 公开外，全部需 JWT（Bearer token，client 以 token 构造）。
+ */
+export declare class TenantsResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 我加入的租户清单（含 type 与我的角色） */
+    list(): Promise<Tenant[]>;
+    /** 创建企业/组织租户（创建者为 owner，type=org） */
+    create(params: {
+        name: string;
+    }): Promise<Tenant>;
+    /** 租户成员列表（含 invited 待接受行；owner/admin 可见 inviteToken 便于管理邀请链接） */
+    members(tenantId: string): Promise<TenantMemberInfo[]>;
+    /** 直加已注册账户（owner/admin；email 或 wallet 定位账户；未注册邮箱请用 invite） */
+    addMember(tenantId: string, params: {
+        email?: string;
+        wallet?: string;
+        role?: TenantMemberRole;
+    }): Promise<TenantMemberInfo>;
+    /** 邀请未注册邮箱（意图记录；受邀者注册/登录后 acceptInvite 激活） */
+    invite(tenantId: string, params: {
+        email: string;
+        role?: TenantMemberRole;
+    }): Promise<TenantInvite>;
+    /** 公开查询邀请（无需登录；展示租户/受邀邮箱/角色/状态） */
+    getInvite(token: string): Promise<PublicInviteInfo>;
+    /** 登录后接受邀请：邮箱须与邀请一致，绑定身份并激活（幂等） */
+    acceptInvite(token: string): Promise<InviteAcceptResult>;
+    /** 撤销待接受邀请（owner/admin） */
+    revokeInvite(tenantId: string, token: string): Promise<SimpleResult>;
+    /** 改派成员角色（owner 全权；admin 仅改 editor/member/viewer，不可授/动 admin；owner 只经转让） */
+    updateMemberRole(tenantId: string, accountId: string, params: {
+        role: TenantMemberRole;
+    }): Promise<MemberRoleUpdateResult>;
+    /** 移除成员（owner 移除非 owner；admin 仅移除 editor/member/viewer；owner 移除前须先转让） */
+    removeMember(tenantId: string, accountId: string): Promise<SimpleResult>;
+    /** owner 转让（仅当前 owner；目标须为 active 成员；转让后原 owner 降 admin） */
+    transferOwner(tenantId: string, params: {
+        accountId: string;
+    }): Promise<TransferOwnerResult>;
+}
+export {};

package/dist/resources/tenants.js

@@ -0,0 +1,59 @@
+/**
+ * Tenants 资源 — 平台统一租户成员模型（G-1~G-3，/api/shared/tenants）。
+ *
+ * 模型：注册即自动建 personal 个人租户（owner）；可显式创建 org 企业租户（owner）；
+ * 成员档位 owner(唯一,转让制) > admin > editor > member/viewer（GRANTABLE=admin/editor/member/viewer，
+ * owner 仅经 transferOwner 产生）；未注册邮箱走 invite 意图记录（不预建占位账户），
+ * 受邀者注册/登录后经 acceptInvite 绑定身份激活（邮箱匹配防冒领）。
+ *
+ * 鉴权：除 getInvite(token) 公开外，全部需 JWT（Bearer token，client 以 token 构造）。
+ */
+export class TenantsResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 我加入的租户清单（含 type 与我的角色） */
+    list() {
+        return this.request("GET", "/api/shared/tenants");
+    }
+    /** 创建企业/组织租户（创建者为 owner，type=org） */
+    create(params) {
+        return this.request("POST", "/api/shared/tenants", { name: params.name });
+    }
+    /** 租户成员列表（含 invited 待接受行；owner/admin 可见 inviteToken 便于管理邀请链接） */
+    members(tenantId) {
+        return this.request("GET", `/api/shared/tenants/${encodeURIComponent(tenantId)}/members`);
+    }
+    /** 直加已注册账户（owner/admin；email 或 wallet 定位账户；未注册邮箱请用 invite） */
+    addMember(tenantId, params) {
+        return this.request("POST", `/api/shared/tenants/${encodeURIComponent(tenantId)}/members`, { email: params.email, wallet: params.wallet, role: params.role || "member" });
+    }
+    /** 邀请未注册邮箱（意图记录；受邀者注册/登录后 acceptInvite 激活） */
+    invite(tenantId, params) {
+        return this.request("POST", `/api/shared/tenants/${encodeURIComponent(tenantId)}/invites`, { email: params.email, role: params.role || "member" });
+    }
+    /** 公开查询邀请（无需登录；展示租户/受邀邮箱/角色/状态） */
+    getInvite(token) {
+        return this.request("GET", `/api/shared/tenants/invites/${encodeURIComponent(token)}`);
+    }
+    /** 登录后接受邀请：邮箱须与邀请一致，绑定身份并激活（幂等） */
+    acceptInvite(token) {
+        return this.request("POST", `/api/shared/tenants/invites/${encodeURIComponent(token)}/accept`);
+    }
+    /** 撤销待接受邀请（owner/admin） */
+    revokeInvite(tenantId, token) {
+        return this.request("POST", `/api/shared/tenants/${encodeURIComponent(tenantId)}/invites/${encodeURIComponent(token)}/revoke`);
+    }
+    /** 改派成员角色（owner 全权；admin 仅改 editor/member/viewer，不可授/动 admin；owner 只经转让） */
+    updateMemberRole(tenantId, accountId, params) {
+        return this.request("PUT", `/api/shared/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(accountId)}`, { role: params.role });
+    }
+    /** 移除成员（owner 移除非 owner；admin 仅移除 editor/member/viewer；owner 移除前须先转让） */
+    removeMember(tenantId, accountId) {
+        return this.request("DELETE", `/api/shared/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(accountId)}`);
+    }
+    /** owner 转让（仅当前 owner；目标须为 active 成员；转让后原 owner 降 admin） */
+    transferOwner(tenantId, params) {
+        return this.request("POST", `/api/shared/tenants/${encodeURIComponent(tenantId)}/transfer-owner`, { accountId: params.accountId });
+    }
+}

package/dist/types.d.ts

@@ -12,7 +12,7 @@ export type BotStatus = "running" | "stopped";
 export type ChannelType = "telegram" | "whatsapp" | "webwidget";
 export type ChannelStatus = "configured" | "unconfigured" | "pairing";
 export type KnowledgeStatus = "processing" | "ready" | "error";
-export type RequestMethod = "GET" | "POST" | "PATCH" | "DELETE";
+export type RequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 export interface Pagination {
     page: number;
     pageSize: number;
@@ -292,13 +292,13 @@ export interface AuthResult {
         walletAddress?: string;
     };
 }
-/** 数学验证码（login/register 前置）：svg 为 data URI，算式恒为非负结果 */
+/** 图形验证码（login/register 前置，可选）：image 为 data URI，算式恒为非负结果 */
 export interface CaptchaResponse {
-    token: string;
-    svg: string;
+    captchaId: string;
+    image: string;
     expiresIn: number;
 }
-/** 验证码作答参数（服务端校验通过才放行登录/注册） */
+/** 验证码作答参数（以 captchaId 为 token；服务端校验通过才放行登录/注册） */
 export interface CaptchaAnswer {
     token: string;
     answer: number;
@@ -791,3 +791,108 @@ export interface MonitorEvent {
     payload: Record<string, unknown>;
     received_at: string;
 }
+/** 通用 ok 结果（{ok:true} 契约：revoke/remove 等） */
+export interface SimpleResult {
+    ok: boolean;
+}
+export type TenantType = "personal" | "org";
+/** 租户内档位全集（owner 仅经转让产生；GRANTABLE=admin/editor/member/viewer） */
+export type TenantMemberRole = "owner" | "admin" | "editor" | "member" | "viewer";
+export type TenantMemberStatus = "active" | "invited";
+/** 租户（清单响应含我在此租户的角色 role） */
+export interface Tenant {
+    id: string;
+    name: string;
+    slug: string;
+    type: TenantType;
+    status?: string | null;
+    tokenBalance?: number | null;
+    createdAt?: string | null;
+    role?: TenantMemberRole;
+}
+/** 租户成员行（GET /:id/members；owner/admin 可见 inviteToken） */
+export interface TenantMemberInfo {
+    id: string;
+    tenantId: string;
+    accountId: string | null;
+    role: TenantMemberRole;
+    status: TenantMemberStatus;
+    email: string | null;
+    username?: string | null;
+    wallet?: string | null;
+    /** 仅 owner/admin 可见；受邀未接受行存在 */
+    inviteToken?: string | null;
+    joinedAt?: string | null;
+}
+/** 邀请意图记录（POST /:id/invites 响应） */
+export interface TenantInvite {
+    id: string;
+    tenantId: string;
+    email: string;
+    role: TenantMemberRole;
+    status: TenantMemberStatus;
+    inviteToken: string;
+}
+/** 公开邀请查询（GET /invites/:token） */
+export interface PublicInviteInfo {
+    tenant: {
+        id: string;
+        name: string;
+        slug: string;
+        type: TenantType;
+    };
+    email: string;
+    role: TenantMemberRole;
+    status: TenantMemberStatus;
+}
+/** 接受邀请结果（POST /invites/:token/accept；幂等） */
+export interface InviteAcceptResult {
+    accepted: boolean;
+    tenantId?: string;
+    role?: TenantMemberRole;
+    /** 该邀请此前已被处理（重复接受/已是成员） */
+    alreadyProcessed?: boolean;
+    alreadyMember?: boolean;
+}
+/** 改派成员角色结果（PUT /:id/members/:accountId） */
+export interface MemberRoleUpdateResult {
+    id: string;
+    accountId: string;
+    role: TenantMemberRole;
+    status: TenantMemberStatus;
+}
+/** owner 转让结果（POST /:id/transfer-owner） */
+export interface TransferOwnerResult {
+    ok: boolean;
+    newOwner: string;
+}
+/** 社媒团队成员行（GET /api/team/members item；id = TenantMember.id 行 id） */
+export interface TeamMemberItem {
+    id: string;
+    tenantId: string;
+    /** 受邀未接受时 null（accountId 可空，不预建占位账户） */
+    userId: string | null;
+    role: TenantMemberRole;
+    status: TenantMemberStatus;
+    email: string | null;
+    name?: string | null;
+    username?: string | null;
+    avatarUrl?: string | null;
+    joinedAt?: string | null;
+}
+/** 社媒团队邀请结果（POST /api/team/invite） */
+export interface TeamInviteResult {
+    invited: boolean;
+    id: string;
+    email: string;
+    role: TenantMemberRole;
+    inviteToken: string;
+}
+/** 存活探活（GET /api/health 匿名 200） */
+export interface HealthInfo {
+    status: string;
+    service?: string;
+    version?: string;
+    uptime?: number;
+    [key: string]: unknown;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reachv2/sdk",
-  "version": "0.1.0",
-  "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）+ 统一 DashboardApi（crm/social 看板）",
+  "version": "0.2.0",
+  "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）+ 统一 DashboardApi（crm/social 看板）+ 统一租户成员模型（Tenants/Team/Health，G-1~G-3）",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",