Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

62.0 KB
Raw Blame
import { MessageMedia, MessageTypes, type Client, type Message } from 'whatsapp-web.js';
import {
  CustomLinkPreview,
  IncomingMessage,
  LocationInput,
  ContactCard,
  DeliveryStatus,
  MediaInput,
  MessageContact,
  MessageReaction,
  MessageResult,
  PollInput,
  Quotable,
} from '../interfaces/whatsapp-engine.interface';
import { MessageWithReactions, SerializedWid, readWid } from '../types/whatsapp-web-js.types';
import { BadRequestException, NotImplementedException } from '@nestjs/common';
import { MessageNotFoundError } from '../../common/errors/message-not-found.error';
import { EngineRefusedError } from '../../common/errors/engine-refused.error';
import { loadRemoteMediaBuffer } from '../../common/media/load-remote-media';
import { chatKind, userPart } from '../identity/wa-id';
import {
  chatHistoryMediaBudgetBytes,
  coerceDeclaredSize,
  inboundMediaMaxBytes,
  ingestMediaBudgetBytes,
  isMediaDownloadEnabled,
} from './inbound-media-cap';
import { buildIncomingMessageBase, mapContactFields } from './message-mapper';
import { buildVCard } from './vcard';
import { EngineNotSupportedError } from '../../common/errors/engine-not-supported.error';
import { RecipientUnreachableError } from '../../common/errors/recipient-unreachable.error';
import { type WwebjsEngineHost, requireClient, withPage } from './wwebjs-host';
import { toCapturedPageError } from './wwebjs-lifecycle';

/**
 * Map a whatsapp-web.js MessageAck integer to the neutral DeliveryStatus.
 * wwebjs: -1 ERROR, 0 PENDING, 1 SERVER (sent), 2 DEVICE (delivered), 3 READ, 4 PLAYED.
 * PLAYED collapses to `read` (preserving prior behaviour, which treated ack>=3 as read).
 */
export function wwebjsAckToDeliveryStatus(ack: number): DeliveryStatus {
  if (ack < 0) return 'failed';
  if (ack >= 3) return 'read';
  if (ack === 2) return 'delivered';
  if (ack === 1) return 'sent';
  return 'pending';
}

/**
 * Extract call detail from a whatsapp-web.js `call_log` message, or `undefined` for any other type.
 * The public Message wrapper doesn't expose call fields, so we read them off the raw `_data`. An
 * incoming call (`!fromMe`) with no recorded `callDuration` was never answered → missed; an outgoing
 * call is never "missed". Used by getChatHistory, where `call_log` entries actually appear.
 */
export function extractWwebjsCall(msg: Message): { video: boolean; missed: boolean } | undefined {
  if ((msg.type as string) !== 'call_log') return undefined;
  const d = (msg as unknown as { _data?: { isVideoCall?: boolean; callDuration?: number } })._data ?? {};
  return { video: Boolean(d.isVideoCall), missed: !msg.fromMe && !d.callDuration };
}

/**
 * The `media` envelope for a message whose blob is not downloaded: keeps the sender-declared metadata
 * so the `media` field stays present (n8n/dashboard contract) while carrying the `omitted` marker
 * instead of base64. Used when downloads are disabled, the size pre-gate trips, the aggregate history
 * budget is spent, or the download fails/times out.
 */
export function declaredOnlyMedia(msg: Message): IncomingMessage['media'] {
  const data = (msg as unknown as { _data?: { size?: number; mimetype?: string; filename?: string } })._data;
  return {
    mimetype: data?.mimetype ?? '',
    filename: data?.filename || undefined,
    omitted: true,
    sizeBytes: coerceDeclaredSize(data?.size),
  };
}

/** The media size the sender declared; 0 when unknown, which does not pre-gate the download. */
export function declaredMediaSize(msg: Message): number {
  return coerceDeclaredSize((msg as unknown as { _data?: { size?: unknown } })._data?.size);
}

/**
 * Whether the adapter's capInboundMediaFor, with no override, downloads this message's media: its
 * pre-gates, read as the message arrives so the download can be given room first.
 */
export function plannedInboundDownload(msg: Message): boolean {
  return Boolean(msg.hasMedia) && isMediaDownloadEnabled() && declaredMediaSize(msg) <= inboundMediaMaxBytes();
}

/** A media download as {@link downloadMediaInPage} returns it: `data` is empty when the payload was over the cap. */
export interface PageMediaDownload {
  mimetype: string;
  filename?: string;
  data: string;
  /** Decrypted byte length, measured in the page. */
  sizeBytes: number;
}

/**
 * Page-side `Message#downloadMedia()` (whatsapp-web.js 1.34.7) with two changes. It passes `mimetype`
 * to `downloadAndMaybeDecrypt()`, which current WhatsApp Web builds require (upstream issue #201908),
 * and it checks the decrypted length against `maxBytes`. The size the sender declares is not the size
 * WhatsApp serves, and upstream base64-encodes and ships whatever it decrypts, so an understated
 * `fileLength` brought an arbitrarily large string over the protocol into Node. An over-cap payload
 * comes back with its size and no data. `undefined` and `null` keep upstream's meaning: no usable
 * media.
 */
export async function downloadMediaInPage(args: {
  msgId: string;
  maxBytes: number;
}): Promise<PageMediaDownload | null | undefined> {
  type PageMsg = Record<string, unknown> & {
    mimetype: string;
    filename?: string;
    mediaData?: { mediaStage: string };
    downloadMedia: (opts: object) => Promise<unknown>;
  };
  const w = window as unknown as {
    require(m: 'WAWebCollections'): {
      Msg: {
        get: (id: string) => PageMsg | undefined;
        getMessagesById: (ids: string[]) => Promise<{ messages?: PageMsg[] } | undefined>;
      };
    };
    require(m: 'WAWebDownloadManager'): {
      downloadManager: { downloadAndMaybeDecrypt: (opts: object) => Promise<ArrayBuffer> };
    };
    WWebJS: { arrayBufferToBase64Async: (buffer: ArrayBuffer) => Promise<string> };
  };
  const collection = w.require('WAWebCollections').Msg;
  const msg = collection.get(args.msgId) || (await collection.getMessagesById([args.msgId]))?.messages?.[0];
  // REUPLOADING: the media expired and the phone is re-uploading it; it cannot be downloaded now.
  if (!msg || !msg.mediaData || msg.mediaData.mediaStage === 'REUPLOADING') return null;
  if (msg.mediaData.mediaStage !== 'RESOLVED') {
    await msg.downloadMedia({ downloadEvenIfExpensive: true, rmrReason: 1 });
  }
  if (msg.mediaData.mediaStage.includes('ERROR') || msg.mediaData.mediaStage === 'FETCHING') return undefined;
  try {
    const noopQpl = {
      addAnnotations() {
        return this;
      },
      addPoint() {
        return this;
      },
    };
    const decrypted = await w.require('WAWebDownloadManager').downloadManager.downloadAndMaybeDecrypt({
      directPath: msg.directPath,
      encFilehash: msg.encFilehash,
      filehash: msg.filehash,
      mediaKey: msg.mediaKey,
      mediaKeyTimestamp: msg.mediaKeyTimestamp,
      type: msg.type,
      mimetype: msg.mimetype,
      signal: new AbortController().signal,
      downloadQpl: noopQpl,
    });
    const meta = { mimetype: msg.mimetype, filename: msg.filename, sizeBytes: decrypted.byteLength };
    if (meta.sizeBytes > args.maxBytes) return { ...meta, data: '' };
    return { ...meta, data: await w.WWebJS.arrayBufferToBase64Async(decrypted) };
  } catch (e) {
    if ((e as { status?: number } | null)?.status === 404) return undefined;
    // WhatsApp Web's rejection classes are minified, and puppeteer rebuilds a page exception from the class
    // name alone (`t: t`). Name the rejection here, with the build it came from, from whatever it carries:
    // a name and message, the class and a status, or a bare string.
    const thrown = e as
      { name?: string; message?: string; status?: number; constructor?: { name?: string } } | string | null | undefined;
    const part = (value: string | number | null | undefined): string =>
      value === undefined || value === null ? '' : String(value);
    let summary: string;
    if (thrown instanceof Object) {
      const name = part(thrown.name) || (thrown.constructor === Object ? '' : part(thrown.constructor?.name));
      const reason = part(thrown.message) || (thrown.status === undefined ? '' : `status ${part(thrown.status)}`);
      summary = name && reason ? `${name}: ${reason}` : name || reason;
    } else {
      summary = part(thrown);
    }
    const build = (window as unknown as { Debug?: { VERSION?: unknown } }).Debug?.VERSION;
    throw new Error(`${summary || 'unknown rejection'} (WhatsApp Web ${String(build)})`, {
      cause: e,
    });
  }
}

