notifkit 0.1.2 → 0.1.4

package/src/shared/cache.ts

@@ -0,0 +1,47 @@
+export class LRUCache<K, V> {
+  private cache = new Map<K, { value: V; expiresAt: number }>();
+  private readonly maxSize: number;
+  private readonly defaultTtlMs: number;
+
+  constructor(maxSize: number = 1000, defaultTtlMs: number = 5 * 60 * 1000) {
+    this.maxSize = maxSize;
+    this.defaultTtlMs = defaultTtlMs;
+  }
+
+  get(key: K): V | undefined {
+    const item = this.cache.get(key);
+    if (!item) return undefined;
+
+    if (Date.now() > item.expiresAt) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    // Refresh position to make it most recently used
+    this.cache.delete(key);
+    this.cache.set(key, item);
+    return item.value;
+  }
+
+  set(key: K, value: V, ttlMs: number = this.defaultTtlMs): void {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      // Delete the oldest item (first inserted)
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.cache.delete(oldestKey);
+      }
+    }
+
+    this.cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+  }
+
+  delete(key: K): void {
+    this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+}

package/src/shared/circuit-breaker.ts

@@ -0,0 +1,74 @@
+export interface CircuitBreakerOptions {
+  failureThreshold: number;
+  resetTimeoutMs: number;
+}
+
+type State = "CLOSED" | "OPEN" | "HALF_OPEN";
+
+export class CircuitBreaker {
+  private state: State = "CLOSED";
+  private failures = 0;
+  private nextAttemptAt = 0;
+  /** True while one caller is testing whether the dependency has recovered. */
+  private probeInFlight = false;
+  private readonly threshold: number;
+  private readonly timeout: number;
+
+  constructor(options: CircuitBreakerOptions) {
+    this.threshold = options.failureThreshold;
+    this.timeout = options.resetTimeoutMs;
+  }
+
+  async execute<T>(action: () => Promise<T>): Promise<T> {
+    // Only one caller gets to find out whether the dependency is back. Letting
+    // the whole waiting crowd through on the first tick after the timeout is
+    // how a struggling provider gets knocked over again the moment it recovers.
+    let isProbe = false;
+
+    if (this.state === "OPEN") {
+      if (Date.now() > this.nextAttemptAt && !this.probeInFlight) {
+        this.state = "HALF_OPEN";
+        this.probeInFlight = true;
+        isProbe = true;
+      } else {
+        throw new Error("Circuit breaker is OPEN");
+      }
+    } else if (this.state === "HALF_OPEN") {
+      if (this.probeInFlight) {
+        throw new Error("Circuit breaker is OPEN");
+      }
+      this.probeInFlight = true;
+      isProbe = true;
+    }
+
+    try {
+      const result = await action();
+      this.onSuccess();
+      return result;
+    } catch (err) {
+      this.onFailure();
+      throw err;
+    } finally {
+      if (isProbe) this.probeInFlight = false;
+    }
+  }
+
+  private onSuccess() {
+    this.failures = 0;
+    this.state = "CLOSED";
+  }
+
+  private onFailure() {
+    this.failures++;
+    if (this.failures >= this.threshold) {
+      this.state = "OPEN";
+      // Restart the clock so the next probe waits a full timeout rather than
+      // firing immediately off the previous deadline.
+      this.nextAttemptAt = Date.now() + this.timeout;
+    }
+  }
+
+  getState(): State {
+    return this.state;
+  }
+}

package/src/shared/dataloader.ts

@@ -0,0 +1,41 @@
+export class DataLoader<K, V> {
+  private keys: K[] = [];
+  private promises: Array<{ resolve: (value: V | Error) => void }> = [];
+  private currentTick: Promise<void> | null = null;
+
+  constructor(private readonly batchLoadFn: (keys: K[]) => Promise<(V | Error)[]>) {}
+
+  load(key: K): Promise<V> {
+    return new Promise((resolve, reject) => {
+      this.keys.push(key);
+      this.promises.push({
+        resolve: (value) => {
+          if (value instanceof Error) reject(value);
+          else resolve(value);
+        },
+      });
+
+      if (!this.currentTick) {
+        this.currentTick = Promise.resolve().then(() => {
+          const keysToLoad = this.keys;
+          const currentPromises = this.promises;
+          this.keys = [];
+          this.promises = [];
+          this.currentTick = null;
+
+          this.batchLoadFn(keysToLoad)
+            .then((results) => {
+              for (let i = 0; i < currentPromises.length; i++) {
+                currentPromises[i]!.resolve(results[i] as V | Error);
+              }
+            })
+            .catch((err) => {
+              for (const p of currentPromises) {
+                p.resolve(err);
+              }
+            });
+        });
+      }
+    });
+  }
+}

