create-nexwire 4.2.3 → 4.2.5

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/notification/index.ts

@@ -1,27 +1,13 @@
-import { eq } from "drizzle-orm";
-import { db } from "@/framework/database/connection.js";
 import { dispatchEvent } from "@/framework/events/dispatcher.js";
-import { resolveAuthProvider } from "@/framework/providers/adapter.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";
 
-let notifications: any = null;
-let modelsLoaded = false;
-let modelsLoadAttempted = false;
-
-async function loadNotificationModel() {
-  if (modelsLoaded) return true;
-  if (modelsLoadAttempted) return false;
-  modelsLoadAttempted = true;
-  try {
-    const notificationMod = await import("@/modules/auth/database/models/notification.js").catch(() => null);
-    if (notificationMod?.notifications) notifications = notificationMod.notifications;
-    modelsLoaded = !!notifications;
-    return modelsLoaded;
-  } catch {
-    return false;
-  }
-}
+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 = {
@@ -46,38 +32,55 @@ export type NotificationOptions = {
   };
 };
 
-/** 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 ok = await loadNotificationModel();
-  if (!ok || !notifications) {
-    console.warn(
-      "[notification] skipped: notification model not available (@/modules/auth/database/models/notification.js). Delete or replace auth/notification without breaking framework."
-    );
+/** 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 };
+}
+
+/**
+ * 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 insertResult = await db.insert(notifications).values({
-    userId,
-    type: options.type || "info",
+
+  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 ? JSON.stringify(options.data) : null
+    body: options.body ?? null,
+    link: options.link ?? null,
+    data: options.data ?? null
   });
 
-  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");
-
-  const [row] = await db.select().from(notifications).where(eq(notifications.id, insertedId));
-  const normalized = normalize(row);
-
   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;
@@ -85,38 +88,18 @@ 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
 ) {
-  let to: string | null = (options.mail as any)?.to || null;
-  let name: string | null = null;
+  let to: string | null = options.mail?.to || null;
 
   if (!to) {
     try {
       const provider = await resolveAuthProvider();
       if (provider?.getUserContact) {
-        const contact = await provider.getUserContact(userId);
-        if (contact?.email) {
-          to = contact.email as string;
-          name = (contact.name as string) || null;
-        }
-      }
-    } catch {}
-  }
-
-  if (!to) {
-    try {
-      const userMod = await import("@/modules/auth/database/models/user.js").catch(() => null);
-      if (userMod?.users) {
-        const [user] = await db
-          .select({ email: userMod.users.email, name: (userMod.users as any).name })
-          .from(userMod.users)
-          .where(eq(userMod.users.id, userId));
-        if (user?.email) {
-          to = user.email as string;
-          name = (user as any).name || null;
-        }
+        const contact = await provider.getUserContact(target.id);
+        if (contact?.email) to = contact.email as string;
       }
     } catch {}
   }
@@ -149,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: any) {
-  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()
-  };
-}

package/express/src/framework/providers/adapter.ts

@@ -1,8 +1,8 @@
 import { eq } from "drizzle-orm";
 import { db } from "@/framework/database/connection.js";
-import type { AuthProvider } from "./contracts.js";
+import type { AuthProvider, NotificationProvider } from "./contracts.js";
 import { loadProviders } from "./loader.js";
-import { getAuthProvider } from "./registry.js";
+import { getAuthProvider, getNotificationProvider } from "./registry.js";
 
 let defaultProvider: AuthProvider | null = null;
 let defaultLoadAttempted = false;
@@ -26,16 +26,16 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
     const refreshTokens = userMod.refreshTokens;
 
     defaultProvider = {
-      async getUserById(id: number) {
+      async getUserById(id: number | string) {
         try {
           const user = await (db.query.users.findFirst as any)?.({
-            where: eq(users.id, id),
+            where: eq(users.id, id as any),
             with: { role: true }
           });
           if (user) return user;
         } catch {}
         try {
-          const rows = await db.select().from(users).where(eq(users.id, id));
+          const rows = await db.select().from(users).where(eq(users.id, id as any));
           return rows?.[0] ?? null;
         } catch {
           return null;
@@ -55,14 +55,14 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
           return null;
         }
       },
-      async deleteRefreshToken(tokenId: number) {
+      async deleteRefreshToken(tokenId: number | string) {
         try {
-          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId));
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId as any));
         } catch {}
       },
-      async revokeRefreshToken(tokenId: number) {
+      async revokeRefreshToken(tokenId: number | string) {
         try {
-          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId));
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId as any));
         } catch {}
       },
       async getAuthContext(user: any, payload?: any) {
@@ -87,7 +87,7 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
           ...user
         };
       },
-      async getUserContact(userId: number) {
+      async getUserContact(userId: number | string) {
         try {
           const user = await this.getUserById(userId);
           if (!user) return null;
@@ -123,3 +123,17 @@ export async function resolveAuthProvider(): Promise<AuthProvider | null> {
   if (def) return def;
   return null;
 }
+
+/**
+ * Why: Resolves the notification storage provider.
+ * When: `notify()` persists a notification; the HTTP handlers read it back.
+ * Where: Notification runtime and the generated notification controller.
+ * How: Provider files are loaded first, so a project can replace the store from
+ *      `src/providers/` or a module provider folder. The notification module is
+ *      opt-in, so an absent provider is a normal state: callers warn once
+ *      (runtime) or answer 503 (HTTP) instead of throwing.
+ */
+export async function resolveNotificationProvider(): Promise<NotificationProvider | null> {
+  await loadProviders();
+  return getNotificationProvider();
+}