@layers/client 1.1.0 → 1.2.0

package/README.md

@@ -1,64 +1,289 @@
-# @layers/client
+# Layers Web SDK
 
-Web browser SDK for Layers Analytics. Thin wrapper over the Rust/WASM core (`@layers/core-wasm`) that adds browser-specific features: localStorage persistence, network detection, page lifecycle flush via `sendBeacon`, and React integration.
+`@layers/client` is the Layers analytics SDK for web browsers. It provides event tracking, screen tracking, user identification, automatic attribution capture (UTM parameters, click IDs, referrer), consent management, and lifecycle-aware event flushing with `sendBeacon` support.
 
-## Install
+## Requirements
+
+- Modern browser with ES module support
+- React 18+ (for React hooks, optional)
+
+## Installation
 
 ```bash
 npm install @layers/client
 # or
+yarn add @layers/client
+# or
 pnpm add @layers/client
 ```
 
 ## Quick Start
 
-```ts
+```typescript
 import { LayersClient } from '@layers/client';
 
 const layers = new LayersClient({
-  apiKey: 'your-api-key',
   appId: 'your-app-id',
   environment: 'production'
 });
-
 await layers.init();
 
 // Track events
-await layers.track('button_click', { button: 'signup' });
-
-// Track screen views
-await layers.screen('home_page');
+layers.track('button_click', { button_name: 'signup' });
 
-// Identify a user
-layers.setAppUserId('user-123');
+// Track page views
+layers.screen('Home');
 
-// Shut down gracefully
-await layers.shutdownAsync();
+// Identify users
+layers.setAppUserId('user_123');
 ```
 
 ## Configuration
 
-All fields for `LayersConfig`:
+### LayersConfig
+
+```typescript
+interface LayersConfig {
+  appId: string;
+  environment: 'development' | 'staging' | 'production';
+  appUserId?: string;
+  enableDebug?: boolean;
+  baseUrl?: string;
+  flushIntervalMs?: number;
+  flushThreshold?: number;
+  maxQueueSize?: number;
+}
+```
+
+| Option            | Type          | Default                   | Description                                      |
+| ----------------- | ------------- | ------------------------- | ------------------------------------------------ |
+| `appId`           | `string`      | _required_                | Your Layers application identifier.              |
+| `environment`     | `Environment` | _required_                | `'development'`, `'staging'`, or `'production'`. |
+| `appUserId`       | `string`      | `undefined`               | Optional user ID to set at construction time.    |
+| `enableDebug`     | `boolean`     | `false`                   | Enable verbose console logging.                  |
+| `baseUrl`         | `string`      | `"https://in.layers.com"` | Custom ingest API endpoint.                      |
+| `flushIntervalMs` | `number`      | `30000`                   | Automatic flush interval in milliseconds.        |
+| `flushThreshold`  | `number`      | `10`                      | Queue size that triggers an automatic flush.     |
+| `maxQueueSize`    | `number`      | `1000`                    | Maximum events in the queue before dropping.     |
+
+```typescript
+const layers = new LayersClient({
+  appId: 'your-app-id',
+  environment: 'development',
+  enableDebug: true,
+  flushIntervalMs: 15000,
+  flushThreshold: 5,
+  maxQueueSize: 5000
+});
+```
+
+## Core API
 
-| Field             | Type                                         | Default                 | Description                                |
-| ----------------- | -------------------------------------------- | ----------------------- | ------------------------------------------ |
-| `apiKey`          | `string`                                     | _required_              | API key from the Layers dashboard          |
-| `appId`           | `string`                                     | _required_              | Application identifier                     |
-| `environment`     | `'development' \| 'staging' \| 'production'` | _required_              | Deployment environment                     |
-| `appUserId`       | `string`                                     | `undefined`             | Pre-set user ID at init time               |
-| `enableDebug`     | `boolean`                                    | `false`                 | Verbose console logging for all SDK calls  |
-| `baseUrl`         | `string`                                     | `https://in.layers.com` | Override the ingest endpoint               |
-| `flushIntervalMs` | `number`                                     | `30000`                 | Periodic flush interval (ms)               |
-| `flushThreshold`  | `number`                                     | `10`                    | Queue depth that triggers auto-flush       |
-| `maxQueueSize`    | `number`                                     | `1000`                  | Max events in queue before dropping oldest |
+### Constructor & Initialization
 
