wldx-cli 0.1.1 → 1.0.0

package/src/auth.mjs

@@ -1,9 +1,10 @@
-// The Wildix login of the user, shared with the wildix-auth agent skill: one file per account in
-// $WILDIX_CONFIG_DIR/tokens (default ~/.wildix/tokens), named <e-mail with @ as _at_>.prod.json, holding the Cognito
-// set {IdToken, AccessToken, RefreshToken, ExpiresIn, email, savedAt}. An expired IdToken is renewed with the
-// RefreshToken and written back in the same format, so the skill and the CLI keep using one session.
+// The Wildix login of the user (x-bees, x-hoppers, Collaboration 7): Cognito CUSTOM_AUTH with a one-time code sent
+// by e-mail. Shared with the wildix-auth agent skill: one file per profile (e-mail) in $WILDIX_CONFIG_DIR/tokens (default
+// ~/.wildix/tokens), named <e-mail with @ as _at_>.prod.json, holding the Cognito set {IdToken, AccessToken,
+// RefreshToken, ExpiresIn, email, savedAt}. An expired IdToken is renewed with the RefreshToken and written back in
+// the same format, so the skill and the CLI keep using one session.
 //
-// The token is never printed and never put on a command line or into the environment of a child process.
+// The tokens are never printed and never put on a command line or into the environment of a child process.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -14,17 +15,29 @@ import {USER_AGENT} from './version.mjs';
 export const CLIENT_ID = '2un9vsk5ghu0ocurajqe4a6l1e';
 export const COGNITO_URL = 'https://cognito-idp.eu-central-1.amazonaws.com/';
 const RENEW_EARLY_MS = 60_000;
-export const LOGIN_HINT = 'Log in with the wildix-auth agent skill (npx skills add gorets/wildix-skills -s wildix-auth); `wx login` is not there yet.';
+// Cognito keeps the session of a sign-in that waits for its code for 3 minutes.
+export const PENDING_TTL_MS = 3 * 60_000;
+export const LOGIN_HINT = 'Log in with: wx login <e-mail>';
 
 export const configDir = (env = process.env) => env.WILDIX_CONFIG_DIR || path.join(os.homedir(), '.wildix');
 export const tokensDir = (env = process.env) => path.join(configDir(env), 'tokens');
 
+const EMAIL = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
+
+export function checkEmail(email) {
+  if (typeof email !== 'string' || !EMAIL.test(email) || email.includes('..')) throw new AuthError(`Not a valid e-mail: ${email}`);
+  return email.toLowerCase();
+}
+
 // The e-mail becomes part of a file name: letters, digits and . _ % + - @ only, no "..".
 export function tokenFile(email, env = process.env) {
   if (!/^[A-Za-z0-9._%+@-]+$/.test(email) || email.includes('..')) throw new AuthError(`Not a valid e-mail: ${email}`);
   return path.join(tokensDir(env), `${email.replace(/@/g, '_at_')}.prod.json`);
 }
 
