@open-mercato/core 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

package/src/modules/customers/data/enrichers.ts

@@ -40,6 +40,13 @@ function diffDays(from: Date, to: Date): number {
   return Math.floor((to.getTime() - from.getTime()) / DAY_MS)
 }
 
+/** Coerce an unknown value to a non-empty string array, or null when absent/empty. */
+function stringArrayOrNull(value: unknown): string[] | null {
+  if (!Array.isArray(value)) return null
+  const strings = value.filter((entry): entry is string => typeof entry === 'string')
+  return strings.length > 0 ? strings : null
+}
+
 async function fetchOpenInteractionCounts(
   db: CustomerKysely,
   dealIds: Set<string>,
@@ -207,4 +214,248 @@ const dealPipelineEnricher: ResponseEnricher<DealRecord> = {
   },
 }
 
-export const enrichers: ResponseEnricher[] = [dealPipelineEnricher]
+type PersonRecord = Record<string, unknown> & { id: string }
+
+/**
+ * Adds `_privateEmailCount` to each Person — the number of that person's PRIVATE
+ * email interactions authored by OTHER users (private emails the current viewer
+ * cannot see). Backs the documented "count of teammates' private emails" badge
+ * (see `apps/docs/docs/user-guide/customers-email.mdx`): a viewer learns an
+ * exchange exists without seeing its content. The count-badge UI is a pending
+ * follow-up; the field is populated here so the consumer can be wired without a
+ * second pass. Owner/tenant scoped and fail-safe to 0 — never leaks content.
+ */
+export const privateEmailCountEnricher: ResponseEnricher<
+  PersonRecord,
+  { _privateEmailCount?: number }
+> = {
+  id: 'customers.private-email-count',
+  targetEntity: 'customers.person',
+  features: ['customers.people.view'],
+  priority: 30,
+  timeout: 1500,
+  fallback: { _privateEmailCount: 0 },
+  critical: false,
+
+  async enrichOne(record, context) {
+    const enriched = await this.enrichMany!([record], context)
+    return enriched[0]
+  },
+
+  async enrichMany(records, context: EnricherContext) {
+    if (records.length === 0) return records
+
+    const db = resolveKyselyClient(context.em)
+    if (!db) {
+      return records.map((record) => ({ ...record, _privateEmailCount: 0 }))
+    }
+
+    const userId = context.userId
+    // Fail-safe to 0 when there is no real authoring user to exclude. An API-key
+    // principal (`auth.sub = "api_key:<id>"`) is not a person, so the
+    // `author_user_id != userId` exclusion below would match nothing and count
+    // every private email — short-circuit it here.
+    if (!userId || userId.startsWith('api_key:')) {
+      return records.map((record) => ({ ...record, _privateEmailCount: 0 }))
+    }
+
+    const personIds = records
+      .map((r) => r.id)
+      .filter((id): id is string => typeof id === 'string' && id.length > 0)
+
+    if (personIds.length === 0) {
+      return records.map((record) => ({ ...record, _privateEmailCount: 0 }))
+    }
+
+    const rows = await (db as CustomerKysely)
+      .selectFrom('customer_interactions')
+      .select(['entity_id'])
+      .select((eb) => eb.fn.countAll().as('count'))
+      .where('tenant_id', '=', context.tenantId)
+      .where('organization_id', '=', context.organizationId)
+      .where('interaction_type', '=', 'email')
+      .where('visibility', '=', 'private')
+      .where('deleted_at', 'is', null)
+      .where('entity_id', 'in', personIds)
+      .where('author_user_id', '!=', userId)
+      .groupBy('entity_id')
+      .execute()
+
+    const countMap = new Map<string, number>()
+    for (const row of rows) {
+      const personId = typeof row.entity_id === 'string' ? row.entity_id : null
+      if (!personId) continue
+      const count = typeof row.count === 'number' ? row.count : Number(row.count)
+      if (Number.isFinite(count)) countMap.set(personId, count)
+    }
+
+    return records.map((record) => ({
+      ...record,
+      _privateEmailCount: countMap.get(record.id) ?? 0,
+    }))
+  },
+}
+
+type InteractionRecord = Record<string, unknown> & {
+  id: string
+  interactionType?: string | null
+  externalMessageId?: string | null
+}
+
+type EmailIntegrationFields = {
+  externalMessageId?: string | null
+  rfcMessageId?: string | null
+  fromAddress?: string | null
+  toAddresses?: string[] | null
+  ccAddresses?: string[] | null
+  subject?: string | null
+  inReplyTo?: string | null
+  references?: string[] | null
+  /** Current visibility of the interaction row, for the private/shared toggle. */
+  currentVisibility?: 'private' | 'shared' | null
+  /** True when the interaction's author is the requesting user — gates the toggle. */
+  isAuthor?: boolean
+}
+
+/**
+ * Enriches email-type customer interactions with MessageChannelLink metadata
+ * so the ActivityCard widget can render Reply/Forward/visibility-toggle actions.
+ *
+ * For each interaction row where `interactionType === 'email'` and
+ * `externalMessageId` is set (the MessageChannelLink UUID), the enricher fetches
+ * the corresponding `MessageChannelLink` row and populates
+ * `_integrations.email.*` from its `channel_metadata` column.
+ *
+ * Non-email rows and rows without an externalMessageId pass through unchanged.
+ * Fail-safe: if the Kysely client is unavailable or the lookup fails, the records
+ * are returned unmodified so the activity timeline still renders (without email
+ * card actions).
+ */
+export const interactionEmailCardEnricher: ResponseEnricher<
+  InteractionRecord,
+  { _integrations?: { email?: EmailIntegrationFields } }
+> = {
+  id: 'customers.interaction-email-card',
+  // Must match the entity ID passed to applyResponseEnrichers in the interactions
+  // GET route (api/interactions/route.ts line 539): 'customers.interaction'.
+  targetEntity: 'customers.interaction',
+  features: ['customers.interactions.view'],
+  priority: 25,
+  timeout: 1500,
+  fallback: {},
+  critical: false,
+
+  async enrichOne(record, ctx) {
+    const results = await this.enrichMany!([record], ctx)
+    return results[0]
+  },
+
+  async enrichMany(records, ctx) {
+    if (records.length === 0) return records
+
+    // Fast path: skip the DB round-trip when no email rows with a link are present.
+    const emailRecords = records.filter(
+      (r) =>
+        r.interactionType === 'email' &&
+        typeof r.externalMessageId === 'string' &&
+        r.externalMessageId.length > 0,
+    )
+    if (emailRecords.length === 0) return records
+
+    const linkIds = Array.from(
+      new Set(emailRecords.map((r) => r.externalMessageId as string)),
+    )
+
+    // message_channel_links is owned by communication_channels; its read-only
+    // shape is declared in CustomerKyselyDb so this stays type-safe without
+    // cross-module coupling. Mirrors privateEmailCountEnricher.
+    const kysely = resolveKyselyClient(ctx.em)
+    if (!kysely) {
+      // Fail-safe: Kysely unavailable (test stubs, unusual driver wrappers).
+      return records
+    }
+
+    let linkRows: Array<{ id: string; channel_metadata: unknown }>
+    try {
+      linkRows = await kysely
+        .selectFrom('message_channel_links')
+        .select(['id', 'channel_metadata'])
+        .where('tenant_id', '=', ctx.tenantId)
+        // Defense-in-depth org scope. `id IN linkIds` already binds the lookup
+        // to this org's interactions, and `message_channel_links.organization_id`
+        // is nullable, so we tolerate NULL to avoid dropping legitimate links.
+        .where((eb) =>
+          eb.or([
+            eb('organization_id', '=', ctx.organizationId),
+            eb('organization_id', 'is', null),
+          ]),
+        )
+        .where('id', 'in', linkIds)
+        .execute()
+    } catch {
+      // Fail-safe: unexpected DB error (missing table in test env, schema drift).
+      return records
+    }
+
+    const byLinkId = new Map<string, EmailIntegrationFields>()
+    for (const row of linkRows) {
+      const meta = (row.channel_metadata ?? {}) as Record<string, unknown>
+      const fields: EmailIntegrationFields = {
+        externalMessageId: row.id,
+        rfcMessageId: typeof meta.messageId === 'string' ? meta.messageId : null,
+        fromAddress: typeof meta.from === 'string' ? meta.from : null,
+        toAddresses: stringArrayOrNull(meta.to),
+        ccAddresses: stringArrayOrNull(meta.cc),
+        // bcc is intentionally NOT surfaced: BCC recipients are blind by design,
+        // so exposing them to every teammate who can view a shared email would
+        // leak the blind-copy list. Keep it out of the enriched response.
+        subject: typeof meta.subject === 'string' ? meta.subject : null,
+        inReplyTo: typeof meta.inReplyTo === 'string' ? meta.inReplyTo : null,
+        references: stringArrayOrNull(meta.references),
+      }
+      byLinkId.set(row.id, fields)
+    }
+
+    const currentUserId = ctx.userId
+
+    return records.map((r) => {
+      if (
+        r.interactionType !== 'email' ||
+        typeof r.externalMessageId !== 'string' ||
+        r.externalMessageId.length === 0
+      ) {
+        return r
+      }
+      const fields = byLinkId.get(r.externalMessageId)
+      if (!fields) return r
+      const visibility =
+        r.visibility === 'private' || r.visibility === 'shared' ? r.visibility : null
+      const authorUserId = typeof r.authorUserId === 'string' ? r.authorUserId : null
+      const isAuthor = Boolean(currentUserId && authorUserId && authorUserId === currentUserId)
+      // Fail-closed (defense-in-depth): never surface another user's PRIVATE
+      // email metadata (subject/from/to/references), even if a consumer forgot
+      // to apply the visibility filter upstream. v1 is strict owner-only (no
+      // admin bypass — `customers.email.view_private` is inert until v2), so a
+      // private row is enriched only for its author. The normal read paths
+      // already drop these rows; this keeps the globally-registered enricher
+      // safe-by-construction for any future consumer that opts into it.
+      if (visibility === 'private' && !isAuthor) {
+        return r
+      }
+      const existingIntegrations = (r._integrations ?? {}) as Record<string, unknown>
+      return {
+        ...r,
+        _integrations: {
+          ...existingIntegrations,
+          email: {
+            ...fields,
+            currentVisibility: visibility,
+            isAuthor,
+          },
+        },
+      }
+    })
+  },
+}
+
+export const enrichers: ResponseEnricher[] = [dealPipelineEnricher, privateEmailCountEnricher, interactionEmailCardEnricher]

