@reachv2/sdk 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# @reachv2/sdk
+
+Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer SDK（crm 域，18 资源）与 aiops-saas SDK（social 域，5 资源）合并而来（P2.4）。一个客户端覆盖客服 / 销售引导、社群维护与社媒运营全部资源。
+
+- 运行时：Node.js >= 18（ESM）
+- 类型：完整 TypeScript 类型定义（自带 `dist/index.d.ts`）
+- License：MIT
+
+## 文档
+
+- **[API Reference](docs/API-REFERENCE.md)**（P2.6）：全部 20 个资源类 + `ReachClient` 共 **120 个方法**的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 `sdk/src` 源码一一对应。
+
+## 安装
+
+```bash
+npm install @reachv2/sdk
+```
+
+## 快速开始
+
+### 方式一：API Key（推荐，服务端 / 简单集成）
+
+```ts
+import { ReachClient } from "@reachv2/sdk";
+
+const client = new ReachClient({
+  baseUrl: "https://reach.codes",     // 统一网关根地址（生产域名，走 HTTPS）
+  apiKey: "reach-xxx",                // 商户 API Key
+});
+
+// 列出 crm 域 agent（唯一 Agent 入口）
+const { agents } = await client.agents.list({ projectId: "project-xxx" });
+
+// 与 agent 对话（RAG + 交易构造由服务端完成）
+const { reply, transaction } = await client.agents.chat("bot-xxx", {
+  message: "我想在 Base 上铸造一个 NFT",
+  userAddress: "0x1234...",
+  chainId: 8453,
+});
+
+// 社媒域：生成文案
+const post = await client.content.generate("AI trends", "twitter", "professional");
+```
+
+### 方式二：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+)/)!;
+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 模式
+```
+
+> **JWT 续期约定**：`login` 签发 7 天有效 JWT 且无 refresh 机制，请提前 1 天重新登录并 `setToken`。
+
+## 认证方式
+
+| 方式 | 配置 | 生效域 |
+|------|------|--------|
+| API Key | `config.apiKey` | 所有请求带 `X-API-Key` Header |
+| 商户 JWT | `client.setToken(jwt)` | 覆盖 API Key，带 `Authorization: Bearer` |
+| 管理员 JWT | `client.admin` 前置 setToken（管理员账号） | Admin 资源（`/api/admin/*`） |
+
+> `setToken()` 是全局切换，调用后所有资源请求优先使用 JWT。
+
+## 统一网关（A.2.4）
+
+合并后 Reach 采用**单后端 + 统一网关层**：`@reachv2/sdk` 只走网关。默认 `serverBaseUrl` 省略时等于 `baseUrl`，全部请求经统一网关；`serverBaseUrl` 仅作内部调试 override。
+
+```ts
+const client = new ReachClient({
+  baseUrl: "https://reach.codes",   // 统一网关
+  apiKey: "reach-xxx",
+});
+```
+
+## 资源概览（client.*）
+
+统一资源按 **crm 域 / social 域 / 共享基础** 组织（A.5.3）：
+
+### 共享基础
+
+| 资源 | 主要能力 | API 域 |
+|------|----------|--------|
+| `client.auth` | 验证码（getCaptcha）、登录、注册、钱包登录（MFA/SSO） | Server |
+| `client.admin` | 平台仪表盘、商户、计费、LLM 设置（需管理员 JWT） | Admin |
+| `client.apiKeys` | API Key 创建/列表/吊销 | Gateway |
+| `client.dashboard` | **统一看板**（DashboardApi）：crm 客服指标 + social 社媒运营看板 | 双域 |
+| `client.orchestration` | 对话编排（多 task × 多 agent） | Server |
+
+### crm 域（源自 aiservicer）
+
+| 资源 | 主要能力 | API 域 |
+|------|----------|--------|
+| `client.agents` | **统一 Agent 入口**（AgentApi）：调用方 agent（list/get/capabilities/chat/prepareTransaction）+ AgentX 链上市场/订阅/状态/用量/发布/技能 + 市场 run/clone | 双域 |
+| `client.project` | 项目 CRUD、列表 | Gateway |
+| `client.bot` | Bot（客服/销售/交易/自定义）CRUD、启停、统计 | Gateway |
+| `client.knowledge` | 知识文档 CRUD、推荐 | Gateway |
+| `client.channel` | 渠道（telegram/whatsapp/webwidget）创建与配置 | Gateway |
+| `client.conversation` | 对话记录与消息 | Gateway |
+| `client.transaction` | 交易意图解析/构造/模拟、协议/合约/calldata 查询 | Gateway |
+| `client.chat` | 服务端对话（含 function calling tools、A2A 编排） | Server |
+| `client.lightrag` | RAG Key 管理 + 文档 CRUD + 查询（per-user namespace） | Gateway |
+| `client.scheduledTasks` | 主 agent 定时任务管理 | Server |
+| `client.internal` | 企业内 Agent：企业级共享知识库 + 监控连接器/事件（`internal` bot） | Server |
+| `client.abis` | 商户租户合约 ABI 管理：list/add/remove（交易 agent 上传 ABI 后即可按函数构造链上调用） | Server |
+
+### social 域（源自 aiops-saas）
+
+| 资源 | 主要能力 | API 域 |
+|------|----------|--------|
+| `client.content` | 社媒文案生成（generate/list/platforms/styles/get/update/delete） | Server |
+| `client.tts` | 文本转语音（synthesize/voices/history） | Server |
+| `client.accounts` | 社媒账号矩阵（list/connect） | Server |
+
+> crm 客服指标（原 `client.analytics`）与社媒运营看板（原 `client.dashboard`）已统一为 `client.dashboard`（DashboardApi）；AgentX（原 `client.agentx`）与社媒 Agent 市场已统一为 `client.agents`（AgentApi）。
+
+## 统一入口说明
+
+- **AgentApi（`client.agents`）**：唯一 Agent 入口（P2.4.3）。吸收 S agent（网关 `/api/v1/agents/*`：list/get/capabilities/chat/prepareTransaction）、S agentx（server `/api/agentx/*` + `/api/merchant/*`：市场/计划/订阅/状态/用量/上下文/发布/技能）与 A agents（server `/api/agents/*`：run/clone，marketplace→listMarketplace）。统一 Agent 资源模型见 REACH_MERGE_PLAN A.2.3/A.2.5。
+- **DashboardApi（`client.dashboard`）**：唯一看板入口（P2.4.4）。crm 域（`global` / `dashboard(projectId)` / `botMetrics` / `summaryByUser`）+ social 域（`overview` / `quota` / `trend`）。
+
+## Function Calling（工具回调）
+
+`chat.send` / `agents.chat` 支持 `tools` 参数（OpenAI function calling 兼容格式）。平台执行工具时 POST 到 `callback_url`，回调体 `{ tool, arguments }`，携带 `X-Tool-Key` 头。
+
+> 平台**不代验签**——回调服务必须自行校验 `X-Tool-Key`（推荐 `timingSafeEqual`）。15s 超时 / 最多 5 轮循环。
+
+## 开发 / 测试
+
+```bash
+cd sdk
+npm install
+npm run build     # tsc → dist
+npm test          # node --test test/（冒烟：导出 + 资源方法面）
+```
+
+## 发布流程（维护者）
+
+```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 组织）
+cd .. && git add sdk/package.json sdk/package-lock.json
+git commit -m "chore(sdk): 发布 @reachv2/sdk@<version>"
+```

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+import { ReachClientConfig, RequestMethod } from "./types.js";
+import { ProjectResource } from "./resources/project.js";
+import { BotResource } from "./resources/bot.js";
+import { AgentApi } from "./resources/agent-api.js";
+import { KnowledgeResource } from "./resources/knowledge.js";
+import { ChannelResource } from "./resources/channel.js";
+import { ConversationResource } from "./resources/conversation.js";
+import { TransactionResource } from "./resources/transaction.js";
+import { AuthResource } from "./resources/auth.js";
+import { ChatResource } from "./resources/chat.js";
+import { ApiKeyResource } from "./resources/api-key.js";
+import { LightRAGResource } from "./resources/lightrag.js";
+import { AdminResource } from "./resources/admin.js";
+import { OrchestrationResource } from "./resources/orchestration.js";
+import { ScheduledTasksResource } from "./resources/scheduledTasks.js";
+import { InternalAgentResource } from "./resources/internalAgent.js";
+import { AbiResource } from "./resources/abis.js";
+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";
+export declare class ReachClient {
+    private apiKey?;
+    private token?;
+    private baseUrl;
+    private serverBaseUrl;
+    project: ProjectResource;
+    bot: BotResource;
+    /** 唯一 Agent 入口（P2.4.3 统一：S agent+agentx + A agents） */
+    agents: AgentApi;
+    knowledge: KnowledgeResource;
+    channel: ChannelResource;
+    conversation: ConversationResource;
+    transaction: TransactionResource;
+    auth: AuthResource;
+    chat: ChatResource;
+    apiKeys: ApiKeyResource;
+    lightrag: LightRAGResource;
+    orchestration: OrchestrationResource;
+    scheduledTasks: ScheduledTasksResource;
+    internal: InternalAgentResource;
+    abis: AbiResource;
+    admin: AdminResource;
+    dashboard: DashboardApi;
+    content: ContentResource;
+    tts: TtsResource;
+    accounts: AccountsResource;
+    constructor(config: ReachClientConfig);
+    /** Set token after wallet login */
+    setToken(token: string): void;
+    /**
+     * Perform an arbitrary Gateway API request.
+     * Advanced use — for endpoints not yet covered by a typed resource.
+     */
+    request<T>(method: RequestMethod, path: string, body?: unknown): Promise<T>;
+    private requestGateway;
+    private requestServer;
+    private _request;
+}

