bridgex 1.0.0 → 2.0.1

package/dist/SMSService.js

@@ -0,0 +1,214 @@
+/**
+ * SMSService — run the SDK as a standalone HTTP microservice.
+ *
+ * Exposes the full SMS API over REST so any other service (Python, Go, Ruby, …)
+ * can send messages without bundling the SDK itself.
+ *
+ * Built on Node's built-in http module — zero extra dependencies.
+ *
+ * Routes
+ * ──────
+ * POST /send               — send a single message
+ * POST /send/many          — send to many recipients
+ * POST /send/object        — send from a plain object
+ * POST /send/object/many   — send objects to many recipients
+ * POST /queue/enqueue      — fire-and-forget via queue
+ * POST /queue/schedule     — schedule a future send
+ * GET  /queue/stats        — queue stats
+ * DELETE /queue/:id        — cancel a queued job
+ * GET  /health             — liveness check
+ * GET  /metrics            — metrics snapshot (if MetricsPlugin attached)
+ *
+ * @example
+ * const service = new SMSService(client, { port: 4000, apiKey: "secret" });
+ * service.withQueue(queue).withMetrics(metricsPlugin);
+ * await service.start();
+ *
+ * // From any other service:
+ * // POST http://localhost:4000/send
+ * // Headers: x-service-key: secret
+ * // Body: { "to": "+1555…", "template": "Hello {name}", "variables": { "name": "Alice" } }
+ */
+import { createServer, } from "node:http";
+export default class SMSService {
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+        this.server = createServer((req, res) => this._handle(req, res));
+        this.startedAt = new Date();
+    }
+    /** Attach a queue so /queue/* endpoints are available. */
+    withQueue(queue) {
+        this.queue = queue;
+        return this;
+    }
+    /** Attach a MetricsPlugin to expose /metrics. */
+    withMetrics(plugin) {
+        this.metricsSnapshot = () => plugin.snapshot();
+        return this;
+    }
+    start() {
+        const { port = 3001, host = "0.0.0.0" } = this.options;
+        return new Promise((resolve) => {
+            this.server.listen(port, host, () => {
+                console.log(`[SMSService] Listening on http://${host}:${port}`);
+                resolve();
+            });
+        });
+    }
+    stop() {
+        return new Promise((resolve, reject) => this.server.close((err) => (err ? reject(err) : resolve())));
+    }
+    // ── Request handler ──────────────────────────────────────────────────────
+    async _handle(req, res) {
+        const { apiKey, timeout = 10000 } = this.options;
+        // Auth
+        if (apiKey && req.headers["x-service-key"] !== apiKey) {
+            return this._json(res, 401, { error: "Unauthorized" });
+        }
+        // Timeout guard
+        const timer = setTimeout(() => {
+            res.writeHead(504);
+            res.end(JSON.stringify({ error: "Gateway timeout" }));
+        }, timeout);
+        try {
+            const url = req.url?.split("?")[0] ?? "/";
+            const method = req.method ?? "GET";
+            // ── GET routes ──
+            if (method === "GET") {
+                if (url === "/health")
+                    return this._health(res);
+                if (url === "/metrics")
+                    return this._metrics(res);
+                if (url === "/queue/stats")
+                    return this._queueStats(res);
+                return this._json(res, 404, { error: "Not found" });
+            }
+            // ── DELETE routes ──
+            if (method === "DELETE") {
+                const match = url.match(/^\/queue\/(.+)$/);
+                if (match)
+                    return this._queueCancel(res, match[1]);
+                return this._json(res, 404, { error: "Not found" });
+            }
+            // ── POST routes ──
+            if (method === "POST") {
+                const body = await this._readBody(req);
+                if (url === "/send")
+                    return this._send(res, body);
+                if (url === "/send/many")
+                    return this._sendMany(res, body);
+                if (url === "/send/object")
+                    return this._sendObject(res, body);
+                if (url === "/send/object/many")
+                    return this._sendObjectMany(res, body);
+                if (url === "/queue/enqueue")
+                    return this._enqueue(res, body);
+                if (url === "/queue/schedule")
+                    return this._schedule(res, body);
+                return this._json(res, 404, { error: "Not found" });
+            }
+            this._json(res, 405, { error: "Method not allowed" });
+        }
+        catch (err) {
+            this._json(res, 500, { error: err.message ?? "Internal error" });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── Route handlers ────────────────────────────────────────────────────────
+    async _send(res, body) {
+        const result = await this.client.send(body);
+        this._json(res, result.ok ? 200 : 422, result);
+    }
+    async _sendMany(res, body) {
+        const { recipients, template, sharedVariables } = body;
+        const result = await this.client.sendMany(recipients, template, sharedVariables);
+        this._json(res, 200, result);
+    }
+    async _sendObject(res, body) {
+        const result = await this.client.sendObject(body);
+        this._json(res, result.ok ? 200 : 422, result);
+    }
+    async _sendObjectMany(res, body) {
+        const result = await this.client.sendObjectMany(body.items ?? body);
+        this._json(res, 200, result);
+    }
+    _enqueue(res, body) {
+        if (!this.queue)
+            return this._json(res, 503, { error: "Queue not configured" });
+        const id = this.queue.enqueue(body);
+        this._json(res, 202, { id, status: "queued" });
+    }
+    _schedule(res, body) {
+        if (!this.queue)
+            return this._json(res, 503, { error: "Queue not configured" });
+        const { at, delayMs, ...params } = body;
+        let id;
+        if (at) {
+            id = this.queue.enqueueAt(params, new Date(at).getTime());
+        }
+        else if (delayMs) {
+            id = this.queue.enqueueAfter(params, delayMs);
+        }
+        else {
+            return this._json(res, 400, {
+                error: "Provide 'at' (ISO date) or 'delayMs'",
+            });
+        }
+        this._json(res, 202, { id, status: "scheduled" });
+    }
+    _queueStats(res) {
+        if (!this.queue)
+            return this._json(res, 503, { error: "Queue not configured" });
+        this._json(res, 200, this.queue.stats());
+    }
+    _queueCancel(res, id) {
+        if (!this.queue)
+            return this._json(res, 503, { error: "Queue not configured" });
+        const ok = this.queue.cancel(id);
+        this._json(res, ok ? 200 : 404, { id, cancelled: ok });
+    }
+    _health(res) {
+        this._json(res, 200, {
+            status: "ok",
+            circuitState: this.client.circuitState,
+            uptime: Math.floor((Date.now() - this.startedAt.getTime()) / 1000),
+            startedAt: this.startedAt.toISOString(),
+            queue: this.queue?.stats() ?? null,
+        });
+    }
+    _metrics(res) {
+        if (!this.metricsSnapshot) {
+            return this._json(res, 503, {
+                error: "Metrics plugin not attached. Call .withMetrics()",
+            });
+        }
+        this._json(res, 200, this.metricsSnapshot());
+    }
+    // ── Helpers ──────────────────────────────────────────────────────────────
+    _json(res, status, body) {
+        const payload = JSON.stringify(body);
+        res.writeHead(status, {
+            "Content-Type": "application/json",
+            "Content-Length": Buffer.byteLength(payload),
+        });
+        res.end(payload);
+    }
+    _readBody(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            req.on("data", (c) => chunks.push(c));
+            req.on("end", () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
+                }
+                catch {
+                    reject(new Error("Invalid JSON body"));
+                }
+            });
+            req.on("error", reject);
+        });
+    }
+}

