bridgex 1.0.0 → 2.0.1

package/src/SMSScheduler.ts

@@ -0,0 +1,250 @@
+import type SMSQueue from "./SMSQueue.js";
+import type { SendParams } from "./types.js";
+import type { SendMeta } from "./SendConfig.js";
+
+export interface ScheduledJob {
+  id: string;
+  name: string;
+  params: SendParams & Partial<SendMeta>;
+  /** Cron expression OR interval ms */
+  schedule: string | number;
+  nextRunAt: number;
+  runCount: number;
+  maxRuns?: number;
+  enabled: boolean;
+}
+
+/**
+ * SMSScheduler — register recurring or one-shot SMS sends.
+ *
+ * Schedules can be:
+ *  - A millisecond interval: `every(60_000, "ping", params)`
+ *  - A cron expression:      `cron("0 9 * * MON-FRI", "weekly-digest", params)`
+ *  - A one-shot future send:  `once(new Date("2025-01-01"), "new-year", params)`
+ *
+ * All jobs are dispatched through an SMSQueue (respects priority, TTL, dedup).
+ *
+ * @example
+ * const scheduler = new SMSScheduler(queue);
+ * scheduler.start();
+ *
+ * scheduler.every(
+ *   24 * 60 * 60 * 1000,
+ *   "daily-digest",
+ *   digestConfig.for(adminPhone)
+ * );
+ *
+ * scheduler.once(
+ *   new Date("2025-06-01T09:00:00"),
+ *   "summer-promo",
+ *   promoConfig.for(phone)
+ * );
+ */
+export default class SMSScheduler {
+  private jobs = new Map<string, ScheduledJob>();
+  private timer?: ReturnType<typeof setInterval>;
+  private readonly tickMs: number;
+
+  constructor(
+    private queue: SMSQueue,
+    options: { tickMs?: number } = {}
+  ) {
+    this.tickMs = options.tickMs ?? 1000;
+  }
+
+  // ── Registration ─────────────────────────────────────────────────────────
+
+  /** Repeat every `intervalMs` milliseconds. */
+  every(
+    intervalMs: number,
+    name: string,
+    params: SendParams & Partial<SendMeta>,
+    options: { maxRuns?: number; runImmediately?: boolean } = {}
+  ): string {
+    const id = `every:${name}`;
+    this.jobs.set(id, {
+      id,
+      name,
+      params,
+      schedule: intervalMs,
+      nextRunAt: options.runImmediately ? Date.now() : Date.now() + intervalMs,
+      runCount: 0,
+      maxRuns: options.maxRuns,
+      enabled: true,
+    });
+    return id;
+  }
+
+  /** Run once at a specific date/time. Automatically removes itself after firing. */
+  once(
+    at: Date | number,
+    name: string,
+    params: SendParams & Partial<SendMeta>
+  ): string {
+    const ts = at instanceof Date ? at.getTime() : at;
+    const id = `once:${name}:${ts}`;
+    this.jobs.set(id, {
+      id,
+      name,
+      params,
+      schedule: 0,
+      nextRunAt: ts,
+      runCount: 0,
+      maxRuns: 1,
+      enabled: true,
+    });
+    return id;
+  }
+
+  /**
+   * Cron-style schedule using a tiny parser (supports minute/hour/day/month/weekday).
+   *
+   * Format: "minute hour day-of-month month day-of-week"
+   * Use "*" for "every", comma for lists, "/" for steps.
+   *
+   * @example scheduler.cron("0 9 * * 1-5", "weekday-morning", params)
+   * @example scheduler.cron("30 8,12,18 * * *", "thrice-daily", params)
+   */
+  cron(
+    expression: string,
+    name: string,
+    params: SendParams & Partial<SendMeta>,
+    options: { maxRuns?: number } = {}
+  ): string {
+    const id = `cron:${name}`;
+    const nextRunAt = nextCronTime(expression);
+    this.jobs.set(id, {
+      id,
+      name,
+      params,
+      schedule: expression,
+      nextRunAt,
+      runCount: 0,
+      maxRuns: options.maxRuns,
+      enabled: true,
+    });
+    return id;
+  }
+
+  // ── Control ──────────────────────────────────────────────────────────────
+
+  pause(id: string): boolean {
+    const job = this.jobs.get(id);
+    if (!job) return false;
+    job.enabled = false;
+    return true;
+  }
+
+  resume(id: string): boolean {
+    const job = this.jobs.get(id);
+    if (!job) return false;
+    job.enabled = true;
+    return true;
+  }
+
+  remove(id: string): boolean {
+    return this.jobs.delete(id);
+  }
+
+  list(): ScheduledJob[] {
+    return Array.from(this.jobs.values());
+  }
+
+  // ── Lifecycle ────────────────────────────────────────────────────────────
+
+  start(): this {
+    if (this.timer) return this;
+    this.timer = setInterval(() => this._tick(), this.tickMs);
+    return this;
+  }
+
+  stop(): this {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    return this;
+  }
+
+  private _tick() {
+    const now = Date.now();
+
+    for (const [id, job] of this.jobs) {
+      if (!job.enabled || job.nextRunAt > now) continue;
+
+      // Dispatch to queue
+      this.queue.enqueue(job.params);
+      job.runCount++;
+
+      // Remove one-shots / exhausted jobs
+      if (job.maxRuns !== undefined && job.runCount >= job.maxRuns) {
+        this.jobs.delete(id);
+        continue;
+      }
+
+      // Advance nextRunAt
+      if (typeof job.schedule === "number" && job.schedule > 0) {
+        job.nextRunAt = now + job.schedule;
+      } else if (typeof job.schedule === "string") {
+        job.nextRunAt = nextCronTime(job.schedule);
+      }
+    }
+  }
+}
+
+// ── Tiny cron parser ─────────────────────────────────────────────────────────
+
+function nextCronTime(expression: string): number {
+  const [minuteExpr, hourExpr, domExpr, monthExpr, dowExpr] =
+    expression.trim().split(/\s+/);
+
+  const now = new Date();
+  const candidate = new Date(now);
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1); // start from next minute
+
+  // Try up to 366 days ahead
+  for (let days = 0; days < 366 * 24 * 60; days++) {
+    const m = candidate.getMinutes();
+    const h = candidate.getHours();
+    const dom = candidate.getDate();
+    const month = candidate.getMonth() + 1;
+    const dow = candidate.getDay();
+
+    if (
+      matchField(minuteExpr, m, 0, 59) &&
+      matchField(hourExpr, h, 0, 23) &&
+      matchField(domExpr, dom, 1, 31) &&
+      matchField(monthExpr, month, 1, 12) &&
+      matchField(dowExpr, dow, 0, 6)
+    ) {
+      return candidate.getTime();
+    }
+
+    candidate.setMinutes(candidate.getMinutes() + 1);
+  }
+
+  throw new Error(`Cannot find next occurrence for cron expression: "${expression}"`);
+}
+
+function matchField(expr: string, value: number, min: number, max: number): boolean {
+  if (expr === "*") return true;
+
+  for (const part of expr.split(",")) {
+    if (part.includes("/")) {
+      const [range, step] = part.split("/");
+      const s = parseInt(step, 10);
+      const [lo, hi] = range === "*"
+        ? [min, max]
+        : range.split("-").map(Number);
+      if (value >= lo && value <= hi && (value - lo) % s === 0) return true;
+    } else if (part.includes("-")) {
+      const [lo, hi] = part.split("-").map(Number);
+      if (value >= lo && value <= hi) return true;
+    } else {
+      if (parseInt(part, 10) === value) return true;
+    }
+  }
+
+  return false;
+}

