@open-mercato/core 0.7.1-develop.7150.1.c1941e0c22 → 0.7.1-develop.7151.1.00d0391847

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'
+  }
+}

package/src/modules/communication_channels/lib/system-email-provider-config.ts

@@ -0,0 +1,62 @@
+import { normalizeEnvString } from '@open-mercato/shared/lib/email/config'
+
+type SystemEmailProviderConfigContext = {
+  fromAddress: string
+}
+
+export const DEFAULT_SYSTEM_EMAIL_PROVIDER = 'resend'
+
+/**
+ * The provider key `sendSystemEmail` resolves channels and credentials against.
+ *
+ * Lives here rather than in `system-email.ts` so a provider package's `setup.ts` can read it without
+ * importing the send path — that module pulls the ORM and the React renderer in behind it, and a
+ * preset that runs at tenant seeding has no business loading either.
+ */
+export function resolveSystemEmailProvider(): string {
+  return normalizeEnvString(process.env.SYSTEM_EMAIL_PROVIDER) ?? DEFAULT_SYSTEM_EMAIL_PROVIDER
+}
+
+/**
+ * Whether a provider package's env preset should seed anything for this instance.
+ *
+ * Only the selected provider seeds. Without this gate a preset fires off whatever env variables
+ * happen to be present, and `AWS_REGION` in particular is a general-purpose variable this repo
+ * already ships uncommented for vector search — so an instance sending through Resend would get an
+ * `isEnabled: true` SES integration and a `status: 'connected'` SES channel it never configured.
+ */
+export function isSelectedSystemEmailProvider(providerKey: string): boolean {
+  return resolveSystemEmailProvider() === providerKey
+}
+
+export type SystemEmailProviderConfigResolver = {
+  providerKey: string
+  isConfigured: () => boolean
+  resolveCredentials: (ctx: SystemEmailProviderConfigContext) => Record<string, unknown>
+}
+
+const SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY = Symbol.for(
+  'open-mercato.communication-channels.system-email-provider-config',
+)
+
+type RegistryGlobal = typeof globalThis & {
+  [SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY]?: Map<string, SystemEmailProviderConfigResolver>
+}
+
+function getRegistry(): Map<string, SystemEmailProviderConfigResolver> {
+  const root = globalThis as RegistryGlobal
+  if (!root[SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY]) {
+    root[SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY] = new Map()
+  }
+  return root[SYSTEM_EMAIL_PROVIDER_CONFIG_REGISTRY]
+}
+
+export function registerSystemEmailProviderConfigResolver(resolver: SystemEmailProviderConfigResolver): void {
+  getRegistry().set(resolver.providerKey, resolver)
+}
+
+export function getSystemEmailProviderConfigResolver(
+  providerKey: string,
+): SystemEmailProviderConfigResolver | undefined {
+  return getRegistry().get(providerKey)
+}

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

