@qverisai/sdk 0.1.1 → 0.2.0

package/dist/client.js

@@ -0,0 +1,293 @@
+/**
+ * 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';
+/** 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;
+    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;
+    }
+    /**
+     * 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 controller = new AbortController();
+        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,
+        };
+        const timeout = setTimeout(() => controller.abort(), resolvedTimeoutMs);
+        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 (!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)),
+                });
+            }
+            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);
+        }
+    }
+    /**
+     * 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"}

package/dist/index.js

@@ -1,233 +1,20 @@
-#!/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');
  * ```
- */
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { v4 as uuidv4 } from 'uuid';
-import { createClientFromEnv } from './api/client.js';
-import { searchToolsSchema, executeSearchTools, } from './tools/search.js';
-import { executeToolSchema, executeExecuteTool, } from './tools/execute.js';
-// ============================================================================
-// Server Configuration
-// ============================================================================
-const SERVER_NAME = 'qveris';
-const SERVER_VERSION = '0.1.0';
-/**
- * Main entry point for the Qveris MCP Server.
  *
- * Sets up the MCP server with stdio transport, registers the search_tools
- * and execute_tool handlers, and starts listening for requests.
- */
-async function main() {
-    // Initialize API client (validates QVERIS_API_KEY)
-    let client;
-    try {
-        client = createClientFromEnv();
-    }
-    catch (error) {
-        console.error(error instanceof Error ? error.message : 'Failed to initialize Qveris client');
-        process.exit(1);
-    }
-    // Generate a default session ID for this server instance
-    const defaultSessionId = uuidv4();
-    // Create MCP server
-    const server = new Server({
-        name: SERVER_NAME,
-        version: SERVER_VERSION,
-    }, {
-        capabilities: {
-            tools: {},
-        },
-    });
-    // =========================================================================
-    // Tool Handlers
-    // =========================================================================
-    /**
-     * Lists available tools.
-     * Returns the search_tools and execute_tool definitions.
-     */
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-        return {
-            tools: [
-                {
-                    name: 'search_tools',
-                    description: 'Search for available tools based on natural language queries. ' +
-                        'Returns relevant tools that can help accomplish tasks. ' +
-                        'Use this to discover tools before executing them.',
-                    inputSchema: searchToolsSchema,
-                },
-                {
-                    name: 'execute_tool',
-                    description: 'Execute a specific remote tool with provided parameters. ' +
-                        'The tool_id and search_id must come from a previous search_tools call. ' +
-                        'Pass parameters to the tool through params_to_tool as a JSON string.',
-                    inputSchema: executeToolSchema,
-                },
-            ],
-        };
-    });
-    /**
-     * Handles tool execution requests.
-     * Routes to the appropriate handler based on tool name.
-     */
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name, arguments: args } = request.params;
-        try {
-            if (name === 'search_tools') {
-                const input = args;
-                // Validate required fields
-                if (!input.query || typeof input.query !== 'string') {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    error: 'Missing required parameter: query',
-                                    hint: 'Provide a natural language query describing the tool capability you need',
-                                }),
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                const result = await executeSearchTools(client, input, defaultSessionId);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify(result, null, 2),
-                        },
-                    ],
-                };
-            }
-            if (name === 'execute_tool') {
-                const input = args;
-                // Validate required fields
-                const missingFields = [];
-                if (!input.tool_id)
-                    missingFields.push('tool_id');
-                if (!input.search_id)
-                    missingFields.push('search_id');
-                if (!input.params_to_tool)
-                    missingFields.push('params_to_tool');
-                if (missingFields.length > 0) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    error: `Missing required parameters: ${missingFields.join(', ')}`,
-                                    hint: 'tool_id and search_id must come from a previous search_tools call',
-                                }),
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                const result = await executeExecuteTool(client, input, defaultSessionId);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify(result, null, 2),
-                        },
-                    ],
-                };
-            }
-            // Unknown tool
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            error: `Unknown tool: ${name}`,
-                            available_tools: ['search_tools', 'execute_tool'],
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        catch (error) {
-            // Handle API errors
-            if (isApiError(error)) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                error: error.message,
-                                status: error.status,
-                                details: error.details,
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            // Handle other errors (including fetch network errors)
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-            const errorCause = error instanceof Error && error.cause instanceof Error
-                ? error.cause.message
-                : undefined;
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            error: errorMessage,
-                            ...(errorCause && { cause: errorCause }),
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    // =========================================================================
-    // Start Server
-    // =========================================================================
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    // Log startup to stderr (stdout is reserved for MCP protocol)
-    console.error(`Qveris MCP Server v${SERVER_VERSION} started`);
-    console.error(`Session ID: ${defaultSessionId}`);
-}
-/**
- * Type guard for API errors.
+ * @module @qverisai/sdk
  */
-function isApiError(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        'status' in error &&
-        'message' in error);
-}
-// Run the server
-main().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-});
+export { Qveris } from './client.js';
+export { QverisApiError } from './errors.js';
+export * from './types.js';
 //# sourceMappingURL=index.js.map