@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.321

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

@@ -1,40 +1,7 @@
-import { TrainError } from '@metro-labs/mcp/train-error';
-import { errMsg } from '@metro-labs/mcp/log';
-import { readCalls } from '@metro-labs/mcp/trains/protocol';
-import { accounts, loadAccounts, accountFor, lineOf, targetOf } from './accounts.js';
-import { createClient, type WAClient } from './client.js';
+import { runClientTrain } from '@metro-labs/core/stations/train-boot';
+import { accounts, loadAccounts } from './accounts.js';
+import { createClient } from './client.js';
 import { startInbound } from './inbound.js';
 import { makeHandleCall } from './actions.js';
 
-const clients = new Map<string, WAClient>();
-
-function clientFor(accountId: string): WAClient {
-  let client = clients.get(accountId);
-  if (!client) {
-    const account = accounts.get(accountId);
-    if (!account)
-      throw new TrainError('not_implemented', `unknown account '${accountId}'`);
-    client = createClient(account);
-    clients.set(accountId, client);
-  }
-  return client;
-}
-
-const handleCall = makeHandleCall(clientFor);
-
-readCalls('whatsapp', handleCall);
-
-function boot(): void {
-  for (const cfg of loadAccounts()) accounts.set(cfg.id, cfg);
-  for (const id of accounts.keys())
-    startInbound(clientFor(id)).catch((err: unknown) => {
-      process.stderr.write(`whatsapp[${id}] inbound failed: ${errMsg(err)}\n`);
-    });
-  process.stderr.write(
-    `whatsapp train ready (inbound+outbound) — ${accounts.size} account(s): ${[...accounts.keys()].join(', ')}\n`,
-  );
-}
-
-boot();
-
-export { clients, accounts, clientFor, accountFor, lineOf, targetOf };
+runClientTrain({ station: 'whatsapp', accounts, loadAccounts, createClient, startInbound, makeHandleCall, disconnectClient: (client) => client.disconnect() });

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

@@ -1,4 +1,4 @@
-import { TrainError } from '@metro-labs/mcp/train-error';
+import { TrainError } from '@metro-labs/core/train-error';
 import type { WAMessageKey } from 'baileys';
 import { isGroupJid } from './parse.js';
 

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

@@ -4,8 +4,9 @@ import makeWASocket, {
   fetchLatestWaWebVersion,
   type WASocket,
 } from 'baileys';
-import { errMsg, log } from '@metro-labs/mcp/log';
+import { errMsg, log } from '@metro-labs/core/log';
 import { inMemoryAuthState } from './auth-state.js';
+import type { ClientRuntime } from './client-types.js';
 
 export class WhatsappLoginError extends Error {}
 
@@ -32,6 +33,13 @@ export function normalizePhone(raw: unknown): string {
   return phone;
 }
 
