@attrove/sdk

@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);
console.log(response.used_message_ids); // msg_xxx IDs
console.log(response.used_meeting_ids); // mtg_xxx IDs
console.log(response.used_event_ids);   // evt_xxx IDs

// 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: ['int_xxx'],           // Only search specific integration
  includeSources: true                   // Include source snippets
});

// Custom instructions + reference context
const custom = await attrove.query('Compare Alice and Bob on budget adherence.', {
  // instructions: control output format and behavior (overrides default style)
  instructions: 'Return a markdown table with columns: Person, On-Track, Key Evidence.',
  // context: ground-truth data the AI treats as authoritative (influences query rewriting, not vector search)
  context: 'FY26 budget: Engineering $2M, Marketing $800K. Alice owns Engineering, Bob owns Marketing.',
});

search(query, options?)

Semantic search that returns raw matches across messages, meetings, and events without AI summarization.

const results = await attrove.search('product launch', {
  afterDate: '2024-01-01',
  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();

// Get a single integration
const integration = await attrove.integrations.get('integration-id');
console.log(`${integration.provider}: last synced ${integration.last_synced_at}`);

// Disconnect an integration
await attrove.integrations.disconnect('integration-uuid');

Threads

// Discover relevant threads via semantic search
const { threads } = await attrove.threads.discover('Q4 budget discussion', {
  integrationTypes: ['slack'],
  afterDate: '2024-01-01',
  limit: 5,
});

for (const thread of threads) {
  console.log(`${thread.title} (score: ${thread.relevance_score})`);
}

// Analyze a thread for structured insights
const analysis = await attrove.threads.analyze('conversation-uuid');
console.log(analysis.summary);
console.log(`Sentiment: ${analysis.sentiment}`);
console.log(`Action items: ${analysis.action_items.length}`);
console.log(`Decisions: ${analysis.decisions.length}`);

// Fetch messages in a thread. Defaults include body_html and headers;
// pass expand: ['raw'] only when you need the raw RFC 5322 email payload.
const page = await attrove.threads.messages('conversation-uuid');

Meetings

// List meetings
const { data: meetings } = await attrove.meetings.list({
  expand: ['summary', 'action_items', 'attendees'],
});

// Get a single meeting
const meeting = await attrove.meetings.get('meeting-id');

// Update a meeting's summary or action items
const updated = await attrove.meetings.update('meeting-id', {
  summary: 'Revised meeting summary.',
  shortSummary: 'Brief revision.',
  actionItems: [
    { description: 'Follow up with client', assignee: 'Alice' },
  ],
});

// Regenerate the AI summary from the transcript
const result = await attrove.meetings.regenerateSummary('meeting-id');
console.log(result.summary);
console.log(`Action items: ${result.action_items.length}`);

Events

// List calendar events
const { data: events } = await attrove.events.list({
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  expand: ['attendees', 'description'],
});

// Get a single event
const event = await attrove.events.get('evt_abc123');

Entities

// List contacts/entities
const { data: entities } = await attrove.entities.list({
  search: 'Alice',
  isBot: false,
});

// Get a contact
const entity = await attrove.entities.get('ent_abc123');

// List account-wide co-occurrence pairs (messages, meetings, calendar events).
// Accepts { limit, minInteractions, includeBots } — NOT an entity ID.
const { data: relationships } = await attrove.entities.relationships({
  limit: 50,
});

Notes

// List notes
const { data: notes } = await attrove.notes.list({ limit: 20 });

// Filter notes linked to a meeting, message, event, entity, or goal
const goalNotes = await attrove.notes.list({
  refType: 'goal',
  refId: 'gol_abc123',
});

// Get a single note
const note = await attrove.notes.get('note_abc123');

Push

// Push partner-owned context directly into Attrove
const pushed = await attrove.push.note({
  title: 'Customer call',
  body: 'CFO asked for ROI math before next review.',
  refType: 'goal',
  refId: 'gol_abc123',
  externalId: 'crm-note-123',
});

console.log(pushed.status); // queued

Goals

// Create an outcome goal to monitor
const goal = await attrove.goals.create({
  title: 'Premier Mechanical pilot decision',
  watchScope: {
    seedQuery: 'Premier Mechanical pilot',
    keywords: ['Premier Mechanical', 'pilot'],
    sourceTypes: ['messages', 'meetings', 'notes'],
  },
  successCriteria: 'Pilot agreement signed.',
});

// Queue a manual evaluation, then poll the goal
const { runId } = await attrove.goals.evaluate(goal.id);
const current = await attrove.goals.get(goal.id);

// Attach manual evidence and inspect status
await attrove.goals.addNote(goal.id, {
  title: 'Phone call',
  body: 'Buyer asked for procurement timeline.',
});
const evidence = await attrove.goals.evidence(goal.id);

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: '[e-mail]',
  firstName: 'John',
  lastName: 'Doe'
});

// Create a durable browser/CLI/MCP handoff session
const session = await admin.users.createConnectSession(id, {
  provider: 'gmail',
  includeInstall: true,
});

// Use the apiKey for subsequent API calls
const attrove = new Attrove({ apiKey, userId: id });

// Send the user to OAuth flow
console.log(session.activation_url);

// Or hand terminal/agent users this command:
console.log(session.cli?.command);

// Configure outbound webhooks
const endpoint = await admin.webhooks.create({
  url: 'https://your-app.example.com/webhooks/attrove',
  eventTypes: ['messages.new', 'notes.new', 'goals.risk_detected'],
  userIds: [id], // omit or pass null for all users in the partner account
});
console.log(endpoint.secret); // returned only on create/rotate-secret

After an integration is connected, verify the first useful answer:

const answer = await attrove.query(
  'What needs my attention this week? Include the source messages or meetings you used.',
  { includeSources: true },
);

console.log(answer.answer);

Webhook deliveries are CloudEvents JSON and are signed with webhook-id, webhook-timestamp, and webhook-signature headers. Use verifyWebhookSignature from @attrove/sdk against the raw request body before JSON parsing.

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