@reachv2/sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,793 @@
+export interface ReachClientConfig {
+    apiKey?: string;
+    token?: string;
+    baseUrl: string;
+    /** Server API base URL (defaults to baseUrl). Used for auth, agentx, chat endpoints. */
+    serverBaseUrl?: string;
+}
+export type BotType = "customer_service" | "sales" | "custom" | "transaction";
+/** Agent 类型（bot.type 直通：support/sales/custom/transaction/omnichat/internal） */
+export type AgentType = "support" | "sales" | "custom" | "transaction" | "omnichat" | "internal";
+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 interface Pagination {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+}
+export interface PaginatedResponse<T> {
+    items: T[];
+    pagination: Pagination;
+}
+export interface Project {
+    id: string;
+    name: string;
+    description: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ProjectCreateParams {
+    name: string;
+    description?: string;
+}
+export interface ProjectUpdateParams {
+    name?: string;
+    description?: string;
+}
+export interface TransactionBotConfig {
+    chains: number[];
+    allowUnknownContracts: boolean;
+    enableSimulation: boolean;
+}
+export interface Bot {
+    id: string;
+    projectId: string;
+    name: string;
+    type: BotType;
+    status: BotStatus;
+    prompt: string;
+    welcomeMessage?: string;
+    config?: TransactionBotConfig;
+    stats: BotStats;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface BotStats {
+    conversations: number;
+    tokens: number;
+}
+export interface BotCreateParams {
+    projectId: string;
+    name: string;
+    type: BotType;
+    prompt: string;
+    welcomeMessage?: string;
+    config?: TransactionBotConfig;
+}
+export interface BotUpdateParams {
+    name?: string;
+    type?: BotType;
+    prompt?: string;
+    welcomeMessage?: string;
+}
+export interface KnowledgeDoc {
+    id: string;
+    botId: string;
+    title: string;
+    fileName: string;
+    format: string;
+    size: number;
+    status: KnowledgeStatus;
+    createdAt: string;
+}
+export interface KnowledgeRecommendation {
+    botType: BotType;
+    title: string;
+    description: string;
+}
+export interface Channel {
+    id: string;
+    botId: string;
+    type: ChannelType;
+    status: ChannelStatus;
+    token?: string;
+    widgetId?: string;
+    embedCode?: string;
+    qrCode?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ChannelConfigureParams {
+    type: ChannelType;
+    token?: string;
+}
+export interface Conversation {
+    id: string;
+    botId: string;
+    channel: ChannelType;
+    status: "active" | "closed" | "transferred";
+    messageCount: number;
+    lastMessage?: string;
+    lastMessageAt?: string;
+    createdAt: string;
+}
+export interface Message {
+    id: string;
+    conversationId: string;
+    role: "user" | "bot" | "human";
+    content: string;
+    createdAt: string;
+}
+export interface ChatToolFunction {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface ChatToolDefinition {
+    type: 'function';
+    function: ChatToolFunction;
+    /** HTTP endpoint reach server POSTs {tool, arguments} to for execution */
+    callback_url: string;
+    /** Optional secret key for callback verification (sent as X-Tool-Key header) */
+    callback_key?: string;
+}
+export interface ChatParams {
+    message: string;
+    conversationId?: string;
+    tools?: ChatToolDefinition[];
+}
+export interface ChatResponse {
+    message: string;
+    conversationId: string;
+}
+export interface DashboardData {
+    projectCount: number;
+    botCount: number;
+    totalConversations: number;
+    totalTokens: number;
+    activeConversations: number;
+    bots: BotMetrics[];
+}
+export interface BotMetrics {
+    botId: string;
+    botName: string;
+    type: BotType;
+    status: BotStatus;
+    conversations: number;
+    tokens: number;
+}
+export interface TxIntent {
+    message: string;
+    userAddress: string;
+    chainId?: number;
+    context?: string;
+    /**
+     * 链上操作类型：显式指定常见操作（mint / vote / stake / claim / transfer / approve 等）
+     * 或租户 ABI 的函数名（如 "transferToken"）/ 协议 action 的 id/name。
+     * 不传则服务端走自然语言解析；常见取值见 capabilities().actions[].action。
+     */
+    action?: string;
+    /** 目标合约地址（0x 开头 40 位 hex；配租户 ABI / common-ops 精确指定目标合约） */
+    contractAddress?: string;
+    /** 协议 id：common-ops / tenant-{abiId}（来自 capabilities().actions[].protocol） */
+    protocolId?: string;
+    /** 操作函数参数（按 ABI 签名命名，如 { amount: '1000000', to: '0x...' }；不传则服务端从消息解析） */
+    params?: Record<string, string>;
+}
+export interface TxStep {
+    label: string;
+    to: string;
+    value: string;
+    data: string;
+    gasLimit?: string;
+}
+export interface PreparedTransaction {
+    txId: string;
+    description: string;
+    steps: TxStep[];
+    sequential: boolean;
+    chainId: number;
+    /** 命中的协议 id（common-ops / tenant-{abiId}），供调用方核对 */
+    protocolId?: string;
+    /** 命中的链上操作类型（mint/vote/stake/claim 或租户 ABI 函数名） */
+    actionId?: string;
+    /** 实际编码的目标合约地址 */
+    contractAddress?: string;
+    warnings: string[];
+    expiresAt: number;
+}
+export interface ContractInfo {
+    address: string;
+    abi: unknown[];
+    name?: string;
+    methods: ContractMethod[];
+}
+export interface ContractMethod {
+    name: string;
+    signature: string;
+    inputs: {
+        name: string;
+        type: string;
+    }[];
+    outputs: {
+        name: string;
+        type: string;
+    }[];
+    stateMutability: string;
+}
+export interface SimulationResult {
+    success: boolean;
+    gasUsed: string;
+    logs?: string[];
+    error?: string;
+}
+export interface DecodedCalldata {
+    methodName: string;
+    methodSignature: string;
+    params: Record<string, unknown>;
+    rawParams: unknown[];
+}
+export interface ProtocolSummary {
+    id: string;
+    name: string;
+    description: string;
+    chains: number[];
+    actions: string[];
+}
+export interface ProtocolRegistryEntry {
+    id: string;
+    name: string;
+    description: string;
+    deployments: ChainDeployment[];
+    actions: ProtocolAction[];
+}
+export interface ChainDeployment {
+    chainId: number;
+    contracts: Record<string, string>;
+}
+export interface ProtocolAction {
+    id: string;
+    name: string;
+    description: string;
+    contractRef: string;
+    functionSignature: string;
+    payable: boolean;
+    requiresApproval?: {
+        tokenContractRef: string;
+        spenderContractRef: string;
+    };
+    paramHints: ParamHint[];
+    prerequisites?: ProtocolAction[];
+}
+export interface ParamHint {
+    name: string;
+    type: string;
+    description: string;
+    source: "user_input" | "derived" | "user_address" | "computed";
+    computeHint?: string;
+}
+export interface WalletChallenge {
+    challenge: string;
+    timestamp: number;
+    nonce: string;
+}
+export interface WalletLoginParams {
+    walletAddress: string;
+    signature: string;
+    timestamp: number;
+    nonce: string;
+}
+export interface AuthResult {
+    token: string;
+    user: {
+        id: string;
+        username: string;
+        role: string;
+        name: string;
+        email: string;
+        walletAddress?: string;
+    };
+}
+/** 数学验证码（login/register 前置）：svg 为 data URI，算式恒为非负结果 */
+export interface CaptchaResponse {
+    token: string;
+    svg: string;
+    expiresIn: number;
+}
+/** 验证码作答参数（服务端校验通过才放行登录/注册） */
+export interface CaptchaAnswer {
+    token: string;
+    answer: number;
+}
+export interface AgentXAgent {
+    id: number;
+    owner: string;
+    tokenURI: string;
+    name: string;
+    status: string;
+}
+export interface AgentXAgentDetail {
+    id: number;
+    owner: string;
+    tokenURI: string;
+    name: string;
+    status: string;
+    description?: string;
+}
+export interface AgentXMarketplaceResult {
+    agents: AgentXAgent[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export interface AgentXSubscriptionPlans {
+    plans: any[];
+}
+export interface AgentXSubscriptionCheck {
+    active: boolean;
+}
+export interface AgentXAgentContext {
+    agentId: number;
+    prompt: string;
+    skills: any[];
+    mcp: any;
+    owner?: string;
+    error?: string;
+}
+export interface AgentXPublishParams {
+    skills?: any[];
+    mcpUrl?: string;
+}
+export interface AgentXPublishResult {
+    success: boolean;
+    needsWallet: boolean;
+    message: string;
+    contractAddress: string;
+    contractAbi: string;
+    functionName: string;
+    args: string[];
+    value: string;
+    botId: string;
+    tokenURI: string;
+}
+export interface AgentXSkill {
+    id: number;
+    bot_id: string;
+    skill_name: string;
+    target_agent_id: number;
+    skill_filter: string[];
+    prompt_override: string;
+    is_active: boolean;
+    created_at: string;
+}
+export interface AgentXSkillCreateParams {
+    skillName: string;
+    targetAgentId: number;
+    skillFilter?: string[];
+    promptOverride?: string;
+}
+export interface AgentXAgentStatus {
+    agentId: number;
+    name: string;
+    owner: string;
+    status: 'online' | 'offline' | 'degraded' | 'unreachable' | 'error' | 'unknown';
+    pingMs: number | null;
+    lastSeen: string | null;
+    onChainStatus: string;
+    message?: string;
+}
+export interface AgentXAgentUsage {
+    agentId: number;
+    totalCalls: number;
+    totalTokens: number;
+    activeSubscribers: number;
+    dailyCalls: {
+        date: string;
+        calls: number;
+    }[];
+}
+export interface AgentXSubscriptionDetail {
+    agentId: number;
+    name: string;
+    owner: string;
+    status: string;
+    subscribedAt: string | null;
+}
+export interface AgentXSubscriptionList {
+    subscriptions: AgentXSubscriptionDetail[];
+    total: number;
+}
+export interface ServerChatParams {
+    message: string;
+    projectId?: string;
+    botId?: string;
+    useAgentLoop?: boolean;
+    userAddress?: string;
+    chainId?: number;
+    tools?: ChatToolDefinition[];
+    /**
+     * 用户自定义 LLM API Key（BYOK，可选）。
+     * 携带时：该次对话使用调用方自己的 Key 调用 LLM，不消耗商户配额；
+     * 未携带时：使用 Bot 配置的 provider（如有）或平台 LLM（按套餐配额）。
+     */
+    llmApiKey?: string;
+    /** 与 llmApiKey 配套的可选 LLM 端点（OpenAI 兼容 /v1，默认平台端点） */
+    llmEndpoint?: string;
+    /** 与 llmApiKey 配套的可选模型名（默认平台模型） */
+    llmModel?: string;
+}
+/** 单次对话 token 用量明细 */
+export interface ChatUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+/** 按用户地址的 token 用量汇总（日维度） */
+export interface ChatUsageSummary {
+    userAddress: string;
+    days: number;
+    daily: {
+        day: string;
+        tokens_in: string;
+        tokens_out: string;
+        calls: string;
+    }[];
+    totals: {
+        tokensIn: number;
+        tokensOut: number;
+        calls: number;
+    };
+}
+export interface ServerChatResponse {
+    reply: string;
+    conversationId?: string;
+    tokensUsed?: number;
+    /** 本次对话真实 token 用量明细（input/output 拆分，用于成本核算） */
+    usage?: ChatUsage;
+    agentLoopUsed?: boolean;
+    toolsCalled?: boolean;
+    transaction?: PreparedTransaction;
+    /** 错误码：A2A 编排命中无订阅子 agent 时为 'a2a_agent_not_accessible'（HTTP 403）；LLM Key 无效为 'LLM_KEY_INVALID'（HTTP 400） */
+    error?: string;
+    /** 结构化错误码（如 'LLM_KEY_INVALID' / 'LLM_UPSTREAM_ERROR'） */
+    code?: string;
+    /** 订阅引导地址：配合 error 返回（如 /api/agentx/agents/{agentId}/plans） */
+    subscribeUrl?: string;
+    /** A2A 编排识别的意图（orchestrated 时返回） */
+    intent?: string;
+    /** A2A 编排命中的目标子 agent（orchestrated 时返回） */
+    targetAgentId?: string;
+}
+export interface AgentSummary {
+    id: string;
+    name: string;
+    type: AgentType;
+    description: string;
+    status: string;
+    projectId: string;
+    merchantId: string;
+    prompt: string;
+    agentxAgentId: number | null;
+    stats: {
+        conversations: number;
+        tokens: number;
+    };
+    createdAt: string;
+}
+export interface AgentListResult {
+    agents: AgentSummary[];
+    total: number;
+}
+export interface AgentListParams {
+    projectId?: string;
+    type?: AgentType;
+}
+export interface AgentChainInfo {
+    chainId: number;
+    name: string;
+    rpcUrl: string;
+    explorerUrl?: string;
+    symbol: string;
+    decimals: number;
+}
+export interface AgentActionType {
+    protocol: string;
+    protocolName: string;
+    action: string;
+    name: string;
+    description: string;
+    signature: string;
+    payable: boolean;
+    /** 目标合约地址（seed 协议部署或租户 ABI 配置的合约；common-ops 无部署时为 null） */
+    contractAddress?: string | null;
+    /** 租户 ABI 配置 id（protocol 为 tenant-{abiId} 时存在；配合 TxIntent.protocolId 精确调用） */
+    abiId?: string;
+}
+export interface AgentCapabilities {
+    type: AgentType;
+    name: string;
+    description: string;
+    chains: AgentChainInfo[];
+    actions: AgentActionType[];
+}
+export interface AgentChatParams {
+    message: string;
+    conversationId?: string;
+    /** 钱包地址：交易/综合 agent 构造链上操作时必填 */
+    userAddress?: string;
+    /** 目标链 id（Ethereum/BNB/Polygon/Arbitrum/Base/Optimism/OxaChain 等） */
+    chainId?: number;
+    agentxAgentId?: number;
+    tools?: ChatToolDefinition[];
+}
+export interface AgentChatResult {
+    reply: string;
+    model?: string;
+    tokensUsed?: number;
+    /** 交易/综合 agent 的链上操作载荷（不签名，由调用方 wallet 弹窗确认） */
+    transaction?: PreparedTransaction;
+}
+/** 商户租户合约 ABI 记录（POST /api/merchant/abis 返回的 row 结构） */
+export interface MerchantAbi {
+    id: string;
+    merchant_id: string;
+    name: string;
+    chain_id: number;
+    contract_address: string;
+    abi: unknown[];
+    description?: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** 新增 ABI 参数（对应 POST /api/merchant/abis body） */
+export interface MerchantAbiCreateParams {
+    name: string;
+    chainId: number;
+    contractAddress: string;
+    abi: unknown[];
+    description?: string;
+}
+export interface LightRAGKeyInfo {
+    id: string;
+    tenant_id: string;
+    name: string;
+    key_prefix: string;
+    created_at: string;
+    last_used_at?: string;
+    expires_at?: string;
+    active: boolean;
+}
+export interface LightRAGDocumentParams {
+    text: string;
+    file_name?: string;
+    /** Per-user namespace within a bot (defaults to botId = shared) */
+    namespace?: string;
+}
+export interface LightRAGQueryParams {
+    query: string;
+    mode?: "mix" | "local" | "global" | "hybrid" | "naive";
+    /** Per-user namespace within a bot (defaults to botId = shared) */
+    namespace?: string;
+}
+export interface LightRAGQueryResult {
+    context: string;
+    mode: string;
+    tenant?: string;
+    namespace?: string;
+}
+export interface LightRAGBatchItem {
+    file_name: string;
+    doc_id?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface LightRAGBatchError {
+    file_name: string;
+    error: string;
+}
+export interface LightRAGBatchResult {
+    /** 成功上传的文档数 */
+    count: number;
+    /** 整体状态：uploaded（全部成功）/ partial（部分失败）/ failed（全部失败） */
+    status: "uploaded" | "partial" | "failed";
+    /** 成功上传的文档明细 */
+    documents: LightRAGBatchItem[];
+    /** 失败项明细 */
+    errors: LightRAGBatchError[];
+}
+export interface GlobalAnalytics {
+    botCount: number;
+    activeBots: number;
+    totalConversations: number;
+    totalTokens: number;
+    bots: BotMetrics[];
+}
+export interface AdminDashboard {
+    merchants: number;
+    activeMerchants: number;
+    projects: number;
+    totalTokens: number;
+    totalConversations: number;
+    activeBots: number;
+    revenue: number;
+    monthlyRevenue: {
+        month: string;
+        revenue: number;
+    }[];
+    monthlyUsers: {
+        month: string;
+        users: number;
+    }[];
+}
+export interface AdminMerchant {
+    id: string;
+    username: string;
+    name: string;
+    email: string;
+    agentId: string;
+    plan: string;
+    status: string;
+    createdAt: string;
+    projectsCount: number;
+    totalTokens: number;
+    totalConversations: number;
+}
+export interface AdminMerchantDetail extends AdminMerchant {
+    projects: Project[];
+}
+export interface AdminBillingRecord {
+    id: string;
+    merchantId: string;
+    merchantName: string;
+    plan: string;
+    amount: number;
+    status: string;
+    date: string;
+    description: string;
+}
+export interface AdminCreateBillingParams {
+    merchantId: string;
+    merchantName?: string;
+    plan: string;
+    amount: number;
+    status?: string;
+    description?: string;
+}
+export interface LlmSettings {
+    provider: string;
+    model: string;
+    api_key: string;
+    base_url: string;
+}
+export interface LlmUpdateParams {
+    provider?: string;
+    model?: string;
+    api_key: string;
+    base_url?: string;
+}
+export type ConversationTaskStatus = "queued" | "running" | "done" | "error" | "cancelled";
+/** AgentX 后台任务（创建后异步执行，轮询 status/result） */
+export interface ConversationTask {
+    id: string;
+    sessionId: string;
+    tenant: string;
+    agentId?: number | null;
+    endUserId?: string | null;
+    message: string;
+    status: ConversationTaskStatus;
+    enableMemory: boolean;
+    prompt?: string | null;
+    skills?: unknown;
+    result?: string | null;
+    error?: string | null;
+    usage?: unknown;
+    iterations?: number | null;
+    createdAt: string;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+}
+/** 会话：多个任务的容器（AgentX 侧持久化） */
+export interface ConversationSession {
+    id: string;
+    tenant: string;
+    agentId?: number | null;
+    endUserId?: string | null;
+    title?: string | null;
+}
+export interface ConversationCapabilities {
+    parallelTasks: boolean;
+    parallelTasksOverride: boolean | null;
+    mode?: string;
+}
+export interface ConversationMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface OrchestrationTaskParams {
+    /** AgentX agent id（缺省时可用 prompt/skills 走 inline 模式） */
+    agentId?: number;
+    message: string;
+    /** Inline 系统提示词 */
+    prompt?: string;
+    /** Inline 技能（MCP/HTTP 工具定义） */
+    skills?: Record<string, unknown>[];
+    enableMemory?: boolean;
+    history?: ConversationMessage[];
+}
+export interface OrchestrateParams {
+    /** 缺省时自动创建会话 */
+    sessionId?: string;
+    tasks: OrchestrationTaskParams[];
+    enableMemory?: boolean;
+}
+export interface OrchestratedTaskResult {
+    agentId?: number | null;
+    taskId: string | null;
+    status: string;
+    ok: boolean;
+    error?: string;
+    code?: string;
+}
+export interface OrchestrateResult {
+    sessionId: string;
+    tasks: OrchestratedTaskResult[];
+    parallelTasksEnabled: boolean;
+}
+export type ScheduledTaskTriggerType = "once" | "cron";
+export type ScheduledTaskStatus = "active" | "running" | "completed" | "cancelled" | "failed";
+export interface ScheduledTask {
+    id: string;
+    botId: string;
+    projectId: string;
+    merchantId: string;
+    agentId?: number | null;
+    description: string;
+    message: string;
+    triggerType: ScheduledTaskTriggerType;
+    cronExpr?: string | null;
+    runAt?: string | null;
+    status: ScheduledTaskStatus;
+    nextRunAt?: string | null;
+    lastRunAt?: string | null;
+    lastResult?: {
+        ok?: boolean;
+        reply?: string;
+        error?: string;
+        model?: string;
+        at?: string;
+    } | null;
+    runCount: number;
+    createdAt: string;
+}
+export type MonitorConnectorKind = "http_poll" | "webhook" | "local";
+export interface EnterpriseDoc {
+    id: string;
+    merchant_id: string;
+    name: string;
+    file_size: number;
+    created_at: string;
+}
+export interface MonitorConnector {
+    id: string;
+    bot_id: string;
+    merchant_id: string;
+    kind: MonitorConnectorKind;
+    name: string;
+    config: Record<string, unknown>;
+    status: string;
+    last_poll_at: string | null;
+    last_event_at: string | null;
+    created_at: string;
+}
+export interface MonitorEvent {
+    id: number;
+    connector_id: string | null;
+    bot_id: string;
+    merchant_id: string;
+    source: string;
+    payload: Record<string, unknown>;
+    received_at: string;
+}