npm package: @heartbeep/beeper
Description: Modern JavaScript SDK for Heartbeep event tracking - beep beep!
Author: Heartbeep
Latest version: 0.1.2

# @heartbeep/beeper 🔔

Modern JavaScript SDK for Heartbeep event tracking. Simple API, TypeScript support, React/Next.js ready. Beep beep!

## Installation

```bash
npm install @heartbeep/beeper
# or
pnpm add @heartbeep/beeper
# or
yarn add @heartbeep/beeper
```

## Quick Start

### Vanilla JavaScript/TypeScript

```typescript
import { Heartbeep } from "@heartbeep/beeper";

const heartbeep = new Heartbeep({
  siteId: "your-site-id",
  debug: true, // optional, logs events in development
});

// Track events
heartbeep.track("pageview");
heartbeep.track("click", { name: "Subscribe Button" });
heartbeep.track("purchase", {
  name: "Premium Plan",
  metadata: { value: 99.99, currency: "USD" },
});

// Convenience methods
heartbeep.pageview("Home Page");
heartbeep.click("Buy Now Button", { section: "hero" });
heartbeep.purchase("Pro Plan", { value: 49.99 });
```

### React

```tsx
import { HeartbeepProvider, useHeartbeep } from "@heartbeep/beeper/react";

// In your root component
function App() {
  return (
    <HeartbeepProvider siteId="your-site-id">
      <YourApp />
    </HeartbeepProvider>
  );
}

// In any component
function Button() {
  const { click } = useHeartbeep();

  return (
    <button onClick={() => click("CTA Button", { variant: "primary" })}>
      Click Me
    </button>
  );
}
```

### Next.js App Router

For Next.js App Router, create a client component wrapper:

```tsx
// app/providers.tsx
"use client";

import { HeartbeepProvider, AutoPageview } from "@heartbeep/beeper/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <HeartbeepProvider siteId="your-site-id">
      <AutoPageview />
      {children}
    </HeartbeepProvider>
  );
}
```

Then use it in your root layout:

```tsx
// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

### Auto Page Tracking

```tsx
import { HeartbeepProvider, AutoPageview } from "@heartbeep/beeper/react";

function App() {
  return (
    <HeartbeepProvider siteId="your-site-id">
      <AutoPageview />
      <YourApp />
    </HeartbeepProvider>
  );
}
```

## API Reference

### `Heartbeep` Class

#### Constructor

```typescript
new Heartbeep(config: HeartbeepConfig)
```

**Config Options:**

- `siteId` (required): Your Heartbeep site ID
- `apiUrl` (optional): Custom API URL
- `debug` (optional): Enable debug logging

#### Methods

##### `track(event, payload?)`

Track a custom event.

```typescript
heartbeep.track("custom-event", {
  name: "Event Name",
  metadata: { key: "value" },
});
```

##### `pageview(name?)`

Track a page view.

```typescript
heartbeep.pageview("Home Page");
```

##### `click(name, metadata?)`

Track a click event.

```typescript
heartbeep.click("Buy Now Button", { section: "hero" });
```

##### `purchase(name, metadata?)`

Track a purchase event.

```typescript
heartbeep.purchase("Pro Plan", {
  value: 49.99,
  currency: "USD",
});
```

### React Hook

The `useHeartbeep()` hook provides access to all tracking methods:

```typescript
const { track, pageview, click, purchase, heartbeep } = useHeartbeep();
```

## TypeScript Support

Full TypeScript support with type definitions included:

```typescript
import type { HeartbeepConfig, TrackEventPayload } from "@heartbeep/beeper";
```

## Migration from Script Tag

Replace your script tag:

```html
<!-- Old -->
<script src="/beep.js" data-site-id="site_123"></script>
<script>
  window.hb("click", "Button");
</script>
```

With the npm package:

```typescript
// New
import { Heartbeep } from "@heartbeep/beeper";
const heartbeep = new Heartbeep({ siteId: "site_123" });
heartbeep.click("Button");
```

## Fun Beep Function

For a bit of fun, we also export a `beep` function:

```typescript
import { beep } from "@heartbeep/beeper";

beep("click", "Fun Button"); // Logs: [Beeper] 🔔 click: Fun Button
```

## Browser Support

- Modern browsers with ES2020 support
- Server-side rendering safe
- Graceful degradation for older browsers

## License

MIT

---

Made with ❤️ by Heartbeep. Beep beep!