-## React Integration
+```typescript
+const layers = new LayersClient(config: LayersConfig);
+await layers.init();
+```
+
+The constructor creates the SDK instance with localStorage-backed persistence. Calling `init()` detects device info, attaches lifecycle listeners (online/offline, visibility change, beforeunload), captures attribution signals, and fetches remote config.
+
+You can call `track()` and `screen()` before `init()` completes -- events are queued.
 
-The SDK includes first-class React bindings via `@layers/client/react`.
+### Event Tracking
+
+```typescript
+track(eventName: string, properties?: EventProperties): void
+```
+
+Events are batched and flushed automatically. Attribution properties (UTM, click IDs, referrer) from the current session are automatically merged into every event.
+
+```typescript
+layers.track('purchase_completed', {
+  product_id: 'sku_123',
+  price: 9.99,
+  currency: 'USD'
+});
+```
+
+### Screen/Page Tracking
+
+```typescript
+screen(screenName: string, properties?: EventProperties): void
+```
+
+Attribution properties are automatically merged.
+
+```typescript
+layers.screen('ProductDetail', { product_id: 'sku_123' });
+```
+
+### User Identity
+
+```typescript
+// Set or clear the app user ID
+setAppUserId(appUserId: string | undefined): void
+
+// Get the current user ID
+getAppUserId(): string | undefined
+
+// Deprecated aliases
+setUserId(userId: string): void
+getUserId(): string | undefined
+```
 
-### Provider
+```typescript
+// After login
+layers.setAppUserId('user_123');
 
-Wrap your app in `<LayersProvider>` to initialize the SDK and make it available to hooks:
+// On logout
+layers.setAppUserId(undefined);
+```
+
+### User Properties
+
+```typescript
+setUserProperties(properties: UserProperties): void
+```
+
+```typescript
+layers.setUserProperties({
+  email: 'user@example.com',
+  plan: 'premium',
+  signup_date: '2024-01-15'
+});
+```
+
+### Consent Management
+
+```typescript
+setConsent(consent: ConsentState): void
+getConsentState(): ConsentState
+```
+
+```typescript
+interface ConsentState {
+  analytics?: boolean;
+  advertising?: boolean;
+}
+```
+
+```typescript
+// User accepts analytics only
+layers.setConsent({ analytics: true, advertising: false });
+
+// Read current state
+const consent = layers.getConsentState();
+```
+
+### Session Management
+
+```typescript
+// Get the current session ID
+getSessionId(): string
+
+// End the current session and start a new one
+startNewSession(): void
+```
+
+### Device Info
+
+```typescript
+setDeviceInfo(deviceInfo: DeviceContext): void
+```
+
+Override auto-detected device context fields.
+
+### Flush & Shutdown
+
+```typescript
+// Flush all queued events to the server
+async flush(): Promise<void>
+
+// Shut down immediately (no flush, events persisted to localStorage)
+shutdown(): void
+
+// Shut down with a final flush (with timeout)
+async shutdownAsync(timeoutMs?: number): Promise<void>  // default: 3000ms
+```
+
+### Error Handling
+
+```typescript
+on(event: 'error', listener: (error: Error) => void): this
+off(event: 'error', listener: (error: Error) => void): this
+```
+
+```typescript
+layers.on('error', (error) => {
+  console.error('Layers error:', error.message);
+});
+```
+
+## Attribution
+
+The SDK automatically captures and persists attribution signals from the current page URL and referrer.
+
+### Captured Signals
+
+**Click IDs** (highest priority -- overwrites existing attribution):
+
+- `fbclid` (Meta/Facebook)
+- `gclid`, `gbraid`, `wbraid` (Google)
+- `ttclid` (TikTok)
+- `msclkid` (Microsoft/Bing)
+- `rclid` (Reddit)
+
+**UTM Parameters**:
+
+- `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`
+
+**Referrer**:
+
+- `document.referrer`
+
+### How It Works
+
+1. On `init()`, the SDK reads the current URL's query parameters and `document.referrer`.
+2. Attribution data is persisted in `localStorage` with a 30-day TTL.
+3. Click IDs take priority -- a new click ID overwrites the entire stored record.
+4. UTM parameters overwrite on fresh campaign visits, but preserve existing click IDs.
+5. Attribution properties are automatically prefixed with `$attribution_` and merged into every `track()` and `screen()` call.
+
+### Manually Reading Attribution
+
+```typescript
+import { getAttribution, getAttributionProperties } from '@layers/client';
+
+// Get the full stored attribution data (or null if expired/missing)
+const attribution = getAttribution();
+
+// Get a flat property bag for merging into events
+const props = getAttributionProperties();
+// { '$attribution_utm_source': 'google', '$attribution_click_id_param': 'gclid', ... }
+```
+
+### AttributionData Type
+
+```typescript
+interface AttributionData {
+  click_id_param?: string;
+  click_id_value?: string;
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+  referrer_url?: string;
+  captured_at: number;
+}
+```
+
+## React Integration
+
+The SDK includes React hooks for idiomatic usage. Import from `@layers/client/react`.
+
+### LayersProvider
 
 ```tsx
 import { LayersProvider } from '@layers/client/react';
@@ -67,7 +292,6 @@ function App() {
   return (
     <LayersProvider
       config={{
-        apiKey: 'your-api-key',
         appId: 'your-app-id',
         environment: 'production'
       }}
@@ -78,73 +302,87 @@ function App() {
 }
 ```
 
