@coventia/softphone 0.5.0 → 0.5.1

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { S as Softphone } from './softphone-JZvJdzU3.cjs';
-export { A as AudioDevices } from './softphone-JZvJdzU3.cjs';
-import { S as SoftphoneConfig, O as OutboundNumberRefusal } from './call-FqcvDg1t.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 LineClaim, j as LineLocation, k as LineState, l as LogLevel, N as NonFatalErrorCode, m as NonFatalSoftphoneError, n as OutboundNumber, o as OutboundNumberKind, p as OutboundNumberSettings, q as OutboundNumberState, r as OutboundNumbersSource, R as RemoteParty, s as RingtoneOption, t as RingtoneSettings, u as RingtoneSource, v as SoftphoneError, w as SoftphoneErrorCode, x as SoftphoneEvent, y as SoftphoneEventMap, z as SoftphoneState, T as TokenEndpointOptions, A as TokenSource, B as TypedEmitter, V as VoiceToken, D as canTransition, G as isFatal, J as isTerminal } from './call-FqcvDg1t.cjs';
+import { S as Softphone } from './softphone-DRoS0jJR.cjs';
+export { A as AudioDevices } from './softphone-DRoS0jJR.cjs';
+import { S as SoftphoneConfig, O as OutboundNumberRefusal } from './call-iGvr2ZnO.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 LineClaim, j as LineLocation, k as LineState, l as LogLevel, N as NonFatalErrorCode, m as NonFatalSoftphoneError, n as OutboundNumber, o as OutboundNumberKind, p as OutboundNumberSettings, q as OutboundNumberState, r as OutboundNumbersSource, R as RemoteParty, s as RingtoneOption, t as RingtoneSettings, u as RingtoneSource, v as SoftphoneError, w as SoftphoneErrorCode, x as SoftphoneEvent, y as SoftphoneEventMap, z as SoftphoneState, T as TokenEndpointOptions, A as TokenSource, B as TypedEmitter, V as VoiceToken, D as canTransition, G as isFatal, J as isTerminal } from './call-iGvr2ZnO.cjs';
 
 /**
  * Construct a softphone.
@@ -67,6 +67,6 @@ declare function isWebRtcSupported(): boolean;
  *   - `MockProvider` — lives at @coventia/softphone/testing, so it never lands in a production bundle.
  */
 
-declare const VERSION = "0.5.0";
+declare const VERSION = "0.5.1";
 
 export { OutboundNumberRefusal, type OutboundNumberRefusedError, Softphone, SoftphoneConfig, VERSION, createSoftphone, isBrowser, isOutboundNumberRefused, isWebRtcSupported };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { S as Softphone } from './softphone-By9sizlV.js';
-export { A as AudioDevices } from './softphone-By9sizlV.js';
-import { S as SoftphoneConfig, O as OutboundNumberRefusal } from './call-FqcvDg1t.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 LineClaim, j as LineLocation, k as LineState, l as LogLevel, N as NonFatalErrorCode, m as NonFatalSoftphoneError, n as OutboundNumber, o as OutboundNumberKind, p as OutboundNumberSettings, q as OutboundNumberState, r as OutboundNumbersSource, R as RemoteParty, s as RingtoneOption, t as RingtoneSettings, u as RingtoneSource, v as SoftphoneError, w as SoftphoneErrorCode, x as SoftphoneEvent, y as SoftphoneEventMap, z as SoftphoneState, T as TokenEndpointOptions, A as TokenSource, B as TypedEmitter, V as VoiceToken, D as canTransition, G as isFatal, J as isTerminal } from './call-FqcvDg1t.js';
+import { S as Softphone } from './softphone-D0ao5W4z.js';
+export { A as AudioDevices } from './softphone-D0ao5W4z.js';
+import { S as SoftphoneConfig, O as OutboundNumberRefusal } from './call-iGvr2ZnO.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 LineClaim, j as LineLocation, k as LineState, l as LogLevel, N as NonFatalErrorCode, m as NonFatalSoftphoneError, n as OutboundNumber, o as OutboundNumberKind, p as OutboundNumberSettings, q as OutboundNumberState, r as OutboundNumbersSource, R as RemoteParty, s as RingtoneOption, t as RingtoneSettings, u as RingtoneSource, v as SoftphoneError, w as SoftphoneErrorCode, x as SoftphoneEvent, y as SoftphoneEventMap, z as SoftphoneState, T as TokenEndpointOptions, A as TokenSource, B as TypedEmitter, V as VoiceToken, D as canTransition, G as isFatal, J as isTerminal } from './call-iGvr2ZnO.js';
 
 /**
  * Construct a softphone.
@@ -67,6 +67,6 @@ declare function isWebRtcSupported(): boolean;
  *   - `MockProvider` — lives at @coventia/softphone/testing, so it never lands in a production bundle.
  */
 
