Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

40.3 KB
Raw Blame
import { Injectable, BadRequestException, NotFoundException, Optional } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { In, ObjectLiteral, Repository } from 'typeorm';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { MessageProjector } from '../session/message-projector.service';
import { SendTextMessageDto, SendMediaMessageDto, SendAudioMessageDto, MessageResponseDto } from './dto';
import { SendTemplateMessageDto } from './dto/send-template.dto';
import { ReplyMessageDto, ClickButtonDto } from './dto/message-actions.dto';
import { Message } from './entities/message.entity';
import { HookManager, applySendingGate } from '../../core/hooks';
import { SendPacingService } from './send-pacing.service';
import { createLogger } from '../../common/services/logger.service';
import { resolveJidCandidates as expandJidCandidates } from '../../engine/identity/jid-candidates';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { ChatMediaArchiveService } from '../chat-media/chat-media-archive.service';
import { StorageService, isMissingObjectError } from '../../common/storage/storage.service';
import { MessageSendService, SaveOutgoingMessageData } from './message-send.service';
import { SessionWriteScope } from '../../common/utils/session-write-scope';
// Type-only: the module binds this class to PLUGIN_MESSAGE_PORT with a `useExisting` alias, which
// TypeScript does not check, so `implements` is what keeps the two in step.
import type { PluginMessagePort } from '../../core/plugins/plugin-host-ports';
import { MessageWindow, messageTimeBoundarySeconds, validateMessageWindow } from './message-window';

// Re-exported for existing importers (bulk send shares the rendered-template cap with the send path).
export { DEFAULT_TEMPLATE_RENDER_MAX_CHARS } from './message-send.service';

export interface GetMessagesOptions extends MessageWindow {
  chatId?: string;
  /** Filter by sender. A phone matches stored `@c.us`/`@s.whatsapp.net` ids AND any lid resolving to it. Group messages match on `author` (the real sender) as well as `from` (which holds the group JID). */
  from?: string;
  limit?: number;
  offset?: number;
  /**
   * Keyset cursor: the `id` of the last row of the previous page. Anchors the window to a ROW
   * instead of to a count, so a write between two pages cannot shift it. Takes precedence over
   * `offset`, which is left working unchanged for callers that already use it.
   */
  after?: string;
  /**
   * Set false to omit every inline media payload, leaving each row's `{ omitted, sizeBytes }` marker
   * and the media endpoint. The budget below is per RESPONSE, so a walk pulls it afresh on every
   * page; a client reading many pages usually wants the rows, not the bytes. Defaults to true.
   */
  inlineMedia?: boolean;
}

/**
 * Aggregate budget for the inline base64 media ONE message-list response may carry, counted in the
 * encoded bytes that actually land in the JSON body. Override with
 * MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES; 0 omits every payload.
 *
 * The row count was already clamped to 1..100, but a row is not a bounded object: `metadata.media.data`
 * holds the whole base64 payload, so a hundred media rows serialise to hundreds of megabytes — past
 * V8's string ceiling the read fails outright, and the dashboard requests the maximum page size with
 * no way to ask for less. Mirrors the export path's budget rather than inventing a second policy.
 *
 * NOT a hard ceiling on the response. The newest payload is let through whatever its size (see
 * spendInlineMediaBudget), so the real bound is `max(budget, one payload)` — and one payload is
 * bounded upstream by `capInboundMedia` at MEDIA_DOWNLOAD_MAX_BYTES (50 MiB by default, ~68 MiB once
 * base64-encoded). That is well inside V8's string ceiling and is the point: the alternative is a
 * large photo no client can ever read back. Raising MEDIA_DOWNLOAD_MAX_BYTES raises this too.
 *
 * It bounds the read as well: getMessages loads a page in chunks and drops each omitted payload
 * before reading the next chunk, so payloads past the budget are never all held at once.
 */
export const DEFAULT_MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES = 8 * 1024 * 1024;

export function resolveMessageListInlineMediaBudgetBytes(): number {
  const parsed = Number.parseInt(process.env.MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES ?? '', 10);
  return Number.isInteger(parsed) && parsed >= 0 ? parsed : DEFAULT_MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES;
}

/** `metadata.media.data` holds `base64 || url`, so a pointer must never be mistaken for a payload. */
const MEDIA_URL_POINTER = /^https?:\/\//i;

/**
 * The engine's own `{ omitted: true, sizeBytes }` marker for a media object whose payload is dropped,
 * the same shape `capInboundMedia` writes when inbound media is skipped on the way in, so a trimmed
 * row is not a new shape consumers must learn. Every descriptive field except `data` survives.
 */
export function omitInlineMedia(media: { data: string; sizeBytes?: number }): Record<string, unknown> {
  const { data, ...withoutPayload } = media;
  return {
    ...withoutPayload,
    omitted: true,
    // Decoded bytes, matching what capInboundMedia reports: the caller asked how big it WAS.
    sizeBytes: media.sizeBytes ?? Buffer.byteLength(data, 'base64'),
  };
}

