bridgex 2.0.1 → 2.1.0

package/dist/HttpClient.js

@@ -1,4 +1,15 @@
-import { NetworkError, ServerError } from "./errors.js";
+import { NetworkError, ServerError, RateLimitError, MaxLimitError, } from "./errors.js";
+// Patterns that indicate a "max messages sent" quota error from the server
+const MAX_LIMIT_PATTERNS = [
+    /max.{0,20}(messages?|sms|send)/i,
+    /quota.{0,20}(exceeded|reached|exhausted)/i,
+    /limit.{0,20}reached/i,
+    /daily.{0,20}(limit|cap)/i,
+    /monthly.{0,20}(limit|cap)/i,
+];
+function isMaxLimitBody(text) {
+    return MAX_LIMIT_PATTERNS.some((p) => p.test(text));
+}
 export default class HttpClient {
     constructor(options) {
         this.options = options;
@@ -19,17 +30,33 @@ export default class HttpClient {
                 signal: controller.signal,
             });
             clearTimeout(timeoutId);
+            if (response.status === 429) {
+                const retryAfter = Number(response.headers.get("Retry-After")) || undefined;
+                throw new RateLimitError("Rate limit exceeded", retryAfter);
+            }
             if (!response.ok) {
                 const text = await response.text();
-                throw new ServerError(`Server responded with ${response.status}`, text);
+                // Detect "max messages sent reached" specifically — not retryable
+                if (response.status === 402 ||
+                    response.status === 403 ||
+                    isMaxLimitBody(text)) {
+                    throw new MaxLimitError(`Message quota exceeded (HTTP ${response.status})`, { status: response.status, body: text });
+                }
+                throw new ServerError(`Server responded with ${response.status}`, {
+                    status: response.status,
+                    body: text,
+                });
             }
             return await response.json();
         }
         catch (error) {
+            clearTimeout(timeoutId);
             if (error.name === "AbortError") {
                 throw new NetworkError("Request timed out");
             }
-            if (error instanceof ServerError) {
+            if (error instanceof ServerError ||
+                error instanceof RateLimitError ||
+                error instanceof MaxLimitError) {
                 throw error;
             }
             throw new NetworkError("Network request failed", error);

package/dist/SMSClient.d.ts

@@ -25,19 +25,22 @@ export default class SMSClient {
     private concurrency;
     private batchSize;
     constructor(options: SMSClientOptions);
-    /** Attach a plugin at any time. */
     use(plugin: Plugin): this;
     private _send;
-    /**
-     * Send a single SMS message.
-     * Returns a Result — never throws.
-     */
+    /** Send a single SMS. Returns a Result — never throws. */
     send(params: SendParams & {
         _meta?: any;
     }): Promise<Result<any>>;
     /**
      * 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.
      */
     sendMany(recipients: Array<{
         to: string;
@@ -51,15 +54,11 @@ export default class SMSClient {
     sendObject<T extends Record<string, unknown>>(params: SendObjectParams<T> & {
         _meta?: any;
     }): Promise<Result<any>>;
-    /**
-     * Send object-derived messages to many recipients.
-     */
+    /** Send object-derived messages to many recipients. */
     sendObjectMany<T extends Record<string, unknown>>(items: Array<SendObjectParams<T> & {
         _meta?: any;
     }>): Promise<BatchResult<any>>;
-    /** Current circuit breaker state. */
     get circuitState(): "CLOSED" | "OPEN" | "HALF_OPEN";
-    /** Manually reset the circuit breaker (e.g. after fixing a downstream issue). */
     resetCircuit(): void;
     private validateOptions;
 }

package/dist/SMSClient.js

@@ -50,13 +50,12 @@ export default class SMSClient {
         this.batchSize = options.batchSize ?? 50;
         options.plugins?.forEach((p) => this.plugins.use(p));
     }
-    /** Attach a plugin at any time. */
     use(plugin) {
         this.plugins.use(plugin);
         return this;
     }
     // ─────────────────────────────────────────────────────────────────────────
-    // Core internal send — all public methods funnel through here
+    // Core internal send
     // ─────────────────────────────────────────────────────────────────────────
     async _send(to, message, tags = []) {
         const start = Date.now();
@@ -86,10 +85,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) {
         const { to, template, variables = {} } = params;
         const tags = params._meta?.tags ?? [];
@@ -106,7 +102,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, template, sharedVariables = {}) {
         const result = {
@@ -115,23 +118,29 @@ 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;
                     const [chunkIndex, recipient] = entry;
                     const globalIndex = chunks.indexOf(chunk) * this.batchSize + chunkIndex;
                     const variables = { ...sharedVariables, ...recipient.variables };
-                    const res = await this.send({
+                    const originalParams = {
                         to: recipient.to,
                         template,
                         variables,
-                    });
+                    };
+                    const res = await this.send({ ...originalParams });
                     if (res.ok) {
                         result.succeeded.push({
                             index: globalIndex,
@@ -141,15 +150,51 @@ export default class SMSClient {
                         result.successCount++;
                     }
                     else {
-                        result.failed.push({
+                        const 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;
     }
@@ -172,9 +217,7 @@ export default class SMSClient {
             return fail(error);
         }
     }
-    /**
-     * Send object-derived messages to many recipients.
-     */
+    /** Send object-derived messages to many recipients. */
     async sendObjectMany(items) {
         const result = {
             succeeded: [],
@@ -182,12 +225,16 @@ 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;
@@ -203,27 +250,37 @@ export default class SMSClient {
                         result.successCount++;
                     }
                     else {
+                        // For object sends, preserve what we can
+                        const originalParams = {
+                            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();
     }
-    // ─────────────────────────────────────────────────────────────────────────
     validateOptions(options) {
         const { baseUrl, apiKey, projectKey } = options;
         if (!baseUrl)

package/dist/SMSQueue.d.ts

@@ -1,6 +1,6 @@
 import type SMSClient from "./SMSClient.js";
 import type PluginManager from "./PluginManager.js";
-import type { SendParams } from "./types.js";
+import type { SendParams, ErrorLog } from "./types.js";
 import type { SendMeta } from "./SendConfig.js";
 export interface QueueJob {
     id: string;
@@ -8,75 +8,105 @@ export interface QueueJob {
     meta: SendMeta["_meta"];
     scheduledAt: number;
     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;
+    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 client;
     private jobs;
+    private deadLetters;
     private dedupSet;
+    private listeners;
     private running;
     private completed;
+    private failedCount;
     private dropped;
     private pollTimer?;
     private readonly concurrency;
     private readonly pollInterval;
     private readonly autoStart;
+    private readonly defaultMaxAttempts;
+    private readonly retryDelay;
     private plugins?;
     constructor(client: SMSClient, options?: QueueOptions, plugins?: PluginManager);
-    /** Enqueue a job for immediate (or next-available) processing. */
-    enqueue(params: SendParams & Partial<SendMeta>): string;
-    /** Enqueue a job to send at a specific future timestamp (epoch ms). */
-    enqueueAt(params: SendParams & Partial<SendMeta>, timestamp: number): string;
-    /** Enqueue a job to send after a delay (ms). */
-    enqueueAfter(params: SendParams & Partial<SendMeta>, delayMs: number): string;
+    on(event: "failed" | "completed" | "dropped", listener: (data: any) => void): this;
+    private emit;
+    enqueue(params: SendParams & Partial<SendMeta>, maxAttempts?: number): string;
+    enqueueAt(params: SendParams & Partial<SendMeta>, timestamp: number, maxAttempts?: number): string;
+    enqueueAfter(params: SendParams & Partial<SendMeta>, delayMs: number, maxAttempts?: number): string;
     private _enqueue;
     private _insertByPriority;
-    /** Start the queue workers. */
+    /**
+     * 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[];
     start(): this;
-    /** Drain the queue (process remaining jobs) then stop. */
     drain(): Promise<void>;
-    /** Stop polling. In-flight jobs still complete. */
     stop(): this;
     private _tick;
     private _process;
     stats(): QueueStats;
-    /** 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[];
+    /** Clear the dead-letter list (e.g. after you've processed/saved them). */
+    clearDeadLetters(): FailedJob[];
     cancel(id: string): boolean;
-    /** Clear all pending (not in-flight) jobs. */
     clear(): number;
 }