@coventia/softphone 0.1.0

package/dist/zadarma/index.cjs

@@ -0,0 +1,1144 @@
+'use strict';
+
+// src/transports/sip/media.ts
+function buildAudioConstraints(deviceId) {
+  return { audio: deviceId ? { deviceId: { exact: deviceId } } : true, video: false };
+}
+function capIceGathering(session, capMs) {
+  let settled = false;
+  let timer;
+  const settle = (ready) => {
+    if (settled) return;
+    settled = true;
+    if (timer) clearTimeout(timer);
+    try {
+      ready();
+    } catch {
+    }
+  };
+  session.on("icecandidate", ({ ready }) => {
+    if (!timer) timer = setTimeout(() => settle(ready), capMs);
+  });
+  return () => {
+    if (timer) clearTimeout(timer);
+  };
+}
+
+// src/transports/sip/ice.ts
+var DEFAULT_ICE_SERVERS = [
+  { urls: "stun:stun.l.google.com:19302" }
+];
+var PC_CONFIG = { iceServers: [...DEFAULT_ICE_SERVERS] };
+
+// src/transports/sip/session.ts
+function mapEndReason(e) {
+  if (e.originator === "local") return "local";
+  if (e.originator === "remote") return "remote";
+  return "failed";
+}
+function mapFailReason(e) {
+  switch (e.cause) {
+    // 486 Busy Here, 600 Busy Everywhere. Also what most endpoints send for a MANUAL DECLINE — SIP
+    // does not distinguish the two, and neither can we, which is why the copy covers both.
+    case "Busy":
+      return "busy";
+    /*
+          `Rejected` is 403 / 603 Decline — an explicit refusal, sent by the endpoints that bother to.
+          `Redirected` is 3xx: not literally a rejection, but it ends the same way — not connected, and
+          nothing to retry.
+    
+          (Both comments sit ABOVE the group rather than between the labels. A comment between two `case`
+          lines makes the first one non-empty to `no-fallthrough`, which then demands a `break` that
+          would be unreachable.)
+        */
+    case "Rejected":
+    case "Redirected":
+      return "rejected";
+    /*
+      `Unavailable` is 480 Temporarily Unavailable / 410 / 408 Request Timeout / 430 — THE ring-out
+      case, and the one that was missing. `No Answer` and `Expires` are local: our own no-answer
+      timer, and a session that expired.
+    */
+    case "Unavailable":
+    case "No Answer":
+    case "Expires":
+      return "no-answer";
+    case "Canceled":
+      return e.originator === "local" ? "local" : "remote";
+    // Everything else is a genuine failure worth naming: Not Found (404/604), Address Incomplete,
+    // Incompatible SDP, Authentication Error, WebRTC Error, RTP Timeout, Connection Error…
+    default:
+      return "failed";
+  }
+}
+function remoteNumberOf(session) {
+  const id = session.remote_identity;
+  return id?.uri?.user ?? id?.uri?.toString() ?? "";
+}
+var SipEngineCall = class {
+  id;
+  direction;
+  remoteNumber;
+  #session;
+  #deps;
+  #listeners = /* @__PURE__ */ new Set();
+  #ended = false;
+  #cancelIceCap = null;
+  /**
+   * The stream behind a LIVE device swap (`swapInputDevice`), if one has happened. Distinct from
+   * JsSIP's own original capture: that one is `_localMediaStreamLocallyGenerated` and JsSIP stops it
+   * itself on close (see `#end`'s comment). This one is ours — obtained with our own `getUserMedia`
+   * call, attached via `replaceTrack`, and never known to JsSIP at all — so nothing else will ever
+   * stop it unless we do, here.
+   */
+  #swappedStream = null;
+  constructor(session, deps) {
+    this.#session = session;
+    this.#deps = deps;
+    this.id = deps.id;
+    this.direction = session.direction === "incoming" ? "inbound" : "outbound";
+    this.remoteNumber = remoteNumberOf(session);
+    this.#wire();
+  }
+  /** @internal — the underlying session, for `completeTransfer`'s REFER…Replaces. */
+  get session() {
+    return this.#session;
+  }
+  onEvent(listener) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+  // ── JsSIP events → raw engine signals ─────────────────────────────────────
+  #wire() {
+    const s = this.#session;
+    if (this.direction === "outbound") {
+      s.on("progress", () => this.#fire({ type: "progress", response: "ringing" }));
+    }
+    const wireRemoteTrack = (pc) => {
+      pc.ontrack = ({ streams }) => {
+        if (streams[0]) this.#fire({ type: "stream", stream: streams[0] });
+      };
+    };
+    s.on("peerconnection", ({ peerconnection }) => wireRemoteTrack(peerconnection));
+    if (s.connection) wireRemoteTrack(s.connection);
+    if (this.direction === "outbound" && this.#deps.iceGatheringCapMs) {
+      this.#cancelIceCap = capIceGathering(s, this.#deps.iceGatheringCapMs);
+    }
+    s.on("accepted", () => this.#onAccepted());
+    s.on("ended", (e) => this.#end(mapEndReason(e), e.cause));
+    s.on("failed", (e) => this.#end(mapFailReason(e), e.cause));
+    s.on("hold", ({ originator }) => this.#fire({ type: "held", originator }));
+    s.on("unhold", ({ originator }) => this.#fire({ type: "unheld", originator }));
+  }
+  /**
+   * The call is live. Nothing to swap: JsSIP opened the real microphone when the session was created,
+   * so the far end has had our actual audio from the first packet.
+   *
+   * There used to be a silent-mic dance here — place the call with a synthetic AudioContext track,
+   * swap the real mic in on accept — so a Bluetooth headset stayed in A2DP while the phone rang. It
+   * cost more than it bought: with no active capture, Firefox restricts ICE gathering and the offer
+   * goes out with no candidates at all, which no STUN or TURN server can fix.
+   */
+  #onAccepted() {
+    this.#fire({ type: "accepted" });
+  }
+  // ── Commands ───────────────────────────────────────────────────────────────
+  async answer() {
+    const deviceId = this.#deps.getInputDeviceId?.() ?? null;
+    this.#session.answer({
+      mediaConstraints: buildAudioConstraints(deviceId),
+      pcConfig: this.#deps.pcConfig ?? PC_CONFIG
+    });
+  }
+  /**
+   * Live-swap the outgoing microphone track — `CallEngine.setInputDevice` on a call that is already
+   * connected. Never touches the FIRST call's capture: that one is JsSIP's own `getUserMedia`, opened
+   * inside `answer()`/`ua.call()` (see `#onAccepted`'s comment on why that stays that way). This is
+   * only for a device chosen AFTER the call is already live.
+   *
+   * `RTCRtpSender.replaceTrack` rather than a fresh `answer()`/re-INVITE: it needs no SDP
+   * renegotiation and the far end never sees an interruption — exactly the mechanism real softphones
+   * use for "switch mic mid-call."
+   */
+  async swapInputDevice(deviceId) {
+    const pc = this.#session.connection;
+    if (!pc || this.#ended) return;
+    const sender = pc.getSenders().find((s) => s.track?.kind === "audio");
+    if (!sender) return;
+    let stream;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia(buildAudioConstraints(deviceId));
+    } catch {
+      return;
+    }
+    if (this.#ended) {
+      for (const track2 of stream.getTracks()) track2.stop();
+      return;
+    }
+    const [track] = stream.getAudioTracks();
+    if (!track) return;
+    await sender.replaceTrack(track);
+    for (const oldTrack of this.#swappedStream?.getTracks() ?? []) oldTrack.stop();
+    this.#swappedStream = stream;
+  }
+  async reject() {
+    this.#deps.onReject?.();
+    this.#session.terminate({ status_code: 486, reason_phrase: "Busy Here" });
+  }
+  async hangup() {
+    this.#session.terminate();
+  }
+  mute(muted) {
+    if (muted) this.#session.mute({ audio: true });
+    else this.#session.unmute({ audio: true });
+  }
+  async hold() {
+    this.#session.hold();
+  }
+  async unhold() {
+    this.#session.unhold();
+  }
+  sendDigits(digits) {
+    this.#session.sendDTMF(digits);
+  }
+  async transfer(target) {
+    this.#session.refer(this.#deps.buildTarget(target));
+  }
+  async startConsult(target) {
+    return this.#deps.placeConsult(target);
+  }
+  async completeTransfer(consult) {
+    const consultSession = consult.session;
+    this.#session.refer(consultSession.remote_identity.uri.toString(), { replaces: consultSession });
+  }
+  // ── internals ──────────────────────────────────────────────────────────────
+  #end(reason, cause) {
+    if (this.#ended) return;
+    this.#ended = true;
+    this.#cancelIceCap?.();
+    for (const track of this.#swappedStream?.getTracks() ?? []) track.stop();
+    this.#swappedStream = null;
+    this.#fire({ type: "ended", reason, cause });
+    this.#listeners.clear();
+  }
+  #fire(event) {
+    if (this.#ended && event.type !== "ended") return;
+    for (const listener of [...this.#listeners]) listener(event);
+  }
+};
+
+// src/core/errors.ts
+var ERROR_CATALOGUE = {
+  // ── Engine lifecycle ────────────────────────────────────────────────────────
+  "engine/duplicate-instance": {
+    fatal: true,
+    message: "A Softphone instance is already running on this page.",
+    solution: "Construct one Softphone and share it. React StrictMode double-mounts in development \u2014 hold the instance above the tree, or in a ref, and call destroy() on unmount."
+  },
+  "engine/not-started": {
+    fatal: false,
+    message: "The softphone has not been started.",
+    solution: "Await softphone.start() before placing or answering a call."
+  },
+  "engine/destroyed": {
+    fatal: true,
+    message: "This Softphone has been destroyed and cannot be reused.",
+    solution: "Construct a new Softphone."
+  },
+  // ── Auth ────────────────────────────────────────────────────────────────────
+  "auth/token-fetch-failed": {
+    fatal: true,
+    message: "Could not obtain a voice token from the token endpoint.",
+    solution: "Check that the token endpoint is reachable and that the headers callback returns a valid host-app session token."
+  },
+  "auth/token-rejected": {
+    fatal: true,
+    message: "The voice token was rejected.",
+    solution: "The token is expired, malformed, or scoped to a different organization. Mint a fresh one."
+  },
+  // ── Media ───────────────────────────────────────────────────────────────────
+  /*
+    NONE of the four codes below are ever actually raised via `createError` — nothing in the SDK
+    constructs a `SoftphoneError` with these codes today. Deleting them was the other option
+    (SPEC discussion); they stay, commented, because the taxonomy and Spanish copy (`error-text.ts`)
+    are worth keeping intact for whenever a real caller wants them, and a `SoftphoneErrorCode` union
+    is a cheap thing to keep honest with a comment, expensive to keep churning as a breaking change.
+  */
+  "media/permission-denied": {
+    fatal: true,
+    message: "Microphone permission was denied.",
+    solution: "The permission prompt names the TOP-LEVEL origin. Ask for it from a user gesture, and re-request via the browser UI if previously blocked."
+    // NEVER RAISED. `MicPermissionGate` (ui/permission/) handles this condition today — it predates
+    // this catalogue and has BETTER, browser-specific unblock instructions than a generic gate could
+    // show. It does not import this catalogue at all; the two are unconnected on purpose.
+  },
+  "media/no-input-device": {
+    fatal: true,
+    message: "No microphone is available.",
+    solution: "Ask the user to connect a microphone, then retry."
+    // NEVER RAISED — same reason as `media/permission-denied` above: `MicPermissionGate` already
+    // owns this.
+  },
+  "media/webrtc-unsupported": {
+    fatal: true,
+    message: "This browser does not expose the WebRTC APIs.",
+    solution: "Usually a privacy extension (uBlock Origin Extra, WebRTC Leak Prevent) disabling RTCPeerConnection \u2014 Twilio documents the same. Ask the user to disable it for this origin."
+    // NEVER RAISED — same reason again: `MicPermissionGate` already owns this.
+  },
+  "media/playback-blocked": {
+    fatal: false,
+    message: "The browser blocked audio playback (autoplay policy).",
+    solution: "Call softphone.startAudio() from a click handler. Until then the user cannot hear the caller, and an INCOMING RINGTONE WILL BE SILENT \u2014 this is how calls get missed."
+    /*
+      NEVER RAISED — different reason from the other three. This is not superseded by an existing
+      UI; the feature it describes (autoplay-recovery) is simply not built yet. `Softphone.canPlayAudio`
+      / `startAudio()` (core/softphone.ts) are Phase 2 and currently no-op stubs — `canPlayAudio`
+      always reports `true`. This is where that future work would report the block once it exists.
+    */
+  },
+  // ── Network / signalling ────────────────────────────────────────────────────
+  "net/registration-failed": {
+    fatal: true,
+    message: "SIP registration failed.",
+    solution: "Usually a stale credential. The engine refreshes and retries; if it persists, the extension may not exist."
+  },
+  "net/transport-failed": {
+    fatal: true,
+    message: "The signalling transport could not be established.",
+    solution: "Check the CSP connect-src directive and any corporate proxy blocking WSS."
+  },
+  "net/ice-failed": {
+    fatal: false,
+    message: "Media connectivity was lost; attempting an ICE restart.",
+    solution: 'Usually a network handoff (wifi \u2192 cellular). The engine recovers on its own; surface a "reconnecting" banner rather than ending the call.'
+    /*
+      NEVER RAISED. The "reconnecting" banner this `solution` describes already exists — CallScreen
+      shows "Reconectando…" directly off the call's own `reconnecting` STATE (`STATUS_LABEL` in
+      views/CallScreen.tsx), which the SIP engine drives without going through the error channel at
+      all. Raising this too would say the same fact twice through two different mechanisms. It would
+      only earn its keep for host-side OBSERVABILITY — counting ICE restarts independently of the UI
+      — which nobody has asked for yet.
+    */
+  },
+  // ── Call ────────────────────────────────────────────────────────────────────
+  "call/not-answerable": {
+    fatal: false,
+    message: "This call cannot be answered in its current state.",
+    solution: "Only a call in `ringing` may be answered. Check call.state first."
+  },
+  "call/busy": {
+    fatal: false,
+    message: "The remote party is busy.",
+    solution: 'Nothing to fix. Note SIP 486 is also what most endpoints send for a manual decline, so do not label this "busy" alone in your UI \u2014 it is equally often "did not answer".'
+  },
+  "call/no-answer": {
+    fatal: false,
+    message: "The remote party did not answer.",
+    solution: "Nothing to fix. Surface it to the user."
+  },
+  "call/rejected": {
+    fatal: false,
+    message: "The remote party rejected the call.",
+    solution: "Nothing to fix. Surface it to the user."
+  },
+  "call/missed": {
+    fatal: false,
+    message: "An incoming call was cancelled before it was answered.",
+    solution: "Nothing to fix \u2014 the caller gave up while it rang. Surface it, and log it as a missed call."
+  },
+  "call/failed": {
+    fatal: false,
+    message: "The call could not be completed.",
+    solution: "The catch-all for a call that never connected \u2014 a bad number, a rejected offer, a media failure. `cause` carries the underlying SIP cause. Nothing is fatal: the phone still works."
+  },
+  "call/transfer-failed": {
+    fatal: false,
+    message: "The transfer could not be completed.",
+    solution: "The original call is still up. Let the user retry or resume."
+  },
+  "call/unsupported": {
+    fatal: false,
+    message: "The provider does not support this operation.",
+    solution: "Guard the UI on the operation before offering it."
+  },
+  // ── Provider ────────────────────────────────────────────────────────────────
+  "provider/provision-failed": {
+    fatal: true,
+    message: "The provider could not issue SIP credentials.",
+    solution: "The backend reached the carrier but got no usable credential. Check the org has a SIP extension provisioned."
+  }
+};
+var CatalogueError = class extends Error {
+  fatal;
+  code;
+  solution;
+  constructor(code, cause) {
+    const spec = ERROR_CATALOGUE[code];
+    super(spec.message, cause === void 0 ? void 0 : { cause });
+    this.name = "SoftphoneError";
+    this.code = code;
+    this.fatal = spec.fatal;
+    this.solution = spec.solution;
+  }
+};
+function isSoftphoneError(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate.fatal === "boolean" && candidate.code in ERROR_CATALOGUE;
+}
+function createError(code, cause) {
+  return new CatalogueError(code, cause);
+}
+
+// src/transports/sip/ua.ts
+var DEFAULT_ICE_CAP_MS = 3e3;
+var REGISTER_EXPIRES = 580;
+var SIGNAL_REFRESH_DEBOUNCE_MS = 3e4;
+var ERROR_DEBOUNCE_MS = 3e4;
+var CALL_END_CODES = {
+  busy: "call/busy",
+  "no-answer": "call/no-answer",
+  rejected: "call/rejected",
+  failed: "call/failed"
+};
+function domainOf(credentials) {
+  const at = credentials.uri.lastIndexOf("@");
+  return at === -1 ? "" : credentials.uri.slice(at + 1);
+}
+var callSeq = 0;
+var nextCallId = () => `sip-${++callSeq}`;
+var SipCallEngine = class {
+  constructor(provider, factory, options = {}) {
+    this.provider = provider;
+    this.factory = factory;
+    this.now = options.now ?? Date.now;
+  }
+  provider;
+  factory;
+  #state = "stopped";
+  #ua = null;
+  /** In-flight `#createUA()`. THE concurrency guard — see `#ensureUA`. */
+  #uaInFlight = null;
+  #domain = "";
+  #activeCall = 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;
+  #incomingListeners = /* @__PURE__ */ new Set();
+  #stateListeners = /* @__PURE__ */ new Set();
+  #errorListeners = /* @__PURE__ */ new Set();
+  #signalUnsub = null;
+  #signalConnectionUnsub = null;
+  #noInviteTimer;
+  #rejectGuardUntil = 0;
+  #signalRefreshAfter = 0;
+  #errorSentAfter = /* @__PURE__ */ new Map();
+  now;
+  #resolvedFactory = null;
+  async #resolveFactory() {
+    if (this.#resolvedFactory) return this.#resolvedFactory;
+    this.#resolvedFactory = typeof this.factory === "function" ? await this.factory() : this.factory;
+    return this.#resolvedFactory;
+  }
+  get state() {
+    return this.#state;
+  }
+  onIncoming(listener) {
+    this.#incomingListeners.add(listener);
+    return () => this.#incomingListeners.delete(listener);
+  }
+  onStateChange(listener) {
+    this.#stateListeners.add(listener);
+    return () => this.#stateListeners.delete(listener);
+  }
+  onError(listener) {
+    this.#errorListeners.add(listener);
+    return () => this.#errorListeners.delete(listener);
+  }
+  /**
+   * Switch the microphone: stored for every FUTURE leg's `mediaConstraints`, and — if a call is live
+   * right now — pushed to it immediately via `SipEngineCall.swapInputDevice` (SPEC §7 Phase 2, device
+   * management). `null` resets to the browser's own default device.
+   */
+  async setInputDevice(deviceId) {
+    this.#inputDeviceId = deviceId;
+    await this.#activeCall?.swapInputDevice(deviceId);
+  }
+  /**
+   * Report a failure, at most once per code per `ERROR_DEBOUNCE_MS`.
+   *
+   * A failing registrar retries, and one emission per attempt would flood a host's logging and make
+   * whatever the widget shows flicker. Debounced per CODE rather than globally, so a transport
+   * failure is never swallowed because a registration failure happened to precede it.
+   */
+  #reportError(code, cause) {
+    this.#emitError(createError(code, cause));
+  }
+  /**
+   * Emit, debouncing FATAL codes only.
+   *
+   * A failing registrar retries, and one emission per attempt would flood a host's logging and make
+   * whatever the widget shows flicker — so the same fatal code is reported at most once per window,
+   * per CODE, so a transport failure is never swallowed because a registration failure preceded it.
+   *
+   * Non-fatal codes are never debounced: they describe one call each, and two busy tones in a row are
+   * two facts, not a repeated one.
+   */
+  #emitError(error) {
+    if (error.fatal) {
+      const now = this.now();
+      if (now < (this.#errorSentAfter.get(error.code) ?? 0)) return;
+      this.#errorSentAfter.set(error.code, now + ERROR_DEBOUNCE_MS);
+    }
+    for (const listener of [...this.#errorListeners]) listener(error);
+  }
+  async start() {
+    this.#setState("starting");
+    if (this.provider.registrationMode === "persistent") {
+      await this.#ensureUA();
+      this.#setState("online");
+    } else {
+      const signal = this.provider.incomingSignal;
+      if (signal) {
+        await signal.connect();
+        this.#signalUnsub = signal.onSignal(() => void this.#onIncomingSignal());
+        this.#signalConnectionUnsub = signal.onConnectionChange?.(
+          (connected) => this.#setState(connected ? "online" : "offline")
+        ) ?? null;
+      }
+      this.#setState(signal?.onConnectionChange ? signal.connected ? "online" : "offline" : "online");
+    }
+  }
+  async stop() {
+    this.#clearNoInviteTimer();
+    this.#signalUnsub?.();
+    this.#signalUnsub = null;
+    this.#signalConnectionUnsub?.();
+    this.#signalConnectionUnsub = null;
+    this.provider.incomingSignal?.disconnect();
+    this.#teardownUA();
+    this.#setState("stopped");
+  }
+  async placeCall(destination, _options) {
+    const ua = await this.#ensureUA();
+    const session = await this.#callWhenRegistered(ua, this.#buildTarget(destination));
+    return this.#wrapCall(session);
+  }
+  // ── incoming (on-demand: push → register → INVITE) ────────────────────────
+  async #onIncomingSignal() {
+    if (this.now() < this.#rejectGuardUntil) return;
+    if (this.#activeCall) return;
+    try {
+      await this.#ensureUA();
+      this.#armNoInviteTeardown();
+    } catch {
+      this.#teardownUA();
+    }
+  }
+  #armNoInviteTeardown() {
+    const ms = this.provider.quirks?.noInviteTeardownMs;
+    if (!ms) return;
+    this.#clearNoInviteTimer();
+    this.#noInviteTimer = setTimeout(() => {
+      if (!this.#activeCall) this.#teardownUA();
+    }, ms);
+  }
+  /**
+   * Rebuild the incoming-signal channel with fresh credentials, after a registration failure.
+   *
+   * Registration fails when the credentials behind it have gone stale — and for Zadarma those come
+   * from the same WebRTC key the push socket is holding. Tearing down the UA alone leaves that stale
+   * key in place, so every subsequent attempt fails the same way and the phone is dead until the page
+   * is reloaded. Reconnecting re-fetches the key. The legacy hook did exactly this from both of its
+   * `registrationFailed` handlers.
+   *
+   * Debounced, which the legacy was not: a provider failing every attempt would otherwise become a
+   * tight loop against our backend and theirs.
+   */
+  async #refreshSignal() {
+    const signal = this.provider.incomingSignal;
+    if (!signal) return;
+    if (this.now() < this.#signalRefreshAfter) return;
+    this.#signalRefreshAfter = this.now() + SIGNAL_REFRESH_DEBOUNCE_MS;
+    try {
+      signal.disconnect();
+      await signal.connect();
+    } catch {
+    }
+  }
+  #clearNoInviteTimer() {
+    if (this.#noInviteTimer) clearTimeout(this.#noInviteTimer);
+    this.#noInviteTimer = void 0;
+  }
+  #onNewSession(session, originator) {
+    if (originator !== "remote") return;
+    this.#clearNoInviteTimer();
+    if (this.#activeCall || this.now() < this.#rejectGuardUntil) {
+      session.terminate({ status_code: 486, reason_phrase: "Busy Here" });
+      return;
+    }
+    const call = this.#wrapCall(session);
+    for (const listener of [...this.#incomingListeners]) listener(call);
+  }
+  // ── UA lifecycle ───────────────────────────────────────────────────────────
+  /**
+   * The single UA, created at most once — even under concurrent callers.
+   *
+   * **The `#ua` check alone is not a guard**, because everything after it awaits: two callers both
+   * see `null`, both `provision()`, both build a UA, and both REGISTER the same extension. Zadarma
+   * rejects the loser, `registrationFailed` tears down, and the survivor may be the one that was
+   * torn down. The visible symptom is two `get_webphone_data.php` calls at startup and a phone that
+   * never registers.
+   *
+   * Concurrency is the normal case here, not an edge: the push socket can signal twice in a
+   * heartbeat (SPEC §3.3 — a push is not an INVITE; it fires for transfers, retries and hangups),
+   * and `placeCall` can land on top of one. So the in-flight promise IS the guard.
+   */
+  async #ensureUA() {
+    if (this.#ua) return this.#ua;
+    this.#uaInFlight ??= this.#createUA().finally(() => {
+      this.#uaInFlight = null;
+    });
+    return this.#uaInFlight;
+  }
+  async #createUA() {
+    const factory = await this.#resolveFactory();
+    let credentials;
+    try {
+      credentials = await this.provider.provision();
+    } catch (cause) {
+      if (isSoftphoneError(cause)) this.#emitError(cause);
+      else this.#reportError("provider/provision-failed", cause);
+      throw cause;
+    }
+    this.#domain = domainOf(credentials);
+    const config = this.#uaConfig(credentials, factory);
+    const ua = factory.createUA(config);
+    ua.on("newRTCSession", ({ session, originator }) => this.#onNewSession(session, originator));
+    ua.on("disconnected", ({ error }) => {
+      if (!error) return;
+      this.#setState("reconnecting");
+      this.#reportError("net/transport-failed", error);
+    });
+    ua.on("connected", () => this.#setState("online"));
+    ua.on("registrationFailed", (e) => {
+      const detail = e;
+      this.#reportError("net/registration-failed", {
+        cause: detail?.cause,
+        status: detail?.response?.status_code,
+        domain: this.#domain,
+        hint: "A bare 401 with no auth challenge usually means the registrar is in the wrong datacenter (SPEC \xA73.1)."
+      });
+      this.#teardownUA();
+      void this.#refreshSignal();
+    });
+    this.#ua = ua;
+    ua.start();
+    return ua;
+  }
+  #uaConfig(credentials, factory) {
+    return {
+      sockets: [factory.createWebSocket(credentials.wsUrl)],
+      uri: credentials.uri,
+      authorization_user: credentials.authUser,
+      password: credentials.password,
+      register: true,
+      register_expires: REGISTER_EXPIRES,
+      connection_recovery_min_interval: 2,
+      connection_recovery_max_interval: 30,
+      // Generic — NOT a provider brand string. If a provider ever requires a specific UA header it
+      // belongs in the provider, not hard-coded here.
+      // NOT ours to choose: Zadarma refuses to register any client whose User-Agent it does not
+      // recognise (see ProviderQuirks.userAgent). The provider decides; the engine just sends it.
+      user_agent: this.provider.quirks?.userAgent ?? "Coventia Softphone"
+    };
+  }
+  #teardownUA() {
+    this.#uaInFlight = null;
+    if (!this.#ua) return;
+    try {
+      this.#ua.terminateSessions({ status_code: 487 });
+      this.#ua.stop();
+    } catch {
+    }
+    this.#ua = null;
+    this.#activeCall = null;
+  }
+  /** Place a call once the UA is registered (its 200 OK for REGISTER has arrived). */
+  /**
+   * **No `mediaStream`** — JsSIP calls `getUserMedia` itself, which is what opens a real capture.
+   *
+   * That is load-bearing, not incidental. Firefox restricts ICE gathering on a page with no active
+   * capture: it discards every address but the default route's ("Ignoring addr from interface other
+   * than …" in about:webrtc) and can end up gathering NOTHING, so the INVITE goes out with
+   * `c=IN IP4 0.0.0.0` and no candidates at all. No STUN or TURN server can rescue an offer that
+   * contains no candidates. The legacy hook passed `mediaConstraints` and nothing else, for what
+   * turns out to be a very good reason.
+   */
+  #callWhenRegistered(ua, target) {
+    const options = { mediaConstraints: buildAudioConstraints(this.#inputDeviceId), pcConfig: PC_CONFIG };
+    if (ua.isRegistered()) return Promise.resolve(ua.call(target, options));
+    return new Promise((resolve) => {
+      ua.on("registered", () => resolve(ua.call(target, options)));
+    });
+  }
+  #wrapCall(session) {
+    const call = new SipEngineCall(session, {
+      id: nextCallId(),
+      buildTarget: (t) => this.#buildTarget(t),
+      placeConsult: (t) => this.#placeConsult(t),
+      // The guard is tied to the reject ACTION, not to `ended` — a normal hangup must not arm it.
+      onReject: () => this.#startRejectGuard(),
+      iceGatheringCapMs: this.provider.quirks?.iceGatheringCapMs ?? DEFAULT_ICE_CAP_MS,
+      // Inbound answers open their own peer connection, so they need the same ICE servers the
+      // outbound leg got. Missing here, an ANSWERED call is the one that fails — the half nobody
+      // tests until a real person picks up.
+      pcConfig: PC_CONFIG,
+      // Read fresh at answer() time, not captured now — a device chosen while the phone is still
+      // ringing must still apply once it is picked up.
+      getInputDeviceId: () => this.#inputDeviceId
+    });
+    this.#activeCall = call;
+    call.onEvent((event) => {
+      if (event.type === "ended") {
+        const missed = call.direction === "inbound" && event.cause === "Canceled";
+        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();
+      }
+    });
+    return call;
+  }
+  async #placeConsult(target) {
+    const ua = await this.#ensureUA();
+    const consultSession = ua.call(this.#buildTarget(target), {
+      mediaConstraints: buildAudioConstraints(this.#inputDeviceId),
+      pcConfig: PC_CONFIG
+    });
+    return 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
+    });
+  }
+  #startRejectGuard() {
+    const ms = this.provider.quirks?.rejectGuardMs;
+    if (ms) this.#rejectGuardUntil = this.now() + ms;
+  }
+  #buildTarget(target) {
+    return target.includes("@") ? target : `sip:${target}@${this.#domain}`;
+  }
+  #setState(state) {
+    if (state === this.#state) return;
+    this.#state = state;
+    for (const listener of [...this.#stateListeners]) listener(state);
+  }
+};
+
+// src/transports/sip/real-factory.ts
+var cached = null;
+async function loadJsSipFactory() {
+  if (cached) return cached;
+  const mod = await import('jssip');
+  const JsSIP = mod.default ?? mod;
+  if (!JsSIP?.UA || !JsSIP?.WebSocketInterface) {
+    throw new Error("jssip: unexpected module shape (no UA / WebSocketInterface)");
+  }
+  cached = {
+    createWebSocket: (wsUrl) => new JsSIP.WebSocketInterface(wsUrl),
+    createUA: (config) => new JsSIP.UA(config)
+  };
+  return cached;
+}
+
+// src/transports/providers/zadarma.ts
+var PING = { localMs: 3e4, globalMs: 6e4 };
+var KEY_REFRESH_BUFFER_MS = 2 * 60 * 60 * 1e3;
+var 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
+  // hook carried this string; the port dropped it, and registration failed for exactly that reason.
+  userAgent: "Zadarma webRTC",
+  // Zadarma re-rings a declined call for ~30 s (return_timeout). Swallow those (§3.4).
+  rejectGuardMs: 35e3,
+  // A push is not an INVITE (§3.3). If none arrives, tear the fresh UA down.
+  noInviteTeardownMs: 5e3,
+  // A ceiling on ICE gathering, not a target: JsSIP sends as soon as gathering completes. 3 s leaves
+  // room for a TURN allocation (whose relay candidates arrive last) while still bounding the ~40 s
+  // Chrome can spend against an unreachable server. See `capIceGathering`.
+  iceGatheringCapMs: 3e3
+};
+function buildPushUrl(key, sip) {
+  const params = new URLSearchParams({ key, integrationType: "site", sipId: sip });
+  return `wss://ws.zadarma.com/webrtc_pushes?${params.toString()}`;
+}
+var ZadarmaPushSignal = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  #socket = null;
+  #connected = false;
+  #pingTimers = [];
+  #refreshTimer;
+  #unwatchBackground;
+  #closed = false;
+  #listeners = /* @__PURE__ */ new Set();
+  #connectionListeners = /* @__PURE__ */ new Set();
+  async connect() {
+    if (this.#socket) return;
+    this.#closed = false;
+    this.#unwatchBackground ??= this.deps.watchBackgroundReconnect?.(() => void this.#reopen());
+    await this.#open();
+  }
+  async #open() {
+    const { key, sip, keyExpiresAt } = await this.deps.fetchKey();
+    if (this.#closed) return;
+    const socket = this.deps.createPushSocket(buildPushUrl(key, sip));
+    this.#socket = socket;
+    socket.on("connect", () => {
+      this.#setConnected(true);
+      this.#startPings(socket);
+    });
+    socket.on("update", () => this.#emit());
+    socket.on("disconnect", () => {
+      this.#stopPings();
+      this.#setConnected(false);
+    });
+    socket.on("connect_error", () => {
+      this.#stopPings();
+      this.#setConnected(false);
+    });
+    this.#armRefresh(keyExpiresAt);
+  }
+  /**
+   * Presence pings — **the reason an idle tab keeps receiving calls**.
+   *
+   * Zadarma's gateway decides whether the extension is online, and it decides from these. Without
+   * them the socket goes quiet, Zadarma marks the extension offline within minutes, and INVITEs stop
+   * being routed — with no error anywhere, because nothing failed. The only visible symptom is that
+   * the phone silently stops ringing until the page is reloaded.
+   *
+   * The names and intervals are Zadarma's, taken from the CRM hook that ran this in production for
+   * years. They are not ours to tune.
+   */
+  #startPings(socket) {
+    this.#stopPings();
+    this.#pingTimers = [
+      setInterval(() => socket.emit("localPing", {}), PING.localMs),
+      setInterval(() => socket.emit("globalPing", {}), PING.globalMs)
+    ];
+  }
+  #stopPings() {
+    for (const t of this.#pingTimers) clearInterval(t);
+    this.#pingTimers = [];
+  }
+  /**
+   * Rebuild the socket before the WebRTC key expires.
+   *
+   * The key is baked into the socket URL, so socket.io's own reconnection re-presents whatever it was
+   * given at construction. A tab left open past the key's 72 h lifetime would reconnect forever with
+   * a dead credential. Absolute, from the backend's `key_expires_at`, so it targets the real expiry
+   * rather than restarting a countdown on every reconnect.
+   */
+  #armRefresh(keyExpiresAt) {
+    clearTimeout(this.#refreshTimer);
+    if (!keyExpiresAt) return;
+    const ms = new Date(keyExpiresAt).getTime() - Date.now() - KEY_REFRESH_BUFFER_MS;
+    if (!Number.isFinite(ms) || ms <= 0) return;
+    this.#refreshTimer = setTimeout(() => void this.#reopen(), ms);
+  }
+  async #reopen() {
+    if (this.#closed) return;
+    this.#stopPings();
+    this.#socket?.close();
+    this.#socket = null;
+    this.#setConnected(false);
+    try {
+      await this.#open();
+    } catch {
+    }
+  }
+  disconnect() {
+    this.#closed = true;
+    this.#stopPings();
+    clearTimeout(this.#refreshTimer);
+    this.#refreshTimer = void 0;
+    this.#unwatchBackground?.();
+    this.#unwatchBackground = void 0;
+    this.#socket?.close();
+    this.#socket = null;
+    this.#setConnected(false);
+  }
+  onSignal(listener) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+  onConnectionChange(listener) {
+    this.#connectionListeners.add(listener);
+    return () => this.#connectionListeners.delete(listener);
+  }
+  get connected() {
+    return this.#connected;
+  }
+  #setConnected(connected) {
+    if (this.#connected === connected) return;
+    this.#connected = connected;
+    for (const listener of [...this.#connectionListeners]) listener(connected);
+  }
+  #emit() {
+    for (const listener of [...this.#listeners]) listener();
+  }
+};
+var ZadarmaProvider = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.incomingSignal = new ZadarmaPushSignal(deps);
+  }
+  deps;
+  name = "zadarma";
+  // Zadarma's PBX ignores a standing registration — it routes INVITEs only to a UA that registered
+  // in response to a push (SPEC §3.2). Hence on-demand.
+  registrationMode = "on-demand";
+  quirks = ZADARMA_QUIRKS;
+  incomingSignal;
+  /**
+   * Per-registration credentialing: fetch a scoped key, then exchange it in the browser for
+   * ephemeral SIP creds. The key fetch is cheap and backend-cached; doing it here (rather than
+   * sharing state with the push signal) keeps the two paths independent.
+   */
+  async provision() {
+    const { key, sip } = await this.deps.fetchKey();
+    const { pass, domain } = await this.deps.exchangeWebphoneData(key, sip);
+    return {
+      uri: `sip:${sip}@${domain}`,
+      authUser: sip,
+      password: pass,
+      wsUrl: `wss://${domain}:4443`
+    };
+  }
+};
+
+// src/core/token-cache.ts
+var SKEW_MS = 6e4;
+var entries = /* @__PURE__ */ new WeakMap();
+var wrappers = /* @__PURE__ */ new WeakMap();
+var isFresh = (token) => token !== null && token.expiresAt.getTime() - Date.now() > SKEW_MS;
+function cachedTokenSource(inner) {
+  const existing = wrappers.get(inner);
+  if (existing) return existing;
+  const entry = { token: null, inflight: null };
+  const wrapper = {
+    async getToken(signal) {
+      if (isFresh(entry.token)) return entry.token;
+      if (entry.inflight !== null) return entry.inflight;
+      entry.inflight = (async () => {
+        try {
+          const token = await inner.getToken(signal);
+          entry.token = token;
+          return token;
+        } finally {
+          entry.inflight = null;
+        }
+      })();
+      return entry.inflight;
+    }
+  };
+  entries.set(inner, entry);
+  entries.set(wrapper, entry);
+  wrappers.set(inner, wrapper);
+  return wrapper;
+}
+function invalidateToken(source) {
+  const entry = entries.get(source);
+  if (!entry) return;
+  entry.token = null;
+}
+
+// src/transports/providers/zadarma-browser.ts
+var UnauthorizedKeyError = class extends Error {
+};
+function makeFetchKey(config) {
+  const attempt = async () => {
+    let token;
+    try {
+      ({ token } = await config.tokenSource.getToken());
+    } catch (cause) {
+      throw createError("auth/token-fetch-failed", cause);
+    }
+    const qs = config.organizationId ? `?organization_id=${encodeURIComponent(config.organizationId)}` : "";
+    const res = await fetch(`${config.apiBase}/phone/webrtc/key${qs}`, {
+      headers: { Authorization: token }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => null);
+      const message = body?.message ?? `webrtc/key HTTP ${res.status}`;
+      throw res.status === 401 ? new UnauthorizedKeyError(message) : new Error(message);
+    }
+    const data = await res.json();
+    return {
+      key: data.key,
+      sip: data.sip,
+      ...data.key_expires_at ? { keyExpiresAt: data.key_expires_at } : {}
+    };
+  };
+  return async () => {
+    try {
+      return await attempt();
+    } catch (error) {
+      if (!(error instanceof UnauthorizedKeyError)) throw error;
+      invalidateToken(config.tokenSource);
+      try {
+        return await attempt();
+      } catch (retryError) {
+        if (retryError instanceof UnauthorizedKeyError) {
+          throw createError("auth/token-rejected", retryError);
+        }
+        throw retryError;
+      }
+    }
+  };
+}
+async function exchangeWebphoneData(key, sip, timeoutMs = 1e4) {
+  const params = new URLSearchParams({
+    // Still sent: the endpoint wraps its response either way, and naming the callback keeps the
+    // wrapper predictable rather than relying on their default.
+    jsonpCallback: "cv",
+    integrationType: "site",
+    key,
+    sipId: sip
+  });
+  let res;
+  try {
+    res = await fetch(
+      `https://api.zadarma.com/sys/webrtc/get_webphone_data.php?${params.toString()}`,
+      { signal: AbortSignal.timeout(timeoutMs) }
+    );
+  } catch (cause) {
+    const timedOut = cause instanceof DOMException && cause.name === "TimeoutError";
+    throw new Error(timedOut ? "get_webphone_data timed out" : "get_webphone_data network error", {
+      cause
+    });
+  }
+  if (!res.ok) throw new Error(`get_webphone_data HTTP ${res.status}`);
+  const data = parseJsonp(await res.text());
+  if (!data || data.error || !data.pass || !data.domain) {
+    throw new Error(data?.error?.content ?? "get_webphone_data: missing SIP credentials");
+  }
+  return { pass: data.pass, domain: data.domain };
+}
+function parseJsonp(text) {
+  const open = text.indexOf("(");
+  const close = text.lastIndexOf(")");
+  const body = open !== -1 && close > open ? text.slice(open + 1, close) : text;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+function createPushSocket(url) {
+  const handlers = /* @__PURE__ */ new Map();
+  let client = null;
+  let closed = false;
+  void (async () => {
+    const mod = await import('socket.io-client-v2');
+    if (closed) return;
+    const connect = mod.default ?? mod.io;
+    if (!connect) throw new Error("socket.io-client-v2: no connect export");
+    const c = connect(url, {
+      transports: ["websocket"],
+      reconnection: true,
+      // The push socket drops on a schedule under background-tab timer throttling, NOT from network
+      // flakiness — every reconnect observed succeeds on the first attempt (push-socket-reliability.md
+      // §2.3, §5.1). There is nothing to back off from on that first attempt, so waiting the old 10s
+      // before retrying was pure, uncontested exposure — an inbound call landing in that window is
+      // lost, unqueued (Zadarma's gateway speaks EIO3, no offline redelivery). `reconnectionDelayMax`
+      // stays as the ceiling for a genuinely down gateway, where backing off still matters.
+      reconnectionDelay: 300,
+      reconnectionDelayMax: 3e4
+    });
+    client = c;
+    for (const [event, cbs] of handlers) for (const cb of cbs) c.on(event, cb);
+  })();
+  return {
+    on(event, cb) {
+      const list = handlers.get(event) ?? [];
+      list.push(cb);
+      handlers.set(event, list);
+      client?.on(event, cb);
+    },
+    emit(event, payload) {
+      client?.emit(event, payload);
+    },
+    close() {
+      closed = true;
+      client?.close();
+    },
+    get connected() {
+      return client?.connected ?? false;
+    }
+  };
+}
+var BACKGROUND_RECONNECT_MS = 2e4;
+var HEARTBEAT_WORKER_SOURCE = `
+  let timer;
+  self.onmessage = (e) => {
+    if (e.data.type === 'start') timer = setInterval(() => self.postMessage('tick'), e.data.intervalMs);
+    else if (e.data.type === 'stop') { clearInterval(timer); timer = undefined; }
+  };
+`;
+function watchBackgroundReconnect(cb) {
+  if (typeof document === "undefined" || typeof Worker === "undefined") return () => {
+  };
+  let worker = null;
+  let blobUrl = null;
+  const ensureWorker = () => {
+    if (!worker) {
+      blobUrl = URL.createObjectURL(new Blob([HEARTBEAT_WORKER_SOURCE], { type: "application/javascript" }));
+      worker = new Worker(blobUrl);
+      worker.onmessage = (e) => {
+        if (e.data === "tick") cb();
+      };
+    }
+    return worker;
+  };
+  const onVisibilityChange = () => {
+    if (document.visibilityState === "hidden") {
+      ensureWorker().postMessage({ type: "start", intervalMs: BACKGROUND_RECONNECT_MS });
+    } else {
+      worker?.postMessage({ type: "stop" });
+    }
+  };
+  document.addEventListener("visibilitychange", onVisibilityChange);
+  if (document.visibilityState === "hidden") onVisibilityChange();
+  return () => {
+    document.removeEventListener("visibilitychange", onVisibilityChange);
+    worker?.postMessage({ type: "stop" });
+    worker?.terminate();
+    if (blobUrl) URL.revokeObjectURL(blobUrl);
+  };
+}
+function makeZadarmaBrowserDeps(config) {
+  return {
+    fetchKey: makeFetchKey(config),
+    exchangeWebphoneData: (key, sip) => exchangeWebphoneData(key, sip),
+    createPushSocket,
+    watchBackgroundReconnect
+  };
+}
+
+// src/transports/zadarma-engine.ts
+function createZadarmaEngine(config) {
+  const provider = new ZadarmaProvider(
+    makeZadarmaBrowserDeps({ ...config, tokenSource: cachedTokenSource(config.tokenSource) })
+  );
+  return new SipCallEngine(provider, loadJsSipFactory);
+}
+
+exports.ZADARMA_QUIRKS = ZADARMA_QUIRKS;
+exports.createZadarmaEngine = createZadarmaEngine;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map