npm package: @reclsdk/sdk
Description: RECL JavaScript SDK — behavioral tracking and personalization
Latest version: 1.0.4

# @reclsdk/sdk

Lightweight JavaScript SDK for RECL Customer Data Platform. Zero dependencies, <5KB gzipped.

## Install

```bash
npm install @reclsdk/sdk
```

## Quick Start

### ES Modules / TypeScript

```ts
import { ReclSDK } from '@reclsdk/sdk';

const sdk = new ReclSDK();
sdk.init('YOUR_PUBLIC_API_KEY', {
  apiUrl: 'https://your-api.example.com',
});

sdk.track('page_view', { page: '/home' });
sdk.identify('user-123', { plan: 'pro' });
```

### Script Tag (CDN)

```html
<script>
  (function(w,d,s,l,i){w[l]=w[l]||function(){(w[l].q=w[l].q||[]).push(arguments)};
  var f=d.getElementsByTagName(s)[0],j=d.createElement(s);j.async=1;
  j.src=i;f.parentNode.insertBefore(j,f);
  })(window,document,'script','recl','https://cdn.example.com/recl.min.js');

  recl('init', 'YOUR_PUBLIC_API_KEY', { apiUrl: 'https://your-api.example.com' });
  recl('track', 'page_view');
</script>
```

### CommonJS

```js
const { ReclSDK } = require('@reclsdk/sdk');
```

## API

### `sdk.init(apiKey, options?)`

Initialize the SDK. Options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiUrl` | `string` | `''` | API endpoint URL |
| `batchSize` | `number` | `10` | Events per batch |
| `batchInterval` | `number` | `5000` | Batch flush interval (ms) |
| `autoTrack` | `boolean` | `true` | Enable auto-tracking |
| `sessionTimeout` | `number` | `1800000` | Session timeout (ms) |
| `debug` | `boolean` | `false` | Enable debug logging |
| `requireConsent` | `boolean` | `false` | Require consent before tracking |
| `identityStorage` | `'localStorage' \| 'cookie'` | `'localStorage'` | Identity storage method |

### `sdk.track(eventType, properties?)`

Track a custom event.

```ts
sdk.track('button_click', { button_id: 'cta-hero', variant: 'blue' });
```

### `sdk.identify(userId, traits?)`

Link the current anonymous user to a known user ID.

```ts
sdk.identify('user-123', { email: 'user@example.com', plan: 'pro' });
```

### `sdk.setGlobalProperties(properties)`

Set properties attached to every subsequent event.

```ts
sdk.setGlobalProperties({ app_version: '2.1.0' });
```

### `sdk.flush()`

Force-send all buffered events immediately.

### `sdk.reset()`

Clear user identity and start a new anonymous session.

### `sdk.getUserId()` / `sdk.getAnonymousId()` / `sdk.getSessionId()` / `sdk.getDeviceId()`

Get current identity values.

### `sdk.enable()` / `sdk.disable()`

Enable or disable tracking.

### `sdk.grantConsent()` / `sdk.revokeConsent()`

Manage GDPR consent. When `requireConsent: true`, events are only sent after `grantConsent()`.

## Auto-Tracking

When `autoTrack: true` (default), the SDK automatically captures:

- **page_view** — on page load and SPA navigation
- **click** — link and button clicks (supports `data-recl-*` attributes)
- **scroll_depth** — max scroll percentage
- **time_on_page** — active time before unload
- **element_visibility** — elements with `data-recl-track-visibility`

## HTML Attributes

```html
<button data-recl-event="signup_click" data-recl-plan="pro">
  Sign Up
</button>
```

## License

MIT