create-nexwire 4.2.2 → 4.2.4

package/express/src/framework/maker-cli/stubs/notification/model.ts.stub

@@ -0,0 +1,29 @@
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+/**
+ * Why: Notifications are stored by a standalone module, not by auth.
+ * When: `notify()` writes a row and `/api/notification/*` reads it back.
+ * Where: `src/modules/notification/database/models/notification.ts`.
+ * How: A polymorphic owner (`notifiable_type` + `notifiable_id`) with no
+ *      foreign key, so deleting or replacing auth cannot cascade-delete
+ *      notifications and a UUID or numeric owner id stores the same way.
+ */
+export const notifications = sqliteTable(
+  "notifications",
+  {
+    id: text("id").primaryKey(),
+    notifiableType: text("notifiable_type").notNull().default("user"),
+    notifiableId: text("notifiable_id").notNull(),
+    type: text("type").notNull(),
+    title: text("title").notNull(),
+    body: text("body"),
+    data: text("data"),
+    link: text("link"),
+    readAt: integer("read_at", { mode: "timestamp" }),
+    createdAt: integer("created_at", { mode: "timestamp" }).defaultNow().notNull()
+  },
+  (table) => [
+    index("notifications_notifiable_read_idx").on(table.notifiableType, table.notifiableId, table.readAt),
+    index("notifications_notifiable_created_idx").on(table.notifiableType, table.notifiableId, table.createdAt)
+  ]
+);

package/express/src/framework/maker-cli/stubs/notification/provider.ts.stub