package/src/SMSService.ts

@@ -0,0 +1,254 @@
+/**
+ * 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,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+import type SMSClient from "./SMSClient.js";
+import type SMSQueue from "./SMSQueue.js";
+import type { MetricsSnapshot } from "./PluginManager.js";
+
+export interface SMSServiceOptions {
+  port?: number;
+  host?: string;
+  /** Shared secret callers must send in the `x-service-key` header */
+  apiKey?: string;
+  /** Request timeout ms (default: 10 000) */
+  timeout?: number;
+}
+
+export default class SMSService {
+  private server = createServer((req, res) => this._handle(req, res));
+  private queue?: SMSQueue;
+  private metricsSnapshot?: () => MetricsSnapshot;
+  private startedAt = new Date();
+
+  constructor(
+    private client: SMSClient,
+    private options: SMSServiceOptions = {},
+  ) {}
+
+  /** Attach a queue so /queue/* endpoints are available. */
+  withQueue(queue: SMSQueue): this {
+    this.queue = queue;
+    return this;
+  }
+
+  /** Attach a MetricsPlugin to expose /metrics. */
+  withMetrics(plugin: { snapshot: () => MetricsSnapshot }): this {
+    this.metricsSnapshot = () => plugin.snapshot();
+    return this;
+  }
+
+  start(): Promise<void> {
+    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(): Promise<void> {
+    return new Promise((resolve, reject) =>
+      this.server.close((err) => (err ? reject(err) : resolve())),
+    );
+  }
+
+  // ── Request handler ──────────────────────────────────────────────────────
+
+  private async _handle(req: IncomingMessage, res: ServerResponse) {
+    const { apiKey, timeout = 10_000 } = 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: any) {
+      this._json(res, 500, { error: err.message ?? "Internal error" });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // ── Route handlers ────────────────────────────────────────────────────────
+
+  private async _send(res: ServerResponse, body: any) {
+    const result = await this.client.send(body);
+    this._json(res, result.ok ? 200 : 422, result);
+  }
+
+  private async _sendMany(res: ServerResponse, body: any) {
+    const { recipients, template, sharedVariables } = body;
+    const result = await this.client.sendMany(
+      recipients,
+      template,
+      sharedVariables,
+    );
+    this._json(res, 200, result);
+  }
+
+  private async _sendObject(res: ServerResponse, body: any) {
+    const result = await this.client.sendObject(body);
+    this._json(res, result.ok ? 200 : 422, result);
+  }
+
+  private async _sendObjectMany(res: ServerResponse, body: any) {
+    const result = await this.client.sendObjectMany(body.items ?? body);
+    this._json(res, 200, result);
+  }
+
+  private _enqueue(res: ServerResponse, body: any) {
+    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" });
+  }
+
+  private _schedule(res: ServerResponse, body: any) {
+    if (!this.queue)
+      return this._json(res, 503, { error: "Queue not configured" });
+    const { at, delayMs, ...params } = body;
+    let id: string;
+    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" });
+  }
+
+  private _queueStats(res: ServerResponse) {
+    if (!this.queue)
+      return this._json(res, 503, { error: "Queue not configured" });
+    this._json(res, 200, this.queue.stats());
+  }
+
+  private _queueCancel(res: ServerResponse, id: string) {
+    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 });
+  }
+
+  private _health(res: ServerResponse) {
+    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,
+    });
+  }
+
+  private _metrics(res: ServerResponse) {
+    if (!this.metricsSnapshot) {
+      return this._json(res, 503, {
+        error: "Metrics plugin not attached. Call .withMetrics()",
+      });
+    }
+    this._json(res, 200, this.metricsSnapshot());
+  }
+
+  // ── Helpers ──────────────────────────────────────────────────────────────
+
+  private _json(res: ServerResponse, status: number, body: unknown) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+      "Content-Type": "application/json",
+      "Content-Length": Buffer.byteLength(payload),
+    });
+    res.end(payload);
+  }
+
+  private _readBody(req: IncomingMessage): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      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/src/SendConfig.ts

