bridgex 1.0.0 → 2.0.1

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;
+}

package/dist/SMSScheduler.js

@@ -0,0 +1,196 @@
+/**
+ * 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 {
+    constructor(queue, options = {}) {
+        this.queue = queue;
+        this.jobs = new Map();
+        this.tickMs = options.tickMs ?? 1000;
+    }
+    // ── Registration ─────────────────────────────────────────────────────────
+    /** Repeat every `intervalMs` milliseconds. */
+    every(intervalMs, name, params, options = {}) {
+        const id = `every:${name}`;
+        this.jobs.set(id, {
+            id,
+            name,
+            params,
+            schedule: intervalMs,
+            nextRunAt: options.runImmediately ? Date.now() : Date.now() + intervalMs,
+            runCount: 0,
+            maxRuns: options.maxRuns,
+            enabled: true,
+        });
+        return id;
+    }
+    /** Run once at a specific date/time. Automatically removes itself after firing. */
+    once(at, name, params) {
+        const ts = at instanceof Date ? at.getTime() : at;
+        const id = `once:${name}:${ts}`;
+        this.jobs.set(id, {
+            id,
+            name,
+            params,
+            schedule: 0,
+            nextRunAt: ts,
+            runCount: 0,
+            maxRuns: 1,
+            enabled: true,
+        });
+        return id;
+    }
+    /**
+     * 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, name, params, options = {}) {
+        const id = `cron:${name}`;
+        const nextRunAt = nextCronTime(expression);
+        this.jobs.set(id, {
+            id,
+            name,
+            params,
+            schedule: expression,
+            nextRunAt,
+            runCount: 0,
+            maxRuns: options.maxRuns,
+            enabled: true,
+        });
+        return id;
+    }
+    // ── Control ──────────────────────────────────────────────────────────────
+    pause(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return false;
+        job.enabled = false;
+        return true;
+    }
+    resume(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return false;
+        job.enabled = true;
+        return true;
+    }
+    remove(id) {
+        return this.jobs.delete(id);
+    }
+    list() {
+        return Array.from(this.jobs.values());
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    start() {
+        if (this.timer)
+            return this;
+        this.timer = setInterval(() => this._tick(), this.tickMs);
+        return this;
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        return this;
+    }
+    _tick() {
+        const now = Date.now();
+        for (const [id, job] of this.jobs) {
+            if (!job.enabled || job.nextRunAt > now)
+                continue;
+            // Dispatch to queue
+            this.queue.enqueue(job.params);
+            job.runCount++;
+            // Remove one-shots / exhausted jobs
+            if (job.maxRuns !== undefined && job.runCount >= job.maxRuns) {
+                this.jobs.delete(id);
+                continue;
+            }
+            // Advance nextRunAt
+            if (typeof job.schedule === "number" && job.schedule > 0) {
+                job.nextRunAt = now + job.schedule;
+            }
+            else if (typeof job.schedule === "string") {
+                job.nextRunAt = nextCronTime(job.schedule);
+            }
+        }
+    }
+}
+// ── Tiny cron parser ─────────────────────────────────────────────────────────
+function nextCronTime(expression) {
+    const [minuteExpr, hourExpr, domExpr, monthExpr, dowExpr] = expression.trim().split(/\s+/);
+    const now = new Date();
+    const candidate = new Date(now);
+    candidate.setSeconds(0, 0);
+    candidate.setMinutes(candidate.getMinutes() + 1); // start from next minute
+    // Try up to 366 days ahead
+    for (let days = 0; days < 366 * 24 * 60; days++) {
+        const m = candidate.getMinutes();
+        const h = candidate.getHours();
+        const dom = candidate.getDate();
+        const month = candidate.getMonth() + 1;
+        const dow = candidate.getDay();
+        if (matchField(minuteExpr, m, 0, 59) &&
+            matchField(hourExpr, h, 0, 23) &&
+            matchField(domExpr, dom, 1, 31) &&
+            matchField(monthExpr, month, 1, 12) &&
+            matchField(dowExpr, dow, 0, 6)) {
+            return candidate.getTime();
+        }
+        candidate.setMinutes(candidate.getMinutes() + 1);
+    }
+    throw new Error(`Cannot find next occurrence for cron expression: "${expression}"`);
+}
+function matchField(expr, value, min, max) {
+    if (expr === "*")
+        return true;
+    for (const part of expr.split(",")) {
+        if (part.includes("/")) {
+            const [range, step] = part.split("/");
+            const s = parseInt(step, 10);
+            const [lo, hi] = range === "*"
+                ? [min, max]
+                : range.split("-").map(Number);
+            if (value >= lo && value <= hi && (value - lo) % s === 0)
+                return true;
+        }
+        else if (part.includes("-")) {
+            const [lo, hi] = part.split("-").map(Number);
+            if (value >= lo && value <= hi)
+                return true;
+        }
+        else {
+            if (parseInt(part, 10) === value)
+                return true;
+        }
+    }
+    return false;
+}

package/dist/SMSService.d.ts

@@ -0,0 +1,41 @@
+import type SMSClient from "./SMSClient.js";
+import type SMSQueue from "./SMSQueue.js";
+import type { MetricsSnapshot } from "./PluginManager.js";
+export interface SMSServiceOptions {
+    port?: number;
+    host?: string;
+    /** Shared secret callers must send in the `x-service-key` header */
+    apiKey?: string;
+    /** Request timeout ms (default: 10 000) */
+    timeout?: number;
+}
+export default class SMSService {
+    private client;
+    private options;
+    private server;
+    private queue?;
+    private metricsSnapshot?;
+    private startedAt;
+    constructor(client: SMSClient, options?: SMSServiceOptions);
+    /** Attach a queue so /queue/* endpoints are available. */
+    withQueue(queue: SMSQueue): this;
+    /** Attach a MetricsPlugin to expose /metrics. */
+    withMetrics(plugin: {
+        snapshot: () => MetricsSnapshot;
+    }): this;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private _handle;
+    private _send;
+    private _sendMany;
+    private _sendObject;
+    private _sendObjectMany;
+    private _enqueue;
+    private _schedule;
+    private _queueStats;
+    private _queueCancel;
+    private _health;
+    private _metrics;
+    private _json;
+    private _readBody;
+}