@open-mercato/core 0.6.5-develop.4384.1.ce2ec6eaaa → 0.6.5-develop.4393.1.de282b5dfd

package/src/modules/communication_channels/api/post/channels/[id]/poll-now/route.ts

@@ -0,0 +1,174 @@
+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 { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CommunicationChannel } from '../../../../../data/entities'
+import { ChannelAccessDeniedError, assertCanManageChannel } from '../../../../../lib/access-control'
+import { COMMUNICATION_CHANNELS_QUEUES, getCommunicationChannelsQueue } from '../../../../../lib/queue'
+import type { PollChannelJobPayload } from '../../../../../workers/poll-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 }>
+}
+
+export const metadata = {
+  path: '/communication_channels/channels/[id]/poll-now',
+  POST: {
+    // Owner self-service: a user may sync their OWN mailbox (gated by
+    // `connect_user_channel`). Polling a shared/tenant-wide channel still
+    // requires `manage` — enforced per channel type by `assertCanManageChannel`.
+    requireAuth: true,
+    requireFeatures: ['communication_channels.connect_user_channel'],
+  },
+}
+
+type RouteContext = {
+  params: Promise<{ id: string }> | { id: string }
+}
+
+/**
+ * Manual poll trigger — enqueues a single `poll-channel` job immediately so
+ * the operator (or a demo) doesn't have to wait for the 60-second scheduler
+ * tick + per-channel `poll_interval_seconds` window.
+ *
+ * Per-user access guard mirrors the rest of the channels API: only the channel
+ * owner (or an admin with `communication_channels.admin`) can trigger a poll.
+ */
+export async function POST(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,
+      organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    dscope,
+  )
+  if (!channel) {
+    return NextResponse.json({ error: 'Channel not found' }, { status: 404 })
+  }
+
+  // Load features via RBAC so admin bypass is honoured.
+  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
+  }
+
+  if (!channel.isActive) {
+    return NextResponse.json({ error: 'Channel is disabled' }, { status: 409 })
+  }
+  // Allow manual poll-now from 'connected' AND 'error' states. The operator's
+  // intent in clicking "Poll now" while the channel is in error is exactly
+  // "retry the connection right now"; a successful poll auto-resets status
+  // back to 'connected' (see poll-channel.ts).
+  // Block only the explicitly-broken lifecycle states.
+  if (channel.status === 'requires_reauth') {
+    return NextResponse.json(
+      { error: 'Channel needs reauthentication — reconnect from /backend/profile/communication-channels' },
+      { status: 409 },
+    )
+  }
+  if (channel.status === 'disconnected') {
+    return NextResponse.json(
+      { error: 'Channel is disconnected — reconnect to resume polling' },
+      { status: 409 },
+    )
+  }
+
+  const guard = await validateRouteMutationGuard({
+    container,
+    req,
+    auth,
+    input: {
+      resourceKind: 'communication_channels.channel',
+      resourceId: channel.id,
+      operation: 'custom',
+      mutationPayload: { action: 'poll-now' },
+    },
+  })
+  if ('response' in guard) return guard.response
+
+  const queue = getCommunicationChannelsQueue(COMMUNICATION_CHANNELS_QUEUES.poll)
+  const payload: PollChannelJobPayload = {
+    channelId: channel.id,
+    scope: {
+      tenantId: auth.tenantId as string,
+      organizationId: organizationId ?? null,
+    },
+    attempt: 1,
+  }
+  await queue.enqueue(payload as unknown as Record<string, unknown>)
+  await guard.afterSuccess()
+
+  return NextResponse.json(
+    {
+      ok: true,
+      channelId: channel.id,
+      queued: true,
+      message: 'Poll queued — new messages will appear after the worker runs.',
+    },
+    { status: 202 },
+  )
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  methods: {
+    POST: {
+      summary: 'Manually trigger a poll cycle for a channel (demo / operator override)',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 202, description: 'Poll job enqueued' },
+        { status: 400, description: 'Invalid channel id' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 404, description: 'Channel not found' },
+        { status: 409, description: 'Channel disabled or not connected' },
+      ],
+    },
+  },
+}
+export default POST

package/src/modules/communication_channels/api/post/channels/[id]/push/register/route.ts

