Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import type { Chat, Contact as BaileysContact, WAMessage, WAMessageKey } from '@whiskeysockets/baileys';
import { ChatSummary, Contact, MessageType } from '../interfaces/whatsapp-engine.interface';
import { chatKind, parseWaId, toNeutralJid as canonicalizeWaId, userPart } from '../identity/wa-id';
import type { LidMappingStore } from '../identity/lid-mapping-store.service';
import { mergeTwinStates, type ChatStateStore, type ChatStateValue } from './baileys-chat-state-store.service';
import { resolveNonNegativeIntEnv } from '../../config/configuration';
import { baileysChatJid } from './baileys-message-mapper';
interface LastMessage {
key: WAMessageKey;
timestamp: number;
text: string;
type?: MessageType;
/** Where the message stands in the order this session observed them, which settles a tie in `timestamp`. */
order: number;
}
// Default per-map entry cap, matching the other per-session bounds (LID_MAPPING_CACHE_MAX,
// BAILEYS_MESSAGE_STORE_LIMIT, the session lidPhoneCache — all 5000). Every read below has a defined
// miss path, so an eviction only costs a re-resolution/re-read, never data loss.
export const SESSION_STORE_MAP_CAP_DEFAULT = 5000;
/**
* Insertion-ordered Map with an LRU cap, the same discipline as LidMappingStoreService: a read or
* write re-inserts the key at the most-recent end, and a set evicts the least-recently-used entry
* while over `max`. `max = 0` means unbounded.
*
* `pinned` marks entries eviction may never take. It exists for the contacts map, where two
* populations share one structure: the account's own address book, which the operator curated and
* which the API reports, and a much larger stream of peers seen once in a group or a broadcast.
* Without it the second evicts the first.
*
* The cap then governs the UNPINNED population alone, which is the one that grows from peer traffic.
* Counting the whole map instead would make a full address book evict each new peer in the same call
* that inserted it, so peers would stop being cached at all once the saved set reached the cap. The
* pinned side is bounded by the account's own contact list rather than by this number.
*/
class LruMap<K, V> {
private readonly map = new Map<K, V>();
/** Entries the predicate does not protect. The cap is measured against exactly these. */
private unpinned = 0;
constructor(
private readonly max: number,
private readonly pinned?: (value: V) => boolean,
) {}
private isPinned(value: V): boolean {
return this.pinned ? this.pinned(value) : false;
}
/** Remove a key while keeping {@link unpinned} honest. No-op for a key that is not held. */
private drop(key: K): void {
if (!this.map.has(key)) {
return;
}
if (!this.isPinned(this.map.get(key) as V)) {
this.unpinned--;
}
this.map.delete(key);
}
has(key: K): boolean {
return this.map.has(key);
}
delete(key: K): void {
this.drop(key);
}
get(key: K): V | undefined {
if (!this.map.has(key)) {
return undefined;
}
const value = this.map.get(key) as V;
this.map.delete(key);
this.map.set(key, value);
return value;
}
set(key: K, value: V): void {
this.drop(key);
this.map.set(key, value);
if (!this.isPinned(value)) {
this.unpinned++;
}
if (!this.max) {
return;
}
while (this.unpinned > this.max) {
const victim = this.oldestEvictable();
if (victim === undefined) {
break; // unreachable while unpinned > 0, and a safe stop if it ever is not
}
this.drop(victim);
}
}
/**
* The least-recently-used entry an eviction may take, or undefined when every entry is pinned.
* Without a `pinned` predicate this is the map head, as before.
*/
private oldestEvictable(): K | undefined {
if (!this.pinned) {
const oldest = this.map.keys().next().value;
return oldest;
}
for (const [key, value] of this.map) {
if (!this.pinned(value)) {
return key;
}
}
return undefined;
}
/**
* LIVE iterator, not a snapshot. {@link get} re-inserts a hit to keep recency order, so a loop
* whose body reads this map through any path is handed the same entry forever. Copy first
* (`[...map.values()]`) whenever the body can reach back into the map.
*/
values(): IterableIterator<V> {
return this.map.values();
}
/** LIVE iterator with the same caveat as {@link values}. */
entries(): IterableIterator<[K, V]> {
return this.map.entries();
}
}
/** A projected contact with the raw store key it came from, so twins can be folded deterministically. */
interface ContactTwin {
contact: Contact;
rawId: string;
}
/** True for a store key in the phone dialect, i.e. the twin that carries a phone number of its own. */
function isPhoneKeyed(rawId: string): boolean {
return rawId.endsWith('@s.whatsapp.net') || rawId.endsWith('@c.us');
}
/**
* Fold two store entries that project to the same person into one row.
*
* Neither side is more correct by position: the store is LRU-ordered, so iteration order tracks
* traffic, and letting it decide meant `GET /contacts` answered with whichever twin had been quiet
* and dropped a pushname the other had just learned, flipping back later. So a field absent on one
* side is filled from the other, and for a field both carry the phone-dialect twin wins, which is
* the entry {@link BaileysSessionStore.findContact} already answers with for the same id. When
* neither or both are phone-keyed, the lower raw key wins: arbitrary, but stable across calls.
*/
function mergeContactTwins(a: ContactTwin, b: ContactTwin): ContactTwin {
const aWins = isPhoneKeyed(a.rawId) !== isPhoneKeyed(b.rawId) ? isPhoneKeyed(a.rawId) : a.rawId <= b.rawId;
const [primary, secondary] = aWins ? [a, b] : [b, a];
return {
rawId: primary.rawId,
contact: {
id: primary.contact.id,
name: primary.contact.name ?? secondary.contact.name,
pushName: primary.contact.pushName ?? secondary.contact.pushName,
number: primary.contact.number || secondary.contact.number,
isMyContact: primary.contact.isMyContact || secondary.contact.isMyContact,
isBlocked: primary.contact.isBlocked || secondary.contact.isBlocked,
profilePicUrl: primary.contact.profilePicUrl ?? secondary.contact.profilePicUrl,
},
};
}
/**
* Per-session, in-memory snapshot of Baileys contacts + chats, fed from `sock.ev` events and mapped to
* the neutral `Contact`/`ChatSummary` on read. Holds no socket, pure data. Baileys has no fetch-all,
* and `messaging-history.set` arrives only on the first link: once the account has synced, WhatsApp
* skips history sync on every later connect (see BaileysHistory.hydrateNames). A new engine (a process
* restart, a session stop and start, a reconnect the gateway runs itself) therefore starts with no
* chats: the groups hydrateNames re-fetches on every open come back at once, a chat with a persisted
* mute, archive or pin (ChatStateStore) is listed from that row, and any other 1:1 chat comes back with
* its next message, since Baileys emits `chats.update` for every real message. Contacts are rebuilt
* from the address-book snapshot instead.
*
* Every map is LRU-bounded (`BAILEYS_SESSION_STORE_MAX_ENTRIES`, default 5000 per map, 0 = unbounded)
* because contacts/chats/lastMessages/lidToPn all grow from peer-controlled traffic — without a cap a
* chatty account leaks one entry per distinct peer ever seen. On the contacts map that cap governs the
* peers ALONE: a contact carrying a saved name is pinned and never evicted, because it comes from the
* account's own address book rather than from traffic, and that side is bounded by the address book
* instead (see LruMap's `pinned`). Miss paths after an eviction:
* `lidToPn` falls back to the contacts map and then the persisted cross-session lid->phone table (all
* writes are written through), `lastMessage` reads null (callers treat it as "nothing known"),
* `getEphemeralExpiration` falls back to `Chat.ephemeralExpiration` then undefined (never forces a
* timer), and contact/name lookups degrade to the raw user-part. `ephemeralByChat` is keyed under both
* the raw and neutral JID (two entries per chat), so its cap is doubled to cover the same number of
* chats.
*/
export class BaileysSessionStore {
private readonly contacts: LruMap<string, BaileysContact>;
private readonly chats: LruMap<string, Chat>;
private readonly lastMessages: LruMap<string, LastMessage>;
/**
* The newest message each chat RECEIVED, kept apart from the preview because a read receipt can
* only acknowledge a message the other side sent: Baileys drops an own key from the receipt, so
* answering with the preview after an API reply sent nothing while the route reported success.
* An evicted entry reads null, which the receipt path answers as "nothing known".
*/
private readonly lastInbound: LruMap<string, { key: WAMessageKey; timestamp: number; order: number }>;
private messageOrder = 0;
private readonly lidToPn: LruMap<string, string>;
/**
* Per-chat disappearing-messages timer (seconds) learned from inbound messages (#473), the reliable
* source for it: `Chat.ephemeralExpiration` (from `chats.*`/history sync) is empirically absent for a
* long-standing timer after a reconnect (observed live: 0 of 159 cached chats carried it). Keyed by
* both the raw and neutral JID so an outbound send addressed in either dialect (phone `@c.us` /
* `@s.whatsapp.net` or `@lid`) resolves to the same entry. See {@link extractEphemeralDuration} for
* which message field is read.
*/
private readonly ephemeralByChat: LruMap<string, number>;
/**
* @param lidStore optional persisted, cross-session lid->phone table that backs resolution beyond
* this session's in-memory map (survives restarts, shared across sessions).
* @param sessionId recorded on rows this session writes to the persisted tables (a lid row's owner).
* @param chatStateStore optional persisted per-session mute/archive/pin, so those chat fields survive a
* reconnect Baileys cannot resync (it only re-emits mutations newer than the
* persisted app-state version, never an already-applied one).
*/
constructor(
private readonly lidStore?: LidMappingStore,
private readonly sessionId?: string,
private readonly chatStateStore?: ChatStateStore,
) {
// Mirrors LidMappingStoreService: a finite default, 0 opts back into unbounded, garbage falls back.
const maxEntries = resolveNonNegativeIntEnv(
process.env.BAILEYS_SESSION_STORE_MAX_ENTRIES,
SESSION_STORE_MAP_CAP_DEFAULT,
);
// A saved name only ever arrives from the account's own app-state address book, never from peer
// traffic, so pinning on it keeps the curated set out of reach of the peers this session happens
// to observe. The pinned population is bounded by the account's own contact list.
this.contacts = new LruMap(maxEntries, contact => Boolean(contact.name));
this.chats = new LruMap(maxEntries);
this.lastMessages = new LruMap(maxEntries);
this.lastInbound = new LruMap(maxEntries);
this.lidToPn = new LruMap(maxEntries);
// Double-keyed (raw + neutral JID per chat), so it needs two slots per chat to cover the same span.
this.ephemeralByChat = new LruMap(maxEntries * 2);
}
upsertContacts(records: Partial<BaileysContact>[] = []): void {
for (const r of records) {
// History-sync / app-state rows sometimes key the person as `lid` and leave `id` empty.
const id = r.id ?? r.lid;
if (!id) {
continue;
}
// Groups/newsletters/status arrive in the same history-sync contact array as people; they
// are not address-book entries and must not occupy the contact cap or GET /contacts.
const kind = parseWaId(id).kind;
if (kind === 'group' || kind === 'newsletter' || kind === 'broadcast' || kind === 'status') {
continue;
}
const existing = this.contacts.get(id) ?? { id };
const merged: BaileysContact = { id: existing.id };
this.assignDefined(merged, existing);
this.assignDefined(merged, { ...r, id });
this.contacts.set(id, merged);
// Capture a lid->phone pair from the merged record (lid + phone can arrive in separate updates).
// `phoneNumber` is the authoritative PN field; fall back to `id` itself only when it's already
// in the phone dialect (a lid-only contact's `id` is `<lid>@lid`, which is not a usable phone).
// A record keyed by its lid carries the lid side in `id` and usually has no `lid` field.
// A name-only update carries no new pair and must not write an older merged phone over the shared table.
const phone = merged.phoneNumber ?? (merged.id.endsWith('@s.whatsapp.net') ? merged.id : undefined);
const lid = merged.lid ?? (parseWaId(merged.id).kind === 'lid' ? merged.id : undefined);
if (lid && phone && (r.lid !== undefined || r.phoneNumber !== undefined)) {
this.lidToPn.set(lid, phone);
this.persistLidMapping(lid, phone, r.phoneNumber !== undefined || kind === 'user');
}
}
}
/**
* Copy own enumerable fields whose value is not `undefined`. History-sync contacts always include
* `name: displayName || name || username || undefined`, and a later `{ ...existing, ...partial }`
* spread would wipe a saved address-book name that arrived first via `contacts.upsert`.
*
* KNOWN LIMIT: a saved name therefore cannot be cleared, so a contact deleted or renamed blank on
* the phone keeps its old name here, stays in `GET /contacts`, and (being named) is pinned against
* eviction. Making an absent name authoritative is NOT a safe fix on its own: the same method
* serves `contacts.update`, which Baileys emits as `{ id, notify }` for the pushname on every
* inbound message, so absent-means-clear there would wipe the address book message by message.
* Only an app-state `contactAction` could carry that meaning, and whether WhatsApp expresses a
* deletion as a contactAction with empty fields is unverified here; settling it needs a live
* account, not a guess on this path.
*/
private assignDefined(target: BaileysContact, source: Partial<BaileysContact>): void {
for (const key of Object.keys(source) as (keyof BaileysContact)[]) {
const value = source[key];
if (value !== undefined) {
(target as unknown as Record<string, unknown>)[key] = value;
}
}
}
upsertChats(records: Partial<Chat>[] = []): void {
for (const r of records) {
if (!r.id) {
continue;
}
// A chat WhatsApp deleted takes no update until a message re-creates it: Baileys applies an own
// write locally (a mute or pin is sent without a message), and a reconnect resyncs a deletion before
// an archive or pin made ahead of it. Kept, either would show on the chat a later message re-creates.
if (this.stillDeleted(r.id, this.toUnixSeconds(r.conversationTimestamp))) {
continue;
}
const existing = this.chats.get(r.id) ?? { id: r.id };
this.chats.set(r.id, { ...existing, ...r });
this.persistChatState(r.id, r);
// A timer the chat itself reports (Baileys emits the EPHEMERAL_SETTING change as chats.update) is
// newer than the one learned from messages, and turning the timer off produces no stamped message
// that could clear it. Own key only, as in persistChatState: history-sync proto defaults are not news.
// Every twin: own sends cache the timer under the phone spelling of a chat Baileys keys by its lid,
// and a twin chat record would otherwise serve the old timer from the getEphemeralExpiration fallback.
if (Object.hasOwn(r, 'ephemeralExpiration')) {
const exp = r.ephemeralExpiration;
for (const key of new Set(this.chatTwins(r.id).flatMap(k => [k, this.toNeutralJid(k)]))) {
if (typeof exp === 'number' && exp > 0) {
this.ephemeralByChat.set(key, exp);
} else {
this.ephemeralByChat.delete(key);
}
const twin = key === r.id ? undefined : this.chats.get(key);
if (twin) this.chats.set(key, { ...twin, ephemeralExpiration: exp });
}
}
}
}
/**
* Drop chats Baileys reports deleted (`chats.delete`: an API delete replayed locally, or one made on
* the phone), with their preview and last inbound message, under every spelling: the id comes from
* the app-state index, which need not be the twin the chat or its messages are keyed under. The
* persisted mute/archive/pin is reset and the row marks the deletion ({@link chatDeletedAt}): WhatsApp
* keeps nothing of the chat while the gateway keeps its stored messages, and a write keyed to one of
* them comes back from Baileys as an update of the chat, which would list it again.
*/
removeChats(ids: string[] = []): void {
const keys = new Set(ids.flatMap(id => this.chatTwins(id)));
for (const key of keys) {
this.chats.delete(key);
this.lastMessages.delete(key);
this.lastInbound.delete(key);
}
if (keys.size && this.chatStateStore && this.sessionId) {
void this.markDeleted(this.chatStateStore, this.sessionId, ids, keys);
}
}
/**
* The marked row is written under the chat's state key, folding the rows of the known twins onto it,
* queued ahead of any later write. The in-memory mappings can lack the lid or phone twin after a
* restart, and a delete is never retried, so the twins only the mapping table pairs are forgotten
* after: a row there would outlive the deletion and put the chat back in the listing.
*
* Baileys reports a deletion by ids alone, so it is dated on arrival. One synced on a reconnect is
* dated later than it happened: a message delivered in the same reconnect counts as older, and the
* chat stays unlisted, its writes declined, until the next one.
*/
private async markDeleted(store: ChatStateStore, sessionId: string, ids: string[], keys: Set<string>): Promise<void> {
const reset = { muteEndTime: null, archived: false, pinned: false, deletedAt: Date.now() };
// Each chat folds its own twins: one event can delete several chats.
const twinsOf = new Map<string, Set<string>>();
for (const id of ids) {
const key = this.stateKey(id);
twinsOf.set(key, new Set([...(twinsOf.get(key) ?? []), ...this.chatTwins(id)]));
}
const marked = Promise.all(
[...twinsOf].map(([key, twins]) =>
store.fold(
sessionId,
key,
[...twins].filter(k => !twinsOf.has(k)),
reset,
),
),
);
const extra = new Set<string>();
for (const id of ids) {
const parsed = parseWaId(id);
try {
if (parsed.kind === 'lid') {
const phone = await this.lidStore?.findPhoneForLid?.(id);
if (phone) extra.add(`${userPart(phone)}@s.whatsapp.net`);
} else if (parsed.kind === 'user') {
for (const lid of (await this.lidStore?.findLidsForPhone?.(parsed.userPart)) ?? []) extra.add(`${lid}@lid`);
}
} catch {
// The table cannot be read; the keys the caches knew are already going.
}
}
await marked;
const missed = [...extra].filter(k => !keys.has(k) && !twinsOf.has(k));
if (missed.length) await store.forget(sessionId, missed);
}
/**
* When WhatsApp deleted the chat (epoch ms), read from its persisted state under any spelling, or
* null when it did not, or a message has re-created the chat since. A message sent at or before it
* belongs to the deleted chat.
*/
chatDeletedAt(chatId: string): number | null {
return this.chatState(chatId, this.chatTwins(chatId))?.deletedAt ?? null;
}
/**
* Whether the chat is marked deleted for a message or chat update dated `timestamp` (epoch seconds, 0
* for none). A message newer than the deletion re-creates the chat on WhatsApp, as a new chat, so its
* marked row goes and the answer is false. Only the rows a mark can sit under are read, the state key
* and the lids the jid and the persisted table name: an empty index skips the scan of this session's
* mappings, too slow to run for each of the thousands of messages a first sync records.
*/
private stillDeleted(jid: string, timestamp: number): boolean {
const store = this.chatStateStore;
const sid = this.sessionId;
if (!store || !sid) return false;
const key = this.stateKey(jid);
const rows = [key, ...this.stateTwins([jid], key, new Map())].flatMap(k => {
const value = store.get(sid, k);
return value ? [{ k, value }] : [];
});
const deletedAt = mergeTwinStates(rows.map(r => r.value))?.deletedAt;
if (!deletedAt) return false;
if (timestamp * 1000 <= deletedAt) return true;
void store.forget(
sid,
rows.map(r => r.k),
);
return false;
}
addLidMappings(mappings: { lid?: string; pn?: string }[] = [], isReported = true): void {
for (const m of mappings) {
if (m.lid && m.pn) {
this.lidToPn.set(m.lid, m.pn);
this.persistLidMapping(m.lid, m.pn, isReported);
}
}
}
/**
* Learn lid->pn mappings from an inbound message key (#362). Baileys v7 replaced the 6.7.x
* `senderLid`/`senderPn`/`participantLid`/`participantPn` fields with `remoteJidAlt` (DM) and
* `participantAlt` (group) — the "Alt" is always the other dialect of the same field
* (`remoteJid`/`participant`): if one side is `@lid`, the Alt is the phone JID, and vice versa. This
* is still the only place a fresh `@lid` sender's number is revealed on the message key itself; the
* pairs flow through addLidMappings, so they also write through to the persistent table.
*/
recordKeyLidMappings(
key: Pick<WAMessageKey, 'remoteJid' | 'remoteJidAlt' | 'participant' | 'participantAlt' | 'fromMe'>,
): void {
// On a status or broadcast-list message `remoteJidAlt` is the SENDER's other dialect (Baileys fills
// it for every non-group chat), so it pairs with `participant`, not with the `@broadcast` id.
const broadcast = key.remoteJid?.endsWith('@broadcast');
this.addLidMappings([
// Own-message remoteJid can name the recipient while senderAlt still names this account.
key.fromMe === true ? {} : this.lidPnPair(broadcast ? key.participant : key.remoteJid, key.remoteJidAlt),
this.lidPnPair(key.participant, key.participantAlt),
]);
}
/**
* Sorts a JID and its WhatsApp-supplied "Alt" counterpart into { lid, pn } by @lid suffix. The pn side
* must be a user id: anything else (a group, a list) would be persisted as that lid's phone number.
*/
private lidPnPair(jid?: string | null, alt?: string | null): { lid?: string; pn?: string } {
if (!jid || !alt) {
return {};
}
const [lid, pn] = jid.endsWith('@lid') ? [jid, alt] : alt.endsWith('@lid') ? [alt, jid] : [];
return lid && pn && parseWaId(pn).kind === 'user' ? { lid, pn } : {};
}
/** Write a learned lid->phone pair through to the persistent table (bare digits, fire-and-forget). */
private persistLidMapping(lidJid: string, pnJid: string, isReported: boolean): void {
if (isReported) void this.lidStore?.remember(userPart(lidJid), userPart(pnJid), this.sessionId);
else void this.lidStore?.rememberIfUnknown?.(userPart(lidJid), userPart(pnJid), this.sessionId);
}
/**
* The next place in the observed order. A live message takes its place on arrival, before the media
* download and the store reads that can let a later one finish first; history, which has none, records 0.
*/
nextMessageOrder(): number {
return ++this.messageOrder;
}
recordMessage(msg: WAMessage, type?: MessageType, order = this.nextMessageOrder()): void {
const chatId = msg.key?.remoteJid;
if (!chatId || !msg.key) {
return;
}
// Learn the chat's disappearing-messages timer from the message itself (#473). This runs before the
// newest-message guard so every inbound refreshes it; the timer is cached under both the raw and
// neutral JID so an outbound send addressed in either dialect (phone or @lid) finds it.
this.recordEphemeralFromMessage(chatId, msg);
// A received broadcast-list message previews in its sender's chat, where Baileys lists it.
const key = this.toEngineJid(baileysChatJid(chatId, msg.key.participant, msg.key.fromMe === true));
const timestamp = this.toUnixSeconds(msg.messageTimestamp);
// Recorded either way: the readers skip a message from before the deletion, and a newer one clears it.
this.stillDeleted(key, timestamp);
if (!msg.key.fromMe) {
const inbound = this.lastInbound.get(key);
if (
!inbound ||
inbound.timestamp < timestamp ||
(inbound.timestamp === timestamp && this.followsOther(msg, order, inbound))
) {
this.lastInbound.set(key, { key: msg.key, timestamp, order });
}
}
const existing = this.lastMessages.get(key);
if (
existing &&
(existing.timestamp > timestamp || (existing.timestamp === timestamp && !this.followsOther(msg, order, existing)))
) {
return; // keep the newest
}
const text = msg.message?.conversation ?? msg.message?.extendedTextMessage?.text ?? '';
this.lastMessages.set(key, { key: msg.key, timestamp, text, type, order });
}
/**
* Whether a message sent in the same second as `other` came after it. Timestamps have a resolution of
* a second, so two messages of a burst tie; the order they were observed in decides, and a repeat of
* the same message (a redelivery) is no later than itself.
*/
private followsOther(msg: WAMessage, order: number, other: { key: WAMessageKey; order: number }): boolean {
return !!msg.key.id && other.key.id !== msg.key.id && order > other.order;
}
/**
* Refresh the chat preview when (and only when) the edited message is still the latest message in
* that chat. Editing an older message must not replace the preview or reorder the conversation. The
* preview may sit on any twin of the chat, the one the listing reads included, so each is checked.
*/
recordMessageEdit(chatId: string, messageId: string, text: string, type?: MessageType): void {
if (!messageId) return;
for (const key of new Set([chatId, this.toEngineJid(chatId)])) {
const existing = this.lastMessages.get(key);
if (existing?.key.id === messageId)
this.lastMessages.set(key, { ...existing, text, type: type ?? existing.type });
}
}
/**
* The key a chat's preview is kept under, for an id in any dialect. One conversation reaches this
* store as `<phone>@c.us` (the API and the listing), `<phone>@s.whatsapp.net` and `<lid>@lid`
* (Baileys, which addresses a lid-migrated contact by its lid and sends to whatever it is given).
* Keying each spelling separately left an API send or an inbound message on a twin the chat row
* never reads, so the chat showed no preview and chat actions found no history. The chat record
* decides: the twin Baileys keyed the chat under wins, then a twin that already holds a preview,
* and a chat known under neither falls back to the engine dialect.
*/
private chatKey(jid: string): string {
if (this.chats.has(jid)) return jid;
const twins = this.chatTwins(jid);
return twins.find(k => this.chats.has(k)) ?? twins.find(k => this.lastMessages.has(k)) ?? this.toEngineJid(jid);
}
/**
* The `<lid>@lid` this session knows for a 1:1 chat or a person, under any spelling of it, or null
* when none is known (and always for a group). WhatsApp keys a lid-migrated contact's chat by its lid.
*/
lidOf(jid: string): string | null {
for (const twin of this.chatTwins(jid)) {
const parsed = parseWaId(twin);
if (parsed.kind === 'lid') return `${parsed.userPart}@lid`;
}
return null;
}
/** Every spelling of one chat this session can connect: the id, its engine form, and its lid or phone twin. */
chatTwins(jid: string): string[] {
const parsed = parseWaId(jid);
const twins = [jid, this.toEngineJid(jid)];
if (parsed.kind === 'lid') {
twins.push(`${parsed.userPart}@lid`);
const phone = this.resolvePhone(jid);
if (phone) twins.push(`${phone}@s.whatsapp.net`);
} else if (parsed.kind === 'user') {
for (const [lid, pn] of this.lidToPn.entries()) {
if (userPart(pn) === parsed.userPart) twins.push(lid);
}
for (const lid of this.lidStore?.lidsForPhone(parsed.userPart) ?? []) twins.push(`${lid}@lid`);
}
return twins;
}
/**
* Cache a positive disappearing-messages timer learned from an inbound message under both the raw chat
* JID and its neutral form, so {@link getEphemeralExpiration} hits regardless of which dialect the caller
* sends to. A non-positive/absent value means "no live timer on this message" and is left untouched (a
* single non-ephemeral message must not clear a known timer; WhatsApp keeps stamping it while on).
* A message no newer than the chat's last timer change (`ephemeralSettingTimestamp`, on any twin) is
* skipped: it carries the old timer, and a reconnect flush or history sync records it after the change.
*/
private recordEphemeralFromMessage(chatId: string, msg: WAMessage): void {
const duration = this.extractEphemeralDuration(msg);
if (duration === undefined) {
return;
}
const setAt = Math.max(
...[this.chatKey(chatId), ...this.chatTwins(chatId)].map(k =>
this.toUnixSeconds(this.chats.get(k)?.ephemeralSettingTimestamp),
),
);
if (setAt > 0 && this.toUnixSeconds(msg.messageTimestamp) <= setAt) {
return;
}
this.ephemeralByChat.set(chatId, duration);
this.ephemeralByChat.set(this.toNeutralJid(chatId), duration);
}
/**
* Best-effort read of a message's disappearing timer (seconds). `WebMessageInfo.ephemeralDuration` is
* populated on history-synced messages but is typically ABSENT on a live 1:1 `messages.upsert`, so fall
* back to the per-message `contextInfo.expiration` WhatsApp stamps on every message in a disappearing
* chat — read after unwrapping the ephemeral / view-once / document-with-caption envelope. Exposed so
* the history-backfill mapper can populate the same signal the live path uses, without duplicating the
* extraction.
*/
extractEphemeralDuration(msg: WAMessage): number | undefined {
const fromInfo = msg.ephemeralDuration;
if (typeof fromInfo === 'number' && fromInfo > 0) {
return fromInfo;
}
const fromContext = this.contextExpiration(msg.message);
return typeof fromContext === 'number' && fromContext > 0 ? fromContext : undefined;
}
/** Walk a message's content (unwrapping known envelopes) and return the first positive `contextInfo.expiration`. */
private contextExpiration(content: WAMessage['message'], depth = 0): number | undefined {
if (!content || typeof content !== 'object' || depth > 4) {
return undefined;
}
const nodes = content as Record<
string,
{ contextInfo?: { expiration?: number | null }; message?: WAMessage['message'] } | undefined
>;
for (const node of Object.values(nodes)) {
const exp = node?.contextInfo?.expiration;
if (typeof exp === 'number' && exp > 0) {
return exp;
}
if (node?.message) {
const nested = this.contextExpiration(node.message, depth + 1);
if (nested !== undefined) {
return nested;
}
}
}
return undefined;
}
listContacts(): Contact[] {
// GET /contacts is the address book, not "everyone this session has ever seen". Baileys
// documents `name` as the one YOU saved; `notify` is only the pushname they set themselves.
//
// Deduplicated by neutral id: one person can occupy two entries, one keyed by `@lid` and one by
// the phone dialect, and when both carry a saved name they project to the SAME id once the lid
// resolves. Listing both put two rows sharing one id into the answer.
//
// The iteration is over a SNAPSHOT, and must stay that way: `toNeutralContact` resolves a lid
// through `resolvePhone`, which reads this very map, and a read moves the entry to the
// most-recent end. Iterating the live map therefore hands the same entry back forever, a
// synchronous loop that wedges the process rather than answering the request.
const byId = new Map<string, ContactTwin>();
for (const c of [...this.contacts.values()]) {
if (!c.name) continue;
const twin: ContactTwin = { contact: this.toNeutralContact(c), rawId: c.id };
const existing = byId.get(twin.contact.id);
byId.set(twin.contact.id, existing ? mergeContactTwins(existing, twin) : twin);
}
return [...byId.values()].map(t => t.contact);
}
findContact(id: string): Contact | null {
const parsed = parseWaId(id);
const keys = [id, this.toEngineJid(id)];
if (parsed.kind === 'lid') {
keys.push(`${parsed.userPart}@lid`);
}
if (parsed.kind === 'user') {
keys.push(`${parsed.userPart}@s.whatsapp.net`, `${parsed.userPart}@c.us`);
}
// One person can occupy two entries, one keyed by `@lid` and one by the phone dialect, and only
// one of them carries the saved name. Prefer the named one: the nameless twin answers
// `isMyContact: false` and no display name for somebody the account has saved.
let unnamed: BaileysContact | undefined;
for (const key of keys) {
const direct = this.contacts.get(key);
if (!direct) continue;
if (direct.name) return this.toNeutralContact(direct);
unnamed ??= direct;
}
if (parsed.kind !== 'user' && parsed.kind !== 'lid') {
return unnamed ? this.toNeutralContact(unnamed) : null;
}
// The twin is keyed under the OTHER dialect, so a direct hit cannot reach it; the scan below
// can, through `lid`/`phoneNumber`. Run it even when a direct hit was found, as long as that hit
// was nameless, and keep the nameless one only if the scan turns up nothing better.
const want = parsed.userPart;
for (const c of this.contacts.values()) {
const phone = c.phoneNumber
? userPart(c.phoneNumber)
: c.id.endsWith('@s.whatsapp.net') || c.id.endsWith('@c.us')
? userPart(c.id)
: '';
const lid = c.lid ? userPart(c.lid) : c.id.endsWith('@lid') ? userPart(c.id) : '';
// Digits are only comparable within one kind: a lid and a phone number can read the same.
if ((parsed.kind === 'user' ? phone : lid) !== want) continue;
if (c.name) return this.toNeutralContact(c);
unnamed ??= c;
}
return unnamed ? this.toNeutralContact(unnamed) : null;
}
/**
* One row per conversation. A contact WhatsApp migrated to a lid can hold two records, one keyed by
* phone and one by lid (Baileys files an update under whichever id its source carried, and a record
* created before the lid->phone mapping was learned stays where it is), and both project to the same
* neutral id; listing each put two rows sharing one id into the answer. They fold like contacts do:
* the phone-keyed record is primary, the twin {@link chatJid} routes app-state writes to, and a field
* the primary lacks comes from the other. The preview is the newest message filed under any key that
* projects to the row, indexed in one pass rather than a twin scan per chat.
*
* Every loop is over a SNAPSHOT: projecting an id resolves a lid through maps whose read moves the
* entry to the most-recent end, so a live iterator would hand the same entry back forever.
*/
listChats(): ChatSummary[] {
const lidIndex = this.lidsByPhone();
const previews = new Map<string, LastMessage>();
for (const [key, m] of [...this.lastMessages.entries()]) {
const id = this.toNeutralJid(key);
const seen = previews.get(id);
if (!seen || m.timestamp > seen.timestamp || (m.timestamp === seen.timestamp && m.order > seen.order)) {
previews.set(id, m);
}
}
const byId = new Map<string, Chat[]>();
for (const c of [...this.chats.values()]) {
const id = this.toNeutralJid(c.id!);
byId.set(id, [...(byId.get(id) ?? []), c]);
}
// A message proves the raw conversation exists even before its chat record reaches this process.
for (const [key] of [...this.lastMessages.entries()]) {
const id = this.toNeutralJid(key);
if (!byId.has(id)) byId.set(id, [{ id: key }]);
}
// A new engine starts with no chats (see the class comment), but a chat with a persisted state is
// known to exist, unless the row marks its deletion. So it is listed before its next message arrives.
if (this.chatStateStore && this.sessionId) {
for (const chatId of this.chatStateStore.chatIds(this.sessionId)) {
const id = this.toNeutralJid(chatId);
if (!byId.has(id)) byId.set(id, [{ id: chatId }]);
}
}
return [...byId].flatMap(([id, records]) => this.toNeutralChat(id, records, previews.get(id), lidIndex) ?? []);
}
/**
* The id the chat is keyed under, for an app-state write addressed with any spelling of it (the
* listing's @c.us id of a lid-keyed chat resolves to the lid). Baileys indexes the patch by this jid
* and replays it locally under the same id, so any other spelling names a chat the phone does not
* hold and lands the echo on a second record.
*/
chatJid(chatId: string): string {
return this.chatKey(chatId);
}
/** The chat's newest message, with `jid`, the id the chat itself is keyed under. */
lastMessage(chatId: string): { key: WAMessageKey; timestamp: number; jid: string } | null {
const m = this.newestAcrossTwins(this.lastMessages, chatId);
return m ? { key: m.key, timestamp: m.timestamp, jid: this.chatJid(chatId) } : null;
}
/** The newest message the chat received (not one this account sent), or null when none is known. */
lastInboundMessage(chatId: string): { key: WAMessageKey; timestamp: number } | null {
const m = this.newestAcrossTwins(this.lastInbound, chatId);
return m ? { key: m.key, timestamp: m.timestamp } : null;
}
/**
* The newest entry `map` holds for a chat under any of its spellings. A message recorded under the
* contact's lid before the lid->phone mapping was learned stays on the lid twin while the chat key
* moves to the phone-keyed chat record, so reading the chat key alone would lose it.
*/
private newestAcrossTwins<T extends { timestamp: number; order: number }>(
map: LruMap<string, T>,
chatId: string,
): T | undefined {
let newest: T | undefined;
for (const k of [this.chatKey(chatId), ...this.chatTwins(chatId)]) {
const v = map.get(k);
if (
v &&
(!newest || v.timestamp > newest.timestamp || (v.timestamp === newest.timestamp && v.order > newest.order))
) {
newest = v;
}
}
return newest;
}
/**
* The chat's disappearing-messages timer in seconds (#473), or `undefined` when no timer is known.
* Only a positive value is returned: `0` / `null` / absent all mean "no known timer", so the caller
* omits the per-message `ephemeralExpiration` and reproduces today's send behavior (Baileys' own send
* guard is truthy). This keeps a stale-empty or boot-window cache from ever forcing a message to
* disappear. Folds a neutral `@c.us` id to the engine dialect first, like the other chat lookups.
*/
getEphemeralExpiration(chatId: string): number | undefined {
// Prefer the timer learned from inbound messages (reliably present); try the raw, engine, and
// neutral keys so an @lid-keyed entry and a phone-dialect send target resolve to the same value.
const fromMessage = [chatId, this.toEngineJid(chatId), ...this.chatTwins(chatId)]
.map(key => this.ephemeralByChat.get(key))
.find(value => typeof value === 'number' && value > 0);
if (typeof fromMessage === 'number' && fromMessage > 0) {
return fromMessage;
}
// Fallback to the chat object's own timer for sessions/engines that do surface it on `chats.*`.
const chat =
this.chats.get(chatId) ??
this.chats.get(this.toEngineJid(chatId)) ??
this.chats.get(this.toNeutralJid(chatId)) ??
this.chats.get(this.chatKey(chatId));
const exp = chat?.ephemeralExpiration;
return typeof exp === 'number' && exp > 0 ? exp : undefined;
}
resolvePhone(id: string): string | null {
const parsed = parseWaId(id);
// A user id (@c.us / @s.whatsapp.net) already carries the phone as its user-part. The @c.us case
// matters once inbound ids are canonicalized: a resolved-lid sender arrives as <phone>@c.us.
if (parsed.kind === 'user') {
return parsed.userPart;
}
if (parsed.kind === 'lid') {
// Look up by the device-stripped lid; mappings/contacts are keyed without a :device suffix.
const lidJid = `${parsed.userPart}@lid`;
const pn = this.lidToPn.get(lidJid) ?? this.lidToPn.get(id);
if (pn) {
return userPart(pn);
}
const contactPhone = (this.contacts.get(lidJid) ?? this.contacts.get(id))?.phoneNumber;
if (contactPhone) {
return userPart(contactPhone);
}
// Fall back to the persistent, cross-session table (in-memory cache, keyed by bare lid digits).
// `null` means a cached negative (known-unresolved); `undefined` means never seen - both -> null.
return this.lidStore?.getCached(parsed.userPart) ?? null;
}
return null;
}
/**
* Normalize identity without deriving it from a display cache. A LID stays a LID; persisted,
* reported mappings bridge it to phone grants and filters at the application boundary.
*/
toNeutralJid(jid: string): string {
return canonicalizeWaId(jid);
}
/**
* Fold an app-facing neutral id back to the engine's raw dialect. The contacts / chats / lastMessages
* maps are keyed by Baileys' raw `@s.whatsapp.net`, but the app now hands us the neutral `@c.us`
* (contact/chat ids are emitted neutral), so map lookups must fold first. The outbound group-participant
* ops fold for the same reason: only `@s.whatsapp.net` encodes to the single-byte protocol token, whereas
* a raw `c.us` server suffix would go on the wire as an unknown string. Groups/lids/others share the
* dialect, so pass them through unchanged.
*/
toEngineJid(jid: string): string {
const parsed = parseWaId(jid);
return parsed.kind === 'user' ? `${parsed.userPart}@s.whatsapp.net` : jid;
}
private toNeutralContact(c: BaileysContact): Contact {
// The number is read off the NEUTRAL id, which has already done the lid resolution: a lid-keyed
// entry whose mapping is known projects to `<phone>@c.us` and carries its number, where reading
// the raw `@lid` key answered an empty string for somebody the account has saved. An unresolved
// lid still answers '', which is the honest answer there.
const id = this.toNeutralJid(c.id);
const number = c.phoneNumber ? userPart(c.phoneNumber) : (this.resolvePhone(c.id) ?? '');
return {
id,
name: c.name ?? c.verifiedName,
pushName: c.notify,
number,
// Baileys distinguishes the two names: `name` is documented as the one YOU saved on your
// WhatsApp, `notify` as the pushname the contact set themselves. Reporting true for everyone
// told an automation that every chat partner was in the addressbook, which is what
// whatsapp-web.js reports honestly from the Contact model.
isMyContact: Boolean(c.name),
isBlocked: false, // best-effort: blocklist state is not tracked in this slice
// A `picture` notification stores the marker 'changed' or 'removed' in imgUrl, not a URL.
profilePicUrl: c.imgUrl && /^https?:\/\//i.test(c.imgUrl) ? c.imgUrl : undefined,
};
}
/**
* Project the records that share neutral `id` (usually one) into a row. `last` is the newest preview
* filed under any of their keys. Null for a chat WhatsApp deleted that no message has re-created since.
*/
private toNeutralChat(
id: string,
records: Chat[],
last: LastMessage | undefined,
lidIndex: Map<string, string[]>,
): ChatSummary | null {
// Chat.id is nullable on Baileys' own type (it's the raw proto.IConversation field), but
// upsertChats() only ever stores a record under a truthy r.id, so every value in `this.chats`
// is provably keyed by a real id. Phone-keyed first, then the lower raw id: stable across calls.
const [c, ...others] = [...records].sort((a, b) =>
isPhoneKeyed(a.id!) !== isPhoneKeyed(b.id!) ? (isPhoneKeyed(a.id!) ? -1 : 1) : a.id! < b.id! ? -1 : 1,
);
const rawId = c.id!;
// Mute/archive/pin come from the persisted store when it has this chat (it survives a reconnect
// Baileys cannot resync), else from the primary's live record. A `null` muteEndTime means unmuted.
const st = this.chatState(
rawId,
records.map(r => r.id!),
lidIndex,
);
// Only a message newer than the deletion re-creates the chat: a record without one is a state update,
// and a message sent before it, delivered late, is the deleted chat's.
const active = () =>
Math.max(last?.timestamp ?? 0, ...records.map(r => this.toUnixSeconds(r.conversationTimestamp)));
if (st?.deletedAt && active() * 1000 <= st.deletedAt) return null;
return {
id,
name: c.name ?? others.find(o => o.name)?.name ?? this.resolveContactName(rawId),
isGroup: rawId.endsWith('@g.us'),
kind: chatKind(id),
// From the most recently active record that has one: new messages to a lid-migrated contact
// count on the lid record while the phone one keeps a stale 0.
unreadCount:
[c, ...others]
.filter(r => r.unreadCount != null)
.sort((a, b) => this.toUnixSeconds(b.conversationTimestamp) - this.toUnixSeconds(a.conversationTimestamp))[0]
?.unreadCount ?? 0,
timestamp: last?.timestamp ?? Math.max(...records.map(r => this.toUnixSeconds(r.conversationTimestamp))),
lastMessage: last?.text,
lastMessageType: last?.type,
archived: st ? st.archived : (c.archived ?? false),
// Baileys reports a pin as an ORDER, not a flag: 0/absent means unpinned.
pinned: st ? st.pinned : Boolean(c.pinned),
muted: this.isMuted(st ? st.muteEndTime : c.muteEndTime),
muteExpiration: this.muteExpirationMs(st ? st.muteEndTime : c.muteEndTime),
};
}
/**
* Whether a Baileys `muteEndTime` is still in the future.
*
* The value arrives in two units. An app-state `chatModify({ mute })` write echoes the epoch
* MILLISECONDS this gateway passed (measured in `chat-mute.spec.ts`, documented in `mute-chat.dto.ts`).
* A history-sync `Conversation.muteEndTime` is a Long in the proto's own unit, seconds like the
* `conversationTimestamp` beside it. So it is normalised by magnitude: below 1e12 is seconds (an
* epoch-ms stamp below 1e12 is a date before 2001-09) and is scaled to ms. The current state survives a
* reconnect via {@link persistChatState}, because Baileys re-emits only app-state mutations newer than
* the persisted version, never an already-applied mute. A negative value is WhatsApp's "Always"
* sentinel (-1, the value WhatsApp Web sends too), a mute with no end.
*/
private isMuted(muteEndTime: number | { toNumber(): number } | null | undefined): boolean {
const raw = this.toUnixSeconds(muteEndTime);
if (!raw) return false;
if (raw < 0) return true;
const endMs = raw < 1e12 ? raw * 1000 : raw;
return endMs > Date.now();
}
/**
* The expiry instant (epoch ms) for {@link ChatSummary.muteExpiration}, or undefined when the chat
* is not muted. Same normalisation as {@link isMuted}, so the two agree: a value only survives here
* when it is still in the future. A mute with no end reads 0, the contract's "muted indefinitely".
*/
private muteExpirationMs(muteEndTime: number | { toNumber(): number } | null | undefined): number | undefined {
const raw = this.toUnixSeconds(muteEndTime);
if (!raw) return undefined;
if (raw < 0) return 0;
const endMs = raw < 1e12 ? raw * 1000 : raw;
return endMs > Date.now() ? endMs : undefined;
}
/**
* Write mute/archive/pin through to the persisted store when a chat update carries them. Own-key
* presence, not truthiness, is the trigger: a history-sync or name-hydration partial that omits these
* keys must not overwrite persisted state, and a live unmute arrives as `muteEndTime: null` (an own
* key) that must persist as null. It has to be an OWN key: history sync hands over decoded
* `proto.Conversation` instances, whose prototype defaults all three fields to null, so the `in`
* operator would read every history chunk as a reset to unpinned, unarchived and unmuted. A no-op
* when this session has no store wired (unit tests, wwjs).
*/
private persistChatState(id: string, r: Partial<Chat>): void {
if (!this.chatStateStore || !this.sessionId) return;
const patch: Partial<ChatStateValue> = {};
if (Object.hasOwn(r, 'muteEndTime')) patch.muteEndTime = this.normalizeMuteEndTime(r.muteEndTime);
if (Object.hasOwn(r, 'archived')) patch.archived = Boolean(r.archived);
if (Object.hasOwn(r, 'pinned')) patch.pinned = Boolean(r.pinned);
if (Object.keys(patch).length) {
// A row still filed under a lid twin is folded onto the state key here, on a real change, never
// on a read: the store picks the newest row from the table, so a twin the cache happens to hold
// cannot overwrite a newer row it does not.
const key = this.stateKey(id);
const twins = this.stateTwins([id], key);
// Only an app-state action (the update holds the state fields alone) may create a row to hold a
// default, like an unpin that must outweigh a pin on a twin row. A message carries `archived:
// false` when the account unarchives on new messages, and a history chat carries its other fields
// too; a default in either creating a row would leave one row per chat ever messaged.
const create = Object.keys(r).every(f => f === 'id' || f === 'conditional' || Object.hasOwn(patch, f));
void (twins.length
? this.chatStateStore.fold(this.sessionId, key, twins, patch, create)
: this.chatStateStore.remember(this.sessionId, key, patch, create));
}
}
/**
* The one key a chat's persisted state lives under, whatever spelling the update carried: the phone
* JID once the lid resolves, else the device-stripped lid, and anything else (a group) as is.
* WhatsApp syncs a lid-migrated contact's pin, mute and archive under the lid while the chat record
* may be keyed by phone, so keying the row by the raw id split one chat's state across two rows and
* the listing read the one that never changed.
*/
private stateKey(id: string): string {
const parsed = parseWaId(id);
if (parsed.kind === 'lid') {
const phone = this.resolvePhone(id);
return phone ? `${phone}@s.whatsapp.net` : `${parsed.userPart}@lid`;
}
return this.toEngineJid(id);
}
/**
* The chat's persisted state. A row may still sit under a lid twin of the state key: written before
* the mapping was learned, or by an earlier version that keyed rows by the raw id. The rows merge
* field by field, as the fold does (see {@link mergeTwinStates}). A read never writes: the twin rows
* are folded onto the state key on the chat's next change (see {@link persistChatState}). `recordIds`
* are the raw ids of every chat record merged into the row, whose lids are twins too.
*/
private chatState(rawId: string, recordIds: string[], lidIndex?: Map<string, string[]>): ChatStateValue | undefined {
const store = this.chatStateStore;
const sid = this.sessionId;
if (!store || !sid) return undefined;
const key = this.stateKey(rawId);
return mergeTwinStates([key, ...this.stateTwins(recordIds, key, lidIndex)].flatMap(k => store.get(sid, k) ?? []));
}
/**
* The lid spellings of a phone-keyed state key: the lids among the chat's own record ids, and the
* ones this session's mappings and the persisted table pair with the phone. The own lids matter when
* only the contact record resolves them, which neither mapping source holds.
*/
private stateTwins(rawIds: string[], key: string, lidIndex?: Map<string, string[]>): string[] {
const parsed = parseWaId(key);
if (parsed.kind !== 'user') return [];
// A single update scans the mappings for this one phone; building the whole index per update
// blocked the event loop for seconds when a first sync carried thousands of state fields.
const twins = new Set(lidIndex?.get(parsed.userPart));
if (!lidIndex) {
for (const [lid, pn] of this.lidToPn.entries()) {
if (userPart(pn) === parsed.userPart) twins.add(`${userPart(lid)}@lid`);
}
}
for (const lid of this.lidStore?.lidsForPhone(parsed.userPart) ?? []) twins.add(`${lid}@lid`);
for (const rawId of rawIds) {
const raw = parseWaId(rawId);
if (raw.kind === 'lid') twins.add(`${raw.userPart}@lid`);
}
return [...twins];
}
/** Phone digits to the lid JIDs this session maps to them, built once per listing. */
private lidsByPhone(): Map<string, string[]> {
const index = new Map<string, string[]>();
for (const [lid, pn] of [...this.lidToPn.entries()]) {
const phone = userPart(pn);
index.set(phone, [...(index.get(phone) ?? []), `${userPart(lid)}@lid`]);
}
return index;
}
/**
* Normalise a raw muteEndTime to canonical epoch ms, or null (0/absent = unmuted). A mute with no end
* keeps the -1 sentinel rather than scaling it. See {@link isMuted}.
*/
private normalizeMuteEndTime(v: number | { toNumber(): number } | null | undefined): number | null {
const n = this.toUnixSeconds(v);
if (!n) return null;
if (n < 0) return -1;
return n < 1e12 ? n * 1000 : n;
}
/**
* Best-known display name for a chat id when Baileys gave the chat no title (#369). Prefers the saved
* contact name, then verifiedName, then pushName (`notify`); for a @lid chat it also tries the contact
* behind the resolved phone. Falls back to the raw user-part so a number/lid is never shown as a JID.
*/
private resolveContactName(id: string): string {
const direct = this.contactDisplayName(id);
if (direct) {
return direct;
}
const parsed = parseWaId(id);
if (parsed.kind === 'lid') {
const lidJid = `${parsed.userPart}@lid`;
const pn =
this.lidToPn.get(lidJid) ??
this.lidToPn.get(id) ??
(this.contacts.get(lidJid) ?? this.contacts.get(id))?.phoneNumber;
if (pn) {
const viaPhone =
this.contactDisplayName(pn) ??
this.contactDisplayName(`${userPart(pn)}@s.whatsapp.net`) ??
this.contactDisplayName(`${userPart(pn)}@c.us`);
if (viaPhone) {
return viaPhone;
}
}
}
return userPart(id);
}
private contactDisplayName(id: string): string | undefined {
const c = this.contacts.get(id);
return c ? (c.name ?? c.verifiedName ?? c.notify ?? undefined) : undefined;
}
private toUnixSeconds(ts: number | { toNumber(): number } | null | undefined): number {
if (ts == null) {
return 0;
}
return typeof ts === 'number' ? ts : ts.toNumber();
}
}