@qverisai/sdk 0.1.2 → 0.3.0

package/dist/client.js

@@ -0,0 +1,334 @@
+/**
+ * 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 { QverisApiError } from './errors.js';
+import { computeRetryDelayMs, DEFAULT_BASE_DELAY_MS, DEFAULT_MAX_DELAY_MS, parseRetryAfterMs, resolveMaxRetries, RETRYABLE_STATUS, } from './retry.js';
+/** Region-specific API base URLs */
+const REGION_URLS = {
+    global: 'https://qveris.ai/api/v1',
+    cn: 'https://qveris.cn/api/v1',
+};
+/**
+ * Detect region from API key prefix.
+ * sk-cn-xxx -> cn, sk-xxx -> global
+ */
+function detectRegionFromKey(apiKey) {
+    return apiKey.startsWith('sk-cn-') ? 'cn' : 'global';
+}
+/**
+ * Resolve the base URL for the QVeris API.
+ * Priority: explicit baseUrl > QVERIS_BASE_URL env > QVERIS_REGION env > key prefix auto-detect > default
+ */
+function resolveBaseUrl(apiKey, explicitBaseUrl) {
+    if (explicitBaseUrl)
+        return explicitBaseUrl.replace(/\/+$/, '');
+    if (typeof process !== 'undefined') {
+        if (process.env.QVERIS_BASE_URL)
+            return process.env.QVERIS_BASE_URL.replace(/\/+$/, '');
+        if (process.env.QVERIS_REGION) {
+            const region = process.env.QVERIS_REGION.toLowerCase();
+            return REGION_URLS[region] ?? REGION_URLS.global;
+        }
+    }
+    return REGION_URLS[detectRegionFromKey(apiKey)];
+}
+/** Default timeout: 30s for discover/inspect/audit, 120s for call */
+const DEFAULT_TIMEOUT_MS = 30_000;
+const EXECUTE_TIMEOUT_MS = 120_000;
+/**
+ * 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 class Qveris {
+    apiKey;
+    baseUrl;
+    defaultTimeoutMs;
+    maxRetries;
+    rateLimitRetries = 0;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('QVeris API key is required.\n' +
+                'Global: https://qveris.ai/account?page=api-keys\n' +
+                'China:  https://qveris.cn/account?page=api-keys');
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = resolveBaseUrl(config.apiKey, config.baseUrl);
+        this.defaultTimeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = resolveMaxRetries(config.maxRetries);
+    }
+    /**
+     * 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() {
+        return this.rateLimitRetries;
+    }
+    /** Sleep for `ms` (a seam so tests can stub out the wait). */
+    async sleep(ms) {
+        if (ms <= 0)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * 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) {
+        const apiKey = process.env.QVERIS_API_KEY;
+        if (!apiKey) {
+            throw new Error('QVERIS_API_KEY environment variable is required.\n' +
+                'Global: https://qveris.ai/account?page=api-keys\n' +
+                'China:  https://qveris.cn/account?page=api-keys');
+        }
+        return new Qveris({ apiKey, ...overrides });
+    }
+    /**
+     * Discover capabilities from a natural-language query. Free.
+     */
+    async discover(query, options = {}) {
+        return this.request('discover', 'POST', '/search', {
+            query,
+            ...(options.limit !== undefined && { limit: options.limit }),
+            ...(options.sessionId !== undefined && { session_id: options.sessionId }),
+        }, options.timeoutMs);
+    }
+    /**
+     * Inspect capabilities by id to get current parameter schemas. Free.
+     * An empty id list resolves locally without a network request.
+     */
+    async inspect(toolIds, options = {}) {
+        const ids = typeof toolIds === 'string' ? [toolIds] : toolIds;
+        if (ids.length === 0) {
+            return { search_id: options.searchId ?? '', total: 0, results: [] };
+        }
+        return this.request('inspect', 'POST', '/tools/by-ids', {
+            tool_ids: ids,
+            ...(options.searchId !== undefined && { search_id: options.searchId }),
+            ...(options.sessionId !== undefined && { session_id: options.sessionId }),
+        }, options.timeoutMs);
+    }
+    /**
+     * Call a capability. The response may include pre-settlement billing;
+     * final charges are reflected in usage() and ledger().
+     */
+    async call(toolId, options) {
+        return this.request('call', 'POST', `/tools/execute?tool_id=${encodeURIComponent(toolId)}`, {
+            parameters: options.parameters,
+            search_id: options.searchId ?? null,
+            ...(options.sessionId !== undefined && { session_id: options.sessionId }),
+            ...(options.maxResponseSize !== undefined && {
+                max_response_size: options.maxResponseSize,
+            }),
+        }, options.timeoutMs ?? EXECUTE_TIMEOUT_MS);
+    }
+    /** Get current credit balance and bucket details. */
+    async credits() {
+        return this.request('credits', 'GET', '/auth/credits');
+    }
+    /** Query request-level usage audit history. */
+    async usage(filters = {}) {
+        return this.request('usage_history', 'GET', '/auth/usage/history/v2', undefined, undefined, filters);
+    }
+    /** Query final credits ledger entries. */
+    async ledger(filters = {}) {
+        return this.request('credits_ledger', 'GET', '/auth/credits/ledger', undefined, undefined, filters);
+    }
+    /**
+     * Makes an authenticated HTTP request and unwraps success envelopes.
+     */
+    async request(operation, method, endpoint, body, timeoutMs, query) {
+        const url = new URL(`${this.baseUrl}${endpoint}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== null && value !== '') {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const resolvedTimeoutMs = timeoutMs ?? this.defaultTimeoutMs;
+        const queryParams = Object.fromEntries(url.searchParams.entries());
+        const requestContext = {
+            source: 'qveris_api',
+            operation,
+            method,
+            endpoint,
+            url: url.toString(),
+            ...(Object.keys(queryParams).length > 0 && { query_params: queryParams }),
+            timeout_ms: resolvedTimeoutMs,
+        };
+        // Retry rate-limited (429) / transient (503) responses: honor Retry-After,
+        // otherwise exponential backoff with jitter, bounded by maxRetries. Each
+        // attempt is a fresh fetch with its own timeout.
+        for (let attempt = 0;; attempt++) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), resolvedTimeoutMs);
+            let retryDelayMs = null;
+            try {
+                const response = await fetch(url.toString(), {
+                    method,
+                    headers: {
+                        'Authorization': `Bearer ${this.apiKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                if (RETRYABLE_STATUS.has(response.status) && attempt < this.maxRetries) {
+                    retryDelayMs = computeRetryDelayMs({
+                        retryAfterMs: parseRetryAfterMs(response.headers.get('retry-after')),
+                        attempt,
+                        baseDelayMs: DEFAULT_BASE_DELAY_MS,
+                        maxDelayMs: DEFAULT_MAX_DELAY_MS,
+                    });
+                    // Discard the body so the connection is released before we retry.
+                    // (`.cancel?.()` so a body without cancel — e.g. a test double —
+                    // can't throw here and mask the rate-limit as a network error.)
+                    await response.body?.cancel?.().catch(() => undefined);
+                    this.rateLimitRetries++;
+                }
+                else if (!response.ok) {
+                    const status = response.status;
+                    let errorMessage;
+                    let errorDetails;
+                    try {
+                        const errorBody = (await response.json());
+                        errorMessage =
+                            errorBody.error_message ||
+                                errorBody.message ||
+                                errorBody.error ||
+                                response.statusText;
+                        errorDetails = errorBody;
+                    }
+                    catch {
+                        errorMessage = response.statusText || `HTTP ${status}`;
+                    }
+                    if (status === 402) {
+                        const pricingHost = this.baseUrl.includes('qveris.cn')
+                            ? 'https://qveris.cn'
+                            : 'https://qveris.ai';
+                        errorMessage = `Insufficient credits. ${errorMessage}. Purchase credits at ${pricingHost}/pricing`;
+                    }
+                    throw new QverisApiError({
+                        status,
+                        message: errorMessage,
+                        ...(errorDetails !== undefined && { details: errorDetails }),
+                        observability: withErrorContext(requestContext, 'http_error', status, extractRequestId(response)),
+                    });
+                }
+                else {
+                    let payload;
+                    try {
+                        payload = await response.json();
+                    }
+                    catch {
+                        throw new QverisApiError({
+                            status: response.status,
+                            message: 'Invalid or empty JSON response from API',
+                            observability: withErrorContext(requestContext, 'invalid_json', response.status, extractRequestId(response)),
+                        });
+                    }
+                    return this.unwrapEnvelope(payload, requestContext);
+                }
+            }
+            catch (err) {
+                if (err instanceof QverisApiError) {
+                    throw err;
+                }
+                if (err instanceof Error && err.name === 'AbortError') {
+                    throw new QverisApiError({
+                        status: 408,
+                        message: 'Request timed out. Check connectivity or increase timeout.',
+                        observability: withErrorContext(requestContext, 'timeout', 0),
+                        ...(errorCause(err) && { cause: errorCause(err) }),
+                    });
+                }
+                throw new QverisApiError({
+                    status: 0,
+                    message: err instanceof Error && err.message ? err.message : 'Network request failed',
+                    observability: withErrorContext(requestContext, 'network_error', 0),
+                    ...(errorCause(err) && { cause: errorCause(err) }),
+                });
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            // Only reached on the retry path (success returns, errors throw above).
+            await this.sleep(retryDelayMs ?? 0);
+        }
+    }
+    /**
+     * Unwrap `{status: "success", data: ...}` envelopes; raw payloads pass
+     * through. A failure envelope throws before any result parsing, matching
+     * the Python SDK behavior.
+     */
+    unwrapEnvelope(payload, context) {
+        if (payload !== null &&
+            typeof payload === 'object' &&
+            'status' in payload &&
+            'data' in payload &&
+            typeof payload.status === 'string') {
+            const envelope = payload;
+            if (envelope.status !== 'success') {
+                throw new QverisApiError({
+                    status: envelope.status_code ?? 400,
+                    message: envelope.message ?? `API returned status "${envelope.status}"`,
+                    details: payload,
+                    observability: withErrorContext(context, 'http_error', envelope.status_code ?? 400),
+                });
+            }
+            return envelope.data;
+        }
+        return payload;
+    }
+}
+function withErrorContext(context, errorType, httpStatus, requestId) {
+    return {
+        ...context,
+        error_type: errorType,
+        ...(httpStatus !== undefined && { http_status: httpStatus }),
+        ...(requestId && { request_id: requestId }),
+    };
+}
+function extractRequestId(response) {
+    const headers = response.headers;
+    return (headers?.get('x-request-id') ??
+        headers?.get('x-qveris-request-id') ??
+        headers?.get('x-correlation-id') ??
+        undefined);
+}
+function errorCause(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const cause = error.cause;
+    if (cause instanceof Error)
+        return cause.message;
+    if (typeof cause === 'string' && cause)
+        return cause;
+    return undefined;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * QVeris SDK error types.
+ *
+ * @module errors
+ */
+import type { ApiError, ApiObservability } from './types.js';
+/**
+ * Error thrown for any failed QVeris API interaction: HTTP errors,
+ * failure envelopes, timeouts, and network failures.
+ *
+ * Carries the same shape as the wire-level {@link ApiError} so callers can
+ * branch on `status` and inspect `observability` for diagnostics.
+ */
+export declare class QverisApiError extends Error implements ApiError {
+    /** HTTP status code (0 for network errors, 408 for timeouts) */
+    readonly status: number;
+    /** Original error details if available */
+    readonly details?: unknown;
+    /** Request metadata for diagnosing API failures */
+    readonly observability?: ApiObservability;
+    /** Lower-level transport or runtime cause when available */
+    readonly cause?: string;
+    constructor(error: ApiError);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,KAAM,YAAW,QAAQ;IAC3D,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAE3B,mDAAmD;IACnD,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAC;IAE1C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,QAAQ;CAQ5B"}

package/dist/errors.js

@@ -0,0 +1,34 @@
+/**
+ * QVeris SDK error types.
+ *
+ * @module errors
+ */
+/**
+ * Error thrown for any failed QVeris API interaction: HTTP errors,
+ * failure envelopes, timeouts, and network failures.
+ *
+ * Carries the same shape as the wire-level {@link ApiError} so callers can
+ * branch on `status` and inspect `observability` for diagnostics.
+ */
+export class QverisApiError extends Error {
+    /** HTTP status code (0 for network errors, 408 for timeouts) */
+    status;
+    /** Original error details if available */
+    details;
+    /** Request metadata for diagnosing API failures */
+    observability;
+    /** Lower-level transport or runtime cause when available */
+    cause;
+    constructor(error) {
+        super(error.message);
+        this.name = 'QverisApiError';
+        this.status = error.status;
+        if (error.details !== undefined)
+            this.details = error.details;
+        if (error.observability !== undefined)
+            this.observability = error.observability;
+        if (error.cause !== undefined)
+            this.cause = error.cause;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,gEAAgE;IACvD,MAAM,CAAS;IAExB,0CAA0C;IACjC,OAAO,CAAW;IAE3B,mDAAmD;IAC1C,aAAa,CAAoB;IAE1C,4DAA4D;IACnD,KAAK,CAAU;IAExB,YAAY,KAAe;QACzB,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9D,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS;YAAE,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;QAChF,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1D,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,27 +1,21 @@
-#!/usr/bin/env node
 /**
- * Qveris MCP Server
+ * QVeris TypeScript SDK.
  *
- * A Model Context Protocol (MCP) server that provides access to the Qveris
- * tool discovery and execution API. Enables LLMs to dynamically search for
- * and execute third-party tools via natural language.
- *
- * @module @qverisai/sdk
- * @version 0.1.0
+ * Typed client for the QVeris Agent External Data & Tool Harness:
+ * discover, inspect, call, plus usage and credits-ledger audit.
  *
  * @example
- * Configure in Claude Desktop or Cursor:
- * ```json
- * {
- *   "mcpServers": {
- *     "qveris": {
- *       "command": "npx",
- *       "args": ["@qverisai/sdk"],
- *       "env": { "QVERIS_API_KEY": "your-api-key" }
- *     }
- *   }
- * }
+ * ```typescript
+ * import { Qveris } from '@qverisai/sdk';
+ *
+ * const qveris = Qveris.fromEnv();
+ * const found = await qveris.discover('weather forecast API');
  * ```
+ *
+ * @module @qverisai/sdk
  */
-export {};
+export { Qveris } from './client.js';
+export type { DiscoverOptions, InspectOptions, CallOptions } from './client.js';
+export { QverisApiError } from './errors.js';
+export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,cAAc,YAAY,CAAC"}