@coventia/softphone 0.2.0 → 0.2.1

package/dist/{engine-CDjkrXHY.d.cts → engine-BlQBo2Ys.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, o as SoftphoneState, k as SoftphoneError } from './call-VKq1I8yP.cjs';
 
 /**
  * The `CallEngine` seam — INTERNAL, not exported from src/index.ts.

package/dist/{engine-EPCKf-Bl.d.ts → engine-C0BOkIcW.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, o as SoftphoneState, k as SoftphoneError } from './call-VKq1I8yP.js';
 
 /**
  * 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;
@@ -1222,11 +1226,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 +1256,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 +1277,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 +1344,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 +1786,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 {
@@ -2051,13 +2151,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 +2201,7 @@ function startPresenceSocket(params) {
       return;
     }
     if (stopped) {
+      if (byeOnArrival) opened.bye?.();
       opened.close();
       return;
     }
@@ -2117,6 +2223,7 @@ function startPresenceSocket(params) {
 // src/core/softphone-impl.ts
 init_errors();
 var liveInstance = false;
+var PRESENCE_TEARDOWN_GRACE_MS = 1e4;
 var BrowserAudioDevices = class {
   inputs = [];
   outputs = [];
@@ -2191,6 +2298,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 +2359,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 +2375,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 +2410,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 +2438,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 +2471,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 +2496,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 +2674,7 @@ function isCallEngine(value) {
 
 // src/index.ts
 init_errors();
-var VERSION = "0.2.0";
+var VERSION = "0.2.1";
 
 exports.CALL_TRANSITIONS = CALL_TRANSITIONS;
 exports.CallEvent = CallEvent;