@open-mercato/core 0.4.2-canary-e6bf6a353e → 0.4.2-canary-49d47ff90e

package/src/modules/notifications/i18n/en.json

@@ -0,0 +1,50 @@
+{
+  "notifications.nav.title": "Notifications",
+  "notifications.title": "Notifications",
+  "notifications.empty": "No notifications",
+  "notifications.markAllRead": "Mark all read",
+  "notifications.actionTaken": "Action taken: {action}",
+  "notifications.filters.all": "All",
+  "notifications.filters.unread": "Unread",
+  "notifications.filters.actionRequired": "Action Required",
+  "notifications.actions.dismiss": "Dismiss",
+  "notifications.actions.undo": "Undo",
+  "notifications.actions.markRead": "Mark as read",
+  "notifications.toast.new": "New notification",
+  "notifications.toast.dismissed": "Notification dismissed",
+  "notifications.toast.actionSuccess": "Action completed successfully",
+  "notifications.toast.actionError": "Failed to execute action",
+  "notifications.error.load": "Failed to load notifications",
+  "notifications.error.action": "Failed to execute action",
+  "notifications.badge.unread": "{count} unread notifications",
+  "notifications.delivery.email.preview": "New notification",
+  "notifications.delivery.email.heading": "You have a new notification",
+  "notifications.delivery.email.bodyIntro": "Review the notification details and take any required actions.",
+  "notifications.delivery.email.actionNotice": "Actions are available in Open Mercato and are read-only in this email.",
+  "notifications.delivery.email.openCta": "Open notification center",
+  "notifications.delivery.email.footer": "Open Mercato notifications",
+  "notifications.delivery.settings.invalid": "Invalid delivery settings",
+  "notifications.settings.pageTitle": "Notification Delivery",
+  "notifications.settings.pageDescription": "Configure delivery strategies for in-app notifications.",
+  "notifications.settings.loadError": "Failed to load notification settings",
+  "notifications.settings.saveError": "Failed to save notification settings",
+  "notifications.settings.saveSuccess": "Notification settings saved",
+  "notifications.settings.loading": "Loading notification settings...",
+  "notifications.settings.saving": "Saving...",
+  "notifications.settings.save": "Save settings",
+  "notifications.settings.core.title": "Core delivery",
+  "notifications.settings.core.description": "Control the default notification center and panel link used by external channels.",
+  "notifications.settings.core.appUrl": "Application URL",
+  "notifications.settings.core.appUrlHint": "Used to build absolute links in email notifications.",
+  "notifications.settings.core.panelPath": "Notification panel path",
+  "notifications.settings.core.panelPathHint": "Relative path for the read-only notification panel.",
+  "notifications.settings.core.databaseLabel": "In-app notifications",
+  "notifications.settings.core.databaseHint": "Store notifications in the database for the panel and bell.",
+  "notifications.settings.email.title": "Email strategy",
+  "notifications.settings.email.description": "Send notification copies via Resend using React templates.",
+  "notifications.settings.email.enabledLabel": "Enable email delivery",
+  "notifications.settings.email.enabledHint": "Email actions are read-only and link back to the notification center.",
+  "notifications.settings.email.from": "From address",
+  "notifications.settings.email.replyTo": "Reply-to",
+  "notifications.settings.email.subjectPrefix": "Subject prefix"
+}

package/src/modules/notifications/i18n/es.json

