bridgex 2.0.0 → 2.1.0

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,14 @@ 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 declare class MaxLimitError extends SMSClientError {
+    constructor(message: string, details?: unknown);
+}
 export {};

package/dist/errors.js

@@ -1,29 +1,57 @@
 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);
+    }
+}
+export class MaxLimitError extends SMSClientError {
+    constructor(message, details) {
+        super(message, "MAX_LIMIT_ERROR", details, false, true);
     }
 }

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, FailedJob, AttemptRecord, } 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, MaxLimitError, } from "./errors.js";
+export type { Result, ErrorLog, SendParams, SendObjectParams, BatchResult, FailedItem, SucceededItem, } 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, MaxLimitError, } from "./errors.js";

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+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;
+    /** Optional template; if omitted the object's message/body/text field is used */
+    template?: string;
+}
+export interface SucceededItem<T> {
+    index: number;
+    to: string;
+    data: T;
+}
+export interface FailedItem {
+    index: number;
+    to: string;
+    error: ErrorLog;
+    /** The original params — preserved so you can re-enqueue or log without data loss */
+    originalParams: SendParams;
+}
+export interface BatchResult<T> {
+    succeeded: SucceededItem<T>[];
+    failed: FailedItem[];
+    total: number;
+    successCount: number;
+    failureCount: number;
+    /** True if the server hit a quota/max-limit and stopped sending */
+    hitMaxLimit: boolean;
+}

package/dist/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bridgex",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "a library for mazz app or a bridge for messaging that allow and automate the use of our service",
   "keywords": [
     "messaging",

package/src/HttpClient.ts

@@ -1,4 +1,9 @@
-import { NetworkError, ServerError } from "./errors.js";
+import {
+  NetworkError,
+  ServerError,
+  RateLimitError,
+  MaxLimitError,
+} from "./errors.js";
 
 interface HttpClientOptions {
   baseUrl: string;
@@ -7,6 +12,19 @@ interface HttpClientOptions {
   timeout?: number;
 }
 
+// Patterns that indicate a "max messages sent" quota error from the server
+const MAX_LIMIT_PATTERNS = [
+  /max.{0,20}(messages?|sms|send)/i,
+  /quota.{0,20}(exceeded|reached|exhausted)/i,
+  /limit.{0,20}reached/i,
+  /daily.{0,20}(limit|cap)/i,
+  /monthly.{0,20}(limit|cap)/i,
+];
+
+function isMaxLimitBody(text: string): boolean {
+  return MAX_LIMIT_PATTERNS.some((p) => p.test(text));
+}
+
 export default class HttpClient {
   constructor(private options: HttpClientOptions) {}
 
@@ -30,21 +48,47 @@ export default class HttpClient {
 
       clearTimeout(timeoutId);
 
+      if (response.status === 429) {
+        const retryAfter =
+          Number(response.headers.get("Retry-After")) || undefined;
+        throw new RateLimitError("Rate limit exceeded", retryAfter);
+      }
+
       if (!response.ok) {
         const text = await response.text();
-        throw new ServerError(`Server responded with ${response.status}`, text);
+
+        // Detect "max messages sent reached" specifically — not retryable
+        if (
+          response.status === 402 ||
+          response.status === 403 ||
+          isMaxLimitBody(text)
+        ) {
+          throw new MaxLimitError(
+            `Message quota exceeded (HTTP ${response.status})`,
+            { status: response.status, body: text },
+          );
+        }
+
+        throw new ServerError(`Server responded with ${response.status}`, {
+          status: response.status,
+          body: text,
+        });
       }
 
       return await response.json();
     } catch (error: any) {
+      clearTimeout(timeoutId);
+
       if (error.name === "AbortError") {
         throw new NetworkError("Request timed out");
       }
-
-      if (error instanceof ServerError) {
+      if (
+        error instanceof ServerError ||
+        error instanceof RateLimitError ||
+        error instanceof MaxLimitError
+      ) {
         throw error;
       }
-
       throw new NetworkError("Network request failed", error);
     }
   }