/** Download a message's media through {@link downloadMediaInPage}, on the page that delivered it. */
export async function downloadCappedMedia(
  msg: Message,
  maxBytes: number,
): Promise<PageMediaDownload | null | undefined> {
  const { pupPage } = (
    msg as unknown as {
      client: { pupPage: { evaluate: <T, A>(fn: (arg: A) => Promise<T>, arg: A) => Promise<T> } };
    }
  ).client;
  return pupPage.evaluate(downloadMediaInPage, { msgId: readWid(msg.id) ?? '', maxBytes });
}

/**
 * Whether a MediaInput's string `data` is an http(s) URL (to be fetched through the SSRF-guarded
 * loadRemoteMedia) rather than base64. Case-insensitive, matching the Baileys adapter — a mixed-case
 * scheme like `HTTPS://` must still route through the guarded fetch, not be treated as base64.
 */
export function isHttpUrl(value: string): boolean {
  return /^https?:\/\//i.test(value);
}

/**
 * Fetch remote media for sending, with an SSRF host guard, a byte cap, and a timeout.
 * The guard runs BEFORE any network call, so an internal/reserved URL throws `SsrfBlockedError`
 * and no outbound socket is opened. The byte cap (node-fetch `size`) and `AbortSignal` timeout
 * bound memory use and hang time. `unsafeMime` is left at its default (false) to preserve the
 * existing MIME-detection behavior.
 */
export async function loadRemoteMedia(url: string, sessionProxyUrl: string | undefined): Promise<MessageMedia> {
  // Fetch through the SSRF-guarded path: it validates the host, pins a direct or SOCKS connection to
  // the vetted IP (so a DNS rebind can't redirect it to an internal target between check and connect;
  // an HTTP/HTTPS session proxy resolves the name itself, so nothing is pinned there), caps bytes,
  // and refuses redirects. We then build the MessageMedia from the returned bytes — NOT via
  // MessageMedia.fromUrl, whose bundled node-fetch performs its own unpinned DNS re-resolution.
  // `sessionProxyUrl` routes the fetch through this session's egress proxy (#1626); the browser's
  // own requests already ride Chromium's --proxy-server, this one is made by the gateway itself.
  const { data, mimetype } = await loadRemoteMediaBuffer(url, sessionProxyUrl);
  // The pathname keeps its percent-encoding, and the recipient would see `Laporan%20Bulanan.pdf`. A
  // malformed escape keeps the raw name, and a decoded slash is replaced so the label stays one name.
  let filename = new URL(url).pathname.split('/').pop() || undefined;
  try {
    filename = filename && decodeURIComponent(filename).replace(/[/\\]/g, '_');
  } catch {
    // URIError: keep the raw basename.
  }
  return new MessageMedia(mimetype || 'application/octet-stream', data.toString('base64'), filename);
}

/**
 * True when a send error is WhatsApp Web's "recipient needs a LID we don't have" failure, a bare
 * Error its own bundle raises when sending to a `@c.us` for a contact WhatsApp has migrated to
 * `@lid`. Matched on WhatsApp Web's error text — there is no structured code; revisit if WhatsApp
 * Web changes it.
 */
export function isNoLidForUserError(err: unknown): boolean {
  return err instanceof Error && err.message.includes('No LID for user');
}

/**
 * True when a send error is the page's "I could not resolve the quoted id" failure, raised only
 * because {@link WwebjsMessaging.quoteOptions} opts out of `ignoreQuoteErrors` (Injected/Utils.js:
 * 197-198). Matched on the text like {@link isNoLidForUserError} — there is no structured code, and
 * puppeteer prefixes its own `Evaluation failed:`, so this is a substring test rather than equality.
 */
export function isQuoteUnresolvedError(err: unknown): boolean {
  return err instanceof Error && err.message.includes('Could not get the quoted message');
}

/**
 * Build a MessageMedia from a MediaInput (URL → fetched, base64/Buffer → wrapped).
 *
 * `trustDeclaredType: false` keeps the fetched response's content-type for a remote URL. Use it
 * wherever the mimetype is an INSTRUCTION rather than a label: whatsapp-web.js decides how to
 * convert a sticker from it, and `Util.formatImageToWebpSticker` returns the media untouched when it
 * already says webp. A caller that declares `image/webp` over bytes that are not webp would then
 * have raw bytes shipped as a sticker. The response describes bytes the caller never saw, so for
 * that one decision it is the better source. The declared filename still wins either way — that is
 * a label, and nothing branches on it.
 */
