@logg/signals 0.1.4 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Universal event tracking SDK for Logg Signals. Track events from web, React Native, and Node.js applications.
 
-**Version 0.1.4** - Test release
+**Version 0.2.0**
 
 ## Features
 
@@ -168,12 +168,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:

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

@@ -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");
     }
@@ -358,7 +363,7 @@ var Signals = class {
     const anonymousId = config.anonymousId ?? uuid();
     this.config = {
       apiKey: config.apiKey,
-      endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
       batchSize: config.batchSize ?? DEFAULT_BATCH_SIZE,
       batchInterval: config.batchInterval ?? DEFAULT_BATCH_INTERVAL,
       maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
@@ -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 ?? "");
     }
   }
 };

package/dist/index.mjs

@@ -50,19 +50,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
@@ -326,7 +330,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");
     }
@@ -334,7 +339,7 @@ var Signals = class {
     const anonymousId = config.anonymousId ?? uuid();
     this.config = {
       apiKey: config.apiKey,
-      endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
       batchSize: config.batchSize ?? DEFAULT_BATCH_SIZE,
       batchInterval: config.batchInterval ?? DEFAULT_BATCH_INTERVAL,
       maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
@@ -360,13 +365,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();
     }
   }
@@ -384,18 +389,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,
@@ -410,8 +452,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()
+      });
     }
   }
   /**
@@ -439,10 +487,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
    */
@@ -534,21 +628,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 ?? "");
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logg/signals",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Universal event tracking SDK for Logg Signals",
   "main": "dist/index.js",
   "module": "dist/index.mjs",