@logg/signals 0.1.0 → 0.1.3

package/dist/index.d.mts

@@ -1,5 +1,23 @@
+interface UserContext {
+    user_id?: string;
+    anon_id?: string;
+    session_id: string;
+}
+interface EventContext {
+    screen?: string;
+    surface?: string;
+    request_id?: string;
+    entry_point?: string;
+    referrer_surface?: string;
+    [key: string]: unknown;
+}
+interface EventTarget {
+    type: string;
+    id: string;
+}
 interface EventData {
     type: string;
+    target?: EventTarget;
     [key: string]: unknown;
 }
 interface Event {
@@ -7,6 +25,9 @@ interface Event {
     timestamp: string;
     session_id: string;
     type: string;
+    user: UserContext;
+    context: EventContext;
+    target?: EventTarget;
     [key: string]: unknown;
 }
 interface ClientMetadata {
@@ -29,7 +50,7 @@ interface EventBatch {
 }
 interface SignalsConfig {
     apiKey: string;
-    endpoint: string;
+    endpoint?: string;
     batchSize?: number;
     batchInterval?: number;
     maxRetries?: number;
@@ -37,6 +58,9 @@ interface SignalsConfig {
     debug?: boolean;
     storage?: StorageAdapter;
     sessionId?: string;
+    userId?: string;
+    anonymousId?: string;
+    context?: EventContext;
 }
 interface StorageAdapter {
     getItem(key: string): Promise<string | null>;
@@ -54,6 +78,8 @@ declare class Signals {
     private flushTimer;
     private isDestroyed;
     private isFlushing;
+    private userContext;
+    private eventContext;
     constructor(config: SignalsConfig);
     private init;
     event(eventData: EventData): Promise<void>;
@@ -63,6 +89,13 @@ declare class Signals {
     private stopFlushTimer;
     getSessionId(): string;
     getQueueSize(): number;
+    identify(userId: string): void;
+    setAnonymousId(anonymousId: string): void;
+    setContext(context: EventContext): void;
+    updateContext(context: Partial<EventContext>): void;
+    getUserContext(): UserContext;
+    getContext(): EventContext;
+    reset(): void;
     destroy(): Promise<void>;
     private log;
 }
@@ -70,8 +103,9 @@ declare class Signals {
 declare class EventQueue {
     private queue;
     private storage;
-    private sessionId;
-    constructor(storage: StorageAdapter, sessionId: string);
+    private getUserContext;
+    private getEventContext;
+    constructor(storage: StorageAdapter, getUserContext: () => UserContext, getEventContext: () => EventContext);
     init(): Promise<void>;
     add(eventData: EventData): Promise<Event>;
     getAll(): Event[];
@@ -109,4 +143,4 @@ declare class MemoryStorageAdapter implements StorageAdapter {
 
 declare function getDefaultStorageAdapter(): StorageAdapter;
 
-export { AsyncStorageAdapter, type ClientMetadata, type Event, type EventBatch, type EventData, EventQueue, LocalStorageAdapter, MemoryStorageAdapter, type QueuedEvent, Signals, type SignalsConfig, type StorageAdapter, getDefaultStorageAdapter };
+export { AsyncStorageAdapter, type ClientMetadata, type Event, type EventBatch, type EventContext, type EventData, EventQueue, type EventTarget, LocalStorageAdapter, MemoryStorageAdapter, type QueuedEvent, Signals, type SignalsConfig, type StorageAdapter, type UserContext, getDefaultStorageAdapter };

package/dist/index.d.ts

@@ -1,5 +1,23 @@
+interface UserContext {
+    user_id?: string;
+    anon_id?: string;
+    session_id: string;
+}
+interface EventContext {
+    screen?: string;
+    surface?: string;
+    request_id?: string;
+    entry_point?: string;
+    referrer_surface?: string;
+    [key: string]: unknown;
+}
+interface EventTarget {
+    type: string;
+    id: string;
+}
 interface EventData {
     type: string;
+    target?: EventTarget;
     [key: string]: unknown;
 }
 interface Event {
@@ -7,6 +25,9 @@ interface Event {
     timestamp: string;
     session_id: string;
     type: string;
+    user: UserContext;
+    context: EventContext;
+    target?: EventTarget;
     [key: string]: unknown;
 }
 interface ClientMetadata {
@@ -29,7 +50,7 @@ interface EventBatch {
 }
 interface SignalsConfig {
     apiKey: string;
-    endpoint: string;
+    endpoint?: string;
     batchSize?: number;
     batchInterval?: number;
     maxRetries?: number;
@@ -37,6 +58,9 @@ interface SignalsConfig {
     debug?: boolean;
     storage?: StorageAdapter;
     sessionId?: string;
+    userId?: string;
+    anonymousId?: string;
+    context?: EventContext;
 }
 interface StorageAdapter {
     getItem(key: string): Promise<string | null>;
@@ -54,6 +78,8 @@ declare class Signals {
     private flushTimer;
     private isDestroyed;
     private isFlushing;
+    private userContext;
+    private eventContext;
     constructor(config: SignalsConfig);
     private init;
     event(eventData: EventData): Promise<void>;
@@ -63,6 +89,13 @@ declare class Signals {
     private stopFlushTimer;
     getSessionId(): string;
     getQueueSize(): number;
+    identify(userId: string): void;
+    setAnonymousId(anonymousId: string): void;
+    setContext(context: EventContext): void;
+    updateContext(context: Partial<EventContext>): void;
+    getUserContext(): UserContext;
+    getContext(): EventContext;
+    reset(): void;
     destroy(): Promise<void>;
     private log;
 }
@@ -70,8 +103,9 @@ declare class Signals {
 declare class EventQueue {
     private queue;
     private storage;
-    private sessionId;
-    constructor(storage: StorageAdapter, sessionId: string);
+    private getUserContext;
+    private getEventContext;
+    constructor(storage: StorageAdapter, getUserContext: () => UserContext, getEventContext: () => EventContext);
     init(): Promise<void>;
     add(eventData: EventData): Promise<Event>;
     getAll(): Event[];
@@ -109,4 +143,4 @@ declare class MemoryStorageAdapter implements StorageAdapter {
 
 declare function getDefaultStorageAdapter(): StorageAdapter;
 
-export { AsyncStorageAdapter, type ClientMetadata, type Event, type EventBatch, type EventData, EventQueue, LocalStorageAdapter, MemoryStorageAdapter, type QueuedEvent, Signals, type SignalsConfig, type StorageAdapter, getDefaultStorageAdapter };
+export { AsyncStorageAdapter, type ClientMetadata, type Event, type EventBatch, type EventContext, type EventData, EventQueue, type EventTarget, LocalStorageAdapter, MemoryStorageAdapter, type QueuedEvent, Signals, type SignalsConfig, type StorageAdapter, type UserContext, getDefaultStorageAdapter };

package/dist/index.js

@@ -67,10 +67,11 @@ async function retry(fn, options) {
 // src/EventQueue.ts
 var STORAGE_KEY = "session_signals_queue";
 var EventQueue = class {
-  constructor(storage, sessionId) {
+  constructor(storage, getUserContext, getEventContext) {
     this.queue = [];
     this.storage = storage;
-    this.sessionId = sessionId;
+    this.getUserContext = getUserContext;
+    this.getEventContext = getEventContext;
   }
   /**
    * Initialize queue by loading persisted events
@@ -91,11 +92,17 @@ var EventQueue = class {
    * Add event to queue
    */
   async add(eventData) {
+    const userContext = this.getUserContext();
+    const eventContext = this.getEventContext();
+    const { type, ...payload } = eventData;
     const event = {
       event_id: uuid(),
       timestamp: getTimestamp(),
-      session_id: this.sessionId,
-      ...eventData
+      session_id: userContext.session_id,
+      type,
+      user: userContext,
+      context: eventContext,
+      ...payload
     };
     this.queue.push({
       event,
@@ -334,6 +341,7 @@ function collectMetadata(version) {
 
 // src/Signals.ts
 var VERSION = "0.1.0";
+var DEFAULT_ENDPOINT = "https://api.logg.com/events";
 var DEFAULT_BATCH_SIZE = 10;
 var DEFAULT_BATCH_INTERVAL = 5e3;
 var DEFAULT_MAX_RETRIES = 3;
@@ -346,21 +354,30 @@ var Signals = class {
     if (!config.apiKey) {
       throw new Error("Signals: apiKey is required");
     }
-    if (!config.endpoint) {
-      throw new Error("Signals: endpoint is required");
-    }
+    const sessionId = config.sessionId ?? uuid();
+    const anonymousId = config.anonymousId ?? uuid();
     this.config = {
       apiKey: config.apiKey,
-      endpoint: config.endpoint,
+      endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
       batchSize: config.batchSize ?? DEFAULT_BATCH_SIZE,
       batchInterval: config.batchInterval ?? DEFAULT_BATCH_INTERVAL,
       maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
       retryDelay: config.retryDelay ?? DEFAULT_RETRY_DELAY,
       debug: config.debug ?? false,
       storage: config.storage ?? getDefaultStorageAdapter(),
-      sessionId: config.sessionId ?? uuid()
+      sessionId
+    };
+    this.userContext = {
+      session_id: sessionId,
+      anon_id: anonymousId,
+      user_id: config.userId
     };
-    this.queue = new EventQueue(this.config.storage, this.config.sessionId);
+    this.eventContext = config.context ?? {};
+    this.queue = new EventQueue(
+      this.config.storage,
+      () => this.userContext,
+      () => this.eventContext
+    );
     this.init();
   }
   /**
@@ -484,6 +501,62 @@ var Signals = class {
   getQueueSize() {
     return this.queue.size();
   }
+  /**
+   * Identify the current user
+   * Call this after user login to associate events with a user ID
+   */
+  identify(userId) {
+    this.userContext.user_id = userId;
+    this.log("User identified", { userId });
+  }
+  /**
+   * Set anonymous ID (useful for cross-device tracking before login)
+   */
+  setAnonymousId(anonymousId) {
+    this.userContext.anon_id = anonymousId;
+    this.log("Anonymous ID set", { anonymousId });
+  }
+  /**
+   * Set the event context (replaces existing context)
+   * Use for setting screen, surface, and other contextual information
+   */
+  setContext(context) {
+    this.eventContext = context;
+    this.log("Context set", context);
+  }
+  /**
+   * Update the event context (merges with existing context)
+   * Use for updating specific context properties without replacing the entire context
+   */
+  updateContext(context) {
+    this.eventContext = { ...this.eventContext, ...context };
+    this.log("Context updated", context);
+  }
+  /**
+   * Get current user context
+   */
+  getUserContext() {
+    return { ...this.userContext };
+  }
+  /**
+   * Get current event context
+   */
+  getContext() {
+    return { ...this.eventContext };
+  }
+  /**
+   * Reset user context (call on logout)
+   * Generates a new anonymous ID and clears user ID
+   */
+  reset() {
+    this.userContext = {
+      session_id: this.config.sessionId,
+      anon_id: uuid(),
+      user_id: void 0
+    };
+    this.eventContext = {};
+    this.log("Context reset");
+  }
   /**
    * Destroy client and cleanup
    */

package/dist/index.mjs

@@ -43,10 +43,11 @@ async function retry(fn, options) {
 // src/EventQueue.ts
 var STORAGE_KEY = "session_signals_queue";
 var EventQueue = class {
-  constructor(storage, sessionId) {
+  constructor(storage, getUserContext, getEventContext) {
     this.queue = [];
     this.storage = storage;
-    this.sessionId = sessionId;
+    this.getUserContext = getUserContext;
+    this.getEventContext = getEventContext;
   }
   /**
    * Initialize queue by loading persisted events
@@ -67,11 +68,17 @@ var EventQueue = class {
    * Add event to queue
    */
   async add(eventData) {
+    const userContext = this.getUserContext();
+    const eventContext = this.getEventContext();
+    const { type, ...payload } = eventData;
     const event = {
       event_id: uuid(),
       timestamp: getTimestamp(),
-      session_id: this.sessionId,
-      ...eventData
+      session_id: userContext.session_id,
+      type,
+      user: userContext,
+      context: eventContext,
+      ...payload
     };
     this.queue.push({
       event,
@@ -310,6 +317,7 @@ function collectMetadata(version) {
 
 // src/Signals.ts
 var VERSION = "0.1.0";
+var DEFAULT_ENDPOINT = "https://api.logg.com/events";
 var DEFAULT_BATCH_SIZE = 10;
 var DEFAULT_BATCH_INTERVAL = 5e3;
 var DEFAULT_MAX_RETRIES = 3;
@@ -322,21 +330,30 @@ var Signals = class {
     if (!config.apiKey) {
       throw new Error("Signals: apiKey is required");
     }
-    if (!config.endpoint) {
-      throw new Error("Signals: endpoint is required");
-    }
+    const sessionId = config.sessionId ?? uuid();
+    const anonymousId = config.anonymousId ?? uuid();
     this.config = {
       apiKey: config.apiKey,
-      endpoint: config.endpoint,
+      endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
       batchSize: config.batchSize ?? DEFAULT_BATCH_SIZE,
       batchInterval: config.batchInterval ?? DEFAULT_BATCH_INTERVAL,
       maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
       retryDelay: config.retryDelay ?? DEFAULT_RETRY_DELAY,
       debug: config.debug ?? false,
       storage: config.storage ?? getDefaultStorageAdapter(),
-      sessionId: config.sessionId ?? uuid()
+      sessionId
+    };
+    this.userContext = {
+      session_id: sessionId,
+      anon_id: anonymousId,
+      user_id: config.userId
     };
-    this.queue = new EventQueue(this.config.storage, this.config.sessionId);
+    this.eventContext = config.context ?? {};
+    this.queue = new EventQueue(
+      this.config.storage,
+      () => this.userContext,
+      () => this.eventContext
+    );
     this.init();
   }
   /**
@@ -460,6 +477,62 @@ var Signals = class {
   getQueueSize() {
     return this.queue.size();
   }
+  /**
+   * Identify the current user
+   * Call this after user login to associate events with a user ID
+   */
+  identify(userId) {
+    this.userContext.user_id = userId;
+    this.log("User identified", { userId });
+  }
+  /**
+   * Set anonymous ID (useful for cross-device tracking before login)
+   */
+  setAnonymousId(anonymousId) {
+    this.userContext.anon_id = anonymousId;
+    this.log("Anonymous ID set", { anonymousId });
+  }
+  /**
+   * Set the event context (replaces existing context)
+   * Use for setting screen, surface, and other contextual information
+   */
+  setContext(context) {
+    this.eventContext = context;
+    this.log("Context set", context);
+  }
+  /**
+   * Update the event context (merges with existing context)
+   * Use for updating specific context properties without replacing the entire context
+   */
+  updateContext(context) {
+    this.eventContext = { ...this.eventContext, ...context };
+    this.log("Context updated", context);
+  }
+  /**
+   * Get current user context
+   */
+  getUserContext() {
+    return { ...this.userContext };
+  }
+  /**
+   * Get current event context
+   */
+  getContext() {
+    return { ...this.eventContext };
+  }
+  /**
+   * Reset user context (call on logout)
+   * Generates a new anonymous ID and clears user ID
+   */
+  reset() {
+    this.userContext = {
+      session_id: this.config.sessionId,
+      anon_id: uuid(),
+      user_id: void 0
+    };
+    this.eventContext = {};
+    this.log("Context reset");
+  }
   /**
    * Destroy client and cleanup
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logg/signals",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Universal event tracking SDK for Logg Signals",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -36,15 +36,7 @@
   ],
   "author": "Logg",
   "license": "MIT",
-  "homepage": "https://github.com/synctree/session-app/tree/main/apps/signals-client#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/synctree/session-app.git",
-    "directory": "apps/signals-client"
-  },
-  "bugs": {
-    "url": "https://github.com/synctree/session-app/issues"
-  },
+  "homepage": "https://logg.com",
   "devDependencies": {
     "@types/node": "^20.10.0",
     "@typescript-eslint/eslint-plugin": "^6.13.0",