npm package: @simple-product/sdk
Description: Simple Product SDK - Track users and product usage
Author: Simple Product
Latest version: 0.1.2

# @simple-product/sdk

Track users and product usage with Simple Product.

## Installation

```bash
npm install @simple-product/sdk
```

## Quick Start

```typescript
import { SimpleProduct } from '@simple-product/sdk';

// Initialize once in your app
const sp = new SimpleProduct({
  apiKey: 'sk_your_api_key',
});

// Identify users when they sign in
sp.identify({
  userId: user.id,
  email: user.email,
  name: user.name,
  company: user.company,
});

// That's it! Analytics are now tracked automatically.
```

## How It Works

The SDK automatically sends a **heartbeat event once per day** per user. This single event powers:

- **DAU/WAU/MAU** - Daily, weekly, monthly active users
- **Retention** - Cohort retention analysis
- **Stickiness** - DAU/MAU engagement ratio

No configuration needed. Just identify your users and analytics happen automatically.

## API Reference

### `new SimpleProduct(config)`

Create a new SDK instance.

```typescript
const sp = new SimpleProduct({
  apiKey: 'sk_your_api_key',        // Required
  endpoint: 'https://...',           // Optional, defaults to production
  disableAutoHeartbeat: false,       // Optional, disable auto-tracking
  debug: false,                      // Optional, enable console logging
});
```

### `sp.identify(params)`

Identify a user. Call this when a user signs in.

```typescript
sp.identify({
  userId: 'user_123',          // Required - your internal user ID
  email: 'user@example.com',   // Optional
  name: 'Jane Doe',            // Optional
  company: 'Acme Inc',         // Optional
  traits: {                    // Optional - any additional data
    plan: 'pro',
    role: 'admin',
  },
});
```

### `sp.track(event, properties?)`

Track a custom event.

```typescript
sp.track('feature_used', {
  feature: 'export_report',
  format: 'csv',
});
```

### `sp.reset()`

Reset the user. Call this when a user signs out.

```typescript
sp.reset();
```

### `sp.destroy()`

Clean up SDK resources. Call this if you need to remove the SDK.

```typescript
sp.destroy();
```

## React Integration (Recommended)

The easiest way to integrate is with our React provider:

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

import { SimpleProductProvider } from '@simple-product/sdk/react';

export function Providers({ children, user }) {
  return (
    <SimpleProductProvider
      apiKey={process.env.NEXT_PUBLIC_SP_API_KEY!}
      user={user ? {
        id: user.id,
        email: user.email,
        name: user.name,
      } : null}
    >
      {children}
    </SimpleProductProvider>
  );
}
```

The provider automatically:
- Calls `identify()` when user changes
- Sends heartbeats once per day
- Resets on logout

### Track Custom Events

```tsx
import { useSimpleProduct } from '@simple-product/sdk/react';

function MyComponent() {
  const { track } = useSimpleProduct();

  return (
    <button onClick={() => track('button_clicked', { button: 'signup' })}>
      Sign Up
    </button>
  );
}
```

## Manual Setup

If you're not using React, you can use the SDK directly:

```tsx
import { SimpleProduct } from '@simple-product/sdk';

const sp = new SimpleProduct({
  apiKey: process.env.NEXT_PUBLIC_SP_API_KEY!,
});

// When user logs in
sp.identify({
  userId: user.id,
  email: user.email,
  name: user.name,
});

// Track custom events
sp.track('feature_used', { feature: 'export' });

// On logout
sp.reset();
```

## License

MIT