bridgex 2.0.0 → 2.0.1

package/dist/CircuitBreaker.d.ts

@@ -0,0 +1,25 @@
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures before opening the circuit */
+    threshold?: number;
+    /** Milliseconds to wait before transitioning to half-open */
+    timeout?: number;
+    /** Number of successful probes to close circuit from half-open */
+    successThreshold?: number;
+}
+type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+export default class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private readonly threshold;
+    private readonly timeout;
+    private readonly successThreshold;
+    constructor(options?: CircuitBreakerOptions);
+    get currentState(): CircuitState;
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    reset(): void;
+}
+export {};

package/dist/CircuitBreaker.js

@@ -0,0 +1,58 @@
+import { CircuitOpenError } from "./errors.js";
+export default class CircuitBreaker {
+    constructor(options = {}) {
+        this.state = "CLOSED";
+        this.failures = 0;
+        this.successes = 0;
+        this.lastFailureTime = 0;
+        this.threshold = options.threshold ?? 5;
+        this.timeout = options.timeout ?? 30000;
+        this.successThreshold = options.successThreshold ?? 2;
+    }
+    get currentState() {
+        return this.state;
+    }
+    async execute(operation) {
+        if (this.state === "OPEN") {
+            if (Date.now() - this.lastFailureTime >= this.timeout) {
+                this.state = "HALF_OPEN";
+                this.successes = 0;
+            }
+            else {
+                throw new CircuitOpenError("Circuit is open — service is temporarily unavailable");
+            }
+        }
+        try {
+            const result = await operation();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    onSuccess() {
+        if (this.state === "HALF_OPEN") {
+            this.successes++;
+            if (this.successes >= this.successThreshold) {
+                this.reset();
+            }
+        }
+        else {
+            this.failures = 0;
+        }
+    }
+    onFailure() {
+        this.failures++;
+        this.lastFailureTime = Date.now();
+        if (this.state === "HALF_OPEN" || this.failures >= this.threshold) {
+            this.state = "OPEN";
+        }
+    }
+    reset() {
+        this.state = "CLOSED";
+        this.failures = 0;
+        this.successes = 0;
+    }
+}

package/dist/CredentialProvisioner.d.ts

@@ -0,0 +1,27 @@
+export interface Credentials {
+    baseUrl: string;
+    apiKey: string;
+    projectKey: string;
+}
+export interface ProvisionOptions {
+    /** Your service's provisioning endpoint */
+    provisionUrl: string;
+    /** Master/admin key used to call the provisioning API */
+    adminKey: string;
+    projectName?: string;
+}
+/**
+ * CredentialProvisioner
+ *
+ * Calls your service's provisioning endpoint to automatically:
+ *  - Generate a new repo token (projectKey)
+ *  - Generate an access token (apiKey)
+ *  - Return the service URL
+ *
+ * Usage:
+ *   const creds = await CredentialProvisioner.provision({ provisionUrl, adminKey });
+ *   const client = new SMSClient(creds);
+ */
+export default class CredentialProvisioner {
+    static provision(options: ProvisionOptions): Promise<Credentials>;
+}

package/dist/CredentialProvisioner.js

@@ -0,0 +1,43 @@
+import { ValidationError } from "./errors.js";
+/**
+ * CredentialProvisioner
+ *
+ * Calls your service's provisioning endpoint to automatically:
+ *  - Generate a new repo token (projectKey)
+ *  - Generate an access token (apiKey)
+ *  - Return the service URL
+ *
+ * Usage:
+ *   const creds = await CredentialProvisioner.provision({ provisionUrl, adminKey });
+ *   const client = new SMSClient(creds);
+ */
+export default class CredentialProvisioner {
+    static async provision(options) {
+        const { provisionUrl, adminKey, projectName } = options;
+        if (!provisionUrl)
+            throw new ValidationError("provisionUrl is required");
+        if (!adminKey)
+            throw new ValidationError("adminKey is required");
+        const response = await fetch(provisionUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${adminKey}`,
+            },
+            body: JSON.stringify({ projectName }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Provisioning failed (${response.status}): ${text}`);
+        }
+        const data = await response.json();
+        // Accept either snake_case or camelCase field names from your API
+        const baseUrl = data.baseUrl ?? data.base_url ?? data.url ?? data.serviceUrl;
+        const apiKey = data.apiKey ?? data.api_key ?? data.accessToken ?? data.access_token;
+        const projectKey = data.projectKey ?? data.project_key ?? data.repoToken ?? data.repo_token;
+        if (!baseUrl || !apiKey || !projectKey) {
+            throw new Error("Provisioning response is missing required fields (baseUrl, apiKey, projectKey)");
+        }
+        return { baseUrl, apiKey, projectKey };
+    }
+}

package/dist/MessageFormatter.d.ts

@@ -1,4 +1,16 @@
 export default class MessageFormatter {
+    /**
+     * Format a template string with variables.
+     * Supports {key} and {nested.key} (for nested objects) placeholders.
+     */
     format(template: string, params?: Record<string, unknown>): string;
-    fromObject(obj: Record<string, unknown>): string;
+    /**
+     * Extract a message from a plain object by looking for common message fields,
+     * then fall back to JSON serialisation.
+     */
+    fromObject(obj: Record<string, unknown>, template?: string): {
+        message: string;
+        variables: Record<string, string>;
+    };
+    fromObject2String(obj: Record<string, unknown>): string;
 }

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