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

package/src/modules/communication_channels/commands/interceptors.ts

@@ -0,0 +1,104 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type {
+  CommandInterceptor,
+  CommandInterceptorBeforeResult,
+  CommandInterceptorUndoContext,
+} from '@open-mercato/shared/lib/commands/command-interceptor'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { CommunicationChannel } from '../data/entities'
+import {
+  COMMUNICATION_CHANNELS_DISCONNECT_CHANNEL_COMMAND_ID,
+  extractSnapshotFromLog,
+  type DisconnectChannelUndoSnapshot,
+} from './disconnect-channel'
+
+/**
+ * Command interceptors for the Communications Hub.
+ *
+ * Phase 4 deliverable 5 of the email integration spec:
+ *   - `beforeUndo` interceptor on `communication_channels.channel.disconnect`.
+ *     If a different channel became primary while this one was disconnected,
+ *     blocking the undo is the right call — restoring `is_primary=true` would
+ *     violate the partial unique index `communication_channels_one_primary_per_user_uq`,
+ *     and silently demoting the *other* channel would surprise the user.
+ *
+ * Auto-discovered by `commands/interceptors.ts` convention; no DI registration
+ * required.
+ */
+export const interceptors: CommandInterceptor[] = [
+  {
+    id: 'communication_channels.disconnect-channel-before-undo',
+    targetCommand: COMMUNICATION_CHANNELS_DISCONNECT_CHANNEL_COMMAND_ID,
+    priority: 50,
+    async beforeUndo(
+      undoContext: CommandInterceptorUndoContext,
+      ctxRuntime,
+    ): Promise<CommandInterceptorBeforeResult | void> {
+      // Read the snapshot exactly as the command's own undo() handler does — from
+      // the persisted action-log `commandPayload.undo` (written by buildLog). The
+      // earlier `result.undo`/`resultJson`/`resultBody` shapes do not exist on the
+      // ActionLog entity, so this guard previously never fired.
+      const snapshot: DisconnectChannelUndoSnapshot | null = extractSnapshotFromLog(
+        undoContext.logEntry,
+      )
+      if (!snapshot) {
+        // No snapshot we can interpret → let undo proceed; the command's own
+        // undo() handler will no-op if the channel can't be re-resolved.
+        return
+      }
+      // Only enforce when the disconnected channel was the primary.
+      if (!snapshot.previousIsPrimary) {
+        return
+      }
+
+      const em = (ctxRuntime.container.resolve('em') as EntityManager).fork()
+      // Resolve only within the snapshot's tenant — never by bare id, which
+      // would cross tenant boundaries. New snapshots always carry tenantId.
+      if (!snapshot.tenantId) return
+      const ownedChannel = await findOneWithDecryption(
+        em,
+        CommunicationChannel,
+        { id: snapshot.channelId, tenantId: snapshot.tenantId },
+        undefined,
+        { tenantId: snapshot.tenantId as string, organizationId: null },
+      )
+      if (!ownedChannel) return // command's undo() will silently no-op
+
+      const otherPrimary = await findOneWithDecryption(
+        em,
+        CommunicationChannel,
+        {
+          tenantId: ownedChannel.tenantId,
+          organizationId: ownedChannel.organizationId ?? null,
+          userId: ownedChannel.userId,
+          isPrimary: true,
+          deletedAt: null,
+        },
+        undefined,
+        {
+          tenantId: ownedChannel.tenantId,
+          organizationId: ownedChannel.organizationId ?? null,
+        },
+      )
+      if (otherPrimary && otherPrimary.id !== snapshot.channelId) {
+        // Operator-facing block reason. Localize via the request locale when
+        // available, but undo can also run outside a request (queue worker / CLI)
+        // where the i18n module registry is uninitialized and resolveTranslations()
+        // throws — fall back to the English string rather than failing the block.
+        const fallback =
+          'Another channel is now primary for this user. Set it as non-primary before restoring the disconnected channel as primary.'
+        let message = fallback
+        try {
+          const { translate } = await resolveTranslations()
+          message = translate('communication_channels.errors.undoBlockedPrimaryConflict', fallback)
+        } catch {
+          message = fallback
+        }
+        return { ok: false, message }
+      }
+    },
+  },
+]
+
+export default interceptors

