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

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

@@ -719,5 +719,6 @@
   "customers~catalog.errors.id_required": "Datensatzkennung ist erforderlich.",
   "customers~catalog.errors.organization_required": "Organisationskontext ist erforderlich.",
   "customers~catalog.errors.tenant_required": "Mandantenkontext ist erforderlich.",
-  "customers~catalog.nav.group": "Katalog"
+  "customers~catalog.nav.group": "Katalog",
+  "notifications.categories.catalog": "Katalog"
 }

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

@@ -719,5 +719,6 @@
   "customers~catalog.errors.id_required": "Record identifier is required.",
   "customers~catalog.errors.organization_required": "Organization context is required.",
   "customers~catalog.errors.tenant_required": "Tenant context is required.",
-  "customers~catalog.nav.group": "Catalog"
+  "customers~catalog.nav.group": "Catalog",
+  "notifications.categories.catalog": "Catalog"
 }

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

@@ -719,5 +719,6 @@
   "customers~catalog.errors.id_required": "El identificador del registro es obligatorio.",
   "customers~catalog.errors.organization_required": "El contexto de organización es obligatorio.",
   "customers~catalog.errors.tenant_required": "El contexto de tenant es obligatorio.",
-  "customers~catalog.nav.group": "Catálogo"
+  "customers~catalog.nav.group": "Catálogo",
+  "notifications.categories.catalog": "Catálogo"
 }

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

@@ -719,5 +719,6 @@
   "customers~catalog.errors.id_required": "레코드 식별자가 필요합니다.",
   "customers~catalog.errors.organization_required": "조직 컨텍스트가 필요합니다.",
   "customers~catalog.errors.tenant_required": "테넌트 컨텍스트가 필요합니다.",
-  "customers~catalog.nav.group": "카탈로그"
+  "customers~catalog.nav.group": "카탈로그",
+  "notifications.categories.catalog": "카탈로그"
 }

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

@@ -719,5 +719,6 @@
   "customers~catalog.errors.id_required": "Identyfikator rekordu jest wymagany.",
   "customers~catalog.errors.organization_required": "Kontekst organizacji jest wymagany.",
   "customers~catalog.errors.tenant_required": "Kontekst tenanta jest wymagany.",
-  "customers~catalog.nav.group": "Katalog"
+  "customers~catalog.nav.group": "Katalog",
+  "notifications.categories.catalog": "Katalog"
 }

package/src/modules/catalog/notifications.ts

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

package/src/modules/communication_channels/acl.ts

