@attrove/sdk

@attrove/sdk

Official TypeScript SDK for the Attrove API. Attrove watches work across your users' email, chat, meetings, and calendar — when something starts to slip, it flags it with proof. Create watched outcomes (Goals) that catch the conversations going quiet, and query the same communication stream with cited evidence.

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
});

// Watch an outcome until it resolves — Attrove flags it if the
// conversation goes quiet or risk shows up, with cited evidence
const goal = await attrove.goals.create({
  title: 'Acme renewal closed by Jun 30',
  watchScope: {
    seedQuery: 'Acme renewal',
    keywords: ['Acme', 'renewal'],
    silenceCondition: { quietAfterDays: 5, alertHealth: 'at_risk' },
  },
  successCriteria: 'Signed order form received.',
});

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

Goals (watched outcomes)

A Goal is a watched outcome — a deal, renewal, follow-up, or deliverable that should resolve. Attrove keeps re-evaluating it against the communication stream and updates its health (on_track, at_risk, blocked, waiting_on_human, insufficient_evidence) with cited evidence. Add a silenceCondition and Attrove flags the goal when the conversation goes quiet — no polling loop in your code.

// Create an outcome goal to monitor
const goal = await attrove.goals.create({
  title: 'Acme Corp pilot decision',
  watchScope: {
    seedQuery: 'Acme Corp pilot',
    keywords: ['Acme Corp', 'pilot'],
    sourceTypes: ['messages', 'meetings', 'notes'],
    // Flag the goal when its conversations go quiet too long
    silenceCondition: { quietAfterDays: 5, alertHealth: 'at_risk' },
  },
  successCriteria: 'Pilot agreement signed.',
});

// List the goals that need attention
const { data: atRisk } = await attrove.goals.list({
  lifecycle: 'active',
  health: 'at_risk',
});

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

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

// Poll lifecycle transitions across goals
const events = await attrove.goals.events({
  types: ['goals.created', 'goals.risk_detected', 'goals.completed'],
  limit: 10,
});
console.log(events.watermark);

// Inspect snapshot history
const snapshots = await attrove.goals.snapshots.list(goal.id, { limit: 5 });

When a quiet goal is fine for now, acknowledge it instead of muting it — Attrove suppresses only the silence escalation until your horizon (or until real activity arrives first) and leaves deadline and blocker risk untouched. When it is time to chase, draftFollowUp() writes the next move for you, grounded in the goal's own thread evidence.

// Silence is expected for a while — acknowledge it (needs a silenceCondition)
await attrove.goals.acknowledge(goal.id, {
  until: '2026-08-01T00:00:00Z',
  reason: 'Buyer is on vacation until August.',
});

// Resume silence monitoring early once they reply
await attrove.goals.clearAcknowledgment(goal.id, { reason: 'Buyer replied.' });

// Draft the next move on a quiet goal, grounded in its thread evidence.
// Read-only: nothing is sent — a human reviews before anything goes out.
const { draft } = await attrove.goals.draftFollowUp(goal.id, {
  directive: 'Nudge for a decision this week.',
});
console.log(draft.subject, draft.body);

Lifecycle never changes autonomously — humans confirm via confirmStatus(). Pair Goals with the goals.risk_detected webhook (see below) to route alerts wherever the owner works.

Commitments (watched obligations)

A Commitment is an explicit obligation an agent registers — a promise, delegation, or handoff with a counterparty, an expected future signal, and a horizon. Attrove watches it until the signal arrives, auto-resolves it when the arrival is detectable, and escalates to a human by email when it silently never comes. Where a Goal is a watched outcome evaluated against evidence, a Commitment is a discrete obligation with a named expected signal — built so agent promises survive agent statelessness.

// Register an obligation so it outlives this session
const watched = await attrove.commitments.watch({
  commitmentText: 'Send Dana the revised proposal for sign-off',
  commitmentKind: 'promised_action',
  expectedSignalType: 'reply',
  expectedSignalDescription: 'Dana approves or requests changes',
  dueAt: '2026-07-22T17:00:00Z',
  counterparty: 'Dana',
  agent: 'release-agent',
  clientDedupKey: 'proposal-dana-2026-07-22', // retry-safe registration
});
console.log(watched.commitmentId, watched.status); // "watching"

