Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

36.5 KB
Raw Blame
import type * as BaileysLib from '@whiskeysockets/baileys';
import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
import { queryLidPhone } from './baileys-identity-query';
import type { WAMessage, WAMessageKey, WASocket } from '@whiskeysockets/baileys';
import {
  ChatSummary,
  Contact,
  MediaInput,
  type StoredChatMessage,
  type StoredChatMessageLookup,
} from '../interfaces/whatsapp-engine.interface';
import { assertReadableImage, resolveMediaBuffer } from './baileys-messaging';
import { type createLogger } from '../../common/services/logger.service';
import { BAILEYS_QUERY_BUDGET_MS, confirmedWrite, withQueryDeadline } from './baileys-query-deadline';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { RecipientUnreachableError } from '../../common/errors/recipient-unreachable.error';
import { LidNotMappedError } from '../../common/errors/lid-not-mapped.error';
import { chatKind, parseWaId, toNeutralJid, userPart } from '../identity/wa-id';
import { storedKeyInChat, storedKeyInChatPersisted } from './baileys-message-mapper';
import { refusedStatusCode } from './baileys-groups';

/**
 * Contacts/profile/chats-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 BaileysContactsHost {
  /** 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;
  loadLib?(): Promise<typeof BaileysLib>;
  readonly logger: ReturnType<typeof createLogger>;
  normalizedSelfJid(): string;
  listContacts(): Contact[];
  findContact(contactId: string): Contact | null;
  resolvePhone(contactId: string): string | null;
  /** The phone the persisted lid->phone table holds for a lid, or null; read when the caches miss. */
  findPersistedLidPhone(lid: string): Promise<string | null>;
  /** Learn a lid->phone pair (written through to the persisted table). */
  recordLidMapping(lid: string, pn: string, isReported?: boolean): void;
  listChats(): ChatSummary[];
  /**
   * The chat's last known message (the handle chatModify needs), or null when none.
   * `jid` is the id the chat itself is keyed under, which for a lid-migrated contact is its lid
   * whatever id was passed.
   */
  lastMessage(chatId: string): { key: WAMessageKey; timestamp: number; jid: string } | null;
  /** The newest message the chat received, the one a read receipt can acknowledge, or null when none. */
  lastInboundMessage(chatId: string): { key: WAMessageKey; timestamp: number } | null;
  /** The `<lid>@lid` known for a 1:1 chat or a person under any spelling of it, or null (always for a group). */
  lidOf(jid: string): string | null;
  /** Every spelling of one chat the session can connect: the id, its engine form, and its lid or phone twin. */
  chatTwins(jid: string): string[];
  /**
   * When WhatsApp deleted the chat (epoch ms), under any of its spellings, or null when it did not or a
   * message has re-created it since.
   */
  chatDeletedAt(chatId: string): number | null;
  /**
   * Stored copies of the named messages, in whatever order the store returns them. Ids the store
   * has never seen are absent, so neither the length nor the order tracks the input. `undefined`
   * when the session was built without a message store.
   */
  getStoredMessages(messageIds: string[]): Promise<WAMessage[]> | undefined;
  /** Fold a neutral @c.us id to the engine @s.whatsapp.net form used as the app-state index key. */
  toEngineJid(jid: string): string;
  /** The id the chat is keyed under (its lid for a lid-migrated contact), the app-state index key. */
  chatJid(chatId: string): string;
  /** Fold an engine jid back to the neutral dialect before it crosses the engine boundary. */
  toNeutralJid(jid: string): string;
}