package/dist/client.js

@@ -0,0 +1,107 @@
+import { ReachError } from "./error.js";
+import { ProjectResource } from "./resources/project.js";
+import { BotResource } from "./resources/bot.js";
+import { AgentApi } from "./resources/agent-api.js";
+import { KnowledgeResource } from "./resources/knowledge.js";
+import { ChannelResource } from "./resources/channel.js";
+import { ConversationResource } from "./resources/conversation.js";
+import { TransactionResource } from "./resources/transaction.js";
+import { AuthResource } from "./resources/auth.js";
+import { ChatResource } from "./resources/chat.js";
+import { ApiKeyResource } from "./resources/api-key.js";
+import { LightRAGResource } from "./resources/lightrag.js";
+import { AdminResource } from "./resources/admin.js";
+import { OrchestrationResource } from "./resources/orchestration.js";
+import { ScheduledTasksResource } from "./resources/scheduledTasks.js";
+import { InternalAgentResource } from "./resources/internalAgent.js";
+import { AbiResource } from "./resources/abis.js";
+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";
+export class ReachClient {
+    constructor(config) {
+        if (!config.apiKey && !config.token) {
+            throw new ReachError("Either apiKey or token must be provided", "MISSING_AUTH", 0);
+        }
+        this.apiKey = config.apiKey;
+        this.token = config.token;
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.serverBaseUrl = config.serverBaseUrl
+            ? config.serverBaseUrl.replace(/\/+$/, "")
+            : this.baseUrl;
+        this.project = new ProjectResource(this.requestGateway.bind(this));
+        this.bot = new BotResource(this.requestGateway.bind(this));
+        this.agents = new AgentApi(this.requestGateway.bind(this), this.requestServer.bind(this));
+        this.knowledge = new KnowledgeResource(this.requestGateway.bind(this));
+        this.channel = new ChannelResource(this.requestGateway.bind(this));
+        this.conversation = new ConversationResource(this.requestGateway.bind(this));
+        this.transaction = new TransactionResource(this.requestGateway.bind(this));
+        this.dashboard = new DashboardApi(this.requestGateway.bind(this), this.requestServer.bind(this));
+        this.auth = new AuthResource(this.requestServer.bind(this));
+        this.chat = new ChatResource(this.requestServer.bind(this));
+        this.apiKeys = new ApiKeyResource(this.requestGateway.bind(this));
+        this.lightrag = new LightRAGResource(this.requestGateway.bind(this));
+        this.admin = new AdminResource(this.requestServer.bind(this));
+        this.orchestration = new OrchestrationResource(this.requestServer.bind(this));
+        this.scheduledTasks = new ScheduledTasksResource(this.requestServer.bind(this));
+        this.internal = new InternalAgentResource(this.requestServer.bind(this));
+        this.abis = new AbiResource(this.requestServer.bind(this));
+        this.content = new ContentResource(this.requestServer.bind(this));
+        this.tts = new TtsResource(this.requestServer.bind(this));
+        this.accounts = new AccountsResource(this.requestServer.bind(this));
+    }
+    /** Set token after wallet login */
+    setToken(token) {
+        this.token = token;
+    }
+    /**
+     * Perform an arbitrary Gateway API request.
+     * Advanced use — for endpoints not yet covered by a typed resource.
+     */
+    request(method, path, body) {
+        return this.requestGateway(method, path, body);
+    }
+    requestGateway(method, path, body) {
+        return this._request(this.baseUrl, method, path, body);
+    }
+    requestServer(method, path, body) {
+        return this._request(this.serverBaseUrl, method, path, body);
+    }
+    async _request(baseUrl, method, path, body) {
+        const url = `${baseUrl}${path}`;
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["X-API-Key"] = this.apiKey;
+        }
+        if (this.token) {
+            headers["Authorization"] = `Bearer ${this.token}`;
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch {
+            throw new ReachError("Network request failed", "NETWORK_ERROR", 0);
+        }
+        if (!response.ok) {
+            let errorBody;
+            try {
+                errorBody = await response.json();
+            }
+            catch {
+                errorBody = null;
+            }
+            const message = errorBody?.message ||
+                `Request failed with status ${response.status}`;
+            throw new ReachError(message, "API_ERROR", response.status, errorBody);
+        }
+        return response.json();
+    }
+}

