@porulle/plugin-notifications 0.1.0

package/src/adapters/types.ts

@@ -0,0 +1,56 @@
+import type { Result } from "../types.js";
+
+/**
+ * SMS Adapter interface.
+ *
+ * Implement this interface to integrate with an SMS provider (e.g. Twilio, Vonage).
+ * The `send` method delivers a text message to the given phone number.
+ */
+export interface SMSAdapter {
+  /** Unique provider identifier (e.g. "twilio", "vonage", "console"). */
+  providerId: string;
+  /** Send an SMS message to the given phone number. */
+  send(params: { to: string; body: string }): Promise<Result<{ messageId: string }>>;
+}
+
+/**
+ * Push Notification Adapter interface.
+ *
+ * Implement this interface to integrate with a push notification service
+ * (e.g. Firebase Cloud Messaging, Apple Push Notification Service).
+ */
+export interface PushAdapter {
+  /** Unique provider identifier (e.g. "fcm", "apns", "console"). */
+  providerId: string;
+  /** Send a push notification to the given device token. */
+  send(params: {
+    deviceToken: string;
+    title: string;
+    body: string;
+    data?: Record<string, unknown>;
+  }): Promise<Result<{ messageId: string }>>;
+}
+
+/**
+ * Print Adapter interface.
+ *
+ * Implement this interface to integrate with a receipt/label printer
+ * (e.g. Epson ESC/POS, Star Line Mode printers).
+ */
+export interface PrintAdapter {
+  /** Unique provider identifier (e.g. "esc_pos", "star", "console"). */
+  providerId: string;
+  /** Send a print job to the given printer. */
+  print(params: {
+    printerId: string;
+    content: Record<string, unknown>;
+    format: "esc_pos" | "star_line" | "label";
+  }): Promise<Result<{ jobId: string }>>;
+}
+
+/** Configuration object for notification adapters. */
+export interface NotificationAdapters {
+  sms?: SMSAdapter;
+  push?: PushAdapter;
+  print?: PrintAdapter;
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+import { defineCommercePlugin } from "@porulle/core";
+import { notificationTemplates, customerNotificationPrefs, notificationLog, printJobs } from "./schema.js";
+import { NotificationService } from "./services/notification-service.js";
+import { PreferenceService } from "./services/preference-service.js";
+import { PrintService } from "./services/print-service.js";
+import { buildNotificationRoutes } from "./routes/notifications.js";
+import type { NotificationAdapters } from "./adapters/types.js";
+
+// Re-exports for consumers
+export type { Db } from "./types.js";
+export type { NotificationTemplate, CustomerNotificationPref, NotificationLogEntry, PrintJob, Result, ResultErr, Channel, PrefChannel, NotificationStatus, PrintJobStatus, PrintJobType } from "./types.js";
+export type { SMSAdapter, PushAdapter, PrintAdapter, NotificationAdapters } from "./adapters/types.js";
+export { NotificationService } from "./services/notification-service.js";
+export { PreferenceService } from "./services/preference-service.js";
+export { PrintService } from "./services/print-service.js";
+export { consoleSMSAdapter, consolePushAdapter, consolePrintAdapter } from "./adapters/console.js";
+
+/**
+ * Notifications Plugin (RFC-030)
+ *
+ * Provides:
+ * - Notification template CRUD with Handlebars-style rendering
+ * - Multi-channel dispatch (email, SMS, push, print)
+ * - Customer notification preferences (opt-out model)
+ * - Notification log with status tracking
+ * - Print job management (receipt, label, sticker, KOT)
+ * - Pluggable adapter architecture for SMS, Push, and Print providers
+ *
+ * @param adapters - Optional adapter configuration. Pass console adapters for dev,
+ *   or real adapters (Twilio, FCM, ESC/POS) for production.
+ */
+export function notificationsPlugin(adapters?: NotificationAdapters) {
+  return defineCommercePlugin({
+    id: "notifications",
+    version: "1.0.0",
+    permissions: [
+      { scope: "notifications:admin", description: "Manage notification templates, send notifications, view log, manage print jobs." },
+      { scope: "notifications:write", description: "Set customer notification preferences." },
+      { scope: "notifications:read", description: "View customer notification preferences." },
+    ],
+    schema: () => ({ notificationTemplates, customerNotificationPrefs, notificationLog, printJobs }),
+    hooks: () => [],
+    routes: (ctx) => {
+      const db = ctx.database.db;
+      if (!db) return [];
+      const notifService = new NotificationService(db, adapters);
+      const prefService = new PreferenceService(db);
+      const printService = new PrintService(db, adapters?.print);
+      return buildNotificationRoutes(notifService, prefService, printService, ctx);
+    },
+  });
+}

package/src/routes/notifications.ts

@@ -0,0 +1,199 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { NotificationService } from "../services/notification-service.js";
+import type { PreferenceService } from "../services/preference-service.js";
+import type { PrintService } from "../services/print-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+
+export function buildNotificationRoutes(
+  notifService: NotificationService,
+  prefService: PreferenceService,
+  printService: PrintService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  // ── Template Routes ────────────────────────────────────────────────
+  const tmpl = router("Notification Templates", "/notifications/templates", ctx);
+
+  tmpl.post("/").summary("Create notification template").permission("notifications:admin")
+    .input(z.object({
+      event: z.string().min(1),
+      channel: z.enum(["email", "sms", "push", "print"]),
+      subject: z.string().optional(),
+      bodyTemplate: z.string().min(1),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as { event: string; channel: "email" | "sms" | "push" | "print"; subject?: string; bodyTemplate: string };
+      const result = await notifService.createTemplate(orgId, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  tmpl.get("/").summary("List notification templates").permission("notifications:admin")
+    .query(z.object({
+      event: z.string().optional(),
+      channel: z.enum(["email", "sms", "push", "print"]).optional(),
+    }))
+    .handler(async ({ query, orgId }) => {
+      const q = query as { event?: string; channel?: "email" | "sms" | "push" | "print" };
+      const result = await notifService.listTemplates(orgId, q);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  tmpl.get("/{id}").summary("Get notification template").permission("notifications:admin")
+    .handler(async ({ params, orgId }) => {
+      const result = await notifService.getTemplate(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  tmpl.patch("/{id}").summary("Update notification template").permission("notifications:admin")
+    .input(z.object({
+      subject: z.string().optional(),
+      bodyTemplate: z.string().optional(),
+      isActive: z.boolean().optional(),
+    }))
+    .handler(async ({ params, input, orgId }) => {
+      const body = input as { subject?: string; bodyTemplate?: string; isActive?: boolean };
+      const result = await notifService.updateTemplate(orgId, params.id!, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  tmpl.delete("/{id}").summary("Soft-delete notification template").permission("notifications:admin")
+    .handler(async ({ params, orgId }) => {
+      const result = await notifService.deleteTemplate(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  // ── Send Route ─────────────────────────────────────────────────────
+  const send = router("Notifications", "/notifications", ctx);
+
+  send.post("/send").summary("Send notification").permission("notifications:admin")
+    .input(z.object({
+      event: z.string().min(1),
+      recipient: z.string().min(1),
+      channel: z.enum(["email", "sms", "push", "print"]),
+      customerId: z.string().uuid().optional(),
+      data: z.record(z.string(), z.unknown()).optional(),
+      metadata: z.record(z.string(), z.unknown()).optional(),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as {
+        event: string; recipient: string; channel: "email" | "sms" | "push" | "print";
+        customerId?: string; data?: Record<string, unknown>; metadata?: Record<string, unknown>;
+      };
+      const result = await notifService.send(orgId, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  // ── Log Route ──────────────────────────────────────────────────────
+  send.get("/log").summary("Query notification log").permission("notifications:admin")
+    .query(z.object({
+      channel: z.string().optional(),
+      event: z.string().optional(),
+      status: z.enum(["queued", "sent", "delivered", "failed"]).optional(),
+      limit: z.coerce.number().int().positive().optional(),
+    }))
+    .handler(async ({ query, orgId }) => {
+      const q = query as { channel?: string; event?: string; status?: "queued" | "sent" | "delivered" | "failed"; limit?: number };
+      const result = await notifService.listLog(orgId, q);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  // ── Preference Routes ──────────────────────────────────────────────
+  const pref = router("Notification Preferences", "/notifications/preferences", ctx);
+
+  pref.post("/").summary("Set customer notification preference").permission("notifications:write")
+    .input(z.object({
+      customerId: z.string().uuid(),
+      channel: z.enum(["email", "sms", "push"]),
+      isEnabled: z.boolean(),
+      destination: z.string().optional(),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as { customerId: string; channel: "email" | "sms" | "push"; isEnabled: boolean; destination?: string };
+      const result = await prefService.setPreference(
+        orgId, body.customerId, body.channel, body.isEnabled, body.destination,
+      );
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  pref.get("/{customerId}").summary("Get customer notification preferences").permission("notifications:read")
+    .handler(async ({ params, orgId }) => {
+      const result = await prefService.getPreferences(orgId, params.customerId!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  // ── Print Routes ───────────────────────────────────────────────────
+  const print = router("Print Jobs", "/notifications/print", ctx);
+
+  print.post("/").summary("Submit print job").permission("notifications:admin")
+    .input(z.object({
+      type: z.enum(["receipt", "label", "sticker", "kot"]),
+      printerId: z.string().min(1),
+      content: z.record(z.string(), z.unknown()),
+      format: z.enum(["esc_pos", "star_line", "label"]).optional(),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as {
+        type: "receipt" | "label" | "sticker" | "kot";
+        printerId: string;
+        content: Record<string, unknown>;
+        format?: "esc_pos" | "star_line" | "label";
+      };
+      const result = await printService.submitJob(orgId, body);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  print.get("/{id}").summary("Get print job").permission("notifications:admin")
+    .handler(async ({ params, orgId }) => {
+      const result = await printService.getJob(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  print.get("/").summary("List print jobs").permission("notifications:admin")
+    .query(z.object({
+      status: z.enum(["queued", "printing", "printed", "failed"]).optional(),
+      printerId: z.string().optional(),
+      type: z.enum(["receipt", "label", "sticker", "kot"]).optional(),
+      limit: z.coerce.number().int().positive().optional(),
+    }))
+    .handler(async ({ query, orgId }) => {
+      const q = query as {
+        status?: "queued" | "printing" | "printed" | "failed";
+        printerId?: string;
+        type?: "receipt" | "label" | "sticker" | "kot";
+        limit?: number;
+      };
+      const result = await printService.listJobs(orgId, q);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  print.patch("/{id}/status").summary("Update print job status").permission("notifications:admin")
+    .input(z.object({
+      status: z.enum(["queued", "printing", "printed", "failed"]),
+      error: z.string().optional(),
+    }))
+    .handler(async ({ params, input, orgId }) => {
+      const body = input as { status: "queued" | "printing" | "printed" | "failed"; error?: string };
+      const result = await printService.updateJobStatus(orgId, params.id!, body.status, body.error);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return [
+    ...tmpl.routes(),
+    ...send.routes(),
+    ...pref.routes(),
+    ...print.routes(),
+  ];
+}

package/src/schema.ts

@@ -0,0 +1,67 @@
+import { pgTable, uuid, text, boolean, timestamp, index, uniqueIndex, jsonb } from "@porulle/core/drizzle";
+
+export const notificationTemplates = pgTable("notification_templates", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  event: text("event").notNull(),
+  channel: text("channel", { enum: ["email", "sms", "push", "print"] }).notNull(),
+  subject: text("subject"),
+  bodyTemplate: text("body_template").notNull(),
+  isActive: boolean("is_active").notNull().default(true),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_notification_templates_org").on(table.organizationId),
+  orgEventChannelUnique: uniqueIndex("notification_templates_org_event_channel_unique").on(
+    table.organizationId, table.event, table.channel,
+  ),
+}));
+
+export const customerNotificationPrefs = pgTable("customer_notification_prefs", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  customerId: uuid("customer_id").notNull(),
+  channel: text("channel", { enum: ["email", "sms", "push"] }).notNull(),
+  isEnabled: boolean("is_enabled").notNull().default(true),
+  destination: text("destination"),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_customer_notification_prefs_org").on(table.organizationId),
+  orgCustomerChannelUnique: uniqueIndex("customer_notification_prefs_org_cust_channel_unique").on(
+    table.organizationId, table.customerId, table.channel,
+  ),
+}));
+
+export const notificationLog = pgTable("notification_log", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  channel: text("channel").notNull(),
+  event: text("event").notNull(),
+  recipient: text("recipient").notNull(),
+  status: text("status", { enum: ["queued", "sent", "delivered", "failed"] }).notNull().default("queued"),
+  error: text("error"),
+  metadata: jsonb("metadata").notNull().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_notification_log_org").on(table.organizationId),
+  channelIdx: index("idx_notification_log_channel").on(table.channel),
+  eventIdx: index("idx_notification_log_event").on(table.event),
+  statusIdx: index("idx_notification_log_status").on(table.status),
+}));
+
+export const printJobs = pgTable("print_jobs", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  type: text("type", { enum: ["receipt", "label", "sticker", "kot"] }).notNull(),
+  printerId: text("printer_id").notNull(),
+  content: jsonb("content").notNull().default({}),
+  status: text("status", { enum: ["queued", "printing", "printed", "failed"] }).notNull().default("queued"),
+  error: text("error"),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_print_jobs_org").on(table.organizationId),
+  statusIdx: index("idx_print_jobs_status").on(table.status),
+  printerIdx: index("idx_print_jobs_printer").on(table.printerId),
+}));

package/src/services/notification-service.ts

@@ -0,0 +1,270 @@
+import { eq, and } from "@porulle/core/drizzle";
+import { notificationTemplates, customerNotificationPrefs, notificationLog } from "../schema.js";
+import type {
+  Db, NotificationTemplate, NotificationLogEntry, Channel, NotificationStatus,
+  Result,
+} from "../types.js";
+import { Ok, Err } from "../types.js";
+import type { SMSAdapter, PushAdapter, NotificationAdapters } from "../adapters/types.js";
+
+export class NotificationService {
+  private smsAdapter: SMSAdapter | undefined;
+  private pushAdapter: PushAdapter | undefined;
+
+  constructor(private db: Db, adapters?: NotificationAdapters) {
+    this.smsAdapter = adapters?.sms;
+    this.pushAdapter = adapters?.push;
+  }
+
+  // ── Template CRUD ──────────────────────────────────────────────────
+
+  async createTemplate(orgId: string, input: {
+    event: string; channel: Channel; subject?: string; bodyTemplate: string;
+  }): Promise<Result<NotificationTemplate>> {
+    const existing = await this.db.select().from(notificationTemplates)
+      .where(and(
+        eq(notificationTemplates.organizationId, orgId),
+        eq(notificationTemplates.event, input.event),
+        eq(notificationTemplates.channel, input.channel),
+      ));
+    if (existing.length > 0) return Err(`Template for '${input.event}' on '${input.channel}' already exists`);
+    const rows = await this.db.insert(notificationTemplates).values({
+      organizationId: orgId,
+      event: input.event,
+      channel: input.channel,
+      subject: input.subject,
+      bodyTemplate: input.bodyTemplate,
+    }).returning();
+    return Ok(rows[0]!);
+  }
+
+  async listTemplates(orgId: string, filters?: {
+    event?: string; channel?: Channel;
+  }): Promise<Result<NotificationTemplate[]>> {
+    const conditions = [eq(notificationTemplates.organizationId, orgId)];
+    if (filters?.event) conditions.push(eq(notificationTemplates.event, filters.event));
+    if (filters?.channel) conditions.push(eq(notificationTemplates.channel, filters.channel));
+    const rows = await this.db.select().from(notificationTemplates).where(and(...conditions));
+    return Ok(rows);
+  }
+
+  async getTemplate(orgId: string, id: string): Promise<Result<NotificationTemplate>> {
+    const rows = await this.db.select().from(notificationTemplates)
+      .where(and(eq(notificationTemplates.organizationId, orgId), eq(notificationTemplates.id, id)));
+    if (rows.length === 0) return Err("Template not found");
+    return Ok(rows[0]!);
+  }
+
+  async updateTemplate(orgId: string, id: string, input: {
+    subject?: string; bodyTemplate?: string; isActive?: boolean;
+  }): Promise<Result<NotificationTemplate>> {
+    const existing = await this.db.select().from(notificationTemplates)
+      .where(and(eq(notificationTemplates.organizationId, orgId), eq(notificationTemplates.id, id)));
+    if (existing.length === 0) return Err("Template not found");
+    const rows = await this.db.update(notificationTemplates).set({
+      ...(input.subject !== undefined ? { subject: input.subject } : {}),
+      ...(input.bodyTemplate !== undefined ? { bodyTemplate: input.bodyTemplate } : {}),
+      ...(input.isActive !== undefined ? { isActive: input.isActive } : {}),
+      updatedAt: new Date(),
+    }).where(eq(notificationTemplates.id, id)).returning();
+    return Ok(rows[0]!);
+  }
+
+  async deleteTemplate(orgId: string, id: string): Promise<Result<NotificationTemplate>> {
+    const existing = await this.db.select().from(notificationTemplates)
+      .where(and(eq(notificationTemplates.organizationId, orgId), eq(notificationTemplates.id, id)));
+    if (existing.length === 0) return Err("Template not found");
+    const rows = await this.db.update(notificationTemplates).set({
+      isActive: false,
+      updatedAt: new Date(),
+    }).where(eq(notificationTemplates.id, id)).returning();
+    return Ok(rows[0]!);
+  }
+
+  // ── Template Rendering ─────────────────────────────────────────────
+
+  /**
+   * Simple Handlebars-style template rendering.
+   * Replaces {{key}} with values from the data object.
+   * Supports nested keys via dot notation: {{order.id}}.
+   */
+  renderTemplate(template: string, data: Record<string, unknown>): string {
+    return template.replace(/\{\{(\w+(?:\.\w+)*)\}\}/g, (_match, key: string) => {
+      const parts = key.split(".");
+      let value: unknown = data;
+      for (const part of parts) {
+        if (value == null || typeof value !== "object") return "";
+        value = (value as Record<string, unknown>)[part];
+      }
+      return value != null ? String(value) : "";
+    });
+  }
+
+  // ── Send Notification ──────────────────────────────────────────────
+
+  /**
+   * Unified send: resolves template, checks customer preferences,
+   * dispatches to the correct channel adapter, and logs the result.
+   */
+  async send(orgId: string, input: {
+    event: string;
+    recipient: string;
+    channel: Channel;
+    customerId?: string;
+    data?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+  }): Promise<Result<NotificationLogEntry>> {
+    // Check customer preference if customerId is provided and channel is not "print"
+    if (input.customerId && input.channel !== "print") {
+      const prefChannel = input.channel as "email" | "sms" | "push";
+      const prefs = await this.db.select().from(customerNotificationPrefs)
+        .where(and(
+          eq(customerNotificationPrefs.organizationId, orgId),
+          eq(customerNotificationPrefs.customerId, input.customerId),
+          eq(customerNotificationPrefs.channel, prefChannel),
+        ));
+      if (prefs.length > 0 && !prefs[0]!.isEnabled) {
+        return Err(`Customer has disabled ${input.channel} notifications`);
+      }
+    }
+
+    // Resolve template if one exists for this event+channel
+    let body = "";
+    let subject: string | undefined;
+    const templates = await this.db.select().from(notificationTemplates)
+      .where(and(
+        eq(notificationTemplates.organizationId, orgId),
+        eq(notificationTemplates.event, input.event),
+        eq(notificationTemplates.channel, input.channel),
+        eq(notificationTemplates.isActive, true),
+      ));
+
+    if (templates.length > 0) {
+      const tmpl = templates[0]!;
+      body = this.renderTemplate(tmpl.bodyTemplate, input.data ?? {});
+      if (tmpl.subject) {
+        subject = this.renderTemplate(tmpl.subject, input.data ?? {});
+      }
+    }
+
+    // Dispatch to adapter
+    let adapterError: string | undefined;
+    let adapterMessageId: string | undefined;
+
+    if (input.channel === "sms" && this.smsAdapter) {
+      const result = await this.smsAdapter.send({ to: input.recipient, body });
+      if (!result.ok) {
+        adapterError = result.error;
+      } else {
+        adapterMessageId = result.value.messageId;
+      }
+    } else if (input.channel === "push" && this.pushAdapter) {
+      const result = await this.pushAdapter.send({
+        deviceToken: input.recipient,
+        title: subject ?? input.event,
+        body,
+        ...(input.data != null ? { data: input.data } : {}),
+      });
+      if (!result.ok) {
+        adapterError = result.error;
+      } else {
+        adapterMessageId = result.value.messageId;
+      }
+    }
+
+    // Log the result
+    const status: NotificationStatus = adapterError ? "failed" : "sent";
+    const logRows = await this.db.insert(notificationLog).values({
+      organizationId: orgId,
+      channel: input.channel,
+      event: input.event,
+      recipient: input.recipient,
+      status,
+      error: adapterError,
+      metadata: {
+        ...input.metadata,
+        ...(adapterMessageId ? { adapterMessageId } : {}),
+        ...(input.data ? { templateData: input.data } : {}),
+      },
+    }).returning();
+
+    return Ok(logRows[0]!);
+  }
+
+  // ── Direct Channel Sends ───────────────────────────────────────────
+
+  async sendSMS(orgId: string, to: string, body: string): Promise<Result<NotificationLogEntry>> {
+    let adapterError: string | undefined;
+    let adapterMessageId: string | undefined;
+
+    if (this.smsAdapter) {
+      const result = await this.smsAdapter.send({ to, body });
+      if (!result.ok) {
+        adapterError = result.error;
+      } else {
+        adapterMessageId = result.value.messageId;
+      }
+    }
+
+    const status: NotificationStatus = adapterError ? "failed" : "sent";
+    const rows = await this.db.insert(notificationLog).values({
+      organizationId: orgId,
+      channel: "sms",
+      event: "direct.sms",
+      recipient: to,
+      status,
+      error: adapterError,
+      metadata: adapterMessageId ? { adapterMessageId } : {},
+    }).returning();
+
+    return Ok(rows[0]!);
+  }
+
+  async sendPush(
+    orgId: string,
+    deviceToken: string,
+    title: string,
+    body: string,
+    data?: Record<string, unknown>,
+  ): Promise<Result<NotificationLogEntry>> {
+    let adapterError: string | undefined;
+    let adapterMessageId: string | undefined;
+
+    if (this.pushAdapter) {
+      const result = await this.pushAdapter.send({ deviceToken, title, body, ...(data != null ? { data } : {}) });
+      if (!result.ok) {
+        adapterError = result.error;
+      } else {
+        adapterMessageId = result.value.messageId;
+      }
+    }
+
+    const status: NotificationStatus = adapterError ? "failed" : "sent";
+    const rows = await this.db.insert(notificationLog).values({
+      organizationId: orgId,
+      channel: "push",
+      event: "direct.push",
+      recipient: deviceToken,
+      status,
+      error: adapterError,
+      metadata: adapterMessageId ? { adapterMessageId } : {},
+    }).returning();
+
+    return Ok(rows[0]!);
+  }
+
+  // ── Log Queries ────────────────────────────────────────────────────
+
+  async listLog(orgId: string, filters?: {
+    channel?: string; event?: string; status?: NotificationStatus; limit?: number;
+  }): Promise<Result<NotificationLogEntry[]>> {
+    const conditions = [eq(notificationLog.organizationId, orgId)];
+    if (filters?.channel) conditions.push(eq(notificationLog.channel, filters.channel));
+    if (filters?.event) conditions.push(eq(notificationLog.event, filters.event));
+    if (filters?.status) conditions.push(eq(notificationLog.status, filters.status));
+    let query = this.db.select().from(notificationLog).where(and(...conditions)).$dynamic();
+    if (filters?.limit) query = query.limit(filters.limit);
+    const rows = await query;
+    return Ok(rows);
+  }
+}