@stage-labs/metro 0.1.0-beta.20 → 0.1.0-beta.201

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

@@ -0,0 +1,160 @@
+import { TrainError } from '@metro-labs/core/train-error';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { publicKeyFor, targetOf, type Account, type Target } from './accounts.js';
+import { sendE2E } from './api.js';
+import { bytesToHex, quoted, seal } from './crypto.js';
+import { encodeFileFor, fileLabel, packFile, type OutgoingFile } from './files.js';
+import { emitOutbound, emitOutboundReaction } from './format.js';
+import { MESSAGE_ID_RE } from './ids.js';
+import {
+  encodeGroupReaction,
+  encodeGroupSyncRequest,
+  encodeGroupText,
+  encodeReaction,
+  encodeText,
+  type GroupRef,
+} from './messages.js';
+
+export const MAX_TEXT_BYTES = 3500;
+const SENT_MAX = 2000;
+
+type Args = Record<string, unknown>;
+
+const sentIds = new Set<string>();
+
+export function noteSent(messageId: string): void {
+  sentIds.add(messageId);
+  while (sentIds.size > SENT_MAX) {
+    const oldest = sentIds.values().next();
+    if (oldest.done) break;
+    sentIds.delete(oldest.value);
+  }
+}
+
+export const sentByUs = (messageId: string): boolean => sentIds.has(messageId);
+
+async function deliver(acct: Account, to: string, plain: Uint8Array, group: boolean): Promise<string> {
+  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);
+  return messageId;
+}
+
+function recipientsOf(acct: Account, group: GroupRef): string[] {
+  const members = acct.groups.recipients(group);
+  if (members === null)
+    throw new TrainError(
+      'threema_unknown_group',
+      'metro has not received this group\'s member list yet; it asked the group creator for it, try again in a moment',
+      { retryable: true },
+    );
+  return members;
+}
+
+export async function requestSync(acct: Account, group: GroupRef): Promise<void> {
+  await deliver(acct, group.creator, encodeGroupSyncRequest(group.groupId), true);
+}
+
+async function fanOut(acct: Account, target: Target, direct: Uint8Array, grouped: (g: GroupRef) => Uint8Array): Promise<string[]> {
+  if (target.kind === 'user') return [await deliver(acct, target.id, direct, false)];
+  const ids: string[] = [];
+  for (const member of recipientsOf(acct, target.group)) ids.push(await deliver(acct, member, grouped(target.group), true));
+  if (ids.length === 0) throw new TrainError('threema_empty_group', 'nobody else is in this group', { retryable: false });
+  return ids;
+}
+
+interface SendArgs {
+  line: string;
+  text?: unknown;
+  replyTo?: unknown;
+  account?: string;
+  attachments?: unknown;
+}
+
+const filesOf = (raw: unknown): OutgoingFile[] =>
+  (Array.isArray(raw) ? raw : [])
+    .map((a) => (a ?? {}) as Record<string, unknown>)
+    .filter((a) => typeof a.path === 'string' && a.path !== '')
+    .map((a) => ({ path: String(a.path), mime: typeof a.mime === 'string' && a.mime !== '' ? a.mime : 'application/octet-stream', name: typeof a.name === 'string' && a.name !== '' ? a.name : 'file' }));
+
+function textOf(a: SendArgs, files: OutgoingFile[]): string {
+  const text = typeof a.text === 'string' ? a.text : '';
+  if (text === '' && files.length === 0)
+    throw new TrainError('threema_text_required', 'give some text or a file to send', { retryable: false });
+  return text;
+}
+
+async function sendFiles(acct: Account, target: Target, files: OutgoingFile[], caption: string | null): Promise<{ ids: string[]; labels: string[] }> {
+  const ids: string[] = [];
+  const labels: string[] = [];
+  for (const [i, file] of files.entries()) {
+    const packed = await packFile(acct, file, i === 0 ? caption : null);
+    const sent = await fanOut(acct, target, encodeFileFor(null, packed), (g) => encodeFileFor(g, packed));
+    ids.push(...sent);
+    labels.push(fileLabel(file));
+  }
+  return { ids, labels };
+}
+
+function messageIdOf(raw: unknown, field: string): string {
+  const id = typeof raw === 'string' ? raw.toLowerCase() : '';
+  if (!MESSAGE_ID_RE.test(id))
+    throw new TrainError('threema_bad_message_id', `${field} must be a Threema message id, 16 hex characters`, { retryable: false });
+  return id;
+}
+
+const replyTargetOf = (raw: unknown): string | undefined => (raw === undefined || raw === null || raw === '' ? undefined : messageIdOf(raw, 'replyTo'));
+
+function bodyOf(text: string, replyTo: string | undefined): string {
+  const body = replyTo === undefined ? text : quoted(replyTo, text);
+  if (Buffer.byteLength(body, 'utf8') > MAX_TEXT_BYTES)
+    throw new TrainError('threema_message_too_long', `Threema carries at most ${MAX_TEXT_BYTES} bytes of text per message; split it up`, { retryable: false });
+  return body;
+}
+
+interface Sent {
+  ids: string[];
+  labels: string[];
+}
+
+const resultOf = (acct: Account, sent: Sent): Record<string, unknown> => ({
+  messageId: sent.ids[0] ?? '',
+  account: acct.cfg.id,
+  ...(sent.ids.length > 1 ? { messageIds: sent.ids } : {}),
+  ...(sent.labels.length > 0 ? { attachments: sent.labels } : {}),
+});
+
+export async function send(id: string, args: Args): Promise<void> {
+  const a = args as unknown as SendArgs;
+  const files = filesOf(a.attachments);
+  const text = textOf(a, files);
+  const replyTo = replyTargetOf(a.replyTo);
+  const { acct, target } = targetOf(a.line, a.account);
+  const body = bodyOf(text, replyTo);
+  const sent: Sent =
+    files.length === 0
+      ? { ids: await fanOut(acct, target, encodeText(body), (g) => encodeGroupText(g, body)), labels: [] }
+      : await sendFiles(acct, target, files, body === '' ? null : body);
+  emitOutbound(acct.cfg.id, a.line, sent.ids[0] ?? '', text === '' ? `[${sent.labels.join(', ')}]` : text, replyTo);
+  respond(id, { result: resultOf(acct, sent) });
+}
+
+interface ReactArgs {
+  line: string;
+  messageId?: unknown;
+  emoji?: unknown;
+  account?: string;
+  action?: unknown;
+}
+
+export async function react(id: string, args: Args): Promise<void> {
+  const a = args as unknown as ReactArgs;
+  const emoji = typeof a.emoji === 'string' ? a.emoji.trim() : '';
+  if (emoji === '') throw new TrainError('threema_emoji_required', 'react needs an emoji', { retryable: false });
+  const messageId = messageIdOf(a.messageId, 'messageId');
+  const removed = a.action === 'removed';
+  const { acct, target } = targetOf(a.line, a.account);
+  const ids = await fanOut(acct, target, encodeReaction(messageId, emoji, removed), (g) => encodeGroupReaction(g, messageId, emoji, removed));
+  emitOutboundReaction(acct.cfg.id, a.line, ids[0] ?? '', emoji, messageId, removed);
+  respond(id, { result: { messageId: ids[0] ?? '', account: acct.cfg.id, emoji, removed } });
+}

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

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

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

