@vibefollow/sdk is the official TypeScript SDK for Vibefollow. One install, one constructor, three resources.
vf.users
Identify users one-at-a-time or bulk-backfill from existing data.
vf.events
Track custom events, batch high-volume writes, and bulk-backfill history.
vf.webhooks
Verify signed webhook deliveries.
.d.ts shipped) and works in every JavaScript runtime that has fetch, AbortController, and crypto.randomUUID — that’s Node 20+, Cloudflare Workers (with nodejs_compat), Vercel Edge, and Deno.
What the SDK handles for you
Authentication
The API key flows into the
Authorization header on every request.Idempotency
Every POST gets a v4 UUID
Idempotency-Key; the backend dedupes within a 24-hour window.Retries
Transient failures (network, 5xx, 429) retry with exponential backoff plus jitter, up to
maxRetries (default 2).Timeouts
Per-request
AbortController timeout (default 10 seconds).Error mapping
HTTP status codes become typed errors you can
catch.Webhook verification
HMAC-SHA256 with constant-time comparison and timestamp tolerance.
What you handle
- Storing your API key (in a secrets manager, exposed to your process as
VIBEFOLLOW_API_KEY). - Storing your webhook secret separately.
- Choosing which events to emit.
- Verifying webhook signatures on inbound deliveries.
Supported runtimes
| Runtime | Status | Notes |
|---|---|---|
| Node 20+ | Supported | Primary target |
| Node 18 | Not supported | fetch is unflagged, but the SDK targets ES2022 features available only in 20+ |
| Cloudflare Workers | Supported | Requires nodejs_compat compatibility flag for webhook verification |
| Vercel Edge | Supported | Webhook verification requires node:crypto — not available on pure-edge runtimes |
| Deno | Supported | --allow-net, --allow-env |
| Browser | Not supported | Your API key must stay server-side |
Next
Installation
Install the SDK across npm, pnpm, yarn, and per-runtime notes.
The VibeFollow class
Constructor signature and configuration options.
users resource
identify, identifyBulk, and 10 typed lifecycle helpers.events resource
track, the batching API, and bulk() for backfills.Errors
The typed error hierarchy and recovery patterns.
Types
Public TypeScript types exported from the package.