-declare const VERSION = "0.5.0";
+declare const VERSION = "0.5.1";
 
 export { OutboundNumberRefusal, type OutboundNumberRefusedError, Softphone, SoftphoneConfig, VERSION, createSoftphone, isBrowser, isOutboundNumberRefused, isWebRtcSupported };

package/dist/index.js

@@ -286,7 +286,7 @@ function coventiaBackend(config, tokenSource, fallbackBaseUrl) {
   }
   let pending = null;
   const load = () => {
-    pending ??= import('./sources-QL2LRZVH.js').then(
+    pending ??= import('./sources-LGFJG7W2.js').then(
       (m) => m.coventiaSources({ ...config, baseUrl, tokenSource })
     );
     return pending;
@@ -421,9 +421,55 @@ function startTransferWatch(params) {
   return stop;
 }
 
+// src/core/start-retry.ts
+var BACKOFF_BASE_MS = 1e3;
+var BACKOFF_MAX_MS = 3e4;
+function backoffDelayMs(attempt, random = Math.random) {
+  const capped = Math.min(BACKOFF_BASE_MS * 2 ** (Math.max(1, attempt) - 1), BACKOFF_MAX_MS);
+  return capped * random();
+}
+function isTransientStatus(status) {
+  return status === 0 || status === 408 || status === 425 || status === 429 || status >= 500;
+}
+function isNetworkFailure(error) {
+  const name = typeof error.name === "string" ? error.name : "";
+  return error instanceof TypeError || name === "AbortError" || name === "TimeoutError" || name === "NetworkError";
+}
+function transientStartFailure(error) {
+  let retryAfterMs = 0;
+  let viaTokenEndpoint = false;
+  let current = error;
+  for (let depth = 0; depth < 6 && current !== null && typeof current === "object"; depth += 1) {
+    const layer = current;
+    if (typeof layer.retryAfterMs === "number" && Number.isFinite(layer.retryAfterMs)) {
+      retryAfterMs = Math.max(retryAfterMs, layer.retryAfterMs);
+    }
+    if (typeof layer.status === "number") return isTransientStatus(layer.status) ? { retryAfterMs } : null;
+    if (isNetworkFailure(layer)) return { retryAfterMs };
+    if (isSoftphoneError(current)) {
+      if (layer.code === "auth/token-rejected") return null;
+      if (layer.code === "auth/token-fetch-failed") viaTokenEndpoint = true;
+    }
+    current = layer.cause;
+  }
+  return viaTokenEndpoint ? { retryAfterMs } : null;
+}
+function watchWake(wake) {
+  if (!isBrowser()) return () => {
+  };
+  const onOnline = () => wake();
+  const onVisibility = () => {
+    if (document.visibilityState === "visible") wake();
+  };
+  window.addEventListener("online", onOnline);
+  document.addEventListener("visibilitychange", onVisibility);
+  return () => {
+    window.removeEventListener("online", onOnline);
+    document.removeEventListener("visibilitychange", onVisibility);
+  };
+}
+
 // src/core/presence-socket.ts
-var RECONNECT_BASE_MS = 1e3;
-var RECONNECT_MAX_MS = 3e4;
 var NOOP_WATCH = { reportCallState: () => {
 }, claimLine: () => false, stop: () => {
 } };
@@ -435,6 +481,7 @@ function startPresenceSocket(params) {
     clientId,
     onLine,
     onClaimResult,
+    onOffer,
     onLineUnsupported,
     onConnectFailed,
     onDisconnect,
@@ -475,8 +522,7 @@ function startPresenceSocket(params) {
   const scheduleReconnect = () => {
     if (stopped) return;
     attempt += 1;
-    const capped = Math.min(RECONNECT_BASE_MS * 2 ** (attempt - 1), RECONNECT_MAX_MS);
-    const delay = capped * random();
+    const delay = backoffDelayMs(attempt, random);
     reconnectTimer = scheduleTimeout(() => void connect(), delay);
   };
   const connect = async () => {
@@ -511,6 +557,9 @@ function startPresenceSocket(params) {
         },
         onClaimResult: (result) => {
           if (!stopped) onClaimResult?.(result);
+        },
+        onOffer: (offer) => {
+          if (!stopped) onOffer?.(offer);
         }
       });
     } catch {
@@ -762,6 +811,17 @@ var SoftphoneImpl = class extends Emitter {
   #claim = null;
   /** Pending: what the server said about the line stops counting (`LINE_LAPSE_MS`). */
   #lineLapseTimer = null;
+  // ── The start retry (incoming-call-reliability.md §4.6) ─────────────────────────────────────────────────
+  // An engine start that failed for a passing reason (a 5xx, the network, a timeout) is attempted again on its
+  // own, with backoff, instead of leaving the phone `offline` until someone presses "Reintentar".
+  /** Failed attempts in the current streak; back to 0 when the engine starts, or the softphone stops. */
+  #startRetries = 0;
+  /** The wait before the next attempt, or `null` when none is pending. */
+  #startRetryTimer = null;
+  /** No attempt before this (epoch ms): a `Retry-After` the failure carried, which a wake-up must honour too. */
+  #startRetryNotBefore = 0;
+  /** Unsubscribes the `online` / tab-visible wake-ups, armed only while an attempt is pending. */
+  #unwatchWake = null;
   /**
    * `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
@@ -844,6 +904,7 @@ var SoftphoneImpl = class extends Emitter {
   async stop() {
     if (!this.#startedHere) return;
     this.#run += 1;
+    this.#cancelStartRetry();
     this.#lineMode = "off";
     this.#sayGoodbye();
     this.#startDecision?.end();
@@ -887,6 +948,7 @@ var SoftphoneImpl = class extends Emitter {
   async call(destination, options) {
     this.#assertUsable();
     const run = this.#run;
+    if (this.#startRetryTimer !== null) this.#wakeStartRetry();
     if (this.#startDecision) {
       let timer;
       const decided = await Promise.race([
@@ -1030,6 +1092,9 @@ var SoftphoneImpl = class extends Emitter {
         clientId: this.#clientId,
         onLine: (update) => this.#onLine(update),
         onClaimResult: (result) => this.#onClaimResult(result),
+        // The calls offered to this line, straight to the engine: after a decline, they say when the declined
+        // call's re-offers stop (incoming-call-reliability.md §4.4). Not public — nothing a host acts on.
+        onOffer: (offer) => this.#engine.noteOffer?.(offer),
         // A source that cannot take part will never answer, and one that cannot connect cannot answer yet:
         // `start()` need not wait out its 4 s for either (R7). A later answer still applies.
         onLineUnsupported: () => this.#releaseFirstLine?.(),
@@ -1076,6 +1141,7 @@ var SoftphoneImpl = class extends Emitter {
     this.#presenceAgents = [];
     this.emit("presenceChanged" /* PresenceChanged */, { agents: [] });
     this.#forgetLine();
+    this.#engine.noteOffer?.(null);
   }
   /**
    * A DELIBERATE stop (`stop()` / `destroy()`): say any call is over, then say goodbye, so the backend drops
@@ -1135,12 +1201,14 @@ var SoftphoneImpl = class extends Emitter {
     });
     return step;
   }
+  /** Resolves when the engine started — or when its failure is being retried on its own (§4.6). */
   async #startEngine(run) {
     const reported = this.#lastError;
     try {
       await this.#engine.start();
+      if (run === this.#run) this.#startRetries = 0;
     } catch (cause) {
-      if (run === this.#run) this.#engineStartFailed(cause, reported);
+      if (run === this.#run && this.#engineStartFailed(cause, reported)) return;
       throw cause;
     }
   }
@@ -1148,19 +1216,99 @@ var SoftphoneImpl = class extends Emitter {
    * An engine start the line asked for failed. Kept as it was, this softphone would stay the owner on the
    * server — `starting`, its presence socket renewing the line — with no push socket anywhere: nobody would
    * listen. So it gives the line up the ordinary way, by closing its presence socket without a goodbye (the
-   * phone was not switched off): the server hands the line on after its grace (R4). The failure is reported
-   * like any engine failure — `SoftphoneEvent.Error` and `lastError`, which is the widget's error gate and
-   * its "Reintentar" (`stop()` then `start()`, which asks for the line again). Nothing retries on its own.
+   * phone was not switched off): the server hands the line on after its grace (R4).
+   *
+   * Then it depends on why (incoming-call-reliability.md §4.6, F5):
+   *   - **a passing failure** (a 5xx, the network, a timeout — `transientStartFailure`) is attempted again on its
+   *     own, after a backoff, as `reconnecting`, with no error gate. Found live: a voice token answered 500 after
+   *     10 s left a background tab `offline` for good, and every call was lost until someone pressed "Reintentar".
+   *     Returns `true`.
+   *   - **anything else** (a refused credential, no extension) is reported like any engine failure —
+   *     `SoftphoneEvent.Error` and `lastError`, which is the widget's error gate and its "Reintentar" (`stop()`
+   *     then `start()`, which asks for the line again) — and nothing retries on its own. Returns `false`.
    */
   #engineStartFailed(cause, reportedBefore) {
     this.#engineOn = false;
     this.#engineRunning = false;
     this.#lineMode = "off";
+    const transient = this.#destroyed ? null : transientStartFailure(cause);
+    this.#stopPresence();
+    if (transient) {
+      this.#scheduleStartRetry(transient.retryAfterMs, cause);
+      this.#setState("reconnecting");
+      return true;
+    }
     if (this.#lastError === reportedBefore) {
       this.#onError(isSoftphoneError(cause) && isFatal(cause) ? cause : createError("net/transport-failed", cause));
     }
-    this.#stopPresence();
     this.#setState("offline");
+    return false;
+  }
+  /**
+   * The next attempt, after the shared backoff (1 s doubling to 30 s, jittered — the presence socket's own) and
+   * never before a `Retry-After` the failure carried. A plain timer: in a hidden tab it can stretch to about a
+   * minute, which is why the browser coming back `online`, or the tab becoming visible, attempts at once
+   * (`watchWake`). One warning per streak, so a console says what is going on without filling up.
+   */
+  #scheduleStartRetry(retryAfterMs, cause) {
+    this.#startRetries += 1;
+    const wait = Math.max(backoffDelayMs(this.#startRetries), retryAfterMs);
+    if (this.#startRetries === 1) {
+      console.warn("[softphone] the phone could not start; it keeps trying on its own", cause);
+    }
+    this.#startRetryNotBefore = Date.now() + retryAfterMs;
+    if (this.#startRetryTimer !== null) clearTimeout(this.#startRetryTimer);
+    const run = this.#run;
+    this.#startRetryTimer = setTimeout(() => void this.#retryStart(run), wait);
+    this.#unwatchWake ??= watchWake(() => this.#wakeStartRetry());
+  }
+  /** The pending attempt, now — unless a `Retry-After` says not yet, in which case it moves up to that moment. */
+  #wakeStartRetry() {
+    if (this.#startRetryTimer === null) return;
+    const run = this.#run;
+    clearTimeout(this.#startRetryTimer);
+    const wait = this.#startRetryNotBefore - Date.now();
+    if (wait > 0) {
+      this.#startRetryTimer = setTimeout(() => void this.#retryStart(run), wait);
+      return;
+    }
+    void this.#retryStart(run);
+  }
+  /** The wait and the wake-ups go; the streak's count stays (the next failure doubles on from it). */
+  #clearStartRetryWait() {
+    if (this.#startRetryTimer !== null) clearTimeout(this.#startRetryTimer);
+    this.#startRetryTimer = null;
+    this.#unwatchWake?.();
+    this.#unwatchWake = null;
+  }
+  #cancelStartRetry() {
+    this.#clearStartRetryWait();
+    this.#startRetries = 0;
+  }
+  /**
+   * One attempt: what "Reintentar" does after its `stop()`, minus the goodbye and the leadership (both kept) —
+   * the presence socket opens again and its `hello` asks for the line, the line decides (`standby` if it went
+   * elsewhere meanwhile, as at any start), and the engine starts. Without the goodbye, an attempt inside the
+   * server's 10 s grace gets the line straight back. Never for a softphone stopped since it was scheduled.
+   */
+  async #retryStart(run) {
+    this.#clearStartRetryWait();
+    if (this.#destroyed || run !== this.#run || !this.#startedHere || !this.#isLeader) return;
+    const decision = this.#openStartDecision();
+    try {
+      this.#lineMode = "deciding";
+      this.#setState("starting");
+      if (this.#presenceWatch && this.#line === "unknown") await this.#waitForFirstLine();
+      if (this.#destroyed || run !== this.#run) return;
+      this.#lineMode = "on";
+      const engineStart = this.#applyLine();
+      if (!engineStart) this.#startRetries = 0;
+      decision.end();
+      await engineStart?.catch(() => {
+      });
+    } finally {
+      decision.end();
+    }
   }
   /** `start()`'s decision (`#startDecision`): ended once, by whichever comes first — the decision or its end. */
   #openStartDecision() {
@@ -1214,6 +1362,7 @@ var SoftphoneImpl = class extends Emitter {
    * waiting softphone answers by listening again.
    */
   #onPresenceDisconnect() {
+    this.#engine.noteOffer?.(null);
     this.#settleClaim(createError("line/unavailable"));
     if (this.#line === "unknown" || this.#lineLapseTimer !== null) return;
     this.#lineLapseTimer = setTimeout(() => {
@@ -1322,6 +1471,7 @@ var SoftphoneImpl = class extends Emitter {
 };
 
 // src/core/default-provider.ts
+var MAX_PENDING_OFFERS = 20;
 var LazyRelay = class {
   #listeners = /* @__PURE__ */ new Set();
   #realOff = /* @__PURE__ */ new Map();
@@ -1348,13 +1498,16 @@ function defaultZadarmaEngine(config) {
   const incoming = new LazyRelay();
   const stateChange = new LazyRelay();
   const error = new LazyRelay();
+  let pendingOffers = [];
   function load() {
-    pending ??= import('./zadarma-engine-TIUE7PZ7.js').then(({ createZadarmaEngine }) => {
+    pending ??= import('./zadarma-engine-VYIXLBQG.js').then(({ createZadarmaEngine }) => {
       const engine = createZadarmaEngine(config);
       incoming.attach({ on: (l) => engine.onIncoming(l) });
       stateChange.attach({ on: (l) => engine.onStateChange(l) });
       error.attach({ on: (l) => engine.onError?.(l) ?? (() => {
       }) });
+      for (const offer of pendingOffers) engine.noteOffer?.(offer);
+      pendingOffers = [];
       real = engine;
       return engine;
     }).catch((cause) => {
@@ -1385,7 +1538,20 @@ function defaultZadarmaEngine(config) {
     },
     onIncoming: (listener) => incoming.subscribe(listener),
     onStateChange: (listener) => stateChange.subscribe(listener),
-    onError: (listener) => error.subscribe(listener)
+    onError: (listener) => error.subscribe(listener),
+    /*
+     * Relayed like the listeners above, or the decline guard on this — the default — path would never hear the
+     * backend (incoming-call-reliability.md §4.4). Before the engine loads, kept (a few) rather than loading it:
+     * a softphone in `standby` hears offers without ever starting an engine.
+     */
+    noteOffer: (offer) => {
+      if (real) {
+        real.noteOffer?.(offer);
+        return;
+      }
+      pendingOffers.push(offer);
+      if (pendingOffers.length > MAX_PENDING_OFFERS) pendingOffers.shift();
+    }
   };
 }
 
@@ -1425,7 +1591,7 @@ function isCallEngine(value) {
 }
 
 // src/index.ts
-var VERSION = "0.5.0";
+var VERSION = "0.5.1";
 
 export { CALL_TRANSITIONS, INITIAL_STATES, VERSION, canTransition, createSoftphone, isTerminal };
 //# sourceMappingURL=index.js.map