Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

15.7 KB
Raw Blame
import { DataSource, FindOperator, 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';

/** The `In([...])` condition a lid-table fake honours; an absent condition matches every row. */
const inList = (value: string, cond?: FindOperator<string>): boolean =>
  cond === undefined || (cond.value as unknown as string[]).includes(value);

describe('ConversationMappingService', () => {
  let ds: DataSource;
  let service: ConversationMappingService;
  beforeEach(async () => {
    ds = new DataSource({
      type: 'better-sqlite3',
      database: ':memory:',
      entities: [ConversationMapping],
      migrations: [],
    });
    await ds.initialize();
    const runner = ds.createQueryRunner();
    await new AddIntegrationFabric1781900000000().up(runner);
    await runner.release();
    service = new ConversationMappingService(ds.getRepository(ConversationMapping));
  });
  afterEach(async () => {
    if (ds.isInitialized) await ds.destroy();
  });

  const key: MappingKey = { sessionId: 'sess-1', chatId: 'chat-1', pluginId: 'chatwoot', instanceId: 'acct1' };

  it('upserts a mapping then get(forwardKey) returns it with a non-empty id', async () => {
    await service.upsert(key, 'conv-1');
    const found = await service.get(key);
    expect(found).not.toBeNull();
    expect(found?.id).toEqual(expect.any(String));
    expect(found?.id.length).toBeGreaterThan(0);
    expect(found?.providerConversationId).toBe('conv-1');
  });

  it('getByProvider reverse lookup returns the same row', async () => {
    await service.upsert(key, 'conv-1');
    const forward = await service.get(key);
    const reverse = await service.getByProvider(key.pluginId, key.instanceId, 'conv-1');
    expect(reverse).not.toBeNull();
    expect(reverse?.id).toBe(forward?.id);
  });

  it('upserting again on the same forward key updates providerConversationId instead of inserting a duplicate', async () => {
    await service.upsert(key, 'conv-1');
    const first = await service.get(key);

    await service.upsert(key, 'conv-2');
    const second = await service.get(key);

    expect(second?.id).toBe(first?.id);
    expect(second?.providerConversationId).toBe('conv-2');

    const stale = await service.getByProvider(key.pluginId, key.instanceId, 'conv-1');
    expect(stale).toBeNull();
  });

  it('rethrows ConversationMappingConflict when a providerConversationId is already bound to a different chat', async () => {
    // Reverse unique key (pluginId, instanceId, providerConversationId): binding conv-1 to chat-1 then to
    // a different chat-2 for the same plugin+instance is a genuine conflict with no forward row to
    // converge onto — it must surface, not silently corrupt or fail-soft to a nonexistent row.
    await service.upsert(key, 'conv-1');
    await expect(
      service.upsert({ sessionId: 'sess-1', chatId: 'chat-2', pluginId: 'chatwoot', instanceId: 'acct1' }, 'conv-1'),
    ).rejects.toBeInstanceOf(ConversationMappingConflict);
  });

  it('converges (updates, does not throw) when the same forward key already exists', async () => {
    await service.upsert(key, 'conv-1');
    await expect(service.upsert(key, 'conv-9')).resolves.toBeUndefined();
    expect((await service.get(key))?.providerConversationId).toBe('conv-9');
  });

  it('findHandoverForChat returns any human/closed row for the chat, ignoring pluginId', async () => {
    // faq-bot keeps a bot mapping; chatwoot-adapter takes the same chat over (human).
    await service.upsert({ sessionId: 'sess-1', chatId: 'chat-1', pluginId: 'faq-bot', instanceId: 'i1' }, 'convA');
    await service.upsert(
      { sessionId: 'sess-1', chatId: 'chat-1', pluginId: 'chatwoot-adapter', instanceId: 'i2' },
      'convB',
      { handoverState: 'human' },
    );
    expect(await service.findHandoverForChat('sess-1', 'chat-1')).toEqual({
      pluginId: 'chatwoot-adapter',
      handoverState: 'human',
    });
    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', isReported: true }];
    const lidStore = new LidMappingStoreService({
      find: ({ where }: { where: { lid?: FindOperator<string>; phone?: FindOperator<string> } }) =>
        Promise.resolve(table.filter(r => inList(r.lid, where.lid) && inList(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();
    });

    it('does not share takeover decisions through an unreported phone alias', async () => {
      table[0].isReported = false;
      try {
        await human('111@lid');
        expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();
        await bot('[email protected]', 'convC');
        expect((await row('[email protected]'))!.handoverState).toBe('bot');
        await service.setHandover((await row('[email protected]'))!.id, 'bot');
        expect((await row('111@lid'))!.handoverState).toBe('human');
      } finally {
        table[0].isReported = true;
      }
    });

    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', isReported: true }); // 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', isReported: true });
      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 insert = repo.insert.bind(repo);
      jest.spyOn(repo, 'insert').mockImplementationOnce(async (entity: Parameters<typeof insert>[0]) => {
        // 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 insert(entity);
      });
      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('releaseTakeovers hands a plugin back its chats and leaves the mappings and other plugins alone', async () => {
    await service.upsert(key, 'conv-1', { handoverState: 'human' });
    await service.upsert({ ...key, chatId: 'chat-2' }, 'conv-2', { handoverState: 'closed' });
    await service.upsert({ ...key, pluginId: 'other', chatId: 'chat-3' }, 'conv-3', { handoverState: 'human' });
    expect(await service.findHandoverForChat('sess-1', 'chat-1')).toMatchObject({ handoverState: 'human' });

    await service.releaseTakeovers('chatwoot');

    expect(await service.findHandoverForChat('sess-1', 'chat-1')).toBeNull();
    expect(await service.findHandoverForChat('sess-1', 'chat-2')).toBeNull();
    expect((await service.get(key))?.providerConversationId).toBe('conv-1');
    expect(await service.findHandoverForChat('sess-1', 'chat-3')).toMatchObject({
      pluginId: 'other',
      handoverState: 'human',
    });
  });

  // SQLite serves every repository from one connection, so a transaction the insert opens is shared with
  // the writes made while it is open, and the rollback of the conflict it expects would undo them too.
  it('does not undo a write made while an upsert is refused for a bound conversation', async () => {
    await service.upsert(key, 'conv-1');
    const repo = ds.getRepository(ConversationMapping);
    const other = { ...key, instanceId: 'acct2', chatId: 'chat-9' };
    let concurrent: Promise<unknown> | undefined;
    ds.subscribers.push({
      listenTo: () => ConversationMapping,
      beforeInsert: event => {
        if ((event.entity as ConversationMapping).chatId === 'chat-3') {
          concurrent = repo.insert({ ...other, providerConversationId: 'conv-9' });
        }
      },
    });

    await expect(service.upsert({ ...key, chatId: 'chat-3' }, 'conv-1')).rejects.toBeInstanceOf(
      ConversationMappingConflict,
    );
    await concurrent;

    expect(await service.get(other)).not.toBeNull();
  });

  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);
    if (!row) throw new Error('expected a mapping row');

    await service.delete(row.id);

    expect(await service.get(key)).toBeNull();
    // The reverse key is free again: binding conv-1 to a different chat now succeeds.
    await expect(
      service.upsert({ sessionId: 'sess-2', chatId: 'chat-2', pluginId: 'chatwoot', instanceId: 'acct1' }, 'conv-1'),
    ).resolves.toBeUndefined();
  });

  it('rebindSession moves a stale row onto the current session (forward key moves with it)', async () => {
    await service.upsert(key, 'conv-1');
    const row = await service.get(key);
    if (!row) throw new Error('expected a mapping row');

    await service.rebindSession(row.id, 'sess-2');

    expect(await service.get(key)).toBeNull();
    const rebound = await service.getByProvider(key.pluginId, key.instanceId, 'conv-1');
    expect(rebound?.sessionId).toBe('sess-2');
    expect(
      await service.get({ sessionId: 'sess-2', chatId: 'chat-1', pluginId: 'chatwoot', instanceId: 'acct1' }),
    ).not.toBeNull();
  });

  it('rebindSession supersedes (deletes) the stale row when the current session already owns the chat', async () => {
    // sess-1's row and sess-2's row bind the SAME chat for the same plugin+instance under different
    // provider conversations (e.g. the provider opened a fresh conversation after the re-pair).
    await service.upsert(key, 'conv-1');
    await service.upsert(
      { sessionId: 'sess-2', chatId: 'chat-1', pluginId: 'chatwoot', instanceId: 'acct1' },
      'conv-2',
    );
    const stale = await service.get(key);
    if (!stale) throw new Error('expected a stale mapping row');

    await service.rebindSession(stale.id, 'sess-2');

    // The forward-key collision is resolved in favor of sess-2's own (fresher) row; the stale one is gone.
    expect(await service.getByProvider('chatwoot', 'acct1', 'conv-1')).toBeNull();
    expect((await service.getByProvider('chatwoot', 'acct1', 'conv-2'))?.sessionId).toBe('sess-2');
  });
});