@qverisai/sdk 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `@qverisai/sdk` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-09
+
+### Added
+
+- Vercel AI SDK adapter: `getQverisTools(qveris)` from `@qverisai/sdk/ai` returns `qveris_discover` / `qveris_inspect` / `qveris_call` tools for `generateText`/`streamText` (`ai` and `zod` as optional peer dependencies). ([#134])
+- Rate-limited (`429`) and transient (`503`) responses are retried automatically: honors `Retry-After`, otherwise exponential backoff with jitter, bounded by the `maxRetries` config option (default 3; `0` disables); `rateLimitRetryCount` exposes the backoff. ([#143])
+
+## [0.2.0] - 2026-07-06
+
+### Added
+
+- First release of the typed QVeris REST client: `discover` / `inspect` / `call` / `credits` / `usage` / `ledger`, zero dependencies (native fetch, Node 18+). ([#106])
+- Wire semantics aligned with the Python SDK and MCP server: success-envelope unwrapping, region auto-detection from the key prefix, structured `QverisApiError` with observability context.
+- Response types cover category objects, capability descriptors, `why_recommended`, and `expected_cost`.
+
+### Note
+
+- `0.1.x` under this npm name was an early MCP-focused SDK, superseded by `@qverisai/mcp`.
+
+[Unreleased]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/js-sdk-v0.3.0...HEAD
+[0.3.0]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/js-sdk-v0.2.0...js-sdk-v0.3.0
+[0.2.0]: https://github.com/QVerisAI/qveris-agent-toolkit/releases/tag/js-sdk-v0.2.0
+[#143]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/143
+[#134]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/134
+[#106]: https://github.com/QVerisAI/qveris-agent-toolkit/issues/106

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 QverisAI
+Copyright (c) 2026 QVerisAI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,216 +1,129 @@
-# @qverisai/sdk
-
-Official Qveris MCP Server SDK — Dynamically search and execute tools via natural language.
-
-[![npm version](https://img.shields.io/npm/v/@qverisai/sdk.svg)](https://www.npmjs.com/package/@qverisai/sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Overview
-
-This SDK provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables LLMs to discover and execute third-party tools through the Qveris API. With three simple tools, your AI assistant can:
-
-- **Search** for tools using natural language queries
-- **Get** detailed information about specific tools by their IDs
-- **Execute** any discovered tool with the appropriate parameters
-
-## Quick Start
-
-### 1. Get Your API Key
-
-Visit [Qveris](https://qveris.ai) to get your API key.
-
-### 2. Configure Your MCP Client
-
-Add the Qveris server to your MCP client configuration:
-
-**Claude Desktop** (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "qveris": {
-      "command": "npx",
-      "args": ["@qverisai/sdk"],
-      "env": {
-        "QVERIS_API_KEY": "your-api-key-here"
-      }
-    }
-  }
-}
-```
-
-**Cursor** (Settings → MCP Servers):
-
-```json
-{
-  "mcpServers": {
-    "qveris": {
-      "command": "npx",
-      "args": ["@qverisai/sdk"],
-      "env": {
-        "QVERIS_API_KEY": "your-api-key-here"
-      }
-    }
-  }
-}
-```
-
-### 3. Start Using
-
-Once configured, You could add this to system prompt:
-
-> "You can use qveris MCP Server to dynamically search and execute tools to help the user. First think about what kind of tools might be useful to accomplish the user's task. Then use the search_tools tool with query describing the capability of the tool, not what params you want to pass to the tool later. Then call a suitable searched tool using the execute_tool tool, passing parameters to the searched tool through params_to_tool. You could reference the examples given if any for each tool. You may call make multiple tool calls in a single response."
-
-Then your AI assistant can search for and execute tools:
-
-> "Find me a weather tool and get the current weather in Tokyo"
-
-The assistant will:
-1. Call `search_tools` with query "weather"
-2. Review the results and select an appropriate tool
-3. Call `execute_tool` with the tool_id and parameters
-
-## Available Tools
-
-### `search_tools`
-
-Search for available tools based on natural language queries.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `query` | string | ✓ | Natural language description of the capability you need |
-| `limit` | number | | Max results to return (1-100, default: 20) |
-| `session_id` | string | | Session identifier for tracking (auto-generated if omitted) |
-
-**Example:**
-
-```json
-{
-  "query": "send email notification",
-  "limit": 10
-}
-```
-
-### `execute_tool`
-
-Execute a discovered tool with specific parameters.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tool_id` | string | ✓ | Tool ID from search results |
-| `search_id` | string | ✓ | Search ID from the search that found this tool |
-| `params_to_tool` | string | ✓ | JSON string of parameters to pass to the tool |
-| `session_id` | string | | Session identifier (auto-generated if omitted) |
-| `max_response_size` | number | | Max response size in bytes (default: 20480) |
-
-**Example:**
-
-```json
-{
-  "tool_id": "openweathermap.weather.execute.v1",
-  "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
-  "params_to_tool": "{\"city\": \"London\", \"units\": \"metric\"}"
-}
-```
-
-### `get_tools_by_ids`
-
-Get detailed descriptions of tools based on their tool IDs. Useful for retrieving information about specific tools when you already know their IDs from previous searches.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tool_ids` | array | ✓ | Array of tool IDs to retrieve (at least one required) |
-| `search_id` | string | | Search ID from the search that returned the tool(s) |
-| `session_id` | string | | Session identifier (auto-generated if omitted) |
-
-**Example:**
-
-```json
-{
-  "tool_ids": ["openweathermap.weather.execute.v1", "worldbank_refined.search_indicators.v1"],
-  "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456"
-}
-```
-
-## Session Management
-
-Providing a consistent `session_id` in a same user session in any tool call enables:
-- Consistent user tracking across multiple tool calls
-- Better analytics and usage patterns
-- Improved tool recommendations over time
-
-If not provided, the SDK automatically generates and maintains a session ID for the lifetime of the server process. However, this result in a much larger granularity of user sessions.
-
-## Response Handling
-
-### Successful Execution
-
-```json
-{
-  "execution_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
-  "tool_id": "openweathermap.weather.execute.v1",
-  "success": true,
-  "result": {
-    "data": {
-      "temperature": 15.5,
-      "humidity": 72,
-      "description": "partly cloudy"
-    }
-  },
-  "execution_time": 0.847
-}
-```
-
-### Large Responses
-
-When tool output exceeds `max_response_size`, you'll receive:
-
-```json
-{
-  "result": {
-    "message": "Result content is too long...",
-    "truncated_content": "[[1678233600000, \"22198.56...",
-    "full_content_file_url": "https://..."
-  }
-}
-```
-
-The `full_content_file_url` is valid for 120 minutes.
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `QVERIS_API_KEY` | ✓ | Your Qveris API key |
-
-## Requirements
-
-- Node.js 18.0.0 or higher
-- A valid Qveris API key
-
-## Development
-
-```bash
-# Clone the repository
-git clone https://github.com/qverisai/sdk.git
-cd sdk
-
-# Install dependencies
-npm install
-
-# Build
-npm build
-
-# Run locally
-QVERIS_API_KEY=your-key node dist/index.js
-```
-
-## License
-
-MIT © [QverisAI](https://github.com/qverisai)
-
-## Support
-
-- 🐛 [Issue Tracker](https://github.com/qverisai/sdk/issues)
-- 💬 Contact: contact@qveris.ai
-
+# @qverisai/sdk
+
+TypeScript SDK for [QVeris](https://qveris.ai) — the Agent External Data & Tool Harness. Discover, inspect and call 1000+ ranked external data & tool capabilities with unified billing and usage audit. No per-provider API keys required.
+
+- **Typed end to end** — response types aligned with the public OpenAPI contract (categories, capabilities, `why_recommended`, `expected_cost`, billing)
+- **Zero dependencies** — native `fetch`, Node.js 18+
+- **Same wire semantics** as the [Python SDK](https://pypi.org/project/qveris/) and the [MCP server](https://www.npmjs.com/package/@qverisai/mcp)
+
+## Install
+
+```bash
+npm install @qverisai/sdk
+```
+
+## Quickstart
+
+```typescript
+import { Qveris } from '@qverisai/sdk';
+
+const qveris = new Qveris({ apiKey: process.env.QVERIS_API_KEY! });
+// or: const qveris = Qveris.fromEnv();
+
+// 1. Discover — free, returns ranked capabilities
+const found = await qveris.discover('stock price market data API', { limit: 5 });
+for (const tool of found.results) {
+  console.log(tool.tool_id, '—', tool.why_recommended);
+}
+
+// 2. Inspect — free, current parameter schemas
+const detail = await qveris.inspect(found.results[0].tool_id, {
+  searchId: found.search_id,
+});
+
+// 3. Call — billed in credits; response includes pre-settlement billing
+const outcome = await qveris.call(found.results[0].tool_id, {
+  searchId: found.search_id,
+  parameters: { symbol: 'AAPL' },
+});
+console.log(outcome.success, outcome.result);
+```
+
+## Audit
+
+```typescript
+// Final charge status for an execution
+const usage = await qveris.usage({ execution_id: outcome.execution_id });
+
+// Credit balance movements
+const ledger = await qveris.ledger({ direction: 'consume', summary: true });
+
+// Current balance
+const credits = await qveris.credits();
+```
+
+## Configuration
+
+| Option / env var | Description |
+| --- | --- |
+| `apiKey` / `QVERIS_API_KEY` | Required. Create one at [qveris.ai](https://qveris.ai/account?page=api-keys) (global) or [qveris.cn](https://qveris.cn/account?page=api-keys) (China) |
+| `baseUrl` / `QVERIS_BASE_URL` | Override API base URL (highest priority) |
+| `QVERIS_REGION` | Force region: `global` or `cn`. Otherwise auto-detected from the key prefix (`sk-cn-…` → China) |
+| `timeoutMs` | Default request timeout (30s; `call` defaults to 120s) |
+| `maxRetries` | Retries for rate-limited (429) / transient (503) responses (default 3; `0` disables) |
+
+## Rate limiting & retries
+
+The client transparently retries rate-limited (`429`) and transient (`503`) responses: it honors the `Retry-After` header when present, otherwise backs off exponentially with full jitter. Each wait is capped and retries are bounded by `maxRetries`, so a call never hangs.
+
+```ts
+const qveris = new Qveris({ apiKey: process.env.QVERIS_API_KEY!, maxRetries: 5 });
+// ... after some calls under load:
+qveris.rateLimitRetryCount; // how many times it backed off (pressure, not failures)
+```
+
+Set `maxRetries: 0` to disable. Rate-limit backoff is retried pressure rather than failure — read `rateLimitRetryCount` to observe it instead of treating the retried `429`s as errors.
+
+## Errors
+
+All failures throw `QverisApiError` (an `Error` subclass) with `status`, `details`, and an `observability` object (operation, endpoint, request id) for diagnostics:
+
+```typescript
+import { QverisApiError } from '@qverisai/sdk';
+
+try {
+  await qveris.call('some.tool.v1', { parameters: {} });
+} catch (err) {
+  if (err instanceof QverisApiError && err.status === 402) {
+    // insufficient credits — err.message includes the purchase link
+  }
+}
+```
+
+## Framework integrations
+
+Expose the QVeris workflow as [Vercel AI SDK](https://sdk.vercel.ai) tools. `ai` and `zod` are peer dependencies:
+
+```bash
+npm install @qverisai/sdk ai zod
+```
+
+```typescript
+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! });
+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.',
+});
+```
+
+## Version history note
+
+Versions `0.1.x` of this npm package were an early MCP-focused SDK, since superseded by [`@qverisai/mcp`](https://www.npmjs.com/package/@qverisai/mcp). The typed REST client documented here starts at **`0.2.0`**.
+
+## Related
+
+- [QVeris CLI](https://www.npmjs.com/package/@qverisai/cli) — `qveris discover / inspect / call / usage / ledger`
+- [QVeris MCP server](https://www.npmjs.com/package/@qverisai/mcp) — for Claude, Cursor and other MCP clients
+- [Python SDK](https://pypi.org/project/qveris/)
+- [REST API docs](https://github.com/QVerisAI/qveris-agent-toolkit/blob/main/docs/en-US/rest-api.md)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,116 @@
+/**
+ * QVeris API client.
+ *
+ * A lightweight, dependency-free typed client for the QVeris REST API using
+ * native fetch (Node.js 18+). Handles authentication, region resolution,
+ * success-envelope unwrapping, timeouts, and error normalization.
+ *
+ * The wire semantics mirror the Python SDK (`qveris` on PyPI) and the MCP
+ * server (`@qverisai/mcp`).
+ *
+ * @module client
+ */
+import type { ApiError, CreditsLedgerRequest, CreditsLedgerResponse, CreditsResponse, ExecuteResponse, QverisClientConfig, SearchResponse, UsageEventsResponse, UsageHistoryRequest } from './types.js';
+/** Options for {@link Qveris.discover}. */
+export interface DiscoverOptions {
+    /** Maximum number of results (1-100, server default 20) */
+    limit?: number;
+    /** Session identifier for tracking */
+    sessionId?: string;
+    /** Per-request timeout override in milliseconds */
+    timeoutMs?: number;
+}
+/** Options for {@link Qveris.inspect}. */
+export interface InspectOptions {
+    /** The search_id from the discover call that returned the tool(s) */
+    searchId?: string;
+    /** Session identifier for tracking */
+    sessionId?: string;
+    /** Per-request timeout override in milliseconds */
+    timeoutMs?: number;
+}
+/** Options for {@link Qveris.call}. */
+export interface CallOptions {
+    /** Key-value parameters matching the tool's parameter schema */
+    parameters: Record<string, unknown>;
+    /** The search_id from the discover call that returned this tool */
+    searchId?: string;
+    /** Session identifier for tracking */
+    sessionId?: string;
+    /** Max response bytes before truncation (-1 for no limit, server default 20480) */
+    maxResponseSize?: number;
+    /** Per-request timeout override in milliseconds (default 120s) */
+    timeoutMs?: number;
+}
+/**
+ * QVeris API client.
+ *
+ * @example
+ * ```typescript
+ * import { Qveris } from '@qverisai/sdk';
+ *
+ * const qveris = new Qveris({ apiKey: process.env.QVERIS_API_KEY! });
+ *
+ * const found = await qveris.discover('stock price market data API', { limit: 5 });
+ * const tool = found.results[0];
+ *
+ * const outcome = await qveris.call(tool.tool_id, {
+ *   searchId: found.search_id,
+ *   parameters: { symbol: 'AAPL' },
+ * });
+ * ```
+ */
+export declare class Qveris {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly defaultTimeoutMs;
+    private readonly maxRetries;
+    private rateLimitRetries;
+    constructor(config: QverisClientConfig);
+    /**
+     * How many times the client has backed off on a rate-limited (429) /
+     * transient (503) response so far. Rate-limit backoff is retried pressure,
+     * not failure — observe this rather than counting the retried responses.
+     */
+    get rateLimitRetryCount(): number;
+    /** Sleep for `ms` (a seam so tests can stub out the wait). */
+    private sleep;
+    /**
+     * Create a client from the QVERIS_API_KEY environment variable.
+     * Region is auto-detected from the key prefix (sk-cn-xxx -> cn), or
+     * overridden via QVERIS_REGION / QVERIS_BASE_URL.
+     */
+    static fromEnv(overrides?: Omit<QverisClientConfig, 'apiKey'>): Qveris;
+    /**
+     * Discover capabilities from a natural-language query. Free.
+     */
+    discover(query: string, options?: DiscoverOptions): Promise<SearchResponse>;
+    /**
+     * Inspect capabilities by id to get current parameter schemas. Free.
+     * An empty id list resolves locally without a network request.
+     */
+    inspect(toolIds: string | string[], options?: InspectOptions): Promise<SearchResponse>;
+    /**
+     * Call a capability. The response may include pre-settlement billing;
+     * final charges are reflected in usage() and ledger().
+     */
+    call(toolId: string, options: CallOptions): Promise<ExecuteResponse>;
+    /** Get current credit balance and bucket details. */
+    credits(): Promise<CreditsResponse>;
+    /** Query request-level usage audit history. */
+    usage(filters?: UsageHistoryRequest): Promise<UsageEventsResponse>;
+    /** Query final credits ledger entries. */
+    ledger(filters?: CreditsLedgerRequest): Promise<CreditsLedgerResponse>;
+    /**
+     * Makes an authenticated HTTP request and unwraps success envelopes.
+     */
+    private request;
+    /**
+     * Unwrap `{status: "success", data: ...}` envelopes; raw payloads pass
+     * through. A failure envelope throws before any result parsing, matching
+     * the Python SDK behavior.
+     */
+    private unwrapEnvelope;
+}
+export type { ApiError };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EAEV,QAAQ,EAGR,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAoCpB,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,MAAM,EAAE,kBAAkB;IActC;;;;OAIG;IACH,IAAI,mBAAmB,IAAI,MAAM,CAEhC;IAED,8DAA8D;YAChD,KAAK;IAKnB;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAAG,MAAM;IAYtE;;OAEG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAcrF;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAkBhG;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAiB1E,qDAAqD;IAC/C,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC;IAIzC,+CAA+C;IACzC,KAAK,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAW5E,0CAA0C;IACpC,MAAM,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAWhF;;OAEG;YACW,OAAO;IA2IrB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAqBvB;AAkCD,YAAY,EAAE,QAAQ,EAAE,CAAC"}