@coventia/softphone 0.1.0 → 0.2.0

package/dist/{engine-D9nbeY08.d.cts → engine-CDjkrXHY.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-BTYlT2SU.cjs';
+import { e as CallOptions, b as CallDirection, H as HangupReason, i as HoldOriginator, o as SoftphoneState, k as SoftphoneError } from './call-DUVnDxsz.cjs';
 
 /**
  * The `CallEngine` seam — INTERNAL, not exported from src/index.ts.

package/dist/{engine-Doa6Brkm.d.ts → engine-EPCKf-Bl.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-BTYlT2SU.js';
+import { e as CallOptions, b as CallDirection, H as HangupReason, i as HoldOriginator, o as SoftphoneState, k as SoftphoneError } from './call-DUVnDxsz.js';
 
 /**
  * The `CallEngine` seam — INTERNAL, not exported from src/index.ts.

package/dist/index.cjs

@@ -92,7 +92,7 @@ var init_token_cache = __esm({
 });
 
 // src/coventia/api.ts
-function createGet(config) {
+function createRequest(config, method) {
   const doFetch = config.fetch ? config.fetch : (...args) => globalThis.fetch(...args);
   const base = config.baseUrl.replace(/\/+$/, "");
   async function attempt(path, params, signal) {
@@ -103,6 +103,7 @@ function createGet(config) {
     }
     const query = qs.toString();
     const res = await doFetch(`${base}${path}${query ? `?${query}` : ""}`, {
+      method,
       // The RAW token, no `Bearer ` prefix — see `VoiceToken.token` (SPEC §6.1).
       headers: { Authorization: token },
       ...signal ? { signal } : {}
@@ -115,7 +116,7 @@ function createGet(config) {
     }
     return body;
   }
-  return async function get(path, params = {}, signal) {
+  return async function request(path, params = {}, signal) {
     try {
       return await attempt(path, params, signal);
     } catch (error) {
@@ -125,6 +126,12 @@ function createGet(config) {
     }
   };
 }
+function createGet(config) {
+  return createRequest(config, "GET");
+}
+function createPost(config) {
+  return createRequest(config, "POST");
+}
 var ApiError;
 var init_api = __esm({
   "src/coventia/api.ts"() {
@@ -167,6 +174,7 @@ function resolverFromContacts(contacts) {
 }
 function coventiaSources(config) {
   const get = createGet(config);
+  const post = createPost(config);
   const base = config.basePath ?? "/phone";
   const org = config.organizationId ? { organization_id: config.organizationId } : {};
   const coventiaContacts = async ({ search, skip, limit }) => {
@@ -251,12 +259,89 @@ function coventiaSources(config) {
       people: (body.people ?? []).map(toAgent)
     };
   };
+  const coventiaTransferOutcomes = async ({ since }) => {
+    const body = await get(
+      `${base}/transfers/outcomes`,
+      { ...org, since }
+    );
+    return {
+      cursor: body.cursor ?? "0",
+      outcomes: (body.outcomes ?? []).map(toTransferOutcome)
+    };
+  };
+  const coventiaPresence = (callbacks) => {
+    const WS = config.WebSocket ?? globalThis.WebSocket;
+    return new Promise((resolve2, reject) => {
+      void (async () => {
+        let ticket;
+        try {
+          const body = await post(`${base}/presence/ticket`, org);
+          if (!body.ticket) throw new Error("presence ticket mint returned no ticket");
+          ticket = body.ticket;
+        } catch (error) {
+          reject(error instanceof Error ? error : new Error(String(error)));
+          return;
+        }
+        const wsUrl = `${toWebSocketUrl(config.baseUrl)}${base}/presence?ticket=${encodeURIComponent(ticket)}`;
+        const ws = new WS(wsUrl);
+        let settled = false;
+        ws.onopen = () => {
+          if (settled) return;
+          settled = true;
+          resolve2({
+            reportCallState: (onCall) => {
+              if (ws.readyState !== WS.OPEN) return;
+              ws.send(JSON.stringify({ type: "call-state", onCall }));
+            },
+            close: () => {
+              ws.onclose = null;
+              ws.onerror = null;
+              ws.close();
+            }
+          });
+        };
+        ws.onmessage = (event) => {
+          let data;
+          try {
+            data = JSON.parse(String(event.data));
+          } catch {
+            return;
+          }
+          const msg = data;
+          if (msg.type === "snapshot") {
+            callbacks.onSnapshot((msg.agents ?? []).map(toPresenceEntry));
+          } else if (msg.type === "delta" && msg.agent) {
+            callbacks.onDelta(toPresenceEntry(msg.agent));
+          }
+        };
+        ws.onclose = () => {
+          if (!settled) {
+            settled = true;
+            reject(new Error("presence socket closed before opening"));
+            return;
+          }
+          callbacks.onClose();
+        };
+        ws.onerror = () => {
+        };
+      })();
+    });
+  };
   const contacts = config.contacts ?? coventiaContacts;
   const resolve = config.resolveContact ?? (config.contacts ? resolverFromContacts(config.contacts) : coventiaResolve);
   const history = withNameResolution(rawHistory, resolve);
-  return { contacts, history, resolveContact: resolve, listAgents: coventiaListAgents };
+  const transferOutcomes = config.transferOutcomes ?? coventiaTransferOutcomes;
+  const presence = config.presence ?? coventiaPresence;
+  return {
+    contacts,
+    history,
+    resolveContact: resolve,
+    listAgents: coventiaListAgents,
+    transferOutcomes,
+    presence
+  };
 }
-var toContact, toDirection, otherParty, isMissed, toOutcome, toDate;
+var toContact, toDirection, otherParty, isMissed, toOutcome, toDate, toTransferOutcome, toPresenceState, toPresenceEntry, toWebSocketUrl;
 var init_sources2 = __esm({
   "src/coventia/sources.ts"() {
     init_sources();
@@ -291,6 +376,20 @@ var init_sources2 = __esm({
       const d = new Date(raw);
       return Number.isNaN(d.getTime()) ? /* @__PURE__ */ new Date(0) : d;
     };
