@coventia/softphone 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { S as Softphone } from './softphone-DhuhcKCy.cjs';
-export { A as AudioDevices } from './softphone-DhuhcKCy.cjs';
-import { S as SoftphoneConfig } from './call-BTYlT2SU.cjs';
-export { C as CALL_TRANSITIONS, a as Call, b as CallDirection, c as CallEvent, d as CallEventMap, e as CallOptions, f as CallState, g as Contact, E as ERROR_CATALOGUE, F as FatalErrorCode, h as FatalSoftphoneError, H as HangupReason, i as HoldOriginator, I as INITIAL_STATES, L as LogLevel, N as NonFatalErrorCode, j as NonFatalSoftphoneError, R as RemoteParty, k as SoftphoneError, l as SoftphoneErrorCode, m as SoftphoneEvent, n as SoftphoneEventMap, o as SoftphoneState, T as TokenEndpointOptions, p as TokenSource, q as TypedEmitter, V as VoiceToken, r as canTransition, s as isFatal, t as isTerminal } from './call-BTYlT2SU.cjs';
+import { S as Softphone } from './softphone-DlGV12Xp.cjs';
+export { A as AudioDevices } from './softphone-DlGV12Xp.cjs';
+import { S as SoftphoneConfig } from './call-VKq1I8yP.cjs';
+export { C as CALL_TRANSITIONS, a as Call, b as CallDirection, c as CallEvent, d as CallEventMap, e as CallOptions, f as CallState, g as Contact, E as ERROR_CATALOGUE, F as FatalErrorCode, h as FatalSoftphoneError, H as HangupReason, i as HoldOriginator, I as INITIAL_STATES, L as LogLevel, N as NonFatalErrorCode, j as NonFatalSoftphoneError, R as RemoteParty, k as SoftphoneError, l as SoftphoneErrorCode, m as SoftphoneEvent, n as SoftphoneEventMap, o as SoftphoneState, T as TokenEndpointOptions, p as TokenSource, q as TypedEmitter, V as VoiceToken, r as canTransition, s as isFatal, t as isTerminal } from './call-VKq1I8yP.cjs';
 
 /**
  * Construct a softphone.
@@ -57,6 +57,6 @@ declare function isWebRtcSupported(): boolean;
  *   - `MockProvider` — lives at @coventia/softphone/testing, so it never lands in a production bundle.
  */
 
-declare const VERSION = "0.0.0";
+declare const VERSION = "0.2.1";
 
 export { Softphone, SoftphoneConfig, VERSION, createSoftphone, isBrowser, isWebRtcSupported };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { S as Softphone } from './softphone-DHmhotbf.js';
-export { A as AudioDevices } from './softphone-DHmhotbf.js';
-import { S as SoftphoneConfig } from './call-BTYlT2SU.js';
-export { C as CALL_TRANSITIONS, a as Call, b as CallDirection, c as CallEvent, d as CallEventMap, e as CallOptions, f as CallState, g as Contact, E as ERROR_CATALOGUE, F as FatalErrorCode, h as FatalSoftphoneError, H as HangupReason, i as HoldOriginator, I as INITIAL_STATES, L as LogLevel, N as NonFatalErrorCode, j as NonFatalSoftphoneError, R as RemoteParty, k as SoftphoneError, l as SoftphoneErrorCode, m as SoftphoneEvent, n as SoftphoneEventMap, o as SoftphoneState, T as TokenEndpointOptions, p as TokenSource, q as TypedEmitter, V as VoiceToken, r as canTransition, s as isFatal, t as isTerminal } from './call-BTYlT2SU.js';
+import { S as Softphone } from './softphone-Cyq3hiIM.js';
+export { A as AudioDevices } from './softphone-Cyq3hiIM.js';
+import { S as SoftphoneConfig } from './call-VKq1I8yP.js';
+export { C as CALL_TRANSITIONS, a as Call, b as CallDirection, c as CallEvent, d as CallEventMap, e as CallOptions, f as CallState, g as Contact, E as ERROR_CATALOGUE, F as FatalErrorCode, h as FatalSoftphoneError, H as HangupReason, i as HoldOriginator, I as INITIAL_STATES, L as LogLevel, N as NonFatalErrorCode, j as NonFatalSoftphoneError, R as RemoteParty, k as SoftphoneError, l as SoftphoneErrorCode, m as SoftphoneEvent, n as SoftphoneEventMap, o as SoftphoneState, T as TokenEndpointOptions, p as TokenSource, q as TypedEmitter, V as VoiceToken, r as canTransition, s as isFatal, t as isTerminal } from './call-VKq1I8yP.js';
 
 /**
  * Construct a softphone.
@@ -57,6 +57,6 @@ declare function isWebRtcSupported(): boolean;
  *   - `MockProvider` — lives at @coventia/softphone/testing, so it never lands in a production bundle.
  */
 