export class BaileysContacts {
  constructor(
    private readonly host: BaileysContactsHost,
    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 getProfilePicture(contactId: string): Promise<string | null> {
    this.host.ensureReady();
    try {
      // The library also accepts a timeoutMs third argument, but passing it only converts the
      // stall into a throw — which this catch would swallow into the same null. The deadline has
      // to be ours, and the catch has to let it past.
      const url = await withQueryDeadline(
        this.sock().profilePictureUrl(contactId, 'image'),
        this.queryBudgetMs,
        'WhatsApp did not answer the profile picture lookup in time',
      );
      return url ?? null;
    } catch (err) {
      // A no-picture verdict arrives as a thrown error, so this catch must keep swallowing — but a
      // query that never came back is not a verdict about the picture.
      //
      // NOTE the whatsapp-web.js adapter does the OPPOSITE on this same interface method, and
      // correctly: there the no-picture verdict is delivered as `undefined`, so every throw is a
      // failure and none of them may become null. Same neutral method, opposite error conventions
      // underneath — do not harmonise the two into a shared helper.
      if (err instanceof EngineTransportError) {
        throw err;
      }
      // Only WhatsApp's own error answer (a numeric code: 404 item-not-found, 401 not-authorized) is
      // that verdict. A socket that closed mid-lookup carries none and must not read as "no picture".
      const code = refusedStatusCode(err);
      if (code === undefined) {
        throw new EngineTransportError('WhatsApp did not answer the profile picture lookup');
      }
      // A rate limit, server timeout (408/429) or server error (5xx) is not a verdict about the picture either.
      if (code === 408 || code === 429 || code >= 500) {
        throw new EngineTransportError(`WhatsApp could not answer the profile picture lookup (code ${code})`);
      }
      this.host.logger.debug('profilePictureUrl failed; no picture or hidden', {
        contactId,
        error: err instanceof Error ? err.message : String(err),
      });
      return null; // no picture set, or hidden by privacy
    }
  }

  async upsertContact(contactId: string, firstName: string, lastName = ''): Promise<void> {
    this.host.ensureReady();
    const fullName = [firstName, lastName].filter(Boolean).join(' ');
    // Baileys addresses the entry by JID, unlike whatsapp-web.js which wants a bare phone number.
    // saveOnPrimaryAddressbook stays false to match the wwjs default (syncToAddressbook=false):
    // writing through to the device addressbook is a heavier action than saving the contact.
    // Fold the neutral @c.us the API speaks to the engine @s.whatsapp.net: addOrEditContact ->
    // chatModify keys the addressbook app-state patch by the raw jid (no jidNormalizedUser, unlike
    // the send path), so a raw @c.us index would land under a key WhatsApp never reads and the
    // write would silently target nothing while the endpoint reports success.
    await this.confirmed(
      this.sock().addOrEditContact(this.host.toEngineJid(contactId), {
        firstName,
        fullName,
        saveOnPrimaryAddressbook: false,
      }),
      'the contact save',
    );
  }

  async deleteContact(contactId: string): Promise<void> {
    this.host.ensureReady();
    // Same app-state key fold as upsertContact — a raw @c.us removal targets a phantom entry.
    await this.confirmed(this.sock().removeContact(this.host.toEngineJid(contactId)), 'the contact removal');
  }

  /**
   * `updateBlockStatus` maps the id between the phone-number and privacy-id dialects before it sends
   * anything, and refuses one it cannot map with `Boom(..., { statusCode: 400 })`: no phone number
   * for a lid, no lid for a phone number, or an id that is neither. Boom is not an HttpException, so
   * those reached the caller as an opaque `500 Internal server error` even though the request was
   * well-formed and the id is a shape this API accepts.
   *
   * Only a 400 is folded in. A dropped connection carries `DisconnectReason.connectionClosed` and the
   * write deadline throws `EngineTransportError`, and reporting either as a bad contact id would send
   * the caller after the wrong problem. whatsapp-web.js already answers `RecipientUnreachableError`
   * (400) for the same cause on the send path, so this is the parity mapping, not a new contract.
   */
  private async mapUnresolvableId<T>(contactId: string, op: () => Promise<T>): Promise<T> {
    try {
      return await op();
    } catch (error) {
      const status = (error as { output?: { statusCode?: unknown } } | null)?.output?.statusCode;
      if (status === 400) throw new RecipientUnreachableError(contactId);
      throw error;
    }
  }

  async blockContact(contactId: string): Promise<void> {
    this.host.ensureReady();
    await this.mapUnresolvableId(contactId, () =>
      this.confirmed(this.sock().updateBlockStatus(contactId, 'block'), 'the block'),
    );
    this.invalidateBlocklist();
  }

  async unblockContact(contactId: string): Promise<void> {
    this.host.ensureReady();
    await this.mapUnresolvableId(contactId, () =>
      this.confirmed(this.sock().updateBlockStatus(contactId, 'unblock'), 'the unblock'),
    );
    this.invalidateBlocklist();
  }

  /**
   * The read half of block/unblockContact. Bounded by our own clock: Baileys' `query()` swallows
   * its timeout, and an unanswered blocklist query would otherwise surface as an EMPTY blocklist —
   * a claim about the account sold in place of a transport failure. Wire items without a jid attr
   * are dropped rather than reported as "undefined". A contact held under both its LID and its phone
   * is two wire items that read as one id, which is listed once.
   */
  async getBlockedContacts(budgetMs: number = this.queryBudgetMs): Promise<string[]> {
    this.host.ensureReady();
    const jids = await withQueryDeadline(
      this.sock().fetchBlocklist(),
      budgetMs,
      'WhatsApp did not answer the blocklist query in time',
    );
    const ids = (jids ?? []).filter((jid): jid is string => Boolean(jid)).map(jid => this.host.toNeutralJid(jid));
    return [...new Set(ids)];
  }

  async setProfileName(name: string): Promise<void> {
    this.host.ensureReady();
    await this.confirmed(this.sock().updateProfileName(name), 'the profile name change');
  }

  async setProfileStatus(status: string): Promise<void> {
    this.host.ensureReady();
    await this.confirmed(this.sock().updateProfileStatus(status), 'the profile status change');
  }

  async setProfilePicture(media: MediaInput): Promise<void> {
    this.host.ensureReady();
    const selfJid = this.host.normalizedSelfJid();
    if (!selfJid) {
      throw new Error('cannot set the profile picture: the own JID is not known yet');
    }
    // updateProfilePicture takes a WAMediaUpload; resolveMediaBuffer covers Buffer | base64 | URL,
    // the same conversion the media sends use.
    const { data } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());
    await assertReadableImage(data);
    await this.confirmed(this.sock().updateProfilePicture(selfJid, data), 'the profile picture change');
  }