package/src/modules/communication_channels/commands/process-inbound-reaction.ts

@@ -0,0 +1,265 @@
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandHandler } from '@open-mercato/shared/lib/commands'
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { emitCommunicationChannelsEvent } from '../events'
+import {
+  CommunicationChannel,
+  ExternalMessage,
+  MessageChannelLink,
+  MessageReaction,
+} from '../data/entities'
+import { inboundReactionEventSchema } from '../data/validators'
+import {
+  allowsMultipleReactionsPerUser,
+  resolveInboundAddMutation,
+} from '../lib/reaction-semantics'
+import type { ChannelCapabilities } from '../lib/adapter'
+import { isUniqueViolation } from '../lib/pg-errors'
+
+const processInboundReactionInputSchema = z.object({
+  channelId: z.string().uuid(),
+  providerKey: z.string().min(1),
+  channelType: z.string().min(1),
+  scope: z.object({
+    tenantId: z.string().uuid(),
+    organizationId: z.string().uuid().nullable(),
+  }),
+  event: inboundReactionEventSchema,
+})
+
+export type ProcessInboundReactionInput = z.infer<typeof processInboundReactionInputSchema>
+
+export type ProcessInboundReactionResult =
+  | { status: 'no_message_link' }
+  | {
+      status: 'added'
+      reactionId: string
+      messageId: string
+      emoji: string
+      replaced: number
+    }
+  | {
+      status: 'removed'
+      messageId: string
+      emoji: string
+      deleted: number
+    }
+  | { status: 'noop' }
+
+export const COMMUNICATION_CHANNELS_PROCESS_INBOUND_REACTION_COMMAND_ID =
+  'communication_channels.reaction.process_inbound'
+
+/**
+ * Inbound reaction processor command.
+ *
+ * Per SPEC-045d §5.2:
+ *   1. Look up `MessageChannelLink` by `(channelId, externalMessageId)` via the
+ *      `ExternalMessage` row (which has the unique constraint on that pair).
+ *   2. For `added`: apply per-provider semantics
+ *      - `multiReactionPerUser=true` (Slack): insert; existing reactions from the
+ *        same reactor are preserved.
+ *      - `multiReactionPerUser=false` (WhatsApp): delete all existing reactions
+ *        from the same reactor for the same message, then insert the new one.
+ *   3. For `removed`: delete matching `MessageReaction` rows for
+ *      `(messageId, emoji, reactedByExternalId)`. If `externalReactionId` is
+ *      provided, prefer that as the lookup key.
+ *   4. Emit `communication_channels.reaction.added` or `.removed`.
+ *
+ * The command is idempotent: re-running it for the same `externalReactionId` will
+ * be a no-op for `added` (unique constraint blocks duplicates) and harmless for
+ * `removed` (delete-where-not-found returns 0).
+ */
+const processInboundReactionCommand: CommandHandler<
+  ProcessInboundReactionInput,
+  ProcessInboundReactionResult
+> = {
+  id: COMMUNICATION_CHANNELS_PROCESS_INBOUND_REACTION_COMMAND_ID,
+  async execute(rawInput, ctx) {
+    const input = processInboundReactionInputSchema.parse(rawInput) as ProcessInboundReactionInput
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const dscope = {
+      tenantId: input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? null,
+    }
+
+    // (1) Find the platform Message via ExternalMessage → MessageChannelLink.
+    const externalMessage = await findOneWithDecryption(
+      em,
+      ExternalMessage,
+      {
+        channelId: input.channelId,
+        externalMessageId: input.event.externalMessageId,
+        tenantId: input.scope.tenantId,
+        organizationId: input.scope.organizationId ?? null,
+      },
+      undefined,
+      dscope,
+    )
+    if (!externalMessage) {
+      // The reaction targets a message we never ingested (e.g., reaction to a
+      // history-only message we skipped). Skip silently.
+      return { status: 'no_message_link' }
+    }
+
+    const channelLink = await findOneWithDecryption(
+      em,
+      MessageChannelLink,
+      {
+        externalMessageId: externalMessage.id,
+        tenantId: input.scope.tenantId,
+        organizationId: input.scope.organizationId ?? null,
+      },
+      undefined,
+      dscope,
+    )
+    if (!channelLink) {
+      return { status: 'no_message_link' }
+    }
+
+    const messageId = channelLink.messageId
+
+    // (2) Resolve channel capabilities for semantics decision.
+    const channel = await findOneWithDecryption(
+      em,
+      CommunicationChannel,
+      {
+        id: input.channelId,
+        tenantId: input.scope.tenantId,
+        organizationId: input.scope.organizationId ?? null,
+        deletedAt: null,
+      },
+      undefined,
+      dscope,
+    )
+    const capabilities = (channel?.capabilities as ChannelCapabilities | null) ?? null
+
+    if (input.event.action === 'added') {
+      const mutation = resolveInboundAddMutation(capabilities)
+      let replaced = 0
+
+      if (mutation === 'replace') {
+        // WhatsApp-style: delete prior reactions from the same reactor.
+        const existing = await findWithDecryption(
+          em,
+          MessageReaction,
+          {
+            messageId,
+            reactedByExternalId: input.event.userIdentifier,
+            tenantId: input.scope.tenantId,
+            organizationId: input.scope.organizationId ?? null,
+          },
+          undefined,
+          dscope,
+        )
+        replaced = existing.length
+        for (const row of existing) em.remove(row)
+        await em.flush()
+      }
+
+      // Insert the new reaction. On a partial actor unique-index conflict,
+      // treat as no-op — provider sent the same reaction twice.
+      let reaction: MessageReaction
+      try {
+        reaction = em.create(MessageReaction, {
+          messageId,
+          emoji: input.event.emoji,
+          reactedByUserId: null,
+          reactedByExternalId: input.event.userIdentifier,
+          reactedByDisplayName: input.event.userDisplayName ?? null,
+          providerKey: input.providerKey,
+          externalReactionId: input.event.externalReactionId ?? null,
+          tenantId: input.scope.tenantId,
+          organizationId: input.scope.organizationId ?? null,
+        })
+        em.persist(reaction)
+        await em.flush()
+      } catch (err) {
+        // Unique constraint violation → idempotent skip.
+        if (isUniqueViolation(err)) {
+          return { status: 'noop' }
+        }
+        throw err
+      }
+
+      await emitCommunicationChannelsEvent(
+        'communication_channels.reaction.added',
+        {
+          reactionId: reaction.id,
+          messageId,
+          channelLinkId: channelLink.id,
+          channelId: input.channelId,
+          providerKey: input.providerKey,
+          channelType: input.channelType,
+          emoji: input.event.emoji,
+          reactedByExternalId: input.event.userIdentifier,
+          reactedByDisplayName: input.event.userDisplayName ?? null,
+          allowsMultiplePerUser: allowsMultipleReactionsPerUser(capabilities),
+          tenantId: input.scope.tenantId,
+          organizationId: input.scope.organizationId ?? null,
+        },
+        { persistent: true },
+      )
+
+      return {
+        status: 'added',
+        reactionId: reaction.id,
+        messageId,
+        emoji: input.event.emoji,
+        replaced,
+      }
+    }
+
+    // input.event.action === 'removed'
+    const filter: Record<string, unknown> = {
+      messageId,
+      reactedByExternalId: input.event.userIdentifier,
+      emoji: input.event.emoji,
+      tenantId: input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? null,
+    }
+    if (input.event.externalReactionId) {
+      filter.externalReactionId = input.event.externalReactionId
+    }
+    const toDelete = await findWithDecryption(
+      em,
+      MessageReaction,
+      filter,
+      undefined,
+      dscope,
+    )
+    for (const row of toDelete) em.remove(row)
+    await em.flush()
+
+    if (toDelete.length > 0) {
+      await emitCommunicationChannelsEvent(
+        'communication_channels.reaction.removed',
+        {
+          messageId,
+          channelLinkId: channelLink.id,
+          channelId: input.channelId,
+          providerKey: input.providerKey,
+          channelType: input.channelType,
+          emoji: input.event.emoji,
+          reactedByExternalId: input.event.userIdentifier,
+          deletedCount: toDelete.length,
+          tenantId: input.scope.tenantId,
+          organizationId: input.scope.organizationId ?? null,
+        },
+        { persistent: true },
+      )
+    }
+
+    return {
+      status: 'removed',
+      messageId,
+      emoji: input.event.emoji,
+      deleted: toDelete.length,
+    }
+  },
+}
+
+registerCommand(processInboundReactionCommand)
+
+export default processInboundReactionCommand