/**
 * Stateful form of spendInlineMediaBudget: feed it the rows of one page newest-first, one at a time,
 * so a caller can drop each omitted payload before it reads the next row.
 */
export function createInlineMediaSpender(budgetBytes: number): (message: Message) => void {
  let spent = 0;
  return message => {
    const metadata = message.metadata as Record<string, unknown> | null | undefined;
    if (!metadata || typeof metadata !== 'object') return;
    // A revoked message has no media, even on a row restored or merged after its revoke was cleared.
    if (message.type === 'revoked') {
      delete metadata.media;
      return;
    }
    const media = metadata.media as { data?: unknown; sizeBytes?: number } | null | undefined;
    if (!media || typeof media.data !== 'string' || MEDIA_URL_POINTER.test(media.data)) return;

    const encoded = Buffer.byteLength(media.data, 'utf8');
    // The newest payload is always let through when inlining is enabled at all. Without this an
    // item larger than the whole budget was omitted even as the ONLY media on the page, so a single
    // large photo or video (well inside the bytes the gateway stores inline) could never be read
    // back through this route: the dashboard thread has no other media source and caches with
    // staleTime: Infinity, leaving a permanent placeholder for media WhatsApp displays.
    // A budget of 0 means "do not inline", not "a very small budget", so it grants no allowance.
    const allowanceApplies = spent === 0 && budgetBytes > 0;
    if (spent + encoded <= budgetBytes || allowanceApplies) {
      spent += encoded;
      return;
    }
    metadata.media = omitInlineMedia({ ...media, data: media.data });
  };
}

/**
 * Spend the budget over an already-ordered (newest-first) page, replacing each payload past it with
 * the omitted marker (see omitInlineMedia). Mutates and returns the rows.
 *
 * A budget, not a blanket strip: the recent media a caller is most likely reading still arrives
 * inline, and anything dropped remains fetchable from GET /:chatId/:messageId/media.
 */
export function spendInlineMediaBudget(messages: Message[], budgetBytes: number): Message[] {
  messages.forEach(createInlineMediaSpender(budgetBytes));
  return messages;
}

/**
 * Floor for the bytes of stored metadata one message-list read loads at once. The page is read in
 * chunks of at most `max(budget, this)` metadata bytes (at least one row each), and each chunk's
 * omitted payloads are dropped before the next chunk is read, so the heap holds about one chunk plus
 * what the budget keeps instead of every payload on the page.
 */
const MESSAGE_LIST_READ_CHUNK_MIN_BYTES = 1024 * 1024;

/** Pin window applied when the caller does not choose one — WhatsApp's own default of 24h. */
export const DEFAULT_PIN_DURATION_SECONDS = 86400;

/**
 * Mimetypes an archived chat-media file may be served as. Everything else — documents, and notably
 * `image/svg+xml`, which is scriptable despite the `image/` prefix — is served as inert
 * octet-stream so the media endpoint cannot host active content on the API origin.
 */
const INERT_MEDIA_MIMETYPE =
  /^(image\/(jpeg|png|gif|webp|bmp)|video\/(mp4|webm|quicktime|3gpp)|audio\/(mpeg|mp4|ogg|aac|wav|webm))$/;

/**
 * The declared mimetype's normalized essence when it is safe to echo back, else inert octet-stream.
 * Parameters are dropped rather than echoed: the sender wrote them, a comma among them makes a
 * browser read a second type, and a character above U+00FF is refused as a header value.
 */
function inertMimetype(mimetype: string): string {
  const essence = mimetype.split(';')[0].trim().toLowerCase();
  return INERT_MEDIA_MIMETYPE.test(essence) ? essence : 'application/octet-stream';
}

@Injectable()
export class MessageService implements PluginMessagePort {
  private readonly logger = createLogger('MessageService');

  constructor(
    @InjectRepository(Message, 'data')
    private readonly messageRepository: Repository<Message>,
    private readonly engines: EngineRegistry,
    private readonly messageProjector: MessageProjector,
    private readonly hookManager: HookManager,
    private readonly lidMappingStore: LidMappingStoreService,
    // Required, not @Optional: a missing pacing service would silently mean "no pacing", which is
    // the one failure mode this feature must not have. The service itself no-ops when disabled.
    private readonly pacing: SendPacingService,
    private readonly sender: MessageSendService,
    // Optional so the existing standalone constructions keep working; absent (like a disabled
    // archive) means the media read endpoint serves only the inline row copy, never archived files.
    @Optional()
    private readonly chatMediaArchive?: ChatMediaArchiveService,
    @Optional()
    private readonly storageService?: StorageService,
  ) {}