package/dist/error.d.ts

@@ -0,0 +1,6 @@
+export declare class ReachError extends Error {
+    code: string;
+    status: number;
+    details: unknown;
+    constructor(message: string, code: string, status: number, details?: unknown);
+}

package/dist/error.js

@@ -0,0 +1,9 @@
+export class ReachError extends Error {
+    constructor(message, code, status, details) {
+        super(message);
+        this.name = "ReachError";
+        this.code = code;
+        this.status = status;
+        this.details = details;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export { ReachClient } from "./client.js";
+export { ReachError } from "./error.js";
+export { ProjectResource } from "./resources/project.js";
+export { BotResource } from "./resources/bot.js";
+export { AgentApi } from "./resources/agent-api.js";
+export { KnowledgeResource } from "./resources/knowledge.js";
+export { ChannelResource } from "./resources/channel.js";
+export { ConversationResource } from "./resources/conversation.js";
+export { DashboardApi } from "./resources/dashboard-api.js";
+export { TransactionResource } from "./resources/transaction.js";
+export { AuthResource } from "./resources/auth.js";
+export { ChatResource } from "./resources/chat.js";
+export { ApiKeyResource } from "./resources/api-key.js";
+export { LightRAGResource } from "./resources/lightrag.js";
+export { AdminResource } from "./resources/admin.js";
+export { OrchestrationResource } from "./resources/orchestration.js";
+export { ScheduledTasksResource } from "./resources/scheduledTasks.js";
+export { InternalAgentResource } from "./resources/internalAgent.js";
+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 type { ApiKeyInfo, ApiKeyCreated } from "./resources/api-key.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+export { ReachClient } from "./client.js";
+export { ReachError } from "./error.js";
+export { ProjectResource } from "./resources/project.js";
+export { BotResource } from "./resources/bot.js";
+export { AgentApi } from "./resources/agent-api.js";
+export { KnowledgeResource } from "./resources/knowledge.js";
+export { ChannelResource } from "./resources/channel.js";
+export { ConversationResource } from "./resources/conversation.js";
+export { DashboardApi } from "./resources/dashboard-api.js";
+export { TransactionResource } from "./resources/transaction.js";
+export { AuthResource } from "./resources/auth.js";
+export { ChatResource } from "./resources/chat.js";
+export { ApiKeyResource } from "./resources/api-key.js";
+export { LightRAGResource } from "./resources/lightrag.js";
+export { AdminResource } from "./resources/admin.js";
+export { OrchestrationResource } from "./resources/orchestration.js";
+export { ScheduledTasksResource } from "./resources/scheduledTasks.js";
+export { InternalAgentResource } from "./resources/internalAgent.js";
+export { AbiResource } from "./resources/abis.js";
+export { ContentResource } from "./resources/content.js";
+export { TtsResource } from "./resources/tts.js";
+export { AccountsResource } from "./resources/accounts.js";

package/dist/resources/abis.d.ts

@@ -0,0 +1,20 @@
+import { RequestMethod, MerchantAbi, MerchantAbiCreateParams } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+export declare class AbiResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 列出当前商户的所有合约 ABI */
+    list(): Promise<{
+        abis: MerchantAbi[];
+    }>;
+    /** 新增合约 ABI（上传后交易 agent 即具备调用该合约函数的能力） */
+    add(params: MerchantAbiCreateParams): Promise<{
+        success: boolean;
+        abi: MerchantAbi;
+    }>;
+    /** 删除合约 ABI（已存在的 agent 能力声明同步移除） */
+    remove(id: string): Promise<{
+        success: boolean;
+    }>;
+}
+export {};

package/dist/resources/abis.js

@@ -0,0 +1,17 @@
+export class AbiResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 列出当前商户的所有合约 ABI */
+    list() {
+        return this.request("GET", "/api/merchant/abis");
+    }
+    /** 新增合约 ABI（上传后交易 agent 即具备调用该合约函数的能力） */
+    add(params) {
+        return this.request("POST", "/api/merchant/abis", params);
+    }
+    /** 删除合约 ABI（已存在的 agent 能力声明同步移除） */
+    remove(id) {
+        return this.request("DELETE", `/api/merchant/abis/${encodeURIComponent(id)}`);
+    }
+}