export async function toMessageMedia(
  media: MediaInput,
  sessionProxyUrl: string | undefined,
  opts?: { trustDeclaredType?: boolean; fallbackType?: string },
): Promise<MessageMedia> {
  if (typeof media.data === 'string' && isHttpUrl(media.data)) {
    const fetched = await loadRemoteMedia(media.data, sessionProxyUrl);
    // `loadRemoteMedia` derives both fields from the response (content-type, URL basename) because
    // that is all it has. The caller usually knows better, so let an explicit `mimetype`/`filename`
    // win — matching `resolveMediaBuffer` on the Baileys adapter, which already prefers the caller's.
    // `application/octet-stream` is the DTO's own placeholder, not a statement about the bytes.
    if (opts?.trustDeclaredType !== false && media.mimetype && media.mimetype !== 'application/octet-stream') {
      fetched.mimetype = media.mimetype;
    }
    // Sticker path (trustDeclaredType:false): a specific fetched image/video MIME stays authoritative,
    // but a generic/empty fetched MIME carries no information, and the caller's declared
    // image/* or video/* would otherwise be discarded — whatsapp-web.js then rejects the format
    // before running the sticker conversion. Fall back ONLY in that one shape: remote URL +
    // trustDeclaredType:false + generic fetched type + convertible declared type. Canonicalize the
    // value handed downstream (lowercased, params stripped) so a mixed-case declared type is
    // normalized exactly once. A declared image/webp IS accepted here when the fetched response
    // carries no usable MIME — the caller is asserting what the bytes actually are, so trusting it
    // only in the generic-fetched shape can't bypass the sticker conversion the way globally
    // trusting a declared WebP over a specific fetched type would. Arbitrary application/* is
    // rejected (e.g. the DTO's own octet-stream placeholder, or application/pdf).
    const normalizeMediaType = (value?: string): string => (value ?? '').split(';', 1)[0].trim().toLowerCase();
    const fetchedType = normalizeMediaType(fetched.mimetype);
    const declaredType = normalizeMediaType(media.mimetype);
    const fetchedTypeIsGeneric =
      !fetchedType || fetchedType === 'application/octet-stream' || fetchedType === 'binary/octet-stream';
    const declaredTypeIsConvertible = declaredType.startsWith('image/') || declaredType.startsWith('video/');
    if (opts?.trustDeclaredType === false && fetchedTypeIsGeneric && declaredTypeIsConvertible) {
      fetched.mimetype = declaredType;
    }
    // An image, video or audio route already says what kind of media it carries. When neither the
    // caller nor the host says more (the placeholder over an empty or generic response, the S3
    // default for an object uploaded without a type), WA Web would classify the bytes from that
    // generic type and deliver a photo as a document, so the route's default type stands in.
    const declaredTypeIsUnknown = !declaredType || declaredType === 'application/octet-stream';
    if (opts?.fallbackType && fetchedTypeIsGeneric && declaredTypeIsUnknown) {
      fetched.mimetype = opts.fallbackType;
    }
    if (media.filename) {
      fetched.filename = media.filename;
    }
    return fetched;
  }
  const data = typeof media.data === 'string' ? media.data : media.data.toString('base64');
  return new MessageMedia(media.mimetype, data, media.filename);
}

/**
 * Build the `MessageResult` for a send from whatever whatsapp-web.js hands back.
 *
 * `client.sendMessage()` can RESOLVE with `undefined` instead of throwing, and it collapses two
 * opposite outcomes into that one value (`Client.js:1558`): the chat could not be resolved so nothing
 * was sent (`if (!chat) return null`, `Client.js:1539`), or the message went out and only its id could
 * not be read back (`Msg.get` miss, `Injected/Utils.js:585`). Nothing here can tell those apart, so an
 * absent message is reported as a failed send: a false negative is visible and retryable, while
 * claiming delivery for a message that never left is not recoverable. wwebjs's own typings hide the
 * case entirely — `index.d.ts` declares `Promise<Message>`, so `strict` never flagged these reads.
 *
 * A `Message` instance is different: wwebjs only builds one from a real message model, so its presence
 * proves the send happened. An id it cannot read there means "sent, id unknown" and carries the empty
 * sentinel `forwardMessage` already returns — which `saveOutgoingMessage` stores as NULL rather than a
 * fabricated id that a later ack could mis-match.
 */
export function toMessageResult(msg: Message | undefined): MessageResult {
  if (!msg) {
    throw new Error(
      'the engine returned no message for this send, so it may not have been delivered — check the chat before retrying',
    );
  }
  const id = msg.id as unknown as SerializedWid | undefined;
  return { id: readWid(id) ?? '', timestamp: msg.timestamp };
}

/**
 * whatsapp-web.js drops some sends to a channel or a status/broadcast list before it touches the page
 * (`Client.js` sendMessage returns null): a reply, a location or a contact card to any of them, and a
 * poll or a sticker to a status or broadcast list. `toMessageResult` can only read that null as a send
 * that may have gone out, a 500 the send breaker counts, so refuse it up front with a 501. The
 * recipient tests are the library's own, so the two cannot drift. A plain 501, not
 * EngineNotSupportedError: the send methods are supported, and that class marks a whole method
 * unavailable in the capability matrix.
 */
function ensureSendable(chatId: string, shape: 'reply' | 'location' | 'contact card' | 'poll' | 'sticker'): void {
  const channel = /@\w*newsletter\b/.test(chatId);
  if (/@\w*broadcast\b/.test(chatId) || (channel && shape !== 'poll' && shape !== 'sticker')) {
    const to = channel ? 'a channel' : 'a status or broadcast list';
    throw new NotImplementedException(`whatsapp-web.js cannot send a ${shape} to ${to}; nothing was sent.`);
  }
}

/**
 * Messaging operations extracted from WhatsAppWebJsAdapter: the send paths (with the @c.us -> @lid
 * resolution cache), reactions, history, delete and edit. The adapter keeps the public methods as
 * thin forwarders and injects the shared host surface (./wwebjs-host) via closures, so the delegate
 * never touches lifecycle state directly.
 */
export class WwebjsMessaging {
  constructor(private readonly host: WwebjsEngineHost) {}

  /** Post-ensureReady client handle; see {@link requireClient} for a teardown that lands in between. */
  private client(): Client {
    return requireClient(this.host);
  }

  /** See {@link withPage} for what a dead page answers here. */
  private withPage<T>(context: string, op: () => Promise<T>): Promise<T> {
    return withPage(this.host, context, op);
  }

  /**
   * A read that runs before a reply or forward has sent anything. When the page died under it, or the
   * session went away meanwhile, nothing was sent: report the death, then answer the not-ready 409 a
   * send gets everywhere else, not the plain page error the send breaker counts. Any other failure
   * rethrows unchanged. Not for the send itself, whose failure leaves the outcome unknown.
   */
  private async readBeforeSend<T>(context: string, read: () => Promise<T>): Promise<T> {
    try {
      return await read();
    } catch (error) {
      this.host.reportIfPageTransportError(error, context);
      this.host.ensureReady();
      throw error;
    }
  }

  // Cache of resolved individual recipients: `<phone>@c.us` -> the id `sendMessage` accepts (a
  // `<lid>@lid` for a migrated contact, or the confirmed `@c.us` for a non-migrated one). `getNumberId`
  // is a rate-limited WhatsApp Web existence probe that also throws intermittently, so caching every
  // confirmed resolution keeps ordinary sends from re-probing on each message (#580). A `@lid` is
  // stable; a stale entry (a contact that migrates mid-session) self-heals via the retry in
  // `sendResolved`.
  // Unbounded Map, bounded in practice by distinct recipients per session; add an LRU only if a
  // session ever addresses a truly unbounded set of fresh numbers.
  private readonly resolvedSendIds = new Map<string, string>();
  // The `<phone>@c.us` keys of the cache above whose `@lid` the mapping store has not taken (its write failed):
  // the next send reports the pair again, so a failed write costs one more write, not a fresh probe.
  private readonly unreportedLids = new Set<string>();

  /**
   * Resolve an individual (`@c.us`) recipient to the id whatsapp-web.js will accept. WhatsApp has
   * migrated some contacts to privacy-id addressing, for which `sendMessage` throws `No LID for user`
   * on the phone WID but accepts the `@lid` that `getNumberId` returns (#573). Any server-confirmed
   * resolution (a distinct `@lid` OR a confirmed non-migrated `@c.us`) is cached, since it is stable
   * and re-probing costs a rate-limited round-trip (#580); a `null`/thrown lookup is NOT cached so an
   * unregistered or transiently-flaky contact keeps being retried. Groups/channels and already-`@lid`
   * targets are returned unchanged, and any resolution failure falls back to the original id so a send
   * is never blocked on it.
   */
  async resolveSendId(chatId: string): Promise<string> {
    if (!chatId.endsWith('@c.us')) {
      return chatId;
    }
    const cached = this.resolvedSendIds.get(chatId);
    if (cached) {
      if (this.unreportedLids.delete(chatId)) this.reportLid(chatId, cached);
      return cached;
    }
    try {
      const wid = await this.host.getNumberId(chatId);
      if (wid) {
        this.resolvedSendIds.set(chatId, wid);
        if (wid.endsWith('@lid')) this.reportLid(chatId, wid);
        return wid;
      }
      return chatId;
    } catch {
      return chatId;
    }
  }