  /**
   * Second sort key for the message list: what makes the page order TOTAL without scrambling the
   * order the messages actually arrived in.
   *
   * A tiebreaker is required, because `createdAt` is not unique. But `id` is a random v4 uuid, so
   * it orders a tie group at random: five same-second messages came back shuffled, and the
   * dashboard renders whatever the server sends. It is also in no index, so SQLite sorted the whole
   * result into a temp b-tree to apply it.
   *
   * SQLite already stores the insertion sequence as `rowid`, the implicit trailing column of every
   * index, so `(createdAt DESC, rowid DESC)` is a plain backward scan of `(sessionId, createdAt)`:
   * arrival order restored, and the temp b-tree gone with it. Measured on the pinned better-sqlite3
   * with the shipped index set.
   *
   * PostgreSQL has no equivalent. `ctid` is physical position and moves on every ack UPDATE, so it
   * cannot order anything, and a monotonic column would need a table rewrite on the hottest table
   * with no recoverable insertion order to backfill from. It keeps `id`: the walk stays correct,
   * and a same-second group keeps its uuid order there.
   */
  private get orderTiebreak(): 'rowid' | 'id' {
    return this.messageRepository.manager?.connection?.options?.type === 'postgres' ? 'id' : 'rowid';
  }

  /**
   * The columns of a predicate, taken out of index consideration on SQLite, so a read of rows by `id` is a
   * primary key lookup. Nothing runs ANALYZE there, and from about ten ids on it prefers an index on the session
   * (or the chat) and visits every row of it, on the event loop. PostgreSQL has statistics and the plain
   * predicate. The column is quoted because TypeORM only quotes a path that follows a space, `=` or `(`, and
   * `from` is a keyword.
   */
  private byPrimaryKey(predicate: string): string {
    return this.orderTiebreak === 'rowid'
      ? predicate.replace(/\bmessage\.(?!id\b)(\w+)/g, '+"message"."$1"')
      : predicate;
  }

  // ========== Outbound sends (delegated) ==========
  //
  // The send family lives on MessageSendService; these pass-throughs keep the MessageService
  // surface stable for the controller, agent tools, plugin capabilities and bulk send, which were
  // all wired here before the split.

  sendText(sessionId: string, dto: SendTextMessageDto): Promise<MessageResponseDto> {
    return this.sender.sendText(sessionId, dto);
  }

  sendTemplate(sessionId: string, dto: SendTemplateMessageDto): Promise<MessageResponseDto> {
    return this.sender.sendTemplate(sessionId, dto);
  }

  sendImage(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
    return this.sender.sendImage(sessionId, dto);
  }

  sendVideo(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
    return this.sender.sendVideo(sessionId, dto);
  }

  sendAudio(sessionId: string, dto: SendAudioMessageDto): Promise<MessageResponseDto> {
    return this.sender.sendAudio(sessionId, dto);
  }

  sendDocument(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
    return this.sender.sendDocument(sessionId, dto);
  }

  sendLocation(
    sessionId: string,
    dto: {
      chatId: string;
      latitude: number;
      longitude: number;
      description?: string;
      address?: string;
      quotedMessageId?: string;
    },
  ): Promise<MessageResponseDto> {
    return this.sender.sendLocation(sessionId, dto);
  }

  sendContact(
    sessionId: string,
    dto: { chatId: string; contactName: string; contactNumber: string; quotedMessageId?: string },
  ): Promise<MessageResponseDto> {
    return this.sender.sendContact(sessionId, dto);
  }

  sendPoll(
    sessionId: string,
    dto: { chatId: string; name: string; options: string[]; allowMultipleAnswers?: boolean; quotedMessageId?: string },
  ): Promise<MessageResponseDto> {
    return this.sender.sendPoll(sessionId, dto);
  }

  sendSticker(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
    return this.sender.sendSticker(sessionId, dto);
  }

  // Typed by the DTO rather than an inline literal, like every sibling forwarder here. The literal
  // listed three fields while the controller already handed it a fourth, so the declaration said
  // less than what flowed through, and a non-REST caller (the agent tool) could not pass it at all.
  reply(sessionId: string, dto: ReplyMessageDto): Promise<MessageResponseDto> {
    return this.sender.reply(sessionId, dto);
  }

  clickButton(sessionId: string, dto: ClickButtonDto): Promise<MessageResponseDto> {
    return this.sender.clickButton(sessionId, dto);
  }

  forward(
    sessionId: string,
    dto: { fromChatId: string; toChatId: string; messageId: string },
  ): Promise<MessageResponseDto> {
    return this.sender.forward(sessionId, dto);
  }

  /** Persist an outbound row; exposed for the bulk path, which reuses the send-persistence rules. */
  saveOutgoingMessage(
    sessionId: string,
    data: SaveOutgoingMessageData,
    lifetime?: SessionWriteScope,
  ): Promise<Message> {
    return this.sender.saveOutgoingMessage(sessionId, data, lifetime);
  }