@@ -12,6 +12,15 @@ export const features = [
    * Default-granted to all roles in `setup.ts`.
    */
   { id: 'communication_channels.connect_user_channel', title: 'Connect own communication channel', module: 'communication_channels' },
+  /**
+   * Connect a tenant-wide channel (`CommunicationChannel.user_id IS NULL`) that
+   * serves every user in the tenant — used for push providers (FCM/APNs/Expo)
+   * whose service account / signing key is shared tenant infrastructure. Gates
+   * `POST /channels/connect/tenant-credentials`. Admin/superadmin only: unlike
+   * `connect_user_channel` (everyone links their own mailbox), connecting shared
+   * push credentials is an administrative action.
+   */
+  { id: 'communication_channels.connect_tenant_channel', title: 'Connect tenant-wide communication channel', module: 'communication_channels' },
   /**
    * Reserved for a future v2 team-oversight capability. NOT consulted in v1:
    * personal mailboxes (`CommunicationChannel.user_id` set) follow the strict

package/src/modules/communication_channels/api/delete/admin/channels/[id]/route.ts

@@ -0,0 +1,168 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CommunicationChannel } from '../../../../../data/entities'
+import {
+  ChannelAccessDeniedError,
+  assertCanManageChannel,
+  channelOrgScopeWhere,
+} from '../../../../../lib/access-control'
+import {
+  COMMUNICATION_CHANNELS_ADMIN_DELETE_CHANNEL_COMMAND_ID,
+  type AdminDeleteChannelInput,
+  type AdminDeleteChannelResult,
+} from '../../../../../commands/admin-delete-channel'
+import { validateRouteMutationGuard } from '../../../../../lib/route-mutation-guard'
+
+type RbacServiceLike = {
+  loadAcl: (
+    userId: string,
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<{ isSuperAdmin: boolean; features: string[]; organizations: string[] | null }>
+}
+
+/**
+ * Admin soft-delete for a TENANT-WIDE communication channel (`user_id IS NULL`).
+ *
+ * Companion to `/communication_channels/channels/[id]` (owner-only, per-user
+ * path). Tenant-wide channels — shared inboxes and the push providers
+ * FCM/APNs/Expo — have no owner, so the owner route rejects them; this route
+ * deletes them under `communication_channels.admin`. The channel is loaded
+ * org-agnostically so tenant-wide `organization_id IS NULL` rows resolve from
+ * any session org; per-user channels are masked as 404.
+ */
+export const metadata = {
+  path: '/communication_channels/admin/channels/[id]',
+  DELETE: {
+    requireAuth: true,
+    requireFeatures: ['communication_channels.admin'],
+  },
+}
+
+type RouteContext = {
+  params: Promise<{ id: string }> | { id: string }
+}
+
+export async function DELETE(req: Request, context: RouteContext): Promise<Response> {
+  const { id } = await context.params
+  if (!z.string().uuid().safeParse(id).success) {
+    return NextResponse.json({ error: 'Invalid channel id' }, { status: 400 })
+  }
+
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub || !auth?.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager).fork()
+  const organizationId = (auth as { orgId?: string | null }).orgId ?? null
+  const dscope = { tenantId: auth.tenantId as string, organizationId }
+
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    {
+      id,
+      tenantId: auth.tenantId as string,
+      ...channelOrgScopeWhere(organizationId),
+      deletedAt: null,
+    },
+    undefined,
+    dscope,
+  )
+  // Mask a missing channel AND a per-user channel (which must go through the
+  // owner path) as 404 so admins can't probe personal-mailbox existence.
+  if (!channel || (channel as { userId?: string | null }).userId != null) {
+    return NextResponse.json({ error: 'Channel not found' }, { status: 404 })
+  }
+
+  let userFeatures: string[] = []
+  try {
+    const rbac = container.resolve('rbacService') as RbacServiceLike
+    const acl = await rbac.loadAcl(auth.sub as string, {
+      tenantId: auth.tenantId as string,
+      organizationId,
+    })
+    userFeatures = acl?.isSuperAdmin ? ['*'] : Array.isArray(acl?.features) ? acl.features : []
+  } catch {
+    userFeatures = []
+  }
+  try {
+    assertCanManageChannel(
+      { userId: (channel as { userId?: string | null }).userId },
+      auth.sub as string,
+      userFeatures,
+      'communication_channels.manage',
+    )
+  } catch (err) {
+    if (err instanceof ChannelAccessDeniedError) {
+      return NextResponse.json({ error: 'Channel not found' }, { status: 404 })
+    }
+    throw err
+  }
+
+  const guard = await validateRouteMutationGuard({
+    container,
+    req,
+    auth,
+    input: {
+      resourceKind: 'communication_channels.channel',
+      resourceId: id,
+      operation: 'delete',
+    },
+  })
+  if ('response' in guard) return guard.response
+
+  const commandBus = container.resolve('commandBus') as CommandBus
+  // Use the CHANNEL's own org (not the caller's session org) so push teardown
+  // and credential resolution key where the channel stored them.
+  const channelOrganizationId = (channel as { organizationId?: string | null }).organizationId ?? null
+  const input: AdminDeleteChannelInput = {
+    channelId: id,
+    scope: { tenantId: auth.tenantId as string, organizationId: channelOrganizationId },
+  }
+  const { result } = await commandBus.execute<AdminDeleteChannelInput, AdminDeleteChannelResult>(
+    COMMUNICATION_CHANNELS_ADMIN_DELETE_CHANNEL_COMMAND_ID,
+    {
+      input,
+      ctx: {
+        container,
+        auth: auth as never,
+        organizationScope: null,
+        selectedOrganizationId: organizationId,
+        organizationIds: organizationId ? [organizationId] : null,
+      },
+    },
+  )
+
+  // 'noop' (channel vanished between the load and the command) and
+  // 'not_tenant_wide' both map to 404 to avoid leaking existence.
+  if (result.status !== 'deleted') {
+    return NextResponse.json({ error: 'Channel not found' }, { status: 404 })
+  }
+  await guard.afterSuccess()
+  return new NextResponse(null, { status: 204 })
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  methods: {
+    DELETE: {
+      summary: 'Admin delete (soft-delete) a tenant-wide communication channel',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 204, description: 'Channel deleted' },
+        { status: 400, description: 'Invalid channel id' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 404, description: 'Channel not found or not a tenant-wide channel' },
+      ],
+    },
+  },
+}
+
+export default DELETE

