@attrove/sdk

Official TypeScript SDK for the Attrove API. Access AI-powered context from your users' Gmail, Slack, Google Calendar, and more.

Installation

npm install @attrove/sdk
# or
yarn add @attrove/sdk
# or
pnpm add @attrove/sdk

Quick Start

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.

// 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.

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

// 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

// 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

// 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

// 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:

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: '[email protected]',
  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:

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:

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

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:

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