@@ -0,0 +1,316 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { ResolvedEmailPayload } from '@open-mercato/shared/lib/email/send'
+import { normalizeEnvString } from '@open-mercato/shared/lib/email/config'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { ChannelAdapterRegistry } from './registry'
+import { htmlToText } from './email-mime'
+import {
+  DEFAULT_SYSTEM_EMAIL_PROVIDER,
+  getSystemEmailProviderConfigResolver,
+  resolveSystemEmailProvider,
+} from './system-email-provider-config'
+import { isTestChannelSeedingEnabled, TEST_SEED_PROVIDER_KEY } from './test-seed'
+import { ensureSystemEmailChannel } from './ensure-system-email-channel'
+import { CommunicationChannel } from '../data/entities'
+
+export { DEFAULT_SYSTEM_EMAIL_PROVIDER }
+
+const logger = createLogger('communication_channels')
+
+type CredentialsServiceLike = {
+  resolve: (
+    integrationId: string,
+    scope: { organizationId: string; tenantId: string; userId?: string | null },
+  ) => Promise<Record<string, unknown> | null>
+}
+
+type ResolvedSystemEmailChannel = Pick<CommunicationChannel, 'providerKey' | 'channelType' | 'organizationId'>
+
+/**
+ * Outcome of resolving which channel a system email should go out through.
+ *
+ * `hasTenantChannel` drives the credential posture and is the whole point of the split: a tenant that
+ * has an explicitly configured Hub channel MUST fail closed when its credentials are missing (never
+ * silently borrow the instance-wide env key), while a tenant with no channel at all is an instance
+ * that simply has not been migrated onto the Communications Hub yet and MUST keep working off env.
+ */
+type ResolvedSystemEmailTarget = {
+  channel: ResolvedSystemEmailChannel
+  hasTenantChannel: boolean
+}
+
+export function isSystemEmailTransportConfigured(): boolean {
+  return getSystemEmailProviderConfigResolver(resolveSystemEmailProvider())?.isConfigured() ?? false
+}
+
+async function renderReactEmail(react: ResolvedEmailPayload['react']): Promise<string | undefined> {
+  if (!react) return undefined
+  const { renderToStaticMarkup } = await import('react-dom/server')
+  const markup = renderToStaticMarkup(react)
+  return markup.startsWith('<!doctype html>') || markup.startsWith('<!DOCTYPE html>')
+    ? markup
+    : `<!doctype html>${markup}`
+}
+
+async function resolveEmailBody(payload: ResolvedEmailPayload): Promise<{
+  html?: string
+  text?: string
+  body: string
+  bodyFormat: 'text' | 'html'
+}> {
+  const html = payload.html ?? (await renderReactEmail(payload.react))
+  const text = payload.text ?? (html ? htmlToText(html) : undefined)
+  if (html) return { html, text, body: html, bodyFormat: 'html' }
+  if (text) return { text, body: text, bodyFormat: 'text' }
+  throw new Error('EMAIL_BODY_NOT_CONFIGURED: provide react, html, or text')
+}
+
+/**
+ * Locate the tenant's system email channel.
+ *
+ * Two probes, both inside the caller's own scope: the caller's organization first, then the
+ * organization-agnostic (`organization_id IS NULL`) row that represents a genuinely tenant-wide
+ * channel. A channel belonging to a *different* organization is deliberately never used — organization
+ * is a scoping boundary, and borrowing another organization's channel would send through credentials
+ * that organization owns. A caller whose organization has no channel falls through to the
+ * instance-wide environment credentials instead, which cross no boundary at all.
+ */
+async function findTenantSystemEmailChannel(
+  em: EntityManager,
+  payload: ResolvedEmailPayload,
+  providerKey: string,
+): Promise<CommunicationChannel | null> {
+  const tenantId = payload.tenantId as string
+  const dscope = { tenantId, organizationId: payload.organizationId ?? null }
+  const base = {
+    providerKey,
+    channelType: 'email',
+    tenantId,
+    userId: null,
+    deletedAt: null,
+  }
+
+  const organizationScopes: Array<string | null> = [payload.organizationId ?? null]
+  if (payload.organizationId) organizationScopes.push(null)
+
+  for (const organizationId of organizationScopes) {
+    const found = await findOneWithDecryption(
+      em,
+      CommunicationChannel,
+      { ...base, organizationId },
+      undefined,
+      dscope,
+    )
+    if (found) return found
+  }
+  return null
+}
+
+async function resolveSystemEmailChannel(
+  em: EntityManager,
+  payload: ResolvedEmailPayload,
+): Promise<ResolvedSystemEmailTarget> {
+  const providerKey = resolveSystemEmailProvider()
+  const envTarget: ResolvedSystemEmailTarget = {
+    channel: {
+      providerKey,
+      channelType: 'email',
+      organizationId: payload.organizationId ?? null,
+    },
+    hasTenantChannel: false,
+  }
+
+  if (!payload.tenantId) {
+    return { ...envTarget, channel: { ...envTarget.channel, organizationId: null } }
+  }
+
+  const dscope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId ?? null,
+  }
+  const explicitChannelId = normalizeEnvString(process.env.SYSTEM_EMAIL_CHANNEL_ID)
+
+  // An operator who pinned SYSTEM_EMAIL_CHANNEL_ID asked for exactly one channel. Honour that
+  // literally and never widen the search or fall back to env — a silent substitution would send
+  // through a provider the operator deliberately did not choose.
+  //
+  // The pin narrows the search; it does not lift the organization boundary. A pinned id is accepted
+  // only when the row is the caller's own organization or the tenant-wide (`organization_id IS NULL`)
+  // one the setting is documented to name. Matching on the id alone would let a pin aimed at one
+  // organization's channel send every other organization's mail through credentials that
+  // organization owns — the same borrowing `findTenantSystemEmailChannel` refuses.
+  const channel = explicitChannelId
+    ? await findOneWithDecryption(
+        em,
+        CommunicationChannel,
+        {
+          id: explicitChannelId,
+          channelType: 'email',
+          tenantId: payload.tenantId,
+          userId: null,
+          deletedAt: null,
+          $or: [{ organizationId: payload.organizationId ?? null }, { organizationId: null }],
+        },
+        undefined,
+        dscope,
+      )
+    : await findTenantSystemEmailChannel(em, payload, providerKey)
+
+  if (channel) {
+    if (!channel.isActive || channel.status !== 'connected') {
+      throw new Error(`SYSTEM_EMAIL_CHANNEL_UNAVAILABLE: channel is ${channel.status}`)
+    }
+    return { channel, hasTenantChannel: true }
+  }
+
+  if (explicitChannelId) {
+    throw new Error(
+      `SYSTEM_EMAIL_CHANNEL_NOT_CONFIGURED: SYSTEM_EMAIL_CHANNEL_ID '${explicitChannelId}' matches no active channel this organization may use`,
+    )
+  }
+
+  if (isTestChannelSeedingEnabled() && providerKey === TEST_SEED_PROVIDER_KEY) {
+    return {
+      channel: { providerKey: TEST_SEED_PROVIDER_KEY, channelType: 'email', organizationId: payload.organizationId ?? null },
+      hasTenantChannel: false,
+    }
+  }
+
+  // No channel row for this tenant. This is the ordinary state of an instance that upgraded into the
+  // Communications Hub: tenants predate the feature, so nothing ever seeded a channel for them.
+  // Do not decide here — `sendSystemEmail` still has to check whether the tenant configured the
+  // provider through the integrations UI before it considers the instance-wide env credentials.
+  return envTarget
+}
+
+function resolveEnvCredentials(providerKey: string, fromAddress: string): Record<string, unknown> {
+  return getSystemEmailProviderConfigResolver(providerKey)?.resolveCredentials({ fromAddress }) ?? { fromAddress }
+}
+
+/**
+ * Decide which credentials a tenant-scoped send uses.
+ *
+ * Three cases, in priority order:
+ *
+ * 1. The tenant has credentials stored for the provider (seeded, or saved through
+ *    `/backend/integrations/channel_<provider>`) — always win. When no Hub channel row exists yet we
+ *    also create one, so configuring the integration in the admin UI produces a usable channel
+ *    instead of credentials nothing reads.
+ * 2. The tenant has a configured channel but no credentials — **fail closed**. Borrowing the
+ *    instance key here would send a tenant's mail through a provider account it did not choose.
+ * 3. The tenant has neither — fall back to the instance-wide env credentials. This is the pre-Hub
+ *    behaviour and the upgrade path: env credentials are instance-wide by definition, so this leaks
+ *    nothing across tenants, and without it every tenant that predates the Hub loses all mail.
+ */
+async function resolveTenantCredentials(
+  container: AppContainer,
+  em: EntityManager,
+  payload: ResolvedEmailPayload,
+  channel: ResolvedSystemEmailChannel,
+  hasTenantChannel: boolean,
+): Promise<Record<string, unknown>> {
+  const tenantId = payload.tenantId as string
+  const organizationId = channel.organizationId ?? payload.organizationId ?? tenantId
+  const credentialsService = container.resolve('integrationCredentialsService') as CredentialsServiceLike
+  const resolvedCredentials = await credentialsService.resolve(`channel_${channel.providerKey}`, {
+    tenantId,
+    organizationId,
+    userId: null,
+  })
+
+  if (resolvedCredentials) {
+    if (!hasTenantChannel) {
+      await ensureSystemEmailChannel(em, {
+        tenantId,
+        organizationId,
+        providerKey: channel.providerKey,
+        externalIdentifier: typeof resolvedCredentials.fromAddress === 'string' ? resolvedCredentials.fromAddress : payload.from,
+      })
+    }
+    return resolvedCredentials
+  }
+
+  if (hasTenantChannel) {
+    throw new Error(
+      `SYSTEM_EMAIL_CREDENTIALS_NOT_CONFIGURED: configure tenant credentials for '${channel.providerKey}'`,
+    )
+  }
+
+  if (!isSystemEmailTransportConfigured()) {
+    throw new Error('SYSTEM_EMAIL_CHANNEL_NOT_CONFIGURED: configure a tenant-wide email channel')
+  }
+
+  logger.warn('Sending system email with instance-wide environment credentials', {
+    tenantId,
+    providerKey: channel.providerKey,
+    reason: `no tenant email channel or credentials configured for '${channel.providerKey}'`,
+    remedy: `run 'yarn mercato seed:defaults --module channel_${channel.providerKey}' to move this tenant onto the Communications Hub`,
+  })
+  return resolveEnvCredentials(channel.providerKey, payload.from)
+}
+
+/**
+ * Choose the address a system email actually leaves from.
+ *
+ * The tenant's configured sender wins whenever the caller did not name one itself. `sendEmail` always
+ * fills `from` in — from `NOTIFICATIONS_EMAIL_FROM` / `EMAIL_FROM` / `ADMIN_EMAIL` — so an adapter that
+ * merely falls back to its credentials when `from` is missing would never reach the tenant's value, and
+ * the "From address" saved in the integrations UI would be inert. A caller that passed an explicit
+ * `from` meant it, and keeps it.
+ */
+function resolveOutboundFromAddress(
+  payload: ResolvedEmailPayload,
+  credentials: Record<string, unknown>,
+): string {
+  if (!payload.fromIsInstanceDefault) return payload.from
+  const configured = credentials.fromAddress
+  return typeof configured === 'string' && configured.trim().length > 0 ? configured : payload.from
+}
+
+export async function sendSystemEmail(
+  container: AppContainer,
+  payload: ResolvedEmailPayload,
+): Promise<void> {
+  const em = (container.resolve('em') as EntityManager).fork()
+  const { channel, hasTenantChannel } = await resolveSystemEmailChannel(em, payload)
+  const registry = container.resolve('channelAdapterRegistry') as ChannelAdapterRegistry
+  const adapter = registry.get(channel.providerKey)
+  if (!adapter) {
+    throw new Error(
+      `[internal] No ChannelAdapter registered for providerKey '${channel.providerKey}'. Enable the provider module.`,
+    )
+  }
+
+  const credentials = payload.tenantId
+    ? await resolveTenantCredentials(container, em, payload, channel, hasTenantChannel)
+    : resolveEnvCredentials(channel.providerKey, payload.from)
+
+  const body = await resolveEmailBody(payload)
+  const converted = await adapter.convertOutbound({
+    body: body.body,
+    bodyFormat: body.bodyFormat,
+    channelMetadata: {
+      to: payload.to,
+      subject: payload.subject,
+      from: resolveOutboundFromAddress(payload, credentials),
+      replyTo: payload.replyTo,
+      attachments: payload.attachments,
+    },
+  })
+
+  const sendResult = await adapter.sendMessage({
+    content: converted.content,
+    credentials,
+    scope: {
+      tenantId: payload.tenantId ?? 'system',
+      organizationId: payload.organizationId ?? payload.tenantId ?? 'system',
+    },
+    metadata: converted.metadata,
+  })
+
+  if (sendResult.status === 'failed') {
+    throw new Error(sendResult.error ?? `SYSTEM_EMAIL_SEND_FAILED: ${channel.providerKey}`)
+  }
+}