@attrove/sdk 0.1.2 → 0.1.4

package/esm/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@attrove/sdk",
+  "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",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "attrove",
+    "sdk",
+    "api",
+    "ai",
+    "rag",
+    "retrieval-augmented-generation",
+    "context",
+    "llm"
+  ],
+  "author": "Attrove <support@attrove.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/attrove/attrove-js.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://docs.attrove.com",
+  "bugs": {
+    "url": "https://github.com/attrove/attrove-js/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "nx build sdk",
+    "test": "nx test sdk"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "~5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module"
+}

package/esm/src/__mocks__/version.js

@@ -0,0 +1,12 @@
+/**
+ * Mock version module for Jest tests.
+ *
+ * This avoids the import.meta.url ESM issue when running tests with ts-jest.
+ */
+export function getVersion() {
+    return '1.0.0-test';
+}
+export function resetVersionCache() {
+    // No-op in mock
+}
+//# sourceMappingURL=version.js.map

package/esm/src/__mocks__/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../../../../packages/sdk/src/__mocks__/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,UAAU,UAAU;IACxB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,gBAAgB;AAClB,CAAC"}

package/esm/src/admin-client.js

@@ -0,0 +1,216 @@
+/**
+ * Attrove Admin Client
+ *
+ * Server-to-server client for partner operations like user provisioning
+ * and integration token generation.
+ */
+import { HttpClient } from './utils/fetch';
+import { ValidationError } from './errors';
+import { ErrorCodes } from './types';
+import { isValidUUID, } from './types';
+import { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_MAX_RETRIES } from './constants';
+/**
+ * Validate the admin client configuration.
+ *
+ * @throws {ValidationError} If the configuration is invalid
+ */
+function validateAdminConfig(config) {
+    // Validate clientId
+    if (!config.clientId || typeof config.clientId !== 'string') {
+        throw new ValidationError('clientId is required and must be a non-empty string', ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'clientId' });
+    }
+    // Validate clientSecret
+    if (!config.clientSecret || typeof config.clientSecret !== 'string') {
+        throw new ValidationError('clientSecret is required and must be a non-empty string', ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'clientSecret' });
+    }
+    // Validate optional fields
+    if (config.timeout !== undefined && (typeof config.timeout !== 'number' || config.timeout <= 0)) {
+        throw new ValidationError('timeout must be a positive number in milliseconds', ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: 'timeout', value: config.timeout });
+    }
+    if (config.maxRetries !== undefined && (typeof config.maxRetries !== 'number' || config.maxRetries < 0)) {
+        throw new ValidationError('maxRetries must be a non-negative number', ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: 'maxRetries', value: config.maxRetries });
+    }
+}
+/**
+ * Users admin resource for managing users.
+ *
+ * Provides methods for creating users, generating integration tokens,
+ * and managing user data.
+ */
+export class AdminUsersResource {
+    constructor(http, clientId) {
+        this.http = http;
+        this.clientId = clientId;
+    }
+    /**
+     * 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 });
+     * ```
+     */
+    async create(options) {
+        const body = {
+            email: options.email,
+            client_id: this.clientId,
+        };
+        if (options.firstName)
+            body.first_name = options.firstName;
+        if (options.lastName)
+            body.last_name = options.lastName;
+        if (options.role)
+            body.role = options.role;
+        // API returns { id, token } but we rename to { id, apiKey } for clarity
+        // Route: POST /v1/users with X-Auth-Type: partner header
+        const response = await this.http.post('/v1/users', body);
+        return {
+            id: response.id,
+            apiKey: response.token,
+        };
+    }
+    /**
+     * 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}`;
+     * ```
+     */
+    async createConnectToken(userId) {
+        // Validate userId format
+        if (!isValidUUID(userId)) {
+            throw new ValidationError('userId must be a valid UUID format', ErrorCodes.VALIDATION_INVALID_FORMAT, { field: 'userId', expected: 'UUID format' });
+        }
+        const body = {
+            client_id: this.clientId,
+        };
+        // Route: POST /v1/users/:user_id/tokens with X-Auth-Type: partner header
+        return this.http.post(`/v1/users/${userId}/tokens`, body);
+    }
+    /**
+     * 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);
+     * ```
+     */
+    async delete(userId) {
+        // TODO: Implement user deletion endpoint
+        throw new Error('User deletion not yet implemented. This feature is coming soon.');
+    }
+}
+/**
+ * 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 class AttroveAdmin {
+    /**
+     * 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) {
+        // Validate configuration before proceeding
+        validateAdminConfig(config);
+        this.config = {
+            clientId: config.clientId,
+            clientSecret: config.clientSecret,
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            timeout: config.timeout ?? DEFAULT_TIMEOUT,
+            maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+            onRetry: config.onRetry,
+        };
+        this.http = new HttpClient({
+            baseUrl: this.config.baseUrl,
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            timeout: this.config.timeout,
+            maxRetries: this.config.maxRetries,
+            onRetry: this.config.onRetry,
+        });
+        // Initialize resources
+        this.users = new AdminUsersResource(this.http, this.config.clientId);
+    }
+}
+//# sourceMappingURL=admin-client.js.map

package/esm/src/admin-client.js.map

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

package/esm/src/client.js

@@ -0,0 +1,308 @@
+/**
+ * Attrove Client
+ *
+ * Main entry point for the Attrove SDK. Provides a simple, intuitive API
+ * for accessing user context through connected integrations.
+ */
+import { HttpClient } from './utils/fetch';
+import { StreamingClient, generateMessageId } from './utils/streaming';
+import { UsersResource } from './resources/users';
+import { MessagesResource } from './resources/messages';
+import { ConversationsResource } from './resources/conversations';
+import { IntegrationsResource } from './resources/integrations';
+import { QueryResource } from './resources/query';
+import { ValidationError } from './errors';
+import { ErrorCodes } from './types';
+import { isValidUUID, } from './types';
+import { DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DEFAULT_MAX_RETRIES } from './constants';
+/**
+ * Validate the Attrove client configuration.
+ *
+ * @throws {ValidationError} If the configuration is invalid
+ */
+function validateConfig(config) {
+    // Validate apiKey
+    if (!config.apiKey || typeof config.apiKey !== 'string') {
+        throw new ValidationError('apiKey is required and must be a non-empty string', ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'apiKey' });
+    }
+    if (!config.apiKey.startsWith('sk_')) {
+        throw new ValidationError('apiKey must start with "sk_" prefix. Make sure you are using a valid API key.', ErrorCodes.VALIDATION_INVALID_FORMAT, { field: 'apiKey', expected: 'sk_...' });
+    }
+    // Validate userId
+    if (!config.userId || typeof config.userId !== 'string') {
+        throw new ValidationError('userId is required and must be a non-empty string', ErrorCodes.VALIDATION_REQUIRED_FIELD, { field: 'userId' });
+    }
+    if (!isValidUUID(config.userId)) {
+        throw new ValidationError('userId must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000")', ErrorCodes.VALIDATION_INVALID_FORMAT, { field: 'userId', expected: 'UUID format' });
+    }
+    // Validate optional fields
+    if (config.timeout !== undefined && (typeof config.timeout !== 'number' || config.timeout <= 0)) {
+        throw new ValidationError('timeout must be a positive number in milliseconds', ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: 'timeout', value: config.timeout });
+    }
+    if (config.maxRetries !== undefined && (typeof config.maxRetries !== 'number' || config.maxRetries < 0)) {
+        throw new ValidationError('maxRetries must be a non-negative number', ErrorCodes.VALIDATION_OUT_OF_RANGE, { field: 'maxRetries', value: config.maxRetries });
+    }
+}
+/**
+ * The Attrove client for accessing user context.
+ *
+ * This is the main entry point for the Attrove SDK. It provides methods for:
+ * - Querying user context with AI (query, search)
+ * - Streaming query responses in real-time
+ * - Accessing user data, messages, conversations, and integrations
+ *
+ * @example
+ * ```ts
+ * import { Attrove } from '@attrove/sdk';
+ *
+ * const attrove = new Attrove({
+ *   apiKey: 'sk_...',
+ *   userId: 'user-uuid'
+ * });
+ *
+ * // 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');
+ * ```
+ */
+export class Attrove {
+    /**
+     * Create a new Attrove client.
+     *
+     * @param config - Client configuration
+     * @throws {ValidationError} If the configuration is invalid (missing apiKey, invalid userId format, etc.)
+     *
+     * @example
+     * ```ts
+     * const attrove = new Attrove({
+     *   apiKey: 'sk_...',
+     *   userId: 'user-uuid',
+     *   timeout: 60000,  // 60 seconds
+     *   onRetry: (info) => console.log(`Retrying (${info.attempt}/${info.maxRetries})...`)
+     * });
+     * ```
+     */
+    constructor(config) {
+        // Validate configuration before proceeding
+        validateConfig(config);
+        this.config = {
+            apiKey: config.apiKey,
+            userId: config.userId,
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            timeout: config.timeout ?? DEFAULT_TIMEOUT,
+            maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+            onRetry: config.onRetry,
+        };
+        this.http = new HttpClient({
+            baseUrl: this.config.baseUrl,
+            apiKey: this.config.apiKey,
+            userId: this.config.userId,
+            timeout: this.config.timeout,
+            maxRetries: this.config.maxRetries,
+            onRetry: this.config.onRetry,
+        });
+        // Initialize resources
+        this.users = new UsersResource(this.http, this.config.userId);
+        this.messages = new MessagesResource(this.http, this.config.userId);
+        this.conversations = new ConversationsResource(this.http, this.config.userId);
+        this.integrations = new IntegrationsResource(this.http, this.config.userId);
+        this.queryResource = new QueryResource(this.http, this.config.userId);
+    }
+    /**
+     * Query the user's unified context with AI.
+     *
+     * This is the primary method for asking questions about the user's data.
+     * It performs semantic search across all connected integrations and returns
+     * an AI-generated answer based on the relevant context.
+     *
+     * @param prompt - The natural language question to answer
+     * @param options - Query options including history, filters, etc.
+     * @returns AI-generated answer with source references
+     *
+     * @throws {AuthenticationError} If the API key is invalid or expired
+     * @throws {ValidationError} If the request parameters are invalid
+     * @throws {RateLimitError} If rate limits are exceeded
+     * @throws {NetworkError} If unable to reach the API
+     * @throws {ServerError} If the server encounters an error
+     *
+     * @example
+     * ```ts
+     * // Simple query
+     * const response = await attrove.query('What did Sarah say about the Q4 budget?');
+     * console.log(response.answer);
+     *
+     * // Multi-turn conversation
+     * let history: ConversationMessage[] = [];
+     *
+     * const first = await attrove.query('What meetings do I have tomorrow?');
+     * history = first.history;
+     *
+     * const followUp = await attrove.query('Who is attending?', { history });
+     * console.log(followUp.answer);
+     * ```
+     */
+    async query(prompt, options) {
+        return this.queryResource.query(prompt, options);
+    }
+    /**
+     * Semantic search across the user's context.
+     *
+     * Returns raw matching messages grouped by conversation, without AI summarization.
+     * Use this when you need full control over how results are displayed.
+     *
+     * @param query - The search query (semantic, not keyword-based)
+     * @param options - Search options including filters, date range, etc.
+     * @returns Matching messages grouped by conversation
+     *
+     * @throws {AuthenticationError} If the API key is invalid or expired
+     * @throws {ValidationError} If the request parameters are invalid
+     * @throws {RateLimitError} If rate limits are exceeded
+     * @throws {NetworkError} If unable to reach the API
+     * @throws {ServerError} If the server encounters an error
+     *
+     * @example
+     * ```ts
+     * const results = await attrove.search('quarterly report', {
+     *   afterDate: '2024-01-01T00:00:00Z',
+     *   includeBodyText: true
+     * });
+     *
+     * for (const [convId, conv] of Object.entries(results.conversations)) {
+     *   console.log(`Conversation: ${conv.conversation_name}`);
+     *   for (const [threadId, messages] of Object.entries(conv.threads)) {
+     *     console.log(`  Thread ${threadId}: ${messages.length} messages`);
+     *   }
+     * }
+     * ```
+     */
+    async search(query, options) {
+        return this.queryResource.search(query, options);
+    }
+    /**
+     * Stream a query response in real-time.
+     *
+     * Connects to the WebSocket endpoint and streams the AI-generated answer
+     * as it's being generated. Useful for displaying results progressively.
+     *
+     * @param prompt - The natural language question to answer
+     * @param options - Query and streaming options
+     * @returns Stream result with full answer and metadata
+     *
+     * @throws {AuthenticationError} If the API key is invalid or expired
+     * @throws {NetworkError} If WebSocket connection fails
+     * @throws {TimeoutError} If connection times out
+     * @throws {AttroveError} If the server returns an error
+     *
+     * @example
+     * ```ts
+     * const result = await attrove.stream('What happened in the meeting?', {
+     *   onChunk: (chunk) => process.stdout.write(chunk),
+     *   onState: (state) => console.log('State:', state),
+     * });
+     *
+     * console.log('\\nFull answer:', result.answer);
+     * ```
+     */
+    async stream(prompt, options = {}) {
+        const { history = [], timezone, integrationIds, conversationIds, allowBotMessages, includeSources, ...streamOptions } = options;
+        // Add the user's prompt to history
+        const fullHistory = [
+            ...history,
+            { role: 'user', content: prompt },
+        ];
+        // Extract query options (separate from stream options)
+        const queryOptions = {
+            timezone,
+            integrationIds,
+            conversationIds,
+            allowBotMessages,
+            includeSources,
+        };
+        const streaming = new StreamingClient(this.config.baseUrl, this.config.apiKey);
+        try {
+            const messageId = generateMessageId();
+            return await streaming.stream(prompt, messageId, fullHistory, queryOptions, streamOptions);
+        }
+        finally {
+            streaming.close();
+        }
+    }
+    /**
+     * Get meeting preparation brief.
+     *
+     * Retrieves context about attendees, recent conversations, and relevant
+     * information to help prepare for an upcoming meeting.
+     *
+     * @experimental This method is not yet implemented and will throw an error.
+     *
+     * @param meetingId - Meeting ID (UUID format)
+     * @returns Meeting brief with attendee info and relevant context
+     *
+     * @throws {Error} Always throws - not yet implemented
+     *
+     * @example
+     * ```ts
+     * // Not yet available
+     * const brief = await attrove.brief('meeting-uuid-here');
+     * console.log(brief.summary);
+     * console.log('Attendees:', brief.attendees);
+     * ```
+     */
+    async brief(meetingId) {
+        // TODO: Implement meeting brief endpoint
+        throw new Error('Meeting brief not yet implemented. This feature is coming soon.');
+    }
+    /**
+     * Get information about an entity (person, company, etc.).
+     *
+     * Retrieves profile information and interaction history for an entity
+     * identified from the user's communications.
+     *
+     * @experimental This method is not yet implemented and will throw an error.
+     *
+     * @param entityId - Entity ID (UUID format)
+     * @returns Entity profile with interaction history
+     *
+     * @throws {Error} Always throws - not yet implemented
+     *
+     * @example
+     * ```ts
+     * // Not yet available
+     * const entity = await attrove.entity('entity-uuid');
+     * console.log(`${entity.name}: ${entity.message_count} messages`);
+     * ```
+     */
+    async entity(entityId) {
+        // TODO: Implement entity endpoint
+        throw new Error('Entity lookup not yet implemented. This feature is coming soon.');
+    }
+    /**
+     * Get a conversation thread.
+     *
+     * Retrieves all messages in a specific conversation thread.
+     *
+     * @experimental This method is not yet implemented and will throw an error.
+     *
+     * @param conversationId - Conversation ID (UUID format)
+     * @returns Conversation thread with messages
+     *
+     * @throws {Error} Always throws - not yet implemented
+     *
+     * @example
+     * ```ts
+     * // Not yet available
+     * const thread = await attrove.thread('conversation-uuid-here');
+     * for (const msg of thread.messages) {
+     *   console.log(`${msg.sender_name}: ${msg.body_text}`);
+     * }
+     * ```
+     */
+    async thread(conversationId) {
+        // TODO: Implement thread endpoint
+        throw new Error('Thread retrieval not yet implemented. This feature is coming soon.');
+    }
+}
+//# sourceMappingURL=client.js.map