+export function assertSamePhone(phone: string, expect: string): void {
+  if (expect !== '' && phone !== '' && phone !== expect)
+    throw new WhatsappLoginError(
+      `This channel is +${expect}. Pair it again with that number, or add a new channel for +${phone}.`,
+    );
+}
+
 function closeReason(err: unknown): number | undefined {
   return (err as { output?: { statusCode?: number } } | undefined)?.output
     ?.statusCode;
@@ -47,14 +55,18 @@ export class WhatsappLogin {
   constructor(
     private phone: string,
     private events: WhatsappLoginEvents,
-  ) {}
+    private expect = '',
+    private runtime: ClientRuntime = { makeSocket: makeWASocket, fetchVersion: fetchLatestWaWebVersion },
+  ) {
+    assertSamePhone(phone, expect);
+  }
 
   get mode(): 'pairing-code' | 'qr' {
     return this.phone === '' ? 'qr' : 'pairing-code';
   }
 
   async start(): Promise<void> {
-    const { version, error } = await fetchLatestWaWebVersion({});
+    const { version, error } = await this.runtime.fetchVersion({});
     if (error)
       throw new WhatsappLoginError(
         'could not reach WhatsApp to start the pairing',
@@ -64,7 +76,7 @@ export class WhatsappLogin {
 
   private open(version: [number, number, number]): void {
     if (this.settled) return;
-    const sock = makeWASocket({
+    const sock = this.runtime.makeSocket({
       version,
       auth: this.auth.state,
       browser: Browsers.macOS('Safari'),
@@ -131,6 +143,10 @@ export class WhatsappLogin {
       );
       return;
     }
+    if (this.expect !== '' && phone !== this.expect) {
+      this.refuseOther(phone);
+      return;
+    }
     const credentials = this.auth.serialize();
     this.settled = true;
     this.closeSocket()
@@ -145,6 +161,23 @@ export class WhatsappLogin {
       });
   }
 
+  private refuseOther(phone: string): void {
+    this.settled = true;
+    const sock = this.sock;
+    const message = `You linked +${phone}, but this channel is +${this.expect}. Nothing was changed. Scan the code with the phone of +${this.expect}.`;
+    (sock === null ? Promise.resolve() : sock.logout('Metro: another phone than the channel'))
+      .catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'whatsapp login: could not unlink the other phone');
+      })
+      .then(() => this.closeSocket())
+      .then(() => {
+        this.events.onFailed(message);
+      })
+      .catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'whatsapp login: failure report failed');
+      });
+  }
+
   private fail(message: string): void {
     if (this.settled) return;
     this.settled = true;

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

@@ -1,5 +1,5 @@
 import type { proto } from 'baileys';
-import { extFromMime } from '@metro-labs/mcp/stations/attachments';
+import { extFromMime } from '@metro-labs/core/stations/attachments';
 
 export type WAMediaKind =
   | 'image'

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

@@ -0,0 +1,94 @@
+import { getBinaryNodeChild, type BinaryNode, type GroupParticipant } from 'baileys';
+import { extractGroupMetadata } from 'baileys/lib/Socket/groups.js';
+import { TrainError } from '@metro-labs/core/train-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { MemberCapability, MemberList, MetroMember } from '@metro-labs/core/stations/types';
+import { isGroupJid } from './parse.js';
+import { phoneOf, type NameBook } from './names.js';
+
+interface WhatsAppMember extends MetroMember {
+  lid?: string;
+  phoneNumber?: string;
+}
+
+function memberName(p: GroupParticipant, names: NameBook): string | undefined {
+  return names.get(p.id) ?? p.name ?? p.notify
+    ?? (p.lid ? names.get(p.lid) : undefined)
+    ?? (p.phoneNumber ? names.get(p.phoneNumber) : undefined);
+}
+
+function memberRole(p: GroupParticipant): string | undefined {
+  return p.admin ?? (p.isSuperAdmin ? 'superadmin' : p.isAdmin ? 'admin' : undefined);
+}
+
+function memberOf(p: GroupParticipant, names: NameBook): WhatsAppMember {
+  const lid = p.id.endsWith('@lid') ? p.id : p.lid;
+  const phoneNumber = p.id.endsWith('@s.whatsapp.net') ? p.id : p.phoneNumber;
+  const displayName = memberName(p, names);
+  const address = phoneOf(phoneNumber);
+  const role = memberRole(p);
+  return {
+    id: p.id,
+    ...(displayName ? { display_name: displayName } : {}),
+    ...(lid ? { lid } : {}),
+    ...(phoneNumber ? { phoneNumber } : {}),
+    ...(address ? { address } : {}),
+    roles: role ? [role] : [],
+    is_admin: role === 'admin' || role === 'superadmin',
+  };
+}
+
+function memberLimit(limit: number | undefined): number {
+  if (limit === undefined) return 200;
+  if (!Number.isFinite(limit) || limit < 1 || !Number.isInteger(limit))
+    throw new TrainError('bad_request', 'limit must be a positive integer');
+  return Math.min(limit, 1000);
+}
+
+function binaryNode(value: unknown): value is BinaryNode {
+  if (!isRecord(value) || typeof value.tag !== 'string' || !isRecord(value.attrs)) return false;
+  if (!Object.values(value.attrs).every((attr) => typeof attr === 'string')) return false;
+  const content = value.content;
+  return content === undefined || typeof content === 'string' || content instanceof Uint8Array
+    || (Array.isArray(content) && content.every(binaryNode));
+}
+
+function memberTotal(response: BinaryNode): number | undefined {
+  const value = getBinaryNodeChild(response, 'group')?.attrs.size;
+  if (!value || !/^\d+$/.test(value)) return undefined;
+  const size = Number(value);
+  return Number.isSafeInteger(size) ? size : undefined;
+}
+
+function capability(total: number | undefined, fetched: number, returned: number): MemberCapability {
+  const complete = total !== undefined && total === fetched && returned === total;
+  const reason = returned < fetched ? 'Member list was limited; increase limit up to 1000'
+    : total === undefined ? 'WhatsApp did not report a total member count'
+      : total !== fetched ? 'WhatsApp returned a partial member list' : undefined;
+  return { supported: true, complete, ...(total === undefined ? {} : { total }), ...(reason ? { reason } : {}) };
+}
+
+export async function listMembers(
+  jid: string,
+  query: (node: BinaryNode) => Promise<unknown>,
+  names: NameBook,
+  limit?: number,
+): Promise<MemberList> {
+  const cap = memberLimit(limit);
+  if (!isGroupJid(jid)) return {
+    members: [],
+    capability: { supported: false, complete: false, reason: 'WhatsApp member lookup requires a group line (@g.us)' },
+  };
+  const response = await query({
+    tag: 'iq', attrs: { type: 'get', xmlns: 'w:g2', to: jid },
+    content: [{ tag: 'query', attrs: { request: 'interactive' } }],
+  });
+  if (!binaryNode(response)) throw new TrainError('whatsapp_call', 'WhatsApp returned invalid group metadata');
+  const group = extractGroupMetadata(response);
+  const participants = [...new Map(group.participants.map((p) => [p.id, p])).values()];
+  const members = participants.slice(0, cap).map((p) => memberOf(p, names));
+  return {
+    members,
+    capability: capability(memberTotal(response), participants.length, members.length),
+  };
+}

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

@@ -0,0 +1,91 @@
+import { jidNormalizedUser, type Contact, type WAMessage, type WASocket } from 'baileys';
+import { bindAppState, noteHistoryContact } from './app-state.js';
+import type { InboundHandlers } from './client-types.js';
+import type { History } from './history.js';
+import type { KeyCache } from './keys.js';
+import { noteContact, type NameBook } from './names.js';
+import { toInbound, toReaction, type SelfRef } from './parse.js';
+
+interface MessageHooks {
+  accountId: string;
+  keys: KeyCache;
+  names: NameBook;
+  history: History;
+  current(): boolean;
+  handlers(): InboundHandlers | undefined;
+  self(): SelfRef;
+}
+
+const person = (jid: string | null | undefined): string | undefined =>
+  jid && (jid.endsWith('@s.whatsapp.net') || jid.endsWith('@lid')) ? jidNormalizedUser(jid) : undefined;
+
+const pair = (a: string, b: string): [string, string] => (a.endsWith('@lid') ? [b, a] : [a, b]);
+
+function noteSender(names: NameBook, m: WAMessage): void {
+  if (m.key.fromMe === true) return;
+  const name = m.pushName ?? m.verifiedBizName;
+  const sender = person(m.key.participant ?? m.key.remoteJid);
+  const alt = person(m.key.participantAlt ?? m.key.remoteJidAlt);
+  for (const jid of [sender, alt]) names.note(jid, name);
+  if (sender !== undefined && alt !== undefined) names.alias(...pair(sender, alt));
+}
+
+export function bindMessages(sock: Pick<WASocket, 'ev' | 'user'>, hooks: MessageHooks): void {
+  const selfJid = (): string | undefined => sock.user?.id ? jidNormalizedUser(sock.user.id) : undefined;
+  const noteContacts = (contacts: Partial<Contact>[]): void => {
+    if (!hooks.current()) return;
+    for (const contact of contacts) {
+      noteContact(hooks.names, contact);
+      noteHistoryContact(hooks.history, contact);
+    }
+  };
+  bindAppState(sock.ev, hooks);
+  sock.ev.on('messages.upsert', ({ messages, type }) => {
+    if (!hooks.current()) return;
+    for (const m of messages) hooks.keys.remember(m.key);
+    hooks.history.ingest(messages, selfJid());
+    const handlers = hooks.handlers();
+    if (type !== 'notify' || !handlers) return;
+    for (const m of messages) {
+      if (m.key.fromMe) continue;
+      const inbound = toInbound(hooks.accountId, m, hooks.self());
+      if (!inbound) continue;
+      hooks.names.note(inbound.senderJid, inbound.pushName);
+      noteSender(hooks.names, m);
+      handlers.onMessage(inbound, m);
+    }
+  });
+  sock.ev.on('lid-mapping.update', ({ pn, lid }) => {
+    if (hooks.current()) hooks.names.alias(pn, lid);
+  });
+  sock.ev.on('contacts.upsert', noteContacts);
+  sock.ev.on('contacts.update', noteContacts);
+  sock.ev.on('messaging-history.set', ({ contacts, messages, lidPnMappings }) => {
+    if (!hooks.current()) return;
+    noteContacts(contacts);
+    for (const { pn, lid } of lidPnMappings ?? []) {
+      hooks.history.alias(pn, lid);
+      hooks.names.alias(pn, lid);
+    }
+    for (const m of messages) {
+      hooks.keys.remember(m.key);
+      noteSender(hooks.names, m);
+    }
+    hooks.history.ingest(messages, selfJid());
+  });
+  sock.ev.on('messages.update', (updates) => {
+    if (hooks.current()) hooks.history.update(updates, selfJid());
+  });
+  sock.ev.on('messages.delete', (event) => {
+    if (hooks.current()) hooks.history.deleteMessages(event);
+  });
+  sock.ev.on('messages.reaction', (events) => {
+    if (!hooks.current()) return;
+    const handlers = hooks.handlers();
+    if (!handlers) return;
+    for (const event of events) {
+      const reaction = toReaction(hooks.accountId, event);
+      if (reaction) handlers.onReaction(reaction);
+    }
+  });
+}

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

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs';
+import { accountFiles } from '@metro-labs/core/stations/account-files';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+
+const MAX_NAMES = 2000;
+const SAVE_DELAY_MS = 2000;
+
+export const nameFiles = accountFiles('WHATSAPP_TOKEN_DIR', 'whatsapp-names-');
+
+export interface NameBook {
+  note(jid: string | null | undefined, name: string | null | undefined): void;
+  get(jid: string): string | undefined;
+  alias(pn: string | null | undefined, lid: string | null | undefined): void;
+}
+
+function loaded(file: string | undefined): Map<string, string> {
+  if (file === undefined) return new Map();
+  try {
+    const raw: unknown = JSON.parse(readFileSync(file, 'utf8'));
+    if (!isRecord(raw)) return new Map();
+    return new Map(Object.entries(raw).filter((e): e is [string, string] => typeof e[1] === 'string' && e[1] !== ''));
+  } catch {
+    return new Map();
+  }
+}
+
+const JID_RE = /^([^@:_]+)(?:_\d+)?(?::\d+)?@([^@]+)$/;
+
+export function idOf(jid: string | null | undefined): string | undefined {
+  const parts = JID_RE.exec(jid ?? '');
+  if (parts === null) return undefined;
+  const [, user = '', server = ''] = parts;
+  return `${user}@${server === 'c.us' ? 's.whatsapp.net' : server}`;
+}
+
+export function makeNameBook(file?: string): NameBook {
+  const names = loaded(file);
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const save = (): void => {
+    timer = null;
+    if (file === undefined) return;
+    try {
+      writeSecure(file, JSON.stringify(Object.fromEntries(names)));
+    } catch (err) {
+      process.stderr.write(`whatsapp: could not save the names: ${errMsg(err)}\n`);
+    }
+  };
+  const schedule = (): void => {
+    if (file !== undefined && timer === null) {
+      timer = setTimeout(save, SAVE_DELAY_MS);
+      timer.unref();
+    }
+  };
+  const note = (raw: string | null | undefined, name: string | null | undefined): void => {
+    const clean = name?.trim() ?? '';
+    const jid = idOf(raw);
+    if (jid === undefined || clean === '' || names.get(jid) === clean) return;
+    names.delete(jid);
+    names.set(jid, clean);
+    if (names.size > MAX_NAMES) {
+      const oldest = names.keys().next().value;
+      if (oldest !== undefined) names.delete(oldest);
+    }
+    schedule();
+  };
+  return {
+    note,
+    get: (jid) => names.get(idOf(jid) ?? jid),
+    alias(rawPn, rawLid) {
+      const pn = idOf(rawPn);
+      const lid = idOf(rawLid);
+      if (pn === undefined || lid === undefined) return;
+      const known = names.get(pn) ?? names.get(lid);
+      if (!names.has(pn)) note(pn, known);
+      if (!names.has(lid)) note(lid, known);
+    },
+  };
+}
+
+export interface ContactNames {
+  id?: string | null;
+  lid?: string | null;
+  phoneNumber?: string | null;
+  name?: string | null;
+  notify?: string | null;
+  verifiedName?: string | null;
+}
+
+const nonBlank = (value: string | null | undefined): string | undefined => (value?.trim() ? value : undefined);
+
+const isLid = (jid: string | null | undefined): jid is string => jid?.endsWith('@lid') === true;
+
+export function noteContact(book: NameBook, c: ContactNames): void {
+  const name = nonBlank(c.name) ?? nonBlank(c.notify) ?? nonBlank(c.verifiedName);
+  for (const jid of [c.id, c.lid, c.phoneNumber]) book.note(jid, name);
+  const lid = c.lid ?? (isLid(c.id) ? c.id : undefined);
+  const pn = c.phoneNumber ?? (isLid(c.id) ? undefined : c.id);
+  book.alias(pn, lid);
+}
+
+export const phoneOf = (jid: string | null | undefined): string | undefined => {
+  const digits = /^(\d{6,})(?::\d+)?@s\.whatsapp\.net$/.exec(jid ?? '')?.[1];
+  return digits === undefined ? undefined : `+${digits}`;
+};

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

@@ -80,9 +80,52 @@ function senderJidOf(key: WAMessageKey, chatJid: string): string {
   return chatJid;
 }
 
+export interface SelfRef {
+  jids: ReadonlySet<string>;
+  sentByMe: (chatJid: string, id: string) => boolean;
+}
+
+const QUOTING_NODES = [
+  'extendedTextMessage',
+  'imageMessage',
+  'videoMessage',
+  'documentMessage',
+  'audioMessage',
+  'stickerMessage',
+] as const;
+
+function contextInfoOf(inner: proto.IMessage): proto.IContextInfo | undefined {
+  for (const node of QUOTING_NODES) {
+    const ctx = inner[node]?.contextInfo;
+    if (ctx) return ctx;
+  }
+  return undefined;
+}
+
+function quoteFacts(ctx: proto.IContextInfo, replyTo: string | undefined, chatJid: string, self: SelfRef): Addressing {
+  const quotedBy = typeof ctx.participant === 'string' ? ctx.participant : '';
+  const mentioned = (ctx.mentionedJid ?? []).some((jid) => self.jids.has(jid));
+  const replyToSelf = replyTo !== undefined && (self.jids.has(quotedBy) || self.sentByMe(chatJid, replyTo));
+  return {
+    ...(mentioned ? { mentionsSelf: true } : {}),
+    ...(replyToSelf ? { replyToSelf: true } : {}),
+  };
+}
+
+type Addressing = Pick<InboundMessage, 'replyTo' | 'mentionsSelf' | 'replyToSelf'>;
+
+function addressing(inner: proto.IMessage, chatJid: string, self: SelfRef | undefined): Addressing {
+  const ctx = contextInfoOf(inner);
+  if (ctx === undefined) return {};
+  const replyTo = typeof ctx.stanzaId === 'string' && ctx.stanzaId !== '' ? ctx.stanzaId : undefined;
+  const base: Addressing = replyTo === undefined ? {} : { replyTo };
+  return self === undefined ? base : { ...base, ...quoteFacts(ctx, replyTo, chatJid, self) };
+}
+
 export function toInbound(
   accountId: string,
   m: WAMessage,
+  self?: SelfRef,
 ): InboundMessage | undefined {
   const chatJid = m.key.remoteJid;
   const messageId = m.key.id;
@@ -102,6 +145,7 @@ export function toInbound(
     isPrivate: isPrivateJid(chatJid),
     ...(m.pushName ? { pushName: m.pushName } : {}),
     ...(media ? { media } : {}),
+    ...addressing(inner, chatJid, self),
   };
 }
 

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

@@ -0,0 +1,158 @@
+import { jidNormalizedUser, type WASocket } from 'baileys';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { nonEmpty, type SenderProfile } from '@metro-labs/core/stations/sender-profile';
+import { phoneOf, type NameBook } from './names.js';
+
+export const NO_PICTURE_MS = 6 * 60 * 60_000;
+export const RATE_LIMITED_MS = 30 * 60_000;
+export const LOOKUP_BUDGET_MS = 6_000;
+export const PROFILE_READS = 4;
+const TRY_MS = 1_500;
+const NO_PICTURE_MAX = 2_000;
+const REFUSED = new Set([401, 403, 404]);
+const RATE_LIMIT_RE = /rate.?over.?limit|too many/i;
+const PICTURE_TYPES = ['image', 'preview'] as const;
+
+type ProfileSocket = Pick<WASocket, 'fetchStatus' | 'profilePictureUrl' | 'signalRepository'>;
+
+export interface PeerProfile {
+  profile: SenderProfile;
+  other: string | null;
+}
+
+export class PictureMemory {
+  private none = new Map<string, number>();
+  private limitedAt: number | null = null;
+
+  constructor(readonly now: () => number = Date.now) {}
+
+  known(jid: string): boolean {
+    const at = this.none.get(jid);
+    if (at === undefined) return false;
+    if (this.now() - at < NO_PICTURE_MS) return true;
+    this.none.delete(jid);
+    return false;
+  }
+
+  remember(jid: string): void {
+    this.none.delete(jid);
+    this.none.set(jid, this.now());
+    if (this.none.size <= NO_PICTURE_MAX) return;
+    const oldest = this.none.keys().next();
+    if (!oldest.done) this.none.delete(oldest.value);
+  }
+
+  limited(): boolean {
+    return this.limitedAt !== null && this.now() - this.limitedAt < RATE_LIMITED_MS;
+  }
+
+  limit(): void {
+    this.limitedAt = this.now();
+  }
+}
+
+type Failure = 'refused' | 'limited' | 'other';
+
+function failureOf(err: unknown): Failure {
+  const output = isRecord(err) && isRecord(err.output) ? err.output : {};
+  const code = typeof output.statusCode === 'number' ? output.statusCode : undefined;
+  if (code === 429 || RATE_LIMIT_RE.test(errMsg(err))) return 'limited';
+  return code !== undefined && REFUSED.has(code) ? 'refused' : 'other';
+}
+
+function within<T, F>(work: Promise<T>, ms: number, fallback: F): Promise<T | F> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<F>((resolve) => {
+    timer = setTimeout(() => {
+      resolve(fallback);
+    }, ms);
+  });
+  return Promise.race([work.catch(() => fallback), late]).finally(() => {
+    clearTimeout(timer);
+  });
+}
+
+async function otherIdOf(sock: ProfileSocket, jid: string): Promise<string | null> {
+  const mapping = sock.signalRepository.lidMapping;
+  const other = await within(jid.endsWith('@lid') ? mapping.getPNForLID(jid) : mapping.getLIDForPN(jid), TRY_MS, null);
+  return other === null ? null : jidNormalizedUser(other);
+}
+
+type Tried = { url: string } | 'none' | 'stop';
+
+async function pictureFor(sock: ProfileSocket, jid: string, memory: PictureMemory, deadline: number): Promise<Tried> {
+  for (const type of PICTURE_TYPES) {
+    const left = deadline - memory.now();
+    if (left <= 0) return 'stop';
+    try {
+      const url = nonEmpty(await sock.profilePictureUrl(jid, type, Math.min(TRY_MS, left)));
+      if (url !== undefined) return { url };
+    } catch (err) {
+      const failure = failureOf(err);
+      if (failure === 'limited') memory.limit();
+      if (failure !== 'refused') return 'stop';
+    }
+  }
+  memory.remember(jid);
+  return 'none';
+}
+
+export async function pictureOf(sock: ProfileSocket, jids: string[], memory: PictureMemory, deadline = memory.now() + LOOKUP_BUDGET_MS): Promise<string | undefined> {
+  for (const jid of jids) {
+    if (memory.limited()) return undefined;
+    if (memory.known(jid)) continue;
+    const tried = await pictureFor(sock, jid, memory, deadline);
+    if (tried === 'stop') return undefined;
+    if (tried !== 'none') return tried.url;
+  }
+  return undefined;
+}
+
+export async function readPeer(sock: ProfileSocket, jid: string, memory: PictureMemory): Promise<PeerProfile> {
+  const deadline = memory.now() + LOOKUP_BUDGET_MS;
+  const other = await otherIdOf(sock, jid);
+  const jids = other === null ? [jid] : [jid, other];
+  const [statuses, picture] = await Promise.all([within(sock.fetchStatus(jid), LOOKUP_BUDGET_MS, undefined), pictureOf(sock, jids, memory, deadline)]);
+  const status: unknown = statuses?.[0]?.status;
+  const about = nonEmpty(isRecord(status) ? status.status : undefined);
+  const phone = phoneOf(jid.endsWith('@lid') ? other : jid);
+  return {
+    other,
+    profile: {
+      id: jid,
+      ...(phone === undefined ? {} : { name: phone, address: phone }),
+      ...(about === undefined ? {} : { about }),
+      ...(picture === undefined ? {} : { avatar: picture }),
+    },
+  };
+}
+
+export function withName(peer: PeerProfile, names: NameBook): SenderProfile {
+  const { profile, other } = peer;
+  if (other !== null) names.alias(profile.id.endsWith('@lid') ? other : profile.id, profile.id.endsWith('@lid') ? profile.id : other);
+  const name = names.get(profile.id) ?? (other === null ? undefined : names.get(other));
+  return name === undefined ? profile : { ...profile, display_name: name };
+}
+
+export function limiter(max: number): <T>(run: () => Promise<T>) => Promise<T> {
+  let active = 0;
+  const waiting: (() => void)[] = [];
+  const release = (): void => {
+    const next = waiting.shift();
+    if (next === undefined) active -= 1;
+    else next();
+  };
+  return async <T>(run: () => Promise<T>): Promise<T> => {
+    if (active >= max)
+      await new Promise<void>((resolve) => {
+        waiting.push(resolve);
+      });
+    else active += 1;
+    try {
+      return await run();
+    } finally {
+      release();
+    }
+  };
+}