@@ -0,0 +1,174 @@
+import { randomUUID } from "node:crypto";
+import { and, count, desc, eq, isNull } from "drizzle-orm";
+import { db } from "@/framework/database/connection.js";
+import type {
+  NotifiableTarget,
+  NotificationCreateInput,
+  NotificationListOptions,
+  NotificationPage,
+  NotificationProvider,
+  NotificationRecord
+} from "@/framework/providers/contracts.js";
+import { registerNotificationProvider } from "@/framework/providers/registry.js";
+import { notifications } from "@/modules/{{module}}/database/models/notification.js";
+
+/** Normalize a target into the polymorphic pair stored in the table. */
+function normalizeTarget(target: NotifiableTarget) {
+  const type = String(target?.type || "user").trim() || "user";
+  if (target?.id === undefined || target?.id === null || target?.id === "") {
+    throw new Error("A notification target needs an id.");
+  }
+  return { type, id: String(target.id) };
+}
+
+/** Build the owner scope shared by every read and write. */
+function scope(target: NotifiableTarget) {
+  const normalized = normalizeTarget(target);
+  return {
+    target: normalized,
+    where: and(eq(notifications.notifiableType, normalized.type), eq(notifications.notifiableId, normalized.id))
+  };
+}
+
+function toIso(value: Date | string | number | null | undefined): string | null {
+  if (value === null || value === undefined) return null;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function parseData(value: unknown): Record<string, unknown> | null {
+  if (!value) return null;
+  if (typeof value === "object") return value as Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(String(value));
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Convert a DB row into the stable shape every consumer receives. */
+function normalizeRow(row: typeof notifications.$inferSelect): NotificationRecord {
+  return {
+    id: String(row.id),
+    notifiableType: row.notifiableType,
+    notifiableId: row.notifiableId,
+    type: row.type,
+    title: row.title,
+    body: row.body ?? null,
+    data: parseData(row.data),
+    link: row.link ?? null,
+    readAt: toIso(row.readAt),
+    createdAt: toIso(row.createdAt) ?? new Date(0).toISOString()
+  };
+}
+
+/**
+ * Why: Ships a working notification store so `notify()` needs no setup.
+ * When: Imported at boot by the provider loader (and lazily by the resolver).
+ * Where: `src/modules/notification/providers/notification.ts`.
+ * How: Drizzle-backed implementation of `NotificationProvider`. The primary
+ *      key is a UUID string, so ids never depend on the auth table; numeric
+ *      targets are accepted and stored as text by the contract.
+ */
+export const notificationProvider: NotificationProvider = {
+  async create(target: NotifiableTarget, input: NotificationCreateInput): Promise<NotificationRecord> {
+    const { target: normalized } = scope(target);
+    const id = randomUUID();
+
+    await db.insert(notifications).values({
+      id,
+      notifiableType: normalized.type,
+      notifiableId: normalized.id,
+      type: input.type || "info",
+      title: input.title,
+      body: input.body ?? null,
+      link: input.link ?? null,
+      data: input.data ? JSON.stringify(input.data) : null
+    });
+
+    const [row] = await db.select().from(notifications).where(eq(notifications.id, id));
+    if (!row) throw new Error("Failed to create notification");
+    return normalizeRow(row);
+  },
+
+  async list(target: NotifiableTarget, options: NotificationListOptions = {}): Promise<NotificationPage> {
+    const { where } = scope(target);
+    const page = Math.max(1, Math.floor(Number(options.page) || 1));
+    const perPage = Math.min(100, Math.max(1, Math.floor(Number(options.perPage) || 20)));
+
+    const [totalRows, unreadRows, rows] = await Promise.all([
+      db.select({ count: count() }).from(notifications).where(where),
+      db.select({ count: count() }).from(notifications).where(and(where, isNull(notifications.readAt))),
+      db
+        .select()
+        .from(notifications)
+        .where(where)
+        .orderBy(desc(notifications.createdAt))
+        .limit(perPage)
+        .offset((page - 1) * perPage)
+    ]);
+
+    return {
+      data: rows.map(normalizeRow),
+      total: Number(totalRows[0]?.count ?? 0),
+      unread: Number(unreadRows[0]?.count ?? 0),
+      page,
+      perPage
+    };
+  },
+
+  async unreadCount(target: NotifiableTarget): Promise<number> {
+    const { where } = scope(target);
+    const rows = await db
+      .select({ count: count() })
+      .from(notifications)
+      .where(and(where, isNull(notifications.readAt)));
+    return Number(rows[0]?.count ?? 0);
+  },
+
+  async markRead(target: NotifiableTarget, id: number | string): Promise<boolean> {
+    const { where } = scope(target);
+    const notificationWhere = and(where, eq(notifications.id, String(id)));
+    const [existing] = await db.select({ id: notifications.id }).from(notifications).where(notificationWhere);
+    if (!existing) return false;
+
+    await db.update(notifications).set({ readAt: new Date() }).where(notificationWhere);
+    return true;
+  },
+
+  async markAllRead(target: NotifiableTarget): Promise<number> {
+    const { where } = scope(target);
+    const unreadWhere = and(where, isNull(notifications.readAt));
+    const rows = await db.select({ count: count() }).from(notifications).where(unreadWhere);
+    const unread = Number(rows[0]?.count ?? 0);
+    if (unread === 0) return 0;
+
+    await db.update(notifications).set({ readAt: new Date() }).where(unreadWhere);
+    return unread;
+  },
+
+  async remove(target: NotifiableTarget, id: number | string): Promise<boolean> {
+    const { where } = scope(target);
+    const notificationWhere = and(where, eq(notifications.id, String(id)));
+    const [existing] = await db.select({ id: notifications.id }).from(notifications).where(notificationWhere);
+    if (!existing) return false;
+
+    await db.delete(notifications).where(notificationWhere);
+    return true;
+  },
+
+  async deleteForTarget(target: NotifiableTarget): Promise<number> {
+    const { where } = scope(target);
+    const rows = await db.select({ count: count() }).from(notifications).where(where);
+    const total = Number(rows[0]?.count ?? 0);
+    if (total === 0) return 0;
+
+    await db.delete(notifications).where(where);
+    return total;
+  }
+};
+
+registerNotificationProvider(notificationProvider);
+
+export default notificationProvider;

package/express/src/framework/maker-cli/stubs/notification/route.api.ts.stub

@@ -1,43 +1,45 @@
 import { createRoute, createRouter, HttpStatusCodes, jsonContent, z } from "@/framework/facade.js";
 import { authMiddleware } from "@/middlewares/auth-middleware.js";
-import { list, markAllRead, markRead, remove, unreadCount } from "../controllers/{{module}}.js";
-import { PaginatedNotificationsSchema, UnreadCountSchema } from "../schemas/{{module}}.js";
+import { list, markAllRead, markRead, remove, unreadCount } from "../controllers/{{leaf}}.js";
+import { PaginatedNotificationsSchema, UnreadCountSchema } from "../schemas/{{leaf}}.js";
+
+const notificationId = z.object({ id: z.string().min(1) });
 
 const listRoute = createRoute({
   path: "/",
   method: "get",
   tags: ["Notifications"],
-  responses: { [HttpStatusCodes.OK]: jsonContent(PaginatedNotificationsSchema, "Paginated notifications") },
+  responses: { [HttpStatusCodes.OK]: jsonContent(PaginatedNotificationsSchema, "Paginated notifications") }
 });
 
 const unreadCountRoute = createRoute({
   path: "/unread-count",
   method: "get",
   tags: ["Notifications"],
-  responses: { [HttpStatusCodes.OK]: jsonContent(UnreadCountSchema, "Unread count") },
+  responses: { [HttpStatusCodes.OK]: jsonContent(UnreadCountSchema, "Unread count") }
 });
 
 const markReadRoute = createRoute({
   path: "/{id}/read",
   method: "patch",
   tags: ["Notifications"],
-  request: { params: z.object({ id: z.coerce.number() }) },
-  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "Marked as read") },
+  request: { params: notificationId },
+  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "Marked as read") }
 });
 
 const markAllReadRoute = createRoute({
   path: "/read-all",
   method: "patch",
   tags: ["Notifications"],
-  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "All marked as read") },
+  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "All marked as read") }
 });
 
 const deleteRoute = createRoute({
   path: "/{id}",
   method: "delete",
   tags: ["Notifications"],
-  request: { params: z.object({ id: z.coerce.number() }) },
-  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "Deleted") },
+  request: { params: notificationId },
+  responses: { [HttpStatusCodes.OK]: jsonContent(z.object({ ok: z.boolean() }), "Deleted") }
 });
 
 export default createRouter()