@@ -0,0 +1,50 @@
+{
+  "notifications.nav.title": "Notificaciones",
+  "notifications.title": "Notificaciones",
+  "notifications.empty": "Sin notificaciones",
+  "notifications.markAllRead": "Marcar todo como leído",
+  "notifications.actionTaken": "Acción realizada: {action}",
+  "notifications.filters.all": "Todas",
+  "notifications.filters.unread": "No leídas",
+  "notifications.filters.actionRequired": "Acción requerida",
+  "notifications.actions.dismiss": "Descartar",
+  "notifications.actions.undo": "Deshacer",
+  "notifications.actions.markRead": "Marcar como leída",
+  "notifications.toast.new": "Nueva notificación",
+  "notifications.toast.dismissed": "Notificación descartada",
+  "notifications.toast.actionSuccess": "Acción completada correctamente",
+  "notifications.toast.actionError": "No se pudo ejecutar la acción",
+  "notifications.error.load": "No se pudieron cargar las notificaciones",
+  "notifications.error.action": "No se pudo ejecutar la acción",
+  "notifications.badge.unread": "{count} notificaciones no leídas",
+  "notifications.delivery.email.preview": "Nueva notificación",
+  "notifications.delivery.email.heading": "Tienes una nueva notificación",
+  "notifications.delivery.email.bodyIntro": "Revisa los detalles de la notificación y realiza las acciones necesarias.",
+  "notifications.delivery.email.actionNotice": "Las acciones están disponibles en Open Mercato y son de solo lectura en este correo.",
+  "notifications.delivery.email.openCta": "Abrir centro de notificaciones",
+  "notifications.delivery.email.footer": "Notificaciones de Open Mercato",
+  "notifications.delivery.settings.invalid": "Configuración de entrega no válida",
+  "notifications.settings.pageTitle": "Entrega de notificaciones",
+  "notifications.settings.pageDescription": "Configura las estrategias de entrega para las notificaciones en la app.",
+  "notifications.settings.loadError": "No se pudieron cargar los ajustes de notificaciones",
+  "notifications.settings.saveError": "No se pudieron guardar los ajustes de notificaciones",
+  "notifications.settings.saveSuccess": "Ajustes de notificaciones guardados",
+  "notifications.settings.loading": "Cargando ajustes de notificaciones...",
+  "notifications.settings.saving": "Guardando...",
+  "notifications.settings.save": "Guardar ajustes",
+  "notifications.settings.core.title": "Entrega principal",
+  "notifications.settings.core.description": "Controla el centro de notificaciones y el enlace del panel para canales externos.",
+  "notifications.settings.core.appUrl": "URL de la aplicación",
+  "notifications.settings.core.appUrlHint": "Se usa para construir enlaces absolutos en notificaciones por email.",
+  "notifications.settings.core.panelPath": "Ruta del panel de notificaciones",
+  "notifications.settings.core.panelPathHint": "Ruta relativa para el panel de notificaciones de solo lectura.",
+  "notifications.settings.core.databaseLabel": "Notificaciones en la app",
+  "notifications.settings.core.databaseHint": "Guarda las notificaciones en la base de datos para el panel y la campana.",
+  "notifications.settings.email.title": "Estrategia de email",
+  "notifications.settings.email.description": "Envía copias de notificaciones vía Resend con plantillas React.",
+  "notifications.settings.email.enabledLabel": "Habilitar entrega por email",
+  "notifications.settings.email.enabledHint": "Las acciones del email son de solo lectura y enlazan al centro de notificaciones.",
+  "notifications.settings.email.from": "Dirección del remitente",
+  "notifications.settings.email.replyTo": "Responder a",
+  "notifications.settings.email.subjectPrefix": "Prefijo de asunto"
+}

package/src/modules/notifications/i18n/pl.json

