@unifiedcommerce/plugin-notifications 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+import type { notificationTemplates, customerNotificationPrefs, notificationLog, printJobs } from "./schema";
+export type { PluginDb as Db } from "@unifiedcommerce/core";
+export type NotificationTemplate = typeof notificationTemplates.$inferSelect;
+export type CustomerNotificationPref = typeof customerNotificationPrefs.$inferSelect;
+export type NotificationLogEntry = typeof notificationLog.$inferSelect;
+export type PrintJob = typeof printJobs.$inferSelect;
+export type Channel = "email" | "sms" | "push" | "print";
+export type PrefChannel = "email" | "sms" | "push";
+export type NotificationStatus = "queued" | "sent" | "delivered" | "failed";
+export type PrintJobStatus = "queued" | "printing" | "printed" | "failed";
+export type PrintJobType = "receipt" | "label" | "sticker" | "kot";
+/** Result type re-exports from core. */
+export { Ok, Err } from "@unifiedcommerce/core";
+export type { PluginResult as Result, PluginResultErr as ResultErr } from "@unifiedcommerce/core";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE7G,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,uBAAuB,CAAC;AAC5D,MAAM,MAAM,oBAAoB,GAAG,OAAO,qBAAqB,CAAC,YAAY,CAAC;AAC7E,MAAM,MAAM,wBAAwB,GAAG,OAAO,yBAAyB,CAAC,YAAY,CAAC;AACrF,MAAM,MAAM,oBAAoB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AACvE,MAAM,MAAM,QAAQ,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AACrD,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AACnD,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAC5E,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,CAAC;AAEnE,wCAAwC;AACxC,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAChD,YAAY,EAAE,YAAY,IAAI,MAAM,EAAE,eAAe,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Result type re-exports from core. */
+export { Ok, Err } from "@unifiedcommerce/core";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@unifiedcommerce/plugin-notifications",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/zod-openapi": "^1.2.2",
+    "@unifiedcommerce/core": "*",
+    "drizzle-orm": "^0.45.1",
+    "hono": "^4.12.5"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ]
+}

package/src/adapters/console.ts

@@ -0,0 +1,52 @@
+import { randomUUID } from "node:crypto";
+import { Ok } from "../types";
+import type { SMSAdapter, PushAdapter, PrintAdapter } from "./types";
+
+/**
+ * Console SMS adapter — logs SMS messages to stdout.
+ * Use for development and testing. Replace with a real adapter (e.g. Twilio) in production.
+ */
+export function consoleSMSAdapter(): SMSAdapter {
+  return {
+    providerId: "console",
+    async send(params) {
+      const messageId = `sms_${randomUUID()}`;
+      console.log(`[SMS:console] to=${params.to} body="${params.body}" messageId=${messageId}`);
+      return Ok({ messageId });
+    },
+  };
+}
+
+/**
+ * Console Push adapter — logs push notifications to stdout.
+ * Use for development and testing. Replace with a real adapter (e.g. FCM) in production.
+ */
+export function consolePushAdapter(): PushAdapter {
+  return {
+    providerId: "console",
+    async send(params) {
+      const messageId = `push_${randomUUID()}`;
+      console.log(
+        `[Push:console] token=${params.deviceToken} title="${params.title}" body="${params.body}" messageId=${messageId}`,
+      );
+      return Ok({ messageId });
+    },
+  };
+}
+
+/**
+ * Console Print adapter — logs print jobs to stdout.
+ * Use for development and testing. Replace with a real adapter (e.g. ESC/POS) in production.
+ */
+export function consolePrintAdapter(): PrintAdapter {
+  return {
+    providerId: "console",
+    async print(params) {
+      const jobId = `print_${randomUUID()}`;
+      console.log(
+        `[Print:console] printer=${params.printerId} format=${params.format} jobId=${jobId}`,
+      );
+      return Ok({ jobId });
+    },
+  };
+}

package/src/adapters/types.ts

@@ -0,0 +1,56 @@
+import type { Result } from "../types";
+
+/**
+ * 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,53 @@
+import { defineCommercePlugin } from "@unifiedcommerce/core";
+import { notificationTemplates, customerNotificationPrefs, notificationLog, printJobs } from "./schema";
+import { NotificationService } from "./services/notification-service";
+import { PreferenceService } from "./services/preference-service";
+import { PrintService } from "./services/print-service";
+import { buildNotificationRoutes } from "./routes/notifications";
+import type { Db } from "./types";
+import type { NotificationAdapters } from "./adapters/types";
+
+// Re-exports for consumers
+export type { Db } from "./types";
+export type { NotificationTemplate, CustomerNotificationPref, NotificationLogEntry, PrintJob, Result, ResultErr, Channel, PrefChannel, NotificationStatus, PrintJobStatus, PrintJobType } from "./types";
+export type { SMSAdapter, PushAdapter, PrintAdapter, NotificationAdapters } from "./adapters/types";
+export { NotificationService } from "./services/notification-service";
+export { PreferenceService } from "./services/preference-service";
+export { PrintService } from "./services/print-service";
+export { consoleSMSAdapter, consolePushAdapter, consolePrintAdapter } from "./adapters/console";
+
+/**
+ * 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 as unknown as 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 "@unifiedcommerce/core";
+import { z } from "@hono/zod-openapi";
+import type { NotificationService } from "../services/notification-service";
+import type { PreferenceService } from "../services/preference-service";
+import type { PrintService } from "../services/print-service";
+import type { PluginRouteRegistration } from "@unifiedcommerce/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 "drizzle-orm/pg-core";
+
+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),
+}));