Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(integration): match a handover across a chat's lid and phone ids
Yudhi Armyndharis2c305938dc24
diff --git a/src/engine/identity/lid-mapping-store.service.ts b/src/engine/identity/lid-mapping-store.service.tsindex e4b66b7c4..0a57c23d6 100644--- a/src/engine/identity/lid-mapping-store.service.ts+++ b/src/engine/identity/lid-mapping-store.service.ts@@ -47,8 +47,9 @@ export interface LidMappingStore {* A cache miss is warmed from the table in the background (rows past the preload cap stay resolvable)* and otherwise falls back to engine re-resolution (the table remains the source of truth), so eviction* only costs a re-resolution, never data loss. The reverse map has no such warm path (nothing looks a- * lid up by phone), so a phone-keyed filter uses {@link findLidsForPhone}, which reads the table. The reverse map is reconciled on each eviction so it does- * not retain entries for LIDs no longer in the forward cache.+ * lid up by phone), so a phone-keyed filter uses {@link findLidsForPhone}, which reads the table. The+ * reverse map is reconciled on each eviction so it does not retain entries for LIDs no longer in the+ * forward cache.*/@Injectable()export class LidMappingStoreService implements LidMappingStore, OnModuleInit {@@ -172,6 +173,22 @@ export class LidMappingStoreService implements LidMappingStore, OnModuleInit {return [...lids];}+ /**+ * Forward lookup that reads the table on a cache miss, for callers that can await (the handover+ * gate). {@link getCached} answers a miss with undefined and only warms in the background, which+ * is exactly when a mapping past the cap or evicted matters. Like {@link findLidsForPhone}, the row+ * is not indexed, and a read error answers null.+ */+ async findPhoneForLid(lid: string): Promise<string | null> {+ if (this.lidToPhone.has(lid)) return this.getCached(lid) ?? null;+ try {+ return (await this.repo.findOne({ where: { lid } }))?.phone ?? null;+ } catch (err) {+ this.logger.warn(`Could not read the phone for a lid: ${err instanceof Error ? err.message : String(err)}`);+ return null;+ }+ }+async remember(lid: string, phone: string | null, sessionId?: string): Promise<void> {if (!lid || this.lidToPhone.get(lid) === phone) {return; // unseen-or-changed only; a no-op write would just churn updatedAtdiff --git a/src/engine/identity/lid-mapping-store.spec.ts b/src/engine/identity/lid-mapping-store.spec.tsindex 7711f75dc..1931cb67c 100644--- a/src/engine/identity/lid-mapping-store.spec.ts+++ b/src/engine/identity/lid-mapping-store.spec.ts@@ -153,6 +153,23 @@ describe('LidMappingStoreService — LRU cap', () => {expect(await store.findLidsForPhone('628000')).toEqual(['111']);});+ it('finds a phone by lid from the table on a cache miss, without indexing the row', async () => {+ process.env.LID_MAPPING_CACHE_MAX = '1';+ const repo = makeFakeRepo();+ const store = new LidMappingStoreService(repo as unknown as Repository<LidMapping>);+ await store.onModuleInit();++ await store.remember('lid-a', '620001');+ await store.remember('lid-b', '620002'); // evicts lid-a; its row stays persisted+ expect(await store.findPhoneForLid('lid-a')).toBe('620001');+ expect(await store.findPhoneForLid('lid-b')).toBe('620002');+ expect(await store.findPhoneForLid('lid-x')).toBeNull();+ expect(store.lidsForPhone('620002')).toEqual(['lid-b']); // the table read did not evict it++ repo.findOne.mockRejectedValueOnce(new Error('connection lost'));+ expect(await store.findPhoneForLid('lid-a')).toBeNull();+ });+it('reconciles the reverse map on eviction (no orphan phoneToLids entries)', async () => {process.env.LID_MAPPING_CACHE_MAX = '2';const repo = makeFakeRepo();diff --git a/src/modules/integration/conversation-mapping.service.spec.ts b/src/modules/integration/conversation-mapping.service.spec.tsindex 83164a608..a19bd12d6 100644--- a/src/modules/integration/conversation-mapping.service.spec.ts+++ b/src/modules/integration/conversation-mapping.service.spec.ts@@ -1,7 +1,9 @@-import { DataSource } from 'typeorm';+import { DataSource, Repository } from 'typeorm';import { ConversationMapping } from './entities/conversation-mapping.entity';import { ConversationMappingConflict, ConversationMappingService, MappingKey } from './conversation-mapping.service';import { AddIntegrationFabric1781900000000 } from '../../database/migrations/1781900000000-AddIntegrationFabric';+import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';+import { LidMapping } from '../../engine/identity/lid-mapping.entity';describe('ConversationMappingService', () => {let ds: DataSource;@@ -87,6 +89,144 @@ describe('ConversationMappingService', () => {expect(await service.findHandoverForChat('sess-1', 'other-chat')).toBeNull();});+ describe('findHandoverForChat across the lid and phone forms of one chat', () => {+ // lid 111 -> phone 628999. A 1:1 chat's neutral id flips from `111@lid` to `[email protected]` once the+ // mapping is learned, so a takeover recorded under either form has to govern the other. The store is+ // real but its cache is empty, as for a mapping past the preload cap or evicted: only the table has it.+ const table = [{ lid: '111', phone: '628999' }];+ const lidStore = new LidMappingStoreService({+ find: ({ where }: { where: { phone: string } }) => Promise.resolve(table.filter(r => r.phone === where.phone)),+ findOne: ({ where }: { where: { lid: string } }) => Promise.resolve(table.find(r => r.lid === where.lid) ?? null),+ } as unknown as Repository<LidMapping>);+ const human = (chatId: string, provider = 'convB') =>+ service.upsert({ sessionId: 'sess-1', chatId, pluginId: 'chatwoot-adapter', instanceId: 'i2' }, provider, {+ handoverState: 'human',+ });+ const bot = (chatId: string, provider: string) =>+ service.upsert({ sessionId: 'sess-1', chatId, pluginId: 'chatwoot-adapter', instanceId: 'i2' }, provider);++ beforeEach(() => {+ service = new ConversationMappingService(ds.getRepository(ConversationMapping), lidStore);+ });++ it('finds a takeover stored under the lid when the chat now arrives by phone', async () => {+ await human('111@lid');+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toEqual({+ pluginId: 'chatwoot-adapter',+ handoverState: 'human',+ });+ });++ it('finds a takeover stored under the phone when the chat arrives by lid', async () => {+ await human('[email protected]');+ expect(await service.findHandoverForChat('sess-1', '111@lid')).toEqual({+ pluginId: 'chatwoot-adapter',+ handoverState: 'human',+ });+ });++ it('does not match another person', async () => {+ await human('111@lid');+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();+ });++ const row = (chatId: string) =>+ service.get({ sessionId: 'sess-1', chatId, pluginId: 'chatwoot-adapter', instanceId: 'i2' });++ it('keeps the takeover when the flip makes the adapter link a fresh row under the phone form', async () => {+ await human('111@lid');+ await bot('[email protected]', 'convC'); // linked by the flip, not a hand-back+ await bot('[email protected]', 'convC'); // and re-linked idempotently+ expect((await row('[email protected]'))!.handoverState).toBe('human');+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toEqual({+ pluginId: 'chatwoot-adapter',+ handoverState: 'human',+ });+ });++ it('a hand-back under either form clears both, and an idempotent upsert does not revive it', async () => {+ await human('111@lid');+ await bot('[email protected]', 'convC');+ await service.setHandover((await row('[email protected]'))!.id, 'bot'); // the agent hands the chat back+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();+ expect(await service.findHandoverForChat('sess-1', '111@lid')).toBeNull();++ await bot('111@lid', 'convB'); // the adapter re-links the lid row with nothing changed+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();+ });++ it('a takeover under either form survives an idempotent upsert of the other form', async () => {+ await bot('111@lid', 'convB');+ await bot('[email protected]', 'convC');+ await service.setHandover((await row('111@lid'))!.id, 'human');+ await bot('[email protected]', 'convC');+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toEqual({+ pluginId: 'chatwoot-adapter',+ handoverState: 'human',+ });+ });++ it('a hand-back reaches a row whose form was paired after the takeover', async () => {+ await human('111@lid');+ await bot('[email protected]', 'convC'); // inherits the takeover+ table.push({ lid: '333', phone: '628999' }); // another lid for the number is learned meanwhile+ try {+ await service.setHandover((await row('[email protected]'))!.id, 'bot');+ expect((await row('111@lid'))!.handoverState).toBe('bot');+ expect(await service.findHandoverForChat('sess-1', '111@lid')).toBeNull();+ } finally {+ table.pop();+ }+ });++ it('a decision on one lid of a number reaches its sibling lid and the phone-form row', async () => {+ table.push({ lid: '222', phone: '628999' });+ try {+ await bot('111@lid', 'convB');+ await bot('222@lid', 'convD');+ await service.setHandover((await row('222@lid'))!.id, 'human');+ expect(await service.findHandoverForChat('sess-1', '111@lid')).toEqual({+ pluginId: 'chatwoot-adapter',+ handoverState: 'human',+ });+ await bot('[email protected]', 'convC'); // a phone-form row joins and inherits the takeover+ expect((await row('[email protected]'))!.handoverState).toBe('human');+ await service.setHandover((await row('111@lid'))!.id, 'bot');+ expect((await row('[email protected]'))!.handoverState).toBe('bot');+ expect(await service.findHandoverForChat('sess-1', '222@lid')).toBeNull();+ } finally {+ table.pop();+ }+ });++ it('a hand-back that lands while a row under the other form is being linked still reaches it', async () => {+ await human('111@lid');+ const repo = ds.getRepository(ConversationMapping);+ const save = repo.save.bind(repo);+ jest.spyOn(repo, 'save').mockImplementationOnce(async (entity: unknown) => {+ // The agent hands back on the lid conversation after the new row read the takeover.+ await service.setHandover((await row('111@lid'))!.id, 'bot');+ return save(entity as ConversationMapping);+ });+ await bot('[email protected]', 'convC');+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();+ });++ it('a row rebound from a deleted session keeps a takeover a fresh row in the new session does not hold', async () => {+ await human('111@lid');+ // The session is re-paired, and the chat arrives by phone before the old lid row is rebound.+ await service.upsert(+ { sessionId: 'sess-2', chatId: '[email protected]', pluginId: 'chatwoot-adapter', instanceId: 'i2' },+ 'convC',+ );+ await service.rebindSession((await row('111@lid'))!.id, 'sess-2');+ expect(await service.findHandoverForChat('sess-2', '[email protected]')).toEqual({+ pluginId: 'chatwoot-adapter',+ handoverState: 'human',+ });+ });+ });+it('delete removes the row so a later reverse-key insert no longer conflicts', async () => {await service.upsert(key, 'conv-1');const row = await service.get(key);diff --git a/src/modules/integration/conversation-mapping.service.ts b/src/modules/integration/conversation-mapping.service.tsindex 7ce03e55d..ca2c4e4f3 100644--- a/src/modules/integration/conversation-mapping.service.ts+++ b/src/modules/integration/conversation-mapping.service.ts@@ -1,8 +1,10 @@-import { Injectable } from '@nestjs/common';+import { Injectable, Optional } from '@nestjs/common';import { InjectRepository } from '@nestjs/typeorm';-import { QueryDeepPartialEntity, Repository } from 'typeorm';+import { In, QueryDeepPartialEntity, Repository } from 'typeorm';import { ConversationMapping, HandoverState } from './entities/conversation-mapping.entity';import { isUniqueViolation } from '../../common/utils/db-errors';+import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';+import { parseWaId } from '../../engine/identity/wa-id';// Type-only: PluginsModule binds this class to PLUGIN_CONVERSATION_MAPPING_PORT with a `useExisting`// alias, which TypeScript does not check, so `implements` is what keeps the two in step.import type { PluginConversationMappingPort } from '../../core/plugins/plugin-host-ports';@@ -34,7 +36,10 @@ export class ConversationMappingConflict extends Error {@Injectable()export class ConversationMappingService implements PluginConversationMappingPort {- constructor(@InjectRepository(ConversationMapping, 'data') private readonly repo: Repository<ConversationMapping>) {}+ constructor(+ @InjectRepository(ConversationMapping, 'data') private readonly repo: Repository<ConversationMapping>,+ @Optional() private readonly lidMappingStore?: LidMappingStoreService,+ ) {}async upsert(key: MappingKey, providerConversationId: string, patch?: Partial<ConversationMapping>): Promise<void> {const existing = await this.repo.findOne({ where: key });@@ -43,7 +48,14 @@ export class ConversationMappingService implements PluginConversationMappingPortreturn;}try {- await this.repo.save(this.repo.create({ ...key, providerConversationId, handoverState: 'bot', ...patch }));+ const handoverState = await this.inheritedHandover(key);+ await this.repo.save(this.repo.create({ ...key, providerConversationId, handoverState, ...patch }));+ // A hand-back on the other form between the read above and this insert did not reach the new row;+ // read again now that the row exists (a later decision updates it directly).+ if (!patch?.handoverState && handoverState !== 'bot') {+ const current = await this.inheritedHandover(key);+ if (current !== handoverState) await this.repo.update({ ...key }, { handoverState: current });+ }} catch (err) {if (!isUniqueViolation(err)) throw err;// A concurrent writer inserted between our findOne and save (forward-key race) OR the reverse@@ -81,21 +93,55 @@ export class ConversationMappingService implements PluginConversationMappingPortreturn this.repo.findOne({ where: key });}- // Session+chat-scoped handover lookup for the core gate: the most-recently-updated human/closed row for- // this chat, IGNORING pluginId. A handover taken by one plugin (e.g. the Chatwoot relay) then governs- // every plugin on that chat — the gate exempts the owner and silences the rest.+ // Session+chat-scoped handover lookup for the core gate: a human/closed state held by any row for this+ // chat, IGNORING pluginId. A handover taken by one plugin (e.g. the Chatwoot relay) then governs every+ // plugin on that chat — the gate exempts the owner and silences the rest.+ //+ // A 1:1 chat's neutral id is `<lid>@lid` while its lid is unresolved and `<phone>@c.us` once the+ // mapping is learned, so a row written under one form is matched from the other as well. Keyed on+ // the literal id alone, a takeover recorded before the mapping was learned stopped applying after+ // it, and the bot answered a chat a human had taken over. Rows stay keyed on the literal id, so one+ // plugin instance can hold a row under each form; setHandover writes the decision to every one of+ // them, and a new row under another form starts in the state the instance already holds, so they agree.async findHandoverForChat(sessionId: string,chatId: string,): Promise<{ pluginId: string; handoverState: HandoverState } | null> {- const row = await this.repo.findOne({- where: [- { sessionId, chatId, handoverState: 'human' },- { sessionId, chatId, handoverState: 'closed' },- ],+ const rows = await this.repo.find({+ where: { sessionId, chatId: In(await this.chatIdAliases(chatId)) },order: { updatedAt: 'DESC' },});- return row ? { pluginId: row.pluginId, handoverState: row.handoverState } : null;+ const held = rows.find(row => row.handoverState === 'human' || row.handoverState === 'closed');+ return held ? { pluginId: held.pluginId, handoverState: held.handoverState } : null;+ }++ // A plugin instance's first row under a chat's other id form starts in the handover the instance holds+ // under the old form. The adapter finds no mapping for the new form and links a fresh one; starting+ // it as 'bot' would leave the two forms disagreeing about a takeover.+ private async inheritedHandover(key: MappingKey): Promise<HandoverState> {+ const others = (await this.chatIdAliases(key.chatId)).filter(id => id !== key.chatId);+ if (!others.length) return 'bot';+ const prior = await this.repo.find({ where: { ...key, chatId: In(others) } });+ return prior.find(row => row.handoverState !== 'bot')?.handoverState ?? 'bot';+ }++ /**+ * The chat id plus its other individual forms: the phone it belongs to and every lid of that phone.+ * A number WhatsApp recycled keeps its earlier owner's lid in the table too, and the table cannot+ * tell which lid is current (a mapping is re-stamped whenever it is seen again), so for handover the+ * two owners' chats are one chat: a takeover or a hand-back on either reaches both.+ */+ private async chatIdAliases(chatId: string): Promise<string[]> {+ const ids = new Set([chatId]);+ const { kind, userPart } = parseWaId(chatId);+ const store = this.lidMappingStore;+ const phone = kind === 'lid' ? await store?.findPhoneForLid(userPart) : kind === 'user' ? userPart : null;+ if (phone && store) {+ // The whole set: the phone and every lid of it, so a lid reaches its sibling lids as the phone does.+ ids.add(`${phone}@c.us`);+ for (const lid of await store.findLidsForPhone(phone)) ids.add(`${lid}@lid`);+ }+ return [...ids];}getByProvider(@@ -106,8 +152,17 @@ export class ConversationMappingService implements PluginConversationMappingPortreturn this.repo.findOne({ where: { pluginId, instanceId, providerConversationId } });}+ // A handover decision is about the chat, not one id form of it: it is written to every row this plugin+ // instance holds for the chat in the session, so a later write to one form (an idempotent upsert)+ // cannot revive or drop the decision through the other. A row rebound from a deleted session keeps+ // the state it carried; where that disagrees with its other form, the gate reads the chat as taken+ // over until the next decision, which errs on the side of keeping the bot quiet.async setHandover(id: string, state: HandoverState): Promise<void> {- await this.repo.update({ id }, { handoverState: state });+ const row = await this.repo.findOne({ where: { id } });+ if (!row) return;+ const { sessionId, pluginId, instanceId } = row;+ const chatId = In(await this.chatIdAliases(row.chatId));+ await this.repo.update({ sessionId, pluginId, instanceId, chatId }, { handoverState: state });}/**