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

package/src/modules/customers/lib/personEmailThreads.ts

@@ -0,0 +1,325 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CustomerInteraction } from '../data/entities'
+import { buildEmailVisibilityMikroFilter } from './visibilityFilter'
+
+/**
+ * Read model that turns a Person's email `CustomerInteraction` rows into
+ * Gmail-style threads for the CRM Person page.
+ *
+ * The Person↔email anchor lives only on `CustomerInteraction`
+ * (`interactionType='email'`, `externalMessageId` → `MessageChannelLink.id`).
+ * The thread grouping key and the rich per-message content (From/To/Cc, body,
+ * direction) live in the communication_channels hub. We read the hub entities
+ * by their string class names — the same cross-module pattern used by
+ * `link-channel-message-handler.ts` — so the customers module never imports the
+ * hub's entity classes (root AGENTS.md: no direct ORM relationships between
+ * modules).
+ */
+
+export type EmailThreadDirection = 'inbound' | 'outbound'
+
+export type PersonEmailMessage = {
+  id: string
+  /** Open Mercato `messages.message` id — used as `parentMessageId` when replying so the reply joins this thread. */
+  messageId: string | null
+  /** RFC2822 Message-ID of this email — used as `In-Reply-To` on a reply. */
+  rfcMessageId: string | null
+  /** RFC2822 References chain for this email. */
+  references: string[]
+  direction: EmailThreadDirection
+  fromName: string | null
+  fromEmail: string | null
+  to: string[]
+  cc: string[]
+  subject: string | null
+  bodyText: string | null
+  sentAt: string
+  providerKey: string | null
+}
+
+export type PersonEmailThread = {
+  threadKey: string
+  subject: string | null
+  preview: string | null
+  participants: string[]
+  lastMessageAt: string
+  messageCount: number
+  providerKey: string | null
+  lastDirection: EmailThreadDirection
+  messages: PersonEmailMessage[]
+}
+
+export type BuildPersonEmailThreadsOptions = {
+  personId: string
+  tenantId: string
+  organizationId: string | null
+  viewerUserId: string | null
+  userFeatures: string[] | null | undefined
+  maxThreads?: number
+  maxMessagesPerThread?: number
+}
+
+const DEFAULT_MAX_THREADS = 50
+const DEFAULT_MAX_MESSAGES_PER_THREAD = 200
+const PREVIEW_LENGTH = 140
+
+type JsonRecord = Record<string, unknown>
+
+/** Extracts `{ email, name }[]` from the many shapes a channel address field can take. */
+function extractAddresses(value: unknown): Array<{ email: string; name: string | null }> {
+  const out: Array<{ email: string; name: string | null }> = []
+  const pushOne = (item: unknown): void => {
+    if (typeof item === 'string') {
+      const trimmed = item.trim()
+      if (trimmed) out.push({ email: trimmed, name: null })
+      return
+    }
+    if (item && typeof item === 'object') {
+      const rec = item as JsonRecord
+      const address = typeof rec.address === 'string' ? rec.address.trim() : null
+      const name = typeof rec.name === 'string' && rec.name.trim() ? rec.name.trim() : null
+      if (address) out.push({ email: address, name })
+    }
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) pushOne(item)
+  } else {
+    pushOne(value)
+  }
+  return out
+}
+
+function firstString(...values: unknown[]): string | null {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim().length > 0) return value
+  }
+  return null
+}
+
+function toStringArray(...values: unknown[]): string[] {
+  for (const value of values) {
+    if (Array.isArray(value)) {
+      const strings = value.filter((item): item is string => typeof item === 'string' && item.trim().length > 0)
+      if (strings.length > 0) return strings
+    }
+  }
+  return []
+}
+
+function truncate(value: string | null): string | null {
+  if (!value) return value
+  const collapsed = value.replace(/\s+/g, ' ').trim()
+  if (collapsed.length <= PREVIEW_LENGTH) return collapsed
+  return `${collapsed.slice(0, PREVIEW_LENGTH - 1)}…`
+}
+
+/**
+ * Builds the per-Person email-thread read model. Pure data assembly — callers
+ * are responsible for auth and scoping (tenantId/organizationId required).
+ */
+export async function buildPersonEmailThreads(
+  em: EntityManager,
+  opts: BuildPersonEmailThreadsOptions,
+): Promise<PersonEmailThread[]> {
+  const {
+    personId,
+    tenantId,
+    organizationId,
+    viewerUserId,
+    userFeatures,
+    maxThreads = DEFAULT_MAX_THREADS,
+    maxMessagesPerThread = DEFAULT_MAX_MESSAGES_PER_THREAD,
+  } = opts
+
+  // ── (1) Load the Person's email interactions (the Person↔email anchor) ──
+  const interactionWhere: JsonRecord = {
+    entity: personId,
+    interactionType: 'email',
+    deletedAt: null,
+    tenantId,
+  }
+  if (organizationId) interactionWhere.organizationId = organizationId
+
+  // Per-email visibility (v1: strict owner-only, no admin bypass) — the CRM
+  // Person page applies the SAME rule as every other interactions read path via
+  // `buildEmailVisibilityMikroFilter`, so the Emails tab and the `/interactions`
+  // timeline can never disagree about who sees an email:
+  //   - `visibility = 'shared'` is visible to every user with CRM access to this
+  //     Person (lets a teammate pick up a handed-off thread),
+  //   - `visibility = 'private'` is visible ONLY to its author (the mailbox
+  //     owner) — never to teammates, not even an admin/superadmin (team
+  //     oversight is a deliberate v2 follow-up),
+  //   - legacy/unset rows (`visibility IS NULL`) stay visible so pre-existing
+  //     CRM history is never silently hidden.
+  // Fail-closed: a null viewer (API-key caller) never matches the author arm, so
+  // it only ever sees shared/legacy rows — never anyone's private email.
+  interactionWhere.$or = buildEmailVisibilityMikroFilter({
+    currentUserId: viewerUserId,
+    userFeatures,
+  }).$or
+
+  // `customer_interaction.title`/`body` are encrypted at rest, so reads go
+  // through `findWithDecryption` even though we only consume non-encrypted
+  // columns here — this keeps the encrypted-entity contract intact.
+  const dscope = { tenantId, organizationId: organizationId ?? null }
+  const interactions = (await findWithDecryption(
+    em,
+    CustomerInteraction,
+    interactionWhere as never,
+    { orderBy: { occurredAt: 'desc', createdAt: 'desc' }, limit: maxThreads * 20 },
+    dscope,
+  )) as CustomerInteraction[]
+
+  const linkIdByInteraction = new Map<string, { occurredAt: Date }>()
+  const linkIds: string[] = []
+  for (const interaction of interactions) {
+    const linkId = interaction.externalMessageId
+    if (!linkId || linkIdByInteraction.has(linkId)) continue
+    linkIdByInteraction.set(linkId, { occurredAt: interaction.occurredAt ?? interaction.createdAt })
+    linkIds.push(linkId)
+  }
+  if (linkIds.length === 0) return []
+
+  // ── (2) Resolve MessageChannelLink rows (rich content + direction) ──────
+  const linkWhere: JsonRecord = { id: { $in: linkIds }, tenantId }
+  if (organizationId) linkWhere.organizationId = organizationId
+  const links = (await findWithDecryption(
+    em,
+    'MessageChannelLink' as never,
+    linkWhere as never,
+    undefined,
+    dscope,
+  )) as JsonRecord[]
+
+  // ── (3) Resolve hub Message rows (the authoritative thread grouping) ────
+  const messageIds = Array.from(
+    new Set(
+      links
+        .map((link) => (typeof link.messageId === 'string' ? (link.messageId as string) : null))
+        .filter((value): value is string => !!value),
+    ),
+  )
+  const messageById = new Map<string, JsonRecord>()
+  if (messageIds.length > 0) {
+    const messageWhere: JsonRecord = { id: { $in: messageIds }, tenantId }
+    if (organizationId) messageWhere.organizationId = organizationId
+    const messages = (await findWithDecryption(
+      em,
+      'Message' as never,
+      messageWhere as never,
+      undefined,
+      dscope,
+    )) as JsonRecord[]
+    for (const message of messages) {
+      if (typeof message.id === 'string') messageById.set(message.id, message)
+    }
+  }
+
+  // ── (4) Build per-message DTOs grouped by thread ────────────────────────
+  const threadsByKey = new Map<string, PersonEmailThread>()
+
+  for (const link of links) {
+    const linkId = typeof link.id === 'string' ? (link.id as string) : null
+    if (!linkId) continue
+    const direction: EmailThreadDirection = link.direction === 'outbound' ? 'outbound' : 'inbound'
+    const providerKey = typeof link.providerKey === 'string' ? (link.providerKey as string) : null
+    const payload = (link.channelPayload ?? null) as JsonRecord | null
+    const meta = (link.channelMetadata ?? null) as JsonRecord | null
+    const messageId = typeof link.messageId === 'string' ? (link.messageId as string) : null
+    const message = messageId ? messageById.get(messageId) ?? null : null
+
+    // Outbound addresses live in channelMetadata; inbound in channelPayload.
+    // Prefer the direction-appropriate source, fall back to the other.
+    const primary = direction === 'outbound' ? meta : payload
+    const secondary = direction === 'outbound' ? payload : meta
+    const fromList = extractAddresses(primary?.from ?? secondary?.from)
+    const toList = extractAddresses(primary?.to ?? secondary?.to)
+    const ccList = extractAddresses(primary?.cc ?? secondary?.cc)
+
+    const subject = firstString(
+      primary?.subject,
+      secondary?.subject,
+      typeof message?.subject === 'string' ? message.subject : null,
+    )
+    const bodyText = firstString(
+      direction === 'outbound' ? meta?.bodyText : payload?.text,
+      direction === 'outbound' ? payload?.text : meta?.bodyText,
+      typeof message?.body === 'string' ? message.body : null,
+    )
+
+    const sentAtRaw =
+      (typeof message?.sentAt === 'string' || message?.sentAt instanceof Date
+        ? message.sentAt
+        : null) ??
+      (link.createdAt instanceof Date || typeof link.createdAt === 'string' ? link.createdAt : null) ??
+      linkIdByInteraction.get(linkId)?.occurredAt ??
+      new Date()
+    const sentAt = (sentAtRaw instanceof Date ? sentAtRaw : new Date(sentAtRaw)).toISOString()
+
+    const threadKey =
+      (typeof message?.threadId === 'string' && message.threadId ? message.threadId : null) ??
+      (messageId ? `message:${messageId}` : `link:${linkId}`)
+
+    const dto: PersonEmailMessage = {
+      id: linkId,
+      messageId,
+      rfcMessageId: firstString(primary?.messageId, secondary?.messageId),
+      references: toStringArray(primary?.references, secondary?.references),
+      direction,
+      fromName: fromList[0]?.name ?? null,
+      fromEmail: fromList[0]?.email ?? null,
+      to: toList.map((a) => a.email),
+      cc: ccList.map((a) => a.email),
+      subject,
+      bodyText,
+      sentAt,
+      providerKey,
+    }
+
+    const existing = threadsByKey.get(threadKey)
+    if (existing) {
+      existing.messages.push(dto)
+    } else {
+      threadsByKey.set(threadKey, {
+        threadKey,
+        subject,
+        preview: null,
+        participants: [],
+        lastMessageAt: sentAt,
+        messageCount: 0,
+        providerKey,
+        lastDirection: direction,
+        messages: [dto],
+      })
+    }
+  }
+
+  // ── (5) Finalize thread summaries ───────────────────────────────────────
+  const threads: PersonEmailThread[] = []
+  for (const thread of threadsByKey.values()) {
+    thread.messages.sort((a, b) => a.sentAt.localeCompare(b.sentAt))
+    if (thread.messages.length > maxMessagesPerThread) {
+      thread.messages = thread.messages.slice(thread.messages.length - maxMessagesPerThread)
+    }
+    const last = thread.messages[thread.messages.length - 1]
+    const firstWithSubject = thread.messages.find((m) => m.subject)
+    const participantSet = new Set<string>()
+    for (const message of thread.messages) {
+      // External counterpart = the "from" for inbound, the "to" for outbound.
+      if (message.direction === 'inbound' && message.fromEmail) participantSet.add(message.fromEmail)
+      if (message.direction === 'outbound') message.to.forEach((email) => participantSet.add(email))
+    }
+    thread.subject = firstWithSubject?.subject ?? thread.subject
+    thread.preview = truncate(last?.bodyText ?? null)
+    thread.participants = Array.from(participantSet)
+    thread.lastMessageAt = last?.sentAt ?? thread.lastMessageAt
+    thread.lastDirection = last?.direction ?? thread.lastDirection
+    thread.providerKey = last?.providerKey ?? thread.providerKey
+    thread.messageCount = thread.messages.length
+    threads.push(thread)
+  }
+
+  threads.sort((a, b) => b.lastMessageAt.localeCompare(a.lastMessageAt))
+  return threads.slice(0, maxThreads)
+}