@@ -0,0 +1,158 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { CrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { CommunicationChannel } from '../../../../../../data/entities'
+import { ChannelAccessDeniedError, assertCanManageChannel } from '../../../../../../lib/access-control'
+import { pushRegister } from '../../../../../../commands/push-register'
+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 }>
+}
+
+/**
+ * Spec C § Phase C5 — Operator-facing "Re-register push" endpoint.
+ *
+ * Owner self-service: a user may (re-)register push on their OWN mailbox (gated
+ * by `connect_user_channel`). Registering push on a shared/tenant-wide channel
+ * still requires `communication_channels.channel.push.manage` — enforced per
+ * channel type by `assertCanManageChannel` in the handler. Used by the profile
+ * page and the channel detail page's `PushStatusSection` to recover from a
+ * `pushStatus='failed'` state.
+ */
+export const metadata = {
+  path: '/communication_channels/channels/[id]/push/register',
+  POST: {
+    requireAuth: true,
+    requireFeatures: ['communication_channels.connect_user_channel'],
+  },
+}
+
+type RouteContext = {
+  params: Promise<{ id: string }> | { id: string }
+}
+
+export async function POST(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 organizationId = (auth as { orgId?: string | null }).orgId ?? null
+  if (!organizationId) {
+    return NextResponse.json({ error: 'No organization scope' }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+
+  // Defense-in-depth: `push.manage` is admin-default, but enforce per-user
+  // ownership anyway so a non-admin operator who is granted `push.manage`
+  // cannot re-register push on another user's channel. Admins (and tenant-wide
+  // channels) pass via `assertCanAccessChannel`. Automatic callers (OAuth
+  // callback, connect, renew worker) invoke `pushRegister` directly and are
+  // intentionally not subject to this user-facing guard.
+  const em = (container.resolve('em') as EntityManager).fork()
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    { id, tenantId: auth.tenantId as string, organizationId, deletedAt: null },
+    undefined,
+    { tenantId: auth.tenantId as string, organizationId },
+  )
+  if (!channel) {
+    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.channel.push.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: 'custom',
+      mutationPayload: { pushStatus: 'register' },
+    },
+  })
+  if ('response' in guard) return guard.response
+
+  try {
+    const result = await pushRegister({
+      container,
+      scope: { tenantId: auth.tenantId as string, organizationId, userId: auth.sub as string },
+      input: { channelId: id },
+    })
+    await guard.afterSuccess()
+    return NextResponse.json({ ok: true, ...result }, { status: 202 })
+  } catch (err) {
+    const candidate = err as CrudFormError
+    if (candidate && typeof candidate.status === 'number') {
+      return NextResponse.json(
+        { error: candidate.message, fieldErrors: candidate.fieldErrors },
+        { status: candidate.status },
+      )
+    }
+    console.error(`[push-register] failed for channel ${id}:`, err)
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Failed to register push' },
+      { status: 500 },
+    )
+  }
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  methods: {
+    POST: {
+      summary: 'Force-register push delivery for a channel (Spec C § Phase C5)',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 202, description: 'Push registration attempted; check result.pushStatus' },
+        { status: 400, description: 'Invalid id or unsupported provider' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing push.manage feature' },
+        { status: 404, description: 'Channel not found' },
+        { status: 409, description: 'Provider does not support push (IMAP)' },
+        { status: 502, description: 'Provider returned an error during registration' },
+        { status: 503, description: 'Webhook base URL or Pub/Sub topic not configured' },
+      ],
+    },
+  },
+}
+
+export default POST

package/src/modules/communication_channels/api/post/channels/[id]/set-primary/route.ts

