@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（P2.6）：全部 20 个资源类 + ReachClient 共 120 个方法的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 sdk/src 源码一一对应。

安装

npm install @reachv2/sdk

快速开始

方式一：API Key（推荐，服务端 / 简单集成）

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 登录（需数学验证码）

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。

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 轮循环。

开发 / 测试

cd sdk
npm install
npm run build     # tsc → dist
npm test          # node --test test/（冒烟：导出 + 资源方法面）

发布流程（维护者）

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>"