  /**
   * Persist a learned phone -> lid so the message read-path (resolveJidCandidates) can bridge this contact's
   * `@c.us` and `@lid` rows on a pure whatsapp-web.js deployment (#583 R3). Fire-and-forget: resolution (and
   * the send) must never block/fail on the write. A write the store reports failed (it resolves false, or
   * rejects) is marked for the next send, unless a newer resolution has replaced this one meanwhile.
   */
  private reportLid(chatId: string, wid: string): void {
    const failed = (): void => {
      if (this.resolvedSendIds.get(chatId) === wid) this.unreportedLids.add(chatId);
    };
    void this.host.config.lidMappingStore
      ?.remember(userPart(wid), userPart(chatId), this.host.config.sessionId)
      ?.then(stored => {
        if (stored === false) failed();
      }, failed);
  }

  /**
   * The send options that attach a quote, or nothing at all when the caller asked for none.
   *
   * `ignoreQuoteErrors` defaults to TRUE in the library (documented at Client.js:1383, applied at
   * :1480): with it left alone an id whatsapp-web.js cannot resolve sends the message ANYWAY,
   * unquoted, and reports success. A caller who asked for a reply and received a loose message has
   * no signal that anything went wrong, so this opts out and lets the failure surface.
   *
   * A second, narrower drop is NOT covered by that flag: if the message resolves but `canReplyMsg`
   * is false, `quotedMsgOptions` stays empty and the send proceeds unquoted (Injected/Utils.js:
   * 187-195). That one is upstream behaviour we cannot switch off from here.
   */
  private quoteOptions(quotedMessageId?: string): { quotedMessageId?: string; ignoreQuoteErrors?: boolean } {
    return quotedMessageId ? { quotedMessageId, ignoreQuoteErrors: false } : {};
  }

  /**
   * Resolve `chatId` and run `send` against the resolved id. If the send fails with `No LID for user`
   * — the signature of a contact whose cached/resolved id is stale (typically a `@c.us` for a contact
   * that has since migrated to `@lid`) — drop the mapping, re-resolve once, and retry only if the
   * fresh id differs, so a genuinely unreachable recipient surfaces its error instead of looping.
   *
   * When re-resolution cannot help, the recipient is unreachable rather than stale, and the raw
   * `No LID for user` is replaced with {@link RecipientUnreachableError} (400). The bare page-side
   * Error carries no status and no recipient, so letting it through produced an opaque 500 for what
   * is really a caller-visible fact the gateway already established: `getNumberId` returned null.
   *
   * `quotedMessageId` gets the same treatment for the same reason. Opting out of `ignoreQuoteErrors`
   * makes an id the page cannot resolve throw, but it throws a bare Error, and two things follow from
   * that: the caller receives a 500 for an id THEY supplied, where the Baileys adapter answers 404
   * (`requireStored`) for the identical request; and `countsTowardSendBreaker` classifies anything
   * that is not an HttpException as an account-standing failure, so a caller retrying a stale id
   * would trip the send breaker on a fault that is purely their own. Mapping it to
   * {@link MessageNotFoundError} (404) settles both — the status matches Baileys and the published
   * `docs/06` table, and the breaker exempts it as a 4xx.
   */
  private async sendResolved<T>(
    chatId: string,
    send: (to: string) => Promise<T>,
    quotedMessageId?: string,
  ): Promise<T> {
    if (quotedMessageId) ensureSendable(chatId, 'reply');
    const to = await this.resolveSendId(chatId);
    // The lookup is an await a teardown can land in, and resolveSendId answers a failed lookup with the
    // unresolved id. The reply and forward legs send through the Message's own client, which the host's
    // readiness check on getClient never sees, so a send must not leave for a closing page from here.
    this.host.ensureReady();
    try {
      return await send(to);
    } catch (err) {
      // A transport-level failure means the page/browser is gone — report it as a death signal.
      // No-op for ordinary send errors; the retry/throw behavior below is unchanged.
      this.host.reportIfPageTransportError(err, 'sendMessage');
      // Before the LID branch: an unresolvable quote is neither stale-id nor transport, and
      // re-resolving the recipient would not make the quoted message appear.
      if (quotedMessageId && isQuoteUnresolvedError(err)) {
        throw new MessageNotFoundError(quotedMessageId);
      }
      if (!chatId.endsWith('@c.us') || !isNoLidForUserError(err)) {
        throw toCapturedPageError(err);
      }
      this.resolvedSendIds.delete(chatId);
      this.unreportedLids.delete(chatId);
      const fresh = await this.resolveSendId(chatId);
      // Same gap as above, and before the comparison: a lookup that failed because the session went away
      // answers the unresolved id, which would read as an unreachable recipient.
      this.host.ensureReady();
      if (fresh === to) {
        throw new RecipientUnreachableError(chatId);
      }
      // The first send threw, but wwjs can throw after the message is already on the wire — so this
      // retry may produce a duplicate. Log it: without this the second copy is invisible.
      this.host.logger.warn('Send retried against a re-resolved id after "No LID for user"; may duplicate', {
        chatId,
        staleId: to,
        freshId: fresh,
      });
      try {
        return await send(fresh);
      } catch (retryErr) {
        // The page can die during the retry as well; report it exactly as the first attempt does.
        this.host.reportIfPageTransportError(retryErr, 'sendMessage');
        // Same remap as the first attempt. Re-resolving the RECIPIENT says nothing about the quoted
        // message, so a send that reaches the page on the fresh id and only then fails on the quote
        // is the same caller fault — without this it would be a 500 on the retry where the identical
        // failure on the first attempt was a 404.
        if (quotedMessageId && isQuoteUnresolvedError(retryErr)) {
          throw new MessageNotFoundError(quotedMessageId);
        }
        // The re-resolved id is no better than the stale one — same unreachable recipient, and the
        // raw error would 500 exactly as the first one did.
        if (isNoLidForUserError(retryErr)) {
          throw new RecipientUnreachableError(chatId);
        }
        throw toCapturedPageError(retryErr);
      }
    }
  }

  async sendTextMessage(
    chatId: string,
    text: string,
    mentions?: string[],
    options?: { linkPreview?: boolean; customPreview?: CustomLinkPreview } & Quotable,
  ): Promise<MessageResult> {
    this.host.ensureReady();
    // wwebjs accepts neutral `<phone>@c.us` WIDs directly as mentionedJidList, so no de-normalization
    // is needed. Omit the options object entirely when none are given to keep today's send behavior.
    //
    // Only an explicit `false` is forwarded. whatsapp-web.js reads the flag as
    // `linkPreview === false ? undefined : true` (Client.js:1458), so passing `true` is identical to
    // passing nothing — sending it anyway would add an options object to every plain send for no
    // change in behaviour.
    // whatsapp-web.js takes a BOOLEAN only (index.d.ts:1547) — there is no way to hand it title,
    // description or a thumbnail. Silently dropping the caller's preview would send a message that
    // looks nothing like what they asked for, so it refuses instead.
    if (options?.customPreview) {
      throw new EngineNotSupportedError('sendTextMessage(customPreview)');
    }
    const sendOptions: {
      mentions?: string[];
      linkPreview?: boolean;
      quotedMessageId?: string;
      ignoreQuoteErrors?: boolean;
    } = this.quoteOptions(options?.quotedMessageId);
    if (mentions?.length) sendOptions.mentions = mentions;
    if (options?.linkPreview === false) sendOptions.linkPreview = false;

    const msg = await this.sendResolved(
      chatId,
      to =>
        Object.keys(sendOptions).length
          ? this.client().sendMessage(to, text, sendOptions)
          : this.client().sendMessage(to, text),
      options?.quotedMessageId,
    );
    return toMessageResult(msg);
  }

