wldx-cli 0.1.1 → 1.1.0

package/src/phone/pbx.mjs

@@ -0,0 +1,158 @@
+// The Call Control REST API of the user's PBX (https://<pbx>/api/v2/call-control/), as the wildix-call-control
+// skill calls it (scripts/lib.sh pbx_call): the PBX from the claims of the login token, the same token as Bearer,
+// answers {"type":"result","result":X} unwrapped, {"type":"error","reason":…} (or a status other than 2xx) turned
+// into an error with a hint per status. Also the checks of call ids, numbers and device contacts of the skill.
+import {jwtClaims} from 'wldx-core/auth';
+import {AuthError, UsageError} from 'wldx-core/errors';
+import {request} from 'wldx-core/http';
+import {pbxUrl} from 'wldx-core/services';
+
+// The SIP watchers that register as a device of the user: wx's own and the one of the skill (sip.sh). They are
+// marked in the device lists and never chosen to ring or to place a call.
+export const WATCHER_USER_AGENT = 'wx watcher';
+const WATCHERS = new Set([WATCHER_USER_AGENT, 'wildix-agent-skills watcher']);
+export const isWatcher = (userAgent) => WATCHERS.has(userAgent);
+
+export class PbxError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = 'PbxError';
+    this.status = status;
+  }
+}
+
+const HINTS = {
+  401: 'The PBX rejected the login: log in again (wx login <e-mail>). A PBX accepts only the login of its own environment (a production login works only on a production PBX).',
+  403: 'The PBX does not allow this to this user: an ordinary user controls only their own calls and devices.',
+  503: 'The PBX could not reach its call engine: try again in a moment.',
+};
+
+function hint(status, reason) {
+  if (status === 404) {
+    return reason.includes('404 Not Found')
+      ? 'This PBX has no Call Control API: it needs a newer WMS version.'
+      : "The PBX does not see this call among the user's current calls: list them again (wx phone list).";
+  }
+  return HINTS[status];
+}
+
+// pbxCall(ctx, METHOD, '/list-calls/', body?): the `result` of the answer (or the whole answer without one).
+export async function pbxCall(ctx, method, path, body) {
+  if (!/^\/[a-z-]+\/$/.test(path)) throw new Error(`not a call-control path: ${path}`);
+  const base = pbxUrl(ctx.token, ctx.env);
+  let res;
+  try {
+    res = await request(`${base}/api/v2/call-control${path}`, {
+      method,
+      token: ctx.token,
+      body,
+      fetchImpl: ctx.fetch,
+      responseType: 'response',
+      timeoutMs: 30_000,
+      service: 'the PBX',
+    });
+  } catch {
+    throw new PbxError(`request failed: ${method} ${path} (the PBX ${base} did not answer)`);
+  }
+  const text = await res.text().catch(() => '');
+  let data;
+  try {
+    data = text ? JSON.parse(text) : undefined;
+  } catch {
+    data = undefined;
+  }
+  if (!res.ok || data?.type === 'error') {
+    let reason;
+    if (data === undefined) reason = text.slice(0, 500);
+    else reason = JSON.stringify(data && typeof data === 'object' && data.reason ? data.reason : data);
+    const lines = [`HTTP ${res.status} from the PBX (${method} ${path}): ${reason}`];
+    const h = hint(res.status, reason);
+    if (h) lines.push(h);
+    throw new PbxError(lines.join('\n'), res.status);
+  }
+  if (data === undefined) return text ? {text} : {};
+  return data?.result ?? data;
+}
+
+// An action: {ok: true, message} (the message of the PBX, or its whole answer).
+export async function pbxAction(ctx, method, path, body) {
+  const r = await pbxCall(ctx, method, path, body);
+  return {ok: true, message: r?.message ?? r};
+}
+
+// A SIP call id as list-calls gives it (the PBX checks the same pattern).
+export function checkCallId(id) {
+  const v = String(id ?? '');
+  if (!/^[A-Za-z0-9.!%*_'+~-]+(@[A-Za-z0-9.-]+)?$/.test(v) || v.length > 100)
+    throw new UsageError(`not a call id (take sipCallId from: wx phone list): ${id}`);
+  return v;
+}
+
+// A number to call or to transfer to: an extension, a phone number, a feature code like *76. Spaces, dashes, dots
+// and brackets that people write in phone numbers are dropped; what is left must be +, digits, * and #.
+export function normNumber(input) {
+  const v = String(input ?? '').replace(/[\s\-.()]/g, '');
+  if (!/^\+?[0-9*#]+$/.test(v) || v.length > 40) throw new UsageError(`not a phone number or extension: ${input}`);
+  return v;
+}
+
+export function checkContact(contact) {
+  const v = String(contact ?? '');
+  if (!/^sip:\S+$/.test(v) || v.length > 255)
+    throw new UsageError(`a device is its SIP contact, as wx phone devices gives it (sip:…): ${contact}`);
+  return v;
+}
+
+export function checkDigits(digits) {
+  const v = String(digits ?? '');
+  if (!/^[0-9*#]+$/.test(v)) throw new UsageError(`DTMF digits are 0-9, * and #: ${digits}`);
+  return v;
+}
+
+// The extension of the login (custom:pbx_user_extension).
+export function extensionOf(token) {
+  const ext = jwtClaims(token)['custom:pbx_user_extension'];
+  if (!/^[0-9]+$/.test(String(ext ?? '')))
+    throw new UsageError('this login has no PBX extension (custom:pbx_user_extension)');
+  return String(ext);
+}
+
+// The SIP password of the user: the PBX gives it to the user's own login token. Never printed.
+export async function sipPassword(ctx, extension) {
+  const base = pbxUrl(ctx.token, ctx.env);
+  let res;
+  try {
+    // Without `Connection: close` the socket of this request may be reused for the SIP WebSocket to the same host,
+    // which the PBX then closes at once (seen with the skill).
+    res = await request(`${base}/api/v1/personal/info?fields=extension%2CsipPassword`, {
+      token: ctx.token,
+      fetchImpl: ctx.fetch,
+      headers: {connection: 'close'},
+      responseType: 'response',
+      timeoutMs: 30_000,
+    });
+  } catch {
+    throw new PbxError(`request failed: GET /api/v1/personal/info (the PBX ${base} did not answer)`);
+  }
+  if (res.status === 401) throw new AuthError('the PBX rejected the login: log in again (wx login <e-mail>)');
+  if (!res.ok) throw new PbxError(`the PBX gave no personal info (HTTP ${res.status})`, res.status);
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = undefined;
+  }
+  const info = body?.result ?? body;
+  if (!info?.sipPassword) throw new PbxError('the PBX did not give the SIP password of this user');
+  if (String(info.extension) !== String(extension))
+    throw new PbxError(`the PBX answered for extension ${info.extension}, not ${extension}`);
+  return String(info.sipPassword);
+}
+
+// The SIP WebSocket of the PBX: wss://<host>/sip/ (the host and port of the PBX address; ws:// only for a custom
+// http:// address in tests) and the SIP domain (the host name).
+export function sipEndpoint(token, env) {
+  const base = new URL(pbxUrl(token, env));
+  const scheme = base.protocol === 'http:' ? 'ws:' : 'wss:';
+  return {wsUrl: `${scheme}//${base.host}/sip/`, domain: base.hostname};
+}

package/src/phone/sip.mjs

@@ -0,0 +1,386 @@
+// A minimal SIP user agent over a WebSocket (RFC 7118), with Node built-ins only: the global WebSocket and
+// node:crypto (MD5 digest). It carries no media and makes no calls: it registers, subscribes, publishes and answers
+// what the PBX sends. Only what the call control of the Wildix PBX needs: non-INVITE client transactions (a WebSocket
+// is reliable: no retransmissions), digest authentication (RFC 2617/3261, MD5, qop=auth), incoming requests answered
+// at once (NOTIFY to the subscriptions, INVITE turned down with 480, OPTIONS 200). The wire format follows sip.js
+// 0.21 (the library the wildix-call-control skill runs), so the PBX sees the same kind of client.
+//
+// Security: the SIP password is used only to compute the digest; it is never sent, printed or put in an error.
+import {EventEmitter} from 'node:events';
+import {createHash, randomBytes} from 'node:crypto';
+
+const ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+export const randomToken = (n) => [...randomBytes(n)].map((b) => ALPHABET[b % ALPHABET.length]).join('');
+const md5 = (s) => createHash('md5').update(s).digest('hex');
+
+export const ALLOWED = [
+  'ACK',
+  'BYE',
+  'CANCEL',
+  'INFO',
+  'INVITE',
+  'MESSAGE',
+  'NOTIFY',
+  'OPTIONS',
+  'PRACK',
+  'REFER',
+  'REGISTER',
+  'SUBSCRIBE',
+];
+const COMPACT = {
+  i: 'call-id',
+  f: 'from',
+  t: 'to',
+  v: 'via',
+  m: 'contact',
+  l: 'content-length',
+  c: 'content-type',
+  o: 'event',
+  k: 'supported',
+  u: 'allow-events',
+  e: 'content-encoding',
+  s: 'subject',
+  r: 'refer-to',
+  b: 'referred-by',
+  x: 'session-expires',
+};
+const TRANSACTION_TIMEOUT_MS = 32_000; // Timer F of RFC 3261
+
+// One SIP message from its text: {method, uri} for a request or {status, reason} for a response; header(name) gives
+// the first value of a header, headers(name) all of them (names without case; compact forms understood).
+export function parseMessage(raw) {
+  const s = String(raw);
+  let split = s.indexOf('\r\n\r\n');
+  let sep = 4;
+  if (split < 0) {
+    split = s.indexOf('\n\n');
+    sep = 2;
+  }
+  const head = split < 0 ? s : s.slice(0, split);
+  const body = split < 0 ? '' : s.slice(split + sep);
+  const lines = head.split(/\r?\n/).reduce((out, l) => {
+    if (/^[ \t]/.test(l) && out.length) out[out.length - 1] += ` ${l.trim()}`;
+    else out.push(l);
+    return out;
+  }, []);
+  const first = lines.shift() ?? '';
+  const msg = {headerList: [], body};
+  let m;
+  if ((m = /^SIP\/2\.0 (\d{3})(?: (.*))?$/.exec(first))) Object.assign(msg, {status: Number(m[1]), reason: m[2] ?? ''});
+  else if ((m = /^([A-Za-z]+) (\S+) SIP\/2\.0$/.exec(first)))
+    Object.assign(msg, {method: m[1].toUpperCase(), uri: m[2]});
+  else throw new Error('not a SIP message');
+  for (const l of lines) {
+    const c = l.indexOf(':');
+    if (c <= 0) continue;
+    let name = l.slice(0, c).trim().toLowerCase();
+    name = COMPACT[name] ?? name;
+    msg.headerList.push([name, l.slice(c + 1).trim()]);
+  }
+  msg.headers = (name) => msg.headerList.filter(([n]) => n === name.toLowerCase()).map(([, v]) => v);
+  msg.header = (name) => msg.headers(name)[0];
+  return msg;
+}
+
+// Parts of header values.
+export const tagOf = (value) => paramOf(value, 'tag');
+export const uriOf = (value) => {
+  const v = String(value ?? '');
+  const a = /<([^>]*)>/.exec(v);
+  return a ? a[1] : v.split(';')[0].trim();
+};
+export function paramOf(value, name) {
+  // The display name and the URI may hold ";tag=" themselves: only the parameters after them count.
+  const v = String(value ?? '')
+    .replace(/^\s*"(?:[^"\\]|\\.)*"/, '')
+    .replace(/<[^>]*>/, '');
+  const m = new RegExp(`;\\s*${name}\\s*=\\s*(?:"([^"]*)"|([^;,\\s]+))`, 'i').exec(v);
+  return m ? (m[1] ?? m[2]) : undefined;
+}
+const branchOf = (via) => /;\s*branch=([^;,\s]+)/i.exec(via ?? '')?.[1];
+const splitList = (values) =>
+  values.flatMap((v) => v.split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)(?![^<]*>)/).map((x) => x.trim())).filter(Boolean);
+
+// A digest challenge (WWW-Authenticate / Proxy-Authenticate) as {realm, nonce, qop, opaque, algorithm, stale}.
+export function parseChallenge(value) {
+  const v = String(value ?? '');
+  if (!/^\s*Digest\s/i.test(v)) return undefined;
+  const out = {};
+  for (const m of v.replace(/^\s*Digest\s+/i, '').matchAll(/([A-Za-z-]+)\s*=\s*(?:"([^"]*)"|([^,\s]+))/g))
+    out[m[1].toLowerCase()] = m[2] ?? m[3];
+  return out;
+}
+
+// The Authorization value for a challenge (MD5; qop auth when offered), as sip.js computes it.
+export function digestAuthorization({username, password, method, uri, challenge, nc = 1, cnonce = randomToken(12)}) {
+  const algorithm = challenge.algorithm ?? 'MD5';
+  if (algorithm.toUpperCase() !== 'MD5')
+    throw new Error(`the PBX asks for a digest algorithm other than MD5: ${algorithm}`);
+  if (!challenge.realm || !challenge.nonce) throw new Error('the PBX sent a digest challenge without realm or nonce');
+  const qops = (challenge.qop ?? '').split(',').map((q) => q.trim());
+  const qop = challenge.qop === undefined ? undefined : qops.includes('auth') ? 'auth' : undefined;
+  if (challenge.qop !== undefined && !qop)
+    throw new Error(`the PBX asks for a digest qop other than auth: ${challenge.qop}`);
+  const ha1 = md5(`${username}:${challenge.realm}:${password}`);
+  const ha2 = md5(`${method}:${uri}`);
+  const ncHex = nc.toString(16).padStart(8, '0');
+  const response = qop
+    ? md5(`${ha1}:${challenge.nonce}:${ncHex}:${cnonce}:${qop}:${ha2}`)
+    : md5(`${ha1}:${challenge.nonce}:${ha2}`);
+  const parts = [
+    `algorithm=MD5`,
+    `username="${username}"`,
+    `realm="${challenge.realm}"`,
+    `nonce="${challenge.nonce}"`,
+    `uri="${uri}"`,
+    `response="${response}"`,
+  ];
+  if (challenge.opaque !== undefined) parts.push(`opaque="${challenge.opaque}"`);
+  if (qop) parts.push(`qop=${qop}`, `cnonce="${cnonce}"`, `nc=${ncHex}`);
+  return `Digest ${parts.join(', ')}`;
+}
+
+// The user agent: one WebSocket to the PBX. Events: 'request' (an incoming request already answered: NOTIFYs go to
+// onNotify), 'disconnect' (the socket closed). onNotify(request) returns true when the NOTIFY belongs to a
+// subscription (answered 200), false otherwise (481).
+export class SipUserAgent extends EventEmitter {
+  constructor({
+    wsUrl,
+    domain,
+    extension,
+    password,
+    userAgent,
+    WebSocketImpl = globalThis.WebSocket,
+    keepAliveSeconds = 30,
+    timeoutMs = TRANSACTION_TIMEOUT_MS,
+  }) {
+    super();
+    this.wsUrl = wsUrl;
+    this.domain = domain;
+    this.extension = extension;
+    this.password = password;
+    this.userAgent = userAgent;
+    this.WebSocketImpl = WebSocketImpl;
+    this.keepAliveSeconds = keepAliveSeconds;
+    this.timeoutMs = timeoutMs;
+    this.aor = `sip:${extension}@${domain}`;
+    this.viaHost = `${randomToken(12)}.invalid`;
+    this.contact = `<sip:${extension}@${this.viaHost};transport=ws>`;
+    this.transactions = new Map();
+    this.nc = new Map(); // nonce -> count
+    this.onNotify = () => false;
+    this.closed = false;
+  }
+
+  // Opens the WebSocket (subprotocol "sip"); rejects when it cannot.
+  open() {
+    if (!this.WebSocketImpl)
+      return Promise.reject(new Error('this Node.js has no WebSocket (Node 22 or newer is needed)'));
+    return new Promise((resolve, reject) => {
+      let opened = false;
+      const ws = new this.WebSocketImpl(this.wsUrl, 'sip');
+      this.ws = ws;
+      ws.binaryType = 'arraybuffer';
+      ws.addEventListener('open', () => {
+        opened = true;
+        if (this.keepAliveSeconds > 0) {
+          this.keepAlive = setInterval(() => this.write('\r\n\r\n'), this.keepAliveSeconds * 1000);
+          this.keepAlive.unref?.();
+        }
+        resolve();
+      });
+      ws.addEventListener('message', (e) =>
+        this.receive(typeof e.data === 'string' ? e.data : Buffer.from(e.data).toString('utf8')),
+      );
+      ws.addEventListener('error', () => {
+        if (!opened) reject(new Error(`the PBX did not open the SIP WebSocket (${new URL(this.wsUrl).host})`));
+      });
+      ws.addEventListener('close', () => {
+        if (!opened) reject(new Error(`the PBX closed the SIP WebSocket (${new URL(this.wsUrl).host})`));
+        this.dropped();
+      });
+    });
+  }
+
+  dropped() {
+    clearInterval(this.keepAlive);
+    for (const t of this.transactions.values()) t.fail(new Error('the SIP connection closed'));
+    this.transactions.clear();
+    if (!this.closed) {
+      this.closed = true;
+      this.emit('disconnect');
+    }
+  }
+
+  close() {
+    this.closed = true;
+    clearInterval(this.keepAlive);
+    for (const t of this.transactions.values()) t.fail(new Error('the SIP connection closed'));
+    this.transactions.clear();
+    try {
+      this.ws?.close();
+    } catch {
+      // already closed
+    }
+  }
+
+  write(text) {
+    if (this.ws?.readyState !== 1) throw new Error('the SIP connection is not open');
+    this.ws.send(text);
+  }
+
+  // Sends a request and resolves with its final response. A digest challenge is answered once (twice when stale).
+  //   o: {ruri, to, from, callId, seq: {cseq}, routes?, headers?: [lines], body?, contentType?}
+  // seq.cseq is incremented for every request sent (the caller keeps it per registration or dialog).
+  async request(method, o) {
+    let auth;
+    for (let round = 0; ; round += 1) {
+      o.seq.cseq += 1;
+      const res = await this.transaction(method, o, auth);
+      if (res.status !== 401 && res.status !== 407) return res;
+      const challenge = parseChallenge(res.header(res.status === 401 ? 'www-authenticate' : 'proxy-authenticate'));
+      const stale = String(challenge?.stale).toLowerCase() === 'true';
+      if (!challenge || round >= (stale ? 2 : 1)) return res;
+      const nc = (this.nc.get(challenge.nonce) ?? 0) + 1;
+      this.nc.set(challenge.nonce, nc);
+      const value = digestAuthorization({
+        username: this.extension,
+        password: this.password,
+        method,
+        uri: o.ruri,
+        challenge,
+        nc,
+      });
+      auth = `${res.status === 401 ? 'Authorization' : 'Proxy-Authorization'}: ${value}`;
+    }
+  }
+
+  transaction(method, o, auth) {
+    const branch = `z9hG4bK${randomToken(23)}`;
+    const body = o.body ?? '';
+    const lines = [
+      `${method} ${o.ruri} SIP/2.0`,
+      ...(o.routes ?? []).map((r) => `Route: ${r}`),
+      `Via: SIP/2.0/WSS ${this.viaHost};branch=${branch}`,
+      `To: ${o.to}`,
+      `From: ${o.from}`,
+      `CSeq: ${o.seq.cseq} ${method}`,
+      `Call-ID: ${o.callId}`,
+      'Max-Forwards: 70',
+      ...(auth ? [auth] : []),
+      ...(o.headers ?? []),
+      `Supported: ${method === 'REGISTER' ? 'outbound, path, gruu' : 'outbound'}`,
+      `User-Agent: ${this.userAgent}`,
+      ...(body ? [`Content-Type: ${o.contentType}`] : []),
+      `Content-Length: ${Buffer.byteLength(body)}`,
+      '',
+      body,
+    ];
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.transactions.delete(branch);
+        reject(new Error(`the PBX did not answer ${method} in time`));
+      }, this.timeoutMs);
+      timer.unref?.();
+      const done = () => {
+        clearTimeout(timer);
+        this.transactions.delete(branch);
+      };
+      this.transactions.set(branch, {
+        method,
+        ok: (res) => {
+          done();
+          resolve(res);
+        },
+        fail: (e) => {
+          done();
+          reject(e);
+        },
+      });
+      try {
+        this.write(lines.join('\r\n'));
+      } catch (e) {
+        done();
+        reject(e);
+      }
+    });
+  }
+
+  receive(text) {
+    if (!text.trim()) return; // a keep-alive answer
+    let msg;
+    try {
+      msg = parseMessage(text);
+    } catch {
+      return;
+    }
+    if (msg.status !== undefined) {
+      const t = this.transactions.get(branchOf(msg.header('via')));
+      if (t && msg.status >= 200) t.ok(msg);
+      return;
+    }
+    this.answerRequest(msg);
+  }
+
+  answerRequest(req) {
+    switch (req.method) {
+      case 'ACK':
+        return;
+      case 'NOTIFY': {
+        let known = false;
+        try {
+          known = this.onNotify(req);
+        } catch (e) {
+          this.emit('error', e);
+          known = true;
+        }
+        this.respond(req, known ? 200 : 481, known ? 'OK' : 'Subscription does not exist');
+        break;
+      }
+      case 'INVITE':
+        // Not a phone: every call offered to this registration is turned down, the user's phones keep ringing.
+        this.respond(req, 480, 'Not a call-handling device');
+        break;
+      case 'OPTIONS':
+        this.respond(req, 200, 'OK', [`Allow: ${ALLOWED.join(',')}`]);
+        break;
+      case 'CANCEL':
+        this.respond(req, 200, 'OK');
+        break;
+      case 'BYE':
+        this.respond(req, 481, 'Call/Transaction Does Not Exist');
+        break;
+      default:
+        this.respond(req, 405, 'Method Not Allowed', [`Allow: ${ALLOWED.join(',')}`]);
+    }
+    this.emit('request', req);
+  }
+
+  respond(req, status, reason, headers = []) {
+    const to = req.header('to') ?? '';
+    const lines = [
+      `SIP/2.0 ${status} ${reason}`,
+      ...req.headers('via').map((v) => `Via: ${v}`),
+      `To: ${tagOf(to) ? to : `${to};tag=${randomToken(10)}`}`,
+      `From: ${req.header('from') ?? ''}`,
+      `Call-ID: ${req.header('call-id') ?? ''}`,
+      `CSeq: ${req.header('cseq') ?? ''}`,
+      ...headers,
+      'Supported: outbound',
+      `User-Agent: ${this.userAgent}`,
+      'Content-Length: 0',
+      '',
+      '',
+    ];
+    try {
+      this.write(lines.join('\r\n'));
+    } catch {
+      // the socket is gone: the PBX retries or drops it
+    }
+  }
+
+  // Record-Route values of a message, one route per entry.
+  static routes(msg) {
+    return splitList(msg.headers('record-route'));
+  }
+}