package/src/modules/customers/lib/visibilityFilter.ts

@@ -0,0 +1,152 @@
+import type { FilterQuery } from '@mikro-orm/postgresql'
+import { hasFeature } from '@open-mercato/shared/security/features'
+import { CustomerInteraction } from '../data/entities'
+
+/**
+ * The ACL feature that grants admins the right to see private emails authored
+ * by other users. Declared in `acl.ts` but granted to NO role in v1 (reserved
+ * for the v2 oversight feature — see `callerHasEmailViewPrivate`).
+ */
+export const EMAIL_VIEW_PRIVATE_FEATURE = 'customers.email.view_private'
+
+/**
+ * Returns true when the caller holds the admin override to see ALL private email
+ * interactions. Honours wildcards (`customers.*`, `*`).
+ *
+ * RESERVED FOR v2 — NOT wired in v1. The v1 model is strict owner-only with no
+ * admin bypass: the visibility filters and `canChangeEmailVisibility` ignore
+ * caller features, and `customers.email.view_private` is granted to no role.
+ * Kept (with {@link EMAIL_VIEW_PRIVATE_FEATURE}) so v2 oversight can opt back in
+ * without re-introducing the helper. Do NOT wire this into a read path without
+ * an explicit v2 spec.
+ */
+export function callerHasEmailViewPrivate(userFeatures: string[] | null | undefined): boolean {
+  if (!Array.isArray(userFeatures) || userFeatures.length === 0) return false
+  return hasFeature(userFeatures, EMAIL_VIEW_PRIVATE_FEATURE)
+}
+
+/**
+ * Authorization predicate for CHANGING an email interaction's visibility.
+ *
+ * Personal mailbox privacy (v1: strict owner-only): ONLY the interaction's
+ * author may flip their own email between private/shared — there is no admin
+ * bypass. Non-email rows and no-op changes are always allowed. Mirrors the gate
+ * in the dedicated `PATCH .../visibility` route so the generic interaction-update
+ * path cannot bypass the privacy control. `userFeatures` is reserved for v2.
+ */
+export function canChangeEmailVisibility(opts: {
+  interactionType: string
+  currentVisibility: string | null | undefined
+  nextVisibility: string | null | undefined
+  authorUserId: string | null | undefined
+  actorUserId: string | null | undefined
+  userFeatures: string[] | null | undefined
+}): boolean {
+  if (opts.interactionType !== 'email') return true
+  if ((opts.nextVisibility ?? null) === (opts.currentVisibility ?? null)) return true
+  return Boolean(opts.actorUserId) && opts.authorUserId === opts.actorUserId
+}
+
+export interface ApplyEmailVisibilityFilterOptions {
+  currentUserId: string | null
+  userFeatures: string[] | null | undefined
+}
+
+/**
+ * Adds a `WHERE` predicate to a kysely query so that:
+ *   - Non-email interactions (calls, meetings, tasks) pass through unchanged.
+ *   - Email interactions with `visibility = 'shared'` are visible to all.
+ *   - Email interactions with `visibility = 'private'` are visible ONLY to the
+ *     `authorUserId` (channel owner).
+ *
+ * Personal mailbox privacy (v1: strict owner-only) — there is NO admin bypass:
+ * a private email is hidden from everyone except its author, including
+ * admins/superadmins. `opts.userFeatures` is retained for signature stability
+ * and reserved for the v2 admin-oversight feature.
+ *
+ * The function expects a kysely-style builder whose `.where()` accepts an
+ * expression-builder callback. Returns the same builder for chaining.
+ */
+export function applyEmailVisibilityFilter<T extends { where: (...args: any[]) => T }>(
+  query: T,
+  opts: ApplyEmailVisibilityFilterOptions,
+): T {
+  const currentUserId = opts.currentUserId
+  // A row is hidden ONLY when it is an email explicitly marked `private` and the
+  // caller is not its author. Everything else stays visible, including:
+  //   - non-email interactions (calls, meetings, tasks),
+  //   - emails marked `shared`,
+  //   - legacy/unset rows where `visibility IS NULL` (e.g. email-log entries
+  //     created before per-email visibility shipped) — these must remain
+  //     visible to avoid silently hiding pre-existing CRM history.
+  return query.where((eb: any) =>
+    eb.or([
+      eb('interaction_type', '!=', 'email'),
+      eb('visibility', 'is', null),
+      eb('visibility', '!=', 'private'),
+      currentUserId
+        ? eb('author_user_id', '=', currentUserId)
+        : eb.val(false),
+    ]),
+  )
+}
+
+type RbacServiceLike = {
+  getGrantedFeatures?: (
+    userId: string,
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<string[] | undefined>
+}
+
+/**
+ * Resolve the caller's granted features (wildcard-aware downstream) so a v2
+ * visibility filter could honour the `customers.email.view_private` admin
+ * override. Returns `undefined` when there is no user or the RBAC service is
+ * unavailable — callers MUST treat `undefined` as "no bypass" (fail closed).
+ *
+ * RESERVED FOR v2 — NOT called by any v1 read path. v1 is strict owner-only, so
+ * the read routes pass `userFeatures: undefined` to the filters rather than
+ * resolving features here (which would be a wasted RBAC round-trip). Re-wire
+ * only under an explicit v2 oversight spec.
+ */
+export async function resolveCallerEmailFeatures(
+  container: { resolve: (name: string) => unknown },
+  userId: string | null,
+  tenantId: string | null,
+  organizationId: string | null,
+): Promise<string[] | undefined> {
+  if (!userId) return undefined
+  try {
+    const rbac = container.resolve('rbacService') as RbacServiceLike | undefined
+    if (!rbac?.getGrantedFeatures) return undefined
+    return await rbac.getGrantedFeatures(userId, { tenantId, organizationId })
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * MikroORM equivalent of {@link applyEmailVisibilityFilter}. Returns a
+ * `FilterQuery` fragment to merge (implicit AND) into a `CustomerInteraction`
+ * where-clause so private email rows are excluded for non-owner, non-admin
+ * callers on MikroORM read paths (`findWithDecryption`/`em.find`/`em.count`).
+ *
+ * Mirrors the kysely predicate exactly, including the legacy `visibility IS NULL`
+ * passthrough so pre-existing CRM history is never hidden. Personal mailbox
+ * privacy (v1: strict owner-only): no admin bypass — a private email is hidden
+ * from everyone except its author. `opts.userFeatures` is reserved for v2.
+ */
+export type EmailVisibilityMikroFilter = { $or?: FilterQuery<CustomerInteraction>[] }
+
+export function buildEmailVisibilityMikroFilter(
+  opts: ApplyEmailVisibilityFilterOptions,
+): EmailVisibilityMikroFilter {
+  return {
+    $or: [
+      { interactionType: { $ne: 'email' } },
+      { visibility: null },
+      { visibility: { $ne: 'private' } },
+      ...(opts.currentUserId ? [{ authorUserId: opts.currentUserId }] : []),
+    ],
+  }
+}

package/src/modules/customers/migrations/.snapshot-open-mercato.json

@@ -3703,6 +3703,23 @@
           "enumItems": [],
           "mappedType": "text"
         },
+        "channel_provider_key": {
+          "name": "channel_provider_key",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
         "created_at": {
           "name": "created_at",
           "type": "timestamptz(6)",
@@ -3788,6 +3805,23 @@
           "enumItems": [],
           "mappedType": "uuid"
         },
+        "external_message_id": {
+          "name": "external_message_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
         "guest_permissions": {
           "name": "guest_permissions",
           "type": "jsonb",
@@ -4194,6 +4228,33 @@
           "keyName": "customer_interactions_type_idx",
           "primary": false,
           "unique": false
+        },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "customer_interactions_external_msg_idx",
+          "primary": false,
+          "unique": false,
+          "expression": "create index \"customer_interactions_external_msg_idx\" on \"customer_interactions\" (\"external_message_id\") where \"external_message_id\" is not null"
+        },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "customer_interactions_email_dedupe_uq",
+          "primary": false,
+          "unique": false,
+          "expression": "create unique index \"customer_interactions_email_dedupe_uq\" on \"customer_interactions\" (\"entity_id\", \"external_message_id\") where \"external_message_id\" is not null and \"deleted_at\" is null"
+        },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "customer_interactions_email_visibility_idx",
+          "primary": false,
+          "unique": false,
+          "expression": "create index \"customer_interactions_email_visibility_idx\" on \"customer_interactions\" (\"entity_id\", \"interaction_type\", \"visibility\", \"author_user_id\") where \"interaction_type\" = 'email' and \"deleted_at\" is null"
         }
       ],
       "checks": [],