  /**
   * Get message history for a session
   */
  async getMessages(
    sessionId: string,
    options: GetMessagesOptions = {},
  ): Promise<{ messages: Message[]; total: number; unknownTimestampTotal?: number }> {
    const { chatId, from, after, inlineMedia } = options;
    validateMessageWindow(options);
    const messageTimeOrder = options.orderBy === 'timestamp';
    // Sanitize pagination: a non-finite limit/offset — e.g. `?limit=abc` -> NaN —
    // must never reach TypeORM's take()/skip(). Clamp to sane bounds; fall back to defaults.
    const rawLimit = options.limit;
    const rawOffset = options.offset;
    const limit =
      typeof rawLimit === 'number' && Number.isFinite(rawLimit) ? Math.min(Math.max(Math.trunc(rawLimit), 1), 100) : 50;
    // Capped at the largest safe integer: a driver refuses an OFFSET of 2^63 or more, and any offset that
    // large is past the last row anyway.
    const offset =
      typeof rawOffset === 'number' && Number.isFinite(rawOffset)
        ? Math.min(Math.max(Math.trunc(rawOffset), 0), Number.MAX_SAFE_INTEGER)
        : 0;

    const tiebreak = messageTimeOrder ? 'id' : this.orderTiebreak;
    // Match across dialects: a stored chatId may be `@s.whatsapp.net` (e.g. an outbound send addressed
    // by a raw engine id) while the caller filters by the neutral `@c.us` from the chat list - same
    // chat, different dialect. Resolving both sides through the table keeps them equal.
    const chatIds = chatId ? await this.resolveJidCandidates(chatId) : undefined;
    // SQLite has no planner statistics here (nothing runs ANALYZE), so with several chatId candidates
    // it prefers the (sessionId, createdAt) index because it already yields the order, and walks the
    // whole session filtering chatId row by row. The unary `+` takes createdAt out of index-order
    // consideration, so it seeks (sessionId, chatId, createdAt) and sorts only that chat's rows, the
    // plan ANALYZE would pick. A single candidate already uses that index in order, and PostgreSQL
    // (no unary `+` on timestamps) has statistics, so both keep the plain key.
    const orderColumn = messageTimeOrder ? 'timestamp' : 'createdAt';
    const orderKey =
      this.orderTiebreak === 'rowid' && chatIds !== undefined && chatIds.length > 1
        ? `+message.${orderColumn}`
        : `message.${orderColumn}`;

    const query = this.messageRepository
      .createQueryBuilder('message')
      .where('message.sessionId = :sessionId', { sessionId })
      .orderBy(orderKey, 'DESC')
      // Message times and bulk ingestion times can tie. The second key keeps pages stable;
      // legacy ingestion order retains its dialect-specific tiebreaker.
      .addOrderBy(`message.${tiebreak}`, 'DESC')
      .take(limit);

    // `after` replaces the offset rather than adding to it: mixing a row anchor with a count is
    // meaningless, and silently ignoring one of the two is friendlier to an SDK that always sends
    // `offset=0` than a 400 would be.
    if (after === undefined) {
      query.skip(offset);
    }

    // The filters a page's rows are read against again once its ids are picked (readPageSpendingBudget). Not the
    // whole query: that also carries the order, the page bounds and the cursor, which the picked ids encode.
    const rowFilters: Array<[clause: string, parameters?: ObjectLiteral]> = [];
    const narrow = (clause: string, parameters?: ObjectLiteral): void => {
      query.andWhere(clause, parameters);
      rowFilters.push([clause, parameters]);
    };

    if (chatIds) {
      narrow('message.chatId IN (:...chatIds)', { chatIds });
    }
    if (options.direction !== undefined) {
      narrow('message.direction = :direction', { direction: options.direction });
    }
    if (options.type !== undefined) narrow('message.type = :messageType', { messageType: options.type });

    if (from) {
      // Resolve the filter through the lid->phone table so a phone matches not just the stored
      // `<phone>@c.us` id but also any lid that resolves to the same person - turning the prior
      // silent miss (a lid-stored author vs a phone filter) into a hit.
      // A group message stores the real sender in `author` (`from` holds the group JID), so match
      // BOTH columns against the same candidate set or the filter skips every group message the
      // person wrote. Query plan: neither `from` nor `author` is indexed - the predicate applies
      // within the (sessionId, createdAt)-narrowed scan exactly as the from-only filter did, so the
      // OR costs nothing the old plan didn't already pay. No new index: per-session narrowing
      // dominates selectivity and a single btree cannot serve an OR across two columns anyway.
      const froms = await this.resolveJidCandidates(from);
      narrow('(message.from IN (:...froms) OR message.author IN (:...authorFroms))', {
        froms,
        authorFroms: froms,
      });
    }

    if (options.messageId !== undefined) {
      narrow('message.waMessageId = :messageId', { messageId: options.messageId });
    }
    const hasTimeSelection = messageTimeOrder || options.since !== undefined || options.until !== undefined;
    // Unknown times cannot belong to a verified time window. Count the gap within the same
    // non-time filters, before applying time bounds, without loading message bodies.
    const unknownTimestampTotal = hasTimeSelection
      ? await query.clone().andWhere('message.timestamp IS NULL').getCount()
      : undefined;
    if (messageTimeOrder) narrow('message.timestamp IS NOT NULL');
    // Integer seconds preserve both boundaries with ceil; fractional bigint parameters fail on PostgreSQL.
    if (options.since !== undefined) {
      narrow('message.timestamp >= :since', { since: messageTimeBoundarySeconds(options.since) });
    }
    if (options.until !== undefined) {
      narrow('message.timestamp < :until', { until: messageTimeBoundarySeconds(options.until) });
    }

    // A budget of 0 means "never inline" and grants no single-payload allowance, which is exactly
    // what an opted-out caller asks for, so the flag picks the budget rather than a second code path.
    const inlineMediaBudget = inlineMedia === false ? 0 : resolveMessageListInlineMediaBudgetBytes();

    // `total` keeps its documented meaning, rows matching the filters, so count before narrowing.
    const total = await query.clone().getCount();

    if (after !== undefined) {
      // A selection cursor must name a row inside this same selection, not merely a row from the
      // session. Otherwise an unrelated time/direction/type could silently truncate a valid walk. A chat or
      // sender filter is left out: its candidate set can change between pages (a lid mapping learned or lost),
      // and the cursor is only a position in time, so a row stored under an alias must still anchor the walk.
      if (
        (messageTimeOrder ||
          options.since !== undefined ||
          options.until !== undefined ||
          options.direction !== undefined ||
          options.type !== undefined ||
          options.messageId !== undefined) &&
        !(await query.clone().andWhere('message.id = :cursorId', { cursorId: after }).getCount())
      ) {
        throw new BadRequestException('Unknown cursor for this message selection');
      }
      // The anchor's sort key is resolved INSIDE the statement. Carrying it in the cursor instead
      // would mean round-tripping a timestamp through JSON, and neither dialect survives that:
      // SQLite holds two text shapes for one instant (`datetime('now')` writes 19 chars, a stamped
      // JS Date writes 23) and compares them as text, while node-postgres truncates the column's
      // microseconds to a millisecond Date. Both mis-seek silently, which is the very failure this
      // cursor exists to remove.
      query.andWhere(
        `(message.${orderColumn}, message.${tiebreak}) < ` +
          `(SELECT anchor."${orderColumn}", anchor."${tiebreak}" FROM messages anchor ` +
          'WHERE anchor."id" = :after AND anchor."sessionId" = :sessionId)',
        { after, sessionId },
      );
    }

    // The page is picked by id only. Each row's metadata can hold a whole base64 payload, so the
    // rows themselves are read in bounded chunks below, sized from a second, id-keyed statement.
    // The size stays out of the ordered one: a sort evaluates its result columns for every matching
    // row, so a size there would be computed across the whole chat, not just this page.
    const pageIds = (await query.select('message.id', 'id').getRawMany<{ id: string }>()).map(r => r.id);
    const page = await this.readMetadataSizes(sessionId, pageIds);

    // An anchor that does not exist (or belongs to another session) makes the row comparison NULL,
    // which returns zero rows and reads exactly like the end of the history. Only pay for the
    // lookup on an empty page, and turn that silent truncation into a loud 400.
    if (
      after !== undefined &&
      page.length === 0 &&
      !(await this.messageRepository.exists({ where: { id: after, sessionId } }))
    ) {
      throw new BadRequestException(`Unknown cursor '${after}' for this session`);
    }

    // The 1..100 clamp above bounds the ROW COUNT, not the response: each row carries its inline
    // base64 in metadata.media.data. Spent newest-first in the selected order, so the
    // most recently viewed media still arrives inline and the rest keeps its omitted marker.
    return {
      messages: await this.readPageSpendingBudget(sessionId, rowFilters, page, inlineMediaBudget),
      total,
      ...(unknownTimestampTotal !== undefined ? { unknownTimestampTotal } : {}),
    };
  }