@@ -0,0 +1,117 @@
+import { createPrivateKey, createPublicKey } from 'node:crypto';
+import {
+  GATEWAY_API,
+  isGatewayId,
+  normalizeThreemaId,
+  parsePrivateKey,
+} from './ids.js';
+
+export { parsePrivateKey } from './ids.js';
+
+export class ThreemaGatewayError extends Error {}
+
+export interface ThreemaCredentials {
+  gatewayId: string;
+  secret: string;
+  privateKey: string;
+}
+
+export interface ThreemaGatewayIdentity {
+  gatewayId: string;
+  publicKey: string;
+  credits: number;
+}
+
+const PKCS8_X25519_PREFIX = Buffer.from(
+  '302e020100300506032b656e04220420',
+  'hex',
+);
+const TIMEOUT_MS = 10_000;
+const PUBLIC_KEY_RE = /^[0-9a-f]{64}$/;
+
+export function publicKeyOf(privateKeyHex: string): string {
+  const der = Buffer.concat([
+    PKCS8_X25519_PREFIX,
+    Buffer.from(privateKeyHex, 'hex'),
+  ]);
+  const key = createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  const jwk = createPublicKey(key).export({ format: 'jwk' });
+  return Buffer.from(String(jwk.x), 'base64url').toString('hex');
+}
+
+async function gatewayGet(
+  path: string,
+  gatewayId: string,
+  secret: string,
+): Promise<Response> {
+  const query = new URLSearchParams({ from: gatewayId, secret });
+  try {
+    return await fetch(`${GATEWAY_API}${path}?${query.toString()}`, {
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch {
+    throw new ThreemaGatewayError(
+      'could not reach the Threema Gateway to check those credentials',
+    );
+  }
+}
+
+function refused(res: Response, what: string): ThreemaGatewayError {
+  if (res.status === 401)
+    return new ThreemaGatewayError(
+      'Threema rejected that Gateway ID or API secret',
+    );
+  if (res.status === 404)
+    return new ThreemaGatewayError(`Threema does not know ${what}`);
+  return new ThreemaGatewayError(
+    `the Threema Gateway answered ${res.status} while checking ${what}`,
+  );
+}
+
+async function fetchCredits(gatewayId: string, secret: string): Promise<number> {
+  const res = await gatewayGet('/credits', gatewayId, secret);
+  if (!res.ok) throw refused(res, 'the credit balance');
+  const credits = Number((await res.text()).trim());
+  if (!Number.isInteger(credits))
+    throw new ThreemaGatewayError(
+      'the Threema Gateway gave an unexpected answer for the credit balance',
+    );
+  return credits;
+}
+
+async function fetchPublicKey(gatewayId: string, secret: string): Promise<string> {
+  const res = await gatewayGet(
+    `/pubkeys/${encodeURIComponent(gatewayId)}`,
+    gatewayId,
+    secret,
+  );
+  if (!res.ok) throw refused(res, `the public key of ${gatewayId}`);
+  const hex = (await res.text()).trim().toLowerCase();
+  if (!PUBLIC_KEY_RE.test(hex))
+    throw new ThreemaGatewayError(
+      'the Threema Gateway gave an unexpected answer for the public key',
+    );
+  return hex;
+}
+
+export async function verifyThreemaGateway(
+  input: ThreemaCredentials,
+): Promise<ThreemaGatewayIdentity> {
+  const gatewayId = normalizeThreemaId(input.gatewayId);
+  if (!isGatewayId(gatewayId))
+    throw new ThreemaGatewayError(
+      'a Threema Gateway ID is a * followed by 7 letters or digits, as in *ABCDEFG',
+    );
+  const privateKey = parsePrivateKey(input.privateKey);
+  if (privateKey === null)
+    throw new ThreemaGatewayError(
+      'the private key is the 64 hex characters from the key file Threema gave you, with or without its private: prefix',
+    );
+  const credits = await fetchCredits(gatewayId, input.secret);
+  const registered = await fetchPublicKey(gatewayId, input.secret);
+  if (registered !== publicKeyOf(privateKey))
+    throw new ThreemaGatewayError(
+      `that private key does not belong to ${gatewayId}: the Gateway holds a different public key for it`,
+    );
+  return { gatewayId, publicKey: registered, credits };
+}

package/runtime/node_modules/@metro-labs/webhook/package.json

@@ -11,7 +11,7 @@
     "test": "tsc --noEmit && bun test test/"
   },
   "dependencies": {
-    "@metro-labs/mcp": "workspace:*"
+    "@metro-labs/core": "workspace:*"
   },
   "devDependencies": {
     "@stage-labs/config": "0.1.0-beta.2",

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

@@ -1,11 +1,8 @@
 import { randomUUID } from 'node:crypto';
-import { Line, asLine } from '@metro-labs/mcp/lines';
-import { mintId, type MetroEvent } from '@metro-labs/mcp/events';
-import type { Endpoint } from '@metro-labs/mcp/endpoints';
-import type { Station, Verb } from '@metro-labs/mcp/stations/types';
-
-const sessionOwner = (sessionId: string): Line =>
-  asLine(`metro://session/${sessionId}`);
+import { Line } from '@metro-labs/core/lines';
+import { mintId, type MetroEvent } from '@metro-labs/core/events';
+import type { Endpoint } from '@metro-labs/core/endpoints';
+import type { Station, Verb } from '@metro-labs/core/stations/types';
 
 export const webhookStation: Station = {
   name: 'webhook',
@@ -31,7 +28,7 @@ export function webhookEntry(
     line,
     lineName: endpoint.label,
     from: line,
-    to: endpoint.session ? sessionOwner(endpoint.session) : line,
+    to: line,
     messageId:
       headers['x-github-delivery'] ?? headers['x-request-id'] ?? randomUUID(),
     text: `${headers['x-github-event'] ?? headers['x-intercom-topic'] ?? 'event'} ${method} ${url}`,

package/runtime/node_modules/@metro-labs/whatsapp/package.json

@@ -14,16 +14,14 @@
     "test": "tsc --noEmit && bun test test/"
   },
   "dependencies": {
-    "@metro-labs/mcp": "workspace:*",
+    "@metro-labs/core": "workspace:*",
     "baileys": "7.0.0-rc14"
   },
   "devDependencies": {
     "@stage-labs/config": "0.1.0-beta.2",
-    "@types/qrcode-terminal": "^0.12.2",
     "eslint": "^10.3.0",
     "knip": "^6.15.0",
     "madge": "^8.0.0",
-    "qrcode-terminal": "^0.12.0",
     "typescript": "^5"
   }
 }

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

@@ -4,7 +4,7 @@ import {
   makeAccountStore,
   resolveAccountId,
   type Die,
-} from '@metro-labs/mcp/stations/account-store';
+} from '@metro-labs/core/stations/account-store';
 import type { WhatsAppAccount } from './types.js';
 
 const ACCOUNTS_FILE =
@@ -28,7 +28,6 @@ function validateAccount(
 export const { loadAccounts } = makeAccountStore<WhatsAppAccount>({
   prefix: 'whatsapp',
   file: ACCOUNTS_FILE,
-  allowlistEnv: ['WHATSAPP_ONLY_ACCOUNTS', 'WHATSAPP_ACCOUNTS'],
   validate(raw, die) {
     const seen = new Set<string>();
     for (const a of raw) validateAccount(a, seen, die);

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

@@ -1,4 +1,4 @@
-import { TrainError } from '@metro-labs/mcp/train-error';
+import { TrainError } from '@metro-labs/core/train-error';
 import type { BinaryNode, WASocket } from 'baileys';
 
 const DEFAULT_ACK_WAIT_MS = 5000;

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

@@ -1,14 +1,16 @@
-import { TrainError } from '@metro-labs/mcp/train-error';
-import { errMsg } from '@metro-labs/mcp/log';
-import { kindOf } from '@metro-labs/mcp/stations/attachments';
+import { TrainError } from '@metro-labs/core/train-error';
+import { errMsg } from '@metro-labs/core/log';
+import { kindOf } from '@metro-labs/core/stations/attachments';
 import {
   makeStation,
   respond,
   type CallMsg,
   type StationHandler,
-} from '@metro-labs/mcp/stations/station-runtime';
+} from '@metro-labs/core/stations/station-runtime';
 import { accountFor, accounts, targetOf } from './accounts.js';
 import { normalizeWhatsApp } from './normalize.js';
+import { phoneNumberOf, senderLookup } from './resolve.js';
+import { assertImage, fieldsOf, parseProfileChange, type ProfileApplied } from '@metro-labs/core/stations/profile';
 import type { WAClient } from './client.js';
 
 type Args = Record<string, unknown>;
@@ -154,7 +156,6 @@ function makeAccounts(clientFor: ClientFor): StationHandler {
         handle: phone === null ? null : `+${phone}`,
         url: phone === null ? null : `https://wa.me/${phone}`,
         connected: phone !== null,
-        owner: a.owner ?? null,
       };
     });
     respond(id, { result: { accounts: list } });
@@ -162,6 +163,37 @@ function makeAccounts(clientFor: ClientFor): StationHandler {
   };
 }
 
+function makeResolveSender(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const accountId = accountFor({ account: str(args.account) });
+    const query = str(args.query) ?? '';
+    const number = phoneNumberOf(query);
+    const found = await guard(() => clientFor(accountId).lookupSender(number));
+    respond(id, { result: { account: accountId, ...senderLookup(query, number, found) } });
+  };
+}
+
+function makeSetProfile(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const accountId = accountFor({ account: str(args.account) });
+    const change = parseProfileChange(args);
+    if (change.avatar !== undefined) assertImage(change.avatar);
+    await guard(() => clientFor(accountId).setProfile(change));
+    const result: ProfileApplied = { account: accountId, applied: fieldsOf(change) };
+    respond(id, { result });
+  };
+}
+
+function makeProfile(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const accountId = accountFor({ account: str(args.account) });
+    const user = str(args.user) ?? '';
+    if (user === '') throw new TrainError('whatsapp_user_required', 'profile needs the jid of the person', { retryable: false });
+    const profile = await guard(() => clientFor(accountId).senderProfile(user));
+    respond(id, { result: profile ?? { id: user } });
+  };
+}
+
 export function makeHandleCall(
   clientFor: ClientFor,
 ): (msg: CallMsg) => Promise<void> {
@@ -172,6 +204,9 @@ export function makeHandleCall(
       react: makeReact(clientFor),
       edit: makeEdit(clientFor),
       delete: makeDelete(clientFor),
+      resolve_sender: makeResolveSender(clientFor),
+      set_profile: makeSetProfile(clientFor),
+      profile: makeProfile(clientFor),
     },
     normalize: normalizeWhatsApp,
   });

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