package/src/modules/customers/migrations/Migration20260527012240_customers.ts

@@ -0,0 +1,23 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260527012240_customers extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "customer_interactions" add "external_message_id" uuid null, add "channel_provider_key" text null;`);
+    // Backfill: pre-existing email-log interactions predate per-email visibility
+    // and have null visibility. Mark them 'shared' so they keep their prior
+    // visible-to-all behavior once the visibility filter is enabled.
+    this.addSql(`update "customer_interactions" set "visibility" = 'shared' where "interaction_type" = 'email' and "visibility" is null and "external_message_id" is null;`);
+    this.addSql(`create index "customer_interactions_external_msg_idx" on "customer_interactions" ("external_message_id") where "external_message_id" is not null;`);
+    this.addSql(`create unique index "customer_interactions_email_dedupe_uq" on "customer_interactions" ("entity_id", "external_message_id") where "external_message_id" is not null and "deleted_at" is null;`);
+    this.addSql(`create index "customer_interactions_email_visibility_idx" on "customer_interactions" ("entity_id", "interaction_type", "visibility", "author_user_id") where "interaction_type" = 'email' and "deleted_at" is null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index if exists "customer_interactions_email_visibility_idx";`);
+    this.addSql(`drop index if exists "customer_interactions_email_dedupe_uq";`);
+    this.addSql(`drop index if exists "customer_interactions_external_msg_idx";`);
+    this.addSql(`alter table "customer_interactions" drop column "external_message_id", drop column "channel_provider_key";`);
+  }
+
+}

package/src/modules/customers/setup.ts

@@ -102,6 +102,7 @@ export const setup: ModuleSetupConfig = {
       'customers.widgets.new-deals',
       'customers.roles.view',
       'customers.roles.manage',
+      'customers.email.compose',
     ],
   },
 }

package/src/modules/customers/subscribers/link-channel-message-received.ts

@@ -0,0 +1,21 @@
+/**
+ * Persistent subscriber for `communication_channels.message.received`.
+ *
+ * When an inbound email arrives, resolves People by address from the linked
+ * MessageChannelLink and creates CustomerInteraction rows (one per match).
+ * Falls back to threading-inheritance (In-Reply-To chain) when no direct
+ * address match is found.
+ *
+ * Logic lives in `../lib/link-channel-message-handler.ts`; both this file
+ * and `link-channel-message-sent.ts` delegate there so the two subscriber
+ * registrations can share a single implementation.
+ */
+import linkChannelMessageHandler from '../lib/link-channel-message-handler'
+
+export const metadata = {
+  event: 'communication_channels.message.received',
+  persistent: true,
+  id: 'customers:link-channel-message-received',
+}
+
+export default linkChannelMessageHandler

package/src/modules/customers/subscribers/link-channel-message-sent.ts

@@ -0,0 +1,21 @@
+/**
+ * Persistent subscriber for `communication_channels.message.sent`.
+ *
+ * When an outbound email is delivered, resolves People by address (or by the
+ * `crmPersonId` hint written by the compose route) and creates CustomerInteraction
+ * rows. Reads `crmVisibility` from `channelMetadata` to set the per-row
+ * visibility ('private' | 'shared').
+ *
+ * Logic lives in `../lib/link-channel-message-handler.ts`; both this file
+ * and `link-channel-message-received.ts` delegate there so the two subscriber
+ * registrations can share a single implementation.
+ */
+import linkChannelMessageHandler from '../lib/link-channel-message-handler'
+
+export const metadata = {
+  event: 'communication_channels.message.sent',
+  persistent: true,
+  id: 'customers:link-channel-message-sent',
+}
+
+export default linkChannelMessageHandler

package/src/modules/integrations/AGENTS.md

@@ -132,6 +132,15 @@ For platform connectors with multiple integrations (e.g., MedusaJS):
 2. If `bundleId` is set, fallback to bundle's credentials
 3. Return `null` if neither exists
 
+## Per-User Credential Scoping
+
+`IntegrationScope` carries an optional `userId?: string | null` (added 2026-05-26 for per-user email channels). Every `createCredentialsService` method scopes by it:
+
+- **Omit `scope.userId`** (or pass `null`) for tenant-wide credentials (shared API keys, e.g. Stripe/Akeneo) — the filter pins `user_id IS NULL`, the historical behaviour.
+- **Pass `scope.userId`** for per-user credentials (Gmail/IMAP mailboxes) — reads and writes land on that user's own row.
+
+Uniqueness across `(integration_id, organization_id, tenant_id, user_id)` is enforced by the partial unique index `integration_credentials_user_lookup_idx` (`WHERE user_id IS NOT NULL AND deleted_at IS NULL`). **Callers MUST thread the correct `userId` on every per-user read AND write** — a tenant-wide scope can never read a user-scoped row and vice versa, so a missing `userId` silently resolves the wrong (or no) credentials.
+
 ## Events
 
 | Event ID | Emitted When |