@open-mercato/core 0.6.8-develop.6984.1.f0cf23f0f6 → 0.6.8-develop.6985.1.fb93574faa

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

@@ -23,6 +23,15 @@ import {
 } from './notificationRecipients'
 import { assertSafeNotificationHref, sanitizeNotificationActions } from './safeHref'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getNotificationType } from './notification-type-registry'
+import { getNotificationTypeOverrides, type NotificationTypeOverrides } from './typeOverrides'
+import { getNotificationDeliveryStrategies } from './deliveryStrategies'
+import { resolveEffectiveChannels } from './shouldDeliver'
+import {
+  createNotificationPreferenceService,
+  type NotificationPreferenceService,
+} from './notificationPreferenceService'
+import { inAppVisibleFilter, inAppVisibleSql, isInAppVisible } from './notificationVisibility'
 
 const logger = createLogger('notifications').child({ component: 'service' })
 
@@ -83,6 +92,7 @@ function applyNotificationContent(
   input: NotificationContentInput,
   recipientUserId: string,
   ctx: NotificationTenantContext,
+  channels: string[] | null,
 ) {
   const actions = sanitizeNotificationActions(input.actions)
   const linkHref = assertSafeNotificationHref(input.linkHref)
@@ -108,6 +118,7 @@ function applyNotificationContent(
   notification.sourceEntityId = input.sourceEntityId
   notification.linkHref = linkHref
   notification.groupKey = input.groupKey
+  notification.channels = channels
   notification.expiresAt = input.expiresAt ? new Date(input.expiresAt) : null
   notification.tenantId = ctx.tenantId
   notification.organizationId = normalizeOrgScope(ctx.organizationId)
@@ -149,16 +160,21 @@ async function emitNotificationSseEvents(
   eventBus: { emit: (event: string, payload: unknown) => Promise<void> },
   notifications: Notification[],
   ctx: NotificationServiceContext,
-  recipientUserIds: string[],
 ): Promise<void> {
+  // Live bell updates only for notifications actually delivered to the in-app channel; the others
+  // exist as records but must not bump anyone's badge/inbox.
+  const visible = notifications.filter((notification) => isInAppVisible(notification.channels))
+  if (visible.length === 0) return
+
+  const visibleRecipientUserIds = Array.from(new Set(visible.map((n) => n.recipientUserId)))
   await eventBus.emit(NOTIFICATION_SSE_EVENTS.BATCH_CREATED, {
     tenantId: ctx.tenantId,
     organizationId: normalizeOrgScope(ctx.organizationId),
-    recipientUserIds,
-    count: notifications.length,
+    recipientUserIds: visibleRecipientUserIds,
+    count: visible.length,
   })
 
-  for (const notification of notifications) {
+  for (const notification of visible) {
     await eventBus.emit(NOTIFICATION_SSE_EVENTS.CREATED, {
       tenantId: notification.tenantId,
       organizationId: notification.organizationId ?? null,
@@ -173,6 +189,7 @@ async function createOrRefreshNotification(
   input: NotificationContentInput,
   recipientUserId: string,
   ctx: NotificationTenantContext,
+  channels: string[] | null,
 ): Promise<Notification> {
   if (input.groupKey && input.groupKey.trim().length > 0) {
     const orgScope = normalizeOrgScope(ctx.organizationId) ?? 'global'
@@ -196,12 +213,12 @@ async function createOrRefreshNotification(
     })
 
     if (existing) {
-      applyNotificationContent(existing, input, recipientUserId, ctx)
+      applyNotificationContent(existing, input, recipientUserId, ctx, channels)
       return existing
     }
   }
 
-  return buildNotificationEntity(em, input, recipientUserId, ctx)
+  return buildNotificationEntity(em, input, recipientUserId, ctx, channels)
 }
 
 export interface NotificationServiceContext {
@@ -258,25 +275,94 @@ export interface NotificationServiceDeps {
 export function createNotificationService(deps: NotificationServiceDeps): NotificationService {
   const { em: rootEm, eventBus, commandBus, container } = deps
 
+  /**
+   * Resolves the authoritative delivery-channel set for one recipient at create time — the single
+   * gate that folds per-send target, per-type eligibility, registered strategies, and the
+   * recipient's per-channel preferences (`nonOptOut` bypasses opt-out). Stored on the row and
+   * replayed by the dispatcher; `in_app` membership also drives bell/inbox visibility.
+   *
+   * Returns `null` (⇒ "all channels", legacy behavior) when no delivery strategies are registered
+   * (e.g. a minimal bootstrap/test), so notifications never become silently undeliverable/invisible
+   * in an environment that simply hasn't wired the seam.
+   */
+  const resolveChannelsFor = async (
+    content: NotificationContentInput,
+    recipientUserId: string,
+    scopeCtx: NotificationServiceContext,
+    preferences: NotificationPreferenceService = createNotificationPreferenceService({ em: rootEm.fork() }),
+    typeOverrides?: NotificationTypeOverrides | null,
+  ): Promise<string[] | null> => {
+    const registeredChannels = getNotificationDeliveryStrategies().map((strategy) => strategy.id)
+    if (registeredChannels.length === 0) return null
+    // Treat an empty target as "no restriction" (all channels) rather than "no deliverable channel":
+    // a programmatic caller that computed an empty array should not silently black-hole the
+    // notification. The HTTP layer rejects an empty `channels` outright (see validators.ts).
+    const targetChannels = content.channels && content.channels.length > 0 ? content.channels : null
+    const overrides = typeOverrides === undefined
+      ? (await getNotificationTypeOverrides(rootEm.fork(), scopeCtx.tenantId, [content.type])).get(content.type) ?? null
+      : typeOverrides
+    return resolveEffectiveChannels({
+      typeId: content.type,
+      type: getNotificationType(content.type),
+      scope: { tenantId: scopeCtx.tenantId, userId: recipientUserId },
+      targetChannels,
+      registeredChannels,
+      preferences,
+      channelsOverride: overrides?.channels ?? null,
+      nonOptOutOverride: overrides?.nonOptOut ?? null,
+    })
+  }
+
+  /**
+   * Broadcast counterpart of {@link resolveChannelsFor}: resolves the channel set for every recipient
+   * up front, BEFORE the write transaction opens, reusing a single forked EM / preference service
+   * across the whole set. This keeps the preference reads out of the write transaction (matching
+   * `create`, which resolves before its transaction) and avoids one EM fork per recipient on large
+   * role/feature broadcasts.
+   */
+  const resolveChannelsForRecipients = async (
+    content: NotificationContentInput,
+    recipientUserIds: string[],
+    scopeCtx: NotificationServiceContext,
+  ): Promise<Array<{ recipientUserId: string; channels: string[] | null }>> => {
+    const preferences = createNotificationPreferenceService({ em: rootEm.fork() })
+    // Stored overrides are per-type (not per-recipient) — read once for the whole broadcast.
+    const typeOverrides =
+      (await getNotificationTypeOverrides(rootEm.fork(), scopeCtx.tenantId, [content.type])).get(content.type) ?? null
+    const resolved: Array<{ recipientUserId: string; channels: string[] | null }> = []
+    for (const recipientUserId of recipientUserIds) {
+      resolved.push({
+        recipientUserId,
+        channels: await resolveChannelsFor(content, recipientUserId, scopeCtx, preferences, typeOverrides),
+      })
+    }
+    return resolved
+  }
+
   return {
     async create(input, ctx) {
       const { recipientUserId, ...content } = input
+      const channels = await resolveChannelsFor(content, recipientUserId, ctx)
       const writeEm = rootEm.fork()
       const notification = await writeEm.transactional(async (tx) => {
         await assertNotificationRecipientsInScope(tx, [recipientUserId], ctx)
-        const entity = await createOrRefreshNotification(tx, content, recipientUserId, ctx)
+        const entity = await createOrRefreshNotification(tx, content, recipientUserId, ctx, channels)
         await tx.flush()
         return entity
       })
 
       await invalidateNotificationCache(container, ctx, 'created')
+      // Always emit the domain event (drives the deliver subscriber → push/email/…). Only bump the
+      // live in-app bell when this notification is actually visible in-app.
       await emitNotificationCreated(eventBus, notification, ctx)
-      await eventBus.emit(NOTIFICATION_SSE_EVENTS.CREATED, {
-        tenantId: notification.tenantId,
-        organizationId: notification.organizationId ?? null,
-        recipientUserId: notification.recipientUserId,
-        notification: toNotificationDto(notification),
-      })
+      if (isInAppVisible(notification.channels)) {
+        await eventBus.emit(NOTIFICATION_SSE_EVENTS.CREATED, {
+          tenantId: notification.tenantId,
+          organizationId: notification.organizationId ?? null,
+          recipientUserId: notification.recipientUserId,
+          notification: toNotificationDto(notification),
+        })
+      }
 
       return notification
     },
@@ -285,12 +371,13 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
       const recipientUserIds = Array.from(new Set(input.recipientUserIds))
       const { recipientUserIds: _recipientUserIds, ...content } = input
       const notifications: Notification[] = []
+      const resolved = await resolveChannelsForRecipients(content, recipientUserIds, ctx)
       const writeEm = rootEm.fork()
 
       await writeEm.transactional(async (tx) => {
         await assertNotificationRecipientsInScope(tx, recipientUserIds, ctx)
-        for (const recipientUserId of recipientUserIds) {
-          const notification = await createOrRefreshNotification(tx, content, recipientUserId, ctx)
+        for (const { recipientUserId, channels } of resolved) {
+          const notification = await createOrRefreshNotification(tx, content, recipientUserId, ctx, channels)
           notifications.push(notification)
         }
         await tx.flush()
@@ -298,7 +385,7 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
 
       await invalidateNotificationCache(container, ctx, 'created')
       await emitNotificationCreatedBatch(eventBus, notifications, ctx)
-      await emitNotificationSseEvents(eventBus, notifications, ctx, recipientUserIds)
+      await emitNotificationSseEvents(eventBus, notifications, ctx)
 
       return notifications
     },
@@ -315,11 +402,12 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
       const { roleId: _roleId, ...content } = input
       const notifications: Notification[] = []
       const uniqueRecipientUserIds = Array.from(new Set(recipientUserIds))
+      const resolved = await resolveChannelsForRecipients(content, uniqueRecipientUserIds, ctx)
       const writeEm = rootEm.fork()
 
       await writeEm.transactional(async (tx) => {
-        for (const recipientUserId of uniqueRecipientUserIds) {
-          const notification = await createOrRefreshNotification(tx, content, recipientUserId, ctx)
+        for (const { recipientUserId, channels } of resolved) {
+          const notification = await createOrRefreshNotification(tx, content, recipientUserId, ctx, channels)
           notifications.push(notification)
         }
         await tx.flush()
@@ -327,7 +415,7 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
 
       await invalidateNotificationCache(container, ctx, 'created')
       await emitNotificationCreatedBatch(eventBus, notifications, ctx)
-      await emitNotificationSseEvents(eventBus, notifications, ctx, uniqueRecipientUserIds)
+      await emitNotificationSseEvents(eventBus, notifications, ctx)
 
       return notifications
     },
@@ -422,11 +510,12 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
       } = input
       const notifications: Notification[] = []
       const uniqueRecipientUserIds = Array.from(new Set(authorizedRecipientUserIds))
+      const resolved = await resolveChannelsForRecipients(content, uniqueRecipientUserIds, ctx)
       const writeEm = rootEm.fork()
 
       await writeEm.transactional(async (tx) => {
-        for (const recipientUserId of uniqueRecipientUserIds) {
-          const notification = await createOrRefreshNotification(tx, content, recipientUserId, ctx)
+        for (const { recipientUserId, channels } of resolved) {
+          const notification = await createOrRefreshNotification(tx, content, recipientUserId, ctx, channels)
           notifications.push(notification)
         }
         await tx.flush()
@@ -434,7 +523,7 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
 
       await invalidateNotificationCache(container, ctx, 'created')
       await emitNotificationCreatedBatch(eventBus, notifications, ctx)
-      await emitNotificationSseEvents(eventBus, notifications, ctx, uniqueRecipientUserIds)
+      await emitNotificationSseEvents(eventBus, notifications, ctx)
 
       return notifications
     },
@@ -467,6 +556,12 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
           .where('recipient_user_id' as any, '=', ctx.userId as any)
           .where('tenant_id' as any, '=', ctx.tenantId)
           .where('status' as any, '=', 'unread')
+          // Only in-app-visible rows count toward the badge (see getUnreadCount),
+          // so "mark all as read" must scope to the SAME set — otherwise it flips
+          // push/email-only rows the user never saw and SSE-broadcasts a read for
+          // notifications that were never in the bell, inflating the returned
+          // count past what the badge showed.
+          .where(inAppVisibleSql() as any)
         if (ctx.organizationId) {
           chain = chain.where('organization_id' as any, '=', ctx.organizationId)
         }
@@ -707,7 +802,10 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
         recipientUserId: ctx.userId,
         tenantId: ctx.tenantId,
         status: 'unread',
-        ...buildNotificationReadScopeWhere(ctx),
+        $and: [
+          buildNotificationReadScopeWhere(ctx),
+          inAppVisibleFilter(),
+        ],
       })
     },
 
@@ -716,7 +814,10 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
       const filters: Record<string, unknown> = {
         recipientUserId: ctx.userId,
         tenantId: ctx.tenantId,
-        ...buildNotificationReadScopeWhere(ctx),
+        $and: [
+          buildNotificationReadScopeWhere(ctx),
+          inAppVisibleFilter(),
+        ],
       }
 
       if (since) {
@@ -732,7 +833,10 @@ export function createNotificationService(deps: NotificationServiceDeps): Notifi
           recipientUserId: ctx.userId,
           tenantId: ctx.tenantId,
           status: 'unread',
-          ...buildNotificationReadScopeWhere(ctx),
+          $and: [
+            buildNotificationReadScopeWhere(ctx),
+            inAppVisibleFilter(),
+          ],
         }),
       ])
 

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

@@ -0,0 +1,48 @@
+import { sql, type RawBuilder } from 'kysely'
+import { IN_APP_CHANNEL } from './strategies/in-app-delivery-strategy'
+
+/**
+ * MikroORM filter fragment selecting notifications that should be VISIBLE in the in-app surfaces
+ * (bell, inbox list, unread count, poll). A row is visible when the `in_app` channel survived the
+ * create-time delivery gate — i.e. `in_app ∈ channels` — or when `channels` is NULL (legacy rows
+ * and any environment without the seam wired, which behave as "all channels" for backward
+ * compatibility). Rows targeted away from in-app (e.g. a push-only send, or a type/preference that
+ * excluded in_app) still exist as durable records but are hidden here.
+ *
+ * AND-composed with the caller's other conditions when merged into a filter object.
+ *
+ * `channels` is a JSONB column (`data/entities.ts`); MikroORM's `$contains` maps to the Postgres
+ * `@>` containment operator with a JSON-encoded operand — i.e. `channels @> '["in_app"]'` — so a row
+ * with `["in_app","email"]` matches and one with `["push"]` does not. Same operator MikroORM emits for
+ * the JSONB `$contains` filters already in production on `staff.role_ids` and `workflows.metadata`.
+ */
+export function inAppVisibleFilter(): { $or: Array<Record<string, unknown>> } {
+  return {
+    $or: [
+      { channels: null },
+      { channels: { $contains: [IN_APP_CHANNEL] } },
+    ],
+  }
+}
+
+/**
+ * In-memory counterpart of {@link inAppVisibleFilter} for a single row's resolved channel set. Used
+ * to gate the live bell SSE emit so a notification suppressed from the in-app channel does not push a
+ * real-time badge/inbox update. `null`/`undefined` channels ⇒ visible (legacy / all-channels).
+ */
+export function isInAppVisible(channels: string[] | null | undefined): boolean {
+  return channels == null || channels.includes(IN_APP_CHANNEL)
+}
+
+/**
+ * Raw-SQL counterpart of {@link inAppVisibleFilter} for queries built with Kysely
+ * (which cannot consume MikroORM's `$contains` fragment). Emits
+ * `(<column> IS NULL OR <column> @> '["in_app"]'::jsonb)` — the exact predicate
+ * MikroORM produces — so raw and ORM paths stay in lock-step. `columnRef` MUST be
+ * a trusted, code-controlled column identifier (never user input).
+ */
+export function inAppVisibleSql(columnRef = 'channels'): RawBuilder<boolean> {
+  return sql<boolean>`(${sql.ref(columnRef)} is null or ${sql.ref(columnRef)} @> ${sql.val(
+    JSON.stringify([IN_APP_CHANNEL]),
+  )}::jsonb)`
+}

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

@@ -1,10 +1,10 @@
 import { z } from 'zod'
 import type { AwilixContainer } from 'awilix'
 import { resolveRequestContext } from '@open-mercato/shared/lib/api/context'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
-import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { resolveNotificationService, type NotificationService } from './notificationService'
 
 /**
@@ -17,6 +17,11 @@ export const NOTIFICATION_RESOURCE_KIND = 'notifications.notification'
  */
 export const NOTIFICATION_SETTINGS_RESOURCE_KIND = 'notifications.settings'
 
+/**
+ * Mutation-guard resource kind for a user's channel preferences.
+ */
+export const NOTIFICATION_PREFERENCE_RESOURCE_KIND = 'notifications.preference'
+
 /**
  * Notification scope context for service calls
  */
@@ -120,6 +125,14 @@ export async function resolveNotificationContext(req: Request): Promise<Notifica
     service: resolveNotificationService(ctx.container),
     scope: {
       tenantId,
+      // The *creator's* org (the shared resolver already falls back to the caller's own org when
+      // nothing is selected), and the push strategy later scopes the recipient's device lookup to
+      // it. Same-org and self-notify (the common paths) match; a cross-org notify — an admin in
+      // org A notifying a user whose devices live in org B — won't match the recipient's devices,
+      // so push is silently dropped for that case. Same for a deliberate all-organizations
+      // selection, which stays tenant-level (org=null) and so only reaches null-org devices.
+      // In-app delivery is unaffected. If cross-org push is ever required, scope the device
+      // lookup by the recipient's org instead.
       organizationId,
       organizationIds,
       userId: ctx.auth?.sub ?? null,

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

@@ -0,0 +1,112 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { NotificationTypeDefinition } from '@open-mercato/shared/modules/notifications/types'
+import type { NotificationPreferenceScope } from './notificationPreferenceService'
+
+const logger = createLogger('notifications').child({ component: 'delivery-gate' })
+
+// One warning per unregistered type id per process — unregistered ids are rare (a renamed/removed type
+// still referenced by an in-flight notification), so the set stays tiny and the log never floods.
+const warnedUnregisteredTypes = new Set<string>()
+
+/**
+ * The single per-channel delivery gate. Every channel (`in_app`, `email`, `push`, custom) is
+ * governed by this one function so opt-out / eligibility / targeting enforcement can never be
+ * bypassed or re-implemented inconsistently per strategy.
+ *
+ * A channel is delivered when ALL hold:
+ *   1. it is a registered strategy id (`registeredChannels`),
+ *   2. the type is eligible for it — the operator's stored override
+ *      (`notification_types.channels`, when set) or the code-declared `type.channels`;
+ *      this runs BEFORE the `nonOptOut` bypass and before user preferences, so a channel
+ *      outside the effective set is completely off for the type,
+ *   3. it is in the per-send target (`targetChannels`, when provided),
+ *   4. either the type is effectively `nonOptOut` (operator override ?? code flag), or the
+ *      recipient has not disabled it (`isChannelEnabled`).
+ *
+ * `silent` is intentionally NOT consulted here — it selects push delivery STYLE, not whether a
+ * channel delivers at all. Absent `type.channels` and absent `targetChannels` both mean "no
+ * restriction", so a fully-default call resolves to every registered channel (pre-Phase-7 behavior).
+ */
+export type ChannelPreferenceReader = {
+  isChannelEnabled(scope: NotificationPreferenceScope, typeId: string, channel: string): Promise<boolean>
+}
+
+/**
+ * The effective eligibility set for a type: the operator's stored override replaces the
+ * code-declared `type.channels`; `null`/absent on both ⇒ no restriction (every channel).
+ */
+export function resolveEligibleChannels(
+  type: NotificationTypeDefinition | undefined,
+  channelsOverride: string[] | null | undefined,
+): string[] | null {
+  return channelsOverride ?? type?.channels ?? null
+}
+
+export type ShouldDeliverParams = {
+  /** The notification's `type` string (used for the preference lookup even when unregistered). */
+  typeId: string
+  /** The registered type definition, when the type id is known. Supplies eligibility + nonOptOut. */
+  type: NotificationTypeDefinition | undefined
+  channel: string
+  scope: NotificationPreferenceScope
+  /** Per-send channel target. `null`/`undefined` → no target restriction. */
+  targetChannels?: string[] | null
+  /** Ids of the currently registered delivery strategies. */
+  registeredChannels: string[]
+  preferences: ChannelPreferenceReader
+  /**
+   * Operator override of the type's eligibility from `notification_types.channels`.
+   * `undefined`/`null` ⇒ no override; the code-declared `type.channels` applies.
+   */
+  channelsOverride?: string[] | null
+  /**
+   * Operator override of the type's `nonOptOut` flag from `notification_types.non_opt_out`.
+   * `undefined`/`null` ⇒ no override; the code-declared flag applies.
+   */
+  nonOptOutOverride?: boolean | null
+}
+
+export async function shouldDeliver(params: ShouldDeliverParams): Promise<boolean> {
+  const {
+    typeId, type, channel, scope, targetChannels, registeredChannels, preferences,
+    channelsOverride, nonOptOutOverride,
+  } = params
+
+  if (!registeredChannels.includes(channel)) return false
+  const eligible = resolveEligibleChannels(type, channelsOverride)
+  if (eligible && !eligible.includes(channel)) return false
+  if (targetChannels && !targetChannels.includes(channel)) return false
+  if ((nonOptOutOverride ?? type?.nonOptOut) === true) return true
+
+  // The type id resolved to no registered definition (renamed/removed type), so its code-declared
+  // `nonOptOut` and eligibility cannot be enforced here — a security type that was `nonOptOut` becomes
+  // silently user-suppressible. Surface that once so it is not invisible (there is no operator override
+  // in play either, else the branch above would have returned).
+  if (!type && nonOptOutOverride == null && !warnedUnregisteredTypes.has(typeId)) {
+    warnedUnregisteredTypes.add(typeId)
+    logger.warn(
+      'Delivery gate evaluated an unregistered notification type; its code-declared nonOptOut/eligibility cannot be enforced and it is subject to user opt-out',
+      { typeId },
+    )
+  }
+
+  return preferences.isChannelEnabled(scope, typeId, channel)
+}
+
+export type ResolveEffectiveChannelsParams = Omit<ShouldDeliverParams, 'channel'>
+
+/**
+ * Resolves the authoritative channel set for a notification at create time: every registered
+ * channel that passes {@link shouldDeliver}. Stored on `Notification.channels` and looped by the
+ * dispatcher; `in_app` membership also gates bell/inbox visibility.
+ */
+export async function resolveEffectiveChannels(
+  params: ResolveEffectiveChannelsParams,
+): Promise<string[]> {
+  const results = await Promise.all(
+    params.registeredChannels.map(async (channel) =>
+      (await shouldDeliver({ ...params, channel })) ? channel : null,
+    ),
+  )
+  return results.filter((channel): channel is string => channel !== null)
+}

package/src/modules/notifications/lib/strategies/email-delivery-strategy.ts

@@ -0,0 +1,63 @@
+import { sendEmail } from '@open-mercato/shared/lib/email/send'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import NotificationEmail from '../../emails/NotificationEmail'
+import type { NotificationDeliveryContext, NotificationDeliveryStrategy } from '../deliveryStrategies'
+
+export const EMAIL_CHANNEL = 'email'
+
+const logger = createLogger('notifications')
+
+const DEBUG = process.env.NOTIFICATIONS_DEBUG === 'true'
+
+function debug(msg: string, fields?: Record<string, unknown>): void {
+  if (DEBUG) logger.debug(msg, fields)
+}
+
+/**
+ * Email delivery as a first-class strategy on the seam (previously hard-coded inline in the dispatch
+ * subscriber). Per-user opt-out and `nonOptOut`/`silent` are enforced upstream at create time via
+ * `shouldDeliver`; this strategy only owns technical deliverability: it runs when email is enabled by
+ * tenant config (`isConfigured`) and there is both a recipient address and a panel deep link.
+ */
+export const emailDeliveryStrategy: NotificationDeliveryStrategy = {
+  id: EMAIL_CHANNEL,
+  defaultEnabled: true,
+  isConfigured: (ctx: NotificationDeliveryContext) => ctx.deliveryConfig.strategies.email.enabled === true,
+  async deliver(ctx: NotificationDeliveryContext) {
+    const { recipient, panelLink, title, body, actionLinks, deliveryConfig, t } = ctx
+    if (!recipient?.email || !panelLink) {
+      debug('email skipped: missing recipient email or panelLink')
+      return
+    }
+
+    const subjectPrefix = deliveryConfig.strategies.email.subjectPrefix?.trim()
+    const subject = subjectPrefix ? `${subjectPrefix} ${title}` : title
+    const copy = {
+      preview: t('notifications.delivery.email.preview', 'New notification'),
+      heading: t('notifications.delivery.email.heading', 'You have a new notification'),
+      bodyIntro: t('notifications.delivery.email.bodyIntro', 'Review the notification details and take any required actions.'),
+      actionNotice: t('notifications.delivery.email.actionNotice', 'Actions are available in Open Mercato and are read-only in this email.'),
+      openCta: t('notifications.delivery.email.openCta', 'Open notification center'),
+      footer: t('notifications.delivery.email.footer', 'Open Mercato notifications'),
+    }
+
+    try {
+      debug('sending email', { to: recipient.email, from: deliveryConfig.strategies.email.from, subject })
+      await sendEmail({
+        to: recipient.email,
+        subject,
+        from: deliveryConfig.strategies.email.from,
+        replyTo: deliveryConfig.strategies.email.replyTo,
+        react: NotificationEmail({
+          title,
+          body,
+          actions: actionLinks,
+          panelUrl: panelLink,
+          copy,
+        }),
+      })
+    } catch (error) {
+      logger.error('email delivery failed', { error })
+    }
+  },
+}

package/src/modules/notifications/lib/strategies/in-app-delivery-strategy.ts

@@ -0,0 +1,21 @@
+import type { NotificationDeliveryStrategy } from '../deliveryStrategies'
+
+export const IN_APP_CHANNEL = 'in_app'
+
+/**
+ * In-app is a first-class channel of the delivery seam, but its "delivery" is the `Notification` row
+ * that `notificationService.create()` writes synchronously (the durable record that push/email
+ * reference and that the bell renders). There is nothing to send here.
+ *
+ * Whether the row is *visible* in the bell/inbox is governed by `in_app ∈ notification.channels`
+ * (resolved at create time by `shouldDeliver`) at the read layer — not by this strategy. Registering
+ * it makes in_app appear in the strategy registry so the create-time gate and the dispatcher treat it
+ * exactly like every other channel, with no channel-specific branch in the dispatcher.
+ */
+export const inAppDeliveryStrategy: NotificationDeliveryStrategy = {
+  id: IN_APP_CHANNEL,
+  defaultEnabled: true,
+  deliver: () => {
+    /* no-op: the row IS the in-app delivery; visibility is a read-layer concern */
+  },
+}