package/dist/SendConfig.d.ts

@@ -0,0 +1,90 @@
+import type { SendParams, SendObjectParams } from "./types.js";
+/**
+ * SendConfig — fluent builder for reusable send settings.
+ *
+ * Build once, reuse everywhere. Eliminates repeating template/variables
+ * across multiple send calls. Supports overrides per-call.
+ *
+ * @example
+ * const otpConfig = new SendConfig()
+ *   .template("Your verification code is {code}. Expires in {expiryMinutes} minutes.")
+ *   .defaults({ expiryMinutes: 10 })
+ *   .tag("otp");
+ *
+ * await client.send(otpConfig.for("+15551234567", { code: "482910" }));
+ *
+ * @example
+ * // Object config with auto-extraction
+ * const orderConfig = new SendConfig()
+ *   .template("Hi {customer.name}, your order {orderId} is {status}.")
+ *   .tag("order-notification");
+ *
+ * await client.sendObject(orderConfig.forObject("+15551234567", order));
+ */
+export default class SendConfig {
+    private _template?;
+    private _defaults;
+    private _tags;
+    private _ttl?;
+    private _priority;
+    private _dedupKey?;
+    /** Set the message template. Supports {variable} and {nested.path} placeholders. */
+    template(tpl: string): this;
+    /** Default variable values merged under per-call variables. */
+    defaults(vars: Record<string, unknown>): this;
+    /** Add a single default variable. */
+    set(key: string, value: unknown): this;
+    /** Tag this config (useful for logging, filtering, hooks). */
+    tag(...tags: string[]): this;
+    /**
+     * Time-to-live in milliseconds.
+     * Messages scheduled/queued past this age will be dropped.
+     */
+    ttl(ms: number): this;
+    /** Queue priority. High-priority jobs jump the queue. */
+    priority(p: "low" | "normal" | "high"): this;
+    /**
+     * Deduplication key.
+     * If two messages with the same dedupKey are enqueued within the TTL window,
+     * the second is silently dropped.
+     */
+    dedupKey(key: string): this;
+    /** Build a SendParams for a single recipient. Variables override defaults. */
+    for(to: string, variables?: Record<string, unknown>): SendParams & SendMeta;
+    /** Build a SendObjectParams for a single recipient. */
+    forObject<T extends Record<string, unknown>>(to: string, object: T): SendObjectParams<T> & SendMeta;
+    /**
+     * Build SendParams for many recipients from an array.
+     * Each recipient entry can supply per-recipient variables.
+     */
+    forMany(recipients: Array<{
+        to: string;
+        variables?: Record<string, unknown>;
+    }>): Array<SendParams & SendMeta>;
+    /** Produce the metadata snapshot for queuing / logging. */
+    meta(): SendMeta["_meta"];
+    /** Clone this config so you can branch without mutating the original. */
+    clone(): SendConfig;
+    /**
+     * Merge another config on top of this one (other wins on conflicts).
+     * Returns a new config — neither is mutated.
+     */
+    merge(other: SendConfig): SendConfig;
+    /** Create an OTP config. */
+    static otp(expiryMinutes?: number): SendConfig;
+    /** Create an order-notification config. */
+    static orderNotification(): SendConfig;
+    /** Create a reminder config. */
+    static reminder(): SendConfig;
+    /** Create a marketing/promo config. */
+    static promo(): SendConfig;
+}
+export interface SendMeta {
+    _meta: {
+        tags: string[];
+        ttl?: number;
+        priority: "low" | "normal" | "high";
+        dedupKey?: string;
+        createdAt: number;
+    };
+}

