@open-mercato/core 0.7.1-develop.7149.1.7efa6e1612 → 0.7.1-develop.7151.1.00d0391847

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.7.1-develop.7149.1.7efa6e1612",
+  "version": "0.7.1-develop.7151.1.00d0391847",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -252,16 +252,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.7.1-develop.7149.1.7efa6e1612",
-    "@open-mercato/shared": "0.7.1-develop.7149.1.7efa6e1612",
-    "@open-mercato/ui": "0.7.1-develop.7149.1.7efa6e1612",
+    "@open-mercato/ai-assistant": "0.7.1-develop.7151.1.00d0391847",
+    "@open-mercato/shared": "0.7.1-develop.7151.1.00d0391847",
+    "@open-mercato/ui": "0.7.1-develop.7151.1.00d0391847",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.7.1-develop.7149.1.7efa6e1612",
-    "@open-mercato/shared": "0.7.1-develop.7149.1.7efa6e1612",
-    "@open-mercato/ui": "0.7.1-develop.7149.1.7efa6e1612",
+    "@open-mercato/ai-assistant": "0.7.1-develop.7151.1.00d0391847",
+    "@open-mercato/shared": "0.7.1-develop.7151.1.00d0391847",
+    "@open-mercato/ui": "0.7.1-develop.7151.1.00d0391847",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.1",

package/src/helpers/integration/communicationChannelsFixtures.ts

@@ -16,8 +16,39 @@ export type SeedAddressField =
   | { address: string; name?: string }
   | Array<string | { address: string; name?: string }>;
 
+export type CapturedTestSeedEmail = {
+  capturedAt: string;
+  externalMessageId: string;
+  conversationId?: string;
+  content: {
+    text?: string;
+    html?: string;
+    bodyFormat?: 'text' | 'markdown' | 'html';
+    attachments?: Array<{ url: string; mimeType: string; fileName: string; fileSize?: number; inline?: boolean }>;
+    raw?: Record<string, unknown>;
+  };
+  credentials: Record<string, unknown>;
+  scope: {
+    tenantId: string;
+    organizationId: string;
+  };
+  metadata?: Record<string, unknown>;
+};
+
 const TEST_SEED_PATH = '/api/communication_channels/test-seed';
 