+    toTransferOutcome = (row) => ({
+      id: row.id ?? "",
+      target: row.target ?? "",
+      status: row.status === "connected" ? "connected" : "not-connected",
+      at: toDate(row.at)
+    });
+    toPresenceState = (raw) => raw === "disponible" || raw === "en_llamada" ? raw : "desconectado";
+    toPresenceEntry = (row) => ({
+      userId: row.userId ?? "",
+      extension: row.extension ?? "",
+      name: row.name ?? null,
+      state: toPresenceState(row.state)
+    });
+    toWebSocketUrl = (httpUrl) => httpUrl.replace(/^http/, "ws").replace(/\/+$/, "");
   }
 });
 
@@ -746,6 +845,14 @@ var init_ua = __esm({
       #uaInFlight = null;
       #domain = "";
       #activeCall = null;
+      /**
+       * The consult leg from `startConsult` (SPEC §5.6), if one is live on this UA right now.
+       *
+       * Tracked separately from `#activeCall` so `#maybeTeardownUA` can tell "both legs are actually gone"
+       * apart from "the main leg ended, but a consult is still up" — see that method's own comment for the
+       * bug this exists to prevent.
+       */
+      #consultCall = null;
       /** The chosen microphone, or `null` for the browser default. Read fresh by every new leg's
        *  `mediaConstraints`, and pushed live to `#activeCall` by `setInputDevice`. */
       #inputDeviceId = null;
@@ -864,9 +971,7 @@ var init_ua = __esm({
         const ms = this.provider.quirks?.noInviteTeardownMs;
         if (!ms) return;
         this.#clearNoInviteTimer();
-        this.#noInviteTimer = setTimeout(() => {
-          if (!this.#activeCall) this.#teardownUA();
-        }, ms);
+        this.#noInviteTimer = setTimeout(() => this.#maybeTeardownUA(), ms);
       }
       /**
        * Rebuild the incoming-signal channel with fresh credentials, after a registration failure.
@@ -988,6 +1093,7 @@ var init_ua = __esm({
         }
         this.#ua = null;
         this.#activeCall = null;
+        this.#consultCall = null;
       }
       /** Place a call once the UA is registered (its 200 OK for REGISTER has arrived). */
       /**
@@ -1030,7 +1136,7 @@ var init_ua = __esm({
             const code = missed ? "call/missed" : CALL_END_CODES[event.reason];
             if (code) this.#reportError(code, event.cause);
             if (this.#activeCall === call) this.#activeCall = null;
-            if (this.provider.registrationMode === "on-demand") this.#teardownUA();
+            this.#maybeTeardownUA();
           }
         });
         return call;
@@ -1041,12 +1147,38 @@ var init_ua = __esm({
           mediaConstraints: buildAudioConstraints(this.#inputDeviceId),
           pcConfig: PC_CONFIG
         });
-        return new SipEngineCall(consultSession, {
+        const consultCall = new SipEngineCall(consultSession, {
           id: nextCallId(),
           buildTarget: (x) => this.#buildTarget(x),
           placeConsult: () => Promise.reject(new Error("cannot consult from a consult leg")),
           iceGatheringCapMs: this.provider.quirks?.iceGatheringCapMs ?? DEFAULT_ICE_CAP_MS
         });
+        this.#consultCall = consultCall;
+        consultCall.onEvent((event) => {
+          if (event.type === "ended") {
+            if (this.#consultCall === consultCall) this.#consultCall = null;
+            this.#maybeTeardownUA();
+          }
+        });
+        return consultCall;
+      }
+      /**
+       * On-demand registration (SPEC §3.3): the UA is disposable once NOTHING is left on it — but "the
+       * main leg ended" (or "no INVITE followed this push") is not the same fact as "nothing is left."
+       * `completeTransfer()` (SPEC §5.6) ends the main leg via a REFER…Replaces BYE *while the consult leg
+       * is still what the PBX needs to bridge the caller onto* — tearing the UA down (and with it, EVERY
+       * session on it, via `terminateSessions`) the instant the main leg's `ended` fires killed that
+       * consult leg out from under the transfer before the bridge could use it, and the caller was simply
+       * gone. Two real call sites hit this independently (found live, 2026-08-04): the main leg's own
+       * `ended` handler, and `#armNoInviteTeardown`'s 5s timer — the latter re-arms on EVERY push,
+       * including unrelated "answered" pushes Zadarma sends around other account activity, so it can fire
+       * minutes after a transfer with no `#activeCall` and no idea a consult leg is mid-handoff. Both now
+       * route through here rather than checking `#activeCall` alone.
+       */
+      #maybeTeardownUA() {
+        if (this.provider.registrationMode !== "on-demand") return;
+        if (this.#activeCall || this.#consultCall) return;
+        this.#teardownUA();
       }
       #startRejectGuard() {
         const ms = this.provider.quirks?.rejectGuardMs;
@@ -1517,6 +1649,8 @@ var SoftphoneEvent = /* @__PURE__ */ ((SoftphoneEvent2) => {
   SoftphoneEvent2["DeviceChange"] = "deviceChange";
   SoftphoneEvent2["Error"] = "error";
   SoftphoneEvent2["LeaderChanged"] = "leaderChanged";
+  SoftphoneEvent2["TransferOutcome"] = "transferOutcome";
+  SoftphoneEvent2["PresenceChanged"] = "presenceChanged";
   return SoftphoneEvent2;
 })(SoftphoneEvent || {});
 var CallEvent = /* @__PURE__ */ ((CallEvent2) => {
@@ -1558,10 +1692,11 @@ function 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 = {
@@ -1573,6 +1708,7 @@ var CallImpl = class _CallImpl extends Emitter {
   }
   engineCall;
   onInternalError;
+  onTransfer;
   #state;
   #remote;
   #answeredAt = null;
@@ -1658,7 +1794,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;
@@ -1680,6 +1819,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();
@@ -1715,6 +1855,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 });
@@ -1758,7 +1904,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)
   };
 }
 