package/dist/SendConfig.js

@@ -0,0 +1,165 @@
+/**
+ * SendConfig — fluent builder for reusable send settings.
+ *
+ * Build once, reuse everywhere. Eliminates repeating template/variables
+ * across multiple send calls. Supports overrides per-call.
+ *
+ * @example
+ * const otpConfig = new SendConfig()
+ *   .template("Your verification code is {code}. Expires in {expiryMinutes} minutes.")
+ *   .defaults({ expiryMinutes: 10 })
+ *   .tag("otp");
+ *
+ * await client.send(otpConfig.for("+15551234567", { code: "482910" }));
+ *
+ * @example
+ * // Object config with auto-extraction
+ * const orderConfig = new SendConfig()
+ *   .template("Hi {customer.name}, your order {orderId} is {status}.")
+ *   .tag("order-notification");
+ *
+ * await client.sendObject(orderConfig.forObject("+15551234567", order));
+ */
+export default class SendConfig {
+    constructor() {
+        this._defaults = {};
+        this._tags = [];
+        this._priority = "normal";
+    }
+    // ── Builder methods ──────────────────────────────────────────────────────
+    /** Set the message template. Supports {variable} and {nested.path} placeholders. */
+    template(tpl) {
+        this._template = tpl;
+        return this;
+    }
+    /** Default variable values merged under per-call variables. */
+    defaults(vars) {
+        this._defaults = { ...this._defaults, ...vars };
+        return this;
+    }
+    /** Add a single default variable. */
+    set(key, value) {
+        this._defaults[key] = value;
+        return this;
+    }
+    /** Tag this config (useful for logging, filtering, hooks). */
+    tag(...tags) {
+        this._tags.push(...tags);
+        return this;
+    }
+    /**
+     * Time-to-live in milliseconds.
+     * Messages scheduled/queued past this age will be dropped.
+     */
+    ttl(ms) {
+        this._ttl = ms;
+        return this;
+    }
+    /** Queue priority. High-priority jobs jump the queue. */
+    priority(p) {
+        this._priority = p;
+        return this;
+    }
+    /**
+     * Deduplication key.
+     * If two messages with the same dedupKey are enqueued within the TTL window,
+     * the second is silently dropped.
+     */
+    dedupKey(key) {
+        this._dedupKey = key;
+        return this;
+    }
+    // ── Materialise ──────────────────────────────────────────────────────────
+    /** Build a SendParams for a single recipient. Variables override defaults. */
+    for(to, variables) {
+        if (!this._template) {
+            throw new Error("SendConfig: template is required. Call .template() first.");
+        }
+        return {
+            to,
+            template: this._template,
+            variables: { ...this._defaults, ...variables },
+            _meta: this.meta(),
+        };
+    }
+    /** Build a SendObjectParams for a single recipient. */
+    forObject(to, object) {
+        return {
+            to,
+            object,
+            template: this._template,
+            _meta: this.meta(),
+        };
+    }
+    /**
+     * Build SendParams for many recipients from an array.
+     * Each recipient entry can supply per-recipient variables.
+     */
+    forMany(recipients) {
+        return recipients.map((r) => this.for(r.to, r.variables));
+    }
+    /** Produce the metadata snapshot for queuing / logging. */
+    meta() {
+        return {
+            tags: [...this._tags],
+            ttl: this._ttl,
+            priority: this._priority,
+            dedupKey: this._dedupKey,
+            createdAt: Date.now(),
+        };
+    }
+    // ── Presets ──────────────────────────────────────────────────────────────
+    /** Clone this config so you can branch without mutating the original. */
+    clone() {
+        const c = new SendConfig();
+        c._template = this._template;
+        c._defaults = { ...this._defaults };
+        c._tags = [...this._tags];
+        c._ttl = this._ttl;
+        c._priority = this._priority;
+        c._dedupKey = this._dedupKey;
+        return c;
+    }
+    /**
+     * Merge another config on top of this one (other wins on conflicts).
+     * Returns a new config — neither is mutated.
+     */
+    merge(other) {
+        return this.clone()
+            .template(other._template ?? this._template ?? "")
+            .defaults({ ...this._defaults, ...other._defaults })
+            .tag(...other._tags)
+            .priority(other._priority);
+    }
+    // ── Static factories ─────────────────────────────────────────────────────
+    /** Create an OTP config. */
+    static otp(expiryMinutes = 10) {
+        return new SendConfig()
+            .template("Your verification code is {code}. Expires in {expiryMinutes} minutes.")
+            .defaults({ expiryMinutes })
+            .tag("otp")
+            .ttl(expiryMinutes * 60 * 1000)
+            .priority("high");
+    }
+    /** Create an order-notification config. */
+    static orderNotification() {
+        return new SendConfig()
+            .template("Hi {name}, your order #{orderId} is now {status}.")
+            .tag("order")
+            .priority("normal");
+    }
+    /** Create a reminder config. */
+    static reminder() {
+        return new SendConfig()
+            .template("Reminder: {message}")
+            .tag("reminder")
+            .priority("low");
+    }
+    /** Create a marketing/promo config. */
+    static promo() {
+        return new SendConfig()
+            .template("{promoMessage}")
+            .tag("promo", "marketing")
+            .priority("low");
+    }
+}

