@stage-labs/metro 0.1.0-beta.262 → 0.1.0-beta.264

package/runtime/node_modules/@metro-labs/whatsapp/src/client-history.ts

@@ -0,0 +1,31 @@
+import { log } from '@metro-labs/core/log';
+import { TrainError } from '@metro-labs/core/train-error';
+import { supportsHistoryDeletion } from './app-state.js';
+import { createHistory, type History } from './history.js';
+
+const UNAVAILABLE = 'WhatsApp local history is unavailable because this runtime lacks the deletion patch. Restart the Metro service parent to install the patched runtime; a page Restart is not enough. Prior history was invalidated to avoid stale deleted messages.';
+const ignore = (): void => undefined;
+
+export function createClientHistory(accountId: string, supported = supportsHistoryDeletion()): History {
+  const history = createHistory(accountId);
+  if (supported) return history;
+  try {
+    history.invalidate();
+  } finally {
+    history.close();
+  }
+  log.warn({ accountId }, UNAVAILABLE);
+  return {
+    read() { throw new TrainError('whatsapp_history_unavailable', UNAVAILABLE); },
+    ingest: ignore,
+    ingestSent: ignore,
+    alias: ignore,
+    clearRange: ignore,
+    invalidate: ignore,
+    update: ignore,
+    deleteMessages: ignore,
+    edit: ignore,
+    flush: ignore,
+    close: ignore,
+  };
+}

package/runtime/node_modules/@metro-labs/whatsapp/src/client-types.ts

@@ -0,0 +1,46 @@
+import type makeWASocket from 'baileys';
+import type { fetchLatestWaWebVersion, WAMessage } from 'baileys';
+import type { MemberList } from '@metro-labs/core/stations/types';
+import type { ProfileChange } from '@metro-labs/core/stations/profile';
+import type { SenderProfile } from '@metro-labs/core/stations/sender-profile';
+import type { WhatsAppAccount } from './types.js';
+import type { InboundMessage, ReactionInput } from './format.js';
+import type { SenderFound } from './resolve.js';
+import type { HistoryOptions, HistoryPage } from './history.js';
+
+export interface InboundHandlers {
+  onMessage(m: InboundMessage, raw: WAMessage): void;
+  onReaction(r: ReactionInput): void;
+}
+
+export interface WAMedia {
+  kind: string;
+  path: string;
+  mime: string;
+  name: string;
+  caption?: string;
+}
+
+export interface WAClient {
+  account: WhatsAppAccount;
+  self(): string | null;
+  start(handlers: InboundHandlers): Promise<void>;
+  read(jid: string, options?: HistoryOptions): Promise<HistoryPage>;
+  listMembers(jid: string, limit?: number): Promise<MemberList>;
+  sendText(jid: string, text: string, quotedId?: string): Promise<string>;
+  sendMedia(jid: string, media: WAMedia, quotedId?: string): Promise<string>;
+  sendReaction(jid: string, messageId: string, emoji: string): Promise<void>;
+  showTyping(jid: string): Promise<void>;
+  editMessage(jid: string, messageId: string, text: string): Promise<void>;
+  deleteMessage(jid: string, messageId: string): Promise<void>;
+  reuploadMedia(m: WAMessage): Promise<WAMessage>;
+  lookupSender(number: string): Promise<SenderFound>;
+  setProfile(change: ProfileChange): Promise<void>;
+  senderProfile(jid: string): Promise<SenderProfile | null>;
+  disconnect(): Promise<void>;
+}
+
+export interface ClientRuntime {
+  makeSocket: typeof makeWASocket;
+  fetchVersion: typeof fetchLatestWaWebVersion;
+}

package/runtime/node_modules/@metro-labs/whatsapp/src/client.ts