@@ -0,0 +1,50 @@
+{
+  "notifications.nav.title": "Powiadomienia",
+  "notifications.title": "Powiadomienia",
+  "notifications.empty": "Brak powiadomień",
+  "notifications.markAllRead": "Oznacz wszystkie jako przeczytane",
+  "notifications.actionTaken": "Wykonana akcja: {action}",
+  "notifications.filters.all": "Wszystkie",
+  "notifications.filters.unread": "Nieprzeczytane",
+  "notifications.filters.actionRequired": "Wymagana akcja",
+  "notifications.actions.dismiss": "Odrzuć",
+  "notifications.actions.undo": "Cofnij",
+  "notifications.actions.markRead": "Oznacz jako przeczytane",
+  "notifications.toast.new": "Nowe powiadomienie",
+  "notifications.toast.dismissed": "Powiadomienie odrzucone",
+  "notifications.toast.actionSuccess": "Akcja wykonana pomyślnie",
+  "notifications.toast.actionError": "Nie udało się wykonać akcji",
+  "notifications.error.load": "Nie udało się załadować powiadomień",
+  "notifications.error.action": "Nie udało się wykonać akcji",
+  "notifications.badge.unread": "{count} nieprzeczytanych powiadomień",
+  "notifications.delivery.email.preview": "Nowe powiadomienie",
+  "notifications.delivery.email.heading": "Masz nowe powiadomienie",
+  "notifications.delivery.email.bodyIntro": "Sprawdź szczegóły powiadomienia i wykonaj wymagane działania.",
+  "notifications.delivery.email.actionNotice": "Akcje są dostępne w Open Mercato i w tym e-mailu są tylko do odczytu.",
+  "notifications.delivery.email.openCta": "Otwórz centrum powiadomień",
+  "notifications.delivery.email.footer": "Powiadomienia Open Mercato",
+  "notifications.delivery.settings.invalid": "Nieprawidłowe ustawienia dostarczania",
+  "notifications.settings.pageTitle": "Dostarczanie powiadomień",
+  "notifications.settings.pageDescription": "Skonfiguruj strategie dostarczania powiadomień w aplikacji.",
+  "notifications.settings.loadError": "Nie udało się załadować ustawień powiadomień",
+  "notifications.settings.saveError": "Nie udało się zapisać ustawień powiadomień",
+  "notifications.settings.saveSuccess": "Ustawienia powiadomień zapisane",
+  "notifications.settings.loading": "Ładowanie ustawień powiadomień...",
+  "notifications.settings.saving": "Zapisywanie...",
+  "notifications.settings.save": "Zapisz ustawienia",
+  "notifications.settings.core.title": "Podstawowe dostarczanie",
+  "notifications.settings.core.description": "Kontroluj centrum powiadomień i link panelu dla kanałów zewnętrznych.",
+  "notifications.settings.core.appUrl": "URL aplikacji",
+  "notifications.settings.core.appUrlHint": "Służy do budowania bezwzględnych linków w powiadomieniach e-mail.",
+  "notifications.settings.core.panelPath": "Ścieżka panelu powiadomień",
+  "notifications.settings.core.panelPathHint": "Względna ścieżka do panelu powiadomień tylko do odczytu.",
+  "notifications.settings.core.databaseLabel": "Powiadomienia w aplikacji",
+  "notifications.settings.core.databaseHint": "Zapisuje powiadomienia w bazie danych dla panelu i dzwonka.",
+  "notifications.settings.email.title": "Strategia e-mail",
+  "notifications.settings.email.description": "Wysyłaj kopie powiadomień przez Resend z szablonami React.",
+  "notifications.settings.email.enabledLabel": "Włącz dostarczanie e-mail",
+  "notifications.settings.email.enabledHint": "Akcje w e-mailu są tylko do odczytu i prowadzą do centrum powiadomień.",
+  "notifications.settings.email.from": "Adres nadawcy",
+  "notifications.settings.email.replyTo": "Odpowiedz do",
+  "notifications.settings.email.subjectPrefix": "Prefiks tematu"
+}

package/src/modules/notifications/index.ts

@@ -0,0 +1,12 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+
+export const metadata: ModuleInfo = {
+  name: 'notifications',
+  title: 'Notifications',
+  version: '0.1.0',
+  description: 'In-app notifications with module-extensible types and actions.',
+  author: 'Open Mercato Team',
+  license: 'Proprietary',
+}
+
+export { features } from './acl'

package/src/modules/notifications/lib/deliveryConfig.ts