  async sendImageMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    return this.sendMediaMessage(chatId, media, undefined, 'image/jpeg');
  }

  async sendVideoMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    return this.sendMediaMessage(chatId, media, undefined, 'video/mp4');
  }

  async sendAudioMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    return this.sendMediaMessage(chatId, media, media.ptt ? { sendAudioAsVoice: true } : undefined, 'audio/mpeg');
  }

  /**
   * Without `sendMediaAsDocument` whatsapp-web.js lets WA Web classify the attachment from its declared
   * mimetype (`Injected/Utils.js` `processMediaData` -> `prepRawMedia`), so an `image/*`, `video/*` or
   * `audio/*` payload posted here reached the recipient as a photo/video/audio bubble — re-encoded and
   * stripped of its filename — instead of a document (#989). Baileys has always forced it via the
   * explicit `document:` content key, so the two engines disagreed on the same request.
   *
   * The flag is withheld for `status@broadcast` and broadcast lists: whatsapp-web.js refuses every
   * `@broadcast` recipient outright once it is set (`Client.js` returns `null`, which `toMessageResult`
   * surfaces as a failed send), so setting it there would turn a working send into an error rather than
   * improve it. Those recipients keep the classification they have today.
   */
  async sendDocumentMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    const kind = chatKind(chatId);
    const asDocument = kind !== 'status' && kind !== 'broadcast';
    return this.sendMediaMessage(chatId, media, asDocument ? { sendMediaAsDocument: true } : undefined);
  }

  private async sendMediaMessage(
    chatId: string,
    media: MediaInput,
    extraOptions?: { sendAudioAsVoice?: boolean; sendMediaAsDocument?: boolean },
    fallbackType?: string,
  ): Promise<MessageResult> {
    this.host.ensureReady();
    this.host.ensureNotChannelRecipient(chatId);

    // Build the media once (a remote URL is fetched here); sendResolved may retry the send itself.
    const messageMedia = await toMessageMedia(media, this.host.config.proxy?.url, { fallbackType });
    // A nameless document reaches WA Web as `new File([blob], undefined)` and is labelled literally
    // "undefined". Only documents render a filename, so default just this path — as Baileys does.
    if (extraOptions?.sendMediaAsDocument && !messageMedia.filename) {
      messageMedia.filename = 'file';
    }
    const msg = await this.sendResolved(
      chatId,
      to =>
        this.client().sendMessage(to, messageMedia, {
          caption: media.caption,
          ...(media.mentions?.length ? { mentions: media.mentions } : {}),
          // sendAudioAsVoice only for audio, sendMediaAsDocument only for documents;
          // {...undefined} contributes no keys.
          ...extraOptions,
          ...this.quoteOptions(media.quotedMessageId),
        }),
      media.quotedMessageId,
    );

    return toMessageResult(msg);
  }

  async sendLocationMessage(chatId: string, location: LocationInput): Promise<MessageResult> {
    this.host.ensureReady();
    ensureSendable(chatId, 'location');
    // Import Location class dynamically from whatsapp-web.js
    const module = await import('whatsapp-web.js');
    const Location = module.Location || module.default?.Location;

    const loc = new Location(location.latitude, location.longitude, {
      name: location.description || '',
      address: location.address || '',
    });
    const msg = await this.sendResolved(
      chatId,
      to => this.client().sendMessage(to, loc, this.quoteOptions(location.quotedMessageId)),
      location.quotedMessageId,
    );
    return toMessageResult(msg);
  }

  async sendContactMessage(chatId: string, contact: ContactCard): Promise<MessageResult> {
    this.host.ensureReady();
    ensureSendable(chatId, 'contact card');
    // Shared builder sanitizes name/number (strips CR/LF, digits-only waid) so a crafted contact
    // can't inject extra vCard fields — the previous inline build interpolated raw values.
    const vcard = buildVCard(contact);

    const msg = await this.sendResolved(
      chatId,
      to =>
        this.client().sendMessage(to, vcard, {
          parseVCards: true,
          ...this.quoteOptions(contact.quotedMessageId),
        }),
      contact.quotedMessageId,
    );
    return toMessageResult(msg);
  }

  async sendStickerMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    this.host.ensureReady();
    // Sticker has its own send path (sendMediaAsSticker), not the sendMediaMessage funnel, but it
    // hits the same channel crash: for a channel wwjs drops the sticker form and runs processMediaData
    // with sendToChannel, which still ends at msg.avParams() (Utils.js:518). Guard it too (#673).
    this.host.ensureNotChannelRecipient(chatId);
    ensureSendable(chatId, 'sticker');
    // Keep the fetched content-type for a remote URL: here the mimetype selects the conversion, and
    // whatsapp-web.js returns the media unconverted once it reads as webp (Util.formatImageToWebpSticker).
    const messageMedia = await toMessageMedia(media, this.host.config.proxy?.url, { trustDeclaredType: false });

    const msg = await this.sendResolved(
      chatId,
      to =>
        this.client().sendMessage(to, messageMedia, {
          sendMediaAsSticker: true,
          ...this.quoteOptions(media.quotedMessageId),
          // Same options bag every other media send uses, so the library tags a sticker exactly as it
          // tags an image. Omitted when empty to leave an untagged sticker call unchanged.
          ...(media.mentions?.length ? { mentions: media.mentions } : {}),
        }),
      media.quotedMessageId,
    );
    return toMessageResult(msg);
  }

  async sendPollMessage(chatId: string, poll: PollInput): Promise<MessageResult> {
    this.host.ensureReady();
    ensureSendable(chatId, 'poll');
    // Import Poll dynamically like Location; the .default fallback covers builds where the
    // classes land on module.default (a plain `module.Poll` would be undefined there and
    // `new Poll` fails with "not a constructor").
    const module = await import('whatsapp-web.js');
    const Poll = module.Poll || module.default?.Poll;

    // wwebjs's typings mark `messageSecret` as required, but at runtime it is optional (it is
    // only used as a custom poll id), so cast to the constructor's options type to pass just
    // allowMultipleAnswers.
    type PollSendOptions = ConstructorParameters<typeof Poll>[2];
    const pollOptions = { allowMultipleAnswers: poll.allowMultipleAnswers === true } as PollSendOptions;
    const msg = await this.sendResolved(
      chatId,
      to =>
        this.client().sendMessage(
          to,
          new Poll(poll.name, poll.options, pollOptions),
          this.quoteOptions(poll.quotedMessageId),
        ),
      poll.quotedMessageId,
    );
    return toMessageResult(msg);
  }

  async replyToMessage(chatId: string, quotedMsgId: string, text: string, mentions?: string[]): Promise<MessageResult> {
    this.host.ensureReady();
    ensureSendable(chatId, 'reply');
    try {
      // Find the message to quote
      const chat = await this.readBeforeSend('replyToMessage', () => this.client().getChatById(chatId));
      if (!chat) {
        throw new MessageNotFoundError(quotedMsgId, chatId);
      }
      const messages = await this.readBeforeSend('replyToMessage', () => chat.fetchMessages({ limit: 100 }));
      const quotedMsg = messages.find(m => m.id._serialized === quotedMsgId);

      if (!quotedMsg) {
        throw new MessageNotFoundError(quotedMsgId);
      }

      // Reply's send leg hits the same `No LID for user` path as a normal send for a migrated contact,
      // so route it through sendResolved (resolve @c.us->@lid, cache, self-heal). reply(content, chatId)
      // accepts an explicit target (#583 R1).
      // reply(content, chatId, options) takes the same options bag as sendMessage, so a quoted send
      // tags participants exactly as a plain one does. The options argument is omitted entirely when
      // no tags were asked for, keeping an ordinary reply's call shape untouched (same rule as the
      // send path).
      const msg = await this.sendResolved(chatId, to =>
        mentions?.length ? quotedMsg.reply(text, to, { mentions }) : quotedMsg.reply(text, to),
      );
      return toMessageResult(msg);
    } catch (error) {
      this.host.reportIfPageTransportError(error, 'replyToMessage');
      throw error;
    }
  }

  async forwardMessage(fromChatId: string, toChatId: string, messageId: string): Promise<MessageResult> {
    this.host.ensureReady();
    try {
      const chat = await this.readBeforeSend('forwardMessage', () => this.client().getChatById(fromChatId));
      if (!chat) {
        throw new MessageNotFoundError(messageId, fromChatId);
      }
      const messages = await this.readBeforeSend('forwardMessage', () => chat.fetchMessages({ limit: 100 }));
      const msgToForward = messages.find(m => m.id._serialized === messageId);

      if (!msgToForward) {
        throw new MessageNotFoundError(messageId);
      }

      // The forward's send leg fails with `No LID for user` for a LID-migrated destination, so resolve
      // it (and self-heal a stale mapping) via sendResolved. Capture the id actually sent to so the
      // id-recovery below reads back from the SAME (resolved) chat, not the raw @c.us (#583 R1).
      // The ids already in that chat are read first, on every attempt, so the recovery below can tell
      // the forwarded copy from an earlier send with the same whole-second timestamp. Only messages
      // WhatsApp Web already holds are read, so this never pages the chat's history in ahead of the
      // send. A read that merely fails never blocks the forward; it only leaves the copy unidentified.
      // The newest timestamp it saw is kept too: a concurrent call on the destination chat can page
      // older history in before the second read, and those messages are older than every one loaded.
      let resolvedTo = toChatId;
      let before = undefined as { ids: Set<string>; newest: number } | undefined;
      await this.sendResolved(toChatId, async to => {
        resolvedTo = to;
        before = undefined;
        try {
          const snapshot = await this.loadedOwnMessages(to);
          before = {
            ids: new Set(snapshot.map(m => toMessageResult(m).id)),
            newest: snapshot.reduce((newest, m) => Math.max(newest, m.timestamp), 0),
          };
        } catch (error) {
          // A page that died under the read is not a read that merely failed. Chromium stopped from
          // outside rejects this call before any death listener runs, so report it for the check below,
          // but only once the page itself reads gone: a live page whose exception merely says "connection
          // closed" is a read that failed, and the forward goes on.
          await this.host.reportOnceGone?.(error, 'forwardMessage');
          this.host.logger.warn(`Could not read the destination chat before forwarding: ${String(error)}`);
        }
        // The read above is a page round trip a teardown can land in. Its failure only leaves the copy
        // unidentified, unless it shows the page is gone, which this check then refuses.
        this.host.ensureReady();
        return msgToForward.forward(to);
      });

      // whatsapp-web.js's forward() returns void, so BEST-EFFORT recover the REAL id of the sent copy by
      // reading it back from the destination chat: the one outgoing message that was not there before
      // the forward, or, when several appeared, the only one marked forwarded. The delivery-ack matcher
      // keys on this id, so a synthetic one would leave the forward stuck at SENT; Baileys already
      // returns the real id. The forward already succeeded here, so recovery must NEVER fail the operation.
      // When the copy can't be identified (no snapshot, or no single candidate, as with two forwards
      // to the same chat at once) we return an explicit-unknown id (empty): message.service then
      // leaves the row's waMessageId unset so no ack can mis-match it. A wrong id is worse: persisting
      // it merges the forward's row into the other message's.
      try {
        if (before) {
          const known = before;
          const fresh = (await this.loadedOwnMessages(resolvedTo)).filter(m => {
            const id = toMessageResult(m).id;
            return id !== '' && !known.ids.has(id) && m.timestamp >= known.newest;
          });
          const forwarded = fresh.filter(m => m.isForwarded);
          const sent = fresh.length === 1 ? fresh[0] : forwarded.length === 1 ? forwarded[0] : undefined;
          if (sent) {
            return toMessageResult(sent);
          }
        }
      } catch (error) {
        // Still surface a dead page even though the send itself succeeded (detection only; the
        // forward's best-effort recovery contract is unchanged).
        this.host.reportIfPageTransportError(error, 'forwardMessage');
        this.host.logger.warn(`Forward succeeded but recovering the sent message id failed: ${String(error)}`);
      }
      return { id: '', timestamp: Math.floor(Date.now() / 1000) };
    } catch (error) {
      this.host.reportIfPageTransportError(error, 'forwardMessage');
      throw error;
    }
  }

  /**
   * The messages this account sent to a chat that WhatsApp Web already holds, forwarded copy included
   * once the send returns. No `limit`: with one, whatsapp-web.js loads earlier history until it has
   * that many, which in a chat this account rarely writes to walks the whole history.
   */
  private async loadedOwnMessages(chatId: string): Promise<Message[]> {
    const chat = await this.client().getChatById(chatId);
    return (await chat?.fetchMessages({ fromMe: true })) ?? [];
  }

  async reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void> {
    this.host.ensureReady();
    await this.withPage('reactToMessage', async () => {
      // NOTE: do NOT resolve chatId to @lid here — whatsapp-web.js reacts using the found message's own
      // id, not this chatId, so LID-resolving the lookup gives no send benefit and would miss a message
      // stored under the pre-migration @c.us chat (#583).
      const chat = await this.client().getChatById(chatId);
      // getChatById RESOLVES undefined for an unknown chat (wwebjs does not throw); guard it so the
      // caller gets the 404 editMessage returns rather than a TypeError surfacing as an opaque 500.
      if (!chat) {
        throw new MessageNotFoundError(messageId, chatId);
      }
      const messages = await chat.fetchMessages({ limit: 100 });
      const message = messages.find(m => m.id._serialized === messageId);
      if (!message) {
        throw new MessageNotFoundError(messageId, chatId);
      }
      // The message acts through the client that read it, which the host's check on getClient never sees
      // again: a teardown that landed in the lookup is the retryable 409, not a write on a closing page.
      this.host.ensureReady();
      await (message as MessageWithReactions).react(emoji);
    });
    this.host.logger.debug('Reacted to message', { messageId, emoji: emoji || '(removed)' });
  }

  async getMessageReactions(chatId: string, messageId: string): Promise<MessageReaction[]> {
    this.host.ensureReady();
    const reactions = await this.withPage('getMessageReactions', async () => {
      const chat = await this.client().getChatById(chatId);
      if (!chat) {
        throw new MessageNotFoundError(messageId, chatId);
      }
      const messages = await chat.fetchMessages({ limit: 100 });
      const message = messages.find(m => m.id._serialized === messageId);
      if (!message) {
        throw new MessageNotFoundError(messageId, chatId);
      }
      const msgWithReactions = message as MessageWithReactions;
      return msgWithReactions.hasReaction ? msgWithReactions.getReactions() : [];
    });
    if (!reactions) {
      return [];
    }
    // Map reactions to our interface format
    const result: MessageReaction[] = [];

    for (const r of reactions) {
      result.push({
        emoji: String(r.id),
        senders: (r.senders || []).map(s => ({
          senderId: String(s.senderId),
          emoji: String(s.reaction),
          timestamp: Number(s.timestamp),
        })),
      });
    }
    return result;
  }

  async getChatHistory(
    chatId: string,
    limit: number = 50,
    includeMedia: boolean = false,
    mediaMaxBytes?: number,
    signal?: AbortSignal,
  ): Promise<IncomingMessage[]> {
    this.host.ensureReady();
    // Chat.fetchMessages only caps the page when `limit > 0` (Chat.js), so a 0/negative/NaN limit fails
    // OPEN and returns every loaded message. Substitute the default, as getChannelMessages does.
    const safeLimit = Number.isFinite(limit) && limit >= 1 ? Math.trunc(limit) : 50;
    const messages = await this.withPage('getChatHistory', async () => {
      const chat = await this.client().getChatById(chatId);
      // Unknown chat: getChatById resolves undefined rather than throwing. A chat this account cannot
      // see has no history to return, so yield an empty page instead of dereferencing undefined (a
      // TypeError that would surface as a 500).
      if (!chat) {
        return [];
      }
      return chat.fetchMessages({ limit: safeLimit });
    });
    const results: IncomingMessage[] = [];
    // Aggregate base64 budget across the whole pass: the per-message cap bounds ONE blob, but without
    // an aggregate bound a 100-message history could stack ~100 × 50 MiB into one response. Once the
    // running total crosses the budget, later media messages get the declared-only `omitted` marker —
    // no download — while everything already inlined stays inline (a small history is byte-identical
    // to before). `signal` (client disconnect) stops the loop between messages; partials are returned.
    // The 25 MiB default is sized for ONE HTTP response and is too tight for a caller that ingests
    // into a store instead (mediaMaxBytes — the status seed): two ~10 MiB videos are ~28 MiB of
    // base64 and would strip every later status. Such a caller gets a budget derived from its own
    // per-item cap rather than an exemption — unbounded here would mean a 50-item seed could stack
    // ~650 MiB of base64 on the heap at connect time. The cap is clamped to MEDIA_DOWNLOAD_MAX_BYTES
    // first, as capInboundMediaFor clamps each item, so an override above it cannot inflate the budget.
    let mediaBudget = !includeMedia
      ? Number.POSITIVE_INFINITY
      : mediaMaxBytes === undefined
        ? chatHistoryMediaBudgetBytes()
        : ingestMediaBudgetBytes(Math.min(mediaMaxBytes, inboundMediaMaxBytes()));
    // Sender contacts resolved so far, keyed like Message.getContact() (`author || from`). Each lookup
    // is a page round trip and a history page repeats the same few senders, so resolve each once; a
    // failed lookup is remembered as undefined rather than retried for every later message.
    const senderContacts = new Map<string, MessageContact | undefined>();
    for (const msg of messages) {
      if (signal?.aborted) {
        break;
      }
      // Reuse the shared mapper so history messages carry the same author/contact
      // enrichment as live incoming messages (#223). The mapper defaults chatId to
      // msg.from, which is wrong here (history includes fromMe messages whose `from`
      // is our own number), so override it to the requested chat and recompute the
      // chatId-derived flags (isGroup, isStatusBroadcast, kind) from the real chat.
      const out = buildIncomingMessageBase(msg);
      out.chatId = chatId;
      out.isGroup = chatId.endsWith('@g.us');
      out.isStatusBroadcast = chatId === 'status@broadcast';
      out.kind = chatKind(chatId);
      // buildIncomingMessageBase only fills `contact` from the raw payload's synchronous
      // notifyName, which is frequently absent on a history-fetched message object (unlike a
      // freshly delivered one). Without this, a group participant not in the account's own
      // contacts (author-only, no saved name) shows no sender label at all in the chat view,
      // even though the live `message` event handler resolves one via getContact() for the
      // exact same message. Mirror that here so history and live rendering agree.
      const senderId = msg.author || msg.from;
      if (!senderContacts.has(senderId)) {
        let resolved: MessageContact | undefined;
        try {
          const contact = await msg.getContact();
          if (contact) resolved = mapContactFields(contact, process.env.WEBHOOK_CONTACT_DETAILS === 'true');
        } catch (error) {
          this.host.logger.warn(
            `Failed to resolve contact for history message ${msg.id._serialized}: ${String(error)}`,
          );
        }
        senderContacts.set(senderId, resolved);
      }
      const merged = { ...out.contact, ...senderContacts.get(senderId) };
      if (Object.keys(merged).length > 0) {
        out.contact = merged;
      }
      const call = extractWwebjsCall(msg);
      if (call) out.call = call;
      // Mirror the live handler's location + quoted-message enrichment so history renders identically —
      // buildIncomingMessageBase sets type='location' but no coordinates, and never resolves quotes.
      if (msg.type === MessageTypes.LOCATION && msg.location) {
        out.location = {
          latitude: Number(msg.location.latitude),
          longitude: Number(msg.location.longitude),
          description: msg.location.description || undefined,
          address: msg.location.address || undefined,
          url: msg.location.url || undefined,
        };
      }
      if (msg.hasQuotedMsg) {
        try {
          const quoted = await msg.getQuotedMessage();
          out.quotedMessage = { id: quoted.id._serialized, body: quoted.body };
        } catch (error) {
          this.host.logger.warn(`Failed to resolve quoted message for ${msg.id._serialized}: ${String(error)}`);
        }
      }
      if (includeMedia && msg.hasMedia) {
        if (mediaBudget <= 0) {
          out.media = declaredOnlyMedia(msg);
        } else {
          try {
            // Same pre-gate + limiter as live media: a large historical blob shouldn't bloat the
            // response/heap. Callers (the status seed) can tighten the cap below the global default.
            const capped = await this.host.capInboundMediaFor(msg, mediaMaxBytes);
            if (capped) {
              out.media = capped;
              // Only an inlined payload spends budget; an omitted marker carries no base64.
              if (capped.data) {
                mediaBudget -= capped.data.length;
              }
            }
          } catch (error) {
            this.host.logger.warn(`Failed to download media for ${msg.id._serialized}: ${String(error)}`);
          }
        }
      }
      results.push(out);
    }
    return results;
  }

  async deleteMessage(chatId: string, messageId: string, forEveryone: boolean = true): Promise<void> {
    this.host.ensureReady();
    // NOTE: do NOT resolve chatId to @lid here — delete operates on the found message's own key, not
    // this chatId, so LID-resolving the lookup gives no benefit and would miss a message stored under
    // the pre-migration @c.us chat (#583).
    await this.withPage('deleteMessage', async () => {
      const chat = await this.client().getChatById(chatId);
      if (!chat) {
        throw new MessageNotFoundError(messageId, chatId);
      }
      const messages = await chat.fetchMessages({ limit: 100 });
      const message = messages.find(m => m.id._serialized === messageId || m.id.id === messageId);
      if (!message) {
        throw new MessageNotFoundError(messageId, chatId);
      }
      this.host.ensureReady();
      await message.delete(forEveryone);
    });
    this.host.logger.debug('Deleted message', { chatId, messageId, forEveryone });
  }

  async editMessage(chatId: string, messageId: string, body: string, mentions?: string[]): Promise<MessageResult> {
    this.host.ensureReady();
    // Same lookup window as react/delete: fetchMessages sees only the 100 most recent messages.
    // NOTE: do NOT resolve chatId to @lid here — edit operates on the found message's own key, not
    // this chatId, so LID-resolving the lookup would miss a message stored under the pre-migration
    // @c.us chat (#583).
    const edited = await this.withPage('editMessage', async () => {
      const chat = await this.client().getChatById(chatId);
      // getChatById RESOLVES undefined for an unknown chat (wwebjs does not throw) — that is the same
      // client-facing outcome as a message outside the fetch window, not a TypeError (-> 500).
      if (!chat) {
        throw new MessageNotFoundError(messageId, chatId);
      }
      const messages = await chat.fetchMessages({ limit: 100 });
      const message = messages.find(m => m.id._serialized === messageId || m.id.id === messageId);
      if (!message) {
        throw new MessageNotFoundError(messageId, chatId);
      }
      this.host.ensureReady();
      // An edit REPLACES the content, so tags are re-applied rather than preserved: omitting mentions
      // drops whatever the original carried. Options omitted entirely when none were asked for.
      return mentions?.length ? message.edit(body, { mentions }) : message.edit(body);
    });
    if (!edited) {
      // wwebjs RESOLVES null (instead of throwing) when the page-side edit is refused — only the
      // account's own text messages are editable; surface the refusal, not a phantom success.
      throw new EngineRefusedError(
        `the edit of message ${messageId} was rejected — only the account's own text messages can be edited`,
      );
    }
    this.host.logger.debug('Edited message', { chatId, messageId });
    return toMessageResult(edited);
  }

  /**
   * Locate a message in the 100-message fetch window shared by react/delete/edit — and now pin.
   * Deliberately NOT applied to the existing call sites: they differ in whether they tolerate an
   * unknown chat, and rewriting them is not this change's business.
   *
   * As with those sites, chatId is NOT lid-resolved: the pin acts on the found message's own key,
   * so resolving would only risk missing a message stored under the pre-migration @c.us chat.
   *
   * Readiness is checked again before the message is returned: it acts through the client that read it, so
   * a teardown that landed in the lookup would otherwise reach a closing page.
   */
  private async findInFetchWindow(chatId: string, messageId: string): Promise<Message> {
    const chat = await this.client().getChatById(chatId);
    // getChatById RESOLVES undefined for an unknown chat rather than throwing, which is the same
    // client-facing outcome as a message outside the window — a 404, not a TypeError-driven 500.
    if (!chat) throw new MessageNotFoundError(messageId, chatId);
    const messages = await chat.fetchMessages({ limit: 100 });
    const message = messages.find(m => m.id._serialized === messageId || m.id.id === messageId);
    if (!message) throw new MessageNotFoundError(messageId, chatId);
    this.host.ensureReady();
    return message;
  }

  async votePoll(chatId: string, pollMessageId: string, options: string[]): Promise<void> {
    this.host.ensureReady();
    // Same 100-message window as pin/react/delete, so a poll older than that is unreachable and
    // reported as not-found rather than as a failed vote.
    try {
      await this.withPage('votePoll', async () => {
        const message = await this.findInFetchWindow(chatId, pollMessageId);
        // vote() matches option TEXTS exactly and silently drops the ones that match nothing. When
        // none match it sends an empty selection, the same as `options: []`, which CLEARS the vote
        // while the route answered 200. Refuse that case with the poll's real options so a typo or a
        // differently-cased text is reported instead of erasing the account's vote. An explicit `[]`
        // is still a deliberate clear. A message with no pollOptions is not a poll; vote() below
        // rejects it with its own error.
        const pollOptions = (message as unknown as { pollOptions?: Array<{ name?: unknown }> }).pollOptions;
        if (options.length > 0 && Array.isArray(pollOptions)) {
          const names = pollOptions.map(o => o?.name).filter((n): n is string => typeof n === 'string');
          if (!options.some(option => names.includes(option))) {
            throw new BadRequestException({
              statusCode: 400,
              error: 'Bad Request',
              message: `None of the options match poll ${pollMessageId}; options must be the exact texts: ${names
                .map(n => JSON.stringify(n))
                .join(', ')}`,
              code: 'POLL_OPTION_NOT_FOUND',
              validOptions: names,
            });
          }
        }
        await (message as unknown as { vote(selected: string[]): Promise<void> }).vote(options);
      });
    } catch (error) {
      // vote() throws a BARE STRING (not an Error) when the target is not a poll creation message
      // (Message.js:1010). Left alone that surfaces as an opaque 500; it is a client mistake, so
      // map it to a 400. Anything that is a real Error is a genuine engine fault and propagates.
      if (typeof error === 'string') {
        throw new BadRequestException(`Message ${pollMessageId} is not a poll: ${error}`);
      }
      throw error;
    }
    this.host.logger.debug('Voted on poll', { chatId, pollMessageId, options: options.length });
  }

  async pinMessage(chatId: string, messageId: string, durationSeconds: number): Promise<void> {
    this.host.ensureReady();
    // The page-side helper returns false rather than throwing for every refusal — a non-number
    // duration, a message it cannot resolve, or a send WhatsApp rejected (Injected/Utils.js:1670).
    // Surface that as a refusal instead of reporting a pin that never happened.
    const pinned = await this.withPage('pinMessage', async () => {
      const message = await this.findInFetchWindow(chatId, messageId);
      return message.pin(durationSeconds);
    });
    if (!pinned) {
      throw new EngineRefusedError(
        `the pin of message ${messageId} was rejected — in a group only admins may pin, and the duration must be 24h, 7d or 30d`,
      );
    }
    this.host.logger.debug('Pinned message', { chatId, messageId, durationSeconds });
  }

  async starMessage(chatId: string, messageId: string, star: boolean): Promise<void> {
    this.host.ensureReady();
    // Both resolve void, and the page-side helper silently does nothing when canStarMsg() refuses
    // the message (Message.js:672-712). There is no signal to map, so a star that WhatsApp declined
    // is indistinguishable from one it accepted — documented rather than faked into a refusal.
    await this.withPage('starMessage', async () => {
      const message = await this.findInFetchWindow(chatId, messageId);
      await (star ? message.star() : message.unstar());
    });
    this.host.logger.debug(star ? 'Starred message' : 'Unstarred message', { chatId, messageId });
  }

  async unpinMessage(chatId: string, messageId: string): Promise<void> {
    this.host.ensureReady();
    // unpin() passes duration 0 itself, so the injected non-number guard cannot bite here; a false
    // return means WhatsApp refused the unpin (e.g. not an admin).
    const unpinned = await this.withPage('unpinMessage', async () => {
      const message = await this.findInFetchWindow(chatId, messageId);
      return message.unpin();
    });
    if (!unpinned) {
      throw new EngineRefusedError(`the unpin of message ${messageId} was rejected — in a group only admins may unpin`);
    }
    this.host.logger.debug('Unpinned message', { chatId, messageId });
  }
}