package/src/shared/events.ts

@@ -0,0 +1,3 @@
+import { EventEmitter } from "node:events";
+
+export const globalEmitter = new EventEmitter();

package/src/shared/index.ts

@@ -0,0 +1,39 @@
+import { randomUUID } from "node:crypto";
+
+export function generateId(): string {
+  return randomUUID();
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class AppError extends Error {
+  readonly code: string;
+
+  constructor(message: string, code: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "AppError";
+    this.code = code;
+  }
+}
+
+export class ValidationError extends AppError {
+  readonly fields?: Record<string, string[]>;
+
+  constructor(message: string, fields?: Record<string, string[]>, options?: ErrorOptions) {
+    super(message, "VALIDATION_ERROR", options);
+    this.name = "ValidationError";
+    this.fields = fields;
+  }
+}
+
+export * from "./events.js";
+export * from "./cache.js";
+export * from "./utils.js";
+export * from "./semaphore.js";
+export * from "./batch-processor.js";
+export * from "./cache.js";
+export * from "./circuit-breaker.js";
+export * from "./dataloader.js";
+export { type WorkerOptions } from "@/workers/index.js";

package/src/shared/semaphore.ts

@@ -0,0 +1,33 @@
+export class AsyncSemaphore {
+  private count = 0;
+  private queue: Array<() => void> = [];
+
+  constructor(private readonly max: number) {}
+
+  async acquire(): Promise<void> {
+    if (this.count < this.max) {
+      this.count++;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+
+  release(): void {
+    if (this.queue.length > 0) {
+      // Hand the permit straight over rather than decrementing and letting the
+      // next acquire take it back — occupancy is unchanged either way.
+      const next = this.queue.shift()!;
+      next();
+    } else if (this.count > 0) {
+      this.count--;
+    }
+    // A release with nothing held is a caller bug, but silently going negative
+    // turns it into over-admission later, which is far harder to trace back.
+  }
+
+  get activeCount(): number {
+    return this.count;
+  }
+}

package/src/shared/utils.ts

@@ -0,0 +1,64 @@
+export function getPriorityBucket(
+  priority: string | undefined,
+): "critical" | "high" | "normal" | "low" {
+  const p = priority || "normal";
+  return p === "critical" || p === "high" ? "critical" : p === "low" ? "low" : "normal";
+}
+
+/**
+ * Canonical form of a destination, for suppression lookups.
+ *
+ * Both the writer (the provider webhook) and the reader (the engine's
+ * pre-dispatch gate) must agree on this, or an unsubscribe recorded as
+ * `Bob@Example.com` will not match a send addressed to `bob@example.com` and
+ * the person keeps receiving mail. Case folding is safe for email domains and
+ * for the local part in every mailbox provider in practice; phone numbers and
+ * push tokens are case-sensitive and are only trimmed.
+ */
+export function normaliseTarget(target: string): string {
+  const trimmed = target.trim();
+  return trimmed.includes("@") ? trimmed.toLowerCase() : trimmed;
+}
+
+export const LUA_SCHEDULER_POLL = `
+  local key = KEYS[1]
+  local maxScore = tonumber(ARGV[1])
+  local limit = tonumber(ARGV[2])
+  local visibilityTimeout = tonumber(ARGV[3]) or 0
+  local tasks = redis.call('ZRANGE', key, 0, maxScore, 'BYSCORE', 'LIMIT', 0, limit)
+  if #tasks > 0 then
+    for i, task in ipairs(tasks) do
+      redis.call('ZADD', key, maxScore + visibilityTimeout, task)
+    end
+  end
+  return tasks
+`;
+
+export const LUA_SCHEDULER_CLAIM = `
+  local payloadKey = KEYS[1]
+  local claimedKey = KEYS[2]
+  
+  if redis.call('EXISTS', payloadKey) == 1 then
+    redis.call('RENAME', payloadKey, claimedKey)
+    return redis.call('GET', claimedKey)
+  elseif redis.call('EXISTS', claimedKey) == 1 then
+    return redis.call('GET', claimedKey)
+  else
+    return nil
+  end
+`;
+/** Release a lock only if we still hold it (value matches our token). */
+export const LUA_RELEASE_LOCK = `
+  if redis.call('GET', KEYS[1]) == ARGV[1] then
+    return redis.call('DEL', KEYS[1])
+  end
+  return 0
+`;
+
+/** Extend a lock's TTL only if we still hold it. */
+export const LUA_RENEW_LOCK = `
+  if redis.call('GET', KEYS[1]) == ARGV[1] then
+    return redis.call('EXPIRE', KEYS[1], ARGV[2])
+  end
+  return 0
+`;

package/src/templates/cache.ts

@@ -0,0 +1,32 @@
+import { LRUCache } from "@/shared/index.js";
+import type { TemplateRepository } from "@/repositories/index.js";
+
+export class TemplateCache {
+  private cache = new LRUCache<string, any>(1000, 5 * 60 * 1000);
+
+  constructor(private readonly templateRepo: TemplateRepository) {}
+
+  async getCachedTemplate(projectId: string, id: string) {
+    const key = `${projectId}:${id}`;
+    const cached = this.cache.get(key);
+    if (cached) return cached;
+
+    const dbTemplate = await this.templateRepo.findById(projectId, id);
+    if (dbTemplate) {
+      this.cache.set(key, dbTemplate);
+    }
+    return dbTemplate;
+  }
+
+  invalidate(projectId: string, id: string) {
+    this.cache.delete(`${projectId}:${id}`);
+  }
+
+  invalidateKey(key: string) {
+    this.cache.delete(key);
+  }
+
+  clear() {
+    this.cache.clear();
+  }
+}

package/src/templates/index.ts

@@ -0,0 +1,69 @@
+import type { RenderedContent } from "@/contracts/index.js";
+export * from "./render.js";
+export * from "./cache.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface TemplateContext {
+  eventType: string;
+  templateVariables: Record<string, unknown>;
+  locale: string;
+  timezone: string;
+  deeplinkScheme: string;
+}
+
+export type TemplateRenderer = (ctx: TemplateContext) => RenderedContent;
+
+/** Coerce a template variable to a non-empty string, or undefined. */
+function asText(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+// ─── TemplateRegistry ────────────────────────────────────────────────────────
+//
+// Open registry — new event types register a renderer without touching this file.
+// The default renderer falls back to the i18n translation table, so most event
+// types work without a custom renderer.
+
+class TemplateRegistry {
+  private readonly renderers = new Map<string, TemplateRenderer>();
+
+  /**
+   * Register a custom renderer for an event type.
+   * Overwrites any previous registration for the same type.
+   */
+  register(eventType: string, renderer: TemplateRenderer): void {
+    this.renderers.set(eventType, renderer);
+  }
+
+  /** Render content for the given context, falling back to the i18n table. */
+  render(ctx: TemplateContext): RenderedContent {
+    const renderer = this.renderers.get(ctx.eventType);
+    if (renderer) return renderer(ctx);
+    return defaultRenderer(ctx);
+  }
+
+  has(eventType: string): boolean {
+    return this.renderers.has(eventType);
+  }
+
+  registeredTypes(): string[] {
+    return [...this.renderers.keys()];
+  }
+}
+
+function defaultRenderer(ctx: TemplateContext): RenderedContent {
+  const vars = ctx.templateVariables;
+
+  // Fall back to any caller-supplied title/body in the payload, then to a generic label.
+  const subject = asText(vars.subject ?? vars.title);
+  const body = asText(vars.body ?? vars.message) ?? `Notification: ${ctx.eventType}`;
+
+  return { content: { subject, body } };
+}
+
+export const templateRegistry = new TemplateRegistry();
+
+export function renderTemplate(ctx: TemplateContext): RenderedContent {
+  return templateRegistry.render(ctx);
+}

package/src/templates/render.ts

@@ -0,0 +1,128 @@
+export function escapeHtml(unsafe: string): string {
+  return String(unsafe)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+/** Strip CR/LF so an interpolated value cannot inject extra headers. */
+export function escapeHeader(unsafe: string): string {
+  return String(unsafe)
+    .replace(/[\r\n]+/g, " ")
+    .trim();
+}
+
+export function interpolate(
+  tmpl: string,
+  variables: Record<string, unknown>,
+  sanitize = true,
+): string {
+  return tmpl
+    .replace(/\{\{\{(\w+)\}\}\}/g, (_, k: string) => {
+      return String(variables[k] ?? "");
+    })
+    .replace(/\{\{(\w+)\}\}/g, (_, k: string) => {
+      const val = String(variables[k] ?? "");
+      return sanitize ? escapeHtml(val) : val;
+    });
+}
+
+/**
+ * How an interpolated value must be escaped, decided by the field it lands in.
+ *
+ *   html   — rendered as markup, so values are HTML-escaped
+ *   header — single-line headers (subject, from, …), so CR/LF are stripped
+ *   text   — plain text body, no escaping needed
+ */
+export type EscapeMode = "html" | "header" | "text";
+
+const HTML_FIELDS = new Set(["html", "htmlbody", "bodyhtml", "htmlcontent"]);
+const HEADER_FIELDS = new Set([
+  "subject",
+  "title",
+  "from",
+  "replyto",
+  "cc",
+  "bcc",
+  "preheader",
+  "preview",
+]);
+
+function escapeModeFor(key: string, inherited: EscapeMode): EscapeMode {
+  const k = key.toLowerCase().replace(/[-_]/g, "");
+  if (HTML_FIELDS.has(k)) return "html";
+  if (HEADER_FIELDS.has(k)) return "header";
+  return inherited;
+}
+
+function applyEscape(value: string, mode: EscapeMode): string {
+  if (mode === "html") return escapeHtml(value);
+  if (mode === "header") return escapeHeader(value);
+  return value;
+}
+
+/**
+ * Interpolate `{{var}}` placeholders in a single leaf string.
+ *
+ * `{{{var}}}` (triple braces) interpolates raw unescaped values.
+ * `{{var}}` (double braces) applies contextual escaping to the substituted value.
+ */
+function interpolateLeaf(
+  tmpl: string,
+  variables: Record<string, unknown>,
+  mode: EscapeMode,
+): string {
+  return tmpl
+    .replace(/\{\{\{(\w+)\}\}\}/g, (_, k: string) => {
+      const raw = variables[k];
+      if (raw === undefined || raw === null) return "";
+      return typeof raw === "string" ? raw : JSON.stringify(raw);
+    })
+    .replace(/\{\{(\w+)\}\}/g, (_, k: string) => {
+      const raw = variables[k];
+      if (raw === undefined || raw === null) return "";
+      return applyEscape(typeof raw === "string" ? raw : JSON.stringify(raw), mode);
+    });
+}
+
+/**
+ * Walk a template content tree and interpolate every leaf string in place.
+ *
+ * Values are substituted into the already-parsed structure. Interpolating into
+ * serialised JSON and re-parsing (the previous approach) let a value containing
+ * a quote either break JSON.parse outright or forge sibling fields such as
+ * `htmlBody`.
+ */
+function renderNode(node: unknown, variables: Record<string, unknown>, mode: EscapeMode): unknown {
+  if (typeof node === "string") return interpolateLeaf(node, variables, mode);
+  if (Array.isArray(node)) return node.map((item) => renderNode(item, variables, mode));
+  if (node && typeof node === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      out[key] = renderNode(value, variables, escapeModeFor(key, mode));
+    }
+    return out;
+  }
+  return node;
+}
+
+export function renderWithTemplate(
+  dbTemplate: { content?: any } | null | undefined,
+  templateVariables: Record<string, unknown>,
+): { content: Record<string, unknown> } {
+  const vars = templateVariables ?? {};
+
+  if (dbTemplate) {
+    const content = (dbTemplate.content ?? {}) as Record<string, unknown>;
+    return { content: renderNode(content, vars, "text") as Record<string, unknown> };
+  }
+
+  return {
+    content: {
+      subject: "Notification",
+      body: JSON.stringify(vars, null, 2),
+    },
+  };
+}

package/src/transport/index.ts

@@ -0,0 +1,96 @@
+import type { NotificationChannel, NotificationDispatchedPayload } from "@/index.js";
+
+// ─── Core interface ──────────────────────────────────────────────────────────
+//
+// Implement this interface to add a new channel (Email, SMS, APNS, Web Push …).
+// Register the implementation with transportRegistry at app startup.
+
+export interface DeliveryResult {
+  success: boolean;
+  providerMessageId?: string;
+  invalidToken?: boolean;
+  error?: string;
+}
+
+export interface WebhookEvent {
+  providerMessageId: string;
+  status: "opened" | "clicked" | "bounced" | "complained" | "unsubscribed";
+  timestamp?: Date;
+  /**
+   * The address the event concerns. Required to suppress it — without this a
+   * bounce or unsubscribe can be logged but not acted on, because the delivery
+   * log records the message, not the destination.
+   */
+  recipient?: string;
+  /**
+   * Whether a bounce is permanent. Only hard bounces suppress; a soft bounce is
+   * a full mailbox or a temporary outage and the address is still good. Left
+   * undefined by providers that do not distinguish them, which is treated as
+   * soft — the conservative reading, since wrongly suppressing a live address
+   * silently stops mail the person still wants.
+   */
+  bounceType?: "hard" | "soft";
+  /** Provider detail worth keeping: the clicked URL, the bounce description. */
+  metadata?: Record<string, unknown>;
+}
+
+export interface Transport {
+  readonly channel: NotificationChannel;
+  readonly limits?: { limit: number; windowSeconds: number };
+  send(task: NotificationDispatchedPayload): Promise<DeliveryResult>;
+
+  webhookPath?: string;
+  /**
+   * Handles the one-time GET verification handshake some providers require
+   * before they'll start POSTing to a webhook URL (e.g. Meta's hub.challenge
+   * subscribe flow). Return the raw challenge string to echo back, or
+   * undefined to reject the request. Providers that don't require this
+   * (Resend, etc.) simply omit it.
+   */
+  verifyWebhookChallenge?: (
+    query: URLSearchParams,
+  ) => Promise<string | undefined> | string | undefined;
+  verifyWebhook?: (
+    rawBody: string,
+    headers: Record<string, string | string[] | undefined>,
+  ) => Promise<boolean> | boolean;
+  parseWebhook?: (
+    body: any,
+    rawBody?: string,
+    headers?: Record<string, string | string[] | undefined>,
+  ) => Promise<WebhookEvent[]>;
+}
+
+// ─── TransportRegistry ───────────────────────────────────────────────────────
+
+class TransportRegistry {
+  private readonly transports = new Map<string, { transport: Transport; priority: number }[]>();
+
+  register(transport: Transport, priority: number = 0): void {
+    const list = this.transports.get(transport.channel) || [];
+    list.push({ transport, priority });
+    // Sort descending so higher priority is first
+    list.sort((a, b) => b.priority - a.priority);
+    this.transports.set(transport.channel, list);
+  }
+
+  get(channel: NotificationChannel): Transport | undefined {
+    const list = this.transports.get(channel);
+    return list && list.length > 0 ? list[0]?.transport : undefined;
+  }
+
+  getAll(channel: NotificationChannel): Transport[] {
+    const list = this.transports.get(channel);
+    return list ? list.map((item) => item.transport) : [];
+  }
+
+  registeredChannels(): string[] {
+    return [...this.transports.keys()];
+  }
+}
+
+export const transportRegistry = new TransportRegistry();
+
+export function registerTransport(transport: Transport, priority: number = 0): void {
+  transportRegistry.register(transport, priority);
+}