@@ -47,4 +49,3 @@ export default createRouter()
   .api(markReadRoute, markRead)
   .api(markAllReadRoute, markAllRead)
   .api(deleteRoute, remove);
-

package/express/src/framework/maker-cli/stubs/notification/route.plain.ts.stub

@@ -1,6 +1,6 @@
 import { group } from "@/framework/facade.js";
 import { authMiddleware } from "@/middlewares/auth-middleware.js";
-import { list, unreadCount, markRead, markAllRead, remove } from "../controllers/{{module}}.js";
+import { list, unreadCount, markRead, markAllRead, remove } from "../controllers/{{leaf}}.js";
 
 export default group()
   .use(authMiddleware)

package/express/src/framework/maker-cli/stubs/notification/schema.plain.ts.stub

@@ -1,26 +1,26 @@
-import { z } from "@/framework/facade.js";
-
-export const NotificationSchema = z.object({
-  id: z.number(),
-  userId: z.number(),
-  type: z.string(),
-  title: z.string(),
-  body: z.string().nullable(),
-  data: z.any().nullable(),
-  link: z.string().nullable(),
-  readAt: z.string().nullable(),
-  createdAt: z.string(),
-});
-
-export const UnreadCountSchema = z.object({
-  count: z.number(),
-});
-
-export const PaginatedNotificationsSchema = z.object({
-  data: z.array(NotificationSchema),
-  total: z.number(),
-  unread: z.number(),
-  page: z.number(),
-  perPage: z.number(),
-});
+import { z } from "@/framework/facade.js";
 
+export const NotificationSchema = z.object({
+  id: z.string(),
+  notifiableType: z.string(),
+  notifiableId: z.string(),
+  type: z.string(),
+  title: z.string(),
+  body: z.string().nullable(),
+  data: z.any().nullable(),
+  link: z.string().nullable(),
+  readAt: z.string().nullable(),
+  createdAt: z.string()
+});
+
+export const UnreadCountSchema = z.object({
+  count: z.number()
+});
+
+export const PaginatedNotificationsSchema = z.object({
+  data: z.array(NotificationSchema),
+  total: z.number(),
+  unread: z.number(),
+  page: z.number(),
+  perPage: z.number()
+});

package/express/src/framework/maker-cli/stubs/notification/schema.ts.stub

@@ -1,26 +1,26 @@
-import { z } from "zod";
-
-export const NotificationSchema = z.object({
-  id: z.number(),
-  userId: z.number(),
-  type: z.string(),
-  title: z.string(),
-  body: z.string().nullable(),
-  data: z.any().nullable(),
-  link: z.string().nullable(),
-  readAt: z.string().nullable(),
-  createdAt: z.string(),
-});
-
-export const UnreadCountSchema = z.object({
-  count: z.number(),
-});
-
-export const PaginatedNotificationsSchema = z.object({
-  data: z.array(NotificationSchema),
-  total: z.number(),
-  unread: z.number(),
-  page: z.number(),
-  perPage: z.number(),
-});
+import { z } from "@/framework/facade.js";
 
+export const NotificationSchema = z.object({
+  id: z.string(),
+  notifiableType: z.string(),
+  notifiableId: z.string(),
+  type: z.string(),
+  title: z.string(),
+  body: z.string().nullable(),
+  data: z.any().nullable(),
+  link: z.string().nullable(),
+  readAt: z.string().nullable(),
+  createdAt: z.string()
+});
+
+export const UnreadCountSchema = z.object({
+  count: z.number()
+});
+
+export const PaginatedNotificationsSchema = z.object({
+  data: z.array(NotificationSchema),
+  total: z.number(),
+  unread: z.number(),
+  page: z.number(),
+  perPage: z.number()
+});

