Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

56.7 KB
Raw Blame
import { queryLidPhone } from './baileys-identity-query';
import type * as BaileysLib from '@whiskeysockets/baileys';
import type {
  AnyMessageContent,
  MiscMessageGenerationOptions,
  WAMessage,
  WAMessageKey,
  WASocket,
} from '@whiskeysockets/baileys';
import { generateSafeLinkPreview } from './safe-link-preview';
import {
  CallLinkType,
  CustomLinkPreview,
  ChatState,
  ContactCard,
  EngineEventCallbacks,
  IncomingMessage,
  LocationInput,
  MediaInput,
  MessageResult,
  MessageType,
  PollInput,
  Product,
  Quotable,
} from '../interfaces/whatsapp-engine.interface';
import { refusedStatusCode, toEngineParticipants } from './baileys-groups';
import { findSelfParticipant } from './baileys-group-mapper';
import { buildVCard } from './vcard';
import {
  baileysChatJid,
  isBaileysCatalogShare,
  mapBaileysMessageType,
  resolveBaileysButtonClick,
  setBaileysText,
  storedKeyInChatPersisted,
} from './baileys-message-mapper';
import { loadRemoteMediaBuffer } from '../../common/media/load-remote-media';
import { BadRequestException, InternalServerErrorException } from '@nestjs/common';
import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
import { EngineRefusedError } from '../../common/errors/engine-refused.error';
import { MessageNotFoundError } from '../../common/errors/message-not-found.error';
import { type createLogger } from '../../common/services/logger.service';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { EngineThrottledError } from '../../common/errors/engine-throttled.error';
import { EngineNotSentError } from '../../common/errors/engine-not-sent.error';
import { parseWaId, userPart } from '../identity/wa-id';
import { BAILEYS_QUERY_BUDGET_MS, confirmedWrite, withQueryDeadline } from './baileys-query-deadline';
import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
import { describeAudio } from './baileys-audio-probe';

/**
 * Messaging-domain operations extracted from BaileysAdapter. The adapter keeps the public
 * methods as thin forwarders and injects this narrow host surface via closures, so the
 * delegate never touches lifecycle state directly.
 */
export interface BaileysMessagingHost {
  /** This session's egress proxy URL (snapshotted at session start), or undefined when direct. */
  sessionProxyUrl(): string | undefined;
  ensureReady(): void;
  /** Post-ensureReady socket handle — call host.ensureReady() first. */
  getSocket(): WASocket;
  /** The live socket, or null once a stop or logout has torn it down. */
  getSocketOrNull(): WASocket | null;
  readonly logger: ReturnType<typeof createLogger>;
  toNeutralJid(jid: string): string;
  toEngineJid(jid: string): string;
  findPersistedLidPhone?(jid: string): Promise<string | null>;
  normalizedSelfJid(): string;
  /** The chat's cached disappearing-messages timer (#473), or undefined when none is known. */
  getEphemeralExpiration(chatId: string): number | undefined;
  /** Baileys timestamps are `number | Long`; normalize to unix seconds. */
  toUnixSeconds(ts: number | string | { toNumber(): number } | null | undefined): number;
  /** Lazily loaded @whiskeysockets/baileys module (ESM-only; loaded on first connect, not at boot). */
  loadLib(): Promise<typeof BaileysLib>;
  /** Persist a just-sent message to the store; undefined when no store is configured. */
  putStoredMessage(msg: WAMessage): Promise<void> | undefined;
  /** Make a just-sent message the chat's last-message preview and sort time (its echo is skipped). */
  recordMessage(msg: WAMessage, type?: MessageType): void;
  /** Replace the chat preview's text when the message is still the chat's last one (edit, or '' once deleted). */
  recordMessageEdit(chatId: string, messageId: string, text: string, type?: MessageType): void;
  /** Record the id of a message this session just sent, so its library echo is recognised as ours. */
  rememberOwnSend(id: string | null | undefined): void;
  /** Look up a previously-seen message from the store (the reply/forward/react/delete handle). */
  getStoredMessage(messageId: string): Promise<WAMessage | null> | undefined;
  /** Rewrite a stored message in place (see BaileysMessageStore.update); undefined without a store. */
  updateStoredMessage(messageId: string, change: (stored: WAMessage) => WAMessage | null): Promise<void> | undefined;
  /** Whether this message was deleted for everyone, even where the stored copy does not show it yet. */
  wasDeletedForEveryone(messageId: string): boolean;
  /** Record a delete for everyone this session just made (see wasDeletedForEveryone). */
  markDeletedForEveryone(messageId: string): void;
  /** The text of an edit of this message the stored copy with key `target` does not show yet, if any. */
  pendingEditOf(messageId: string, target: WAMessageKey): string | undefined;
  /** Remember a lid<->phone pair the socket resolved, so later reads do not have to ask again. */
  recordLidMapping(lid: string, pn: string, isReported?: boolean): void;
  /** The currently-registered onMessageCreate callback, if any (assigned at initialize()). */
  getOnMessageCreate(): EngineEventCallbacks['onMessageCreate'];
  /** Map a WAMessage to its neutral shape (the adapter's inbound mapper). */
  mapMessage(
    msg: WAMessage,
    contentType: string | undefined,
    opts?: { skipMediaDownload?: boolean },
  ): Promise<IncomingMessage>;
}

/** RIFF….WEBP magic. Sniffed from the bytes, because the declared label may be the DTO's placeholder. */
function isWebpBuffer(data: Buffer): boolean {
  return (
    data.length > 12 &&
    data.subarray(0, 4).toString('ascii') === 'RIFF' &&
    data.subarray(8, 12).toString('ascii') === 'WEBP'
  );
}

/**
 * Sticker payloads must BE WebP, not merely be called WebP.
 *
 * Baileys stamps the label unconditionally — `prepareWAMessageMedia` applies
 * `if (!uploadData.mimetype) uploadData.mimetype = MIMETYPE_MAP[mediaType]` with
 * `MIMETYPE_MAP.sticker = 'image/webp'` (Utils/messages.js:18, 86-88) — and transcodes nothing. So
 * a PNG handed over here is published as a stickerMessage whose declared type contradicts its bytes,
 * and the send still reports success. whatsapp-web.js has no such gap: `sendMediaAsSticker: true`
 * routes through `Util.formatToWebpSticker`, which converts `image/*` and throws for anything else.
 *
 * An input that is already WebP is passed through BYTE-IDENTICAL: re-encoding an existing sticker
 * would strip the WebP EXIF sticker-pack metadata and change its size.
 *
 * `{ animated: true }` is not optional — without it sharp silently keeps only the first frame, which
 * would reintroduce the same quiet-corruption this function exists to remove.
 */
