@coventia/softphone 0.2.0 → 0.3.0

package/dist/{engine-EPCKf-Bl.d.ts → engine-BgBsIcEa.d.ts}

@@ -1,4 +1,4 @@
-import { e as CallOptions, b as CallDirection, H as HangupReason, i as HoldOriginator, o as SoftphoneState, k as SoftphoneError } from './call-DUVnDxsz.js';
+import { e as CallOptions, b as CallDirection, H as HangupReason, i as HoldOriginator, r as SoftphoneState, n as SoftphoneError } from './call-CaPDWVk3.js';
 
 /**
  * The `CallEngine` seam — INTERNAL, not exported from src/index.ts.

package/dist/{engine-CDjkrXHY.d.cts → engine-CU2rEo3g.d.cts}

@@ -1,4 +1,4 @@
-import { e as CallOptions, b as CallDirection, H as HangupReason, i as HoldOriginator, o as SoftphoneState, k as SoftphoneError } from './call-DUVnDxsz.cjs';
+import { e as CallOptions, b as CallDirection, H as HangupReason, i as HoldOriginator, r as SoftphoneState, n as SoftphoneError } from './call-CaPDWVk3.cjs';
 
 /**
  * The `CallEngine` seam — INTERNAL, not exported from src/index.ts.

package/dist/index.cjs

@@ -293,6 +293,10 @@ function coventiaSources(config) {
               if (ws.readyState !== WS.OPEN) return;
               ws.send(JSON.stringify({ type: "call-state", onCall }));
             },
+            bye: () => {
+              if (ws.readyState !== WS.OPEN) return;
+              ws.send(JSON.stringify({ type: "bye" }));
+            },
             close: () => {
               ws.onclose = null;
               ws.onerror = null;
@@ -327,6 +331,56 @@ function coventiaSources(config) {
       })();
     });
   };
+  const fileBase = config.baseUrl.replace(/\/+$/, "");
+  const toLoop = (l) => l && Number.isFinite(l.start) && Number.isFinite(l.end) && l.start >= 0 && l.end > l.start ? { start: l.start, end: l.end } : null;
+  const toRingtoneSettings = (body) => {
+    const catalogue = (body.catalogue ?? []).map((r) => ({
+      id: r.id,
+      name: r.name,
+      url: r.path ? `${fileBase}${r.path}` : null,
+      loop: r.path ? toLoop(r.loop) : null
+    }));
+    const builtIn = catalogue.find((r) => r.url === null)?.id ?? "clasico";
+    const effective = catalogue.some((r) => r.id === body.effective) ? body.effective : builtIn;
+    return { catalogue, orgDefault: body.orgDefault ?? null, mine: body.user ?? null, effective };
+  };
+  const CACHE_PREFIX = "coventia-softphone:ringtones:";
+  const cacheKey = async () => {
+    try {
+      const { identity } = await config.tokenSource.getToken();
+      return `${CACHE_PREFIX}${fileBase}|${config.organizationId ?? "-"}|${identity}`;
+    } catch {
+      return null;
+    }
+  };
+  const remember = async (settings) => {
+    const key = await cacheKey();
+    try {
+      if (key) globalThis.localStorage?.setItem(key, JSON.stringify(settings));
+    } catch {
+    }
+    return settings;
+  };
+  const recall = async () => {
+    const key = await cacheKey();
+    try {
+      const raw = key ? globalThis.localStorage?.getItem(key) : null;
+      const s = raw ? JSON.parse(raw) : null;
+      const ok = s && Array.isArray(s.catalogue) && s.catalogue.every((r) => typeof r?.id === "string" && typeof r.name === "string" && (r.url === null || typeof r.url === "string")) && s.catalogue.some((r) => r.id === s.effective);
+      return ok ? { ...s, catalogue: s.catalogue.map((r) => ({ ...r, loop: toLoop(r.loop) })) } : null;
+    } catch {
+      return null;
+    }
+  };
+  const ringtones = {
+    get: async (signal) => remember(toRingtoneSettings(await get(`${base}/ringtones`, org, signal))),
+    // `null` clears: the empty id is dropped from the query by the request helper, and the backend reads a
+    // missing `ringtone_id` as "clear".
+    setMine: async (id) => remember(
+      toRingtoneSettings(await post(`${base}/ringtones/user`, { ...org, ringtone_id: id ?? "" }))
+    ),
+    cached: recall
+  };
   const contacts = config.contacts ?? coventiaContacts;
   const resolve = config.resolveContact ?? (config.contacts ? resolverFromContacts(config.contacts) : coventiaResolve);
   const history = withNameResolution(rawHistory, resolve);
@@ -338,7 +392,8 @@ function coventiaSources(config) {
     resolveContact: resolve,
     listAgents: coventiaListAgents,
     transferOutcomes,
-    presence
+    presence,
+    ringtones
   };
 }
 var toContact, toDirection, otherParty, isMissed, toOutcome, toDate, toTransferOutcome, toPresenceState, toPresenceEntry, toWebSocketUrl;
@@ -1222,11 +1277,13 @@ function buildPushUrl(key, sip) {
   const params = new URLSearchParams({ key, integrationType: "site", sipId: sip });
   return `wss://ws.zadarma.com/webrtc_pushes?${params.toString()}`;
 }
-var PING, KEY_REFRESH_BUFFER_MS, ZADARMA_QUIRKS, ZadarmaPushSignal, ZadarmaProvider;
+var PING, KEY_REFRESH_BUFFER_MS, REBUILD_CONNECT_TIMEOUT_MS, REBUILD_RETRY_MS, ZADARMA_QUIRKS, ZadarmaPushSignal, ZadarmaProvider;
 var init_zadarma = __esm({
   "src/transports/providers/zadarma.ts"() {
     PING = { localMs: 3e4, globalMs: 6e4 };
     KEY_REFRESH_BUFFER_MS = 2 * 60 * 60 * 1e3;
+    REBUILD_CONNECT_TIMEOUT_MS = 1e4;
+    REBUILD_RETRY_MS = 3e4;
     ZADARMA_QUIRKS = {
       // Zadarma's registrar REFUSES to register a WebRTC client with any other User-Agent — a clean 401
       // after a valid digest challenge, indistinguishable from a wrong password (§3.1). The old CRM
@@ -1250,6 +1307,12 @@ var init_zadarma = __esm({
       #connected = false;
       #pingTimers = [];
       #refreshTimer;
+      /** The replacement socket of a rebuild in flight, not yet current. */
+      #candidate = null;
+      /** Abandons the rebuild in flight (closing its candidate). */
+      #abortRebuild = null;
+      #rebuilding = false;
+      #retryTimer;
       #unwatchBackground;
       #closed = false;
       #listeners = /* @__PURE__ */ new Set();
