@stage-labs/metro 0.1.0-beta.276 → 0.1.0-beta.277

package/runtime/node_modules/@metro-labs/telegram-bot/src/observed-chats.ts

@@ -0,0 +1,172 @@
+import { readFileSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import {
+  DIRECTORY_LIMIT,
+  type ChannelEntry,
+  type ChannelSnapshot,
+} from '@metro-labs/core/stations/channel-directory';
+import { lineOf } from './accounts.js';
+import type { TgChat, TgMsg, TgMyChatMember, TgUpdate } from './types.js';
+
+type Metadata = Omit<ChannelEntry, 'line'>;
+
+const kinds = new Set(['direct', 'group', 'channel', 'thread']);
+const chatId = (id: number): boolean => Number.isSafeInteger(id) && id !== 0;
+const cleanName = (name: string | undefined): string | undefined =>
+  name?.trim() ? Array.from(name.trim()).slice(0, 256).join('') : undefined;
+
+function kindOf(chat: TgChat): Metadata['kind'] | undefined {
+  if (chat.type === 'private') return 'direct';
+  if (chat.type === 'group' || chat.type === 'supergroup') return 'group';
+  if (chat.type === 'channel') return 'channel';
+  return undefined;
+}
+
+function metadataOf(raw: unknown): Metadata | undefined {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || typeof raw.kind !== 'string') return undefined;
+  if (!/^-?[1-9]\d*(\/[1-9]\d*)?$/.test(raw.id) || !kinds.has(raw.kind)) return undefined;
+  const parts = raw.id.split('/').map(Number);
+  if (!parts.every(chatId) || (raw.kind === 'thread') !== (parts.length === 2)) return undefined;
+  const name = typeof raw.name === 'string' ? cleanName(raw.name) : undefined;
+  return { id: raw.id, kind: raw.kind as Metadata['kind'], ...(name ? { name } : {}) };
+}
+
+function savedMetadata(account: string, file: string): unknown[] {
+  const raw: unknown = JSON.parse(readFileSync(file, 'utf8'));
+  if (!isRecord(raw) || raw.version !== 1 || raw.account !== account || !Array.isArray(raw.channels))
+    throw new Error('invalid observed chat metadata');
+  return raw.channels.slice(-DIRECTORY_LIMIT);
+}
+
+function topicIdOf(message: TgMsg): number | undefined {
+  if (!message.is_topic_message || message.chat.type !== 'supergroup' || !chatId(message.chat.id)) return undefined;
+  const id = message.message_thread_id;
+  return id !== undefined && Number.isSafeInteger(id) && id > 0 ? id : undefined;
+}
+
+function loaded(account: string, file: string | undefined): Map<string, Metadata> {
+  const entries = new Map<string, Metadata>();
+  if (file === undefined) return entries;
+  try {
+    for (const value of savedMetadata(account, file)) {
+      const entry = metadataOf(value);
+      if (entry) entries.set(entry.id, entry);
+    }
+  } catch (err) {
+    if (!isRecord(err) || err.code !== 'ENOENT')
+      log.warn({ account, err: errMsg(err) }, 'telegram-bot: could not load observed chats');
+  }
+  return entries;
+}
+
+export class ObservedChats {
+  private readonly entries: Map<string, Metadata>;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(private readonly account: string, private readonly file?: string) {
+    this.entries = loaded(account, file);
+  }
+
+  snapshot(): ChannelSnapshot {
+    const channels = [...this.entries.values()].map((entry) => {
+      const [chat, topic] = entry.id.split('/');
+      return { ...entry, line: lineOf(this.account, chat ?? '', topic === undefined ? undefined : Number(topic)) };
+    });
+    return {
+      channels,
+      capability: {
+        supported: true,
+        complete: false,
+        source: 'local',
+        reason: `Telegram Bot API has no all-chats API. Only chat and topic metadata observed in updates on this box is available, up to ${DIRECTORY_LIMIT} entries; unobserved chats and missed updates are not included.`,
+      },
+    };
+  }
+
+  observe(update: TgUpdate): void {
+    for (const message of [update.message, update.channel_post])
+      if (message) this.message(message);
+    for (const event of [update.message_reaction, update.message_reaction_count])
+      if (event) this.chat(event.chat);
+    if (update.my_chat_member) this.membership(update.my_chat_member);
+  }
+
+  flush(): void {
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    this.timer = undefined;
+    if (this.file === undefined) return;
+    writeSecure(this.file, JSON.stringify({ version: 1, account: this.account, channels: [...this.entries.values()] }));
+  }
+
+  private changed(): void {
+    if (this.file === undefined || this.timer !== undefined) return;
+    this.timer = setTimeout(() => {
+      try {
+        this.flush();
+      } catch (err) {
+        log.warn({ account: this.account, err: errMsg(err) }, 'telegram-bot: could not save observed chats');
+      }
+    }, 2000);
+    this.timer.unref();
+  }
+
+  private note(entry: Metadata): void {
+    const previous = this.entries.get(entry.id);
+    const name = entry.name ?? previous?.name;
+    this.entries.delete(entry.id);
+    this.entries.set(entry.id, { id: entry.id, kind: entry.kind, ...(name ? { name } : {}) });
+    if (this.entries.size > DIRECTORY_LIMIT) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest !== undefined) this.entries.delete(oldest);
+    }
+    if (!previous || previous.name !== name || previous.kind !== entry.kind) this.changed();
+  }
+
+  private remove(id: number): void {
+    for (const key of this.entries.keys()) {
+      if (key === String(id) || key.startsWith(`${id}/`)) {
+        this.entries.delete(key);
+        this.changed();
+      }
+    }
+  }
+
+  private chat(chat: TgChat): void {
+    const kind = kindOf(chat);
+    if (!chatId(chat.id) || kind === undefined) return;
+    const name = cleanName(kind === 'direct'
+      ? [chat.first_name, chat.last_name].map((part) => part?.trim()).filter(Boolean).join(' ') || (chat.username ? `@${chat.username}` : undefined)
+      : chat.title);
+    this.note({ id: String(chat.id), kind, ...(name ? { name } : {}) });
+  }
+
+  private message(message: TgMsg): void {
+    if (message.migrate_to_chat_id !== undefined && chatId(message.migrate_to_chat_id)) {
+      this.remove(message.chat.id);
+      this.chat({ ...message.chat, id: message.migrate_to_chat_id, type: 'supergroup' });
+      return;
+    }
+    if (message.migrate_from_chat_id !== undefined && chatId(message.migrate_from_chat_id))
+      this.remove(message.migrate_from_chat_id);
+    this.chat(message.chat);
+    this.topic(message);
+  }
+
+  private topic(message: TgMsg): void {
+    const topic = topicIdOf(message);
+    if (topic === undefined) return;
+    const name = cleanName(message.forum_topic_edited?.name ?? message.forum_topic_created?.name);
+    this.note({ id: `${message.chat.id}/${topic}`, kind: 'thread', ...(name ? { name } : {}) });
+  }
+
+  private membership(update: TgMyChatMember): void {
+    const { status, is_member: isMember } = update.new_chat_member;
+    if (status === 'left' || status === 'kicked' || (status === 'restricted' && isMember === false))
+      this.remove(update.chat.id);
+    else if (status === 'creator' || status === 'administrator' || status === 'member'
+      || (status === 'restricted' && isMember === true))
+      this.chat(update.chat);
+  }
+}