@@ -1806,6 +1954,166 @@ 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;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (reconnectTimer !== null) {
+      cancelTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    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) {
+      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
 init_errors();
 var liveInstance = false;
@@ -1869,6 +2177,21 @@ 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;
+  #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
@@ -1901,6 +2224,9 @@ var SoftphoneImpl = class extends Emitter {
   get activeCall() {
     return this.#activeCall;
   }
+  get presence() {
+    return this.#presenceAgents;
+  }
   get canPlayAudio() {
     return true;
   }
@@ -1937,6 +2263,10 @@ 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.#presenceWatch?.stop();
+    this.#presenceWatch = null;
     await this.stop().catch(() => {
     });
     this.#setState("destroyed");
@@ -1967,7 +2297,8 @@ 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 off = call.on("ended" /* Ended */, () => {
@@ -1992,11 +2323,62 @@ var SoftphoneImpl = class extends Emitter {
     this.#state = state;
     if (state === "online") this.#lastError = null;
     this.emit("stateChanged" /* StateChanged */, { state, previous });
+    this.#syncPresenceWatch();
   }
   #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`.
+   */
+  #syncPresenceWatch() {
+    const shouldRun = Boolean(this.sources) && this.#state === "online" && this.#isLeader;
+    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 });
+        }
+      });
+    } else {
+      this.#presenceWatch?.stop();
+      this.#presenceWatch = null;
+      this.#presenceAgents = [];
+      this.emit("presenceChanged" /* PresenceChanged */, { agents: [] });
+    }
+  }
+  /**
+   * 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.
@@ -2116,7 +2498,7 @@ function isCallEngine(value) {
 
 // src/index.ts
 init_errors();
-var VERSION = "0.0.0";
+var VERSION = "0.2.0";
 
 exports.CALL_TRANSITIONS = CALL_TRANSITIONS;
 exports.CallEvent = CallEvent;