bridgex 2.0.0 → 2.0.1

package/dist/SMSClient.js

@@ -0,0 +1,236 @@
+import HttpClient from "./HttpClient.js";
+import RetryHandler from "./RetryHandler.js";
+import CircuitBreaker from "./CircuitBreaker.js";
+import MessageFormatter from "./MessageFormatter.js";
+import PluginManager from "./PluginManager.js";
+import { ValidationError } from "./errors.js";
+import { chunkArray } from "./helpers.js";
+function toErrorLog(error) {
+    if (error instanceof Error) {
+        const e = error;
+        return {
+            name: e.name ?? "Error",
+            message: e.message,
+            code: e.code ?? "UNKNOWN",
+            isClientError: e.isClientError ?? false,
+            isServerError: e.isServerError ?? false,
+            details: e.details,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    return {
+        name: "UnknownError",
+        message: String(error),
+        code: "UNKNOWN",
+        isClientError: false,
+        isServerError: false,
+        timestamp: new Date().toISOString(),
+    };
+}
+function ok(data) {
+    return { ok: true, data, error: null };
+}
+function fail(error) {
+    return { ok: false, data: null, error: toErrorLog(error) };
+}
+export default class SMSClient {
+    constructor(options) {
+        this.options = options;
+        this.validateOptions(options);
+        this.http = new HttpClient({
+            baseUrl: options.baseUrl,
+            apiKey: options.apiKey,
+            projectKey: options.projectKey,
+        });
+        this.retry = new RetryHandler(options.retry);
+        this.circuit = new CircuitBreaker(options.circuitBreaker);
+        this.formatter = new MessageFormatter();
+        this.plugins = new PluginManager();
+        this.concurrency = options.concurrency ?? 5;
+        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
+    // ─────────────────────────────────────────────────────────────────────────
+    async _send(to, message, tags = []) {
+        const start = Date.now();
+        await this.plugins.fire("onSend", { to, message, tags });
+        try {
+            const data = await this.circuit.execute(() => this.retry.execute(() => this.http.post("/sms/send", { to, message })));
+            await this.plugins.fire("onSuccess", {
+                to,
+                message,
+                tags,
+                data,
+                durationMs: Date.now() - start,
+            });
+            return data;
+        }
+        catch (err) {
+            await this.plugins.fire("onError", {
+                to,
+                message,
+                tags,
+                error: toErrorLog(err),
+                durationMs: Date.now() - start,
+            });
+            throw err;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Public API
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Send a single SMS message.
+     * Returns a Result — never throws.
+     */
+    async send(params) {
+        const { to, template, variables = {} } = params;
+        const tags = params._meta?.tags ?? [];
+        try {
+            if (!to)
+                throw new ValidationError("Recipient phone number is required");
+            const message = this.formatter.format(template, variables);
+            const data = await this._send(to, message, tags);
+            return ok(data);
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    /**
+     * Send the same template to many recipients.
+     * Each recipient can supply its own variables; shared variables are the fallback.
+     */
+    async sendMany(recipients, template, sharedVariables = {}) {
+        const result = {
+            succeeded: [],
+            failed: [],
+            total: recipients.length,
+            successCount: 0,
+            failureCount: 0,
+        };
+        const chunks = chunkArray(recipients, this.batchSize);
+        for (const chunk of chunks) {
+            const queue = [...chunk.entries()];
+            await Promise.all(new Array(this.concurrency).fill(null).map(async () => {
+                while (queue.length > 0) {
+                    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({
+                        to: recipient.to,
+                        template,
+                        variables,
+                    });
+                    if (res.ok) {
+                        result.succeeded.push({
+                            index: globalIndex,
+                            to: recipient.to,
+                            data: res.data,
+                        });
+                        result.successCount++;
+                    }
+                    else {
+                        result.failed.push({
+                            index: globalIndex,
+                            to: recipient.to,
+                            error: res.error,
+                        });
+                        result.failureCount++;
+                    }
+                }
+            }));
+        }
+        return result;
+    }
+    /**
+     * Send a message derived from a plain object.
+     * Auto-detects message from message/body/text/content fields,
+     * or formats via an optional template using the object's keys.
+     */
+    async sendObject(params) {
+        const { to, object, template } = params;
+        const tags = params._meta?.tags ?? [];
+        try {
+            if (!to)
+                throw new ValidationError("Recipient phone number is required");
+            const { message } = this.formatter.fromObject(object, template);
+            const data = await this._send(to, message, tags);
+            return ok(data);
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    /**
+     * Send object-derived messages to many recipients.
+     */
+    async sendObjectMany(items) {
+        const result = {
+            succeeded: [],
+            failed: [],
+            total: items.length,
+            successCount: 0,
+            failureCount: 0,
+        };
+        const chunks = chunkArray(items, this.batchSize);
+        for (const chunk of chunks) {
+            const queue = [...chunk.entries()];
+            await Promise.all(new Array(this.concurrency).fill(null).map(async () => {
+                while (queue.length > 0) {
+                    const entry = queue.shift();
+                    if (!entry)
+                        break;
+                    const [chunkIndex, item] = entry;
+                    const globalIndex = chunks.indexOf(chunk) * this.batchSize + chunkIndex;
+                    const res = await this.sendObject(item);
+                    if (res.ok) {
+                        result.succeeded.push({
+                            index: globalIndex,
+                            to: item.to,
+                            data: res.data,
+                        });
+                        result.successCount++;
+                    }
+                    else {
+                        result.failed.push({
+                            index: globalIndex,
+                            to: item.to,
+                            error: res.error,
+                        });
+                        result.failureCount++;
+                    }
+                }
+            }));
+        }
+        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)
+            throw new ValidationError("baseUrl is required");
+        if (!apiKey)
+            throw new ValidationError("apiKey is required");
+        if (!projectKey)
+            throw new ValidationError("projectKey is required");
+    }
+}

package/dist/SMSQueue.d.ts

@@ -0,0 +1,82 @@
+import type SMSClient from "./SMSClient.js";
+import type PluginManager from "./PluginManager.js";
+import type { SendParams } from "./types.js";
+import type { SendMeta } from "./SendConfig.js";
+export interface QueueJob {
+    id: string;
+    params: SendParams;
+    meta: SendMeta["_meta"];
+    scheduledAt: number;
+    enqueuedAt: number;
+    attempts: number;
+}
+export interface QueueOptions {
+    /** Max concurrent workers processing the queue (default: 3) */
+    concurrency?: number;
+    /** How often (ms) the queue polls for scheduled jobs (default: 1000) */
+    pollInterval?: number;
+    /** Whether to start processing automatically on first enqueue (default: true) */
+    autoStart?: boolean;
+}
+export interface QueueStats {
+    pending: number;
+    running: number;
+    completed: number;
+    dropped: number;
+}
+/**
+ * SMSQueue — an in-process job queue for fire-and-forget or scheduled SMS.
+ *
+ * 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)
+ *
+ * @example
+ * const queue = new SMSQueue(client, { concurrency: 5 });
+ * queue.start();
+ *
+ * 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);
+ */
+export default class SMSQueue {
+    private client;
+    private jobs;
+    private dedupSet;
+    private running;
+    private completed;
+    private dropped;
+    private pollTimer?;
+    private readonly concurrency;
+    private readonly pollInterval;
+    private readonly autoStart;
+    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;
+    private _enqueue;
+    private _insertByPriority;
+    /** Start the queue workers. */
+    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. */
+    cancel(id: string): boolean;
+    /** Clear all pending (not in-flight) jobs. */
+    clear(): number;
+}

package/dist/SMSQueue.js

@@ -0,0 +1,207 @@
+const PRIORITY_WEIGHT = {
+    high: 3,
+    normal: 2,
+    low: 1,
+};
+/**
+ * SMSQueue — an in-process job queue for fire-and-forget or scheduled SMS.
+ *
+ * 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)
+ *
+ * @example
+ * const queue = new SMSQueue(client, { concurrency: 5 });
+ * queue.start();
+ *
+ * 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);
+ */
+export default class SMSQueue {
+    constructor(client, options = {}, plugins) {
+        this.client = client;
+        this.jobs = [];
+        this.dedupSet = new Set();
+        this.running = 0;
+        this.completed = 0;
+        this.dropped = 0;
+        this.concurrency = options.concurrency ?? 3;
+        this.pollInterval = options.pollInterval ?? 1000;
+        this.autoStart = options.autoStart ?? true;
+        this.plugins = plugins;
+    }
+    // ── Enqueue ──────────────────────────────────────────────────────────────
+    /** Enqueue a job for immediate (or next-available) processing. */
+    enqueue(params) {
+        return this._enqueue(params, 0);
+    }
+    /** Enqueue a job to send at a specific future timestamp (epoch ms). */
+    enqueueAt(params, timestamp) {
+        return this._enqueue(params, timestamp);
+    }
+    /** Enqueue a job to send after a delay (ms). */
+    enqueueAfter(params, delayMs) {
+        return this._enqueue(params, Date.now() + delayMs);
+    }
+    _enqueue(params, scheduledAt) {
+        const meta = params._meta ?? {
+            tags: [],
+            priority: "normal",
+            createdAt: Date.now(),
+        };
+        // Deduplication
+        if (meta.dedupKey) {
+            if (this.dedupSet.has(meta.dedupKey)) {
+                this.dropped++;
+                this.plugins?.fire("onDrop", {
+                    to: params.to,
+                    tags: meta.tags,
+                    reason: "dedup",
+                });
+                return meta.dedupKey; // return key so caller can identify it
+            }
+            this.dedupSet.add(meta.dedupKey);
+        }
+        const id = meta.dedupKey ??
+            `job_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const job = {
+            id,
+            params,
+            meta,
+            scheduledAt,
+            enqueuedAt: Date.now(),
+            attempts: 0,
+        };
+        this._insertByPriority(job);
+        if (this.autoStart && !this.pollTimer) {
+            this.start();
+        }
+        return id;
+    }
+    _insertByPriority(job) {
+        const w = PRIORITY_WEIGHT[job.meta.priority] ?? 2;
+        // Find insertion point: higher weight jobs go first
+        let i = 0;
+        while (i < this.jobs.length &&
+            PRIORITY_WEIGHT[this.jobs[i].meta.priority ?? "normal"] >= w)
+            i++;
+        this.jobs.splice(i, 0, job);
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    /** Start the queue workers. */
+    start() {
+        if (this.pollTimer)
+            return this;
+        this.pollTimer = setInterval(() => this._tick(), this.pollInterval);
+        this._tick(); // immediate first tick
+        return this;
+    }
+    /** Drain the queue (process remaining jobs) then stop. */
+    async drain() {
+        this.stop();
+        while (this.jobs.length > 0 || this.running > 0) {
+            await new Promise((r) => setTimeout(r, 50));
+            this._tick();
+        }
+    }
+    /** Stop polling. In-flight jobs still complete. */
+    stop() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+        return this;
+    }
+    // ── Processing ───────────────────────────────────────────────────────────
+    _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);
+        }
+    }
+    async _process(job) {
+        const { params, meta } = job;
+        const now = Date.now();
+        // TTL check
+        if (meta.ttl && now - meta.createdAt > meta.ttl) {
+            this.dropped++;
+            if (meta.dedupKey)
+                this.dedupSet.delete(meta.dedupKey);
+            await this.plugins?.fire("onDrop", {
+                to: params.to,
+                tags: meta.tags,
+                reason: "ttl",
+            });
+            return;
+        }
+        this.running++;
+        const start = Date.now();
+        await this.plugins?.fire("onSend", {
+            to: params.to,
+            tags: meta.tags,
+            template: params.template,
+        });
+        const result = (await this.client.send(params));
+        this.running--;
+        const durationMs = Date.now() - start;
+        if (result.ok) {
+            this.completed++;
+            if (meta.dedupKey)
+                this.dedupSet.delete(meta.dedupKey);
+            await this.plugins?.fire("onSuccess", {
+                to: params.to,
+                tags: meta.tags,
+                data: result.data,
+                durationMs,
+            });
+        }
+        else {
+            if (meta.dedupKey)
+                this.dedupSet.delete(meta.dedupKey);
+            await this.plugins?.fire("onError", {
+                to: params.to,
+                tags: meta.tags,
+                error: result.error,
+                durationMs,
+            });
+        }
+    }
+    // ── Stats ────────────────────────────────────────────────────────────────
+    stats() {
+        return {
+            pending: this.jobs.length,
+            running: this.running,
+            completed: this.completed,
+            dropped: this.dropped,
+        };
+    }
+    /** Cancel a job by id. Returns true if found and removed. */
+    cancel(id) {
+        const idx = this.jobs.findIndex((j) => j.id === id);
+        if (idx === -1)
+            return false;
+        const [job] = this.jobs.splice(idx, 1);
+        if (job.meta.dedupKey)
+            this.dedupSet.delete(job.meta.dedupKey);
+        return true;
+    }
+    /** Clear all pending (not in-flight) jobs. */
+    clear() {
+        const count = this.jobs.length;
+        this.jobs.forEach((j) => j.meta.dedupKey && this.dedupSet.delete(j.meta.dedupKey));
+        this.jobs = [];
+        return count;
+    }
+}

package/dist/SMSScheduler.d.ts

@@ -0,0 +1,75 @@
+import type SMSQueue from "./SMSQueue.js";
+import type { SendParams } from "./types.js";
+import type { SendMeta } from "./SendConfig.js";
+export interface ScheduledJob {
+    id: string;
+    name: string;
+    params: SendParams & Partial<SendMeta>;
+    /** Cron expression OR interval ms */
+    schedule: string | number;
+    nextRunAt: number;
+    runCount: number;
+    maxRuns?: number;
+    enabled: boolean;
+}
+/**
+ * SMSScheduler — register recurring or one-shot SMS sends.
+ *
+ * Schedules can be:
+ *  - A millisecond interval: `every(60_000, "ping", params)`
+ *  - A cron expression:      `cron("0 9 * * MON-FRI", "weekly-digest", params)`
+ *  - A one-shot future send:  `once(new Date("2025-01-01"), "new-year", params)`
+ *
+ * All jobs are dispatched through an SMSQueue (respects priority, TTL, dedup).
+ *
+ * @example
+ * const scheduler = new SMSScheduler(queue);
+ * scheduler.start();
+ *
+ * scheduler.every(
+ *   24 * 60 * 60 * 1000,
+ *   "daily-digest",
+ *   digestConfig.for(adminPhone)
+ * );
+ *
+ * scheduler.once(
+ *   new Date("2025-06-01T09:00:00"),
+ *   "summer-promo",
+ *   promoConfig.for(phone)
+ * );
+ */
+export default class SMSScheduler {
+    private queue;
+    private jobs;
+    private timer?;
+    private readonly tickMs;
+    constructor(queue: SMSQueue, options?: {
+        tickMs?: number;
+    });
+    /** Repeat every `intervalMs` milliseconds. */
+    every(intervalMs: number, name: string, params: SendParams & Partial<SendMeta>, options?: {
+        maxRuns?: number;
+        runImmediately?: boolean;
+    }): string;
+    /** Run once at a specific date/time. Automatically removes itself after firing. */
+    once(at: Date | number, name: string, params: SendParams & Partial<SendMeta>): string;
+    /**
+     * Cron-style schedule using a tiny parser (supports minute/hour/day/month/weekday).
+     *
+     * Format: "minute hour day-of-month month day-of-week"
+     * Use "*" for "every", comma for lists, "/" for steps.
+     *
+     * @example scheduler.cron("0 9 * * 1-5", "weekday-morning", params)
+     * @example scheduler.cron("30 8,12,18 * * *", "thrice-daily", params)
+     */
+    cron(expression: string, name: string, params: SendParams & Partial<SendMeta>, options?: {
+        maxRuns?: number;
+    }): string;
+    pause(id: string): boolean;
+    resume(id: string): boolean;
+    remove(id: string): boolean;
+    list(): ScheduledJob[];
+    start(): this;
+    stop(): this;
+    private _tick;
+}