@open-mercato/core 0.6.5-develop.4384.1.ce2ec6eaaa → 0.6.5-develop.4397.1.9a65481757

package/src/modules/communication_channels/commands/connect-credential-channel.ts

@@ -0,0 +1,243 @@
+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 type { ChannelAdapterRegistry } from '../lib/registry'
+import { createConnectedChannelRow, MailboxAlreadyConnectedError } from '../lib/connect-channel'
+
+const connectCredentialChannelSchema = z.object({
+  providerKey: z.string().min(1).max(64),
+  displayName: z.string().min(1).max(255),
+  /** Provider-specific credential fields — opaque to the hub; the adapter validates. */
+  credentials: z.record(z.string(), z.unknown()),
+  /** Optional polling interval (seconds) — set when adapter is polling-based. */
+  pollIntervalSeconds: z.number().int().positive().max(86_400).optional(),
+  userId: z.string().uuid(),
+  scope: z.object({
+    tenantId: z.string().uuid(),
+    organizationId: z.string().uuid().nullable(),
+  }),
+})
+
+export type ConnectCredentialChannelInput = z.infer<typeof connectCredentialChannelSchema>
+
+export type ConnectCredentialChannelResult =
+  | { status: 'connected'; channelId: string; externalIdentifier: string | null }
+  | { status: 'validation_failed'; errors: Record<string, string> }
+  | { status: 'no_adapter'; reason: string }
+  | { status: 'duplicate_mailbox'; externalIdentifier: string; existingProviderKey: string }
+
+export const COMMUNICATION_CHANNELS_CONNECT_CREDENTIAL_CHANNEL_COMMAND_ID =
+  'communication_channels.channel.connect_credential'
+
+type CredentialsServiceLike = {
+  save?: (
+    integrationId: string,
+    credentials: Record<string, unknown>,
+    scope: { organizationId: string; tenantId: string; userId?: string | null },
+  ) => Promise<string | void>
+}
+
+/**
+ * Connect a per-user credential-based channel (IMAP, and future basic-auth providers).
+ *
+ * Flow:
+ *   1. Resolve the adapter for `providerKey`.
+ *   2. Call `adapter.validateCredentials?` — adapters that don't implement it
+ *      are accepted optimistically (the hub trusts the adapter to fail on first
+ *      use). Adapters with the method return field-level errors via Zod-like
+ *      `{ ok: false, errors: { fieldName: 'message' } }`; we forward those to
+ *      the caller for `createCrudFormError`.
+ *   3. Persist the credentials encrypted via `integrationCredentialsService.save?` if available.
+ *   4. Create the `CommunicationChannel` row with `userId = currentUser.id`,
+ *      `status = 'connected'`, and the adapter's declared capabilities snapshot.
+ *
+ * The route handler binds the `userId` field from the authenticated session;
+ * the command refuses inputs whose `userId` doesn't pass UUID validation.
+ */
+const connectCredentialChannelCommand: CommandHandler<
+  ConnectCredentialChannelInput,
+  ConnectCredentialChannelResult
+> = {
+  id: COMMUNICATION_CHANNELS_CONNECT_CREDENTIAL_CHANNEL_COMMAND_ID,
+  async execute(rawInput, ctx) {
+    const input = connectCredentialChannelSchema.parse(rawInput) as ConnectCredentialChannelInput
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const adapterRegistry = ctx.container.resolve('channelAdapterRegistry') as ChannelAdapterRegistry
+    const adapter = adapterRegistry.get(input.providerKey)
+    if (!adapter) {
+      return {
+        status: 'no_adapter',
+        reason: `No adapter registered for provider '${input.providerKey}'`,
+      }
+    }
+
+    // Optional credential validation.
+    if (typeof adapter.validateCredentials === 'function') {
+      const validation = await adapter.validateCredentials({
+        providerKey: input.providerKey,
+        credentials: input.credentials,
+        scope: {
+          tenantId: input.scope.tenantId,
+          organizationId: input.scope.organizationId ?? input.scope.tenantId,
+        },
+      })
+      if (!validation.ok) {
+        return {
+          status: 'validation_failed',
+          errors: validation.errors ?? { _form: 'Credential validation failed' },
+        }
+      }
+    }
+
+    // Persist credentials best-effort.
+    let credentialsService: CredentialsServiceLike | null = null
+    try {
+      credentialsService = ctx.container.resolve('integrationCredentialsService') as CredentialsServiceLike
+    } catch {
+      credentialsService = null
+    }
+    // Arg order MUST be (integrationId, credentials, scope) — matches the real
+    // CredentialsService signature. The legacy reversed order swapped the scope
+    // object into the credentials field; see review C1 (2026-05-26).
+    //
+    // `scope.userId` is set so the credentials service writes a per-user row.
+    // Without this, two users on the same tenant share one credentials row
+    // (see review R2-C1 / N1, 2026-05-26).
+    const credentialsScope = {
+      tenantId: input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? input.scope.tenantId,
+      userId: input.userId,
+    }
+    let credentialsRefId: string | null = null
+    let credentialsPersisted = false
+    if (credentialsService?.save) {
+      try {
+        await credentialsService.save(
+          `channel_${input.providerKey}`,
+          { ...input.credentials, userId: input.userId },
+          credentialsScope,
+        )
+        credentialsPersisted = true
+      } catch (err) {
+        console.warn(
+          `[communication_channels:connect_credential] credentials persist failed for ${input.providerKey}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        )
+      }
+      // Resolve the saved row id so we can link channel.credentialsRef. Best-effort.
+      if (credentialsPersisted) {
+        try {
+          const { IntegrationCredentials } = await import(
+            '@open-mercato/core/modules/integrations/data/entities'
+          )
+          const { findOneWithDecryption } = await import(
+            '@open-mercato/shared/lib/encryption/find'
+          )
+          const row = await findOneWithDecryption(
+            em,
+            IntegrationCredentials,
+            {
+              integrationId: `channel_${input.providerKey}`,
+              tenantId: credentialsScope.tenantId,
+              organizationId: credentialsScope.organizationId,
+              userId: credentialsScope.userId,
+              deletedAt: null,
+            },
+            undefined,
+            credentialsScope,
+          )
+          credentialsRefId = (row as { id?: string } | null)?.id ?? null
+        } catch {
+          credentialsRefId = null
+        }
+      }
+    }
+
+    // Mailbox identity for this channel: the email address. IMAP/SMTP credentials
+    // carry it as `fromAddress`; other credential providers may use `username` or
+    // `email`. Normalize emails to lowercase so the cross-provider duplicate guard
+    // and the per-(tenant,user,provider,mailbox) heal index match canonically.
+    const credBag = input.credentials as Record<string, unknown>
+    const rawIdentifier =
+      (typeof credBag.username === 'string' && credBag.username.length > 0 ? credBag.username : null) ??
+      (typeof credBag.email === 'string' && credBag.email.length > 0 ? credBag.email : null) ??
+      (typeof credBag.fromAddress === 'string' && credBag.fromAddress.length > 0
+        ? credBag.fromAddress
+        : null)
+    const externalIdentifier =
+      rawIdentifier && rawIdentifier.includes('@') ? rawIdentifier.toLowerCase() : rawIdentifier
+
+    // Fail-safe: if credentials persistence failed (no `credentialsRef`), the
+    // channel is created in `requires_reauth` + isActive=false so workers
+    // don't poll a channel that has no usable credentials. The user can
+    // reconnect to recover (see review R2-H4 / F6, 2026-05-26).
+    const credentialsAvailable = credentialsRefId !== null
+    let channel
+    try {
+      channel = await createConnectedChannelRow({
+        em,
+        adapter,
+        providerKey: input.providerKey,
+        displayName: input.displayName,
+        externalIdentifier,
+        credentialsRefId,
+        userId: input.userId,
+        scope: { tenantId: input.scope.tenantId, organizationId: input.scope.organizationId ?? null },
+        pollIntervalSeconds: input.pollIntervalSeconds,
+      })
+    } catch (err) {
+      // Same mailbox already connected via another provider — reject so we don't
+      // create a second channel that double-ingests every message.
+      if (err instanceof MailboxAlreadyConnectedError) {
+        return {
+          status: 'duplicate_mailbox',
+          externalIdentifier: err.externalIdentifier,
+          existingProviderKey: err.existingProviderKey,
+        }
+      }
+      throw err
+    }
+
+    // Spec C § Phase C5 — best-effort push registration for providers that
+    // support it (Gmail). Failures persist as `pushStatus='failed'`
+    // on the channel state but do NOT fail the connect — polling fallback
+    // covers the channel until the operator clicks "Re-register push".
+    // Imported lazily to avoid a circular module load (push-register reads
+    // the channel adapter registry, which is initialised after this module).
+    if (credentialsAvailable && input.providerKey === 'gmail') {
+      const adapterSupportsPush =
+        typeof adapter.registerPush === 'function' && typeof adapter.unregisterPush === 'function'
+      const organizationId = input.scope.organizationId
+      if (adapterSupportsPush && organizationId) {
+        try {
+          const { pushRegister } = await import('./push-register')
+          await pushRegister({
+            container: ctx.container,
+            scope: {
+              tenantId: input.scope.tenantId,
+              organizationId,
+              userId: input.userId,
+            },
+            input: { channelId: channel.id },
+          })
+        } catch (err) {
+          // Never fail the connect on push errors — operator can manually
+          // re-register via the dedicated route. Log + continue.
+          console.warn(
+            `[connect-credential-channel] best-effort pushRegister failed for ${channel.id}: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          )
+        }
+      }
+    }
+
+    return { status: 'connected', channelId: channel.id, externalIdentifier }
+  },
+}
+
+registerCommand(connectCredentialChannelCommand)
+
+export default connectCredentialChannelCommand