+function resolveSystemCaptureCredentials(): {
+  accessToken: string;
+  captureCorrelationToken: string;
+} {
+  const accessToken = process.env.OM_TEST_EMAIL_CAPTURE_ACCESS_TOKEN?.trim();
+  const captureCorrelationToken = process.env.OM_TEST_EMAIL_CAPTURE_CORRELATION_TOKEN?.trim();
+  if (!accessToken || !captureCorrelationToken) {
+    throw new Error('[internal] System email capture credentials are not configured by the integration harness');
+  }
+  return { accessToken, captureCorrelationToken };
+}
+
 /**
  * Probe whether the env-gated test-seed endpoint is enabled in the target app.
  * Returns false when the route answers 404 (flag off) so callers can `test.skip`.
@@ -80,6 +111,104 @@ export async function seedConnectedChannel(
   return expectId(body?.channelId, 'connect-channel response should include channelId');
 }
 
+export async function seedSystemEmailChannel(
+  request: APIRequestContext,
+  token: string,
+  input: { displayName?: string; externalIdentifier?: string } = {},
+): Promise<string> {
+  const response = await apiRequest(request, 'POST', TEST_SEED_PATH, {
+    token,
+    data: { action: 'seed-system-channel', ...input },
+  });
+  expect(
+    response.status(),
+    'POST /api/communication_channels/test-seed (seed-system-channel) should return 201',
+  ).toBe(201);
+  const body = await readJsonSafe<{ channelId?: string }>(response);
+  return expectId(body?.channelId, 'seed-system-channel response should include channelId');
+}
+
+export async function clearCapturedSystemEmails(
+  request: APIRequestContext,
+  token: string,
+  options: { systemRecipient?: string } = {},
+): Promise<void> {
+  const captureCredentials = options.systemRecipient ? resolveSystemCaptureCredentials() : null;
+  const response = await apiRequest(request, 'POST', TEST_SEED_PATH, {
+    token,
+    data: {
+      action: 'clear-capture',
+      ...options,
+      ...(captureCredentials
+        ? { captureCorrelationToken: captureCredentials.captureCorrelationToken }
+        : {}),
+    },
+    headers: captureCredentials
+      ? { 'x-om-test-email-capture-access-token': captureCredentials.accessToken }
+      : undefined,
+  });
+  expect(response.ok(), 'POST /api/communication_channels/test-seed (clear-capture) should succeed').toBeTruthy();
+}
+
+export async function listCapturedSystemEmails(
+  request: APIRequestContext,
+  token: string,
+  options: { systemRecipient?: string } = {},
+): Promise<CapturedTestSeedEmail[]> {
+  const captureCredentials = options.systemRecipient ? resolveSystemCaptureCredentials() : null;
+  const response = await apiRequest(request, 'POST', TEST_SEED_PATH, {
+    token,
+    data: {
+      action: 'list-capture',
+      ...options,
+      ...(captureCredentials
+        ? { captureCorrelationToken: captureCredentials.captureCorrelationToken }
+        : {}),
+    },
+    headers: captureCredentials
+      ? { 'x-om-test-email-capture-access-token': captureCredentials.accessToken }
+      : undefined,
+  });
+  expect(response.ok(), 'POST /api/communication_channels/test-seed (list-capture) should succeed').toBeTruthy();
+  const body = await readJsonSafe<{ items?: CapturedTestSeedEmail[] }>(response);
+  return Array.isArray(body?.items) ? body.items : [];
+}
+
+export async function waitForCapturedSystemEmail(
+  request: APIRequestContext,
+  token: string,
+  predicate: (email: CapturedTestSeedEmail) => boolean,
+  options: {
+    timeoutMs?: number;
+    intervalMs?: number;
+    description?: string;
+    systemRecipient?: string;
+  } = {},
+): Promise<CapturedTestSeedEmail> {
+  const timeoutMs = options.timeoutMs ?? 20_000;
+  const intervalMs = options.intervalMs ?? 1_000;
+  const deadline = Date.now() + timeoutMs;
+  let lastItems: CapturedTestSeedEmail[] = [];
+  while (Date.now() < deadline) {
+    lastItems = await listCapturedSystemEmails(request, token, {
+      systemRecipient: options.systemRecipient,
+    });
+    const found = lastItems.find(predicate);
+    if (found) return found;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  const summary = lastItems.map((item) => ({
+    to: item.metadata?.to,
+    from: item.metadata?.from,
+    subject: item.metadata?.subject,
+    scope: item.scope,
+    bodyFormat: item.content?.bodyFormat,
+  }));
+  throw new Error(
+    `Timed out waiting for captured system email${options.description ? `: ${options.description}` : ''}. Captured ${lastItems.length} message(s): ${JSON.stringify(summary)}`,
+  );
+}
+
 /**
  * Seed an inbound `MessageChannelLink` for `channelId` and emit
  * `communication_channels.message.received` through the real event bus. The

package/src/helpers/integration/crmFixtures.ts

@@ -55,7 +55,7 @@ export async function createCompanyFixture(
 export async function createPersonFixture(
   request: APIRequestContext,
   token: string,
-  input: { firstName: string; lastName: string; displayName: string; companyEntityId?: string },
+  input: { firstName: string; lastName: string; displayName: string; companyEntityId?: string; primaryEmail?: string },
 ): Promise<string> {
   const data: Record<string, unknown> = {
     firstName: input.firstName,
@@ -65,6 +65,9 @@ export async function createPersonFixture(
   if (input.companyEntityId) {
     data.companyEntityId = input.companyEntityId;
   }
+  if (input.primaryEmail) {
+    data.primaryEmail = input.primaryEmail;
+  }
   return createEntity(request, token, '/api/customers/people', data, ['id', 'entityId', 'personId']);
 }
 

package/src/modules/auth/api/reset.ts

@@ -76,7 +76,13 @@ export async function POST(req: Request) {
   }
 
   try {
-    await sendEmail({ to: user.email, subject, react: ResetPasswordEmail({ resetUrl, copy }) })
+    await sendEmail({
+      to: user.email,
+      subject,
+      react: ResetPasswordEmail({ resetUrl, copy }),
+      tenantId: user.tenantId ? String(user.tenantId) : undefined,
+      organizationId: user.organizationId ? String(user.organizationId) : null,
+    })
   } catch (err) {
     logger.error('Failed to send reset email', { err })
   }

package/src/modules/auth/api/users/resend-invite/route.ts

@@ -175,7 +175,13 @@ export async function POST(req: Request) {
 
   let emailSent = true
   try {
-    await sendEmail({ to: user.email, subject, react: InviteUserEmail({ inviteUrl, copy }) })
+    await sendEmail({
+      to: user.email,
+      subject,
+      react: InviteUserEmail({ inviteUrl, copy }),
+      tenantId: user.tenantId ? String(user.tenantId) : auth.tenantId ?? undefined,
+      organizationId: user.organizationId ? String(user.organizationId) : null,
+    })
   } catch (err) {
     logger.error('Failed to send invitation email', { err })
     emailSent = false

package/src/modules/auth/commands/users.ts

@@ -504,7 +504,13 @@ async function sendInviteToUser(
 
   let emailSent = true
   try {
-    await sendEmail({ to: user.email, subject, react: InviteUserEmail({ inviteUrl, copy }) })
+    await sendEmail({
+      to: user.email,
+      subject,
+      react: InviteUserEmail({ inviteUrl, copy }),
+      tenantId: user.tenantId ? String(user.tenantId) : undefined,
+      organizationId: user.organizationId ? String(user.organizationId) : null,
+    })
   } catch (err) {
     logger.error('Failed to send invitation email', { err })
     emailSent = false

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

@@ -66,6 +66,10 @@
   "auth.acl.features.channel_gmail.view": "View Gmail channel configuration",
   "auth.acl.features.channel_imap.configure": "Configure IMAP channel defaults",
   "auth.acl.features.channel_imap.view": "View IMAP channel configuration",
+  "auth.acl.features.channel_resend.configure": "Configure Resend channel defaults",
+  "auth.acl.features.channel_resend.view": "View Resend channel configuration",
+  "auth.acl.features.channel_ses.configure": "Configure Amazon SES channel defaults",
+  "auth.acl.features.channel_ses.view": "View Amazon SES channel configuration",
   "auth.acl.features.checkout.create": "Create checkout links and templates",
   "auth.acl.features.checkout.delete": "Delete checkout links and templates",
   "auth.acl.features.checkout.edit": "Edit checkout links and templates",

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

@@ -66,6 +66,10 @@
   "auth.acl.features.channel_gmail.view": "View Gmail channel configuration",
   "auth.acl.features.channel_imap.configure": "Configure IMAP channel defaults",
   "auth.acl.features.channel_imap.view": "View IMAP channel configuration",
+  "auth.acl.features.channel_resend.configure": "Configure Resend channel defaults",
+  "auth.acl.features.channel_resend.view": "View Resend channel configuration",
+  "auth.acl.features.channel_ses.configure": "Configure Amazon SES channel defaults",
+  "auth.acl.features.channel_ses.view": "View Amazon SES channel configuration",
   "auth.acl.features.checkout.create": "Create checkout links and templates",
   "auth.acl.features.checkout.delete": "Delete checkout links and templates",
   "auth.acl.features.checkout.edit": "Edit checkout links and templates",

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

@@ -66,6 +66,10 @@
   "auth.acl.features.channel_gmail.view": "View Gmail channel configuration",
   "auth.acl.features.channel_imap.configure": "Configure IMAP channel defaults",
   "auth.acl.features.channel_imap.view": "View IMAP channel configuration",
+  "auth.acl.features.channel_resend.configure": "Configure Resend channel defaults",
+  "auth.acl.features.channel_resend.view": "View Resend channel configuration",
+  "auth.acl.features.channel_ses.configure": "Configure Amazon SES channel defaults",
+  "auth.acl.features.channel_ses.view": "View Amazon SES channel configuration",
   "auth.acl.features.checkout.create": "Create checkout links and templates",
   "auth.acl.features.checkout.delete": "Delete checkout links and templates",
   "auth.acl.features.checkout.edit": "Edit checkout links and templates",

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

@@ -66,6 +66,10 @@
   "auth.acl.features.channel_gmail.view": "View Gmail channel configuration",
   "auth.acl.features.channel_imap.configure": "Configure IMAP channel defaults",
   "auth.acl.features.channel_imap.view": "View IMAP channel configuration",
+  "auth.acl.features.channel_resend.configure": "Configure Resend channel defaults",
+  "auth.acl.features.channel_resend.view": "View Resend channel configuration",
+  "auth.acl.features.channel_ses.configure": "Configure Amazon SES channel defaults",
+  "auth.acl.features.channel_ses.view": "View Amazon SES channel configuration",
   "auth.acl.features.checkout.create": "Create checkout links and templates",
   "auth.acl.features.checkout.delete": "Delete checkout links and templates",
   "auth.acl.features.checkout.edit": "Edit checkout links and templates",

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

@@ -66,6 +66,10 @@
   "auth.acl.features.channel_gmail.view": "Wyświetl konfigurację kanału Gmail",
   "auth.acl.features.channel_imap.configure": "Konfiguruj domyślne ustawienia kanału IMAP",
   "auth.acl.features.channel_imap.view": "Wyświetl konfigurację kanału IMAP",
+  "auth.acl.features.channel_resend.configure": "Konfiguruj domyślne ustawienia kanału Resend",
+  "auth.acl.features.channel_resend.view": "Wyświetl konfigurację kanału Resend",
+  "auth.acl.features.channel_ses.configure": "Konfiguruj domyślne ustawienia kanału Amazon SES",
+  "auth.acl.features.channel_ses.view": "Wyświetl konfigurację kanału Amazon SES",
   "auth.acl.features.checkout.create": "Twórz linki i szablony płatności",
   "auth.acl.features.checkout.delete": "Usuwaj linki i szablony płatności",
   "auth.acl.features.checkout.edit": "Edytuj linki i szablony płatności",

package/src/modules/communication_channels/api/post/test-seed/route.ts

@@ -22,8 +22,12 @@ import { emitCommunicationChannelsEvent } from '../../../events'
 import {
   TEST_SEED_CHAT_PROVIDER_KEY,
   TEST_SEED_PROVIDER_KEY,
+  clearTestSeedCapturedMessages,
+  createTestSeedPlatformMessage,
   ensureTestSeedAdapterRegistered,
+  isTestEmailCaptureAccessAuthorized,
   isTestChannelSeedingEnabled,
+  listTestSeedCapturedMessages,
 } from '../../../lib/test-seed'
 import {
   COMMUNICATION_CHANNELS_INGEST_INBOUND_COMMAND_ID,
@@ -135,6 +139,24 @@ const ingestInboundSchema = z.object({
   externalConversationId: z.string().min(1).max(255),
 })
 
+const seedSystemChannelSchema = z.object({
+  action: z.literal('seed-system-channel'),
+  displayName: z.string().min(1).max(255).optional(),
+  externalIdentifier: z.string().min(1).max(255).optional(),
+})
+
+const clearCaptureSchema = z.object({
+  action: z.literal('clear-capture'),
+  systemRecipient: z.string().email().max(320).optional(),
+  captureCorrelationToken: z.string().min(32).max(512).optional(),
+})
+
+const listCaptureSchema = z.object({
+  action: z.literal('list-capture'),
+  systemRecipient: z.string().email().max(320).optional(),
+  captureCorrelationToken: z.string().min(32).max(512).optional(),
+})
+
 const emitInboundSchema = z.object({
   action: z.literal('emit-inbound'),
   /** Channel that owns the inbound message; controls authorUserId + default visibility. */
