@qverisai/sdk 0.1.2 → 0.3.0

package/dist/integrations/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/integrations/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDlF"}

package/dist/integrations/ai.js

@@ -0,0 +1,87 @@
+/**
+ * Vercel AI SDK adapter for QVeris.
+ *
+ * Exposes the QVeris discover / inspect / call workflow as Vercel AI SDK tools,
+ * so an agent built with the `ai` package can find and invoke thousands of
+ * external capabilities through one QVeris API key.
+ *
+ * `ai` and `zod` are peer dependencies — install them alongside `@qverisai/sdk`.
+ *
+ * @example
+ * ```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),
+ *   maxSteps: 6,
+ *   prompt: 'Find a stock quote capability and quote AAPL.',
+ * });
+ * ```
+ *
+ * @module @qverisai/sdk/ai
+ */
+import { tool } from 'ai';
+import { z } from 'zod';
+/**
+ * Build Vercel AI SDK tools for the QVeris discover/inspect/call workflow.
+ *
+ * @param qveris - The Qveris client to route calls through.
+ * @param options - Optional `sessionId` for correlation/pricing context.
+ * @returns A tools object keyed by `qveris_discover` / `qveris_inspect` /
+ *   `qveris_call`, ready to pass to `generateText`/`streamText`.
+ */
+export function getQverisTools(qveris, options = {}) {
+    if (!qveris ||
+        typeof qveris.discover !== 'function' ||
+        typeof qveris.inspect !== 'function' ||
+        typeof qveris.call !== 'function') {
+        throw new TypeError('getQverisTools requires a valid Qveris client instance.');
+    }
+    const { sessionId } = options;
+    return {
+        qveris_discover: tool({
+            description: 'Discover QVeris capabilities from a natural-language query. Free; returns candidates and a search_id.',
+            inputSchema: z.object({
+                query: z.string().describe("Capability query, e.g. 'weather forecast API'."),
+                limit: z.number().int().min(1).max(100).optional().describe('Number of results (1-100).'),
+            }),
+            execute: async ({ query, limit }) => qveris.discover(query, { ...(limit !== undefined && { limit }), ...(sessionId && { sessionId }) }),
+        }),
+        qveris_inspect: tool({
+            description: 'Inspect one or more QVeris capabilities by tool_id before calling them. Free.',
+            inputSchema: z.object({
+                tool_ids: z.array(z.string()).describe('Tool IDs returned by discover.'),
+                search_id: z.string().optional().describe('The search_id from the discover response, if available.'),
+            }),
+            execute: async ({ tool_ids, search_id }) => qveris.inspect(tool_ids, { ...(search_id && { searchId: search_id }), ...(sessionId && { sessionId }) }),
+        }),
+        qveris_call: tool({
+            description: 'Call a selected QVeris capability with parameters. May consume credits.',
+            inputSchema: z.object({
+                tool_id: z.string().describe('The capability tool_id, from discover or inspect.'),
+                params_to_tool: z
+                    .record(z.string(), z.unknown())
+                    .optional()
+                    .describe('Parameters to pass to the capability.'),
+                search_id: z.string().optional().describe('The search_id from the discover response, if available.'),
+                max_response_size: z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('Max response size in bytes; -1 means unlimited.'),
+            }),
+            execute: async ({ tool_id, search_id, params_to_tool = {}, max_response_size }) => qveris.call(tool_id, {
+                parameters: params_to_tool,
+                ...(search_id && { searchId: search_id }),
+                ...(max_response_size !== undefined && { maxResponseSize: max_response_size }),
+                ...(sessionId && { sessionId }),
+            }),
+        }),
+    };
+}
+//# sourceMappingURL=ai.js.map

package/dist/integrations/ai.js.map

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