-declare const VERSION = "0.0.0";
+declare const VERSION = "0.2.1";
 
 export { Softphone, SoftphoneConfig, VERSION, createSoftphone, isBrowser, isWebRtcSupported };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { isBrowser } from './chunk-KAXEMJ7E.js';
 export { isBrowser, isWebRtcSupported } from './chunk-KAXEMJ7E.js';
-export { CallEvent, SoftphoneEvent } from './chunk-N2N2EQQJ.js';
+export { CallEvent, SoftphoneEvent } from './chunk-7R6LOOAI.js';
 import { isFatal } from './chunk-2ZSOGGPO.js';
 export { ERROR_CATALOGUE, isFatal } from './chunk-2ZSOGGPO.js';
 import { cachedTokenSource } from './chunk-MHOJHG5E.js';
@@ -75,13 +75,17 @@ 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 {
-  constructor(engineCall, onListenerError, onInternalError) {
+  constructor(engineCall, onListenerError, onInternalError, onTransfer) {
     super(onListenerError);
     this.engineCall = engineCall;
     this.onInternalError = onInternalError;
+    this.onTransfer = onTransfer;
     this.#onListenerError = onListenerError;
     this.#state = INITIAL_STATES[engineCall.direction];
     this.#remote = {
@@ -93,6 +97,7 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   engineCall;
   onInternalError;
+  onTransfer;
   #state;
   #remote;
   #answeredAt = null;
@@ -178,7 +183,10 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   async hangup() {
     if (isTerminal(this.#state)) return;
-    await this.engineCall.hangup();
+    const consult = this.#consultCall;
+    this.#consultCall = null;
+    this.#consultEngineCall = null;
+    await Promise.all([consult?.hangup() ?? Promise.resolve(), this.engineCall.hangup()]);
   }
   mute(muted) {
     if (this.#muted === muted) return;
@@ -200,6 +208,7 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   async transfer(target) {
     await this.engineCall.transfer(target);
+    this.onTransfer?.(target, this.#remote.number.trim() || null);
   }
   async startConsult(target) {
     await this.hold();
@@ -235,6 +244,12 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   #end(reason) {
     if (isTerminal(this.#state)) return;
+    if (this.#consultCall) {
+      const consult = this.#consultCall;
+      this.#consultCall = null;
+      this.#consultEngineCall = null;
+      void consult.hangup();
+    }
     const from = this.#state;
     this.#state = "ended";
     this.emit("stateChanged" /* StateChanged */, { state: "ended", previous: from });
@@ -269,7 +284,7 @@ function coventiaBackend(config, tokenSource, fallbackBaseUrl) {
   }
   let pending = null;
   const load = () => {
-    pending ??= import('./sources-N4BOEDRL.js').then(
+    pending ??= import('./sources-IRKNQPWW.js').then(
       (m) => m.coventiaSources({ ...config, baseUrl, tokenSource })
     );
     return pending;
@@ -278,7 +293,9 @@ function coventiaBackend(config, tokenSource, fallbackBaseUrl) {
     contacts: async (params) => (await load()).contacts(params),
     history: async (params) => (await load()).history(params),
     resolveContact: async (number) => (await load()).resolveContact(number),
-    listAgents: async () => (await load()).listAgents()
+    listAgents: async () => (await load()).listAgents(),
+    transferOutcomes: async (params) => (await load()).transferOutcomes(params),
+    presence: async (callbacks) => (await load()).presence(callbacks)
   };
 }
 
@@ -315,8 +332,175 @@ function webLocksTabLock(lockName = LOCK_NAME) {
   };
 }
 
+// src/core/transfer-watch.ts
+var FAST_INTERVAL_MS = 2e3;
+var FAST_WINDOW_MS = 1e4;
+var SLOW_INTERVAL_MS = 5e3;
+var DEADLINE_MS = 9e4;
+var EXTENSION_LIKE = /^\d{1,6}$/;
+function startTransferWatch(params) {
+  const {
+    target,
+    callerNumber,
+    source,
+    getIsLeader,
+    emit,
+    setTimeout: scheduleTimeout = globalThis.setTimeout,
+    clearTimeout: cancelTimeout = globalThis.clearTimeout,
+    now = () => Date.now()
+  } = params;
+  if (!EXTENSION_LIKE.test(target)) return () => {
+  };
+  if (!getIsLeader()) return () => {
+  };
+  let stopped = false;
+  let timer = null;
+  let cursor = null;
+  const startedAt = now();
+  const stop = () => {
+    stopped = true;
+    if (timer !== null) {
+      cancelTimeout(timer);
+      timer = null;
+    }
+  };
+  const finish = (status) => {
+    stop();
+    emit({ status, target, caller: callerNumber, at: new Date(now()) });
+  };
+  const scheduleNext = () => {
+    if (stopped) return;
+    const elapsed = now() - startedAt;
+    if (elapsed >= DEADLINE_MS) {
+      stop();
+      return;
+    }
+    timer = scheduleTimeout(() => void poll(), elapsed < FAST_WINDOW_MS ? FAST_INTERVAL_MS : SLOW_INTERVAL_MS);
+  };
+  const poll = async () => {
+    if (stopped) return;
+    if (!getIsLeader()) {
+      stop();
+      return;
+    }
+    let page;
+    try {
+      page = await source(cursor === null ? {} : { since: cursor });
+    } catch {
+      if (!stopped) scheduleNext();
+      return;
+    }
+    if (stopped) return;
+    if (cursor === null) {
+      cursor = page.cursor;
+    } else {
+      cursor = page.cursor;
+      const match = page.outcomes.find((o) => o.target === target);
+      if (match) {
+        finish(match.status);
+        return;
+      }
+    }
+    scheduleNext();
+  };
+  void poll();
+  return stop;
+}
+
+// src/core/presence-socket.ts
+var RECONNECT_BASE_MS = 1e3;
+var RECONNECT_MAX_MS = 3e4;
+var NOOP_WATCH = { reportCallState: () => {
+}, stop: () => {
+} };
+function startPresenceSocket(params) {
+  const {
+    source,
+    getIsLeader,
+    onAgentsChanged,
+    setTimeout: scheduleTimeout = globalThis.setTimeout,
+    clearTimeout: cancelTimeout = globalThis.clearTimeout,
+    random = Math.random
+  } = params;
+  if (!getIsLeader()) return NOOP_WATCH;
+  let stopped = false;
+  let attempt = 0;
+  let reconnectTimer = null;
+  let agents = /* @__PURE__ */ new Map();
+  let lastReportedOnCall = null;
+  let connection = null;
+  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;
+  };
+  const scheduleReconnect = () => {
+    if (stopped) return;
+    attempt += 1;
+    const capped = Math.min(RECONNECT_BASE_MS * 2 ** (attempt - 1), RECONNECT_MAX_MS);
+    const delay = capped * random();
+    reconnectTimer = scheduleTimeout(() => void connect(), delay);
+  };
+  const connect = async () => {
+    if (stopped) return;
+    if (!getIsLeader()) {
+      stop();
+      return;
+    }
+    let opened;
+    try {
+      opened = await source({
+        onSnapshot: (snapshot) => {
+          agents = new Map(snapshot.map((agent) => [agent.userId, agent]));
+          onAgentsChanged([...agents.values()]);
+        },
+        onDelta: (agent) => {
+          agents.set(agent.userId, agent);
+          onAgentsChanged([...agents.values()]);
+        },
+        onClose: () => {
+          if (connection === null) return;
+          connection = null;
+          scheduleReconnect();
+        }
+      });
+    } catch {
+      if (!stopped) scheduleReconnect();
+      return;
+    }
+    if (stopped) {
+      if (byeOnArrival) opened.bye?.();
+      opened.close();
+      return;
+    }
+    connection = opened;
+    attempt = 0;
+    if (lastReportedOnCall !== null) connection.reportCallState(lastReportedOnCall);
+  };
+  void connect();
+  return {
+    reportCallState: (onCall) => {
+      if (onCall === lastReportedOnCall) return;
+      lastReportedOnCall = onCall;
+      connection?.reportCallState(onCall);
+    },
+    stop
+  };
+}
+
 // src/core/softphone-impl.ts
 var liveInstance = false;
+var PRESENCE_TEARDOWN_GRACE_MS = 1e4;
 var BrowserAudioDevices = class {
   inputs = [];
   outputs = [];
@@ -377,6 +561,23 @@ var SoftphoneImpl = class extends Emitter {
   /** Contacts + history, whenever there is a Coventia backend to reach. The widget reads these. */
   sources;
   audio;
+  /**
+   * Every in-flight transfer-outcome watch (Phase A), so `destroy()` can stop all of them. Never
+   * pruned as individual watches finish on their own — `stop()` is idempotent and cheap to call again,
+   * and a session accumulating a handful of closures for however many transfers it makes is not worth
+   * the bookkeeping a self-removing set would add.
+   */
+  #activeWatches = /* @__PURE__ */ new Set();
+  /**
+   * Phase B (presence-gated transfer picker). ONE long-lived watch, not a member of `#activeWatches`
+   * — that set is per-transfer instances a live call spawns and forgets; this is a single background
+   * connection tied to the softphone's own lifecycle, started and stopped by `#syncPresenceWatch`
+   * 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
    * internal seam, not something an integrator tunes). Tests construct this class directly with a
@@ -409,6 +610,9 @@ var SoftphoneImpl = class extends Emitter {
   get activeCall() {
     return this.#activeCall;
   }
+  get presence() {
+    return this.#presenceAgents;
+  }
   get canPlayAudio() {
     return true;
   }
@@ -432,6 +636,7 @@ var SoftphoneImpl = class extends Emitter {
   }
   async stop() {
     if (!this.#startedHere) return;
+    this.#sayGoodbye();
     this.#tabLock.release();
     if (this.#isLeader) {
       await this.#engine.stop();
@@ -445,6 +650,9 @@ var SoftphoneImpl = class extends Emitter {
   async destroy() {
     if (this.#destroyed) return;
     this.#destroyed = true;
+    for (const stopWatch of this.#activeWatches) stopWatch();
+    this.#activeWatches.clear();
+    this.#sayGoodbye();
     await this.stop().catch(() => {
     });
     this.#setState("destroyed");
@@ -475,14 +683,19 @@ var SoftphoneImpl = class extends Emitter {
     const call = new CallImpl(
       engineCall,
       (event, error) => this.#reportListenerError("call", event, error),
-      (message) => this.#reportInternalError(message)
+      (message) => this.#reportInternalError(message),
+      (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) {
@@ -500,11 +713,125 @@ var SoftphoneImpl = class extends Emitter {
     this.#state = state;
     if (state === "online") this.#lastError = null;
     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;
     this.emit("leaderChanged" /* LeaderChanged */, { isLeader });
+    this.#syncPresenceWatch();
+  }
+  /**
+   * Phase B (presence-gated transfer picker, `docs/specs/transfer-presence-picker.md` plan T6/T7).
+   * The ONE place that decides whether the presence connection should be running right now — called
+   * after every `#setState`/`#setLeader` transition rather than left to either alone, since either
+   * one flipping can change the answer. No-ops entirely when no Coventia backend is configured
+   * (`sources` is null) — same guard `#onTransfer` uses, and for the same reason: nothing to open.
+   *
+   * `presence-socket.ts`'s own `getIsLeader` is checked at start and before each reconnect attempt,
+   * not on a poll tick the way `startTransferWatch`'s is — see that module's own doc comment for why.
+   * 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 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({
+        source: this.sources.presence,
+        getIsLeader: () => this.#isLeader,
+        onAgentsChanged: (agents) => {
+          this.#presenceAgents = agents;
+          this.emit("presenceChanged" /* PresenceChanged */, { agents });
+        }
+      });
+      this.#syncCallState();
+    } else {
+      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
+   * null): there is then nothing to poll, and behaviour is exactly what it was before this feature
+   * existed (spec §5.4).
+   */
+  #onTransfer(target, callerNumber) {
+    if (!this.sources) return;
+    const stopWatch = startTransferWatch({
+      target,
+      callerNumber,
+      source: this.sources.transferOutcomes,
+      getIsLeader: () => this.#isLeader,
+      emit: (payload) => this.emit("transferOutcome" /* TransferOutcome */, payload)
+    });
+    this.#activeWatches.add(stopWatch);
   }
   /**
    * Re-emit an engine failure to the host, and remember it if it is fatal.
@@ -563,7 +890,7 @@ function defaultZadarmaEngine(config) {
   const stateChange = new LazyRelay();
   const error = new LazyRelay();
   function load() {
-    pending ??= import('./zadarma-engine-DN2SZSQ3.js').then(({ createZadarmaEngine }) => {
+    pending ??= import('./zadarma-engine-L5DEFXUS.js').then(({ createZadarmaEngine }) => {
       const engine = createZadarmaEngine(config);
       incoming.attach({ on: (l) => engine.onIncoming(l) });
       stateChange.attach({ on: (l) => engine.onStateChange(l) });
@@ -623,7 +950,7 @@ function isCallEngine(value) {
 }
 
 // src/index.ts
-var VERSION = "0.0.0";
+var VERSION = "0.2.1";
 
 export { CALL_TRANSITIONS, INITIAL_STATES, VERSION, canTransition, createSoftphone, isTerminal };
 //# sourceMappingURL=index.js.map