  /**
   * The stored metadata size of each page row, in page order. OCTET_LENGTH, not LENGTH: both
   * SQLite and PostgreSQL answer it from the stored header, while a character count has to read
   * (and on PostgreSQL detoast) every payload in full, which the chunked read then does again.
   */
  private async readMetadataSizes(
    sessionId: string,
    pageIds: string[],
  ): Promise<Array<{ id: string; metadataLength: number | string | null }>> {
    if (pageIds.length === 0) return [];
    const sizes = await this.messageRepository
      .createQueryBuilder('message')
      .select('message.id', 'id')
      .addSelect('OCTET_LENGTH(message.metadata)', 'metadataLength')
      .where('message.id IN (:...pageIds)', { pageIds })
      .andWhere(`${this.byPrimaryKey('message.sessionId')} = :sessionId`, { sessionId })
      .getRawMany<{ id: string; metadataLength: number | string | null }>();
    const sizeById = new Map(sizes.map(r => [r.id, r.metadataLength]));
    return pageIds.map(id => ({ id, metadataLength: sizeById.get(id) ?? null }));
  }

  /**
   * Load the rows of a page in its order, in chunks of at most `max(budget, 1 MiB)` stored metadata
   * bytes (at least one row per chunk), spending the inline media budget on each chunk before the
   * next is read. Loading the whole page at once put every payload on the heap before the budget
   * dropped most of them. The rows are re-read against the filters of the selection, so a row deleted or
   * replaced since the page was picked, and no longer matching, is left out.
   */
  private async readPageSpendingBudget(
    sessionId: string,
    filters: Array<[clause: string, parameters?: ObjectLiteral]>,
    page: Array<{ id: string; metadataLength: number | string | null }>,
    budgetBytes: number,
  ): Promise<Message[]> {
    const spend = createInlineMediaSpender(budgetBytes);
    const chunkLimit = Math.max(budgetBytes, MESSAGE_LIST_READ_CHUNK_MIN_BYTES);
    const messages: Message[] = [];
    let chunk: string[] = [];
    let chunkBytes = 0;

    const flush = async (): Promise<void> => {
      const query = this.messageRepository
        .createQueryBuilder('message')
        .select('message')
        .where(`${this.byPrimaryKey('message.sessionId')} = :sessionId`, { sessionId })
        .andWhere('message.id IN (:...chunkIds)', { chunkIds: chunk });
      for (const [clause, parameters] of filters) query.andWhere(this.byPrimaryKey(clause), parameters);
      const rows = await query.getMany();
      const byId = new Map(rows.map(row => [row.id, row]));
      for (const id of chunk) {
        const row = byId.get(id);
        if (!row) continue;
        spend(row);
        messages.push(row);
      }
      chunk = [];
      chunkBytes = 0;
    };

    for (const { id, metadataLength } of page) {
      const bytes = Number(metadataLength) || 0;
      if (chunk.length > 0 && chunkBytes + bytes > chunkLimit) await flush();
      chunk.push(id);
      chunkBytes += bytes;
    }
    if (chunk.length > 0) await flush();
    return messages;
  }