// Session start: re-hydrate open obligations (never resolved history)
const { commitments, hasMore, nextCursor } =
  await attrove.commitments.checkOutcomes({ reader: 'release-agent' });
for (const open of commitments) console.log(open.summaryLine);

// Record what actually happened, citing the satisfying signal
await attrove.commitments.resolve(watched.commitmentId, {
  resolution: 'satisfied',
  signalRef: 'message:dana-approval',
  actor: 'release-agent',
});

The strict definition is a feature: a registration becomes an active watch only when it carries expectedSignalType and a checkAfter/dueAt horizon. Underspecified registrations are never rejected — and never escalate. They come back as status: 'suggested' with a missing array listing what to add, so a human can triage them later — a suggested commitment accepts only dismissed; to watch it, re-register it with an expected signal and a horizon. Resolutions for an active watch are satisfied, silent_drop, dismissed, or at_risk (flag without closing); terminal states are immutable. Link a commitment to a goal with parentGoalId when the obligation belongs to a watched outcome.

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}`);

// Check connection status
const status = await attrove.users.status();
if (status.state === 'needs_you') {
  for (const action of status.needs_action) {
    // prompt the user to reconnect via action.connect_url
  }
}

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}`);

// Create one link — a connect session — for the signed-in user, no partner
// credentials required. Returns an existing active session when one exists,
// otherwise creates one. Same response shape as admin.users.createConnectSession.
const session = await attrove.integrations.createConnectSession({
  provider: 'gmail', // optional — omit to open a source picker
});
console.log(session.activation_url);

// 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}`);

// Reversibly archive a pushed meeting by opaque ID or external ID
await attrove.meetings.delete({ externalId: 'fireflies-meeting-123' });

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');

// Reversibly archive a note by opaque ID or external ID
await attrove.notes.delete({ id: '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

Meeting, event, and note titles are trimmed and limited to 500 Unicode code points. A queued response means Attrove accepted the push for asynchronous indexing; the content is not query-ready yet.

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, then parseWebhookEvent to get a fully typed event:

import express from 'express';
import { parseWebhookEvent, verifyWebhookSignature } from '@attrove/sdk';

const app = express();

// Capture the raw body — signatures are computed over the exact bytes.
app.post(
  '/webhooks/attrove',
  express.raw({ type: 'application/cloudevents+json' }),
  (req, res) => {
    if (!verifyWebhookSignature(req.headers, req.body, process.env.ATTROVE_WEBHOOK_SECRET!)) {
      return res.status(401).end();
    }

    // Discriminated union: switching on event.type narrows event.data.
    const event = parseWebhookEvent(req.body);
    switch (event.type) {
      case 'goals.next_move_changed': {
        // Ball-in-court flip: the next move appeared, changed owner,
        // re-anchored to different evidence, or cleared.
        const { goal, next_move, previous_owner } = event.data;
        if (next_move?.owner === 'us') {
          console.log(`Your move on "${goal.title}": ${next_move.obligation}`);
        } else if (next_move === null) {
          console.log(`"${goal.title}" has no open move (was: ${previous_owner})`);
        }
        break;
      }
      case 'goals.risk_detected':
        console.log(`At risk: ${event.data.goal.title}`);
        break;
      case 'unknown_event':
        // A newer event type than this SDK version (or a malformed
        // envelope) — safe to log and ignore.
        break;
    }

    // Dedupe on the webhook-id header (stable across retries), then ack fast.
    res.status(204).end();
  },
);

parseWebhookEvent never throws on an unrecognized event type — it returns the unknown_event member instead (as it also does for a recognized type whose envelope is malformed), so API-side event additions cannot break your receiver. For a recognized type, the data payload is returned with its declared type but is not deeply field-validated (only the envelope is): null-check nested fields (next_move?.owner, data.snapshot_id) rather than assuming a declared field is present, since server-side drift could omit one.

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,
  Goal,
  GoalEventsPage
} from '@attrove/sdk';

Requirements

• Node.js 18.0.0 or later
• TypeScript 4.7+ (if using TypeScript)

License

MIT