@reachv2/sdk 0.3.3 → 0.4.0

package/dist/resources/merchant.js

@@ -0,0 +1,143 @@
+/**
+ * MerchantResource — 商户域（客服工作台 / 商户控制台）。
+ *
+ * 端点：Server API `/api/merchant/*`，全部要求 `role=merchant` 的 JWT
+ * （邮箱/钱包注册后需先 `auth.merchantOnboard()` 或接受商户邀请，见 v0.4.0 说明）。
+ *
+ * 注意：商户域直接返回 db 行（snake_case），与网关 `/api/v1` 的 camelCase 不同。
+ */
+export class MerchantResource {
+    constructor(request) {
+        this.request = request;
+    }
+    // ═══ 看板 / 工单 ═══
+    /** 商户看板（项目/Bot/会话/文档/token 配额 + 近 14 天趋势） */
+    dashboard() {
+        return this.request("GET", "/api/merchant/dashboard");
+    }
+    /** 转人工工单列表（近期 200 条） */
+    listTickets() {
+        return this.request("GET", "/api/merchant/tickets");
+    }
+    /** 更新工单状态 / 处理人（resolved 会同步会话状态） */
+    updateTicket(id, params) {
+        return this.request("PATCH", `/api/merchant/tickets/${encodeURIComponent(id)}`, params);
+    }
+    // ═══ 项目 / Bot ═══
+    /** 项目列表（含 bot_count / total_tokens / total_conversations 聚合） */
+    listProjects() {
+        return this.request("GET", "/api/merchant/projects");
+    }
+    /** 项目详情 */
+    getProject(projectId) {
+        return this.request("GET", `/api/merchant/projects/${encodeURIComponent(projectId)}`);
+    }
+    /** 新建项目（默认名「新项目」） */
+    createProject(params) {
+        return this.request("POST", "/api/merchant/projects", params);
+    }
+    /** 更新项目（name / description 等） */
+    updateProject(projectId, patch) {
+        return this.request("PATCH", `/api/merchant/projects/${encodeURIComponent(projectId)}`, patch);
+    }
+    /** 项目下 Bot 列表 */
+    listBots(projectId) {
+        return this.request("GET", `/api/merchant/projects/${encodeURIComponent(projectId)}/bots`);
+    }
+    /** 在项目下新建 Bot（type 由服务端固定为 support） */
+    createBot(projectId, params) {
+        return this.request("POST", `/api/merchant/projects/${encodeURIComponent(projectId)}/bots`, params);
+    }
+    /** 更新 Bot（name / prompt / status 等） */
+    updateBot(projectId, botId, patch) {
+        return this.request("PATCH", `/api/merchant/projects/${encodeURIComponent(projectId)}/bots/${encodeURIComponent(botId)}`, patch);
+    }
+    // ═══ Bot LLM 配置（BYOK / 平台托管） ═══
+    /** 读取 Bot 的 LLM 配置（未配置返回 null） */
+    getLlmConfig(projectId, botId) {
+        return this.request("GET", `/api/merchant/projects/${encodeURIComponent(projectId)}/bots/${encodeURIComponent(botId)}/llm-config`);
+    }
+    /** 写入 Bot 的 LLM 配置（BYOK） */
+    setLlmConfig(projectId, botId, params) {
+        return this.request("POST", `/api/merchant/projects/${encodeURIComponent(projectId)}/bots/${encodeURIComponent(botId)}/llm-config`, params);
+    }
+    /** 重置回平台托管 LLM */
+    resetLlmConfig(projectId, botId) {
+        return this.request("DELETE", `/api/merchant/projects/${encodeURIComponent(projectId)}/bots/${encodeURIComponent(botId)}/llm-config`);
+    }
+    // ═══ 链 ═══
+    /** 可用链列表（内置链 + 商户自定义链） */
+    listChains() {
+        return this.request("GET", "/api/merchant/chains");
+    }
+    /** 添加自定义链 */
+    addChain(params) {
+        return this.request("POST", "/api/merchant/chains", params);
+    }
+    /** 删除自定义链 */
+    removeChain(chainId) {
+        return this.request("DELETE", `/api/merchant/chains/${chainId}`);
+    }
+    // ═══ 团队（owner/admin 可管理） ═══
+    /** 团队成员列表（owner + 成员 + 待接受邀请） */
+    getTeam() {
+        return this.request("GET", "/api/merchant/team");
+    }
+    /** 直接加人（目标账户需已注册；email 或 wallet 二选一） */
+    addTeamMember(params) {
+        return this.request("POST", "/api/merchant/team/members", params);
+    }
+    /** 生成邀请（邮箱未注册亦可；受邀者登录后接受） */
+    createTeamInvite(params) {
+        return this.request("POST", "/api/merchant/team/invites", params);
+    }
+    /** 撤销未接受的邀请 */
+    revokeTeamInvite(token) {
+        return this.request("POST", `/api/merchant/team/invites/${encodeURIComponent(token)}/revoke`);
+    }
+    /** 修改成员角色 */
+    updateTeamMemberRole(accountId, role) {
+        return this.request("PUT", `/api/merchant/team/members/${encodeURIComponent(accountId)}`, { role });
+    }
+    /** 移除成员 */
+    removeTeamMember(accountId) {
+        return this.request("DELETE", `/api/merchant/team/members/${encodeURIComponent(accountId)}`);
+    }
+    // ═══ 权限 / 审计（governance） ═══
+    /** 当前账户在本商户的权限码 */
+    myPermissions() {
+        return this.request("GET", "/api/merchant/my-permissions");
+    }
+    /** 角色目录（RBAC） */
+    listRoles() {
+        return this.request("GET", "/api/merchant/roles");
+    }
+    /** 可分配角色选项 */
+    roleOptions() {
+        return this.request("GET", "/api/merchant/role-options");
+    }
+    /** 成员及其角色 */
+    listMembers() {
+        return this.request("GET", "/api/merchant/members");
+    }
+    /** 修改成员角色集合 */
+    updateMemberRoles(userId, roles) {
+        return this.request("PUT", `/api/merchant/members/${encodeURIComponent(userId)}/roles`, { roles });
+    }
+    /** 审计日志（action / resourceType / status / limit / offset） */
+    listAuditLogs(params = {}) {
+        const query = new URLSearchParams();
+        if (params.action)
+            query.set("action", params.action);
+        if (params.resourceType)
+            query.set("resourceType", params.resourceType);
+        if (params.status)
+            query.set("status", params.status);
+        if (params.limit != null)
+            query.set("limit", String(params.limit));
+        if (params.offset != null)
+            query.set("offset", String(params.offset));
+        const qs = query.toString();
+        return this.request("GET", `/api/merchant/audit-logs${qs ? `?${qs}` : ""}`);
+    }
+}