package/src/modules/communication_channels/commands/push-register.ts

@@ -0,0 +1,203 @@
+import { z } from 'zod'
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CommunicationChannel } from '../data/entities'
+import { getChannelAdapterRegistry } from '../lib/adapter-registry-singleton'
+import { refreshCredentialsIfNeeded } from '../lib/credential-refresh'
+import { emitCommunicationChannelsEvent } from '../events'
+import type { PushRegistration } from '../lib/adapter'
+
+/**
+ * Spec C § Phase C5 — Register provider push delivery for a channel.
+ *
+ * Resolves credentials + tenant OAuth client config, then calls
+ * `adapter.registerPush(...)`. Applies the returned state patch to
+ * `channel.channelState` and flips `pollIntervalSeconds` to the
+ * adapter's recommendation (or leaves it as-is on failure so polling
+ * fallback continues).
+ *
+ * Idempotent: calling on a channel that already has `pushStatus='active'`
+ * is OK — the adapter re-issues the underlying registration and we update
+ * the cursor / expiry to the new value.
+ */
+
+export const pushRegisterSchema = z.object({
+  channelId: z.string().uuid(),
+})
+
+export interface PushRegisterScope {
+  tenantId: string
+  organizationId: string
+  userId?: string | null
+}
+
+export interface PushRegisterResult {
+  channelId: string
+  pushStatus: 'active' | 'failed'
+  channelState: Record<string, unknown>
+  error?: { code: string; message: 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>
+}
+
+export async function pushRegister(params: {
+  container: AwilixContainer
+  scope: PushRegisterScope
+  input: { channelId: string }
+}): Promise<PushRegisterResult> {
+  const input = pushRegisterSchema.parse(params.input)
+  const { container, scope } = params
+
+  const em = (container.resolve('em') as EntityManager).fork()
+  const dscope = { tenantId: scope.tenantId, organizationId: scope.organizationId }
+
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    {
+      id: input.channelId,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    dscope,
+  )
+  if (!channel) {
+    throw createCrudFormError(
+      'Channel not found',
+      { channelId: 'Channel not found' },
+      { status: 404 },
+    )
+  }
+  if (!channel.isActive || channel.status !== 'connected') {
+    throw createCrudFormError(
+      'Channel must be connected to register push',
+      { channelId: `Channel status is ${channel.status}` },
+      { status: 400 },
+    )
+  }
+
+  const adapter = getChannelAdapterRegistry().get(channel.providerKey)
+  if (!adapter) {
+    throw createCrudFormError(
+      'Channel provider is not available',
+      { channelId: `No adapter for provider "${channel.providerKey}"` },
+      { status: 400 },
+    )
+  }
+  if (typeof adapter.registerPush !== 'function') {
+    throw createCrudFormError(
+      'Push delivery is not supported on this provider',
+      { channelId: `Provider "${channel.providerKey}" does not implement registerPush` },
+      { status: 409 },
+    )
+  }
+
+  // Credentials.
+  let credentialsService: CredentialsServiceLike | null = null
+  try {
+    credentialsService = container.resolve('integrationCredentialsService') as CredentialsServiceLike
+  } catch {
+    credentialsService = null
+  }
+  const credentialsScope = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: channel.userId ?? null,
+  }
+  let credentials: Record<string, unknown> = {}
+  if (channel.credentialsRef && credentialsService) {
+    try {
+      credentials =
+        (await credentialsService.resolve(`channel_${channel.providerKey}`, credentialsScope)) ?? {}
+    } catch {
+      credentials = {}
+    }
+  }
+  const refreshed = await refreshCredentialsIfNeeded(
+    { adapter, channelId: channel.id, credentials, scope: credentialsScope },
+    { credentialsService },
+  )
+  credentials = refreshed.credentials
+
+  // Per-provider provider config.
+  let providerConfig: Record<string, unknown> | undefined
+  let notificationUrl = ''
+
+  if (channel.providerKey === 'gmail') {
+    const topic = process.env.OM_GMAIL_PUBSUB_TOPIC
+    providerConfig = { pubsubTopic: topic ?? '' }
+    notificationUrl = '' // Gmail does not use a per-call URL; Pub/Sub subscription is preconfigured.
+  }
+
+  let registration: PushRegistration
+  try {
+    registration = await adapter.registerPush({
+      channelId: channel.id,
+      credentials,
+      scope: { tenantId: scope.tenantId, organizationId: scope.organizationId },
+      notificationUrl,
+      providerConfig,
+    })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'registerPush threw'
+    throw createCrudFormError(
+      'Push registration failed',
+      { channelId: message.slice(0, 500) },
+      { status: 502 },
+    )
+  }
+
+  // Persist results.
+  const previousState = (channel.channelState as Record<string, unknown> | null) ?? {}
+  channel.channelState = { ...previousState, ...registration.channelStatePatch }
+  if (registration.status === 'active' && typeof registration.recommendedPollIntervalSeconds === 'number') {
+    channel.pollIntervalSeconds = registration.recommendedPollIntervalSeconds
+  }
+  await em.flush()
+
+  if (registration.status === 'active') {
+    await emitCommunicationChannelsEvent(
+      'communication_channels.push.registered',
+      {
+        channelId: channel.id,
+        providerKey: channel.providerKey,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+      },
+      { persistent: true },
+    )
+  } else {
+    await emitCommunicationChannelsEvent(
+      'communication_channels.push.failed',
+      {
+        channelId: channel.id,
+        providerKey: channel.providerKey,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        error: registration.error ?? null,
+      },
+      { persistent: true },
+    )
+  }
+
+  return {
+    channelId: channel.id,
+    pushStatus: registration.status,
+    channelState: (channel.channelState as Record<string, unknown> | null) ?? {},
+    error: registration.error,
+  }
+}

