# @vibeping/sdk

Analytics, error tracking, and web vitals for vibe-coded apps. One script tag, zero cookies, 4.3KB gzipped.

Built for apps made with [Lovable](https://lovable.dev), [Bolt.new](https://bolt.new), [Cursor](https://cursor.sh), and [Replit](https://replit.com).

## Quick Start

### Option A: Script Tag (recommended)

```html
<script
  src="https://cdn.jsdelivr.net/npm/@vibeping/sdk@latest/dist/vibeping.umd.js"
  data-id="YOUR_PROJECT_ID"
></script>
```

That's it. Page views, errors, and Web Vitals are captured automatically.

### Option B: npm

```bash
npm install @vibeping/sdk
```

```typescript
import { init } from '@vibeping/sdk';

init({ id: 'YOUR_PROJECT_ID' });
```

## What It Tracks

- **Page views** — automatic, works with SPAs
- **JavaScript errors** — caught and uncaught, with stack traces
- **Web Vitals** — LCP, CLS, INP, TTFB, FID (deprecated)
- **Custom events** — track signups, purchases, anything

## Privacy First

- No cookies
- No personal data collection
- GDPR compliant by default

## Configuration

```typescript
init({
  id: 'YOUR_PROJECT_ID',
  apiUrl: 'https://app.vibeping.dev',
  debug: false,
});
```

| Option   | Type      | Default                    | Description                        |
| -------- | --------- | -------------------------- | ---------------------------------- |
| `id`     | `string`  | required                   | Your project ID from the dashboard |
| `apiUrl` | `string`  | `https://app.vibeping.dev` | API endpoint for event ingestion   |
| `debug`  | `boolean` | `false`                    | Enable verbose console logging     |

## Custom Events

```typescript
import { track, identify } from '@vibeping/sdk';

track('signup', { plan: 'pro', source: 'landing-page' });
track('purchase', { amount: 29, currency: 'USD' });
identify({ userId: 'user_123', plan: 'pro' });
```

## Script Tag Runtime API

When loaded via `<script>`, the SDK exposes itself on `window.__vibeping` with:

- `init(config)` — initialize the SDK (auto-invoked when `data-id` is set)
- `track(name, props?)` — send a custom event
- `identify(traits)` — associate user traits with the session
- `flush()` — force-flush any buffered events to the API
- `destroy()` — tear down listeners, flush, and clean up

```html
<script>
  window.__vibeping.track('cta_click', { label: 'hero' });
  // Before a hard navigation:
  window.__vibeping.flush();
</script>
```

Add `data-debug="true"` to the script tag to enable debug logging.

## Links

- [Documentation](https://vibeping.dev/docs)
- [Dashboard](https://app.vibeping.dev)
- [GitHub](https://github.com/Vibeping/vibeping)
- [Website](https://vibeping.dev)

## License

MIT — see [LICENSE](../../LICENSE) for details.