  async deleteProfilePicture(): Promise<void> {
    this.host.ensureReady();
    const selfJid = this.host.normalizedSelfJid();
    if (!selfJid) {
      // Same guard as setProfilePicture: an empty jid would send the removal at nothing while the
      // endpoint reported success.
      throw new Error('cannot delete the profile picture: the own JID is not known yet');
    }
    // The same socket call `deleteGroupPicture` already uses, addressed at the account instead of a
    // group. Baileys resolves void either way, so an acknowledged write is the only signal there is.
    await this.confirmed(this.sock().removeProfilePicture(selfJid), 'the profile picture removal');
  }

  async getContacts(): Promise<Contact[]> {
    this.host.ensureReady();
    return this.withBlockedState(this.host.listContacts());
  }

  async getContactById(contactId: string): Promise<Contact | null> {
    this.host.ensureReady();
    const contact = this.host.findContact(contactId);
    if (!contact) return null;
    if (
      !storedKeyInChat({ remoteJid: contact.id }, contactId, toNeutralJid) &&
      !(await this.matchesChat({ remoteJid: contact.id }, contactId))
    )
      return null;
    return (await this.withBlockedState([contact]))[0];
  }

  /**
   * Stamp the real blocklist state onto contacts the store mapped.
   *
   * The store has no socket, so its mapper defaulted `isBlocked` to a literal `false` for everyone —
   * a claim about the account, not a reading of it, while THIS session's own blocklist query returns
   * the real ids. Automation that skips blocked contacts before sending therefore messaged people the
   * account had explicitly blocked.
   *
   * A failed blocklist query degrades rather than failing the read: contacts are still useful, and
   * getBlockedContacts deliberately throws instead of returning an empty list precisely so a
   * transport failure is not sold as "nobody is blocked". The default is kept and the gap is warned
   * about, so the degradation is visible instead of silent.
   */
  private async withBlockedState(contacts: Contact[]): Promise<Contact[]> {
    if (contacts.length === 0) return contacts;
    const blocked = await this.blockedIds();
    if (!blocked) return contacts;
    return contacts.map(contact => ({ ...contact, isBlocked: blocked.has(contact.id) }));
  }

  /** Memoised blocklist. See {@link blockedIds} for why this is not queried per read. */
  private blocklistMemo?: { at: number; ids: Set<string> | null };

  /** The open query, shared by every caller that arrives while it is in flight. */
  private blocklistInFlight?: Promise<Set<string> | null>;

  /** Incremented on every block/unblock so a query started earlier cannot write a stale memo. */
  private blocklistGeneration = 0;