package/src/modules/customers/data/entities.ts

@@ -1,5 +1,6 @@
 import { Collection, OptionalProps } from '@mikro-orm/core'
 import { Entity, Index, ManyToOne, OneToMany, OneToOne, PrimaryKey, Property, Unique } from '@mikro-orm/decorators/legacy'
+import type { DictionaryEntrySortMode } from '@open-mercato/core/modules/dictionaries/lib/entrySort'
 
 export type CustomerEntityKind = 'person' | 'company'
 export type CustomerAddressFormat = 'line_first' | 'street_first'
@@ -541,8 +542,23 @@ export class CustomerActivity {
   name: 'customer_interactions_type_idx',
   properties: ['tenantId', 'organizationId', 'interactionType'],
 })
+@Index({
+  name: 'customer_interactions_external_msg_idx',
+  expression:
+    `create index "customer_interactions_external_msg_idx" on "customer_interactions" ("external_message_id") where "external_message_id" is not null`,
+})
+@Index({
+  name: 'customer_interactions_email_dedupe_uq',
+  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`,
+})
+@Index({
+  name: 'customer_interactions_email_visibility_idx',
+  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`,
+})
 export class CustomerInteraction {
-  [OptionalProps]?: 'status' | 'pinned' | 'createdAt' | 'updatedAt' | 'deletedAt' | 'durationMinutes' | 'location' | 'allDay' | 'recurrenceRule' | 'recurrenceEnd' | 'participants' | 'reminderMinutes' | 'visibility' | 'linkedEntities' | 'guestPermissions'
+  [OptionalProps]?: 'status' | 'pinned' | 'createdAt' | 'updatedAt' | 'deletedAt' | 'durationMinutes' | 'location' | 'allDay' | 'recurrenceRule' | 'recurrenceEnd' | 'participants' | 'reminderMinutes' | 'visibility' | 'linkedEntities' | 'guestPermissions' | 'externalMessageId' | 'channelProviderKey'
 
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
@@ -562,6 +578,24 @@ export class CustomerInteraction {
   @Property({ name: 'body', type: 'text', nullable: true })
   body?: string | null
 
+  /**
+   * UUID pointing at `communication_channels.message_channel_link.id`.
+   * Set only for rows where `interactionType === 'email'`.
+   *
+   * The cross-module link is declared in `data/extensions.ts` rather than as
+   * a raw FK (root AGENTS.md: no direct ORM relationships between modules).
+   */
+  @Property({ name: 'external_message_id', type: 'uuid', nullable: true })
+  externalMessageId?: string | null
+
+  /**
+   * Denormalized provider key from `MessageChannelLink.providerKey`. Common
+   * values today: 'gmail', 'imap'. Stored as open text so future
+   * providers (e.g. 'slack', 'whatsapp') can register without a schema change.
+   */
+  @Property({ name: 'channel_provider_key', type: 'text', nullable: true })
+  channelProviderKey?: string | null
+
   @Property({ name: 'status', type: 'text', default: 'planned' })
   status: string = 'planned'
 
@@ -613,6 +647,18 @@ export class CustomerInteraction {
   @Property({ name: 'reminder_minutes', type: 'int', nullable: true })
   reminderMinutes?: number | null
 
+  /**
+   * Visibility flag, shared across interaction types but with a per-type
+   * value space:
+   *   - Email rows (interactionType='email'): 'private' | 'shared'.
+   *     Filtered by `lib/visibilityFilter.ts` so private emails are only
+   *     visible only to the channel-owner author (v1 strict owner-only; no admin bypass).
+   *   - Activity rows (call/meeting/task): 'team' | 'public'. Surfaced via
+   *     the ScheduleActivityDialog footer.
+   * Stored as plain text to keep the column reusable for future visibility
+   * vocabularies; the application enforces the per-type vocabulary at the
+   * boundary (API routes, subscribers).
+   */
   @Property({ name: 'visibility', type: 'text', nullable: true })
   visibility?: string | null
 
@@ -750,7 +796,7 @@ export class CustomerAddress {
 @Entity({ tableName: 'customer_settings' })
 @Unique({ name: 'customer_settings_scope_unique', properties: ['organizationId', 'tenantId'] })
 export class CustomerSettings {
-  [OptionalProps]?: 'createdAt' | 'updatedAt' | 'addressFormat' | 'stuckThresholdDays'
+  [OptionalProps]?: 'createdAt' | 'updatedAt' | 'addressFormat' | 'stuckThresholdDays' | 'dictionarySortModes'
 
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
@@ -767,6 +813,9 @@ export class CustomerSettings {
   @Property({ name: 'stuck_threshold_days', type: 'int', default: 14 })
   stuckThresholdDays: number = 14
 
+  @Property({ name: 'dictionary_sort_modes', type: 'jsonb', nullable: true })
+  dictionarySortModes?: Record<string, DictionaryEntrySortMode> | null
+
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 

package/src/modules/customers/data/extensions.ts

@@ -0,0 +1,26 @@
+import type { EntityExtension } from '@open-mercato/shared/modules/entities'
+
+/**
+ * Cross-module entity links declared by the customers module.
+ *
+ * Per root AGENTS.md, modules do NOT form direct ORM relationships across
+ * boundaries. Instead, plain UUID columns reference IDs in other modules and
+ * the link is declared here so the data engine + UI tooling can traverse.
+ *
+ * Canonical EntityExtension shape from `@open-mercato/shared/modules/entities`:
+ *   `{ base, extension, join: { baseKey, extensionKey }, cardinality?, required?, description? }`
+ */
+
+const entityExtensions: EntityExtension[] = [
+  {
+    base: 'customers:customer_interaction',
+    extension: 'communication_channels:message_channel_link',
+    join: { baseKey: 'external_message_id', extensionKey: 'id' },
+    cardinality: 'many-to-one',
+    description:
+      'Links an email CustomerInteraction to the MessageChannelLink that tracks its external channel metadata',
+  },
+]
+
+export const extensions = entityExtensions
+export default entityExtensions

package/src/modules/customers/data/guards.ts

@@ -0,0 +1,67 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { MutationGuard } from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { parseOptimisticLockEnv } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { getAllOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_CONFLICT_ERROR,
+  OPTIMISTIC_LOCK_ENV_VAR,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+function normalizeIsoToken(raw: string): string | null {
+  const ms = Date.parse(raw)
+  if (!Number.isFinite(ms)) return null
+  return new Date(ms).toISOString()
+}
+
+const optimisticLockGuard: MutationGuard = {
+  id: 'customers.optimistic-lock',
+  targetEntity: '*',
+  operations: ['update', 'delete'],
+  priority: 100,
+  async validate(input) {
+    const config = parseOptimisticLockEnv(process.env[OPTIMISTIC_LOCK_ENV_VAR])
+    if (config.mode === 'off') return { ok: true }
+    const enabled = config.mode === 'all' || config.entities.has(input.resourceKind.toLowerCase())
+    if (!enabled) return { ok: true }
+    const readers = getAllOptimisticLockReaders()
+    const reader = readers[input.resourceKind]
+    if (!reader) return { ok: true }
+    const expectedRaw = input.requestHeaders.get(OPTIMISTIC_LOCK_HEADER_NAME)
+    if (!expectedRaw || expectedRaw.trim().length === 0) return { ok: true }
+    const expectedIso = normalizeIsoToken(expectedRaw.trim())
+    if (!expectedIso) return { ok: true }
+    if (!input.resourceId) return { ok: true }
+    const container = await createRequestContainer()
+    let em: EntityManager
+    try {
+      em = container.resolve('em') as EntityManager
+    } catch {
+      return { ok: true }
+    }
+    const currentRaw = await reader(em, {
+      resourceKind: input.resourceKind,
+      resourceId: input.resourceId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId ?? null,
+    })
+    if (currentRaw == null) return { ok: true }
+    const currentIso = normalizeIsoToken(currentRaw)
+    if (currentIso == null) return { ok: true }
+    if (currentIso === expectedIso) return { ok: true }
+    return {
+      ok: false,
+      status: 409,
+      body: {
+        error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
+        code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+        currentUpdatedAt: currentIso,
+        expectedUpdatedAt: expectedIso,
+      },
+    }
+  },
+}
+
+export const guards: MutationGuard[] = [optimisticLockGuard]

package/src/modules/customers/data/validators.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { isValidPhoneNumber } from '@open-mercato/shared/lib/phone'
+import { dictionaryEntrySortModeSchema } from '@open-mercato/core/modules/dictionaries/lib/entrySort'
 
 const uuid = () => z.string().uuid()
 
@@ -9,9 +10,39 @@ export const ACTIVITY_TIME_REQUIRED_MESSAGE_KEY = 'customers.activities.errors.t
 export const ACTIVITY_PHONE_REQUIRED_MESSAGE_KEY = 'customers.activities.errors.phoneRequired'
 export const ACTIVITY_PHONE_INVALID_MESSAGE_KEY = 'customers.activities.errors.phoneInvalid'
 
-const phoneSchema = z.string().trim().max(50).refine((val) => {
-  return isValidPhoneNumber(val)
-}, { message: CUSTOMER_PHONE_INVALID_MESSAGE_KEY }).optional()
+const emptyStringToNull = (value: unknown): unknown => {
+  if (typeof value !== 'string') return value
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : null
+}
+
+const phoneSchema = z.preprocess(
+  emptyStringToNull,
+  z
+    .string()
+    .trim()
+    .max(50)
+    .refine((val) => isValidPhoneNumber(val), { message: CUSTOMER_PHONE_INVALID_MESSAGE_KEY })
+    .nullable()
+    .optional(),
+)
+
+const clearableEmailSchema = z.preprocess(
+  emptyStringToNull,
+  z.string().email().max(320).nullable().optional(),
+)
+
+const clearableUrlSchema = z.preprocess(
+  emptyStringToNull,
+  z.string().url().max(300).nullable().optional(),
+)
+
+// Domain is a plain (non-URL) string that maps to a nullable column, so blanking
+// a previously-set value on edit must transmit null to clear it. See #2529.
+const clearableDomainSchema = z.preprocess(
+  emptyStringToNull,
+  z.string().trim().max(200).nullable().optional(),
+)
 
 const interactionPhoneNumberSchema = z.string().trim().max(50).optional().nullable()
 
@@ -41,12 +72,7 @@ const baseEntitySchema = {
   displayName: displayNameSchema,
   description: z.string().trim().max(4000).optional(),
   ownerUserId: uuid().optional(),
-  primaryEmail: z
-    .string()
-    .trim()
-    .email()
-    .max(320)
-    .optional(),
+  primaryEmail: clearableEmailSchema,
   primaryPhone: phoneSchema,
   status: z.string().trim().max(100).optional(),
   lifecycleStage: z.string().trim().max(100).optional(),
@@ -64,8 +90,8 @@ const personDetailsSchema = {
   department: z.string().trim().max(150).optional(),
   seniority: z.string().trim().max(100).optional(),
   timezone: z.string().trim().max(120).optional(),
-  linkedInUrl: z.string().trim().url().max(300).optional(),
-  twitterUrl: z.string().trim().url().max(300).optional(),
+  linkedInUrl: clearableUrlSchema,
+  twitterUrl: clearableUrlSchema,
   companyEntityId: uuid().nullable().optional(),
 }
 
@@ -75,8 +101,8 @@ const personLastNameSchema = z.string().trim().min(1).max(120)
 const companyDetailsSchema = {
   legalName: z.string().trim().max(200).optional(),
   brandName: z.string().trim().max(200).optional(),
-  domain: z.string().trim().max(200).optional(),
-  websiteUrl: z.string().trim().url().max(300).optional(),
+  domain: clearableDomainSchema,
+  websiteUrl: clearableUrlSchema,
   industry: z.string().trim().max(150).optional(),
   sizeBucket: z.string().trim().max(100).optional(),
   annualRevenue: z.coerce.number().min(0).optional(),
@@ -530,6 +556,12 @@ export const customerStuckThresholdUpsertSchema = scopedSchema.extend({
   stuckThresholdDays: z.number().int().min(1).max(365),
 })
 
+export const customerDictionarySortModesSchema = z.record(z.string(), dictionaryEntrySortModeSchema)
+
+export const customerDictionarySortModesUpsertSchema = scopedSchema.extend({
+  dictionarySortModes: customerDictionarySortModesSchema,
+})
+
 export type PersonCreateInput = z.infer<typeof personCreateSchema>
 export type PersonUpdateInput = z.infer<typeof personUpdateSchema>
 export type CompanyCreateInput = z.infer<typeof companyCreateSchema>
@@ -549,6 +581,7 @@ export type TodoLinkCreateInput = z.infer<typeof todoLinkCreateSchema>
 export type TodoLinkWithTodoCreateInput = z.infer<typeof todoLinkWithTodoCreateSchema>
 export type CustomerSettingsUpsertInput = z.infer<typeof customerSettingsUpsertSchema>
 export type CustomerStuckThresholdUpsertInput = z.infer<typeof customerStuckThresholdUpsertSchema>
+export type CustomerDictionarySortModesUpsertInput = z.infer<typeof customerDictionarySortModesUpsertSchema>
 export type CustomerAddressFormatInput = z.infer<typeof customerAddressFormatSchema>
 export type InteractionCompleteInput = z.infer<typeof interactionCompleteSchema>
 export type InteractionCancelInput = z.infer<typeof interactionCancelSchema>

package/src/modules/customers/di.ts

@@ -1,11 +1,77 @@
 import { asValue } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
 import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { OptimisticLockCurrentReader } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { registerOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 import { CustomerEntity, CustomerAddress, CustomerInteraction } from './data/entities'
 
+const RESOURCE_KIND_COMPANY = 'customers.company'
+// The CRUD factory derives resourceKind via singularize-the-second-segment of
+// the commandId. For `customers.companies.update` it produces 'customers.company'.
+// For `customers.people.update` it does NOT singularize 'people' → 'person' (the
+// irregular plural is preserved), so the runtime resourceKind is
+// 'customers.people'. We register the reader under BOTH names so the
+// env opt-in entry can use either form (`customers.person` per spec or
+// `customers.people` matching the factory's derivation).
+const RESOURCE_KIND_PERSON = 'customers.person'
+const RESOURCE_KIND_PEOPLE = 'customers.people'
+
+const readCustomerCompanyUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => {
+  const row = await em.findOne(
+    CustomerEntity,
+    {
+      id: resourceId,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+      kind: 'company',
+      deletedAt: null,
+    },
+    { fields: ['updatedAt'] as const },
+  )
+  return row?.updatedAt instanceof Date ? row.updatedAt.toISOString() : null
+}
+
+const readCustomerPersonUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => {
+  const row = await em.findOne(
+    CustomerEntity,
+    {
+      id: resourceId,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+      kind: 'person',
+      deletedAt: null,
+    },
+    { fields: ['updatedAt'] as const },
+  )
+  return row?.updatedAt instanceof Date ? row.updatedAt.toISOString() : null
+}
+
+// Hand-wired readers must register at module-load time so they LAND BEFORE
+// the factory's `registerOptimisticLockReaderIfAbsent` calls in
+// `makeCrudRoute`. The discriminator (`kind: 'company' | 'person'`) cannot
+// be expressed by the generic auto-reader because both kinds share the
+// `customer_entities` polymorphic table. Registered unconditionally — the
+// guard's mode check short-circuits when `OM_OPTIMISTIC_LOCK=off`.
+registerOptimisticLockReaders({
+  [RESOURCE_KIND_COMPANY]: readCustomerCompanyUpdatedAt,
+  [RESOURCE_KIND_PERSON]: readCustomerPersonUpdatedAt,
+  [RESOURCE_KIND_PEOPLE]: readCustomerPersonUpdatedAt,
+})
+
 export function register(container: AppContainer) {
   container.register({
     CustomerEntity: asValue(CustomerEntity),
     CustomerAddress: asValue(CustomerAddress),
     CustomerInteraction: asValue(CustomerInteraction),
   })
+  // `crudMutationGuardService` is registered platform-wide in the shared
+  // DI bootstrap (`packages/shared/src/lib/di/container.ts`). It already
+  // resolves the hand-wired readers above from the global store, so this
+  // module no longer needs its own DI binding.
 }

package/src/modules/customers/encryption.ts

@@ -40,6 +40,17 @@ export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
       { field: 'body' },
     ],
   },
+  {
+    // Interactions carry call/meeting notes and, for interactionType='email',
+    // the email subject (title) and body — sensitive PII. Encrypt at rest like
+    // the sibling customer_activity. Read paths use findWithDecryption; the
+    // interactions list route decrypts title/body for the returned page.
+    entityId: 'customers:customer_interaction',
+    fields: [
+      { field: 'title' },
+      { field: 'body' },
+    ],
+  },
   {
     entityId: 'customers:customer_comment',
     fields: [{ field: 'body' }],

package/src/modules/customers/events.ts

@@ -78,6 +78,10 @@ const events = [
   { id: 'customers.person_company_link.created', label: 'Person Linked To Company', entity: 'person_company_link', category: 'crud', clientBroadcast: true },
   { id: 'customers.person_company_link.updated', label: 'Person-Company Link Updated', entity: 'person_company_link', category: 'crud', clientBroadcast: true },
   { id: 'customers.person_company_link.deleted', label: 'Person Unlinked From Company', entity: 'person_company_link', category: 'crud', clientBroadcast: true },
+
+  // ── Email integration (2026-05-27) ────────────────────────────────────────
+  { id: 'customers.email.linked', label: 'Email Linked To Person', entity: 'email_link', category: 'lifecycle', clientBroadcast: true },
+  { id: 'customers.email.visibility_changed', label: 'Email Visibility Changed', entity: 'email_link', category: 'lifecycle', clientBroadcast: true },
 ] as const
 
 export const eventsConfig = createModuleEvents({