@adtrackify/at-service-common 3.19.25 → 4.0.0

package/dist/esm/__tests__/identity-cache/identity-cache-tier-routing.spec.js

@@ -0,0 +1,850 @@
+import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
+import { IDENTITY_CACHE_STALENESS_TIER } from '../../helpers/identity-cache-helper';
+import { CACHE_WRITE_REASON } from '../../services/db/identity-cache-dynamodb-service';
+const mockInvokeFunction = jest.fn();
+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(),
+    },
+    LambdaInvokeClient: jest.fn().mockImplementation(() => ({
+        invokeFunction: mockInvokeFunction,
+    })),
+}));
+jest.mock('../../helpers/index.js', () => ({
+    Logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    },
+}));
+import { IdentityCacheDynamoDbService, } from '../../services/db/identity-cache-dynamodb-service.js';
+import { DynamoDbClient } from '../../clients/index.js';
+import { Logger } from '../../helpers/index.js';
+const mockedDynamoDbClient = DynamoDbClient;
+const mockedLogger = Logger;
+describe('Identity Cache Three-Tier Routing', () => {
+    const pixelId = 'pixel123';
+    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safePut.mockReset();
+        mockedDynamoDbClient.safeDelete.mockReset();
+        mockedDynamoDbClient.safeBatchGet.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockedDynamoDbClient.safeQueryByGSI.mockReset();
+        mockedDynamoDbClient.batchWrite.mockReset();
+        mockInvokeFunction.mockReset();
+        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+    });
+    describe('TIER: VOLATILE_ONLY — Returns merged identity, NO Neptune, NO cache write', () => {
+        it('should return merged identity without Neptune call when only ipAddress is stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        ipAddress: '192.168.1.1',
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(result?.identityId).toBe('identity456');
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+        it('should return merged identity without Neptune call when only userAgent is stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    userAgent: 'Chrome/120.0',
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        userAgent: 'Mozilla/5.0',
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+        it('should return merged identity without Neptune call when only IP-sourced addresses are stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'New York', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ city: 'Chicago', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+    });
+    describe('TIER: ADDRESS_UPDATE — Writes to cache, NO Neptune call', () => {
+        it('should write to cache but skip Neptune when new non-IP address is added', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Boston', firstName: 'John', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(result?.traits?.addresses).toHaveLength(1);
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should write to cache and skip Neptune when address with PII but no source is added', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Miami', lastName: 'Smith' }],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should log with writeReason ADDRESS_UPDATE and staleTraits', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Seattle', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: address update only (skipping Neptune)', expect.objectContaining({
+                pixelId,
+                writeReason: CACHE_WRITE_REASON.ADDRESS_UPDATE,
+                staleTier: IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE,
+            }));
+        });
+    });
+    describe('TIER: IDENTITY_STALE — Calls Neptune AND writes to cache', () => {
+        it('should call Neptune and write to cache when emails are stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['old@email.com'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { emails: ['old@email.com', 'new@email.com', 'resolved@email.com'] },
+                    },
+                }),
+            });
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should call Neptune and write to cache when phones are stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    phones: ['+1234567890', '+9876543210'],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        phones: ['+1234567890'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { phones: ['+1234567890', '+9876543210'] },
+                    },
+                }),
+            });
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should log with writeReason STALE_TRAITS, staleTraits, and traitChanges', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: { emails: ['old@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { emails: ['old@email.com', 'new@email.com'] },
+                    },
+                }),
+            });
+            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: stale identity traits update', expect.objectContaining({
+                pixelId,
+                writeReason: CACHE_WRITE_REASON.STALE_TRAITS,
+                staleTier: IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE,
+                staleTraits: expect.arrayContaining(['emails']),
+            }));
+        });
+    });
+    describe('CACHE_MISS — Calls Neptune AND writes to cache', () => {
+        it('should call Neptune and write to cache on complete cache miss', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { emails: ['test@email.com'] },
+                    },
+                }),
+            });
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should log with writeReason CACHE_MISS', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { emails: ['test@email.com'] },
+                    },
+                }),
+            });
+            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: new identity', expect.objectContaining({
+                pixelId,
+                writeReason: CACHE_WRITE_REASON.CACHE_MISS,
+            }));
+        });
+    });
+    describe('EMAIL_POINTER_DISCOVERY — Calls Neptune with discovered identityId', () => {
+        it('should call Neptune with discovered identityId from email pointer', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['test@email.com'] },
+            };
+            const pointerRecord = {
+                pk: `email#${pixelId}#test@email.com`,
+                pixelId,
+                identityId: 'discovered-id',
+                gsi1pk: 'discovered-id',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'discovered-id',
+                        traits: { emails: ['test@email.com', 'other@email.com'] },
+                    },
+                }),
+            });
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result?.identityId).toBe('discovered-id');
+            expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
+                context: {
+                    identity: expect.objectContaining({
+                        identityId: 'discovered-id',
+                    }),
+                },
+            }));
+        });
+    });
+});
+describe('Identity Cache stripAddressTimestamps', () => {
+    const pixelId = 'pixel123';
+    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockInvokeFunction.mockReset();
+        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+    });
+    it('should strip cra and upa from addresses during comparison', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [
+                    {
+                        city: 'Test City',
+                        s: ADDRESS_INFO_SOURCE.INPUT,
+                        cra: Date.parse('2024-01-01T00:00:00Z'),
+                        upa: Date.parse('2024-01-15T00:00:00Z'),
+                    },
+                ],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        {
+                            city: 'Test City',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                            cra: Date.parse('2023-06-01T00:00:00Z'),
+                            upa: Date.parse('2023-12-01T00:00:00Z'),
+                        },
+                    ],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+    });
+    it('should NOT mutate the original object when stripping timestamps', async () => {
+        const originalAddress = {
+            city: 'Original City',
+            s: ADDRESS_INFO_SOURCE.INPUT,
+            cra: Date.parse('2024-01-01T00:00:00Z'),
+            upa: Date.parse('2024-01-15T00:00:00Z'),
+        };
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [{ ...originalAddress }],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        {
+                            city: 'Original City',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                            cra: Date.parse('2023-06-01T00:00:00Z'),
+                            upa: Date.parse('2023-06-15T00:00:00Z'),
+                        },
+                    ],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(incomingIdentity.traits?.addresses?.[0]).toHaveProperty('cra');
+        expect(incomingIdentity.traits?.addresses?.[0]).toHaveProperty('upa');
+        expect(cachedResponse.response.traits?.addresses?.[0]).toHaveProperty('cra');
+        expect(cachedResponse.response.traits?.addresses?.[0]).toHaveProperty('upa');
+    });
+    it('should handle identity with no addresses', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+    });
+    it('should handle identity with empty addresses array', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+    });
+    it('should handle addresses without cra/upa (no-op)', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [{ city: 'Simple City', s: ADDRESS_INFO_SOURCE.INPUT }],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Simple City', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+    });
+});
+describe('Identity Cache fastDeepEqual with Timestamp Stripping', () => {
+    const pixelId = 'pixel123';
+    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockInvokeFunction.mockReset();
+        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+    });
+    it('should treat cached and merged as equal when they differ ONLY in cra/upa', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [
+                    {
+                        city: 'Same City',
+                        province: 'Same State',
+                        country: 'Same Country',
+                        s: ADDRESS_INFO_SOURCE.INPUT,
+                        cra: Date.parse('2024-06-01T00:00:00Z'),
+                        upa: Date.parse('2024-06-15T00:00:00Z'),
+                    },
+                ],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        {
+                            city: 'Same City',
+                            province: 'Same State',
+                            country: 'Same Country',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                            cra: Date.parse('2024-01-01T00:00:00Z'),
+                            upa: Date.parse('2024-01-15T00:00:00Z'),
+                        },
+                    ],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+        expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+    });
+    it('should treat cached and merged as NOT equal when address content differs (plus cra/upa)', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [
+                    {
+                        city: 'Different City',
+                        province: 'Same State',
+                        s: ADDRESS_INFO_SOURCE.INPUT,
+                        cra: Date.parse('2024-06-01T00:00:00Z'),
+                        upa: Date.parse('2024-06-15T00:00:00Z'),
+                    },
+                ],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        {
+                            city: 'Original City',
+                            province: 'Same State',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                            cra: Date.parse('2024-01-01T00:00:00Z'),
+                            upa: Date.parse('2024-01-15T00:00:00Z'),
+                        },
+                    ],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+    });
+});
+describe('Identity Cache Logging Levels', () => {
+    const pixelId = 'pixel123';
+    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockInvokeFunction.mockReset();
+        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+    });
+    it('should log at debug level when cache is fresh (deep equal)', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(mockedLogger.debug).toHaveBeenCalledWith(expect.stringContaining('identity cache'), expect.any(Object));
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+        expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+    });
+    it('should log at info level for ADDRESS_UPDATE path', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [{ city: 'New City', s: ADDRESS_INFO_SOURCE.INPUT }],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: address update only (skipping Neptune)', expect.objectContaining({
+            writeReason: CACHE_WRITE_REASON.ADDRESS_UPDATE,
+            staleTraits: expect.any(Array),
+        }));
+    });
+    it('should log at info level for IDENTITY_STALE path with traitChanges', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['old@email.com', 'new@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        mockInvokeFunction.mockResolvedValueOnce({
+            statusCode: 200,
+            body: JSON.stringify({
+                identity: {
+                    identityId: 'identity456',
+                    traits: { emails: ['old@email.com', 'new@email.com'] },
+                },
+            }),
+        });
+        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: stale identity traits update', expect.objectContaining({
+            writeReason: CACHE_WRITE_REASON.STALE_TRAITS,
+            staleTraits: expect.arrayContaining(['emails']),
+            traitChanges: expect.any(Object),
+        }));
+    });
+});
+describe('getIdentityFromCache staleness tier results', () => {
+    const pixelId = 'pixel123';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+    });
+    it('should return staleTier NONE when cached and incoming are deep equal', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+        expect(result.isCacheStale).toBe(false);
+        expect(result.skipNeptune).toBeUndefined();
+    });
+    it('should return staleTier ADDRESS_UPDATE and skipNeptune=true for new non-IP address', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [{ city: 'New City', s: ADDRESS_INFO_SOURCE.INPUT }],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+        expect(result.isCacheStale).toBe(true);
+        expect(result.skipNeptune).toBe(true);
+        expect(result.writeReason).toBe(CACHE_WRITE_REASON.ADDRESS_UPDATE);
+    });
+    it('should return staleTier IDENTITY_STALE and skipNeptune=false for new email', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['old@email.com', 'new@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+        expect(result.isCacheStale).toBe(true);
+        expect(result.skipNeptune).toBe(false);
+        expect(result.writeReason).toBe(CACHE_WRITE_REASON.STALE_TRAITS);
+    });
+});
+//# sourceMappingURL=identity-cache-tier-routing.spec.js.map