notifkit 0.1.3 → 0.1.4

package/src/server.ts

@@ -0,0 +1,277 @@
+import { EventEmitter } from "node:events";
+import { registerTransport, type Transport } from "./transport/index.js";
+import { globalEmitter } from "./shared/index.js";
+import { createLogger, type Logger } from "./logger/index.js";
+import type { LanguageModel } from "ai";
+
+export interface NotifkitOptions {
+  redisUrl?: string;
+  databaseUrl?: string;
+  port?: number;
+  logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent";
+  nodeEnv?: "development" | "test" | "production";
+  services: (
+    "api" | "delivery" | "engine" | "enricher" | "scheduler" | "ai" | "workflow" | "events" | "all"
+  )[];
+  providers?: Transport[];
+  autoMigrate?: boolean;
+  aiModel?: LanguageModel;
+  workerConcurrency?: number;
+  redisOptions?: {
+    maxQueueLength?: number;
+  };
+  dbOptions?: {
+    maxConnections?: number;
+  };
+}
+
+export class NotifkitServer extends EventEmitter {
+  private options: NotifkitOptions;
+  private pgContainer: any = null;
+  private redisContainer: any = null;
+  private eventCleanupFns: (() => void)[] = [];
+  private signalHandlersAttached = false;
+  private sigintHandler?: () => void;
+  private sigtermHandler?: () => void;
+  private logger: Logger;
+
+  constructor(options: NotifkitOptions) {
+    super();
+    this.options = options;
+    this.logger = createLogger({
+      name: "server",
+      level: options.logLevel || (process.env.LOG_LEVEL as any) || "info",
+    });
+
+    // Forward worker/API events to the server instance
+    const eventNames = [
+      "delivery:delivered",
+      "delivery:failed",
+      "notification:throttled",
+      "notification:failed",
+      "notification:skipped",
+      "notification:canceled",
+    ];
+    for (const name of eventNames) {
+      const listener = (...args: any[]) => {
+        this.emit(name, ...args);
+      };
+      globalEmitter.on(name, listener);
+      this.eventCleanupFns.push(() => {
+        globalEmitter.off(name, listener);
+      });
+    }
+  }
+
+  async start() {
+    // 1. Initial configuration setup for environment overrides
+    const { setGlobalConfig, readBaseConfig } = await import("./config/index.js");
+    if (this.options.port) process.env.PORT = String(this.options.port);
+    if (this.options.logLevel) process.env.LOG_LEVEL = this.options.logLevel;
+    if (this.options.nodeEnv) process.env.NODE_ENV = this.options.nodeEnv;
+    if (this.options.workerConcurrency)
+      process.env.WORKER_CONCURRENCY = String(this.options.workerConcurrency);
+    if (this.options.redisOptions?.maxQueueLength)
+      process.env.QUEUE_MAX_LEN = String(this.options.redisOptions.maxQueueLength);
+    if (this.options.dbOptions?.maxConnections)
+      process.env.DB_MAX_CONNECTIONS = String(this.options.dbOptions.maxConnections);
+
+    const isProduction = process.env.NODE_ENV === "production";
+
+    // 2. Spin up test containers if needed (only in development/test)
+    if (!this.options.redisUrl) {
+      if (process.env.REDIS_URL) {
+        this.options.redisUrl = process.env.REDIS_URL;
+      } else if (!isProduction) {
+        this.logger.info(
+          "No redisUrl provided, spinning up Redis container for development/testing...",
+        );
+        const { RedisContainer } = await import("@testcontainers/redis");
+        this.redisContainer = await new RedisContainer("redis:alpine").start();
+        this.options.redisUrl = this.redisContainer.getConnectionUrl();
+      } else {
+        throw new Error(
+          "Missing required configuration: REDIS_URL must be provided when running in production mode.",
+        );
+      }
+    }
+
+    if (!this.options.databaseUrl) {
+      if (process.env.DATABASE_URL) {
+        this.options.databaseUrl = process.env.DATABASE_URL;
+      } else if (!isProduction) {
+        this.logger.info(
+          "No databaseUrl provided, spinning up PostgreSQL container for development/testing...",
+        );
+        const { PostgreSqlContainer } = await import("@testcontainers/postgresql");
+        this.pgContainer = await new PostgreSqlContainer("postgres:15-alpine").start();
+        this.options.databaseUrl = this.pgContainer.getConnectionUri();
+      } else {
+        throw new Error(
+          "Missing required configuration: DATABASE_URL must be provided when running in production mode.",
+        );
+      }
+    }
+
+    if (this.options.redisUrl) process.env.REDIS_URL = this.options.redisUrl;
+    if (this.options.databaseUrl) process.env.DATABASE_URL = this.options.databaseUrl;
+
+    // 3. Set global config overrides
+    const finalConfig = readBaseConfig();
+    setGlobalConfig(finalConfig);
+    if (this.options.aiModel) {
+      const { setAiConfig } = await import("./config/index.js");
+      setAiConfig({ aiModel: this.options.aiModel });
+    }
+
+    // 4. Run database migrations if enabled
+    if (this.options.autoMigrate !== false) {
+      this.logger.info("Running database migrations...");
+      const { createDatabase, runMigrations } = await import("./db/index.js");
+      const { db, sql } = createDatabase({ url: this.options.databaseUrl! });
+      await runMigrations(db);
+      await sql.end();
+      this.logger.info("Database migrations complete");
+    }
+
+    const services = this.options.services.includes("all")
+      ? ["api", "delivery", "engine", "enricher", "scheduler", "ai", "workflow", "events"]
+      : this.options.services;
+
+    if (this.options.providers) {
+      for (const provider of this.options.providers) {
+        registerTransport(provider);
+      }
+      this.logger.info(`Registered ${this.options.providers.length} custom providers`);
+    }
+
+    const startupPromises: Promise<any>[] = [];
+
+    if (services.includes("api")) {
+      const { startApiServer } = await import("./services/api/main.js");
+      startupPromises.push(startApiServer());
+    }
+
+    if (services.includes("delivery")) {
+      const { startDeliveryWorker } = await import("./services/delivery/main.js");
+      startupPromises.push(startDeliveryWorker());
+    }
+
+    if (services.includes("engine")) {
+      const { startEngineWorker } = await import("./services/engine/main.js");
+      startupPromises.push(startEngineWorker());
+    }
+
+    if (services.includes("enricher")) {
+      const { startEnricherWorker } = await import("./services/enricher/main.js");
+      startupPromises.push(startEnricherWorker());
+    }
+
+    if (services.includes("scheduler")) {
+      const { startSchedulerWorker } = await import("./services/scheduler/main.js");
+      startupPromises.push(startSchedulerWorker());
+    }
+
+    if (services.includes("ai")) {
+      const { startAiWorker } = await import("./services/ai/main.js");
+      startupPromises.push(startAiWorker());
+    }
+
+    if (services.includes("workflow")) {
+      const { startWorkflowWorker } = await import("./services/workflow/main.js");
+      startupPromises.push(startWorkflowWorker());
+    }
+
+    if (services.includes("events")) {
+      const { startEventWorker } = await import("./services/events/main.js");
+      startupPromises.push(startEventWorker());
+    }
+
+    const handleSignal = async (signal: string) => {
+      this.logger.info(`Received ${signal}, starting graceful shutdown...`);
+      await this.stop();
+      process.exit(0);
+    };
+
+    if (!this.signalHandlersAttached) {
+      this.sigintHandler = () => {
+        void handleSignal("SIGINT");
+      };
+      this.sigtermHandler = () => {
+        void handleSignal("SIGTERM");
+      };
+      process.once("SIGINT", this.sigintHandler);
+      process.once("SIGTERM", this.sigtermHandler);
+      this.signalHandlersAttached = true;
+    }
+
+    await Promise.all(startupPromises);
+  }
+
+  async stop() {
+    if (this.signalHandlersAttached) {
+      if (this.sigintHandler) process.removeListener("SIGINT", this.sigintHandler);
+      if (this.sigtermHandler) process.removeListener("SIGTERM", this.sigtermHandler);
+      this.signalHandlersAttached = false;
+    }
+
+    // Cleanup event listeners to prevent memory leaks
+    for (const cleanup of this.eventCleanupFns) {
+      cleanup();
+    }
+    this.eventCleanupFns = [];
+
+    const services = this.options.services.includes("all")
+      ? ["api", "delivery", "engine", "enricher", "scheduler", "ai", "workflow", "events"]
+      : this.options.services;
+
+    if (services.includes("api")) {
+      const { stopApiServer } = await import("./services/api/main.js");
+      await stopApiServer();
+    }
+
+    if (services.includes("delivery")) {
+      const { stopDeliveryWorker } = await import("./services/delivery/main.js");
+      await stopDeliveryWorker();
+    }
+
+    if (services.includes("engine")) {
+      const { stopEngineWorker } = await import("./services/engine/main.js");
+      await stopEngineWorker();
+    }
+
+    if (services.includes("enricher")) {
+      const { stopEnricherWorker } = await import("./services/enricher/main.js");
+      await stopEnricherWorker();
+    }
+
+    if (services.includes("scheduler")) {
+      const { stopSchedulerWorker } = await import("./services/scheduler/main.js");
+      await stopSchedulerWorker();
+    }
+
+    if (services.includes("ai")) {
+      const { stopAiWorker } = await import("./services/ai/main.js");
+      await stopAiWorker();
+    }
+
+    if (services.includes("workflow")) {
+      const { stopWorkflowWorker } = await import("./services/workflow/main.js");
+      await stopWorkflowWorker();
+    }
+
+    if (services.includes("events")) {
+      const { stopEventWorker } = await import("./services/events/main.js");
+      await stopEventWorker();
+    }
+
+    if (this.pgContainer) {
+      this.logger.info("Stopping PostgreSQL container...");
+      await this.pgContainer.stop();
+    }
+    if (this.redisContainer) {
+      this.logger.info("Stopping Redis container...");
+      await this.redisContainer.stop();
+    }
+  }
+}