  /**
   * How long one blocklist answer is reused. Short enough that a block made elsewhere shows up
   * quickly, long enough that a burst of reads costs one query.
   */
  private static readonly BLOCKLIST_MEMO_MS = 5_000;

  /**
   * Deadline for the blocklist query when it is ENRICHING a contact read, deliberately far below the
   * engine-wide budget `/contacts/blocked` uses. There the blocklist is the answer and waiting is
   * right; here it is one field on rows the caller already has, and a contact read used to be an
   * in-memory lookup. Past this the read returns with isBlocked at its default and a warning —
   * the same degradation a failed query already produces.
   */
  private static readonly BLOCKLIST_ENRICHMENT_BUDGET_MS = 5_000;

  /**
   * The account's blocked ids, or null when the query failed.
   *
   * Memoised because a single contact read is not the only caller: a session seeding its status
   * history resolves each unique poster through getContactById purely to read a NAME
   * (session-engine-leaf-events), so querying per read turned one connect into N network round-trips,
   * each with its own deadline. The failure is memoised too — a broken blocklist must not cost N
   * queries either — and block/unblock invalidate it so a just-changed state is not read stale.
   */
  private async blockedIds(): Promise<Set<string> | null> {
    if (this.blocklistMemo && Date.now() - this.blocklistMemo.at < BaileysContacts.BLOCKLIST_MEMO_MS) {
      return this.blocklistMemo.ids;
    }
    // Share one query with every caller that arrives while it is open, so a burst costs one round
    // trip rather than one per caller. Note which callers this actually helps: the status seed
    // resolves posters SEQUENTIALLY (`await resolvePoster(...)` per item) and memoises per jid, so it
    // never has two lookups in flight — the memo above is what bounds that loop. This bounds
    // genuinely concurrent readers instead, such as two contact requests arriving together.
    this.blocklistInFlight ??= this.queryBlockedIds();
    return this.blocklistInFlight;
  }

  private async queryBlockedIds(): Promise<Set<string> | null> {
    // Read before the query so an invalidation that lands DURING it can be detected: block/unblock
    // clears the memo, and a pre-change answer arriving afterwards would re-memoise the state the
    // caller just changed, for the whole window.
    const generation = this.blocklistGeneration;
    let ids: Set<string> | null;
    try {
      ids = new Set(await this.getBlockedContacts(BaileysContacts.BLOCKLIST_ENRICHMENT_BUDGET_MS));
    } catch (error) {
      this.host.logger.warn('Blocklist unavailable; contact isBlocked left at its default', {
        error: error instanceof Error ? error.message : String(error),
      });
      ids = null;
    } finally {
      // Only if the handle is still this query's. After an invalidation the field belongs to a query
      // started later, and clearing it there would send the next reader into a third query while the
      // second was still open — defeating the sharing exactly inside the window it introduced.
      if (generation === this.blocklistGeneration) {
        this.blocklistInFlight = undefined;
      }
    }
    // Stamped with the time the ANSWER arrived, not the time the query started. Stamping the start
    // wrote an already-expired memo for any query slower than the window — so the memo absorbed
    // only the fast queries and collapsed on exactly the slow ones it was added for.
    if (generation === this.blocklistGeneration) {
      this.blocklistMemo = { at: Date.now(), ids };
    }
    return ids;
  }

  /** Bumped by block/unblock so an in-flight query cannot memoise pre-change state afterwards. */
  private invalidateBlocklist(): void {
    this.blocklistMemo = undefined;
    this.blocklistInFlight = undefined;
    this.blocklistGeneration += 1;
  }

  /**
   * `resolvePhone` reads caches only, so for a lid its null means "not cached", not "no phone": the
   * mapping may have been evicted, or sit past the preload cap after a restart. Answering null there
   * told the sender resolver the lid had no phone, and it stored that null over the real mapping. So a
   * lid miss reads the persisted table, then Baileys' own signal-key mapping, and rejects when neither
   * knows it; a rejection is a transient unknown the resolver neither caches nor persists.
   */
  async resolveContactPhone(contactId: string): Promise<string | null> {
    this.host.ensureReady();
    const cached = this.host.resolvePhone(contactId);
    if (cached || parseWaId(contactId).kind !== 'lid') return cached;
    const persisted = await this.host.findPersistedLidPhone(contactId);
    if (persisted) return persisted;
    const pn = await this.sock()
      .signalRepository?.lidMapping?.getPNForLID(contactId)
      .catch(() => null);
    if (pn) {
      this.host.recordLidMapping(contactId, pn, false);
      return userPart(pn);
    }
    throw new LidNotMappedError(contactId);
  }

