@behavr/sdk

Official SDK for Behavr — Calibration-as-a-service for AI agent communication.

Installation

npm install @behavr/sdk

Quick Start

import { Behavr } from '@behavr/sdk';

// Initialize with your API key
const behavr = new Behavr({
  apiKey: 'bvr_your_api_key_here',
});

// Capture a message after sending it (async, non-blocking)
await behavr.capture({
  messageId: 'msg_123',
  content: 'Following up on our conversation from last week...',
  channel: 'email',
  interactionType: 'followup',
  conversationId: 'conv_456',
});

// Record an outcome when you receive a reply
await behavr.outcome({
  messageId: 'msg_123',
  type: 'reply',
  delay: '2 hours',
  sentiment: 'positive',
});

Features

• ✅ Async & Non-blocking — Fire-and-forget, never blocks your app
• ✅ Automatic Retries — Handles transient failures gracefully
• ✅ Rate Limiting — Respects API quotas automatically
• ✅ TypeScript — Full type safety out of the box
• ✅ Framework Agnostic — Works with any stack

API Reference

new Behavr(config)

Create a new Behavr client.

Options:

• apiKey (required) — Your Behavr API key
• baseUrl (optional) — Custom API endpoint (defaults to https://api.behavr.dev)
• retryAttempts (optional) — Number of retry attempts (default: 3)
• retryDelay (optional) — Base retry delay in ms (default: 1000)
• debug (optional) — Enable debug logging (default: false)

behavr.capture(options)

Capture a message sent by your AI agent (async, returns immediately).

Options:

• messageId (required) — Unique identifier for this message
• content (required) — The actual message content
• channel (optional) — email | slack | sms | chat | whatsapp | other
• interactionType (optional) — followup | decline | escalation | cold_outreach | support | other
• conversationId (optional) — Group messages into conversations
• metadata (optional) — Additional custom data

behavr.outcome(options)

Record an outcome for a previously captured message (async).

Options:

• messageId (required) — The message ID this outcome relates to
• type (required) — reply | no_reply | escalation | churn | positive | negative
• delay (optional) — Time between message and outcome (e.g., '2 hours')
• sentiment (optional) — positive | neutral | negative | unknown
• metadata (optional) — Additional custom data

behavr.flush()

Wait for all queued operations to complete. Useful for graceful shutdown.

await behavr.flush();

Use Cases

Sales SDR Follow-ups

const behavr = new Behavr({ apiKey: process.env.BEHAVR_API_KEY });

// After sending follow-up
await behavr.capture({
  messageId: outboundEmail.id,
  content: outboundEmail.body,
  channel: 'email',
  interactionType: 'followup',
  metadata: {
    prospectId: prospect.id,
    sequence: 'cold-outreach-v2',
  },
});

// When they reply
await behavr.outcome({
  messageId: outboundEmail.id,
  type: 'reply',
  delay: '4 hours',
  sentiment: 'positive',
});

Customer Support

// After sending support response
await behavr.capture({
  messageId: ticket.lastMessageId,
  content: agent.response,
  channel: 'chat',
  interactionType: 'support',
  conversationId: ticket.id,
});

// If escalated
await behavr.outcome({
  messageId: ticket.lastMessageId,
  type: 'escalation',
  delay: '10 minutes',
});

Consumer Apps (Boundaries)

// When handling sensitive requests
await behavr.capture({
  messageId: messageId,
  content: agentResponse,
  channel: 'chat',
  interactionType: 'decline',
  metadata: {
    requestType: 'inappropriate-dating',
  },
});

Environment Variables

BEHAVR_API_KEY=bvr_your_api_key_here

Debug Mode

Enable debug logging to troubleshoot integration issues:

const behavr = new Behavr({
  apiKey: 'bvr_...',
  debug: true, // Logs all API calls and errors
});

Error Handling

The SDK automatically retries on transient failures (network errors, 5xx responses). It will not retry on client errors (4xx) except rate limits (429).

If you need to handle errors explicitly, use the sync methods:

try {
  await behavr.captureSync({
    messageId: 'msg_123',
    content: 'Hello world',
  });
} catch (error) {
  console.error('Failed to capture message:', error);
}

License

MIT

Support

• 📖 Documentation: https://docs.behavr.dev
• 💬 Discord: https://discord.gg/behavr
• 📧 Email: [email protected]