@@ -0,0 +1,145 @@
+import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import { notificationDeliveryConfigSchema, type NotificationDeliveryConfigInput } from '../data/validators'
+
+export const NOTIFICATIONS_DELIVERY_CONFIG_KEY = 'delivery_strategies'
+
+export type NotificationDeliveryStrategyState = {
+  enabled: boolean
+}
+
+export type NotificationEmailDeliveryConfig = NotificationDeliveryStrategyState & {
+  from?: string
+  replyTo?: string
+  subjectPrefix?: string
+}
+
+export type NotificationDeliveryConfig = {
+  appUrl?: string
+  panelPath: string
+  strategies: {
+    database: NotificationDeliveryStrategyState
+    email: NotificationEmailDeliveryConfig
+  }
+}
+
+const envString = (value: string | undefined | null) => {
+  if (!value) return undefined
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : undefined
+}
+
+const resolveEnvDefaults = () => {
+  const appUrl = envString(
+    process.env.NOTIFICATIONS_APP_URL ||
+    process.env.APPLICATION_URL ||
+    process.env.NEXT_PUBLIC_APP_URL ||
+    process.env.APP_URL
+  )
+  const panelPath = envString(process.env.NOTIFICATIONS_PANEL_PATH)
+  const emailEnabled = parseBooleanWithDefault(process.env.NOTIFICATIONS_EMAIL_ENABLED, true)
+  const emailFrom = envString(process.env.NOTIFICATIONS_EMAIL_FROM || process.env.EMAIL_FROM)
+  const emailReplyTo = envString(process.env.NOTIFICATIONS_EMAIL_REPLY_TO || process.env.ADMIN_EMAIL)
+  const emailSubjectPrefix = envString(process.env.NOTIFICATIONS_EMAIL_SUBJECT_PREFIX)
+
+  return {
+    appUrl,
+    panelPath,
+    emailEnabled,
+    emailFrom,
+    emailReplyTo,
+    emailSubjectPrefix,
+  }
+}
+
+export const DEFAULT_NOTIFICATION_DELIVERY_CONFIG: NotificationDeliveryConfig = (() => {
+  const env = resolveEnvDefaults()
+  return {
+    appUrl: env.appUrl,
+    panelPath: env.panelPath ?? '/backend/notifications',
+    strategies: {
+      database: { enabled: true },
+      email: {
+        enabled: env.emailEnabled,
+        from: env.emailFrom,
+        replyTo: env.emailReplyTo,
+        subjectPrefix: env.emailSubjectPrefix,
+      },
+    },
+  }
+})()
+
+const normalizeDeliveryConfig = (input?: unknown | null): NotificationDeliveryConfig => {
+  const parsed = notificationDeliveryConfigSchema.safeParse(input ?? {})
+  if (!parsed.success) {
+    return { ...DEFAULT_NOTIFICATION_DELIVERY_CONFIG }
+  }
+
+  const value = parsed.data ?? {}
+  const strategies = value.strategies ?? {}
+
+  return {
+    appUrl: value.appUrl,
+    panelPath: value.panelPath ?? DEFAULT_NOTIFICATION_DELIVERY_CONFIG.panelPath,
+    strategies: {
+      database: {
+        enabled: DEFAULT_NOTIFICATION_DELIVERY_CONFIG.strategies.database.enabled,
+      },
+      email: {
+        enabled: strategies.email?.enabled ?? DEFAULT_NOTIFICATION_DELIVERY_CONFIG.strategies.email.enabled,
+        from: strategies.email?.from,
+        replyTo: strategies.email?.replyTo,
+        subjectPrefix: strategies.email?.subjectPrefix,
+      },
+    },
+  }
+}
+
+type Resolver = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export async function resolveNotificationDeliveryConfig(
+  resolver: Resolver,
+  options?: { defaultValue?: NotificationDeliveryConfig }
+): Promise<NotificationDeliveryConfig> {
+  const fallback = options?.defaultValue ?? DEFAULT_NOTIFICATION_DELIVERY_CONFIG
+  let service: ModuleConfigService
+  try {
+    service = resolver.resolve<ModuleConfigService>('moduleConfigService')
+  } catch {
+    return { ...fallback }
+  }
+  try {
+    const value = await service.getValue('notifications', NOTIFICATIONS_DELIVERY_CONFIG_KEY, { defaultValue: fallback })
+    return normalizeDeliveryConfig(value)
+  } catch {
+    return { ...fallback }
+  }
+}
+
+export async function saveNotificationDeliveryConfig(
+  resolver: Resolver,
+  config: NotificationDeliveryConfigInput
+): Promise<void> {
+  let service: ModuleConfigService
+  try {
+    service = resolver.resolve<ModuleConfigService>('moduleConfigService')
+  } catch {
+    throw new Error('Configuration service unavailable')
+  }
+
+  const normalized = normalizeDeliveryConfig(config)
+  await service.setValue('notifications', NOTIFICATIONS_DELIVERY_CONFIG_KEY, normalized)
+}
+
+export function resolveNotificationPanelUrl(config: NotificationDeliveryConfig): string | null {
+  const base = config.appUrl
+    || process.env.APPLICATION_URL
+    || process.env.NEXT_PUBLIC_APP_URL
+    || process.env.APP_URL
+  if (!base || !base.trim()) {
+    return config.panelPath
+  }
+  return `${base.replace(/\/$/, '')}${config.panelPath}`
+}

