@logg/signals 0.1.5 → 0.3.0

package/README.md

@@ -2,7 +2,9 @@
 
 Universal event tracking SDK for Logg Signals. Track events from web, React Native, and Node.js applications.
 
-**Version 0.1.4** - Test release
+Also ships an embeddable on-device recommender as a separate entry point — see [On-Device Recommender](#on-device-recommender-loggsignalsreco).
+
+**Version 0.3.0**
 
 ## Features
 
@@ -12,7 +14,7 @@ Universal event tracking SDK for Logg Signals. Track events from web, React Nati
 ✅ **Persistent storage** - Uses localStorage, AsyncStorage, or memory as fallback  
 ✅ **Retry logic** - Exponential backoff for failed requests  
 ✅ **Auto metadata** - Automatically collects browser/device information  
-✅ **Small bundle** - <5KB gzipped  
+✅ **Small bundle** - <5KB gzipped (tracking entry; recommender is a separate opt-in entry)  
 
 ## Installation
 
@@ -168,12 +170,53 @@ const queueSize = signals.getQueueSize();
 
 ### `signals.destroy()`
 
-Destroy the client, flush remaining events, and cleanup resources.
+Destroy the client. **Drains the entire queue** (flushes batches until empty
+or sends start stalling) before shutting down. Always `await` this on
+process exit / app teardown — anything left in the in-memory queue after
+the Node process exits is lost.
 
 ```typescript
 await signals.destroy();
 ```
 
+### `signals.flushAll()`
+
+Drain the queue without destroying the client. Useful for backfill scripts
+that want a checkpoint before moving on. Returns the number of events that
+could not be sent (zero on full success).
+
+```typescript
+const stranded = await signals.flushAll();
+if (stranded > 0) {
+  console.warn(`${stranded} events failed to deliver`);
+}
+```
+
+### `signals.on('error', listener)` / `signals.off('error', listener)`
+
+Subscribe to delivery errors. `signals.event()` and `signals.flush()` never
+throw on backend failures, so this is how you observe them. The listener
+receives a `SignalsErrorEvent`:
+
+```typescript
+const off = signals.on('error', (e) => {
+  // e.type: 'send_failed' | 'send_retry' | 'destroy_pending'
+  // e.message:      human-readable description
+  // e.error:        the underlying Error
+  // e.batchId:      uuid of the failing/retrying batch (if applicable)
+  // e.eventCount:   number of events in the affected batch
+  // e.pendingCount: number of events still queued after the failure
+  // e.attempt:      1-indexed retry attempt (for 'send_retry' only)
+  console.error('[signals]', e.type, e.message, e.pendingCount, 'queued');
+});
+
+// later
+off();
+```
+
+If no `error` listener is attached, the SDK falls back to `console.warn`
+so failures are at least visible during development.
+
 ## Event Batching
 
 Events are automatically batched to reduce network requests:
@@ -414,6 +457,75 @@ function trackUserEvent(event: Omit<EventData, 'userId'>) {
 }
 ```
 
+## On-Device Recommender (`@logg/signals/reco`)
+
+A pure-TypeScript, zero-dependency recommendation engine that runs entirely on
+the client — ship it inside a React Native bundle, a web app, or a Node
+process. The backend hands the app a flat catalog (a few thousand items × a
+few feature columns); the device ranks it live as the user scrolls, dwells,
+taps, and favourites.
+
+It lives at its own entry point so tracking-only consumers don't pay for it:
+
+```typescript
+import { Recommender, DualBucketRecommender, SIGNALS } from '@logg/signals/reco';
+import type { BaseItem, Schema } from '@logg/signals/reco';
+```
+
+Two engines ship behind the same surface — pick at construction time:
+
+| Engine | Class | Best for |
+|---|---|---|
+| v1 | `Recommender` | Probabilistic exploration, smoother defaults |
+| v2 | `DualBucketRecommender` | Explicit liked/disliked separation, tighter exploit |
+
+The library is **domain-agnostic and generic over your item shape**. You bring
+an item type extending `BaseItem` (only `id` is required) and a `Schema<T>`
+that extracts categorical feature values from each item — the engine has no
+built-in vocabulary of brands, prices, or categories.
+
+```typescript
+import { Recommender, SIGNALS, logDecadeBucket, type BaseItem, type Schema } from '@logg/signals/reco';
+
+interface Listing extends BaseItem {
+  brand: string | null;
+  category: string | null;
+  price_cents: number | null;
+  popularity: number;
+}
+
+const schema = {
+  brand: { extract: (i: Listing) => i.brand, capacity: 4, weight: 0.4 },
+  category: { extract: (i: Listing) => i.category, capacity: 2, weight: 0.2 },
+  price_band: {
+    extract: (i: Listing) => (i.price_cents != null ? logDecadeBucket(i.price_cents / 100) : null),
+    weight: 0.4,
+  },
+} satisfies Schema<Listing>;
+
+const reco = new Recommender(catalog, {
+  schema,
+  popularity: (i) => i.popularity, // optional cold-start prior
+});
+
+reco.prime(usersCollection);          // pre-warm from a known collection
+reco.setOwned(['id-1', 'id-2']);      // excluded from results
+
+reco.engage(item, SIGNALS.view);      // saw and scrolled past
+reco.engage(item, SIGNALS.collect);   // added to collection
+reco.engage(item, -3);                // strong negative — caller picks any magnitude
+
+const { items, scores, diagnostics } = reco.recommend(20);
+```
+
+Methods shared by both engines: `prime()`, `engage()`, `recommend()`,
+`setOwned()`, `clearSeen()`, `reset()`, `seenCount()`. The dual engine adds
+`setSampleSize(k)` to tune explore vs. exploit.
+
+Advanced primitives (slot tables, interest state, bucket admission, the
+weighted sampler, and `seededRng` for deterministic tests) are exported from
+the same entry for callers building custom pipelines or CLIs on top.
+
 ## License
 
 MIT

package/dist/chunk-Y6FXYEAI.mjs

@@ -0,0 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __require
+};

package/dist/index.d.mts

@@ -71,20 +71,37 @@ interface QueuedEvent {
     event: Event;
     timestamp: number;
 }
+type SignalsErrorType = 'send_failed' | 'send_retry' | 'destroy_pending';
+interface SignalsErrorEvent {
+    type: SignalsErrorType;
+    message: string;
+    error?: Error;
+    batchId?: string;
+    eventCount?: number;
+    pendingCount?: number;
+    attempt?: number;
+}
+type SignalsErrorListener = (event: SignalsErrorEvent) => void;
 
 declare class Signals {
     private config;
     private queue;
     private flushTimer;
     private isDestroyed;
-    private isFlushing;
+    private flushingPromise;
+    private errorListeners;
     private userContext;
     private eventContext;
     constructor(config: SignalsConfig);
     private init;
     event(eventData: EventData): Promise<void>;
     flush(): Promise<void>;
+    flushAll(): Promise<number>;
+    private doFlushOnce;
     private sendBatch;
+    on(event: 'error', listener: SignalsErrorListener): () => void;
+    off(event: 'error', listener: SignalsErrorListener): void;
+    private emitError;
     private startFlushTimer;
     private stopFlushTimer;
     getSessionId(): string;
@@ -106,7 +123,7 @@ declare class EventQueue {
     private getUserContext;
     private getEventContext;
     constructor(storage: StorageAdapter, getUserContext: () => UserContext, getEventContext: () => EventContext);
-    init(): Promise<void>;
+    init(): Promise<number>;
     add(eventData: EventData): Promise<Event>;
     getAll(): Event[];
     getBatch(size: number): Event[];
@@ -143,4 +160,4 @@ declare class MemoryStorageAdapter implements StorageAdapter {
 
 declare function getDefaultStorageAdapter(): StorageAdapter;
 
-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 };
+export { AsyncStorageAdapter, type ClientMetadata, type Event, type EventBatch, type EventContext, type EventData, EventQueue, type EventTarget, LocalStorageAdapter, MemoryStorageAdapter, type QueuedEvent, Signals, type SignalsConfig, type SignalsErrorEvent, type SignalsErrorListener, type SignalsErrorType, type StorageAdapter, type UserContext, getDefaultStorageAdapter };

package/dist/index.d.ts

@@ -71,20 +71,37 @@ interface QueuedEvent {
     event: Event;
     timestamp: number;
 }
+type SignalsErrorType = 'send_failed' | 'send_retry' | 'destroy_pending';
+interface SignalsErrorEvent {
+    type: SignalsErrorType;
+    message: string;
+    error?: Error;
+    batchId?: string;
+    eventCount?: number;
+    pendingCount?: number;
+    attempt?: number;
+}
+type SignalsErrorListener = (event: SignalsErrorEvent) => void;
 
 declare class Signals {
     private config;
     private queue;
     private flushTimer;
     private isDestroyed;
-    private isFlushing;
+    private flushingPromise;
+    private errorListeners;
     private userContext;
     private eventContext;
     constructor(config: SignalsConfig);
     private init;
     event(eventData: EventData): Promise<void>;
     flush(): Promise<void>;
+    flushAll(): Promise<number>;
+    private doFlushOnce;
     private sendBatch;
+    on(event: 'error', listener: SignalsErrorListener): () => void;
+    off(event: 'error', listener: SignalsErrorListener): void;
+    private emitError;
     private startFlushTimer;
     private stopFlushTimer;
     getSessionId(): string;
@@ -106,7 +123,7 @@ declare class EventQueue {
     private getUserContext;
     private getEventContext;
     constructor(storage: StorageAdapter, getUserContext: () => UserContext, getEventContext: () => EventContext);
-    init(): Promise<void>;
+    init(): Promise<number>;
     add(eventData: EventData): Promise<Event>;
     getAll(): Event[];
     getBatch(size: number): Event[];
@@ -143,4 +160,4 @@ declare class MemoryStorageAdapter implements StorageAdapter {
 
 declare function getDefaultStorageAdapter(): StorageAdapter;
 
-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 };
+export { AsyncStorageAdapter, type ClientMetadata, type Event, type EventBatch, type EventContext, type EventData, EventQueue, type EventTarget, LocalStorageAdapter, MemoryStorageAdapter, type QueuedEvent, Signals, type SignalsConfig, type SignalsErrorEvent, type SignalsErrorListener, type SignalsErrorType, type StorageAdapter, type UserContext, getDefaultStorageAdapter };

package/dist/index.js

@@ -18,8 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var index_exports = {};
-__export(index_exports, {
+var src_exports = {};
+__export(src_exports, {
   AsyncStorageAdapter: () => AsyncStorageAdapter,
   EventQueue: () => EventQueue,
   LocalStorageAdapter: () => LocalStorageAdapter,
@@ -27,7 +27,7 @@ __export(index_exports, {
   Signals: () => Signals,
   getDefaultStorageAdapter: () => getDefaultStorageAdapter
 });
-module.exports = __toCommonJS(index_exports);
+module.exports = __toCommonJS(src_exports);
 
 // src/utils/helpers.ts
 function uuid() {
@@ -74,19 +74,23 @@ var EventQueue = class {
     this.getEventContext = getEventContext;
   }
   /**
-   * Initialize queue by loading persisted events
+   * Initialize queue by loading persisted events.
+   * Returns the number of events loaded from storage so callers can decide
+   * whether to force an immediate flush without racing against new events.
    */
   async init() {
     try {
       const stored = await this.storage.getItem(STORAGE_KEY);
       if (stored) {
         const parsed = JSON.parse(stored);
-        this.queue = Array.isArray(parsed) ? parsed : [];
+        const loaded = Array.isArray(parsed) ? parsed : [];
+        this.queue = loaded.concat(this.queue);
+        return loaded.length;
       }
     } catch (error) {
       console.warn("Failed to load persisted events:", error);
-      this.queue = [];
     }
+    return 0;
   }
   /**
    * Add event to queue
@@ -350,7 +354,8 @@ var Signals = class {
   constructor(config) {
     this.flushTimer = null;
     this.isDestroyed = false;
-    this.isFlushing = false;
+    this.flushingPromise = null;
+    this.errorListeners = /* @__PURE__ */ new Set();
     if (!config.apiKey) {
       throw new Error("Signals: apiKey is required");
     }
@@ -384,13 +389,13 @@ var Signals = class {
    * Initialize client
    */
   async init() {
-    await this.queue.init();
+    const persistedCount = await this.queue.init();
     this.log("Signals initialized", {
       sessionId: this.config.sessionId,
       queueSize: this.queue.size()
     });
     this.startFlushTimer();
-    if (!this.queue.isEmpty()) {
+    if (persistedCount > 0) {
       await this.flush();
     }
   }
@@ -408,18 +413,55 @@ var Signals = class {
     }
   }
   /**
-   * Manually flush events
+   * Send one batch of up to `batchSize` events. If a flush is already
+   * in-flight, callers join that one rather than starting a new request — this
+   * preserves at-most-one-in-flight delivery without silently no-op'ing.
+   *
+   * Failures do not throw. They emit a `send_failed` error event and leave
+   * events in the queue for the next flush.
    */
   async flush() {
-    if (this.isDestroyed || this.queue.isEmpty() || this.isFlushing) {
+    if (this.queue.isEmpty()) return;
+    if (this.flushingPromise) {
+      await this.flushingPromise.catch(() => {
+      });
       return;
     }
-    this.isFlushing = true;
-    const events = this.queue.getBatch(this.config.batchSize);
-    if (events.length === 0) {
-      this.isFlushing = false;
-      return;
+    this.flushingPromise = this.doFlushOnce();
+    try {
+      await this.flushingPromise;
+    } finally {
+      this.flushingPromise = null;
     }
+  }
+  /**
+   * Drain the entire queue. Loops `flush()` until the queue is empty or sends
+   * keep failing without making progress. Use at process shutdown or anywhere
+   * a backfill / migration script needs every queued event to land.
+   *
+   * Returns the number of events still queued (and thus unsent) after the
+   * drain attempt completes. Zero means full success.
+   */
+  async flushAll() {
+    let consecutiveStalls = 0;
+    while (!this.queue.isEmpty() && consecutiveStalls < 3) {
+      const before = this.queue.size();
+      await this.flush();
+      if (this.queue.size() === before) {
+        consecutiveStalls++;
+      } else {
+        consecutiveStalls = 0;
+      }
+    }
+    return this.queue.size();
+  }
+  /**
+   * Send a single batch. Internal — call via flush() so the in-flight gate
+   * is honored.
+   */
+  async doFlushOnce() {
+    const events = this.queue.getBatch(this.config.batchSize);
+    if (events.length === 0) return;
     this.log(`Flushing ${events.length} events`);
     const batch = {
       api_key: this.config.apiKey,
@@ -434,8 +476,14 @@ var Signals = class {
       this.log("Batch sent successfully");
     } catch (error) {
       this.log("Failed to send batch", error);
-    } finally {
-      this.isFlushing = false;
+      this.emitError({
+        type: "send_failed",
+        message: `Failed to send batch after ${this.config.maxRetries} retries`,
+        error: error instanceof Error ? error : new Error(String(error)),
+        batchId: batch.batch_id,
+        eventCount: events.length,
+        pendingCount: this.queue.size()
+      });
     }
   }
   /**
@@ -463,10 +511,56 @@ var Signals = class {
         initialDelay: this.config.retryDelay,
         onRetry: (attempt, error) => {
           this.log(`Retry attempt ${attempt}`, error);
+          this.emitError({
+            type: "send_retry",
+            message: `Retrying batch send (attempt ${attempt})`,
+            error,
+            batchId: batch.batch_id,
+            eventCount: batch.events.length,
+            attempt
+          });
         }
       }
     );
   }
+  /**
+   * Subscribe to error events from the SDK. Returns an unsubscribe function.
+   *
+   * @example
+   *   const off = signals.on('error', (e) => {
+   *     console.error('[signals]', e.type, e.message, e.error);
+   *   });
+   *   // ... later
+   *   off();
+   */
+  on(event, listener) {
+    if (event !== "error") {
+      throw new Error(`Signals.on: unknown event "${event}"`);
+    }
+    this.errorListeners.add(listener);
+    return () => this.errorListeners.delete(listener);
+  }
+  /** Remove a previously registered error listener. */
+  off(event, listener) {
+    if (event !== "error") return;
+    this.errorListeners.delete(listener);
+  }
+  emitError(payload) {
+    if (this.errorListeners.size === 0) {
+      console.warn(
+        `[Signals] ${payload.type}: ${payload.message}`,
+        payload.error ?? "",
+        payload.pendingCount !== void 0 ? `(${payload.pendingCount} events still queued)` : ""
+      );
+      return;
+    }
+    for (const listener of this.errorListeners) {
+      try {
+        listener(payload);
+      } catch {
+      }
+    }
+  }
   /**
    * Start periodic flush timer
    */
@@ -558,21 +652,38 @@ var Signals = class {
     this.log("Context reset");
   }
   /**
-   * Destroy client and cleanup
+   * Destroy the client and drain the queue.
+   *
+   * Awaits any in-flight flush, then keeps flushing batches until the queue
+   * is empty (or sends keep failing without progress). Only after that does
+   * the instance refuse new events. If anything remains undrainable, emits a
+   * `destroy_pending` error so callers can see the loss instead of having it
+   * silently swallowed at process exit.
    */
   async destroy() {
     if (this.isDestroyed) return;
     this.log("Destroying Signals instance");
-    this.isDestroyed = true;
     this.stopFlushTimer();
-    await this.flush();
+    if (this.flushingPromise) {
+      await this.flushingPromise.catch(() => {
+      });
+    }
+    const stranded = await this.flushAll();
+    this.isDestroyed = true;
+    if (stranded > 0) {
+      this.emitError({
+        type: "destroy_pending",
+        message: `Destroyed with ${stranded} unsent events \u2014 sends are failing`,
+        pendingCount: stranded
+      });
+    }
   }
   /**
    * Debug logging
    */
   log(message, data) {
     if (this.config.debug) {
-      console.log(`[LoggClient] ${message}`, data ?? "");
+      console.log(`[Signals] ${message}`, data ?? "");
     }
   }
 };