package/src/phone/xml.mjs

@@ -0,0 +1,57 @@
+// A small XML reader for the bodies of the SIP event packages of the PBX (dialog-info, reginfo, active-device):
+// elements, attributes, text. No DTD, no external entities (a DOCTYPE is refused). Element names are matched
+// without their namespace prefix, as ltx does.
+
+const TOKEN =
+  /<!--[\s\S]*?-->|<!\[CDATA\[([\s\S]*?)\]\]>|<\?[\s\S]*?\?>|<\/\s*([^\s>]+)\s*>|<([^\s/>!?]+)((?:\s+[^\s=/>]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(\/?)>|([^<]+)/y;
+const ATTR = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+const NAMED = {lt: '<', gt: '>', amp: '&', quot: '"', apos: "'"};
+
+function decode(s) {
+  return s.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-z]+);/g, (m, e) => {
+    if (e[0] === '#') {
+      const code = e[1] === 'x' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+      return code <= 0x10ffff ? String.fromCodePoint(code) : m;
+    }
+    return NAMED[e] ?? m;
+  });
+}
+
+const local = (name) => name.slice(name.indexOf(':') + 1);
+
+// Parses a document and returns its root element: {name, attrs, children, text}. Throws on what is not XML.
+export function parseXml(text) {
+  const s = String(text ?? '').trim();
+  if (/<!DOCTYPE/i.test(s)) throw new Error('XML with a DOCTYPE is not accepted');
+  const root = {name: '#document', attrs: {}, children: [], text: ''};
+  const stack = [root];
+  TOKEN.lastIndex = 0;
+  while (TOKEN.lastIndex < s.length) {
+    const at = TOKEN.lastIndex;
+    const m = TOKEN.exec(s);
+    if (!m || m.index !== at) throw new Error(`not XML at character ${at}`);
+    const top = stack[stack.length - 1];
+    const [whole, cdata, closing, opening, attrText, selfClosing, chars] = m;
+    if (whole.startsWith('<!--') || whole.startsWith('<?')) continue;
+    if (cdata !== undefined) top.text += cdata;
+    else if (chars !== undefined) top.text += decode(chars);
+    else if (closing !== undefined) {
+      if (stack.length < 2 || top.name !== local(closing)) throw new Error(`unexpected </${closing}>`);
+      stack.pop();
+    } else if (opening !== undefined) {
+      const attrs = {};
+      for (const a of (attrText ?? '').matchAll(ATTR)) attrs[a[1]] = decode(a[2] ?? a[3] ?? '');
+      const el = {name: local(opening), attrs, children: [], text: ''};
+      top.children.push(el);
+      if (!selfClosing) stack.push(el);
+    }
+  }
+  if (stack.length !== 1) throw new Error(`<${stack[stack.length - 1].name}> is not closed`);
+  const [el] = root.children;
+  if (!el || root.children.length > 1) throw new Error('an XML document has one root element');
+  return el;
+}
+
+export const child = (el, name) => el?.children.find((c) => c.name === name);
+export const children = (el, name) => el?.children.filter((c) => c.name === name) ?? [];
+export const text = (el) => (el ? el.text.trim() : undefined);

