@stage-labs/metro 0.1.0-beta.27 → 0.1.0-beta.271

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

@@ -0,0 +1,195 @@
+import { errMsg, log } from '@metro-labs/core/log';
+import { TrainError } from '@metro-labs/core/train-error';
+import type { proto, WAMessage, WAMessageUpdate } from 'baileys';
+import { HistoryEvents } from './history-events.js';
+import { HistoryState } from './history-state.js';
+import {
+  HISTORY_LIMITS, HISTORY_SAVE_MS, HISTORY_SWEEP_MS, newestFirst,
+  type History, type HistoryDelete, type HistoryOptions, type HistoryPage, type HistoryRow, type StoredRow,
+} from './history-types.js';
+
+export { historyFiles } from './history-state.js';
+export type { History, HistoryOptions, HistoryPage, HistoryRow } from './history-types.js';
+
+function shown(row: StoredRow): HistoryRow {
+  return {
+    key: { ...row.key }, messageId: row.key.id ?? '', chatJid: row.key.remoteJid ?? '',
+    fromMe: row.key.fromMe === true, timestamp: new Date(row.at).toISOString(), text: row.text,
+    ...(row.senderJid ? { senderJid: row.senderJid } : {}),
+    ...(row.truncated ? { truncated: true } : {}),
+    ...(row.attachments ? { attachments: row.attachments.map((a) => ({ ...a })) } : {}),
+  };
+}
+
+function readBounds(options: HistoryOptions): { limit: number; since: number } {
+  const limit = options.limit ?? 50;
+  const since = options.since === undefined ? 0 : Date.parse(options.since);
+  if (!Number.isInteger(limit) || limit < 1 || !Number.isFinite(since))
+    throw new TrainError('bad_request', 'WhatsApp history needs a positive integer limit and a valid since timestamp');
+  return { limit: Math.min(limit, HISTORY_LIMITS.pageSize), since };
+}
+
+const rowTime = (row: StoredRow | undefined): string | null => row === undefined ? null : new Date(row.at).toISOString();
+
+function boundedPage(result: HistoryPage, rows: StoredRow[], limit: number): HistoryPage {
+  let bytes = Buffer.byteLength(JSON.stringify(result));
+  for (const row of rows.slice(0, limit)) {
+    const message = shown(row);
+    const added = Buffer.byteLength(JSON.stringify(message)) + 1;
+    const cursor = Buffer.byteLength(JSON.stringify({ count: result.messages.length + 1, hasMore: true, nextBefore: message.messageId }));
+    if (bytes + added + cursor > HISTORY_LIMITS.pageBytes - 128 * 1024) break;
+    result.messages.push(message);
+    bytes += added;
+  }
+  result.count = result.messages.length;
+  result.hasMore = rows.length > result.count;
+  if (result.hasMore) result.nextBefore = result.messages.at(-1)?.messageId;
+  return result;
+}
+
+function page(state: HistoryState, jid: string, options: HistoryOptions): HistoryPage {
+  const { limit, since } = readBounds(options);
+  const rows = [...state.rows.values()].filter((row) => state.same(row.key.remoteJid ?? '', jid)).sort(newestFirst);
+  const before = options.before === undefined ? -1 : rows.findIndex((row) => row.key.id === options.before);
+  if (options.before !== undefined && before < 0)
+    throw new TrainError('whatsapp_history_cursor', 'The before message is not retained in this chat. Read without before to restart local pagination.');
+  const matching = rows.slice(before + 1).filter((row) => row.at >= since);
+  return boundedPage({
+    messages: [], count: 0, hasMore: false,
+    coverage: {
+      partial: true, source: 'local',
+      description: 'Only locally observed or synced messages and successful sends with known expiry state. Own sends with unknown expiry are omitted until observed or synced. Gaps remain; no older backfill or media downloads. View-once and unknown-expiry content is omitted. before is exclusive; since is inclusive. Pages reserve output-formatting overhead within the serialized-byte limit. hasMore describes retained local matches only.',
+      oldest: rowTime(rows.at(-1)), newest: rowTime(rows[0]),
+      retained: rows.length, retainedAfter: new Date(state.after(jid)).toISOString(), limits: HISTORY_LIMITS,
+    },
+  }, matching, limit);
+}
+
+class LocalHistory implements History {
+  private readonly state: HistoryState;
+  private readonly events: HistoryEvents;
+  private readonly sweep: ReturnType<typeof setInterval>;
+  private timer?: ReturnType<typeof setTimeout>;
+  private closed = false;
+
+  constructor(private readonly accountId: string) {
+    this.state = new HistoryState(accountId);
+    this.events = new HistoryEvents(this.state);
+    this.state.prune(Date.now());
+    this.sweep = setInterval(() => { this.saveSafely(); }, HISTORY_SWEEP_MS);
+    this.sweep.unref();
+    this.schedule();
+  }
+
+  private assertOpen(): void {
+    if (this.closed) throw new TrainError('whatsapp_history_closed', 'WhatsApp local history is closed');
+  }
+
+  private saveSafely(): void {
+    try {
+      this.flush();
+    } catch (err) {
+      log.error({ accountId: this.accountId, err: errMsg(err) }, 'whatsapp: could not save local history');
+    }
+  }
+
+  private schedule(): void {
+    if (this.timer) return;
+    this.timer = setTimeout(() => { this.saveSafely(); }, HISTORY_SAVE_MS);
+    this.timer.unref();
+  }
+
+  private changed(now: number): void {
+    this.state.prune(now);
+    this.schedule();
+  }
+
+  read(jid: string, options: HistoryOptions = {}): HistoryPage {
+    this.assertOpen();
+    this.changed(Date.now());
+    this.state.assertReadable(jid);
+    return page(this.state, jid, options);
+  }
+
+  ingest(messages: readonly WAMessage[], selfJid?: string): void {
+    this.ingestAll(messages, selfJid);
+  }
+
+  ingestSent(messages: readonly WAMessage[], selfJid?: string, ephemeralExpiration?: number): void {
+    this.ingestAll(messages, selfJid, { expiration: ephemeralExpiration });
+  }
+
+  private ingestAll(messages: readonly WAMessage[], selfJid?: string, sent?: { expiration?: number }): void {
+    this.assertOpen();
+    const now = Date.now();
+    for (const [index, message] of messages.entries()) {
+      this.events.ingest(message, now, selfJid, sent);
+      if (index % 128 === 127) this.state.prune(now);
+    }
+    this.changed(now);
+  }
+
+  alias(pn: string, lid: string): void {
+    this.assertOpen();
+    const now = Date.now();
+    this.state.alias(pn, lid, now);
+    this.changed(now);
+  }
+
+  clearRange(jid: string, range?: proto.SyncActionValue.ISyncActionMessageRange | null): void {
+    this.assertOpen();
+    const now = Date.now();
+    this.state.clearRange(jid, range ?? {}, now);
+    this.changed(now);
+  }
+
+  invalidate(): void {
+    this.assertOpen();
+    this.state.invalidate(Date.now());
+  }
+
+  update(updates: readonly WAMessageUpdate[], selfJid?: string): void {
+    this.assertOpen();
+    const now = Date.now();
+    for (const [index, update] of updates.entries()) {
+      this.events.update(update, now, selfJid);
+      if (index % 128 === 127) this.state.prune(now);
+    }
+    this.changed(now);
+  }
+
+  deleteMessages(event: HistoryDelete): void {
+    this.assertOpen();
+    const now = Date.now();
+    if ('keys' in event) {
+      for (const [index, key] of event.keys.entries()) {
+        this.state.remove(key, now);
+        if (index % 128 === 127) this.state.prune(now);
+      }
+    } else this.state.clear(event.jid, now);
+    this.changed(now);
+  }
+
+  edit(jid: string, messageId: string, text: string): void {
+    this.assertOpen();
+    const now = Date.now();
+    this.state.prune(now);
+    this.events.edit(jid, messageId, text, now);
+    this.changed(now);
+  }
+
+  flush(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    this.state.flush();
+  }
+
+  close(): void {
+    if (this.closed) return;
+    clearInterval(this.sweep);
+    this.closed = true;
+    this.flush();
+  }
+}
+
+export const createHistory = (accountId: string): History => new LocalHistory(accountId);

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