@@ -3,8 +3,8 @@ import {
   assertAttachmentSize,
   saveStreamToCache,
   type SavedAttachment,
-} from '@metro-labs/mcp/stations/attachments';
-import { TrainError } from '@metro-labs/mcp/train-error';
+} from '@metro-labs/core/stations/attachments';
+import { TrainError } from '@metro-labs/core/train-error';
 import { baileysLogger } from './logger.js';
 import type { WAMediaRef } from './media.js';
 

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

@@ -8,7 +8,7 @@ import {
   type SignalDataTypeMap,
   type SignalKeyStore,
 } from 'baileys';
-import { TrainError } from '@metro-labs/mcp/train-error';
+import { TrainError } from '@metro-labs/core/train-error';
 import {
   isPersistedKeyType,
   tokenStoreFor,

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

@@ -1,4 +1,5 @@
 import makeWASocket, {
+  jidNormalizedUser,
   Browsers,
   DisconnectReason,
   fetchLatestWaWebVersion,
@@ -7,12 +8,16 @@ import makeWASocket, {
   type WAMessageKey,
   type WASocket,
 } from 'baileys';
-import { TrainError } from '@metro-labs/mcp/train-error';
-import { errMsg } from '@metro-labs/mcp/log';
+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 { toInbound, toReaction, type ReactionEvent } from './parse.js';
+import type { SenderFound } from './resolve.js';
+import type { ProfileChange } from '@metro-labs/core/stations/profile';
+import { makeProfileCache, nonEmpty, type SenderProfile } from '@metro-labs/core/stations/sender-profile';
+import { toInbound, toReaction, type ReactionEvent, type SelfRef } from './parse.js';
 import { baileysLogger } from './logger.js';
+import { makeNameBook, 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';
@@ -48,6 +53,9 @@ export interface WAClient {
   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>;
 }
 
@@ -61,6 +69,7 @@ interface State {
   keys: KeyCache;
   outbox: Outbox;
   acks: AckWatch;
+  names: NameBook;
 }
 
 type SendOpts = Parameters<WASocket['sendMessage']>[2];
@@ -72,16 +81,28 @@ function resetGate(st: State): void {
   });
 }
 
+function selfRef(st: State, sock: WASocket): SelfRef {
+  const jids = new Set<string>();
+  const me = sock.user;
+  if (me?.id) jids.add(jidNormalizedUser(me.id));
+  if (me?.lid) jids.add(jidNormalizedUser(me.lid));
+  return { jids, sentByMe: (jid, id) => st.keys.lookup(jid, id)?.fromMe === true };
+}
+
 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);