package/express/src/framework/maker-cli/stubs/provider/module-barrel.ts.stub

@@ -0,0 +1,19 @@
+/**
+ * Providers for the {{module}} module.
+ *
+ * This file is imported automatically at boot, so whatever it registers is
+ * available to the whole application. Use this to plug implementations (e.g.
+ * auth, payments) into the app - not to export the module's API to other
+ * modules (that is what facade.ts is for):
+ *
+ *   import { registerProvider } from "@/framework/facade.js";
+ *
+ *   registerProvider("{{module}}", { ... });
+ *
+ * A module with more than one provider keeps them in providers/*.ts instead -
+ * those files are imported at boot too.
+ *
+ * Rule: a module never imports another module's provider implementation.
+ */
+
+export {};

package/express/src/framework/maker-cli/stubs/provider/module.ts.stub

@@ -0,0 +1,21 @@
+import { registerProvider } from "@/framework/facade.js";
+
+/**
+ * Why: Plugs the {{name}} implementation into the application.
+ * When: Imported automatically at boot from each module's providers folder.
+ * Where: src/modules/{{module}}/providers/{{name}}.ts
+ *
+ * Reach it from anywhere in the app:
+ *
+ *   import { getProvider } from "@/framework/facade.js";
+ *   const {{camel}} = getProvider<typeof {{camel}}Provider>("{{name}}");
+ *
+ * Rule: a provider never imports another module's provider implementation.
+ */
+export const {{camel}}Provider = {
+  async handle(input: unknown) {
+    return input;
+  }
+};
+
+registerProvider("{{name}}", {{camel}}Provider);

package/express/src/framework/maker-cli/stubs/provider/name.ts.stub

@@ -0,0 +1,21 @@
+import { registerProvider } from "@/framework/facade.js";
+
+/**
+ * Why: Plugs the {{name}} implementation into the application.
+ * When: Imported automatically at boot from src/providers/.
+ * Where: src/providers/{{name}}.ts
+ *
+ * Reach it from anywhere in the app:
+ *
+ *   import { getProvider } from "@/framework/facade.js";
+ *   const {{camel}} = getProvider<typeof {{camel}}Provider>("{{name}}");
+ *
+ * Rule: a provider never imports another provider's implementation.
+ */
+export const {{camel}}Provider = {
+  async handle(input: unknown) {
+    return input;
+  }
+};
+
+registerProvider("{{name}}", {{camel}}Provider);

package/express/src/framework/maker-cli/utils/help.mjs

@@ -89,7 +89,11 @@ const COMMAND_GROUPS = [
     // `module:make-middleware` writes inside one module and applies only to it.
     // In the same section the two look interchangeable, which is exactly the
     // mistake a developer is about to make.
-    commands: ["middleware:make"]
+    //
+    // `provider:make` follows the same split: it writes to src/providers and
+    // applies to the whole app, `module:make-provider` writes inside one
+    // module and applies only to it.
+    commands: ["middleware:make", "provider:make"]
   },
   {
     title: "Generators - modules",
@@ -107,6 +111,7 @@ const COMMAND_GROUPS = [
       "module:make-test",
       "module:make-helper",
       "module:make-middleware",
+      "module:make-provider",
       "module:make-type"
     ]
   },

package/express/src/framework/notification/index.ts

@@ -1,10 +1,13 @@
-import { eq } from "drizzle-orm";
-import { db } from "@/framework/database/connection.js";
 import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import { resolveAuthProvider, resolveNotificationProvider } from "@/framework/providers/adapter.js";
+import type { NotifiableTarget, NotificationRecord } from "@/framework/providers/contracts.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
 import { mail } from "@/framework/support/mail.js";
