@snovasys/usage-analytics-sdk 1.0.0

package/README.md

@@ -0,0 +1,638 @@
+# @snovasys/usage-analytics-sdk
+
+Lightweight, extensible usage analytics SDK for browser and Node. Emit events from your app without coupling to a specific analytics provider; plug in Microsoft Clarity, Google Analytics, or your own API via **listeners**. One API, multiple backends.
+
+## Features
+
+- **Single API** – `init`, `track`, `identify`. No provider-specific code in your app.
+- **Multiple listeners** – Send the same events to Clarity, GA, and your backend at once.
+- **Pre-init safe** – Call `track` or `identify` before `init()`; choose to **queue** (replay after init) or **drop**.
+- **Enriched events** – Every event gets `appId`, `environment`, `timestamp`, `sessionId`, `userId` (if identified), and SDK version.
+- **Error isolation** – One failing listener does not break others; optional `onError` callback.
+- **SSR / Node safe** – No `window` access until needed; in Node/SSR, pre-init events are dropped.
+- **Zero/minimal deps** – Core has no runtime dependencies; listeners are optional entry points.
+- **Auto-configuration** – Pass `configUrl` or `getConfig` at init; the SDK fetches config and creates built-in listeners (Clarity, GA, custom API) **without** you passing listener factories.
+- **Switch listeners without touching package or products** – In simple terms: the **package** stays unchanged, **products** stay unchanged. Only the **pointing** (Clarity vs GA vs custom API, etc.) changes—and that comes from **config** (a URL or API you control). Switch from Clarity to GA by updating that config; no package republish, no product redeploy.
+- **Direct backend communication** – Built-in listeners send events **from the client** directly to Clarity, GA, and your API. No proxy hop; minimal bandwidth.
+
+---
+
+## Install
+
+```bash
+npm install @snovasys/usage-analytics-sdk
+```
+
+Optional listeners (install only what you use):
+
+```bash
+# No extra install for noop and custom-api – they live in this package
+# Import from '@snovasys/usage-analytics-sdk/noop' or '@snovasys/usage-analytics-sdk/custom-api'
+```
+
+---
+
+## Quick start
+
+Minimal setup: init with an app id, then track.
+
+```ts
+import { init, track } from '@snovasys/usage-analytics-sdk';
+
+await init({ appId: 'my-app' });
+track({ name: 'feature_used', properties: { feature: 'export' } });
+```
+
+With a listener (e.g. send events to your API):
+
+```ts
+import { init, track } from '@snovasys/usage-analytics-sdk';
+import { createCustomApiListener } from '@snovasys/usage-analytics-sdk/custom-api';
+
+await init({
+  appId: 'my-app',
+  environment: 'production',
+  listeners: [
+    {
+      id: 'api',
+      listener: createCustomApiListener({
+        endpoint: 'https://api.example.com/analytics/events',
+        apiKey: 'optional-key',
+      }),
+      config: {},
+    },
+  ],
+});
+track({ name: 'page_view', properties: { path: '/dashboard' } });
+```
+
+**Auto-config (no listener code in your app):** Pass **appId** and **environment** from your environment files; the config API returns **listener details only**. See [Auto-configuration and direct backend communication](#auto-configuration-and-direct-backend-communication) and [docs/configuration.md](docs/configuration.md).
+
+```ts
+import { init, track } from '@snovasys/usage-analytics-sdk';
+
+await init({
+  appId: import.meta.env.VITE_APP_ID,           // or process.env.REACT_APP_ID, etc.
+  environment: import.meta.env.VITE_ENV ?? 'production',
+  configUrl: 'https://config.example.com/analytics/listeners.json',
+});
+track({ name: 'feature_used', properties: { feature: 'export' } });
+```
+
+Events go **directly** from the client to Clarity, GA, and your API; no proxy.
+
+---
+
+## Script tag (index.html) – no API calls
+
+1. **Add one script** in your **index page**, loaded from a CDN (or your own host).
+2. **Put config in the script tag** via the `data-config` attribute – that config decides **which listeners** (Clarity, GA, custom API, etc.) receive events.
+3. **Add track calls** across your app; all events go to the listeners configured in that script tag.
+
+**No other API calls** – the script reads config from the tag and initializes; no fetch, no backend.
+
+### 1. Add the script tag in index.html
+
+Load the script from a CDN (industry standard: unpkg or jsDelivr) and pass config in the **script tag** using `data-config` (JSON):
+
+```html
+<!DOCTYPE html>
+<html>
+<head>...</head>
+<body>
+  <script
+    src="https://unpkg.com/@snovasys/usage-analytics-sdk/dist/usage-analytics.min.js"
+    data-config='{"appId":"my-app","environment":"production","listeners":[{"id":"clarity","config":{"projectId":"your-clarity-project-id"}},{"id":"ga","config":{"measurementId":"G-XXXXXXXX"}}]}'
+  ></script>
+</body>
+</html>
+```
+
+**Using unpkg or jsDelivr (free CDNs)**
+
+Both [unpkg](https://unpkg.com) and [jsDelivr](https://www.jsdelivr.com) are **free**, no signup required. They serve files from the npm registry.
+
+| CDN | Script URL |
+|-----|------------|
+| **unpkg** | `https://unpkg.com/@snovasys/usage-analytics-sdk@1/dist/usage-analytics.min.js` |
+| **jsDelivr** | `https://cdn.jsdelivr.net/npm/@snovasys/usage-analytics-sdk@1/dist/usage-analytics.min.js` |
+
+- Replace `@1` with your desired version (e.g. `@1.0.0`) to pin it in production.
+- Omit the version (e.g. `.../usage-analytics-sdk/dist/...`) to get the latest release, but pinning is recommended for stability.
+
+**Example with unpkg:**
+
+```html
+<script
+  src="https://unpkg.com/@snovasys/usage-analytics-sdk@1/dist/usage-analytics.min.js"
+  data-config='{"appId":"my-app","listeners":[{"id":"clarity","config":{"projectId":"abc123"}}]}'
+></script>
+```
+
+**Example with jsDelivr:**
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/@snovasys/usage-analytics-sdk@1/dist/usage-analytics.min.js"
+  data-config='{"appId":"my-app","listeners":[{"id":"clarity","config":{"projectId":"abc123"}}]}'
+></script>
+```
+
+You can also copy `dist/usage-analytics.min.js` from the package into your app and use a relative path instead of a CDN.
+
+**Maintainers:** jsDelivr serves from npm. To make the package available on jsDelivr, publish to npm first; see [PUBLISH.md](PUBLISH.md).
+
+### 2. Add track calls across your code
+
+The script exposes `UsageAnalytics` on `window`. Call `track` (and optionally `identify`) anywhere in your app:
+
+```javascript
+UsageAnalytics.track({ name: 'page_view', properties: { path: window.location.pathname } });
+UsageAnalytics.track({ name: 'feature_used', properties: { feature: 'export' } });
+UsageAnalytics.identify('user-123', { email: 'user@example.com' });
+```
+
+**Which listeners receive these events** is determined **only** by the `data-config` in the script tag you added in index.html. Change Clarity vs GA vs custom API by editing that config and redeploying the page.
+
+### Fallback: config in a separate script
+
+If you prefer not to put JSON in the script tag, set `window.__ANALYTICS_CONFIG__` in an inline script **before** the SDK script; the script will use it when `data-config` is not present.
+
+---
+
+## How to use – full feature guide
+
+### 1. `init(options)` – initialize once
+
+Call `init()` early in your app (e.g. in `main.ts` or root layout). It is **idempotent**: calling it again re-applies config. It returns a **Promise**; you can `await init(...)` to know when the SDK is ready.
+
+**Required**
+
+- **`appId`** (string) – Your application identifier. Used in every event so you can filter by app. Set from environment variables (e.g. `VITE_APP_ID`, `REACT_APP_ID`) when using remote config.
+
+**Optional**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `environment` | string | `'production'` | e.g. `production`, `staging`, `dev`. Added to every event. |
+| `listeners` | ListenerEntry[] | `[]` | List of listener instances and their config. See [Listeners](#listeners) below. |
+| `preInitBehavior` | `'queue'` \| `'drop'` | `'drop'` | What to do with `track`/`identify` calls **before** `init()`: **queue** (replay after init) or **drop** (ignore). |
+| `queueMaxSize` | number | 100 | When `preInitBehavior === 'queue'`, max events to keep. When full, oldest are dropped (FIFO). |
+| `queueTtlMs` | number | 5000 | When queueing, events older than this (ms) at flush time are dropped. |
+| `onError` | `(error, context?) => void` | — | Called when a listener throws (e.g. in `init` or `track`). Use for logging or monitoring. |
+| `sessionId` | string | (generated) | If you don’t set it, the SDK generates a UUID and optionally persists it in `sessionStorage` keyed by `appId`. |
+
+**Auto-config options** (when using remote config): `configUrl` (URL to fetch config), `getConfig` (async function returning config), `listenerFactories` (map id → factory to add/override built-in listeners), `fetch` (custom fetch for `configUrl`). See [Auto-configuration](#auto-configuration-and-direct-backend-communication) and [docs/configuration.md](docs/configuration.md).
+
+**Example – full config**
+
+```ts
+await init({
+  appId: 'my-app',
+  environment: import.meta.env.PROD ? 'production' : 'development',
+  preInitBehavior: 'queue',
+  queueMaxSize: 50,
+  queueTtlMs: 3000,
+  onError: (err, ctx) => console.error('Analytics listener error', ctx?.listenerId, err),
+  listeners: [
+    { id: 'api', listener: createCustomApiListener({ endpoint: '...' }), config: {} },
+  ],
+});
+```
+
+---
+
+### 2. `track(event)` – emit an event
+
+Fire-and-forget. Safe to call before `init()` (then queued or dropped per `preInitBehavior`).
+
+**Event shape**
+
+- **`name`** (string, required) – Event name, e.g. `page_view`, `feature_used`, `button_click`.
+- **`properties`** (object, optional) – Extra data (JSON-serializable). e.g. `{ path: '/dashboard', role: 'admin' }`.
+- **`timestamp`** (string, optional) – ISO 8601; if omitted, the SDK sets it to now.
+
+**Example**
+
+```ts
+track({ name: 'page_view', properties: { path: '/dashboard', title: 'Dashboard' } });
+track({ name: 'feature_used', properties: { feature: 'export', format: 'csv', rows: 100 } });
+track({ name: 'signup_completed' });
+```
+
+Every event is **enriched** before being sent to listeners: `timestamp`, `eventId`, `appId`, `environment`, `sdkVersion`, `sessionId`, and (if you called `identify`) `userId` are added automatically.
+
+---
+
+### 3. `identify(userId, traits?)` – set user identity
+
+Call when the user logs in or you know their id. The SDK stores it and adds **`userId`** to every subsequent `track` envelope. Listeners that support identity (e.g. your API) can implement `identify` and receive this call too.
+
+- **`userId`** (string) – Your stable user id.
+- **`traits`** (object, optional) – e.g. `{ email, name, plan }`.
+
+**Example**
+
+```ts
+identify('user-123', { email: 'user@example.com', plan: 'pro' });
+track({ name: 'settings_updated' }); // envelope will include userId: 'user-123'
+```
+
+Same as `track`, **identify** is safe before `init()` (queued or dropped). On flush, all queued `identify` calls are replayed **before** queued `track` calls.
+
+---
+
+### 4. `flush()` – wait for batched sends
+
+Some listeners (e.g. custom API) batch events and send periodically. Call **`flush()`** when you need to wait for current batches to be sent (e.g. before page unload or in tests).
+
+```ts
+window.addEventListener('beforeunload', () => {
+  flush(); // best-effort; may not complete if page unloads immediately
+});
+```
+
+Returns a **Promise**; await it if you need to block until listeners have flushed.
+
+---
+
+### 5. `reset()` – clear state and teardown listeners
+
+Clears the pre-init queue, clears stored `userId`, and calls **`teardown()`** on each listener (if implemented). Use in **tests** (between cases) or on **logout** so the next user does not inherit the previous identity.
+
+```ts
+await reset();
+// SDK is no longer initialized; track/identify will queue or drop again until init() is called
+```
+
+---
+
+### Auto-configuration and direct backend communication
+
+When you pass **`configUrl`** or **`getConfig`** at init, the SDK **fetches listener configuration** and **creates listeners automatically** from its built-in registry (noop, clarity, ga, custom-api). **appId** and **environment** are always taken from init options (e.g. from your environment files); only listener details come from the API.
+
+- **Config API** – Your backend returns JSON with **listener details only**: `{ listeners: [ { id, enabled?, config } ] }`. **appId** and **environment** are not read from the API; pass them to `init()` from your env. See [docs/configuration.md](docs/configuration.md) for the full contract.
+- **Built-in listeners** – The SDK creates and registers the corresponding listeners (Clarity, GA, custom API) from the config. No proxy: each listener sends events **directly** from the client to its backend (Clarity, Google, your API). Bandwidth overhead is minimal; config is fetched once at init.
+- **Manual override** – Use **`listenerFactories`** to add custom listener ids or override built-in ones when using remote config.
+
+Example: **appId** and **environment** from env files; config API returns only listeners. Products call `init({ appId: import.meta.env.VITE_APP_ID, environment: import.meta.env.VITE_ENV, configUrl: 'https://...' })` and get Clarity, GA, and custom API auto-configured. Events go client → Clarity, client → GA, client → your API.
+
+---
+
+### Pre-init behavior (queue vs drop)
+
+Calls to **`track`** and **`identify`** before **`init()`** are handled according to **`preInitBehavior`**:
+
+| Mode | Behavior |
+|------|----------|
+| **`drop`** (default) | Events before `init()` are ignored. |
+| **`queue`** | Events are stored (up to `queueMaxSize`, events older than `queueTtlMs` at flush are dropped). After `init()` completes, queued **identify** calls are replayed first (in order), then queued **track** calls (in order). |
+
+**When to use queue**
+
+- You load the SDK early and call `track`/`identify` before your init code runs (e.g. in a shared layout).
+- You want early events (e.g. first click) to be sent once the SDK is initialized.
+
+**When to use drop**
+
+- You always call `init()` before any `track`/`identify` (e.g. in `main.ts`).
+- You want to avoid any memory or replay logic (e.g. strict SSR).
+
+**SSR / Node:** When `typeof window === 'undefined'`, the SDK **always drops** pre-init events (no queue), regardless of `preInitBehavior`. Call `init()` only in the browser or omit analytics in SSR bundles.
+
+---
+
+### Listeners
+
+Listeners are **adapters** that receive the same enriched event envelope and send it to a backend (Clarity, GA, your API). You pass **instances** at `init()`; the core does not import provider code.
+
+**No-op listener** – Use when analytics is disabled or in tests.
+
+```ts
+import { createNoopListener } from '@snovasys/usage-analytics-sdk/noop';
+
+listeners: [{ id: 'noop', listener: createNoopListener(), config: {} }]
+```
+
+**Custom API listener** – POST events to your endpoint. Optional batching.
+
+```ts
+import { createCustomApiListener } from '@snovasys/usage-analytics-sdk/custom-api';
+
+listeners: [
+  {
+    id: 'api',
+    listener: createCustomApiListener({
+      endpoint: 'https://api.example.com/analytics/events',
+      apiKey: 'optional-bearer-token',
+      batchSize: 10,        // send after 10 events (default 1)
+      flushIntervalMs: 5000, // or after 5s (default 5000)
+    }),
+    config: {},
+  },
+]
+```
+
+**Clarity and GA listeners** – Built-in listeners (script injection; no npm deps). Use via auto-config (id `clarity` / `ga` in remote config) or import for manual wiring:
+
+```ts
+import { createClarityListener } from '@snovasys/usage-analytics-sdk/clarity';
+import { createGAListener } from '@snovasys/usage-analytics-sdk/ga';
+
+listeners: [
+  { id: 'clarity', listener: createClarityListener({ projectId: 'your-project-id' }), config: {} },
+  { id: 'ga', listener: createGAListener({ measurementId: 'G-XXXXXXXX' }), config: {} },
+]
+```
+
+**Multiple listeners** – Same events go to all.
+
+```ts
+listeners: [
+  { id: 'api', listener: createCustomApiListener({ endpoint: '...' }), config: {} },
+  { id: 'noop', listener: createNoopListener(), config: {} },
+  // Add Clarity/GA adapters the same way
+],
+```
+
+**Listener entry shape**
+
+- **`id`** (string, optional) – For logging and `onError(context.listenerId)`.
+- **`enabled`** (boolean, default `true`) – If `false`, the listener is not registered.
+- **`listener`** – Object implementing `init(config)`, `track(envelope)`, and optionally `identify`, `flush`, `teardown`.
+- **`config`** – Passed to `listener.init(config)` (opaque to the SDK).
+
+---
+
+### How an admin decides whether Clarity (or any backend) receives events
+
+The SDK does **not** decide which backends receive events. The **app** (or the config an admin controls) decides at **init** by which listeners it passes and whether each is **enabled**.
+
+**Two ways an admin can control this:**
+
+1. **Include or exclude the listener** – Only add the Clarity listener to `listeners` when the admin wants Clarity to receive events (e.g. from env or remote config).
+2. **Use the `enabled` flag** – Add the Clarity listener to the config but set **`enabled: false`** when the admin wants Clarity off. The SDK will not register that listener, so Clarity will not receive any events.
+
+**Who controls the config?**
+
+The object passed to `init(options)` is built by your app. The admin controls it indirectly by controlling **how** that object is built, for example:
+
+- **Environment variables** – e.g. `VITE_ANALYTICS_CLARITY_ENABLED=true` and `VITE_ANALYTICS_CLARITY_PROJECT_ID=xxx`. The app reads these and only adds (or enables) the Clarity listener when the admin has set them.
+- **Remote config / feature flags** – Admin toggles “Clarity” in a dashboard; the app fetches config and builds the `listeners` array accordingly before calling `init()`.
+- **Admin API** – Backend returns which analytics backends are enabled for the tenant or app; the app builds `listeners` from that and calls `init()`.
+
+**Example – env-driven: Clarity only when enabled**
+
+```ts
+import { init, track } from '@snovasys/usage-analytics-sdk';
+import { createClarityListener } from '@snovasys/usage-analytics-sdk-clarity'; // or your Clarity adapter
+
+const clarityProjectId = import.meta.env.VITE_CLARITY_PROJECT_ID;
+const clarityEnabled = import.meta.env.VITE_CLARITY_ENABLED === 'true';
+
+const listeners = [];
+if (clarityEnabled && clarityProjectId) {
+  listeners.push({
+    id: 'clarity',
+    enabled: true,
+    listener: createClarityListener({ projectId: clarityProjectId }),
+    config: { projectId: clarityProjectId },
+  });
+}
+
+await init({
+  appId: 'my-app',
+  listeners,
+});
+```
+
+**Example – admin toggle: Clarity enabled/disabled via `enabled`**
+
+```ts
+// analyticsConfig comes from your backend or feature-flag service (admin-controlled)
+const analyticsConfig = await fetchAnalyticsConfig(); // { clarityEnabled: true, clarityProjectId: '...' }
+
+const listeners = [
+  {
+    id: 'clarity',
+    enabled: analyticsConfig.clarityEnabled,
+    listener: createClarityListener({ projectId: analyticsConfig.clarityProjectId }),
+    config: { projectId: analyticsConfig.clarityProjectId },
+  },
+];
+
+await init({ appId: 'my-app', listeners });
+```
+
+**Summary**
+
+| Admin wants Clarity to receive events | What to do |
+|---------------------------------------|------------|
+| Yes | Include Clarity listener in `listeners` with `enabled: true` (or omit `enabled`; default is true). |
+| No  | Either omit the Clarity listener from `listeners`, or include it with **`enabled: false`**. |
+
+The SDK never talks to Clarity by itself; it only forwards events to the listeners you register at init. So **whether Clarity receives events is entirely decided by the config you pass into `init()`** (which you can drive from env, feature flags, or admin API).
+
+---
+
+### Multi-product setup: switch listeners for all products without a release
+
+**Problem:** You have many products (e.g. 100), each with its own frontend. As a company admin you want to turn Clarity (or another listener) on or off for **all** products, or change which backends receive events, **without** releasing every product or editing each app’s code.
+
+If each product decides listeners at **build time** (e.g. env vars) or from **product-specific** config, then changing listeners globally means changing config in every product and doing a release for each. That does not scale.
+
+**Solution: central runtime config.** All products get their analytics config from **one admin-controlled API** (or feature-flag service) **at runtime**, before calling `init()`. The company admin changes that central config; every product picks up the new config on the next load (or after cache TTL). No per-product release needed.
+
+**Pattern:**
+
+1. **Central config API** – A single backend (e.g. platform BFF, config service, or feature-flag service) that the company admin updates. It returns which listeners are enabled and their settings (e.g. Clarity project id, custom API endpoint, etc.), optionally per product/tenant or globally.
+2. **Same bootstrap in every product** – Each product’s app, at startup (e.g. in `main.ts` or root layout):
+   - Calls the central API (e.g. `GET /api/platform/analytics-config` or your feature-flag SDK).
+   - Builds the `listeners` array from the response (which listeners are enabled, their config).
+   - Calls `init({ appId, environment, listeners, ... })` with that config.
+
+So the **source of truth** for “which listeners are on” is the central API, not env vars or code in each product. Admin changes the central config; all products follow it on next load.
+
+**Example – central config API response (admin-controlled):**
+
+```json
+{
+  "listeners": [
+    { "id": "clarity", "enabled": true, "config": { "projectId": "abc123" } },
+    { "id": "custom-api", "enabled": true, "config": { "endpoint": "https://api.example.com/events", "apiKey": "..." } }
+  ]
+}
+```
+
+**Example – product bootstrap (same in every product):**
+
+```ts
+// In every product's main.ts or analytics bootstrap – same code, config comes from central API
+import { init, track } from '@snovasys/usage-analytics-sdk';
+import { createClarityListener } from '@snovasys/usage-analytics-sdk-clarity';
+import { createCustomApiListener } from '@snovasys/usage-analytics-sdk/custom-api';
+
+async function bootstrapAnalytics() {
+  const centralConfig = await fetch('https://platform.example.com/api/analytics-config').then(r => r.json());
+  // centralConfig.listeners: [{ id, enabled, config }, ...]
+
+  const listeners = centralConfig.listeners
+    .filter((entry: { enabled: boolean }) => entry.enabled)
+    .map((entry: { id: string; config: unknown }) => {
+      if (entry.id === 'clarity') {
+        return { id: 'clarity', listener: createClarityListener(entry.config as { projectId: string }), config: entry.config };
+      }
+      if (entry.id === 'custom-api') {
+        return { id: 'custom-api', listener: createCustomApiListener(entry.config as { endpoint: string; apiKey?: string }), config: entry.config };
+      }
+      return null;
+    })
+    .filter(Boolean);
+
+  await init({
+    appId: 'my-product-id', // or from centralConfig
+    environment: import.meta.env.MODE,
+    listeners,
+  });
+}
+
+await bootstrapAnalytics();
+track({ name: 'app_loaded' });
+```
+
+**Optional:** You can cache the config (e.g. in memory or sessionStorage with a TTL) so you don’t hit the API on every load; when the admin changes the config, products still pick it up after cache expiry or next deploy of the central API.
+
+**Summary:**
+
+| Approach | Admin changes listeners for all products |
+|----------|------------------------------------------|
+| Build-time / env per product | Needs a release (or env change + release) per product. |
+| **Central runtime config API** | Admin updates central API; all products get new config on next load. **No product release needed.** |
+
+The SDK does not fetch config itself; it only accepts the config you pass to `init()`. So you keep one central API (or feature-flag service) as the source of truth, and every product uses the same pattern: fetch config → build listeners → init().
+
+---
+
+### Error handling
+
+- **Config validation** – Invalid `init` options (e.g. missing `appId`) throw; the SDK does not partially init.
+- **Listener init** – If `listener.init(config)` throws, the SDK calls **`onError(error, { listenerId })`** and does **not** register that listener. Other listeners are still registered.
+- **Listener track/identify** – The SDK wraps each call in try/catch. If a listener throws, **`onError`** is called and the loop continues to the next listener. One failing listener does not break others or your app.
+
+**Example**
+
+```ts
+onError: (error, ctx) => {
+  logger.error('Analytics listener failed', { listenerId: ctx?.listenerId, error });
+}
+```
+
+---
+
+### Session and user identity
+
+- **Session id** – If you do not pass **`sessionId`** in `init()`, the SDK generates a UUID and, in the browser, can persist it in `sessionStorage` (keyed by `appId`) so it survives reloads. In Node/SSR there is no storage; a new id is used per process.
+- **User id** – Set via **`identify(userId, traits?)`**. Stored in memory and added to every subsequent event envelope until **`reset()`** (e.g. logout).
+
+---
+
+## Usage examples
+
+**Minimal (no listeners – events are dropped after enrich)**
+
+```ts
+import { init, track } from '@snovasys/usage-analytics-sdk';
+await init({ appId: 'my-app' });
+track({ name: 'app_loaded' });
+```
+
+**With custom API and user identity**
+
+```ts
+import { init, track, identify } from '@snovasys/usage-analytics-sdk';
+import { createCustomApiListener } from '@snovasys/usage-analytics-sdk/custom-api';
+
+await init({
+  appId: 'my-app',
+  environment: 'production',
+  listeners: [
+    {
+      id: 'api',
+      listener: createCustomApiListener({
+        endpoint: 'https://api.example.com/events',
+        apiKey: process.env.ANALYTICS_API_KEY,
+        batchSize: 5,
+      }),
+      config: {},
+    },
+  ],
+});
+
+identify(user.id, { email: user.email });
+track({ name: 'dashboard_viewed', properties: { tab: 'overview' } });
+```
+
+**Queue mode – track before init**
+
+```ts
+// Script runs early; init() runs later (e.g. after config load)
+track({ name: 'early_click', properties: { target: 'nav' } });
+identify('anonymous-session');
+
+await init({
+  appId: 'my-app',
+  preInitBehavior: 'queue',
+  queueMaxSize: 100,
+  queueTtlMs: 5000,
+  listeners: [/* ... */],
+});
+// Queued identify then track are replayed to listeners
+```
+
+**With onError**
+
+```ts
+await init({
+  appId: 'my-app',
+  onError: (error, ctx) => {
+    if (ctx?.listenerId) {
+      reportToMonitoring({ listenerId: ctx.listenerId, error: error.message });
+    }
+  },
+  listeners: [/* ... */],
+});
+```
+
+**Logout – reset identity**
+
+```ts
+async function logout() {
+  await reset();
+  // Redirect or clear auth state
+}
+```
+
+---
+
+## Entry points
+
+| Import | Contents |
+|--------|----------|
+| `@snovasys/usage-analytics-sdk` | Core: `init`, `track`, `identify`, `flush`, `reset`, `isInitialized`, and types. |
+| `@snovasys/usage-analytics-sdk/noop` | `createNoopListener()`, `noopListener`, and types. |
+| `@snovasys/usage-analytics-sdk/custom-api` | `createCustomApiListener(config)`, `CustomApiListenerConfig`, and types. |
+
+Only import the entry points you use so bundlers can tree-shake the rest.
+
+---
+
+## API reference and listener authoring
+
+- **[API reference](docs/api.md)** – All methods and types.
+- **[Listener authoring](docs/listener-authoring.md)** – Implement your own listener (e.g. Clarity, GA) and ship it as a separate package.
+
+---
+
+## License
+
+MIT