  /**
   * Expand a user JID filter into every stored id that refers to the same person: the literal input
   * (so an exact lid filter still matches), the user-part in both user dialects (`@c.us` /
   * `@s.whatsapp.net`), and every lid the resolution table maps to that phone.
   *
   * Scoped by chat kind. For a non-user kind (group/status/newsletter/broadcast) the stored id can
   * only ever be the literal JID, so no candidates are generated: expanding a group or channel id's
   * digits into the user dialects (or probing the lid table with them) could mis-resolve the filter
   * onto an unrelated entity whose phone digits happen to match — fail closed on the literal id.
   * A `@lid` input forward-resolves to its phone instead of minting `<lid-digits>@c.us` (the lid's
   * digits are NOT a phone), so rows stored under the resolved form still match a raw-lid filter.
   */
  private async resolveJidCandidates(value: string): Promise<string[]> {
    // Rules live in the shared helper (engine/identity/jid-candidates) so this filter and the
    // API-key chat scope cannot disagree about which ids refer to the same entity. The raw input is
    // kept as a candidate too: a row stored under a non-folded spelling must still match it.
    const expanded = await expandJidCandidates(value, {
      resolveLid: lid => this.lidMappingStore.findPhoneForLid(lid),
      lidsForPhone: phone => this.lidMappingStore.findLidsForPhone(phone),
    });
    return [...new Set([value, ...expanded])];
  }

  // ========== Phase 3: Reactions ==========

  async reactToMessage(sessionId: string, dto: { chatId: string; messageId: string; emoji: string }): Promise<void> {
    const engine = this.getEngine(sessionId);
    await engine.reactToMessage(dto.chatId, dto.messageId, dto.emoji);
  }

  async getMessageReactions(sessionId: string, chatId: string, messageId: string) {
    const engine = this.getEngine(sessionId);
    return engine.getMessageReactions(chatId, messageId);
  }

