@sessionlens/sdk 0.2.0 → 0.3.0

package/README.md

@@ -45,6 +45,125 @@ sessionLens.sessionLensIdentify({
 sessionLens.sessionLensReset();
 ```
 
+## Identity and anonymous tracking (0.3.0+)
+
+`user_id` is optional. Without it, events are tracked against a persistent anonymous device id
+(`localStorage._sl_device_id`). Link the device to a person when you know who they are:
+
+```javascript
+await sessionLens.sessionLensInit({ sdk_key: '...', org_id: '...' }); // no user_id needed
+
+sessionLens.sessionLensTrack({ event_name: 'pricing_viewed' });       // anonymous
+
+sessionLens.identify('user-123', { name: 'Ada Lovelace', email: 'ada@example.com', plan: 'pro' });
+sessionLens.setUserProperties({ company: 'Analytical Engines' });     // name/email map to core profile fields
+
+sessionLens.reset();                                                  // on logout: new anonymous identity
+```
+
+- Identifying again on the same device (a different user) links the device to the new user; past events keep their original attribution.
+- `alias(newId, oldId)` is deprecated and simply calls `identify(newId)`.
+- Passing `user_id` to `sessionLensInit` still works and behaves like an implicit `identify()`.
+- Each event is automatically enriched with `$device_id`, `$distinct_id`, `$insert_id`, `$library`, `$library_version`, `$current_url`, `$pathname`, `$referrer`, `$initial_referrer`, UTM parameters, screen size and client browser/OS hints. Browser, OS and geo (from the request IP) are derived on the server.
+- Trait limits: at most 100 keys, keys up to 128 characters, values up to 4 KB. Trait keys may not start with `$` or contain `.`; offending keys are dropped without failing the call.
+
+### Advanced Usage with Custom Configuration
+
+```javascript
+import sessionLens from '@sessionlens/sdk';
+
+// Initialize with custom API configuration
+await sessionLens.sessionLensInit({
+  sdk_key: 'your-sdk-key-here',
+  user_id: 'user123',
+  org_id: 'org456',
+  api_base_url: 'https://dev-api.sessionlens.com/v1', // Custom API base URL
+  endpoints: {
+    events: '/custom/events/ingest',     // Custom events endpoint
+    identify: '/custom/user/identify',   // Custom identify endpoint
+    reset: '/custom/session/reset',      // Custom reset endpoint
+    validate: '/custom/org/validate'     // Custom validation endpoint
+  },
+  debug: true
+});
+
+// Track events with rich properties
+sessionLens.sessionLensTrack({
+  event_name: 'user_action',
+  properties: {
+    action_type: 'form_submit',
+    form_name: 'contact_form',
+    fields_completed: 5,
+    time_spent: 120, // seconds
+    user_segment: 'premium',
+    referrer: document.referrer,
+    user_agent: navigator.userAgent
+  },
+  timestamp: Date.now() // Optional: auto-generated if not provided
+});
+
+// Identify user with comprehensive properties
+sessionLens.sessionLensIdentify({
+  user_id: 'user123',
+  properties: {
+    email: 'user@example.com',
+    name: 'John Doe',
+    plan: 'premium',
+    company: 'Acme Corp',
+    signup_date: '2024-01-15',
+    last_login: new Date().toISOString(),
+    preferences: {
+      theme: 'dark',
+      language: 'en',
+      notifications: true
+    }
+  }
+});
+```
+
+### Environment-Specific Configuration
+
+```javascript
+import sessionLens from '@sessionlens/sdk';
+
+// Determine environment
+const environment = process.env.NODE_ENV || 'development';
+
+// Environment-specific configuration
+const configs = {
+  development: {
+    api_base_url: 'https://dev-api.sessionlens.com/v1',
+    debug: true
+  },
+  staging: {
+    api_base_url: 'https://staging-api.sessionlens.com/v1',
+    debug: true
+  },
+  production: {
+    api_base_url: 'https://api.sessionlens.com/v1',
+    debug: false
+  }
+};
+
+// Initialize with environment-specific config
+await sessionLens.sessionLensInit({
+  sdk_key: 'your-sdk-key-here',
+  user_id: 'user123',
+  org_id: 'org456',
+  ...configs[environment]
+});
+
+// Track environment info
+sessionLens.sessionLensTrack({
+  event_name: 'app_initialized',
+  properties: {
+    environment: environment,
+    version: '1.0.0',
+    timestamp: Date.now()
+  }
+});
+```
+
 ### React Integration
 
 ```jsx
@@ -86,6 +205,103 @@ function App() {
 }
 ```
 
+### React Integration with Custom Configuration
+
+```jsx
+import React from 'react';
+import { useSessionLens, useSessionLensTrack, useSessionLensIdentify } from '@sessionlens/sdk';
+
+function App() {
+  // Environment-specific configuration
+  const environment = process.env.NODE_ENV || 'development';
+  
+  const configs = {
+    development: {
+      api_base_url: 'https://dev-api.sessionlens.com/v1',
+      debug: true
+    },
+    staging: {
+      api_base_url: 'https://staging-api.sessionlens.com/v1',
+      debug: true
+    },
+    production: {
+      api_base_url: 'https://api.sessionlens.com/v1',
+      debug: false
+    }
+  };
+
+  // Initialize SDK with environment-specific config
+  useSessionLens({
+    sdk_key: 'your-sdk-key-here',
+    user_id: 'user123',
+    org_id: 'org456',
+    ...configs[environment]
+  });
+
+  const track = useSessionLensTrack();
+  const identify = useSessionLensIdentify();
+
+  const handlePageView = () => {
+    track({
+      event_name: 'page_view',
+      properties: {
+        page: window.location.pathname,
+        referrer: document.referrer,
+        environment: environment,
+        timestamp: Date.now()
+      }
+    });
+  };
+
+  const handleUserAction = (action, details) => {
+    track({
+      event_name: 'user_action',
+      properties: {
+        action_type: action,
+        ...details,
+        user_agent: navigator.userAgent,
+        screen_resolution: `${screen.width}x${screen.height}`
+      }
+    });
+  };
+
+  const handleUserLogin = (userData) => {
+    identify({
+      user_id: userData.id,
+      properties: {
+        email: userData.email,
+        name: userData.name,
+        login_method: userData.loginMethod,
+        last_login: new Date().toISOString(),
+        preferences: userData.preferences
+      }
+    });
+  };
+
+  // Track page view on component mount
+  React.useEffect(() => {
+    handlePageView();
+  }, []);
+
+  return (
+    <div>
+      <button onClick={() => handleUserAction('button_click', { button: 'header_cta' })}>
+        Track Event
+      </button>
+      <button onClick={() => handleUserLogin({ 
+        id: 'user123', 
+        email: 'user@example.com',
+        name: 'John Doe',
+        loginMethod: 'email',
+        preferences: { theme: 'dark' }
+      })}>
+        Identify User
+      </button>
+    </div>
+  );
+}
+```
+
 ## Configuration
 
 ### Runtime Configuration

package/dist/core/config.d.ts

@@ -1,14 +1,16 @@
 export interface SessionLensConfig {
     sdk_key: string;
-    user_id: string;
+    user_id?: string;
     org_id: string;
     project_id?: string;
+    app?: string;
     debug?: boolean;
     api_base_url?: string;
     endpoints?: {
         events?: string;
         identify?: string;
         reset?: string;
+        userProperties?: string;
         validate?: string;
     };
 }
@@ -17,10 +19,11 @@ interface SessionInfo {
     client_id: string;
     org_id: string;
     project_id: string;
-    user_id: string;
+    user_id?: string;
     started_at: number;
     last_activity: number;
 }
+export declare function restartSession(): void;
 export declare function sessionLensInit(config: SessionLensConfig): Promise<void>;
 export declare function sessionLensGetConfig(): SessionLensConfig;
 export declare function getSessionInfo(): SessionInfo;

package/dist/core/enrich.d.ts

@@ -0,0 +1,6 @@
+/**
+ * System properties attached to every event. All browser access is guarded so this
+ * is safe to call during SSR (only identity/library fields are returned there).
+ * The server re-derives browser/os/geo authoritatively; the client UA fields are a fallback.
+ */
+export declare function buildSystemProperties(clientTimestamp: number): Record<string, any>;

package/dist/core/identity.d.ts

@@ -0,0 +1,14 @@
+export interface Identity {
+    device_id: string;
+    distinct_id: string;
+    user_id?: string;
+}
+export declare function getDeviceId(): string;
+/** Current identity. Anonymous visitors have distinct_id === device_id and no user_id. */
+export declare function getIdentity(): Identity;
+/** Persist a user identity. From now on events carry distinct_id = userId. */
+export declare function setUser(userId: string): void;
+/** Forget the user and start a fresh anonymous identity on a new device id. */
+export declare function resetIdentity(): Identity;
+/** Referrer of the very first page load, persisted once ('$direct' when there was none). */
+export declare function getInitialReferrer(currentReferrer: string): string;

package/dist/core/tracker.d.ts

@@ -1,4 +1,19 @@
+import { SessionLensConfig } from './config';
 import { SessionLensEvent, SessionLensUser } from '../types';
+/**
+ * Initialize the SDK. If `config.user_id` is supplied (pre-0.3 integrations) it is treated
+ * as an implicit identify() - sent only when it differs from the persisted identity.
+ */
+export declare function sessionLensInit(config: SessionLensConfig): Promise<void>;
 export declare function sessionLensTrack(event: SessionLensEvent): void;
+/** Link the current device to `userId` (last identify wins) and optionally set traits. */
+export declare function identify(userId: string, traits?: Record<string, any>): void;
+/** @deprecated Aliasing is subsumed by identify(); `oldId` is ignored (the device link is implicit). */
+export declare function alias(newId: string, _oldId?: string): void;
+/** Set traits on the current profile (`name` and `email` map to core profile fields). */
+export declare function setUserProperties(traits: Record<string, any>): void;
+/** Legacy signature: sessionLensIdentify({ user_id, properties }). */
 export declare function sessionLensIdentify(user: SessionLensUser): void;
-export declare function sessionLensReset(): void;
+/** Forget the user, start an anonymous identity on a new device id and a new session. */
+export declare function reset(): void;
+export declare const sessionLensReset: typeof reset;

package/dist/index.d.ts

@@ -2,12 +2,18 @@ import { SessionLensConfig } from './core/config';
 import { SessionLensEvent, SessionLensUser, SessionLensInstance } from './types';
 export * from './types';
 export { SessionLensConfig } from './core/config';
+export { SDK_VERSION } from './version';
 export * from './integrations/react';
 declare class SessionLens implements SessionLensInstance {
     sessionLensInit(config: SessionLensConfig): Promise<void>;
     sessionLensTrack(event: SessionLensEvent): void;
     sessionLensIdentify(user: SessionLensUser): void;
     sessionLensReset(): void;
+    identify(userId: string, traits?: Record<string, any>): void;
+    /** @deprecated Use identify(). */
+    alias(newId: string, oldId?: string): void;
+    setUserProperties(traits: Record<string, any>): void;
+    reset(): void;
 }
 declare const sessionLens: SessionLens;
 export default sessionLens;