@queuedash/sdk 2.0.0 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @queuedash/sdk
 
-Official SDK for Queuedash - Real-time monitoring for BullMQ, Bull, Bee-Queue, and GroupMQ.
+Official SDK for Queuedash - queue monitoring for BullMQ, Bull, and Bee-Queue.
 
 ## Installation
 
@@ -14,7 +14,7 @@ yarn add @queuedash/sdk
 
 ## Quick Start
 
-The SDK auto-detects your queue library (BullMQ, Bull, Bee-Queue, or GroupMQ) - just use `attach()`:
+The SDK auto-detects your queue library (BullMQ 5+, Bull 4+, or Bee-Queue 1+) - just use `attach()`. First add the queue in Queuedash under the same name: jobs sent for a queue name Queuedash doesn't know are dropped.
 
 ### BullMQ
 
@@ -82,9 +82,9 @@ qd.attach(new Queue("notifications", { connection }));
 
 Get your API key from [Queuedash](https://queuedash.com):
 
-1. Navigate to your project
-2. Click "API Keys"
-3. Generate a new API key
+1. Open your project
+2. In the environment's API Keys section, click Add
+3. Copy the key (it's shown once)
 
 ```bash
 # Set in your environment
@@ -98,7 +98,8 @@ const qd = new Queuedash({
   // Required: Your API key from Queuedash
   apiKey: string,
 
-  // Optional: Custom API URL (default: https://api.queuedash.com)
+  // Optional: Where batches are sent (default: https://sync.queuedash.com
+  // when NODE_ENV is "production", otherwise http://localhost:4002)
   baseUrl?: string,
 
   // Optional: Batch size for syncing jobs (default: 50)
@@ -128,8 +129,9 @@ The SDK is production-ready with multiple layers of protection:
 **Retry Logic**
 
 - Automatic retries up to 5 times (configurable)
-- Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (capped)
-- Jobs preserved in local queue until successfully synced
+- Exponential backoff: 1s → 2s → 4s → 8s → 16s (capped at 30s)
+- Jobs that arrive during a backoff are held and sent with the retry
+- A batch that still fails after the last retry (~31s after the first failure, with defaults) is dropped and reported via `onError`
 
 **Circuit Breaker**
 
@@ -147,18 +149,18 @@ The SDK is production-ready with multiple layers of protection:
 
 - SIGTERM/SIGINT handlers flush pending jobs before exit
 - Call `await qd.stop()` to manually stop
-- No jobs lost during normal shutdown
+- Shutdown doesn't wait out a retry backoff: pending jobs get one final attempt, and if that fails they're reported via `onError` instead of retried
 
 **Request Safety**
 
 - 30-second timeout on all HTTP requests
-- Duplicate detection prevents same job syncing twice
+- Only the latest pending update for each job is sent
 - Network errors handled gracefully
 
 ## Features
 
-- **Auto-detection**: Works with BullMQ, Bull, Bee-Queue, and GroupMQ automatically
-- **Real-time sync**: Jobs are synced as events happen
+- **Auto-detection**: Works with BullMQ, Bull, and Bee-Queue automatically
+- **Event-driven**: A job is sent when the SDK hears an event for it (GroupMQ isn't supported)
 - **Smart batching**: Events are automatically batched for performance
 - **Auto-retry**: Failed syncs are automatically retried
 - **Zero config**: Works out of the box with sensible defaults

package/dist/client.d.ts

@@ -15,17 +15,19 @@ export declare class Queuedash {
     private jobQueue;
     private flushTimer?;
     private isFlushing;
+    private inFlightFlush?;
+    private retryTimer?;
+    private stopped;
     private retryCount;
     private circuitBreakerFailures;
     private circuitBreakerOpen;
     private circuitBreakerResetTimer?;
-    private syncingJobIds;
     private managedQueueEvents;
     private attachedQueues;
     constructor(options: QueuedashOptions);
     /**
      * Attach a queue or worker for monitoring.
-     * Auto-detects the queue library (BullMQ, Bull, Bee-Queue, GroupMQ).
+     * Auto-detects the queue library (BullMQ, Bull, Bee-Queue).
      *
      * @example
      * ```ts
@@ -60,16 +62,27 @@ export declare class Queuedash {
      * Queue a job for syncing (internal use)
      */
     syncJob(job: JobData): void;
+    private jobKey;
     /**
-     * Manually flush all pending jobs
+     * Manually flush all pending jobs. Unlike the periodic and batch-size
+     * flushes, this doesn't wait for a pending retry backoff.
      */
     flush(): Promise<void>;
+    private syncPendingJobs;
+    /**
+     * Put unsent jobs back at the front of the queue, unless a newer snapshot
+     * of the same job was queued while they were in flight
+     */
+    private requeue;
     private splitIntoChunks;
     private sendBatch;
     private openCircuitBreaker;
     private log;
+    private clearRetryTimer;
     /**
-     * Stop the client, close managed resources, and flush remaining jobs
+     * Stop the client, close managed resources, and flush remaining jobs.
+     * A pending retry backoff is skipped: remaining jobs get one final attempt,
+     * and if that fails they're reported via onError instead of retried.
      */
     stop(): Promise<void>;
     private startFlushTimer;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAgB,MAAM,SAAS,CAAC;AAiBlE,KAAK,iBAAiB,GAAG;IACvB,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,GAAG,CAAC;IAC9D,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAcF,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAyB;IAEzC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,UAAU,CAAC,CAAiB;IACpC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,sBAAsB,CAAK;IACnC,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,wBAAwB,CAAC,CAAiB;IAClD,OAAO,CAAC,aAAa,CAAqB;IAG1C,OAAO,CAAC,kBAAkB,CAA2B;IACrD,OAAO,CAAC,cAAc,CAAqB;gBAE/B,OAAO,EAAE,gBAAgB;IAsBrC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,IAAI;IAyBzE,OAAO,CAAC,UAAU;YAqCJ,YAAY;IAqE1B,OAAO,CAAC,kBAAkB;IAK1B,OAAO,CAAC,UAAU;IAiClB,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,oBAAoB;IAoB5B,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqChE;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAyB3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsF5B,OAAO,CAAC,eAAe;YAuBT,SAAS;IA+BvB,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,GAAG;IAQX;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,qBAAqB;CAiB9B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAgB,MAAM,SAAS,CAAC;AAiBlE,KAAK,iBAAiB,GAAG;IACvB,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,GAAG,CAAC;IAC9D,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAeF,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAyB;IAGzC,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,UAAU,CAAC,CAAiB;IACpC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAgB;IAGtC,OAAO,CAAC,UAAU,CAAC,CAAiB;IAEpC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,sBAAsB,CAAK;IACnC,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,wBAAwB,CAAC,CAAiB;IAGlD,OAAO,CAAC,kBAAkB,CAA2B;IACrD,OAAO,CAAC,cAAc,CAAqB;gBAE/B,OAAO,EAAE,gBAAgB;IAsBrC;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,IAAI;IAqCzE,OAAO,CAAC,UAAU;YAqCJ,YAAY;IAwE1B,OAAO,CAAC,kBAAkB;IAK1B,OAAO,CAAC,UAAU;IAsClB,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,oBAAoB;IAoB5B,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqChE;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAgC3B,OAAO,CAAC,MAAM;IAId;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAsBd,eAAe;IAoE7B;;;OAGG;IACH,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,eAAe;YAuBT,SAAS;IAmCvB,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,GAAG;IAQX,OAAO,CAAC,eAAe;IAOvB;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B3B,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,qBAAqB;CAiB9B"}

package/dist/client.js

@@ -37,12 +37,14 @@ exports.Queuedash = void 0;
 const MAX_PAYLOAD_SIZE = 4.5 * 1024 * 1024; // 4.5MB
 class Queuedash {
     constructor(options) {
-        this.jobQueue = [];
+        // Latest unsent snapshot per `${queueName}:${jobId}`, oldest first
+        this.jobQueue = new Map();
         this.isFlushing = false;
+        // Set by stop(): failed syncs are reported instead of retried
+        this.stopped = false;
         this.retryCount = 0;
         this.circuitBreakerFailures = 0;
         this.circuitBreakerOpen = false;
-        this.syncingJobIds = new Set();
         // Track attached resources for cleanup
         this.managedQueueEvents = [];
         this.attachedQueues = new Set();
@@ -66,7 +68,7 @@ class Queuedash {
     }
     /**
      * Attach a queue or worker for monitoring.
-     * Auto-detects the queue library (BullMQ, Bull, Bee-Queue, GroupMQ).
+     * Auto-detects the queue library (BullMQ, Bull, Bee-Queue).
      *
      * @example
      * ```ts
@@ -85,9 +87,22 @@ class Queuedash {
     attach(resource, options) {
         const type = this.detectType(resource);
         switch (type) {
-            case "bullmq-queue":
-                this.attachBullMQ(resource, options?.events);
+            case "bullmq-queue": {
+                const queue = resource;
+                // This can fail after attach() has returned, where the caller can't
+                // catch it, and an unhandled rejection would crash the process
+                this.attachBullMQ(queue, options?.events).catch((error) => {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    const errorMsg = `Failed to attach queue "${queue.name}"`;
+                    if (this.onError) {
+                        this.onError(new Error(`${errorMsg}: ${err.message}`));
+                    }
+                    else {
+                        console.error(`Queuedash: ${errorMsg}`, err);
+                    }
+                });
                 break;
+            }
             case "bullmq-worker":
                 this.attachBullMQWorker(resource);
                 break;
@@ -98,7 +113,7 @@ class Queuedash {
                 this.attachBee(resource);
                 break;
             default:
-                throw new Error("Queuedash: Unknown queue type. Supported: BullMQ Queue/Worker, Bull, Bee-Queue, GroupMQ");
+                throw new Error("Queuedash: Unknown queue type. Supported: BullMQ Queue, Bull, Bee-Queue");
         }
         return this;
     }
@@ -139,27 +154,31 @@ class Queuedash {
             events = existingEvents;
         }
         else {
-            try {
-                // Dynamic import to avoid requiring bullmq as a direct dependency
-                const { QueueEvents } = await Promise.resolve().then(() => __importStar(require("bullmq")));
-                const queueEvents = new QueueEvents(queueName, {
-                    connection: queue.opts?.connection,
-                    prefix: queue.redisPrefix,
-                });
-                this.managedQueueEvents.push(queueEvents);
-                events = queueEvents;
-            }
-            catch (e) {
-                throw new Error("Queuedash: Failed to create QueueEvents. Make sure bullmq is installed.");
-            }
+            // Dynamic import to avoid requiring bullmq as a direct dependency
+            const { QueueEvents } = await Promise.resolve().then(() => __importStar(require("bullmq"))).catch((error) => {
+                throw new Error(`Could not load bullmq (is it installed?): ${error.message}`);
+            });
+            // Throws if BullMQ rejects the connection, e.g. a shared ioredis instance
+            // without maxRetriesPerRequest: null. attach() reports the error as is
+            const queueEvents = new QueueEvents(queueName, {
+                connection: queue.opts?.connection,
+                // BullMQ keeps the key prefix in opts.prefix; without it QueueEvents
+                // listens on the default "bull" keys
+                prefix: queue.opts?.prefix ?? queue.redisPrefix,
+            });
+            this.managedQueueEvents.push(queueEvents);
+            events = queueEvents;
         }
         this.attachedQueues.add(`bullmq:${queueName}`);
         const syncJobById = (jobId, status) => {
-            queue.getJob(jobId).then((job) => {
+            queue
+                .getJob(jobId)
+                .then((job) => {
                 if (job) {
                     this.syncJob(this.extractBullMQJobData(job, queueName, status));
                 }
-            });
+            })
+                .catch((error) => this.log(`Failed to load job ${jobId}`, error));
         };
         events.on("waiting", ({ jobId }) => syncJobById(jobId, "waiting"));
         events.on("progress", ({ jobId }) => syncJobById(jobId, "active"));
@@ -185,14 +204,19 @@ class Queuedash {
             return;
         }
         this.attachedQueues.add(`bull:${queueName}`);
-        queue.on("global:completed", (job) => {
-            this.syncJob(this.extractBullJobData(job, queueName));
-        });
-        queue.on("global:failed", (job) => {
-            if (job) {
-                this.syncJob(this.extractBullJobData(job, queueName));
-            }
-        });
+        // Global events pass (jobId, result) rather than a Job, so load the job
+        const syncJobById = (jobId) => {
+            queue
+                .getJob(jobId)
+                .then((job) => {
+                if (job) {
+                    this.syncJob(this.extractBullJobData(job, queueName));
+                }
+            })
+                .catch((error) => this.log(`Failed to load job ${jobId}`, error));
+        };
+        queue.on("global:completed", (jobId) => syncJobById(jobId));
+        queue.on("global:failed", (jobId) => syncJobById(jobId));
         queue.on("active", (job) => {
             this.syncJob(this.extractBullJobData(job, queueName));
         });
@@ -285,9 +309,9 @@ class Queuedash {
      * Delete a job (soft delete in Queuedash)
      */
     async deleteJob(jobId, queueName) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
         try {
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
             const response = await fetch(`${this.apiUrl}/api/v1/jobs/${encodeURIComponent(jobId)}?queueName=${encodeURIComponent(queueName)}`, {
                 method: "DELETE",
                 headers: {
@@ -295,7 +319,6 @@ class Queuedash {
                 },
                 signal: controller.signal,
             });
-            clearTimeout(timeoutId);
             if (!response.ok) {
                 const errorText = await response.text();
                 throw new Error(`HTTP ${response.status}: ${errorText}`);
@@ -310,6 +333,9 @@ class Queuedash {
                 console.error(`Queuedash: Failed to delete job ${jobId}`, err);
             }
         }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     /**
      * Queue a job for syncing (internal use)
@@ -318,32 +344,55 @@ class Queuedash {
         if (this.circuitBreakerOpen) {
             return;
         }
-        const jobKey = `${job.queueName}:${job.jobId}`;
-        if (this.syncingJobIds.has(jobKey)) {
+        const jobKey = this.jobKey(job);
+        // A newer snapshot replaces the pending one and keeps its place in line.
+        // If the previous snapshot is already in flight, this one waits here for
+        // the next flush (the API upserts on queue + jobId).
+        if (this.jobQueue.has(jobKey)) {
+            this.jobQueue.set(jobKey, job);
             return;
         }
-        this.syncingJobIds.add(jobKey);
-        if (this.jobQueue.length >= this.maxQueueSize) {
-            const dropped = this.jobQueue.shift();
-            this.log(`Queue size limit reached (${this.maxQueueSize}), dropping oldest job: ${dropped?.jobId}`);
+        if (this.jobQueue.size >= this.maxQueueSize) {
+            const oldest = this.jobQueue.entries().next().value;
+            if (oldest) {
+                this.jobQueue.delete(oldest[0]);
+            }
+            this.log(`Queue size limit reached (${this.maxQueueSize}), dropping oldest job: ${oldest?.[1].jobId}`);
         }
-        this.jobQueue.push(job);
-        if (this.jobQueue.length >= this.batchSize) {
+        this.jobQueue.set(jobKey, job);
+        if (this.jobQueue.size >= this.batchSize && !this.retryTimer) {
             this.flush();
         }
     }
+    jobKey(job) {
+        return `${job.queueName}:${job.jobId}`;
+    }
     /**
-     * Manually flush all pending jobs
+     * Manually flush all pending jobs. Unlike the periodic and batch-size
+     * flushes, this doesn't wait for a pending retry backoff.
      */
     async flush() {
         if (this.isFlushing ||
-            this.jobQueue.length === 0 ||
+            this.jobQueue.size === 0 ||
             this.circuitBreakerOpen) {
             return;
         }
+        // This attempt replaces any scheduled retry; if it fails, the next retry
+        // is scheduled with a longer backoff
+        this.clearRetryTimer();
         this.isFlushing = true;
-        const jobsToSync = [...this.jobQueue];
-        this.jobQueue = [];
+        this.inFlightFlush = this.syncPendingJobs();
+        try {
+            await this.inFlightFlush;
+        }
+        finally {
+            this.isFlushing = false;
+            this.inFlightFlush = undefined;
+        }
+    }
+    async syncPendingJobs() {
+        const jobsToSync = [...this.jobQueue.values()];
+        this.jobQueue = new Map();
         try {
             // Check if payload is too large and split into chunks if needed
             const payload = JSON.stringify({ jobs: jobsToSync });
@@ -353,9 +402,6 @@ class Queuedash {
                     await this.sendBatch(chunk);
                     // Remove successfully sent jobs so they aren't re-queued on later chunk failure
                     jobsToSync.splice(0, chunk.length);
-                    chunk.forEach((job) => {
-                        this.syncingJobIds.delete(`${job.queueName}:${job.jobId}`);
-                    });
                 }
                 this.retryCount = 0;
                 this.circuitBreakerFailures = 0;
@@ -364,9 +410,6 @@ class Queuedash {
             await this.sendBatch(jobsToSync);
             this.retryCount = 0;
             this.circuitBreakerFailures = 0;
-            jobsToSync.forEach((job) => {
-                this.syncingJobIds.delete(`${job.queueName}:${job.jobId}`);
-            });
         }
         catch (error) {
             this.retryCount++;
@@ -375,22 +418,22 @@ class Queuedash {
             if (this.circuitBreakerFailures >= 10) {
                 this.openCircuitBreaker();
             }
-            if (this.retryCount <= this.maxRetries) {
-                this.jobQueue.unshift(...jobsToSync);
+            if (this.retryCount <= this.maxRetries && !this.stopped) {
+                this.requeue(jobsToSync);
                 const backoffMs = Math.min(1000 * Math.pow(2, this.retryCount - 1), 30000);
                 this.log(`Retry ${this.retryCount}/${this.maxRetries} after ${backoffMs}ms`, err);
-                setTimeout(() => {
-                    if (this.jobQueue.length > 0) {
+                this.retryTimer = setTimeout(() => {
+                    this.retryTimer = undefined;
+                    if (this.jobQueue.size > 0) {
                         this.flush();
                     }
                 }, backoffMs);
             }
             else {
                 this.retryCount = 0;
-                jobsToSync.forEach((job) => {
-                    this.syncingJobIds.delete(`${job.queueName}:${job.jobId}`);
-                });
-                const errorMsg = `Failed to sync ${jobsToSync.length} jobs after ${this.maxRetries} retries`;
+                const errorMsg = this.stopped
+                    ? `Failed to sync ${jobsToSync.length} jobs while stopping`
+                    : `Failed to sync ${jobsToSync.length} jobs after ${this.maxRetries} retries`;
                 if (this.onError) {
                     this.onError(new Error(`${errorMsg}: ${err.message}`));
                 }
@@ -399,9 +442,23 @@ class Queuedash {
                 }
             }
         }
-        finally {
-            this.isFlushing = false;
+    }
+    /**
+     * Put unsent jobs back at the front of the queue, unless a newer snapshot
+     * of the same job was queued while they were in flight
+     */
+    requeue(jobs) {
+        const requeued = new Map();
+        for (const job of jobs) {
+            const jobKey = this.jobKey(job);
+            if (!this.jobQueue.has(jobKey)) {
+                requeued.set(jobKey, job);
+            }
+        }
+        for (const [jobKey, job] of this.jobQueue) {
+            requeued.set(jobKey, job);
         }
+        this.jobQueue = requeued;
     }
     splitIntoChunks(jobs, maxSize) {
         const chunks = [];
@@ -424,24 +481,30 @@ class Queuedash {
     }
     async sendBatch(jobs) {
         const controller = new AbortController();
+        // Covers reading the body too: if a response stalled mid-body, this flush
+        // would never finish and no later flush could start
         const timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
-        const response = await fetch(`${this.apiUrl}/api/v1/jobs/sync`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${this.apiKey}`,
-            },
-            body: JSON.stringify({ jobs }),
-            signal: controller.signal,
-        });
-        clearTimeout(timeoutId);
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`HTTP ${response.status}: ${errorText}`);
+        try {
+            const response = await fetch(`${this.apiUrl}/api/v1/jobs/sync`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ jobs }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            const result = (await response.json());
+            if (!result.success && result.errors) {
+                console.warn("Queuedash: Some jobs failed to sync:", result.errors);
+            }
         }
-        const result = (await response.json());
-        if (!result.success && result.errors) {
-            console.warn("Queuedash: Some jobs failed to sync:", result.errors);
+        finally {
+            clearTimeout(timeoutId);
         }
     }
     openCircuitBreaker() {
@@ -466,8 +529,16 @@ class Queuedash {
             console.warn(`Queuedash: ${message}`);
         }
     }
+    clearRetryTimer() {
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = undefined;
+        }
+    }
     /**
-     * Stop the client, close managed resources, and flush remaining jobs
+     * Stop the client, close managed resources, and flush remaining jobs.
+     * A pending retry backoff is skipped: remaining jobs get one final attempt,
+     * and if that fails they're reported via onError instead of retried.
      */
     async stop() {
         if (this.flushTimer) {
@@ -485,11 +556,19 @@ class Queuedash {
                 // Ignore close errors
             }
         }
+        // flush() is a no-op while another flush is in flight, so let that one
+        // finish first; otherwise snapshots queued behind it would never be sent
+        while (this.inFlightFlush) {
+            await this.inFlightFlush.catch(() => { });
+        }
+        // Don't wait out a pending backoff (up to 30s) during shutdown
+        this.stopped = true;
+        this.clearRetryTimer();
         await this.flush();
     }
     startFlushTimer() {
         this.flushTimer = setInterval(() => {
-            if (this.jobQueue.length > 0) {
+            if (this.jobQueue.size > 0 && !this.retryTimer) {
                 this.flush();
             }
         }, this.flushInterval);
@@ -506,8 +585,8 @@ class Queuedash {
         process.once("SIGTERM", shutdown);
         process.once("SIGINT", shutdown);
         process.once("beforeExit", () => {
-            if (this.jobQueue.length > 0) {
-                console.warn(`Queuedash: Process exiting with ${this.jobQueue.length} unsync'd jobs`);
+            if (this.jobQueue.size > 0) {
+                console.warn(`Queuedash: Process exiting with ${this.jobQueue.size} unsync'd jobs`);
             }
         });
     }

package/dist/client.spec.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const events_1 = require("events");
+const bullmq_1 = require("bullmq");
 const client_1 = require("./client");
+// Stub QueueEvents so attaching a BullMQ queue doesn't connect to Redis
+jest.mock("bullmq", () => ({
+    QueueEvents: jest.fn().mockImplementation(() => ({
+        on: jest.fn(),
+        close: jest.fn().mockResolvedValue(undefined),
+    })),
+}));
+const MockQueueEvents = bullmq_1.QueueEvents;
 // Increase max listeners to avoid warnings from multiple SDK instances
 process.setMaxListeners(100);
 // Mock timers for testing
@@ -172,12 +182,9 @@ describe("Queuedash SDK", () => {
                 redisPrefix: "bull",
             };
             // BullMQ detection works - attach returns this for chaining
-            // The internal async call to create QueueEvents will fail (no bullmq installed)
-            // but detection itself should not throw "Unknown queue type"
+            // and doesn't throw "Unknown queue type"
             const result = sdk.attach(mockBullMQQueue);
             expect(result).toBe(sdk);
-            // The error will be thrown asynchronously but detection worked
-            // because it didn't throw "Unknown queue type" synchronously
         });
         it("should detect BullMQ Worker (has opts.connection, no getJob)", () => {
             const mockBullMQWorker = {
@@ -219,6 +226,89 @@ describe("Queuedash SDK", () => {
             expect(() => sdk.attach(123)).toThrow("Queuedash: Unknown queue type");
         });
     });
+    describe("BullMQ QueueEvents", () => {
+        beforeEach(() => {
+            MockQueueEvents.mockClear();
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key" });
+        });
+        // attach() creates QueueEvents after an async import of bullmq
+        const attachAndWait = async (queue) => {
+            sdk.attach(queue);
+            jest.useRealTimers();
+            await new Promise((resolve) => setImmediate(resolve));
+            jest.useFakeTimers();
+        };
+        it("should listen with the queue's custom prefix", async () => {
+            // Shaped like a BullMQ 5 Queue: the prefix lives in opts, no redisPrefix
+            await attachAndWait({
+                name: "prefixed-queue",
+                getJob: jest.fn(),
+                opts: { connection: {}, prefix: "myapp" },
+            });
+            expect(MockQueueEvents).toHaveBeenCalledTimes(1);
+            expect(MockQueueEvents).toHaveBeenCalledWith("prefixed-queue", expect.objectContaining({ prefix: "myapp" }));
+        });
+        it("should fall back to redisPrefix when opts.prefix is not set", async () => {
+            await attachAndWait({
+                name: "legacy-queue",
+                getJob: jest.fn(),
+                opts: { connection: {} },
+                redisPrefix: "legacy",
+            });
+            expect(MockQueueEvents).toHaveBeenCalledWith("legacy-queue", expect.objectContaining({ prefix: "legacy" }));
+        });
+        // e.g. the queue shares an ioredis instance with default options: fine
+        // for a Queue, but BullMQ rejects it for QueueEvents' blocking connection
+        const connectionError = () => new Error("BullMQ: Your redis options maxRetriesPerRequest must be null.");
+        it("should report a QueueEvents failure instead of crashing the process", async () => {
+            MockQueueEvents.mockImplementationOnce(() => {
+                throw connectionError();
+            });
+            // attach() has already returned when this fails; Jest fails this test
+            // if the rejection goes unhandled
+            await attachAndWait({
+                name: "shared-connection-queue",
+                getJob: jest.fn(),
+                opts: { connection: {} },
+            });
+            expect(consoleErrorSpy).toHaveBeenCalledWith('Queuedash: Failed to attach queue "shared-connection-queue"', connectionError());
+        });
+        it("should pass a QueueEvents failure to onError", async () => {
+            const onError = jest.fn();
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key", onError });
+            MockQueueEvents.mockImplementationOnce(() => {
+                throw connectionError();
+            });
+            await attachAndWait({
+                name: "shared-connection-queue",
+                getJob: jest.fn(),
+                opts: { connection: {} },
+            });
+            expect(onError).toHaveBeenCalledTimes(1);
+            expect(onError.mock.calls[0][0].message).toBe('Failed to attach queue "shared-connection-queue": ' +
+                connectionError().message);
+        });
+        it("should warn instead of leaving an unhandled rejection when getJob fails", async () => {
+            // e.g. the app closed its Queue before calling qd.stop()
+            const queue = {
+                name: "closed-queue",
+                opts: { connection: {} },
+                getJob: jest.fn().mockRejectedValue(new Error("Connection is closed.")),
+            };
+            // Shaped like QueueEvents: an EventEmitter with close()
+            const events = Object.assign(new events_1.EventEmitter(), {
+                close: async () => { },
+            });
+            sdk.attach(queue, { events });
+            events.emit("completed", { jobId: "1" });
+            // Let the rejection settle; Jest fails this test if it goes unhandled
+            jest.useRealTimers();
+            await new Promise((resolve) => setImmediate(resolve));
+            jest.useFakeTimers();
+            expect(queue.getJob).toHaveBeenCalledWith("1");
+            expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining("Failed to load job 1"));
+        });
+    });
     describe("attach() Method", () => {
         beforeEach(() => {
             sdk = new client_1.Queuedash({ apiKey: "test-api-key" });
@@ -340,6 +430,98 @@ describe("Queuedash SDK", () => {
             expect(mockFetch).not.toHaveBeenCalled();
         });
     });
+    describe("Snapshot Updates", () => {
+        const okResponse = {
+            ok: true,
+            json: () => Promise.resolve({ success: true, synced: 1 }),
+        };
+        // Keeps the next sync request in flight until the test settles it
+        const holdNextFetch = () => {
+            const request = {
+                resolve: (_response) => { },
+                reject: (_error) => { },
+            };
+            mockFetch.mockImplementationOnce(() => new Promise((resolve, reject) => {
+                request.resolve = resolve;
+                request.reject = reject;
+            }));
+            return request;
+        };
+        const sentJobs = (call) => JSON.parse(mockFetch.mock.calls[call][1].body).jobs;
+        const snapshot = (jobId, status) => ({
+            ...createMockJobData(jobId),
+            status,
+        });
+        beforeEach(() => {
+            mockFetch.mockResolvedValue(okResponse);
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key" });
+        });
+        it("should replace a pending snapshot with a newer one", () => {
+            sdk.syncJob(snapshot("job-1", "waiting"));
+            sdk.syncJob(snapshot("job-1", "completed"));
+            jest.advanceTimersByTime(100);
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(sentJobs(0)).toEqual([
+                expect.objectContaining({ jobId: "job-1", status: "completed" }),
+            ]);
+        });
+        it("should send a snapshot that arrives while the job's batch is in flight", async () => {
+            const request = holdNextFetch();
+            sdk.syncJob(snapshot("job-1", "waiting"));
+            const inFlight = sdk.flush();
+            sdk.syncJob(snapshot("job-1", "completed"));
+            request.resolve(okResponse);
+            await inFlight;
+            jest.advanceTimersByTime(100);
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            expect(sentJobs(1)).toEqual([
+                expect.objectContaining({ jobId: "job-1", status: "completed" }),
+            ]);
+        });
+        it("should not requeue a failed snapshot over a newer one", async () => {
+            const request = holdNextFetch();
+            sdk.syncJob(snapshot("job-1", "waiting"));
+            const inFlight = sdk.flush();
+            sdk.syncJob(snapshot("job-1", "completed"));
+            request.reject(new Error("Network error"));
+            await inFlight;
+            // Retried once the 1s backoff elapses
+            jest.advanceTimersByTime(1000);
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            expect(sentJobs(1)).toEqual([
+                expect.objectContaining({ jobId: "job-1", status: "completed" }),
+            ]);
+        });
+        it("should send snapshots queued behind an in-flight flush on stop()", async () => {
+            const request = holdNextFetch();
+            sdk.syncJob(snapshot("job-1", "waiting"));
+            const inFlight = sdk.flush();
+            sdk.syncJob(snapshot("job-1", "completed"));
+            const stopped = sdk.stop();
+            request.resolve(okResponse);
+            await Promise.all([inFlight, stopped]);
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            expect(sentJobs(1)).toEqual([
+                expect.objectContaining({ jobId: "job-1", status: "completed" }),
+            ]);
+        });
+        it("should accept new snapshots for a job dropped by maxQueueSize", () => {
+            sdk = new client_1.Queuedash({
+                apiKey: "test-api-key",
+                batchSize: 100,
+                maxQueueSize: 2,
+            });
+            sdk.syncJob(snapshot("job-1", "waiting"));
+            sdk.syncJob(snapshot("job-2", "waiting"));
+            sdk.syncJob(snapshot("job-3", "waiting")); // drops job-1
+            sdk.syncJob(snapshot("job-1", "completed")); // drops job-2
+            jest.advanceTimersByTime(100);
+            expect(sentJobs(0)).toEqual([
+                expect.objectContaining({ jobId: "job-3", status: "waiting" }),
+                expect.objectContaining({ jobId: "job-1", status: "completed" }),
+            ]);
+        });
+    });
     describe("flush() Method", () => {
         beforeEach(() => {
             mockFetch.mockResolvedValue({
@@ -478,6 +660,132 @@ describe("Queuedash SDK", () => {
             expect(onError).toHaveBeenCalled();
             expect(onError.mock.calls[0][0].message).toContain("401");
         });
+        it("should clear the request timeout when fetch rejects", async () => {
+            mockFetch.mockRejectedValue(new Error("Network error"));
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key", maxRetries: 0 });
+            sdk.syncJob(createMockJobData("job-1"));
+            const timerCount = jest.getTimerCount();
+            await sdk.flush();
+            // A leftover abort timer would keep the process alive for 30s
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(jest.getTimerCount()).toBe(timerCount);
+        });
+        it("should time out a response body that stalls", async () => {
+            mockFetch.mockImplementation((_url, { signal }) => Promise.resolve(stalledResponse(signal, { ok: true })));
+            const onError = jest.fn();
+            sdk = new client_1.Queuedash({
+                apiKey: "test-api-key",
+                maxRetries: 0,
+                requestTimeout: 5000,
+                onError,
+            });
+            sdk.syncJob(createMockJobData("job-1"));
+            sdk.flush();
+            await jest.advanceTimersByTimeAsync(4999);
+            expect(onError).not.toHaveBeenCalled();
+            // Fails at requestTimeout instead of blocking every later flush
+            await jest.advanceTimersByTimeAsync(1);
+            expect(onError).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe("Retry Backoff", () => {
+        const okResponse = {
+            ok: true,
+            json: () => Promise.resolve({ success: true, synced: 1 }),
+        };
+        let onError;
+        beforeEach(() => {
+            onError = jest.fn();
+            mockFetch.mockRejectedValue(new Error("Network error"));
+        });
+        it("should not retry before each backoff elapses", async () => {
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key", onError });
+            sdk.syncJob(createMockJobData("job-1"));
+            await jest.advanceTimersByTimeAsync(100); // periodic flush: attempt 1
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            // The periodic flush keeps ticking every 100ms throughout
+            for (const backoffMs of [1000, 2000, 4000, 8000, 16000]) {
+                const attempts = mockFetch.mock.calls.length;
+                await jest.advanceTimersByTimeAsync(backoffMs - 1);
+                expect(mockFetch).toHaveBeenCalledTimes(attempts);
+                await jest.advanceTimersByTimeAsync(1);
+                expect(mockFetch).toHaveBeenCalledTimes(attempts + 1);
+            }
+            // The sixth failed attempt uses up maxRetries (5)
+            expect(onError).toHaveBeenCalledTimes(1);
+            expect(onError.mock.calls[0][0].message).toContain("Failed to sync 1 jobs after 5 retries");
+        });
+        it("should not flush a full batch before the backoff elapses", async () => {
+            // No periodic flush within the test, only batch-size flushes
+            sdk = new client_1.Queuedash({
+                apiKey: "test-api-key",
+                batchSize: 2,
+                flushInterval: 60000,
+                onError,
+            });
+            sdk.syncJob(createMockJobData("job-1"));
+            sdk.syncJob(createMockJobData("job-2"));
+            await jest.advanceTimersByTimeAsync(0); // attempt 1 fails
+            sdk.syncJob(createMockJobData("job-3"));
+            sdk.syncJob(createMockJobData("job-4"));
+            await jest.advanceTimersByTimeAsync(999);
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            // The retry also sends the jobs held back during the backoff
+            mockFetch.mockResolvedValue(okResponse);
+            await jest.advanceTimersByTimeAsync(1);
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            expect(JSON.parse(mockFetch.mock.calls[1][1].body).jobs).toHaveLength(4);
+        });
+        it("should not wait for the backoff on an explicit flush()", async () => {
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key", onError });
+            sdk.syncJob(createMockJobData("job-1"));
+            await jest.advanceTimersByTimeAsync(100); // attempt 1 fails
+            mockFetch.mockResolvedValue(okResponse);
+            await sdk.flush();
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            // The success cancels the backoff, so periodic flushes resume
+            sdk.syncJob(createMockJobData("job-2"));
+            await jest.advanceTimersByTimeAsync(100);
+            expect(mockFetch).toHaveBeenCalledTimes(3);
+        });
+        it("should resume flushing held jobs after the circuit breaker resets", async () => {
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key", maxRetries: 20, onError });
+            sdk.syncJob(createMockJobData("job-1"));
+            // 10 consecutive failures, 1s, 2s, 4s, 8s, 16s, then 30s (capped) apart
+            await jest.advanceTimersByTimeAsync(100 + 1000 + 2000 + 4000 + 8000 + 16000 + 30000 * 4);
+            expect(mockFetch).toHaveBeenCalledTimes(10);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining("Circuit breaker opened"));
+            // Nothing is sent while it's open, including the retry due 30s later
+            await jest.advanceTimersByTimeAsync(59999);
+            expect(mockFetch).toHaveBeenCalledTimes(10);
+            // It resets after 60s and the next periodic flush sends the held job
+            mockFetch.mockResolvedValue(okResponse);
+            await jest.advanceTimersByTimeAsync(101);
+            expect(mockFetch).toHaveBeenCalledTimes(11);
+        });
+        it("should make one final attempt on stop() instead of waiting out the backoff", async () => {
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key", onError });
+            sdk.syncJob(createMockJobData("job-1"));
+            await jest.advanceTimersByTimeAsync(100); // attempt 1 fails
+            mockFetch.mockResolvedValue(okResponse);
+            await sdk.stop();
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            expect(JSON.parse(mockFetch.mock.calls[1][1].body).jobs).toEqual([
+                expect.objectContaining({ jobId: "job-1" }),
+            ]);
+            expect(onError).not.toHaveBeenCalled();
+        });
+        it("should report instead of retrying when the final attempt on stop() fails", async () => {
+            sdk = new client_1.Queuedash({ apiKey: "test-api-key", onError });
+            sdk.syncJob(createMockJobData("job-1"));
+            await jest.advanceTimersByTimeAsync(100); // attempt 1 fails
+            await sdk.stop();
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            expect(onError).toHaveBeenCalledTimes(1);
+            expect(onError.mock.calls[0][0].message).toContain("Failed to sync 1 jobs while stopping");
+            await jest.advanceTimersByTimeAsync(60000);
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+        });
     });
     describe("deleteJob() Method", () => {
         beforeEach(() => {
@@ -536,6 +844,27 @@ describe("Queuedash SDK", () => {
             jest.useFakeTimers();
             expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining("Failed to delete job"), expect.any(Error));
         });
+        it("should clear the request timeout when fetch rejects", async () => {
+            mockFetch.mockRejectedValue(new Error("Network error"));
+            const timerCount = jest.getTimerCount();
+            await sdk.deleteJob("job-123", "test-queue");
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(jest.getTimerCount()).toBe(timerCount);
+        });
+        it("should time out an error response body that stalls", async () => {
+            mockFetch.mockImplementation((_url, { signal }) => Promise.resolve(stalledResponse(signal, { ok: false, status: 500 })));
+            const onError = jest.fn();
+            sdk = new client_1.Queuedash({
+                apiKey: "test-api-key",
+                requestTimeout: 5000,
+                onError,
+            });
+            sdk.deleteJob("job-123", "test-queue");
+            await jest.advanceTimersByTimeAsync(4999);
+            expect(onError).not.toHaveBeenCalled();
+            await jest.advanceTimersByTimeAsync(1);
+            expect(onError).toHaveBeenCalledTimes(1);
+        });
     });
     describe("Circuit Breaker", () => {
         beforeEach(() => {
@@ -669,6 +998,38 @@ describe("Queuedash SDK", () => {
             expect(body.jobs[0].data).toEqual({ foo: "bar" });
             expect(body.jobs[0].progress).toBe(50);
         });
+        it("should load the job for Bull global events, which pass a job id", async () => {
+            const mockBullQueue = {
+                name: "test-queue",
+                clients: [{}],
+                on: jest.fn(),
+                getJob: jest.fn((jobId) => Promise.resolve({
+                    id: jobId,
+                    name: "test-job",
+                    data: { foo: "bar" },
+                    opts: {},
+                    timestamp: Date.now(),
+                    finishedOn: Date.now(),
+                    progress: () => 100,
+                })),
+            };
+            sdk.attach(mockBullQueue);
+            const handler = (event) => mockBullQueue.on.mock.calls.find((call) => call[0] === event)[1];
+            // Bull emits global events as (jobId, result, previousState)
+            handler("global:completed")("123", '"done"', "active");
+            handler("global:failed")("456", "boom", "active");
+            await Promise.all(mockBullQueue.getJob.mock.results.map((r) => r.value));
+            jest.useRealTimers();
+            await sdk.flush();
+            jest.useFakeTimers();
+            expect(mockBullQueue.getJob).toHaveBeenCalledWith("123");
+            expect(mockBullQueue.getJob).toHaveBeenCalledWith("456");
+            const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+            expect(body.jobs).toEqual([
+                expect.objectContaining({ jobId: "123", data: { foo: "bar" } }),
+                expect.objectContaining({ jobId: "456", data: { foo: "bar" } }),
+            ]);
+        });
         it("should handle Bee-Queue succeeded event and set finishedAt", () => {
             const mockBeeQueue = {
                 name: "test-queue",
@@ -807,3 +1168,11 @@ function createMockJobData(jobId, queueName = "test-queue") {
         finishedAt: null,
     };
 }
+// Mock response whose headers arrived but whose body never finishes, unless
+// the request is aborted
+function stalledResponse(signal, fields) {
+    const readBody = () => new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(new Error("This operation was aborted")));
+    });
+    return { ...fields, json: readBody, text: readBody };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@queuedash/sdk",
-  "version": "2.0.0",
-  "description": "Queuedash SDK for real-time queue monitoring",
+  "version": "2.0.1",
+  "description": "Queuedash SDK for BullMQ, Bull, and Bee-Queue monitoring",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -13,7 +13,6 @@
     "bullmq",
     "bull",
     "bee-queue",
-    "groupmq",
     "monitoring",
     "dashboard"
   ],