+// A sign-in that waits for its code (wx login --send-code, then --code): the Cognito session, privately.
+export const pendingFile = (email, env = process.env) => path.join(tokensDir(env), `.${email.replace(/@/g, '_at_')}.pending.json`);
+
 function readJson(file) {
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -54,7 +67,7 @@ export function sessions(env = process.env) {
   const dir = tokensDir(env);
   let names;
   try {
-    names = fs.readdirSync(dir).filter((n) => n.endsWith('.prod.json')).sort();
+    names = fs.readdirSync(dir).filter((n) => n.endsWith('.prod.json') && !n.startsWith('.')).sort();
   } catch {
     return [];
   }
@@ -64,65 +77,198 @@ export function sessions(env = process.env) {
     .map((set) => ({email: set.email, expiresAt: expiresAt(set)}));
 }
 
-// Which account: --account, else WILDIX_EMAIL, else the only saved session.
-export function pickAccount(env = process.env, account) {
-  const email = account || env.WILDIX_EMAIL;
-  if (email) return email;
+// ── profiles ─────────────────────────────────────────────────────────────────────────────────────────────────
+// A profile is an e-mail logged in to Wildix. The default one is kept in $WILDIX_CONFIG_DIR/wx.json ({"defaultProfile":
+// e-mail}, 0600); the wildix-auth skill does not read it.
+export const settingsFile = (env = process.env) => path.join(configDir(env), 'wx.json');
+const readSettings = (env) => readJson(settingsFile(env)) ?? {};
+const sameEmail = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
+
+// The default profile, when it is still logged in; else undefined.
+export function defaultProfile(env = process.env) {
+  const wanted = readSettings(env).defaultProfile;
+  return wanted ? sessions(env).find((s) => sameEmail(s.email, wanted))?.email : undefined;
+}
+
+export function setDefaultProfile(email, env = process.env) {
+  const settings = readSettings(env);
+  if (email) settings.defaultProfile = email;
+  else delete settings.defaultProfile;
+  writePrivate(settingsFile(env), settings);
+}
+
+// Which profile, and why: --profile, else WILDIX_EMAIL, else the default profile, else the only one logged in.
+// Returns {email, by: 'option'|'environment'|'default'|'only'}.
+export function chooseProfile(env = process.env, profile) {
   const list = sessions(env);
+  const given = profile || env.WILDIX_EMAIL;
+  // An e-mail given in another case is the saved session of that e-mail.
+  if (given) return {email: list.find((s) => sameEmail(s.email, given))?.email ?? given, by: profile ? 'option' : 'environment'};
   if (!list.length) throw new AuthError(`Not logged in to Wildix. ${LOGIN_HINT}`);
-  if (list.length > 1) {
-    throw new AuthError(`Several Wildix accounts are logged in. Pick one with --account or WILDIX_EMAIL:\n${list.map((s) => `  ${s.email}`).join('\n')}`);
-  }
-  return list[0].email;
+  const byDefault = defaultProfile(env);
+  if (byDefault) return {email: byDefault, by: 'default'};
+  if (list.length === 1) return {email: list[0].email, by: 'only'};
+  throw new AuthError(
+    `Several profiles are logged in and none is the default. Choose one for this command with --profile, or set the default: wx profile use <e-mail>\n${list.map((s) => `  ${s.email}`).join('\n')}`,
+  );
 }
 
+export const pickProfile = (env = process.env, profile) => chooseProfile(env, profile).email;
+
 // The format of the skill: whole seconds, no milliseconds (its bash parses it with `date -f %Y-%m-%dT%H:%M:%SZ`).
 export const stamp = (ms) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
 
+function writePrivate(file, data) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, {recursive: true, mode: 0o700});
+  try {
+    fs.chmodSync(dir, 0o700);
+  } catch {
+    // not ours to change: the file itself is still 0600
+  }
+  const tmp = path.join(dir, `.${path.basename(file)}.${crypto.randomBytes(6).toString('hex')}`);
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, {mode: 0o600, flag: 'wx'});
+  fs.renameSync(tmp, file);
+}
+
 // Writes a token set privately (0600) and atomically; a set without IdToken, RefreshToken and ExpiresIn is refused.
 export function saveTokens(file, set) {
   if (typeof set?.IdToken !== 'string' || typeof set?.RefreshToken !== 'string' || typeof set?.ExpiresIn !== 'number') {
     throw new AuthError('The answer carried no complete set of tokens: nothing was saved.');
   }
-  const dir = path.dirname(file);
-  fs.mkdirSync(dir, {recursive: true, mode: 0o700});
-  const tmp = path.join(dir, `.${path.basename(file)}.${crypto.randomBytes(6).toString('hex')}`);
-  fs.writeFileSync(tmp, `${JSON.stringify(set, null, 2)}\n`, {mode: 0o600, flag: 'wx'});
-  fs.renameSync(tmp, file);
+  writePrivate(file, set);
 }
 