package/dist/errors.d.ts

@@ -1,7 +1,17 @@
 declare class SMSClientError extends Error {
     code: string;
     details?: unknown;
-    constructor(message: string, code: string, details?: unknown);
+    isClientError: boolean;
+    isServerError: boolean;
+    constructor(message: string, code: string, details?: unknown, isClientError?: boolean, isServerError?: boolean);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        details: unknown;
+        isClientError: boolean;
+        isServerError: boolean;
+    };
 }
 export declare class ServerError extends SMSClientError {
     constructor(message: string, details?: unknown);
@@ -15,4 +25,11 @@ export declare class TemplateError extends SMSClientError {
 export declare class NetworkError extends SMSClientError {
     constructor(message: string, details?: unknown);
 }
+export declare class RateLimitError extends SMSClientError {
+    retryAfter?: number;
+    constructor(message: string, retryAfter?: number, details?: unknown);
+}
+export declare class CircuitOpenError extends SMSClientError {
+    constructor(message: string, details?: unknown);
+}
 export {};

package/dist/errors.js

@@ -1,29 +1,52 @@
 class SMSClientError extends Error {
-    constructor(message, code, details) {
+    constructor(message, code, details, isClientError = false, isServerError = false) {
         super(message);
         this.name = this.constructor.name;
         this.code = code;
         this.details = details;
+        this.isClientError = isClientError;
+        this.isServerError = isServerError;
         Object.setPrototypeOf(this, new.target.prototype);
     }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            details: this.details,
+            isClientError: this.isClientError,
+            isServerError: this.isServerError,
+        };
+    }
 }
 export class ServerError extends SMSClientError {
     constructor(message, details) {
-        super(message, "SERVER_ERROR", details);
+        super(message, "SERVER_ERROR", details, false, true);
     }
 }
 export class ValidationError extends SMSClientError {
     constructor(message, details) {
-        super(message, "VALIDATION_ERROR", details);
+        super(message, "VALIDATION_ERROR", details, true, false);
     }
 }
 export class TemplateError extends SMSClientError {
     constructor(message, details) {
-        super(message, "TEMPLATE_ERROR", details);
+        super(message, "TEMPLATE_ERROR", details, true, false);
     }
 }
 export class NetworkError extends SMSClientError {
     constructor(message, details) {
-        super(message, "NETWORK_ERROR", details);
+        super(message, "NETWORK_ERROR", details, false, false);
+    }
+}
+export class RateLimitError extends SMSClientError {
+    constructor(message, retryAfter, details) {
+        super(message, "RATE_LIMIT_ERROR", details, false, true);
+        this.retryAfter = retryAfter;
+    }
+}
+export class CircuitOpenError extends SMSClientError {
+    constructor(message, details) {
+        super(message, "CIRCUIT_OPEN", details, false, false);
     }
 }

package/dist/helpers.d.ts

@@ -0,0 +1,3 @@
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function flattenObject(obj: Record<string, unknown>, prefix?: string, separator?: string): Record<string, string>;
+export declare function chunkArray<T>(array: T[], size: number): T[][];

package/dist/helpers.js

@@ -0,0 +1,23 @@
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function flattenObject(obj, prefix = "", separator = ".") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}${separator}${key}` : key;
+        if (isObject(value)) {
+            Object.assign(result, flattenObject(value, fullKey, separator));
+        }
+        else if (value !== null && value !== undefined) {
+            result[fullKey] = String(value);
+        }
+    }
+    return result;
+}
+export function chunkArray(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}

package/dist/main.d.ts

@@ -1 +1,20 @@
-export { SMSClient } from "./client/SMSManager.js";
+export { default as SMSClient } from "./SMSClient.js";
+export type { SMSClientOptions } from "./SMSClient.js";
+export { default as SendConfig } from "./SendConfig.js";
+export type { SendMeta } from "./SendConfig.js";
+export { default as SMSService } from "./SMSService.js";
+export type { SMSServiceOptions } from "./SMSService.js";
+export { default as SMSQueue } from "./SMSQueue.js";
+export type { QueueOptions, QueueStats, QueueJob } from "./SMSQueue.js";
+export { default as SMSScheduler } from "./SMSScheduler.js";
+export type { ScheduledJob } from "./SMSScheduler.js";
+export { default as PluginManager, LoggerPlugin, MetricsPlugin, } from "./PluginManager.js";
+export type { Plugin, PluginHooks, MetricsSnapshot } from "./PluginManager.js";
+export { default as CredentialProvisioner, type ProvisionOptions, type Credentials, } from "./CredentialProvisioner.js";
+export { default as CircuitBreaker } from "./CircuitBreaker.js";
+export type { CircuitBreakerOptions } from "./CircuitBreaker.js";
+export { default as RetryHandler } from "./RetryHandler.js";
+export type { RetryOptions } from "./RetryHandler.js";
+export { default as MessageFormatter } from "./MessageFormatter.js";
+export { ServerError, ValidationError, TemplateError, NetworkError, RateLimitError, CircuitOpenError, } from "./errors.js";
+export type { Result, ErrorLog, SendParams, SendObjectParams, BatchResult, } from "./types.js";

package/dist/main.js

@@ -1 +1,19 @@
-export { SMSClient } from "./client/SMSManager.js";
+// Core client
+export { default as SMSClient } from "./SMSClient.js";
+// Config builder
+export { default as SendConfig } from "./SendConfig.js";
+// Microservice
+export { default as SMSService } from "./SMSService.js";
+// Queue & Scheduler
+export { default as SMSQueue } from "./SMSQueue.js";
+export { default as SMSScheduler } from "./SMSScheduler.js";
+// Plugins
+export { default as PluginManager, LoggerPlugin, MetricsPlugin, } from "./PluginManager.js";
+// Credential provisioning
+export { default as CredentialProvisioner, } from "./CredentialProvisioner.js";
+// Lower-level building blocks (advanced use)
+export { default as CircuitBreaker } from "./CircuitBreaker.js";
+export { default as RetryHandler } from "./RetryHandler.js";
+export { default as MessageFormatter } from "./MessageFormatter.js";
+// Errors
+export { ServerError, ValidationError, TemplateError, NetworkError, RateLimitError, CircuitOpenError, } from "./errors.js";

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+export type Result<T> = {
+    ok: true;
+    data: T;
+    error: null;
+} | {
+    ok: false;
+    data: null;
+    error: ErrorLog;
+};
+export interface ErrorLog {
+    name: string;
+    message: string;
+    code: string;
+    isClientError: boolean;
+    isServerError: boolean;
+    details?: unknown;
+    timestamp: string;
+}
+export interface SendParams {
+    to: string;
+    template: string;
+    variables?: Record<string, unknown>;
+}
+export interface SendObjectParams<T extends Record<string, unknown>> {
+    to: string;
+    object: T;
+    template?: string;
+}
+export interface BatchResult<T> {
+    succeeded: Array<{
+        index: number;
+        to: string;
+        data: T;
+    }>;
+    failed: Array<{
+        index: number;
+        to: string;
+        error: ErrorLog;
+    }>;
+    total: number;
+    successCount: number;
+    failureCount: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};