package/dist/retry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Rate-limit aware retry helpers for the QVeris client.
+ *
+ * Pure functions the client uses to decide whether and how long to wait before
+ * retrying a rate-limited (`429`) or transient (`503`) response — honoring the
+ * `Retry-After` header when present, otherwise exponential backoff with full
+ * jitter. Kept separate from the client so the delay math is unit-testable.
+ *
+ * @module @qverisai/sdk/retry
+ */
+export declare const DEFAULT_MAX_RETRIES = 3;
+export declare const DEFAULT_BASE_DELAY_MS = 500;
+export declare const DEFAULT_MAX_DELAY_MS = 60000;
+/** HTTP statuses worth retrying: rate limiting + transient unavailability. */
+export declare const RETRYABLE_STATUS: Set<number>;
+/**
+ * Parse a `Retry-After` header into milliseconds.
+ *
+ * Accepts both RFC 9110 forms — a delta in seconds (`"12"`) or an HTTP-date.
+ * Returns `null` when absent/unparseable, and never a negative value.
+ */
+export declare function parseRetryAfterMs(value: string | null | undefined, now?: number): number | null;
+export interface RetryDelayOptions {
+    /** Parsed `Retry-After` in ms, or null to use backoff. */
+    retryAfterMs: number | null;
+    /** Zero-based attempt index (0 = first retry). */
+    attempt: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    /** Jitter source in [0, 1); defaults to `Math.random`. */
+    random?: () => number;
+}
+/**
+ * Compute how long to wait before the next attempt, in milliseconds.
+ *
+ * Honors `retryAfterMs` (capped at `maxDelayMs`); otherwise exponential backoff
+ * `baseDelayMs * 2**attempt` with full jitter, capped at `maxDelayMs`.
+ */
+export declare function computeRetryDelayMs(options: RetryDelayOptions): number;
+/** Resolve a caller-supplied `maxRetries` to a safe non-negative integer. */
+export declare function resolveMaxRetries(maxRetries: number | undefined): number;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAG3C,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,aAAsB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAgB3G;AAED,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAQtE;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGxE"}

package/dist/retry.js

