@open-mercato/core 0.6.8-develop.6983.1.e4f794099e → 0.6.8-develop.6985.1.fb93574faa

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

@@ -192,5 +192,6 @@
   "inbox_ops.translate.show_original": "Show original",
   "inbox_ops.translate.translate": "Translate",
   "inbox_ops.untitled_proposal": "Untitled proposal",
-  "inbox_ops.view_in_messages": "View in Messages"
+  "inbox_ops.view_in_messages": "View in Messages",
+  "notifications.categories.inbox_ops": "Inbox"
 }

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

@@ -192,5 +192,6 @@
   "inbox_ops.translate.show_original": "Mostrar original",
   "inbox_ops.translate.translate": "Traducir",
   "inbox_ops.untitled_proposal": "Propuesta sin t\u00edtulo",
-  "inbox_ops.view_in_messages": "Ver en mensajes"
+  "inbox_ops.view_in_messages": "Ver en mensajes",
+  "notifications.categories.inbox_ops": "Bandeja de entrada"
 }

package/src/modules/inbox_ops/i18n/ko.json

@@ -192,5 +192,6 @@
   "inbox_ops.translate.show_original": "원문 보기",
   "inbox_ops.translate.translate": "번역",
   "inbox_ops.untitled_proposal": "제목 없는 제안",
-  "inbox_ops.view_in_messages": "메시지에서 보기"
+  "inbox_ops.view_in_messages": "메시지에서 보기",
+  "notifications.categories.inbox_ops": "받은편지함"
 }

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

@@ -192,5 +192,6 @@
   "inbox_ops.translate.show_original": "Poka\u017c orygina\u0142",
   "inbox_ops.translate.translate": "Przet\u0142umacz",
   "inbox_ops.untitled_proposal": "Propozycja bez tytu\u0142u",
-  "inbox_ops.view_in_messages": "Zobacz w wiadomo\u015bciach"
+  "inbox_ops.view_in_messages": "Zobacz w wiadomo\u015bciach",
+  "notifications.categories.inbox_ops": "Skrzynka"
 }

package/src/modules/inbox_ops/notifications.ts

@@ -3,6 +3,8 @@ import type { NotificationTypeDefinition } from '@open-mercato/shared/modules/no
 export const notificationTypes: NotificationTypeDefinition[] = [
   {
     type: 'inbox_ops.proposal.created',
+    // Ships without push — operators re-enable it per type from the Notification Delivery settings.
+    channels: ['in_app', 'email'],
     module: 'inbox_ops',
     titleKey: 'inbox_ops.notifications.proposal_created.title',
     bodyKey: 'inbox_ops.notifications.proposal_created.body',

package/src/modules/messages/i18n/de.json

@@ -259,5 +259,6 @@
   "messages.visibilityInternal": "Intern",
   "messages.visibilityInternalHint": "Interne Nachrichten werden an ausgewählte Systemnutzer gesendet.",
   "messages.visibilityPublic": "Öffentlich",
-  "messages.visibilityPublicHint": "Öffentliche Nachrichten werden nur an externe E-Mail gesendet."
+  "messages.visibilityPublicHint": "Öffentliche Nachrichten werden nur an externe E-Mail gesendet.",
+  "notifications.categories.messages": "Nachrichten"
 }

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

@@ -259,5 +259,6 @@
   "messages.visibilityInternal": "Internal",
   "messages.visibilityInternalHint": "Internal messages are sent to selected system users.",
   "messages.visibilityPublic": "Public",
-  "messages.visibilityPublicHint": "Public messages are sent to external email only."
+  "messages.visibilityPublicHint": "Public messages are sent to external email only.",
+  "notifications.categories.messages": "Messages"
 }

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

@@ -259,5 +259,6 @@
   "messages.visibilityInternal": "Interna",
   "messages.visibilityInternalHint": "Los mensajes internos se envían a los usuarios del sistema seleccionados.",
   "messages.visibilityPublic": "Pública",
-  "messages.visibilityPublicHint": "Los mensajes públicos se envían solo al correo externo."
+  "messages.visibilityPublicHint": "Los mensajes públicos se envían solo al correo externo.",
+  "notifications.categories.messages": "Mensajes"
 }

package/src/modules/messages/i18n/ko.json

