<!-- qveris-sdk-release: js-sdk-v0.4.0 -->

QVeris TypeScript SDK

类型化的 TypeScript/JavaScript SDK，让你在自己的 Agent 和应用中发现、检查、调用并审计 10,000+ 真实已验证的 API 能力。

@qverisai/sdk v0.4.0 是最新测试版本。它是对 QVeris REST API（discover、inspect、call、credits、usage、ledger）的轻量类型化封装，零运行时依赖——使用平台原生 fetch（Node.js 18+）——并与 Python SDK 和 MCP 服务器 保持一致的通信语义。

安装

npm install @qverisai/sdk

需要 Node.js 18+（原生 fetch）。该包仅支持 ESM。

认证

SDK 从环境变量 QVERIS_API_KEY 读取 API 密钥，并通过 QVERIS_BASE_URL 指向 API 地址。请设置：

export QVERIS_API_KEY="your-api-key"
export QVERIS_BASE_URL="https://qveris.cn/api/v1"

在控制台/API密钥中创建密钥。可从环境变量创建客户端，也可以显式传入配置：

import { Qveris } from '@qverisai/sdk';

const qveris = Qveris.fromEnv();
// 或
const explicit = new Qveris({
  apiKey: 'your-api-key',
  baseUrl: 'https://qveris.cn/api/v1',
});

API 地址优先级为：显式 baseUrl > QVERIS_BASE_URL。API key 不参与地址选择；请按上面的示例设置地址。

快速开始

核心工作流是 discover → inspect → call，然后可选地审计发生了什么。所有方法都返回 Promise。

import { Qveris } from '@qverisai/sdk';

const qveris = Qveris.fromEnv();

// 1. 用自然语言发现能力（免费）
const discovered = await qveris.discover('weather forecast API', { limit: 5 });
const tool = discovered.results[0];

// 2. 检查所选能力的完整参数
const inspected = await qveris.inspect(tool.tool_id, { searchId: discovered.search_id });
const selected = inspected.results[0];

// 3. 调用（可能消耗积分）
const params = selected.examples?.sample_parameters ?? { city: 'London' };
const result = await qveris.call(selected.tool_id, {
  parameters: params,
  searchId: discovered.search_id,
  maxResponseSize: 20480,
});
console.log(result.success, result.result);

// 4. 审计最终扣费结果
const usage = await qveris.usage({ execution_id: result.execution_id, summary: true });
const ledger = await qveris.ledger({ summary: true, limit: 5 });
console.log(usage.total, ledger.total);

客户端基于 fetch、无状态，无需手动关闭连接。

配置参考

new Qveris(config) 接受：

字段	环境变量	默认值	说明
apiKey	QVERIS_API_KEY	—（必填）	API 密钥，以 Authorization: Bearer ... 发送
baseUrl	QVERIS_BASE_URL	按上文设置	API 基础地址；构造参数优先级最高
timeoutMs	—	30000	默认请求超时（call 默认 120000）

Qveris.fromEnv(overrides?) 从 QVERIS_API_KEY 构建客户端，并接受相同的非密钥选项。

API 参考

Qveris

方法	REST 端点	用途
discover(query, options?)	POST /search	用自然语言发现能力（免费）
inspect(toolIds, options?)	POST /tools/by-ids	获取能力完整元数据（免费）
call(toolId, options)	POST /tools/execute	执行能力（可能消耗积分）
credits()	GET /auth/credits	当前积分余额与分桶
usage(filters?)	GET /auth/usage/history/v2	审计请求状态与扣费结果
ledger(filters?)	GET /auth/credits/ledger	查看最终积分余额变动

选项结构：

• discover(query, { limit?, sessionId?, timeoutMs? })
• inspect(toolIds, { searchId?, sessionId?, timeoutMs? }) —— toolIds 接受单个字符串或数组；空数组会短路，直接返回空响应而不发起网络请求。
• call(toolId, { parameters, searchId?, sessionId?, maxResponseSize?, timeoutMs? })