package/runtime/node_modules/@metro-labs/telegram-bot/src/station.ts

@@ -1,10 +1,14 @@
 import type { Station, Verb } from '@metro-labs/core/stations/types';
 import { PROFILE_FIELDS, type ProfileField } from '@metro-labs/core/stations/profile';
+import { channelFiles } from './channel-files.js';
 
 export const telegramBotStation: Station = {
   name: 'telegram-bot',
   hasAccounts: true,
   hasTrain: true,
+  discoversChannels: true,
+  forget: channelFiles.forget,
+  forgetExcept: channelFiles.forgetExcept,
   messageVerbs: new Set<Verb>([
     'send',
     'reply',

package/runtime/node_modules/@metro-labs/telegram-bot/src/types.ts

@@ -13,18 +13,45 @@ export interface TgUser {
   is_bot?: boolean;
 }
 
+export interface TgChat {
+  id: number;
+  type: string;
+  title?: string;
+  first_name?: string;
+  last_name?: string;
+  username?: string;
+}
+
+export interface TgMyChatMember {
+  chat: TgChat;
+  new_chat_member: { status: string; is_member?: boolean };
+}
+
+export interface TgUpdate {
+  update_id: number;
+  message?: TgMsg;
+  channel_post?: TgMsg;
+  my_chat_member?: TgMyChatMember;
+  message_reaction?: TgReaction;
+  message_reaction_count?: TgReactionCount;
+}
+
 export interface TgMsg {
   entities?: TgEntity[];
   caption_entities?: TgEntity[];
   reply_to_message?: { message_id: number; from?: { id: number; username?: string; is_bot?: boolean } };
   message_id: number;
   date: number;
-  chat: { id: number; type: string; title?: string; first_name?: string };
+  chat: TgChat;
   from?: TgUser;
   text?: string;
   caption?: string;
   message_thread_id?: number;
   is_topic_message?: boolean;
+  forum_topic_created?: { name: string };
+  forum_topic_edited?: { name?: string };
+  migrate_to_chat_id?: number;
+  migrate_from_chat_id?: number;
   photo?: { file_id: string; file_size?: number }[];
   document?: { file_name?: string; file_id?: string; mime_type?: string };
   voice?: { file_id?: string; duration?: number; mime_type?: string };
@@ -37,7 +64,7 @@ export interface TgMsg {
 }
 
 export interface TgReaction {
-  chat: { id: number; type: string };
+  chat: TgChat;
   message_id: number;
   user?: TgUser;
   date: number;
@@ -46,7 +73,7 @@ export interface TgReaction {
 }
 
 export interface TgReactionCount {
-  chat: { id: number; type: string };
+  chat: TgChat;
   message_id: number;
   date: number;
   reactions: {

package/runtime/node_modules/@metro-labs/telegram-bot/src/updates.ts

@@ -0,0 +1,26 @@
+import { emitInbound } from '@metro-labs/core/stations/train-events';
+import { observeChannels } from './channels.js';
+import {
+  envelope,
+  reactionCountEnvelope,
+  reactionEnvelope,
+  saveMediaAndEmit,
+} from './format.js';
+import type { TgUpdate } from './types.js';
+
+export function handleUpdate(id: string, update: TgUpdate): void {
+  observeChannels(id, update);
+  if (update.message && !update.message.from?.is_bot) {
+    const env = envelope(id, update.message);
+    emitInbound(id, env);
+    saveMediaAndEmit(id, update.message, env.id as string);
+  }
+  if (update.message_reaction) {
+    const env = reactionEnvelope(id, update.message_reaction);
+    if (env) emitInbound(id, env);
+  }
+  if (update.message_reaction_count) {
+    const env = reactionCountEnvelope(id, update.message_reaction_count);
+    if (env) emitInbound(id, env);
+  }
+}

package/runtime/node_modules/@metro-labs/threema/src/accounts.ts

@@ -4,6 +4,8 @@ import {
   type Die,
 } from '@metro-labs/core/stations/account-store';
 import { Line } from '@metro-labs/core/lines';
+import { ChannelDirectory } from '@metro-labs/core/stations/channel-directory';
+import { DirectStore } from './chats.js';
 import { fetchPublicKey } from './api.js';
 import { hexToBytes, keyPairFrom, type KeyPair } from './crypto.js';
 import { isGatewayId, normalizeThreemaId, parsePrivateKey } from './ids.js';
@@ -47,6 +49,8 @@ export interface Account {
   publicKeys: Map<string, Uint8Array>;
   requestedRosters: Set<string>;
   groups: GroupStore;
+  chats: DirectStore;
+  directory: ChannelDirectory;
 }
 
 export type Target = { kind: 'user'; id: string } | { kind: 'group'; group: GroupRef };
@@ -56,7 +60,15 @@ export const accounts = new Map<string, Account>();
 export function bootAccount(cfg: AccountConfig): Account {
   const key = parsePrivateKey(cfg.privateKey);
   if (key === null) throw new Error(`account '${cfg.id}' has no usable private key`);
-  return { cfg, keys: keyPairFrom(key), publicKeys: new Map(), requestedRosters: new Set(), groups: new GroupStore(cfg.id, cfg.gatewayId) };
+  return {
+    cfg,
+    keys: keyPairFrom(key),
+    publicKeys: new Map(),
+    requestedRosters: new Set(),
+    groups: new GroupStore(cfg.id, cfg.gatewayId),
+    chats: new DirectStore(cfg.id),
+    directory: new ChannelDirectory(),
+  };
 }
 
 export function accountFor(id: string): Account {

package/runtime/node_modules/@metro-labs/threema/src/actions.ts

@@ -7,6 +7,7 @@ import {
 import { messagingAliases } from '@metro-labs/core/stations/messaging-normalize';
 import { accountFor, accounts, publicKeyFor, targetOf, type Account } from './accounts.js';
 import { hexToBytes, macMatches, open } from './crypto.js';
+import { listChannels } from './channels.js';
 import { groupLineOf, type InboundMeta } from './format.js';
 import { groupKey } from './groups.js';
 import { deliver } from './inbound.js';
@@ -119,6 +120,11 @@ async function callback(id: string, args: Args): Promise<void> {
 }
 
 export const handleCall = makeStation({
-  handlers: { accounts: listAccounts, send, react, callback, listMembers },
+  handlers: {
+    accounts: listAccounts, send, react, callback, listMembers,
+    async listChannels(id, args) {
+      respond(id, { result: await listChannels(args) });
+    },
+  },
   normalize: messagingAliases({ action: 'removed' }),
 });

package/runtime/node_modules/@metro-labs/threema/src/channels.ts

@@ -0,0 +1,37 @@
+import { TrainError } from '@metro-labs/core/train-error';
+import { DIRECTORY_LIMIT, type ChannelList, type ChannelSnapshot } from '@metro-labs/core/stations/channel-directory';
+import { accountFor, type Account } from './accounts.js';
+import { groupLineOf, lineOf } from './format.js';
+import { groupKey, parseGroupKey } from './groups.js';
+
+function snapshot(acct: Account): ChannelSnapshot {
+  return {
+    channels: [
+      ...acct.groups.list().slice(0, DIRECTORY_LIMIT + 1).filter((group) => parseGroupKey(groupKey(group)) !== null).map((group) => ({
+        id: groupKey(group),
+        line: groupLineOf(acct.cfg.id, group),
+        kind: 'group' as const,
+        ...(group.name ? { name: Array.from(group.name).slice(0, 256).join('') } : {}),
+      })),
+      ...acct.chats.list().map((chat) => ({
+        id: chat.id,
+        line: lineOf(acct.cfg.id, chat.id),
+        kind: 'direct' as const,
+        ...(chat.name ? { name: chat.name } : {}),
+      })),
+    ],
+    capability: {
+      supported: true,
+      complete: false,
+      source: 'local',
+      reason: `Threema Gateway has no remote conversation-list or history endpoint. Only locally stored groups and up to ${DIRECTORY_LIMIT} observed direct chats are listed; conversations not observed by this Metro are unavailable.`,
+    },
+  };
+}
+
+export function listChannels(args: Record<string, unknown>): Promise<ChannelList> {
+  if (typeof args.account !== 'string' || !args.account.trim())
+    throw new TrainError('bad_request', 'listChannels requires an explicit Threema account');
+  const acct = accountFor(args.account);
+  return acct.directory.list(acct.cfg.id, args, () => Promise.resolve(snapshot(acct)));
+}

package/runtime/node_modules/@metro-labs/threema/src/chats.ts

@@ -0,0 +1,88 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { log } from '@metro-labs/core/log';
+import { accountFiles } from '@metro-labs/core/stations/account-files';
+import { DIRECTORY_LIMIT } from '@metro-labs/core/stations/channel-directory';
+import { isThreemaId, normalizeThreemaId } from './ids.js';
+
+interface DirectChat {
+  id: string;
+  name?: string;
+}
+
+export const chatFiles = accountFiles('THREEMA_GROUPS_DIR', 'threema-chats-');
+
+const nameOf = (name: unknown): string | undefined =>
+  typeof name === 'string' ? Array.from(name.trim()).slice(0, 256).join('') || undefined : undefined;
+
+function directChat(entry: unknown): DirectChat | undefined {
+  if (!entry || typeof entry !== 'object' || !('id' in entry) || typeof entry.id !== 'string') return undefined;
+  const id = normalizeThreemaId(entry.id);
+  if (!isThreemaId(id)) return undefined;
+  const name = nameOf('name' in entry ? entry.name : undefined);
+  return { id, ...(name ? { name } : {}) };
+}
+
+function readChats(path: string): Map<string, DirectChat> {
+  try {
+    if (statSync(path).size > DIRECTORY_LIMIT * 2048) throw new Error('Threema chat metadata is too large');
+    const raw: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    const chats = new Map<string, DirectChat>();
+    if (!Array.isArray(raw)) throw new Error('Threema chat metadata must be an array');
+    for (const entry of raw.slice(-DIRECTORY_LIMIT)) {
+      const chat = directChat(entry);
+      if (chat) chats.set(chat.id, chat);
+    }
+    return chats;
+  } catch (err) {
+    if (!(err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT'))
+      log.warn({ err, path }, 'threema: could not load chat metadata');
+    return new Map();
+  }
+}
+
+export class DirectStore {
+  private readonly path: string;
+  private readonly chats: Map<string, DirectChat>;
+
+  constructor(accountId: string) {
+    this.path = chatFiles.path(accountId);
+    this.chats = readChats(this.path);
+  }
+
+  list(): DirectChat[] {
+    return [...this.chats.values()].map((chat) => ({ ...chat }));
+  }
+
+  note(rawId: string, rawName?: string): void {
+    const id = normalizeThreemaId(rawId);
+    if (!isThreemaId(id)) return;
+    const previous = this.chats.get(id);
+    const name = nameOf(rawName) ?? previous?.name;
+    if (previous && name === previous.name) return;
+    this.chats.delete(id);
+    this.chats.set(id, { id, ...(name ? { name } : {}) });
+    while (this.chats.size > DIRECTORY_LIMIT) {
+      const oldest = this.chats.keys().next();
+      if (oldest.done) break;
+      this.chats.delete(oldest.value);
+    }
+    this.save();
+  }
+
+  private save(): void {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      const tmp = `${this.path}.${randomUUID()}.tmp`;
+      try {
+        writeFileSync(tmp, JSON.stringify(this.list()), { mode: 0o600, flag: 'wx' });
+        renameSync(tmp, this.path);
+      } finally {
+        rmSync(tmp, { force: true });
+      }
+    } catch (err) {
+      log.warn({ err, path: this.path }, 'threema: could not save chat metadata');
+    }
+  }
+}

package/runtime/node_modules/@metro-labs/threema/src/inbound.ts

@@ -76,7 +76,12 @@ function chat(acct: Account, m: InboundMeta, d: Decoded): string | null {
   return null;
 }
 
+function isDirectChat(d: Decoded): boolean {
+  return d.kind === 'text' || ((d.kind === 'file' || d.kind === 'reaction' || d.kind === 'receipt') && d.group === null);
+}
+
 export function deliver(acct: Account, m: InboundMeta, d: Decoded): string {
+  if (isDirectChat(d)) acct.chats.note(m.from, m.nickname);
   const handled = control(acct, m, d) ?? chat(acct, m, d);
   if (handled !== null) return handled;
   if (d.kind === 'receipt') return reactions(acct, m, d);

package/runtime/node_modules/@metro-labs/threema/src/outbound.ts

@@ -37,6 +37,7 @@ async function deliver(acct: Account, to: string, plain: Uint8Array, group: bool
   const { nonce, box } = seal(plain, await publicKeyFor(acct, to), acct.keys);
   const messageId = await sendE2E(acct.cfg, to, bytesToHex(nonce), bytesToHex(box), group);
   noteSent(messageId);
+  if (!group) acct.chats.note(to);
   return messageId;
 }
 

package/runtime/node_modules/@metro-labs/threema/src/station.ts

@@ -1,13 +1,21 @@
 import type { Station, Verb } from '@metro-labs/core/stations/types';
 import { groupFiles } from './groups.js';
+import { chatFiles } from './chats.js';
 
 export const threemaStation: Station = {
   name: 'threema',
   hasAccounts: true,
   hasTrain: true,
+  discoversChannels: true,
   messageVerbs: new Set<Verb>(['send', 'reply', 'react', 'unreact']),
   attachmentMode: 'canonical',
-  forget: groupFiles.forget,
-  forgetExcept: groupFiles.forgetExcept,
+  forget(accountId) {
+    groupFiles.forget(accountId);
+    chatFiles.forget(accountId);
+  },
+  forgetExcept(accountIds) {
+    groupFiles.forgetExcept(accountIds);
+    chatFiles.forgetExcept(accountIds);
+  },
   tools: [],
 };

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

@@ -138,6 +138,16 @@ function makeRead(clientFor: ClientFor): StationHandler {
   };
 }
 
+function makeListChannels(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const account = str(args.account);
+    if (!account) throw new TrainError('bad_request', 'listChannels requires an account');
+    const accountId = accountFor({ account });
+    const result = await guard(() => clientFor(accountId).listChannels(args));
+    respond(id, { result });
+  };
+}
+
 function makeListMembers(clientFor: ClientFor): StationHandler {
   return async (id, args) => {
     const { client, jid } = resolve({ line: args.line }, clientFor);
@@ -239,6 +249,7 @@ export function makeHandleCall(
       send: makeSend(clientFor),
       read: makeRead(clientFor),
       listMembers: makeListMembers(clientFor),
+      listChannels: makeListChannels(clientFor),
       react: makeReact(clientFor),
       typing: makeTyping(clientFor),
       edit: makeEdit(clientFor),

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

@@ -0,0 +1,137 @@
+import { readFileSync, statSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import { accountFiles } from '@metro-labs/core/stations/account-files';
+import { DIRECTORY_LIMIT, type ChannelEntry } from '@metro-labs/core/stations/channel-directory';
+import { lineOf } from './accounts.js';
+
+export const channelFiles = accountFiles('WHATSAPP_TOKEN_DIR', 'whatsapp-channels-');
+const FILE_BYTES = 16 * 1024 * 1024;
+const NAME_LIMIT = 256;
+
+interface ChatMetadata {
+  id?: string | null;
+  name?: string | null;
+  conversationTimestamp?: number | { toNumber(): number } | null;
+}
+
+interface StoredChat {
+  id: string;
+  name?: string;
+  deleted?: true;
+  deletedAt?: number;
+}
+
+function directId(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value.length > 128 || !/^\d+(?::\d+)?@(s\.whatsapp\.net|lid)$/.test(value)) return undefined;
+  return value.replace(/:\d+@/, '@');
+}
+
+export function channelName(value: unknown): string | undefined {
+  return typeof value === 'string' ? value.trim().slice(0, NAME_LIMIT) || undefined : undefined;
+}
+
+function deletionTime(value: unknown): number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : Date.now();
+}
+
+function newerActivity(chat: ChatMetadata, deletedAt: number): boolean {
+  const value = chat.conversationTimestamp;
+  const seconds = typeof value === 'number' ? value : value?.toNumber();
+  if (seconds === undefined || !Number.isSafeInteger(seconds)) return false;
+  const at = seconds * 1000;
+  return at > deletedAt && at <= Date.now();
+}
+
+function blocked(chat: ChatMetadata, prior: StoredChat | undefined, fresh: boolean): boolean {
+  return prior?.deleted === true && (!fresh || !newerActivity(chat, deletionTime(prior.deletedAt)));
+}
+
+function storedChat(row: unknown): StoredChat | undefined {
+  if (!isRecord(row)) return undefined;
+  const id = directId(row.id);
+  if (!id) return undefined;
+  return row.deleted === true
+    ? { id, deleted: true, deletedAt: deletionTime(row.deletedAt) }
+    : { id, name: channelName(row.name) };
+}
+
+export class KnownChats {
+  private readonly chats = new Map<string, StoredChat>();
+  private readonly file: string;
+
+  constructor(private readonly accountId: string) {
+    this.file = channelFiles.path(accountId);
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      if (statSync(this.file).size > FILE_BYTES) throw new Error('channel metadata file is too large');
+      const raw: unknown = JSON.parse(readFileSync(this.file, 'utf8'));
+      if (!Array.isArray(raw)) throw new Error('invalid channel metadata');
+      for (const row of raw.slice(-DIRECTORY_LIMIT)) {
+        const chat = storedChat(row);
+        if (chat) this.put(chat);
+      }
+    } catch (err) {
+      if (isRecord(err) && err.code === 'ENOENT') return;
+      log.warn({ accountId: this.accountId, err: errMsg(err) }, 'whatsapp: could not load channel metadata');
+    }
+  }
+
+  private put(row: StoredChat): void {
+    this.chats.delete(row.id);
+    this.chats.set(row.id, row);
+    if (this.chats.size > DIRECTORY_LIMIT) {
+      const oldest = this.chats.keys().next().value;
+      if (oldest !== undefined) this.chats.delete(oldest);
+    }
+  }
+
+  private save(): void {
+    try {
+      writeSecure(this.file, JSON.stringify([...this.chats.values()]));
+    } catch (err) {
+      log.warn({ accountId: this.accountId, err: errMsg(err) }, 'whatsapp: could not save channel metadata');
+    }
+  }
+
+  private noteChat(chat: ChatMetadata, fresh: boolean): boolean {
+    const id = directId(chat.id);
+    if (!id) return false;
+    const prior = this.chats.get(id);
+    if (blocked(chat, prior, fresh)) return false;
+    const name = channelName(chat.name) ?? prior?.name;
+    if (prior && !prior.deleted && prior.name === name) return false;
+    this.put({ id, name });
+    return true;
+  }
+
+  note(chats: readonly ChatMetadata[], fresh = false): void {
+    let changed = false;
+    for (const chat of chats) {
+      if (this.noteChat(chat, fresh)) changed = true;
+    }
+    if (changed) this.save();
+  }
+
+  remove(ids: readonly string[]): void {
+    let changed = false;
+    for (const value of ids) {
+      const id = directId(value);
+      if (!id) continue;
+      const deletedAt = Math.max(Date.now(), this.chats.get(id)?.deletedAt ?? 0);
+      this.put({ id, deleted: true, deletedAt });
+      changed = true;
+    }
+    if (changed) this.save();
+  }
+
+  list(): ChannelEntry[] {
+    return [...this.chats.values()].filter((chat) => !chat.deleted).map(({ id, name }) => ({
+      id, line: lineOf(this.accountId, id), kind: 'direct', ...(name ? { name } : {}),
+    }));
+  }
+}