@@ -11,13 +11,17 @@ import makeWASocket, {
 import { TrainError } from '@metro-labs/core/train-error';
 import { errMsg } from '@metro-labs/core/log';
 import type { WhatsAppAccount } from './types.js';
-import type { InboundMessage, ReactionInput } from './format.js';
-import type { SenderFound } from './resolve.js';
-import type { ProfileChange } from '@metro-labs/core/stations/profile';
+import type { InboundHandlers, WAClient, WAMedia, ClientRuntime } from './client-types.js';
+export type { InboundHandlers, WAClient, WAMedia } from './client-types.js';
 import { makeProfileCache, nonEmpty, type SenderProfile } from '@metro-labs/core/stations/sender-profile';
-import { toInbound, toReaction, type ReactionEvent, type SelfRef } from './parse.js';
+import type { SelfRef } from './parse.js';
+import type { History } from './history.js';
+import { createClientHistory } from './client-history.js';
+import { bindMessages } from './messages.js';
+import { listMembers } from './members.js';
+import { SendExpiry } from './send-expiry.js';
 import { baileysLogger } from './logger.js';
-import { makeNameBook, nameFiles, noteContact, phoneOf, type NameBook } from './names.js';
+import { makeNameBook, nameFiles, phoneOf, type NameBook } from './names.js';
 import { useAccountAuthState } from './auth-state.js';
 import { knownKey, makeKeyCache, targetKey, type KeyCache } from './keys.js';
 import { makeOutbox, type Outbox } from './outbox.js';
@@ -30,41 +34,15 @@ import {
   type AckWatch,
 } from './ack.js';
 
-export interface InboundHandlers {
-  onMessage(m: InboundMessage, raw: WAMessage): void;
-  onReaction(r: ReactionInput): void;
-}
-
-export interface WAMedia {
-  kind: string;
-  path: string;
-  mime: string;
-  name: string;
-  caption?: string;
-}
-
-export interface WAClient {
-  account: WhatsAppAccount;
-  self(): string | null;
-  start(handlers: InboundHandlers): Promise<void>;
-  sendText(jid: string, text: string, quotedId?: string): Promise<string>;
-  sendMedia(jid: string, media: WAMedia, quotedId?: string): Promise<string>;
-  sendReaction(jid: string, messageId: string, emoji: string): Promise<void>;
-  showTyping(jid: string): Promise<void>;
-  editMessage(jid: string, messageId: string, text: string): Promise<void>;
-  deleteMessage(jid: string, messageId: string): Promise<void>;
-  reuploadMedia(m: WAMessage): Promise<WAMessage>;
-  lookupSender(number: string): Promise<SenderFound>;
-  setProfile(change: ProfileChange): Promise<void>;
-  senderProfile(jid: string): Promise<SenderProfile | null>;
-  disconnect(): Promise<void>;
-}
-
 interface State {
   account: WhatsAppAccount;
+  runtime: ClientRuntime;
+  history: History;
+  expiry: SendExpiry;
   handlers?: InboundHandlers;
   sock?: WASocket;
   closed: boolean;
+  closing?: Promise<void>;
   openResolve?: () => void;
   openPromise: Promise<void>;
   keys: KeyCache;
@@ -91,32 +69,14 @@ function selfRef(st: State, sock: WASocket): SelfRef {
 }
 
 function bindInbound(st: State, sock: WASocket): void {
-  sock.ev.on('messages.upsert', ({ messages, type }) => {
-    for (const m of messages) st.keys.remember(m.key);
-    if (type !== 'notify' || !st.handlers) return;
-    for (const m of messages) {
-      if (m.key.fromMe) continue;
-      const inbound = toInbound(st.account.id, m, selfRef(st, sock));
-      if (inbound) st.names.note(inbound.senderJid, inbound.pushName);
-      if (inbound) st.handlers.onMessage(inbound, m);
-    }
-  });
-  sock.ev.on('contacts.upsert', (contacts) => {
-    for (const c of contacts) noteContact(st.names, c);
-  });
-  sock.ev.on('contacts.update', (contacts) => {
-    for (const c of contacts) noteContact(st.names, c);
-  });
-  sock.ev.on('messaging-history.set', ({ contacts, messages }) => {
-    for (const c of contacts) noteContact(st.names, c);
-    for (const m of messages) if (m.key.fromMe !== true) st.names.note(m.key.participant ?? m.key.remoteJid, m.pushName);
-  });
-  sock.ev.on('messages.reaction', (events: ReactionEvent[]) => {
-    if (!st.handlers) return;
-    for (const event of events) {
-      const reaction = toReaction(st.account.id, event);
-      if (reaction) st.handlers.onReaction(reaction);
-    }
+  bindMessages(sock, {
+    accountId: st.account.id,
+    keys: st.keys,
+    names: st.names,
+    history: st.history,
+    current: () => !st.closed && st.sock === sock,
+    handlers: () => st.handlers,
+    self: () => selfRef(st, sock),
   });
 }
 
@@ -197,19 +157,22 @@ async function connect(st: State): Promise<void> {
     st.account.credentials,
     st.account.id,
   );
-  const { version, error } = await fetchLatestWaWebVersion({});
+  if (st.closed) return;
+  const { version, error } = await st.runtime.fetchVersion({});
+  if (st.closed) return;
   if (error) {
     throw new TrainError(
       'whatsapp_connect',
       `failed to fetch WhatsApp web version: ${errMsg(error)}`,
     );
   }
-  const sock = makeWASocket({
+  const sock = st.runtime.makeSocket({
     version,
     auth: state,
     browser: Browsers.macOS('Safari'),
     markOnlineOnConnect: false,
     syncFullHistory: false,
+    emitOwnEvents: false,
     logger: baileysLogger(st.account.id),
     getMessage: (key) => Promise.resolve(servedFromOutbox(st, key)),
   });
@@ -217,6 +180,7 @@ async function connect(st: State): Promise<void> {
   sock.ev.on('creds.update', () => void saveCreds());
   bindConnection(st, sock);
   bindInbound(st, sock);
+  st.expiry.bind(sock, () => !st.closed && st.sock === sock);
   bindDelivery(st, sock);
 }
 
@@ -233,7 +197,7 @@ async function lidFor(st: State, sock: WASocket, jid: string): Promise<string |
 
 async function ready(st: State): Promise<WASocket> {
   await st.openPromise;
-  if (!st.sock) throw new TrainError('whatsapp_call', 'socket not connected');
+  if (st.closed || !st.sock) throw new TrainError('whatsapp_call', 'socket not connected');
   return st.sock;
 }
 
@@ -244,10 +208,13 @@ async function send(
   opts?: SendOpts,
 ): Promise<string> {
   const sock = await ready(st);
-  const sent = await sock.sendMessage(jid, content, opts);
-  st.keys.remember(sent?.key);
-  st.outbox.remember(sent?.key, sent?.message);
-  const messageId = sent?.key.id;
+  const expiration = await st.expiry.forSend(sock, jid, content);
+  if (st.closed || st.sock !== sock) throw new TrainError('whatsapp_call', 'socket not connected');
+  const sent = await sock.sendMessage(jid, content, expiration === undefined ? opts : { ...opts, ephemeralExpiration: expiration });
+  const key = sent?.key;
+  st.keys.remember(key);
+  st.outbox.remember(key, sent?.message);
+  const messageId = key?.id;
   if (!messageId)
     throw new TrainError(
       'whatsapp_call',
@@ -256,9 +223,15 @@ async function send(
   const ack = await st.acks.wait(messageId, ACK_WAIT_MS);
   const refused = ack ? rejection(ack) : undefined;
   if (refused) throw refused;
+  recordSent(st, sock, sent, expiration);
   return messageId;
 }
 
+function recordSent(st: State, sock: WASocket, sent: WAMessage | undefined, expiration?: number): void {
+  if (!sent || st.closed) return;
+  st.history.ingestSent([sent], sock.user?.id ? jidNormalizedUser(sock.user.id) : undefined, expiration);
+}
+
 function quotedOpts(st: State, jid: string, quotedId: string): SendOpts {
   return {
     quoted: {
@@ -300,9 +273,24 @@ async function readProfile(st: State, jid: string): Promise<SenderProfile> {
   };
 }
 
-export function createClient(account: WhatsAppAccount): WAClient {
+async function disconnect(st: State): Promise<void> {
+  st.closed = true;
+  st.openResolve?.();
+  try {
+    st.history.close();
+  } finally {
+    const sock = st.sock;
+    st.sock = undefined;
+    await sock?.end(undefined);
+  }
+}
+
+function initialState(account: WhatsAppAccount, runtime: ClientRuntime): State {
   const st: State = {
     account,
+    runtime,
+    history: createClientHistory(account.id),
+    expiry: new SendExpiry(account.id),
     closed: false,
     openPromise: Promise.resolve(),
     keys: makeKeyCache(),
@@ -311,6 +299,14 @@ export function createClient(account: WhatsAppAccount): WAClient {
     names: makeNameBook(nameFiles.path(account.id)),
   };
   resetGate(st);
+  return st;
+}
+
+export function createClient(
+  account: WhatsAppAccount,
+  runtime: ClientRuntime = { makeSocket: makeWASocket, fetchVersion: fetchLatestWaWebVersion },
+): WAClient {
+  const st = initialState(account, runtime);
   const senders = makeProfileCache<SenderProfile>((jid) => readProfile(st, jid), {
     onError: (jid, err) => process.stderr.write(`whatsapp[${st.account.id}] could not read the profile of ${jid}: ${errMsg(err)}\n`),
   });
@@ -331,6 +327,14 @@ export function createClient(account: WhatsAppAccount): WAClient {
         );
       }
     },
+    read(jid, options) {
+      const page = st.history.read(jid, options);
+      for (const message of page.messages) st.keys.remember(message.key);
+      return Promise.resolve(page);
+    },
+    listMembers(jid, limit) {
+      return listMembers(jid, async (node): Promise<unknown> => await (await ready(st)).query(node), st.names, limit);
+    },
     sendText(jid, text, quotedId) {
       return send(
         st,
@@ -365,6 +369,7 @@ export function createClient(account: WhatsAppAccount): WAClient {
       await send(st, jid, {
         delete: knownKey(st.keys, jid, messageId, true),
       });
+      if (!st.closed) st.history.deleteMessages({ keys: [{ remoteJid: jid, id: messageId }] });
     },
     async reuploadMedia(m) {
       const sock = await ready(st);
@@ -388,13 +393,6 @@ export function createClient(account: WhatsAppAccount): WAClient {
       }
     },
     senderProfile: (jid) => senders.get(jid),
-    async disconnect() {
-      st.closed = true;
-      try {
-        await st.sock?.end(undefined);
-      } catch {
-        st.sock = undefined;
-      }
-    },
+    disconnect: () => st.closing ??= disconnect(st),
   };
 }

package/runtime/node_modules/@metro-labs/whatsapp/src/history-events.ts

@@ -0,0 +1,127 @@
+import { proto, WAMessageStubType, type WAMessage, type WAMessageKey, type WAMessageUpdate } from 'baileys';
+import { clipped, historyContent, historyKey, numberOf, projectMessage } from './history-message.js';
+import { isGroupJid } from './parse.js';
+import { HISTORY_LIMITS, type StoredRow } from './history-types.js';
+import type { HistoryState } from './history-state.js';
+
+const earlierExpiry = (a?: number, b?: number): number | undefined => a === undefined ? b : b === undefined ? a : Math.min(a, b);
+const timestamp = (message: WAMessage): number | undefined => {
+  const seconds = numberOf(message.messageTimestamp);
+  return seconds === undefined ? undefined : seconds * 1000;
+};
+
+function removed(event: WAMessageUpdate): boolean {
+  return event.key.isViewOnce === true || event.update.message === null || event.update.messageStubType === WAMessageStubType.REVOKE;
+}
+
+function acceptedSent(row: StoredRow, sent?: { expiration?: number }): boolean {
+  return !sent || (row.key.fromMe === true && (row.expiresAt !== undefined || sent.expiration === 0));
+}
+
+function editedRow(old: StoredRow, row: StoredRow, revision: number): StoredRow {
+  const expiresAt = earlierExpiry(old.expiresAt, row.expiresAt);
+  return { ...old, ...row, truncated: row.truncated ?? false, editedAt: revision, ...(expiresAt === undefined ? {} : { expiresAt }) };
+}
+
+export class HistoryEvents {
+  constructor(private readonly state: HistoryState) {}
+
+  private author(old: WAMessageKey, editor: WAMessageKey): boolean {
+    if ((old.fromMe === true) !== (editor.fromMe === true)) return false;
+    if (!isGroupJid(old.remoteJid ?? '')) return true;
+    if (old.participant && editor.participant) return this.state.same(old.participant, editor.participant);
+    return old.fromMe === true;
+  }
+
+  private edited(key: WAMessageKey, message: proto.IMessage, revision: number, now: number, selfJid?: string): void {
+    const old = this.state.get(key);
+    if (!old) {
+      this.state.remove(key, now);
+      return;
+    }
+    if (!this.author(old.key, key)) return;
+    const row = projectMessage({ key: old.key, message, messageTimestamp: old.at / 1000 }, now, selfJid);
+    if (row === 'omit') this.state.remove(old.key, now, old.at);
+    if (!row || row === 'omit' || revision > now || revision <= (old.editedAt ?? old.at)) return;
+    this.state.put(editedRow(old, row, revision));
+  }
+
+  private protocol(message: WAMessage, now: number, selfJid?: string): boolean {
+    const protocol = historyContent(message.message).message?.protocolMessage;
+    if (!protocol) return false;
+    if (!protocol.key?.id) return true;
+    if (protocol.key.remoteJid && !this.state.same(protocol.key.remoteJid, message.key.remoteJid ?? '')) return true;
+    const key = historyKey({ ...message.key, id: protocol.key.id });
+    if (key) this.applyProtocol(key, protocol, message, now, selfJid);
+    return true;
+  }
+
+  private applyProtocol(key: WAMessageKey, protocol: proto.Message.IProtocolMessage, message: WAMessage, now: number, selfJid?: string): void {
+    if (protocol.type === proto.Message.ProtocolMessage.Type.REVOKE) this.state.remove(key, now);
+    if (protocol.type === proto.Message.ProtocolMessage.Type.MESSAGE_EDIT && protocol.editedMessage) {
+      const revision = numberOf(protocol.timestampMs) ?? timestamp(message) ?? 0;
+      this.edited(key, protocol.editedMessage, revision, now, selfJid);
+    }
+  }
+
+  ingest(message: WAMessage, now: number, selfJid?: string, sent?: { expiration?: number }): void {
+    if (!historyKey(message.key)) return;
+    const at = timestamp(message);
+    if (at !== undefined && this.state.outside(message.key, at, now)) return;
+    this.state.observe(message.key, now);
+    if (message.messageStubType === WAMessageStubType.REVOKE) {
+      this.state.remove(message.key, now, at);
+      return;
+    }
+    if (!this.protocol(message, now, selfJid)) this.content(message, now, selfJid, sent);
+  }
+
+  private content(message: WAMessage, now: number, selfJid?: string, sent?: { expiration?: number }): void {
+    const row = projectMessage(message, now, selfJid, sent?.expiration);
+    if (row === 'omit') this.state.remove(message.key, now, timestamp(message));
+    if (!row || row === 'omit' || this.state.blocked(row.key, row.at) || !acceptedSent(row, sent)) return;
+    const old = this.state.get(row.key);
+    if (old) this.duplicate(old, row);
+    else this.state.put(row);
+  }
+
+  private duplicate(old: StoredRow, row: StoredRow): void {
+    const expiresAt = earlierExpiry(old.expiresAt, row.expiresAt);
+    if (expiresAt !== undefined) old.expiresAt = expiresAt;
+    if (old.key.fromMe === true && old.senderJid === undefined && row.key.fromMe === true && row.senderJid) old.senderJid = row.senderJid;
+  }
+
+  update(event: WAMessageUpdate, now: number, selfJid?: string): void {
+    const { key, update } = event;
+    if (!historyKey(key)) return;
+    const originalAt = this.state.get(key)?.at ?? timestamp({ ...update, key });
+    if (removed(event) || update.ephemeralDuration || update.ephemeralStartTimestamp) {
+      this.state.remove(key, now, originalAt);
+      return;
+    }
+    this.state.observe(key, now);
+    if (!update.message) return;
+    const full = { ...update, key };
+    if (this.protocol(full, now, selfJid)) return;
+    const revision = timestamp(full);
+    if (revision) this.edited(key, update.message, revision, now, selfJid);
+    else this.refresh(full, now, selfJid);
+  }
+
+  private refresh(message: WAMessage, now: number, selfJid?: string): void {
+    const old = this.state.get(message.key);
+    const row = projectMessage({ ...message, messageTimestamp: old ? old.at / 1000 : undefined }, now, selfJid);
+    if (row === 'omit') this.state.remove(message.key, now, old?.at);
+    else if (row && old) this.duplicate(old, row);
+  }
+
+  edit(jid: string, messageId: string, source: string, now: number): void {
+    const old = this.state.get({ remoteJid: jid, id: messageId });
+    if (!old) {
+      this.state.remove({ remoteJid: jid, id: messageId }, now);
+      return;
+    }
+    const text = clipped(source, HISTORY_LIMITS.textBytes);
+    this.state.put({ ...old, text, truncated: text !== source, editedAt: now });
+  }
+}

package/runtime/node_modules/@metro-labs/whatsapp/src/history-files.ts

@@ -0,0 +1,39 @@
+import { readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { accountFiles, type AccountFiles } from '@metro-labs/core/stations/account-files';
+import { isRecord } from '@metro-labs/core/is-record';
+
+const files = accountFiles('WHATSAPP_TOKEN_DIR', 'whatsapp-history-');
+const TEMP_NAME = /^(whatsapp-history-[A-Za-z0-9_-]*\.json)\.tmp-[1-9]\d*$/;
+
+function cleanTemps(dir: string, remove: (name: string) => boolean): void {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch (err) {
+    if (isRecord(err) && err.code === 'ENOENT') return;
+    throw err;
+  }
+  for (const name of names) {
+    const original = TEMP_NAME.exec(name)?.[1];
+    if (original && remove(original)) rmSync(join(dir, name), { force: true });
+  }
+}
+
+export function clearHistoryTemps(path: string): void {
+  const name = basename(path);
+  cleanTemps(dirname(path), (original) => original === name);
+}
+
+export const historyFiles: AccountFiles = {
+  path: files.path,
+  forget(accountId) {
+    files.forget(accountId);
+    clearHistoryTemps(files.path(accountId));
+  },
+  forgetExcept(keptAccountIds) {
+    files.forgetExcept(keptAccountIds);
+    const kept = new Set(keptAccountIds.map((id) => basename(files.path(id))));
+    cleanTemps(dirname(files.path('')), (original) => !kept.has(original));
+  },
+};

package/runtime/node_modules/@metro-labs/whatsapp/src/history-identity.ts

@@ -0,0 +1,58 @@
+import { jidNormalizedUser, type WAMessageKey } from 'baileys';
+import { TrainError } from '@metro-labs/core/train-error';
+import { HISTORY_LIMITS } from './history-types.js';
+
+export const normalizedJid = (jid: string): string => jidNormalizedUser(jid);
+const phone = (jid: string): boolean => jid.endsWith('@s.whatsapp.net');
+const lid = (jid: string): boolean => jid.endsWith('@lid');
+const identity = (v: unknown): v is string => typeof v === 'string' && v.length <= 256 && (phone(v) || lid(v));
+const invalid = (): never => { throw new TrainError('whatsapp_history_invalid', 'WhatsApp history aliases are invalid; refusing to discard replay protection'); };
+
+export class HistoryIdentity {
+  private readonly groups = new Map<string, readonly string[]>();
+
+  constructor(value: unknown = []) {
+    if (!Array.isArray(value)) return invalid();
+    for (const group of value) this.restore(group);
+    if (this.groups.size > HISTORY_LIMITS.aliases) return invalid();
+  }
+
+  private restore(group: unknown): void {
+    if (!Array.isArray(group) || !group.every(identity)) return invalid();
+    const pn = group.find(phone);
+    const alternate = group.find(lid);
+    if (!pn || !alternate) return invalid();
+    for (const jid of group) this.alias(jid, phone(jid) ? alternate : pn);
+  }
+
+  get size(): number { return this.groups.size; }
+
+  known(jid: string): readonly string[] {
+    const normalized = normalizedJid(jid);
+    return this.groups.get(normalized) ?? [normalized];
+  }
+
+  canonical(jid: string): string { return this.known(jid)[0] ?? normalizedJid(jid); }
+
+  same(left: string, right: string): boolean { return this.canonical(left) === this.canonical(right); }
+
+  alias(left: string, right: string): boolean {
+    if (!identity(left) || !identity(right)) return false;
+    const a = normalizedJid(left);
+    const b = normalizedJid(right);
+    if (phone(a) === phone(b) || this.same(a, b)) return false;
+    const group = [...new Set([...this.known(a), ...this.known(b)])].sort();
+    for (const jid of group) this.groups.set(jid, group);
+    return true;
+  }
+
+  remember(key: WAMessageKey): boolean {
+    const chat = this.alias(key.remoteJid ?? '', key.remoteJidAlt ?? '');
+    const sender = this.alias(key.participant ?? '', key.participantAlt ?? '');
+    return chat || sender;
+  }
+
+  clear(): void { this.groups.clear(); }
+
+  serialize(): readonly (readonly string[])[] { return [...new Set(this.groups.values())]; }
+}