bridgex 1.0.0 → 2.0.1

package/dist/MessageFormatter.js

@@ -1,21 +1,45 @@
 import { TemplateError, ValidationError } from "./errors.js";
-import { isObject } from "./help.js";
+import { isObject, flattenObject } from "./helpers.js";
 export default class MessageFormatter {
+    /**
+     * Format a template string with variables.
+     * Supports {key} and {nested.key} (for nested objects) placeholders.
+     */
     format(template, params = {}) {
         if (typeof template !== "string" || template.trim() === "") {
             throw new ValidationError("Message template must be a non-empty string");
         }
-        return template.replace(/\{(\w+)\}/g, (_, key) => {
-            if (!(key in params)) {
+        const flat = flattenObject(params);
+        return template.replace(/\{([\w.]+)\}/g, (_, key) => {
+            if (!(key in flat)) {
                 throw new TemplateError(`Missing template variable: ${key}`);
             }
-            return String(params[key]);
+            return flat[key];
         });
     }
-    fromObject(obj) {
+    /**
+     * Extract a message from a plain object by looking for common message fields,
+     * then fall back to JSON serialisation.
+     */
+    fromObject(obj, template) {
         if (!isObject(obj)) {
             throw new ValidationError("Message object must be a valid object");
         }
-        return JSON.stringify(obj);
+        const variables = flattenObject(obj);
+        if (template) {
+            return { message: this.format(template, obj), variables };
+        }
+        // Auto-detect a message field from the object
+        const messageCandidates = ["message", "body", "text", "content", "sms"];
+        for (const candidate of messageCandidates) {
+            if (typeof obj[candidate] === "string" && obj[candidate]) {
+                return { message: obj[candidate], variables };
+            }
+        }
+        // Fall back to serialised JSON
+        return { message: JSON.stringify(obj), variables };
+    }
+    fromObject2String(obj) {
+        return this.fromObject(obj).message;
     }
 }

package/dist/PluginManager.d.ts

@@ -0,0 +1,77 @@
+import type { ErrorLog } from "./types.js";
+export interface HookContext {
+    to: string;
+    message?: string;
+    template?: string;
+    tags?: string[];
+    attempt?: number;
+    durationMs?: number;
+}
+export interface PluginHooks {
+    /** Called before every send attempt */
+    onSend?: (ctx: HookContext) => void | Promise<void>;
+    /** Called after a successful send */
+    onSuccess?: (ctx: HookContext & {
+        data: unknown;
+    }) => void | Promise<void>;
+    /** Called after a failed send (after all retries) */
+    onError?: (ctx: HookContext & {
+        error: ErrorLog;
+    }) => void | Promise<void>;
+    /** Called on each retry attempt */
+    onRetry?: (ctx: HookContext & {
+        attempt: number;
+        error: ErrorLog;
+    }) => void | Promise<void>;
+    /** Called when a job is dropped (TTL expired or dedup) */
+    onDrop?: (ctx: HookContext & {
+        reason: "ttl" | "dedup";
+    }) => void | Promise<void>;
+}
+export type Plugin = PluginHooks & {
+    name: string;
+};
+/**
+ * PluginManager — registers plugins and fires lifecycle hooks.
+ *
+ * @example
+ * const plugins = new PluginManager();
+ * plugins.use(LoggerPlugin("my-service"));
+ * plugins.use(MetricsPlugin(prometheusRegistry));
+ */
+export default class PluginManager {
+    private plugins;
+    use(plugin: Plugin): this;
+    remove(name: string): this;
+    fire<K extends keyof PluginHooks>(hook: K, ctx: Parameters<NonNullable<PluginHooks[K]>>[0]): Promise<void>;
+}
+/**
+ * Console logger plugin.
+ * @example plugins.use(LoggerPlugin("order-service"));
+ */
+export declare function LoggerPlugin(serviceName?: string): Plugin;
+/**
+ * In-memory metrics plugin. Exposes `.snapshot()` for health-check endpoints.
+ *
+ * @example
+ * const metrics = MetricsPlugin();
+ * plugins.use(metrics);
+ * // later:
+ * console.log(metrics.snapshot());
+ */
+export declare function MetricsPlugin(): Plugin & {
+    snapshot: () => MetricsSnapshot;
+    reset: () => void;
+};
+export interface MetricsSnapshot {
+    sent: number;
+    succeeded: number;
+    failed: number;
+    dropped: number;
+    retries: number;
+    totalDurationMs: number;
+    errorCodes: Record<string, number>;
+    successRate: number;
+    avgDurationMs: number;
+    capturedAt: string;
+}

package/dist/PluginManager.js

@@ -0,0 +1,101 @@
+/**
+ * PluginManager — registers plugins and fires lifecycle hooks.
+ *
+ * @example
+ * const plugins = new PluginManager();
+ * plugins.use(LoggerPlugin("my-service"));
+ * plugins.use(MetricsPlugin(prometheusRegistry));
+ */
+export default class PluginManager {
+    constructor() {
+        this.plugins = [];
+    }
+    use(plugin) {
+        this.plugins.push(plugin);
+        return this;
+    }
+    remove(name) {
+        this.plugins = this.plugins.filter((p) => p.name !== name);
+        return this;
+    }
+    async fire(hook, ctx) {
+        for (const plugin of this.plugins) {
+            const fn = plugin[hook];
+            if (fn) {
+                try {
+                    await fn(ctx);
+                }
+                catch (err) {
+                    // Plugins must never crash the main flow
+                    console.error(`[SMSPlugin:${plugin.name}] hook "${hook}" threw:`, err);
+                }
+            }
+        }
+    }
+}
+// ── Built-in plugins ────────────────────────────────────────────────────────
+/**
+ * Console logger plugin.
+ * @example plugins.use(LoggerPlugin("order-service"));
+ */
+export function LoggerPlugin(serviceName = "sms-sdk") {
+    return {
+        name: "logger",
+        onSend: ({ to, tags }) => console.log(`[${serviceName}] → sending to ${to}${tags?.length ? ` [${tags.join(", ")}]` : ""}`),
+        onSuccess: ({ to, durationMs }) => console.log(`[${serviceName}] ✓ delivered to ${to} in ${durationMs}ms`),
+        onError: ({ to, error }) => console.error(`[${serviceName}] ✗ failed to ${to}: [${error.code}] ${error.message}`),
+        onRetry: ({ to, attempt, error }) => console.warn(`[${serviceName}] ↻ retry #${attempt} for ${to}: ${error.message}`),
+        onDrop: ({ to, reason }) => console.warn(`[${serviceName}] ⊘ dropped job for ${to} (${reason})`),
+    };
+}
+/**
+ * In-memory metrics plugin. Exposes `.snapshot()` for health-check endpoints.
+ *
+ * @example
+ * const metrics = MetricsPlugin();
+ * plugins.use(metrics);
+ * // later:
+ * console.log(metrics.snapshot());
+ */
+export function MetricsPlugin() {
+    const state = {
+        sent: 0,
+        succeeded: 0,
+        failed: 0,
+        dropped: 0,
+        retries: 0,
+        totalDurationMs: 0,
+        errorCodes: {},
+    };
+    return {
+        name: "metrics",
+        onSend: () => { state.sent++; },
+        onSuccess: ({ durationMs = 0 }) => {
+            state.succeeded++;
+            state.totalDurationMs += durationMs;
+        },
+        onError: ({ error }) => {
+            state.failed++;
+            state.errorCodes[error.code] = (state.errorCodes[error.code] ?? 0) + 1;
+        },
+        onRetry: () => { state.retries++; },
+        onDrop: () => { state.dropped++; },
+        snapshot() {
+            return {
+                ...state,
+                successRate: state.sent > 0 ? state.succeeded / state.sent : 0,
+                avgDurationMs: state.succeeded > 0 ? state.totalDurationMs / state.succeeded : 0,
+                capturedAt: new Date().toISOString(),
+            };
+        },
+        reset() {
+            state.sent = 0;
+            state.succeeded = 0;
+            state.failed = 0;
+            state.dropped = 0;
+            state.retries = 0;
+            state.totalDurationMs = 0;
+            state.errorCodes = {};
+        },
+    };
+}

package/dist/RetryHandler.d.ts

@@ -2,9 +2,16 @@ export interface RetryOptions {
     maxAttempts?: number;
     delay?: number;
     strategy?: "fixed" | "exponential";
+    jitter?: boolean;
+    /** Error codes that should NOT be retried (e.g. validation errors) */
+    nonRetryableCodes?: string[];
 }
 export default class RetryHandler {
-    private options;
+    private readonly maxAttempts;
+    private readonly delay;
+    private readonly strategy;
+    private readonly jitter;
+    private readonly nonRetryableCodes;
     constructor(options?: RetryOptions);
     execute<T>(operation: () => Promise<T>): Promise<T>;
 }

package/dist/RetryHandler.js

@@ -1,24 +1,46 @@
 import { setTimeout } from "node:timers/promises";
+import { RateLimitError } from "./errors.js";
 export default class RetryHandler {
     constructor(options = {}) {
-        this.options = options;
+        this.maxAttempts = options.maxAttempts ?? 3;
+        this.delay = options.delay ?? 500;
+        this.strategy = options.strategy ?? "fixed";
+        this.jitter = options.jitter ?? true;
+        this.nonRetryableCodes = new Set(options.nonRetryableCodes ?? ["VALIDATION_ERROR", "TEMPLATE_ERROR"]);
     }
     async execute(operation) {
-        const { maxAttempts = 3, delay = 500, strategy = "fixed" } = this.options;
         let attempt = 0;
-        while (attempt < maxAttempts) {
+        let lastError;
+        while (attempt < this.maxAttempts) {
             try {
                 return await operation();
             }
             catch (error) {
+                lastError = error;
                 attempt++;
-                if (attempt >= maxAttempts) {
+                // Don't retry client-side or non-retryable errors
+                if (error?.isClientError || this.nonRetryableCodes.has(error?.code)) {
                     throw error;
                 }
-                const waitTime = strategy === "exponential" ? delay * 2 ** (attempt - 1) : delay;
+                if (attempt >= this.maxAttempts)
+                    break;
+                // Respect Retry-After for rate limit errors
+                let waitTime;
+                if (error instanceof RateLimitError && error.retryAfter) {
+                    waitTime = error.retryAfter * 1000;
+                }
+                else {
+                    waitTime =
+                        this.strategy === "exponential"
+                            ? this.delay * 2 ** (attempt - 1)
+                            : this.delay;
+                    if (this.jitter) {
+                        waitTime += Math.random() * waitTime * 0.2;
+                    }
+                }
                 await setTimeout(waitTime);
             }
         }
-        throw new Error("Retry failed unexpectedly");
+        throw lastError;
     }
 }

package/dist/SMSClient.d.ts

@@ -0,0 +1,65 @@
+import { type RetryOptions } from "./RetryHandler.js";
+import { type CircuitBreakerOptions } from "./CircuitBreaker.js";
+import PluginManager, { type Plugin } from "./PluginManager.js";
+import type { Result, SendParams, SendObjectParams, BatchResult } from "./types.js";
+export interface SMSClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    projectKey: string;
+    retry?: RetryOptions;
+    circuitBreaker?: CircuitBreakerOptions;
+    /** Max concurrent requests when sending in bulk (default: 5) */
+    concurrency?: number;
+    /** Chunk size for sendMany (default: 50) */
+    batchSize?: number;
+    /** Plugins to attach at construction time */
+    plugins?: Plugin[];
+}
+export default class SMSClient {
+    private options;
+    private http;
+    private retry;
+    private circuit;
+    private formatter;
+    readonly plugins: PluginManager;
+    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(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.
+     */
+    sendMany(recipients: Array<{
+        to: string;
+        variables?: Record<string, unknown>;
+    }>, template: string, sharedVariables?: Record<string, unknown>): Promise<BatchResult<any>>;
+    /**
+     * 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.
+     */
+    sendObject<T extends Record<string, unknown>>(params: SendObjectParams<T> & {
+        _meta?: any;
+    }): Promise<Result<any>>;
+    /**
+     * 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

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