package/esm/src/client.js.map

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

package/esm/src/constants.js

@@ -0,0 +1,65 @@
+/**
+ * SDK Constants
+ *
+ * Centralized constants used across the SDK. Consolidating these ensures
+ * consistency and makes maintenance easier.
+ */
+/**
+ * SDK version string.
+ *
+ * This version is updated by the release process. Keep it in sync with
+ * the version in package.json. For programmatic access, use `getVersion()`
+ * from './version'.
+ */
+export const SDK_VERSION = '0.1.3';
+/**
+ * Default API base URL for Attrove services.
+ */
+export const DEFAULT_BASE_URL = 'https://api.attrove.com';
+/**
+ * Default request timeout in milliseconds.
+ */
+export const DEFAULT_TIMEOUT = 30000;
+/**
+ * Default number of retry attempts for failed requests.
+ */
+export const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Initial delay for retry backoff in milliseconds.
+ */
+export const INITIAL_RETRY_DELAY = 1000;
+/**
+ * HTTP status codes that trigger automatic retries.
+ */
+export const RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+/**
+ * Set of retryable status codes for O(1) lookup.
+ */
+export const RETRYABLE_STATUS_SET = new Set(RETRY_STATUS_CODES);
+/**
+ * WebSocket close code descriptions for better error messages.
+ */
+export const WS_CLOSE_CODES = {
+    1000: 'Normal closure',
+    1001: 'Server going away',
+    1002: 'Protocol error',
+    1003: 'Unsupported data type',
+    1005: 'No status code received',
+    1006: 'Connection lost abnormally (no close frame)',
+    1007: 'Invalid frame payload data',
+    1008: 'Policy violation',
+    1009: 'Message too large',
+    1010: 'Missing expected extension',
+    1011: 'Internal server error',
+    1012: 'Service restart',
+    1013: 'Try again later',
+    1014: 'Bad gateway',
+    1015: 'TLS handshake failure',
+};
+/**
+ * Get a human-readable description for a WebSocket close code.
+ */
+export function getWsCloseReason(code) {
+    return WS_CLOSE_CODES[code] || 'Unknown close reason';
+}
+//# sourceMappingURL=constants.js.map