bridgex 2.0.0 → 2.1.0

package/src/SMSClient.ts

@@ -13,6 +13,7 @@ import type {
   SendParams,
   SendObjectParams,
   BatchResult,
+  FailedItem,
 } from "./types.js";
 
 export interface SMSClientOptions {
@@ -88,14 +89,13 @@ export default class SMSClient {
     options.plugins?.forEach((p) => this.plugins.use(p));
   }
 
-  /** Attach a plugin at any time. */
   use(plugin: Plugin): this {
     this.plugins.use(plugin);
     return this;
   }
 
   // ─────────────────────────────────────────────────────────────────────────
-  // Core internal send — all public methods funnel through here
+  // Core internal send
   // ─────────────────────────────────────────────────────────────────────────
 
   private async _send(
@@ -134,10 +134,7 @@ export default class SMSClient {
   // Public API
   // ─────────────────────────────────────────────────────────────────────────
 
-  /**
-   * Send a single SMS message.
-   * Returns a Result — never throws.
-   */
+  /** Send a single SMS. Returns a Result — never throws. */
   async send(params: SendParams & { _meta?: any }): Promise<Result<any>> {
     const { to, template, variables = {} } = params;
     const tags = params._meta?.tags ?? [];
@@ -154,7 +151,14 @@ export default class SMSClient {
 
   /**
    * Send the same template to many recipients.
-   * Each recipient can supply its own variables; shared variables are the fallback.
+   *
+   * Detailed batch report:
+   * - succeeded[]: index, to, data (the server's response JSON)
+   * - failed[]:    index, to, error (typed ErrorLog), originalParams (full params preserved)
+   * - hitMaxLimit: true if the server signalled quota exhausted — stops sending immediately
+   *
+   * Failed recipients' originalParams can be passed straight to queue.enqueue()
+   * so nothing is lost.
    */
   async sendMany(
     recipients: Array<{ to: string; variables?: Record<string, unknown> }>,
@@ -167,16 +171,22 @@ export default class SMSClient {
       total: recipients.length,
       successCount: 0,
       failureCount: 0,
+      hitMaxLimit: false,
     };
 
     const chunks = chunkArray(recipients, this.batchSize);
 
-    for (const chunk of chunks) {
+    outer: for (const chunk of chunks) {
+      // Shared flag: if one worker hits MAX_LIMIT, all workers stop
+      let maxLimitHit = false;
+
       const queue = [...chunk.entries()];
 
       await Promise.all(
         new Array(this.concurrency).fill(null).map(async () => {
           while (queue.length > 0) {
+            if (maxLimitHit) break;
+
             const entry = queue.shift();
             if (!entry) break;
 
@@ -184,11 +194,13 @@ export default class SMSClient {
             const globalIndex =
               chunks.indexOf(chunk) * this.batchSize + chunkIndex;
             const variables = { ...sharedVariables, ...recipient.variables };
-            const res = await this.send({
+            const originalParams: SendParams = {
               to: recipient.to,
               template,
               variables,
-            });
+            };
+
+            const res = await this.send({ ...originalParams });
 
             if (res.ok) {
               result.succeeded.push({
@@ -198,16 +210,56 @@ export default class SMSClient {
               });
               result.successCount++;
             } else {
-              result.failed.push({
+              const failedItem: FailedItem = {
                 index: globalIndex,
                 to: recipient.to,
                 error: res.error,
-              });
+                originalParams,
+              };
+              result.failed.push(failedItem);
               result.failureCount++;
+
+              // Quota exhausted — stop sending the rest immediately
+              if (res.error.code === "MAX_LIMIT_ERROR") {
+                maxLimitHit = true;
+                result.hitMaxLimit = true;
+              }
             }
           }
         }),
       );
+
+      // Also break the outer chunk loop if quota hit
+      if (result.hitMaxLimit) {
+        // Mark remaining recipients as failed with the quota error — data is NOT lost
+        const processedIndices = new Set([
+          ...result.succeeded.map((s) => s.index),
+          ...result.failed.map((f) => f.index),
+        ]);
+
+        for (let i = 0; i < recipients.length; i++) {
+          if (!processedIndices.has(i)) {
+            const r = recipients[i];
+            const variables = { ...sharedVariables, ...r.variables };
+            result.failed.push({
+              index: i,
+              to: r.to,
+              error: {
+                name: "MaxLimitError",
+                message:
+                  "Skipped — server quota was exhausted before this recipient",
+                code: "MAX_LIMIT_ERROR",
+                isClientError: false,
+                isServerError: true,
+                timestamp: new Date().toISOString(),
+              },
+              originalParams: { to: r.to, template, variables },
+            });
+            result.failureCount++;
+          }
+        }
+        break outer;
+      }
     }
 
     return result;
@@ -234,9 +286,7 @@ export default class SMSClient {
     }
   }
 
-  /**
-   * Send object-derived messages to many recipients.
-   */
+  /** Send object-derived messages to many recipients. */
   async sendObjectMany<T extends Record<string, unknown>>(
     items: Array<SendObjectParams<T> & { _meta?: any }>,
   ): Promise<BatchResult<any>> {
@@ -246,16 +296,20 @@ export default class SMSClient {
       total: items.length,
       successCount: 0,
       failureCount: 0,
+      hitMaxLimit: false,
     };
 
     const chunks = chunkArray(items, this.batchSize);
 
-    for (const chunk of chunks) {
+    outer: for (const chunk of chunks) {
+      let maxLimitHit = false;
       const queue = [...chunk.entries()];
 
       await Promise.all(
         new Array(this.concurrency).fill(null).map(async () => {
           while (queue.length > 0) {
+            if (maxLimitHit) break;
+
             const entry = queue.shift();
             if (!entry) break;
 
@@ -272,33 +326,43 @@ export default class SMSClient {
               });
               result.successCount++;
             } else {
+              // For object sends, preserve what we can
+              const originalParams: SendParams = {
+                to: item.to,
+                template: item.template ?? JSON.stringify(item.object),
+                variables: {},
+              };
               result.failed.push({
                 index: globalIndex,
                 to: item.to,
                 error: res.error,
+                originalParams,
               });
               result.failureCount++;
+
+              if (res.error.code === "MAX_LIMIT_ERROR") {
+                maxLimitHit = true;
+                result.hitMaxLimit = true;
+              }
             }
           }
         }),
       );
+
+      if (result.hitMaxLimit) break outer;
     }
 
     return result;
   }
 
-  /** Current circuit breaker state. */
   get circuitState() {
     return this.circuit.currentState;
   }
 
-  /** Manually reset the circuit breaker (e.g. after fixing a downstream issue). */
   resetCircuit() {
     this.circuit.reset();
   }
 
-  // ─────────────────────────────────────────────────────────────────────────
-
   private validateOptions(options: SMSClientOptions): void {
     const { baseUrl, apiKey, projectKey } = options;
     if (!baseUrl) throw new ValidationError("baseUrl is required");

package/src/SMSQueue.ts

@@ -1,6 +1,6 @@
 import type SMSClient from "./SMSClient.js";
 import type PluginManager from "./PluginManager.js";
-import type { SendParams, Result } from "./types.js";
+import type { SendParams, Result, ErrorLog } from "./types.js";
 import type { SendMeta } from "./SendConfig.js";
 
 type Priority = "low" | "normal" | "high";
@@ -10,62 +10,96 @@ const PRIORITY_WEIGHT: Record<Priority, number> = {
   low: 1,
 };
 
+/** Error codes that are permanent — re-queuing won't help. */
+const NON_RETRYABLE_CODES = new Set([
+  "VALIDATION_ERROR",
+  "TEMPLATE_ERROR",
+  "MAX_LIMIT_ERROR", // quota exhausted — no point retrying until quota resets
+]);
+
 export interface QueueJob {
   id: string;
   params: SendParams;
   meta: SendMeta["_meta"];
-  scheduledAt: number; // epoch ms — 0 = immediately
+  scheduledAt: number; // epoch ms — 0 means "run ASAP"
   enqueuedAt: number;
+  /** How many times this job has been attempted (including the current one) */
   attempts: number;
+  /** Max retry attempts before giving up (default: 3) */
+  maxAttempts: number;
+  /** Full history of every attempt result for this job */
+  history: AttemptRecord[];
+}
+
+export interface AttemptRecord {
+  attempt: number;
+  timestamp: string; // ISO 8601
+  ok: boolean;
+  durationMs: number;
+  error?: ErrorLog;
+  data?: unknown;
 }
 
 export interface QueueOptions {
-  /** Max concurrent workers processing the queue (default: 3) */
+  /** Max concurrent workers (default: 3) */
   concurrency?: number;
-  /** How often (ms) the queue polls for scheduled jobs (default: 1000) */
+  /** Poll interval ms (default: 1000) */
   pollInterval?: number;
-  /** Whether to start processing automatically on first enqueue (default: true) */
+  /** Auto-start on first enqueue (default: true) */
   autoStart?: boolean;
+  /** Default max retry attempts per job (default: 3) */
+  maxAttempts?: number;
+  /** Base retry delay ms for failed jobs (default: 2000) */
+  retryDelay?: number;
 }
 
 export interface QueueStats {
   pending: number;
   running: number;
   completed: number;
+  failed: number;
   dropped: number;
 }
 
+export interface FailedJob {
+  job: QueueJob;
+  finalError: ErrorLog;
+  /** All attempt records so nothing is lost */
+  history: AttemptRecord[];
+}
+
 /**
- * SMSQueue — an in-process job queue for fire-and-forget or scheduled SMS.
+ * SMSQueue — priority job queue with full retry, failure history, and data preservation.
  *
- * Features:
- * - Priority lanes (high / normal / low)
- * - Deduplication via dedupKey
- * - TTL — drops stale jobs before sending
- * - Scheduled sends (send at a future timestamp)
- * - Concurrency-limited workers
- * - Plugin hooks (onDrop, onSuccess, onError, onRetry)
+ * When a job fails:
+ *   - If the error is retryable (network, server, rate-limit) → re-queued with backoff
+ *   - If the error is permanent (validation, quota exhausted) → moved to dead-letter list
+ *   - The full attempt history is kept on every job so no data is ever silently lost
  *
  * @example
- * const queue = new SMSQueue(client, { concurrency: 5 });
+ * const queue = new SMSQueue(client, { concurrency: 5, maxAttempts: 4 });
  * queue.start();
+ * queue.on("failed", ({ job, finalError }) => saveToDb(job, finalError));
  *
- * const cfg = SendConfig.otp().dedupKey(`otp:${userId}`);
- * await queue.enqueue(cfg.for(phone, { code }));
- *
- * // Schedule for later
- * await queue.enqueueAt(cfg.for(phone, { code }), Date.now() + 60_000);
+ * queue.enqueue(otpConfig.for(phone, { code }));
  */
 export default class SMSQueue {
   private jobs: QueueJob[] = [];
+  private deadLetters: FailedJob[] = [];
   private dedupSet = new Set<string>();
+  private listeners: Map<string, Array<(data: any) => void>> = new Map();
+
   private running = 0;
   private completed = 0;
+  private failedCount = 0;
   private dropped = 0;
   private pollTimer?: ReturnType<typeof setInterval>;
+
   private readonly concurrency: number;
   private readonly pollInterval: number;
   private readonly autoStart: boolean;
+  private readonly defaultMaxAttempts: number;
+  private readonly retryDelay: number;
   private plugins?: PluginManager;
 
   constructor(
@@ -76,32 +110,61 @@ export default class SMSQueue {
     this.concurrency = options.concurrency ?? 3;
     this.pollInterval = options.pollInterval ?? 1000;
     this.autoStart = options.autoStart ?? true;
+    this.defaultMaxAttempts = options.maxAttempts ?? 3;
+    this.retryDelay = options.retryDelay ?? 2000;
     this.plugins = plugins;
   }
 
+  // ── Event emitter (tiny, no deps) ────────────────────────────────────────
+
+  on(
+    event: "failed" | "completed" | "dropped",
+    listener: (data: any) => void,
+  ): this {
+    if (!this.listeners.has(event)) this.listeners.set(event, []);
+    this.listeners.get(event)!.push(listener);
+    return this;
+  }
+
+  private emit(event: string, data: unknown) {
+    this.listeners.get(event)?.forEach((fn) => {
+      try {
+        fn(data);
+      } catch {
+        /* listener errors must not crash the queue */
+      }
+    });
+  }
+
   // ── Enqueue ──────────────────────────────────────────────────────────────
 
-  /** Enqueue a job for immediate (or next-available) processing. */
-  enqueue(params: SendParams & Partial<SendMeta>): string {
-    return this._enqueue(params, 0);
+  enqueue(
+    params: SendParams & Partial<SendMeta>,
+    maxAttempts?: number,
+  ): string {
+    return this._enqueue(params, 0, maxAttempts);
   }
 
-  /** Enqueue a job to send at a specific future timestamp (epoch ms). */
-  enqueueAt(params: SendParams & Partial<SendMeta>, timestamp: number): string {
-    return this._enqueue(params, timestamp);
+  enqueueAt(
+    params: SendParams & Partial<SendMeta>,
+    timestamp: number,
+    maxAttempts?: number,
+  ): string {
+    return this._enqueue(params, timestamp, maxAttempts);
   }
 
-  /** Enqueue a job to send after a delay (ms). */
   enqueueAfter(
     params: SendParams & Partial<SendMeta>,
     delayMs: number,
+    maxAttempts?: number,
   ): string {
-    return this._enqueue(params, Date.now() + delayMs);
+    return this._enqueue(params, Date.now() + delayMs, maxAttempts);
   }
 
   private _enqueue(
     params: SendParams & Partial<SendMeta>,
     scheduledAt: number,
+    maxAttempts?: number,
   ): string {
     const meta = (params as any)._meta ?? {
       tags: [],
@@ -118,7 +181,8 @@ export default class SMSQueue {
           tags: meta.tags,
           reason: "dedup",
         });
-        return meta.dedupKey; // return key so caller can identify it
+        this.emit("dropped", { reason: "dedup", params });
+        return meta.dedupKey;
       }
       this.dedupSet.add(meta.dedupKey);
     }
@@ -134,20 +198,19 @@ export default class SMSQueue {
       scheduledAt,
       enqueuedAt: Date.now(),
       attempts: 0,
+      maxAttempts: maxAttempts ?? this.defaultMaxAttempts,
+      history: [],
     };
 
     this._insertByPriority(job);
 
-    if (this.autoStart && !this.pollTimer) {
-      this.start();
-    }
+    if (this.autoStart && !this.pollTimer) this.start();
 
     return id;
   }
 
   private _insertByPriority(job: QueueJob) {
     const w = PRIORITY_WEIGHT[job.meta.priority as Priority] ?? 2;
-    // Find insertion point: higher weight jobs go first
     let i = 0;
     while (
       i < this.jobs.length &&
@@ -157,17 +220,32 @@ export default class SMSQueue {
     this.jobs.splice(i, 0, job);
   }
 
-  // ── Lifecycle ────────────────────────────────────────────────────────────
+  // ── Re-enqueue (used after failure) ──────────────────────────────────────
+
+  /**
+   * Re-enqueue jobs that previously failed.
+   * Pass the array from `queue.getDeadLetters()` or `batchResult.failed` re-wrapped.
+   * Clears them from the dead-letter list.
+   */
+  requeueFailed(jobs: FailedJob[]): string[] {
+    return jobs.map(({ job }) => {
+      // Remove from dead-letter list
+      this.deadLetters = this.deadLetters.filter((d) => d.job.id !== job.id);
+      // Re-insert with attempt history preserved
+      this._insertByPriority(job);
+      return job.id;
+    });
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
 
-  /** Start the queue workers. */
   start(): this {
     if (this.pollTimer) return this;
     this.pollTimer = setInterval(() => this._tick(), this.pollInterval);
-    this._tick(); // immediate first tick
+    this._tick();
     return this;
   }
 
-  /** Drain the queue (process remaining jobs) then stop. */
   async drain(): Promise<void> {
     this.stop();
     while (this.jobs.length > 0 || this.running > 0) {
@@ -176,7 +254,6 @@ export default class SMSQueue {
     }
   }
 
-  /** Stop polling. In-flight jobs still complete. */
   stop(): this {
     if (this.pollTimer) {
       clearInterval(this.pollTimer);
@@ -185,16 +262,13 @@ export default class SMSQueue {
     return this;
   }
 
-  // ── Processing ───────────────────────────────────────────────────────────
+  // ── Processing ────────────────────────────────────────────────────────────
 
   private _tick() {
     const now = Date.now();
-
     while (this.running < this.concurrency && this.jobs.length > 0) {
-      // Find next ready job (scheduledAt <= now)
       const idx = this.jobs.findIndex((j) => j.scheduledAt <= now);
       if (idx === -1) break;
-
       const [job] = this.jobs.splice(idx, 1);
       this._process(job);
     }
@@ -213,10 +287,12 @@ export default class SMSQueue {
         tags: meta.tags,
         reason: "ttl",
       });
+      this.emit("dropped", { reason: "ttl", job });
       return;
     }
 
     this.running++;
+    job.attempts++;
     const start = Date.now();
     await this.plugins?.fire("onSend", {
       to: params.to,
@@ -225,11 +301,21 @@ export default class SMSQueue {
     });
 
     const result = (await (this.client as any).send(params)) as Result<any>;
-
     this.running--;
     const durationMs = Date.now() - start;
 
+    // Record this attempt
+    const record: AttemptRecord = {
+      attempt: job.attempts,
+      timestamp: new Date().toISOString(),
+      ok: result.ok,
+      durationMs,
+      ...(result.ok ? { data: result.data } : { error: result.error }),
+    };
+    job.history.push(record);
+
     if (result.ok) {
+      // ── SUCCESS ──────────────────────────────────────────────────────────
       this.completed++;
       if (meta.dedupKey) this.dedupSet.delete(meta.dedupKey);
       await this.plugins?.fire("onSuccess", {
@@ -238,29 +324,76 @@ export default class SMSQueue {
         data: result.data,
         durationMs,
       });
+      this.emit("completed", { job, data: result.data });
     } else {
-      if (meta.dedupKey) this.dedupSet.delete(meta.dedupKey);
+      // ── FAILURE ──────────────────────────────────────────────────────────
+      const isPermanent = NON_RETRYABLE_CODES.has(result.error.code);
+      const retriesExhausted = job.attempts >= job.maxAttempts;
+
       await this.plugins?.fire("onError", {
         to: params.to,
         tags: meta.tags,
         error: result.error,
         durationMs,
+        attempt: job.attempts,
       });
+
+      if (!isPermanent && !retriesExhausted) {
+        // ── RE-QUEUE with exponential backoff ─────────────────────────────
+        const backoff = this.retryDelay * 2 ** (job.attempts - 1);
+        job.scheduledAt = Date.now() + backoff;
+        this._insertByPriority(job); // put back in queue
+
+        await this.plugins?.fire("onRetry", {
+          to: params.to,
+          tags: meta.tags,
+          error: result.error,
+          attempt: job.attempts,
+        });
+      } else {
+        // ── DEAD LETTER — data is preserved, never silently lost ──────────
+        this.failedCount++;
+        if (meta.dedupKey) this.dedupSet.delete(meta.dedupKey);
+
+        const failedJob: FailedJob = {
+          job,
+          finalError: result.error,
+          history: job.history,
+        };
+
+        this.deadLetters.push(failedJob);
+        this.emit("failed", failedJob);
+      }
     }
   }
 
-  // ── Stats ────────────────────────────────────────────────────────────────
+  // ── Inspection ────────────────────────────────────────────────────────────
 
   stats(): QueueStats {
     return {
       pending: this.jobs.length,
       running: this.running,
       completed: this.completed,
+      failed: this.failedCount,
       dropped: this.dropped,
     };
   }
 
-  /** Cancel a job by id. Returns true if found and removed. */
+  /**
+   * Returns all jobs that exhausted their retries or hit a permanent error.
+   * Each entry includes the full attempt history — no data is lost.
+   */
+  getDeadLetters(): FailedJob[] {
+    return [...this.deadLetters];
+  }
+
+  /** Clear the dead-letter list (e.g. after you've processed/saved them). */
+  clearDeadLetters(): FailedJob[] {
+    const copy = [...this.deadLetters];
+    this.deadLetters = [];
+    return copy;
+  }
+
   cancel(id: string): boolean {
     const idx = this.jobs.findIndex((j) => j.id === id);
     if (idx === -1) return false;
@@ -269,7 +402,6 @@ export default class SMSQueue {
     return true;
   }
 
-  /** Clear all pending (not in-flight) jobs. */
   clear(): number {
     const count = this.jobs.length;
     this.jobs.forEach(

package/src/errors.ts

@@ -69,3 +69,9 @@ export class CircuitOpenError extends SMSClientError {
     super(message, "CIRCUIT_OPEN", details, false, false);
   }
 }
+
+export class MaxLimitError extends SMSClientError {
+  constructor(message: string, details?: unknown) {
+    super(message, "MAX_LIMIT_ERROR", details, false, true);
+  }
+}