bridgex 1.0.0 → 2.0.1

package/package.json

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

package/src/CircuitBreaker.ts

@@ -0,0 +1,81 @@
+import { CircuitOpenError } from "./errors.js";
+
+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: CircuitState = "CLOSED";
+  private failures = 0;
+  private successes = 0;
+  private lastFailureTime = 0;
+
+  private readonly threshold: number;
+  private readonly timeout: number;
+  private readonly successThreshold: number;
+
+  constructor(options: CircuitBreakerOptions = {}) {
+    this.threshold = options.threshold ?? 5;
+    this.timeout = options.timeout ?? 30_000;
+    this.successThreshold = options.successThreshold ?? 2;
+  }
+
+  get currentState(): CircuitState {
+    return this.state;
+  }
+
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    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;
+    }
+  }
+
+  private onSuccess() {
+    if (this.state === "HALF_OPEN") {
+      this.successes++;
+      if (this.successes >= this.successThreshold) {
+        this.reset();
+      }
+    } else {
+      this.failures = 0;
+    }
+  }
+
+  private 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/src/CredentialProvisioner.ts

@@ -0,0 +1,68 @@
+import { ValidationError } from "./errors.js";
+
+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 async provision(options: ProvisionOptions): Promise<Credentials> {
+    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/src/MessageFormatter.ts

@@ -1,26 +1,57 @@
 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: string, params: Record<string, unknown> = {}): string {
     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 as Record<string, unknown>);
+
+    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: 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> } {
     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] as string, variables };
+      }
+    }
+
+    // Fall back to serialised JSON
+    return { message: JSON.stringify(obj), variables };
+  }
+
+  fromObject2String(obj: Record<string, unknown>): string {
+    return this.fromObject(obj).message;
   }
 }

package/src/PluginManager.ts

@@ -0,0 +1,155 @@
+import type { ErrorLog, SendParams } 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: Plugin[] = [];
+
+  use(plugin: Plugin): this {
+    this.plugins.push(plugin);
+    return this;
+  }
+
+  remove(name: string): this {
+    this.plugins = this.plugins.filter((p) => p.name !== name);
+    return this;
+  }
+
+  async fire<K extends keyof PluginHooks>(
+    hook: K,
+    ctx: Parameters<NonNullable<PluginHooks[K]>>[0]
+  ): Promise<void> {
+    for (const plugin of this.plugins) {
+      const fn = plugin[hook] as ((c: typeof ctx) => void | Promise<void>) | undefined;
+      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"): Plugin {
+  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(): Plugin & {
+  snapshot: () => MetricsSnapshot;
+  reset: () => void;
+} {
+  const state = {
+    sent: 0,
+    succeeded: 0,
+    failed: 0,
+    dropped: 0,
+    retries: 0,
+    totalDurationMs: 0,
+    errorCodes: {} as Record<string, number>,
+  };
+
+  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(): MetricsSnapshot {
+      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 = {};
+    },
+  };
+}
+
+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/src/RetryHandler.ts

@@ -1,36 +1,69 @@
 import { setTimeout } from "node:timers/promises";
+import { RateLimitError } from "./errors.js";
 
 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 {
-  constructor(private options: RetryOptions = {}) {}
+  private readonly maxAttempts: number;
+  private readonly delay: number;
+  private readonly strategy: "fixed" | "exponential";
+  private readonly jitter: boolean;
+  private readonly nonRetryableCodes: Set<string>;
 
-  async execute<T>(operation: () => Promise<T>): Promise<T> {
-    const { maxAttempts = 3, delay = 500, strategy = "fixed" } = this.options;
+  constructor(options: RetryOptions = {}) {
+    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<T>(operation: () => Promise<T>): Promise<T> {
     let attempt = 0;
+    let lastError: unknown;
 
-    while (attempt < maxAttempts) {
+    while (attempt < this.maxAttempts) {
       try {
         return await operation();
-      } catch (error) {
+      } catch (error: any) {
+        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: number;
+        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;
   }
 }