> ## 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.

# SDK overview

> `@vibefollow/sdk` — the official TypeScript SDK for Vibefollow.

`@vibefollow/sdk` is the official TypeScript SDK for Vibefollow. One install, one constructor, three resources.

<CardGroup cols={3}>
  <Card title="vf.users" icon="user" href="/sdk/resources/users">
    Identify users one-at-a-time or bulk-backfill from existing data.
  </Card>

  <Card title="vf.events" icon="bolt" href="/sdk/resources/events">
    Track custom events, batch high-volume writes, and bulk-backfill history.
  </Card>

  <Card title="vf.webhooks" icon="webhook" href="/webhooks/signature-verification">
    Verify signed webhook deliveries.
  </Card>
</CardGroup>

The package is fully typed (TypeScript-first, `.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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key">
    The API key flows into the `Authorization` header on every request.
  </Card>

  <Card title="Idempotency" icon="fingerprint">
    Every POST gets a v4 UUID `Idempotency-Key`; the backend dedupes within a 24-hour window.
  </Card>

  <Card title="Retries" icon="rotate">
    Transient failures (network, 5xx, 429) retry with exponential backoff plus jitter, up to `maxRetries` (default 2).
  </Card>

  <Card title="Timeouts" icon="clock">
    Per-request `AbortController` timeout (default 10 seconds).
  </Card>

  <Card title="Error mapping" icon="triangle-exclamation">
    HTTP status codes become typed errors you can `catch`.
  </Card>

  <Card title="Webhook verification" icon="shield-halved">
    HMAC-SHA256 with constant-time comparison and timestamp tolerance.
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/sdk/installation">
    Install the SDK across npm, pnpm, yarn, and per-runtime notes.
  </Card>

  <Card title="The VibeFollow class" icon="cube" href="/sdk/class-vibefollow">
    Constructor signature and configuration options.
  </Card>

  <Card title="users resource" icon="user" href="/sdk/resources/users">
    `identify`, `identifyBulk`, and 10 typed lifecycle helpers.
  </Card>

  <Card title="events resource" icon="bolt" href="/sdk/resources/events">
    `track`, the batching API, and `bulk()` for backfills.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/sdk/errors">
    The typed error hierarchy and recovery patterns.
  </Card>

  <Card title="Types" icon="brackets-curly" href="/sdk/types">
    Public TypeScript types exported from the package.
  </Card>
</CardGroup>