@qverisai/sdk 0.1.2 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 QverisAI
+Copyright (c) 2025 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,93 @@
-# @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) |
+
+## 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
+  }
+}
+```
+
+## 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,106 @@
+/**
+ * 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;
+    constructor(config: QverisClientConfig);
+    /**
+     * 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;AAGH,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;gBAE9B,MAAM,EAAE,kBAAkB;IAatC;;;;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;IAsHrB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAqBvB;AAkCD,YAAY,EAAE,QAAQ,EAAE,CAAC"}