wldx-cli 0.1.1 → 1.1.0

package/src/commands/section.mjs

@@ -0,0 +1,101 @@
+// wx section: the user's sections of the chat inbox (the agent skill's sections.sh). The list and its counters come
+// from the inbox; creating, renaming, deleting and moving channels are not implemented by the service yet.
+import {UsageError} from 'wldx-core/errors';
+import {apiPath} from 'wldx-core/http';
+import {channelId} from '../stream.mjs';
+import {done} from '../chat/format.mjs';
+import {NOT_IMPLEMENTED, api, notImplemented} from '../chat/lib.mjs';
+import {sectionLines} from './inbox.mjs';
+
+function sectionId(value) {
+  if (!/^[a-z0-9_-]{1,32}$/.test(String(value)))
+    throw new UsageError(`A section id must match [a-z0-9_-] (up to 32): ${value}`);
+  return value;
+}
+
+function sectionName(value) {
+  const v = String(value ?? '');
+  if (!v.trim() || v.length > 80) throw new UsageError(`A section name has 1 to 80 characters: ${value}`);
+  return v;
+}
+
+const list = {
+  summary: 'your inbox sections with their counters',
+  usage: 'wx section list',
+  details: 'The sections of wx inbox get. The channels of a section: wx chat list --section ID.',
+  options: {},
+  args: [0, 0],
+  async run(ctx) {
+    const r = await api(ctx).call('GET', '/inbox');
+    return {sections: r?.sections ?? []};
+  },
+  text: (r, ctx) => (r.sections.length ? sectionLines(r.sections, ctx) : 'No sections.'),
+};
+
+const make = (name, summary, usage, operation, args, request, text) => ({
+  summary: `${summary}${NOT_IMPLEMENTED}`,
+  usage: `wx section ${name} ${usage}`,
+  details: notImplemented(operation),
+  options: {},
+  args: [args, args],
+  async run(ctx) {
+    const [method, path, body] = request(ctx.positionals);
+    return api(ctx).call(method, path, body);
+  },
+  text: done(text),
+});
+
+const section = {
+  summary: `your inbox sections${NOT_IMPLEMENTED.replace(')', ', except list)')}`,
+  auth: true,
+  commands: {
+    list,
+    create: make(
+      'create',
+      'create a section',
+      '<sectionId> <name>',
+      'CreateSection',
+      2,
+      ([id, name]) => ['POST', '/sections', {sectionId: sectionId(id), name: sectionName(name)}],
+      'Created',
+    ),
+    rename: make(
+      'rename',
+      'rename a section',
+      '<sectionId> <name>',
+      'RenameSection',
+      2,
+      ([id, name]) => ['PATCH', apiPath`/sections/${sectionId(id)}`, {name: sectionName(name)}],
+      'Renamed',
+    ),
+    delete: make(
+      'delete',
+      'delete a section',
+      '<sectionId>',
+      'DeleteSection',
+      1,
+      ([id]) => ['DELETE', apiPath`/sections/${sectionId(id)}`],
+      'Deleted',
+    ),
+    add: make(
+      'add',
+      'put a channel into a section',
+      '<channel> <sectionId>',
+      'MoveChannelToSection',
+      2,
+      ([ch, id]) => ['PUT', apiPath`/channels/${channelId(ch)}/sections/${sectionId(id)}`],
+      'Added',
+    ),
+    remove: make(
+      'remove',
+      'take a channel out of a section',
+      '<channel> <sectionId>',
+      'RemoveChannelFromSection',
+      2,
+      ([ch, id]) => ['DELETE', apiPath`/channels/${channelId(ch)}/sections/${sectionId(id)}`],
+      'Removed',
+    ),
+  },
+};
+
+export const groups = {section};

package/src/commands/user.mjs

