@attrove/sdk 0.1.3 → 0.1.4

package/esm/src/utils/streaming.js

@@ -0,0 +1,363 @@
+/**
+ * WebSocket Streaming Utilities
+ *
+ * Provides WebSocket connection management for streaming LLM responses.
+ *
+ * Security Note: The WebSocket connection passes the authentication token
+ * as a query parameter. While this is a common pattern for WebSocket auth
+ * (since WebSocket doesn't support custom headers in browsers), be aware that:
+ * - Tokens may appear in server access logs
+ * - Tokens may be visible in network inspection tools
+ * - Using short-lived tokens is recommended for production use
+ */
+import { isValidStreamFrame } from '../types';
+import { AttroveError, NetworkError, TimeoutError } from '../errors';
+import { ErrorCodes } from '../types';
+import { getWsCloseReason, DEFAULT_TIMEOUT } from '../constants';
+/**
+ * Streaming query client for WebSocket-based LLM responses.
+ *
+ * Provides real-time streaming of AI-generated answers with support for:
+ * - Progress callbacks for each chunk
+ * - State change notifications
+ * - Cancellation via AbortSignal
+ * - Automatic cleanup on completion or error
+ *
+ * @example
+ * ```ts
+ * const streaming = new StreamingClient(baseUrl, apiKey);
+ * try {
+ *   const result = await streaming.stream(query, messageId, history, options, {
+ *     onChunk: (chunk) => console.log(chunk),
+ *   });
+ *   console.log('Answer:', result.answer);
+ * } finally {
+ *   streaming.close();
+ * }
+ * ```
+ */
+export class StreamingClient {
+    constructor(baseUrl, token) {
+        this.ws = null;
+        this.currentMessageId = null;
+        // Convert HTTP URL to WebSocket URL
+        const wsBaseUrl = baseUrl.replace(/^http/, 'ws');
+        this.wsUrl = `${wsBaseUrl}/ws/llm-stream`;
+        this.token = token;
+    }
+    /**
+     * Connect to the WebSocket server.
+     *
+     * @throws {TimeoutError} If connection times out
+     * @throws {NetworkError} If connection fails
+     */
+    async connect(timeout = DEFAULT_TIMEOUT) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new TimeoutError(`WebSocket connection timed out after ${timeout}ms`));
+            }, timeout);
+            try {
+                // Note: Token is passed as query parameter because WebSocket API
+                // doesn't support custom headers in browsers. This is a common pattern
+                // but means the token may appear in server logs.
+                const url = new URL(this.wsUrl);
+                url.searchParams.set('token', this.token);
+                const ws = new WebSocket(url.toString());
+                ws.onopen = () => {
+                    clearTimeout(timeoutId);
+                    resolve(ws);
+                };
+                ws.onerror = () => {
+                    clearTimeout(timeoutId);
+                    reject(new NetworkError(`WebSocket connection to ${this.wsUrl} failed. Check your network connection and ensure the API endpoint is accessible.`));
+                };
+                ws.onclose = (event) => {
+                    if (event.code !== 1000) {
+                        clearTimeout(timeoutId);
+                        const reason = getWsCloseReason(event.code);
+                        reject(new NetworkError(`WebSocket closed during connection (code ${event.code}: ${reason}). This may indicate a server issue or network problem.`));
+                    }
+                };
+            }
+            catch (err) {
+                clearTimeout(timeoutId);
+                reject(new NetworkError(`Failed to create WebSocket: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        });
+    }
+    /**
+     * Stream a query response.
+     *
+     * @param query - The natural language question to answer
+     * @param messageId - Unique message ID for tracking this stream
+     * @param history - Conversation history for context
+     * @param queryOptions - Query options (filters, timezone, etc.)
+     * @param streamOptions - Streaming options (callbacks, timeout, etc.)
+     * @returns Stream result with full answer and metadata
+     *
+     * @throws {NetworkError} If WebSocket connection fails or errors during streaming
+     * @throws {TimeoutError} If connection times out
+     * @throws {AttroveError} If the server returns an error
+     */
+    async stream(query, messageId, history, queryOptions = {}, streamOptions = {}) {
+        const { onChunk, onState, onStart, onError, onEnd, onWarning, signal, timeout = DEFAULT_TIMEOUT } = streamOptions;
+        // Store warning callback for use in cancel() and cleanup()
+        this.onWarning = onWarning;
+        let answer = '';
+        let usedMessageIds = [];
+        let cancelled = false;
+        let completed = false;
+        // Connect to WebSocket
+        this.ws = await this.connect(timeout);
+        this.currentMessageId = messageId;
+        return new Promise((resolve, reject) => {
+            if (!this.ws) {
+                reject(new NetworkError('WebSocket not connected'));
+                return;
+            }
+            const ws = this.ws;
+            // Track abort handler for cleanup
+            let abortHandler;
+            // Cleanup function to remove listeners and close connection
+            const cleanupAndFinish = () => {
+                completed = true;
+                if (signal && abortHandler) {
+                    signal.removeEventListener('abort', abortHandler);
+                }
+                this.cleanup();
+            };
+            // Handle abort signal
+            if (signal) {
+                abortHandler = () => {
+                    if (!completed) {
+                        this.cancel();
+                        cancelled = true;
+                    }
+                };
+                signal.addEventListener('abort', abortHandler);
+                // Check if already aborted
+                if (signal.aborted) {
+                    this.cancel();
+                    cancelled = true;
+                }
+            }
+            // Send the query to the server after connection is established
+            const queryPayload = {
+                type: 'query',
+                message_id: messageId,
+                query,
+                client_timezone: queryOptions.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone,
+                history: history.length > 0 ? history : undefined,
+                integration_ids: queryOptions.integrationIds,
+                conversation_ids: queryOptions.conversationIds,
+                allow_bot_messages: queryOptions.allowBotMessages,
+                expand: queryOptions.includeSources ? 'sources' : undefined,
+            };
+            try {
+                ws.send(JSON.stringify(queryPayload));
+            }
+            catch (err) {
+                const error = new NetworkError(`Failed to send query to server: ${err instanceof Error ? err.message : String(err)}`);
+                onError?.(error);
+                cleanupAndFinish();
+                reject(error);
+                return;
+            }
+            ws.onmessage = (event) => {
+                // Parse JSON separately to provide better error messages
+                let parsed;
+                try {
+                    parsed = JSON.parse(event.data);
+                }
+                catch (parseErr) {
+                    const error = new AttroveError(`Failed to parse stream message: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`, ErrorCodes.INTERNAL_ERROR, undefined, { category: 'parse', rawDataPreview: String(event.data).substring(0, 200) });
+                    onError?.(error);
+                    cleanupAndFinish();
+                    reject(error);
+                    return;
+                }
+                // Validate the frame structure at runtime
+                if (!isValidStreamFrame(parsed)) {
+                    const error = new AttroveError('Received invalid stream frame format from server', ErrorCodes.INTERNAL_ERROR, undefined, { category: 'parse', rawDataPreview: JSON.stringify(parsed).substring(0, 200) });
+                    onError?.(error);
+                    cleanupAndFinish();
+                    reject(error);
+                    return;
+                }
+                const frame = parsed;
+                // Verify message ID matches - log mismatch for debugging
+                if (frame.message_id !== messageId) {
+                    const warningContext = {
+                        expected: messageId,
+                        received: frame.message_id,
+                        frameType: frame.type,
+                    };
+                    if (onWarning) {
+                        onWarning('Received message with mismatched message_id, ignoring', warningContext);
+                    }
+                    else {
+                        // prettier-ignore
+                        console.warn('[AttroveSDK] Received message with mismatched message_id, ignoring:', warningContext);
+                    }
+                    return;
+                }
+                // Process the parsed frame - callback errors will propagate naturally
+                switch (frame.type) {
+                    case 'stream_start':
+                        onStart?.();
+                        break;
+                    case 'state':
+                        onState?.(frame.state);
+                        break;
+                    case 'chunk':
+                        answer += frame.content;
+                        onChunk?.(frame.content);
+                        break;
+                    case 'message_ids':
+                        usedMessageIds = frame.used_message_ids;
+                        break;
+                    case 'error': {
+                        const error = new AttroveError(frame.error, ErrorCodes.INTERNAL_ERROR);
+                        onError?.(error);
+                        cleanupAndFinish();
+                        reject(error);
+                        break;
+                    }
+                    case 'end': {
+                        cancelled = frame.reason === 'cancelled';
+                        if (frame.used_message_ids) {
+                            usedMessageIds = frame.used_message_ids;
+                        }
+                        onEnd?.(frame.reason);
+                        // Build updated history
+                        const updatedHistory = [
+                            ...history,
+                            { role: 'assistant', content: answer },
+                        ];
+                        cleanupAndFinish();
+                        resolve({
+                            answer,
+                            history: updatedHistory,
+                            usedMessageIds,
+                            cancelled,
+                        });
+                        break;
+                    }
+                }
+            };
+            ws.onerror = () => {
+                if (!completed) {
+                    const error = new NetworkError(`WebSocket error during streaming. The connection was interrupted. You may need to retry the query.`);
+                    onError?.(error);
+                    cleanupAndFinish();
+                    reject(error);
+                }
+            };
+            ws.onclose = (event) => {
+                if (!completed && event.code !== 1000) {
+                    const reason = getWsCloseReason(event.code);
+                    const error = new NetworkError(`WebSocket closed unexpectedly (code ${event.code}: ${reason}). The stream may need to be retried.`);
+                    onError?.(error);
+                    cleanupAndFinish();
+                    reject(error);
+                }
+            };
+        });
+    }
+    /**
+     * Cancel the current stream.
+     *
+     * Sends a stop message to the server to cancel the ongoing query.
+     * This is a best-effort operation - if the connection is already
+     * closed or in an invalid state, the cancellation will return
+     * a result indicating the failure reason but won't throw an error.
+     *
+     * @returns Result object with success status and reason
+     *
+     * @example
+     * ```ts
+     * const result = streaming.cancel();
+     * if (!result.success) {
+     *   if (result.reason === 'no_active_stream') {
+     *     console.log('No stream to cancel');
+     *   } else if (result.reason === 'send_failed') {
+     *     console.error('Failed to send cancel:', result.error);
+     *   }
+     * }
+     * ```
+     */
+    cancel() {
+        if (!this.ws || !this.currentMessageId) {
+            return { success: false, reason: 'no_active_stream' };
+        }
+        try {
+            this.ws.send(JSON.stringify({
+                type: 'stop',
+                message_id: this.currentMessageId,
+            }));
+            return { success: true, reason: 'sent' };
+        }
+        catch (err) {
+            // Cancellation is best-effort - the WebSocket may already be closed
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            const context = { messageId: this.currentMessageId, wsReadyState: this.ws?.readyState };
+            if (this.onWarning) {
+                this.onWarning('Failed to send cancel message', { error: errorMessage, ...context });
+            }
+            else {
+                // prettier-ignore
+                console.warn('[AttroveSDK] Failed to send cancel message:', errorMessage, context);
+            }
+            return { success: false, reason: 'send_failed', error: errorMessage };
+        }
+    }
+    /**
+     * Clean up resources.
+     *
+     * Closes the WebSocket connection and resets internal state.
+     * This is called automatically when a stream completes, errors,
+     * or is cancelled.
+     */
+    cleanup() {
+        if (this.ws) {
+            try {
+                this.ws.close(1000);
+            }
+            catch (err) {
+                // Cleanup is best-effort - the WebSocket may already be closed
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                if (this.onWarning) {
+                    this.onWarning('Failed to close WebSocket cleanly', { error: errorMessage });
+                }
+                else {
+                    // prettier-ignore
+                    console.warn('[AttroveSDK] Failed to close WebSocket cleanly:', errorMessage);
+                }
+            }
+            this.ws = null;
+        }
+        this.currentMessageId = null;
+        this.onWarning = undefined;
+    }
+    /**
+     * Close the connection.
+     *
+     * Call this when you're done with the streaming client to ensure
+     * all resources are properly cleaned up.
+     */
+    close() {
+        this.cleanup();
+    }
+}
+/**
+ * Generate a unique message ID for streaming.
+ *
+ * Creates a message ID in the format `msg_{timestamp}_{random}` that is
+ * sufficiently unique for tracking individual stream requests.
+ *
+ * @returns A unique message ID string
+ */
+export function generateMessageId() {
+    return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+//# sourceMappingURL=streaming.js.map

package/esm/src/utils/streaming.js.map

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

package/esm/src/version.js

@@ -0,0 +1,26 @@
+/**
+ * SDK Version Utilities
+ *
+ * Provides version information for the SDK using a static constant.
+ * This ensures browser compatibility while keeping the API consistent.
+ */
+import { SDK_VERSION } from './constants';
+/**
+ * Get the SDK version.
+ *
+ * Returns the SDK version string from the hardcoded constant.
+ * This value should be kept in sync with package.json during releases.
+ */
+export function getVersion() {
+    return SDK_VERSION;
+}
+/**
+ * Reset the cached version.
+ *
+ * @deprecated This function has no effect. Version is now a static constant.
+ * Kept for API compatibility with existing tests.
+ */
+export function resetVersionCache() {
+    // No-op - version is now a static constant
+}
+//# sourceMappingURL=version.js.map

package/esm/src/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../../../packages/sdk/src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,2CAA2C;AAC7C,CAAC"}

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "@attrove/sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Official TypeScript SDK for the Attrove API - AI-powered context retrieval for your apps",
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./cjs/index.js",
+  "module": "./esm/index.js",
+  "types": "./types/src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts",
-      "require": "./src/index.ts"
+      "import": {
+        "types": "./types/src/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "require": {
+        "types": "./types/src/index.d.ts",
+        "default": "./cjs/index.js"
+      }
     }
   },
   "files": [
-    "dist",
+    "cjs",
+    "esm",
+    "types",
     "README.md"
   ],
   "sideEffects": false,
@@ -52,4 +59,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/types/src/__mocks__/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Mock version module for Jest tests.
+ *
+ * This avoids the import.meta.url ESM issue when running tests with ts-jest.
+ */
+export declare function getVersion(): string;
+export declare function resetVersionCache(): void;
+//# sourceMappingURL=version.d.ts.map

package/types/src/__mocks__/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/src/__mocks__/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/types/src/admin-client.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Attrove Admin Client
+ *
+ * Server-to-server client for partner operations like user provisioning
+ * and integration token generation.
+ */
+import { HttpClient } from './utils/fetch';
+import { AttroveAdminConfig, CreateUserOptions, CreateUserResponse, CreateTokenResponse } from './types';
+/**
+ * Users admin resource for managing users.
+ *
+ * Provides methods for creating users, generating integration tokens,
+ * and managing user data.
+ */
+export declare class AdminUsersResource {
+    private readonly http;
+    private readonly clientId;
+    constructor(http: HttpClient, clientId: string);
+    /**
+     * Create or retrieve a user.
+     *
+     * Creates a new user by email, or retrieves an existing user if one exists.
+     * Returns an API key (sk_) for authenticating requests on behalf of this user.
+     *
+     * @param options - User creation options
+     * @returns User ID and API key
+     *
+     * @throws {ValidationError} If the email is invalid
+     * @throws {AuthenticationError} If partner credentials are invalid
+     * @throws {RateLimitError} If rate limits are exceeded
+     * @throws {NetworkError} If unable to reach the API
+     *
+     * @example
+     * ```ts
+     * const admin = Attrove.admin({ clientId, clientSecret });
+     *
+     * const { id, apiKey } = await admin.users.create({
+     *   email: 'user@example.com',
+     *   firstName: 'John',
+     *   lastName: 'Doe'
+     * });
+     *
+     * // Use the apiKey to make API calls on behalf of this user
+     * const attrove = new Attrove({ apiKey, userId: id });
+     * ```
+     */
+    create(options: CreateUserOptions): Promise<CreateUserResponse>;
+    /**
+     * Create an integration token for a user.
+     *
+     * Generates a short-lived token (pit_) for initiating OAuth flows.
+     * Use this token to redirect end-users to connect their integrations.
+     *
+     * @param userId - User ID (UUID format)
+     * @returns Integration token and expiration time
+     *
+     * @throws {ValidationError} If the userId is not a valid UUID
+     * @throws {AuthenticationError} If partner credentials are invalid
+     * @throws {NotFoundError} If the user doesn't exist
+     * @throws {RateLimitError} If rate limits are exceeded
+     * @throws {NetworkError} If unable to reach the API
+     *
+     * @example
+     * ```ts
+     * const admin = Attrove.admin({ clientId, clientSecret });
+     *
+     * const { token, expires_at } = await admin.users.createConnectToken(userId);
+     *
+     * // Redirect user to OAuth flow with this token
+     * const oauthUrl = `https://connect.attrove.com/oauth/gmail?token=${token}`;
+     * ```
+     */
+    createConnectToken(userId: string): Promise<CreateTokenResponse>;
+    /**
+     * Delete a user.
+     *
+     * Permanently deletes a user and all associated data.
+     *
+     * @experimental This method is not yet implemented and will throw an error.
+     *
+     * @param userId - User ID (UUID format)
+     *
+     * @throws {Error} Always throws - not yet implemented
+     *
+     * @example
+     * ```ts
+     * // Not yet available
+     * const admin = Attrove.admin({ clientId, clientSecret });
+     * await admin.users.delete(userId);
+     * ```
+     */
+    delete(userId: string): Promise<void>;
+}
+/**
+ * Admin client for server-to-server operations.
+ *
+ * Use this client for operations that require partner authentication:
+ * - Creating users
+ * - Generating integration tokens
+ * - Managing user data
+ *
+ * @example
+ * ```ts
+ * import { Attrove } from '@attrove/sdk';
+ *
+ * const admin = Attrove.admin({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret'
+ * });
+ *
+ * // Create a user
+ * const { id, apiKey } = await admin.users.create({
+ *   email: 'user@example.com'
+ * });
+ *
+ * // Generate an integration token
+ * const { token: connectToken } = await admin.users.createConnectToken(id);
+ * ```
+ */
+export declare class AttroveAdmin {
+    private readonly http;
+    private readonly config;
+    /**
+     * Users resource for managing users.
+     */
+    readonly users: AdminUsersResource;
+    /**
+     * Create a new admin client.
+     *
+     * @param config - Admin client configuration
+     * @throws {ValidationError} If the configuration is invalid (missing clientId, clientSecret, etc.)
+     *
+     * @example
+     * ```ts
+     * const admin = new AttroveAdmin({
+     *   clientId: 'your-client-id',
+     *   clientSecret: 'your-client-secret',
+     *   timeout: 60000  // 60 seconds
+     * });
+     * ```
+     */
+    constructor(config: AttroveAdminConfig);
+}
+//# sourceMappingURL=admin-client.d.ts.map

package/types/src/admin-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-client.d.ts","sourceRoot":"","sources":["../../../../../packages/sdk/src/admin-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EAEpB,MAAM,SAAS,CAAC;AA6CjB;;;;;GAKG;AACH,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,MAAM;IAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmBrE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAkBtE;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAI5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsF;IAE7G;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IAEnC;;;;;;;;;;;;;;OAcG;gBACS,MAAM,EAAE,kBAAkB;CAyBvC"}