@@ -172,6 +194,9 @@ const bodySchema = z.discriminatedUnion('action', [
   connectChannelSchema,
   ingestInboundSchema,
   emitInboundSchema,
+  seedSystemChannelSchema,
+  clearCaptureSchema,
+  listCaptureSchema,
 ])
 
 export async function POST(req: Request): Promise<Response> {
@@ -196,14 +221,97 @@ export async function POST(req: Request): Promise<Response> {
     )
   }
 
+  const tenantId = auth.tenantId as string
+  const organizationId = (auth as { orgId?: string | null }).orgId ?? null
+  const userId = auth.sub as string
+  const captureScope = { tenantId, organizationId }
+
+  if (
+    (body.action === 'clear-capture' || body.action === 'list-capture')
+    && body.systemRecipient
+    && (
+      !body.captureCorrelationToken
+      || !isTestEmailCaptureAccessAuthorized(req.headers.get('x-om-test-email-capture-access-token'))
+    )
+  ) {
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
+  }
+
+  if (body.action === 'clear-capture') {
+    await clearTestSeedCapturedMessages(captureScope, {
+      systemRecipient: body.systemRecipient,
+      captureCorrelationToken: body.captureCorrelationToken,
+    })
+    return NextResponse.json({ ok: true })
+  }
+
+  if (body.action === 'list-capture') {
+    return NextResponse.json({
+      items: (await listTestSeedCapturedMessages(captureScope, {
+        systemRecipient: body.systemRecipient,
+        captureCorrelationToken: body.captureCorrelationToken,
+      })).map(({ captureCorrelationToken: _captureCorrelationToken, ...message }) => message),
+    })
+  }
+
   const container = await createRequestContainer()
   // Defensive: make sure the stub adapter is registered for this process even if
   // a worker-only node skipped module di registration.
   ensureTestSeedAdapterRegistered()
 