package/src/modules/communication_channels/commands/delete-channel.ts

@@ -0,0 +1,193 @@
+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 { CommunicationChannel } from '../data/entities'
+import { pushUnregister } from './push-unregister'
+import { emitCommunicationChannelsEvent } from '../events'
+
+const deleteChannelSchema = z.object({
+  channelId: z.string().uuid(),
+  userId: z.string().uuid(),
+  scope: z.object({
+    tenantId: z.string().uuid(),
+    organizationId: z.string().uuid().nullable(),
+  }),
+})
+
+export type DeleteChannelInput = z.infer<typeof deleteChannelSchema>
+
+export type DeleteChannelResult =
+  | { status: 'deleted'; channelId: string; undo: DeleteChannelUndoSnapshot }
+  | { status: 'noop'; reason: string }
+  | { status: 'not_owner'; reason: string }
+
+export interface DeleteChannelUndoSnapshot {
+  channelId: string
+  // Optional only for back-compat with any pre-existing log entries; new
+  // snapshots always set it so the undo lookup stays tenant-scoped.
+  tenantId?: string
+}
+
+export const COMMUNICATION_CHANNELS_DELETE_CHANNEL_COMMAND_ID =
+  'communication_channels.channel.delete'
+
+/**
+ * Soft-delete a per-user channel (sets `deleted_at`) — the channel row only.
+ * Channel re-resolution (polling scheduler, inbound routing) and the
+ * one-primary-per-user unique index already filter `deleted_at IS NULL`, so the
+ * soft-delete stops new ingest into this channel. It does NOT cascade: existing
+ * conversation / message / thread / reaction read-models carry `channelId` /
+ * `conversationId` but are not channel-gated, so they remain readable via joins
+ * until a future retention sweep. `is_primary` is cleared so a later undo cannot
+ * resurrect a second primary for the user (the partial-unique index would
+ * otherwise reject the restore).
+ *
+ * Provider-side push delivery is torn down best-effort BEFORE the soft-delete,
+ * while `credentialsRef` is still present — mirrors `disconnect-channel`.
+ *
+ * Undoable: undo clears `deleted_at` to restore the row. It intentionally does
+ * NOT re-claim primary status (would risk the one-primary-per-user constraint);
+ * the owner re-selects a primary after a restore.
+ */
+const deleteChannelCommand: CommandHandler<DeleteChannelInput, DeleteChannelResult> = {
+  id: COMMUNICATION_CHANNELS_DELETE_CHANNEL_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 = deleteChannelSchema.parse(rawInput) as DeleteChannelInput
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const dscope = {
+      tenantId: input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? null,
+    }
+
+    const channel = await findOneWithDecryption(
+      em,
+      CommunicationChannel,
+      {
+        id: input.channelId,
+        tenantId: input.scope.tenantId,
+        organizationId: input.scope.organizationId ?? null,
+        deletedAt: null,
+      },
+      undefined,
+      dscope,
+    )
+    if (!channel) {
+      return { status: 'noop', reason: 'channel not found' }
+    }
+    if (channel.userId !== input.userId) {
+      return { status: 'not_owner', reason: 'channel is not owned by the current user' }
+    }
+
+    // Tear down provider-side push delivery before the soft-delete, while
+    // credentials are still resolvable. Best-effort — failures are logged inside
+    // pushUnregister and never re-raised.
+    if (input.scope.organizationId) {
+      try {
+        await pushUnregister({
+          container: ctx.container,
+          scope: {
+            tenantId: input.scope.tenantId,
+            organizationId: input.scope.organizationId,
+            userId: input.userId,
+          },
+          input: { channelId: channel.id },
+        })
+      } catch (err) {
+        console.warn(
+          `[delete-channel] push unregister failed for ${channel.id}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        )
+      }
+    }
+
+    channel.deletedAt = new Date()
+    channel.isPrimary = false
+    await em.flush()
+
+    // Emit AFTER flush so subscribers observe the committed soft-delete.
+    // Lifecycle parity with `disconnect` (which emits `channel.disconnected`) so
+    // workflows/audit can observe the full channel lifecycle. Persistent so the
+    // delivery can retry on failure.
+    await emitCommunicationChannelsEvent(
+      'communication_channels.channel.deleted',
+      {
+        channelId: channel.id,
+        userId: input.userId,
+        providerKey: channel.providerKey,
+        channelType: channel.channelType,
+        tenantId: input.scope.tenantId,
+        organizationId: input.scope.organizationId ?? null,
+      },
+      { persistent: true },
+    )
+
+    return {
+      status: 'deleted',
+      channelId: channel.id,
+      undo: { channelId: channel.id, tenantId: channel.tenantId },
+    }
+  },
+  // 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() (which clears deleted_at) would no-op.
+  async buildLog({ input, result }) {
+    if (result.status !== 'deleted') return null
+    return {
+      resourceKind: 'communication_channels.channel',
+      resourceId: result.channelId,
+      tenantId: result.undo.tenantId ?? input.scope.tenantId,
+      organizationId: input.scope.organizationId ?? null,
+      payload: { undo: result.undo },
+    }
+  },
+  async undo({ ctx, logEntry }) {
+    const snapshot = extractSnapshotFromLog(logEntry)
+    if (!snapshot || !snapshot.tenantId) return
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    // Re-find WITHOUT the `deletedAt: null` filter — the row we are restoring is
+    // soft-deleted. Tenant-scoped to avoid cross-tenant resolution by bare id.
+    const channel = await findOneWithDecryption(
+      em,
+      CommunicationChannel,
+      { id: snapshot.channelId, tenantId: snapshot.tenantId },
+      undefined,
+      { tenantId: snapshot.tenantId, organizationId: null },
+    )
+    if (!channel) return
+    channel.deletedAt = null
+    await em.flush()
+  },
+}
+
+/**
+ * Defensive shape-validator for the delete snapshot — mirrors the helper in
+ * `disconnect-channel.ts` so tests can construct snapshots directly.
+ */
+export function extractUndoPayload(value: unknown): DeleteChannelUndoSnapshot | null {
+  if (!value || typeof value !== 'object') return null
+  const candidate = (value as { undo?: unknown; channelId?: unknown }).undo ?? value
+  if (!candidate || typeof candidate !== 'object') return null
+  const obj = candidate as Record<string, unknown>
+  if (typeof obj.channelId !== 'string') return null
+  return {
+    channelId: obj.channelId,
+    tenantId: typeof obj.tenantId === 'string' ? obj.tenantId : undefined,
+  }
+}
+
+function extractSnapshotFromLog(logEntry: unknown): DeleteChannelUndoSnapshot | null {
+  const undo = extractSharedUndoPayload<DeleteChannelUndoSnapshot>((logEntry ?? null) as never)
+  if (undo) return extractUndoPayload(undo)
+  return extractUndoPayload(logEntry)
+}
+
+registerCommand(deleteChannelCommand)
+
+export default deleteChannelCommand