  // eslint-disable-next-line @typescript-eslint/require-await
  async getChats(): Promise<ChatSummary[]> {
    this.host.ensureReady();
    return this.host.listChats();
  }

  async sendSeen(
    chatId: string,
    messageIds?: string[],
    authors?: ReadonlyMap<string, string>,
    stored?: StoredChatMessageLookup,
  ): Promise<boolean> {
    this.host.ensureReady();
    const socket = this.sock();
    const keys = await this.receiptKeys(socket, chatId, messageIds, authors, stored);
    if (keys.length === 0) {
      return false; // nothing known to mark read
    }
    // readMessages reaches fetchPrivacySettings, which destructures the query result and throws a
    // raw TypeError on an unanswered one — no Boom, so nothing downstream can classify it. Marking
    // a chat read is idempotent, so bounding it is safe: a repeat costs nothing.
    await this.confirmed(this.sock(socket).readMessages(keys), 'the read receipt');
    return true;
  }

  /**
   * The keys a read receipt should acknowledge: the messages the caller named, or the newest one the
   * chat received when it named none.
   *
   * Baileys acknowledges individual messages, not chats, and the receipt node enumerates ids rather
   * than carrying a read-up-to watermark. Caller-supplied ids are what make that correct: the
   * lastInboundMessage fallback holds only the newest message, so a burst of three inbound messages
   * left the first two permanently unread, and a session that restarted since the message arrived
   * had nothing to acknowledge at all (a silent false under a 200).
   *
   * Named ids are resolved through the message store rather than synthesised, because the receipt
   * needs the whole key. A synthesised key carries no `participant`, so a group receipt names no
   * sender; its hardcoded `fromMe: false` is wrong for an id that belongs to an outbound message;
   * and its jid is whichever dialect the caller happened to send. The stored key has all three
   * right. Ids the store has never seen — history backfill is emitted but not persisted — keep the
   * synthesised key in a 1:1 chat, which is what that case ran on before. A group receipt that names
   * no sender cannot be attributed, so there the key takes `authors` (message id to the stored poster,
   * which the gateway keeps for every group message), and an id with no known author is left out of
   * the receipt rather than sent as one WhatsApp may ignore.
   */
  private async receiptKeys(
    socket: WASocket,
    chatId: string,
    messageIds?: string[],
    authors?: ReadonlyMap<string, string>,
    storedLast?: StoredChatMessageLookup,
  ): Promise<WAMessageKey[]> {
    // null as well as undefined: the REST body rejects an explicit null, but this is the engine
    // boundary and an internal caller reaching it with one used to dereference it below as a 500.
    if (messageIds === undefined || messageIds === null) {
      // The newest RECEIVED message, not the preview: after an API reply the preview is an own key,
      // which Baileys drops from the receipt, so the call would answer true having sent nothing.
      // After a restart memory holds none until the next one arrives; the gateway's stored copy
      // stands in, rebuilt the way a chat write keys it.
      const last = this.sinceDeletion(chatId, this.host.lastInboundMessage(chatId));
      if (last && (await this.matchesChat(last.key, chatId, socket))) return [last.key];
      if (!isEngineChatId(chatId)) return [];
      const row = this.sinceDeletion(chatId, await this.readStored(chatId, storedLast));
      const received = row && !row.fromMe ? this.storedTarget(chatId, row) : null;
      return received && (await this.matchesChat(received.key, chatId, socket)) ? [received.key] : [];
    }
    if (messageIds.length === 0) {
      return []; // an explicit empty list asks for nothing to be acknowledged, not for the newest
    }
    const remoteJid = this.host.toEngineJid(chatId);
    const stored = (await this.host.getStoredMessages(messageIds)) ?? [];
    // A stored key is only usable when it belongs to THIS chat. Without the check, an id from
    // another chat in the same session carried that chat's remoteJid into readMessages, so the
    // receipt landed there while the route answered success for the chat the caller named.
    // The comparison runs in the NEUTRAL dialect rather than the engine one: toEngineJid folds
    // @c.us and @s.whatsapp.net together but returns @lid untouched, and Baileys stores a DM key
    // under the peer's lid once WhatsApp addresses the chat that way. toNeutralJid resolves that
    // lid to its phone user-part through the session's lid mapping, so both spellings of one chat
    // still meet. Anything that still differs falls back to the synthesised key for the ADDRESSED
    // chat, which is exactly what every id ran on before stored keys existed.
    const keyById = new Map<string, WAMessageKey>();
    for (const msg of stored) {
      if (msg.key?.id && msg.key.remoteJid && (await this.matchesChat(msg.key, chatId, socket))) {
        keyById.set(msg.key.id, msg.key);
      }
    }
    const inGroup = chatKind(remoteJid) === 'group';
    return messageIds.flatMap((id): WAMessageKey[] => {
      const key = keyById.get(id);
      if (key) return [key];
      if (!inGroup) return [{ remoteJid, id, fromMe: false }];
      const author = authors?.get(id);
      return author ? [{ remoteJid, id, fromMe: false, participant: this.host.toEngineJid(author) }] : [];
    });
  }