package/src/stream.mjs

@@ -1,19 +1,12 @@
 // The Wildix stream service (chats): https://<region>.stream.wildix.com/api/v1, region eu-1 by default.
-import {UsageError} from './errors.mjs';
-import {request} from './http.mjs';
+import {UsageError} from 'wldx-core/errors';
+import {request} from 'wldx-core/http';
+import {streamUrl} from 'wldx-core/services';
 
-const WILDIX_HOST = /^https:\/\/[a-z0-9-]+(\.[a-z0-9-]+)*\.wildix\.com(:[0-9]+)?$/;
 const ID = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
 
-// The base address. The token is only ever sent to https://<host>.wildix.com; WILDIX_ALLOW_CUSTOM_URL=1 lifts this
-// for tests against a local server.
-export function streamBase(env = process.env) {
-  const base = (env.WILDIX_STREAM_URL || `https://${env.WILDIX_STREAM_REGION || 'eu-1'}.stream.wildix.com`).replace(/\/+$/, '');
-  if (env.WILDIX_ALLOW_CUSTOM_URL !== '1' && !WILDIX_HOST.test(base)) {
-    throw new UsageError(`The stream service address must be https://<host>.wildix.com, got: ${base}`);
-  }
-  return base;
-}
+// The base address (see services.mjs for the overrides).
+export const streamBase = (env = process.env) => streamUrl(env);
 
 const valid = (v) => ID.test(v) && !v.includes('..');
 
@@ -30,7 +23,11 @@ export function channelId(input) {
 
 // A message id from an id or from an inbox link to the message (the last path segment).
 export function messageId(input) {
-  const v = String(input).replace(/[?#].*$/s, '').replace(/\/+$/, '').split('/').pop();
+  const v = String(input)
+    .replace(/[?#].*$/s, '')
+    .replace(/\/+$/, '')
+    .split('/')
+    .pop();
   if (!valid(v)) throw new UsageError(`Not a message id: ${input}`);
   return v;
 }
@@ -38,6 +35,7 @@ export function messageId(input) {
 export function streamClient({token, env = process.env, fetchImpl}) {
   const api = `${streamBase(env)}/api/v1`;
   return {
-    call: (method, path, body) => request(api + path, {method, token, body, fetchImpl, service: 'the stream service'}),
+    call: (method, path, body, options = {}) =>
+      request(api + path, {method, token, body, fetchImpl, service: 'the stream service', ...options}),
   };
 }

package/src/version.mjs

@@ -1,4 +1,3 @@
 import {readFileSync} from 'node:fs';
 
 export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-export const USER_AGENT = `wldx-cli/${VERSION}`;