Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

62.2 KB
Raw Blame
import { Test, TestingModule } from '@nestjs/testing';
import { getRepositoryToken } from '@nestjs/typeorm';
import { FindOperator, In, Repository } from 'typeorm';
import { BadRequestException, NotFoundException } from '@nestjs/common';
import { MessageService, spendInlineMediaBudget } from './message.service';
import { MessageSendService } from './message-send.service';
import { Message } from './entities/message.entity';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { MessageProjector } from '../session/message-projector.service';
import type { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';
import { HookManager } from '../../core/hooks';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { LidMapping } from '../../engine/identity/lid-mapping.entity';
import { SendPacingService } from './send-pacing.service';

/** 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);

/** Pacing is off by default in these tests; the governor's own spec covers its behaviour. */
const inertPacing = (): SendPacingService =>
  ({
    assertSendAllowed: jest.fn().mockResolvedValue(undefined),
    recordSendFailure: jest.fn(),
    recordSendSuccess: jest.fn(),
  }) as unknown as SendPacingService;

/**
 * Completes a query-builder fake with the list read getMessages performs: a count, the page as
 * id/length pairs, then the rows themselves by id. `rows` answers with what the fake's filters match.
 */
function withListRead<T extends object>(qb: T, repository: Partial<Repository<Message>>, rows: () => Message[]): T {
  Object.assign(qb, {
    select: jest.fn().mockReturnValue(qb),
    addSelect: jest.fn().mockReturnValue(qb),
    clone: jest.fn().mockReturnValue(qb),
    getMany: jest.fn().mockImplementation(() => Promise.resolve(rows())),
    getCount: jest.fn().mockImplementation(() => Promise.resolve(rows().length)),
    getRawMany: jest
      .fn()
      .mockImplementation(() =>
        Promise.resolve(rows().map(r => ({ id: r.id, metadataLength: JSON.stringify(r.metadata ?? null).length }))),
      ),
  });
  repository.find = jest
    .fn()
    .mockImplementation(({ where }: { where: { id: FindOperator<string> } }) =>
      Promise.resolve(rows().filter(r => inList(r.id, where.id))),
    );
  return qb;
}

function createMockEngine() {
  return {
    reactToMessage: jest.fn().mockResolvedValue(undefined),
    getMessageReactions: jest.fn().mockResolvedValue([]),
    deleteMessage: jest.fn().mockResolvedValue(undefined),
    pinMessage: jest.fn().mockResolvedValue(undefined),
    starMessage: jest.fn().mockResolvedValue(undefined),
    votePoll: jest.fn().mockResolvedValue(undefined),
    unpinMessage: jest.fn().mockResolvedValue(undefined),
    editMessage: jest.fn().mockResolvedValue({ id: 'wa-msg-1', timestamp: 1706868000 }),
    getChatHistory: jest.fn().mockResolvedValue([]),
  };
}

describe('MessageService', () => {
  let service: MessageService;
  let repository: jest.Mocked<Partial<Repository<Message>>>;
  let engines: EngineRegistry;
  let messageProjector: { recordOutboundMessageEdit: jest.Mock; recordRevoke: jest.Mock };
  let hookManager: jest.Mocked<Partial<HookManager>>;
  let lidMappingStore: { findLidsForPhone: jest.Mock; findPhoneForLid: jest.Mock };
  let mockEngine: ReturnType<typeof createMockEngine>;
  let pacing: { assertSendAllowed: jest.Mock };

  beforeEach(async () => {
    repository = {
      create: jest.fn().mockImplementation((data: Partial<Message>) => ({ id: 'msg-uuid-1', ...data }) as Message),
      save: jest.fn().mockImplementation(msg => Promise.resolve(msg)),
      findOne: jest.fn().mockResolvedValue(null),
      update: jest.fn().mockResolvedValue({ affected: 1 }),
      delete: jest.fn().mockResolvedValue({ affected: 1 }),
      createQueryBuilder: jest.fn(),
    };

    mockEngine = createMockEngine();

    messageProjector = {
      recordOutboundMessageEdit: jest.fn().mockResolvedValue(undefined),
      recordRevoke: jest.fn().mockResolvedValue(undefined),
    };

    engines = new EngineRegistry();
    engines.set('sess-1', mockEngine as unknown as IWhatsAppEngine);

    hookManager = {
      // Echo the input straight back so the message:sending gate is a pass-through by default; the
      // edit tests override with continue:false (block) or a modified input.
      execute: jest
        .fn()
        .mockImplementation((_event: string, data: unknown) => Promise.resolve({ continue: true, data })),
    };

    lidMappingStore = {
      findLidsForPhone: jest.fn().mockResolvedValue([]),
      findPhoneForLid: jest.fn().mockResolvedValue(null),
    };

    const module: TestingModule = await Test.createTestingModule({
      providers: [
        MessageService,
        // The send family lives on MessageSendService; nothing here exercises it, so a bare stub
        // stands in for the delegation target.
        { provide: MessageSendService, useValue: {} },
        {
          provide: SendPacingService,
          useValue: {
            assertSendAllowed: jest.fn().mockResolvedValue(undefined),
            recordSendFailure: jest.fn(),
            recordSendSuccess: jest.fn(),
          },
        },
        { provide: getRepositoryToken(Message, 'data'), useValue: repository },
        { provide: EngineRegistry, useValue: engines },
        { provide: MessageProjector, useValue: messageProjector },
        { provide: HookManager, useValue: hookManager },
        { provide: LidMappingStoreService, useValue: lidMappingStore },
      ],
    }).compile();

    service = module.get<MessageService>(MessageService);
    pacing = module.get(SendPacingService);
  });

  // ── outbound send delegation ──────────────────────────────────────

  describe('outbound send delegation', () => {
    it('passes a send request straight through to MessageSendService and returns its answer', async () => {
      const sendText = jest.fn().mockResolvedValue({ messageId: 'wa-msg-1', timestamp: 1706868000 });
      const facade = new MessageService(
        repository as Repository<Message>,
        engines,
        messageProjector as unknown as MessageProjector,
        hookManager as HookManager,
        lidMappingStore as unknown as LidMappingStoreService,
        inertPacing(),
        { sendText } as unknown as MessageSendService,
      );

      const result = await facade.sendText('sess-1', { chatId: '[email protected]', text: 'hi' });

      expect(sendText).toHaveBeenCalledWith('sess-1', { chatId: '[email protected]', text: 'hi' });
      expect(result).toEqual({ messageId: 'wa-msg-1', timestamp: 1706868000 });
    });

    it('passes a reply straight through with its tag list intact', async () => {
      // This forwarder is the entry point the controller and the agent tool both call. Its parameter
      // was an inline three-field literal while the controller already handed it a fourth, so the
      // body reached the sender only because structural typing does not strip excess properties.
      const reply = jest.fn().mockResolvedValue({ messageId: 'wa-msg-2', timestamp: 1706868001 });
      const facade = new MessageService(
        repository as Repository<Message>,
        engines,
        messageProjector as unknown as MessageProjector,
        hookManager as HookManager,
        lidMappingStore as unknown as LidMappingStoreService,
        inertPacing(),
        { reply } as unknown as MessageSendService,
      );

      const body = { chatId: '[email protected]', quotedMessageId: 'Q1', text: 'hi @62811', mentions: ['[email protected]'] };
      await facade.reply('sess-1', body);

      expect(reply).toHaveBeenCalledWith('sess-1', body);
    });
  });

  // ── getMessages pagination guard ──────────────────────────────────

  describe('getMessages pagination guard', () => {
    interface QbMock {
      where: jest.Mock;
      orderBy: jest.Mock;
      addOrderBy: jest.Mock;
      skip: jest.Mock;
      take: jest.Mock;
      andWhere: jest.Mock;
    }
    const makeQb = (): QbMock => {
      const qb: QbMock = {
        where: jest.fn(),
        orderBy: jest.fn(),
        addOrderBy: jest.fn(),
        skip: jest.fn(),
        take: jest.fn(),
        andWhere: jest.fn(),
      };
      qb.where.mockReturnValue(qb);
      qb.orderBy.mockReturnValue(qb);
      qb.addOrderBy.mockReturnValue(qb);
      qb.skip.mockReturnValue(qb);
      qb.take.mockReturnValue(qb);
      qb.andWhere.mockReturnValue(qb);
      return withListRead(qb, repository, () => []);
    };

    it('falls back to defaults on NaN limit/offset (never take(NaN))', async () => {
      const qb = makeQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      await service.getMessages('sess-1', { limit: NaN, offset: NaN });
      expect(qb.take).toHaveBeenCalledWith(50);
      expect(qb.skip).toHaveBeenCalledWith(0);
    });

    it('clamps an oversized limit to 100 and a negative offset to 0', async () => {
      const qb = makeQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      await service.getMessages('sess-1', { limit: 999, offset: -5 });
      expect(qb.take).toHaveBeenCalledWith(100);
      expect(qb.skip).toHaveBeenCalledWith(0);
    });

    it('caps an offset past the largest safe integer, which a driver would refuse as an OFFSET', async () => {
      const qb = makeQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      await service.getMessages('sess-1', { offset: 2 ** 63 });
      expect(qb.skip).toHaveBeenCalledWith(Number.MAX_SAFE_INTEGER);
    });
  });

  // ── getMessages keyset cursor ─────────────────────────────────────

  describe('getMessages anchors on `after` instead of a count', () => {
    /** The cursor path counts the whole filter match (7 here), then reads the page after the anchor. */
    const makeCursorQb = (rows: Message[]) => {
      const qb = withListRead(
        {
          where: jest.fn().mockReturnThis(),
          orderBy: jest.fn().mockReturnThis(),
          addOrderBy: jest.fn().mockReturnThis(),
          skip: jest.fn().mockReturnThis(),
          take: jest.fn().mockReturnThis(),
          andWhere: jest.fn().mockReturnThis(),
        },
        repository,
        () => rows,
      ) as unknown as Record<string, jest.Mock>;
      qb.getCount.mockResolvedValue(7);
      return qb;
    };

    it('narrows on the anchor row and leaves skip() unused, so a concurrent write cannot shift the window', async () => {
      const qb = makeCursorQb([{ id: 'm-2' } as Message]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      const result = await service.getMessages('sess-1', { after: 'm-1', offset: 500 });

      expect(qb.skip.mock.calls.every(([value]) => value === undefined)).toBe(true);
      const [clause, params] = qb.andWhere.mock.calls[0] as [string, Record<string, unknown>];
      // rowid, not id: the stub repository carries no manager, which reads as "not postgres".
      expect(clause).toContain('(message.createdAt, message.rowid) <');
      // The anchor's sort key is resolved in SQL; only the id crosses the JS boundary.
      expect(clause).toContain('FROM messages anchor');
      expect(params).toEqual({ after: 'm-1', sessionId: 'sess-1' });
      // `total` counts the filter match, not the post-cursor remainder, so it stays stable per page.
      expect(result.total).toBe(7);
    });

    /**
     * The dialect split, pinned on the default test job rather than only in the postgres-gated
     * suite: a typo in the accessor would otherwise ship a `rowid` term to PostgreSQL, where the
     * column does not exist and every message list would 500.
     */
    it('keeps id as the tiebreak on postgres, where there is no rowid', async () => {
      const qb = makeCursorQb([{ id: 'm-2' } as Message]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      (repository as unknown as { manager: unknown }).manager = {
        connection: { options: { type: 'postgres' } },
      };

      await service.getMessages('sess-1', { after: 'm-1' });

      const [clause] = qb.andWhere.mock.calls[0] as [string];
      expect(clause).toContain('(message.createdAt, message.id) <');
      expect(clause).toContain('anchor."id"');
      expect(clause).not.toContain('rowid');
      expect(qb.addOrderBy).toHaveBeenCalledWith('message.id', 'DESC');

      delete (repository as unknown as { manager?: unknown }).manager;
    });

    /**
     * The unary `+` sort key is SQLite-only. PostgreSQL has no unary `+` for timestamps, and TypeORM
     * leaves the bare `message.createdAt` after it unquoted, so a chat page there would 500.
     */
    it('keeps the plain createdAt key for a multi-candidate chat on postgres', async () => {
      const qb = makeCursorQb([{ id: 'm-2' } as Message]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      (repository as unknown as { manager: unknown }).manager = {
        connection: { options: { type: 'postgres' } },
      };

      await service.getMessages('sess-1', { chatId: '[email protected]' });

      expect(qb.orderBy).toHaveBeenCalledWith('message.createdAt', 'DESC');
      expect(qb.orderBy).not.toHaveBeenCalledWith('+message.createdAt', 'DESC');

      delete (repository as unknown as { manager?: unknown }).manager;
    });

    it('takes createdAt out of index order for a multi-candidate chat on sqlite only', async () => {
      const qb = makeCursorQb([{ id: 'm-2' } as Message]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      await service.getMessages('sess-1', { chatId: '[email protected]' });
      expect(qb.orderBy).toHaveBeenLastCalledWith('+message.createdAt', 'DESC');

      await service.getMessages('sess-1', { chatId: '[email protected]' });
      expect(qb.orderBy).toHaveBeenLastCalledWith('message.createdAt', 'DESC');
    });

    it('orders by rowid on sqlite, which is the arrival order and needs no sort', async () => {
      const qb = makeCursorQb([{ id: 'm-2' } as Message]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      await service.getMessages('sess-1', { after: 'm-1' });

      // The order term is applied before the cursor branch, so the cursor harness pins it too.
      expect(qb.addOrderBy).toHaveBeenCalledWith('message.rowid', 'DESC');
    });

    it('rejects a cursor that names no row in this session rather than reading as end-of-history', async () => {
      const qb = makeCursorQb([]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      repository.exists = jest.fn().mockResolvedValue(false);

      await expect(service.getMessages('sess-1', { after: 'nope' })).rejects.toThrow(BadRequestException);
      expect(repository.exists).toHaveBeenCalledWith({ where: { id: 'nope', sessionId: 'sess-1' } });
    });

    it('returns an empty page, not an error, when a valid cursor reaches the end of the history', async () => {
      const qb = makeCursorQb([]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      repository.exists = jest.fn().mockResolvedValue(true);

      await expect(service.getMessages('sess-1', { after: 'm-last' })).resolves.toEqual({ messages: [], total: 7 });
    });
  });

  // ── getMessages from-filter (lid resolution becomes a hit) ─────────
  describe('getMessages from-filter resolves a lid to a phone', () => {
    // A group message whose stored author is an unresolved lid, plus a plain DM from the same person.
    const lidRow = { id: 'm-lid', from: '111@lid', chatId: '[email protected]' } as Message;
    const dmRow = { id: 'm-dm', from: '[email protected]', chatId: '[email protected]' } as Message;
    const rows = [lidRow, dmRow];

    // A query-builder fake that actually filters by the `(from IN (:...froms) OR author IN (:...authorFroms))`
    // clause it receives, so the test exercises the resolution-driven expansion end to end (filter -> rows).
    const makeFilteringQb = () => {
      let froms: string[] | null = null;
      let authorFroms: string[] | null = null;
      const qb = {
        where: jest.fn().mockReturnThis(),
        orderBy: jest.fn().mockReturnThis(),
        addOrderBy: jest.fn().mockReturnThis(),
        skip: jest.fn().mockReturnThis(),
        take: jest.fn().mockReturnThis(),
        andWhere: jest
          .fn()
          .mockImplementation((_clause: string, params?: { froms?: string[]; authorFroms?: string[] }) => {
            if (params?.froms) froms = params.froms;
            if (params?.authorFroms) authorFroms = params.authorFroms;
            return qb;
          }),
      };
      return withListRead(qb, repository, () =>
        froms || authorFroms
          ? rows.filter(
              r => froms?.includes(r.from) || (r.author != null && (authorFroms?.includes(r.author) ?? false)),
            )
          : rows,
      );
    };

    it('returns the lid-authored message once the table maps the lid to that phone (the hit)', async () => {
      lidMappingStore.findLidsForPhone.mockResolvedValue(['111']); // table: lid 111 -> phone 628999
      const qb = makeFilteringQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      const { messages } = await service.getMessages('sess-1', { from: '628999' });

      expect(lidMappingStore.findLidsForPhone).toHaveBeenCalledWith('628999');
      expect(messages.map(m => m.id).sort()).toEqual(['m-dm', 'm-lid']);
    });

    it.each([true, false])(
      'uses table origin for a phone filter with an empty cache (reported=%s)',
      async isReported => {
        // The mapping is only in the table: past the preload cap or evicted by the LRU.
        const table = [{ lid: '111', phone: '628999', isReported }];
        const store = 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))),
        } as unknown as Repository<LidMapping>);
        const qb = makeFilteringQb();
        (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
        const withStore = new MessageService(
          repository as Repository<Message>,
          engines,
          messageProjector as unknown as MessageProjector,
          hookManager as HookManager,
          store,
          inertPacing(),
          {} as MessageSendService,
        );

        const { messages } = await withStore.getMessages('sess-1', { from: '628999' });

        expect(store.lidsForPhone('628999')).toEqual([]);
        expect(messages.map(m => m.id).sort()).toEqual(isReported ? ['m-dm', 'm-lid'] : ['m-dm']);
      },
    );

    it.each([true, false])('uses table origin for a LID filter with an empty cache (reported=%s)', async isReported => {
      const table = [{ lid: '111', phone: '628999', isReported }];
      const store = new LidMappingStoreService({
        findOne: ({ where }: { where: { lid: string } }) =>
          Promise.resolve(table.find(r => r.lid === where.lid) ?? null),
      } as unknown as Repository<LidMapping>);
      const qb = makeFilteringQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      const withStore = new MessageService(
        repository as Repository<Message>,
        engines,
        messageProjector as unknown as MessageProjector,
        hookManager as HookManager,
        store,
        inertPacing(),
        {} as MessageSendService,
      );

      const { messages } = await withStore.getMessages('sess-1', { from: '111@lid' });

      expect(messages.map(m => m.id).sort()).toEqual(isReported ? ['m-dm', 'm-lid'] : ['m-lid']);
    });

    it('misses the lid-authored message when the table has no mapping (the prior silent miss)', async () => {
      lidMappingStore.findLidsForPhone.mockResolvedValue([]); // unresolved: no lid -> phone row yet
      const qb = makeFilteringQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      const { messages } = await service.getMessages('sess-1', { from: '628999' });

      expect(messages.map(m => m.id)).toEqual(['m-dm']); // only the @c.us DM matches
    });

    // `<n>@hosted` is the Meta-hosted dialect of the SAME phone account, which is why Baileys
    // rewrites it to `<n>@s.whatsapp.net` on every inbound message. Rows therefore land under the
    // plain dialect while a chat id we published may carry the hosted suffix, so a filter given the
    // hosted form has to expand to the phone dialects or it returns none of the person's history.
    it('expands a hosted id into the phone dialects, so it finds rows stored under @c.us', async () => {
      const qb = makeFilteringQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      const { messages } = await service.getMessages('sess-1', { from: '628999@hosted' });

      expect(messages.map(m => m.id)).toEqual(['m-dm']);
      expect(lidMappingStore.findLidsForPhone).toHaveBeenCalledWith('628999');
      const calls = qb.andWhere.mock.calls as Array<[string, { froms?: string[] }?]>;
      const froms = calls.find(c => c[1]?.froms)?.[1]?.froms;
      expect(froms).toEqual(expect.arrayContaining(['628999@hosted', '[email protected]', '[email protected]']));
    });
  });

  // ── getMessages from-filter matches the group author ──────────────
  describe('getMessages from-filter matches the group author', () => {
    // Group rows: `from` holds the group JID; the real sender lives in `author`.
    const aliceGroupRow = { id: 'm-grp-alice', from: '[email protected]', author: '[email protected]', chatId: '[email protected]' } as Message;
    const bobGroupRow = { id: 'm-grp-bob', from: '[email protected]', author: '[email protected]', chatId: '[email protected]' } as Message;
    const aliceDmRow = { id: 'm-dm', from: '[email protected]', chatId: '[email protected]' } as Message;
    // A query-builder fake applying the chatId AND (from OR author) predicates like the real SQL.
    const makeAuthorQb = (rows: Message[]) => {
      let chatIds: string[] | null = null;
      let froms: string[] | null = null;
      let authorFroms: string[] | null = null;
      const qb = {
        where: jest.fn().mockReturnThis(),
        orderBy: jest.fn().mockReturnThis(),
        addOrderBy: jest.fn().mockReturnThis(),
        skip: jest.fn().mockReturnThis(),
        take: jest.fn().mockReturnThis(),
        andWhere: jest
          .fn()
          .mockImplementation(
            (_clause: string, params?: { chatIds?: string[]; froms?: string[]; authorFroms?: string[] }) => {
              if (params?.chatIds) chatIds = params.chatIds;
              if (params?.froms) froms = params.froms;
              if (params?.authorFroms) authorFroms = params.authorFroms;
              return qb;
            },
          ),
      };
      return withListRead(qb, repository, () => {
        let matched = rows;
        if (chatIds) matched = matched.filter(r => chatIds!.includes(r.chatId));
        if (froms || authorFroms) {
          matched = matched.filter(
            r => froms?.includes(r.from) || (r.author != null && (authorFroms?.includes(r.author) ?? false)),
          );
        }
        return matched;
      });
    };

    it('returns group messages authored by the filtered phone (matched via author, not from)', async () => {
      lidMappingStore.findLidsForPhone.mockResolvedValue([]);
      const qb = makeAuthorQb([aliceGroupRow, bobGroupRow, aliceDmRow]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      const { messages } = await service.getMessages('sess-1', { from: '628999' });

      // Alice's group row + her DM; Bob's group row (same `from` = group JID) stays out.
      expect(messages.map(m => m.id).sort()).toEqual(['m-dm', 'm-grp-alice']);
    });

    it('matches a group author stored as a lid once the table maps the lid to the phone', async () => {
      const lidAuthorRow = { id: 'm-grp-lid', from: '[email protected]', author: '111@lid', chatId: '[email protected]' } as Message;
      lidMappingStore.findLidsForPhone.mockResolvedValue(['111']); // table: lid 111 -> phone 628999
      const qb = makeAuthorQb([aliceGroupRow, bobGroupRow, aliceDmRow, lidAuthorRow]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      const { messages } = await service.getMessages('sess-1', { from: '628999' });

      expect(messages.map(m => m.id).sort()).toEqual(['m-dm', 'm-grp-alice', 'm-grp-lid']);
    });

    it('still applies the chatId filter alongside the from/author match', async () => {
      lidMappingStore.findLidsForPhone.mockResolvedValue([]);
      const qb = makeAuthorQb([aliceGroupRow, bobGroupRow, aliceDmRow]);
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      const { messages } = await service.getMessages('sess-1', { chatId: '[email protected]', from: '628999' });

      // Alice's DM is excluded by the chatId filter, Bob's row by the from/author filter.
      expect(messages.map(m => m.id)).toEqual(['m-grp-alice']);
    });
  });

  // ── candidate expansion is scoped by chat kind ────────────────────
  describe('getMessages candidate expansion is scoped by chat kind', () => {
    // Captures the candidate arrays the service binds, so the scoping is asserted directly.
    const makeCaptureQb = () => {
      const captured: { chatIds?: string[]; froms?: string[]; authorFroms?: string[] } = {};
      const qb = {
        where: jest.fn().mockReturnThis(),
        orderBy: jest.fn().mockReturnThis(),
        addOrderBy: jest.fn().mockReturnThis(),
        skip: jest.fn().mockReturnThis(),
        take: jest.fn().mockReturnThis(),
        andWhere: jest
          .fn()
          .mockImplementation(
            (_clause: string, params?: { chatIds?: string[]; froms?: string[]; authorFroms?: string[] }) => {
              if (params?.chatIds) captured.chatIds = params.chatIds;
              if (params?.froms) captured.froms = params.froms;
              if (params?.authorFroms) captured.authorFroms = params.authorFroms;
              return qb;
            },
          ),
      };
      return { qb: withListRead(qb, repository, () => []), captured };
    };

    it('expands a @lid chatId to the phone the table names, not a stale cached one', async () => {
      // This node cached lid 111 -> 628999; another node has since re-mapped it to 628777 in the
      // shared table. The chat fence reads the table, so history must expand to the same phone or a
      // key allowed only 111@lid would read chat 628999.
      const table = [{ lid: '111', phone: '628999', isReported: true }];
      const store = 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),
        upsert: () => Promise.resolve({}),
      } as unknown as Repository<LidMapping>);
      await store.remember('111', '628999');
      table[0].phone = '628777';
      const { qb, captured } = makeCaptureQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);
      const withStore = new MessageService(
        repository as Repository<Message>,
        engines,
        messageProjector as unknown as MessageProjector,
        hookManager as HookManager,
        store,
        inertPacing(),
        {} as MessageSendService,
      );

      await withStore.getMessages('sess-1', { chatId: '111@lid' });

      expect(captured.chatIds).toEqual(['111@lid', '[email protected]', '[email protected]']);
    });

    it('does not expand a group chatId into the user dialects (fail-closed on the literal id)', async () => {
      const { qb, captured } = makeCaptureQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      await service.getMessages('sess-1', { chatId: '[email protected]' });

      // No `[email protected]`/`@s.whatsapp.net` and no lid-table probe with the group's digits.
      expect(captured.chatIds).toEqual(['[email protected]']);
      expect(lidMappingStore.findLidsForPhone).not.toHaveBeenCalled();
      expect(lidMappingStore.findPhoneForLid).not.toHaveBeenCalled();
    });

    it('does not expand a status broadcast or newsletter chatId', async () => {
      const { qb, captured } = makeCaptureQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      await service.getMessages('sess-1', { chatId: 'status@broadcast' });
      expect(captured.chatIds).toEqual(['status@broadcast']);

      await service.getMessages('sess-1', { chatId: '12345@newsletter' });
      expect(captured.chatIds).toEqual(['12345@newsletter']);

      expect(lidMappingStore.findLidsForPhone).not.toHaveBeenCalled();
    });

    it('forward-resolves a @lid from-filter to its phone instead of minting <lid-digits>@c.us', async () => {
      lidMappingStore.findPhoneForLid.mockResolvedValue('628999'); // table: lid 111 -> phone 628999
      const { qb, captured } = makeCaptureQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      await service.getMessages('sess-1', { from: '111@lid' });

      expect(lidMappingStore.findPhoneForLid).toHaveBeenCalledWith('111');
      expect(captured.froms).toEqual(['111@lid', '[email protected]', '[email protected]']);
      expect(captured.authorFroms).toEqual(captured.froms); // same candidates drive the author match
      expect(captured.froms).not.toContain('[email protected]'); // the lid's digits are not a phone
      expect(lidMappingStore.findLidsForPhone).not.toHaveBeenCalled();
    });

    it('keeps an unresolved @lid filter to the literal id only', async () => {
      lidMappingStore.findPhoneForLid.mockResolvedValue(null); // known-unresolved
      const { qb, captured } = makeCaptureQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      await service.getMessages('sess-1', { from: '111@lid' });

      expect(captured.froms).toEqual(['111@lid']);
    });

    it('adds the folded <lid>@lid form for an upper-case or hosted lid filter', async () => {
      lidMappingStore.findPhoneForLid.mockResolvedValue(null);
      const { qb, captured } = makeCaptureQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      await service.getMessages('sess-1', { from: '111@LID' });
      expect(captured.froms).toEqual(['111@LID', '111@lid']);

      await service.getMessages('sess-1', { from: '[email protected]' });
      expect(captured.froms).toEqual(['[email protected]', '111@lid']);
      expect(lidMappingStore.findPhoneForLid).toHaveBeenCalledWith('111');
    });

    it('keeps the user-dialect expansion for a bare phone filter', async () => {
      lidMappingStore.findLidsForPhone.mockResolvedValue(['111']);
      const { qb, captured } = makeCaptureQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      await service.getMessages('sess-1', { from: '628999' });

      expect(captured.froms).toEqual(['628999', '[email protected]', '[email protected]', '111@lid']);
      expect(lidMappingStore.findLidsForPhone).toHaveBeenCalledWith('628999');
    });
  });

  // ── getMessages chatId filter is dialect-agnostic ─────────────────
  describe('getMessages chatId filter matches across dialects', () => {
    // A message stored with the raw @s.whatsapp.net chatId (e.g. an outbound send addressed by a raw id).
    const stored = { id: 'm1', from: '[email protected]', chatId: '[email protected]' } as Message;

    const makeChatQb = () => {
      let chatIds: string[] | null = null;
      const qb = {
        where: jest.fn().mockReturnThis(),
        orderBy: jest.fn().mockReturnThis(),
        addOrderBy: jest.fn().mockReturnThis(),
        skip: jest.fn().mockReturnThis(),
        take: jest.fn().mockReturnThis(),
        andWhere: jest.fn().mockImplementation((_clause: string, params?: { chatIds?: string[] }) => {
          if (params?.chatIds) chatIds = params.chatIds;
          return qb;
        }),
      };
      return withListRead(qb, repository, () => (chatIds && chatIds.includes(stored.chatId) ? [stored] : []));
    };

    it('returns a @s.whatsapp.net-stored message when filtering by the neutral @c.us chat id', async () => {
      lidMappingStore.findLidsForPhone.mockResolvedValue([]);
      const qb = makeChatQb();
      (repository.createQueryBuilder as jest.Mock).mockReturnValue(qb);

      const { messages } = await service.getMessages('sess-1', { chatId: '[email protected]' });

      expect(messages.map(m => m.id)).toEqual(['m1']);
    });
  });

  // ── reactToMessage / deleteMessage ────────────────────────────────

  describe('reactToMessage', () => {
    it('should call engine.reactToMessage', async () => {
      await service.reactToMessage('sess-1', {
        chatId: '[email protected]',
        messageId: 'wa-msg-1',
        emoji: '👍',
      });

      expect(mockEngine.reactToMessage).toHaveBeenCalledWith('[email protected]', 'wa-msg-1', '👍');
    });
  });

  describe('getChatHistory', () => {
    it('should call engine.getChatHistory with default limit and includeMedia=false', async () => {
      await service.getChatHistory('sess-1', '[email protected]');
      expect(mockEngine.getChatHistory).toHaveBeenCalledWith('[email protected]', 50, false);
    });

    it('should pass through custom limit', async () => {
      await service.getChatHistory('sess-1', '[email protected]', 10);
      expect(mockEngine.getChatHistory).toHaveBeenCalledWith('[email protected]', 10, false);
    });

    it('should pass through includeMedia flag', async () => {
      await service.getChatHistory('sess-1', '[email protected]', 5, true);
      expect(mockEngine.getChatHistory).toHaveBeenCalledWith('[email protected]', 5, true);
    });

    it('should clamp the limit to [1, 100] and default non-finite values to 50', async () => {
      await service.getChatHistory('sess-1', '[email protected]', 500);
      expect(mockEngine.getChatHistory).toHaveBeenLastCalledWith('[email protected]', 100, false);

      await service.getChatHistory('sess-1', '[email protected]', 0);
      expect(mockEngine.getChatHistory).toHaveBeenLastCalledWith('[email protected]', 1, false);

      await service.getChatHistory('sess-1', '[email protected]', Number.NaN);
      expect(mockEngine.getChatHistory).toHaveBeenLastCalledWith('[email protected]', 50, false);
    });

    it('should return engine result', async () => {
      const fake = [{ id: 'm1', body: 'hi', from: 'a', to: 'b', chatId: '[email protected]' }];
      mockEngine.getChatHistory.mockResolvedValueOnce(fake);
      const result = await service.getChatHistory('sess-1', '[email protected]');
      expect(result).toBe(fake);
    });

    it('threads an abort signal through to the engine when one is given', async () => {
      const { signal } = new AbortController();
      await service.getChatHistory('sess-1', '[email protected]', 50, true, false, signal);
      expect(mockEngine.getChatHistory).toHaveBeenCalledWith('[email protected]', 50, true, undefined, signal);
    });

    describe('deep mode (#347)', () => {
      it('allows a limit above the standard 100 cap when deep=true', async () => {
        await service.getChatHistory('sess-1', '[email protected]', 500, false, true);
        expect(mockEngine.getChatHistory).toHaveBeenLastCalledWith('[email protected]', 500, false);
      });

      it('clamps a deep limit to the 2000 ceiling', async () => {
        await service.getChatHistory('sess-1', '[email protected]', 5000, false, true);
        expect(mockEngine.getChatHistory).toHaveBeenLastCalledWith('[email protected]', 2000, false);
      });

      it('forces includeMedia off in deep mode (metadata-only)', async () => {
        await service.getChatHistory('sess-1', '[email protected]', 300, true, true);
        expect(mockEngine.getChatHistory).toHaveBeenLastCalledWith('[email protected]', 300, false);
      });

      it('still clamps to 100 when deep is not set (regression guard)', async () => {
        await service.getChatHistory('sess-1', '[email protected]', 500, false, false);
        expect(mockEngine.getChatHistory).toHaveBeenLastCalledWith('[email protected]', 100, false);
      });
    });
  });

  describe('deleteMessage', () => {
    it('should call engine.deleteMessage with forEveryone default true', async () => {
      await service.deleteMessage('sess-1', {
        chatId: '[email protected]',
        messageId: 'wa-msg-1',
      });

      expect(mockEngine.deleteMessage).toHaveBeenCalledWith('[email protected]', 'wa-msg-1', true);
    });

    it('should pass forEveryone=false when specified', async () => {
      await service.deleteMessage('sess-1', {
        chatId: '[email protected]',
        messageId: 'wa-msg-1',
        forEveryone: false,
      });

      expect(mockEngine.deleteMessage).toHaveBeenCalledWith('[email protected]', 'wa-msg-1', false);
    });

    it('clears the stored row through the same revoke as an engine revoke, after the engine delete', async () => {
      await service.deleteMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1' });

      // Naming the chat it deleted in, so the row of another chat that holds the id is left alone.
      expect(messageProjector.recordRevoke).toHaveBeenCalledWith('sess-1', 'wa-msg-1', {
        kind: 'revoke',
        chatId: '[email protected]',
      });
      expect(mockEngine.deleteMessage.mock.invocationCallOrder[0]).toBeLessThan(
        messageProjector.recordRevoke.mock.invocationCallOrder[0],
      );
      expect(repository.update).not.toHaveBeenCalled();
    });
  });

  describe('editMessage', () => {
    it('edits via the engine, delegates the stored-row update, and returns the engine result', async () => {
      const res = await service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' });

      expect(mockEngine.editMessage).toHaveBeenCalledWith('[email protected]', 'wa-msg-1', 'edited');
      // Persistence is delegated to the session's per-message mutation queue (serialized with the
      // inbound edit path) — the service no longer writes the row directly.
      expect(messageProjector.recordOutboundMessageEdit).toHaveBeenCalledWith('sess-1', 'wa-msg-1', 'edited', {
        kind: 'edit',
        chatId: '[email protected]',
        fromMe: true,
      });
      expect(repository.update).not.toHaveBeenCalled();
      expect(res).toEqual({ messageId: 'wa-msg-1', timestamp: 1706868000 });
    });

    it('still succeeds when the delegated stored-row update is a no-op (the engine edit already happened)', async () => {
      // recordOutboundMessageEdit is best-effort by contract (never rejects); a missing row or a
      // failed write is logged inside the session service, not surfaced here.
      const res = await service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' });

      expect(res).toEqual({ messageId: 'wa-msg-1', timestamp: 1706868000 });
    });

    it('propagates the engine not-found error as-is (MessageNotFoundError → 404)', async () => {
      mockEngine.editMessage.mockRejectedValueOnce(new NotFoundException('Message wa-msg-1 not found'));
      await expect(
        service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' }),
      ).rejects.toBeInstanceOf(NotFoundException);
      expect(messageProjector.recordOutboundMessageEdit).not.toHaveBeenCalled();
    });

    it('throws BadRequestException when the session is not started', async () => {
      engines.delete('sess-1');
      await expect(
        service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' }),
      ).rejects.toBeInstanceOf(BadRequestException);
      expect(mockEngine.editMessage).not.toHaveBeenCalled();
    });

    // An edit replaces the text the recipient sees, so it belongs to the same moderation
    // chokepoint as every other sender rather than going out unseen by plugins.
    it('runs the message:sending gate tagged as an edit', async () => {
      await service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' });

      expect(hookManager.execute).toHaveBeenCalledWith(
        'message:sending',
        expect.objectContaining({ type: 'edit' }),
        expect.any(Object),
      );
    });

    // An edit only UPDATEs the existing row, so it is judged against the caps but never held in the
    // admission window: holding it would charge the day's allowance for a message that is not sent.
    it('checks an edit against the pacing caps without holding it', async () => {
      await service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' });

      expect(pacing.assertSendAllowed).toHaveBeenCalledWith('sess-1', '[email protected]', { hold: false });
    });

    it('lets a plugin block an edit before the engine is called', async () => {
      (hookManager.execute as jest.Mock).mockResolvedValueOnce({ continue: false, data: {} });

      await expect(
        service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' }),
      ).rejects.toThrow('Message sending blocked by plugin');

      expect(mockEngine.editMessage).not.toHaveBeenCalled();
      expect(messageProjector.recordOutboundMessageEdit).not.toHaveBeenCalled();
    });

    it('threads a plugin-rewritten edit body through to the engine and the stored row', async () => {
      (hookManager.execute as jest.Mock).mockResolvedValueOnce({
        continue: true,
        data: { input: { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'redacted' } },
      });

      await service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'secret' });

      expect(mockEngine.editMessage).toHaveBeenCalledWith('[email protected]', 'wa-msg-1', 'redacted');
      expect(messageProjector.recordOutboundMessageEdit).toHaveBeenCalledWith(
        'sess-1',
        'wa-msg-1',
        'redacted',
        expect.objectContaining({ kind: 'edit', chatId: '[email protected]' }),
      );
    });

    it('judges the stored row by the chat the gate sent the edit to, not the one the caller named', async () => {
      (hookManager.execute as jest.Mock).mockResolvedValueOnce({
        continue: true,
        data: { input: { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' } },
      });

      await service.editMessage('sess-1', { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'edited' });

      expect(mockEngine.editMessage).toHaveBeenCalledWith('[email protected]', 'wa-msg-1', 'edited');
      expect(messageProjector.recordOutboundMessageEdit).toHaveBeenCalledWith('sess-1', 'wa-msg-1', 'edited', {
        kind: 'edit',
        chatId: '[email protected]',
        fromMe: true,
      });
    });

    it('honours a plugin that rewrites the tag list, not the list the caller sent', async () => {
      // message:sending is a moderation chokepoint, so a handler that drops a WID from the list must
      // win. Reading the caller's own dto here instead of the gated one would send the unredacted
      // tags while the hook reported success, and no other assertion in this file would notice.
      (hookManager.execute as jest.Mock).mockResolvedValueOnce({
        continue: true,
        data: { input: { chatId: '[email protected]', messageId: 'wa-msg-1', body: 'hi @62811', mentions: ['[email protected]'] } },
      });

      await service.editMessage('sess-1', {
        chatId: '[email protected]',
        messageId: 'wa-msg-1',
        body: 'hi @62811 @62999',
        mentions: ['[email protected]', '[email protected]'],
      });

      expect(mockEngine.editMessage).toHaveBeenCalledWith('[email protected]', 'wa-msg-1', 'hi @62811', ['[email protected]']);
    });
  });

  // ── pin / unpin ───────────────────────────────────────────────────

  describe('pinMessage / unpinMessage', () => {
    it('defaults the pin window to 24h when the caller does not choose one', async () => {
      await service.pinMessage('sess-1', { chatId: '[email protected]', messageId: 'M1' });
      expect(mockEngine.pinMessage).toHaveBeenCalledWith('[email protected]', 'M1', 86400);
    });

    it('passes an explicit window through untouched', async () => {
      await service.pinMessage('sess-1', { chatId: '[email protected]', messageId: 'M1', durationSeconds: 2592000 });
      expect(mockEngine.pinMessage).toHaveBeenCalledWith('[email protected]', 'M1', 2592000);
    });

    it('unpins without a duration', async () => {
      await service.unpinMessage('sess-1', { chatId: '[email protected]', messageId: 'M1' });
      expect(mockEngine.unpinMessage).toHaveBeenCalledWith('[email protected]', 'M1');
    });

    it('does not touch the stored message row — a pin is WhatsApp-owned chat state that expires', async () => {
      (repository.update as jest.Mock).mockClear();
      await service.pinMessage('sess-1', { chatId: '[email protected]', messageId: 'M1' });
      expect(repository.update).not.toHaveBeenCalled();
    });
  });

  describe('votePoll', () => {
    it('passes the option texts through unchanged', async () => {
      await service.votePoll('sess-1', { chatId: '[email protected]', pollMessageId: 'P1', options: ['A', 'B'] });
      expect(mockEngine.votePoll).toHaveBeenCalledWith('[email protected]', 'P1', ['A', 'B']);
    });

    it('forwards an empty selection, which clears the vote rather than being a no-op', async () => {
      await service.votePoll('sess-1', { chatId: '[email protected]', pollMessageId: 'P1', options: [] });
      expect(mockEngine.votePoll).toHaveBeenCalledWith('[email protected]', 'P1', []);
    });
  });

  describe('starMessage', () => {
    it.each([true, false])('passes star=%s straight through to the engine', async star => {
      await service.starMessage('sess-1', { chatId: '[email protected]', messageId: 'M1', star });
      expect(mockEngine.starMessage).toHaveBeenCalledWith('[email protected]', 'M1', star);
    });
  });

  // ── archived chat media (read path) ───────────────────────────────

  describe('getChatMedia', () => {
    const archived = (mimetype: string) => ({
      getMedia: jest.fn().mockResolvedValue({ path: 'chat-media/sess-1/abc.bin', mimetype }),
    });
    const storage = (buffer = Buffer.from('BYTES')) => ({ getFile: jest.fn().mockResolvedValue(buffer) });

    const build = (archive: unknown, store: unknown): MessageService =>
      new MessageService(
        repository as Repository<Message>,
        engines,
        messageProjector as unknown as MessageProjector,
        hookManager as HookManager,
        lidMappingStore as unknown as LidMappingStoreService,
        inertPacing(),
        {} as MessageSendService,
        archive as never,
        store as never,
      );

    it('serves an inert image type unchanged', async () => {
      const svc = build(archived('image/jpeg'), storage());
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).resolves.toEqual({
        buffer: Buffer.from('BYTES'),
        mimetype: 'image/jpeg',
      });
    });

    it.each([
      ['image/svg+xml', 'scriptable despite the image/ prefix'],
      ['text/html', 'a document a sender chose the type of'],
      ['application/pdf', 'renderable by the browser plugin'],
      ['application/javascript', 'outright active content'],
    ])('downgrades %s to octet-stream (%s)', async mimetype => {
      const svc = build(archived(mimetype), storage());
      const { mimetype: served } = await svc.getChatMedia('sess-1', '[email protected]', 'wa-1');
      expect(served).toBe('application/octet-stream');
    });

    // A sender declares the mimetype, and the value becomes the Content-Type header. Parameters are
    // dropped: a comma inside them makes a browser read a second type, and a character above U+00FF
    // makes Node refuse the header, which failed the route with a 500 on every call.
    it.each([
      ['image/png;x=1,text/html', 'image/png'],
      ['image/png;,image/svg+xml', 'image/png'],
      ['image/jpeg;\u0101', 'image/jpeg'],
      ['audio/ogg; codecs=opus', 'audio/ogg'],
      ['IMAGE/PNG', 'image/png'],
    ])('serves %p as its essence %p', async (declared, expected) => {
      const svc = build(archived(declared), storage());
      const { mimetype: served } = await svc.getChatMedia('sess-1', '[email protected]', 'wa-1');
      expect(served).toBe(expected);
    });

    it('404s when nothing is archived for the message', async () => {
      const svc = build({ getMedia: jest.fn().mockResolvedValue(null) }, storage());
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).rejects.toThrow(NotFoundException);
    });

    it.each([
      ['local ENOENT', Object.assign(new Error('missing'), { code: 'ENOENT' })],
      // S3 reports a miss with a .name and NO .code — an ENOENT-only check turned this into a 500
      // on the one backend where retention/lifecycle rules make a missing object most likely.
      ['S3 NoSuchKey', Object.assign(new Error('NoSuchKey'), { name: 'NoSuchKey' })],
      ['S3 NotFound', Object.assign(new Error('NotFound'), { name: 'NotFound' })],
      ['S3 404 metadata', Object.assign(new Error('gone'), { $metadata: { httpStatusCode: 404 } })],
    ])('404s when the row outlived its file (%s)', async (_label, err) => {
      const svc = build(archived('image/png'), { getFile: jest.fn().mockRejectedValue(err) });
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).rejects.toThrow(NotFoundException);
    });

    it('does not swallow a genuine storage fault as a 404', async () => {
      const svc = build(archived('image/png'), { getFile: jest.fn().mockRejectedValue(new Error('S3 500')) });
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).rejects.toThrow('S3 500');
    });

    // ── inline fallback (sent-message media, #1165) ──────────────────

    const inlineRow = (media: Record<string, unknown>) => ({ id: 'msg-uuid-1', metadata: { media } });
    const noArchive = () => ({ getMedia: jest.fn().mockResolvedValue(null) });

    it('serves the inline row copy when nothing is archived', async () => {
      (repository.findOne as jest.Mock).mockResolvedValue(
        inlineRow({ mimetype: 'image/jpeg', data: Buffer.from('INLINE').toString('base64') }),
      );
      const svc = build(noArchive(), storage());
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).resolves.toEqual({
        buffer: Buffer.from('INLINE'),
        mimetype: 'image/jpeg',
      });
      expect(repository.findOne).toHaveBeenCalledWith({
        where: { sessionId: 'sess-1', chatId: In(['[email protected]', '[email protected]']), waMessageId: 'wa-1' },
      });
    });

    it('looks the row up across chatId dialects — outbound rows store the literal or the neutral form by race', async () => {
      (repository.findOne as jest.Mock).mockResolvedValue(
        inlineRow({ mimetype: 'image/jpeg', data: Buffer.from('SENT').toString('base64') }),
      );
      const svc = build(noArchive(), storage());
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).resolves.toEqual({
        buffer: Buffer.from('SENT'),
        mimetype: 'image/jpeg',
      });
      expect(repository.findOne).toHaveBeenCalledWith({
        where: {
          sessionId: 'sess-1',
          chatId: In(['[email protected]', '[email protected]']),
          waMessageId: 'wa-1',
        },
      });
    });

    it('404s for a revoked row that still carries an inline copy', async () => {
      (repository.findOne as jest.Mock).mockResolvedValue({
        ...inlineRow({ mimetype: 'image/jpeg', data: Buffer.from('GONE').toString('base64') }),
        type: 'revoked',
      });
      const svc = build(noArchive(), storage());
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).rejects.toThrow(NotFoundException);
    });

    it('prefers the archived file over the inline copy when both exist', async () => {
      (repository.findOne as jest.Mock).mockResolvedValue(
        inlineRow({ mimetype: 'image/png', data: Buffer.from('INLINE').toString('base64') }),
      );
      const svc = build(archived('image/png'), storage(Buffer.from('ARCHIVE-BYTES')));
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).resolves.toEqual({
        buffer: Buffer.from('ARCHIVE-BYTES'),
        mimetype: 'image/png',
      });
    });

    it('downgrades an active inline mimetype to octet-stream, matching the archive path', async () => {
      (repository.findOne as jest.Mock).mockResolvedValue(
        inlineRow({ mimetype: 'text/html', data: Buffer.from('<img>').toString('base64') }),
      );
      const svc = build(noArchive(), storage());
      const { mimetype: served } = await svc.getChatMedia('sess-1', '[email protected]', 'wa-1');
      expect(served).toBe('application/octet-stream');
    });

    it.each([
      // A URL-based send persists the URL STRING in metadata.media.data (buildMediaInput:
      // `data: base64 || dto.url!`) — decoding it as base64 would serve garbage bytes.
      ['a URL string from a url-based send', { mimetype: 'image/png', data: 'https://example.com/cat.png' }],
      ['the omitted marker', { mimetype: 'image/png', omitted: true, sizeBytes: 99 }],
      ['a payload with no mimetype', { data: Buffer.from('X').toString('base64') }],
      ['a media object with no data', { mimetype: 'image/png' }],
    ])('404s when the inline copy is %s', async (_label, media) => {
      (repository.findOne as jest.Mock).mockResolvedValue(inlineRow(media));
      const svc = build(noArchive(), storage());
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).rejects.toThrow(NotFoundException);
    });

    it('falls back to the inline copy when the archived file was purged by retention', async () => {
      (repository.findOne as jest.Mock).mockResolvedValue(
        inlineRow({ mimetype: 'image/jpeg', data: Buffer.from('STILL-HERE').toString('base64') }),
      );
      const svc = build(archived('image/jpeg'), {
        getFile: jest.fn().mockRejectedValue(Object.assign(new Error('missing'), { code: 'ENOENT' })),
      });
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).resolves.toEqual({
        buffer: Buffer.from('STILL-HERE'),
        mimetype: 'image/jpeg',
      });
    });

    it('serves the inline copy when no storage backend is configured', async () => {
      (repository.findOne as jest.Mock).mockResolvedValue(
        inlineRow({ mimetype: 'image/jpeg', data: Buffer.from('INLINE').toString('base64') }),
      );
      const svc = build(archived('image/jpeg'), undefined);
      await expect(svc.getChatMedia('sess-1', '[email protected]', 'wa-1')).resolves.toEqual({
        buffer: Buffer.from('INLINE'),
        mimetype: 'image/jpeg',
      });
    });
  });

  // The budget is only worth anything if the read path actually applies it: the wiring is one line and
  // would vanish silently. This drives getMessages through a faked query builder and asserts the
  // response is bounded, not just that the helper exists.
  describe('MessageService.getMessages bounds its inline media', () => {
    it('applies the budget to the rows it returns', async () => {
      const prev = process.env.MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES;
      process.env.MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES = '25000';
      try {
        const rows = Array.from(
          { length: 100 },
          (_, i) =>
            ({
              id: `m${i}`,
              metadata: { media: { mimetype: 'image/jpeg', data: 'x'.repeat(10_000) } },
            }) as unknown as Message,
        );
        const builder = {
          where: jest.fn().mockReturnThis(),
          andWhere: jest.fn().mockReturnThis(),
          orderBy: jest.fn().mockReturnThis(),
          addOrderBy: jest.fn().mockReturnThis(),
          skip: jest.fn().mockReturnThis(),
          take: jest.fn().mockReturnThis(),
        };
        (repository.createQueryBuilder as unknown as jest.Mock).mockReturnValue(
          withListRead(builder, repository, () => rows),
        );

        const result = await service.getMessages('sess-1', { limit: 100 });

        const inlineBytes = result.messages
          .map(m => (m.metadata as { media?: { data?: unknown } }).media?.data)
          .filter((d): d is string => typeof d === 'string')
          .reduce((sum, d) => sum + d.length, 0);
        expect(result.messages).toHaveLength(100); // the page is intact
        expect(inlineBytes).toBeLessThanOrEqual(25_000); // its payload is not
      } finally {
        if (prev === undefined) delete process.env.MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES;
        else process.env.MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES = prev;
      }
    });

    // The budget is per response, so a walk pulls it afresh on every page. `inlineMedia: false` is
    // how a client reading many pages asks for the rows without the bytes.
    it('omits every payload when the caller opts out, including the one the allowance would let through', async () => {
      const rows = Array.from(
        { length: 3 },
        (_, i) =>
          ({
            id: `m${i}`,
            metadata: { media: { mimetype: 'image/jpeg', data: 'x'.repeat(10_000) } },
          }) as unknown as Message,
      );
      const builder = {
        where: jest.fn().mockReturnThis(),
        andWhere: jest.fn().mockReturnThis(),
        orderBy: jest.fn().mockReturnThis(),
        addOrderBy: jest.fn().mockReturnThis(),
        skip: jest.fn().mockReturnThis(),
        take: jest.fn().mockReturnThis(),
      };
      (repository.createQueryBuilder as unknown as jest.Mock).mockReturnValue(
        withListRead(builder, repository, () => rows),
      );

      const result = await service.getMessages('sess-1', { limit: 100, inlineMedia: false });

      expect(result.messages).toHaveLength(3); // the rows survive, only the payloads go
      for (const message of result.messages) {
        const media = (message.metadata as { media: Record<string, unknown> }).media;
        expect(media.data).toBeUndefined();
        expect(media).toMatchObject({ mimetype: 'image/jpeg', omitted: true, sizeBytes: 7500 });
      }
    });
  });
});