-async function renew(email, set, {env, fetchImpl, now}) {
+// One call to the Cognito identity provider. Returns the answer; throws AuthError with Cognito's reason.
+export async function cognito(target, payload, fetchImpl = globalThis.fetch) {
   const res = await fetchImpl(COGNITO_URL, {
     method: 'POST',
     headers: {
       'user-agent': USER_AGENT,
       'content-type': 'application/x-amz-json-1.1',
       'cache-control': 'no-store',
-      'x-amz-target': 'AWSCognitoIdentityProviderService.InitiateAuth',
+      'x-amz-target': `AWSCognitoIdentityProviderService.${target}`,
     },
-    body: JSON.stringify({AuthFlow: 'REFRESH_TOKEN_AUTH', ClientId: CLIENT_ID, AuthParameters: {REFRESH_TOKEN: set.RefreshToken}, ClientMetadata: {}}),
+    body: JSON.stringify(payload),
     redirect: 'error',
     signal: AbortSignal.timeout(30_000),
   });
   const body = await res.json().catch(() => ({}));
-  const result = body?.AuthenticationResult;
-  if (!res.ok || body?.__type || typeof result?.IdToken !== 'string') {
-    throw new AuthError(`The session of ${email} could not be renewed (${body?.message || body?.__type || `HTTP ${res.status}`}). ${LOGIN_HINT}`);
+  if (!res.ok || body?.__type) {
+    const err = new AuthError(body?.message || body?.__type || `HTTP ${res.status}`);
+    err.type = body?.__type;
+    throw err;
+  }
+  return body ?? {};
+}
+
+async function renew(email, set, {env, fetchImpl, now}) {
+  let body;
+  try {
+    body = await cognito('InitiateAuth', {AuthFlow: 'REFRESH_TOKEN_AUTH', ClientId: CLIENT_ID, AuthParameters: {REFRESH_TOKEN: set.RefreshToken}, ClientMetadata: {}}, fetchImpl);
+  } catch (e) {
+    if (e instanceof AuthError) throw new AuthError(`The session of ${email} could not be renewed (${e.message}). ${LOGIN_HINT}`);
+    throw e;
   }
-  // Cognito does not send a new RefreshToken on a refresh: the saved one is kept.
-  const next = {...result, email, savedAt: stamp(now), RefreshToken: set.RefreshToken, ExpiresIn: result.ExpiresIn ?? set.ExpiresIn};
+  const result = body.AuthenticationResult;
+  if (typeof result?.IdToken !== 'string') throw new AuthError(`The session of ${email} could not be renewed. ${LOGIN_HINT}`);
+  // Cognito sends no new RefreshToken on a refresh unless rotation is on for the client: then the new one is kept,
+  // else the saved one.
+  const next = {...result, email, savedAt: stamp(now), RefreshToken: result.RefreshToken ?? set.RefreshToken, ExpiresIn: result.ExpiresIn ?? set.ExpiresIn};
   saveTokens(tokenFile(email, env), next);
   return next;
 }
 
-// A valid IdToken of the account: WILDIX_ID_TOKEN as given (tests, CI), else the saved session, renewed when it
-// expires within a minute.
-export async function getToken({account, env = process.env, fetchImpl = globalThis.fetch, now = Date.now()} = {}) {
-  if (env.WILDIX_ID_TOKEN) return env.WILDIX_ID_TOKEN;
-  const email = pickAccount(env, account);
+// The saved token set of the profile as it is (not renewed), or undefined.
+export function savedSession(email, env = process.env) {
+  const set = readJson(tokenFile(email, env));
+  return typeof set?.IdToken === 'string' ? set : undefined;
+}
+
+// The saved token set of the profile, renewed when its IdToken expires within a minute.
+export async function getSession({profile, env = process.env, fetchImpl = globalThis.fetch, now = Date.now()} = {}) {
+  const email = pickProfile(env, profile);
   const set = readJson(tokenFile(email, env));
   if (typeof set?.IdToken !== 'string') throw new AuthError(`No saved session for ${email}. ${LOGIN_HINT}`);
-  if (expiresAt(set) - RENEW_EARLY_MS > now) return set.IdToken;
+  if (expiresAt(set) - RENEW_EARLY_MS > now) return set;
   if (typeof set.RefreshToken !== 'string') throw new AuthError(`The session of ${email} has expired. ${LOGIN_HINT}`);
-  return (await renew(email, set, {env, fetchImpl, now})).IdToken;
+  return renew(email, set, {env, fetchImpl, now});
+}
+
+// A valid IdToken of the profile: WILDIX_ID_TOKEN as given (tests, CI), else the saved session (renewed).
+export async function getToken(options = {}) {
+  const env = options.env ?? process.env;
+  if (env.WILDIX_ID_TOKEN) return env.WILDIX_ID_TOKEN;
+  return (await getSession(options)).IdToken;
+}
+
+// ── signing in ───────────────────────────────────────────────────────────────────────────────────────────────
+// Starts a sign-in: Wildix sends a one-time code to the e-mail. Returns the Cognito session that the code answers.
+export async function startLogin(email, fetchImpl = globalThis.fetch) {
+  let body;
+  try {
+    body = await cognito('InitiateAuth', {AuthFlow: 'CUSTOM_AUTH', ClientId: CLIENT_ID, AuthParameters: {USERNAME: email}, ClientMetadata: {}}, fetchImpl);
+  } catch (e) {
+    if (e instanceof AuthError) throw new AuthError(`Wildix did not start a sign-in for ${email}: ${e.message}`);
+    throw e;
+  }
+  if (typeof body.Session !== 'string') throw new AuthError(`Wildix did not start a sign-in for ${email}.`);
+  return body.Session;
+}
+
+// Answers the code. Returns {saved: true} with the session stored, or {saved: false, session} when the code was not
+// accepted (Cognito answers a wrong code with a new challenge and a new session, which takes the next try).
+export async function finishLogin(email, session, code, {env = process.env, fetchImpl = globalThis.fetch, now = Date.now()} = {}) {
+  let body;
+  try {
+    body = await cognito('RespondToAuthChallenge', {
+      ChallengeName: 'CUSTOM_CHALLENGE',
+      ChallengeResponses: {USERNAME: email, ANSWER: code},
+      ClientId: CLIENT_ID,
+      Session: session,
+    }, fetchImpl);
+  } catch (e) {
+    if (e instanceof AuthError) throw new AuthError(`The sign-in of ${email} failed: ${e.message}. Start again: wx login ${email}`);
+    throw e;
+  }
+  const result = body.AuthenticationResult;
+  if (typeof result?.IdToken !== 'string') return {saved: false, session: body.Session};
+  saveTokens(tokenFile(email, env), {...result, email, savedAt: stamp(now)});
+  // The first profile becomes the default one; a second login does not change it.
+  const isDefault = !defaultProfile(env) || sameEmail(defaultProfile(env), email);
+  if (!defaultProfile(env)) setDefaultProfile(email, env);
+  return {saved: true, isDefault};
+}
+
+export function savePending(email, session, {env = process.env, now = Date.now()} = {}) {
+  writePrivate(pendingFile(email, env), {email, session, startedAt: now});
+}
+
+// The waiting sign-in of the e-mail, or undefined when there is none or it is older than Cognito keeps it.
+export function readPending(email, {env = process.env, now = Date.now()} = {}) {
+  const p = readJson(pendingFile(email, env));
+  if (typeof p?.session !== 'string' || !(now - p.startedAt < PENDING_TTL_MS)) return undefined;
+  return p;
+}
+
+export function dropPending(email, env = process.env) {
+  fs.rmSync(pendingFile(email, env), {force: true});
+}
+
+// ── signing out ──────────────────────────────────────────────────────────────────────────────────────────────
+// Revokes the refresh token of the profile (this device) and deletes its local session. With everywhere, signs the
+// profile out of every device (GlobalSignOut, which needs a valid AccessToken). An error leaves the local session
+// as it was: it is still valid, and the call can be repeated.
+export async function logout(email, {everywhere = false, env = process.env, fetchImpl = globalThis.fetch, now = Date.now()} = {}) {
+  const file = tokenFile(email, env);
+  const set = readJson(file);
+  if (!set) throw new AuthError(`No saved session for ${email}.`);
+  if (everywhere) {
+    const fresh = await getSession({profile: email, env, fetchImpl, now});
+    await cognito('GlobalSignOut', {AccessToken: fresh.AccessToken}, fetchImpl);
+  } else {
+    await cognito('RevokeToken', {Token: set.RefreshToken, ClientId: CLIENT_ID}, fetchImpl);
+  }
+  fs.rmSync(file, {force: true});
+  if (sameEmail(readSettings(env).defaultProfile ?? '', email)) setDefaultProfile(undefined, env);
 }

package/src/chat/format.mjs

@@ -0,0 +1,97 @@
+// Text output of the chat commands: one line per channel, message, member or person, local times, names of
+// people instead of their ids (looked up by the command, see withNames in lib.mjs).
+import {localTime, oneLine, paint, table} from '../format.mjs';
+import {displayName, nameIn} from './lib.mjs';
+
+const reactions = (counts) => {
+  const parts = Object.entries(counts ?? {}).filter(([, n]) => n > 0).map(([t, n]) => `${t} ${n}`);
+  return parts.length ? `[${parts.join(', ')}]` : '';
+};
+
+// The text of a message on one line, with what goes with it: files, reply, edits, reactions.
+export function messageText(m, data, {max = 2000} = {}) {
+  if (!m) return '';
+  if (m.messageType === 'deleted' || m.deletedAt) return '(deleted)';
+  const parts = [];
+  if (m.system) parts.push('[system]');
+  if (m.quote) parts.push(`(reply to ${nameIn(data, m.quote.userId)})`);
+  if (m.forward) parts.push('(forwarded)');
+  if (m.text) parts.push(oneLine(m.text, max));
+  for (const f of m.attachments ?? []) parts.push(`[file: ${oneLine(f.name, 80)}]`);
+  if (m.giphy) parts.push('[giphy]');
+  if (m.pollId) parts.push('[poll]');
+  if (m.editedAt) parts.push('(edited)');
+  if (m.pinned) parts.push('(pinned)');
+  const r = reactions(m.reactionCounts);
+  if (r) parts.push(r);
+  return parts.join(' ');
+}
+
+// Messages as a transcript, oldest first: time, author, text, and the message id.
+export function messageLines(messages, data, ctx) {
+  const c = paint(ctx);
+  const sorted = [...(messages ?? [])].sort((a, b) => (a.timelineSeq ?? 0) - (b.timelineSeq ?? 0));
+  return table(sorted.map((m) => [c.dim(localTime(m.createdAt)), c.bold(nameIn(data, m.userId) || '?'), `${messageText(m, data)}  ${c.dim(m.messageId)}`]));
+}
+
+// The title of a channel: its subject, or for a 1:1 channel the name of the other person.
+export const channelTitle = (ch, data) => ch?.subject || (ch?.peerId ? nameIn(data, ch.peerId) : '') || (ch?.channelType === 'direct' ? '(direct)' : '(no subject)');
+
+// The people a channel line names: the other person of a 1:1 channel, the author of the last message.
+export const channelUserIds = (ch) => [ch?.peerId, ch?.lastMessage?.userId];
+
+function flags(ch, c) {
+  const i = ch.inbox;
+  if (!i) return '';
+  const f = [];
+  if (i.unreadCount) f.push(c.yellow(`${i.unreadCount} new`));
+  if (i.mentionUnreadCount) f.push(c.yellow(`@${i.mentionUnreadCount}`));
+  if (i.pinned) f.push('pinned');
+  if (i.muted) f.push('muted');
+  if (i.hidden) f.push('archived');
+  return f.join(' ');
+}
+
+const preview = (ch, data) => {
+  const m = ch.lastMessage;
+  if (!m) return '';
+  const text = m.messageType === 'deleted' ? '(deleted)' : oneLine(m.text ?? (m.pollId ? '[poll]' : ''), 80);
+  return `${nameIn(data, m.userId)}: ${text}`;
+};
+
+// Channels: last activity, id, inbox flags, title, the last message.
+export function channelLines(channels, data, ctx) {
+  const c = paint(ctx);
+  return table((channels ?? []).map((ch) => [c.dim(localTime(ch.lastActivityAt)), ch.channelId, flags(ch, c), c.bold(oneLine(channelTitle(ch, data), 50)), c.dim(preview(ch, data))]));
+}
+
+export function channelDetails(ch, data, ctx) {
+  const c = paint(ctx);
+  if (!ch) return [];
+  const rows = [
+    ['Channel', ch.channelId],
+    ['Title', c.bold(channelTitle(ch, data))],
+    ['Type', [ch.channelType, ch.access, ch.broadcast && 'broadcast', ch.external && 'external'].filter(Boolean).join(' · ')],
+  ];
+  if (ch.description) rows.push(['Description', oneLine(ch.description, 300)]);
+  if (ch.peerId) rows.push(['With', `${nameIn(data, ch.peerId)} (${ch.peerId})`]);
+  rows.push(['Members', String(ch.membersCount ?? '')]);
+  rows.push(['Created', `${localTime(ch.createdAt)}${ch.createdBy ? ` by ${nameIn(data, ch.createdBy)}` : ''}`]);
+  rows.push(['Last activity', localTime(ch.lastActivityAt)]);
+  if (ch.pinnedMessageIds?.length) rows.push(['Pinned', ch.pinnedMessageIds.join(', ')]);
+  if (ch.autoRecord !== undefined || ch.autoTranscribe !== undefined) {
+    rows.push(['Conferences', [ch.autoRecord && 'auto record', ch.autoTranscribe && 'auto transcribe'].filter(Boolean).join(', ') || 'manual']);
+  }
+  if (ch.inbox) rows.push(['Inbox', flags(ch, c) || 'read']);
+  return table(rows);
+}
+
+// A person on one line: name, id, e-mail, extension, bot.
+export function userLine(u, c) {
+  return [c.bold(displayName(u) ?? ''), u.id, u.email ?? '', u.pbxExtension ? `ext ${u.pbxExtension}` : '', u.bot ? 'bot' : '', u.deactivatedAt ? c.dim('deactivated') : ''];
+}
+
+export const nextPage = (cursor, c) => (cursor ? [c.dim(`More: --cursor ${cursor}`)] : []);
+
+// The text of a command that changes something: what was done (the JSON output keeps the answer of the service).
+export const done = (what) => (r, ctx) => (typeof what === 'function' ? what(r, ctx) : what);

package/src/chat/lib.mjs

@@ -0,0 +1,162 @@
+// Helpers of the chat commands (wx chat, channel, inbox, file, user, section): the checks of the agent skill's
+// lib.sh (whole numbers in a range, ids, reaction types, secret paths), the user id of the logged-in user, names
+// of users for the text output, and the presigned upload and download of files (no token goes to those URLs).
+import {randomUUID} from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {jwtClaims} from '../auth.mjs';
+import {UsageError} from '../errors.mjs';
+import {readForUpload, refuseUnsafeWrite} from '../files.mjs';
+import {apiPath, request} from '../http.mjs';
+import {streamClient} from '../stream.mjs';
+
+// The operations the service answers with HTTP 400 "Operation <Name> is not implemented." (checked 2026-11-05).
+export const NOT_IMPLEMENTED_CHECKED = '2026-11-05';
+export const NOT_IMPLEMENTED = ' (not implemented by the service yet)';
+export const notImplemented = (operation) =>
+  `The service does not implement ${operation} yet (it answers HTTP 400 "Operation ${operation} is not implemented.", checked ${NOT_IMPLEMENTED_CHECKED}). Do not retry it.`;
+
+// A whole number from min to max (the service refuses anything else with a 400 that tells little); undefined stays.
+export function checkInt(name, value, min, max) {
+  if (value === undefined) return undefined;
+  const s = String(value);
+  if (!/^\d{1,12}$/.test(s) || Number(s) < min || Number(s) > max) throw new UsageError(`--${name} must be a whole number from ${min} to ${max}: ${value}`);
+  return Number(s);
+}
+
+// An id that goes into a request path or a body: id characters only, never "/", "?", "#", ".." or nothing.
+export function checkId(what, value) {
+  const v = String(value ?? '');
+  if (!/^[A-Za-z0-9_+][A-Za-z0-9_.:+-]*$/.test(v) || v.includes('..')) throw new UsageError(`${what} is not a valid id: ${value}`);
+  return v;
+}
+
+export function checkReaction(type) {
+  if (!/^[a-z0-9_+-]{1,64}$/.test(String(type))) throw new UsageError(`A reaction type must match [a-z0-9_+-] (up to 64): ${type}`);
+  return type;
+}
+
+// The id of a new group channel: 8-4-4-4-8 characters. Without one the service makes a 36-character id that none
+// of its own calls accepts afterwards.
+export const CHANNEL_ID = /^[0-9a-z_]{8}-[0-9a-z_]{4}-[0-9a-z_]{4}-[0-9a-z_]{4}-[0-9a-z_]{8}$/;
+export const newChannelId = () => randomUUID().slice(0, -4);
+
+// The text argument; "-" reads stdin.
+export async function readText(arg, stdin) {
+  if (arg !== '-') return arg;
+  const chunks = [];
+  for await (const c of stdin) chunks.push(Buffer.from(c));
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export const api = (ctx) => ctx.client(streamClient);
+
+// The stream user id of the logged-in user, found by the e-mail of the token (once per context).
+const ME = Symbol('me');
+export async function meId(ctx, client = api(ctx)) {
+  if (ctx[ME]) return ctx[ME];
+  const email = jwtClaims(ctx.token).email;
+  if (!email) throw new Error('The login token carries no e-mail');
+  const r = await client.call('POST', '/users/query', {query: {emails: [email]}});
+  const id = r?.users?.[0]?.id;
+  if (!id) throw new Error('Could not find your chat user');
+  ctx[ME] = id;
+  return id;
+}
+
+export const displayName = (u) => u?.displayName ?? u?.name;
+
+// The users of these ids, one users query per 100 ids: Map id -> user. A lookup that fails gives no users (a name
+// is a nicety of the text output: the id is printed instead).
+export async function usersById(client, ids) {
+  const unique = [...new Set(ids.filter((id) => typeof id === 'string' && id))];
+  const out = new Map();
+  for (let i = 0; i < unique.length; i += 100) {
+    try {
+      const r = await client.call('POST', '/users/query', {query: {ids: unique.slice(i, i + 100)}});
+      for (const u of r?.users ?? []) out.set(u.id, u);
+    } catch {
+      // names stay ids
+    }
+  }
+  return out;
+}
+
+// Names for the text output ride on the result under a symbol: JSON output (JSON.stringify) never sees them.
+export const NAMES = Symbol('names');
+export async function withNames(ctx, data, ids, client = api(ctx)) {
+  if (ctx.output !== 'text' || !data || typeof data !== 'object') return data;
+  const users = await usersById(client, ids);
+  Object.defineProperty(data, NAMES, {value: users, enumerable: false});
+  return data;
+}
+export const nameIn = (data, id) => (id ? displayName(data?.[NAMES]?.get(id)) ?? id : '');
+
+// The ids of people a message names: its author, the author of its quote.
+export const messageUserIds = (m) => [m?.userId, m?.quote?.userId, m?.pinnedBy];
+
+// ── files ───────────────────────────────────────────────────────────────────────────────────────────────────
+
+// The checks of files to attach and to save: src/files.mjs.
+export {refuseSecretPath} from '../files.mjs';
+
+const MIME = {
+  txt: 'text/plain', md: 'text/markdown', csv: 'text/csv', html: 'text/html', htm: 'text/html', css: 'text/css', js: 'text/javascript',
+  json: 'application/json', xml: 'application/xml', pdf: 'application/pdf', zip: 'application/zip', gz: 'application/gzip',
+  tar: 'application/x-tar', doc: 'application/msword', docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint', pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml', heic: 'image/heic',
+  mp3: 'audio/mpeg', wav: 'audio/wav', ogg: 'audio/ogg', m4a: 'audio/mp4', mp4: 'video/mp4', mov: 'video/quicktime', webm: 'video/webm',
+};
+export const mimeOf = (file) => MIME[path.extname(file).slice(1).toLowerCase()] ?? 'application/octet-stream';
+
+// A presigned URL of the storage: https (http only with WILDIX_ALLOW_CUSTOM_URL=1, tests). It gets no token.
+function presigned(url, env) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    throw new Error('The service gave no valid storage link');
+  }
+  if (u.protocol !== 'https:' && !(env.WILDIX_ALLOW_CUSTOM_URL === '1' && u.protocol === 'http:')) throw new Error(`The storage link is not https: ${u.protocol}`);
+  return u.href;
+}
+
+const ATTACHMENT_FIELDS = ['fsId', 'name', 'size', 'mime', 'width', 'height', 'thumbnail'];
+export const attachmentOf = (f) => Object.fromEntries(ATTACHMENT_FIELDS.filter((k) => f?.[k] !== undefined && f?.[k] !== null).map((k) => [k, f[k]]));
+
+// Uploads a file to a channel and returns the attachment object to put into a message (fsId, name, size, mime…).
+export async function uploadFile(ctx, channel, file, client = api(ctx)) {
+  const data = readForUpload(path.resolve(ctx.cwd ?? process.cwd(), file), ctx.env);
+  const name = path.basename(file);
+  const r = await client.call('POST', apiPath`/channels/${channel}/files`, {name});
+  if (!r?.fsId || !r?.presignedUploadUrl) throw new Error('Unexpected answer of the upload: no fsId or link');
+  const fsId = checkId('The file id of the answer', r.fsId);
+  await request(presigned(r.presignedUploadUrl, ctx.env), {method: 'PUT', raw: {data, contentType: mimeOf(file)}, responseType: 'text', fetchImpl: ctx.fetch, timeoutMs: 600_000, service: 'the storage'});
+  const info = await client.call('GET', apiPath`/channels/${channel}/files/${fsId}`);
+  return attachmentOf(info?.file ?? {fsId, name, size: data.length});
+}
+
+// Saves a file of a message to `to`, which must not exist yet (nothing is ever overwritten).
+export async function downloadFile(ctx, channel, message, fsId, to, client = api(ctx)) {
+  const out = path.resolve(ctx.cwd ?? process.cwd(), to);
+  refuseUnsafeWrite(out, ctx.env);
+  if (fs.existsSync(out)) throw new UsageError(`${to} exists already: choose another path (nothing was overwritten or deleted)`);
+  const dir = path.dirname(out);
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw new UsageError(`The folder of ${to} does not exist`);
+  const r = await client.call('GET', apiPath`/channels/${channel}/messages/${message}/files/${fsId}/download-url` + '?download=1');
+  if (!r?.presignedDownloadUrl) throw new Error('No download link in the answer');
+  const data = await request(presigned(r.presignedDownloadUrl, ctx.env), {responseType: 'buffer', fetchImpl: ctx.fetch, timeoutMs: 600_000, service: 'the storage'});
+  const tmp = path.join(dir, `.download.${process.pid}.${randomUUID().slice(0, 8)}`);
+  fs.writeFileSync(tmp, data, {flag: 'wx', mode: 0o600});
+  try {
+    fs.linkSync(tmp, out); // fails when the path appeared meanwhile: never overwrites
+  } catch (e) {
+    if (e.code === 'EEXIST') throw new UsageError(`${to} appeared meanwhile: nothing was overwritten`);
+    throw e;
+  } finally {
+    fs.rmSync(tmp, {force: true});
+  }
+  return {ok: true, file: out, bytes: data.length};
+}