@adtrackify/at-service-common 5.0.0 → 5.0.2

package/dist/esm/__tests__/identity-cache/identity-cache-dynamodb-db-service.spec.js

@@ -1,554 +1,554 @@
-jest.mock('../../clients/index.js', () => ({
-    DynamoDbClient: {
-        safeGet: jest.fn(),
-        safePut: jest.fn(),
-        safeDelete: jest.fn(),
-        safeBatchGet: jest.fn(),
-        safeBatchWrite: jest.fn(),
-        safeQueryByGSI: jest.fn(),
-        batchWrite: jest.fn(),
-    },
-}));
-jest.mock('../../helpers/index.js', () => ({
-    Logger: {
-        debug: jest.fn(),
-        info: jest.fn(),
-        warn: jest.fn(),
-        error: jest.fn(),
-    },
-}));
-import { IdentityCacheDynamoDbDbService } from '../../services/db/identity-cache-dynamodb-service/identity-cache-dynamodb-db-service.js';
-import { DynamoDbClient } from '../../clients/index.js';
-import { Logger } from '../../helpers/index.js';
-const mockedDynamoDbClient = DynamoDbClient;
-const mockedLogger = Logger;
-describe('IdentityCacheDynamoDbDbService.getIdentityFromCachePure()', () => {
-    const pixelId = 'pixel-test-123';
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockedDynamoDbClient.safeGet.mockReset();
-        mockedDynamoDbClient.safePut.mockReset();
-        mockedDynamoDbClient.safeBatchWrite.mockReset();
-    });
-    describe('cache hit by identity ID', () => {
-        it('should return cachedIdentity with lookupPath=identity_id and cacheHit=true', async () => {
-            const incomingIdentity = {
-                identityId: 'identity-123',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#identity-123`,
-                pixelId,
-                identityId: 'identity-123',
-                response: {
-                    identityId: 'identity-123',
-                    traits: {
-                        emails: ['test@email.com', 'cached@email.com'],
-                        phones: ['555-1234'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(true);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(result.cachedIdentity).toEqual(cachedRecord.response);
-            expect(result.discoveredIdentityId).toBeUndefined();
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledTimes(1);
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `identity#${pixelId}#identity-123`);
-        });
-        it('should return cachedIdentity with all traits preserved', async () => {
-            const incomingIdentity = {
-                identityId: 'full-traits-id',
-                traits: { emails: ['new@email.com'] },
-            };
-            const fullCachedIdentity = {
-                identityId: 'full-traits-id',
-                traits: {
-                    emails: ['existing@email.com', 'another@email.com'],
-                    phones: ['555-1111', '555-2222'],
-                    addresses: [{ city: 'New York', zip: '10001' }],
-                    userIds: ['user-1', 'user-2'],
-                    shopifyYIds: ['shopify-y-1'],
-                    click: { fbp: 'fb.1.123.456' },
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Mozilla/5.0...',
-                },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#full-traits-id`,
-                pixelId,
-                identityId: 'full-traits-id',
-                response: fullCachedIdentity,
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(true);
-            expect(result.cachedIdentity).toEqual(fullCachedIdentity);
-            expect(result.cachedIdentity?.traits?.emails).toHaveLength(2);
-            expect(result.cachedIdentity?.traits?.phones).toHaveLength(2);
-            expect(result.cachedIdentity?.traits?.addresses).toHaveLength(1);
-        });
-        it('should NOT perform any merge logic', async () => {
-            const incomingIdentity = {
-                identityId: 'merge-test-id',
-                traits: {
-                    emails: ['new-email@test.com'],
-                    phones: ['999-0000'],
-                },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#merge-test-id`,
-                pixelId,
-                identityId: 'merge-test-id',
-                response: {
-                    identityId: 'merge-test-id',
-                    traits: {
-                        emails: ['old-email@test.com'],
-                        phones: ['111-2222'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cachedIdentity?.traits?.emails).toEqual(['old-email@test.com']);
-            expect(result.cachedIdentity?.traits?.phones).toEqual(['111-2222']);
-            expect(result.cachedIdentity?.traits?.emails).not.toContain('new-email@test.com');
-        });
-        it('should NOT perform staleness computation', async () => {
-            const incomingIdentity = {
-                identityId: 'stale-test-id',
-                traits: {
-                    emails: ['new-email@test.com'],
-                },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#stale-test-id`,
-                pixelId,
-                identityId: 'stale-test-id',
-                response: {
-                    identityId: 'stale-test-id',
-                    traits: {
-                        emails: ['old-email@test.com'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result).not.toHaveProperty('isCacheStale');
-            expect(result).not.toHaveProperty('staleTier');
-            expect(result).not.toHaveProperty('staleTracker');
-            expect(result).not.toHaveProperty('writeReason');
-            expect(result).not.toHaveProperty('skipNeptune');
-        });
-    });
-    describe('cache hit by email pointer', () => {
-        it('should return discoveredIdentityId with lookupPath=email_pointer and cacheHit=true', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['lookup@email.com'] },
-            };
-            const emailPointerRecord = {
-                pk: `email#${pixelId}#lookup@email.com`,
-                pixelId,
-                identityId: 'discovered-identity-456',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(true);
-            expect(result.lookupPath).toBe('email_pointer');
-            expect(result.discoveredIdentityId).toBe('discovered-identity-456');
-            expect(result.cachedIdentity).toBeUndefined();
-        });
-        it('should use first email in emails array for lookup', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['first@email.com', 'second@email.com'] },
-            };
-            const emailPointerRecord = {
-                pk: `email#${pixelId}#first@email.com`,
-                pixelId,
-                identityId: 'pointer-identity-789',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.discoveredIdentityId).toBe('pointer-identity-789');
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#first@email.com`);
-        });
-        it('should NOT merge traits when returning email pointer discovery', async () => {
-            const incomingIdentity = {
-                traits: {
-                    emails: ['discovery@email.com'],
-                    phones: ['incoming-phone'],
-                },
-            };
-            const emailPointerRecord = {
-                pk: `email#${pixelId}#discovery@email.com`,
-                pixelId,
-                identityId: 'discovered-id',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cachedIdentity).toBeUndefined();
-            expect(result.discoveredIdentityId).toBe('discovered-id');
-        });
-    });
-    describe('cache miss', () => {
-        it('should return lookupPath=miss and cacheHit=false when identity not found', async () => {
-            const incomingIdentity = {
-                identityId: 'nonexistent-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(result.cachedIdentity).toBeUndefined();
-            expect(result.discoveredIdentityId).toBeUndefined();
-        });
-        it('should return lookupPath=miss and cacheHit=false when email pointer not found', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['unknown@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-            expect(result.cachedIdentity).toBeUndefined();
-            expect(result.discoveredIdentityId).toBeUndefined();
-        });
-        it('should return lookupPath=miss when cached record has no response field', async () => {
-            const incomingIdentity = {
-                identityId: 'no-response-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            const incompleteRecord = {
-                pk: `identity#${pixelId}#no-response-identity`,
-                pixelId,
-                identityId: 'no-response-identity',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(incompleteRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(result.cachedIdentity).toBeUndefined();
-        });
-        it('should return lookupPath=miss when no email provided for pointer lookup', async () => {
-            const incomingIdentity = {
-                traits: { phones: ['555-1234'] },
-            };
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-    });
-    describe('invalid input handling', () => {
-        it('should return cache miss for undefined pixelId', async () => {
-            const incomingIdentity = {
-                identityId: 'test-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(undefined, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-        it('should return cache miss for empty pixelId', async () => {
-            const incomingIdentity = {
-                identityId: 'test-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure('', incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-        });
-        it('should return cache miss for undefined incomingIdentity', async () => {
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, undefined);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-        });
-        it('should return cache miss for null incomingIdentity', async () => {
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, null);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-        });
-    });
-    describe('error handling', () => {
-        it('should return cache miss when DynamoDB throws an error', async () => {
-            const incomingIdentity = {
-                identityId: 'error-test-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB connection failed'));
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(result.cachedIdentity).toBeUndefined();
-            expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache - getItemByPk failed', expect.objectContaining({
-                error: expect.any(Error),
-                errorMessage: 'DynamoDB connection failed',
-            }));
-        });
-        it('should handle non-Error thrown values', async () => {
-            const incomingIdentity = {
-                identityId: 'string-error-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockRejectedValueOnce('String error message');
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache - getItemByPk failed', expect.objectContaining({
-                errorMessage: 'String error message',
-            }));
-        });
-    });
-    describe('verification: no merge or staleness logic', () => {
-        it('should not call mergeIdentityTraits', async () => {
-            const incomingIdentity = {
-                identityId: 'verify-no-merge',
-                traits: { emails: ['incoming@email.com'] },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#verify-no-merge`,
-                pixelId,
-                identityId: 'verify-no-merge',
-                response: {
-                    identityId: 'verify-no-merge',
-                    traits: { emails: ['cached@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cachedIdentity).toBe(cachedRecord.response);
-            expect(result.cachedIdentity?.traits?.emails).toEqual(['cached@email.com']);
-        });
-        it('should not call isIdentityCacheStale', async () => {
-            const incomingIdentity = {
-                identityId: 'verify-no-staleness',
-                traits: {
-                    emails: ['new-email@test.com'],
-                },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#verify-no-staleness`,
-                pixelId,
-                identityId: 'verify-no-staleness',
-                response: {
-                    identityId: 'verify-no-staleness',
-                    traits: { emails: ['old-email@test.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(Object.keys(result)).toEqual(['cachedIdentity', 'lookupPath', 'cacheHit']);
-        });
-        it('result should only contain pure lookup properties', async () => {
-            const incomingIdentity = {
-                identityId: 'result-shape-test',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#result-shape-test`,
-                pixelId,
-                identityId: 'result-shape-test',
-                response: {
-                    identityId: 'result-shape-test',
-                    traits: { emails: ['test@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result).toEqual({
-                cachedIdentity: cachedRecord.response,
-                lookupPath: 'identity_id',
-                cacheHit: true,
-            });
-            expect(result).not.toHaveProperty('resolvedIdentity');
-            expect(result).not.toHaveProperty('isCacheStale');
-            expect(result).not.toHaveProperty('staleTracker');
-            expect(result).not.toHaveProperty('staleTier');
-            expect(result).not.toHaveProperty('writeReason');
-            expect(result).not.toHaveProperty('skipNeptune');
-            expect(result).not.toHaveProperty('mergedIdentity');
-        });
-    });
-    describe('logging', () => {
-        it('should log debug on cache hit by identity ID', async () => {
-            const incomingIdentity = {
-                identityId: 'log-test-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#log-test-id`,
-                pixelId,
-                identityId: 'log-test-id',
-                response: {
-                    identityId: 'log-test-id',
-                    traits: { emails: ['test@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure lookup hit', expect.objectContaining({
-                pixelId,
-                identityId: 'log-test-id',
-            }));
-        });
-        it('should log debug on cache miss', async () => {
-            const incomingIdentity = {
-                identityId: 'miss-log-test',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure lookup miss', expect.objectContaining({
-                pixelId,
-                identityId: 'miss-log-test',
-            }));
-        });
-        it('should log debug on email pointer discovery', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['email-pointer@test.com'] },
-            };
-            const emailPointerRecord = {
-                pk: `email#${pixelId}#email-pointer@test.com`,
-                pixelId,
-                identityId: 'discovered-from-pointer',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
-            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure email pointer discovery', expect.objectContaining({
-                pixelId,
-                discoveredIdentityId: 'discovered-from-pointer',
-            }));
-        });
-    });
-});
-describe('mergeAndComputeIdentityStaleness (pure function)', () => {
-    const { mergeAndComputeIdentityStaleness, IDENTITY_CACHE_STALENESS_TIER } = jest.requireActual('@adtrackify/at-shared-utils');
-    describe('merge behavior', () => {
-        it('should merge incoming traits with cached traits', () => {
-            const incomingIdentity = {
-                identityId: 'merge-test',
-                traits: {
-                    emails: ['new@email.com'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'merge-test',
-                traits: {
-                    emails: ['cached@email.com'],
-                    phones: ['555-1234'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.traits?.emails).toContain('new@email.com');
-            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
-            expect(result.mergedIdentity.traits?.phones).toContain('555-1234');
-        });
-    });
-    describe('staleness tier computation', () => {
-        it('should return NONE tier when no traits are stale', () => {
-            const incomingIdentity = {
-                identityId: 'same-test',
-                traits: { emails: ['same@email.com'] },
-            };
-            const cachedIdentity = {
-                identityId: 'same-test',
-                traits: { emails: ['same@email.com'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should return VOLATILE_ONLY tier when incoming has new IP address (cached has none)', () => {
-            const incomingIdentity = {
-                identityId: 'volatile-test',
-                traits: {
-                    emails: ['same@email.com'],
-                    ipAddress: '192.168.1.100',
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'volatile-test',
-                traits: {
-                    emails: ['same@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should return ADDRESS_UPDATE tier when non-IP address is new', () => {
-            const incomingIdentity = {
-                identityId: 'address-test',
-                traits: {
-                    emails: ['same@email.com'],
-                    addresses: [{ firstName: 'John', city: 'New York' }],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'address-test',
-                traits: {
-                    emails: ['same@email.com'],
-                    addresses: [],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE tier when email changes', () => {
-            const incomingIdentity = {
-                identityId: 'stale-test',
-                traits: {
-                    emails: ['new@email.com'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'stale-test',
-                traits: {
-                    emails: ['old@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-        });
-    });
-    describe('staleTraits extraction', () => {
-        it('should include changed trait names in staleTraits array', () => {
-            const incomingIdentity = {
-                identityId: 'traits-test',
-                traits: {
-                    emails: ['new@email.com'],
-                    phones: ['999-0000'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'traits-test',
-                traits: {
-                    emails: ['old@email.com'],
-                    phones: ['111-2222'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTraits).toContain('emails');
-            expect(result.staleTraits).toContain('phones');
-        });
-    });
-});
+jest.mock('../../clients/index.js', () => ({
+    DynamoDbClient: {
+        safeGet: jest.fn(),
+        safePut: jest.fn(),
+        safeDelete: jest.fn(),
+        safeBatchGet: jest.fn(),
+        safeBatchWrite: jest.fn(),
+        safeQueryByGSI: jest.fn(),
+        batchWrite: jest.fn(),
+    },
+}));
+jest.mock('../../helpers/index.js', () => ({
+    Logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    },
+}));
+import { IdentityCacheDynamoDbDbService } from '../../services/db/identity-cache-dynamodb-service/identity-cache-dynamodb-db-service.js';
+import { DynamoDbClient } from '../../clients/index.js';
+import { Logger } from '../../helpers/index.js';
+const mockedDynamoDbClient = DynamoDbClient;
+const mockedLogger = Logger;
+describe('IdentityCacheDynamoDbDbService.getIdentityFromCachePure()', () => {
+    const pixelId = 'pixel-test-123';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safePut.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+    });
+    describe('cache hit by identity ID', () => {
+        it('should return cachedIdentity with lookupPath=identity_id and cacheHit=true', async () => {
+            const incomingIdentity = {
+                identityId: 'identity-123',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#identity-123`,
+                pixelId,
+                identityId: 'identity-123',
+                response: {
+                    identityId: 'identity-123',
+                    traits: {
+                        emails: ['test@email.com', 'cached@email.com'],
+                        phones: ['555-1234'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(true);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(result.cachedIdentity).toEqual(cachedRecord.response);
+            expect(result.discoveredIdentityId).toBeUndefined();
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledTimes(1);
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `identity#${pixelId}#identity-123`);
+        });
+        it('should return cachedIdentity with all traits preserved', async () => {
+            const incomingIdentity = {
+                identityId: 'full-traits-id',
+                traits: { emails: ['new@email.com'] },
+            };
+            const fullCachedIdentity = {
+                identityId: 'full-traits-id',
+                traits: {
+                    emails: ['existing@email.com', 'another@email.com'],
+                    phones: ['555-1111', '555-2222'],
+                    addresses: [{ city: 'New York', zip: '10001' }],
+                    userIds: ['user-1', 'user-2'],
+                    shopifyYIds: ['shopify-y-1'],
+                    click: { fbp: 'fb.1.123.456' },
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Mozilla/5.0...',
+                },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#full-traits-id`,
+                pixelId,
+                identityId: 'full-traits-id',
+                response: fullCachedIdentity,
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(true);
+            expect(result.cachedIdentity).toEqual(fullCachedIdentity);
+            expect(result.cachedIdentity?.traits?.emails).toHaveLength(2);
+            expect(result.cachedIdentity?.traits?.phones).toHaveLength(2);
+            expect(result.cachedIdentity?.traits?.addresses).toHaveLength(1);
+        });
+        it('should NOT perform any merge logic', async () => {
+            const incomingIdentity = {
+                identityId: 'merge-test-id',
+                traits: {
+                    emails: ['new-email@test.com'],
+                    phones: ['999-0000'],
+                },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#merge-test-id`,
+                pixelId,
+                identityId: 'merge-test-id',
+                response: {
+                    identityId: 'merge-test-id',
+                    traits: {
+                        emails: ['old-email@test.com'],
+                        phones: ['111-2222'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cachedIdentity?.traits?.emails).toEqual(['old-email@test.com']);
+            expect(result.cachedIdentity?.traits?.phones).toEqual(['111-2222']);
+            expect(result.cachedIdentity?.traits?.emails).not.toContain('new-email@test.com');
+        });
+        it('should NOT perform staleness computation', async () => {
+            const incomingIdentity = {
+                identityId: 'stale-test-id',
+                traits: {
+                    emails: ['new-email@test.com'],
+                },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#stale-test-id`,
+                pixelId,
+                identityId: 'stale-test-id',
+                response: {
+                    identityId: 'stale-test-id',
+                    traits: {
+                        emails: ['old-email@test.com'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result).not.toHaveProperty('isCacheStale');
+            expect(result).not.toHaveProperty('staleTier');
+            expect(result).not.toHaveProperty('staleTracker');
+            expect(result).not.toHaveProperty('writeReason');
+            expect(result).not.toHaveProperty('skipNeptune');
+        });
+    });
+    describe('cache hit by email pointer', () => {
+        it('should return discoveredIdentityId with lookupPath=email_pointer and cacheHit=true', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['lookup@email.com'] },
+            };
+            const emailPointerRecord = {
+                pk: `email#${pixelId}#lookup@email.com`,
+                pixelId,
+                identityId: 'discovered-identity-456',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(true);
+            expect(result.lookupPath).toBe('email_pointer');
+            expect(result.discoveredIdentityId).toBe('discovered-identity-456');
+            expect(result.cachedIdentity).toBeUndefined();
+        });
+        it('should use first email in emails array for lookup', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['first@email.com', 'second@email.com'] },
+            };
+            const emailPointerRecord = {
+                pk: `email#${pixelId}#first@email.com`,
+                pixelId,
+                identityId: 'pointer-identity-789',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.discoveredIdentityId).toBe('pointer-identity-789');
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#first@email.com`);
+        });
+        it('should NOT merge traits when returning email pointer discovery', async () => {
+            const incomingIdentity = {
+                traits: {
+                    emails: ['discovery@email.com'],
+                    phones: ['incoming-phone'],
+                },
+            };
+            const emailPointerRecord = {
+                pk: `email#${pixelId}#discovery@email.com`,
+                pixelId,
+                identityId: 'discovered-id',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cachedIdentity).toBeUndefined();
+            expect(result.discoveredIdentityId).toBe('discovered-id');
+        });
+    });
+    describe('cache miss', () => {
+        it('should return lookupPath=miss and cacheHit=false when identity not found', async () => {
+            const incomingIdentity = {
+                identityId: 'nonexistent-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(result.cachedIdentity).toBeUndefined();
+            expect(result.discoveredIdentityId).toBeUndefined();
+        });
+        it('should return lookupPath=miss and cacheHit=false when email pointer not found', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['unknown@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+            expect(result.cachedIdentity).toBeUndefined();
+            expect(result.discoveredIdentityId).toBeUndefined();
+        });
+        it('should return lookupPath=miss when cached record has no response field', async () => {
+            const incomingIdentity = {
+                identityId: 'no-response-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            const incompleteRecord = {
+                pk: `identity#${pixelId}#no-response-identity`,
+                pixelId,
+                identityId: 'no-response-identity',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(incompleteRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(result.cachedIdentity).toBeUndefined();
+        });
+        it('should return lookupPath=miss when no email provided for pointer lookup', async () => {
+            const incomingIdentity = {
+                traits: { phones: ['555-1234'] },
+            };
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+    });
+    describe('invalid input handling', () => {
+        it('should return cache miss for undefined pixelId', async () => {
+            const incomingIdentity = {
+                identityId: 'test-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(undefined, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+        it('should return cache miss for empty pixelId', async () => {
+            const incomingIdentity = {
+                identityId: 'test-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure('', incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+        });
+        it('should return cache miss for undefined incomingIdentity', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, undefined);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+        });
+        it('should return cache miss for null incomingIdentity', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, null);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+        });
+    });
+    describe('error handling', () => {
+        it('should return cache miss when DynamoDB throws an error', async () => {
+            const incomingIdentity = {
+                identityId: 'error-test-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB connection failed'));
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(result.cachedIdentity).toBeUndefined();
+            expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache - getItemByPk failed', expect.objectContaining({
+                error: expect.any(Error),
+                errorMessage: 'DynamoDB connection failed',
+            }));
+        });
+        it('should handle non-Error thrown values', async () => {
+            const incomingIdentity = {
+                identityId: 'string-error-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockRejectedValueOnce('String error message');
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache - getItemByPk failed', expect.objectContaining({
+                errorMessage: 'String error message',
+            }));
+        });
+    });
+    describe('verification: no merge or staleness logic', () => {
+        it('should not call mergeIdentityTraits', async () => {
+            const incomingIdentity = {
+                identityId: 'verify-no-merge',
+                traits: { emails: ['incoming@email.com'] },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#verify-no-merge`,
+                pixelId,
+                identityId: 'verify-no-merge',
+                response: {
+                    identityId: 'verify-no-merge',
+                    traits: { emails: ['cached@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cachedIdentity).toBe(cachedRecord.response);
+            expect(result.cachedIdentity?.traits?.emails).toEqual(['cached@email.com']);
+        });
+        it('should not call isIdentityCacheStale', async () => {
+            const incomingIdentity = {
+                identityId: 'verify-no-staleness',
+                traits: {
+                    emails: ['new-email@test.com'],
+                },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#verify-no-staleness`,
+                pixelId,
+                identityId: 'verify-no-staleness',
+                response: {
+                    identityId: 'verify-no-staleness',
+                    traits: { emails: ['old-email@test.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(Object.keys(result)).toEqual(['cachedIdentity', 'lookupPath', 'cacheHit']);
+        });
+        it('result should only contain pure lookup properties', async () => {
+            const incomingIdentity = {
+                identityId: 'result-shape-test',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#result-shape-test`,
+                pixelId,
+                identityId: 'result-shape-test',
+                response: {
+                    identityId: 'result-shape-test',
+                    traits: { emails: ['test@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result).toEqual({
+                cachedIdentity: cachedRecord.response,
+                lookupPath: 'identity_id',
+                cacheHit: true,
+            });
+            expect(result).not.toHaveProperty('resolvedIdentity');
+            expect(result).not.toHaveProperty('isCacheStale');
+            expect(result).not.toHaveProperty('staleTracker');
+            expect(result).not.toHaveProperty('staleTier');
+            expect(result).not.toHaveProperty('writeReason');
+            expect(result).not.toHaveProperty('skipNeptune');
+            expect(result).not.toHaveProperty('mergedIdentity');
+        });
+    });
+    describe('logging', () => {
+        it('should log debug on cache hit by identity ID', async () => {
+            const incomingIdentity = {
+                identityId: 'log-test-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#log-test-id`,
+                pixelId,
+                identityId: 'log-test-id',
+                response: {
+                    identityId: 'log-test-id',
+                    traits: { emails: ['test@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure lookup hit', expect.objectContaining({
+                pixelId,
+                identityId: 'log-test-id',
+            }));
+        });
+        it('should log debug on cache miss', async () => {
+            const incomingIdentity = {
+                identityId: 'miss-log-test',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure lookup miss', expect.objectContaining({
+                pixelId,
+                identityId: 'miss-log-test',
+            }));
+        });
+        it('should log debug on email pointer discovery', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['email-pointer@test.com'] },
+            };
+            const emailPointerRecord = {
+                pk: `email#${pixelId}#email-pointer@test.com`,
+                pixelId,
+                identityId: 'discovered-from-pointer',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
+            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure email pointer discovery', expect.objectContaining({
+                pixelId,
+                discoveredIdentityId: 'discovered-from-pointer',
+            }));
+        });
+    });
+});
+describe('mergeAndComputeIdentityStaleness (pure function)', () => {
+    const { mergeAndComputeIdentityStaleness, IDENTITY_CACHE_STALENESS_TIER } = jest.requireActual('@adtrackify/at-shared-utils');
+    describe('merge behavior', () => {
+        it('should merge incoming traits with cached traits', () => {
+            const incomingIdentity = {
+                identityId: 'merge-test',
+                traits: {
+                    emails: ['new@email.com'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'merge-test',
+                traits: {
+                    emails: ['cached@email.com'],
+                    phones: ['555-1234'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.traits?.emails).toContain('new@email.com');
+            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
+            expect(result.mergedIdentity.traits?.phones).toContain('555-1234');
+        });
+    });
+    describe('staleness tier computation', () => {
+        it('should return NONE tier when no traits are stale', () => {
+            const incomingIdentity = {
+                identityId: 'same-test',
+                traits: { emails: ['same@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'same-test',
+                traits: { emails: ['same@email.com'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should return VOLATILE_ONLY tier when incoming has new IP address (cached has none)', () => {
+            const incomingIdentity = {
+                identityId: 'volatile-test',
+                traits: {
+                    emails: ['same@email.com'],
+                    ipAddress: '192.168.1.100',
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'volatile-test',
+                traits: {
+                    emails: ['same@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should return ADDRESS_UPDATE tier when non-IP address is new', () => {
+            const incomingIdentity = {
+                identityId: 'address-test',
+                traits: {
+                    emails: ['same@email.com'],
+                    addresses: [{ firstName: 'John', city: 'New York' }],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'address-test',
+                traits: {
+                    emails: ['same@email.com'],
+                    addresses: [],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE tier when email changes', () => {
+            const incomingIdentity = {
+                identityId: 'stale-test',
+                traits: {
+                    emails: ['new@email.com'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'stale-test',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+        });
+    });
+    describe('staleTraits extraction', () => {
+        it('should include changed trait names in staleTraits array', () => {
+            const incomingIdentity = {
+                identityId: 'traits-test',
+                traits: {
+                    emails: ['new@email.com'],
+                    phones: ['999-0000'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'traits-test',
+                traits: {
+                    emails: ['old@email.com'],
+                    phones: ['111-2222'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTraits).toContain('emails');
+            expect(result.staleTraits).toContain('phones');
+        });
+    });
+});
 //# sourceMappingURL=identity-cache-dynamodb-db-service.spec.js.map