package/src/services/ai/main.ts

@@ -0,0 +1,404 @@
+import { randomUUID } from "node:crypto";
+import { loadEnv, readBaseConfig } from "@/index.js";
+import { createLogger } from "@/index.js";
+import { RedisClient, type Redis } from "@/index.js";
+import {
+  StreamConsumer,
+  PendingMessageScanner,
+  StreamProducer,
+  type StreamMessage,
+} from "@/index.js";
+import { BaseWorker } from "@/index.js";
+import {
+  STREAMS,
+  CONSUMER_GROUPS,
+  registry,
+  buildStreamEvent,
+  type NotificationAiPendingPayload,
+  type NotificationDispatchedPayload,
+  getAiConfig,
+  AI_DEFAULTS,
+} from "@/index.js";
+import { generateText } from "ai";
+import { type StreamName } from "@/contracts/streams.js";
+import { IdempotencyGuard } from "@/index.js";
+import { TemplateRepository } from "@/index.js";
+import { createDatabase } from "@/db/index.js";
+import { scheduledPayloads } from "@/db/schema.js";
+import { getPriorityBucket, globalEmitter, type WorkerOptions } from "@/shared/index.js";
+import { renderWithTemplate, TemplateCache } from "@/templates/index.js";
+import { startHealthReporter } from "@/workers/index.js";
+
+// ─── Bootstrap ─────────────────────────────────────────────────────────────
+
+loadEnv();
+const config = readBaseConfig();
+
+let logger: ReturnType<typeof createLogger>;
+let redis: RedisClient;
+let sql: any;
+let db: any;
+let templateRepo: TemplateRepository;
+
+let templateCache: TemplateCache;
+
+let consumer: StreamConsumer;
+let pendingScanner: PendingMessageScanner;
+let worker: BaseWorker;
+let healthInterval: NodeJS.Timeout | null = null;
+let subscriber: any = null;
+
+/**
+ * A model failure that retrying cannot fix (bad prompt, rejected request,
+ * unsupported model). Thrown so the notification fails once instead of being
+ * re-billed on every retry.
+ */
+export class PermanentAiError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "PermanentAiError";
+  }
+}
+
+/** Timeouts, rate limits and 5xx are worth another attempt; 4xx are not. */
+export function isRetryableAiError(err: unknown): boolean {
+  if (err instanceof PermanentAiError) return false;
+
+  const e = err as { name?: string; statusCode?: number; status?: number } | null;
+  if (!e) return false;
+
+  if (e.name === "TimeoutError" || e.name === "AbortError") return true;
+
+  const status = e.statusCode ?? e.status;
+  if (typeof status === "number") {
+    return status === 408 || status === 409 || status === 429 || status >= 500;
+  }
+
+  // Unclassifiable (network errors, transport failures) — assume transient.
+  return true;
+}
+
+export interface AiWorkerOptions extends WorkerOptions {
+  registry: any;
+  idempotency: any;
+  redis: Redis;
+  generateAiContent: any;
+  templateCache: TemplateCache;
+  scheduledProducer: any;
+  outboundProducers: any;
+  db: any;
+}
+
+export class AiWorker extends BaseWorker {
+  private readonly registry: any;
+  private readonly idempotency: any;
+  private readonly redisCli: Redis;
+  private readonly generateAiContent: any;
+  private readonly templateCache: TemplateCache;
+  private readonly scheduledProducer: any;
+  private readonly outboundProducers: any;
+  private readonly db: any;
+
+  constructor(options: AiWorkerOptions) {
+    super(options);
+    this.registry = options.registry;
+    this.idempotency = options.idempotency;
+    this.redisCli = options.redis;
+    this.generateAiContent = options.generateAiContent;
+    this.templateCache = options.templateCache;
+    this.scheduledProducer = options.scheduledProducer;
+    this.outboundProducers = options.outboundProducers;
+    this.db = options.db;
+  }
+  async process(message: StreamMessage): Promise<void> {
+    const { event } = message;
+
+    const payloadResult = this.registry.safeParsePayload("notification.ai_pending", event.payload);
+    if (!payloadResult.success) {
+      this.logger.warn(
+        { messageId: message.id, issues: payloadResult.error.issues },
+        "invalid notification.ai_pending payload — skipping",
+      );
+      return;
+    }
+
+    const pending = payloadResult.data as NotificationAiPendingPayload;
+
+    // Idempotency
+    const idempotencyKey = `${pending.enrichedEventId}:${pending.recipientId}:${pending.channel}:ai`;
+    if (!(await this.idempotency.checkAndMark(idempotencyKey))) {
+      this.logger.debug(
+        { messageId: message.id, eventId: event.id },
+        "duplicate ai task — skipping",
+      );
+      return;
+    }
+    try {
+      // Execute AI prompts. Each key is a separate billed model call, so the
+      // count is capped rather than being driven by whatever the caller sent.
+      const promptEntries = Object.entries(pending.aiPrompts);
+      const maxPrompts =
+        getAiConfig().maxPromptsPerNotification ?? AI_DEFAULTS.maxPromptsPerNotification;
+      if (promptEntries.length > maxPrompts) {
+        this.logger.warn(
+          { messageId: message.id, requested: promptEntries.length, maxPrompts },
+          "aiPrompts exceeds the per-notification cap — extra prompts ignored",
+        );
+      }
+
+      const generatedVars: Record<string, string> = {};
+      for (const [key, prompt] of promptEntries.slice(0, maxPrompts)) {
+        generatedVars[key] = await this.generateAiContent(prompt, pending.templateVariables);
+      }
+
+      // Merge generated vars with original template vars
+      const finalVars = { ...pending.templateVariables, ...generatedVars };
+
+      const dbTemplate = pending.templateId
+        ? await this.templateCache.getCachedTemplate(pending.projectId, pending.templateId)
+        : null;
+
+      const rendered = renderWithTemplate(dbTemplate, finalVars);
+
+      const taskId = randomUUID();
+      const destination =
+        pending.channel === "email"
+          ? pending.recipient.email
+          : pending.channel === "sms" || pending.channel === "whatsapp"
+            ? pending.recipient.phone
+            : pending.channel === "webhook"
+              ? pending.recipient.webhook
+              : pending.channel === "telegram"
+                ? pending.recipient.telegram
+                : pending.channel === "discord"
+                  ? pending.recipient.discord
+                  : pending.channel === "slack"
+                    ? pending.recipient.slack
+                    : pending.channel === "push"
+                      ? (pending.recipient.pushTokens?.[0] ?? pending.recipient.pushToken)
+                      : undefined;
+      const resolvedDestination =
+        destination ?? (pending.channel === "push" ? undefined : pending.recipientId);
+
+      const taskPayload: NotificationDispatchedPayload = {
+        projectId: pending.projectId,
+        taskId,
+        enrichedEventId: pending.enrichedEventId,
+        recipientId: pending.recipientId,
+        channel: pending.channel,
+        priority: pending.priority,
+        templateId: pending.templateId,
+        templateVariables: pending.templateVariables,
+        aiPrompts: pending.aiPrompts,
+        recipient: pending.recipient,
+        renderedContent: rendered,
+        destination: resolvedDestination,
+        deliveryOptions: {
+          maxAttempts: 3,
+          timeoutMs: 10_000,
+        },
+        fallbackChain: pending.fallbackChain,
+      };
+
+      const envelope = buildStreamEvent(
+        "notification.dispatched",
+        taskPayload as Record<string, unknown>,
+        "ai-worker",
+        event.metadata.traceId,
+      );
+
+      // Route by scheduledAt
+      const now = Date.now();
+      const scheduledAt = pending.scheduledAt ? new Date(pending.scheduledAt).getTime() : now;
+
+      if (scheduledAt > now) {
+        await this.db.insert(scheduledPayloads).values({
+          taskId,
+          payload: taskPayload,
+        });
+
+        const scheduledEnvelope = buildStreamEvent(
+          "notification.scheduled",
+          {
+            projectId: pending.projectId,
+            enrichedEventId: pending.enrichedEventId,
+            taskId,
+            scheduledAt: pending.scheduledAt!,
+          },
+          "ai-worker",
+          event.metadata.traceId,
+        );
+
+        await this.scheduledProducer.publish(scheduledEnvelope);
+        this.logger.info(
+          {
+            messageId: message.id,
+            taskId,
+            scheduledAt: pending.scheduledAt,
+            traceId: event.metadata.traceId,
+          },
+          "task scheduled and payload cached after AI generation",
+        );
+      } else {
+        const p = getPriorityBucket(pending.priority);
+        const outboundProducer = this.outboundProducers[p] ?? this.outboundProducers["normal"]!;
+
+        await outboundProducer.publish(envelope);
+        this.logger.info(
+          {
+            messageId: message.id,
+            taskId,
+            recipientId: pending.recipientId,
+            traceId: event.metadata.traceId,
+          },
+          "task dispatched after AI generation",
+        );
+      }
+    } catch (err) {
+      await this.idempotency.unmark(idempotencyKey);
+      if (err instanceof PermanentAiError || (err as Error)?.name === "PermanentAiError") {
+        // Retrying re-bills the same failing prompt. Fail the notification once.
+        this.logger.error(
+          { err, messageId: message.id, recipientId: pending.recipientId },
+          "AI generation failed permanently — dropping notification without retry",
+        );
+        globalEmitter.emit(
+          "notification:failed",
+          pending.enrichedEventId,
+          (err as Error).message,
+          pending.channel,
+        );
+        return;
+      }
+      throw err;
+    }
+  }
+}
+
+export async function startAiWorker() {
+  logger = createLogger({ name: "ai", level: config.LOG_LEVEL });
+  redis = new RedisClient({ url: config.REDIS_URL, name: "ai", logger });
+  const dbData = createDatabase({ url: config.DATABASE_URL, applicationName: "ai", logger });
+  sql = dbData.sql;
+  db = dbData.db;
+  templateRepo = new TemplateRepository(db);
+  templateCache = new TemplateCache(templateRepo);
+  consumer = new StreamConsumer({
+    redis: redis.native,
+    stream: STREAMS.AI_PENDING as StreamName,
+    group: CONSUMER_GROUPS.AI,
+    consumer: `ai-${process.pid}`,
+    dlqStream: STREAMS.DEAD_LETTER,
+    batchSize: config.WORKER_CONCURRENCY,
+    logger,
+  });
+
+  pendingScanner = new PendingMessageScanner({
+    redis: redis.native,
+    stream: STREAMS.AI_PENDING as StreamName,
+    group: CONSUMER_GROUPS.AI,
+    consumer: `ai-${process.pid}`,
+    logger,
+  });
+
+  const outboundProducers = {
+    critical: new StreamProducer({
+      redis: redis.native,
+      stream: STREAMS.OUTBOUND_CRITICAL,
+      logger,
+    }),
+    normal: new StreamProducer({ redis: redis.native, stream: STREAMS.OUTBOUND_NORMAL, logger }),
+    low: new StreamProducer({ redis: redis.native, stream: STREAMS.OUTBOUND_LOW, logger }),
+  };
+
+  const scheduledProducer = new StreamProducer({
+    redis: redis.native,
+    stream: STREAMS.SCHEDULED,
+    logger,
+  });
+
+  const idempotency = new IdempotencyGuard({
+    redis: redis.native,
+    keyPrefix: "notif:processed:ai",
+    ttlSeconds: 86_400,
+  });
+
+  // AI generation
+  async function generateAiContent(prompt: string, vars: Record<string, unknown>): Promise<string> {
+    const aiConfig = getAiConfig();
+    const interpolated = prompt.replace(/\{\{(\w+)\}\}/g, (_, k: string) => String(vars[k] ?? ""));
+
+    if (!aiConfig || !aiConfig.aiModel) {
+      logger.warn("AI worker called but no AI model was provided to NotifkitServer");
+      return `[AI Disabled] ${interpolated}`;
+    }
+
+    const maxOutputTokens = aiConfig.maxOutputTokens ?? AI_DEFAULTS.maxOutputTokens;
+    const timeoutMs = aiConfig.timeoutMs ?? AI_DEFAULTS.timeoutMs;
+
+    try {
+      const { text } = await generateText({
+        model: aiConfig.aiModel,
+        prompt: interpolated,
+        maxOutputTokens,
+        abortSignal: AbortSignal.timeout(timeoutMs),
+      });
+
+      return text;
+    } catch (err) {
+      // BaseWorker retries a throw up to maxRetriesBeforeDlq, and every retry is
+      // another billed call. Only re-throw for failures a retry could actually
+      // fix; a malformed prompt or a rejected request must not be re-billed.
+      if (isRetryableAiError(err)) {
+        logger.error({ err }, "AI generation failed (transient) — will retry");
+        throw err;
+      }
+      throw new PermanentAiError(err instanceof Error ? err.message : String(err), { cause: err });
+    }
+  }
+
+  worker = new AiWorker({
+    consumer,
+    pendingScanner,
+    logger,
+    concurrency: config.WORKER_CONCURRENCY,
+    registry,
+    idempotency,
+    redis: redis.native,
+    generateAiContent,
+    templateCache,
+    scheduledProducer,
+    outboundProducers,
+    db,
+  });
+
+  subscriber = redis.native.duplicate();
+  await subscriber.subscribe("template.invalidated");
+  subscriber.on("message", (channel: string, message: string) => {
+    if (channel === "template.invalidated") {
+      templateCache.invalidateKey(message);
+      logger.info({ cacheKey: message }, "invalidated template cache");
+    }
+  });
+
+  healthInterval = startHealthReporter("ai", worker, redis, logger);
+
+  logger.info({ env: config.NODE_ENV, redis: config.REDIS_URL }, "ai starting");
+  await worker.start();
+}
+
+export async function stopAiWorker(): Promise<void> {
+  logger?.info("shutdown initiated");
+  if (healthInterval) {
+    clearInterval(healthInterval);
+    healthInterval = null;
+  }
+  if (subscriber) {
+    subscriber.disconnect();
+    subscriber = null;
+  }
+  if (worker) await worker.stop();
+  if (sql) await sql.end();
+  if (redis) await redis.disconnect();
+  logger?.info("ai stopped");
+}