package/src/modules/notifications/lib/events.ts

@@ -0,0 +1,48 @@
+export const NOTIFICATION_EVENTS = {
+  CREATED: 'notifications.created',
+  READ: 'notifications.read',
+  ACTIONED: 'notifications.actioned',
+  DISMISSED: 'notifications.dismissed',
+  RESTORED: 'notifications.restored',
+  EXPIRED: 'notifications.expired',
+} as const
+
+export type NotificationCreatedPayload = {
+  notificationId: string
+  recipientUserId: string
+  type: string
+  title: string
+  tenantId: string
+  organizationId?: string | null
+}
+
+export type NotificationReadPayload = {
+  notificationId: string
+  userId: string
+  tenantId: string
+}
+
+export type NotificationActionedPayload = {
+  notificationId: string
+  actionId: string
+  userId: string
+  tenantId: string
+}
+
+export type NotificationDismissedPayload = {
+  notificationId: string
+  userId: string
+  tenantId: string
+}
+
+export type NotificationRestoredPayload = {
+  notificationId: string
+  userId: string
+  tenantId: string
+  status: 'read' | 'unread'
+}
+
+export type NotificationExpiredPayload = {
+  notificationIds: string[]
+  tenantId: string
+}

package/src/modules/notifications/lib/notificationBuilder.ts

@@ -0,0 +1,121 @@
+import type { NotificationTypeDefinition, NotificationTypeAction } from '@open-mercato/shared/modules/notifications/types'
+import type { CreateNotificationInput, CreateBatchNotificationInput, CreateRoleNotificationInput, CreateFeatureNotificationInput } from '../data/validators'
+
+/**
+ * Transform type definition actions to API input actions.
+ * Type definitions use labelKey (i18n-first), while API input uses label with optional labelKey.
+ */
+function mapActions(actions: NotificationTypeAction[] | undefined) {
+  if (!actions || actions.length === 0) return undefined
+  return actions.map((action) => ({
+    id: action.id,
+    label: action.labelKey,
+    labelKey: action.labelKey,
+    variant: action.variant,
+    icon: action.icon,
+    commandId: action.commandId,
+    href: action.href,
+    confirmRequired: action.confirmRequired,
+    confirmMessage: action.confirmMessageKey,
+  }))
+}
+
+/**
+ * Common options for building notifications from type definitions
+ */
+interface CommonBuildOptions {
+  titleVariables?: Record<string, string>
+  bodyVariables?: Record<string, string>
+  sourceEntityType?: string
+  sourceEntityId?: string
+  linkHref?: string
+  groupKey?: string
+  expiresAt?: string
+}
+
+/**
+ * Build base notification fields from a type definition.
+ * Shared logic used by all notification builder functions.
+ */
+function buildBaseNotificationFields(
+  typeDef: NotificationTypeDefinition,
+  options: CommonBuildOptions
+) {
+  return {
+    type: typeDef.type,
+    titleKey: typeDef.titleKey,
+    bodyKey: typeDef.bodyKey,
+    titleVariables: options.titleVariables,
+    bodyVariables: options.bodyVariables,
+    title: typeDef.titleKey,
+    body: typeDef.bodyKey,
+    icon: typeDef.icon,
+    severity: typeDef.severity,
+    actions: mapActions(typeDef.actions),
+    primaryActionId: typeDef.primaryActionId,
+    sourceModule: typeDef.module,
+    sourceEntityType: options.sourceEntityType,
+    sourceEntityId: options.sourceEntityId,
+    linkHref: options.linkHref ?? typeDef.linkHref,
+    groupKey: options.groupKey,
+    expiresAt: options.expiresAt ?? (
+      typeDef.expiresAfterHours
+        ? new Date(Date.now() + typeDef.expiresAfterHours * 60 * 60 * 1000).toISOString()
+        : undefined
+    ),
+  }
+}
+
+/**
+ * Build a notification input from a type definition with i18n support.
+ * This is the recommended way to create notifications - use type definitions from notifications.ts
+ * to ensure i18n-first approach.
+ */
+export function buildNotificationFromType(
+  typeDef: NotificationTypeDefinition,
+  options: CommonBuildOptions & { recipientUserId: string }
+): CreateNotificationInput {
+  return {
+    recipientUserId: options.recipientUserId,
+    ...buildBaseNotificationFields(typeDef, options),
+  }
+}
+
+/**
+ * Build a batch notification input from a type definition
+ */
+export function buildBatchNotificationFromType(
+  typeDef: NotificationTypeDefinition,
+  options: CommonBuildOptions & { recipientUserIds: string[] }
+): CreateBatchNotificationInput {
+  return {
+    recipientUserIds: options.recipientUserIds,
+    ...buildBaseNotificationFields(typeDef, options),
+  }
+}
+
+/**
+ * Build a role notification input from a type definition
+ */
+export function buildRoleNotificationFromType(
+  typeDef: NotificationTypeDefinition,
+  options: CommonBuildOptions & { roleId: string }
+): CreateRoleNotificationInput {
+  return {
+    roleId: options.roleId,
+    ...buildBaseNotificationFields(typeDef, options),
+  }
+}
+
+/**
+ * Build a feature-based notification input from a type definition
+ */
+export function buildFeatureNotificationFromType(
+  typeDef: NotificationTypeDefinition,
+  options: CommonBuildOptions & { requiredFeature: string }
+): CreateFeatureNotificationInput {
+  return {
+    requiredFeature: options.requiredFeature,
+    ...buildBaseNotificationFields(typeDef, options),
+  }
+}