package/src/modules/communication_channels/commands/push-renew.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import type { AwilixContainer } from 'awilix'
+import { pushRegister } from './push-register'
+
+/**
+ * Spec C § Phase C4 — Renew a push registration.
+ *
+ * The renewal action is to call the same `registerPush` adapter method again —
+ * Gmail's `users.watch` is idempotent (it returns a fresh `expiration` and
+ * `historyId`).
+ *
+ * Callers: the daily renewal cron worker (`gmail-renew-watch.ts`). The
+ * operator-facing `POST /push/register` route invokes `pushRegister` directly
+ * without needing this helper.
+ */
+
+export const pushRenewSchema = z.object({
+  channelId: z.string().uuid(),
+})
+
+export interface PushRenewScope {
+  tenantId: string
+  organizationId: string
+  userId?: string | null
+}
+
+export interface PushRenewResult {
+  channelId: string
+  pushStatus: 'active' | 'failed'
+  error?: { code: string; message: string }
+}
+
+export async function pushRenew(params: {
+  container: AwilixContainer
+  scope: PushRenewScope
+  input: { channelId: string }
+}): Promise<PushRenewResult> {
+  const input = pushRenewSchema.parse(params.input)
+  const result = await pushRegister({
+    container: params.container,
+    scope: params.scope,
+    input: { channelId: input.channelId },
+  })
+  return {
+    channelId: result.channelId,
+    pushStatus: result.pushStatus,
+    error: result.error,
+  }
+}