@@ -1265,20 +1328,35 @@ var init_zadarma = __esm({
         if (this.#closed) return;
         const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
         this.#socket = socket;
+        this.#attach(socket);
+        this.#armRefresh(keyExpiresAt);
+      }
+      /**
+       * Wires one socket's events. `this.#socket` is read when an event FIRES, not when it is wired: a socket that
+       * has been replaced must stop driving connectivity (our own `close()` of it emits `disconnect`, which would
+       * otherwise flip the state to offline right after a perfectly healthy swap). `update` is the exception — it is
+       * forwarded from any socket not yet closed, because a push seen twice is harmless (the engine ignores a
+       * repeated signal mid-call and reuses a UA that already exists) while one seen by neither is a missed call.
+       *
+       * With `hooks`, the socket is a rebuild's candidate: its first `connect` or failure goes to the rebuild instead
+       * of changing the connection state (it is not current yet).
+       */
+      #attach(socket, hooks) {
         socket.on("connect", () => {
+          if (hooks && socket === this.#candidate) return hooks.onConnect();
+          if (socket !== this.#socket) return;
           this.#setConnected(true);
           this.#startPings(socket);
         });
         socket.on("update", () => this.#emit());
-        socket.on("disconnect", () => {
-          this.#stopPings();
-          this.#setConnected(false);
-        });
-        socket.on("connect_error", () => {
+        const lost = () => {
+          if (hooks && socket === this.#candidate) return hooks.onFailure();
+          if (socket !== this.#socket) return;
           this.#stopPings();
           this.#setConnected(false);
-        });
-        this.#armRefresh(keyExpiresAt);
+        };
+        socket.on("disconnect", lost);
+        socket.on("connect_error", lost);
       }
       /**
        * Presence pings — **the reason an idle tab keeps receiving calls**.
@@ -1317,22 +1395,92 @@ var init_zadarma = __esm({
         if (!Number.isFinite(ms) || ms <= 0) return;
         this.#refreshTimer = setTimeout(() => void this.#reopen(), ms);
       }
+      /**
+       * Replaces the push socket with a fresh one — MAKE-BEFORE-BREAK (presence-client-reporting.md §4.1, T8).
+       *
+       * Why it must happen at all: Zadarma's gateway decides the extension is alive from the raw Engine.IO ping, which
+       * a hidden tab's throttled timers silently stop sending, so while the tab is hidden the socket is rebuilt every
+       * 20 s (`push-socket-reliability.md` §5.3), and once before the key expires. Why it must not leave a gap: the
+       * old close-then-reopen reported `connected = false` for the ~0.5 s in between, which took the softphone
+       * `offline`, tore down the presence socket and left Zadarma with no socket to push an incoming call to.
+       *
+       * Now the OLD socket stays up and stays current until the NEW one has actually connected; only then do we swap,
+       * move the pings and close the old one. A healthy rebuild never changes `connected`. A failed one — the key fetch
+       * throws, the socket errors, or it has not connected within `REBUILD_CONNECT_TIMEOUT_MS` — keeps the old socket
+       * and retries, instead of leaving the tab disconnected. Zadarma does not evict the older of two sockets for one
+       * sip (multi-tab-leader-election.md §1), so the overlap is safe.
+       */
       async #reopen() {
-        if (this.#closed) return;
-        this.#stopPings();
-        this.#socket?.close();
-        this.#socket = null;
-        this.#setConnected(false);
+        if (this.#closed || this.#rebuilding) return;
+        if (!this.#socket) {
+          try {
+            await this.#open();
+          } catch {
+          }
+          return;
+        }
+        this.#rebuilding = true;
         try {
-          await this.#open();
+          const { key, sip, keyExpiresAt } = await this.deps.fetchKey();
+          if (this.#closed) return;
+          const swapped = await new Promise((resolve) => {
+            const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
+            this.#candidate = socket;
+            let settled = false;
+            const finish = (ok) => {
+              if (settled) return;
+              settled = true;
+              clearTimeout(timer);
+              this.#abortRebuild = null;
+              if (ok && socket.connected) {
+                this.#swapIn(socket, keyExpiresAt);
+              } else {
+                this.#candidate = null;
+                socket.close();
+              }
+              resolve(ok && socket.connected);
+            };
+            const timer = setTimeout(() => finish(false), REBUILD_CONNECT_TIMEOUT_MS);
+            this.#abortRebuild = () => finish(false);
+            this.#attach(socket, { onConnect: () => finish(true), onFailure: () => finish(false) });
+          });
+          if (!swapped) this.#armRetry();
         } catch {
+          this.#armRetry();
+        } finally {
+          this.#rebuilding = false;
         }
       }
+      /**
+       * The moment of the swap — synchronous, called from the candidate's own `connect` event so nothing can run
+       * between "the new socket is up" and "it is the current one". Order matters: `#socket` moves first, so the old
+       * socket's `disconnect` (our own `close()` of it, just below) is ignored by `#attach`.
+       */
+      #swapIn(socket, keyExpiresAt) {
+        const previous = this.#socket;
+        this.#socket = socket;
+        this.#candidate = null;
+        clearTimeout(this.#retryTimer);
+        this.#retryTimer = void 0;
+        this.#stopPings();
+        this.#startPings(socket);
+        this.#setConnected(true);
+        previous?.close();
+        this.#armRefresh(keyExpiresAt);
+      }
+      #armRetry() {
+        if (this.#closed) return;
+        clearTimeout(this.#retryTimer);
+        this.#retryTimer = setTimeout(() => void this.#reopen(), REBUILD_RETRY_MS);
+      }
       disconnect() {
         this.#closed = true;
         this.#stopPings();
         clearTimeout(this.#refreshTimer);
         this.#refreshTimer = void 0;
+        clearTimeout(this.#retryTimer);
+        this.#retryTimer = void 0;
+        this.#abortRebuild?.();
         this.#unwatchBackground?.();
         this.#unwatchBackground = void 0;
         this.#socket?.close();
@@ -1689,6 +1837,9 @@ function canTransition(from, to) {
 function isTerminal(state) {
   return CALL_TRANSITIONS[state].length === 0;
 }
+function isOnCallState(state) {
+  return state !== "ringing" && !isTerminal(state);
+}
 
 // src/core/call-impl.ts
 var CallImpl = class _CallImpl extends Emitter {
@@ -1906,7 +2057,12 @@ function coventiaBackend(config, tokenSource, fallbackBaseUrl) {
     resolveContact: async (number) => (await load()).resolveContact(number),
     listAgents: async () => (await load()).listAgents(),
     transferOutcomes: async (params) => (await load()).transferOutcomes(params),
-    presence: async (callbacks) => (await load()).presence(callbacks)
+    presence: async (callbacks) => (await load()).presence(callbacks),
+    ringtones: {
+      get: async (signal) => (await load()).ringtones.get(signal),
+      setMine: async (id) => (await load()).ringtones.setMine(id),
+      cached: async () => (await load()).ringtones.cached?.() ?? null
+    }
   };
 }
 
@@ -2051,13 +2207,18 @@ function startPresenceSocket(params) {
   let agents = /* @__PURE__ */ new Map();
   let lastReportedOnCall = null;
   let connection = null;
-  const stop = () => {
+  let byeOnArrival = false;
+  const stop = (options) => {
     if (stopped) return;
     stopped = true;
     if (reconnectTimer !== null) {
       cancelTimeout(reconnectTimer);
       reconnectTimer = null;
     }
+    if (options?.bye) {
+      byeOnArrival = true;
+      connection?.bye?.();
+    }
     connection?.close();
     connection = null;
   };
@@ -2096,6 +2257,7 @@ function startPresenceSocket(params) {
       return;
     }
     if (stopped) {
+      if (byeOnArrival) opened.bye?.();
       opened.close();
       return;
     }
@@ -2117,18 +2279,36 @@ function startPresenceSocket(params) {
 // src/core/softphone-impl.ts
 init_errors();
 var liveInstance = false;
+var PRESENCE_TEARDOWN_GRACE_MS = 1e4;
 var BrowserAudioDevices = class {
   inputs = [];
   outputs = [];
   currentInputId = null;
   currentOutputId = null;
+  currentRingtoneOutputId = null;
   canSelectOutput;
+  canSelectRingtoneOutput;
   #engine;
   #onChange;
+  /**
+   * What the user CHOSE, remembered across reloads — distinct from the `current*` fields, which are
+   * what is usable right now. Keeping them apart is what stops a fresh page load from wiping a saved
+   * choice: until the microphone has been granted, Chrome enumerates every device with a blank id, so
+   * "is the saved device in the list?" is no on every first enumeration. The preference survives
+   * that; `current*` simply reads `null` until the device is really there.
+   */
+  #preferred;
+  /** The input the engine was last told about — it starts on the system default (`null`). */
+  #engineInputId = null;
   constructor(engine, onChange) {
     this.#engine = engine;
     this.#onChange = onChange;
     this.canSelectOutput = isBrowser() && typeof HTMLMediaElement !== "undefined" && "setSinkId" in HTMLMediaElement.prototype;
+    this.canSelectRingtoneOutput = this.canSelectOutput;
+    this.#preferred = readStoredDevices();
+    this.currentInputId = this.#preferred.input;
+    this.currentOutputId = this.#preferred.output;
+    this.currentRingtoneOutputId = this.#preferred.ringtone;
     if (isBrowser() && navigator.mediaDevices) {
       void this.refresh();
       navigator.mediaDevices.addEventListener?.("devicechange", () => void this.refresh());
@@ -2144,26 +2324,63 @@ var BrowserAudioDevices = class {
     }
     this.inputs = all.filter((d) => d.kind === "audioinput");
     this.outputs = all.filter((d) => d.kind === "audiooutput");
-    if (this.currentInputId && !this.inputs.some((d) => d.deviceId === this.currentInputId)) {
-      this.currentInputId = null;
-    }
-    if (this.currentOutputId && !this.outputs.some((d) => d.deviceId === this.currentOutputId)) {
-      this.currentOutputId = null;
-    }
+    this.currentInputId = usable(this.#preferred.input, this.inputs);
+    this.currentOutputId = usable(this.#preferred.output, this.outputs);
+    this.currentRingtoneOutputId = usable(this.#preferred.ringtone, this.outputs);
     this.#onChange();
+    if (this.currentInputId && this.currentInputId !== this.#engineInputId) {
+      await this.#tellEngine(this.currentInputId);
+    }
   }
   async setInput(deviceId) {
     this.currentInputId = deviceId;
+    this.#remember({ input: deviceId });
     this.#onChange();
+    await this.#tellEngine(deviceId);
+  }
+  async #tellEngine(deviceId) {
+    this.#engineInputId = deviceId;
     await this.#engine.setInputDevice?.(deviceId);
   }
   async setOutput(deviceId) {
     this.currentOutputId = deviceId;
+    this.#remember({ output: deviceId });
     this.#onChange();
   }
-  async setRingtoneOutput() {
+  async setRingtoneOutput(deviceId) {
+    this.currentRingtoneOutputId = deviceId;
+    this.#remember({ ringtone: deviceId });
+    this.#onChange();
+  }
+  #remember(patch) {
+    this.#preferred = { ...this.#preferred, ...patch };
+    writeStoredDevices(this.#preferred);
   }
 };
+var DEVICES_KEY = "coventia-softphone:devices";
+var NO_DEVICES = { input: null, output: null, ringtone: null };
+function usable(id, list) {
+  return id && list.some((d) => d.deviceId === id) ? id : null;
+}
+function readStoredDevices() {
+  if (!isBrowser()) return NO_DEVICES;
+  try {
+    const raw = JSON.parse(globalThis.localStorage?.getItem(DEVICES_KEY) ?? "null");
+    if (!raw || typeof raw !== "object") return NO_DEVICES;
+    const pick = (v) => typeof v === "string" && v ? v : null;
+    const r = raw;
+    return { input: pick(r.input), output: pick(r.output), ringtone: pick(r.ringtone) };
+  } catch {
+    return NO_DEVICES;
+  }
+}
+function writeStoredDevices(devices) {
+  if (!isBrowser()) return;
+  try {
+    globalThis.localStorage?.setItem(DEVICES_KEY, JSON.stringify(devices));
+  } catch {
+  }
+}
 var SoftphoneImpl = class extends Emitter {
   #state = "stopped";
   #lastError = null;
@@ -2191,6 +2408,8 @@ var SoftphoneImpl = class extends Emitter {
    * rather than by any one call.
    */
   #presenceWatch = null;
+  /** A pending state-driven teardown of the watch — see `PRESENCE_TEARDOWN_GRACE_MS`. */
+  #presenceTeardownTimer = null;
   #presenceAgents = [];
   /**
    * `tabLock` defaults to the real Web Locks implementation — not part of `SoftphoneConfig` (an
@@ -2250,6 +2469,7 @@ var SoftphoneImpl = class extends Emitter {
   }
   async stop() {
     if (!this.#startedHere) return;
+    this.#sayGoodbye();
     this.#tabLock.release();
     if (this.#isLeader) {
       await this.#engine.stop();
@@ -2265,8 +2485,7 @@ var SoftphoneImpl = class extends Emitter {
     this.#destroyed = true;
     for (const stopWatch of this.#activeWatches) stopWatch();
     this.#activeWatches.clear();
-    this.#presenceWatch?.stop();
-    this.#presenceWatch = null;
+    this.#sayGoodbye();
     await this.stop().catch(() => {
     });
     this.#setState("destroyed");
@@ -2301,11 +2520,15 @@ var SoftphoneImpl = class extends Emitter {
       (target, callerNumber) => this.#onTransfer(target, callerNumber)
     );
     this.#activeCall = call;
+    const offState = call.on("stateChanged" /* StateChanged */, () => this.#syncCallState());
+    this.#syncCallState();
     const off = call.on("ended" /* Ended */, () => {
       off();
+      offState();
       if (this.#activeCall === call) {
         this.#activeCall = null;
         this.emit("activeCallChanged" /* ActiveCallChanged */, { call: null });
+        this.#syncCallState();
       }
     });
     if (this.#resolveContact) {
@@ -2325,6 +2548,21 @@ var SoftphoneImpl = class extends Emitter {
     this.emit("stateChanged" /* StateChanged */, { state, previous });
     this.#syncPresenceWatch();
   }
+  /**
+   * Whether this softphone is on a call right now, as presence means it (`isOnCallState`). There is a single
+   * active-call slot, and a consult leg is a child of that call, so the parent staying alive covers a consult.
+   */
+  #isOnCall() {
+    return this.#activeCall !== null && isOnCallState(this.#activeCall.state);
+  }
+  /**
+   * Reports the current on-a-call value to the backend. The watch de-duplicates (it only sends on change) and
+   * remembers the latest value to replay after a reconnect, so this can be called on every transition without
+   * ceremony. A no-op while there is no presence watch (not online, not the leader, no backend configured).
+   */
+  #syncCallState() {
+    this.#presenceWatch?.reportCallState(this.#isOnCall());
+  }
   #setLeader(isLeader) {
     if (isLeader === this.#isLeader) return;
     this.#isLeader = isLeader;
@@ -2343,9 +2581,21 @@ var SoftphoneImpl = class extends Emitter {
    * This still passes `getIsLeader: () => this.#isLeader` for that narrower, defensive recheck; the
    * BROAD online/leader gate — whether to be connected AT ALL — is owned entirely here, the same
    * split `#onTransfer` already has with `startTransferWatch`.
+   *
+   * One exception to "tear down the moment `online` is lost": a leader that is merely `offline` or
+   * `reconnecting` keeps its watch for `PRESENCE_TEARDOWN_GRACE_MS` — a blip shorter than that never touches
+   * the presence socket at all. Anything else (stopped, starting, destroyed, or no longer the leader) still
+   * tears it down at once: those are not blips, and a follower must never hold a connection.
    */
   #syncPresenceWatch() {
-    const shouldRun = Boolean(this.sources) && this.#state === "online" && this.#isLeader;
+    const eligible = Boolean(this.sources) && this.#isLeader;
+    const shouldRun = eligible && this.#state === "online";
+    const blip = eligible && (this.#state === "offline" || this.#state === "reconnecting");
+    if (!blip) this.#cancelPresenceTeardown();
+    if (blip && this.#presenceWatch !== null) {
+      this.#schedulePresenceTeardown();
+      return;
+    }
     if (shouldRun === (this.#presenceWatch !== null)) return;
     if (shouldRun) {
       this.#presenceWatch = startPresenceSocket({
@@ -2356,13 +2606,49 @@ var SoftphoneImpl = class extends Emitter {
           this.emit("presenceChanged" /* PresenceChanged */, { agents });
         }
       });
+      this.#syncCallState();
     } else {
-      this.#presenceWatch?.stop();
-      this.#presenceWatch = null;
-      this.#presenceAgents = [];
-      this.emit("presenceChanged" /* PresenceChanged */, { agents: [] });
+      this.#stopPresence();
     }
   }
+  /**
+   * Starts the grace period before an `offline` / `reconnecting` leader loses its presence socket. Idempotent
+   * on purpose: a second notification inside the same blip must NOT push the deadline back.
+   */
+  #schedulePresenceTeardown() {
+    if (this.#presenceTeardownTimer !== null) return;
+    this.#presenceTeardownTimer = setTimeout(() => {
+      this.#presenceTeardownTimer = null;
+      if (this.#state === "online" && this.#isLeader) return;
+      this.#stopPresence();
+    }, PRESENCE_TEARDOWN_GRACE_MS);
+  }
+  #cancelPresenceTeardown() {
+    if (this.#presenceTeardownTimer === null) return;
+    clearTimeout(this.#presenceTeardownTimer);
+    this.#presenceTeardownTimer = null;
+  }
+  /**
+   * Stops the presence watch and forgets its roster. A STATE-DRIVEN teardown (the softphone left `online`
+   * for good, or lost leadership) passes nothing and says no goodbye; only a deliberate stop passes `bye`.
+   * Any pending grace-period teardown is cancelled — there is nothing left for it to do.
+   */
+  #stopPresence(options) {
+    this.#cancelPresenceTeardown();
+    if (!this.#presenceWatch) return;
+    this.#presenceWatch.stop(options);
+    this.#presenceWatch = null;
+    this.#presenceAgents = [];
+    this.emit("presenceChanged" /* PresenceChanged */, { agents: [] });
+  }
+  /**
+   * A DELIBERATE stop (`stop()` / `destroy()`): say any call is over, then say goodbye, so the backend drops
+   * this phone at once instead of waiting out the close grace. Idempotent — a second call finds no watch.
+   */
+  #sayGoodbye() {
+    this.#presenceWatch?.reportCallState(false);
+    this.#stopPresence({ bye: true });
+  }
   /**
    * Phase A (transfer outcome relay, `docs/specs/transfer-outcome-relay.md`) — `CallImpl.transfer()`'s
    * internal seam calls this. No-ops entirely when no Coventia backend is configured (`sources` is
@@ -2498,7 +2784,7 @@ function isCallEngine(value) {
 
 // src/index.ts
 init_errors();
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
 exports.CALL_TRANSITIONS = CALL_TRANSITIONS;
 exports.CallEvent = CallEvent;