describe('spendInlineMediaBudget', () => {
  const row = (id: string, base64Len: number, extra: Record<string, unknown> = {}): Message =>
    ({
      id,
      metadata: { media: { mimetype: 'image/jpeg', filename: 'a.jpg', data: 'x'.repeat(base64Len), ...extra } },
    }) as unknown as Message;

  const mediaOf = (m: Message): Record<string, unknown> => (m.metadata as { media: Record<string, unknown> }).media;

  it('keeps payloads while the budget lasts', () => {
    const rows = [row('a', 100), row('b', 100)];
    spendInlineMediaBudget(rows, 1000);
    expect(mediaOf(rows[0]).data).toHaveLength(100);
    expect(mediaOf(rows[1]).data).toHaveLength(100);
  });

  // The rows arrive newest-first, so the budget is spent on the most recent media and older rows
  // fall back to the marker the engine itself emits when inbound media is skipped.
  it('replaces the payload with the omitted marker once the budget is spent', () => {
    const rows = [row('newest', 600), row('older', 600)];
    spendInlineMediaBudget(rows, 1000);

    expect(mediaOf(rows[0]).data).toHaveLength(600);
    expect(mediaOf(rows[1]).data).toBeUndefined();
    expect(mediaOf(rows[1]).omitted).toBe(true);
    expect(mediaOf(rows[1]).mimetype).toBe('image/jpeg'); // the descriptive fields survive
    expect(typeof mediaOf(rows[1]).sizeBytes).toBe('number');
  });

  it('bounds the total inline bytes it lets through', () => {
    const rows = Array.from({ length: 100 }, (_, i) => row(`m${i}`, 10_000));
    spendInlineMediaBudget(rows, 25_000);

    const total = rows
      .map(m => mediaOf(m).data)
      .filter((d): d is string => typeof d === 'string')
      .reduce((sum, d) => sum + d.length, 0);
    expect(total).toBeLessThanOrEqual(25_000);
  });

  it('never touches a URL pointer, which is not a payload', () => {
    const rows = [row('pointer', 0, { data: 'https://cdn.example/a.jpg' })];
    spendInlineMediaBudget(rows, 0);
    expect(mediaOf(rows[0]).data).toBe('https://cdn.example/a.jpg');
    expect(mediaOf(rows[0]).omitted).toBeUndefined();
  });

  it('reports the decoded size the caller asked about, preferring a stored sizeBytes', () => {
    const rows = [row('a', 400, { sizeBytes: 4242 })];
    spendInlineMediaBudget(rows, 0);
    expect(mediaOf(rows[0]).sizeBytes).toBe(4242);
  });

  /**
   * A payload bigger than the whole budget was omitted even as the only media on the page, so a
   * single large photo or video — well inside the 50 MiB the gateway stores inline — could never be
   * read back through this route. The dashboard's thread has no other media source and fetches with
   * staleTime: Infinity, so the user saw a permanent 📎 placeholder for an image WhatsApp shows.
   *
   * The newest payload is therefore always let through when inlining is enabled at all. The budget
   * still bounds everything after it, and a budget of 0 still means "no inline media", so an
   * operator who switched inlining off does not get one payload back.
   */
  it('lets the newest payload through even when it alone exceeds the budget', () => {
    const rows = [row('huge', 5000)];
    spendInlineMediaBudget(rows, 1000);

    expect(mediaOf(rows[0]).data).toHaveLength(5000);
    expect(mediaOf(rows[0]).omitted).toBeUndefined();
  });

  // Negative twin: the allowance is for the FIRST payload only — it must not become a blanket pass.
  it('still omits the rows after an oversized newest payload', () => {
    const rows = [row('huge', 5000), row('next', 10), row('later', 10)];
    spendInlineMediaBudget(rows, 1000);

    expect(mediaOf(rows[0]).data).toHaveLength(5000);
    expect(mediaOf(rows[1]).data).toBeUndefined();
    expect(mediaOf(rows[1]).omitted).toBe(true);
    expect(mediaOf(rows[2]).omitted).toBe(true);
  });

  // A budget of 0 is an explicit "do not inline", not a small budget — no allowance applies.
  it('grants no allowance when inlining is switched off entirely', () => {
    const rows = [row('huge', 5000)];
    spendInlineMediaBudget(rows, 0);

    expect(mediaOf(rows[0]).data).toBeUndefined();
    expect(mediaOf(rows[0]).omitted).toBe(true);
  });
  // A revoked message has no media. A row restored from an older backup, or merged onto after its
  // revoke was cleared, can still carry a payload; the list must not return it, and it must not
  // spend the newest-payload allowance the next real media is owed.
  it('drops the media of a revoked row and still inlines the media after it', () => {
    const revoked = row('revoked', 5000);
    revoked.type = 'revoked';
    const rows = [revoked, row('image', 3000)];
    spendInlineMediaBudget(rows, 1000);

    expect(rows[0].metadata.media).toBeUndefined();
    expect(mediaOf(rows[1]).data).toHaveLength(3000);
    expect(mediaOf(rows[1]).omitted).toBeUndefined();
  });
});