package/dist/resources/accounts.d.ts

@@ -0,0 +1,15 @@
+import { RequestMethod } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/**
+ * Accounts 资源 — 社媒账号矩阵（源自 aiops-saas @aiops/sdk AccountsApi）。
+ * 端点走 Server API（/api/accounts/*）。
+ */
+export declare class AccountsResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 账号列表 */
+    list(): Promise<any>;
+    /** 连接平台账号（OAuth 凭据） */
+    connect(platform: string, credentials: Record<string, unknown>): Promise<any>;
+}
+export {};

package/dist/resources/accounts.js

@@ -0,0 +1,17 @@
+/**
+ * Accounts 资源 — 社媒账号矩阵（源自 aiops-saas @aiops/sdk AccountsApi）。
+ * 端点走 Server API（/api/accounts/*）。
+ */
+export class AccountsResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 账号列表 */
+    list() {
+        return this.request("GET", "/api/accounts");
+    }
+    /** 连接平台账号（OAuth 凭据） */
+    connect(platform, credentials) {
+        return this.request("POST", `/api/accounts/${platform}/connect`, credentials);
+    }
+}

package/dist/resources/admin.d.ts

@@ -0,0 +1,34 @@
+import { RequestMethod, AdminDashboard, AdminMerchant, AdminMerchantDetail, AdminBillingRecord, AdminCreateBillingParams, LlmSettings, LlmUpdateParams } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/**
+ * Admin resource — 平台管理端点（server 域 /api/admin/*）。
+ * 需要 admin JWT Token（`client.setToken(...)` 或构造时传入 `token`）。
+ */
+export declare class AdminResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 获取管理仪表盘统计（商户/项目/Token/对话/营收/月度趋势） */
+    getDashboard(): Promise<AdminDashboard>;
+    /** 列出所有商户（含套餐/状态/用量） */
+    listMerchants(): Promise<AdminMerchant[]>;
+    /** 获取商户详情（含其项目列表） */
+    getMerchant(id: string): Promise<AdminMerchantDetail>;
+    /** 更新商户套餐（如 starter / pro） */
+    updateMerchantPlan(id: string, plan: string): Promise<{
+        success: boolean;
+        merchantId: string;
+        plan: string;
+    }>;
+    /** 获取所有计费记录 */
+    listBilling(): Promise<AdminBillingRecord[]>;
+    /** 创建计费记录（同时更新对应商户套餐） */
+    createBilling(params: AdminCreateBillingParams): Promise<AdminBillingRecord>;
+    /** 获取 LLM 设置 */
+    getSettings(): Promise<LlmSettings>;
+    /** 更新 LLM 设置（api_key 必填） */
+    updateSettings(params: LlmUpdateParams): Promise<{
+        success: boolean;
+        settings: LlmSettings;
+    }>;
+}
+export {};