  private async matchesChat(key: WAMessageKey, chatId: string, expected?: WASocket): Promise<boolean> {
    const socket = this.sock(expected);
    const persisted = await storedKeyInChatPersisted(key, chatId, jid => this.host.findPersistedLidPhone(jid));
    this.sock(socket);
    if (persisted) return true;
    const requested = parseWaId(chatId);
    const stored = parseWaId(key.remoteJid ?? '');
    if (!((requested.kind === 'user' && stored.kind === 'lid') || (requested.kind === 'lid' && stored.kind === 'user')))
      return false;
    const phone = requested.kind === 'user' ? requested.userPart : stored.userPart;
    const lid = requested.kind === 'lid' ? requested.userPart : stored.userPart;
    if (typeof socket.executeUSyncQuery !== 'function' || !this.host.loadLib) return false;
    const library = await this.host.loadLib();
    this.sock(socket);
    const confirmed = await queryLidPhone(socket, library, phone, lid, this.queryBudgetMs);
    this.sock(socket);
    if (confirmed) this.host.recordLidMapping(`${lid}@lid`, `${phone}@s.whatsapp.net`);
    return confirmed;
  }

  async confirmedChatJid(chatId: string): Promise<string> {
    const jid = this.host.chatJid(chatId);
    if (!(await this.matchesChat({ remoteJid: jid }, chatId))) throw new RecipientUnreachableError(chatId);
    return jid;
  }

  /**
   * The message a chat write is keyed to, and the jid that indexes the patch, made to agree (#1891).
   *
   * The phone applies a clear or delete only when both name the chat the way it holds it. A message
   * this session holds in memory carries that form itself: the patch is indexed by the jid the
   * message arrived under, its lid on a lid-addressed chat and its phone jid otherwise. Indexing it by
   * the listed phone jid instead named two different chats, which the server accepted and the phone
   * ignored. A stored message carries no addressing, so it is keyed by the chat's lid whenever one is
   * known (the stored row brings the one the engine reported for its phone), else by the phone jid.
   *
   * An own group message carries no `participant` (the phone ignores the range with one); a received
   * one needs its sender, which Baileys requires.
   *
   * The message is the newest one in memory, else (none, or one that yields no usable key) the newest
   * the gateway stored. Either key must belong to the chat ({@link matchesChat}), else it is not used.
   * With neither, `rangeless()` allows a patch without a range: it is indexed by the chat's jid, and
   * only for a chat the session knows (a message in memory or stored, or a chat record or state row
   * the listing holds) whose jid passes the same check. Otherwise the answer is null.
   *
   * Only the message in memory serves an id spelled any other way than the engine keys chats
   * ({@link isEngineChatId}): the stored lookup normalizes the id and finds the chat's rows, but the
   * patch would still be indexed by the misspelled id, which names no chat on the phone.
   *
   * A message, in memory or stored, sent at or before WhatsApp deleted the chat neither keys the write
   * nor shows the session knows the chat (see {@link sinceDeletion}).
   */
  private async chatWriteRange(
    socket: WASocket,
    chatId: string,
    stored: StoredChatMessageLookup | undefined,
    rangeless: () => boolean = () => false,
  ): Promise<ChatWriteRange | null> {
    const last = this.sinceDeletion(chatId, this.host.lastMessage(chatId));
    const inMemory = last ? this.memoryTarget(chatId, last.key, last.timestamp) : null;
    if (inMemory && (await this.matchesChat(inMemory.key, chatId, socket))) return toRange(inMemory);
    if (!isEngineChatId(chatId)) return null;
    const row = this.sinceDeletion(chatId, await this.readStored(chatId, stored));
    const fromStore = row ? this.storedTarget(chatId, row) : null;
    if (fromStore && (await this.matchesChat(fromStore.key, chatId, socket))) return toRange(fromStore);
    if (!rangeless() || !(last || row || this.listedChats(chatId).length)) return null;
    const jid = this.host.chatJid(chatId);
    return (await this.matchesChat({ remoteJid: jid }, chatId, socket)) ? { jid, lastMessages: [] } : null;
  }