@@ -0,0 +1,114 @@
+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 {
+  COMMUNICATION_CHANNELS_SET_PRIMARY_COMMAND_ID,
+  type SetPrimaryChannelInput,
+  type SetPrimaryChannelResult,
+} from '../../../../../commands/set-primary-channel'
+import { validateRouteMutationGuard } from '../../../../../lib/route-mutation-guard'
+
+export const metadata = {
+  path: '/communication_channels/channels/[id]/set-primary',
+  POST: {
+    // Owner self-service: every email user controls their own channels. The
+    // set-primary command enforces strict ownership (`not_owner` → 404), and
+    // "primary" only applies to per-user channels, so `connect_user_channel`
+    // is the correct gate (not `manage`).
+    requireAuth: true,
+    requireFeatures: ['communication_channels.connect_user_channel'],
+  },
+}
+
+type RouteContext = {
+  params: Promise<{ id: string }> | { id: string }
+}
+
+export async function POST(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 guard = await validateRouteMutationGuard({
+    container,
+    req,
+    auth,
+    input: {
+      resourceKind: 'communication_channels.channel',
+      resourceId: id,
+      operation: 'custom',
+      mutationPayload: { isPrimary: true },
+    },
+  })
+  if ('response' in guard) return guard.response
+
+  const commandBus = container.resolve('commandBus') as CommandBus
+
+  const input: SetPrimaryChannelInput = {
+    channelId: id,
+    userId: auth.sub as string,
+    scope: {
+      tenantId: auth.tenantId as string,
+      organizationId: (auth as { orgId?: string | null }).orgId ?? null,
+    },
+  }
+  const { result } = await commandBus.execute<
+    SetPrimaryChannelInput,
+    SetPrimaryChannelResult
+  >(COMMUNICATION_CHANNELS_SET_PRIMARY_COMMAND_ID, {
+    input,
+    ctx: {
+      container,
+      auth: auth as never,
+      organizationScope: null,
+      selectedOrganizationId: (auth as { orgId?: string | null }).orgId ?? null,
+      organizationIds: (auth as { orgId?: string | null }).orgId
+        ? [(auth as { orgId?: string | null }).orgId!]
+        : null,
+    },
+  })
+
+  // Non-ownership maps to 404 (existence masking), consistent with the other
+  // channel-scoped routes (GET [id], poll-now, import-history, test-send, DELETE).
+  if (result.status === 'not_owner') {
+    return NextResponse.json({ error: 'Channel not found' }, { status: 404 })
+  }
+  if (result.status === 'noop') {
+    return NextResponse.json({ channelId: id, isPrimary: true, unchanged: true }, { status: 200 })
+  }
+  await guard.afterSuccess()
+  return NextResponse.json(
+    {
+      channelId: result.channelId,
+      isPrimary: true,
+      previousPrimaryChannelId: result.previousPrimaryChannelId,
+    },
+    { status: 200 },
+  )
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  methods: {
+    POST: {
+      summary: 'Mark a per-user channel as primary',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 200, description: 'Channel set as primary (or already primary)' },
+        { status: 400, description: 'Invalid channel id' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 404, description: 'Channel not found or not owned by current user' },
+      ],
+    },
+  },
+}
+export default POST

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