-The provider creates a `LayersClient` on mount, calls `init()`, and shuts it down on unmount.
+Initializes the client on mount and shuts it down on unmount.
 
-### Hooks
+### useLayers
 
-All hooks must be used inside a `<LayersProvider>`.
-
-#### `useTrack()`
+```typescript
+function useLayers(): LayersClient;
+```
 
-Returns a stable, memoized function for tracking events:
+Returns the `LayersClient` instance. Throws if used outside a `<LayersProvider>`.
 
 ```tsx
-import { useTrack } from '@layers/client/react';
+function MyComponent() {
+  const layers = useLayers();
+  layers.track('component_viewed');
+}
+```
+
+### useTrack
+
+```typescript
+function useTrack(): (eventName: string, properties?: EventProperties) => void;
+```
 
+Returns a stable, memoized track function.
+
+```tsx
 function SignupButton() {
   const track = useTrack();
 
-  return <button onClick={() => track('signup_click', { source: 'hero' })}>Sign up</button>;
+  return <button onClick={() => track('signup_click', { source: 'hero' })}>Sign Up</button>;
 }
 ```
 
-#### `useScreen()`
+### useScreen
 
-Returns a stable, memoized function for tracking screen views:
+```typescript
+function useScreen(): (screenName: string, properties?: EventProperties) => void;
+```
 
-```tsx
-import { useScreen } from '@layers/client/react';
-import { useEffect } from 'react';
+Returns a stable, memoized screen tracking function.
 
+```tsx
 function Dashboard() {
   const screen = useScreen();
   useEffect(() => {
-    screen('dashboard');
+    screen('Dashboard');
   }, [screen]);
 
-  return <div>...</div>;
+  return <div>Dashboard</div>;
 }
 ```
 
-#### `useIdentify()`
+### useIdentify
 
-Returns a function to set (or clear) the app user ID:
+```typescript
+function useIdentify(): (userId: string | undefined) => void;
+```
 
-```tsx
-import { useIdentify } from '@layers/client/react';
+Returns a stable, memoized identify function. Pass `undefined` to clear.
 
+```tsx
 function LoginForm() {
   const identify = useIdentify();
 
-  const onLogin = (userId: string) => {
-    identify(userId);
-  };
-
-  const onLogout = () => {
-    identify(undefined);
-  };
+  const onLogin = (userId: string) => identify(userId);
+  const onLogout = () => identify(undefined);
 }
 ```
 
-#### `useConsent()`
+### useConsent
 
-Returns functions to get and set consent state:
+```typescript
+function useConsent(): {
+  setConsent: (consent: ConsentState) => void;
+  getConsentState: () => ConsentState;
+};
+```
 
 ```tsx
-import { useConsent } from '@layers/client/react';
-
 function ConsentBanner() {
-  const { setConsent, getConsentState } = useConsent();
+  const { setConsent } = useConsent();
 
   return (
     <button onClick={() => setConsent({ analytics: true, advertising: false })}>
@@ -154,71 +392,84 @@ function ConsentBanner() {
 }
 ```
 
-#### `useLayers()`
+## Automatic Behaviors
 
