@open-mercato/core 0.6.5-develop.4384.1.ce2ec6eaaa → 0.6.5-develop.4397.1.9a65481757

package/src/modules/communication_channels/migrations/Migration20260526134719_communication_channels.ts

@@ -0,0 +1,55 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260526134719_communication_channels extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "channel_thread_mappings" ("id" uuid not null default gen_random_uuid(), "external_conversation_id" uuid not null, "message_thread_id" uuid not null, "channel_id" uuid not null, "provider_key" text not null, "external_thread_ref" text not null, "assigned_user_id" uuid null, "tenant_id" uuid not null, "organization_id" uuid null, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "channel_thread_mappings_thread_idx" on "channel_thread_mappings" ("message_thread_id", "tenant_id");`);
+    this.addSql(`create index "channel_thread_mappings_ext_conv_idx" on "channel_thread_mappings" ("external_conversation_id", "tenant_id");`);
+    this.addSql(`alter table "channel_thread_mappings" add constraint "channel_thread_mappings_ext_conv_uq" unique ("external_conversation_id", "tenant_id");`);
+
+    this.addSql(`create table "communication_channels" ("id" uuid not null default gen_random_uuid(), "provider_key" text not null, "channel_type" text not null, "display_name" text not null, "external_identifier" text null, "credentials_ref" uuid null, "capabilities" jsonb null, "is_active" boolean not null default true, "user_id" uuid null, "is_primary" boolean not null default false, "poll_interval_seconds" int null, "last_polled_at" timestamptz null, "status" text not null default 'connected', "last_error" text null, "channel_state" jsonb null, "tenant_id" uuid not null, "organization_id" uuid null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create index "communication_channels_tenant_type_active_idx" on "communication_channels" ("tenant_id", "channel_type", "is_active");`);
+    this.addSql(`create index "communication_channels_tenant_provider_idx" on "communication_channels" ("tenant_id", "provider_key");`);
+    this.addSql(`create unique index "communication_channels_one_primary_per_user_uq" on "communication_channels" ("user_id") where "is_primary" and "user_id" is not null and "deleted_at" is null;`);
+    this.addSql(`create index "communication_channels_poll_due_idx" on "communication_channels" ("is_active", "last_polled_at") where "deleted_at" is null;`);
+    this.addSql(`create index "communication_channels_user_lookup_idx" on "communication_channels" ("user_id", "channel_type", "deleted_at");`);
+
+    this.addSql(`create table "external_conversations" ("id" uuid not null default gen_random_uuid(), "channel_id" uuid not null, "external_conversation_id" text not null, "subject" text null, "contact_person_id" uuid null, "assigned_user_id" uuid null, "last_message_at" timestamptz null, "tenant_id" uuid not null, "organization_id" uuid null, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "external_conversations_assigned_user_idx" on "external_conversations" ("assigned_user_id");`);
+    this.addSql(`create index "external_conversations_contact_person_idx" on "external_conversations" ("contact_person_id");`);
+    this.addSql(`create index "external_conversations_channel_idx" on "external_conversations" ("channel_id", "external_conversation_id");`);
+    this.addSql(`alter table "external_conversations" add constraint "external_conversations_channel_external_uq" unique ("channel_id", "external_conversation_id");`);
+
+    this.addSql(`create table "external_messages" ("id" uuid not null default gen_random_uuid(), "channel_id" uuid not null, "conversation_id" uuid not null, "external_message_id" text not null, "direction" text not null, "sender_identifier" text null, "sender_display_name" text null, "provider_timestamp" timestamptz null, "tenant_id" uuid not null, "organization_id" uuid null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "external_messages_channel_external_idx" on "external_messages" ("channel_id", "external_message_id");`);
+    this.addSql(`create index "external_messages_conversation_idx" on "external_messages" ("conversation_id");`);
+    this.addSql(`alter table "external_messages" add constraint "external_messages_channel_external_uq" unique ("channel_id", "external_message_id");`);
+
+    this.addSql(`create table "message_channel_links" ("id" uuid not null default gen_random_uuid(), "message_id" uuid not null, "external_conversation_id" uuid not null, "external_message_id" uuid null, "provider_key" text not null, "channel_type" text not null, "direction" text not null, "delivery_status" text not null default 'pending', "channel_payload" jsonb null, "channel_content_type" text null, "interactive_state" jsonb null, "channel_metadata" jsonb null, "tenant_id" uuid not null, "organization_id" uuid null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "message_channel_links_ext_msg_idx" on "message_channel_links" ("external_message_id");`);
+    this.addSql(`create index "message_channel_links_ext_conv_idx" on "message_channel_links" ("external_conversation_id");`);
+    this.addSql(`create index "message_channel_links_message_idx" on "message_channel_links" ("message_id");`);
+    this.addSql(`alter table "message_channel_links" add constraint "message_channel_links_message_uq" unique ("message_id");`);
+
+    this.addSql(`create table "message_reactions" ("id" uuid not null default gen_random_uuid(), "message_id" uuid not null, "emoji" text not null, "reacted_by_user_id" uuid null, "reacted_by_external_id" text null, "reacted_by_display_name" text null, "provider_key" text null, "external_reaction_id" text null, "tenant_id" uuid not null, "organization_id" uuid null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`alter table "message_reactions" add constraint "message_reactions_exactly_one_actor_chk" check (("reacted_by_user_id" is null) <> ("reacted_by_external_id" is null));`);
+    this.addSql(`create index "message_reactions_message_emoji_idx" on "message_reactions" ("message_id", "emoji");`);
+    this.addSql(`create index "message_reactions_message_idx" on "message_reactions" ("message_id");`);
+    this.addSql(`create unique index "message_reactions_external_actor_uq" on "message_reactions" ("tenant_id", "message_id", "emoji", "reacted_by_external_id") where "reacted_by_external_id" is not null;`);
+    this.addSql(`create unique index "message_reactions_internal_actor_uq" on "message_reactions" ("tenant_id", "message_id", "emoji", "reacted_by_user_id") where "reacted_by_user_id" is not null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "message_reactions";`);
+    this.addSql(`drop table if exists "message_channel_links";`);
+    this.addSql(`drop table if exists "external_messages";`);
+    this.addSql(`drop table if exists "external_conversations";`);
+    this.addSql(`drop index if exists "communication_channels_user_lookup_idx";`);
+    this.addSql(`drop index if exists "communication_channels_poll_due_idx";`);
+    this.addSql(`drop index if exists "communication_channels_one_primary_per_user_uq";`);
+    this.addSql(`drop table if exists "communication_channels";`);
+    this.addSql(`drop table if exists "channel_thread_mappings";`);
+  }
+
+}

package/src/modules/communication_channels/migrations/Migration20260527195446_communication_channels.ts

@@ -0,0 +1,20 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260527195446_communication_channels extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "channel_ingest_dead_letters" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid null, "channel_id" uuid not null, "provider_key" text not null, "external_uid" text null, "external_message_id" text null, "error_class" text not null, "error_message" text not null, "raw_body" text null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "channel_ingest_dead_letters_created_idx" on "channel_ingest_dead_letters" ("tenant_id", "created_at");`);
+    this.addSql(`create index "channel_ingest_dead_letters_channel_idx" on "channel_ingest_dead_letters" ("channel_id", "tenant_id");`);
+
+    this.addSql(`create table "channel_thread_tokens" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid null, "message_thread_id" uuid not null, "token" text not null, "created_at" timestamptz not null, "last_seen_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create index "channel_thread_tokens_thread_idx" on "channel_thread_tokens" ("message_thread_id", "tenant_id");`);
+    this.addSql(`alter table "channel_thread_tokens" add constraint "channel_thread_tokens_token_uq" unique ("tenant_id", "token");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "channel_ingest_dead_letters";`);
+    this.addSql(`drop table if exists "channel_thread_tokens";`);
+  }
+
+}

package/src/modules/communication_channels/migrations/Migration20260529231848_communication_channels.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260529231848_communication_channels extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create index "communication_channels_provider_external_idx" on "communication_channels" ("provider_key", "external_identifier") where "deleted_at" is null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index "communication_channels_provider_external_idx";`);
+  }
+
+}

package/src/modules/communication_channels/migrations/Migration20260531120000_communication_channels.ts

@@ -0,0 +1,24 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260531120000_communication_channels extends Migration {
+
+  override up(): void | Promise<void> {
+    // Enforce one thread token per (tenant, message_thread_id). Replaces the
+    // earlier non-unique `channel_thread_tokens_thread_idx` so `getOrCreateThreadToken`
+    // is idempotent under concurrency (insert-on-conflict). The new unique index
+    // also serves the `WHERE tenant_id = ? AND message_thread_id = ?` lookup.
+    this.addSql(`drop index if exists "channel_thread_tokens_thread_idx";`);
+    this.addSql(`alter table "channel_thread_tokens" add constraint "channel_thread_tokens_thread_uq" unique ("tenant_id", "message_thread_id");`);
+    // Enforce one channel per (tenant, user, provider, mailbox) so a reconnect
+    // heals the existing row instead of inserting a duplicate. Partial: tenant-wide
+    // (null user_id) and identifier-less channels are exempt.
+    this.addSql(`create unique index "communication_channels_user_provider_external_uq" on "communication_channels" ("tenant_id", "user_id", "provider_key", "external_identifier") where "deleted_at" is null and "user_id" is not null and "external_identifier" is not null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index if exists "communication_channels_user_provider_external_uq";`);
+    this.addSql(`alter table "channel_thread_tokens" drop constraint if exists "channel_thread_tokens_thread_uq";`);
+    this.addSql(`create index "channel_thread_tokens_thread_idx" on "channel_thread_tokens" ("message_thread_id", "tenant_id");`);
+  }
+
+}

package/src/modules/communication_channels/notifications.client.ts

@@ -0,0 +1,50 @@
+'use client'
+
+import type { NotificationTypeDefinition } from '@open-mercato/shared/modules/notifications/types'
+import { MessageReceivedRenderer } from './widgets/notifications/MessageReceivedRenderer'
+import { ChannelRequiresReauthRenderer } from './widgets/notifications/ChannelRequiresReauthRenderer'
+
+export const communicationChannelsNotificationTypes: NotificationTypeDefinition[] = [
+  {
+    type: 'communication_channels.message.received',
+    module: 'communication_channels',
+    titleKey: 'communication_channels.notifications.message_received.title',
+    bodyKey: 'communication_channels.notifications.message_received.body',
+    icon: 'message-circle',
+    severity: 'info',
+    actions: [
+      {
+        id: 'view',
+        labelKey: 'common.view',
+        variant: 'outline',
+        href: '/backend/messages/{sourceEntityId}',
+        icon: 'external-link',
+      },
+    ],
+    linkHref: '/backend/messages/{sourceEntityId}',
+    Renderer: MessageReceivedRenderer,
+    expiresAfterHours: 168,
+  },
+  {
+    type: 'communication_channels.channel.requires_reauth',
+    module: 'communication_channels',
+    titleKey: 'communication_channels.notifications.channel_requires_reauth.title',
+    bodyKey: 'communication_channels.notifications.channel_requires_reauth.body',
+    icon: 'alert-triangle',
+    severity: 'warning',
+    actions: [
+      {
+        id: 'reconnect',
+        labelKey: 'communication_channels.notifications.channel_requires_reauth.reconnect',
+        variant: 'outline',
+        href: '/backend/profile/communication-channels?reconnect={sourceEntityId}',
+        icon: 'refresh-cw',
+      },
+    ],
+    linkHref: '/backend/profile/communication-channels?reconnect={sourceEntityId}',
+    Renderer: ChannelRequiresReauthRenderer,
+    expiresAfterHours: 720,
+  },
+]
+
+export default communicationChannelsNotificationTypes

package/src/modules/communication_channels/notifications.handlers.ts

@@ -0,0 +1,86 @@
+import type { NotificationHandler } from '@open-mercato/shared/modules/notifications/handler'
+
+/**
+ * Reactive notification handlers for the Communications Hub (Phase 4 of the
+ * email integration spec).
+ *
+ * These handlers fire on the browser when the matching notification arrives via
+ * the notifications stream. They run in addition to (not instead of) the static
+ * UI surfaces:
+ *
+ *   - The notification appears in the user's bell dropdown via
+ *     `notifications.client.ts` renderers (already wired in slice 2a).
+ *   - The dropdown's primary action navigates to the reconnect URL.
+ *
+ * What the handlers add:
+ *   - **Toast**: surfaces the message even when the user isn't looking at the
+ *     bell. The reauth toast is the highest-signal interruption — without
+ *     reauth the channel goes silent.
+ *   - **Event emit**: lets the profile page / channel admin DataTable hook in
+ *     via `useAppEvent(...)` (DOM Event Bridge) so they auto-refresh when the
+ *     state flips without requiring a manual reload.
+ *   - **Refresh notifications**: keeps the bell badge accurate.
+ *
+ * Custom event names emitted here on the DOM Event Bridge. They are published
+ * for any page that opts in via `useAppEvent(...)`; no surface subscribes to
+ * them today (the unified inbox auto-refreshes from the `messages.message.*`
+ * bridge, and the reconnect flow is driven by the bell notification + its
+ * reconnect action). Kept as forward-compatible hooks for future
+ * row-highlight / refetch UX.
+ */
+
+export const CHANNEL_REQUIRES_REAUTH_EVENT = 'om:communication_channels:channel-requires-reauth'
+export const MESSAGE_RECEIVED_EVENT = 'om:communication_channels:message-received'
+
+export const notificationHandlers: NotificationHandler[] = [
+  {
+    id: 'communication_channels.channel-requires-reauth-toast',
+    notificationType: 'communication_channels.channel.requires_reauth',
+    features: ['communication_channels.connect_user_channel'],
+    priority: 110,
+    handle(notification, context) {
+      context.toast({
+        title: notification.title,
+        body: notification.body ?? undefined,
+        severity: 'warning',
+        action: {
+          label:
+            context.t?.(
+              'communication_channels.notifications.channel_requires_reauth.reconnect',
+              'Reconnect',
+            ) ?? 'Reconnect',
+          onClick: () => {
+            const channelId = notification.sourceEntityId
+            const target = channelId
+              ? `/backend/profile/communication-channels?reconnect=${encodeURIComponent(channelId)}`
+              : '/backend/profile/communication-channels'
+            context.navigate(target)
+          },
+        },
+      })
+      context.emitEvent(CHANNEL_REQUIRES_REAUTH_EVENT, {
+        notificationId: notification.id,
+        channelId: notification.sourceEntityId ?? null,
+      })
+      context.refreshNotifications()
+    },
+  },
+  {
+    id: 'communication_channels.message-received-event',
+    notificationType: 'communication_channels.message.received',
+    features: ['communication_channels.view'],
+    priority: 100,
+    handle(notification, context) {
+      // Inbox refresh is the only side effect — the user's bell dropdown already
+      // shows the notification entry. A toast here would be noisy because the
+      // bell badge increments anyway, and inbound email lands in the unified
+      // inbox where the user expects it.
+      context.emitEvent(MESSAGE_RECEIVED_EVENT, {
+        notificationId: notification.id,
+        messageId: notification.sourceEntityId ?? null,
+      })
+    },
+  },
+]
+
+export default notificationHandlers

package/src/modules/communication_channels/notifications.ts

@@ -0,0 +1,52 @@
+import type { NotificationTypeDefinition } from '@open-mercato/shared/modules/notifications/types'
+
+export const notificationTypes: NotificationTypeDefinition[] = [
+  {
+    type: 'communication_channels.message.received',
+    module: 'communication_channels',
+    titleKey: 'communication_channels.notifications.message_received.title',
+    bodyKey: 'communication_channels.notifications.message_received.body',
+    icon: 'message-circle',
+    severity: 'info',
+    actions: [
+      {
+        id: 'view',
+        labelKey: 'common.view',
+        variant: 'outline',
+        href: '/backend/messages/{sourceEntityId}',
+        icon: 'external-link',
+      },
+    ],
+    linkHref: '/backend/messages/{sourceEntityId}',
+    expiresAfterHours: 168, // 7 days
+  },
+  {
+    /**
+     * Channel-agnostic notification raised when an adapter loses authorization
+     * (OAuth refresh token revoked, IMAP/SMTP password rotated, WhatsApp token expired).
+     * Persisted by the `channel-requires-reauth-notification` subscriber in
+     * response to the `communication_channels.channel.requires_reauth` event
+     * (emitted by the poll worker and outbound delivery). Consumed by the email
+     * integration spec's reconnect flow.
+     */
+    type: 'communication_channels.channel.requires_reauth',
+    module: 'communication_channels',
+    titleKey: 'communication_channels.notifications.channel_requires_reauth.title',
+    bodyKey: 'communication_channels.notifications.channel_requires_reauth.body',
+    icon: 'alert-triangle',
+    severity: 'warning',
+    actions: [
+      {
+        id: 'reconnect',
+        labelKey: 'communication_channels.notifications.channel_requires_reauth.reconnect',
+        variant: 'outline',
+        href: '/backend/profile/communication-channels?reconnect={sourceEntityId}',
+        icon: 'refresh-cw',
+      },
+    ],
+    linkHref: '/backend/profile/communication-channels?reconnect={sourceEntityId}',
+    expiresAfterHours: 720, // 30 days — auth issues should be addressed promptly
+  },
+]
+
+export default notificationTypes

package/src/modules/communication_channels/setup.ts

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto'
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import { COMMUNICATION_CHANNELS_QUEUES } from './lib/queue'
+
+type SchedulerServiceLike = {
+  register: (registration: {
+    id: string
+    name: string
+    scopeType: 'system' | 'organization' | 'tenant'
+    organizationId?: string
+    tenantId?: string
+    scheduleType: 'cron' | 'interval'
+    scheduleValue: string
+    timezone?: string
+    targetType: 'queue' | 'command'
+    targetQueue?: string
+    targetPayload?: unknown
+    sourceType?: 'user' | 'module'
+    sourceModule?: string
+    isEnabled?: boolean
+    description?: string
+  }) => Promise<void>
+}
+
+/**
+ * Tick interval in seconds. Default 60s per email integration spec
+ * § Hub Deltas → Delta 6 (scheduler mechanism).
+ */
+const POLL_TICK_INTERVAL_SECONDS = Math.max(
+  10,
+  Number.parseInt(process.env.OM_HUB_POLL_SCHEDULER_TICK_SECONDS ?? '60', 10) || 60,
+)
+
+/**
+ * `scheduled_jobs.id` is a uuid column, so a module-owned schedule's stable
+ * registration key must be hashed into a uuid rather than used verbatim — this
+ * keeps `schedulerService.register()` an idempotent upsert across re-runs of
+ * seedDefaults instead of trying to insert a raw string into the uuid PK.
+ */
+function stableScheduleUuid(stableKey: string): string {
+  const hex = createHash('sha256').update(stableKey).digest('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+function stablePollTickScheduleId(organizationId: string): string {
+  return stableScheduleUuid(`communication_channels:poll-tick:${organizationId}`)
+}
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    superadmin: [
+      'communication_channels.view',
+      'communication_channels.manage',
+      'communication_channels.react',
+      'communication_channels.assign',
+      'communication_channels.connect_user_channel',
+      'communication_channels.admin',
+      'communication_channels.channel.import_history',
+      'communication_channels.channel.push.manage',
+    ],
+    admin: [
+      'communication_channels.view',
+      'communication_channels.manage',
+      'communication_channels.react',
+      'communication_channels.assign',
+      'communication_channels.connect_user_channel',
+      'communication_channels.admin',
+      'communication_channels.channel.import_history',
+      'communication_channels.channel.push.manage',
+    ],
+    manager: [
+      'communication_channels.view',
+      'communication_channels.manage',
+      'communication_channels.react',
+      'communication_channels.assign',
+      'communication_channels.connect_user_channel',
+    ],
+    employee: [
+      'communication_channels.view',
+      'communication_channels.react',
+      'communication_channels.connect_user_channel',
+    ],
+  },
+
+  async seedDefaults({ container, organizationId, tenantId }) {
+    /**
+     * Register the per-channel polling tick with `@open-mercato/scheduler`.
+     *
+     * Per email integration spec § Hub Deltas → Delta 6: every
+     * `POLL_TICK_INTERVAL_SECONDS` (default 60s), enqueue a single
+     * `communication-channels-poll-tick` job that enumerates due channels and
+     * fans out to the `communication-channels-poll` queue.
+     *
+     * The registration is per-organization (one tick row per org/tenant pair)
+     * so multi-tenant deploys schedule independently. Skipped silently when the
+     * scheduler module isn't enabled — keeps the hub usable in scheduler-less
+     * test harnesses.
+     */
+    const cradle = container as { hasRegistration?: (name: string) => boolean }
+    if (typeof cradle.hasRegistration !== 'function' || !cradle.hasRegistration('schedulerService')) {
+      return
+    }
+    const schedulerService = container.resolve('schedulerService') as SchedulerServiceLike
+    // Best-effort: a scheduler failure must not abort tenant initialization for
+    // every other module (mirrors the ai_assistant setup pattern). The schedule
+    // ids are deterministic uuids so re-runs upsert idempotently.
+    try {
+      await schedulerService.register({
+        id: stablePollTickScheduleId(organizationId),
+        name: 'Communication channels poll tick',
+        description:
+          `Enumerates active polling channels every ${POLL_TICK_INTERVAL_SECONDS}s and enqueues per-channel poll jobs.`,
+        scopeType: 'organization',
+        organizationId,
+        tenantId,
+        scheduleType: 'interval',
+        scheduleValue: `${POLL_TICK_INTERVAL_SECONDS}s`,
+        timezone: 'UTC',
+        targetType: 'queue',
+        targetQueue: COMMUNICATION_CHANNELS_QUEUES.pollTick,
+        targetPayload: {
+          scope: { tenantId, organizationId },
+        },
+        sourceType: 'module',
+        sourceModule: 'communication_channels',
+        isEnabled: true,
+      })
+
+      // Spec C § Phase C4 — Gmail watch renewal cron, per-org so multi-tenant
+      // deploys schedule independently.
+      await schedulerService.register({
+        id: stableScheduleUuid(`communication_channels:gmail-renew-watch:${organizationId}`),
+        name: 'Gmail watch renewal',
+        description:
+          'Daily 04:00 UTC. Re-issues gmail.users.watch for channels within OM_PUSH_RENEWAL_GMAIL_LEAD_HOURS of expiry.',
+        scopeType: 'organization',
+        organizationId,
+        tenantId,
+        scheduleType: 'cron',
+        scheduleValue: '0 4 * * *',
+        timezone: 'UTC',
+        targetType: 'queue',
+        targetQueue: COMMUNICATION_CHANNELS_QUEUES.gmailRenewWatch,
+        targetPayload: { scope: { tenantId, organizationId } },
+        sourceType: 'module',
+        sourceModule: 'communication_channels',
+        isEnabled: true,
+      })
+    } catch (error) {
+      console.warn(
+        '[communication_channels] Failed to register module schedules:',
+        error instanceof Error ? error.message : error,
+      )
+    }
+  },
+}
+
+export default setup

package/src/modules/communication_channels/subscribers/channel-requires-reauth-notification.ts

@@ -0,0 +1,118 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CommunicationChannel } from '../data/entities'
+import { notificationTypes } from '../notifications'
+import {
+  buildNotificationFromType,
+  buildFeatureNotificationFromType,
+} from '../../notifications/lib/notificationBuilder'
+import { resolveNotificationService } from '../../notifications/lib/notificationService'
+
+/**
+ * Subscriber: re-authentication notification.
+ *
+ * Listens to `communication_channels.channel.requires_reauth` (emitted by the
+ * poll worker and outbound delivery when an
+ * adapter loses authorization) and raises the in-app
+ * `communication_channels.channel.requires_reauth` notification so the affected
+ * user sees a bell entry + reconnect CTA and the reactive toast handler
+ * (`notifications.handlers.ts`) fires. This is the producer half of the
+ * notification contract declared in `notifications.ts` /
+ * `notifications.client.ts` — without it the notification is never persisted.
+ *
+ * Recipient: per-user channels notify the channel owner (`channel.userId`) — the
+ * only person who can complete their own OAuth/credential reconnect. Tenant-wide
+ * (shared) channels have no owner, so operators holding
+ * `communication_channels.manage` are notified instead.
+ *
+ * Idempotency: `groupKey = channelId` collapses repeated reauth events for the
+ * same channel onto one notification (the notification service dedupes by
+ * tenant/org/recipient/type/groupKey under an advisory lock), so a flapping
+ * channel or a subscriber retry never spams the bell.
+ */
+export const metadata = {
+  event: 'communication_channels.channel.requires_reauth',
+  persistent: true,
+  id: 'communication_channels:channel-requires-reauth-notification',
+}
+
+const NOTIFICATION_TYPE = 'communication_channels.channel.requires_reauth'
+const MANAGE_FEATURE = 'communication_channels.manage'
+
+type RequiresReauthPayload = {
+  channelId?: string
+  providerKey?: string
+  channelType?: string
+  reason?: string
+  tenantId?: string
+  organizationId?: string | null
+}
+
+type SubscriberContext = {
+  resolve: <T = unknown>(name: string) => T
+  container?: { resolve: <T = unknown>(name: string) => T }
+}
+
+function resolveFromCtx<T = unknown>(ctx: SubscriberContext, name: string): T {
+  if (typeof ctx?.resolve === 'function') return ctx.resolve<T>(name)
+  if (ctx?.container && typeof ctx.container.resolve === 'function') {
+    return ctx.container.resolve<T>(name)
+  }
+  throw new Error(
+    `channel-requires-reauth-notification: subscriber context has no resolver (looking for '${name}')`,
+  )
+}
+
+export default async function handler(
+  payload: RequiresReauthPayload,
+  ctx: SubscriberContext,
+): Promise<void> {
+  if (!payload?.channelId || !payload.tenantId) {
+    return
+  }
+
+  const typeDef = notificationTypes.find((type) => type.type === NOTIFICATION_TYPE)
+  if (!typeDef) return
+
+  const scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId ?? null,
+  }
+
+  const em = resolveFromCtx<EntityManager>(ctx, 'em').fork()
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    {
+      id: payload.channelId,
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId ?? null,
+      deletedAt: null,
+    },
+    undefined,
+    scope,
+  )
+  if (!channel) return
+
+  const notificationService = resolveNotificationService(ctx)
+  const common = {
+    sourceEntityType: 'communication_channel',
+    sourceEntityId: payload.channelId,
+    groupKey: payload.channelId,
+  }
+
+  if (channel.userId) {
+    await notificationService.create(
+      buildNotificationFromType(typeDef, { ...common, recipientUserId: channel.userId }),
+      scope,
+    )
+    return
+  }
+
+  // Tenant-wide (shared) channel — no single owner. Notify operators who can
+  // reconnect it on behalf of the tenant.
+  await notificationService.createForFeature(
+    buildFeatureNotificationFromType(typeDef, { ...common, requiredFeature: MANAGE_FEATURE }),
+    scope,
+  )
+}