  /**
   * Read a message's media: the archived file when one exists, else the inline copy persisted on
   * the message row. The fallback is what makes media sent BY the account retrievable here — the
   * archive covers outbound media only when CHAT_MEDIA_ARCHIVE_OUTBOUND=true, but outbound rows
   * carry the payload inline: the REST send persists it, wwjs downloads it for the own-send echo, and
   * Baileys downloads it for phone-composed fromMe messages (the Baileys API-send echo alone carries
   * only a marker, which the REST-persisted copy covers) — #1165. It also serves an inbound message
   * whose archived file was purged by retention while the inline copy lives on.
   *
   * Unlike status media (only ever an image, a video or a voice note), chat media includes documents
   * a sender chose the type of — so the declared mimetype is echoed back only when it is inert, and the caller
   * serves the result as an attachment regardless. Both matter: an allow-list alone would still let
   * `image/svg+xml` through as active content on the API origin.
   */
  async getChatMedia(
    sessionId: string,
    chatId: string,
    messageId: string,
  ): Promise<{ buffer: Buffer; mimetype: string }> {
    const chatIds = await this.resolveJidCandidates(chatId);
    const media = await this.chatMediaArchive?.getMedia(sessionId, chatIds, messageId);
    if (media && this.storageService) {
      try {
        return { buffer: await this.storageService.getFile(media.path), mimetype: inertMimetype(media.mimetype) };
      } catch (error) {
        // The row outlived its file: the retention purge (or a concurrent delete) removed it
        // between the DB read and this read. Not a server fault — try the inline copy instead.
        if (!isMissingObjectError(error)) {
          throw error;
        }
      }
    }

    // Match across dialects like getMessages does: an outbound row stores the caller's literal
    // chatId (REST persist) or the engine-neutral form (own-send echo) depending on which writer
    // won the persist race, so a literal match would 404 on half the rows this fallback exists for.
    const row = await this.messageRepository.findOne({
      where: { sessionId, chatId: In(chatIds), waMessageId: messageId },
    });
    const inline = (row?.metadata as { media?: { data?: unknown; mimetype?: unknown; omitted?: unknown } })?.media;
    if (
      // A revoked message's media is gone, even on a row cleared before revokes dropped it.
      row?.type === 'revoked' ||
      !inline ||
      inline.omitted ||
      typeof inline.data !== 'string' ||
      !inline.data ||
      typeof inline.mimetype !== 'string' ||
      !inline.mimetype ||
      // A URL-based send persists the URL STRING as `data` (buildMediaInput: `data: base64 ||
      // dto.url!`) — the bytes were fetched at send time and never stored. Decoding the URL as
      // base64 would serve garbage, so report it as absent. Same discriminator as the send path.
      /^https?:\/\//i.test(inline.data)
    ) {
      throw new NotFoundException('No media stored for this message');
    }
    return { buffer: Buffer.from(inline.data, 'base64'), mimetype: inertMimetype(inline.mimetype) };
  }

  /** Maximum messages a single getChatHistory call may request from the engine. */
  private static readonly MAX_CHAT_HISTORY_LIMIT = 100;

  /** Higher ceiling for opt-in deep history (`deep=true`). Bounded so a caller still can't ask unbounded. */
  private static readonly MAX_DEEP_CHAT_HISTORY_LIMIT = 2000;

  /**
   * Fetch chat history live from WhatsApp (bypasses local DB).
   * Returns the most recent `limit` messages for the given chat.
   * When `includeMedia` is true, downloads media (base64) for messages that have it.
   *
   * `limit` is clamped to [1, 100] (and falls back to 50 for non-finite input) so a caller cannot ask the
   * engine to fetch an unbounded number of messages. When `deep` is true the ceiling is raised to 2000
   * (for reaching weeks/months back on whatsapp-web.js, which can load earlier messages on demand) and
   * media is forced off — downloading base64 for up to 2000 messages would be an enormous, slow payload.
   *
   * An optional `signal` (HTTP client disconnect) is threaded to the engine, which checks it between
   * media downloads. Callers without cancellation keep the exact three-argument engine call shape.
   */
  async getChatHistory(
    sessionId: string,
    chatId: string,
    limit = 50,
    includeMedia = false,
    deep = false,
    signal?: AbortSignal,
  ) {
    const engine = this.getEngine(sessionId);
    const ceiling = deep ? MessageService.MAX_DEEP_CHAT_HISTORY_LIMIT : MessageService.MAX_CHAT_HISTORY_LIMIT;
    const safeLimit = Number.isFinite(limit) ? Math.min(Math.max(Math.trunc(limit), 1), ceiling) : 50;
    const media = deep ? false : includeMedia;
    return signal
      ? engine.getChatHistory(chatId, safeLimit, media, undefined, signal)
      : engine.getChatHistory(chatId, safeLimit, media);
  }

  // ========== Delete Message ==========

  /**
   * Pin a message for a bounded window. Nothing is persisted locally: a pin is chat state owned by
   * WhatsApp, not a property of our message row, and it expires on WhatsApp's clock — a mirrored
   * copy here would silently go stale.
   */
  async pinMessage(sessionId: string, dto: { chatId: string; messageId: string; durationSeconds?: number }) {
    const engine = this.getEngine(sessionId);
    await engine.pinMessage(dto.chatId, dto.messageId, dto.durationSeconds ?? DEFAULT_PIN_DURATION_SECONDS);
    return { success: true };
  }

  async unpinMessage(sessionId: string, dto: { chatId: string; messageId: string }) {
    const engine = this.getEngine(sessionId);
    await engine.unpinMessage(dto.chatId, dto.messageId);
    return { success: true };
  }