-  const tenantId = auth.tenantId as string
-  const organizationId = (auth as { orgId?: string | null }).orgId ?? null
-  const userId = auth.sub as string
+  if (body.action === 'seed-system-channel') {
+    const em = (container.resolve('em') as EntityManager).fork()
+    const credentialsService = container.resolve('integrationCredentialsService') as {
+      save: (
+        integrationId: string,
+        credentials: Record<string, unknown>,
+        scope: { organizationId: string; tenantId: string; userId?: string | null },
+      ) => Promise<void>
+    }
+    await credentialsService.save(
+      `channel_${TEST_SEED_PROVIDER_KEY}`,
+      { testSeed: true },
+      { tenantId, organizationId: organizationId ?? tenantId, userId: null },
+    )
+    let channel = await findOneWithDecryption(
+      em,
+      CommunicationChannel,
+      {
+        providerKey: TEST_SEED_PROVIDER_KEY,
+        channelType: 'email',
+        tenantId,
+        organizationId,
+        userId: null,
+        deletedAt: null,
+      },
+      undefined,
+      { tenantId, organizationId },
+    )
+    if (!channel) {
+      const stamp = Date.now()
+      channel = em.create(CommunicationChannel, {
+        providerKey: TEST_SEED_PROVIDER_KEY,
+        channelType: 'email',
+        displayName: body.displayName ?? `Test Seed System Email ${stamp}`,
+        externalIdentifier: body.externalIdentifier ?? `system-${stamp}@test-seed.local`,
+        userId: null,
+        isPrimary: false,
+        isActive: true,
+        status: 'connected',
+        tenantId,
+        organizationId,
+      })
+      em.persist(channel)
+      await em.flush()
+    } else if (!channel.isActive || channel.status !== 'connected') {
+      channel.isActive = true
+      channel.status = 'connected'
+      channel.lastError = null
+      await em.flush()
+    }
+
+    return NextResponse.json({ channelId: channel.id }, { status: 201 })
+  }
 
   if (body.action === 'connect-channel') {
     const stamp = Date.now()
@@ -424,32 +532,16 @@ export async function POST(req: Request): Promise<Response> {
   em.persist(conversation)
   await em.flush()
 
-  // Insert the platform `messages.message` row via raw SQL rather than importing
-  // the messages module's entity class (cross-module ORM coupling rule). Only
-  // `thread_id` matters for the hub-thread inheritance join (TC-CRM-EMAIL-005);
-  // the rest satisfy NOT NULL constraints.
-  const messageRows = (await em.getConnection().execute(
-    `INSERT INTO messages
-       (type, thread_id, sender_user_id, subject, body, body_format, priority, status,
-        is_draft, sent_at, visibility, source_entity_type, source_entity_id,
-        tenant_id, organization_id, created_at, updated_at)
-     VALUES
-       (?, ?, ?, ?, ?, 'text', 'normal', 'sent',
-        false, now(), 'public', 'communication_channels.test_seed_inbound', ?,
-        ?, ?, now(), now())
-     RETURNING id`,
-    [
-      `channel.${providerKey}`,
-      body.messageThreadId ?? null,
-      userId,
-      body.subject ?? '(no subject)',
-      body.bodyText ?? '',
-      body.channelId,
-      tenantId,
-      organizationId,
-    ],
-  )) as Array<{ id: string }>
-  const messageId = messageRows[0]?.id
+  const messageId = await createTestSeedPlatformMessage(em, {
+    providerKey,
+    threadId: body.messageThreadId,
+    senderUserId: userId,
+    subject: body.subject,
+    bodyText: body.bodyText,
+    channelId: body.channelId,
+    tenantId,
+    organizationId,
+  })
   if (!messageId) {
     return NextResponse.json({ error: '[internal] failed to seed message row' }, { status: 500 })
   }

package/src/modules/communication_channels/di.ts

@@ -1,5 +1,6 @@
 import { asValue } from 'awilix'
 import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { registerEmailTransport } from '@open-mercato/shared/lib/email/transport'
 import {
   CommunicationChannel,
   ExternalConversation,
@@ -11,6 +12,7 @@ import {
 import { getChannelAdapterRegistry } from './lib/adapter-registry-singleton'
 import { ensureTestSeedAdapterRegistered } from './lib/test-seed'
 import { sendAsUser } from './lib/send-as-user'
+import { isSystemEmailTransportConfigured, sendSystemEmail } from './lib/system-email'
 import { resolveChannelTypeSafely } from './lib/resolve-channel-type'
 
 export function register(container: AppContainer) {
@@ -19,6 +21,11 @@ export function register(container: AppContainer) {
   // integration harness connect a channel + complete the outbound send chain.
   // See lib/test-seed.ts.
   ensureTestSeedAdapterRegistered()
+  registerEmailTransport({
+    id: 'communication_channels',
+    send: (payload) => sendSystemEmail(container, payload),
+    isConfigured: isSystemEmailTransportConfigured,
+  })
 
   container.register({
     // Entity class registrations (for EntityManager lookups by string)
@@ -37,6 +44,7 @@ export function register(container: AppContainer) {
     // In-process send-as-user facade. Cross-module callers (e.g. the customers
     // compose route) resolve this instead of making an HTTP self-call.
     communicationChannelsSendAsUser: asValue(sendAsUser),
+    communicationChannelsSendSystemEmail: asValue(sendSystemEmail),
 
     // Cross-module channel-type lookup. The messages compose route resolves this
     // to decide whether an external correspondent must carry an email address

package/src/modules/communication_channels/lib/ensure-system-email-channel.ts

@@ -0,0 +1,85 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CommunicationChannel } from '../data/entities'
+
+const logger = createLogger('communication_channels')
+
+export type EnsureSystemEmailChannelInput = {
+  tenantId: string
+  organizationId: string
+  providerKey: string
+  externalIdentifier: string
+  displayName?: string
+  capabilities?: Record<string, unknown>
+}
+
+export type EnsureSystemEmailChannelResult = 'created' | 'updated' | 'failed'
+
+/**
+ * Idempotently create or refresh a tenant's system email channel row.
+ *
+ * Shared by the two places that need the same row: the provider env preset, which runs at tenant setup
+ * and again on every `yarn mercato seed:defaults --module channel_<provider>` used to migrate tenants
+ * that predate the Communications Hub, and the lazy repair in `sendSystemEmail` for a tenant whose
+ * credentials were saved through the integrations admin UI (which stores credentials but has no hook
+ * to create the channel).
+ *
+ * Never throws: a channel row is a convenience for the Hub UI and for later lookups, so a failure to
+ * write one must not take down the caller — an email send in particular still has usable credentials.
+ */
+export async function ensureSystemEmailChannel(
+  em: EntityManager,
+  input: EnsureSystemEmailChannelInput,
+): Promise<EnsureSystemEmailChannelResult> {
+  const { tenantId, organizationId, providerKey, externalIdentifier } = input
+  const displayName = input.displayName ?? `${providerKey} system email`
+  const dscope = { tenantId, organizationId }
+
+  try {
+    const existing = await findOneWithDecryption(
+      em,
+      CommunicationChannel,
+      {
+        providerKey,
+        channelType: 'email',
+        tenantId,
+        organizationId,
+        userId: null,
+        deletedAt: null,
+      },
+      undefined,
+      dscope,
+    )
+
+    if (existing) {
+      existing.displayName = displayName
+      existing.externalIdentifier = externalIdentifier
+      if (input.capabilities) existing.capabilities = { ...input.capabilities }
+      existing.isActive = true
+      existing.status = 'connected'
+      existing.lastError = null
+      await em.flush()
+      return 'updated'
+    }
+
+    const channel = em.create(CommunicationChannel, {
+      providerKey,
+      channelType: 'email',
+      displayName,
+      externalIdentifier,
+      capabilities: { ...(input.capabilities ?? {}) },
+      isActive: true,
+      status: 'connected',
+      userId: null,
+      pollIntervalSeconds: null,
+      tenantId,
+      organizationId,
+    })
+    await em.persist(channel).flush()
+    return 'created'
+  } catch (err) {
+    logger.warn('Could not ensure system email channel', { err, tenantId, providerKey })
+    return 'failed'
+  }
+}