package/src/modules/communication_channels/api/get/channels/[id]/health/route.ts

@@ -8,7 +8,11 @@ import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 import { CommunicationChannel, ExternalConversation, MessageChannelLink } from '../../../../../data/entities'
-import { ChannelAccessDeniedError, assertCanAccessChannel } from '../../../../../lib/access-control'
+import {
+  ChannelAccessDeniedError,
+  assertCanAccessChannel,
+  channelOrgScopeWhereFromFilter,
+} from '../../../../../lib/access-control'
 
 type RbacServiceLike = {
   loadAcl: (
@@ -67,7 +71,7 @@ export async function GET(req: Request, context: RouteContext): Promise<Response
   const channel = await findOneWithDecryption(
     em,
     CommunicationChannel,
-    { id, tenantId: auth.tenantId, ...orgFilter.where, deletedAt: null },
+    { id, tenantId: auth.tenantId, ...channelOrgScopeWhereFromFilter(orgFilter), deletedAt: null },
     undefined,
     dscope,
   )

package/src/modules/communication_channels/api/get/channels/[id]/route.ts

@@ -7,7 +7,11 @@ import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 import { CommunicationChannel } from '../../../../data/entities'
-import { ChannelAccessDeniedError, assertCanAccessChannel } from '../../../../lib/access-control'
+import {
+  ChannelAccessDeniedError,
+  assertCanAccessChannel,
+  channelOrgScopeWhereFromFilter,
+} from '../../../../lib/access-control'
 
 type RbacServiceLike = {
   loadAcl: (
@@ -50,7 +54,7 @@ export async function GET(req: Request, context: RouteContext): Promise<Response
     {
       id,
       tenantId: auth.tenantId,
-      ...orgFilter.where,
+      ...channelOrgScopeWhereFromFilter(orgFilter),
       deletedAt: null,
     },
     undefined,

package/src/modules/communication_channels/api/get/channels/route.ts

@@ -7,6 +7,7 @@ import { findAndCountWithDecryption } from '@open-mercato/shared/lib/encryption/
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 import { CommunicationChannel } from '../../../data/entities'
+import { channelOrgScopeWhereFromFilter } from '../../../lib/access-control'
 
 export const metadata = {
   path: '/communication_channels/channels',
@@ -58,7 +59,7 @@ export async function GET(req: Request): Promise<Response> {
   // one — admins included — can see another user's connected personal account.
   const where: Record<string, unknown> = {
     tenantId: auth.tenantId,
-    ...orgFilter.where,
+    ...channelOrgScopeWhereFromFilter(orgFilter),
     deletedAt: null,
     userId: null,
   }

package/src/modules/communication_channels/api/post/channels/[id]/test-send/route.ts

@@ -7,7 +7,11 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { CommunicationChannel } from '../../../../../data/entities'
 import { getChannelAdapter } from '../../../../../lib/adapter-registry-singleton'
-import { ChannelAccessDeniedError, assertCanManageChannel } from '../../../../../lib/access-control'
+import {
+  ChannelAccessDeniedError,
+  assertCanManageChannel,
+  channelOrgScopeWhere,
+} from '../../../../../lib/access-control'
 import { refreshCredentialsIfNeeded } from '../../../../../lib/credential-refresh'
 import { validateRouteMutationGuard } from '../../../../../lib/route-mutation-guard'
 
@@ -90,7 +94,7 @@ export async function POST(req: Request, context: RouteContext): Promise<Respons
     {
       id,
       tenantId: auth.tenantId as string,
-      organizationId,
+      ...channelOrgScopeWhere(organizationId),
       deletedAt: null,
     },
     undefined,
@@ -99,6 +103,13 @@ export async function POST(req: Request, context: RouteContext): Promise<Respons
   if (!channel) {
     return NextResponse.json({ error: 'Channel not found' }, { status: 404 })
   }
+  // Resolve credentials at the channel's OWN org, not the caller's selected org.
+  // Tenant-wide channels store `organization_id = NULL` and their credentials
+  // live at `organization_id = tenantId` (see connect-credential-channel.ts), so
+  // the read key must be `channel.organizationId ?? tenantId` — keying on the
+  // session org would resolve `{}` for a tenant-wide channel viewed from a
+  // non-null org.
+  const channelCredentialsOrg = channel.organizationId ?? (auth.tenantId as string)
   // Load features via RBAC service so admin bypass (`communication_channels.admin`,
   // wildcards, super-admin) is honoured. The `auth` object from
   // `getAuthFromRequest` carries identity only — feature ACLs live in the RBAC
@@ -172,14 +183,14 @@ export async function POST(req: Request, context: RouteContext): Promise<Respons
       (await credentialsService
         .resolve(`channel_${channel.providerKey}`, {
           tenantId: auth.tenantId as string,
-          organizationId: organizationId ?? (auth.tenantId as string),
+          organizationId: channelCredentialsOrg,
           userId: channel.userId ?? null,
         })
         .catch(() => null)) ?? {}
   }
   const credentialScope = {
     tenantId: auth.tenantId as string,
-    organizationId: organizationId ?? (auth.tenantId as string),
+    organizationId: channelCredentialsOrg,
     userId: channel.userId ?? null,
   }
   const refreshed = await refreshCredentialsIfNeeded(
@@ -203,7 +214,7 @@ export async function POST(req: Request, context: RouteContext): Promise<Respons
       credentials,
       scope: {
         tenantId: auth.tenantId as string,
-        organizationId: organizationId ?? (auth.tenantId as string),
+        organizationId: channelCredentialsOrg,
       },
       metadata: { to: body.to, subject: body.subject ?? 'Test send', testSend: true },
     })

package/src/modules/communication_channels/api/post/channels/connect/credentials/route.ts

@@ -9,6 +9,7 @@ import {
   type ConnectCredentialChannelInput,
   type ConnectCredentialChannelResult,
 } from '../../../../../commands/connect-credential-channel'
+import type { ChannelAdapterRegistry } from '../../../../../lib/registry'
 import { validateRouteMutationGuard } from '../../../../../lib/route-mutation-guard'
 
 export const metadata = {
@@ -44,6 +45,24 @@ export async function POST(req: Request): Promise<Response> {
   }
 
   const container = await createRequestContainer()
+
+  // Tenant-scoped providers (push: FCM/APNs/Expo) must go through the admin-gated
+  // tenant route, not this per-user one (granted to manager/employee via
+  // `connect_user_channel`). Reject them here so a non-admin can't mint a
+  // privileged tenant-wide channel. The command enforces the same invariant
+  // (`wrong_scope_for_route`) as defense-in-depth.
+  const adapterRegistry = container.resolve('channelAdapterRegistry') as ChannelAdapterRegistry
+  const earlyAdapter = adapterRegistry.get(body.providerKey)
+  if (earlyAdapter && earlyAdapter.channelScope === 'tenant') {
+    return NextResponse.json(
+      {
+        error: 'This provider is connected tenant-wide by an administrator, not per-user.',
+        code: 'provider_is_tenant_scoped',
+      },
+      { status: 403 },
+    )
+  }
+
   const guard = await validateRouteMutationGuard({
     container,
     req,
@@ -93,8 +112,24 @@ export async function POST(req: Request): Promise<Response> {
   if (result.status === 'no_adapter') {
     return NextResponse.json({ error: result.reason }, { status: 404 })
   }
+  if (result.status === 'wrong_scope_for_route') {
+    return NextResponse.json(
+      {
+        error: 'This provider is connected tenant-wide by an administrator, not per-user.',
+        code: 'provider_is_tenant_scoped',
+      },
+      { status: 403 },
+    )
+  }
   if (result.status === 'validation_failed') {
-    return NextResponse.json({ error: 'Credential validation failed', fieldErrors: result.errors }, { status: 422 })
+    return NextResponse.json(
+      {
+        error: 'Credential validation failed',
+        fieldErrors: result.errors,
+        ...(result.errorCodes ? { fieldErrorCodes: result.errorCodes } : {}),
+      },
+      { status: 422 },
+    )
   }
   if (result.status === 'duplicate_mailbox') {
     return NextResponse.json(
@@ -124,6 +159,7 @@ export const openApi = {
       responses: [
         { status: 201, description: 'Channel connected' },
         { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Provider is tenant-scoped — use the tenant connect route' },
         { status: 404, description: 'Unknown provider' },
         { status: 409, description: 'Mailbox already connected via another provider' },
         { status: 422, description: 'Invalid body or credential validation failed' },

package/src/modules/communication_channels/api/post/channels/connect/tenant-credentials/route.ts

@@ -0,0 +1,175 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import {
+  COMMUNICATION_CHANNELS_CONNECT_CREDENTIAL_CHANNEL_COMMAND_ID,
+  type ConnectCredentialChannelInput,
+  type ConnectCredentialChannelResult,
+} from '../../../../../commands/connect-credential-channel'
+import type { ChannelAdapterRegistry } from '../../../../../lib/registry'
+import { validateRouteMutationGuard } from '../../../../../lib/route-mutation-guard'
+
+export const metadata = {
+  path: '/communication_channels/channels/connect/tenant-credentials',
+  POST: {
+    requireAuth: true,
+    requireFeatures: ['communication_channels.connect_tenant_channel'],
+  },
+}
+
+const bodySchema = z.object({
+  providerKey: z.string().min(1).max(64),
+  displayName: z.string().min(1).max(255),
+  credentials: z.record(z.string(), z.unknown()),
+  pollIntervalSeconds: z.number().int().positive().max(86_400).optional(),
+})
+
+export async function POST(req: Request): Promise<Response> {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.sub || !auth?.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  let body: z.infer<typeof bodySchema>
+  try {
+    const json = await readJsonSafe(req, null)
+    body = bodySchema.parse(json)
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Invalid request body' },
+      { status: 422 },
+    )
+  }
+
+  const container = await createRequestContainer()
+
+  // Reject providers that are NOT tenant-scoped so an admin can't force a
+  // per-user provider (Gmail/IMAP) into a shared tenant-wide channel. Push
+  // providers (FCM/APNs/Expo) declare `channelScope: 'tenant'` on their adapter.
+  const adapterRegistry = container.resolve('channelAdapterRegistry') as ChannelAdapterRegistry
+  const adapter = adapterRegistry.get(body.providerKey)
+  if (!adapter) {
+    return NextResponse.json(
+      { error: `No adapter registered for provider '${body.providerKey}'` },
+      { status: 404 },
+    )
+  }
+  if (adapter.channelScope !== 'tenant') {
+    return NextResponse.json(
+      {
+        error: 'This provider connects per-user channels; use the personal channel connect flow instead.',
+        code: 'provider_not_tenant_scoped',
+      },
+      { status: 400 },
+    )
+  }
+
+  const guard = await validateRouteMutationGuard({
+    container,
+    req,
+    auth,
+    input: {
+      resourceKind: 'communication_channels.channel',
+      resourceId: `new:${body.providerKey}`,
+      operation: 'create',
+      mutationPayload: {
+        providerKey: body.providerKey,
+        displayName: body.displayName,
+        pollIntervalSeconds: body.pollIntervalSeconds,
+      },
+    },
+  })
+  if ('response' in guard) return guard.response
+
+  const commandBus = container.resolve('commandBus') as CommandBus
+  const orgId = (auth as { orgId?: string | null }).orgId ?? null
+
+  const input: ConnectCredentialChannelInput = {
+    providerKey: body.providerKey,
+    displayName: body.displayName,
+    credentials: body.credentials,
+    pollIntervalSeconds: body.pollIntervalSeconds,
+    // Tenant-wide: no owning user. The command re-derives the effective scope
+    // from the adapter, so the channel + credentials are stored with user_id NULL.
+    userId: null,
+    scope: {
+      tenantId: auth.tenantId as string,
+      organizationId: orgId,
+    },
+  }
+  const { result } = await commandBus.execute<
+    ConnectCredentialChannelInput,
+    ConnectCredentialChannelResult
+  >(COMMUNICATION_CHANNELS_CONNECT_CREDENTIAL_CHANNEL_COMMAND_ID, {
+    input,
+    ctx: {
+      container,
+      auth: auth as never,
+      organizationScope: null,
+      selectedOrganizationId: orgId,
+      organizationIds: orgId ? [orgId] : null,
+    },
+  })
+
+  if (result.status === 'no_adapter') {
+    return NextResponse.json({ error: result.reason }, { status: 404 })
+  }
+  if (result.status === 'wrong_scope_for_route') {
+    // Unreachable in practice — this route always dispatches with userId: null —
+    // but handle it so the result union narrows and the invariant is explicit.
+    return NextResponse.json(
+      { error: 'Unexpected per-user scope on the tenant connect route.', code: 'wrong_scope_for_route' },
+      { status: 500 },
+    )
+  }
+  if (result.status === 'validation_failed') {
+    // `fieldErrors` stays English for API consumers and logs; `fieldErrorCodes`
+    // lets the connect widget render a localized message per field.
+    return NextResponse.json(
+      {
+        error: 'Credential validation failed',
+        fieldErrors: result.errors,
+        ...(result.errorCodes ? { fieldErrorCodes: result.errorCodes } : {}),
+      },
+      { status: 422 },
+    )
+  }
+  if (result.status === 'duplicate_mailbox') {
+    return NextResponse.json(
+      {
+        error: `This mailbox is already connected via "${result.existingProviderKey}". Disconnect it there before connecting it again with a different provider.`,
+        code: 'mailbox_already_connected',
+      },
+      { status: 409 },
+    )
+  }
+  await guard.afterSuccess()
+  return NextResponse.json(
+    {
+      channelId: result.channelId,
+      externalIdentifier: result.externalIdentifier,
+    },
+    { status: 201 },
+  )
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  methods: {
+    POST: {
+      summary: 'Connect a tenant-wide credential-based channel (push: FCM/APNs/Expo)',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 201, description: 'Channel connected' },
+        { status: 400, description: 'Provider is not tenant-scoped' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 404, description: 'Unknown provider' },
+        { status: 422, description: 'Invalid body or credential validation failed' },
+      ],
+    },
+  },
+}
+export default POST

package/src/modules/communication_channels/backend/communication_channels/channels/page.tsx

@@ -34,8 +34,17 @@ export default function ChannelsListPage() {
   const [page, setPage] = React.useState(1)
   const [isLoading, setIsLoading] = React.useState(true)
   const [errorMessage, setErrorMessage] = React.useState<string | null>(null)
+  // Bumped by injected connect widgets (FCM/APNs/Expo) so a freshly connected
+  // tenant-wide channel appears without a manual page reload.
+  const [reloadToken, setReloadToken] = React.useState(0)
   const pageSize = 50
 
+  const reload = React.useCallback(() => setReloadToken((token) => token + 1), [])
+  const injectionContext = React.useMemo(
+    () => ({ tableId: extensionPoints.hosts.channelsTable.tableId, reload }),
+    [reload],
+  )
+
   React.useEffect(() => {
     let cancelled = false
     async function load() {
@@ -70,7 +79,7 @@ export default function ChannelsListPage() {
     return () => {
       cancelled = true
     }
-  }, [page, t])
+  }, [page, reloadToken, t])
 
   const columns = React.useMemo<ColumnDef<ChannelRow>[]>(
     () => [
@@ -116,6 +125,7 @@ export default function ChannelsListPage() {
         <DataTable<ChannelRow>
           title={t('communication_channels.nav.title', 'Communication Channels')}
           extensionTableId={extensionPoints.hosts.channelsTable.tableId}
+          injectionContext={injectionContext}
           columns={columns}
           data={rows}
           isLoading={isLoading}