  /**
   * Star or unstar a message. Like a pin, this is WhatsApp-owned state and is not mirrored locally
   * — but unlike a pin it is private to the account and never expires.
   *
   * Best-effort on whatsapp-web.js: its star/unstar resolve void and silently do nothing when
   * WhatsApp declines the message, so a 200 here means the instruction was delivered, not that the
   * star is definitely set.
   */
  async starMessage(sessionId: string, dto: { chatId: string; messageId: string; star: boolean }) {
    const engine = this.getEngine(sessionId);
    await engine.starMessage(dto.chatId, dto.messageId, dto.star);
    return { success: true };
  }

  /**
   * Cast a vote on a poll. Not supported on the Baileys engine, which surfaces as a 501 from the
   * adapter. `options` are option texts — see the engine interface for why there are no ids.
   */
  async votePoll(sessionId: string, dto: { chatId: string; pollMessageId: string; options: string[] }) {
    const engine = this.getEngine(sessionId);
    await engine.votePoll(dto.chatId, dto.pollMessageId, dto.options);
    return { success: true };
  }

  async deleteMessage(
    sessionId: string,
    dto: { chatId: string; messageId: string; forEveryone?: boolean },
  ): Promise<void> {
    const engine = this.getEngine(sessionId);
    await engine.deleteMessage(dto.chatId, dto.messageId, dto.forEveryone ?? true);

    // Clear the stored message the same way an engine revoke does (body, media and metadata), on
    // its mutation chain. Best-effort: never rejects. No localized display string is persisted
    // here; the dashboard renders the localized "message deleted" text.
    await this.messageProjector.recordRevoke(sessionId, dto.messageId, { kind: 'revoke', chatId: dto.chatId });
  }

  // ========== Edit Message ==========

  async editMessage(
    sessionId: string,
    dto: { chatId: string; messageId: string; body: string; mentions?: string[] },
  ): Promise<MessageResponseDto> {
    const engine = this.getEngine(sessionId);
    // An edit replaces the text the recipient sees, so it is content leaving the account and goes
    // through the same moderation chokepoint as every other sender. A plugin can rewrite `body`
    // here exactly as it can for a first send.
    const finalDto = await this.applySendingGate(sessionId, 'edit', dto);
    const result = finalDto.mentions?.length
      ? await engine.editMessage(finalDto.chatId, finalDto.messageId, finalDto.body, finalDto.mentions)
      : await engine.editMessage(finalDto.chatId, finalDto.messageId, finalDto.body);

    // Best-effort: reflect the new body in the stored copy (mirrors deleteMessage's revoked flag),
    // serialized with the inbound edit/reaction writers through the session's per-message mutation
    // queue. A missing row must not fail the request — the engine edit already succeeded.
    await this.messageProjector.recordOutboundMessageEdit(sessionId, finalDto.messageId, finalDto.body, {
      kind: 'edit',
      chatId: finalDto.chatId,
      fromMe: true,
    });
    return { messageId: result.id, timestamp: result.timestamp };
  }

  /**
   * Run the pre-send `message:sending` plugin gate for one outbound message and return the
   * (possibly plugin-modified) input, or throw BadRequestException if a plugin blocked the send.
   * On this query-side class the edit path is the one sender it gates; the text, media, and
   * extended senders pass through the twin method in MessageSendService. Both funnel into the
   * same core/hooks/sending-gate implementation (shared with StatusService too), so no outbound
   * sender skips moderation.
   */
  private async applySendingGate<T extends object>(sessionId: string, type: string, input: T): Promise<T> {
    // Pacing runs BEFORE the plugin gate, so a send that policy forbids never reaches a plugin at
    // all — plugins should not be asked to moderate, or given the chance to rewrite, traffic that is
    // not going to be sent. The consequence is deliberate and documented in the hook contract: a
    // paced-out send fires no `message:sending`, so a plugin cannot observe it. Refusals are a 429
    // carrying `code: SEND_PACING_LIMITED`; a plugin veto stays a 400.
    // Every gated sender's DTO addresses its destination as `chatId` except forward, which uses
    // `toChatId` — without the fallback a forward skipped the cold-reachout gate entirely, while
    // its persisted row still drained the cold budget. Edit carries a chatId too; the edited
    // message's own row already makes that chat warm, so the cold rule is a no-op there. An edit
    // writes no row, so it is judged against the caps without being held as a new send.
    const target = input as { chatId?: string; toChatId?: string };
    await this.pacing.assertSendAllowed(sessionId, target.chatId ?? target.toChatId, { hold: false });
    return applySendingGate(this.hookManager, sessionId, type, input, 'MessageService');
  }

  private getEngine(sessionId: string) {
    return this.engines.require(
      sessionId,
      () => new BadRequestException(`Session '${sessionId}' is not active. Start the session first.`),
    );
  }
}