/**
 * Load the deferred `sharp` binary, mapping a LOAD failure to a 500 rather than the decode path's 400.
 * A native-binary load failure (older CPU, stripped/musl image, missing prebuilt) is a host capability
 * gap: a valid PNG would hit it too, so reporting it as a 400 tells the caller their image is malformed.
 */
export async function loadSharp() {
  try {
    return (await import('sharp')).default;
  } catch (error) {
    throw new InternalServerErrorException(
      `Sticker conversion is unavailable: sharp could not load (${error instanceof Error ? error.message : String(error)}).`,
    );
  }
}

/**
 * Refuse SVG input process-wide. OpenWA never needs it, yet a sticker and the thumbnail of every outbound
 * image hand caller-supplied bytes to sharp, which autodetects SVG and parses it with librsvg: a native
 * decoder with a memory-safety record that is the largest attack surface on those two routes. The block is
 * libvips state shared by every importer of sharp, Baileys included, so it has to be set before the first
 * decode and not by the first sticker. Best effort: a sharp that cannot load has nothing to block, and the
 * routes that need it report that themselves (see loadSharp).
 */
export async function blockSvgDecoding(): Promise<void> {
  try {
    (await import('sharp')).default.block({ operation: ['VipsForeignLoadSvg'] });
  } catch {
    // sharp could not load, so there is no decoder to block.
  }
}

/**
 * Refuse a picture the image decoder cannot read, before Baileys hands it to that decoder: its own
 * conversion rejects such a file with an error nothing maps, which reached the client as a 500. An SVG is
 * one since blockSvgDecoding, and so is a file that is no image at all. Only the header is read. A sharp
 * that cannot load is left to the library, which reports that itself.
 */
export async function assertReadableImage(data: Buffer): Promise<void> {
  const sharp = await import('sharp').then(
    module => module.default,
    () => undefined,
  );
  if (!sharp) return;
  try {
    await sharp(data).metadata();
  } catch (error) {
    throw new BadRequestException(
      `The picture could not be read as an image (SVG is not accepted): ${error instanceof Error ? error.message : String(error)}`,
    );
  }
}

/**
 * Animation frames a sticker conversion accepts: a 10-second animation at 50 fps. Each frame is
 * resized and encoded at 512x512 (a few ms apiece), so cost is linear in the frame count, and a
 * GIF of 1x1 frames packs tens of thousands of them into well under a megabyte.
 */
export const MAX_STICKER_FRAMES = 500;

/**
 * Conversions running at once, process-wide. Each sharp call (the frame scan, then the pipeline)
 * holds a libuv threadpool worker (4 by default) for its whole run, and that pool also serves fs,
 * dns.lookup, crypto and zlib.
 */
const stickerConversions = new ConcurrencyLimiter(2);

