@adtrackify/at-service-common 4.0.3 → 4.0.4

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

@@ -1,728 +1,728 @@
-import { buildIdentityPk, buildEmailPk, buildIdentityMapPk, buildForcePurgePk, } from '@adtrackify/at-tracking-event-types';
-import { mergeIdentityTraits } from '@adtrackify/at-shared-utils';
-import fastDeepEqual from 'fast-deep-equal';
-import { DateTime } from 'luxon';
-import { DynamoDbClient, LambdaInvokeClient } from '../../clients/index.js';
-import { Logger } from '../../helpers/index.js';
-import { isIdentityCacheStale, IDENTITY_CACHE_STALENESS_TIER, } from '../../helpers/identity-cache-helper.js';
-const TABLE_NAME = process.env.IDENTITY_CACHE_TABLE_V2 ?? '';
-const GSI1_NAME = process.env.IDENTITY_CACHE_GSI1 ?? 'gsi1pk-index';
-const FORCE_PURGE_TTL_SECONDS = 60 * 60 * 24 * 30;
-export var CACHE_WRITE_REASON;
-(function (CACHE_WRITE_REASON) {
-    CACHE_WRITE_REASON["CACHE_MISS"] = "cache_miss";
-    CACHE_WRITE_REASON["STALE_TRAITS"] = "stale_traits";
-    CACHE_WRITE_REASON["EMAIL_POINTER_DISCOVERY"] = "email_pointer_discovery";
-    CACHE_WRITE_REASON["ADDRESS_UPDATE"] = "address_update";
-})(CACHE_WRITE_REASON || (CACHE_WRITE_REASON = {}));
-export class IdentityCacheDynamoDbService {
-    static lambdaInvokeClient;
-    static getLambdaInvokeClient() {
-        if (!this.lambdaInvokeClient) {
-            this.lambdaInvokeClient = new LambdaInvokeClient();
-        }
-        return this.lambdaInvokeClient;
-    }
-    static getIdentityWithCaching = async (pixelId, incomingIdentity, identifyPrivateLambdaArn) => {
-        try {
-            if (!pixelId || !incomingIdentity) {
-                Logger.error('IdentityCache - missing required params', { pixelId, incomingIdentity });
-                return undefined;
-            }
-            const cacheResponse = await this.readFromCache(pixelId, incomingIdentity);
-            let resolvedIdentity = cacheResponse.resolvedIdentity;
-            const isCacheStale = cacheResponse.isCacheStale;
-            const cachedIdentity = cacheResponse.cachedIdentity;
-            const staleTracker = cacheResponse.staleTracker;
-            const writeReason = cacheResponse.writeReason;
-            const staleTier = cacheResponse.staleTier;
-            const skipNeptune = cacheResponse.skipNeptune;
-            if (resolvedIdentity && !isCacheStale) {
-                const tierLabel = staleTier === IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY ? 'volatile_traits_only' : 'fresh';
-                Logger.info(`IdentityCache - identity cache hit - ${tierLabel}`, {
-                    pixelId,
-                    identityId: resolvedIdentity.identityId,
-                    staleTier,
-                    cachedIdentity: cachedIdentity ?? null,
-                    incomingIdentity,
-                    resolvedIdentity,
-                    incomingClick: incomingIdentity?.traits?.click ?? null,
-                    cachedClick: cachedIdentity?.traits?.click ?? null,
-                    resolvedClick: resolvedIdentity?.traits?.click ?? null,
-                });
-                return resolvedIdentity;
-            }
-            if (resolvedIdentity && skipNeptune && writeReason === CACHE_WRITE_REASON.ADDRESS_UPDATE) {
-                const staleTraits = staleTracker ? this.extractStaleTraitNames(staleTracker) : [];
-                Logger.info('IdentityCache - identity cache write: address update only (skipping Neptune)', {
-                    pixelId,
-                    identityId: resolvedIdentity.identityId,
-                    writeReason,
-                    staleTier,
-                    staleTraits,
-                    cachedIdentity: cachedIdentity ?? null,
-                    incomingIdentity,
-                    resolvedIdentity,
-                    incomingClick: incomingIdentity?.traits?.click ?? null,
-                    cachedClick: cachedIdentity?.traits?.click ?? null,
-                    resolvedClick: resolvedIdentity?.traits?.click ?? null,
-                    traitChanges: cachedIdentity ? this.computeTraitChanges(cachedIdentity, resolvedIdentity) : { reason: 'no cached identity' },
-                });
-                await this.safeWriteBackToCache(pixelId, resolvedIdentity, 'address update');
-                return resolvedIdentity;
-            }
-            const identityForNeptune = resolvedIdentity ?? incomingIdentity;
-            Logger.info('IdentityCache - identity cache stale - fetching from Neptune', {
-                pixelId,
-                identityId: identityForNeptune?.identityId,
-                staleTier,
-                writeReason,
-                staleTraits: staleTracker ? this.extractStaleTraitNames(staleTracker) : [],
-                cachedIdentity: cachedIdentity ?? null,
-                incomingIdentity,
-                identityForNeptune,
-                incomingClick: incomingIdentity?.traits?.click ?? null,
-                cachedClick: cachedIdentity?.traits?.click ?? null,
-                hasDiscoveredIdentityId: !!resolvedIdentity?.identityId,
-            });
-            const neptuneIdentity = await this.resolveFromNeptune(pixelId, identityForNeptune, identifyPrivateLambdaArn);
-            if (neptuneIdentity) {
-                resolvedIdentity = neptuneIdentity;
-                const cachedForComparison = cachedIdentity ? this.stripAddressTimestamps(cachedIdentity) : undefined;
-                const neptuneForComparison = this.stripAddressTimestamps(neptuneIdentity);
-                const shouldWrite = !cachedForComparison || !fastDeepEqual(cachedForComparison, neptuneForComparison);
-                if (shouldWrite) {
-                    const staleTraits = staleTracker ? this.extractStaleTraitNames(staleTracker) : [];
-                    const isNewIdentity = writeReason === CACHE_WRITE_REASON.CACHE_MISS || writeReason === CACHE_WRITE_REASON.EMAIL_POINTER_DISCOVERY;
-                    const writeType = isNewIdentity ? 'new_identity' : 'stale_traits_update';
-                    Logger.info(`IdentityCache - identity cache write: ${writeType}`, {
-                        pixelId,
-                        identityId: neptuneIdentity.identityId,
-                        writeReason,
-                        staleTier,
-                        staleTraits,
-                        cachedIdentity: cachedIdentity ?? null,
-                        incomingIdentity,
-                        neptuneIdentity,
-                        incomingClick: incomingIdentity?.traits?.click ?? null,
-                        cachedClick: cachedIdentity?.traits?.click ?? null,
-                        neptuneClick: neptuneIdentity?.traits?.click ?? null,
-                        traitChanges: cachedIdentity
-                            ? this.computeTraitChanges(cachedIdentity, neptuneIdentity)
-                            : { reason: 'no cached identity' },
-                    });
-                    await this.safeWriteBackToCache(pixelId, resolvedIdentity, 'neptune write-back');
-                }
-                else {
-                    Logger.info('IdentityCache - identity cache skip write - Neptune matches cached', {
-                        pixelId,
-                        identityId: neptuneIdentity.identityId,
-                        staleTier,
-                        cachedIdentity: cachedIdentity ?? null,
-                        incomingIdentity,
-                        neptuneIdentity,
-                        incomingClick: incomingIdentity?.traits?.click ?? null,
-                        cachedClick: cachedIdentity?.traits?.click ?? null,
-                        neptuneClick: neptuneIdentity?.traits?.click ?? null,
-                    });
-                }
-            }
-            else {
-                Logger.error('IdentityCache - Neptune resolution failed', {
-                    pixelId,
-                    staleTier,
-                    writeReason,
-                    cachedIdentity: cachedIdentity ?? null,
-                    incomingIdentity,
-                    identityForNeptune,
-                    incomingClick: incomingIdentity?.traits?.click ?? null,
-                });
-            }
-            if (!resolvedIdentity) {
-                Logger.error('IdentityCache - no identity found, using incoming', {
-                    pixelId,
-                    incomingIdentity,
-                    incomingClick: incomingIdentity?.traits?.click ?? null,
-                });
-                resolvedIdentity = incomingIdentity;
-            }
-            return resolvedIdentity;
-        }
-        catch (error) {
-            Logger.error('IdentityCache - getIdentityWithCaching failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                incomingIdentity,
-                incomingClick: incomingIdentity?.traits?.click ?? null,
-            });
-            return undefined;
-        }
-    };
-    static getIdentityFromCache = async (pixelId, incomingIdentity) => {
-        try {
-            if (!pixelId || !incomingIdentity) {
-                return { resolvedIdentity: undefined, isCacheStale: true, writeReason: CACHE_WRITE_REASON.CACHE_MISS };
-            }
-            if (incomingIdentity.identityId) {
-                const pk = buildIdentityPk(pixelId, incomingIdentity.identityId);
-                Logger.debug('IdentityCache - lookup by identityId', { pixelId, pk, incomingIdentity });
-                const cachedIdentityResponse = await this.getItemByPk(pk);
-                if (!cachedIdentityResponse) {
-                    Logger.debug('IdentityCache - identity cache miss - no cached identity found', {
-                        pixelId,
-                        identityId: incomingIdentity.identityId,
-                        incomingIdentity,
-                        incomingClick: incomingIdentity?.traits?.click ?? null,
-                    });
-                    return { resolvedIdentity: undefined, isCacheStale: true, writeReason: CACHE_WRITE_REASON.CACHE_MISS };
-                }
-                Logger.debug('IdentityCache - found cached identity', {
-                    pixelId,
-                    identityId: incomingIdentity.identityId,
-                    cachedIdentity: cachedIdentityResponse.response,
-                    cachedClick: cachedIdentityResponse.response?.traits?.click ?? null,
-                });
-                const mergedTraits = mergeIdentityTraits(incomingIdentity.traits, cachedIdentityResponse.response.traits);
-                const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
-                const identityStaleCacheTracker = isIdentityCacheStale(cachedIdentityResponse.response, mergedIdentity);
-                const cachedForComparison = this.stripAddressTimestamps(cachedIdentityResponse.response);
-                const mergedForComparison = this.stripAddressTimestamps(mergedIdentity);
-                const isDeepEqual = fastDeepEqual(cachedForComparison, mergedForComparison);
-                const staleTier = identityStaleCacheTracker.staleTier;
-                let isCacheStale = identityStaleCacheTracker.isCacheStale;
-                if (isDeepEqual) {
-                    Logger.debug('IdentityCache - deep equal (after stripping timestamps)', {
-                        pixelId,
-                        identityId: incomingIdentity.identityId,
-                        staleTier,
-                    });
-                    isCacheStale = false;
-                }
-                else {
-                    Logger.debug('IdentityCache - not deep equal', {
-                        pixelId,
-                        identityId: incomingIdentity.identityId,
-                        staleTier,
-                        identityStaleCacheTracker,
-                        incomingClick: incomingIdentity?.traits?.click ?? null,
-                        cachedClick: cachedIdentityResponse.response?.traits?.click ?? null,
-                        mergedClick: mergedIdentity?.traits?.click ?? null,
-                    });
-                }
-                const isVolatileOnly = staleTier === IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY;
-                const isAddressUpdateOnly = staleTier === IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE;
-                const skipNeptune = isVolatileOnly || isAddressUpdateOnly;
-                if (isVolatileOnly && !isDeepEqual) {
-                    Logger.debug('IdentityCache - volatile only - treating as cache hit', {
-                        pixelId,
-                        identityId: incomingIdentity.identityId,
-                        staleTier,
-                    });
-                    isCacheStale = false;
-                }
-                let writeReason;
-                if (isCacheStale) {
-                    if (isAddressUpdateOnly) {
-                        writeReason = CACHE_WRITE_REASON.ADDRESS_UPDATE;
-                    }
-                    else {
-                        writeReason = CACHE_WRITE_REASON.STALE_TRAITS;
-                    }
-                }
-                if (isCacheStale) {
-                    Logger.debug('IdentityCache - stale detected', {
-                        pixelId,
-                        identityId: incomingIdentity.identityId,
-                        isCacheStale,
-                        isDeepEqual,
-                        staleTier,
-                        skipNeptune,
-                        writeReason,
-                        incomingClick: incomingIdentity?.traits?.click ?? null,
-                        cachedClick: cachedIdentityResponse.response?.traits?.click ?? null,
-                        mergedClick: mergedIdentity?.traits?.click ?? null,
-                    });
-                }
-                return {
-                    resolvedIdentity: mergedIdentity,
-                    isCacheStale,
-                    cachedIdentity: cachedIdentityResponse.response,
-                    staleTracker: isCacheStale ? identityStaleCacheTracker : undefined,
-                    writeReason,
-                    staleTier,
-                    skipNeptune: isCacheStale ? skipNeptune : undefined,
-                };
-            }
-            const discoveredIdentityId = await this.getIdentityIdFromEmailLookup(pixelId, incomingIdentity);
-            if (discoveredIdentityId) {
-                Logger.debug('IdentityCache - identityId from email pointer', {
-                    pixelId,
-                    discoveredIdentityId,
-                    incomingIdentity,
-                    incomingClick: incomingIdentity?.traits?.click ?? null,
-                });
-                const identityWithDiscoveredId = {
-                    ...incomingIdentity,
-                    identityId: discoveredIdentityId,
-                };
-                return { resolvedIdentity: identityWithDiscoveredId, isCacheStale: true, writeReason: CACHE_WRITE_REASON.EMAIL_POINTER_DISCOVERY };
-            }
-            return { resolvedIdentity: undefined, isCacheStale: true, writeReason: CACHE_WRITE_REASON.CACHE_MISS };
-        }
-        catch (error) {
-            Logger.error('IdentityCache - getIdentityFromCache failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                incomingIdentity,
-                incomingClick: incomingIdentity?.traits?.click ?? null,
-            });
-            return { resolvedIdentity: undefined, isCacheStale: true, writeReason: CACHE_WRITE_REASON.CACHE_MISS };
-        }
-    };
-    static getIdentityMap = async (pixelId, identityId) => {
-        try {
-            if (!pixelId || !identityId) {
-                return undefined;
-            }
-            const pk = buildIdentityMapPk(pixelId, identityId);
-            const result = (await DynamoDbClient.safeGet(TABLE_NAME, 'pk', pk));
-            return result ?? undefined;
-        }
-        catch (error) {
-            Logger.error('IdentityCache - getIdentityMap failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                identityId,
-            });
-            return undefined;
-        }
-    };
-    static getForcePurgeFlag = async (pixelId, identityId) => {
-        try {
-            if (!pixelId || !identityId) {
-                return false;
-            }
-            const pk = buildForcePurgePk(pixelId, identityId);
-            const result = await DynamoDbClient.safeGet(TABLE_NAME, 'pk', pk);
-            return result !== null;
-        }
-        catch (error) {
-            Logger.error('IdentityCache - getForcePurgeFlag failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                identityId,
-            });
-            return false;
-        }
-    };
-    static updateIdentityCache = async (pixelId, response) => {
-        try {
-            if (!response?.identityId || !pixelId) {
-                return;
-            }
-            const items = [];
-            const now = new Date().toISOString();
-            items.push({
-                pk: buildIdentityPk(pixelId, response.identityId),
-                response,
-                updatedAt: now,
-                pixelId,
-                identityId: response.identityId,
-                gsi1pk: response.identityId,
-            });
-            const emails = response.traits?.emails ?? [];
-            for (const email of emails) {
-                if (email) {
-                    const pointerRecord = {
-                        pk: buildEmailPk(pixelId, email),
-                        updatedAt: now,
-                        pixelId,
-                        identityId: response.identityId,
-                        gsi1pk: response.identityId,
-                    };
-                    items.push(pointerRecord);
-                }
-            }
-            await DynamoDbClient.safeBatchWrite(TABLE_NAME, items);
-            Logger.debug('IdentityCache - cache written', { pixelId, identityId: response.identityId, itemCount: items.length });
-        }
-        catch (error) {
-            Logger.error('IdentityCache - updateIdentityCache failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-            });
-        }
-    };
-    static putIdentityMap = async (pixelId, identityId, linkedIdentities) => {
-        try {
-            if (!pixelId || !identityId) {
-                return;
-            }
-            const item = {
-                pk: buildIdentityMapPk(pixelId, identityId),
-                pixelId,
-                identityId,
-                linkedIdentities,
-                updatedAt: new Date().toISOString(),
-            };
-            await DynamoDbClient.safePut(TABLE_NAME, item);
-            Logger.debug('IdentityCache - identity map written', { pixelId, identityId, linkedIdentities });
-        }
-        catch (error) {
-            Logger.error('IdentityCache - putIdentityMap failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                identityId,
-            });
-        }
-    };
-    static setForcePurgeFlag = async (pixelId, identityId, ttlSeconds = FORCE_PURGE_TTL_SECONDS) => {
-        try {
-            if (!pixelId || !identityId) {
-                return;
-            }
-            const now = new Date().toISOString();
-            const ttl = DateTime.utc().plus({ seconds: ttlSeconds }).toSeconds();
-            const item = {
-                pk: buildForcePurgePk(pixelId, identityId),
-                pixelId,
-                identityId,
-                createdAt: now,
-                ttl: Math.floor(ttl),
-            };
-            await DynamoDbClient.safePut(TABLE_NAME, item);
-            Logger.debug('IdentityCache - force purge flag set', { pixelId, identityId, ttlSeconds });
-        }
-        catch (error) {
-            Logger.error('IdentityCache - setForcePurgeFlag failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                identityId,
-            });
-        }
-    };
-    static deleteIdentityCache = async (pixelId, incomingIdentity, resolvedIdentity) => {
-        try {
-            if (!pixelId) {
-                return;
-            }
-            const deleteKeys = [];
-            const identityIdsToDelete = new Set();
-            if (incomingIdentity?.identityId) {
-                identityIdsToDelete.add(incomingIdentity.identityId);
-            }
-            if (resolvedIdentity?.identityId) {
-                identityIdsToDelete.add(resolvedIdentity.identityId);
-            }
-            for (const identityId of identityIdsToDelete) {
-                const relatedItems = await this.queryByGsi1(identityId);
-                for (const item of relatedItems) {
-                    if (item.pk && item.pixelId === pixelId) {
-                        deleteKeys.push({ pk: item.pk });
-                    }
-                }
-            }
-            if (incomingIdentity?.traits?.emails) {
-                for (const email of incomingIdentity.traits.emails) {
-                    deleteKeys.push({ pk: buildEmailPk(pixelId, email) });
-                }
-            }
-            if (resolvedIdentity?.traits?.emails) {
-                for (const email of resolvedIdentity.traits.emails) {
-                    deleteKeys.push({ pk: buildEmailPk(pixelId, email) });
-                }
-            }
-            const uniqueKeys = Array.from(new Set(deleteKeys.map((k) => k.pk))).map((pk) => ({ pk }));
-            if (uniqueKeys.length > 0) {
-                await this.safeBatchDelete(uniqueKeys);
-                Logger.debug('IdentityCache - cache items deleted', { pixelId, deletedCount: uniqueKeys.length });
-            }
-        }
-        catch (error) {
-            Logger.error('IdentityCache - deleteIdentityCache failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-            });
-        }
-    };
-    static deleteIdentityMap = async (pixelId, identityId) => {
-        try {
-            if (!pixelId || !identityId) {
-                return;
-            }
-            const pk = buildIdentityMapPk(pixelId, identityId);
-            await DynamoDbClient.safeDelete(TABLE_NAME, 'pk', pk);
-            Logger.debug('IdentityCache - identity map deleted', { pixelId, identityId });
-        }
-        catch (error) {
-            Logger.error('IdentityCache - deleteIdentityMap failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                identityId,
-            });
-        }
-    };
-    static deleteForcePurgeFlag = async (pixelId, identityId) => {
-        try {
-            if (!pixelId || !identityId) {
-                return;
-            }
-            const pk = buildForcePurgePk(pixelId, identityId);
-            await DynamoDbClient.safeDelete(TABLE_NAME, 'pk', pk);
-            Logger.debug('IdentityCache - force purge flag deleted', { pixelId, identityId });
-        }
-        catch (error) {
-            Logger.error('IdentityCache - deleteForcePurgeFlag failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                identityId,
-            });
-        }
-    };
-    static readFromCache = async (pixelId, incomingIdentity) => {
-        return await this.getIdentityFromCache(pixelId, incomingIdentity);
-    };
-    static resolveFromNeptune = async (pixelId, incomingIdentity, identifyPrivateLambdaArn) => {
-        try {
-            const client = this.getLambdaInvokeClient();
-            const response = await client.invokeFunction(identifyPrivateLambdaArn, {
-                pixelId,
-                context: { identity: incomingIdentity },
-            });
-            if (response?.statusCode === 200 && response?.body) {
-                const identifyResponse = JSON.parse(response.body);
-                return identifyResponse?.identity;
-            }
-            return incomingIdentity;
-        }
-        catch (error) {
-            Logger.error('IdentityCache - Neptune resolution failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                incomingIdentity,
-                incomingClick: incomingIdentity?.traits?.click ?? null,
-            });
-            return undefined;
-        }
-    };
-    static writeBackToCache = async (pixelId, resolvedIdentity) => {
-        await this.updateIdentityCache(pixelId, resolvedIdentity);
-    };
-    static safeWriteBackToCache = async (pixelId, resolvedIdentity, context) => {
-        try {
-            await this.writeBackToCache(pixelId, resolvedIdentity);
-        }
-        catch (writeError) {
-            Logger.error(`IdentityCache - write back failed (${context})`, {
-                error: writeError,
-                errorMessage: writeError instanceof Error ? writeError.message : String(writeError),
-                pixelId,
-                identityId: resolvedIdentity?.identityId,
-                resolvedClick: resolvedIdentity?.traits?.click ?? null,
-            });
-        }
-    };
-    static getIdentityIdFromEmailLookup = async (pixelId, incomingIdentity) => {
-        try {
-            if (!pixelId || !incomingIdentity) {
-                return undefined;
-            }
-            const firstEmail = incomingIdentity.traits?.emails?.[0];
-            if (!firstEmail) {
-                return undefined;
-            }
-            const pk = buildEmailPk(pixelId, firstEmail);
-            Logger.debug('IdentityCache - email secondary lookup', { pixelId, pk, email: firstEmail });
-            const result = (await DynamoDbClient.safeGet(TABLE_NAME, 'pk', pk));
-            if (!result) {
-                return undefined;
-            }
-            Logger.debug('IdentityCache - identityId from email lookup', { pixelId, identityId: result.identityId, email: firstEmail });
-            return result.identityId;
-        }
-        catch (error) {
-            Logger.error('IdentityCache - email lookup failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pixelId,
-                incomingIdentity,
-            });
-            return undefined;
-        }
-    };
-    static getItemByPk = async (pk) => {
-        try {
-            const result = (await DynamoDbClient.safeGet(TABLE_NAME, 'pk', pk));
-            return result ?? undefined;
-        }
-        catch (error) {
-            Logger.error('IdentityCache - getItemByPk failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                pk,
-            });
-            return undefined;
-        }
-    };
-    static queryByGsi1 = async (identityId) => {
-        try {
-            const results = await DynamoDbClient.safeQueryByGSI(TABLE_NAME, GSI1_NAME, 'gsi1pk', identityId);
-            return (results ?? []);
-        }
-        catch (error) {
-            Logger.error('IdentityCache - queryByGsi1 failed', {
-                error,
-                errorMessage: error instanceof Error ? error.message : String(error),
-                identityId,
-            });
-            return [];
-        }
-    };
-    static safeBatchDelete = async (keys) => {
-        if (keys.length === 0) {
-            return;
-        }
-        const chunks = this.chunkArray(keys, 25);
-        for (const chunk of chunks) {
-            try {
-                const deleteRequests = chunk.map((key) => ({
-                    DeleteRequest: { Key: { pk: key.pk } },
-                }));
-                await DynamoDbClient.batchWrite({
-                    RequestItems: { [TABLE_NAME]: deleteRequests },
-                });
-            }
-            catch (error) {
-                Logger.error('IdentityCache - batch delete failed', {
-                    error,
-                    errorMessage: error instanceof Error ? error.message : String(error),
-                    chunkSize: chunk.length,
-                });
-            }
-        }
-    };
-    static chunkArray(items, size) {
-        const chunks = [];
-        for (let i = 0; i < items.length; i += size) {
-            chunks.push(items.slice(i, i + size));
-        }
-        return chunks;
-    }
-    static stripAddressTimestamps(identity) {
-        if (!identity?.traits?.addresses?.length) {
-            return identity;
-        }
-        const strippedAddresses = identity.traits.addresses.map((addr) => {
-            if (!addr)
-                return addr;
-            const { cra, upa, ...rest } = addr;
-            return rest;
-        });
-        return {
-            ...identity,
-            traits: {
-                ...identity.traits,
-                addresses: strippedAddresses,
-            },
-        };
-    }
-    static extractStaleTraitNames(tracker) {
-        const staleTraits = [];
-        if (tracker.isIdentityIdStale)
-            staleTraits.push('identityId');
-        if (tracker.isUserIdsStale)
-            staleTraits.push('userIds');
-        if (tracker.isIdsStale)
-            staleTraits.push('ids');
-        if (tracker.isEmailsStale)
-            staleTraits.push('emails');
-        if (tracker.isPhonesStale)
-            staleTraits.push('phones');
-        if (tracker.isShopifyYIdsStale)
-            staleTraits.push('shopifyYIds');
-        if (tracker.isGendersStale)
-            staleTraits.push('genders');
-        if (tracker.isDobsStale)
-            staleTraits.push('dobs');
-        if (tracker.isAddressesStale)
-            staleTraits.push('addresses');
-        if (tracker.isClickInfosStale)
-            staleTraits.push('clickInfos');
-        if (tracker.isIpAddressStale)
-            staleTraits.push('ipAddress');
-        if (tracker.isUserAgentStale)
-            staleTraits.push('userAgent');
-        if (tracker.isThirdPartyContactsStale)
-            staleTraits.push('thirdPartyContacts');
-        return staleTraits;
-    }
-    static computeTraitChanges(cachedIdentity, resolvedIdentity) {
-        const changes = {};
-        const cachedTraits = cachedIdentity.traits ?? {};
-        const resolvedTraits = resolvedIdentity.traits ?? {};
-        const arrayTraits = [
-            'emails',
-            'phones',
-            'userIds',
-            'shopifyYIds',
-            'shopifyCustomerIds',
-            'klaviyoIds',
-            'genders',
-            'dobs',
-            'ids',
-        ];
-        for (const trait of arrayTraits) {
-            const cachedValue = cachedTraits[trait];
-            const resolvedValue = resolvedTraits[trait];
-            if (!fastDeepEqual(cachedValue, resolvedValue)) {
-                changes[trait] = {
-                    cached: cachedValue ?? [],
-                    resolved: resolvedValue ?? [],
-                };
-            }
-        }
-        if (!fastDeepEqual(cachedTraits.addresses, resolvedTraits.addresses)) {
-            changes.addresses = {
-                cached: cachedTraits.addresses ?? [],
-                resolved: resolvedTraits.addresses ?? [],
-            };
-        }
-        if (!fastDeepEqual(cachedTraits.click, resolvedTraits.click)) {
-            changes.click = {
-                cached: cachedTraits.click ?? {},
-                resolved: resolvedTraits.click ?? {},
-            };
-        }
-        if (cachedTraits.ipAddress !== resolvedTraits.ipAddress) {
-            changes.ipAddress = {
-                cached: cachedTraits.ipAddress,
-                resolved: resolvedTraits.ipAddress,
-            };
-        }
-        if (cachedTraits.userAgent !== resolvedTraits.userAgent) {
-            changes.userAgent = {
-                cached: cachedTraits.userAgent,
-                resolved: resolvedTraits.userAgent,
-            };
-        }
-        if (cachedIdentity.identityId !== resolvedIdentity.identityId) {
-            changes.identityId = {
-                cached: cachedIdentity.identityId,
-                resolved: resolvedIdentity.identityId,
-            };
-        }
-        return changes;
-    }
-}
+import { buildIdentityPk, buildEmailPk, buildIdentityMapPk, buildForcePurgePk, } from '@adtrackify/at-tracking-event-types';
+import { mergeIdentityTraits } from '@adtrackify/at-shared-utils';
+import fastDeepEqual from 'fast-deep-equal';
+import { DateTime } from 'luxon';
+import { DynamoDbClient, LambdaInvokeClient } from '../../clients/index.js';
+import { Logger } from '../../helpers/index.js';
+import { isIdentityCacheStale, IDENTITY_CACHE_STALENESS_TIER, } from '../../helpers/identity-cache-helper.js';
+const TABLE_NAME = process.env.IDENTITY_CACHE_TABLE_V2 ?? '';
+const GSI1_NAME = process.env.IDENTITY_CACHE_GSI1 ?? 'gsi1pk-index';
+const FORCE_PURGE_TTL_SECONDS = 60 * 60 * 24 * 30;
+export var CACHE_WRITE_REASON;
+(function (CACHE_WRITE_REASON) {
+    CACHE_WRITE_REASON["CACHE_MISS"] = "cache_miss";
+    CACHE_WRITE_REASON["STALE_TRAITS"] = "stale_traits";
+    CACHE_WRITE_REASON["EMAIL_POINTER_DISCOVERY"] = "email_pointer_discovery";
+    CACHE_WRITE_REASON["ADDRESS_UPDATE"] = "address_update";
+})(CACHE_WRITE_REASON || (CACHE_WRITE_REASON = {}));
+export class IdentityCacheDynamoDbService {
+    static lambdaInvokeClient;
+    static getLambdaInvokeClient() {
+        if (!this.lambdaInvokeClient) {
+            this.lambdaInvokeClient = new LambdaInvokeClient();
+        }
+        return this.lambdaInvokeClient;
+    }
+    static getIdentityWithCaching = async (pixelId, incomingIdentity, identifyPrivateLambdaArn) => {
+        try {
+            if (!pixelId || !incomingIdentity) {
+                Logger.error('IdentityCache - missing required params', { pixelId, incomingIdentity });
+                return undefined;
+            }
+            const cacheResponse = await this.readFromCache(pixelId, incomingIdentity);
+            let resolvedIdentity = cacheResponse.resolvedIdentity;
+            const isCacheStale = cacheResponse.isCacheStale;
+            const cachedIdentity = cacheResponse.cachedIdentity;
+            const staleTracker = cacheResponse.staleTracker;
+            const writeReason = cacheResponse.writeReason;
+            const staleTier = cacheResponse.staleTier;
+            const skipNeptune = cacheResponse.skipNeptune;
+            if (resolvedIdentity && !isCacheStale) {
+                const tierLabel = staleTier === IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY ? 'volatile_traits_only' : 'fresh';
+                Logger.info(`IdentityCache - identity cache hit - ${tierLabel}`, {
+                    pixelId,
+                    identityId: resolvedIdentity.identityId,
+                    staleTier,
+                    cachedIdentity: cachedIdentity ?? null,
+                    incomingIdentity,
+                    resolvedIdentity,
+                    incomingClick: incomingIdentity?.traits?.click ?? null,
+                    cachedClick: cachedIdentity?.traits?.click ?? null,
+                    resolvedClick: resolvedIdentity?.traits?.click ?? null,
+                });
+                return resolvedIdentity;
+            }
+            if (resolvedIdentity && skipNeptune && writeReason === CACHE_WRITE_REASON.ADDRESS_UPDATE) {
+                const staleTraits = staleTracker ? this.extractStaleTraitNames(staleTracker) : [];
+                Logger.info('IdentityCache - identity cache write: address update only (skipping Neptune)', {
+                    pixelId,
+                    identityId: resolvedIdentity.identityId,
+                    writeReason,
+                    staleTier,
+                    staleTraits,
+                    cachedIdentity: cachedIdentity ?? null,
+                    incomingIdentity,
+                    resolvedIdentity,
+                    incomingClick: incomingIdentity?.traits?.click ?? null,
+                    cachedClick: cachedIdentity?.traits?.click ?? null,
+                    resolvedClick: resolvedIdentity?.traits?.click ?? null,
+                    traitChanges: cachedIdentity ? this.computeTraitChanges(cachedIdentity, resolvedIdentity) : { reason: 'no cached identity' },
+                });
+                await this.safeWriteBackToCache(pixelId, resolvedIdentity, 'address update');
+                return resolvedIdentity;
+            }
+            const identityForNeptune = resolvedIdentity ?? incomingIdentity;
+            Logger.info('IdentityCache - identity cache stale - fetching from Neptune', {
+                pixelId,
+                identityId: identityForNeptune?.identityId,
+                staleTier,
+                writeReason,
+                staleTraits: staleTracker ? this.extractStaleTraitNames(staleTracker) : [],
+                cachedIdentity: cachedIdentity ?? null,
+                incomingIdentity,
+                identityForNeptune,
+                incomingClick: incomingIdentity?.traits?.click ?? null,
+                cachedClick: cachedIdentity?.traits?.click ?? null,
+                hasDiscoveredIdentityId: !!resolvedIdentity?.identityId,
+            });
+            const neptuneIdentity = await this.resolveFromNeptune(pixelId, identityForNeptune, identifyPrivateLambdaArn);
+            if (neptuneIdentity) {
+                resolvedIdentity = neptuneIdentity;
+                const cachedForComparison = cachedIdentity ? this.stripAddressTimestamps(cachedIdentity) : undefined;
+                const neptuneForComparison = this.stripAddressTimestamps(neptuneIdentity);
+                const shouldWrite = !cachedForComparison || !fastDeepEqual(cachedForComparison, neptuneForComparison);
+                if (shouldWrite) {
+                    const staleTraits = staleTracker ? this.extractStaleTraitNames(staleTracker) : [];
+                    const isNewIdentity = writeReason === CACHE_WRITE_REASON.CACHE_MISS || writeReason === CACHE_WRITE_REASON.EMAIL_POINTER_DISCOVERY;
+                    const writeType = isNewIdentity ? 'new_identity' : 'stale_traits_update';
+                    Logger.info(`IdentityCache - identity cache write: ${writeType}`, {
+                        pixelId,
+                        identityId: neptuneIdentity.identityId,
+                        writeReason,
+                        staleTier,
+                        staleTraits,
+                        cachedIdentity: cachedIdentity ?? null,
+                        incomingIdentity,
+                        neptuneIdentity,
+                        incomingClick: incomingIdentity?.traits?.click ?? null,
+                        cachedClick: cachedIdentity?.traits?.click ?? null,
+                        neptuneClick: neptuneIdentity?.traits?.click ?? null,
+                        traitChanges: cachedIdentity
+                            ? this.computeTraitChanges(cachedIdentity, neptuneIdentity)
+                            : { reason: 'no cached identity' },
+                    });
+                    await this.safeWriteBackToCache(pixelId, resolvedIdentity, 'neptune write-back');
+                }
+                else {
+                    Logger.info('IdentityCache - identity cache skip write - Neptune matches cached', {
+                        pixelId,
+                        identityId: neptuneIdentity.identityId,
+                        staleTier,
+                        cachedIdentity: cachedIdentity ?? null,
+                        incomingIdentity,
+                        neptuneIdentity,
+                        incomingClick: incomingIdentity?.traits?.click ?? null,
+                        cachedClick: cachedIdentity?.traits?.click ?? null,
+                        neptuneClick: neptuneIdentity?.traits?.click ?? null,
+                    });
+                }
+            }
+            else {
+                Logger.error('IdentityCache - Neptune resolution failed', {
+                    pixelId,
+                    staleTier,
+                    writeReason,
+                    cachedIdentity: cachedIdentity ?? null,
+                    incomingIdentity,
+                    identityForNeptune,
+                    incomingClick: incomingIdentity?.traits?.click ?? null,
+                });
+            }
+            if (!resolvedIdentity) {
+                Logger.error('IdentityCache - no identity found, using incoming', {
+                    pixelId,
+                    incomingIdentity,
+                    incomingClick: incomingIdentity?.traits?.click ?? null,
+                });
+                resolvedIdentity = incomingIdentity;
+            }
+            return resolvedIdentity;
+        }
+        catch (error) {
+            Logger.error('IdentityCache - getIdentityWithCaching failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                incomingIdentity,
+                incomingClick: incomingIdentity?.traits?.click ?? null,
+            });
+            return undefined;
+        }
+    };
+    static getIdentityFromCache = async (pixelId, incomingIdentity) => {
+        try {
+            if (!pixelId || !incomingIdentity) {
+                return { resolvedIdentity: undefined, isCacheStale: true, writeReason: CACHE_WRITE_REASON.CACHE_MISS };
+            }
+            if (incomingIdentity.identityId) {
+                const pk = buildIdentityPk(pixelId, incomingIdentity.identityId);
+                Logger.debug('IdentityCache - lookup by identityId', { pixelId, pk, incomingIdentity });
+                const cachedIdentityResponse = await this.getItemByPk(pk);
+                if (!cachedIdentityResponse) {
+                    Logger.debug('IdentityCache - identity cache miss - no cached identity found', {
+                        pixelId,
+                        identityId: incomingIdentity.identityId,
+                        incomingIdentity,
+                        incomingClick: incomingIdentity?.traits?.click ?? null,
+                    });
+                    return { resolvedIdentity: undefined, isCacheStale: true, writeReason: CACHE_WRITE_REASON.CACHE_MISS };
+                }
+                Logger.debug('IdentityCache - found cached identity', {
+                    pixelId,
+                    identityId: incomingIdentity.identityId,
+                    cachedIdentity: cachedIdentityResponse.response,
+                    cachedClick: cachedIdentityResponse.response?.traits?.click ?? null,
+                });
+                const mergedTraits = mergeIdentityTraits(incomingIdentity.traits, cachedIdentityResponse.response.traits);
+                const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
+                const identityStaleCacheTracker = isIdentityCacheStale(cachedIdentityResponse.response, mergedIdentity);
+                const cachedForComparison = this.stripAddressTimestamps(cachedIdentityResponse.response);
+                const mergedForComparison = this.stripAddressTimestamps(mergedIdentity);
+                const isDeepEqual = fastDeepEqual(cachedForComparison, mergedForComparison);
+                const staleTier = identityStaleCacheTracker.staleTier;
+                let isCacheStale = identityStaleCacheTracker.isCacheStale;
+                if (isDeepEqual) {
+                    Logger.debug('IdentityCache - deep equal (after stripping timestamps)', {
+                        pixelId,
+                        identityId: incomingIdentity.identityId,
+                        staleTier,
+                    });
+                    isCacheStale = false;
+                }
+                else {
+                    Logger.debug('IdentityCache - not deep equal', {
+                        pixelId,
+                        identityId: incomingIdentity.identityId,
+                        staleTier,
+                        identityStaleCacheTracker,
+                        incomingClick: incomingIdentity?.traits?.click ?? null,
+                        cachedClick: cachedIdentityResponse.response?.traits?.click ?? null,
+                        mergedClick: mergedIdentity?.traits?.click ?? null,
+                    });
+                }
+                const isVolatileOnly = staleTier === IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY;
+                const isAddressUpdateOnly = staleTier === IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE;
+                const skipNeptune = isVolatileOnly || isAddressUpdateOnly;
+                if (isVolatileOnly && !isDeepEqual) {
+                    Logger.debug('IdentityCache - volatile only - treating as cache hit', {
+                        pixelId,
+                        identityId: incomingIdentity.identityId,
+                        staleTier,
+                    });
+                    isCacheStale = false;
+                }
+                let writeReason;
+                if (isCacheStale) {
+                    if (isAddressUpdateOnly) {
+                        writeReason = CACHE_WRITE_REASON.ADDRESS_UPDATE;
+                    }
+                    else {
+                        writeReason = CACHE_WRITE_REASON.STALE_TRAITS;
+                    }
+                }
+                if (isCacheStale) {
+                    Logger.debug('IdentityCache - stale detected', {
+                        pixelId,
+                        identityId: incomingIdentity.identityId,
+                        isCacheStale,
+                        isDeepEqual,
+                        staleTier,
+                        skipNeptune,
+                        writeReason,
+                        incomingClick: incomingIdentity?.traits?.click ?? null,
+                        cachedClick: cachedIdentityResponse.response?.traits?.click ?? null,
+                        mergedClick: mergedIdentity?.traits?.click ?? null,
+                    });
+                }
+                return {
+                    resolvedIdentity: mergedIdentity,
+                    isCacheStale,
+                    cachedIdentity: cachedIdentityResponse.response,
+                    staleTracker: isCacheStale ? identityStaleCacheTracker : undefined,
+                    writeReason,
+                    staleTier,
+                    skipNeptune: isCacheStale ? skipNeptune : undefined,
+                };
+            }
+            const discoveredIdentityId = await this.getIdentityIdFromEmailLookup(pixelId, incomingIdentity);
+            if (discoveredIdentityId) {
+                Logger.debug('IdentityCache - identityId from email pointer', {
+                    pixelId,
+                    discoveredIdentityId,
+                    incomingIdentity,
+                    incomingClick: incomingIdentity?.traits?.click ?? null,
+                });
+                const identityWithDiscoveredId = {
+                    ...incomingIdentity,
+                    identityId: discoveredIdentityId,
+                };
+                return { resolvedIdentity: identityWithDiscoveredId, isCacheStale: true, writeReason: CACHE_WRITE_REASON.EMAIL_POINTER_DISCOVERY };
+            }
+            return { resolvedIdentity: undefined, isCacheStale: true, writeReason: CACHE_WRITE_REASON.CACHE_MISS };
+        }
+        catch (error) {
+            Logger.error('IdentityCache - getIdentityFromCache failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                incomingIdentity,
+                incomingClick: incomingIdentity?.traits?.click ?? null,
+            });
+            return { resolvedIdentity: undefined, isCacheStale: true, writeReason: CACHE_WRITE_REASON.CACHE_MISS };
+        }
+    };
+    static getIdentityMap = async (pixelId, identityId) => {
+        try {
+            if (!pixelId || !identityId) {
+                return undefined;
+            }
+            const pk = buildIdentityMapPk(pixelId, identityId);
+            const result = (await DynamoDbClient.safeGet(TABLE_NAME, 'pk', pk));
+            return result ?? undefined;
+        }
+        catch (error) {
+            Logger.error('IdentityCache - getIdentityMap failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                identityId,
+            });
+            return undefined;
+        }
+    };
+    static getForcePurgeFlag = async (pixelId, identityId) => {
+        try {
+            if (!pixelId || !identityId) {
+                return false;
+            }
+            const pk = buildForcePurgePk(pixelId, identityId);
+            const result = await DynamoDbClient.safeGet(TABLE_NAME, 'pk', pk);
+            return result !== null;
+        }
+        catch (error) {
+            Logger.error('IdentityCache - getForcePurgeFlag failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                identityId,
+            });
+            return false;
+        }
+    };
+    static updateIdentityCache = async (pixelId, response) => {
+        try {
+            if (!response?.identityId || !pixelId) {
+                return;
+            }
+            const items = [];
+            const now = new Date().toISOString();
+            items.push({
+                pk: buildIdentityPk(pixelId, response.identityId),
+                response,
+                updatedAt: now,
+                pixelId,
+                identityId: response.identityId,
+                gsi1pk: response.identityId,
+            });
+            const emails = response.traits?.emails ?? [];
+            for (const email of emails) {
+                if (email) {
+                    const pointerRecord = {
+                        pk: buildEmailPk(pixelId, email),
+                        updatedAt: now,
+                        pixelId,
+                        identityId: response.identityId,
+                        gsi1pk: response.identityId,
+                    };
+                    items.push(pointerRecord);
+                }
+            }
+            await DynamoDbClient.safeBatchWrite(TABLE_NAME, items);
+            Logger.debug('IdentityCache - cache written', { pixelId, identityId: response.identityId, itemCount: items.length });
+        }
+        catch (error) {
+            Logger.error('IdentityCache - updateIdentityCache failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+            });
+        }
+    };
+    static putIdentityMap = async (pixelId, identityId, linkedIdentities) => {
+        try {
+            if (!pixelId || !identityId) {
+                return;
+            }
+            const item = {
+                pk: buildIdentityMapPk(pixelId, identityId),
+                pixelId,
+                identityId,
+                linkedIdentities,
+                updatedAt: new Date().toISOString(),
+            };
+            await DynamoDbClient.safePut(TABLE_NAME, item);
+            Logger.debug('IdentityCache - identity map written', { pixelId, identityId, linkedIdentities });
+        }
+        catch (error) {
+            Logger.error('IdentityCache - putIdentityMap failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                identityId,
+            });
+        }
+    };
+    static setForcePurgeFlag = async (pixelId, identityId, ttlSeconds = FORCE_PURGE_TTL_SECONDS) => {
+        try {
+            if (!pixelId || !identityId) {
+                return;
+            }
+            const now = new Date().toISOString();
+            const ttl = DateTime.utc().plus({ seconds: ttlSeconds }).toSeconds();
+            const item = {
+                pk: buildForcePurgePk(pixelId, identityId),
+                pixelId,
+                identityId,
+                createdAt: now,
+                ttl: Math.floor(ttl),
+            };
+            await DynamoDbClient.safePut(TABLE_NAME, item);
+            Logger.debug('IdentityCache - force purge flag set', { pixelId, identityId, ttlSeconds });
+        }
+        catch (error) {
+            Logger.error('IdentityCache - setForcePurgeFlag failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                identityId,
+            });
+        }
+    };
+    static deleteIdentityCache = async (pixelId, incomingIdentity, resolvedIdentity) => {
+        try {
+            if (!pixelId) {
+                return;
+            }
+            const deleteKeys = [];
+            const identityIdsToDelete = new Set();
+            if (incomingIdentity?.identityId) {
+                identityIdsToDelete.add(incomingIdentity.identityId);
+            }
+            if (resolvedIdentity?.identityId) {
+                identityIdsToDelete.add(resolvedIdentity.identityId);
+            }
+            for (const identityId of identityIdsToDelete) {
+                const relatedItems = await this.queryByGsi1(identityId);
+                for (const item of relatedItems) {
+                    if (item.pk && item.pixelId === pixelId) {
+                        deleteKeys.push({ pk: item.pk });
+                    }
+                }
+            }
+            if (incomingIdentity?.traits?.emails) {
+                for (const email of incomingIdentity.traits.emails) {
+                    deleteKeys.push({ pk: buildEmailPk(pixelId, email) });
+                }
+            }
+            if (resolvedIdentity?.traits?.emails) {
+                for (const email of resolvedIdentity.traits.emails) {
+                    deleteKeys.push({ pk: buildEmailPk(pixelId, email) });
+                }
+            }
+            const uniqueKeys = Array.from(new Set(deleteKeys.map((k) => k.pk))).map((pk) => ({ pk }));
+            if (uniqueKeys.length > 0) {
+                await this.safeBatchDelete(uniqueKeys);
+                Logger.debug('IdentityCache - cache items deleted', { pixelId, deletedCount: uniqueKeys.length });
+            }
+        }
+        catch (error) {
+            Logger.error('IdentityCache - deleteIdentityCache failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+            });
+        }
+    };
+    static deleteIdentityMap = async (pixelId, identityId) => {
+        try {
+            if (!pixelId || !identityId) {
+                return;
+            }
+            const pk = buildIdentityMapPk(pixelId, identityId);
+            await DynamoDbClient.safeDelete(TABLE_NAME, 'pk', pk);
+            Logger.debug('IdentityCache - identity map deleted', { pixelId, identityId });
+        }
+        catch (error) {
+            Logger.error('IdentityCache - deleteIdentityMap failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                identityId,
+            });
+        }
+    };
+    static deleteForcePurgeFlag = async (pixelId, identityId) => {
+        try {
+            if (!pixelId || !identityId) {
+                return;
+            }
+            const pk = buildForcePurgePk(pixelId, identityId);
+            await DynamoDbClient.safeDelete(TABLE_NAME, 'pk', pk);
+            Logger.debug('IdentityCache - force purge flag deleted', { pixelId, identityId });
+        }
+        catch (error) {
+            Logger.error('IdentityCache - deleteForcePurgeFlag failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                identityId,
+            });
+        }
+    };
+    static readFromCache = async (pixelId, incomingIdentity) => {
+        return await this.getIdentityFromCache(pixelId, incomingIdentity);
+    };
+    static resolveFromNeptune = async (pixelId, incomingIdentity, identifyPrivateLambdaArn) => {
+        try {
+            const client = this.getLambdaInvokeClient();
+            const response = await client.invokeFunction(identifyPrivateLambdaArn, {
+                pixelId,
+                context: { identity: incomingIdentity },
+            });
+            if (response?.statusCode === 200 && response?.body) {
+                const identifyResponse = JSON.parse(response.body);
+                return identifyResponse?.identity;
+            }
+            return incomingIdentity;
+        }
+        catch (error) {
+            Logger.error('IdentityCache - Neptune resolution failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                incomingIdentity,
+                incomingClick: incomingIdentity?.traits?.click ?? null,
+            });
+            return undefined;
+        }
+    };
+    static writeBackToCache = async (pixelId, resolvedIdentity) => {
+        await this.updateIdentityCache(pixelId, resolvedIdentity);
+    };
+    static safeWriteBackToCache = async (pixelId, resolvedIdentity, context) => {
+        try {
+            await this.writeBackToCache(pixelId, resolvedIdentity);
+        }
+        catch (writeError) {
+            Logger.error(`IdentityCache - write back failed (${context})`, {
+                error: writeError,
+                errorMessage: writeError instanceof Error ? writeError.message : String(writeError),
+                pixelId,
+                identityId: resolvedIdentity?.identityId,
+                resolvedClick: resolvedIdentity?.traits?.click ?? null,
+            });
+        }
+    };
+    static getIdentityIdFromEmailLookup = async (pixelId, incomingIdentity) => {
+        try {
+            if (!pixelId || !incomingIdentity) {
+                return undefined;
+            }
+            const firstEmail = incomingIdentity.traits?.emails?.[0];
+            if (!firstEmail) {
+                return undefined;
+            }
+            const pk = buildEmailPk(pixelId, firstEmail);
+            Logger.debug('IdentityCache - email secondary lookup', { pixelId, pk, email: firstEmail });
+            const result = (await DynamoDbClient.safeGet(TABLE_NAME, 'pk', pk));
+            if (!result) {
+                return undefined;
+            }
+            Logger.debug('IdentityCache - identityId from email lookup', { pixelId, identityId: result.identityId, email: firstEmail });
+            return result.identityId;
+        }
+        catch (error) {
+            Logger.error('IdentityCache - email lookup failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pixelId,
+                incomingIdentity,
+            });
+            return undefined;
+        }
+    };
+    static getItemByPk = async (pk) => {
+        try {
+            const result = (await DynamoDbClient.safeGet(TABLE_NAME, 'pk', pk));
+            return result ?? undefined;
+        }
+        catch (error) {
+            Logger.error('IdentityCache - getItemByPk failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                pk,
+            });
+            return undefined;
+        }
+    };
+    static queryByGsi1 = async (identityId) => {
+        try {
+            const results = await DynamoDbClient.safeQueryByGSI(TABLE_NAME, GSI1_NAME, 'gsi1pk', identityId);
+            return (results ?? []);
+        }
+        catch (error) {
+            Logger.error('IdentityCache - queryByGsi1 failed', {
+                error,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                identityId,
+            });
+            return [];
+        }
+    };
+    static safeBatchDelete = async (keys) => {
+        if (keys.length === 0) {
+            return;
+        }
+        const chunks = this.chunkArray(keys, 25);
+        for (const chunk of chunks) {
+            try {
+                const deleteRequests = chunk.map((key) => ({
+                    DeleteRequest: { Key: { pk: key.pk } },
+                }));
+                await DynamoDbClient.batchWrite({
+                    RequestItems: { [TABLE_NAME]: deleteRequests },
+                });
+            }
+            catch (error) {
+                Logger.error('IdentityCache - batch delete failed', {
+                    error,
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                    chunkSize: chunk.length,
+                });
+            }
+        }
+    };
+    static chunkArray(items, size) {
+        const chunks = [];
+        for (let i = 0; i < items.length; i += size) {
+            chunks.push(items.slice(i, i + size));
+        }
+        return chunks;
+    }
+    static stripAddressTimestamps(identity) {
+        if (!identity?.traits?.addresses?.length) {
+            return identity;
+        }
+        const strippedAddresses = identity.traits.addresses.map((addr) => {
+            if (!addr)
+                return addr;
+            const { cra, upa, ...rest } = addr;
+            return rest;
+        });
+        return {
+            ...identity,
+            traits: {
+                ...identity.traits,
+                addresses: strippedAddresses,
+            },
+        };
+    }
+    static extractStaleTraitNames(tracker) {
+        const staleTraits = [];
+        if (tracker.isIdentityIdStale)
+            staleTraits.push('identityId');
+        if (tracker.isUserIdsStale)
+            staleTraits.push('userIds');
+        if (tracker.isIdsStale)
+            staleTraits.push('ids');
+        if (tracker.isEmailsStale)
+            staleTraits.push('emails');
+        if (tracker.isPhonesStale)
+            staleTraits.push('phones');
+        if (tracker.isShopifyYIdsStale)
+            staleTraits.push('shopifyYIds');
+        if (tracker.isGendersStale)
+            staleTraits.push('genders');
+        if (tracker.isDobsStale)
+            staleTraits.push('dobs');
+        if (tracker.isAddressesStale)
+            staleTraits.push('addresses');
+        if (tracker.isClickInfosStale)
+            staleTraits.push('clickInfos');
+        if (tracker.isIpAddressStale)
+            staleTraits.push('ipAddress');
+        if (tracker.isUserAgentStale)
+            staleTraits.push('userAgent');
+        if (tracker.isThirdPartyContactsStale)
+            staleTraits.push('thirdPartyContacts');
+        return staleTraits;
+    }
+    static computeTraitChanges(cachedIdentity, resolvedIdentity) {
+        const changes = {};
+        const cachedTraits = cachedIdentity.traits ?? {};
+        const resolvedTraits = resolvedIdentity.traits ?? {};
+        const arrayTraits = [
+            'emails',
+            'phones',
+            'userIds',
+            'shopifyYIds',
+            'shopifyCustomerIds',
+            'klaviyoIds',
+            'genders',
+            'dobs',
+            'ids',
+        ];
+        for (const trait of arrayTraits) {
+            const cachedValue = cachedTraits[trait];
+            const resolvedValue = resolvedTraits[trait];
+            if (!fastDeepEqual(cachedValue, resolvedValue)) {
+                changes[trait] = {
+                    cached: cachedValue ?? [],
+                    resolved: resolvedValue ?? [],
+                };
+            }
+        }
+        if (!fastDeepEqual(cachedTraits.addresses, resolvedTraits.addresses)) {
+            changes.addresses = {
+                cached: cachedTraits.addresses ?? [],
+                resolved: resolvedTraits.addresses ?? [],
+            };
+        }
+        if (!fastDeepEqual(cachedTraits.click, resolvedTraits.click)) {
+            changes.click = {
+                cached: cachedTraits.click ?? {},
+                resolved: resolvedTraits.click ?? {},
+            };
+        }
+        if (cachedTraits.ipAddress !== resolvedTraits.ipAddress) {
+            changes.ipAddress = {
+                cached: cachedTraits.ipAddress,
+                resolved: resolvedTraits.ipAddress,
+            };
+        }
+        if (cachedTraits.userAgent !== resolvedTraits.userAgent) {
+            changes.userAgent = {
+                cached: cachedTraits.userAgent,
+                resolved: resolvedTraits.userAgent,
+            };
+        }
+        if (cachedIdentity.identityId !== resolvedIdentity.identityId) {
+            changes.identityId = {
+                cached: cachedIdentity.identityId,
+                resolved: resolvedIdentity.identityId,
+            };
+        }
+        return changes;
+    }
+}
 //# sourceMappingURL=identity-cache-dynamodb-service.js.map