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

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

@@ -0,0 +1,168 @@
+import { z } from 'zod'
+import type { AwilixContainer } from 'awilix'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CommunicationChannel } from '../data/entities'
+import { getChannelAdapterRegistry } from '../lib/adapter-registry-singleton'
+import { refreshCredentialsIfNeeded } from '../lib/credential-refresh'
+import { POLLING_ONLY_DEFAULT_INTERVAL_SECONDS } from '../lib/connect-channel'
+import { emitCommunicationChannelsEvent } from '../events'
+
+/**
+ * Spec C § Phase C5 — Tear down a previously-registered push delivery.
+ *
+ * Called from `disconnect-channel.ts` (per-user disconnect path) so the
+ * provider-side `users.watch` subscription doesn't keep firing
+ * notifications at a webhook that no longer recognises the channel.
+ *
+ * Idempotent + best-effort: a missing registration, a 404 from the provider,
+ * or any adapter error is logged but never raised. The caller still proceeds
+ * with the disconnect (the channel row is cleared regardless of whether the
+ * provider-side teardown succeeded).
+ *
+ * Companion to `commands/push-register.ts` — same lib-style helper shape,
+ * not a `registerCommand`-style command (push lifecycle has no undo).
+ */
+
+export const pushUnregisterSchema = z.object({
+  channelId: z.string().uuid(),
+})
+
+export interface PushUnregisterScope {
+  tenantId: string
+  organizationId: string
+  userId?: string | null
+}
+
+export interface PushUnregisterResult {
+  channelId: string
+  status: 'unregistered' | 'noop' | 'failed'
+  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 pushUnregister(params: {
+  container: AwilixContainer
+  scope: PushUnregisterScope
+  input: { channelId: string }
+}): Promise<PushUnregisterResult> {
+  const input = pushUnregisterSchema.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,
+    },
+    undefined,
+    dscope,
+  )
+  if (!channel) {
+    return { channelId: input.channelId, status: 'noop' }
+  }
+
+  const adapter = getChannelAdapterRegistry().get(channel.providerKey)
+  if (!adapter || typeof adapter.unregisterPush !== 'function') {
+    return { channelId: channel.id, status: 'noop' }
+  }
+
+  const channelState = (channel.channelState as Record<string, unknown> | null) ?? {}
+  const pushStatus = typeof channelState.pushStatus === 'string' ? channelState.pushStatus : null
+  if (!pushStatus || pushStatus === 'inactive') {
+    return { channelId: channel.id, status: 'noop' }
+  }
+
+  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 = {}
+    }
+  }
+  try {
+    const refreshed = await refreshCredentialsIfNeeded(
+      { adapter, channelId: channel.id, credentials, scope: credentialsScope },
+      { credentialsService },
+    )
+    credentials = refreshed.credentials
+  } catch {
+    // Refresh failure is non-fatal — unregister tolerates expired tokens
+    // because the provider will simply return 401, which the adapter swallows
+    // or we ignore below.
+  }
+
+  try {
+    await adapter.unregisterPush({
+      channelId: channel.id,
+      credentials,
+      scope: { tenantId: scope.tenantId, organizationId: scope.organizationId },
+      channelState,
+    })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    console.warn(
+      `[push-unregister] adapter.unregisterPush failed for channel ${channel.id}: ${message}`,
+    )
+    return {
+      channelId: channel.id,
+      status: 'failed',
+      error: { code: 'adapter_unregister_failed', message: message.slice(0, 500) },
+    }
+  }
+
+  // Clear push markers from channel state so a subsequent reconnect starts
+  // fresh.
+  channel.channelState = {
+    ...channelState,
+    pushStatus: 'inactive',
+    watchExpirationMs: null,
+  }
+  // Restore the polling-only default cadence (matching connect) so the channel
+  // keeps working until disconnect itself flips `isActive: false`.
+  channel.pollIntervalSeconds = POLLING_ONLY_DEFAULT_INTERVAL_SECONDS
+  await em.flush()
+
+  await emitCommunicationChannelsEvent(
+    'communication_channels.push.deactivated',
+    {
+      channelId: channel.id,
+      providerKey: channel.providerKey,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      reason: 'unregistered',
+    },
+    { persistent: true },
+  )
+
+  return { channelId: channel.id, status: 'unregistered' }
+}