@@ -1,9 +1,8 @@
 import type { WAMessage } from 'baileys';
-import { errMsg } from '@metro-labs/mcp/log';
-import { emit } from './wire.js';
+import { emit } from '@metro-labs/core/stations/station-runtime';
+import { reportAttachment } from '@metro-labs/core/stations/train-events';
+import { lineOf } from './accounts.js';
 import {
-  attachmentFailedEnvelope,
-  attachmentSavedEnvelope,
   envelope,
   reactionEnvelope,
   type InboundMessage,
@@ -11,31 +10,19 @@ import {
 import { saveWhatsAppMedia } from './attachments.js';
 import type { WAClient } from './client.js';
 
-async function saveMedia(
+function saveMedia(
   client: WAClient,
   m: InboundMessage,
   raw: WAMessage,
   sourceId: string,
-): Promise<void> {
+): void {
   const ref = m.media;
   if (!ref) return;
-  try {
-    const saved = await saveWhatsAppMedia(
-      m.accountId,
-      raw,
-      ref,
-      m.messageId,
-      0,
-      (msg) => client.reuploadMedia(msg),
-    );
-    emit(attachmentSavedEnvelope(m, sourceId, ref, saved, 0));
-  } catch (err) {
-    const reason = errMsg(err);
-    process.stderr.write(
-      `whatsapp[${m.accountId}] ${ref.kind} download failed for ${m.messageId}: ${reason}\n`,
-    );
-    emit(attachmentFailedEnvelope(m, sourceId, ref, 0, reason));
-  }
+  reportAttachment(
+    saveWhatsAppMedia(m.accountId, raw, ref, m.messageId, 0, (msg) => client.reuploadMedia(msg)),
+    { station: 'whatsapp', account: m.accountId, line: lineOf(m.accountId, m.chatJid), forId: sourceId, index: 0 },
+    { saved: { kind: ref.kind }, failed: { kind: ref.kind, name: ref.name, mime: ref.mime } },
+  );
 }
 
 export async function startInbound(client: WAClient): Promise<void> {
@@ -44,11 +31,7 @@ export async function startInbound(client: WAClient): Promise<void> {
       const env = envelope(m);
       emit(env);
       if (!m.media) return;
-      saveMedia(client, m, raw, String(env.id)).catch((err: unknown) => {
-        process.stderr.write(
-          `whatsapp[${m.accountId}] media event not emitted: ${errMsg(err)}\n`,
-        );
-      });
+      saveMedia(client, m, raw, String(env.id));
     },
     onReaction: (r) => {
       emit(reactionEnvelope(r));

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,7 +4,7 @@ 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';
 
 export class WhatsappLoginError extends Error {}

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,70 @@
+import { jidNormalizedUser, type Contact, 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;
+}
+
+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);
+      handlers.onMessage(inbound, m);
+    }
+  });
+  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);
+    for (const m of messages) {
+      hooks.keys.remember(m.key);
+      if (m.key.fromMe !== true) hooks.names.note(m.key.participant ?? m.key.remoteJid, m.pushName);
+    }
+    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,75 @@
+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;
+}
+
+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();
+  }
+}
+
+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`);
+    }
+  };
+  return {
+    note(jid, name) {
+      const clean = name?.trim() ?? '';
+      if (!jid || 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);
+      }
+      if (file !== undefined && timer === null) {
+        timer = setTimeout(save, SAVE_DELAY_MS);
+        timer.unref();
+      }
+    },
+    get: (jid) => names.get(jid),
+  };
+}
+
+export interface ContactNames {
+  id?: string | null;
+  lid?: string | null;
+  phoneNumber?: string | null;
+  name?: string | null;
+  notify?: string | null;
+}
+
+export function noteContact(book: NameBook, c: ContactNames): void {
+  const name = c.name ?? c.notify;
+  for (const jid of [c.id, c.lid, c.phoneNumber]) book.note(jid, name);
+}
+
+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/resolve.ts

@@ -0,0 +1,52 @@
+import { TrainError } from '@metro-labs/core/train-error';
+
+const INTERNATIONAL = /^[1-9]\d{5,17}$/;
+
+export interface SenderFound {
+  exists: boolean;
+  jid: string | null;
+  lid: string | null;
+}
+
+export interface SenderLookup extends SenderFound {
+  query: string;
+  number: string;
+  id: string | null;
+}
+
+function refuse(query: string, why: string): never {
+  throw new TrainError('bad_request', `'${query}' ${why}`);
+}
+
+function international(query: string, digits: string): string {
+  if (digits.startsWith('00')) return digits.slice(2);
+  if (digits.startsWith('0'))
+    refuse(
+      query,
+      'is a national number, so metro cannot tell which country it is in; write it in full international form, as in 41791234567 for a Swiss 079 123 45 67',
+    );
+  return digits;
+}
+
+export function phoneNumberOf(raw: string): string {
+  const query = raw.trim();
+  if (query.toLowerCase().endsWith('@lid'))
+    refuse(query, 'is already a sender id, so add it directly instead of looking it up');
+  const local = query.split('@')[0] ?? '';
+  const digits = local.replace(/\D/g, '');
+  const number = local.startsWith('+') ? digits : international(query, digits);
+  if (!INTERNATIONAL.test(number))
+    refuse(query, 'is not a phone number metro can look up; write it in full international form, as in 41791234567');
+  return number;
+}
+
+export function senderLookup(query: string, number: string, found: SenderFound): SenderLookup {
+  return {
+    query: query.trim(),
+    number,
+    exists: found.exists,
+    jid: found.jid,
+    lid: found.lid,
+    id: found.lid ?? found.jid,
+  };
+}