@attrove/sdk 0.1.2 → 0.1.4

package/cjs/src/utils/streaming.js

@@ -0,0 +1,368 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMessageId = exports.StreamingClient = void 0;
+const types_1 = require("../types");
+const errors_1 = require("../errors");
+const types_2 = require("../types");
+const constants_1 = require("../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();
+ * }
+ * ```
+ */
+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 = constants_1.DEFAULT_TIMEOUT) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new errors_1.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 errors_1.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 = (0, constants_1.getWsCloseReason)(event.code);
+                        reject(new errors_1.NetworkError(`WebSocket closed during connection (code ${event.code}: ${reason}). This may indicate a server issue or network problem.`));
+                    }
+                };
+            }
+            catch (err) {
+                clearTimeout(timeoutId);
+                reject(new errors_1.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 = constants_1.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 errors_1.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 errors_1.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 errors_1.AttroveError(`Failed to parse stream message: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`, types_2.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 (!(0, types_1.isValidStreamFrame)(parsed)) {
+                    const error = new errors_1.AttroveError('Received invalid stream frame format from server', types_2.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 errors_1.AttroveError(frame.error, types_2.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 errors_1.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 = (0, constants_1.getWsCloseReason)(event.code);
+                    const error = new errors_1.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();
+    }
+}
+exports.StreamingClient = StreamingClient;
+/**
+ * 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
+ */
+function generateMessageId() {
+    return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+exports.generateMessageId = generateMessageId;
+//# sourceMappingURL=streaming.js.map

package/cjs/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/cjs/src/version.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * SDK Version Utilities
+ *
+ * Provides version information for the SDK using a static constant.
+ * This ensures browser compatibility while keeping the API consistent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetVersionCache = exports.getVersion = void 0;
+const constants_1 = require("./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.
+ */
+function getVersion() {
+    return constants_1.SDK_VERSION;
+}
+exports.getVersion = getVersion;
+/**
+ * Reset the cached version.
+ *
+ * @deprecated This function has no effect. Version is now a static constant.
+ * Kept for API compatibility with existing tests.
+ */
+function resetVersionCache() {
+    // No-op - version is now a static constant
+}
+exports.resetVersionCache = resetVersionCache;
+//# sourceMappingURL=version.js.map

package/cjs/src/version.js.map

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

package/esm/README.md

@@ -0,0 +1,247 @@
+# @attrove/sdk
+
+Official TypeScript SDK for the Attrove API. Access AI-powered context from your users' Gmail, Slack, Google Calendar, and more.
+
+## Installation
+
+```bash
+npm install @attrove/sdk
+# or
+yarn add @attrove/sdk
+# or
+pnpm add @attrove/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Attrove } from '@attrove/sdk';
+
+// Create a client
+const attrove = new Attrove({
+  apiKey: 'sk_...',  // API key from your dashboard
+  userId: 'user-uuid' // User ID from provisioning
+});
+
+// Query user's context
+const response = await attrove.query('What meetings do I have tomorrow?');
+console.log(response.answer);
+
+// Search for specific information
+const results = await attrove.search('quarterly report');
+```
+
+## Core Methods
+
+### `query(prompt, options?)`
+
+Ask questions about the user's unified context with AI-generated answers.
+
+```typescript
+// Simple query
+const response = await attrove.query('What did Sarah say about the Q4 budget?');
+console.log(response.answer);
+
+// Multi-turn conversation - pass history from previous response
+let history = response.history;
+const followUp = await attrove.query('What about Q3?', { history });
+// Update history for subsequent queries
+history = followUp.history;
+
+// With filters
+const filtered = await attrove.query('Latest updates', {
+  integrationIds: ['integration-uuid'],  // Only search specific integration
+  includeSources: true                   // Include source snippets
+});
+```
+
+### `search(query, options?)`
+
+Semantic search that returns raw messages without AI summarization.
+
+```typescript
+const results = await attrove.search('product launch', {
+  afterDate: '2024-01-01T00:00:00Z',
+  senderDomains: ['acme.com'],
+  includeBodyText: true
+});
+
+for (const [convId, conv] of Object.entries(results.conversations)) {
+  console.log(`Conversation: ${conv.conversation_name}`);
+}
+```
+
+## Resource Namespaces
+
+### Users
+
+```typescript
+// Get user profile and integrations
+const { user, integrations } = await attrove.users.get();
+
+// Update user profile
+await attrove.users.update({
+  timezone: 'America/New_York'
+});
+
+// Get sync statistics
+const stats = await attrove.users.syncStats();
+console.log(`Messages: ${stats.totals.messages.count}`);
+```
+
+### Messages
+
+```typescript
+// List messages
+const { data, pagination } = await attrove.messages.list({
+  limit: 20,
+  expand: ['body_text']
+});
+
+// Get specific messages (e.g., after a query)
+const { data: messages } = await attrove.messages.list({
+  ids: response.used_message_ids,
+  expand: ['body_text']
+});
+
+// Get a single message by ID
+const message = await attrove.messages.get('message-uuid');
+```
+
+### Conversations
+
+```typescript
+// List conversations
+const { data: conversations } = await attrove.conversations.list({
+  syncedOnly: true
+});
+
+// Update sync settings
+await attrove.conversations.updateSync([
+  { id: 'conversation-uuid-1', importMessages: true },
+  { id: 'conversation-uuid-2', importMessages: false }
+]);
+```
+
+### Integrations
+
+```typescript
+// List integrations
+const integrations = await attrove.integrations.list();
+
+// Disconnect an integration
+await attrove.integrations.disconnect('integration-uuid');
+```
+
+## Server-to-Server (Admin) API
+
+Use the admin client for operations that require partner authentication:
+
+```typescript
+import { Attrove } from '@attrove/sdk';
+
+// Create admin client
+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',
+  firstName: 'John',
+  lastName: 'Doe'
+});
+
+// Generate integration token for OAuth flow
+const { token: connectToken, expires_at } = await admin.users.createConnectToken(id);
+
+// Use the apiKey for subsequent API calls
+const attrove = new Attrove({ apiKey, userId: id });
+
+// Redirect user to OAuth flow
+// The URL format depends on your deployment - check your dashboard for the exact URL
+// Example: const oauthUrl = `${YOUR_BASE_URL}/connect/gmail?token=${connectToken}`;
+```
+
+## Error Handling
+
+The SDK provides typed errors for better error handling:
+
+```typescript
+import {
+  Attrove,
+  AttroveError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError
+} from '@attrove/sdk';
+
+try {
+  const response = await attrove.query('...');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+  } else if (error instanceof NotFoundError) {
+    console.log('Resource not found');
+  } else if (error instanceof AttroveError) {
+    console.log(`Error: ${error.code} - ${error.message}`);
+  }
+}
+```
+
+## Streaming (Advanced)
+
+For real-time streaming of query responses:
+
+```typescript
+const result = await attrove.stream('What happened in the meeting?', {
+  onChunk: (chunk) => process.stdout.write(chunk),
+  onState: (state) => console.log('State:', state),
+  onEnd: (reason) => console.log('Stream ended:', reason)
+});
+
+console.log('Full answer:', result.answer);
+```
+
+> **Note:** Streaming uses WebSocket connections and requires the same API key authentication as other SDK methods. It is primarily intended for end-user facing applications where progressive display of responses improves the user experience.
+
+## Configuration
+
+```typescript
+const attrove = new Attrove({
+  apiKey: 'sk_...',           // Required: API key
+  userId: 'user-uuid',        // Required: User ID
+  baseUrl: 'https://api.attrove.com',  // Optional: API base URL
+  timeout: 30000,             // Optional: Request timeout (ms)
+  maxRetries: 3               // Optional: Retry attempts
+});
+```
+
+## TypeScript Support
+
+The SDK is fully typed. Import types as needed:
+
+```typescript
+import {
+  QueryOptions,
+  QueryResponse,
+  SearchOptions,
+  SearchResponse,
+  User,
+  Message,
+  Integration,
+  ConversationMessage
+} from '@attrove/sdk';
+```
+
+## Requirements
+
+- Node.js 18.0.0 or later
+- TypeScript 4.7+ (if using TypeScript)
+
+## License
+
+MIT