@wopr-network/platform-core 1.29.0 → 1.31.0

package/dist/email/notification-worker.d.ts

@@ -5,18 +5,21 @@
  * Do NOT put the interval inside this class.
  */
 import type { EmailClient } from "./client.js";
+import type { HandlebarsRenderer } from "./handlebars-renderer.js";
 import type { INotificationPreferencesRepository, INotificationQueueRepository } from "./notification-repository-types.js";
 export interface NotificationWorkerConfig {
     queue: INotificationQueueRepository;
     emailClient: EmailClient;
     preferences: INotificationPreferencesRepository;
     batchSize?: number;
+    handlebarsRenderer?: HandlebarsRenderer;
 }
 export declare class NotificationWorker {
     private readonly queue;
     private readonly emailClient;
     private readonly preferences;
     private readonly batchSize;
+    private readonly handlebarsRenderer;
     constructor(config: NotificationWorkerConfig);
     /** Process one batch of pending notifications. Returns count of processed items. */
     processBatch(): Promise<number>;

package/dist/email/notification-worker.js

@@ -35,17 +35,21 @@ const PREF_MAP = {
     "dividend-weekly-digest": "billing_receipts",
     "role-changed": "account_role_changes",
     "team-invite": "account_team_invites",
+    "fleet-update-available": "fleet_updates",
+    "fleet-update-complete": "fleet_updates",
 };
 export class NotificationWorker {
     queue;
     emailClient;
     preferences;
     batchSize;
+    handlebarsRenderer;
     constructor(config) {
         this.queue = config.queue;
         this.emailClient = config.emailClient;
         this.preferences = config.preferences;
         this.batchSize = config.batchSize ?? 10;
+        this.handlebarsRenderer = config.handlebarsRenderer;
     }
     /** Process one batch of pending notifications. Returns count of processed items. */
     async processBatch() {
@@ -74,8 +78,14 @@ export class NotificationWorker {
                         continue;
                     }
                 }
-                // Render the template
-                const rendered = renderNotificationTemplate(notif.template, data);
+                // Try DB-driven Handlebars first, fall back to code templates
+                let rendered = null;
+                if (this.handlebarsRenderer) {
+                    rendered = await this.handlebarsRenderer.render(notif.template, data);
+                }
+                if (!rendered) {
+                    rendered = renderNotificationTemplate(notif.template, data);
+                }
                 // Send via email client
                 await this.emailClient.send({
                     to: email,

package/dist/fleet/fleet-event-emitter.d.ts

@@ -7,6 +7,8 @@ export interface BotFleetEvent {
     botId: string;
     tenantId: string;
     timestamp: string;
+    /** Image tag or version string, when available (e.g. from update events). */
+    version?: string;
 }
 export interface NodeFleetEvent {
     type: NodeEventType;

package/dist/fleet/fleet-notification-listener.d.ts

@@ -0,0 +1,13 @@
+import type { INotificationPreferencesRepository } from "../email/notification-repository-types.js";
+import type { NotificationService } from "../email/notification-service.js";
+import type { FleetEventEmitter } from "./fleet-event-emitter.js";
+export interface FleetNotificationListenerDeps {
+    eventEmitter: FleetEventEmitter;
+    notificationService: NotificationService;
+    preferences: INotificationPreferencesRepository;
+    /** Resolve tenant ID to owner email. Return null if no email found. */
+    resolveEmail: (tenantId: string) => Promise<string | null>;
+    /** Debounce window in ms before sending summary email. Default 60_000. */
+    debounceMs?: number;
+}
+export declare function initFleetNotificationListener(deps: FleetNotificationListenerDeps): () => Promise<void>;

package/dist/fleet/fleet-notification-listener.js

@@ -0,0 +1,67 @@
+import { logger } from "../config/logger.js";
+export function initFleetNotificationListener(deps) {
+    const { eventEmitter, notificationService, preferences, resolveEmail } = deps;
+    const debounceMs = deps.debounceMs ?? 60_000;
+    const pending = new Map();
+    async function flush(tenantId) {
+        const rollout = pending.get(tenantId);
+        if (!rollout)
+            return;
+        pending.delete(tenantId);
+        try {
+            const prefs = await preferences.get(tenantId);
+            if (!prefs.fleet_updates)
+                return;
+            const email = await resolveEmail(tenantId);
+            if (!email) {
+                logger.warn("Fleet notification skipped: no email for tenant", { tenantId });
+                return;
+            }
+            notificationService.notifyFleetUpdateComplete(tenantId, email, rollout.version, rollout.succeeded, rollout.failed);
+        }
+        catch (err) {
+            logger.error("Fleet notification flush error", { err, tenantId });
+        }
+    }
+    const unsubscribe = eventEmitter.subscribe((event) => {
+        if (!("tenantId" in event))
+            return;
+        const botEvent = event;
+        if (botEvent.type !== "bot.updated" && botEvent.type !== "bot.update_failed")
+            return;
+        let rollout = pending.get(botEvent.tenantId);
+        if (!rollout) {
+            rollout = {
+                tenantId: botEvent.tenantId,
+                version: botEvent.version ?? "latest",
+                succeeded: 0,
+                failed: 0,
+                timer: setTimeout(() => flush(botEvent.tenantId), debounceMs),
+            };
+            pending.set(botEvent.tenantId, rollout);
+        }
+        else {
+            // Reset timer on each new event (sliding window)
+            clearTimeout(rollout.timer);
+            rollout.timer = setTimeout(() => flush(botEvent.tenantId), debounceMs);
+            if (botEvent.version)
+                rollout.version = botEvent.version;
+        }
+        if (botEvent.type === "bot.updated") {
+            rollout.succeeded++;
+        }
+        else {
+            rollout.failed++;
+        }
+    });
+    return async () => {
+        unsubscribe();
+        const flushes = [];
+        for (const [tenantId, rollout] of pending) {
+            clearTimeout(rollout.timer);
+            flushes.push(flush(tenantId));
+        }
+        pending.clear();
+        await Promise.allSettled(flushes);
+    };
+}

package/dist/fleet/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./drizzle-tenant-update-config-repository.js";
+export type { FleetNotificationListenerDeps } from "./fleet-notification-listener.js";
+export { initFleetNotificationListener } from "./fleet-notification-listener.js";
 export * from "./init-fleet-updater.js";
 export * from "./repository-types.js";
 export * from "./rollout-orchestrator.js";

package/dist/fleet/index.js

@@ -1,4 +1,5 @@
 export * from "./drizzle-tenant-update-config-repository.js";
+export { initFleetNotificationListener } from "./fleet-notification-listener.js";
 export * from "./init-fleet-updater.js";
 export * from "./repository-types.js";
 export * from "./rollout-orchestrator.js";

package/dist/fleet/init-fleet-updater.d.ts

@@ -12,7 +12,7 @@
  */
 import type Docker from "dockerode";
 import type { IBotProfileRepository } from "./bot-profile-repository.js";
-import type { FleetEventEmitter } from "./fleet-event-emitter.js";
+import { FleetEventEmitter } from "./fleet-event-emitter.js";
 import type { FleetManager } from "./fleet-manager.js";
 import { ImagePoller } from "./image-poller.js";
 import type { IProfileStore } from "./profile-store.js";
@@ -46,6 +46,8 @@ export interface FleetUpdaterHandle {
     updater: ContainerUpdater;
     orchestrator: RolloutOrchestrator;
     snapshotManager: VolumeSnapshotManager;
+    /** Fleet event emitter for subscribing to bot/node lifecycle events */
+    eventEmitter: FleetEventEmitter;
     /** Stop the poller and wait for any active rollout to finish */
     stop: () => Promise<void>;
 }

package/dist/fleet/init-fleet-updater.js

@@ -11,6 +11,7 @@
  * all bots need updating.
  */
 import { logger } from "../config/logger.js";
+import { FleetEventEmitter } from "./fleet-event-emitter.js";
 import { ImagePoller } from "./image-poller.js";
 import { RolloutOrchestrator } from "./rollout-orchestrator.js";
 import { createRolloutStrategy } from "./rollout-strategy.js";
@@ -29,7 +30,8 @@ import { VolumeSnapshotManager } from "./volume-snapshot-manager.js";
  * @param config - Optional pipeline configuration
  */
 export function initFleetUpdater(docker, fleet, profileStore, profileRepo, config = {}) {
-    const { strategy: strategyType = "rolling-wave", strategyOptions, snapshotDir = "/data/fleet/snapshots", onBotUpdated, onRolloutComplete, configRepo, eventEmitter, } = config;
+    const { strategy: strategyType = "rolling-wave", strategyOptions, snapshotDir = "/data/fleet/snapshots", onBotUpdated, onRolloutComplete, configRepo, eventEmitter: configEventEmitter, } = config;
+    const emitter = configEventEmitter ?? new FleetEventEmitter();
     const poller = new ImagePoller(docker, profileStore);
     const updater = new ContainerUpdater(docker, profileStore, fleet, poller);
     const snapshotManager = new VolumeSnapshotManager(docker, snapshotDir);
@@ -54,16 +56,28 @@ export function initFleetUpdater(docker, fleet, profileStore, profileRepo, confi
             return results.filter((p) => p !== null);
         },
         onBotUpdated: (result) => {
-            // Emit fleet events if emitter is provided
-            if (eventEmitter) {
-                eventEmitter.emit({
+            // Fire-and-forget: resolve tenantId + emit event asynchronously
+            // The orchestrator callback is sync (void return) — async work must not block rollout progress
+            void (async () => {
+                let tenantId = "";
+                try {
+                    const profile = await profileRepo.get(result.botId);
+                    if (profile)
+                        tenantId = profile.tenantId;
+                }
+                catch {
+                    // Best-effort — event still fires with empty tenantId
+                }
+                // Extract version tag from image name (e.g. "ghcr.io/org/image:v1.2.3" → "v1.2.3")
+                const version = result.newImage.includes(":") ? (result.newImage.split(":").pop() ?? "latest") : "latest";
+                emitter.emit({
                     type: result.success ? "bot.updated" : "bot.update_failed",
                     botId: result.botId,
-                    tenantId: "",
+                    tenantId,
                     timestamp: new Date().toISOString(),
+                    version,
                 });
-            }
-            // Chain user-provided callback
+            })();
             onBotUpdated?.(result);
         },
         onRolloutComplete: (result) => {
@@ -96,6 +110,7 @@ export function initFleetUpdater(docker, fleet, profileStore, profileRepo, confi
         updater,
         orchestrator,
         snapshotManager,
+        eventEmitter: emitter,
         stop: async () => {
             poller.stop();
             // Wait for any in-flight rollout to complete before returning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/email/notification-worker.ts

@@ -7,17 +7,20 @@
 
 import { logger } from "../config/logger.js";
 import type { EmailClient } from "./client.js";
+import type { HandlebarsRenderer } from "./handlebars-renderer.js";
 import type {
   INotificationPreferencesRepository,
   INotificationQueueRepository,
 } from "./notification-repository-types.js";
 import { renderNotificationTemplate, type TemplateName } from "./notification-templates.js";
+import type { TemplateResult } from "./templates.js";
 
 export interface NotificationWorkerConfig {
   queue: INotificationQueueRepository;
   emailClient: EmailClient;
   preferences: INotificationPreferencesRepository;
   batchSize?: number;
+  handlebarsRenderer?: HandlebarsRenderer;
 }
 
 /** Templates that bypass user preference checks — always sent. */
@@ -50,6 +53,8 @@ const PREF_MAP: Record<string, string> = {
   "dividend-weekly-digest": "billing_receipts",
   "role-changed": "account_role_changes",
   "team-invite": "account_team_invites",
+  "fleet-update-available": "fleet_updates",
+  "fleet-update-complete": "fleet_updates",
 };
 
 export class NotificationWorker {
@@ -57,12 +62,14 @@ export class NotificationWorker {
   private readonly emailClient: EmailClient;
   private readonly preferences: INotificationPreferencesRepository;
   private readonly batchSize: number;
+  private readonly handlebarsRenderer: HandlebarsRenderer | undefined;
 
   constructor(config: NotificationWorkerConfig) {
     this.queue = config.queue;
     this.emailClient = config.emailClient;
     this.preferences = config.preferences;
     this.batchSize = config.batchSize ?? 10;
+    this.handlebarsRenderer = config.handlebarsRenderer;
   }
 
   /** Process one batch of pending notifications. Returns count of processed items. */
@@ -96,8 +103,14 @@ export class NotificationWorker {
           }
         }
 
-        // Render the template
-        const rendered = renderNotificationTemplate(notif.template as TemplateName, data);
+        // Try DB-driven Handlebars first, fall back to code templates
+        let rendered: TemplateResult | null = null;
+        if (this.handlebarsRenderer) {
+          rendered = await this.handlebarsRenderer.render(notif.template, data);
+        }
+        if (!rendered) {
+          rendered = renderNotificationTemplate(notif.template as TemplateName, data);
+        }
 
         // Send via email client
         await this.emailClient.send({

package/src/fleet/fleet-event-emitter.ts

@@ -26,6 +26,8 @@ export interface BotFleetEvent {
   botId: string;
   tenantId: string;
   timestamp: string;
+  /** Image tag or version string, when available (e.g. from update events). */
+  version?: string;
 }
 
 export interface NodeFleetEvent {

package/src/fleet/fleet-notification-listener.ts

@@ -0,0 +1,95 @@
+import { logger } from "../config/logger.js";
+import type { INotificationPreferencesRepository } from "../email/notification-repository-types.js";
+import type { NotificationService } from "../email/notification-service.js";
+import type { BotFleetEvent, FleetEventEmitter } from "./fleet-event-emitter.js";
+
+export interface FleetNotificationListenerDeps {
+  eventEmitter: FleetEventEmitter;
+  notificationService: NotificationService;
+  preferences: INotificationPreferencesRepository;
+  /** Resolve tenant ID to owner email. Return null if no email found. */
+  resolveEmail: (tenantId: string) => Promise<string | null>;
+  /** Debounce window in ms before sending summary email. Default 60_000. */
+  debounceMs?: number;
+}
+
+interface PendingRollout {
+  tenantId: string;
+  version: string;
+  succeeded: number;
+  failed: number;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export function initFleetNotificationListener(deps: FleetNotificationListenerDeps): () => Promise<void> {
+  const { eventEmitter, notificationService, preferences, resolveEmail } = deps;
+  const debounceMs = deps.debounceMs ?? 60_000;
+  const pending = new Map<string, PendingRollout>();
+
+  async function flush(tenantId: string): Promise<void> {
+    const rollout = pending.get(tenantId);
+    if (!rollout) return;
+    pending.delete(tenantId);
+
+    try {
+      const prefs = await preferences.get(tenantId);
+      if (!prefs.fleet_updates) return;
+
+      const email = await resolveEmail(tenantId);
+      if (!email) {
+        logger.warn("Fleet notification skipped: no email for tenant", { tenantId });
+        return;
+      }
+
+      notificationService.notifyFleetUpdateComplete(
+        tenantId,
+        email,
+        rollout.version,
+        rollout.succeeded,
+        rollout.failed,
+      );
+    } catch (err) {
+      logger.error("Fleet notification flush error", { err, tenantId });
+    }
+  }
+
+  const unsubscribe = eventEmitter.subscribe((event) => {
+    if (!("tenantId" in event)) return;
+    const botEvent = event as BotFleetEvent;
+    if (botEvent.type !== "bot.updated" && botEvent.type !== "bot.update_failed") return;
+
+    let rollout = pending.get(botEvent.tenantId);
+    if (!rollout) {
+      rollout = {
+        tenantId: botEvent.tenantId,
+        version: botEvent.version ?? "latest",
+        succeeded: 0,
+        failed: 0,
+        timer: setTimeout(() => flush(botEvent.tenantId), debounceMs),
+      };
+      pending.set(botEvent.tenantId, rollout);
+    } else {
+      // Reset timer on each new event (sliding window)
+      clearTimeout(rollout.timer);
+      rollout.timer = setTimeout(() => flush(botEvent.tenantId), debounceMs);
+      if (botEvent.version) rollout.version = botEvent.version;
+    }
+
+    if (botEvent.type === "bot.updated") {
+      rollout.succeeded++;
+    } else {
+      rollout.failed++;
+    }
+  });
+
+  return async () => {
+    unsubscribe();
+    const flushes: Promise<void>[] = [];
+    for (const [tenantId, rollout] of pending) {
+      clearTimeout(rollout.timer);
+      flushes.push(flush(tenantId));
+    }
+    pending.clear();
+    await Promise.allSettled(flushes);
+  };
+}

package/src/fleet/index.ts

@@ -1,4 +1,6 @@
 export * from "./drizzle-tenant-update-config-repository.js";
+export type { FleetNotificationListenerDeps } from "./fleet-notification-listener.js";
+export { initFleetNotificationListener } from "./fleet-notification-listener.js";
 export * from "./init-fleet-updater.js";
 export * from "./repository-types.js";
 export * from "./rollout-orchestrator.js";

package/src/fleet/init-fleet-updater.ts

@@ -14,7 +14,7 @@
 import type Docker from "dockerode";
 import { logger } from "../config/logger.js";
 import type { IBotProfileRepository } from "./bot-profile-repository.js";
-import type { FleetEventEmitter } from "./fleet-event-emitter.js";
+import { FleetEventEmitter } from "./fleet-event-emitter.js";
 import type { FleetManager } from "./fleet-manager.js";
 import { ImagePoller } from "./image-poller.js";
 import type { IProfileStore } from "./profile-store.js";
@@ -46,6 +46,8 @@ export interface FleetUpdaterHandle {
   updater: ContainerUpdater;
   orchestrator: RolloutOrchestrator;
   snapshotManager: VolumeSnapshotManager;
+  /** Fleet event emitter for subscribing to bot/node lifecycle events */
+  eventEmitter: FleetEventEmitter;
   /** Stop the poller and wait for any active rollout to finish */
   stop: () => Promise<void>;
 }
@@ -76,9 +78,11 @@ export function initFleetUpdater(
     onBotUpdated,
     onRolloutComplete,
     configRepo,
-    eventEmitter,
+    eventEmitter: configEventEmitter,
   } = config;
 
+  const emitter = configEventEmitter ?? new FleetEventEmitter();
+
   const poller = new ImagePoller(docker, profileStore);
   const updater = new ContainerUpdater(docker, profileStore, fleet, poller);
   const snapshotManager = new VolumeSnapshotManager(docker, snapshotDir);
@@ -106,16 +110,28 @@ export function initFleetUpdater(
       return results.filter((p) => p !== null);
     },
     onBotUpdated: (result) => {
-      // Emit fleet events if emitter is provided
-      if (eventEmitter) {
-        eventEmitter.emit({
+      // Fire-and-forget: resolve tenantId + emit event asynchronously
+      // The orchestrator callback is sync (void return) — async work must not block rollout progress
+      void (async () => {
+        let tenantId = "";
+        try {
+          const profile = await profileRepo.get(result.botId);
+          if (profile) tenantId = profile.tenantId;
+        } catch {
+          // Best-effort — event still fires with empty tenantId
+        }
+
+        // Extract version tag from image name (e.g. "ghcr.io/org/image:v1.2.3" → "v1.2.3")
+        const version = result.newImage.includes(":") ? (result.newImage.split(":").pop() ?? "latest") : "latest";
+
+        emitter.emit({
           type: result.success ? "bot.updated" : "bot.update_failed",
           botId: result.botId,
-          tenantId: "",
+          tenantId,
           timestamp: new Date().toISOString(),
+          version,
         });
-      }
-      // Chain user-provided callback
+      })();
       onBotUpdated?.(result);
     },
     onRolloutComplete: (result) => {
@@ -152,6 +168,7 @@ export function initFleetUpdater(
     updater,
     orchestrator,
     snapshotManager,
+    eventEmitter: emitter,
     stop: async () => {
       poller.stop();
       // Wait for any in-flight rollout to complete before returning