@@ -0,0 +1,241 @@
+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 { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+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 { refreshCredentialsIfNeeded } from '../../../../../lib/credential-refresh'
+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 }>
+}
+
+export const metadata = {
+  path: '/communication_channels/channels/[id]/test-send',
+  POST: {
+    // Owner self-service: a user may send a test from their OWN mailbox (gated
+    // by `connect_user_channel`). Test-sending from a shared/tenant-wide channel
+    // still requires `manage` — enforced per channel type by `assertCanManageChannel`.
+    requireAuth: true,
+    requireFeatures: ['communication_channels.connect_user_channel'],
+  },
+}
+
+const bodySchema = z.object({
+  to: z.string().email(),
+  subject: z.string().min(1).max(500).optional(),
+  body: z.string().max(50_000).optional(),
+})
+
+type RouteContext = {
+  params: Promise<{ id: string }> | { id: string }
+}
+
+type CredentialsServiceLike = {
+  resolve: (
+    integrationId: string,
+    scope: { organizationId: string; tenantId: string; userId?: string | null },
+  ) => Promise<Record<string, unknown> | null>
+  save?: (
+    integrationId: string,
+    credentials: Record<string, unknown>,
+    scope: { organizationId: string; tenantId: string; userId?: string | null },
+  ) => Promise<void>
+}
+
+/**
+ * Admin diagnostic — send a test message via the adapter without creating a
+ * platform `Message`. Useful for verifying credentials + outbound connectivity
+ * after a channel is configured.
+ *
+ * The result is NOT persisted to `ExternalMessage` / `MessageChannelLink` — it
+ * is a one-shot probe.
+ */
+export async function POST(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 })
+  }
+
+  let body: z.infer<typeof bodySchema>
+  try {
+    body = bodySchema.parse(await readJsonSafe(req, null))
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Invalid request body' },
+      { status: 422 },
+    )
+  }
+
+  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,
+      organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    dscope,
+  )
+  if (!channel) {
+    return NextResponse.json({ error: 'Channel not found' }, { status: 404 })
+  }
+  // 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
+  // service and must be loaded per request.
+  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.userId },
+      auth.sub as string,
+      userFeatures,
+      'communication_channels.manage',
+    )
+  } catch (err) {
+    if (err instanceof ChannelAccessDeniedError) {
+      return NextResponse.json({ error: 'Channel not found' }, { status: 404 })
+    }
+    const status = (err as { statusCode?: number }).statusCode ?? 403
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Access denied' },
+      { status },
+    )
+  }
+  if (!channel.isActive || channel.status !== 'connected') {
+    return NextResponse.json(
+      { error: `Channel is in status '${channel.status}' (not connected)` },
+      { status: 409 },
+    )
+  }
+
+  const guard = await validateRouteMutationGuard({
+    container,
+    req,
+    auth,
+    input: {
+      resourceKind: 'communication_channels.channel',
+      resourceId: channel.id,
+      operation: 'custom',
+      mutationPayload: body as unknown as Record<string, unknown>,
+    },
+  })
+  if ('response' in guard) return guard.response
+
+  const adapter = getChannelAdapter(channel.providerKey)
+  if (!adapter) {
+    return NextResponse.json(
+      { error: `No adapter registered for provider '${channel.providerKey}'` },
+      { status: 404 },
+    )
+  }
+
+  // Resolve credentials + optionally refresh.
+  let credentials: Record<string, unknown> = {}
+  let credentialsService: CredentialsServiceLike | null = null
+  try {
+    credentialsService = container.resolve('integrationCredentialsService') as CredentialsServiceLike
+  } catch {
+    credentialsService = null
+  }
+  if (channel.credentialsRef && credentialsService) {
+    credentials =
+      (await credentialsService
+        .resolve(`channel_${channel.providerKey}`, {
+          tenantId: auth.tenantId as string,
+          organizationId: organizationId ?? (auth.tenantId as string),
+          userId: channel.userId ?? null,
+        })
+        .catch(() => null)) ?? {}
+  }
+  const credentialScope = {
+    tenantId: auth.tenantId as string,
+    organizationId: organizationId ?? (auth.tenantId as string),
+    userId: channel.userId ?? null,
+  }
+  const refreshed = await refreshCredentialsIfNeeded(
+    {
+      adapter,
+      channelId: channel.id,
+      credentials,
+      scope: credentialScope,
+    },
+    { credentialsService },
+  )
+  credentials = refreshed.credentials
+
+  try {
+    const converted = await adapter.convertOutbound({
+      body: body.body ?? 'Test message from Open Mercato',
+      bodyFormat: 'text',
+    })
+    const result = await adapter.sendMessage({
+      content: converted.content,
+      credentials,
+      scope: {
+        tenantId: auth.tenantId as string,
+        organizationId: organizationId ?? (auth.tenantId as string),
+      },
+      metadata: { to: body.to, subject: body.subject ?? 'Test send', testSend: true },
+    })
+    await guard.afterSuccess()
+    return NextResponse.json({
+      status: result.status,
+      externalMessageId: result.externalMessageId,
+      providerError: result.error ?? null,
+    })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'send failed'
+    return NextResponse.json({ status: 'failed', error: message }, { status: 502 })
+  }
+}
+
+export const openApi = {
+  tags: ['CommunicationChannels'],
+  methods: {
+    POST: {
+      summary: 'Diagnostic — send a test message through the channel without persisting',
+      tags: ['CommunicationChannels'],
+      responses: [
+        { status: 200, description: 'Test send result' },
+        { status: 400, description: 'Invalid channel id' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Not allowed to manage this channel' },
+        { status: 404, description: 'Channel or adapter not found' },
+        { status: 409, description: 'Channel not connected' },
+        { status: 422, description: 'Invalid request body' },
+        { status: 502, description: 'Provider error' },
+      ],
+    },
+  },
+}
+export default POST