@unifiedcommerce/plugin-notifications 0.0.1

package/dist/adapters/console.d.ts

@@ -0,0 +1,17 @@
+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 declare function consoleSMSAdapter(): SMSAdapter;
+/**
+ * Console Push adapter — logs push notifications to stdout.
+ * Use for development and testing. Replace with a real adapter (e.g. FCM) in production.
+ */
+export declare function consolePushAdapter(): PushAdapter;
+/**
+ * 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 declare function consolePrintAdapter(): PrintAdapter;
+//# sourceMappingURL=console.d.ts.map

package/dist/adapters/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/adapters/console.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAErE;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,UAAU,CAS9C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,CAWhD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,YAAY,CAWlD"}

package/dist/adapters/console.js

@@ -0,0 +1,44 @@
+import { randomUUID } from "node:crypto";
+import { Ok } 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() {
+    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() {
+    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() {
+    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/dist/adapters/types.d.ts

@@ -0,0 +1,62 @@
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,IAAI,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACpF;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,IAAI,CAAC,MAAM,EAAE;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,GAAG,OAAO,CAAC,MAAM,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,KAAK,CAAC,MAAM,EAAE;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;KAC3C,GAAG,OAAO,CAAC,MAAM,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACxC;AAED,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB"}

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { NotificationAdapters } from "./adapters/types";
+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 declare function notificationsPlugin(adapters?: NotificationAdapters): import("@unifiedcommerce/core").CommercePlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,YAAY,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAClC,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACzM,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEhG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,oBAAoB,kDAoBlE"}

package/dist/index.js

@@ -0,0 +1,46 @@
+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";
+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) {
+    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/dist/routes/notifications.d.ts

@@ -0,0 +1,11 @@
+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 declare function buildNotificationRoutes(notifService: NotificationService, prefService: PreferenceService, printService: PrintService, ctx: {
+    services?: Record<string, unknown>;
+    database?: {
+        db: unknown;
+    };
+}): PluginRouteRegistration[];
+//# sourceMappingURL=notifications.d.ts.map

package/dist/routes/notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/routes/notifications.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,mBAAmB,EACjC,WAAW,EAAE,iBAAiB,EAC9B,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GACtE,uBAAuB,EAAE,CA0L3B"}

package/dist/routes/notifications.js

@@ -0,0 +1,170 @@
+import { router } from "@unifiedcommerce/core";
+import { z } from "@hono/zod-openapi";
+export function buildNotificationRoutes(notifService, prefService, printService, ctx) {
+    // ── 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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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;
+        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(),
+    ];
+}