@@ -259,5 +259,6 @@
   "messages.visibilityInternal": "내부",
   "messages.visibilityInternalHint": "내부 메시지는 선택한 시스템 사용자에게 전송됩니다.",
   "messages.visibilityPublic": "공개",
-  "messages.visibilityPublicHint": "공개 메시지는 외부 이메일로만 전송됩니다."
+  "messages.visibilityPublicHint": "공개 메시지는 외부 이메일로만 전송됩니다.",
+  "notifications.categories.messages": "메시지"
 }

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

@@ -259,5 +259,6 @@
   "messages.visibilityInternal": "Wewnętrzna",
   "messages.visibilityInternalHint": "Wiadomości wewnętrzne są wysyłane do wybranych użytkowników systemu.",
   "messages.visibilityPublic": "Publiczna",
-  "messages.visibilityPublicHint": "Wiadomości publiczne są wysyłane wyłącznie na zewnętrzny e-mail."
+  "messages.visibilityPublicHint": "Wiadomości publiczne są wysyłane wyłącznie na zewnętrzny e-mail.",
+  "notifications.categories.messages": "Wiadomo\u015bci"
 }

package/src/modules/messages/notifications.ts

@@ -3,6 +3,8 @@ import type { NotificationTypeDefinition } from '@open-mercato/shared/modules/no
 export const notificationTypes: NotificationTypeDefinition[] = [
   {
     type: 'messages.new',
+    // Ships without push — operators re-enable it per type from the Notification Delivery settings.
+    channels: ['in_app', 'email'],
     module: 'messages',
     titleKey: 'messages.notifications.new.title',
     bodyKey: 'messages.notifications.new.body',

package/src/modules/notifications/AGENTS.md

@@ -0,0 +1,54 @@
+# Notifications Module — Agent Guidelines
+
+In-app notifications plus two channel-agnostic surfaces that every delivery channel (in-app, push, future email/SMS) reads from: a **DB-mirrored notification type catalogue** and **per-user channel preferences**. See `.ai/specs/2026-04-28-push-notifications-and-devices.md` (Phase 2).
+
+## Always
+
+- Register new notification types in your **own** module's `notifications.ts` (`notificationTypes: NotificationTypeDefinition[]`). The generator aggregates them; `bootstrap.ts` feeds the aggregate into the in-memory registry (`lib/notification-type-registry.ts`) via `registerNotificationTypes(...)`. Do **not** add a defaults array here.
+- Read channel preferences through `NotificationPreferenceService` (DI: `notificationPreferenceService`) — never query `notification_preferences` directly from another module. Use `isChannelEnabled(scope, typeId, channel)` (defaults to `true` when no row exists — lazy-seed, default-on).
+- Keep type ids **FROZEN** (BACKWARD_COMPATIBILITY.md): once a `NotificationTypeDefinition.type` ships it is a stable contract; renames need the deprecation protocol.
+- Keep API URLs **STABLE**: `/api/notifications/types`, `/api/notifications/preferences` are additive-only.
+- Wire custom write routes through the mutation guard via `runGuardedNotificationWrite(...)` in `lib/routeHelpers.ts` (the preferences `PUT` does this).
+
+## Delivery channels & the gate (Phase 7)
+
+- **Every channel is a strategy on one seam.** `in_app`, `email`, and `push` are all `NotificationDeliveryStrategy` objects (`lib/deliveryStrategies.ts`), registered via a `notifications.delivery-strategies.ts` convention file discovered by the `delivery-strategies` generator plugin. `in_app` is a no-op strategy — the durable `Notification` row IS the in-app delivery; its bell/inbox **visibility** is `in_app ∈ notification.channels` (see `lib/notificationVisibility.ts`), applied at the read layer, not by the strategy.
+- **One gate, at create time.** `notificationService.create*` calls `resolveEffectiveChannels` (`lib/shouldDeliver.ts`) once per recipient — composing per-send target (`input.channels`) ∩ per-type eligibility (`NotificationTypeDefinition.channels`) ∩ registered strategies ∩ the recipient's per-channel preference (`nonOptOut` bypasses opt-out; `silent` is orthogonal) — and snapshots the result on `Notification.channels`. The dispatch subscriber then just loops the registered strategies filtered by that set (`NULL ⇒ all channels`, legacy/BC). **Do not** re-implement opt-out logic inside a strategy — the gate already ran. Use `isConfigured(ctx)`/`supports(notification)` only for technical deliverability.
+- **Absent `channels` on a create call ⇒ all channels** (unchanged behavior). Pass `channels: ['push']` (etc.) to target a subset.
+- **Channel catalogue.** Add a channel's UI metadata by exporting `notificationChannels: NotificationChannelDefinition[]` from a `notification-channels.ts` (generator-discovered → `getNotificationChannels()` → `GET /api/notifications/channels`; the preferences UI reads it). Keep each delivery-strategy `id` and its channel-definition `id` in sync — behavior layer (strategy registry) + metadata layer (channel registry), same id.
+- **When adding an in-app read surface** (a new bell/inbox/count query), AND-in `inAppVisibleFilter()` so suppressed rows stay hidden.
+
+## Never
+
+- Never create a cross-module ORM relationship to `notification_types` / `notification_preferences`. `NotificationPreference.notificationTypeId` is a **soft string ref** to a type id, not a FK relation.
+- Never gate per-user opt-out inside a delivery strategy — enforcement is centralized in the create-time gate (`shouldDeliver`). A strategy that re-checks preferences double-counts and drifts.
+- Never write per-tenant rows into `notification_types`. Code-registered types are **system-wide** (`tenant_id IS NULL`); the column is nullable only to leave room for future tenant-defined types.
+- Never expose another tenant's preferences — all reads/writes are scoped by `(tenantId, userId)`.
+
+## Type catalogue (read-through mirror)
+
+- The in-memory `NotificationTypeDefinition` registry is the source of truth for code. `notification_types` is a **read-through DB mirror** so remote clients (mobile apps) can enumerate types over HTTP without shipping the catalogue.
+- `syncNotificationTypes(em)` reconciles the registry into the table (idempotent, `tenant_id IS NULL`). It runs lazily on the first `GET /api/notifications/types` per process and on the `notifications.type_registry.sync` event (emitted from `setup.ts` `seedDefaults`; handled by `subscribers/sync-notification-types.ts`).
+- Field map: `id ← def.type`, `label_key ← def.labelKey ?? def.titleKey`, `description_key ← def.descriptionKey ?? null`, `category ← def.category ?? deriveCategory(def.type)`. Give a type a distinct preferences-screen label by adding optional `labelKey`/`descriptionKey` to its `NotificationTypeDefinition` (additive — falls back to `titleKey`).
+- **Grouping (`category`).** Defaults to the prefix before the first dot in the type id (`sales.order.created` → `sales`), resolved once in `syncNotificationTypes` so every mirrored row carries a key and read paths need no fallback branch. Declare `category` on the definition only to override that default.
+- **Category labels live in the declaring module, never here.** This module ships no `notifications.categories.*` entries and holds no list of categories — it must stay ignorant of which ones exist. To localize a heading, add `notifications.categories.<key>` to **your own** module's `i18n/{en,pl,es,de}.json`; dictionaries merge flat across modules, so the shared key namespace costs no coupling. A category with no translation anywhere falls back to the raw key.
+- **`GET /api/notifications/types` returns resolved display strings** — `label`, `description`, `categoryLabel` — alongside the existing `labelKey`/`descriptionKey`/`category`, so clients without the app dictionary (the mobile app) render directly. Locale comes from `resolveLocaleFromRequest` (`?locale=` → `x-locale` → cookie → `Accept-Language`), re-validated through `resolveSupportedLocale` because only that helper's `Accept-Language` branch validates its input. **Group on `category`, display `categoryLabel`** — grouping on the localized string re-partitions the list whenever the locale changes.
+- Mark a type `silent: true` on its `NotificationTypeDefinition` to make its pushes content-available wake-ups (no banner, data-only). `silent` controls **delivery style only** — the notification still flows through the normal `notificationService.create()` path (in-app row created, per-channel push preference respected); to make a silent type always fire, also mark it `nonOptOut: true`. There is no separate silent-send API — the `push` delivery strategy handles `silent` types. The flag lives only in the in-memory registry (not mirrored to `notification_types`).
+- A create call may carry an optional `data` (arbitrary app-readable string map — persisted on the row, exposed in the notification DTO, and delivered in the push data payload) and `pushOptions` (flat `sound`/`badge`/`image`/`priority`/`channelId`/`body` map — persisted, push-only, mapped per provider by the push adapters). Both are additive optional fields on the create/batch/role/feature schemas.
+
+## Preferences & optimistic locking
+
+- `NotificationPreference` carries `updated_at` but is **intentionally excluded** from the curated `optimistic-lock-editable-entities.test.ts` `notifications` list: it is an idempotent, lazy-seeded self-setting written through a service (`setPreferences`) + mutation guard, **not** `CrudForm`/`makeCrudRoute`, so a lost-update undo stack adds no value. When a preferences UI lands (Phase 5), its mutating call must either send the optimistic-lock version header or carry an inline `optimistic-lock-exempt` marker to satisfy `optimistic-lock-ui-coverage.test.ts`.
+
+## ACL
+
+- `notifications.view`, `notifications.create`, `notifications.manage`, `notifications.manage_preferences` (self-serve; granted to all default roles). After editing `acl.ts`, run `yarn mercato auth sync-role-acls`.
+
+## Validation
+
+```bash
+yarn generate
+yarn db:generate            # diff probe; keep only the notifications migration + snapshot
+yarn workspace @open-mercato/core build
+yarn workspace @open-mercato/core test
+```

package/src/modules/notifications/acl.ts

@@ -2,6 +2,8 @@ export const features = [
   { id: 'notifications.view', title: 'View own notifications', module: 'notifications' },
   { id: 'notifications.create', title: 'Create notifications for others', module: 'notifications' },
   { id: 'notifications.manage', title: 'Manage all notifications', module: 'notifications' },
+  { id: 'notifications.manage_preferences', title: 'Manage own notification preferences', module: 'notifications' },
+  { id: 'notifications.manage_user_preferences', title: "Manage other users' notification preferences", module: 'notifications' },
 ]
 
 export default features

package/src/modules/notifications/api/admin/preferences/route.ts

@@ -0,0 +1,193 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { User } from '../../../../auth/data/entities'
+import { assertActorCanAccessUserTarget } from '../../../../auth/lib/grantChecks'
+import { resolveOrganizationScopeForRequest } from '../../../../directory/utils/organizationScope'
+import type { RbacService } from '../../../../auth/services/rbacService'
+import { resolveNotificationPreferenceService, type NotificationPreferenceScope } from '../../../lib/notificationPreferenceService'
+import {
+  runGuardedNotificationWrite,
+  notificationValidationErrorResponse,
+  NOTIFICATION_PREFERENCE_RESOURCE_KIND,
+} from '../../../lib/routeHelpers'
+import { PREFERENCE_UPDATED_EVENT, emitNotificationEvent } from '../../../events'
+import {
+  adminPreferencesQuerySchema,
+  adminUpdatePreferencesSchema,
+  notificationPreferenceItemSchema,
+} from '../../../data/validators'
+import { errorResponseSchema } from '../../openapi'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['notifications.manage_user_preferences'] },
+  PUT: { requireAuth: true, requireFeatures: ['notifications.manage_user_preferences'] },
+}
+
+const unauthorized = async () => {
+  const { t } = await resolveTranslations()
+  return NextResponse.json({ error: t('api.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+}
+
+/**
+ * Authorize the acting admin to manage a target user's preferences. Returns an error response to
+ * send, or null when access is granted. Two gates, mirroring the platform's user-management scoping:
+ *   - 404 when the user does not exist in the acting tenant (existence/tenant check — the shared
+ *     `assertActorCanAccessUserTarget` delegates silently on a fully-missing target).
+ *   - standard org scoping via `assertActorCanAccessUserTarget` (403 out-of-org / 404 cross-tenant,
+ *     super-admin and `__all__` bypass) — the same guard `auth` user CRUD uses, instead of a
+ *     hand-rolled tenant-only check.
+ */
+async function authorizeTargetUser(
+  container: AwilixContainer,
+  em: EntityManager,
+  auth: AuthContext & { sub: string; tenantId: string },
+  req: Request,
+  targetUserId: string,
+): Promise<NextResponse | null> {
+  const { t } = await resolveTranslations()
+  const user = await findOneWithDecryption(
+    em,
+    User,
+    { id: targetUserId, tenantId: auth.tenantId, deletedAt: null },
+    undefined,
+    { tenantId: auth.tenantId, organizationId: null },
+  )
+  if (!user) {
+    return NextResponse.json({ error: t('notifications.preferences.userNotFound', 'User not found') }, { status: 404 })
+  }
+  try {
+    const rbacService = container.resolve('rbacService') as RbacService
+    await assertActorCanAccessUserTarget({
+      em,
+      rbacService,
+      actorUserId: auth.sub,
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId ?? null,
+      targetUserId,
+      organizationScope: await resolveOrganizationScopeForRequest({
+        container,
+        auth,
+        request: req,
+        tenantId: auth.tenantId,
+      }),
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    throw err
+  }
+  return null
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub || !auth.tenantId) return await unauthorized()
+
+  const url = new URL(req.url)
+  const parsed = adminPreferencesQuerySchema.safeParse({ userId: url.searchParams.get('userId') ?? undefined })
+  if (!parsed.success) return notificationValidationErrorResponse(parsed.error)
+
+  const container = await createRequestContainer()
+  try {
+    const em = container.resolve('em') as EntityManager
+    const denied = await authorizeTargetUser(container, em, { ...auth, sub: auth.sub, tenantId: auth.tenantId }, req, parsed.data.userId)
+    if (denied) return denied
+    const service = resolveNotificationPreferenceService(container)
+    const scope: NotificationPreferenceScope = { tenantId: auth.tenantId, userId: parsed.data.userId }
+    const rows = await service.listForUser(scope)
+    const items = rows.map((row) => ({
+      notificationTypeId: row.notificationTypeId,
+      channel: row.channel,
+      enabled: row.enabled,
+    }))
+    return NextResponse.json({ items })
+  } finally {
+    const disposable = container as unknown as { dispose?: () => Promise<void> }
+    if (typeof disposable.dispose === 'function') await disposable.dispose()
+  }
+}
+
+export async function PUT(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub || !auth.tenantId) return await unauthorized()
+
+  const parsed = adminUpdatePreferencesSchema.safeParse(await readJsonSafe(req, {}))
+  if (!parsed.success) return notificationValidationErrorResponse(parsed.error)
+
+  const container = await createRequestContainer()
+  try {
+    const em = container.resolve('em') as EntityManager
+    const denied = await authorizeTargetUser(container, em, { ...auth, sub: auth.sub, tenantId: auth.tenantId }, req, parsed.data.userId)
+    if (denied) return denied
+    const service = resolveNotificationPreferenceService(container)
+    const scope: NotificationPreferenceScope = { tenantId: auth.tenantId, userId: parsed.data.userId }
+    const guarded = await runGuardedNotificationWrite(
+      container,
+      { tenantId: auth.tenantId, organizationId: auth.orgId ?? null, userId: auth.sub },
+      req,
+      {
+        resourceKind: NOTIFICATION_PREFERENCE_RESOURCE_KIND,
+        resourceId: parsed.data.userId,
+        operation: 'update',
+        payload: parsed.data as Record<string, unknown>,
+      },
+      () =>
+        service.setPreferences(
+          scope,
+          parsed.data.preferences.map((p) => ({ typeId: p.notificationTypeId, channel: p.channel, enabled: p.enabled })),
+        ),
+    )
+    if (!guarded.ok) return guarded.response
+
+    // Skip the event on no-op writes (nothing actually changed).
+    if (guarded.result > 0) {
+      await emitNotificationEvent(PREFERENCE_UPDATED_EVENT, {
+        tenantId: auth.tenantId,
+        organizationId: auth.orgId ?? null,
+        userId: parsed.data.userId,
+      })
+    }
+
+    return NextResponse.json({ ok: true })
+  } finally {
+    const disposable = container as unknown as { dispose?: () => Promise<void> }
+    if (typeof disposable.dispose === 'function') await disposable.dispose()
+  }
+}
+
+export const openApi = {
+  GET: {
+    summary: "Get a user's notification preferences (admin)",
+    description: "Returns a target user's stored channel preferences. Requires notifications.manage_user_preferences.",
+    tags: ['Notifications'],
+    parameters: [{ name: 'userId', in: 'query', required: true, schema: { type: 'string', format: 'uuid' } }],
+    responses: {
+      200: {
+        description: 'Stored preferences',
+        content: { 'application/json': { schema: z.object({ items: z.array(notificationPreferenceItemSchema) }) } },
+      },
+      401: { description: 'Unauthorized', content: { 'application/json': { schema: errorResponseSchema } } },
+      404: { description: 'User not found', content: { 'application/json': { schema: errorResponseSchema } } },
+    },
+  },
+  PUT: {
+    summary: "Update a user's notification preferences (admin)",
+    description: "Bulk-updates a target user's channel preferences. Requires notifications.manage_user_preferences.",
+    tags: ['Notifications'],
+    requestBody: { required: true, content: { 'application/json': { schema: adminUpdatePreferencesSchema } } },
+    responses: {
+      200: { description: 'Preferences updated', content: { 'application/json': { schema: z.object({ ok: z.boolean() }) } } },
+      400: { description: 'Invalid request body', content: { 'application/json': { schema: errorResponseSchema } } },
+      401: { description: 'Unauthorized', content: { 'application/json': { schema: errorResponseSchema } } },
+      404: { description: 'User not found', content: { 'application/json': { schema: errorResponseSchema } } },
+    },
+  },
+}

package/src/modules/notifications/api/channels/route.ts

@@ -0,0 +1,54 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { getNotificationChannels } from '../../lib/notification-channel-registry'
+import { errorResponseSchema } from '../openapi'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['notifications.view'] },
+}
+
+const channelItemSchema = z.object({
+  id: z.string(),
+  labelKey: z.string(),
+  descriptionKey: z.string().nullable(),
+})
+
+export async function GET(req: Request) {
+  const { t } = await resolveTranslations()
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub || !auth.tenantId) {
+    return NextResponse.json({ error: t('api.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+  }
+
+  const items = getNotificationChannels().map((channel) => ({
+    id: channel.id,
+    labelKey: channel.labelKey,
+    descriptionKey: channel.descriptionKey ?? null,
+  }))
+  return NextResponse.json({ items })
+}
+
+export const openApi = {
+  GET: {
+    summary: 'List notification delivery channels',
+    description:
+      'Returns the registered delivery channel catalogue (in-app, email, push, …) so a preferences screen can render one column per channel without a hardcoded list.',
+    tags: ['Notifications'],
+    responses: {
+      200: {
+        description: 'Notification channel catalogue',
+        content: {
+          'application/json': {
+            schema: z.object({ items: z.array(channelItemSchema) }),
+          },
+        },
+      },
+      401: {
+        description: 'Unauthorized',
+        content: { 'application/json': { schema: errorResponseSchema } },
+      },
+    },
+  },
+}

package/src/modules/notifications/api/preferences/route.ts

@@ -0,0 +1,131 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { resolveNotificationPreferenceService, type NotificationPreferenceScope } from '../../lib/notificationPreferenceService'
+import {
+  runGuardedNotificationWrite,
+  notificationValidationErrorResponse,
+  NOTIFICATION_PREFERENCE_RESOURCE_KIND,
+} from '../../lib/routeHelpers'
+import { PREFERENCE_UPDATED_EVENT, emitNotificationEvent } from '../../events'
+import { updatePreferencesSchema, notificationPreferenceItemSchema } from '../../data/validators'
+import { errorResponseSchema } from '../openapi'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['notifications.manage_preferences'] },
+  PUT: { requireAuth: true, requireFeatures: ['notifications.manage_preferences'] },
+}
+
+const unauthorized = async () => {
+  const { t } = await resolveTranslations()
+  return NextResponse.json({ error: t('api.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub || !auth.tenantId) return await unauthorized()
+
+  const container = await createRequestContainer()
+  try {
+    const service = resolveNotificationPreferenceService(container)
+    const scope: NotificationPreferenceScope = { tenantId: auth.tenantId, userId: auth.sub }
+    const rows = await service.listForUser(scope)
+    const items = rows.map((row) => ({
+      notificationTypeId: row.notificationTypeId,
+      channel: row.channel,
+      enabled: row.enabled,
+    }))
+    return NextResponse.json({ items })
+  } finally {
+    const disposable = container as unknown as { dispose?: () => Promise<void> }
+    if (typeof disposable.dispose === 'function') await disposable.dispose()
+  }
+}
+
+export async function PUT(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub || !auth.tenantId) return await unauthorized()
+
+  const parsed = updatePreferencesSchema.safeParse(await readJsonSafe(req, {}))
+  if (!parsed.success) return notificationValidationErrorResponse(parsed.error)
+
+  const container = await createRequestContainer()
+  try {
+    const service = resolveNotificationPreferenceService(container)
+    const scope: NotificationPreferenceScope = { tenantId: auth.tenantId, userId: auth.sub }
+    const guarded = await runGuardedNotificationWrite(
+      container,
+      { tenantId: auth.tenantId, organizationId: auth.orgId ?? null, userId: auth.sub },
+      req,
+      {
+        resourceKind: NOTIFICATION_PREFERENCE_RESOURCE_KIND,
+        resourceId: auth.sub,
+        operation: 'update',
+        payload: parsed.data as Record<string, unknown>,
+      },
+      () =>
+        service.setPreferences(
+          scope,
+          parsed.data.preferences.map((p) => ({
+            typeId: p.notificationTypeId,
+            channel: p.channel,
+            enabled: p.enabled,
+          })),
+        ),
+    )
+    if (!guarded.ok) return guarded.response
+
+    // Skip the event on no-op writes (nothing actually changed).
+    if (guarded.result > 0) {
+      await emitNotificationEvent(PREFERENCE_UPDATED_EVENT, {
+        tenantId: auth.tenantId,
+        organizationId: auth.orgId ?? null,
+        userId: auth.sub,
+      })
+    }
+
+    return NextResponse.json({ ok: true })
+  } finally {
+    const disposable = container as unknown as { dispose?: () => Promise<void> }
+    if (typeof disposable.dispose === 'function') await disposable.dispose()
+  }
+}
+
+export const openApi = {
+  GET: {
+    summary: 'Get notification preferences',
+    description: "Returns the current user's stored channel preferences (absent rows default to enabled).",
+    tags: ['Notifications'],
+    responses: {
+      200: {
+        description: 'Stored preferences',
+        content: {
+          'application/json': {
+            schema: z.object({ items: z.array(notificationPreferenceItemSchema) }),
+          },
+        },
+      },
+      401: { description: 'Unauthorized', content: { 'application/json': { schema: errorResponseSchema } } },
+    },
+  },
+  PUT: {
+    summary: 'Update notification preferences',
+    description: "Bulk-updates the current user's channel preferences.",
+    tags: ['Notifications'],
+    requestBody: {
+      required: true,
+      content: { 'application/json': { schema: updatePreferencesSchema } },
+    },
+    responses: {
+      200: {
+        description: 'Preferences updated',
+        content: { 'application/json': { schema: z.object({ ok: z.boolean() }) } },
+      },
+      400: { description: 'Invalid request body', content: { 'application/json': { schema: errorResponseSchema } } },
+      401: { description: 'Unauthorized', content: { 'application/json': { schema: errorResponseSchema } } },
+    },
+  },
+}

package/src/modules/notifications/api/route.ts

@@ -12,6 +12,7 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi/types'
 import { Notification } from '../data/entities'
 import { listNotificationsSchema, createNotificationSchema } from '../data/validators'
 import { toNotificationDto } from '../lib/notificationMapper'
+import { inAppVisibleFilter } from '../lib/notificationVisibility'
 import {
   buildNotificationReadScopeWhere,
   getNotificationReadScopeTagOrganizationIds,
@@ -136,7 +137,13 @@ export async function GET(req: Request) {
   const filters: Record<string, unknown> = {
     recipientUserId: userId,
     tenantId: scope.tenantId,
-    ...buildNotificationReadScopeWhere(scope),
+    // Read scope AND in-app visibility: both fragments carry their own `$or`, so they must be
+    // AND-composed instead of spread (a spread would silently drop one of them).
+    // Hidden rows are those not delivered to the in-app channel (push-only / opted-out); they remain as records.
+    $and: [
+      buildNotificationReadScopeWhere(scope),
+      inAppVisibleFilter(),
+    ],
   }
 
   if (input.status) {