package/src/modules/notifications/lib/notificationFactory.ts

@@ -0,0 +1,76 @@
+import type { EntityManager } from '@mikro-orm/core'
+import { Notification } from '../data/entities'
+import type { CreateNotificationInput } from '../data/validators'
+import { NOTIFICATION_EVENTS } from './events'
+import { assertSafeNotificationHref, sanitizeNotificationActions } from './safeHref'
+
+export type NotificationContentInput = Omit<CreateNotificationInput, 'recipientUserId'>
+
+export type NotificationTenantContext = {
+  tenantId: string
+  organizationId?: string | null
+}
+
+export function buildNotificationEntity(
+  em: EntityManager,
+  input: NotificationContentInput,
+  recipientUserId: string,
+  ctx: NotificationTenantContext
+): Notification {
+  const actions = sanitizeNotificationActions(input.actions)
+  const linkHref = assertSafeNotificationHref(input.linkHref)
+
+  return em.create(Notification, {
+    recipientUserId,
+    type: input.type,
+    // i18n-first: store keys and variables for translation at display time
+    titleKey: input.titleKey,
+    bodyKey: input.bodyKey,
+    titleVariables: input.titleVariables,
+    bodyVariables: input.bodyVariables,
+    // Fallback text (required for backward compatibility)
+    title: input.title || input.titleKey || '',
+    body: input.body,
+    icon: input.icon,
+    severity: input.severity ?? 'info',
+    actionData: actions
+      ? {
+          actions,
+          primaryActionId: input.primaryActionId,
+        }
+      : null,
+    sourceModule: input.sourceModule,
+    sourceEntityType: input.sourceEntityType,
+    sourceEntityId: input.sourceEntityId,
+    linkHref,
+    groupKey: input.groupKey,
+    expiresAt: input.expiresAt ? new Date(input.expiresAt) : null,
+    tenantId: ctx.tenantId,
+    organizationId: ctx.organizationId,
+  })
+}
+
+export async function emitNotificationCreated(
+  eventBus: { emit: (event: string, payload: unknown) => Promise<void> },
+  notification: Notification,
+  ctx: NotificationTenantContext
+): Promise<void> {
+  await eventBus.emit(NOTIFICATION_EVENTS.CREATED, {
+    notificationId: notification.id,
+    recipientUserId: notification.recipientUserId,
+    type: notification.type,
+    title: notification.title,
+    tenantId: ctx.tenantId,
+    organizationId: ctx.organizationId,
+  })
+}
+
+export async function emitNotificationCreatedBatch(
+  eventBus: { emit: (event: string, payload: unknown) => Promise<void> },
+  notifications: Notification[],
+  ctx: NotificationTenantContext
+): Promise<void> {
+  for (const notification of notifications) {
+    await emitNotificationCreated(eventBus, notification, ctx)
+  }
+}

package/src/modules/notifications/lib/notificationMapper.ts