@@ -0,0 +1,159 @@
+// wx user: people of the corporate directory on the stream service (the agent skill's users.sh and search.sh
+// users): who you are, a colleague by name (any script, typos, as it sounds), e-mail or phone.
+import {jwtClaims} from 'wldx-core/auth';
+import {UsageError} from 'wldx-core/errors';
+import {paint, table} from 'wldx-core/format';
+import {query} from 'wldx-core/http';
+import {nextPage, userLine} from '../chat/format.mjs';
+import {api, checkId, checkInt, displayName} from '../chat/lib.mjs';
+
+const me = {
+  summary: 'the logged-in user: id, name, e-mail, extension',
+  usage: 'wx user me',
+  options: {},
+  args: [0, 0],
+  async run(ctx) {
+    const email = jwtClaims(ctx.token).email;
+    if (!email) throw new Error('The login token carries no e-mail');
+    const r = await api(ctx).call('POST', '/users/query', {query: {emails: [email]}});
+    return r?.users?.[0] ?? null;
+  },
+  text(u, ctx) {
+    if (!u) return 'Not found in the chat directory.';
+    const rows = [
+      ['Name', paint(ctx).bold(displayName(u) ?? '')],
+      ['Id', u.id],
+      ['E-mail', u.email ?? ''],
+    ];
+    if (u.pbxExtension) rows.push(['Extension', u.pbxExtension]);
+    if (u.timeZone) rows.push(['Time zone', u.timeZone]);
+    if (u.locale) rows.push(['Locale', u.locale]);
+    return table(rows);
+  },
+};
+
+const brief = (r) => ({
+  margin: r?.margin,
+  nextCursor: r?.nextCursor,
+  results: (r?.results ?? []).map((x) => ({
+    id: x.user?.id,
+    name: x.user?.displayName,
+    email: x.user?.email,
+    extension: x.user?.pbxExtension,
+    bot: x.user?.bot,
+    confidence: x.confidence,
+    matchedOn: x.matchedOn,
+  })),
+});
+
+const find = {
+  summary: 'find a colleague by name (any script, typos, as it sounds), e-mail or phone',
+  usage:
+    'wx user find <query> [--mode auto|name|email|phone] [--kind human|bot|all] [--with-extension] [--min-confidence 0..1] [--brief] [--size 1-50] [--cursor C]',
+  details: [
+    'An e-mail or a phone number (with its country code, +…) is looked up exactly (confidence 1). confidence (0..1)',
+    'is how much the query looks like the name, not the probability that it is the right person (default cut 0.5;',
+    '--min-confidence 0 shows every candidate). margin is the confidence of the first hit minus the second: near 0,',
+    'the answer is ambiguous: ask which one, never guess. --brief keeps id, name, email, extension, bot, confidence,',
+    'matchedOn (JSON).',
+  ].join('\n'),
+  options: {
+    mode: {
+      type: 'string',
+      choices: ['auto', 'name', 'email', 'phone'],
+      description: 'what the query is (auto by default)',
+    },
+    kind: {type: 'string', choices: ['human', 'bot', 'all'], description: 'people (default), bots or both'},
+    'with-extension': {type: 'boolean', description: 'only people with a PBX extension'},
+    'min-confidence': {
+      type: 'string',
+      placeholder: '0..1',
+      description: 'drop hits below this confidence (default 0.5)',
+    },
+    brief: {type: 'boolean', description: 'only the fields needed to pick a person'},
+    size: {type: 'string', placeholder: '1-50', description: 'results per page (default 20)'},
+    cursor: {type: 'string', description: 'the next page (nextCursor of the previous one)'},
+  },
+  args: [1, 1],
+  async run(ctx) {
+    const {values} = ctx;
+    const minc = values['min-confidence'];
+    if (minc !== undefined && !/^(0|1|0?\.[0-9]+|1\.0+)$/.test(minc))
+      throw new UsageError(`--min-confidence is a number from 0 to 1: ${minc}`);
+    const q = query({
+      q: ctx.positionals[0],
+      mode: values.mode,
+      kind: values.kind,
+      withExtensionOnly: values['with-extension'] && 'true',
+      minConfidence: minc,
+      size: checkInt('size', values.size, 1, 50),
+      cursor: values.cursor,
+    });
+    const r = await api(ctx).call('GET', `/search/users${q}`);
+    return values.brief ? brief(r) : r;
+  },
+  text(r, ctx) {
+    const c = paint(ctx);
+    const hits = r?.results ?? [];
+    if (!hits.length) return 'Nobody found.';
+    const rows = hits.map((x) => {
+      const u = x.user ?? {id: x.id, displayName: x.name, email: x.email, pbxExtension: x.extension, bot: x.bot};
+      return [...userLine(u, c), `${Number(x.confidence ?? 0).toFixed(2)} ${x.matchedOn ?? ''}`.trim()];
+    });
+    const lines = table(rows);
+    if (hits.length > 1 && typeof r.margin === 'number')
+      lines.push(
+        r.margin < 0.1
+          ? c.yellow(`Ambiguous (margin ${r.margin.toFixed(2)}): several people fit, ask which one`)
+          : c.dim(`margin ${r.margin.toFixed(2)}`),
+      );
+    return [...lines, ...nextPage(r.nextCursor, c)];
+  },
+};
+
+const EMAIL = /@/;
+const PHONE = /^\+?[0-9]{4,17}$/;
+
+const get = {
+  summary: 'people by user id, e-mail or phone (exact lookup)',
+  usage: 'wx user get [<id|email|phone>...] [--id USERID]... [--email EMAIL]... [--phone PHONE]...',
+  details:
+    'A value given without an option is an e-mail when it has "@", a phone when it is digits (+ allowed), else a user id. For a search by name: wx user find.',
+  options: {
+    id: {type: 'string', multiple: true, placeholder: 'USERID', description: 'a user id'},
+    email: {type: 'string', multiple: true, placeholder: 'EMAIL', description: 'an e-mail address'},
+    phone: {type: 'string', multiple: true, placeholder: 'PHONE', description: 'a phone number'},
+  },
+  args: [0, 100],
+  async run(ctx) {
+    const {values} = ctx;
+    const ids = [...(values.id ?? [])];
+    const emails = [...(values.email ?? [])];
+    const phones = [...(values.phone ?? [])];
+    for (const v of ctx.positionals) {
+      if (EMAIL.test(v)) emails.push(v);
+      else if (PHONE.test(v.replace(/[\s()-]/g, ''))) phones.push(v.replace(/[\s()-]/g, ''));
+      else ids.push(v);
+    }
+    const q = {};
+    if (ids.length) q.ids = ids.map((id) => checkId('The user id', id));
+    if (emails.length) q.emails = emails;
+    if (phones.length) q.phones = phones;
+    if (!Object.keys(q).length)
+      throw new UsageError('Give a user id, an e-mail or a phone (or --id, --email, --phone)', ctx.usage());
+    return api(ctx).call('POST', '/users/query', {query: q});
+  },
+  text(r, ctx) {
+    const c = paint(ctx);
+    const list = r?.users ?? [];
+    return list.length ? table(list.map((u) => userLine(u, c))) : 'Nobody found.';
+  },
+};
+
+const user = {
+  summary: 'people: you, a colleague by name, e-mail or phone',
+  auth: true,
+  commands: {me, find, get},
+};
+
+export const groups = {user};

package/src/history/text.mjs

@@ -0,0 +1,86 @@
+// Text formatters shared by wx calls, meetings and conversations: the AI summary, the insights, the people of a call.
+import {duration, oneLine} from 'wldx-core/format';
+
+const SECTIONS = [
+  'topics',
+  'keyPoints',
+  'review',
+  'decisions',
+  'progress',
+  'issues',
+  'actionItems',
+  'nextSteps',
+  'customerInsights',
+  'customerResponse',
+  'salesProposals',
+  'competitiveInformation',
+  'implementationTimeline',
+  'budget',
+  'tags',
+];
+
+// "actionItems" -> "Action items"
+export const label = (key) => {
+  const words = key.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+};
+
+const valueText = (v) =>
+  v === null || v === undefined
+    ? ''
+    : typeof v === 'object'
+      ? Array.isArray(v) && v.every((x) => typeof x !== 'object')
+        ? v.join('; ')
+        : JSON.stringify(v)
+      : String(v);
+
+function bullets(title, items, indent = '') {
+  const list = (items ?? []).filter((x) => x !== null && x !== undefined && x !== '');
+  if (!list.length) return [];
+  return [`${indent}${title}:`, ...list.map((x) => `${indent}  - ${oneLine(valueText(x), 400)}`)];
+}
+
+// The sections of a summary ({topics: [...], decisions: [...], ...}) as bullet lists.
+export function sectionLines(json, indent = '') {
+  const lines = [];
+  for (const key of SECTIONS) if (Array.isArray(json?.[key])) lines.push(...bullets(label(key), json[key], indent));
+  if (json?.csat && (json.csat.score || json.csat.reason))
+    lines.push(
+      `${indent}CSAT: ${[json.csat.score, json.csat.reason && oneLine(json.csat.reason, 300)].filter(Boolean).join(' · ')}`,
+    );
+  return lines;
+}
+
+// GET .../summary: {status, summary: {title, brief, json}}.
+export function summaryLines(r) {
+  if (r?.status !== 'SUCCEEDED') return [`No summary: ${r?.status ?? 'UNKNOWN'}`];
+  const s = r.summary ?? {};
+  const lines = [];
+  if (s.title) lines.push(oneLine(s.title, 200));
+  if (s.brief) lines.push(oneLine(s.brief, 2000));
+  const sections = sectionLines(s.json);
+  if (sections.length) lines.push('', ...sections);
+  return lines;
+}
+
+// {projectionId: {fieldId: value}} as "projection" lines with indented "field: value".
+export function insightLines(compact, indent = '') {
+  const lines = [];
+  for (const [id, fields] of Object.entries(compact ?? {})) {
+    lines.push(`${indent}${id}:`);
+    for (const [f, v] of Object.entries(fields ?? {})) lines.push(`${indent}  ${f}: ${oneLine(valueText(v), 300)}`);
+  }
+  return lines;
+}
+
+// A party of a call: "Name (ext 201) +3902…", whatever is known.
+export function party(p) {
+  if (!p) return '';
+  const ext = p.userExtension ?? p.extension;
+  return [p.name, ext && `(${ext})`, p.phone && p.phone !== ext ? p.phone : undefined].filter(Boolean).join(' ');
+}
+
+// Seconds or milliseconds as "m:ss".
+export const secs = (s) => (Number.isFinite(s) ? duration(s) : '');
+// A duration from milliseconds; '—' when there is none (no calls in the window).
+export const millis = (ms) => (Number.isFinite(ms) ? duration(ms / 1000) : '—');

package/src/history/wda.mjs

@@ -0,0 +1,171 @@
+// Wildix Data Analytics (https://wda.wildix.com/v2): the history of calls and conferences, their AI insights, the
+// search over conversations and the queue reports (x-caracal). A client bound to the token, and the helpers the
+// commands of wx calls, meetings, conversations and reports share (ids, numbers, dates, the shapes of the skill).
+import fs from 'node:fs';
+import path from 'node:path';
+import {HttpError, UsageError} from 'wldx-core/errors';
+import {refuseUnsafeWrite} from 'wldx-core/files';
+import {request} from 'wldx-core/http';
+import {wdaUrl} from 'wldx-core/services';
+
+const FORBIDDEN_HINT =
+  'The login has no access to this record (a meeting or call of other people, or a role without the right).';
+
+// wdaClient({token, env, fetchImpl}) (for ctx.client): get(path), post(path, body), soft(path) (null on a 404).
+// The path is relative to /v2 and built with apiPath`` by the caller.
+export function wdaClient({token, env, fetchImpl}) {
+  const root = `${wdaUrl(env)}/v2`;
+  async function call(method, p, body) {
+    try {
+      return await request(root + p, {method, token, body, fetchImpl, service: 'WDA'});
+    } catch (e) {
+      if (e instanceof HttpError && e.status === 403) e.message += `\n${FORBIDDEN_HINT}`;
+      throw e;
+    }
+  }
+  return {
+    get: (p) => call('GET', p),
+    post: (p, body) => call('POST', p, body),
+    async soft(p) {
+      try {
+        return await call('GET', p);
+      } catch (e) {
+        if (e instanceof HttpError && e.status === 404) return null;
+        throw e;
+      }
+    },
+  };
+}
+
+// An optional part of a readable card (a summary, insights): null when it is not there (404); another failure is
+// told on stderr and the card goes on without it (as the scripts of the skill do).
+export async function optional(promise, info) {
+  try {
+    return await promise;
+  } catch (e) {
+    if (!(e instanceof HttpError && e.status === 404)) info(`Warning: ${e.message.split('\n')[0]}`);
+    return null;
+  }
+}
+
+// Nothing to show: no transcription, or no such record. Exit code 3, as in the scripts of the skill.
+export class NoDataError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'NoDataError';
+    this.exitCode = 3;
+  }
+}
+
+const ID = /^[A-Za-z0-9_+][A-Za-z0-9_.:+-]*$/;
+
+// An id that goes into a request path (a call id, a queue id, a file id).
+export function checkId(what, value) {
+  const v = String(value ?? '');
+  if (!ID.test(v) || v.includes('..')) throw new UsageError(`${what} is not a valid id: ${value}`);
+  return v;
+}
+
+// A conference id from an id or a link (the last path segment of .../insights/conferences/<id>).
+export function conferenceId(input) {
+  const v = String(input).split(/[?#]/)[0].replace(/\/$/, '').split('/').pop();
+  if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(v) || v.includes('..') || v === 'conferences')
+    throw new UsageError(`not a conference id: ${input}`);
+  return v;
+}
+
+// A call: the call id and the flow index (a transferred call has several flows; the first is 0).
+export function callFlow(positionals) {
+  const [id, flow = '0'] = positionals;
+  if (!/^\d{1,9}$/.test(flow)) throw new UsageError(`the flow index must be a number: ${flow}`);
+  return {callId: checkId('the call id', id), flow: Number(flow)};
+}
+
+// A whole number from min to max (the services refuse anything else with a 400 that tells little).
+export function intOption(name, value, min, max) {
+  if (value === undefined) return undefined;
+  if (!/^\d{1,12}$/.test(value) || Number(value) < min || Number(value) > max)
+    throw new UsageError(`${name} must be a whole number from ${min} to ${max}: ${value}`);
+  return Number(value);
+}
+
+export function checkZone(value) {
+  if (value === undefined) return undefined;
+  if (!/^[A-Za-z][A-Za-z0-9_+/-]{0,63}$/.test(value)) throw new UsageError(`not a time zone: ${value}`);
+  return value;
+}
+
+// An ISO time given to a filter (--from, --to of the call history and the search): passed on as it is, once it
+// is a time at all.
+export function checkIso(name, value) {
+  if (value === undefined) return undefined;
+  if (!/^\d{4}-\d{2}-\d{2}/.test(value) || Number.isNaN(Date.parse(value)))
+    throw new UsageError(`${name} must be an ISO time (2026-11-07 or 2026-11-07T09:00:00Z): ${value}`);
+  return value;
+}
+
+// The local IANA time zone (TZ, else the zone of the machine).
+export const localZone = (env) => env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+
+// jq's todate: "2026-11-05T11:21:29Z" from milliseconds.
+export const isoSeconds = (ms) => new Date(Math.floor((ms || 0) / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+// jq's `a // b // c`: the first value that is not null, undefined or false.
+export const alt = (...values) => values.find((v) => v !== null && v !== undefined && v !== false) ?? null;
+
+// {k: obj[k] ?? null} for the keys (jq's `{a, b}`).
+export const pick = (obj, keys) => Object.fromEntries(keys.map((k) => [k, obj?.[k] ?? null]));
+
+// jq's `unique`: sorted, no repeats.
+export const unique = (values) => [...new Set(values)].sort();
+
+// The insights that succeeded, as {projectionId: {fieldId: value}}.
+export function compactInsights(r) {
+  const out = {};
+  for (const p of r?.insights ?? []) {
+    if (p.status !== 'SUCCEEDED' || !(p.fields ?? []).length) continue;
+    out[p.id] = Object.fromEntries(p.fields.map((f) => [f.id, f.value ?? null]));
+  }
+  return out;
+}
+
+// The participants of a conference by name (or e-mail), each once.
+export const participantNames = (conference) =>
+  unique(
+    (conference?.participants ?? [])
+      .map((p) => alt(p.info?.name, p.info?.email))
+      .filter((n) => n !== null)
+      .map((n) => String(n).replace(/\s+/g, ' ').trim()),
+  );
+
+// Writes a transcript to a private file (folders 0700, file 0600) and returns its absolute path. An existing path
+// is replaced only when it is a transcript of the same conference written earlier (its second line is
+// "# conferenceId: <id>"): the path may have come from fetched text, so nothing else is touched.
+export function writePrivate(file, content, {cwd, conferenceId: id, env = process.env} = {}) {
+  if (!file) throw new UsageError('empty output path');
+  const target = path.resolve(cwd ?? process.cwd(), file);
+  refuseUnsafeWrite(target, env);
+  let exists = false;
+  try {
+    fs.lstatSync(target);
+    exists = true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  if (exists) {
+    let second;
+    try {
+      second = fs.readFileSync(target, 'utf8').slice(0, 8192).split('\n')[1];
+    } catch {
+      second = undefined;
+    }
+    if (!id || second !== `# conferenceId: ${id}`)
+      throw new Error(`${file} exists: choose another path (nothing was overwritten)`);
+  }
+  fs.mkdirSync(path.dirname(target), {recursive: true, mode: 0o700});
+  fs.writeFileSync(target, content, {mode: 0o600, flag: exists ? 'w' : 'wx'});
+  return target;
+}
+
+// "1 queue", "2 queues".
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;

package/src/live/socket.mjs

@@ -0,0 +1,139 @@
+// The connection to the live stream of Wildix Data Analytics (WDA), wss://wda-ws.wildix.com (src/services.mjs).
+//
+// Protocol: {"action":"authorize","token"} -> {"event":"authorized"}; then
+// {"action":"subscribe","topic","version","state","filter"} -> the current state as {"event":"broadcast","topic",
+// "data":[…]} frames, then {"event":"subscribed","topic"}; afterwards one broadcast per change.
+// An error is {"event":"error","message","code","source"}: `source` echoes the request, which for authorize holds
+// the token, so it is never printed (and the token is scrubbed from every message shown).
+import {AuthError} from 'wldx-core/errors';
+
+export const AUTH_TIMEOUT_MS = 20_000;
+export const SNAPSHOT_TIMEOUT_MS = 30_000;
+
+export const subscription = (topic, extra = {}) => ({action: 'subscribe', topic, version: '2', ...extra});
+
+// The message of a refused subscription, as the skill words it.
+export function explain(topic, d, license) {
+  if (d.code === 403 && (topic === 'services' || topic === 'conversations')) {
+    return `the live service allows ${topic === 'services' ? 'call queues' : 'the conversations of the company'} only to users with a Premium license (this login: ${license ?? 'unknown'})`;
+  }
+  if (d.code === 401) return 'the live service lost the login: run the command again';
+  return `the live service refused the ${topic} subscription (${d.code ?? '?'}): ${d.message}`;
+}
+
+// Opens a connection and logs in. Resolves with the connection:
+//   listeners   a Set of functions called with every frame after the login, and {event: '_closed', code} at the end
+//   send(obj)   sends one request
+//   snapshot(topic, extra)   subscribes with the state and resolves with every item broadcast until "subscribed"
+//   close()     closes it (a _closed frame follows)
+// Rejects with AuthError when the service refuses the token, with Error when it cannot connect.
+export function connect({
+  url,
+  token,
+  WebSocket = globalThis.WebSocket,
+  license,
+  timeoutMs = AUTH_TIMEOUT_MS,
+  snapshotTimeoutMs = SNAPSHOT_TIMEOUT_MS,
+}) {
+  const scrub = (s) =>
+    token
+      ? String(s ?? '')
+          .split(token)
+          .join('[token]')
+      : String(s ?? '');
+  return new Promise((resolve, reject) => {
+    const listeners = new Set();
+    let ws;
+    try {
+      ws = new WebSocket(`${url}/`);
+    } catch (e) {
+      reject(new Error(`could not connect to the live service: ${scrub(e.message)}`));
+      return;
+    }
+    let done = false;
+    const send = (obj) => {
+      try {
+        ws.send(JSON.stringify(obj));
+      } catch {
+        // closed meanwhile: the _closed frame tells the listeners
+      }
+    };
+    const conn = {
+      listeners,
+      send,
+      close() {
+        try {
+          ws.close(1000);
+        } catch {
+          // already closed
+        }
+      },
+      snapshot(topic, extra = {}) {
+        return new Promise((ok, fail) => {
+          const items = [];
+          const timer = setTimeout(
+            () => finish(new Error(`no answer for ${topic} in ${Math.round(snapshotTimeoutMs / 1000)} seconds`)),
+            snapshotTimeoutMs,
+          );
+          const listener = (d) => {
+            if (d.event === 'broadcast' && d.topic === topic)
+              items.push(...(Array.isArray(d.data) ? d.data : [d.data]));
+            else if (d.event === 'subscribed' && d.topic === topic) finish();
+            else if (d.event === 'error')
+              finish(Object.assign(new Error(scrub(explain(topic, d, license))), {code: d.code}));
+            else if (d.event === '_closed')
+              finish(new Error(`the live service closed the connection (code ${d.code})`));
+          };
+          function finish(err) {
+            clearTimeout(timer);
+            listeners.delete(listener);
+            if (err) fail(err);
+            else ok(items);
+          }
+          listeners.add(listener);
+          send(subscription(topic, {state: true, ...extra}));
+        });
+      },
+      scrub,
+    };
+    const timer = setTimeout(() => {
+      if (done) return;
+      done = true;
+      conn.close();
+      reject(new Error(`the live service did not answer in ${Math.round(timeoutMs / 1000)} seconds`));
+    }, timeoutMs);
+    ws.onopen = () => send({action: 'authorize', token});
+    ws.onmessage = (m) => {
+      let d;
+      try {
+        d = JSON.parse(typeof m.data === 'string' ? m.data : Buffer.from(m.data).toString('utf8'));
+      } catch {
+        return;
+      }
+      if (!d || typeof d !== 'object') return;
+      if (!done) {
+        if (d.event === 'authorized') {
+          done = true;
+          clearTimeout(timer);
+          resolve(conn);
+        } else if (d.event === 'error') {
+          done = true;
+          clearTimeout(timer);
+          conn.close();
+          reject(new AuthError(`the live service refused the login: ${scrub(d.message)}`));
+        }
+        return;
+      }
+      for (const l of [...listeners]) l(d);
+    };
+    ws.onclose = (ev) => {
+      if (!done) {
+        done = true;
+        clearTimeout(timer);
+        reject(new Error(`the live service closed the connection (code ${ev?.code})`));
+      }
+      for (const l of [...listeners]) l({event: '_closed', code: ev?.code});
+    };
+    ws.onerror = () => {};
+  });
+}