@hed-hog/contact 0.0.279 → 0.0.285

package/src/person/person.service.ts

@@ -4,13 +4,21 @@ import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
 import { Prisma, PrismaService } from '@hed-hog/api-prisma';
 import { FileService, SettingService } from '@hed-hog/core';
 import {
-  BadRequestException,
-  Inject,
-  Injectable,
-  NotFoundException,
-  forwardRef,
+    BadRequestException,
+    Inject,
+    Injectable,
+    NotFoundException,
+    forwardRef,
 } from '@nestjs/common';
+import { CreateFollowupDTO } from './dto/create-followup.dto';
+import {
+    CreateInteractionDTO,
+    PersonInteractionTypeDTO,
+} from './dto/create-interaction.dto';
 import { CreateDTO } from './dto/create.dto';
+import { CheckPersonDuplicatesQueryDTO } from './dto/duplicates-query.dto';
+import { MergePersonDTO } from './dto/merge.dto';
+import { UpdateLifecycleStageDTO } from './dto/update-lifecycle-stage.dto';
 
 const CONTACT_ALLOW_COMPANY_REGISTRATION_SETTING =
   'contact-allow-company-registration';
@@ -23,6 +31,33 @@ const CONTACT_OWNER_ALLOWED_ROLE_SLUGS = [
 type PersonActivityAction = 'created' | 'updated' | 'interaction_created';
 const EMPLOYER_COMPANY_METADATA_KEY = 'employer_company_id';
 const NOTES_METADATA_KEY = 'notes';
+const MERGED_INTO_PERSON_METADATA_KEY = 'merged_into_person_id';
+const OWNER_USER_METADATA_KEY = 'owner_user_id';
+const SOURCE_METADATA_KEY = 'source';
+const LIFECYCLE_STAGE_METADATA_KEY = 'lifecycle_stage';
+const NEXT_ACTION_AT_METADATA_KEY = 'next_action_at';
+const SCORE_METADATA_KEY = 'score';
+const DEAL_VALUE_METADATA_KEY = 'deal_value';
+const TAGS_METADATA_KEY = 'tags';
+const LAST_INTERACTION_AT_METADATA_KEY = 'last_interaction_at';
+const INTERACTIONS_METADATA_KEY = 'interactions';
+
+type DuplicateReason = 'email' | 'phone' | 'document';
+
+type DuplicateMatch = {
+  id: number;
+  name: string;
+  reasons: DuplicateReason[];
+};
+
+type PersonInteractionRecord = {
+  id: number;
+  type: CreateInteractionDTO['type'];
+  notes: string | null;
+  created_at: string;
+  user_id: number | null;
+  user_name: string | null;
+};
 
 @Injectable()
 export class PersonService {
@@ -125,6 +160,227 @@ export class PersonService {
     return Array.from(byId.values());
   }
 
+  async checkDuplicates(query: CheckPersonDuplicatesQueryDTO) {
+    const excludedPersonId = this.coerceNumber(query.person_id);
+    const normalizedEmail = this.normalizeEmail(query.email);
+    const normalizedPhone = this.normalizeDigits(query.phone || '');
+    const normalizedDocument = this.normalizeDigits(query.document_value || '');
+    const documentTypeId = this.coerceNumber(query.document_type_id);
+
+    if (!normalizedEmail && !normalizedPhone && !normalizedDocument) {
+      return { hasDuplicates: false, matches: [] as DuplicateMatch[] };
+    }
+
+    const reasonsByPersonId = new Map<number, Set<DuplicateReason>>();
+
+    if (normalizedEmail) {
+      const emailRows = await this.prismaService.contact.findMany({
+        where: {
+          ...(excludedPersonId > 0
+            ? {
+                person_id: {
+                  not: excludedPersonId,
+                },
+              }
+            : {}),
+          contact_type: {
+            code: {
+              equals: 'EMAIL',
+              mode: 'insensitive',
+            },
+          },
+          value: {
+            equals: normalizedEmail,
+            mode: 'insensitive',
+          },
+        },
+        select: {
+          person_id: true,
+        },
+      });
+
+      for (const row of emailRows) {
+        this.addDuplicateReason(reasonsByPersonId, row.person_id, 'email');
+      }
+    }
+
+    if (normalizedPhone) {
+      const excludedPersonFilter =
+        excludedPersonId > 0
+          ? Prisma.sql` AND c.person_id <> ${excludedPersonId}`
+          : Prisma.empty;
+
+      const phoneRows = await this.prismaService.$queryRaw<
+        Array<{ person_id: number }>
+      >(
+        Prisma.sql`
+          SELECT DISTINCT c.person_id
+          FROM contact c
+          JOIN contact_type ct ON ct.id = c.contact_type_id
+          WHERE UPPER(ct.code) IN ('PHONE', 'MOBILE', 'WHATSAPP')
+            AND regexp_replace(COALESCE(c.value, ''), '[^0-9]+', '', 'g') = ${normalizedPhone}
+            ${excludedPersonFilter}
+        `,
+      );
+
+      for (const row of phoneRows) {
+        this.addDuplicateReason(reasonsByPersonId, row.person_id, 'phone');
+      }
+    }
+
+    if (normalizedDocument) {
+      const excludedPersonFilter =
+        excludedPersonId > 0
+          ? Prisma.sql` AND d.person_id <> ${excludedPersonId}`
+          : Prisma.empty;
+      const documentTypeFilter =
+        documentTypeId > 0
+          ? Prisma.sql` AND d.document_type_id = ${documentTypeId}`
+          : Prisma.empty;
+
+      const documentRows = await this.prismaService.$queryRaw<
+        Array<{ person_id: number }>
+      >(
+        Prisma.sql`
+          SELECT DISTINCT d.person_id
+          FROM document d
+          WHERE regexp_replace(COALESCE(d.value, ''), '[^0-9]+', '', 'g') = ${normalizedDocument}
+            ${excludedPersonFilter}
+            ${documentTypeFilter}
+        `,
+      );
+
+      for (const row of documentRows) {
+        this.addDuplicateReason(reasonsByPersonId, row.person_id, 'document');
+      }
+    }
+
+    const duplicateIds = Array.from(reasonsByPersonId.keys());
+    if (duplicateIds.length === 0) {
+      return { hasDuplicates: false, matches: [] as DuplicateMatch[] };
+    }
+
+    const people = await this.prismaService.person.findMany({
+      where: {
+        id: {
+          in: duplicateIds,
+        },
+      },
+      select: {
+        id: true,
+        name: true,
+      },
+      orderBy: {
+        name: 'asc',
+      },
+    });
+
+    const matches = people.map((person) => ({
+      id: person.id,
+      name: person.name,
+      reasons: Array.from(reasonsByPersonId.get(person.id) || []),
+    }));
+
+    return {
+      hasDuplicates: matches.length > 0,
+      matches,
+    };
+  }
+
+  async merge(data: MergePersonDTO, locale: string) {
+    const sourcePersonId = this.coerceNumber(data.source_person_id);
+    const targetPersonId = this.coerceNumber(data.target_person_id);
+
+    if (sourcePersonId <= 0 || targetPersonId <= 0) {
+      throw new BadRequestException(
+        getLocaleText(
+          'validation.idMustBeInteger',
+          locale,
+          'Source and target person IDs must be valid integers.',
+        ),
+      );
+    }
+
+    if (sourcePersonId === targetPersonId) {
+      throw new BadRequestException(
+        getLocaleText(
+          'personMergeSameRecord',
+          locale,
+          'Source and target person must be different records.',
+        ),
+      );
+    }
+
+    const [sourcePerson, targetPerson] = await Promise.all([
+      this.prismaService.person.findUnique({
+        where: { id: sourcePersonId },
+        select: { id: true, name: true, type: true },
+      }),
+      this.prismaService.person.findUnique({
+        where: { id: targetPersonId },
+        select: { id: true, name: true, type: true },
+      }),
+    ]);
+
+    if (!sourcePerson) {
+      throw new NotFoundException(
+        getLocaleText(
+          'personNotFound',
+          locale,
+          `Person with ID ${sourcePersonId} not found`,
+        ),
+      );
+    }
+
+    if (!targetPerson) {
+      throw new NotFoundException(
+        getLocaleText(
+          'personNotFound',
+          locale,
+          `Person with ID ${targetPersonId} not found`,
+        ),
+      );
+    }
+
+    if (sourcePerson.type !== targetPerson.type) {
+      throw new BadRequestException(
+        getLocaleText(
+          'personMergeTypeMismatch',
+          locale,
+          'Only records with the same type can be merged.',
+        ),
+      );
+    }
+
+    await this.prismaService.$transaction(async (tx) => {
+      await this.mergeContacts(tx, sourcePersonId, targetPersonId);
+      await this.mergeDocuments(tx, sourcePersonId, targetPersonId);
+      await this.mergeAddresses(tx, sourcePersonId, targetPersonId);
+      await this.mergeMetadata(tx, sourcePersonId, targetPersonId);
+
+      await tx.person.update({
+        where: { id: sourcePersonId },
+        data: {
+          status: 'inactive',
+        },
+      });
+
+      await this.upsertMetadataValue(
+        tx,
+        sourcePersonId,
+        MERGED_INTO_PERSON_METADATA_KEY,
+        targetPersonId,
+      );
+    });
+
+    return {
+      success: true,
+      source_person_id: sourcePersonId,
+      target_person_id: targetPersonId,
+      strategy: 'contact_only',
+    };
+  }
+
   async list(
     paginationParams: PaginationDTO & {
       type?: string;
@@ -164,6 +420,54 @@ export class PersonService {
       where.status = paginationParams.status;
     }
 
+    const ownerUserId = this.resolveRequestedOwnerUserId(
+      paginationParams.owner_user_id,
+      paginationParams.mine,
+      currentUserId,
+    );
+
+    const metadataFilters: any[] = [];
+
+    if (ownerUserId > 0) {
+      metadataFilters.push({
+        person_metadata: {
+          some: {
+            key: OWNER_USER_METADATA_KEY,
+            value: ownerUserId as any,
+          },
+        },
+      });
+    }
+
+    if (paginationParams.source && paginationParams.source !== 'all') {
+      metadataFilters.push({
+        person_metadata: {
+          some: {
+            key: SOURCE_METADATA_KEY,
+            value: paginationParams.source as any,
+          },
+        },
+      });
+    }
+
+    if (
+      paginationParams.lifecycle_stage &&
+      paginationParams.lifecycle_stage !== 'all'
+    ) {
+      metadataFilters.push({
+        person_metadata: {
+          some: {
+            key: LIFECYCLE_STAGE_METADATA_KEY,
+            value: paginationParams.lifecycle_stage as any,
+          },
+        },
+      });
+    }
+
+    if (metadataFilters.length > 0) {
+      where.AND = [...(Array.isArray(where.AND) ? where.AND : []), ...metadataFilters];
+    }
+
     if (search) {
       where.OR = await this.buildSearchFilters(search);
     }
@@ -233,6 +537,139 @@ export class PersonService {
     return normalized;
   }
 
+  async listInteractions(id: number, locale: string) {
+    const person = await this.ensurePersonAccessible(id, locale);
+    const metadata = await this.prismaService.person_metadata.findFirst({
+      where: {
+        person_id: person.id,
+        key: INTERACTIONS_METADATA_KEY,
+      },
+      select: {
+        value: true,
+      },
+    });
+
+    return this.metadataToInteractions(metadata?.value);
+  }
+
+  async createInteraction(
+    id: number,
+    data: CreateInteractionDTO,
+    locale: string,
+    user: { id?: number; name?: string | null },
+  ) {
+    const person = await this.ensurePersonAccessible(id, locale);
+    const interaction = this.buildInteractionRecord(data, user);
+
+    await this.prismaService.$transaction(async (tx) => {
+      const currentInteractions = await this.loadInteractionsFromTx(tx, person.id);
+      const nextInteractions = this.sortInteractions([
+        interaction,
+        ...currentInteractions,
+      ]);
+
+      await this.upsertMetadataValue(
+        tx,
+        person.id,
+        INTERACTIONS_METADATA_KEY,
+        nextInteractions,
+      );
+      await this.upsertMetadataValue(
+        tx,
+        person.id,
+        LAST_INTERACTION_AT_METADATA_KEY,
+        interaction.created_at,
+      );
+    });
+
+    return interaction;
+  }
+
+  async scheduleFollowup(
+    id: number,
+    data: CreateFollowupDTO,
+    locale: string,
+    user: { id?: number; name?: string | null },
+  ) {
+    const person = await this.ensurePersonAccessible(id, locale);
+    const normalizedNextActionAt = this.normalizeDateTimeOrNull(data.next_action_at);
+
+    if (!normalizedNextActionAt) {
+      throw new BadRequestException(
+        getLocaleText(
+          'validation.dateMustBeString',
+          locale,
+          'next_action_at must be a valid datetime.',
+        ),
+      );
+    }
+
+    await this.prismaService.$transaction(async (tx) => {
+      await this.upsertMetadataValue(
+        tx,
+        person.id,
+        NEXT_ACTION_AT_METADATA_KEY,
+        normalizedNextActionAt,
+      );
+
+      const notes = this.normalizeTextOrNull(data.notes);
+      if (notes) {
+        const interaction = this.buildInteractionRecord(
+          {
+            type: PersonInteractionTypeDTO.NOTE,
+            notes,
+          },
+          user,
+        );
+        const currentInteractions = await this.loadInteractionsFromTx(tx, person.id);
+        const nextInteractions = this.sortInteractions([
+          interaction,
+          ...currentInteractions,
+        ]);
+
+        await this.upsertMetadataValue(
+          tx,
+          person.id,
+          INTERACTIONS_METADATA_KEY,
+          nextInteractions,
+        );
+        await this.upsertMetadataValue(
+          tx,
+          person.id,
+          LAST_INTERACTION_AT_METADATA_KEY,
+          interaction.created_at,
+        );
+      }
+    });
+
+    return {
+      success: true,
+      next_action_at: normalizedNextActionAt,
+    };
+  }
+
+  async updateLifecycleStage(
+    id: number,
+    data: UpdateLifecycleStageDTO,
+    locale: string,
+  ) {
+    const person = await this.ensurePersonAccessible(id, locale);
+
+    await this.prismaService.$transaction(async (tx) => {
+      await this.upsertMetadataValue(
+        tx,
+        person.id,
+        LIFECYCLE_STAGE_METADATA_KEY,
+        data.lifecycle_stage,
+      );
+    });
+
+    return {
+      success: true,
+      lifecycle_stage: data.lifecycle_stage,
+    };
+  }
+
   async create(data: CreateDTO, locale: string) {
     const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
 
@@ -257,6 +694,13 @@ export class PersonService {
         employer_company_id: allowCompanyRegistration
           ? data.employer_company_id ?? null
           : null,
+        owner_user_id: data.owner_user_id,
+        source: data.source,
+        lifecycle_stage: data.lifecycle_stage,
+        next_action_at: data.next_action_at,
+        score: data.score,
+        deal_value: data.deal_value,
+        tags: data.tags,
       });
 
       return person;
@@ -315,6 +759,13 @@ export class PersonService {
               ? undefined
               : data.employer_company_id
             : null,
+          owner_user_id: data.owner_user_id,
+          source: data.source,
+          lifecycle_stage: data.lifecycle_stage,
+          next_action_at: data.next_action_at,
+          score: data.score,
+          deal_value: data.deal_value,
+          tags: data.tags,
         });
 
         await this.syncContacts(tx, id, incomingContacts);
@@ -487,6 +938,89 @@ export class PersonService {
       }
     }
 
+    const ownerUserIdByPersonId = new Map<number, number>();
+    const sourceByPersonId = new Map<number, string | null>();
+    const lifecycleStageByPersonId = new Map<number, string | null>();
+    const nextActionAtByPersonId = new Map<number, string | null>();
+    const scoreByPersonId = new Map<number, number | null>();
+    const dealValueByPersonId = new Map<number, number | null>();
+    const tagsByPersonId = new Map<number, string[]>();
+    const lastInteractionAtByPersonId = new Map<number, string | null>();
+    const interactionCountByPersonId = new Map<number, number>();
+
+    for (const person of people) {
+      const metadata = this.metadataArrayToMap(person.person_metadata);
+      const ownerUserId = this.metadataToNumber(metadata.get(OWNER_USER_METADATA_KEY));
+      if (ownerUserId > 0) {
+        ownerUserIdByPersonId.set(person.id, ownerUserId);
+      }
+
+      const source = this.metadataToString(metadata.get(SOURCE_METADATA_KEY));
+      if (source) {
+        sourceByPersonId.set(person.id, source);
+      }
+
+      const lifecycleStage = this.metadataToString(
+        metadata.get(LIFECYCLE_STAGE_METADATA_KEY),
+      );
+      if (lifecycleStage) {
+        lifecycleStageByPersonId.set(person.id, lifecycleStage);
+      }
+
+      const nextActionAt = this.metadataToIsoString(
+        metadata.get(NEXT_ACTION_AT_METADATA_KEY),
+      );
+      if (nextActionAt) {
+        nextActionAtByPersonId.set(person.id, nextActionAt);
+      }
+
+      const score = this.metadataToNumber(metadata.get(SCORE_METADATA_KEY));
+      if (score != null) {
+        scoreByPersonId.set(person.id, score);
+      }
+
+      const dealValue = this.metadataToNumber(metadata.get(DEAL_VALUE_METADATA_KEY));
+      if (dealValue != null) {
+        dealValueByPersonId.set(person.id, dealValue);
+      }
+
+      const tags = this.metadataToStringArray(metadata.get(TAGS_METADATA_KEY));
+      if (tags.length > 0) {
+        tagsByPersonId.set(person.id, tags);
+      }
+
+      const lastInteractionAt = this.metadataToIsoString(
+        metadata.get(LAST_INTERACTION_AT_METADATA_KEY),
+      );
+      if (lastInteractionAt) {
+        lastInteractionAtByPersonId.set(person.id, lastInteractionAt);
+      }
+
+      interactionCountByPersonId.set(
+        person.id,
+        this.metadataToInteractions(metadata.get(INTERACTIONS_METADATA_KEY)).length,
+      );
+    }
+
+    const ownerUserIds = Array.from(new Set(ownerUserIdByPersonId.values()));
+    const ownerUsers =
+      ownerUserIds.length > 0
+        ? await this.prismaService.user.findMany({
+            where: {
+              id: {
+                in: ownerUserIds,
+              },
+            },
+            select: {
+              id: true,
+              name: true,
+            },
+          })
+        : [];
+    const ownerUserById = new Map(
+      ownerUsers.map((item) => [item.id, { id: item.id, name: item.name || `#${item.id}` }]),
+    );
+
     const employerCompanyIds = Array.from(
       new Set(Array.from(employerCompanyIdByPersonId.values())),
     );
@@ -533,6 +1067,7 @@ export class PersonService {
               employerCompanyById.get(employerCompanyId),
             )
           : null;
+      const ownerUserId = ownerUserIdByPersonId.get(person.id) ?? null;
 
       return {
         id: person.id,
@@ -551,6 +1086,17 @@ export class PersonService {
         headquarter_id: companyData?.headquarter_id ?? null,
         branch_ids: branchesByHeadquarterId.get(person.id) || [],
         notes: this.metadataToString(metadata.get(NOTES_METADATA_KEY)),
+        owner_user_id: ownerUserId,
+        owner_user: ownerUserId ? ownerUserById.get(ownerUserId) ?? null : null,
+        source: sourceByPersonId.get(person.id) ?? null,
+        lifecycle_stage: lifecycleStageByPersonId.get(person.id) ?? 'new',
+        next_action_at: nextActionAtByPersonId.get(person.id) ?? null,
+        score: scoreByPersonId.get(person.id) ?? 0,
+        deal_value: dealValueByPersonId.get(person.id) ?? 0,
+        tags: tagsByPersonId.get(person.id) ?? [],
+        last_interaction_at:
+          lastInteractionAtByPersonId.get(person.id) ?? person.created_at?.toISOString?.() ?? null,
+        interaction_count: interactionCountByPersonId.get(person.id) ?? 0,
         employer_company_id: allowCompanyRegistration ? employerCompanyId : null,
         employer_company: allowCompanyRegistration ? employerCompany : null,
         contact: person.contact || [],
@@ -584,6 +1130,72 @@ export class PersonService {
     return null;
   }
 
+  private metadataToNumber(value: unknown): number | null {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value;
+    }
+
+    if (typeof value === 'string') {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+
+    return null;
+  }
+
+  private metadataToIsoString(value: unknown): string | null {
+    if (!value) return null;
+    const parsed = new Date(String(value));
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+  }
+
+  private metadataToStringArray(value: unknown): string[] {
+    if (Array.isArray(value)) {
+      return value
+        .map((item) => this.normalizeTextOrNull(item))
+        .filter((item): item is string => Boolean(item));
+    }
+
+    if (typeof value === 'string') {
+      return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    }
+
+    return [];
+  }
+
+  private metadataToInteractions(value: unknown): PersonInteractionRecord[] {
+    if (!Array.isArray(value)) {
+      return [];
+    }
+
+    return this.sortInteractions(
+      value
+        .map((item) => {
+          if (!item || typeof item !== 'object') return null;
+          const interaction = item as Record<string, unknown>;
+          const createdAt = this.metadataToIsoString(interaction.created_at);
+          const type = this.normalizeTextOrNull(interaction.type);
+
+          if (!createdAt || !type) {
+            return null;
+          }
+
+          return {
+            id: this.coerceNumber(interaction.id) || Date.now(),
+            type: type as CreateInteractionDTO['type'],
+            notes: this.normalizeTextOrNull(interaction.notes),
+            created_at: createdAt,
+            user_id: this.coerceNumber(interaction.user_id) || null,
+            user_name: this.normalizeTextOrNull(interaction.user_name),
+          };
+        })
+        .filter((item): item is PersonInteractionRecord => item != null),
+    );
+  }
+
   private async syncPersonSubtypeData(
     tx: any,
     personId: number,
@@ -752,7 +1364,19 @@ export class PersonService {
   private async syncPersonMetadata(
     tx: any,
     personId: number,
-    data: { notes?: unknown; employer_company_id?: unknown },
+    data: {
+      notes?: unknown;
+      employer_company_id?: unknown;
+      owner_user_id?: unknown;
+      source?: unknown;
+      lifecycle_stage?: unknown;
+      next_action_at?: unknown;
+      score?: unknown;
+      deal_value?: unknown;
+      tags?: unknown;
+      last_interaction_at?: unknown;
+      interactions?: unknown;
+    },
   ) {
     if (data.notes !== undefined) {
       await this.upsertMetadataValue(tx, personId, NOTES_METADATA_KEY, data.notes);
@@ -766,6 +1390,77 @@ export class PersonService {
         data.employer_company_id,
       );
     }
+
+    if (data.owner_user_id !== undefined) {
+      await this.upsertMetadataValue(
+        tx,
+        personId,
+        OWNER_USER_METADATA_KEY,
+        data.owner_user_id,
+      );
+    }
+
+    if (data.source !== undefined) {
+      await this.upsertMetadataValue(tx, personId, SOURCE_METADATA_KEY, data.source);
+    }
+
+    if (data.lifecycle_stage !== undefined) {
+      await this.upsertMetadataValue(
+        tx,
+        personId,
+        LIFECYCLE_STAGE_METADATA_KEY,
+        data.lifecycle_stage,
+      );
+    }
+
+    if (data.next_action_at !== undefined) {
+      await this.upsertMetadataValue(
+        tx,
+        personId,
+        NEXT_ACTION_AT_METADATA_KEY,
+        this.normalizeDateTimeOrNull(data.next_action_at),
+      );
+    }
+
+    if (data.score !== undefined) {
+      await this.upsertMetadataValue(tx, personId, SCORE_METADATA_KEY, data.score);
+    }
+
+    if (data.deal_value !== undefined) {
+      await this.upsertMetadataValue(
+        tx,
+        personId,
+        DEAL_VALUE_METADATA_KEY,
+        data.deal_value,
+      );
+    }
+
+    if (data.tags !== undefined) {
+      const normalizedTags = Array.isArray(data.tags)
+        ? data.tags
+            .map((item) => this.normalizeTextOrNull(item))
+            .filter((item): item is string => Boolean(item))
+        : null;
+      await this.upsertMetadataValue(tx, personId, TAGS_METADATA_KEY, normalizedTags);
+    }
+
+    if (data.last_interaction_at !== undefined) {
+      await this.upsertMetadataValue(
+        tx,
+        personId,
+        LAST_INTERACTION_AT_METADATA_KEY,
+        this.normalizeDateTimeOrNull(data.last_interaction_at),
+      );
+    }
+
+    if (data.interactions !== undefined) {
+      await this.upsertMetadataValue(
+        tx,
+        personId,
+        INTERACTIONS_METADATA_KEY,
+        data.interactions,
+      );
+    }
   }
 
   private async upsertMetadataValue(
@@ -808,7 +1503,7 @@ export class PersonService {
     });
   }
 
-  private normalizeMetadataValue(value: unknown): string | number | boolean | null {
+  private normalizeMetadataValue(value: unknown): Prisma.InputJsonValue | null {
     if (value == null) return null;
 
     if (typeof value === 'string') {
@@ -824,6 +1519,14 @@ export class PersonService {
       return value;
     }
 
+    if (Array.isArray(value) || typeof value === 'object') {
+      try {
+        return JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue;
+      } catch {
+        return null;
+      }
+    }
+
     return null;
   }
 
@@ -927,6 +1630,310 @@ export class PersonService {
     }
   }
 
+  private addDuplicateReason(
+    reasonsByPersonId: Map<number, Set<DuplicateReason>>,
+    personId: number,
+    reason: DuplicateReason,
+  ) {
+    if (!reasonsByPersonId.has(personId)) {
+      reasonsByPersonId.set(personId, new Set<DuplicateReason>());
+    }
+
+    reasonsByPersonId.get(personId)?.add(reason);
+  }
+
+  private async mergeContacts(tx: any, sourcePersonId: number, targetPersonId: number) {
+    const [sourceContacts, targetContacts] = await Promise.all([
+      tx.contact.findMany({ where: { person_id: sourcePersonId } }),
+      tx.contact.findMany({ where: { person_id: targetPersonId } }),
+    ]);
+
+    const existingByKey = new Set(
+      targetContacts.map((contact: any) =>
+        this.buildContactDedupKey(contact.contact_type_id, contact.value),
+      ),
+    );
+    const hasPrimaryType = new Set(
+      targetContacts
+        .filter((contact: any) => contact.is_primary)
+        .map((contact: any) => Number(contact.contact_type_id)),
+    );
+
+    for (const sourceContact of sourceContacts) {
+      const dedupKey = this.buildContactDedupKey(
+        sourceContact.contact_type_id,
+        sourceContact.value,
+      );
+
+      if (existingByKey.has(dedupKey)) {
+        continue;
+      }
+
+      const keepPrimary =
+        sourceContact.is_primary &&
+        !hasPrimaryType.has(Number(sourceContact.contact_type_id));
+
+      await tx.contact.create({
+        data: {
+          person_id: targetPersonId,
+          contact_type_id: sourceContact.contact_type_id,
+          value: sourceContact.value,
+          is_primary: keepPrimary,
+        },
+      });
+
+      existingByKey.add(dedupKey);
+
+      if (keepPrimary) {
+        hasPrimaryType.add(Number(sourceContact.contact_type_id));
+      }
+    }
+
+    await tx.contact.deleteMany({
+      where: {
+        person_id: sourcePersonId,
+      },
+    });
+  }
+
+  private async mergeDocuments(tx: any, sourcePersonId: number, targetPersonId: number) {
+    const [sourceDocuments, targetDocuments] = await Promise.all([
+      tx.document.findMany({ where: { person_id: sourcePersonId } }),
+      tx.document.findMany({ where: { person_id: targetPersonId } }),
+    ]);
+
+    const existingByKey = new Set(
+      targetDocuments.map((document: any) =>
+        this.buildDocumentDedupKey(document.document_type_id, document.value),
+      ),
+    );
+
+    for (const sourceDocument of sourceDocuments) {
+      const dedupKey = this.buildDocumentDedupKey(
+        sourceDocument.document_type_id,
+        sourceDocument.value,
+      );
+
+      if (existingByKey.has(dedupKey)) {
+        continue;
+      }
+
+      await tx.document.create({
+        data: {
+          person_id: targetPersonId,
+          document_type_id: sourceDocument.document_type_id,
+          value: sourceDocument.value,
+        },
+      });
+
+      existingByKey.add(dedupKey);
+    }
+
+    await tx.document.deleteMany({
+      where: {
+        person_id: sourcePersonId,
+      },
+    });
+  }
+
+  private async mergeAddresses(tx: any, sourcePersonId: number, targetPersonId: number) {
+    const [sourceLinks, targetLinks] = await Promise.all([
+      tx.person_address.findMany({
+        where: { person_id: sourcePersonId },
+        include: { address: true },
+      }),
+      tx.person_address.findMany({
+        where: { person_id: targetPersonId },
+        include: { address: true },
+      }),
+    ]);
+
+    const targetByKey = new Map<string, any>();
+    const hasPrimaryType = new Set<string>();
+
+    for (const link of targetLinks) {
+      if (!link.address) continue;
+
+      targetByKey.set(this.buildAddressDedupKey(link.address), link.address);
+      if (link.address.is_primary && link.address.address_type) {
+        hasPrimaryType.add(String(link.address.address_type));
+      }
+    }
+
+    for (const sourceLink of sourceLinks) {
+      if (!sourceLink.address) {
+        await tx.person_address.delete({ where: { id: sourceLink.id } });
+        continue;
+      }
+
+      const sourceAddress = sourceLink.address;
+      const dedupKey = this.buildAddressDedupKey(sourceAddress);
+      const existingTargetAddress = targetByKey.get(dedupKey);
+
+      if (existingTargetAddress) {
+        if (
+          sourceAddress.is_primary &&
+          sourceAddress.address_type &&
+          !hasPrimaryType.has(String(sourceAddress.address_type))
+        ) {
+          await tx.address.update({
+            where: { id: existingTargetAddress.id },
+            data: {
+              is_primary: true,
+            },
+          });
+
+          hasPrimaryType.add(String(sourceAddress.address_type));
+        }
+
+        await tx.person_address.delete({ where: { id: sourceLink.id } });
+        await tx.address.delete({ where: { id: sourceAddress.id } });
+        continue;
+      }
+
+      const keepPrimary =
+        sourceAddress.is_primary &&
+        sourceAddress.address_type &&
+        !hasPrimaryType.has(String(sourceAddress.address_type));
+
+      await tx.person_address.update({
+        where: { id: sourceLink.id },
+        data: {
+          person_id: targetPersonId,
+        },
+      });
+
+      if (Boolean(sourceAddress.is_primary) !== Boolean(keepPrimary)) {
+        await tx.address.update({
+          where: { id: sourceAddress.id },
+          data: {
+            is_primary: Boolean(keepPrimary),
+          },
+        });
+      }
+
+      targetByKey.set(dedupKey, sourceAddress);
+      if (keepPrimary && sourceAddress.address_type) {
+        hasPrimaryType.add(String(sourceAddress.address_type));
+      }
+    }
+  }
+
+  private async mergeMetadata(tx: any, sourcePersonId: number, targetPersonId: number) {
+    const [sourceMetadata, targetMetadata] = await Promise.all([
+      tx.person_metadata.findMany({ where: { person_id: sourcePersonId } }),
+      tx.person_metadata.findMany({ where: { person_id: targetPersonId } }),
+    ]);
+
+    const targetByKey = new Map<string, any>();
+
+    for (const metadata of targetMetadata) {
+      if (!targetByKey.has(metadata.key)) {
+        targetByKey.set(metadata.key, metadata);
+      }
+    }
+
+    for (const sourceItem of sourceMetadata) {
+      if (sourceItem.key === MERGED_INTO_PERSON_METADATA_KEY) {
+        await tx.person_metadata.delete({ where: { id: sourceItem.id } });
+        continue;
+      }
+
+      const targetItem = targetByKey.get(sourceItem.key);
+      if (!targetItem) {
+        await tx.person_metadata.update({
+          where: { id: sourceItem.id },
+          data: {
+            person_id: targetPersonId,
+          },
+        });
+        targetByKey.set(sourceItem.key, sourceItem);
+        continue;
+      }
+
+      if (sourceItem.key === NOTES_METADATA_KEY) {
+        const targetNotes = this.metadataToString(targetItem.value);
+        const sourceNotes = this.metadataToString(sourceItem.value);
+
+        if (sourceNotes && sourceNotes !== targetNotes) {
+          const nextNotes = [targetNotes, sourceNotes].filter(Boolean).join('\n\n');
+          await tx.person_metadata.update({
+            where: { id: targetItem.id },
+            data: {
+              value: nextNotes,
+            },
+          });
+        }
+      } else if (sourceItem.key === TAGS_METADATA_KEY) {
+        const mergedTags = Array.from(
+          new Set([
+            ...this.metadataToStringArray(targetItem.value),
+            ...this.metadataToStringArray(sourceItem.value),
+          ]),
+        );
+
+        await tx.person_metadata.update({
+          where: { id: targetItem.id },
+          data: {
+            value: mergedTags,
+          },
+        });
+      } else if (sourceItem.key === INTERACTIONS_METADATA_KEY) {
+        const mergedInteractions = this.sortInteractions([
+          ...this.metadataToInteractions(targetItem.value),
+          ...this.metadataToInteractions(sourceItem.value),
+        ]);
+
+        await tx.person_metadata.update({
+          where: { id: targetItem.id },
+          data: {
+            value: mergedInteractions,
+          },
+        });
+      }
+
+      await tx.person_metadata.delete({ where: { id: sourceItem.id } });
+    }
+  }
+
+  private buildContactDedupKey(contactTypeId: number, value: string) {
+    return `${contactTypeId}::${this.normalizeText(value).toLowerCase()}`;
+  }
+
+  private buildDocumentDedupKey(documentTypeId: number, value: string) {
+    const normalizedDigits = this.normalizeDigits(value || '');
+    const normalizedValue = normalizedDigits || this.normalizeText(value).toLowerCase();
+    return `${documentTypeId}::${normalizedValue}`;
+  }
+
+  private buildAddressDedupKey(address: {
+    line1?: string | null;
+    line2?: string | null;
+    city?: string | null;
+    state?: string | null;
+    country_code?: string | null;
+    postal_code?: string | null;
+  }) {
+    const parts = [
+      this.normalizeText(address.line1 || ''),
+      this.normalizeText(address.line2 || ''),
+      this.normalizeText(address.city || ''),
+      this.normalizeText(address.state || ''),
+      this.normalizeText(address.country_code || ''),
+      this.normalizeDigits(address.postal_code || ''),
+    ];
+
+    return parts.join('::').toLowerCase();
+  }
+
+  private normalizeEmail(value?: string | null) {
+    return this.normalizeText(value || '').toLowerCase();
+  }
+
+  private normalizeText(value: string) {
+    return String(value || '').trim();
+  }
+
   private validateSinglePrimaryPerType(
     items: any[],
     groupKey: string,
@@ -965,11 +1972,93 @@ export class PersonService {
     return trimmed.length > 0 ? trimmed : null;
   }
 
+  private normalizeDateTimeOrNull(value: unknown): string | null {
+    if (!value) return null;
+    const date = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+  }
+
   private coerceNumber(value: unknown): number {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : 0;
   }
 
+  private resolveRequestedOwnerUserId(
+    ownerUserId: string | number | undefined,
+    mine: string | boolean | undefined,
+    currentUserId?: number,
+  ) {
+    if (
+      mine === true ||
+      mine === 'true' ||
+      mine === '1'
+    ) {
+      return Number(currentUserId) > 0 ? Number(currentUserId) : 0;
+    }
+
+    return this.coerceNumber(ownerUserId);
+  }
+
+  private async ensurePersonAccessible(id: number, locale: string) {
+    const allowCompanyRegistration = await this.isCompanyRegistrationAllowed();
+    const person = await this.prismaService.person.findUnique({
+      where: { id },
+      select: {
+        id: true,
+        type: true,
+      },
+    });
+
+    if (!person) {
+      throw new BadRequestException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    if (!allowCompanyRegistration && person.type === 'company') {
+      throw new NotFoundException(
+        getLocaleText('personNotFound', locale, `Person with ID ${id} not found`),
+      );
+    }
+
+    return person;
+  }
+
+  private async loadInteractionsFromTx(tx: any, personId: number) {
+    const metadata = await tx.person_metadata.findFirst({
+      where: {
+        person_id: personId,
+        key: INTERACTIONS_METADATA_KEY,
+      },
+      select: {
+        value: true,
+      },
+    });
+
+    return this.metadataToInteractions(metadata?.value);
+  }
+
+  private buildInteractionRecord(
+    data: Pick<CreateInteractionDTO, 'type' | 'notes'>,
+    user: { id?: number; name?: string | null },
+  ): PersonInteractionRecord {
+    return {
+      id: Date.now() + Math.floor(Math.random() * 1000),
+      type: data.type,
+      notes: this.normalizeTextOrNull(data.notes),
+      created_at: new Date().toISOString(),
+      user_id: Number(user?.id) > 0 ? Number(user.id) : null,
+      user_name: this.normalizeTextOrNull(user?.name) || null,
+    };
+  }
+
+  private sortInteractions(interactions: PersonInteractionRecord[]) {
+    return [...interactions].sort(
+      (left, right) =>
+        new Date(right.created_at).getTime() - new Date(left.created_at).getTime(),
+    );
+  }
+
   private async buildSearchFilters(search: string) {
     const normalizedDigits = this.normalizeDigits(search);
     const filters: any[] = [];