Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vibefollow.com/llms.txt

Use this file to discover all available pages before exploring further.

1

Install the SDK

Node 20 or later is required. The SDK also runs on Cloudflare Workers (with nodejs_compat), Vercel Edge, and Deno. See Edge runtimes for the runtime-specific notes.
npm install @vibefollow/sdk
2

Grab an API key

API keys are issued in the Vibefollow dashboard under Settings → Developers → API keys. They follow the Stripe-style prefix scheme:
  • sk_live_… — production
  • sk_test_… — sandbox (future)
Store the key in your secrets manager and expose it to your process as VIBEFOLLOW_API_KEY.
Never commit a key, and never ship one to the browser. The full secret is shown exactly once at creation time — if you lose it, revoke and reissue.
3

Identify a user and emit an event

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

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

// Upsert a user
await vf.users.identify('usr_42', {
  email: 'jane@acme.io',
  name: 'Jane Doe',
  plan: 'trial',
});

// Emit a lifecycle event
await vf.users.signedUp('usr_42', { plan: 'trial', source: 'organic' });
That’s it. The SDK takes care of authentication, idempotency, retries, and error mapping.
identify is an upsert — calling it twice with the same userId updates traits in place. Pass any trait keys you want (plan, signupDate, company, role, …); unknown keys flow into the traits JSON column for audience filtering.
4

Try a real lifecycle event

The nine canonical lifecycle events have typed helpers. They’re equivalent to calling events.track('user_signed_up', …) but you get autocomplete and protection against name typos.
await vf.users.trialStarted('usr_42', { trialDays: 14 });

await vf.users.featureUsed('usr_42', {
  feature: 'dashboard_export',
  count: 1,
});

await vf.users.subscriptionChanged('usr_42', {
  from: 'trial',
  to: 'pro',
  interval: 'yearly',
  mrr: 9900, // cents
});
See the full list in Lifecycle events.
5

Verify a webhook (optional)

Vibefollow signs every outbound webhook delivery. Verify it with webhooks.constructEvent() — pass the raw body, the signature header, and your webhook secret:
import { VibeFollow, WebhookSignatureError } from '@vibefollow/sdk';

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

app.post('/webhooks/vibefollow', express.raw({ type: '*/*' }), (req, res) => {
  try {
    const event = vf.webhooks.constructEvent(
      req.body, // raw Buffer or string — not JSON.parse'd
      req.headers['x-vibefollow-signature'],
      process.env.VIBEFOLLOW_WEBHOOK_SECRET!,
    );

    if (event.type === 'email.replied') {
      console.log('reply tone:', event.data.tone);
    }

    res.sendStatus(204);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(401);
    throw err;
  }
});
Full payload spec for every event type: Webhook event types.
Your first event is now flowing. Calls to identify and lifecycle helpers return Promise<void> — if they resolve without throwing, the event was accepted (202 Accepted) and is on the ingest queue.

​
Next steps

Authentication

Issue, store, rotate, and revoke API keys the right way.

Events overview

The mental model behind identify + track, and how events drive triggers.

The 9 lifecycle events

First-class helpers for every canonical event Vibefollow knows about.

Custom events

events.track() for anything outside the canonical set, plus batching for backfills.

Webhooks overview

Signature verification, retry policy, and the inbound event catalog.

Errors

Typed errors you can catch — AuthError, RateLimitError, etc.