package/src/modules/communication_channels/commands/queue-import-history.ts

@@ -0,0 +1,180 @@
+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 type {
+  ProgressService,
+  ProgressServiceContext,
+} from '../../progress/lib/progressService'
+import { CommunicationChannel } from '../data/entities'
+import { getChannelAdapterRegistry } from '../lib/adapter-registry-singleton'
+import { COMMUNICATION_CHANNELS_QUEUES, getCommunicationChannelsQueue } from '../lib/queue'
+
+/**
+ * Spec B § Phase B6 — operator-triggered backlog import.
+ *
+ * Validates the channel + adapter capability, creates a `ProgressJob`, then
+ * enqueues a `channel-import-history` job. Returns the job id so the UI can
+ * track progress via the existing ProgressTopBar.
+ *
+ * Concurrency guard: at most one in-flight import per channel — a second call
+ * while the first is still running returns a 429 envelope via
+ * `createCrudFormError`. The worker itself runs with `concurrency: 1` so a
+ * dropped guard is still safe.
+ */
+
+export const queueImportHistorySchema = z.object({
+  channelId: z.string().uuid(),
+  sinceDays: z.number().int().min(1).max(365).default(30),
+  contactEmails: z
+    .array(z.string().email().max(255))
+    .max(200)
+    .optional(),
+  maxMessages: z.number().int().min(1).max(5000).default(1000),
+})
+
+export type QueueImportHistoryInput = z.infer<typeof queueImportHistorySchema>
+
+export interface QueueImportHistoryScope {
+  tenantId: string
+  organizationId: string
+  userId?: string | null
+}
+
+export interface QueueImportHistoryResult {
+  progressJobId: string
+  totalCountHint: number
+}
+
+export const CHANNEL_IMPORT_HISTORY_JOB_TYPE = 'communication_channels.channel.import_history'
+
+export interface ChannelImportHistoryJobPayload {
+  progressJobId: string
+  channelId: string
+  sinceDays: number
+  contactEmails?: string[]
+  maxMessages: number
+  scope: { tenantId: string; organizationId: string }
+}
+
+export async function queueImportHistory(params: {
+  container: AwilixContainer
+  scope: QueueImportHistoryScope
+  input: QueueImportHistoryInput
+}): Promise<QueueImportHistoryResult> {
+  const input = queueImportHistorySchema.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') {
+    // 409 (not 400): the request is well-formed but the channel is in a
+    // conflicting state (requires_reauth / error / disconnected). The UI maps
+    // this to the localized "reconnect first" flash; see spec § API Contracts.
+    throw createCrudFormError(
+      'Channel is not connected',
+      { channelId: 'Channel must be connected to import history' },
+      { status: 409 },
+    )
+  }
+
+  // Adapter must declare `importHistory` — Gmail / IMAP adapters gain it
+  // in Spec C. Other providers (chat, SMS) cannot do historical inbox sweeps.
+  const adapter = getChannelAdapterRegistry().get(channel.providerKey)
+  if (!adapter) {
+    throw createCrudFormError(
+      'Channel provider is not available',
+      { channelId: `No adapter registered for provider "${channel.providerKey}"` },
+      { status: 400 },
+    )
+  }
+  if (typeof adapter.importHistory !== 'function') {
+    throw createCrudFormError(
+      'History import is not supported on this provider',
+      { channelId: `Provider "${channel.providerKey}" does not support history import yet` },
+      { status: 400 },
+    )
+  }
+
+  const progressService = container.resolve('progressService') as ProgressService
+  const progressContext: ProgressServiceContext = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId ?? null,
+  }
+
+  // Concurrency guard (best-effort): refuse if another import is already
+  // in-flight for the same channel. We can't query by meta in a portable way
+  // without DB-specific JSON operators, so we scan the small active-jobs window.
+  // This check and `createJob` below are NOT atomic — two near-simultaneous
+  // requests for the same channel can both pass and enqueue. That is acceptable,
+  // not corrupting: the import worker runs at concurrency 1 (duplicate jobs run
+  // sequentially, never in parallel) and inbound ingest dedups by the
+  // `(channel_id, external_message_id)` unique index, so the worst case is
+  // wasted re-fetch work, never duplicate rows.
+  const active = await progressService.getActiveJobs(progressContext)
+  const conflict = active.find((job) => {
+    if (job.jobType !== CHANNEL_IMPORT_HISTORY_JOB_TYPE) return false
+    const meta = (job.meta ?? {}) as Record<string, unknown>
+    return meta.channelId === channel.id
+  })
+  if (conflict) {
+    throw createCrudFormError(
+      'An import is already in progress for this channel',
+      { channelId: 'Another history import is already running' },
+      { status: 429 },
+    )
+  }
+
+  const progressJob = await progressService.createJob(
+    {
+      jobType: CHANNEL_IMPORT_HISTORY_JOB_TYPE,
+      name: `Import history: ${channel.displayName ?? channel.externalIdentifier ?? channel.providerKey}`,
+      description: `Import up to ${input.maxMessages} messages from the last ${input.sinceDays} days`,
+      totalCount: input.maxMessages,
+      cancellable: true,
+      meta: {
+        channelId: channel.id,
+        providerKey: channel.providerKey,
+        sinceDays: input.sinceDays,
+        contactEmailsCount: input.contactEmails?.length ?? 0,
+        maxMessages: input.maxMessages,
+      },
+    },
+    progressContext,
+  )
+
+  const payload: ChannelImportHistoryJobPayload = {
+    progressJobId: progressJob.id,
+    channelId: channel.id,
+    sinceDays: input.sinceDays,
+    contactEmails: input.contactEmails,
+    maxMessages: input.maxMessages,
+    scope: { tenantId: scope.tenantId, organizationId: scope.organizationId },
+  }
+  const queue = getCommunicationChannelsQueue(COMMUNICATION_CHANNELS_QUEUES.importHistory)
+  await queue.enqueue(payload as unknown as Record<string, unknown>)
+
+  return { progressJobId: progressJob.id, totalCountHint: input.maxMessages }
+}