async function toWebpSticker(data: Buffer, mimetype: string): Promise<Buffer> {
  if (isWebpBuffer(data)) {
    return data;
  }
  if (!mimetype.startsWith('image/')) {
    // Deliberately a 400 rather than EngineNotSupportedError: the capability IS supported, this
    // particular payload cannot become a sticker. A 501 would report the wrong thing and would also
    // make the row look unavailable to the parity gate's throw-scan.
    throw new BadRequestException(
      `A sticker must be a WebP image, or an image this gateway can convert to one. Received '${mimetype}'.`,
    );
  }
  // Imported lazily so an unusable `sharp` (a native binary that will not build or load on an older
  // CPU, a stripped image) degrades ONLY this one Baileys sticker route instead of killing the whole
  // gateway at boot. `sharp` sits at the top of a module the built-in engine loads unconditionally, so
  // an eager import made a single optional capability a hard boot requirement on both engines. Same
  // deferral the adapters already use for the engine libraries themselves.
  const sharp = await loadSharp();
  try {
    const image = sharp(data, { animated: true });
    return await stickerConversions.run(async () => {
      // Counting frames only scans the file, so an oversized animation is refused before any decode.
      // The scan still runs on the threadpool and grows faster than the frame count, so it holds the
      // same slot as the pipeline.
      const { pages = 1 } = await image.metadata();
      if (pages > MAX_STICKER_FRAMES) {
        throw new BadRequestException(
          `The sticker animation has ${pages} frames; at most ${MAX_STICKER_FRAMES} can be converted.`,
        );
      }
      return image
        .resize(512, 512, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
        .webp()
        .toBuffer();
    });
  } catch (error) {
    if (error instanceof BadRequestException) throw error;
    // Bytes that do not decode as the image they claim to be. Refuse before the socket rather than
    // ship them mislabelled — that is the whole point.
    throw new BadRequestException(
      `The sticker image could not be converted to WebP: ${error instanceof Error ? error.message : String(error)}`,
    );
  }
}

/** Fetched Content-Types that say nothing about the bytes (a missing header reads as ''). */
const GENERIC_FETCHED_TYPES = new Set(['', 'application/octet-stream', 'binary/octet-stream']);

/**
 * Resolve a MediaInput's data (Buffer | base64 string | http(s) URL) to bytes + mimetype.
 *
 * `sessionProxyUrl` is this session's egress proxy, which the URL fetch leaves through (#1626). It
 * is required, not optional, so a new call site cannot fetch direct on a proxied session by omission.
 *
 * `fallbackType` is the kind's default (image/jpeg, video/mp4, audio/mpeg, application/octet-stream for a
 * document), used for a URL whose type neither the caller nor the host names. A document needs one too:
 * Baileys labels a document with an empty type as application/pdf.
 */
export async function resolveMediaBuffer(
  media: MediaInput,
  sessionProxyUrl: string | undefined,
  fallbackType?: string,
): Promise<{ data: Buffer; mimetype: string }> {
  if (Buffer.isBuffer(media.data)) {
    return { data: media.data, mimetype: media.mimetype };
  }
  if (/^https?:\/\//i.test(media.data)) {
    const fetched = await loadRemoteMediaBuffer(media.data, sessionProxyUrl);
    // A generic placeholder mimetype (buildMediaInput's 'application/octet-stream' default when the
    // caller supplied none) carries no real signal, so the fetched Content-Type decides. That header
    // is taken as the host sent it, not sniffed from the bytes, so a missing or generic one is no
    // better than the placeholder and the kind's default stands in. This serves URL-based sends where
    // the caller has no mimetype to pass through the conversation-send facade (e.g. chatwoot-adapter
    // outbound relay).
    const callerMimetype = media.mimetype && media.mimetype !== 'application/octet-stream' ? media.mimetype : null;
    const unknown = fallbackType !== undefined && GENERIC_FETCHED_TYPES.has(fetched.mimetype.toLowerCase());
    return { data: fetched.data, mimetype: callerMimetype ?? (unknown ? fallbackType : fetched.mimetype) };
  }
  return { data: Buffer.from(media.data, 'base64'), mimetype: media.mimetype };
}

/**
 * Give a WhatsApp throttle or timeout answer (WA code 429 or 408) its retryable 503 instead of letting
 * the raw Boom surface as a 500. `sendMessage` awaits several IQs before it relays the message (group
 * roster, devices, sessions) and nothing after the relay awaits a result, so a numeric code here is a
 * query WhatsApp turned away: a 429 provably sent nothing. Every other failure is returned untouched.
 */
export function mapSendRefusal(error: unknown): unknown {
  const code = refusedStatusCode(error);
  if (code === 429) return new EngineThrottledError('WhatsApp rate-limited the send (code 429)');
  if (code === 408) return new EngineTransportError('WhatsApp timed out a query the send depends on (code 408)');
  return error;
}

export class BaileysMessaging {
  constructor(
    private readonly host: BaileysMessagingHost,
    private readonly queryBudgetMs: number = BAILEYS_QUERY_BUDGET_MS,
  ) {}

  /** Bound a write whose confirmation the library discards; see baileys-query-deadline.ts. */
  private confirmed<T>(work: Promise<T>, operation: string): Promise<T> {
    return confirmedWrite(work, this.queryBudgetMs, operation);
  }

  /** Post-ensureReady socket handle. */
  private sock(expected?: WASocket): WASocket {
    const socket = this.host.getSocket();
    if (expected && socket !== expected) throw new EngineNotReadyError();
    return socket;
  }

  async sendTextMessage(
    chatId: string,
    text: string,
    mentions?: string[],
    sendOptions?: { linkPreview?: boolean; customPreview?: CustomLinkPreview } & Quotable,
  ): Promise<MessageResult> {
    this.host.ensureReady();
    const jid = await this.toDeliverableJid(chatId);
    // Baileys spreads the caller's options LAST (messages-send.js:1086), so `getUrlInfo` here
    // replaces its hardcoded one — which delegates to a package carrying an unfixed SSRF advisory
    // (see safe-link-preview.ts). Passed on every text send so that generator is never reachable,
    // not only when a preview was asked for.
    const options = {
      ...(this.withEphemeral(jid) ?? {}),
      getUrlInfo: (text: string) => generateSafeLinkPreview(text, { sessionProxyUrl: this.host.sessionProxyUrl() }),
      // Merged rather than assigned: getUrlInfo above must survive, or the library's own vulnerable
      // preview generator becomes reachable again on quoted sends only.
      ...((await this.quoteOption(sendOptions?.quotedMessageId)) ?? {}),
    };
    // `linkPreview: null` is Baileys' explicit "no preview": with the key absent it instead calls the
    // configured generator (Utils/messages.js:279-281), which for us means a blocking outbound fetch
    // of every URL in the text (up to 3s each, no cache) before the message can go out.
    //
    // Previews are therefore OPT-IN on this engine: only `linkPreview: true` leaves the key absent.
    // That keeps the documented engine default ("Baileys builds none") true, and keeps a bulk
    // campaign whose template carries a slow or dead URL from stalling on every single message.
    // getUrlInfo above is still passed unconditionally, so the library's vulnerable generator stays
    // unreachable on the paths that do generate.
    const content = {
      text,
      ...this.withMentions(mentions),
      ...(sendOptions?.linkPreview === true ? {} : { linkPreview: null }),
      // A caller-supplied preview short-circuits generation entirely: with the key present Baileys
      // never calls getUrlInfo, so nothing is fetched and the metadata is used verbatim.
      ...(sendOptions?.customPreview
        ? {
            linkPreview: {
              'matched-text': sendOptions.customPreview.url,
              'canonical-url': sendOptions.customPreview.url,
              title: sendOptions.customPreview.title,
              ...(sendOptions.customPreview.description ? { description: sendOptions.customPreview.description } : {}),
            },
          }
        : {}),
    };
    const sent = await this.send(jid, content, options);
    if (sent) {
      void this.host.putStoredMessage(sent)?.catch(err =>
        this.host.logger.warn('Failed to persist sent message to store', {
          error: err instanceof Error ? err.message : String(err),
        }),
      );
      this.host.recordMessage(sent, 'text');
      // Parity with the wwjs engine's message_create → message.sent (see emitOwnSendEcho).
      void this.emitOwnSendEcho(sent);
    }
    return {
      id: sent?.key?.id ?? '',
      timestamp: this.host.toUnixSeconds(sent?.messageTimestamp),
    };
  }

  async checkNumberExists(number: string): Promise<boolean> {
    return (await this.getNumberId(number)) !== null;
  }

  async getNumberId(number: string): Promise<string | null> {
    this.host.ensureReady();
    const results = await withQueryDeadline(
      this.sock().onWhatsApp(number),
      this.queryBudgetMs,
      'WhatsApp did not answer the number-check query in time',
    );
    // onWhatsApp has no else branch after `if (results)`, so it resolves undefined when the usync
    // query goes unanswered — and Baileys' query() swallows its own timeout rather than throwing.
    // An empty ARRAY is a real answer; undefined is the absence of one, and coalescing the two
    // turns "we never heard back" into "this number is not on WhatsApp", which the caller then
    // acts on. The two are distinguishable here, so they are distinguished.
    if (results === undefined) {
      throw new EngineTransportError('WhatsApp did not answer the number-check query');
    }
    const hit = results[0];
    // Baileys returns a raw `<phone>@s.whatsapp.net`; neutralize it before it crosses the engine
    // boundary so the value matches whatsapp-web.js (`<phone>@c.us`) and the IWhatsAppEngine contract
    // (no raw `@s.whatsapp.net` in a neutral field). It also round-trips back to a send on either engine.
    return hit?.exists ? this.host.toNeutralJid(hit.jid) : null;
  }

  async sendChatState(chatId: string, state: ChatState): Promise<void> {
    this.host.ensureReady();
    const presence = state === 'typing' ? 'composing' : state === 'recording' ? 'recording' : 'paused';
    try {
      await this.sock().sendPresenceUpdate(presence, await this.toDeliverableJid(chatId));
    } catch (error) {
      // Presence is best-effort — a failure here must never surface as a 500 on the direct typing
      // endpoint or MCP tool (mirrors the whatsapp-web.js adapter; #583 R4). A migrated contact can
      // yield `No LID for user` on the presence path even when the actual send succeeds.
      this.host.logger.warn(`Could not set chat state '${state}' for ${chatId} (best-effort)`, {
        error: String(error),
      });
    }
  }

  /**
   * Publish the account's own GLOBAL presence — the no-jid form of sendPresenceUpdate, which
   * addresses the whole account rather than a chat (`<presence>`, not a per-chat `<chatstate>`).
   * Not best-effort, unlike sendChatState: the caller asked for a specific visibility, so a
   * failure surfaces instead of leaving the account silently online (#871).
   *
   * Baileys resolves this call without sending anything when `creds.me.name` is unset (it logs
   * "no name present, ignoring presence update request" and returns). `sock.user` is that cred.
   * Refusing here keeps PUT /presence from reporting success for an update that never left.
   */
  async setOnlinePresence(available: boolean): Promise<void> {
    this.host.ensureReady();
    if (!this.sock().user?.name) {
      throw new EngineNotReadyError(
        'The account push name is not available yet, so this presence update would be ignored. Retry once the session has synced its profile name.',
      );
    }
    await this.sock().sendPresenceUpdate(available ? 'available' : 'unavailable');
  }

  /**
   * Subscribe to a chat's presence. Unlike sendChatState this is NOT best-effort: the caller asked
   * for a subscription, and silently swallowing a failure would leave them waiting for updates that
   * can never arrive. A failure surfaces so the caller can retry or stop expecting them.
   */
  async subscribeToPresence(chatId: string): Promise<void> {
    this.host.ensureReady();
    await this.sock().presenceSubscribe(await this.toDeliverableJid(chatId));
  }

  /**
   * Send a native product card (#905). Baileys has no catalog-lookup-then-send helper, so the
   * adapter resolves the Product first; here it becomes a {product} message whose snapshot is
   * priced in thousandths (priceAmount1000) and whose image is handed to Baileys as a URL upload.
   * The card needs an image — a product whose catalog entry has none cannot be sent this way.
   */
  async sendProductMessage(chatId: string, product: Product, body?: string): Promise<MessageResult> {
    this.host.ensureReady();
    if (!product.imageUrl) {
      throw new BadRequestException(`Product ${product.id} has no image — a product card requires one`);
    }
    const content: AnyMessageContent = {
      product: {
        productId: product.id,
        title: product.name,
        description: product.description,
        currencyCode: product.currency,
        priceAmount1000: product.price === undefined ? undefined : Math.round(product.price * 1000),
        retailerId: product.retailerId,
        url: product.url || undefined,
        productImage: { url: product.imageUrl },
      },
      businessOwnerJid: this.host.toEngineJid(this.host.normalizedSelfJid()),
      body,
    };
    return this.sendContent(chatId, content);
  }

  async sendImageMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    this.host.ensureReady();
    const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl(), 'image/jpeg');
    return this.sendContent(
      chatId,
      {
        image: data,
        caption: media.caption,
        mimetype,
        ...this.withMentions(media.mentions),
      },
      await this.quoteOption(media.quotedMessageId),
    );
  }

  async sendVideoMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    this.host.ensureReady();
    const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl(), 'video/mp4');
    return this.sendContent(
      chatId,
      {
        video: data,
        caption: media.caption,
        mimetype,
        ...this.withMentions(media.mentions),
      },
      await this.quoteOption(media.quotedMessageId),
    );
  }

  async sendAudioMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    this.host.ensureReady();
    const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl(), 'audio/mpeg');
    const ptt = media.ptt ?? false;
    return this.sendContent(
      chatId,
      // Audio carries no caption, so a mention here tags the recipient through contextInfo without
      // visible @text. It is still forwarded: the route accepts `mentions` (SendAudioMessageDto
      // extends SendMediaMessageDto) and whatsapp-web.js sends it, so dropping it here made the same
      // request notify participants on one engine and silently not on the other.
      // The duration and a voice note's waveform come from describeAudio, never from Baileys, which
      // would read the file in this process.
      { audio: data, mimetype, ptt, ...(await describeAudio(data, ptt)), ...this.withMentions(media.mentions) },
      await this.quoteOption(media.quotedMessageId),
    );
  }

  async sendDocumentMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    this.host.ensureReady();
    const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl(), 'application/octet-stream');
    return this.sendContent(
      chatId,
      {
        document: data,
        mimetype,
        fileName: media.filename ?? 'file',
        caption: media.caption,
        ...this.withMentions(media.mentions),
      },
      await this.quoteOption(media.quotedMessageId),
    );
  }

  async createCallLink(type: CallLinkType, startTime: number): Promise<string> {
    this.host.ensureReady();
    const lib = await this.host.loadLib();
    // The socket resolves only the bare `token` attribute of the `link_create` node; the finished
    // link is that token behind one of the library's two exported prefixes. Note the audio prefix
    // WhatsApp itself uses is `/voice/`, which is also what whatsapp-web.js calls the same thing.
    //
    // No timeoutMs is passed: without it the library's wait resolves nothing after its own 60 s, which
    // would read as "no link". The wrap below is the deadline, but its 503 is rethrown as a 500:
    // minting is non-idempotent and the deadline does not cancel the query, so a client replaying a
    // 503 could create a second link. Same rule as createGroup and the whatsapp-web.js call link.
    let token: string | undefined;
    try {
      token = await this.confirmed(
        this.sock().createCallLink(type, { startTime: Math.floor(startTime / 1000) }),
        'the call link',
      );
    } catch (err) {
      throw err instanceof EngineTransportError ? new Error(err.message) : err;
    }
    if (!token) {
      // A prefix with nothing after it is a dead link that looks like a real one — the caller would
      // hand it to a user and only find out then.
      throw new EngineRefusedError('WhatsApp did not return a call link');
    }
    return `${type === 'video' ? lib.CALL_VIDEO_PREFIX : lib.CALL_AUDIO_PREFIX}${token}`;
  }

  async sendStickerMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
    this.host.ensureReady();
    const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());
    // A sticker has neither text nor caption, but stickerMessage carries a contextInfo like every
    // other content type, so a mention still tags the participant. The route accepts the field
    // (send-sticker shares SendMediaMessageDto) and docs/06 lists it among the media sends that
    // take one, so dropping it here left a documented capability doing nothing.
    return this.sendContent(
      chatId,
      { sticker: await toWebpSticker(data, mimetype), ...this.withMentions(media.mentions) },
      await this.quoteOption(media.quotedMessageId),
    );
  }

  async sendLocationMessage(chatId: string, location: LocationInput): Promise<MessageResult> {
    this.host.ensureReady();
    return this.sendContent(
      chatId,
      {
        location: {
          degreesLatitude: location.latitude,
          degreesLongitude: location.longitude,
          name: location.description,
          address: location.address,
        },
      },
      await this.quoteOption(location.quotedMessageId),
    );
  }

  async sendContactMessage(chatId: string, contact: ContactCard): Promise<MessageResult> {
    this.host.ensureReady();
    return this.sendContent(
      chatId,
      {
        contacts: { displayName: contact.name, contacts: [{ vcard: buildVCard(contact) }] },
      },
      await this.quoteOption(contact.quotedMessageId),
    );
  }

  async sendPollMessage(chatId: string, poll: PollInput): Promise<MessageResult> {
    this.host.ensureReady();
    // selectableCount 1 = single choice; 0 = no limit, which is how WhatsApp expresses
    // "allow multiple answers". Baileys generates the poll's messageSecret itself.
    return this.sendContent(
      chatId,
      {
        poll: {
          name: poll.name,
          values: poll.options,
          selectableCount: poll.allowMultipleAnswers ? 0 : 1,
        },
      },
      await this.quoteOption(poll.quotedMessageId),
    );
  }

  async replyToMessage(chatId: string, quotedMsgId: string, text: string, mentions?: string[]): Promise<MessageResult> {
    this.host.ensureReady();
    const socket = this.sock();
    const quoted = await this.requireStored(quotedMsgId);
    // The one requireStored path that had no chat check. whatsapp-web.js resolves the quote by
    // fetching from the named chat and 404s when the id is not in it, so the same request replied
    // across conversations here and was refused there. The library encodes the foreign chat into
    // contextInfo rather than rejecting it (Utils/messages.js), so the adapter is the only guard.
    // NOT applied to quoteOption: cross-chat quoting on the send-* routes is deliberate and
    // published in docs/06.
    await this.assertStoredInChat(quoted, chatId, quotedMsgId, socket);
    return this.sendContent(chatId, { text, ...this.withMentions(mentions) }, { quoted }, socket);
  }

  /**
   * Send a structured button/list reply against a stored business prompt.
   *
   * Classic prompts (`buttonsMessage` / `templateMessage` / `listMessage`) go through Baileys'
   * `buttonReply` / `listReply` helpers via {@link sendContent}, so the send inherits
   * `withEphemeral`, the store put and the own-send echo. Native-flow `interactiveMessage` has no
   * helper; it uses the template `buttonReply` shape, which is unverified against a live business
   * native-flow prompt.
   */
  async clickButton(chatId: string, messageId: string, buttonId: string, text?: string): Promise<MessageResult> {
    this.host.ensureReady();
    const socket = this.sock();
    const quoted = await this.requireStored(messageId);
    await this.assertStoredInChat(quoted, chatId, messageId, socket);

    const b = await this.host.loadLib();
    const normalized = b.normalizeMessageContent(quoted.message ?? undefined) ?? quoted.message ?? {};
    const contentType = b.getContentType(normalized);
    const resolved = resolveBaileysButtonClick(normalized, contentType, buttonId, text);
    if (!resolved.ok) {
      if (resolved.error === 'unknown_button') {
        throw new BadRequestException(
          `buttonId "${buttonId}" is not among the clickable choices on message ${messageId}`,
        );
      }
      throw new BadRequestException(
        `message ${messageId} is not a WhatsApp Business button/list prompt that can be clicked`,
      );
    }

    const result = await this.sendContent(chatId, resolved.payload.content as AnyMessageContent, { quoted }, socket);
    return { ...result, body: resolved.payload.text };
  }

  async forwardMessage(fromChatId: string, toChatId: string, messageId: string): Promise<MessageResult> {
    this.host.ensureReady();
    const socket = this.sock();
    const forward = await this.requireStored(messageId);
    // fromChatId was accepted and then ignored, so a message id from ANY chat forwarded successfully
    // while whatsapp-web.js answered 404 for the same request (it fetches from the named chat and
    // fails when the id is not in it). Same check the star and react paths already apply.
    await this.assertStoredInChat(forward, fromChatId, messageId, socket);
    return this.sendContent(toChatId, { forward }, undefined, socket);
  }

  async reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void> {
    this.host.ensureReady();
    const socket = this.sock();
    const target = await this.requireStored(messageId);
    await this.assertStoredInChat(target, chatId, messageId, socket);
    // Resolved like any other send: a lid-migrated contact rejects PN-addressed sends (ack 463).
    await this.send(
      await this.toDeliverableJid(chatId, socket),
      { react: { text: emoji, key: target.key } },
      undefined,
      socket,
    );
  }

  async deleteMessage(chatId: string, messageId: string, forEveryone = true): Promise<void> {
    this.host.ensureReady();
    const socket = this.sock();
    // A message already deleted for everyone can still be deleted for me: that clears its placeholder.
    const target = await this.requireStored(messageId, true);
    await this.assertStoredInChat(target, chatId, messageId, socket);
    // Only the sender, or a group admin, can delete a message for everyone. WhatsApp ignores any other
    // revoke, yet the send resolves, so it would report a deletion that never happened. WhatsApp Web
    // deletes such a message for the account alone instead, and so does this. A group whose member
    // list shows no row for the account proves nothing either way, so the revoke still goes out there.
    // Whichever branch runs, the text leaves this account's view, so clear the preview immediately.
    const chatJid = target.key.remoteJid ?? chatId;
    // The preview of a received broadcast-list message is kept in its sender's chat.
    const previewJid = baileysChatJid(chatJid, target.key.participant, target.key.fromMe === true);
    if (
      forEveryone &&
      (target.key.fromMe === true || (await this.selfIsGroupAdmin(target.key.remoteJid, socket)) !== false)
    ) {
      await this.send(await this.toDeliverableJid(chatId, socket), { delete: target.key }, undefined, socket);
      this.host.recordMessageEdit(previewJid, messageId, '', 'revoked');
      // Clear the stored copy before the buffered echo arrives. Record the deletion first so it
      // survives a failed store write or a repeat delivery of the original.
      this.host.markDeletedForEveryone(messageId);
      await this.changeStored(messageId, stored => ({ ...stored, message: null }));
      return;
    }
    // Delete-for-me (revoke on this device only): Baileys exposes it as a chat modification, not a
    // sendMessage. The stored message timestamp (epoch seconds) is part of the payload.
    await this.confirmed(
      this.sock(socket).chatModify(
        {
          deleteForMe: {
            deleteMedia: true,
            key: target.key,
            timestamp: this.host.toUnixSeconds(target.messageTimestamp),
          },
        },
        // Indexed by the chat the message is stored in: for a lid-keyed chat that is its lid, which the
        // @c.us id the listing publishes does not fold to.
        this.host.toEngineJid(chatJid),
      ),
      'the delete-for-me',
    );
    this.host.recordMessageEdit(previewJid, messageId, '', 'revoked');
  }

  /**
   * Whether the account is an admin of this chat: false for anything that is not a group, and
   * undefined when no participant row can be identified as the account.
   */
  private async selfIsGroupAdmin(jid: string | null | undefined, socket?: WASocket): Promise<boolean | undefined> {
    if (!jid?.endsWith('@g.us')) return false;
    const metadata = await withQueryDeadline(
      this.sock(socket).groupMetadata(jid),
      this.queryBudgetMs,
      'WhatsApp did not answer the group metadata query in time',
    );
    if (socket) this.sock(socket);
    const self = findSelfParticipant(metadata, this.host.normalizedSelfJid(), id => this.host.toNeutralJid(id));
    return self === undefined ? undefined : self.admin === 'admin' || self.admin === 'superadmin';
  }

  async editMessage(chatId: string, messageId: string, body: string, mentions?: string[]): Promise<MessageResult> {
    this.host.ensureReady();
    const socket = this.sock();
    const target = await this.requireStored(messageId);
    // The chat check comes first so a message from another chat answers not-found whichever side
    // sent it; checking fromMe first would tell an inbound message there from an own one.
    await this.assertStoredInChat(target, chatId, messageId, socket);
    // Only the account's own messages are editable: WhatsApp refuses the edit of an inbound message
    // but the send would still resolve, dressing the refusal up as success (and the service layer
    // would then "update" the stored body). Refuse first — mirrors the wwjs null-edit guard.
    if (target.key.fromMe !== true) {
      throw new EngineRefusedError(
        `the edit of message ${messageId} was rejected — only the account's own messages can be edited`,
      );
    }
    // An edit keeps the original message id, so it is neither re-persisted nor echoed as a new send.
    // The destination is resolved like any other send: a lid-migrated contact rejects PN-addressed
    // sends with ack error 463 (see toDeliverableJid).
    const jid = await this.toDeliverableJid(chatId, socket);
    // Same guard as sendContent: an edit carries text, so without it the library would fetch
    // every URL in the new body through its own vulnerable generator.
    // Tags are applied to the inner message's contextInfo BEFORE the library wraps it in the
    // protocolMessage edit envelope, so an edit can re-tag participants. An edit REPLACES the
    // content, so omitting mentions drops whatever tags the original carried.
    const editContent = { text: body, ...this.withMentions(mentions), edit: target.key };
    const b = await this.host.loadLib();
    await this.send(jid, this.previewSafe(editContent), this.previewSafeOptions(editContent), socket);
    // Update the preview and raw copy immediately, ahead of the buffered echo.
    this.host.recordMessageEdit(target.key.remoteJid ?? chatId, messageId, body);
    // A later quote must carry the updated text even before the edit's echo arrives.
    await this.changeStored(messageId, stored => {
      const content = b.normalizeMessageContent(stored.message ?? undefined);
      return content && setBaileysText(content, body) ? stored : null;
    });
    // Both fields describe the EDITED MESSAGE, not the protocol envelope that carried the edit.
    // That envelope has an id and a send time of its own; answering with either would name something
    // no route can address and no stored row is keyed by, and would disagree with the
    // whatsapp-web.js engine, which re-reads the message and reports the original of both. An edit
    // does not move a message in the chat, so its timestamp is still the one it was sent at.
    return { id: messageId, timestamp: this.host.toUnixSeconds(target.messageTimestamp) };
  }

  /**
   * Build the `{ mentions }` slice of a Baileys message content, de-normalizing neutral `@c.us` WIDs to
   * the engine dialect. Returns an empty object when none are given so the content is byte-identical to
   * the pre-#530 send (no stray `mentions` key). The text must still contain the `@<number>` token for
   * WhatsApp to render the tag — that is the caller's responsibility.
   */
  private withMentions(mentions?: string[]): { mentions?: string[] } {
    return mentions?.length ? { mentions: toEngineParticipants(mentions, jid => this.host.toEngineJid(jid)) } : {};
  }

  /**
   * Resolve a 1:1 phone-dialect chat id (`@c.us` / `@s.whatsapp.net`) to the contact's `@lid` when the
   * mapping is known. WhatsApp rejects PN-addressed 1:1 sends to LID-migrated accounts with ack error
   * 463 ("missing tctoken" — the privacy token is stored and honored under the LID), while the very
   * same send addressed to the LID delivers (verified live). Unmapped phone ids still need the
   * canonical Baileys domain; the library does not rewrite a neutral @c.us destination.
   */
  private async toDeliverableJid(chatId: string, expected?: WASocket): Promise<string> {
    if (expected) this.sock(expected);
    const { kind, userPart: user } = parseWaId(chatId);
    if (kind === 'lid') return `${user}@lid`;
    if (kind !== 'user') return chatId;
    const pn = this.host.toEngineJid(chatId);
    const sock = this.sock();
    try {
      const lid = await withQueryDeadline(
        Promise.resolve(sock.signalRepository?.lidMapping?.getLIDForPN(pn)),
        this.queryBudgetMs,
        'WhatsApp did not answer the recipient LID lookup in time',
      );
      if (this.host.getSocketOrNull() !== sock) throw new EngineNotReadyError();
      // Record what the socket just told us. This resolution is the one place a cold contact's lid
      // becomes known before any message arrives, and without writing it back the session store
      // still believes the two ids are unrelated — which makes an ownership check comparing the
      // stored key's lid against a phone-dialect chatId reject a message that IS in that chat.
      if (lid) this.host.recordLidMapping(`${userPart(lid)}@lid`, pn, false);
      return lid ? `${userPart(lid)}@lid` : pn;
    } catch (error) {
      if (this.host.getSocketOrNull() !== sock || error instanceof EngineNotReadyError) throw new EngineNotReadyError();
      if (error instanceof EngineTransportError) throw new EngineNotSentError(error.message);
      return pn; // LID resolution is best-effort; the phone destination must still be canonical.
    }
  }

  /**
   * Fold the chat's known disappearing-messages timer into Baileys' send options so outbound messages
   * honor the chat's ephemeral setting (#473). Returns `options` unchanged when no positive timer is
   * cached: omitting `ephemeralExpiration` reproduces today's behavior (Baileys' send guard is truthy),
   * so an unknown / boot-window / stale-empty cache never forces a message to disappear. Returning
   * `undefined` keeps the send a 2-arg call, identical to before. React/delete/status do not route
   * through here, so they are excluded by construction (reactions are NOT excluded by Baileys' guard).
   */
  private withEphemeral(
    chatId: string,
    options?: MiscMessageGenerationOptions,
  ): MiscMessageGenerationOptions | undefined {
    const ephemeralExpiration = this.host.getEphemeralExpiration(chatId);
    if (ephemeralExpiration === undefined) {
      return options;
    }
    return { ...options, ephemeralExpiration };
  }

  /** Send a Baileys content object and shape the result like the other sends. */
  /**
   * Keep the library's own preview generator unreachable, and keep it from firing at all.
   *
   * `generateWAMessageContent` calls the generator whenever the content carries `text` and no
   * explicit `linkPreview` (Utils/messages.js), and the default generator delegates to
   * `link-preview-js`, which carries an unfixed SSRF advisory. sendTextMessage guards both halves
   * itself; every OTHER text-bearing send goes through here, and used to guard neither, so a reply
   * or an edit containing a URL made the gateway fetch it through the vulnerable path.
   *
   * `linkPreview: null` is Baileys' explicit "no preview", which matches the documented engine
   * default. A caller that set one already keeps it.
   */
  private previewSafe(content: AnyMessageContent): AnyMessageContent {
    if (!('text' in content) || 'linkPreview' in content) return content;
    return { ...content, linkPreview: null };
  }

  /**
   * Options carrying the vetted generator, so the library's own is never selected. Added only for
   * text-bearing content: media sends never reach the generator, and leaving their options untouched
   * keeps the two-argument sendMessage call they already make.
   */
  private previewSafeOptions(content: AnyMessageContent, options?: MiscMessageGenerationOptions) {
    if (!('text' in content)) return options;
    return {
      ...(options ?? {}),
      getUrlInfo: (text: string) => generateSafeLinkPreview(text, { sessionProxyUrl: this.host.sessionProxyUrl() }),
    };
  }

  private async sendContent(
    chatId: string,
    content: AnyMessageContent,
    options?: MiscMessageGenerationOptions,
    expected?: WASocket,
  ): Promise<MessageResult> {
    if (expected) this.sock(expected);
    const b = await this.host.loadLib();
    if (expected) this.sock(expected);
    const jid = await this.toDeliverableJid(chatId, expected);
    const safe = this.previewSafe(content);
    const merged = this.previewSafeOptions(safe, this.withEphemeral(jid, options));
    const sent = await this.send(jid, safe, merged, expected);
    if (sent) {
      void this.host.putStoredMessage(sent)?.catch(err =>
        this.host.logger.warn('Failed to persist sent message to store', {
          error: err instanceof Error ? err.message : String(err),
        }),
      );
      // Preview metadata must not turn a completed send into a retryable failure.
      let type: MessageType | undefined;
      try {
        if (sent.message) {
          const normalized = b.normalizeMessageContent(sent.message) ?? sent.message;
          type = mapBaileysMessageType(
            b.getContentType(normalized),
            normalized.audioMessage?.ptt === true,
            isBaileysCatalogShare(normalized),
          );
        }
      } catch (error) {
        this.host.logger.warn('Failed to classify sent message preview', { error: String(error) });
      }
      this.host.recordMessage(sent, type);
      // wwjs fires `message_create` for its own API sends, which SessionService turns into `message.sent`.
      // Baileys' own socket-sends echo back only as a `type:'append'` upsert, which handleMessagesUpsert
      // skips by the id send() recorded, so that event never fired for API sends. Emit the outbound
      // "created" callback here for parity: best-effort,
      // and off the response path. No media re-download: the API caller already holds the
      // payload and the REST send path persists it (wwjs, by contrast, does download it on its echo).
      void this.emitOwnSendEcho(sent);
    }
    return { id: sent?.key?.id ?? '', timestamp: this.host.toUnixSeconds(sent?.messageTimestamp) };
  }

  /**
   * Every send goes through here. Content message ids are recorded before the library echoes
   * them back. Baileys re-emits each own send through `messages.upsert` tagged `append`, the
   * same tag WhatsApp uses to replay what the account typed on its phone while the gateway was
   * down, and the id is the only thing that tells the two apart (see handleMessagesUpsert). The
   * record is synchronous on the send's own continuation, ahead of the library's buffered echo.
   *
   * A send that fails after a stop or logout has torn its socket down is not ready (409), the same as
   * one interrupted before it reached the socket; a failure on a socket still in place propagates.
   */
  private async send(
    jid: string,
    content: Parameters<WASocket['sendMessage']>[1],
    options?: Parameters<WASocket['sendMessage']>[2],
    expected?: WASocket,
  ): Promise<WAMessage | undefined> {
    const sock = this.sock(expected);
    if (parseWaId(jid).kind === 'user') {
      let numberId: string | null;
      try {
        numberId = await this.getNumberId(jid);
      } catch (error) {
        if (this.host.getSocketOrNull() !== sock) throw new EngineNotReadyError();
        throw new EngineNotSentError(`WhatsApp could not check the recipient before send: ${String(error)}`);
      }
      if (this.host.getSocketOrNull() !== sock) throw new EngineNotReadyError();
      if (!numberId) throw new BadRequestException(`WhatsApp reports recipient ${jid} is not registered`);
      const canonical = this.host.toEngineJid(numberId);
      if (canonical !== jid) jid = await this.toDeliverableJid(numberId);
    }
    if (this.host.getSocketOrNull() !== sock) throw new EngineNotReadyError();
    let sent: WAMessage | undefined;
    try {
      sent = options ? await sock.sendMessage(jid, content, options) : await sock.sendMessage(jid, content);
    } catch (error) {
      if (this.host.getSocketOrNull() !== sock) throw new EngineNotReadyError();
      throw mapSendRefusal(error);
    }
    // Mutations are announced by their library echo; no local callback replaces it.
    if (!('react' in content || 'delete' in content || 'edit' in content)) this.host.rememberOwnSend(sent?.key?.id);
    return sent;
  }

  /**
   * Emit the engine-neutral "message created" callback for a message this session just sent via the API,
   * so downstream `message.sent` webhook/WS/hook delivery matches the whatsapp-web.js engine. Best-effort:
   * a mapping failure must never fail the send that already succeeded.
   */
  private async emitOwnSendEcho(sent: WAMessage): Promise<void> {
    const onMessageCreate = this.host.getOnMessageCreate();
    if (!onMessageCreate) return;
    try {
      const b = await this.host.loadLib();
      if (!sent.message || !sent.key?.remoteJid) return;
      const normalizedRoot = b.normalizeMessageContent(sent.message) ?? sent.message;
      const contentType = b.getContentType(normalizedRoot);
      // protocol / reaction / empty own messages carry no neutral "sent" content.
      if (!contentType || contentType === 'protocolMessage' || contentType === 'reactionMessage') return;
      const neutral = await this.host.mapMessage(sent, contentType, { skipMediaDownload: true });
      onMessageCreate(neutral);
    } catch (err) {
      this.host.logger.warn('Failed to emit own-send echo', {
        error: err instanceof Error ? err.message : String(err),
      });
    }
  }

  /**
   * Turn an optional quoted-message id into Baileys' `quoted` send option.
   *
   * Baileys quotes by full stored message, never by id, so an id has to be resolved first — and an
   * id we cannot resolve is a hard failure rather than a silent unquoted send: the caller asked for
   * a reply, and a plain message delivered under that name is the wrong result reported as success.
   */
  private async quoteOption(quotedMessageId?: string): Promise<MiscMessageGenerationOptions | undefined> {
    if (!quotedMessageId) return undefined;
    return { quoted: await this.requireStored(quotedMessageId) };
  }

  /**
   * Resolve a previously-seen message from the store, or throw a clear not-found error.
   *
   * A message deleted for everyone is kept with its content removed, and is not found here unless
   * `allowDeleted`: quoting it would hand WhatsApp the deleted content again (Baileys copies the
   * quoted message into the reply's contextInfo), and there is nothing left to forward, react to or
   * edit. A message the session knows was deleted is treated the same while its stored copy still
   * holds the content, as it can when the delete overtook the original's own store write. An edit
   * that overtook it the same way is applied to a copy, so a quote or forward carries the edited text.
   */
  private async requireStored(messageId: string, allowDeleted = false): Promise<WAMessage> {
    const found = await this.host.getStoredMessage(messageId);
    const deleted = !found?.message || this.host.wasDeletedForEveryone(messageId);
    if (!found?.key || (deleted && !allowDeleted)) {
      throw new MessageNotFoundError(messageId);
    }
    const edited = deleted ? undefined : this.host.pendingEditOf(messageId, found.key);
    if (edited === undefined) return found;
    const b = await this.host.loadLib();
    const copy = JSON.parse(JSON.stringify(found, b.BufferJSON.replacer), b.BufferJSON.reviver) as WAMessage;
    const content = b.normalizeMessageContent(copy.message ?? undefined);
    if (content) setBaileysText(content, edited);
    return copy;
  }

  /** Apply a change this session just made to the stored copy. Best-effort: the change already went out. */
  private async changeStored(messageId: string, change: (stored: WAMessage) => WAMessage | null): Promise<void> {
    try {
      await this.host.updateStoredMessage(messageId, change);
    } catch (err) {
      this.host.logger.warn('Failed to apply an edit or delete to the message store', {
        msgId: messageId,
        error: err instanceof Error ? err.message : String(err),
      });
    }
  }

  /**
   * The stored key must belong to the requested chat — acting with another chat's key is a
   * not-found here, not a cross-chat write (a pin sent into chat A referencing chat B's message, or
   * a star indexed under the wrong conversation, would report success). Both sides are neutralized
   * so @c.us/@s.whatsapp.net (and a known lid<->pn twin) compare equal, and a received broadcast-list
   * message is found under the sender chat it is reported in.
   */
  private async assertStoredInChat(
    target: WAMessage,
    chatId: string,
    messageId: string,
    socket: WASocket,
  ): Promise<void> {
    this.sock(socket);
    const persisted = await storedKeyInChatPersisted(
      target.key,
      chatId,
      this.host.findPersistedLidPhone?.bind(this.host),
    );
    this.sock(socket);
    if (persisted) return;
    const requested = parseWaId(chatId);
    const stored = parseWaId(
      baileysChatJid(target.key.remoteJid ?? '', target.key.participant, target.key.fromMe === true),
    );
    if ((requested.kind === 'user' && stored.kind === 'lid') || (requested.kind === 'lid' && stored.kind === 'user')) {
      const phone = requested.kind === 'user' ? requested.userPart : stored.userPart;
      const lid = requested.kind === 'lid' ? requested.userPart : stored.userPart;
      if (typeof socket.executeUSyncQuery === 'function') {
        const library = await this.host.loadLib();
        if (this.host.getSocketOrNull() !== socket) throw new EngineNotReadyError();
        const confirmed = await queryLidPhone(socket, library, phone, lid, this.queryBudgetMs);
        if (this.host.getSocketOrNull() !== socket) throw new EngineNotReadyError();
        if (confirmed) {
          this.host.recordLidMapping(`${lid}@lid`, `${phone}@s.whatsapp.net`);
          return;
        }
      }
    }
    throw new MessageNotFoundError(messageId, chatId);
  }

  async starMessage(chatId: string, messageId: string, star: boolean): Promise<void> {
    this.host.ensureReady();
    const socket = this.sock();
    const target = await this.requireStored(messageId);
    await this.assertStoredInChat(target, chatId, messageId, socket);
    // fromMe is load-bearing: the same message id addresses a different message depending on
    // direction, so omitting it would star the wrong side of the conversation.
    // chatModify keys the star app-state index by the raw jid (no jidNormalizedUser, unlike the send
    // path), so it takes the chat the message is stored in, folded to the engine form: a neutral @c.us,
    // or the phone jid of a chat keyed by the contact's lid, would index a phantom chat and the star
    // would silently apply to nothing.
    await this.confirmed(
      this.sock(socket).chatModify(
        { star: { messages: [{ id: target.key.id!, fromMe: target.key.fromMe ?? false }], star } },
        this.host.toEngineJid(target.key.remoteJid ?? chatId),
      ),
      'the star change',
    );
  }

  /**
   * Pin/unpin a message IN THE CHAT. Deliberately not `chatModify({pin})` — that pins the chat
   * itself in the chat list, a different feature that happens to share the word.
   */
  async pinMessage(chatId: string, messageId: string, durationSeconds: number): Promise<void> {
    this.host.ensureReady();
    const socket = this.sock();
    const target = await this.requireStored(messageId);
    await this.assertStoredInChat(target, chatId, messageId, socket);
    // Read the enum through the LAZY loader rather than a static import. @whiskeysockets/baileys is
    // pure ESM and every other site in this codebase defers it to first connect; a module-scope
    // require would drag ~590 modules into boot even for whatsapp-web.js-only processes.
    const { proto } = await this.host.loadLib();
    await this.send(
      await this.toDeliverableJid(chatId, socket),
      {
        pin: target.key,
        type: proto.PinInChat.Type.PIN_FOR_ALL,
        // WhatsApp recognises only these three windows; the DTO rejects anything else before we
        // get here, so the cast documents the contract rather than widening it.
        time: durationSeconds as 86400 | 604800 | 2592000,
      },
      undefined,
      socket,
    );
  }

  async unpinMessage(chatId: string, messageId: string): Promise<void> {
    this.host.ensureReady();
    const socket = this.sock();
    const target = await this.requireStored(messageId);
    await this.assertStoredInChat(target, chatId, messageId, socket);
    const { proto } = await this.host.loadLib();
    // `time` is meaningless for an unpin and is omitted rather than sent as a dummy value.
    await this.send(
      await this.toDeliverableJid(chatId, socket),
      {
        pin: target.key,
        type: proto.PinInChat.Type.UNPIN_FOR_ALL,
      },
      undefined,
      socket,
    );
  }
}