@@ -0,0 +1,208 @@
+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?: string;
+  private _defaults: Record<string, unknown> = {};
+  private _tags: string[] = [];
+  private _ttl?: number;
+  private _priority: "low" | "normal" | "high" = "normal";
+  private _dedupKey?: string;
+
+  // ── Builder methods ──────────────────────────────────────────────────────
+
+  /** Set the message template. Supports {variable} and {nested.path} placeholders. */
+  template(tpl: string): this {
+    this._template = tpl;
+    return this;
+  }
+
+  /** Default variable values merged under per-call variables. */
+  defaults(vars: Record<string, unknown>): this {
+    this._defaults = { ...this._defaults, ...vars };
+    return this;
+  }
+
+  /** Add a single default variable. */
+  set(key: string, value: unknown): this {
+    this._defaults[key] = value;
+    return this;
+  }
+
+  /** Tag this config (useful for logging, filtering, hooks). */
+  tag(...tags: string[]): this {
+    this._tags.push(...tags);
+    return this;
+  }
+
+  /**
+   * Time-to-live in milliseconds.
+   * Messages scheduled/queued past this age will be dropped.
+   */
+  ttl(ms: number): this {
+    this._ttl = ms;
+    return this;
+  }
+
+  /** Queue priority. High-priority jobs jump the queue. */
+  priority(p: "low" | "normal" | "high"): this {
+    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: string): this {
+    this._dedupKey = key;
+    return this;
+  }
+
+  // ── Materialise ──────────────────────────────────────────────────────────
+
+  /** Build a SendParams for a single recipient. Variables override defaults. */
+  for(to: string, variables?: Record<string, unknown>): SendParams & SendMeta {
+    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<T extends Record<string, unknown>>(
+    to: string,
+    object: T,
+  ): SendObjectParams<T> & SendMeta {
+    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: Array<{ to: string; variables?: Record<string, unknown> }>,
+  ): Array<SendParams & SendMeta> {
+    return recipients.map((r) => this.for(r.to, r.variables));
+  }
+
+  /** Produce the metadata snapshot for queuing / logging. */
+  meta(): SendMeta["_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(): SendConfig {
+    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: SendConfig): SendConfig {
+    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): SendConfig {
+    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(): SendConfig {
+    return new SendConfig()
+      .template("Hi {name}, your order #{orderId} is now {status}.")
+      .tag("order")
+      .priority("normal");
+  }
+
+  /** Create a reminder config. */
+  static reminder(): SendConfig {
+    return new SendConfig()
+      .template("Reminder: {message}")
+      .tag("reminder")
+      .priority("low");
+  }
+
+  /** Create a marketing/promo config. */
+  static promo(): SendConfig {
+    return new SendConfig()
+      .template("{promoMessage}")
+      .tag("promo", "marketing")
+      .priority("low");
+  }
+}
+
+export interface SendMeta {
+  _meta: {
+    tags: string[];
+    ttl?: number;
+    priority: "low" | "normal" | "high";
+    dedupKey?: string;
+    createdAt: number;
+  };
+}