package/dist/types.d.ts

@@ -525,7 +525,7 @@ export interface AgentChatParams {
     conversationId?: string;
     /** 钱包地址：交易/综合 agent 构造链上操作时必填 */
     userAddress?: string;
-    /** 目标链 id（Ethereum/BNB/Polygon/Arbitrum/Base/Optimism/OxaChain 等） */
+    /** 目标链 id（Ethereum/BNB/Polygon/Arbitrum/Base/Optimism 等） */
     chainId?: number;
     agentxAgentId?: number;
     tools?: ChatToolDefinition[];
@@ -903,3 +903,242 @@ export interface HealthInfo {
     uptime?: number;
     [key: string]: unknown;
 }
+/** 商户入驻参数（POST /api/auth/merchant-onboard） */
+export interface MerchantOnboardParams {
+    /** 商户名称（owner 未绑定时用于创建商户） */
+    name: string;
+}
+/** 商户入驻 / 接受邀请结果：在 AuthResult 基础上追加绑定信息 */
+export interface MerchantAuthResult extends AuthResult {
+    merchantId?: string | number;
+    role?: string;
+    accepted?: boolean;
+    alreadyMember?: boolean;
+    alreadyProcessed?: boolean;
+}
+/** 公开商户邀请信息（GET /api/auth/merchant-invites/:token，登录前可读） */
+export interface MerchantInviteInfo {
+    merchant: {
+        id: string | number;
+        name: string;
+    };
+    email: string | null;
+    role: string;
+    status: string;
+}
+/** 发送邮箱验证码（POST /api/auth/email-code/send） */
+export interface EmailCodeSendResult {
+    sent: boolean;
+    ttlSec: number;
+}
+/** 验证码登录参数（POST /api/auth/email-code/login；启用 MFA 的账户需再带 mfaCode） */
+export interface EmailCodeLoginParams {
+    email: string;
+    code: string;
+    mfaCode?: string;
+}
+/** 当前账户 + 租户成员关系（GET /api/auth/me） */
+export interface AccountMeResult extends AuthAccount {
+    tenants: Array<{
+        id: string | number;
+        name: string;
+        slug: string;
+        role: string;
+    }>;
+}
+/** 商户看板（GET /api/merchant/dashboard；camelCase） */
+export interface MerchantDashboardStats {
+    projects: number;
+    bots: number;
+    totalTokens: number;
+    totalConversations: number;
+    documentsCount: number;
+    activeAgents: number;
+    plan: string;
+    planLabel?: string | null;
+    seatCount?: number | null;
+    planStartedAt?: string | null;
+    planExpiresAt?: string | null;
+    docLimit?: number | null;
+    tokenQuota?: number | null;
+    tokensUsedThisMonth?: number;
+    tokensRemaining?: number | null;
+    conversationTrend?: unknown[];
+    botDistribution?: unknown[];
+    quality?: unknown;
+    groupActivity?: unknown;
+}
+/** 转人工工单（GET /api/merchant/tickets，camelCase） */
+export interface MerchantTicket {
+    id: string;
+    conversationId: string | null;
+    botId: string | null;
+    merchantId: string;
+    channel: string | null;
+    title: string | null;
+    status: "open" | "in_progress" | "resolved" | "closed" | string;
+    handler: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MerchantTicketUpdateParams {
+    status?: "open" | "in_progress" | "resolved" | "closed";
+    handler?: string;
+}
+/** 商户项目（GET /api/merchant/projects；snake_case + 聚合计数） */
+export interface MerchantProject {
+    id: string;
+    name: string;
+    description?: string | null;
+    bot_count?: number;
+    total_tokens?: number;
+    total_conversations?: number;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+/** 商户 Bot（GET /api/merchant/projects/:id/bots；snake_case） */
+export interface MerchantBot {
+    id: string;
+    project_id: string;
+    name: string;
+    type?: string;
+    status?: string;
+    description?: string | null;
+    prompt?: string | null;
+    [key: string]: unknown;
+}
+export interface MerchantProjectCreateParams {
+    name: string;
+    description?: string;
+}
+export interface MerchantBotCreateParams {
+    name: string;
+    description?: string;
+    prompt?: string;
+}
+/** Bot LLM 配置（GET /api/merchant/.../llm-config 返回 snake_case；未配置时为 null） */
+export interface MerchantLlmConfig {
+    provider: string;
+    endpoint_url: string | null;
+    api_key: string | null;
+    model: string | null;
+}
+/** 写入 Bot LLM 配置（BYOK） */
+export interface MerchantLlmConfigInput {
+    provider: string;
+    endpointUrl?: string;
+    apiKey?: string;
+    model?: string;
+}
+export interface MerchantChain {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    explorerUrl?: string | null;
+    symbol?: string | null;
+    decimals?: number | null;
+    [key: string]: unknown;
+}
+export interface MerchantChainAddParams {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    explorerUrl?: string;
+    symbol?: string;
+    decimals?: number;
+}
+/** GET /api/merchant/chains */
+export interface MerchantChainList {
+    chains: MerchantChain[];
+    /** 自定义链 id 列表（内置链之外） */
+    custom: number[];
+}
+/** 可授予的商户团队角色（owner 仅商户所有者，不可授予） */
+export type MerchantTeamRole = "admin" | "editor" | "member" | "viewer";
+export interface MerchantTeamMember {
+    key: string;
+    accountId: string | null;
+    role: "owner" | MerchantTeamRole;
+    status: "active" | "invited" | string;
+    username: string | null;
+    email: string | null;
+    wallet: string | null;
+    joinedAt: string | null;
+    /** 仅 owner/admin 可见：待接受邀请的 token */
+    inviteToken?: string;
+}
+export interface MerchantTeamResult {
+    merchantId: string;
+    canManage: boolean;
+    members: MerchantTeamMember[];
+}
+export interface MerchantTeamMemberAddParams {
+    email?: string;
+    wallet?: string;
+    role?: MerchantTeamRole;
+}
+export interface MerchantTeamInviteParams {
+    email: string;
+    role?: MerchantTeamRole;
+}
+export interface MerchantTeamInviteResult {
+    ok: boolean;
+    id: string | number;
+    email: string;
+    role: MerchantTeamRole;
+    status: "invited" | string;
+    inviteToken: string;
+    inviteUrl: string;
+}
+/** 通道连接 / 状态结果（各平台字段不同，保留索引签名） */
+export interface ChannelActionResult {
+    success?: boolean;
+    status?: string;
+    message?: string;
+    qr?: string | null;
+    [key: string]: unknown;
+}
+export interface SendTextParams {
+    chatId: string;
+    text: string;
+}
+/** Telegram 文件发送：documentName 指向该 Bot 已上传的文档 */
+export interface TelegramSendFileParams {
+    chatId: string;
+    documentName: string;
+    caption?: string;
+}
+export interface DiscordDmParams {
+    userId: string;
+    text: string;
+    /** 默认 true：未 opt-in / 不可达则拒绝发送 */
+    enforceOptIn?: boolean;
+}
+export interface DiscordDmOptInParams {
+    userId: string;
+    status: "opted_in" | "revoked" | string;
+    source?: string;
+    note?: string;
+}
+export interface MerchantGroupList {
+    groups: Array<Record<string, unknown>>;
+    botRunning?: boolean;
+    botUsername?: string | null;
+    botConnected?: boolean;
+    [key: string]: unknown;
+}
+export interface EmailMailbox {
+    id: string;
+    botId: string;
+    address: string;
+    [key: string]: unknown;
+}
+export interface EmailMailboxCreateParams {
+    address: string;
+    [key: string]: unknown;
+}
+export interface EmailThreadList {
+    threads: Array<Record<string, unknown>>;
+    take: number;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reachv2/sdk",
-  "version": "0.3.3",
-  "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/ContentPlans 内容计划/PublishPlans 发布计划/BrowserTemplates 流程模板/AiMedia 视频脚本/Effect 效果追踪/SeoGeo SEO-GEO 矩阵/ContentRules 内容规则引擎/DataSources 数据源）+ 统一 DashboardApi（crm/social 看板）+ 统一租户成员模型（Tenants/Team/Health，G-1~G-3）",
+  "version": "0.4.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/ContentPlans 内容计划/PublishPlans 发布计划/BrowserTemplates 流程模板/AiMedia 视频脚本/Effect 效果追踪/SeoGeo SEO-GEO 矩阵/ContentRules 内容规则引擎/DataSources 数据源）+ 商户域（Merchant 控制台/ChannelAdmin 通道与群发/EmailChannel 邮件通道）+ 统一 DashboardApi（crm/social 看板）+ 统一租户成员模型（Tenants/Team/Health，G-1~G-3）",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,6 +18,7 @@
     "clean": "rm -rf dist",
     "build": "npm run clean && tsc",
     "test": "node --test",
+    "openapi": "node scripts/generate-openapi.mjs",
     "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [