wldx-cli 0.1.1 → 1.0.0

package/src/live/views.mjs

@@ -0,0 +1,321 @@
+// What the live commands print, from the items of the WDA live stream: short views by default, the raw items with
+// `full`. Ported from live.mjs of the wildix-live-monitor skill (same fields, same order, same filters), as pure
+// functions: the commands in src/commands/live.mjs only connect, subscribe and hand the items over.
+import {agentFigures, queueFigures, sumStats} from './stats.mjs';
+
+export const drop = (o) => JSON.parse(JSON.stringify(o)); // removes the undefined fields
+
+const isPaused = (a) => a?.paused === 'true' || a?.paused === true;
+
+// The view functions bound to one run: full (raw items), company and extension of the login, the clock.
+export function makeViews({full = false, company, myExtension, now = () => Date.now()} = {}) {
+  // Left out unless full: e-mail, public IP address, geographic location and user agent of people.
+  function party(p) {
+    if (!p) return undefined;
+    if (full) return p;
+    return drop({
+      name: p.name,
+      phone: p.phone,
+      extension: p.userExtension,
+      department: p.userDepartment,
+      group: p.groupName,
+      type: p.type,
+      role: p.role,
+      device: p.userDevice,
+      sipCallId: p.sipCallId,
+    });
+  }
+
+  function flowView(f) {
+    return drop({
+      flowIndex: f.flowIndex,
+      status: f.status,
+      direction: f.direction,
+      caller: party(f.caller),
+      callee: party(f.callee),
+      destination: f.destination,
+      queue: f.queue ?? f.service,
+      start: f.startTime ? new Date(f.startTime).toISOString() : undefined,
+      talkSeconds: f.talkTime ? Math.round(f.talkTime / 1000) : undefined,
+      waitSeconds: f.waitTime ? Math.round(f.waitTime / 1000) : undefined,
+      holdSeconds: f.holdTime ? Math.round(f.holdTime / 1000) : undefined,
+      recording: f.recordings?.length ? true : undefined,
+      transcription: f.transcriptionStatus,
+      tags: f.tags?.length ? f.tags : undefined,
+    });
+  }
+
+  function insights(a) {
+    if (!a) return undefined;
+    const v = (k) => a[`copilot.${k}`]?.payload?.metric?.value;
+    return drop({sentiment: v('sentiment'), csat: v('csat'), topics: v('topics'), signals: v('signals')});
+  }
+
+  function conversationView(c) {
+    if (full) return c;
+    const base = {id: c.id, type: c.event, trigger: c.eventTrigger, start: c.start};
+    if (c.event === 'call') return drop({...base, flows: (Array.isArray(c.flows) ? c.flows : []).map(flowView)});
+    if (c.event === 'chat') {
+      return drop({
+        ...base,
+        status: c.status,
+        subject: c.subject,
+        direction: c.direction,
+        channelId: c.channelId,
+        customers: c.customers?.map((p) => drop({name: p.name, company: p.company})),
+        agents: c.agents?.map((p) => drop({name: p.name, bot: p.bot || undefined})),
+        tags: c.tags?.length ? c.tags : undefined,
+        insights: insights(c.annotationsByKey),
+      });
+    }
+    if (c.event === 'conference') {
+      return drop({
+        ...base,
+        subject: c.subject,
+        participants: c.participants?.map((p) => drop({name: p.name, role: p.role, type: p.type})),
+        insights: insights(c.annotationsByKey),
+      });
+    }
+    // completions and annotations: say what ended or changed, not more
+    return drop({...base, flows: typeof c.flows === 'number' ? c.flows : undefined, key: c.key, insights: insights(c.annotationsByKey)});
+  }
+
+  function agentView(a, stats) {
+    if (full) return stats ? {...a, stats: agentFigures(stats)} : a;
+    return drop({
+      name: a.name,
+      extension: a.userExtension,
+      department: a.department,
+      status: a.status,
+      paused: isPaused(a) || undefined,
+      reason: a.reason || undefined,
+      message: a.message || undefined,
+      stats: stats ? agentFigures(stats) : undefined,
+    });
+  }
+
+  function queueView(s) {
+    const agentStats = s.stats?.agentStats ?? {};
+    if (full) return s.stats ? {...s, figures: queueFigures(s.stats, now())} : s;
+    return drop({
+      id: s.id,
+      name: s.name,
+      pbx: s.pbx,
+      strategy: s.strategy,
+      maxCalls: s.maxCalls ? Number(s.maxCalls) : undefined,
+      calls: s.calls?.length ?? 0,
+      callIds: s.calls?.length ? s.calls : undefined,
+      stats: queueFigures(s.stats, now()),
+      agents: s.agents?.map((a) => agentView(a, s.stats ? agentStats[a.id] : undefined)),
+    });
+  }
+
+  function serviceCallView(c) {
+    if (full) return c;
+    return drop({
+      queueId: c.id,
+      trigger: c.eventTrigger,
+      callId: c.callId,
+      direction: c.direction,
+      customer: c.customer?.phone ?? c.customer?.name,
+      start: c.startTime ? new Date(c.startTime).toISOString() : undefined,
+      agents: c.relatedAgents?.length,
+    });
+  }
+
+  function presenceView(p) {
+    if (full) return p;
+    return drop({
+      extension: p.extension,
+      company: p.company !== company ? p.company : undefined,
+      status: p.status,
+      message: p.message || undefined,
+      until: p.until || undefined,
+      phone: p.telephony,
+    });
+  }
+
+  function textView(chunk, call) {
+    const flow = Array.isArray(call?.flows) ? call.flows.find((f) => f.flowIndex === chunk.flowIndex) : undefined;
+    const who = chunk.speaker === 'caller' ? flow?.caller : chunk.speaker === 'callee' ? flow?.callee : undefined;
+    return drop({
+      flow: chunk.flowIndex,
+      speaker: chunk.speaker ?? chunk.participant?.name,
+      name: who?.name ?? chunk.participant?.name ?? chunk.name,
+      text: chunk.text,
+      final: chunk.isFinal,
+      at: chunk.start ?? chunk.time,
+      language: chunk.language,
+      sentiment: chunk.sentiment,
+    });
+  }
+
+  const isMineCall = (c) =>
+    Boolean(myExtension) && Array.isArray(c.flows) && c.flows.some((f) => f.caller?.userExtension === myExtension || f.callee?.userExtension === myExtension);
+
+  return {full, company, myExtension, now, party, flowView, insights, conversationView, agentView, queueView, serviceCallView, presenceView, textView, isMineCall};
+}
+
+// The last item of every id, in the order of their first appearance.
+export const lastById = (items) => {
+  const m = new Map();
+  for (const it of items) if (it?.id) m.set(it.id, it);
+  return [...m.values()];
+};
+
+// Transcription items: a stored transcript ({flowIndex, chunks: {id: chunk}}), a live line ({chunk}), or a
+// conference transcript; each becomes chunks with the flow index kept.
+export function chunksOf(item) {
+  if (item?.chunk) return [{...item.chunk, flowIndex: item.flowIndex, participant: item.participant}];
+  if (item?.chunks && typeof item.chunks === 'object') return Object.values(item.chunks).map((c) => ({...c, flowIndex: item.flowIndex}));
+  return [];
+}
+
+// `queues`: the snapshot of the services topic, filtered and sorted, the queues with calls first.
+//   filters: {pbx, name, busy, paused, active}; stats: whether the statistics were asked for
+export function queuesResult(items, {pbx, name, busy, paused, active, stats} = {}, views = makeViews()) {
+  let qs = lastById(items.filter((i) => i?.event === 'service'));
+  if (pbx) qs = qs.filter((q) => q.pbx === pbx);
+  const text = name?.toLowerCase();
+  if (text) qs = qs.filter((q) => q.name?.toLowerCase().includes(text));
+  if (busy) qs = qs.filter((q) => q.calls?.length);
+  if (paused) qs = qs.filter((q) => q.agents?.some(isPaused));
+  if (active) qs = qs.filter((q) => q.calls?.length || q.stats?.offered || q.stats?.outbound);
+  qs.sort((a, b) => (b.calls?.length ?? 0) - (a.calls?.length ?? 0) || (b.stats?.offered ?? 0) - (a.stats?.offered ?? 0) || String(a.name).localeCompare(String(b.name)));
+  const pbxs = [...new Set(qs.map((q) => q.pbx))];
+  return drop({
+    total: qs.length,
+    callsWaitingOrTalking: qs.reduce((n, q) => n + (q.calls?.length ?? 0), 0),
+    pbxs: pbxs.length > 1 ? Object.fromEntries(pbxs.map((p) => [p, qs.filter((q) => q.pbx === p).length])) : undefined,
+    stats: stats ? queueFigures(sumStats(qs.map((q) => q.stats)), views.now()) : undefined,
+    queues: qs.map(views.queueView),
+  });
+}
+
+// `conversations`: the calls, chats and conferences of the snapshot, newest first.
+//   kinds: ['call', 'chat', 'conference'] to keep (none: all); mine; status; limit (50)
+export function conversationsResult(items, {kinds = [], mine, status, limit = 50} = {}, views = makeViews()) {
+  let cs = lastById(items.filter((i) => ['call', 'chat', 'conference'].includes(i?.event)));
+  const byType = {};
+  for (const c of cs) byType[c.event] = (byType[c.event] ?? 0) + 1;
+  if (kinds.length) cs = cs.filter((c) => kinds.includes(c.event));
+  if (mine) cs = cs.filter(views.isMineCall);
+  const want = status?.toUpperCase();
+  if (want) cs = cs.filter((c) => String(c.status ?? (Array.isArray(c.flows) ? c.flows.at(-1)?.status : undefined) ?? '').toUpperCase() === want);
+  cs.sort((a, b) => String(b.start).localeCompare(String(a.start)));
+  return {total: cs.length, byType, shown: Math.min(limit, cs.length), items: cs.slice(0, limit).map(views.conversationView)};
+}
+
+// `presence`: one entry per extension asked for, in the order given; `status: unknown` for nobody.
+export function presenceResult(items, extensions, views = makeViews()) {
+  const found = new Map(items.filter(Boolean).map((p) => [String(p.extension), p]));
+  return {presence: extensions.map((ext) => (found.has(ext) ? views.presenceView(found.get(ext)) : {extension: ext, status: 'unknown'}))};
+}
+
+// The WDA id of a call from the conversations snapshot, by the SIP call id of one of its parties.
+export function callIdBySip(items, sipCallId) {
+  const call = items.find((c) => c?.event === 'call' && Array.isArray(c.flows) && c.flows.some((f) => f.caller?.sipCallId === sipCallId || f.callee?.sipCallId === sipCallId));
+  return call?.id;
+}
+
+// `transcript`: what was said so far (final lines only), the call and its annotations.
+export function transcriptSnapshot(items, id, kind, views = makeViews()) {
+  const call = items.find((i) => i?.event === 'call' || i?.event === 'conference');
+  const lines = items.flatMap(chunksOf).filter((c) => c.text).sort((a, b) => (a.start ?? 0) - (b.start ?? 0));
+  const annotations = items.filter((i) => String(i?.event).endsWith('_annotation'));
+  return {
+    call,
+    snapshot: drop({
+      id,
+      type: kind,
+      call: call ? views.conversationView(call) : undefined,
+      transcript: lines.filter((c) => c.isFinal !== false).map((c) => views.textView(c, call)),
+      annotations: annotations.length ? annotations.map((a) => drop({key: a.key, payload: a.payload})) : undefined,
+    }),
+  };
+}
+
+// `transcript --follow`: the events of one broadcast item. state.call is the call last seen (names the speakers).
+// Returns {events: [{event, data}], end: boolean}.
+export function transcriptEvents(it, id, state, views = makeViews()) {
+  if (!it) return {events: [], end: false};
+  if (it.event === 'call' || it.event === 'conference') {
+    state.call = it;
+    return {events: [{event: 'CALL', data: views.conversationView(it)}], end: false};
+  }
+  if (/_complete$|_interrupted$/.test(String(it.event))) return {events: [{event: 'END', data: {id, event: it.event}}], end: true};
+  if (String(it.event).endsWith('_annotation')) return {events: [{event: 'ANNOTATION', data: drop({key: it.key, payload: it.payload})}], end: false};
+  return {events: chunksOf(it).filter((c) => c.text).map((c) => ({event: 'TEXT', data: views.textView(c, state.call)})), end: false};
+}
+
+// `watch`: turns the frames of the connection into events. o: {views, wantConv, wantQueues, wantStats, calls, mine,
+// statsOpts(), explain(topic, d)}. frame(d) returns {events: [{event, data}], fatal?: message}; reset() is called
+// on every (re)connection (with stats the queues are read again before QUEUE_STATS lines).
+export function watchFrames(o) {
+  const {views} = o;
+  const full = views.full;
+  const queueNames = new Map();
+  const mineIds = new Set();
+  let queuesReady = !o.wantStats;
+  const ev = (event, data) => ({event, data: data ?? {}});
+
+  function frame(d) {
+    const events = [];
+    if (d.event === 'error') {
+      events.push(ev('ERROR', {message: o.explain(d.source?.topic ?? 'subscription', d), code: d.code}));
+      return d.code === 403 ? {events, fatal: events[0].data.message} : {events};
+    }
+    if (d.event === 'subscribed' && d.topic === 'services' && !queuesReady) {
+      queuesReady = true;
+      events.push(ev('QUEUES', {queues: queueNames.size, stats: o.statsOpts()}));
+      return {events};
+    }
+    if (d.event !== 'broadcast') return {events};
+    for (const it of Array.isArray(d.data) ? d.data : [d.data]) {
+      if (!it || typeof it !== 'object') continue;
+      if (d.topic === 'presence') events.push(ev('PRESENCE', views.presenceView(it)));
+      else if (d.topic === 'services') {
+        if (it.event === 'service' && it.name) queueNames.set(it.id, it.name);
+        if (!queuesReady) continue;
+        if (it.event === 'service_stats_update') {
+          if (!o.wantStats) continue;
+          const agentStats = it.stats?.agentStats ?? {};
+          events.push(ev('QUEUE_STATS', full ? it : drop({
+            id: it.id,
+            name: queueNames.get(it.id),
+            ...queueFigures(it.stats, views.now()),
+            agents: Object.keys(agentStats).length
+              ? Object.fromEntries(Object.entries(agentStats).map(([k, v]) => [k.startsWith(`${it.id}_`) ? k.slice(String(it.id).length + 1) : k, agentFigures(v)]))
+              : undefined,
+          })));
+          continue;
+        }
+        // A change names what changed (eventTrigger) and carries only that: usually one agent, no queue name.
+        if (it.event === 'service') events.push(ev('QUEUE', full ? it : drop({trigger: it.eventTrigger, ...views.queueView(it)})));
+        else if (it.event === 'serviceCall' || it.event === 'service_call') events.push(ev('QUEUE_CALL', views.serviceCallView(it)));
+        else events.push(ev(String(it.event).toUpperCase(), full ? it : drop({id: it.id, trigger: it.eventTrigger})));
+      } else if (d.topic === 'conversations') {
+        const type = String(it.event);
+        if (o.calls && !type.startsWith('call')) continue;
+        if (o.mine) {
+          if (type === 'call' && views.isMineCall(it)) mineIds.add(it.id);
+          if (!mineIds.has(it.id)) continue;
+          // The skill forgot the call at any other event (an annotation too); here only when it ends.
+          if (/_complete$|_interrupted$/.test(type)) mineIds.delete(it.id);
+        }
+        events.push(ev(type.toUpperCase(), views.conversationView(it)));
+      }
+    }
+    return {events};
+  }
+
+  return {
+    frame,
+    reset() {
+      queuesReady = !o.wantStats;
+    },
+    get queueNames() {
+      return queueNames;
+    },
+  };
+}

package/src/phone/control.mjs

@@ -0,0 +1,377 @@
+// The SIP channel of the PBX, as the wildix-call-control skill uses it (through @gorets/wildix-callcontrol): a
+// headless SIP user of the logged-in extension that registers, subscribes to the event packages `dialog` (calls and
+// presence), `reg` (devices) and `active-device` (ringing mode), and sends call commands as Wildix TAPI PUBLISH
+// requests (event `wildixtsp/action`), the way Wildix clients do. Same behaviour as that library: the same events,
+// reconnect and resubscribe with the same backoff, a registration that lingers at most `expires` seconds when the
+// process is killed.
+//
+// Events: registered, ready (the first dialog state after each registration), callStart, callUpdate, callEnd,
+// devicesChanged, presenceChanged, activeDeviceChanged, reconnecting {attempt}, error (an Error).
+import {EventEmitter} from 'node:events';
+import {CallTracker, ValueTracker, deviceName, devicesEqual, parseActiveDevice, parseDialogInfo, parseRegInfo, toActiveDevice} from './events.mjs';
+import {ALLOWED, SipUserAgent, paramOf, randomToken, tagOf, uriOf} from './sip.mjs';
+
+export const TAPI_EVENT = 'wildixtsp/action';
+export const RECORD_ACTIONS = ['on', 'off', 'pause', 'unpause'];
+const PACKAGES = ['dialog', 'reg', 'active-device'];
+const SUBSCRIPTION_DISPOSE_GRACE_MS = 500;
+
+// 3 s, then up to 30 s over five attempts (quadratic), as the library.
+export function backoffMs(attempt) {
+  const a = Math.min(Math.max(attempt, 1), 5);
+  return Math.round(((30_000 - 3_000) / 16) * (a - 1) ** 2 + 3_000);
+}
+
+const bounded = (work, ms) => {
+  let timer;
+  return Promise.race([work.catch(() => undefined), new Promise((r) => (timer = setTimeout(r, ms)))]).finally(() => clearTimeout(timer));
+};
+
+export class CallControl extends EventEmitter {
+  // {domain, wsUrl, extension, password, userAgent, expires, WebSocketImpl, keepAliveSeconds, disconnectTimeoutMs, backoff}
+  constructor(config) {
+    super();
+    this.config = config;
+    this.expires = config.expires ?? 3600;
+    if (!Number.isInteger(this.expires) || this.expires <= 0) throw new Error(`expires must be a positive integer: ${config.expires}`);
+    this.disconnectTimeoutMs = config.disconnectTimeoutMs ?? 10_000;
+    this.backoff = config.backoff ?? backoffMs;
+    this.aor = `sip:${config.extension}@${config.domain}`;
+    this.stopping = false;
+    this.ready = false;
+    this.generation = 0;
+    this.reconnectAttempt = 0;
+    this.subs = new Map(); // Call-ID -> subscription
+    this.timers = new Set();
+    this.calls = new CallTracker();
+    this.devices = new ValueTracker();
+    this.presence = new ValueTracker();
+    this.activeDevice = new ValueTracker();
+  }
+
+  later(fn, ms) {
+    const t = setTimeout(() => {
+      this.timers.delete(t);
+      fn();
+    }, ms);
+    this.timers.add(t);
+    return t;
+  }
+
+  cancel(t) {
+    if (t) {
+      clearTimeout(t);
+      this.timers.delete(t);
+    }
+  }
+
+  async connect() {
+    this.stopping = false;
+    await this.start();
+    this.reconnectAttempt = 0;
+    this.emit('registered');
+  }
+
+  async start() {
+    const c = this.config;
+    const ua = new SipUserAgent({
+      wsUrl: c.wsUrl,
+      domain: c.domain,
+      extension: c.extension,
+      password: c.password,
+      userAgent: c.userAgent,
+      WebSocketImpl: c.WebSocketImpl,
+      keepAliveSeconds: c.keepAliveSeconds ?? 30,
+      timeoutMs: c.timeoutMs,
+    });
+    ua.onNotify = (req) => this.notify(req);
+    ua.on('error', (e) => this.emit('error', e));
+    // Only a connection that was up reconnects; one that fails to come up is the caller's error.
+    let live = false;
+    ua.on('disconnect', () => {
+      if (live && this.ua === ua && !this.stopping) this.scheduleReconnect();
+    });
+    this.ua = ua;
+    this.generation += 1;
+    this.ready = false;
+    try {
+      await ua.open();
+      await this.register(this.generation);
+      live = true;
+      if (ua.closed) throw new Error('the PBX closed the SIP connection right after the registration');
+    } catch (e) {
+      if (this.ua === ua) this.ua = undefined;
+      ua.close();
+      throw e;
+    }
+    for (const pkg of PACKAGES) this.subscribe(pkg, this.generation, 0);
+  }
+
+  // REGISTER, refreshed before it runs out. A refresh that fails reconnects.
+  async register(generation, expires = this.expires) {
+    const ua = this.ua;
+    this.registration ??= {callId: randomToken(22), fromTag: randomToken(10), seq: {cseq: 0}};
+    const r = this.registration;
+    const res = await ua.request('REGISTER', {
+      ruri: `sip:${this.config.domain}`,
+      to: `<${this.aor}>`,
+      from: `<${this.aor}>;tag=${r.fromTag}`,
+      callId: r.callId,
+      seq: r.seq,
+      headers: ['X-Disable-DirectRTP: yes', `Contact: ${ua.contact};expires=${expires}`, `Allow: ACK,CANCEL,INVITE,MESSAGE,BYE,OPTIONS,INFO,NOTIFY,REFER`],
+    });
+    if (res.status === 423 && expires > 0) {
+      const min = Number(res.header('min-expires'));
+      if (Number.isInteger(min) && min > expires) return this.register(generation, min);
+    }
+    if (res.status < 200 || res.status >= 300) throw new Error(`REGISTER rejected: ${res.status} ${res.reason}`);
+    if (expires === 0) return;
+    const ours = res.headers('contact').flatMap((v) => v.split(/,(?![^<]*>)/)).find((v) => uriOf(v).includes(ua.viaHost));
+    const granted = Number(paramOf(ours, 'expires') ?? res.header('expires') ?? expires) || expires;
+    this.cancel(this.registerTimer);
+    this.registerTimer = this.later(() => {
+      if (this.stopping || generation !== this.generation) return;
+      this.register(generation).catch((e) => {
+        if (generation !== this.generation || this.stopping) return;
+        this.emit('error', e);
+        this.scheduleReconnect();
+      });
+    }, Math.max(1, granted * 0.9) * 1000);
+  }
+
+  subscribe(pkg, generation, attempt) {
+    if (!this.ua || this.stopping || generation !== this.generation) return;
+    const sub = {pkg, generation, attempt, callId: randomToken(22), fromTag: randomToken(10), seq: {cseq: 0}, remoteTag: undefined, target: undefined, routes: []};
+    this.subs.set(sub.callId, sub);
+    this.sendSubscribe(sub, this.expires).then(
+      (res) => {
+        if (this.subs.get(sub.callId) !== sub) return;
+        if (res.status >= 200 && res.status < 300) {
+          sub.attempt = 0;
+          if (!sub.remoteTag) {
+            sub.remoteTag = tagOf(res.header('to'));
+            sub.target = res.header('contact') ? uriOf(res.header('contact')) : undefined;
+            sub.routes = SipUserAgent.routes(res).reverse();
+          }
+          this.scheduleRefresh(sub, Number(res.header('expires')) || this.expires);
+        } else {
+          this.emit('error', new Error(`SUBSCRIBE ${pkg} rejected: ${res.status} ${res.reason}`));
+          this.terminated(sub);
+        }
+      },
+      (e) => {
+        if (this.subs.get(sub.callId) !== sub) return;
+        this.emit('error', e);
+        this.terminated(sub);
+      },
+    );
+  }
+
+  sendSubscribe(sub, expires) {
+    const inDialog = Boolean(sub.remoteTag);
+    return this.ua.request('SUBSCRIBE', {
+      ruri: inDialog && sub.target ? sub.target : this.aor,
+      routes: inDialog ? sub.routes : [],
+      to: `<${this.aor}>${inDialog ? `;tag=${sub.remoteTag}` : ''}`,
+      from: `<${this.aor}>;tag=${sub.fromTag}`,
+      callId: sub.callId,
+      seq: sub.seq,
+      headers: [`Allow: ${ALLOWED.join(',')}`, `Event: ${sub.pkg}`, `Expires: ${expires}`, `Contact: ${this.ua.contact}`],
+    });
+  }
+
+  scheduleRefresh(sub, seconds) {
+    this.cancel(sub.timer);
+    sub.timer = this.later(() => {
+      if (this.stopping || this.subs.get(sub.callId) !== sub) return;
+      this.sendSubscribe(sub, this.expires).then(
+        (res) => {
+          if (this.subs.get(sub.callId) !== sub) return;
+          if (res.status >= 200 && res.status < 300) this.scheduleRefresh(sub, Number(res.header('expires')) || this.expires);
+          else this.terminated(sub);
+        },
+        () => this.subs.get(sub.callId) === sub && this.terminated(sub),
+      );
+    }, Math.max(1, seconds * 0.9) * 1000);
+  }
+
+  // A subscription that ended: subscribe again, after a backoff, while connected.
+  terminated(sub) {
+    this.cancel(sub.timer);
+    this.subs.delete(sub.callId);
+    if (this.stopping || sub.generation !== this.generation) return;
+    const attempt = sub.attempt + 1;
+    this.later(() => this.subscribe(sub.pkg, sub.generation, attempt), this.backoff(attempt));
+  }
+
+  // A NOTIFY: true when it belongs to one of our subscriptions.
+  notify(req) {
+    const sub = this.subs.get(req.header('call-id'));
+    if (!sub || tagOf(req.header('to')) !== sub.fromTag) return false;
+    if (!sub.remoteTag) {
+      sub.remoteTag = tagOf(req.header('from'));
+      sub.target = req.header('contact') ? uriOf(req.header('contact')) : undefined;
+      sub.routes = SipUserAgent.routes(req);
+    }
+    const state = req.header('subscription-state') ?? '';
+    const body = req.body ?? '';
+    try {
+      if (sub.pkg === 'dialog') this.onDialog(body);
+      else if (sub.pkg === 'reg') this.onReg(body);
+      else this.onActiveDevice(body);
+    } catch (e) {
+      this.emit('error', new Error(`could not read the ${sub.pkg} state from the PBX: ${e.message}`));
+    }
+    if (/^\s*terminated/i.test(state)) {
+      sub.attempt = 0;
+      this.terminated(sub);
+    } else {
+      const expires = Number(paramOf(state, 'expires'));
+      if (Number.isFinite(expires) && expires > 0) this.scheduleRefresh(sub, expires);
+    }
+    return true;
+  }
+
+  onDialog(body) {
+    if (body.trim()) {
+      const {dialogs, presence} = parseDialogInfo(body);
+      const {started, updated, ended} = this.calls.apply(dialogs);
+      for (const c of started) this.emit('callStart', c);
+      for (const c of updated) this.emit('callUpdate', c);
+      for (const c of ended) this.emit('callEnd', c);
+      const next = presence ? {...presence} : undefined;
+      if (this.presence.apply(next) && next) this.emit('presenceChanged', next);
+    }
+    // The PBX answers the unsubscribe of disconnect() with a last NOTIFY: that is not a new start.
+    if (!this.ready && !this.stopping) {
+      this.ready = true;
+      this.emit('ready');
+    }
+  }
+
+  onReg(body) {
+    if (!body.trim() || !this.ua) return;
+    const via = this.ua.viaHost;
+    const devices = parseRegInfo(body).map((d) => ({uri: d.uri, userAgent: d.userAgent, deviceName: deviceName(d.userAgent), isLocalRegistration: d.uri.includes(via)}));
+    if (this.devices.apply(devices, devicesEqual)) this.emit('devicesChanged', devices);
+  }
+
+  onActiveDevice(body) {
+    if (!body.trim()) return;
+    const next = toActiveDevice(parseActiveDevice(body));
+    if (this.activeDevice.apply(next) && next) this.emit('activeDeviceChanged', next);
+  }
+
+  isReady() {
+    return this.ready;
+  }
+
+  waitUntilReady(timeoutMs = 10_000) {
+    if (this.ready) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const onReady = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        this.off('ready', onReady);
+        reject(new Error(`no call state from the PBX within ${timeoutMs} ms`));
+      }, timeoutMs);
+      this.once('ready', onReady);
+    });
+  }
+
+  getActiveCalls() {
+    return this.calls.list();
+  }
+
+  getDevices() {
+    return this.devices.value ?? [];
+  }
+
+  getPresence() {
+    return this.presence.value;
+  }
+
+  getActiveDevice() {
+    return this.activeDevice.value;
+  }
+
+  // A TAPI command: PUBLISH to the user's own address with W-TapiCommand and its parameters. Resolves when the PBX
+  // takes it (2xx): taken, not necessarily done.
+  async tapi(command, ...params) {
+    if (!this.ua) throw new Error('not connected to the PBX');
+    const headers = [`W-TapiCommand: ${command}`];
+    params.forEach((p, i) => p !== undefined && headers.push(`W-TapiParam${i + 1}: ${p}`));
+    headers.push(`Event: ${TAPI_EVENT}`, 'Expires: 1');
+    for (const h of headers) if (/[\r\n]/.test(h)) throw new Error('a SIP header value cannot hold a line break');
+    const res = await this.ua.request('PUBLISH', {ruri: this.aor, to: `<${this.aor}>`, from: `<${this.aor}>;tag=${randomToken(10)}`, callId: randomToken(22), seq: {cseq: 0}, headers});
+    if (res.status < 200 || res.status >= 300) throw new Error(`TAPI command "${command}" rejected: ${res.status} ${res.reason}`);
+  }
+
+  record(callId, action) {
+    if (!RECORD_ACTIONS.includes(action)) return Promise.reject(new Error(`record action must be one of ${RECORD_ACTIONS.join(', ')}`));
+    return this.tapi('record', callId, action);
+  }
+
+  conferenceTransfer(callId, destination) {
+    return this.tapi('conftransfer', callId, destination);
+  }
+
+  scheduleReconnect() {
+    if (this.stopping || this.reconnectTimer) return;
+    this.reconnectAttempt += 1;
+    this.emit('reconnecting', {attempt: this.reconnectAttempt});
+    this.reconnectTimer = this.later(() => {
+      this.reconnectTimer = undefined;
+      this.reconnect();
+    }, this.backoff(this.reconnectAttempt));
+  }
+
+  async reconnect() {
+    if (this.stopping) return;
+    this.dropState();
+    const old = this.ua;
+    this.ua = undefined;
+    old?.close();
+    try {
+      await this.start();
+      this.reconnectAttempt = 0;
+      this.emit('registered');
+    } catch (e) {
+      if (this.stopping) return;
+      this.emit('error', e);
+      this.scheduleReconnect();
+    }
+  }
+
+  // Forgets the registration and the subscriptions of the connection that is gone (the calls stay known, so the
+  // state after the reconnect is told as changes).
+  dropState() {
+    this.cancel(this.registerTimer);
+    for (const s of this.subs.values()) this.cancel(s.timer);
+    this.subs.clear();
+    this.registration = undefined;
+  }
+
+  // Ends the registration and the subscriptions (sent together; the registration waited for at most
+  // disconnectTimeoutMs, the subscriptions 0.5 s), then closes the socket. Never rejects.
+  async disconnect() {
+    this.stopping = true;
+    this.ready = false;
+    for (const t of this.timers) clearTimeout(t);
+    this.timers.clear();
+    this.reconnectTimer = undefined;
+    const ua = this.ua;
+    if (ua && !ua.closed) {
+      const subs = [...this.subs.values()].filter((s) => s.remoteTag);
+      const unregistered = this.registration ? this.register(this.generation, 0).catch(() => undefined) : Promise.resolve();
+      const unsubscribed = Promise.all(subs.map((s) => this.sendSubscribe(s, 0).catch(() => undefined)));
+      await bounded(Promise.all([unregistered, bounded(unsubscribed, SUBSCRIPTION_DISPOSE_GRACE_MS)]), this.disconnectTimeoutMs);
+    }
+    this.subs.clear();
+    this.registration = undefined;
+    ua?.close();
+    this.ua = undefined;
+  }
+}