+      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) st.names.note(c.id, c.name ?? c.notify);
+  });
   sock.ev.on('messages.reaction', (events: ReactionEvent[]) => {
     if (!st.handlers) return;
     for (const event of events) {
@@ -191,6 +212,17 @@ async function connect(st: State): Promise<void> {
   bindDelivery(st, sock);
 }
 
+async function lidFor(st: State, sock: WASocket, jid: string): Promise<string | null> {
+  try {
+    return await sock.signalRepository.lidMapping.getLIDForPN(jid);
+  } catch (e) {
+    process.stderr.write(
+      `whatsapp[${st.account.id}] no lid on file for ${jid}: ${errMsg(e)}\n`,
+    );
+    return null;
+  }
+}
+
 async function ready(st: State): Promise<WASocket> {
   await st.openPromise;
   if (!st.sock) throw new TrainError('whatsapp_call', 'socket not connected');
@@ -244,6 +276,22 @@ function mediaContent(m: WAMedia): SendContent {
   };
 }
 
+async function readProfile(st: State, jid: string): Promise<SenderProfile> {
+  const sock = await ready(st);
+  const [statuses, avatar] = await Promise.all([sock.fetchStatus(jid).catch(() => undefined), sock.profilePictureUrl(jid, 'image').catch(() => undefined)]);
+  const about = nonEmpty((statuses?.[0]?.status as { status?: unknown } | undefined)?.status);
+  const picture = nonEmpty(avatar);
+  const phone = phoneOf(jid.endsWith('@lid') ? await sock.signalRepository.lidMapping.getPNForLID(jid).catch(() => null) : jid);
+  const name = st.names.get(jid);
+  return {
+    id: jid,
+    ...(name === undefined ? {} : { display_name: name }),
+    ...(phone === undefined ? {} : { name: phone, address: phone }),
+    ...(about === undefined ? {} : { about }),
+    ...(picture === undefined ? {} : { avatar: picture }),
+  };
+}
+
 export function createClient(account: WhatsAppAccount): WAClient {
   const st: State = {
     account,
@@ -252,8 +300,12 @@ export function createClient(account: WhatsAppAccount): WAClient {
     keys: makeKeyCache(),
     outbox: makeOutbox(),
     acks: makeAckWatch(),
+    names: makeNameBook(),
   };
   resetGate(st);
+  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`),
+  });
   return {
     account,
     self() {
@@ -306,6 +358,24 @@ export function createClient(account: WhatsAppAccount): WAClient {
       const sock = await ready(st);
       return sock.updateMediaMessage(m);
     },
+    async lookupSender(number) {
+      const sock = await ready(st);
+      const found = (await sock.onWhatsApp(number))?.[0];
+      if (found?.exists !== true) return { exists: false, jid: null, lid: null };
+      const jid = jidNormalizedUser(found.jid);
+      return { exists: true, jid, lid: await lidFor(st, sock, jid) };
+    },
+    async setProfile(change) {
+      const sock = await ready(st);
+      if (change.name !== undefined) await sock.updateProfileName(change.name);
+      if (change.bio !== undefined) await sock.updateProfileStatus(change.bio);
+      if (change.avatar !== undefined) {
+        const me = sock.user?.id;
+        if (me === undefined) throw new TrainError('whatsapp_call', 'own jid unknown');
+        await sock.updateProfilePicture(me, { url: change.avatar.path });
+      }
+    },
+    senderProfile: (jid) => senders.get(jid),
     async disconnect() {
       st.closed = true;
       try {