events - Vibefollow

The vf.events resource handles custom event tracking, in-memory batching for live writes, and one-shot bulk for backfills. Use it for anything outside the canonical 10 lifecycle events.

`track(eventName, userId, properties?)`

Emit a single event. Idempotent on the server when the auto-generated Idempotency-Key is preserved across retries (handled by the client).

await vf.events.track('dashboard_created', 'usr_42', {
  source: 'wizard',
  workspaceId: 'ws_3',
});

eventName

string

required

Event name. Snake_case recommended. The backend validates only that it’s a non-empty string — reserved-name collisions return ValidationError.

userId

string

required

External user ID.

properties

EventProperties

JSON-serialisable property bag. Defaults to {}.

Show EventProperties shape

type EventProperties = Record<string, unknown>;

Returns: Promise<void>.

`batch(options?)`

Returns an EventBatch — an in-memory buffer that flushes in one POST. Useful for backfills and high-volume write paths.

const batch = vf.events.batch({
  maxSize: 100,
  maxAgeMs: 5_000,
});

for (const row of historicalEvents) {
  batch.track(row.name, row.userId, row.properties);
}

await batch.flush();

options.maxSize

number

default:"100"

Auto-flush when the queue reaches this size.

options.maxAgeMs

number

default:"5000"

Auto-flush when this many milliseconds have elapsed since the first queued event.

options.suppressTriggers

boolean

default:"false"

When true, every user touched by the batch is marked as historical — the server sets suppressTriggersUntil on each TrackedUser so the trigger-rules cron skips them. Use it when seeding your existing user base into Vibefollow so customers don’t get a “welcome” email months after they actually signed up. The watermark dissolves automatically the first time the user emits a normal (non-suppressed) event, so flipping back to live mode is one config change away.

Seeding historical users

import { VibeFollow } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });

const backfill = vf.events.batch({
  maxSize: 100,
  maxAgeMs: 5_000,
  suppressTriggers: true,
});

for (const row of existingUsers) {
  backfill.track('user_signed_up', row.id, { signedUpAt: row.createdAt });
}

await backfill.flush();

// Live signups go through a normal batch (or events.track) and DO fire
// welcomes as expected — suppression is per-batch, not per-project.
const live = vf.events.batch();
live.track('user_signed_up', 'usr_new', {});
await live.flush();

`EventBatch`

`batch.track(eventName, userId, properties?)`

Enqueue an event. Same shape as events.track(), but synchronous — returns void. Auto-flushes when the buffer fills or the age timer fires.

batch.track('dashboard_created', 'usr_42', { source: 'wizard' });

`batch.flush()`

Drain the queue and POST to /api/v1/events/batch. No-op when empty. Always await — the returned promise resolves only after the network round-trip.

await batch.flush();

Always await batch.flush() before process exit. Lambda-style runtimes that freeze the event loop will lose any queue still in memory. Long-running servers should also call flush() in a shutdown hook (SIGTERM handler).

`bulk(records)`

Send up to 1,000 events in a single POST — the one-shot counterpart to batch()’s in-memory buffer. Use bulk() when you already have the full array (CSV row, DB query, data warehouse export) and don’t want the timing/flushing semantics of EventBatch.

const result = await vf.events.bulk([
  {
    external_user_id: 'usr_42',
    name: 'user_signed_up',
    timestamp: '2024-01-15T10:00:00Z',
    properties: { plan: 'trial' },
  },
  {
    external_user_id: 'usr_42',
    name: 'trial_started',
    timestamp: '2024-01-15T10:00:05Z',
    properties: { trialDays: 14 },
  },
]);

console.log(result.data.accepted); // 2

records

BulkEventRecord[]

required

Array of event records. Empty arrays short-circuit; arrays larger than 1,000 throw RangeError.

Show BulkEventRecord shape

interface BulkEventRecord {
  external_user_id: string; // required
  name: string;             // required
  timestamp?: string;       // ISO 8601 with offset
  properties?: EventProperties;
}

Returns: Promise<BulkIngestResponse>. Per-record validation errors land in data.errors[] with the original array index; the rest are queued.

Duplicate (external_user_id, name, timestamp) tuples are deduped by the server-side events_dedupe_unique index, so any chunk that 429s or 5xxs is safe to retry — reimporting the same backfill twice is a no-op for matching rows.

Backfilling more than 1,000 events

Same chunk() pattern as users.identifyBulk():

import { VibeFollow, chunk } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });

for (const slice of chunk(historicalEvents, 1000)) {
  await vf.events.bulk(slice);
}

Trade-offs

Use case	Choose
Real-time, interactive	`events.track()` — per-event POST
Buffer & auto-flush live writes	`events.batch()` — in-memory queue with timing
One-shot backfill / data export	`events.bulk()` — you already have the array
Stream from data warehouse	`events.bulk()` paired with `chunk()`
Webhook fan-out / fan-in	`events.track()` — small enough that batching adds latency

Single-event POST is cheap (sub-100ms typical). Don’t reach for the batch API unless you’re moving thousands of events.

Failure modes

Single track() fails (NetworkError, ServerError, RateLimitError)

Auto-retried up to maxRetries. Throws on exhaustion. The SDK preserves the Idempotency-Key across retries so duplicates are deduped server-side within 24 hours.

batch.flush() fails

Throws — the queue is already drained at this point. Re-enqueueing on failure would risk duplicates.

batch.track() overflows

Synchronously triggers flush(); the next track() after that just enqueues normally.

Process exits before flush()

In-memory queue is lost. Always await flush() in a shutdown handler.

​track(eventName, userId, properties?)

​batch(options?)

​Seeding historical users

​EventBatch

​batch.track(eventName, userId, properties?)

​batch.flush()

​bulk(records)

​Backfilling more than 1,000 events

​Trade-offs

​Failure modes

`track(eventName, userId, properties?)`

`batch(options?)`

Seeding historical users

`EventBatch`

`batch.track(eventName, userId, properties?)`

`batch.flush()`

`bulk(records)`

Backfilling more than 1,000 events

Trade-offs

Failure modes