package/dist/resources/admin.js

@@ -0,0 +1,41 @@
+/**
+ * Admin resource — 平台管理端点（server 域 /api/admin/*）。
+ * 需要 admin JWT Token（`client.setToken(...)` 或构造时传入 `token`）。
+ */
+export class AdminResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 获取管理仪表盘统计（商户/项目/Token/对话/营收/月度趋势） */
+    getDashboard() {
+        return this.request("GET", "/api/admin/dashboard");
+    }
+    /** 列出所有商户（含套餐/状态/用量） */
+    listMerchants() {
+        return this.request("GET", "/api/admin/merchants");
+    }
+    /** 获取商户详情（含其项目列表） */
+    getMerchant(id) {
+        return this.request("GET", `/api/admin/merchants/${id}`);
+    }
+    /** 更新商户套餐（如 starter / pro） */
+    updateMerchantPlan(id, plan) {
+        return this.request("POST", `/api/admin/merchants/${id}/plan`, { plan });
+    }
+    /** 获取所有计费记录 */
+    listBilling() {
+        return this.request("GET", "/api/admin/billing");
+    }
+    /** 创建计费记录（同时更新对应商户套餐） */
+    createBilling(params) {
+        return this.request("POST", "/api/admin/billing", params);
+    }
+    /** 获取 LLM 设置 */
+    getSettings() {
+        return this.request("GET", "/api/admin/settings");
+    }
+    /** 更新 LLM 设置（api_key 必填） */
+    updateSettings(params) {
+        return this.request("POST", "/api/admin/settings", params);
+    }
+}