package/src/modules/communication_channels/commands/reassign-conversation.ts

@@ -0,0 +1,273 @@
+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 { extractUndoPayload as extractSharedUndoPayload } from '@open-mercato/shared/lib/commands/undo'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { ChannelThreadMapping, ExternalConversation } from '../data/entities'
+import { emitCommunicationChannelsEvent } from '../events'
+
+const reassignConversationSchema = z.object({
+  threadId: z.string().uuid(),
+  /** Set to `null` to unassign the conversation. */
+  assignedUserId: z.string().uuid().nullable(),
+  scope: z.object({
+    tenantId: z.string().uuid(),
+    organizationId: z.string().uuid().nullable(),
+  }),
+})
+
+export type ReassignConversationInput = z.infer<typeof reassignConversationSchema>
+
+export type ReassignConversationResult =
+  | {
+      status: 'reassigned'
+      threadId: string
+      previousAssignedUserId: string | null
+      nextAssignedUserId: string | null
+      conversationId: string
+      undo: ReassignConversationUndoSnapshot
+    }
+  | { status: 'no_channel_link'; reason: string }
+  | { status: 'invalid_assignee'; reason: string }
+  | { status: 'noop'; reason: string }
+
+export interface ReassignConversationUndoSnapshot {
+  threadMappingId: string
+  conversationId: string
+  // Optional for backward compatibility with log entries written before tenant
+  // scoping was added to the undo lookup; new snapshots always set it.
+  tenantId?: string
+  previousAssignedUserId: string | null
+  newAssignedUserId: string | null
+}
+
+export const COMMUNICATION_CHANNELS_REASSIGN_CONVERSATION_COMMAND_ID =
+  'communication_channels.conversation.reassign'
+
+/**
+ * Reassign the owning user of a channel-linked conversation.
+ *
+ * Updates both `ChannelThreadMapping.assignedUserId` and the linked
+ * `ExternalConversation.assignedUserId` so subscribers (notification handlers,
+ * future dashboards) see a consistent owner. No external provider call —
+ * reassignment is an internal-routing concern.
+ *
+ * Idempotent: when the new owner matches the existing one, returns `noop`.
+ *
+ * The command is undoable: the `before` snapshot captures the previous owner on
+ * both rows so undo can restore them atomically.
+ */
+const reassignConversationCommand: CommandHandler<
+  ReassignConversationInput,
+  ReassignConversationResult
+> = {
+  id: COMMUNICATION_CHANNELS_REASSIGN_CONVERSATION_COMMAND_ID,
+  // Explicitly undoable (the bus also infers this from `undo` below, but
+  // declaring it keeps undoability from silently dropping under a refactor).
+  isUndoable: true,
+  async execute(rawInput, ctx) {
+    const input = reassignConversationSchema.parse(rawInput) as ReassignConversationInput
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const dscope = {
+      tenantId: input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? null,
+    }
+
+    const mapping = await findOneWithDecryption(
+      em,
+      ChannelThreadMapping,
+      {
+        messageThreadId: input.threadId,
+        tenantId: input.scope.tenantId,
+        organizationId: input.scope.organizationId ?? null,
+      },
+      // `message_thread_id` is non-unique (only `(external_conversation_id,
+      // tenant_id)` is unique). The 1:1 thread↔mapping invariant holds in v1,
+      // but order deterministically so a future many-conversations-per-thread
+      // merge can never resolve an arbitrary mapping here.
+      { orderBy: { createdAt: 'asc' } },
+      dscope,
+    )
+    if (!mapping) {
+      return {
+        status: 'no_channel_link',
+        reason: `no ChannelThreadMapping for thread ${input.threadId}`,
+      }
+    }
+
+    const previousAssignedUserId = mapping.assignedUserId ?? null
+    if (previousAssignedUserId === input.assignedUserId) {
+      return { status: 'noop', reason: 'assigned user unchanged' }
+    }
+
+    // Reject an assignee that is not a live user of this tenant — a UUID-shaped
+    // body alone must not create a cross-tenant / dangling owner reference.
+    if (input.assignedUserId) {
+      // Reference the `auth` user row by string entity name so this command does
+      // not import the auth module's entities (module independence); `as never`
+      // matches the codebase pattern for cross-module decrypted reads.
+      const assignee = await findOneWithDecryption(
+        em,
+        'User' as never,
+        { id: input.assignedUserId, tenantId: input.scope.tenantId, deletedAt: null } as never,
+        undefined,
+        dscope,
+      )
+      if (!assignee) {
+        return {
+          status: 'invalid_assignee',
+          reason: 'assigned user is not a member of this tenant',
+        }
+      }
+    }
+
+    const conversation = await findOneWithDecryption(
+      em,
+      ExternalConversation,
+      {
+        id: mapping.externalConversationId,
+        tenantId: input.scope.tenantId,
+        organizationId: input.scope.organizationId ?? null,
+      },
+      undefined,
+      dscope,
+    )
+    if (!conversation) {
+      return {
+        status: 'no_channel_link',
+        reason: `no ExternalConversation for thread ${input.threadId}`,
+      }
+    }
+
+    // `assignedUserId` is an advisory routing pointer, not a DB foreign key
+    // (modules don't share ORM relations). The assignee-existence check above
+    // and this write are not atomic, so a user deleted in between leaves a
+    // harmless dangling pointer — consistent with the module's no-FK design.
+    mapping.assignedUserId = input.assignedUserId
+    conversation.assignedUserId = input.assignedUserId
+    await em.flush()
+
+    try {
+      await emitCommunicationChannelsEvent(
+        'communication_channels.conversation.reassigned',
+        {
+          conversationId: conversation.id,
+          channelId: mapping.channelId,
+          messageThreadId: input.threadId,
+          previousAssignedUserId,
+          assignedUserId: input.assignedUserId,
+          tenantId: input.scope.tenantId,
+          organizationId: input.scope.organizationId ?? null,
+        },
+        { persistent: true },
+      )
+    } catch (emitErr) {
+      // Best-effort lifecycle/workflow-trigger signal — a bus failure must not
+      // abort the reassignment (the rows are already committed above).
+      console.warn(
+        '[communication_channels:reassign-conversation] reassigned event emit failed:',
+        emitErr instanceof Error ? emitErr.message : emitErr,
+      )
+    }
+
+    const undo: ReassignConversationUndoSnapshot = {
+      threadMappingId: mapping.id,
+      conversationId: conversation.id,
+      tenantId: mapping.tenantId,
+      previousAssignedUserId,
+      newAssignedUserId: input.assignedUserId,
+    }
+
+    return {
+      status: 'reassigned',
+      threadId: input.threadId,
+      previousAssignedUserId,
+      nextAssignedUserId: input.assignedUserId,
+      conversationId: conversation.id,
+      undo,
+    }
+  },
+  // Persist the undo snapshot into the action log. Without this, the command bus
+  // mints an undo token (so the UI offers "Undo") but the snapshot returned from
+  // execute() is never stored, and undo() would silently no-op.
+  async buildLog({ input, result }) {
+    if (result.status !== 'reassigned') return null
+    return {
+      resourceKind: 'communication_channels.channel',
+      resourceId: result.conversationId,
+      tenantId: result.undo.tenantId ?? input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? null,
+      payload: { undo: result.undo },
+      snapshotBefore: result.undo,
+    }
+  },
+  async undo({ ctx, logEntry }) {
+    const snapshot = extractSnapshotFromLog(logEntry)
+    if (!snapshot) return
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    // Never resolve by bare id (cross-tenant). New snapshots always carry
+    // tenantId; refuse the undo if a legacy snapshot lacks it.
+    if (!snapshot.tenantId) return
+    const dscope = { tenantId: snapshot.tenantId, organizationId: null }
+
+    const mapping = await findOneWithDecryption(
+      em,
+      ChannelThreadMapping,
+      { id: snapshot.threadMappingId, tenantId: snapshot.tenantId },
+      undefined,
+      dscope,
+    )
+    const conversation = await findOneWithDecryption(
+      em,
+      ExternalConversation,
+      { id: snapshot.conversationId, tenantId: snapshot.tenantId },
+      undefined,
+      dscope,
+    )
+    if (mapping) mapping.assignedUserId = snapshot.previousAssignedUserId
+    if (conversation) conversation.assignedUserId = snapshot.previousAssignedUserId
+    if (mapping || conversation) await em.flush()
+  },
+}
+
+/**
+ * Read the undo payload defensively — wraps the shared
+ * `@open-mercato/shared/lib/commands/undo.ts` helper with a narrow-by-shape
+ * validation so callers get a strongly-typed snapshot or `null`.
+ *
+ * Kept as a separate export for test ergonomics (tests can mock the snapshot
+ * shape directly without round-tripping through a CommandLogEntry).
+ */
+export function extractUndoPayload(value: unknown): ReassignConversationUndoSnapshot | null {
+  if (!value || typeof value !== 'object') return null
+  const candidate = (value as { undo?: unknown }).undo ?? value
+  if (!candidate || typeof candidate !== 'object') return null
+  const obj = candidate as Record<string, unknown>
+  if (typeof obj.threadMappingId !== 'string' || typeof obj.conversationId !== 'string') return null
+  return {
+    threadMappingId: obj.threadMappingId,
+    conversationId: obj.conversationId,
+    tenantId: typeof obj.tenantId === 'string' ? obj.tenantId : undefined,
+    previousAssignedUserId:
+      typeof obj.previousAssignedUserId === 'string' ? obj.previousAssignedUserId : null,
+    newAssignedUserId: typeof obj.newAssignedUserId === 'string' ? obj.newAssignedUserId : null,
+  }
+}
+
+/**
+ * Pulls the reassignment snapshot from a command log entry — first via the
+ * shared `extractUndoPayload` helper, then through the local shape-validator.
+ * Always falls back to `null` so the undo handler can no-op safely.
+ */
+export function extractSnapshotFromLog(logEntry: unknown): ReassignConversationUndoSnapshot | null {
+  const undo = extractSharedUndoPayload<ReassignConversationUndoSnapshot>(
+    (logEntry ?? null) as never,
+  )
+  if (undo) return extractUndoPayload(undo)
+  return extractUndoPayload(logEntry)
+}
+
+registerCommand(reassignConversationCommand)
+
+export default reassignConversationCommand