  private async readStored(
    chatId: string,
    stored: StoredChatMessageLookup | undefined,
  ): Promise<StoredChatMessage | null> {
    if (!stored) return null;
    try {
      return await stored();
    } catch (err) {
      this.host.logger.warn('Could not read the stored last message of a chat', {
        chatId,
        error: err instanceof Error ? err.message : String(err),
      });
      return null;
    }
  }

  /**
   * The message, unless it was sent at or before WhatsApp deleted the chat. WhatsApp keeps nothing of a
   * deleted chat while the gateway keeps its stored messages: a write keyed to one names a message the
   * phone no longer holds, and Baileys applies its own patch locally all the same, so the deleted chat
   * would be listed again. Such a message does not show the chat exists either.
   */
  private sinceDeletion<T extends { timestamp: number }>(chatId: string, message: T | null): T | null {
    const deletedAt = this.host.chatDeletedAt(chatId);
    return message && (deletedAt === null || message.timestamp * 1000 > deletedAt) ? message : null;
  }

  /** A message held in memory, keyed under the jid it arrived with; null when it cannot be used. */
  private memoryTarget(chatId: string, key: WAMessageKey, timestamp: number): WriteTarget | null {
    if (!key.id || !timestamp) return null;
    const chatJid = this.host.chatJid(chatId);
    const group = parseWaId(chatJid).kind === 'group';
    const fromMe = key.fromMe === true;
    if (group && !fromMe && !key.participant) return null;
    const jid = group ? chatJid : this.host.toEngineJid(key.remoteJid ?? chatJid);
    return target(jid, key.id, fromMe, group && !fromMe ? (key.participant ?? undefined) : undefined, timestamp);
  }

  /** A stored message, keyed by the chat's lid whenever one is known; null when it cannot be used. */
  private storedTarget(chatId: string, row: StoredChatMessage): WriteTarget | null {
    if (!row.id || !row.timestamp) return null;
    const chatJid = this.host.chatJid(chatId);
    const group = parseWaId(chatJid).kind === 'group';
    if (group && !row.fromMe && !row.author) return null;
    const jid = group ? chatJid : (row.lid ?? this.host.lidOf(chatJid) ?? this.host.toEngineJid(chatJid));
    const participant =
      group && !row.fromMe && row.author
        ? (row.authorLid ?? this.host.lidOf(row.author) ?? this.host.toEngineJid(row.author))
        : undefined;
    return target(jid, row.id, row.fromMe, participant, row.timestamp);
  }

  /**
   * The chat as the session lists it (a chat record or a persisted state row) under any spelling of it: a
   * row is keyed by the lid or the phone it was learned under, whichever form the caller writes it with.
   */
  private listedChats(chatId: string): ChatSummary[] {
    const ids = new Set(this.host.chatTwins(chatId).map(jid => this.host.toNeutralJid(jid)));
    return this.host.listChats().filter(chat => ids.has(chat.id));
  }

  /**
   * Without a known message the mark goes out with no range, which the phone applies to a chat in the
   * list. It is reported as not done for an archived chat, which the phone leaves unmarked then, and
   * for a chat the session does not know or whose jid does not check out.
   */
  async markUnread(chatId: string, stored?: StoredChatMessageLookup): Promise<boolean> {
    this.host.ensureReady();
    const socket = this.sock();
    const range = await this.chatWriteRange(
      socket,
      chatId,
      stored,
      () => !this.listedChats(chatId).some(c => c.archived),
    );
    if (!range) return false;
    await this.confirmed(
      this.sock(socket).chatModify({ markRead: false, lastMessages: range.lastMessages }, range.jid),
      'the unread mark',
    );
    return true;
  }