-Returns the raw `LayersClient` instance for advanced usage:
-
-```tsx
-import { useLayers } from '@layers/client/react';
+- **Attribution capture**: UTM parameters, click IDs, and referrer are captured and persisted on init.
+- **Attribution enrichment**: Stored attribution is merged into every `track()` and `screen()` call.
+- **Online/offline detection**: Events are flushed when the browser reconnects.
+- **Visibility change flush**: Events are flushed via `navigator.sendBeacon` when the page is hidden (tab switch, minimize).
+- **Before unload flush**: Events are persisted to `localStorage` on page close.
+- **Periodic flush**: Events are flushed on a timer (configurable).
+- **Remote config**: Server configuration is fetched during init.
+- **Device context**: OS, browser, locale, screen size, and timezone are detected automatically.
+- **Event persistence**: Events are persisted in `localStorage` and rehydrated on page load.
 
-function Advanced() {
-  const layers = useLayers();
-  // layers.setUserProperties({ plan: 'pro' });
-}
-```
+## SPA (Single Page App) Usage
 
-## Error Handling
+For single-page apps with client-side routing, call `screen()` on route changes:
 
-Register error listeners to catch errors from `track()`, `screen()`, and `flush()` that would otherwise be silently dropped:
+```typescript
+// React Router
+import { useLocation } from 'react-router-dom';
 
-```ts
-const layers = new LayersClient({ ... });
+function RouteTracker() {
+  const location = useLocation();
+  const screen = useScreen();
 
-layers.on('error', (err) => {
-  console.error('Layers SDK error:', err.message);
-  // Send to your error reporting service
-});
+  useEffect(() => {
+    screen(location.pathname, { search: location.search });
+  }, [location, screen]);
 
-// Remove a specific listener
-layers.off('error', myListener);
+  return null;
+}
 ```
 
-When `enableDebug` is `true` and no error listeners are registered, errors are logged to `console.warn`.
+```typescript
+'use client';
 
-## Consent Management
+import { usePathname } from 'next/navigation';
 
-Control what data the SDK collects:
+function PageTracker() {
+  const pathname = usePathname();
+  const screen = useScreen();
 
-```ts
-// Allow analytics, deny advertising
-layers.setConsent({ analytics: true, advertising: false });
+  useEffect(() => {
+    screen(pathname);
+  }, [pathname, screen]);
 
-// Check current state
-const consent = layers.getConsentState();
+  return null;
+}
 ```
 
-When `analytics` is `false`, `track()` and `screen()` calls are silently dropped.
-
-## Page Lifecycle (sendBeacon)
-
-The SDK automatically flushes events when the page becomes hidden using `navigator.sendBeacon()` for reliable delivery. If `sendBeacon` fails, events are persisted to localStorage and retried on the next page load.
-
-On `beforeunload`, events are synchronously written to localStorage as a last resort.
-
-## Debug Mode
-
-Enable `enableDebug: true` to see detailed logs for every SDK operation:
-
-```
-[Layers] track("button_click", 2 properties)
-[Layers] screen("home_page", 0 properties)
-[Layers] setAppUserId("user-123")
+## TypeScript Types
+
+```typescript
+import type {
+  AttributionData,
+  BaseEvent,
+  ConsentState,
+  DeviceContext,
+  Environment,
+  ErrorListener,
+  EventProperties,
+  EventsBatchPayload,
+  LayersConfig,
+  RemoteConfigResponse,
+  UserProperties
+} from '@layers/client';
 ```
 
-## Server-Side Rendering
+## Wire Protocol Types
 
-The SDK safely handles SSR environments where `window`, `document`, and `navigator` are unavailable. Device detection and lifecycle listeners are skipped in SSR. For server-side tracking, use [@layers/node](../node) instead.
+The package also exports TypeScript interfaces for the Layers wire protocol, useful for building custom integrations:
 
-## License
-
-MIT
+```typescript
+import type {
+  BaseEvent,
+  ConsentPayload,
+  EventsBatchPayload,
+  RemoteConfigResponse,
+  SKANPostbackPayload,
+  UserPropertiesPayload
+} from '@layers/client';
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/client",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -33,7 +33,7 @@
     "dist"
   ],
   "dependencies": {
-    "@layers/core-wasm": "1.1.0"
+    "@layers/core-wasm": "1.2.0"
   },
   "peerDependencies": {
     "react": ">=18"