@@ -0,0 +1,63 @@
+/**
+ * Rate-limit aware retry helpers for the QVeris client.
+ *
+ * Pure functions the client uses to decide whether and how long to wait before
+ * retrying a rate-limited (`429`) or transient (`503`) response — honoring the
+ * `Retry-After` header when present, otherwise exponential backoff with full
+ * jitter. Kept separate from the client so the delay math is unit-testable.
+ *
+ * @module @qverisai/sdk/retry
+ */
+export const DEFAULT_MAX_RETRIES = 3;
+export const DEFAULT_BASE_DELAY_MS = 500;
+export const DEFAULT_MAX_DELAY_MS = 60_000;
+const MAX_BACKOFF_EXPONENT = 30; // guards 2**attempt against overflow
+/** HTTP statuses worth retrying: rate limiting + transient unavailability. */
+export const RETRYABLE_STATUS = new Set([429, 503]);
+/**
+ * Parse a `Retry-After` header into milliseconds.
+ *
+ * Accepts both RFC 9110 forms — a delta in seconds (`"12"`) or an HTTP-date.
+ * Returns `null` when absent/unparseable, and never a negative value.
+ */
+export function parseRetryAfterMs(value, now = Date.now()) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    // Delta-seconds form: a non-negative integer.
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    // HTTP-date form. Require a letter (month name / "GMT") so Date.parse's
+    // leniency doesn't turn junk like "-5" into a spurious date.
+    if (!/[a-zA-Z]/.test(trimmed))
+        return null;
+    const dateMs = Date.parse(trimmed);
+    if (Number.isNaN(dateMs))
+        return null;
+    return Math.max(0, dateMs - now);
+}
+/**
+ * Compute how long to wait before the next attempt, in milliseconds.
+ *
+ * Honors `retryAfterMs` (capped at `maxDelayMs`); otherwise exponential backoff
+ * `baseDelayMs * 2**attempt` with full jitter, capped at `maxDelayMs`.
+ */
+export function computeRetryDelayMs(options) {
+    const { retryAfterMs, attempt, baseDelayMs, maxDelayMs } = options;
+    if (retryAfterMs != null) {
+        return Math.min(retryAfterMs, maxDelayMs);
+    }
+    const random = options.random ?? Math.random;
+    const capped = Math.min(baseDelayMs * 2 ** Math.min(attempt, MAX_BACKOFF_EXPONENT), maxDelayMs);
+    return capped * (0.5 + 0.5 * random());
+}
+/** Resolve a caller-supplied `maxRetries` to a safe non-negative integer. */
+export function resolveMaxRetries(maxRetries) {
+    if (maxRetries == null || !Number.isFinite(maxRetries))
+        return DEFAULT_MAX_RETRIES;
+    return Math.max(0, Math.floor(maxRetries));
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,MAAM,oBAAoB,GAAG,EAAE,CAAC,CAAC,qCAAqC;AAEtE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAgC,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAC1F,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAEhC,8CAA8C;IAC9C,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAChC,CAAC;IAED,wEAAwE;IACxE,6DAA6D;IAC7D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,CAAC;AACnC,CAAC;AAaD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA0B;IAC5D,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACnE,IAAI,YAAY,IAAI,IAAI,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,oBAAoB,CAAC,EAAE,UAAU,CAAC,CAAC;IAChG,OAAO,MAAM,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,MAAM,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAAC,UAA8B;IAC9D,IAAI,UAAU,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACnF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/types.d.ts

@@ -1,30 +1,18 @@
 /**
  * Qveris API Type Definitions
  *
- * This module contains TypeScript types that match the Qveris API v0.1.6 schema.
- * All types are fully documented for IDE autocompletion and developer experience.
+ * This module contains TypeScript types that match the Qveris API schema.
+ * Aligned with backend ToolInfo, SearchResponse, ToolCallResponse, and
+ * the REST API documentation at docs/en-US/rest-api.md.
  *
  * @module types
  * @see {@link https://qveris.ai/api/v1} Qveris API Base URL
  */
 /**
  * Request body for the Search Tools API.
- *
- * @example
- * ```typescript
- * const request: SearchRequest = {
- *   query: "weather forecast API",
- *   limit: 10,
- *   session_id: "abcd1234-ab12-ab12-ab12-abcdef123456"
- * };
- * ```
  */
 export interface SearchRequest {
-    /**
-     * Natural language search query describing the tool capability you need.
-     * @example "weather forecast API"
-     * @example "send email notification"
-     */
+    /** Natural language search query describing the tool capability you need. */
     query: string;
     /**
      * Maximum number of results to return.
@@ -33,15 +21,11 @@ export interface SearchRequest {
      * @maximum 100
      */
     limit?: number;
-    /**
-     * Session identifier for tracking user sessions.
-     * Same ID corresponds to the same user session.
-     */
+    /** Session identifier for tracking user sessions. */
     session_id?: string;
 }
 /**
  * Parameter definition for a tool.
- * Describes a single input parameter that a tool accepts.
  */
 export interface ToolParameter {
     /** Parameter name (used as key in the parameters object) */
@@ -62,41 +46,146 @@ export interface ToolExamples {
     /** Sample parameter values demonstrating typical usage */
     sample_parameters?: Record<string, unknown>;
 }
+/**
+ * Historical execution performance statistics for a tool.
+ */
+export interface ToolStats {
+    /** Historical average execution time in milliseconds */
+    avg_execution_time_ms?: number;
+    /** Historical success rate (0.0 - 1.0) */
+    success_rate?: number;
+    /** Legacy fallback estimate in credits per call */
+    cost?: number;
+}
+export interface BillingPrice {
+    amount_credits: number;
+    per?: number | null;
+    unit?: string | null;
+    unit_label?: string | null;
+}
+export interface BillingChargeLine {
+    component_key: string;
+    quantity?: number | null;
+    unit?: string | null;
+    unit_label?: string | null;
+    price?: BillingPrice | null;
+    amount_credits?: number | null;
+    description?: string | null;
+    is_adjustment?: boolean | null;
+}
+export interface BillingRule {
+    metering_mode?: string;
+    billing_unit?: string;
+    billing_unit_label?: string;
+    price?: BillingPrice | null;
+    price_breakdown?: Record<string, unknown>[] | null;
+    pricing_dimensions?: Record<string, unknown>[] | null;
+    minimum_charge_credits?: number | null;
+    snapshot_id?: number | null;
+    snapshot_version?: string | null;
+    runtime_pricing_version?: string | null;
+    pricing_source_system?: string | null;
+    description?: string;
+}
+export interface CompactBillingStatement {
+    price?: BillingPrice | null;
+    quantity?: number | null;
+    charge_lines?: BillingChargeLine[] | null;
+    minimum_charge_credits?: number | null;
+    list_amount_credits?: number | null;
+    requested_amount_credits?: number | null;
+    summary?: string | null;
+}
+/**
+ * Category/tag attached to a tool.
+ * Current API responses return category objects; legacy responses returned
+ * plain strings, so `ToolInfo.categories` accepts both.
+ */
+export interface ToolCategory {
+    slug?: string;
+    name?: string;
+    description?: string;
+}
+/**
+ * Coverage tag attached to a capability (e.g. market coverage).
+ */
+export interface ToolCapabilityTag {
+    id?: string;
+    name?: string;
+    type?: string;
+    description?: string;
+}
+/**
+ * Standardized capability descriptor attached to a tool
+ * (e.g. "MKT.BARS.ADJUSTED" with market coverage tags).
+ */
+export interface ToolCapability {
+    id?: string;
+    tag?: ToolCapabilityTag[];
+}
 /**
  * Information about a tool returned from search results.
  * Contains everything needed to understand and execute the tool.
  */
 export interface ToolInfo {
-    /** Unique identifier for the tool (used in execute_tool) */
+    /** Unique identifier for the tool (used in call) */
     tool_id: string;
     /** Human-readable display name */
     name: string;
     /** Detailed description of what the tool does */
     description: string;
+    /** Tool categories/tags: category objects, or plain strings in legacy responses */
+    categories?: Array<string | ToolCategory>;
+    /** Standardized capability descriptors with coverage tags */
+    capabilities?: ToolCapability[];
+    /** Provider identifier */
+    provider_id?: string;
     /** Name of the organization/service providing this tool */
     provider_name?: string;
     /** Description of the provider */
     provider_description?: string;
+    /** Provider website URL */
+    provider_website_url?: string;
     /**
      * Geographic availability of the tool.
      * - "global" - Available worldwide
      * - "US|CA" - Whitelist: only available in US and Canada
-     * - "!CN|RU" - Blacklist: not available in China and Russia
+     * - "-CN|RU" - Blacklist: not available in China and Russia
      */
     region?: string;
-    /** Average response latency in milliseconds */
-    avg_latency_ms?: number;
     /** List of parameters the tool accepts */
     params?: ToolParameter[];
     /** Usage examples with sample parameters */
     examples?: ToolExamples;
+    /** Historical execution performance statistics */
+    stats?: ToolStats;
+    /** Structured rule-level billing metadata when available */
+    billing_rule?: BillingRule;
+    /** Pre-call cost estimate in credits, when available */
+    expected_cost?: string | number;
+    /** Relevance score for the search query (0.0 - 1.0, higher = better match) */
+    final_score?: number;
+    /** Human-readable explanation of why this tool was recommended (Discover results only) */
+    why_recommended?: string;
+    /** Whether this tool has been executed before (verified in production) */
+    has_last_execution?: boolean;
+    /** Most recent execution record, if available */
+    last_execution_record?: Record<string, unknown>;
+    /** Documentation URL for the tool */
+    docs_url?: string;
+    /** Protocol type */
+    protocol?: string;
 }
 /**
  * Performance statistics for a search operation.
  */
 export interface SearchStats {
     /** Total time to complete the search in milliseconds */
-    search_time_ms: number;
+    search_time_ms?: number;
+    /** Vector recall count */
+    vector_recall_count?: number;
+    /** Fulltext recall count */
+    fulltext_recall_count?: number;
 }
 /**
  * Response from the Search Tools API.
@@ -106,7 +195,7 @@ export interface SearchResponse {
     query?: string;
     /**
      * Unique identifier for this search.
-     * Required when calling execute_tool for any tool from these results.
+     * Required when calling call for any tool from these results.
      */
     search_id: string;
     /** Total number of results returned */
@@ -115,58 +204,32 @@ export interface SearchResponse {
     results: ToolInfo[];
     /** Search performance statistics */
     stats?: SearchStats;
+    /** User's remaining credits after this operation */
+    remaining_credits?: number;
+    /** Total elapsed time in milliseconds */
+    elapsed_time_ms?: number;
 }
 /**
  * Request body for the Get Tools by IDs API.
- *
- * @example
- * ```typescript
- * const request: GetToolsByIdsRequest = {
- *   tool_ids: ["tool-1", "tool-2"],
- *   search_id: "search-123",
- *   session_id: "abcd1234-ab12-ab12-ab12-abcdef123456"
- * };
- * ```
  */
 export interface GetToolsByIdsRequest {
-    /**
-     * Array of tool IDs to retrieve information for.
-     */
+    /** Array of tool IDs to retrieve information for. */
     tool_ids: string[];
-    /**
-     * The search_id from the search that returned the tool(s).
-     * Optional but recommended for analytics and billing.
-     */
+    /** The search_id from the search that returned the tool(s). */
     search_id?: string;
-    /**
-     * Session identifier for tracking user sessions.
-     * Same ID corresponds to the same user session.
-     */
+    /** Session identifier for tracking user sessions. */
     session_id?: string;
 }
 /**
  * Request body for the Execute Tool API.
- *
- * @example
- * ```typescript
- * const request: ExecuteRequest = {
- *   search_id: "abcd1234-ab12-ab12-ab12-abcdef123456",
- *   session_id: "abcd1234-ab12-ab12-ab12-abcdef123456",
- *   parameters: { city: "London", units: "metric" },
- *   max_response_size: 20480
- * };
- * ```
  */
 export interface ExecuteRequest {
     /**
      * The search_id from the search that returned this tool.
-     * Links the execution to the original search for analytics.
+     * Links the execution to the original search for analytics and billing.
      */
     search_id: string;
-    /**
-     * Session identifier for tracking user sessions.
-     * Same ID corresponds to the same user session.
-     */
+    /** Session identifier for tracking user sessions. */
     session_id?: string;
     /**
      * Key-value pairs of parameters to pass to the tool.
@@ -206,6 +269,11 @@ export interface ExecuteResultTruncated {
      * Useful for previewing the data structure.
      */
     truncated_content: string;
+    /**
+     * JSON Schema describing the structure of the full content.
+     * Helps the agent understand the data shape without downloading.
+     */
+    content_schema?: Record<string, unknown>;
 }
 /**
  * Union type for execution results (either full data or truncated).
@@ -235,9 +303,119 @@ export interface ExecuteResponse {
     error_message?: string | null;
     /** Execution duration in seconds */
     execution_time?: number;
+    /** Execution duration in milliseconds (alternative field) */
+    elapsed_time_ms?: number;
+    /** Legacy fallback estimate; use usage audit or credits ledger for final charge */
+    cost?: number;
+    /** Structured pre-settlement billing statement when available */
+    billing?: CompactBillingStatement;
+    /** Legacy/full pre-settlement bill snapshot when returned directly */
+    pre_settlement_bill?: Record<string, unknown>;
+    /** User's remaining credits after this execution */
+    remaining_credits?: number;
     /** Timestamp of execution (ISO 8601 format) */
+    created_at?: string;
+}
+export interface ApiEnvelope<T> {
+    status: string;
+    message?: string;
+    status_code?: number;
+    data: T;
+}
+export interface CreditsResponse {
+    remaining_credits: number;
+    daily_free?: Record<string, unknown>;
+    invite_reward?: Record<string, unknown>;
+    welcome_bonus?: Record<string, unknown>;
+    purchased?: Record<string, unknown>;
+}
+export interface UsageHistoryRequest {
+    start_date?: string;
+    end_date?: string;
+    summary?: boolean;
+    bucket?: string;
+    event_type?: string;
+    kind?: string;
+    success?: boolean;
+    charge_outcome?: string;
+    search_id?: string;
+    execution_id?: string;
+    min_credits?: number;
+    max_credits?: number;
+    limit?: number;
+    page?: number;
+    page_size?: number;
+}
+export interface UsageEventItem {
+    id: string;
+    event_type: string;
+    kind?: string | null;
+    source_system: string;
+    source_ref_type?: string | null;
+    source_ref_id?: string | null;
+    session_id?: string | null;
+    search_id?: string | null;
+    execution_id?: string | null;
+    tool_id?: string | null;
+    model?: string | null;
+    query?: string | null;
+    success: boolean;
+    charge_outcome?: string | null;
+    error_message?: string | null;
+    billing_snapshot_status?: string | null;
+    pre_settlement_bill?: Record<string, unknown> | null;
+    settlement_result?: Record<string, unknown> | null;
+    requested_amount_credits?: number | null;
+    actual_amount_credits?: number | null;
+    credits_ledger_entry_id?: string | null;
+    display_target?: string | null;
+    billing_summary?: string | null;
+    pre_settlement_amount_credits?: number | null;
+    settled_amount_credits?: number | null;
+    created_at: string;
+}
+export interface UsageEventsResponse {
+    items: UsageEventItem[];
+    total: number;
+    page: number;
+    page_size: number;
+    summary?: Record<string, unknown> | null;
+}
+export interface CreditsLedgerRequest {
+    start_date?: string;
+    end_date?: string;
+    summary?: boolean;
+    bucket?: string;
+    entry_type?: string;
+    direction?: string;
+    min_credits?: number;
+    max_credits?: number;
+    limit?: number;
+    page?: number;
+    page_size?: number;
+}
+export interface CreditsLedgerItem {
+    id: string;
+    entry_type: string;
+    amount_credits: number;
+    source_system: string;
+    source_ref_type?: string | null;
+    source_ref_id?: string | null;
+    pre_settlement_bill?: Record<string, unknown> | null;
+    settlement_result?: Record<string, unknown> | null;
+    balance_before?: Record<string, unknown> | null;
+    balance_after?: Record<string, unknown> | null;
+    ledger_metadata?: Record<string, unknown> | null;
+    description?: string | null;
     created_at: string;
 }
+export interface CreditsLedgerResponse {
+    items: CreditsLedgerItem[];
+    total: number;
+    page: number;
+    page_size: number;
+    summary?: Record<string, unknown> | null;
+}
 /**
  * Configuration options for the Qveris API client.
  */
@@ -246,10 +424,32 @@ export interface QverisClientConfig {
     apiKey: string;
     /** Base URL for the API (defaults to production) */
     baseUrl?: string;
+    /** Default request timeout in milliseconds */
+    timeoutMs?: number;
+    /**
+     * Max automatic retries for rate-limited (429) / transient (503) responses.
+     * Honors `Retry-After`, otherwise backs off exponentially with jitter.
+     * Defaults to 3; set to 0 to disable.
+     */
+    maxRetries?: number;
 }
 /**
  * Error response from the Qveris API.
  */
+export type ApiOperation = 'discover' | 'inspect' | 'call' | 'credits' | 'usage_history' | 'credits_ledger';
+export type ApiErrorType = 'http_error' | 'invalid_json' | 'timeout' | 'network_error';
+export interface ApiObservability {
+    source: 'qveris_api';
+    operation: ApiOperation;
+    method: 'GET' | 'POST';
+    endpoint: string;
+    url: string;
+    query_params?: Record<string, string>;
+    timeout_ms: number;
+    http_status?: number;
+    request_id?: string;
+    error_type?: ApiErrorType;
+}
 export interface ApiError {
     /** HTTP status code */
     status: number;
@@ -257,5 +457,9 @@ export interface ApiError {
     message: string;
     /** Original error details if available */
     details?: unknown;
+    /** Request metadata for diagnosing API/provider/tool-chain failures. */
+    observability?: ApiObservability;
+    /** Lower-level transport or runtime cause when available. */
+    cause?: string;
 }
 //# sourceMappingURL=types.d.ts.map