usage(...) 和 ledger(...) 接受过滤对象，如 start_date、end_date、summary、bucket、charge_outcome、execution_id、search_id、direction、entry_type、min_credits、max_credits、limit、page、page_size。

类型化响应

所有方法返回与公开 OpenAPI 合同对齐的类型化结果。未知的后端字段会透传，因此新增的 API 元数据不会破坏旧版 SDK 客户端。

• 发现 / 检查：SearchResponse → results: ToolInfo[]；ToolInfo 含 tool_id、name、description、categories（对象或字符串）、capabilities、params、examples、stats、billing_rule、expected_cost，以及（仅 discover）why_recommended。
• 调用：ExecuteResponse，含 execution_id、success、result、error_message、billing（CompactBillingStatement）、cost、remaining_credits。
• 用量审计：UsageEventsResponse → items: UsageEventItem[]、total、summary。
• 积分账本：CreditsLedgerResponse → items: CreditsLedgerItem[]、total、summary。

import type { ExecuteResponse } from '@qverisai/sdk';

function explain(result: ExecuteResponse): string {
  if (!result.success) return `failed: ${result.error_message}`;
  const charged = result.billing?.summary ?? 'no billing info';
  return `ok (${charged}); remaining=${result.remaining_credits}`;
}

接入你自己的 Agent 循环

类型化客户端天然可作为任何 LLM Agent 框架的工具后端：把 discover / inspect / call 作为工具暴露给模型，再把工具调用路由回客户端。由于 discover 返回 why_recommended 和 expected_cost，你的 Agent 可以在调用前对能力进行排序和预算控制。

框架集成

Vercel AI SDK

把 QVeris 工作流暴露为 Vercel AI SDK 工具。ai 和 zod 是 peer 依赖（从 @qverisai/sdk/ai 子路径导入）：

npm install @qverisai/sdk ai zod

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { Qveris } from '@qverisai/sdk';
import { getQverisTools } from '@qverisai/sdk/ai';

const qveris = new Qveris({
  apiKey: process.env.QVERIS_API_KEY!,
  baseUrl: 'https://qveris.cn/api/v1',
});
const { text } = await generateText({
  model: openai('gpt-4o'),
  tools: getQverisTools(qveris), // qveris_discover / qveris_inspect / qveris_call
  maxSteps: 6,
  prompt: 'Find a stock quote capability and quote AAPL.',
});

Python SDK 还提供 LangChain 和 OpenAI Agents SDK 适配器。

错误处理

每个失败请求都会抛出 QverisApiError——一个 Error 子类，携带：

属性	说明
status	HTTP 状态码（0 网络错误，408 超时，402 积分不足，……）
details	服务端返回的错误体（如有）
observability	请求上下文（operation、endpoint、request id），用于诊断
cause	更底层的传输/运行时原因（如有）

import { Qveris, QverisApiError } from '@qverisai/sdk';

const qveris = Qveris.fromEnv();
try {
  await qveris.call('some.tool.v1', { parameters: {} });
} catch (err) {
  if (err instanceof QverisApiError && err.status === 402) {
    // 积分不足 —— err.message 含购买链接
  }
}

result.success 只反映能力调用本身。不要把它当作最终扣费结果——请用 usage(...) / ledger(...) 确认扣费。

兼容性

• Node.js >=18（原生 fetch）。仅 ESM。
• 响应类型与公开方法尽量遵循增量兼容。
• 破坏性变更需要主版本号提升并附迁移说明。

@qverisai/sdk 的 0.1.x 版本是早期以 MCP 为中心的 SDK，现已被 @qverisai/mcp 取代。本文档所述的类型化 REST 客户端从 0.2.0 起。

链接

• 包：npm 上的 @qverisai/sdk
• 源码：packages/js-sdk
• REST API：rest-api.md
• 获取 API 密钥：控制台/API密钥