bridgex 1.0.0 → 2.0.1

package/src/SMSClient.ts

@@ -0,0 +1,308 @@
+import HttpClient from "./HttpClient.js";
+import RetryHandler, { type RetryOptions } from "./RetryHandler.js";
+import CircuitBreaker, {
+  type CircuitBreakerOptions,
+} from "./CircuitBreaker.js";
+import MessageFormatter from "./MessageFormatter.js";
+import PluginManager, { type Plugin } from "./PluginManager.js";
+import { ValidationError } from "./errors.js";
+import { chunkArray } from "./helpers.js";
+import type {
+  Result,
+  ErrorLog,
+  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[];
+}
+
+function toErrorLog(error: unknown): ErrorLog {
+  if (error instanceof Error) {
+    const e = error as any;
+    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<T>(data: T): Result<T> {
+  return { ok: true, data, error: null };
+}
+
+function fail<T>(error: unknown): Result<T> {
+  return { ok: false, data: null, error: toErrorLog(error) };
+}
+
+export default class SMSClient {
+  private http: HttpClient;
+  private retry: RetryHandler;
+  private circuit: CircuitBreaker;
+  private formatter: MessageFormatter;
+  readonly plugins: PluginManager;
+  private concurrency: number;
+  private batchSize: number;
+
+  constructor(private options: SMSClientOptions) {
+    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: Plugin): this {
+    this.plugins.use(plugin);
+    return this;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Core internal send — all public methods funnel through here
+  // ─────────────────────────────────────────────────────────────────────────
+
+  private async _send(
+    to: string,
+    message: string,
+    tags: string[] = [],
+  ): Promise<any> {
+    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: SendParams & { _meta?: any }): Promise<Result<any>> {
+    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: Array<{ to: string; variables?: Record<string, unknown> }>,
+    template: string,
+    sharedVariables: Record<string, unknown> = {},
+  ): Promise<BatchResult<any>> {
+    const result: BatchResult<any> = {
+      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<T extends Record<string, unknown>>(
+    params: SendObjectParams<T> & { _meta?: any },
+  ): Promise<Result<any>> {
+    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<T extends Record<string, unknown>>(
+    items: Array<SendObjectParams<T> & { _meta?: any }>,
+  ): Promise<BatchResult<any>> {
+    const result: BatchResult<any> = {
+      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();
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+
+  private validateOptions(options: SMSClientOptions): void {
+    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/src/SMSQueue.ts

@@ -0,0 +1,281 @@
+import type SMSClient from "./SMSClient.js";
+import type PluginManager from "./PluginManager.js";
+import type { SendParams, Result } from "./types.js";
+import type { SendMeta } from "./SendConfig.js";
+
+type Priority = "low" | "normal" | "high";
+const PRIORITY_WEIGHT: Record<Priority, number> = {
+  high: 3,
+  normal: 2,
+  low: 1,
+};
+
+export interface QueueJob {
+  id: string;
+  params: SendParams;
+  meta: SendMeta["_meta"];
+  scheduledAt: number; // epoch ms — 0 = immediately
+  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 jobs: QueueJob[] = [];
+  private dedupSet = new Set<string>();
+  private running = 0;
+  private completed = 0;
+  private dropped = 0;
+  private pollTimer?: ReturnType<typeof setInterval>;
+  private readonly concurrency: number;
+  private readonly pollInterval: number;
+  private readonly autoStart: boolean;
+  private plugins?: PluginManager;
+
+  constructor(
+    private client: SMSClient,
+    options: QueueOptions = {},
+    plugins?: PluginManager,
+  ) {
+    this.concurrency = options.concurrency ?? 3;
+    this.pollInterval = options.pollInterval ?? 1000;
+    this.autoStart = options.autoStart ?? true;
+    this.plugins = plugins;
+  }
+
+  // ── Enqueue ──────────────────────────────────────────────────────────────
+
+  /** Enqueue a job for immediate (or next-available) processing. */
+  enqueue(params: SendParams & Partial<SendMeta>): string {
+    return this._enqueue(params, 0);
+  }
+
+  /** Enqueue a job to send at a specific future timestamp (epoch ms). */
+  enqueueAt(params: SendParams & Partial<SendMeta>, timestamp: number): string {
+    return this._enqueue(params, timestamp);
+  }
+
+  /** Enqueue a job to send after a delay (ms). */
+  enqueueAfter(
+    params: SendParams & Partial<SendMeta>,
+    delayMs: number,
+  ): string {
+    return this._enqueue(params, Date.now() + delayMs);
+  }
+
+  private _enqueue(
+    params: SendParams & Partial<SendMeta>,
+    scheduledAt: number,
+  ): string {
+    const meta = (params as any)._meta ?? {
+      tags: [],
+      priority: "normal" as Priority,
+      createdAt: Date.now(),
+    };
+
+    // Deduplication
+    if (meta.dedupKey) {
+      if (this.dedupSet.has(meta.dedupKey)) {
+        this.dropped++;
+        this.plugins?.fire("onDrop", {
+          to: params.to,
+          tags: meta.tags,
+          reason: "dedup",
+        });
+        return meta.dedupKey; // return key so caller can identify it
+      }
+      this.dedupSet.add(meta.dedupKey);
+    }
+
+    const id =
+      meta.dedupKey ??
+      `job_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    const job: QueueJob = {
+      id,
+      params,
+      meta,
+      scheduledAt,
+      enqueuedAt: Date.now(),
+      attempts: 0,
+    };
+
+    this._insertByPriority(job);
+
+    if (this.autoStart && !this.pollTimer) {
+      this.start();
+    }
+
+    return id;
+  }
+
+  private _insertByPriority(job: QueueJob) {
+    const w = PRIORITY_WEIGHT[job.meta.priority as Priority] ?? 2;
+    // Find insertion point: higher weight jobs go first
+    let i = 0;
+    while (
+      i < this.jobs.length &&
+      PRIORITY_WEIGHT[(this.jobs[i].meta.priority as Priority) ?? "normal"] >= w
+    )
+      i++;
+    this.jobs.splice(i, 0, job);
+  }
+
+  // ── Lifecycle ────────────────────────────────────────────────────────────
+
+  /** Start the queue workers. */
+  start(): this {
+    if (this.pollTimer) return this;
+    this.pollTimer = setInterval(() => this._tick(), this.pollInterval);
+    this._tick(); // immediate first tick
+    return this;
+  }
+
+  /** Drain the queue (process remaining jobs) then stop. */
+  async drain(): Promise<void> {
+    this.stop();
+    while (this.jobs.length > 0 || this.running > 0) {
+      await new Promise((r) => setTimeout(r, 50));
+      this._tick();
+    }
+  }
+
+  /** Stop polling. In-flight jobs still complete. */
+  stop(): this {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = undefined;
+    }
+    return this;
+  }
+
+  // ── Processing ───────────────────────────────────────────────────────────
+
+  private _tick() {
+    const now = Date.now();
+
+    while (this.running < this.concurrency && this.jobs.length > 0) {
+      // Find next ready job (scheduledAt <= now)
+      const idx = this.jobs.findIndex((j) => j.scheduledAt <= now);
+      if (idx === -1) break;
+
+      const [job] = this.jobs.splice(idx, 1);
+      this._process(job);
+    }
+  }
+
+  private async _process(job: QueueJob) {
+    const { params, meta } = job;
+    const now = Date.now();
+
+    // TTL check
+    if (meta.ttl && now - meta.createdAt > meta.ttl) {
+      this.dropped++;
+      if (meta.dedupKey) this.dedupSet.delete(meta.dedupKey);
+      await this.plugins?.fire("onDrop", {
+        to: params.to,
+        tags: meta.tags,
+        reason: "ttl",
+      });
+      return;
+    }
+
+    this.running++;
+    const start = Date.now();
+    await this.plugins?.fire("onSend", {
+      to: params.to,
+      tags: meta.tags,
+      template: params.template,
+    });
+
+    const result = (await (this.client as any).send(params)) as Result<any>;
+
+    this.running--;
+    const durationMs = Date.now() - start;
+
+    if (result.ok) {
+      this.completed++;
+      if (meta.dedupKey) this.dedupSet.delete(meta.dedupKey);
+      await this.plugins?.fire("onSuccess", {
+        to: params.to,
+        tags: meta.tags,
+        data: result.data,
+        durationMs,
+      });
+    } else {
+      if (meta.dedupKey) this.dedupSet.delete(meta.dedupKey);
+      await this.plugins?.fire("onError", {
+        to: params.to,
+        tags: meta.tags,
+        error: result.error,
+        durationMs,
+      });
+    }
+  }
+
+  // ── Stats ────────────────────────────────────────────────────────────────
+
+  stats(): QueueStats {
+    return {
+      pending: this.jobs.length,
+      running: this.running,
+      completed: this.completed,
+      dropped: this.dropped,
+    };
+  }
+
+  /** Cancel a job by id. Returns true if found and removed. */
+  cancel(id: string): boolean {
+    const idx = this.jobs.findIndex((j) => j.id === id);
+    if (idx === -1) return false;
+    const [job] = this.jobs.splice(idx, 1);
+    if (job.meta.dedupKey) this.dedupSet.delete(job.meta.dedupKey);
+    return true;
+  }
+
+  /** Clear all pending (not in-flight) jobs. */
+  clear(): number {
+    const count = this.jobs.length;
+    this.jobs.forEach(
+      (j) => j.meta.dedupKey && this.dedupSet.delete(j.meta.dedupKey),
+    );
+    this.jobs = [];
+    return count;
+  }
+}