buddy-assist-connector

Official SDK for syncing external data sources with Buddy Assist AI. Push documents from any source — databases, file systems, APIs, CMS — and let the AI chatbot answer questions using your data with semantic vector search.

Installation

npm install buddy-assist-connector

Quick Start

import { BuddyConnector } from 'buddy-assist-connector';

const buddy = new BuddyConnector({
  apiKey: process.env.BUDDY_API_KEY!,
  projectId: process.env.BUDDY_PROJECT_ID!,
});

// Create or update a single document
await buddy.put({
  externalId: 'doc-123',
  title: 'Getting Started Guide',
  content: 'Full text content of your document...',
  url: 'https://docs.example.com/getting-started',
  metadata: { department: 'engineering', version: '2.0' },
});

// Batch push (auto-batched in chunks of 100)
await buddy.putMany([
  { externalId: 'faq-1', title: 'How to reset password', content: '...' },
  { externalId: 'faq-2', title: 'Billing questions', content: '...' },
]);

// Remove a document
await buddy.remove('doc-123');

// Check sync status
const status = await buddy.status();
console.log(`${status.totalChunks} chunks indexed`);

Sync Modes

Each document can be synced in one of three modes by setting mode on the document:

| Mode | Content stored on our servers? | Search quality | Query latency | Use when | |---|---|---|---|---| | copy (default) | Yes — full text | Best | Fastest | You're OK with sending content | | index | Only embeddings, raw text discarded after indexing | Best | Fastest | You want search but not raw storage | | reference | No — only id/title/url/metadata | Lower | Slower (live fetch) | Compliance forbids copying, or content changes constantly |

// Copy mode (default)
await buddy.put({
  externalId: 'policy-1',
  title: 'Refund Policy',
  content: 'Our refund policy states...',
});

// Index mode — content is embedded then forgotten
await buddy.put({
  externalId: 'policy-2',
  title: 'Privacy Policy',
  content: 'We collect...',
  mode: 'index',
});

// Reference mode — no content sent, fetched live at query time
await buddy.put({
  externalId: 'product-42',
  title: 'Wireless Headphones',
  url: 'https://yourstore.com/api/products/42',
  metadata: { sku: 'WH-42', category: 'audio' },
  mode: 'reference',
});

index and reference modes require backend support. If your Buddy Assist server doesn't yet support them, documents fall back to copy mode automatically.

Protecting your reference endpoint (optional)

When Buddy Assist fetches a reference document's live content, it sends a plain GET to your url by default. If the URL is public, that's fine. If it isn't, you can require Buddy Assist to sign every request.

Step 1. In your Buddy Assist dashboard, generate and save a reference_fetch_secret on your project.

Step 2. Every outbound request will then include these headers:

| Header | Value | |---|---| | X-BuddyAssist-Timestamp | Unix seconds when the request was signed | | X-BuddyAssist-Signature | sha256=<hex> — HMAC-SHA256 of ${timestamp}.${url} | | X-BuddyAssist-Project | Your project ID |

Step 3. Verify on your endpoint before returning content:

// Express / Node example
import crypto from 'crypto';

app.get('/buddy-fetch/:id', (req, res) => {
  const ts = req.header('X-BuddyAssist-Timestamp');
  const sig = req.header('X-BuddyAssist-Signature') || '';
  const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`;

  // Reject stale requests (5 min window)
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return res.status(401).send('stale');
  }

  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', process.env.BUDDY_REFERENCE_SECRET!)
      .update(`${ts}.${url}`)
      .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('bad signature');
  }

  // Verified — return the document body
  const doc = await db.docs.findById(req.params.id);
  res.type('text/plain').send(doc.body);
});

If you leave reference_fetch_secret empty on your project, no signing headers are sent and your endpoint must be publicly reachable (or protected by other means). This is your decision — the SDK supports both.

Reconcile (cleanup stale documents)

Keep Buddy Assist in sync with your system by removing anything you no longer have:

// You track which IDs you last told Buddy about.
const previousIds = await db.buddySyncLog.getAll(); // your bookkeeping
const currentIds = (await db.articles.findAll()).map((a) => a.id);

// Push everything that currently exists
await buddy.putMany(
  (await db.articles.findAll()).map((a) => ({
    externalId: a.id,
    title: a.title,
    content: a.body,
  })),
);

// Remove anything from the previous batch that no longer exists
const result = await buddy.reconcile({ previousIds, currentIds });
console.log(`Reconciled: kept ${result.kept}, removed ${result.removed.length}`);

// Persist new state for next run
await db.buddySyncLog.replace(currentIds);

Watch a Directory (Node.js)

// Auto-sync files from a directory
buddy.watchDirectory('/path/to/docs', {
  fileTypes: ['.md', '.txt', '.pdf'],
  recursive: true,
  pollInterval: 5000, // check every 5 seconds
  mode: 'copy', // or 'index' / 'reference'
});

// Stop watching
buddy.unwatchDirectory('/path/to/docs');

API Reference

new BuddyConnector(config)

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your project API key | | projectId | string | Yes | Your project ID | | apiBaseUrl | string | No | Custom API base URL | | source | string | No | Source identifier (default: 'sdk') | | fetchImpl | typeof fetch | No | Custom fetch implementation |

Methods (current)

• put(doc) — Create or update a single document
• putMany(docs) — Batch create/update (auto-chunks if >100)
• remove(externalId) — Delete a synced document
• removeMany(externalIds) — Delete many synced documents
• reconcile({ previousIds, currentIds }) — Delete anything in previousIds not in currentIds
• status() — Get sync statistics
• watchDirectory(path, options) — Auto-sync file changes
• unwatchDirectory(path) — Stop watching
• unwatchAll() — Stop all watchers

Deprecated (still work, removed in v2)

• pushDocument(doc) → use put(doc)
• pushDocuments(docs) → use putMany(docs)
• removeDocument(id) → use remove(id)
• getStatus() → use status()

License

MIT