package/dist/resources/agent-api.d.ts

@@ -0,0 +1,61 @@
+import { RequestMethod, AgentListParams, AgentListResult, AgentSummary, AgentCapabilities, AgentChatParams, AgentChatResult, TxIntent, PreparedTransaction, AgentXMarketplaceResult, AgentXAgentDetail, AgentXSubscriptionPlans, AgentXSubscriptionCheck, AgentXAgentContext, AgentXPublishParams, AgentXPublishResult, AgentXSkill, AgentXSkillCreateParams, AgentXAgentStatus, AgentXAgentUsage, AgentXSubscriptionList } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/**
+ * AgentApi — Reach 唯一 Agent 入口（P2.4.3 统一）。
+ *
+ * 吸收三侧方法面（A.5.2/A.2.3 AgentX 合版）：
+ * - S agent（网关 /api/v1/agents/*）：list / get / capabilities / chat / prepareTransaction
+ * - S agentx（server /api/agentx/* + /api/merchant/*）：链上市场 / 订阅 / 状态用量 / 发布 / 技能
+ * - A agents（server /api/agents/*）：marketplace → listMarketplace、run / clone
+ *
+ * 端点保持两侧现状（agent 走网关 /api/v1、agentx/agents 走 server），
+ * 待 2.4.5 统一网关后全部走网关（A.2.4：SDK 只走网关）。
+ * 统一 Agent 资源模型：S「Bot 可发布为 Agent」+ A「平台原生 Agent 市场」，见 A.2.5。
+ */
+export declare class AgentApi {
+    private gatewayRequest;
+    private serverRequest;
+    constructor(gatewayRequest: RequestFn, serverRequest: RequestFn);
+    /** 列出调用方可用的 agent（可按 projectId / type 过滤） */
+    list(params?: AgentListParams): Promise<AgentListResult>;
+    /** 获取单个 agent 详情 */
+    get(id: string): Promise<AgentSummary>;
+    /** 该 agent 支持什么：类型、可用链、可执行的链上操作类型 */
+    capabilities(id: string): Promise<AgentCapabilities>;
+    /** 直接与该 agent 对话（RAG + 交易构造由服务端完成，返回 transaction 载荷） */
+    chat(id: string, params: AgentChatParams): Promise<AgentChatResult>;
+    /** 构造链上交易（不签名；返回步骤/calldata，由调用方 wallet 弹窗确认） */
+    prepareTransaction(id: string, intent: TxIntent): Promise<PreparedTransaction>;
+    /** 运行一个 agent（A：平台原生 Agent 市场模式） */
+    run(id: string, message: string, skillNames?: string[]): Promise<any>;
+    /** 克隆 agent 到工作区 */
+    clone(id: string): Promise<any>;
+    /** 列出 AgentX 链上市场中的 Agent（吸收 A agents.marketplace → /api/agents/marketplace/search） */
+    listMarketplace(params?: {
+        page?: number;
+        pageSize?: number;
+        search?: string;
+        type?: string;
+    }): Promise<AgentXMarketplaceResult>;
+    /** 获取 AgentX Agent 详情 */
+    getAgent(agentId: number): Promise<AgentXAgentDetail>;
+    /** 获取 Agent 的订阅计划 */
+    getPlans(agentId: number): Promise<AgentXSubscriptionPlans>;
+    /** 检查用户对 Agent 的订阅状态 */
+    checkSubscription(agentId: number, subscriberAddress: string): Promise<AgentXSubscriptionCheck>;
+    /** 列出用户的所有订阅 */
+    listSubscriptions(subscriberAddress: string): Promise<AgentXSubscriptionList>;
+    /** 获取 Agent 运行状态（在线/离线/延迟等） */
+    getAgentStatus(agentId: number): Promise<AgentXAgentStatus>;
+    /** 获取 Agent 用量统计（调用次数、Token 消耗、活跃订阅者） */
+    getAgentUsage(agentId: number): Promise<AgentXAgentUsage>;
+    /** 加载 Agent 上下文（需要有效订阅） */
+    loadAgentContext(agentId: number, subscriberAddress: string): Promise<AgentXAgentContext>;
+    /** 将 Bot 发布到 AgentX 市场，返回链上交易参数 */
+    publishBot(projectId: string, botId: string, params?: AgentXPublishParams): Promise<AgentXPublishResult>;
+    /** 获取 Bot 的 A2A 技能列表 */
+    listSkills(projectId: string, botId: string): Promise<AgentXSkill[]>;
+    /** 给 Bot 添加 A2A 技能（链接到另一个 AgentX Agent） */
+    addSkill(projectId: string, botId: string, params: AgentXSkillCreateParams): Promise<AgentXSkill>;
+}
+export {};