  async clearChatMessages(chatId: string, stored?: StoredChatMessageLookup): Promise<boolean> {
    this.host.ensureReady();
    const socket = this.sock();
    const range = await this.chatWriteRange(socket, chatId, stored);
    if (!range) {
      return false; // the clear removes messages up to the one it is keyed to; never guess one
    }
    await this.confirmed(
      this.sock(socket).chatModify({ clear: true, lastMessages: range.lastMessages }, range.jid),
      'the chat clear',
    );
    return true;
  }

  /**
   * Without a known message the change goes out with no range, which WhatsApp applies as well, but
   * only for a chat the session knows and whose jid checks out. Baileys replays its own patch locally,
   * so archiving an id the account has no chat with would list that chat from then on.
   */
  async archiveChat(chatId: string, archive: boolean, stored?: StoredChatMessageLookup): Promise<boolean> {
    this.host.ensureReady();
    const socket = this.sock();
    const range = await this.chatWriteRange(socket, chatId, stored, () => true);
    if (!range) return false;
    await this.confirmed(
      this.sock(socket).chatModify({ archive, lastMessages: range.lastMessages }, range.jid),
      'the archive change',
    );
    return true;
  }

  async muteChat(chatId: string, muteUntil: number | null): Promise<void> {
    this.host.ensureReady();
    const socket = this.sock();
    // Deliberately no lastMessage lookup: the `mute` member of ChatModification carries no
    // `lastMessages`, unlike archive/clear/delete, so a chat with no known history mutes fine.
    const jid = await this.confirmedChatJid(chatId);
    await this.confirmed(this.sock(socket).chatModify({ mute: muteUntil }, jid), 'the mute change');
  }

  async pinChat(chatId: string, pin: boolean): Promise<boolean> {
    this.host.ensureReady();
    const socket = this.sock();
    // No lastMessage lookup: the `pin` member of ChatModification carries no `lastMessages`, unlike
    // archive/clear/delete, so a chat with no known history pins fine. Always true — Baileys writes
    // the app-state patch and reports nothing back, so it has no equivalent of the whatsapp-web.js
    // three-pin refusal to surface.
    const jid = await this.confirmedChatJid(chatId);
    await this.confirmed(this.sock(socket).chatModify({ pin }, jid), 'the pin change');
    return true;
  }

  async deleteChat(chatId: string, stored?: StoredChatMessageLookup): Promise<boolean> {
    this.host.ensureReady();
    const socket = this.sock();
    const range = await this.chatWriteRange(socket, chatId, stored);
    if (!range) {
      return false; // the delete removes messages up to the one it is keyed to; never guess one
    }
    await this.confirmed(
      this.sock(socket).chatModify({ delete: true, lastMessages: range.lastMessages }, range.jid),
      'the chat delete',
    );
    return true;
  }
}

type WriteTarget = { jid: string; key: WAMessageKey; timestamp: number };
type ChatWriteRange = { jid: string; lastMessages: { key: WAMessageKey; messageTimestamp: number }[] };

function target(
  jid: string,
  id: string,
  fromMe: boolean,
  participant: string | undefined,
  timestamp: number,
): WriteTarget {
  return { jid, key: { remoteJid: jid, fromMe, id, ...(participant ? { participant } : {}) }, timestamp };
}

function toRange(write: WriteTarget): ChatWriteRange {
  return { jid: write.jid, lastMessages: [{ key: write.key, messageTimestamp: write.timestamp }] };
}

/**
 * Whether a chat id is spelled the way the engine keys chats: `<id>@g.us`, `<lid>@lid` or a phone in
 * either user dialect, lowercase, with no device suffix or surrounding space. chatJid folds a phone's
 * two dialects and nothing else, so `[email protected]` or a bare `628111` would index a patch by a jid that
 * names no chat.
 */
function isEngineChatId(chatId: string): boolean {
  const { kind, userPart: id } = parseWaId(chatId);
  const domains =
    kind === 'group' ? ['g.us'] : kind === 'lid' ? ['lid'] : kind === 'user' ? ['c.us', 's.whatsapp.net'] : [];
  return domains.some(domain => chatId === `${id}@${domain}`);
}