-import { notifications } from "@/modules/auth/database/models/notification.js";
-import { users } from "@/modules/auth/database/models/user.js";
+
+let missingProviderWarned = false;
+
+/** A numeric id (default auth), a string id (UUID/ULID), or an explicit target. */
+export type NotificationTarget = number | string | NotifiableTarget;
 
 /** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */
 export type NotificationOptions = {
@@ -22,36 +25,62 @@ export type NotificationOptions = {
   broadcast?: boolean;
   /** Email delivery options */
   mail?: {
+    /** Explicit recipient. Skips the auth provider contact lookup. */
+    to?: string;
     subject?: string;
     html?: string;
   };
 };
 
-/** Create a notification and persist it to the database. Optionally broadcast via Socket.IO and/or send by email. */
-export async function notify(userId: number, options: NotificationOptions) {
-  const insertResult = await db.insert(notifications).values({
-    userId,
-    type: options.type || "info",
-    title: options.title,
-    body: options.body || null,
-    link: options.link || null,
-    data: options.data ? JSON.stringify(options.data) : null
-  });
+/** Turn the public target argument into the polymorphic owner pair. */
+function normalizeTarget(target: NotificationTarget): Required<Pick<NotifiableTarget, "id">> & { type: string } {
+  if (target !== null && typeof target === "object") {
+    return {
+      type: String(target.type || "user").trim() || "user",
+      id: target.id
+    };
+  }
+  return { type: "user", id: target as number | string };
+}
 
-  const insertedId = Number((insertResult as any)[0]?.insertId ?? (insertResult as any).insertId ?? (insertResult as any).lastInsertRowid);
-  if (!insertedId) throw new Error("Failed to create notification");
+/**
+ * Why: Persists a notification through the registered provider.
+ * When: A feature wants to record something for a user (or another notifiable).
+ * Where: Application code, through the framework facade.
+ * How: The provider owns storage; broadcasting and email stay here so a custom
+ *      store cannot silently disable them. A missing provider is reported once
+ *      and returns `null` instead of throwing, matching the framework's
+ *      "optional module" behaviour.
+ */
+export async function notify(target: NotificationTarget, options: NotificationOptions): Promise<NotificationRecord | null> {
+  const provider = await resolveNotificationProvider();
+  if (!provider) {
+    if (!missingProviderWarned) {
+      missingProviderWarned = true;
+      console.warn(
+        '[notification] skipped: no notification provider is registered. Run "bun maker module:make-notification notification" then "bun maker module:migrate notification", or register a provider in src/providers/.'
+      );
+    }
+    return null;
+  }
 
-  const [row] = await db.select().from(notifications).where(eq(notifications.id, insertedId));
-  const normalized = normalize(row);
+  const normalizedTarget = normalizeTarget(target);
+  const normalized = await provider.create(normalizedTarget, {
+    type: options.type,
+    title: options.title,
+    body: options.body ?? null,
+    link: options.link ?? null,
+    data: options.data ?? null
+  });
 
   if (options.broadcast) {
     await dispatchEvent("notification.created", normalized, {
-      broadcast: { users: [userId] }
+      broadcast: { users: [normalizedTarget.id] }
     });
   }
 
   if (options.mail) {
-    await sendMailChannel(userId, normalized, options);
+    await sendMailChannel(normalizedTarget, normalized, options);
   }
 
   return normalized;
@@ -59,13 +88,23 @@ export async function notify(userId: number, options: NotificationOptions) {
 
 /** Deliver an email notification, either queued (if Redis is available) or direct. */
 async function sendMailChannel(
-  userId: number,
-  notification: { id: number; title: string; body: string | null },
+  target: { type: string; id: number | string },
+  notification: NotificationRecord,
   options: NotificationOptions
 ) {
-  const [user] = await db.select({ email: users.email, name: users.name }).from(users).where(eq(users.id, userId));
+  let to: string | null = options.mail?.to || null;
 
-  if (!user?.email) return;
+  if (!to) {
+    try {
+      const provider = await resolveAuthProvider();
+      if (provider?.getUserContact) {
+        const contact = await provider.getUserContact(target.id);
+        if (contact?.email) to = contact.email as string;
+      }
+    } catch {}
+  }
+
+  if (!to) return;
 
   const subject = options.mail?.subject || notification.title;
   const html = options.mail?.html || defaultMailHtml(notification.title, notification.body);
@@ -74,14 +113,14 @@ async function sendMailChannel(
     await dispatchEvent(
       "notification:mail",
       {
-        to: user.email,
+        to,
         subject,
         html
       },
       { queue: "mail" }
     );
   } else {
-    await mail.sendMail({ to: user.email, subject, html });
+    await mail.sendMail({ to, subject, html });
   }
 }
 
@@ -93,24 +132,3 @@ function defaultMailHtml(title: string, body: string | null) {
 function escapeHtml(str: string) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-
-/** Convert a DB row into the normalized response shape, parsing the `data` JSON column. */
-function normalize(row: typeof notifications.$inferSelect) {
-  let parsed: unknown = null;
-  if (row.data) {
-    try {
-      parsed = JSON.parse(row.data);
-    } catch {}
-  }
-  return {
-    id: row.id,
-    userId: row.userId,
-    type: row.type,
-    title: row.title,
-    body: row.body,
-    data: parsed,
-    link: row.link,
-    readAt: row.readAt?.toISOString() || null,
-    createdAt: row.createdAt.toISOString()
-  };
-}