@@ -0,0 +1,33 @@
+import type { NotificationDto } from '@open-mercato/shared/modules/notifications/types'
+import { Notification } from '../data/entities'
+
+export function toNotificationDto(notification: Notification): NotificationDto {
+  return {
+    id: notification.id,
+    type: notification.type,
+    title: notification.title,
+    body: notification.body,
+    titleKey: notification.titleKey,
+    bodyKey: notification.bodyKey,
+    titleVariables: notification.titleVariables,
+    bodyVariables: notification.bodyVariables,
+    icon: notification.icon,
+    severity: notification.severity,
+    status: notification.status,
+    actions: notification.actionData?.actions?.map((action) => ({
+      id: action.id,
+      label: action.label,
+      labelKey: action.labelKey,
+      variant: action.variant,
+      icon: action.icon,
+    })) ?? [],
+    primaryActionId: notification.actionData?.primaryActionId,
+    sourceModule: notification.sourceModule,
+    sourceEntityType: notification.sourceEntityType,
+    sourceEntityId: notification.sourceEntityId,
+    linkHref: notification.linkHref,
+    createdAt: notification.createdAt.toISOString(),
+    readAt: notification.readAt?.toISOString() ?? null,
+    actionTaken: notification.actionTaken,
+  }
+}

package/src/modules/notifications/lib/notificationRecipients.ts

@@ -0,0 +1,83 @@
+import type { Knex } from 'knex'
+import { hasFeature } from '@open-mercato/shared/security/features'
+
+interface AclRow {
+  user_id: string
+  features_json: unknown
+  is_super_admin: boolean
+}
+
+function normalizeFeatures(features: unknown): string[] | undefined {
+  if (!Array.isArray(features)) return undefined
+  const normalized = features.filter((feature): feature is string => typeof feature === 'string')
+  return normalized.length ? normalized : undefined
+}
+
+/**
+ * Extract user IDs from ACL rows that have the required feature or are super admins.
+ */
+function collectUsersWithFeature(
+  userIdsSet: Set<string>,
+  rows: AclRow[],
+  requiredFeature: string
+): void {
+  for (const row of rows) {
+    if (row.is_super_admin) {
+      userIdsSet.add(row.user_id)
+      continue
+    }
+
+    const features = normalizeFeatures(row.features_json)
+    if (features && hasFeature(features, requiredFeature)) {
+      userIdsSet.add(row.user_id)
+    }
+  }
+}
+
+export async function getRecipientUserIdsForRole(
+  knex: Knex,
+  tenantId: string,
+  roleId: string
+): Promise<string[]> {
+  const userRoles = await knex('user_roles')
+    .join('users', 'user_roles.user_id', 'users.id')
+    .where('user_roles.role_id', roleId)
+    .whereNull('user_roles.deleted_at')
+    .whereNull('users.deleted_at')
+    .where('users.tenant_id', tenantId)
+    .select('users.id as user_id')
+
+  return userRoles.map((row: { user_id: string }) => row.user_id)
+}
+
+export async function getRecipientUserIdsForFeature(
+  knex: Knex,
+  tenantId: string,
+  requiredFeature: string
+): Promise<string[]> {
+  const userIdsSet = new Set<string>()
+
+  const userAcls = await knex('user_acls')
+    .join('users', 'user_acls.user_id', 'users.id')
+    .where('user_acls.tenant_id', tenantId)
+    .whereNull('user_acls.deleted_at')
+    .whereNull('users.deleted_at')
+    .where('users.tenant_id', tenantId)
+    .select('users.id as user_id', 'user_acls.features_json', 'user_acls.is_super_admin')
+
+  collectUsersWithFeature(userIdsSet, userAcls, requiredFeature)
+
+  const roleAcls = await knex('role_acls')
+    .join('user_roles', 'role_acls.role_id', 'user_roles.role_id')
+    .join('users', 'user_roles.user_id', 'users.id')
+    .where('role_acls.tenant_id', tenantId)
+    .whereNull('role_acls.deleted_at')
+    .whereNull('user_roles.deleted_at')
+    .whereNull('users.deleted_at')
+    .where('users.tenant_id', tenantId)
+    .select('users.id as user_id', 'role_acls.features_json', 'role_acls.is_super_admin')
+
+  collectUsersWithFeature(userIdsSet, roleAcls, requiredFeature)
+
+  return Array.from(userIdsSet)
+}