@reachv2/sdk

Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer SDK（crm 域，18 资源）与 aiops-saas SDK（social 域，5 资源）合并而来（P2.4），现统一为 37 个资源类 / 287 个资源方法。一个客户端覆盖客服 / 销售引导、社群维护与社媒运营全部资源（含商户入驻与商户控制台、通道/群发、邮件通道、计费与配额、效果追踪、SEO/GEO、内容规则与数据源）。

• 运行时：Node.js >= 18（ESM）
• 类型：完整 TypeScript 类型定义（自带 dist/index.d.ts）
• License：MIT

文档

• API Reference（P2.6，v0.3.0 补 P-REACH 四域，v0.4.0 补商户/通道，v0.5.0 补计费/配额）：全部 37 个资源类 + ReachClient 共 287 个资源方法（另含 ReachClient.setToken / request）的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 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" });

// 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]);

// 2) 登录：返回 { accessToken, refreshToken, account }
const { accessToken } = await client.auth.login("[email protected]", "password", { token: captchaId, answer });
client.setToken(accessToken); // SDK 不会自动接线，需手动 setToken 切换为 JWT 模式

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/恢复码）重试。

认证方式

| 方式 | 配置 | 生效域 | |------|------|--------| | 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。

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，返回 { 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
• 工具规模：255（crm 87 + social 168），按域白名单裁剪（当前 crm / social），tools/list 返回实际可用集合

会话按 MCP Streamable HTTP 规范：先 initialize 取得 mcp-session-id， 再发 notifications/initialized，之后 tools/call，结束时 DELETE 会话。

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。

const client = new ReachClient({
  baseUrl: "https://reach.codes",   // 统一网关
  apiKey: "reach-xxx",
});

资源概览（client.*）

统一资源按 crm 域 / social 域 / 共享基础 组织（A.5.3）：

共享基础

| 资源 | 主要能力 | API 域 | |------|----------|--------| | client.auth | 验证码（getCaptcha）、登录、注册、钱包登录、邮箱验证码登录、商户入驻（merchantOnboard）/ 商户邀请、refresh / logout / me（MFA/SSO） | Server | | client.admin | 平台仪表盘、商户、计费、LLM 设置（需管理员 JWT） | Admin | | client.apiKeys | API Key 创建/列表/吊销 | Gateway | | 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 域 | |------|----------|--------| | client.agents | 统一 Agent 入口（AgentApi）：调用方 agent（list/get/capabilities/chat/prepareTransaction）+ 市场搜索（listMarketplace → /api/agents/marketplace/search）+ 市场 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；平台共享 namespace market / onchain 只读可查） | 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/create） | Server | | client.contentPlans | 内容计划（ContentPlansResource）：计划名 + 主题时间轴（list/create） | Server | | client.publishPlans | 发布计划（PublishPlansResource）：多站点分步编排，get 返回每步待审草稿，approve/reject 完成审批（list/get/approve/reject） | Server | | client.browserTemplates | 浏览器操作模板（BrowserTemplatesResource）：流程编排模板（list/update） | Server | | client.aiMedia | AI 媒体（AiMediaResource）：视频脚本生成（script） | Server |

social 域 — P-REACH（效果 / SEO-GEO / 内容规则 / 数据源，v0.3.0 新增）

| 资源 | 主要能力 | API 域 | |------|----------|--------| | client.effect | 效果追踪（EffectResource）：指标字典、日快照、汇总/ROI/归因/周报、告警、GEO 探针问题集（18 方法） | Server | | client.seoGeo | SEO/GEO 域（SeoGeoResource）：品牌档案 / 渠道集 / 内容矩阵（草稿→发布→回采）/ GEO 资产（24 方法） | Server | | client.contentRules | 内容规则引擎（ContentRulesResource）：规则 CRUD + 发布前打分/优化 + 发布后效果/GEO 评估 + 记录趋势（12 方法） | Server | | client.dataSources | 数据源适配器（DataSourcesResource）：指标明细 / 趋势（2 方法；其余 CRUD/适配器/同步/告警/调度已于 2026-09-19 下线） | Server |

商户域 — P0（入驻 / 控制台 / 通道，v0.4.0 新增）

| 资源 | 主要能力 | API 域 | |------|----------|--------| | client.merchant | 商户控制台（MerchantResource）：看板/工单、项目与 Bot、Bot LLM 配置（BYOK）、自定义链、团队与邀请、RBAC 权限/成员/审计（28 方法） | Server | | client.channelAdmin | 通道管理（ChannelAdminResource）：通道总览、Telegram / WhatsApp / Discord 连接与发消息、群组管理与群发、项目级异步群发任务（33 方法；不含 multipart upload-send） | Server | | client.emailChannel | 客服邮件通道（EmailChannelResource）：邮箱账号 CRUD、SMTP 发信、IMAP 拉取、原始邮件投递、邮件线程（10 方法） | Server |

/api/merchant/* 全部要求 JWT 带 role=merchant：邮箱/钱包注册后需先 client.auth.merchantOnboard({ name }) 或接受商户邀请（client.auth.acceptMerchantInvite(token)），再 setToken(返回的 accessToken)。 商户域直接返回 db 行（多为 snake_case），与网关 /api/v1 的 camelCase 不同。

计费 / 配额 — P1（v0.5.0 新增）

| 资源 | 主要能力 | API 域 | |------|----------|--------| | client.billing | 社媒域计费（BillingResource）：套餐 / Token 包 / 价格（公开）、Token 包购买（Stripe Checkout，未配置时落 pending）、Customer Portal、浏览器实例配额与购买流水（7 方法） | Server | | client.sharedBilling | 统一计费（SharedBillingResource）：订阅列表 / 当前订阅与本月用量、用量记账、Token 包购买（支持推广余额抵扣）、加密收款（通道 / 下单 / 列表 / 详情 / 取消 / 确认）（12 方法） | Server | | client.quota | 社媒域本月配额（QuotaResource）：copywriting / tts / video / poster 的 limit / used / remaining / allowed（1 方法） | Server |

两个计费资源路径不同：client.billing → /api/billing/*（社媒域），client.sharedBilling → /api/shared/billing/*（统一账本）。 订阅 / 用量 / 加密收款需 账户 JWT + 租户成员，tenantId 显式传参；plans / token-packs / prices / crypto/methods 公开。 已退役端点未封装：POST /api/billing/checkout 与 POST /api/shared/billing/subscriptions 恒 410（新购走 /api/seats）； webhook / payments-events 为服务端验签回调，不属于 SDK 调用面。

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）、市场（server /api/agents/marketplace/search：listMarketplace）与 A agents（server /api/agents/*：run/clone）。/api/agentx/* 服务端未挂载，相关方法已于 v0.4.0 移除。统一 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     # clean + tsc → dist
npm test          # node --test，覆盖 test/*.test.mjs

| 测试文件 | 覆盖 | |----------|------| | test/client.test.mjs | ReachClient 核心行为：构造校验（MISSING_AUTH）、认证 Header、双 base 路由、body 序列化、错误语义 | | test/resources.test.mjs | 全量 37 资源类 287 方法的 method / path / body 断言（要求每个方法至少被一条用例覆盖） | | test/smoke.test.mjs | 导出面 + 资源方法面快照 |

测试跑 dist/ 产物，改完 src/ 必须先 npm run build。

发布流程（维护者）

cd sdk
npm version <minor> --no-git-tag-version   # 小版本递增，紧贴 API 变更
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>"