@coventia/softphone 0.4.0 → 0.5.1

package/dist/zadarma/index.d.cts

@@ -1,5 +1,5 @@
-import { x as TokenSource } from '../call-C6YpT6uR.cjs';
-import { C as CallEngine } from '../engine-CDdaSojx.cjs';
+import { A as TokenSource } from '../call-iGvr2ZnO.cjs';
+import { C as CallEngine } from '../engine-BKoT_Pj7.cjs';
 
 /**
  * Provider quirk timers. All optional. A self-hosted provider supplies none of them — which is the
@@ -23,20 +23,47 @@ interface ProviderQuirks {
      */
     readonly userAgent?: string;
     /**
-     * After a reject, ignore inbound INVITEs for this long.
+     * Setting it turns the decline guard on; its value is the guard's FALLBACK window.
      *
-     * Zadarma: 35 000. Its `return_timeout` is ~30 s, during which it RE-RINGS the extension you just
-     * declined. Without this the user is re-rung immediately after hanging up on a caller.
+     * Zadarma: 35 000. Zadarma re-offers a declined call until its ring time ends (the route's
+     * `return_timeout`, ~30 s by default), and nothing in the re-offer tells it from a new call. So after a
+     * decline the engine ignores offers from THE DECLINED CALLER — never anyone else's — while that call is
+     * alive: until the backend says it ended, when it announced it (`CallEngine.noteOffer`); otherwise for
+     * this long after the decline (incoming-call-reliability.md §4.4, Q1).
+     *
+     * Was `rejectGuardMs`, which swallowed every offer and every INVITE in the window, whoever called (CWA-81).
      */
-    readonly rejectGuardMs?: number;
+    readonly declinedCallerGuardMs?: number;
     /**
-     * After an incoming signal, tear the UA down if no INVITE arrives within this long.
+     * Once a REGISTER sent for an offer is answered (its 200 OK), tear the UA down if no INVITE follows within
+     * this long.
+     *
+     * Zadarma: 10 000. Zadarma sends the INVITE ~0.1 s after the 200 OK; a UA left registered with nothing
+     * coming is the standing registration SPEC §3.2 rules out. Counted from the 200 OK, never from `start()`:
+     * on a slow network the WSS alone can take longer than any fixed window (incoming-call-reliability.md F3).
      *
-     * Zadarma: 5 000. The push fires for ANY activity on the extension — transfers, retries, hangups —
-     * not just for a call to answer. Without the teardown a spurious push leaves a UA registered,
-     * which blocks the next real call.
+     * Was `noInviteTeardownMs` (5 000), counted from `ua.start()`.
+     */
+    readonly noInviteAfterRegisterMs?: number;
+    /**
+     * @deprecated Since 0.5.1: `declinedCallerGuardMs`. Kept, with the same value, only because `ZADARMA_QUIRKS`
+     * is exported from `@coventia/softphone/zadarma` and a patch release must not drop a field from it. The engine
+     * does not read it.
+     */
+    readonly rejectGuardMs?: number;
+    /**
+     * @deprecated Since 0.5.1: `noInviteAfterRegisterMs`. Kept, with the same value, for the same reason as
+     * `rejectGuardMs`. The engine does not read it.
      */
     readonly noInviteTeardownMs?: number;
+    /**
+     * The longest an offer may wait for its INVITE, counted from the signal: a leak guard, nothing more.
+     *
+     * Zadarma: 120 000. The wait normally ends with the INVITE, with the offer ending (`offer-ended`), or with
+     * `noInviteAfterRegisterMs`; this only stops a registration that never completes from living forever. It
+     * never fires on a real offer, so it reports nothing (incoming-call-reliability.md §4.3).
+     */
+    readonly offerWaitMaxMs?: number;
     /**
      * Give up waiting for ICE gathering after this long and send the INVITE anyway.
      *
@@ -64,7 +91,7 @@ declare const ZADARMA_QUIRKS: ProviderQuirks;
  * intact (SPEC §3.1).
  */
 interface ZadarmaBrowserConfig {
-    /** Coventia backend base URL, e.g. `https://api.coventia.es`. */
+    /** Coventia's domain only, like `SoftphoneConfig.apiBase`: no path, the SDK builds every route. */
     readonly apiBase: string;
     /** Provides the auth token for the backend key fetch. */
     readonly tokenSource: TokenSource;
@@ -77,9 +104,8 @@ interface ZadarmaBrowserConfig {
  * exchange + push socket) → `ZadarmaProvider` → `SipCallEngine`, with jssip loaded lazily via a
  * dynamic import (SPEC §10.2 — importing the package stays SSR-safe).
  *
- * This is the real thing the app and the e2e smoke test use. It is intentionally NOT the automatic
- * default of `createSoftphone` yet — the app wires it explicitly in S9, and the voice-token endpoint
- * migration is Phase 2 (SPEC §6).
+ * This is the real thing the app and the e2e smoke test use, and what `createSoftphone` builds by
+ * default from `apiBase` when no `provider` is given (`core/default-provider.ts`).
  */
 declare function createZadarmaEngine(config: ZadarmaBrowserConfig): CallEngine;
 

package/dist/zadarma/index.d.ts

@@ -1,5 +1,5 @@
-import { x as TokenSource } from '../call-C6YpT6uR.js';
-import { C as CallEngine } from '../engine-DPft99Wj.js';
+import { A as TokenSource } from '../call-iGvr2ZnO.js';
+import { C as CallEngine } from '../engine-CeGh5Yai.js';
 
 /**
  * Provider quirk timers. All optional. A self-hosted provider supplies none of them — which is the
@@ -23,20 +23,47 @@ interface ProviderQuirks {
      */
     readonly userAgent?: string;
     /**
-     * After a reject, ignore inbound INVITEs for this long.
+     * Setting it turns the decline guard on; its value is the guard's FALLBACK window.
      *
-     * Zadarma: 35 000. Its `return_timeout` is ~30 s, during which it RE-RINGS the extension you just
-     * declined. Without this the user is re-rung immediately after hanging up on a caller.
+     * Zadarma: 35 000. Zadarma re-offers a declined call until its ring time ends (the route's
+     * `return_timeout`, ~30 s by default), and nothing in the re-offer tells it from a new call. So after a
+     * decline the engine ignores offers from THE DECLINED CALLER — never anyone else's — while that call is
+     * alive: until the backend says it ended, when it announced it (`CallEngine.noteOffer`); otherwise for
+     * this long after the decline (incoming-call-reliability.md §4.4, Q1).
+     *
+     * Was `rejectGuardMs`, which swallowed every offer and every INVITE in the window, whoever called (CWA-81).
      */
-    readonly rejectGuardMs?: number;
+    readonly declinedCallerGuardMs?: number;
     /**
-     * After an incoming signal, tear the UA down if no INVITE arrives within this long.
+     * Once a REGISTER sent for an offer is answered (its 200 OK), tear the UA down if no INVITE follows within
+     * this long.
+     *
+     * Zadarma: 10 000. Zadarma sends the INVITE ~0.1 s after the 200 OK; a UA left registered with nothing
+     * coming is the standing registration SPEC §3.2 rules out. Counted from the 200 OK, never from `start()`:
+     * on a slow network the WSS alone can take longer than any fixed window (incoming-call-reliability.md F3).
      *
-     * Zadarma: 5 000. The push fires for ANY activity on the extension — transfers, retries, hangups —
-     * not just for a call to answer. Without the teardown a spurious push leaves a UA registered,
-     * which blocks the next real call.
+     * Was `noInviteTeardownMs` (5 000), counted from `ua.start()`.
+     */
+    readonly noInviteAfterRegisterMs?: number;
+    /**
+     * @deprecated Since 0.5.1: `declinedCallerGuardMs`. Kept, with the same value, only because `ZADARMA_QUIRKS`
+     * is exported from `@coventia/softphone/zadarma` and a patch release must not drop a field from it. The engine
+     * does not read it.
+     */
+    readonly rejectGuardMs?: number;
+    /**
+     * @deprecated Since 0.5.1: `noInviteAfterRegisterMs`. Kept, with the same value, for the same reason as
+     * `rejectGuardMs`. The engine does not read it.
      */
     readonly noInviteTeardownMs?: number;
+    /**
+     * The longest an offer may wait for its INVITE, counted from the signal: a leak guard, nothing more.
+     *
+     * Zadarma: 120 000. The wait normally ends with the INVITE, with the offer ending (`offer-ended`), or with
+     * `noInviteAfterRegisterMs`; this only stops a registration that never completes from living forever. It
+     * never fires on a real offer, so it reports nothing (incoming-call-reliability.md §4.3).
+     */
+    readonly offerWaitMaxMs?: number;
     /**
      * Give up waiting for ICE gathering after this long and send the INVITE anyway.
      *
@@ -64,7 +91,7 @@ declare const ZADARMA_QUIRKS: ProviderQuirks;
  * intact (SPEC §3.1).
  */
 interface ZadarmaBrowserConfig {
-    /** Coventia backend base URL, e.g. `https://api.coventia.es`. */
+    /** Coventia's domain only, like `SoftphoneConfig.apiBase`: no path, the SDK builds every route. */
     readonly apiBase: string;
     /** Provides the auth token for the backend key fetch. */
     readonly tokenSource: TokenSource;
@@ -77,9 +104,8 @@ interface ZadarmaBrowserConfig {
  * exchange + push socket) → `ZadarmaProvider` → `SipCallEngine`, with jssip loaded lazily via a
  * dynamic import (SPEC §10.2 — importing the package stays SSR-safe).
  *
- * This is the real thing the app and the e2e smoke test use. It is intentionally NOT the automatic
- * default of `createSoftphone` yet — the app wires it explicitly in S9, and the voice-token endpoint
- * migration is Phase 2 (SPEC §6).
+ * This is the real thing the app and the e2e smoke test use, and what `createSoftphone` builds by
+ * default from `apiBase` when no `provider` is given (`core/default-provider.ts`).
  */
 declare function createZadarmaEngine(config: ZadarmaBrowserConfig): CallEngine;
 

package/dist/zadarma/index.js

@@ -1,5 +1,7 @@
-export { ZADARMA_QUIRKS, createZadarmaEngine } from '../chunk-EYEDPD7Y.js';
-import '../chunk-2ZSOGGPO.js';
+export { ZADARMA_QUIRKS, createZadarmaEngine } from '../chunk-3UTUWGVG.js';
+import '../chunk-M76SAXXM.js';
+import '../chunk-FRXHEHQA.js';
+import '../chunk-DZRSSZWB.js';
 import '../chunk-MHOJHG5E.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/zadarma-engine-VYIXLBQG.js

@@ -0,0 +1,7 @@
+export { createZadarmaEngine } from './chunk-3UTUWGVG.js';
+import './chunk-M76SAXXM.js';
+import './chunk-FRXHEHQA.js';
+import './chunk-DZRSSZWB.js';
+import './chunk-MHOJHG5E.js';
+//# sourceMappingURL=zadarma-engine-VYIXLBQG.js.map
+//# sourceMappingURL=zadarma-engine-VYIXLBQG.js.map

package/dist/{zadarma-engine-L5DEFXUS.js.map → zadarma-engine-VYIXLBQG.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"zadarma-engine-L5DEFXUS.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"zadarma-engine-VYIXLBQG.js"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coventia/softphone",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Embeddable browser softphone SDK for Zadarma: a framework-free engine, React components, and a Web Component drop-in.",
   "type": "module",
   "author": "Coventia",

package/dist/chunk-2ZSOGGPO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/errors.ts"],"names":[],"mappings":"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","file":"chunk-2ZSOGGPO.js","sourcesContent":["/**\r\n * The error taxonomy.\r\n *\r\n * Two things make this worth more than `onError(Error)`:\r\n *\r\n *  1. **Fatal vs non-fatal, as a discriminated union.** A fatal error means the call (or the engine)\r\n *     is over and the host must react. A non-fatal one is a warning the host may surface or ignore.\r\n *     Collapsing them into one channel — which is what almost every SDK does — forces every\r\n *     integrator to re-derive the distinction from string matching. Daily's split is the model.\r\n *\r\n *  2. **A coded catalogue with a `solution` per code.** Twilio and Telnyx both ship this and\r\n *     integrators love it, because the support conversation becomes \"send me the code\" instead of\r\n *     \"send me your logs\".\r\n *\r\n * The catalogue below is the SINGLE source of truth: `fatal` is derived from it at the type level,\r\n * so a code cannot be fatal in the table and non-fatal in a type, and adding a code without deciding\r\n * its severity is a compile error.\r\n */\r\n\r\ninterface ErrorSpec {\r\n  readonly fatal: boolean;\r\n  /** What went wrong, for a developer. */\r\n  readonly message: string;\r\n  /** What to do about it. Shown in logs and in our docs. */\r\n  readonly solution: string;\r\n}\r\n\r\nexport const ERROR_CATALOGUE = {\r\n  // ── Engine lifecycle ────────────────────────────────────────────────────────\r\n  'engine/duplicate-instance': {\r\n    fatal: true,\r\n    message: 'A Softphone instance is already running on this page.',\r\n    solution:\r\n      'Construct one Softphone and share it. React StrictMode double-mounts in development — hold the instance above the tree, or in a ref, and call destroy() on unmount.',\r\n  },\r\n  'engine/not-started': {\r\n    fatal: false,\r\n    message: 'The softphone has not been started.',\r\n    solution: 'Await softphone.start() before placing or answering a call.',\r\n  },\r\n  'engine/destroyed': {\r\n    fatal: true,\r\n    message: 'This Softphone has been destroyed and cannot be reused.',\r\n    solution: 'Construct a new Softphone.',\r\n  },\r\n\r\n  // ── Auth ────────────────────────────────────────────────────────────────────\r\n  'auth/token-fetch-failed': {\r\n    fatal: true,\r\n    message: 'Could not obtain a voice token from the token endpoint.',\r\n    solution:\r\n      'Check that the token endpoint is reachable and that the headers callback returns a valid host-app session token.',\r\n  },\r\n  'auth/token-rejected': {\r\n    fatal: true,\r\n    message: 'The voice token was rejected.',\r\n    solution:\r\n      'The token is expired, malformed, or scoped to a different organization. Mint a fresh one.',\r\n  },\r\n\r\n  // ── Media ───────────────────────────────────────────────────────────────────\r\n  /*\r\n    NONE of the four codes below are ever actually raised via `createError` — nothing in the SDK\r\n    constructs a `SoftphoneError` with these codes today. Deleting them was the other option\r\n    (SPEC discussion); they stay, commented, because the taxonomy and Spanish copy (`error-text.ts`)\r\n    are worth keeping intact for whenever a real caller wants them, and a `SoftphoneErrorCode` union\r\n    is a cheap thing to keep honest with a comment, expensive to keep churning as a breaking change.\r\n  */\r\n  'media/permission-denied': {\r\n    fatal: true,\r\n    message: 'Microphone permission was denied.',\r\n    solution:\r\n      '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.',\r\n    // NEVER RAISED. `MicPermissionGate` (ui/permission/) handles this condition today — it predates\r\n    // this catalogue and has BETTER, browser-specific unblock instructions than a generic gate could\r\n    // show. It does not import this catalogue at all; the two are unconnected on purpose.\r\n  },\r\n  'media/no-input-device': {\r\n    fatal: true,\r\n    message: 'No microphone is available.',\r\n    solution: 'Ask the user to connect a microphone, then retry.',\r\n    // NEVER RAISED — same reason as `media/permission-denied` above: `MicPermissionGate` already\r\n    // owns this.\r\n  },\r\n  'media/webrtc-unsupported': {\r\n    fatal: true,\r\n    message: 'This browser does not expose the WebRTC APIs.',\r\n    solution:\r\n      'Usually a privacy extension (uBlock Origin Extra, WebRTC Leak Prevent) disabling RTCPeerConnection — Twilio documents the same. Ask the user to disable it for this origin.',\r\n    // NEVER RAISED — same reason again: `MicPermissionGate` already owns this.\r\n  },\r\n  'media/playback-blocked': {\r\n    fatal: false,\r\n    message: 'The browser blocked audio playback (autoplay policy).',\r\n    solution:\r\n      'Call softphone.startAudio() from a click handler. Until then the user cannot hear the caller, and an INCOMING RINGTONE WILL BE SILENT — this is how calls get missed.',\r\n    /*\r\n      NEVER RAISED — different reason from the other three. This is not superseded by an existing\r\n      UI; the feature it describes (autoplay-recovery) is simply not built yet. `Softphone.canPlayAudio`\r\n      / `startAudio()` (core/softphone.ts) are Phase 2 and currently no-op stubs — `canPlayAudio`\r\n      always reports `true`. This is where that future work would report the block once it exists.\r\n    */\r\n  },\r\n\r\n  // ── Network / signalling ────────────────────────────────────────────────────\r\n  'net/registration-failed': {\r\n    fatal: true,\r\n    message: 'SIP registration failed.',\r\n    solution: 'Usually a stale credential. The engine refreshes and retries; if it persists, the extension may not exist.',\r\n  },\r\n  'net/transport-failed': {\r\n    fatal: true,\r\n    message: 'The signalling transport could not be established.',\r\n    solution: 'Check the CSP connect-src directive and any corporate proxy blocking WSS.',\r\n  },\r\n  'net/ice-failed': {\r\n    fatal: false,\r\n    message: 'Media connectivity was lost; attempting an ICE restart.',\r\n    solution:\r\n      'Usually a network handoff (wifi → cellular). The engine recovers on its own; surface a \"reconnecting\" banner rather than ending the call.',\r\n    /*\r\n      NEVER RAISED. The \"reconnecting\" banner this `solution` describes already exists — CallScreen\r\n      shows \"Reconectando…\" directly off the call's own `reconnecting` STATE (`STATUS_LABEL` in\r\n      views/CallScreen.tsx), which the SIP engine drives without going through the error channel at\r\n      all. Raising this too would say the same fact twice through two different mechanisms. It would\r\n      only earn its keep for host-side OBSERVABILITY — counting ICE restarts independently of the UI\r\n      — which nobody has asked for yet.\r\n    */\r\n  },\r\n\r\n  // ── Call ────────────────────────────────────────────────────────────────────\r\n  'call/not-answerable': {\r\n    fatal: false,\r\n    message: 'This call cannot be answered in its current state.',\r\n    solution: 'Only a call in `ringing` may be answered. Check call.state first.',\r\n  },\r\n  'call/busy': {\r\n    fatal: false,\r\n    message: 'The remote party is busy.',\r\n    solution:\r\n      'Nothing to fix. Note SIP 486 is also what most endpoints send for a manual decline, so do not ' +\r\n      'label this \"busy\" alone in your UI — it is equally often \"did not answer\".',\r\n  },\r\n  'call/no-answer': {\r\n    fatal: false,\r\n    message: 'The remote party did not answer.',\r\n    solution: 'Nothing to fix. Surface it to the user.',\r\n  },\r\n  'call/rejected': {\r\n    fatal: false,\r\n    message: 'The remote party rejected the call.',\r\n    solution: 'Nothing to fix. Surface it to the user.',\r\n  },\r\n  'call/missed': {\r\n    fatal: false,\r\n    message: 'An incoming call was cancelled before it was answered.',\r\n    solution:\r\n      'Nothing to fix — the caller gave up while it rang. Surface it, and log it as a missed call.',\r\n  },\r\n  'call/failed': {\r\n    fatal: false,\r\n    message: 'The call could not be completed.',\r\n    solution:\r\n      'The catch-all for a call that never connected — a bad number, a rejected offer, a media ' +\r\n      'failure. `cause` carries the underlying SIP cause. Nothing is fatal: the phone still works.',\r\n  },\r\n  'call/transfer-failed': {\r\n    fatal: false,\r\n    message: 'The transfer could not be completed.',\r\n    solution: 'The original call is still up. Let the user retry or resume.',\r\n  },\r\n  'call/unsupported': {\r\n    fatal: false,\r\n    message: 'The provider does not support this operation.',\r\n    solution: 'Guard the UI on the operation before offering it.',\r\n  },\r\n\r\n  // ── Provider ────────────────────────────────────────────────────────────────\r\n  'provider/provision-failed': {\r\n    fatal: true,\r\n    message: 'The provider could not issue SIP credentials.',\r\n    solution:\r\n      'The backend reached the carrier but got no usable credential. Check the org has a SIP extension provisioned.',\r\n  },\r\n} as const satisfies Record<string, ErrorSpec>;\r\n\r\nexport type SoftphoneErrorCode = keyof typeof ERROR_CATALOGUE;\r\n\r\n/** Codes whose spec says `fatal: true`. Derived — cannot drift from the catalogue. */\r\nexport type FatalErrorCode = {\r\n  [K in SoftphoneErrorCode]: (typeof ERROR_CATALOGUE)[K]['fatal'] extends true ? K : never;\r\n}[SoftphoneErrorCode];\r\n\r\nexport type NonFatalErrorCode = Exclude<SoftphoneErrorCode, FatalErrorCode>;\r\n\r\n/**\r\n * A fatal error: the call, or the engine, is over.\r\n *\r\n * `if (err.fatal)` narrows `err.code` to the fatal codes — which is the entire point of the split,\r\n * and the thing JSDoc could not have expressed (SPEC §2.2).\r\n */\r\nexport interface FatalSoftphoneError extends Error {\r\n  readonly fatal: true;\r\n  readonly code: FatalErrorCode;\r\n  readonly solution: string;\r\n}\r\n\r\n/** A non-fatal error: a warning. The call, if any, continues. */\r\nexport interface NonFatalSoftphoneError extends Error {\r\n  readonly fatal: false;\r\n  readonly code: NonFatalErrorCode;\r\n  readonly solution: string;\r\n}\r\n\r\nexport type SoftphoneError = FatalSoftphoneError | NonFatalSoftphoneError;\r\n\r\n/**\r\n * The one concrete error class. Not exported: the public contract is the `SoftphoneError` union and\r\n * the `code` on it, so nothing outside should be reaching for `instanceof`. It is a real `Error`\r\n * subclass, so `instanceof Error`, `.stack` and console formatting all behave as a host expects.\r\n */\r\nclass CatalogueError extends Error {\r\n  readonly fatal: boolean;\r\n  readonly code: SoftphoneErrorCode;\r\n  readonly solution: string;\r\n\r\n  constructor(code: SoftphoneErrorCode, cause?: unknown) {\r\n    const spec: ErrorSpec = ERROR_CATALOGUE[code];\r\n    // `cause` is only passed when there IS one: `{ cause: undefined }` would still define the\r\n    // property, and an error carrying an explicit `undefined` cause reads as \"we looked and found\r\n    // nothing\" rather than \"nothing was passed\".\r\n    super(spec.message, cause === undefined ? undefined : { cause });\r\n    this.name = 'SoftphoneError';\r\n    this.code = code;\r\n    this.fatal = spec.fatal;\r\n    this.solution = spec.solution;\r\n  }\r\n}\r\n\r\n/**\r\n * Is this already one of ours?\r\n *\r\n * Used where a layer catches whatever a lower one threw: a failure that already carries a catalogue\r\n * code should be reported AS that code, not flattened into the generic one for the layer that caught\r\n * it. Without this, a rejected voice token surfaces as \"the provider could not issue credentials\",\r\n * which is true and useless.\r\n *\r\n * Structural, not `instanceof` — the concrete class is not exported, and a duck-typed object with a\r\n * real code is as good as one of ours.\r\n */\r\nexport function isSoftphoneError(value: unknown): value is SoftphoneError {\r\n  if (typeof value !== 'object' || value === null) return false;\r\n  const candidate = value as { code?: unknown; fatal?: unknown };\r\n  return typeof candidate.fatal === 'boolean' && (candidate.code as string) in ERROR_CATALOGUE;\r\n}\r\n\r\n/** Type guard, for hosts that would rather not rely on structural narrowing. */\r\nexport function isFatal(error: SoftphoneError): error is FatalSoftphoneError {\r\n  return error.fatal;\r\n}\r\n\r\n/**\r\n * Construct a catalogue-backed error. **The only way the SDK raises one** — every `message` and\r\n * `solution` a host sees comes from the table above, so no call site invents error prose.\r\n *\r\n * The return type narrows on the code: `createError('call/busy')` is a `NonFatalSoftphoneError`, and\r\n * reading `.fatal` on it gives `false`, not `boolean`.\r\n */\r\nexport function createError<C extends SoftphoneErrorCode>(\r\n  code: C,\r\n  cause?: unknown,\r\n): C extends FatalErrorCode ? FatalSoftphoneError : NonFatalSoftphoneError {\r\n  // The one cast in this module. A conditional return type cannot be verified from inside the\r\n  // implementation — TypeScript has no way to prove the branch for an unresolved `C` — so the\r\n  // guarantee rests on `fatal` being copied from the catalogue that DERIVES `FatalErrorCode`. The\r\n  // test suite asserts that agreement for every code, which is the check the compiler cannot make.\r\n  return new CatalogueError(code, cause) as C extends FatalErrorCode\r\n    ? FatalSoftphoneError\r\n    : NonFatalSoftphoneError;\r\n}\r\n"]}

package/dist/chunk-7R6LOOAI.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/events.ts"],"names":["SoftphoneEvent","CallEvent"],"mappings":";AAcO,IAAK,cAAA,qBAAAA,eAAAA,KAAL;AAEL,EAAAA,gBAAA,cAAA,CAAA,GAAe,cAAA;AAEf,EAAAA,gBAAA,cAAA,CAAA,GAAe,cAAA;AAMf,EAAAA,gBAAA,mBAAA,CAAA,GAAoB,mBAAA;AAQpB,EAAAA,gBAAA,iBAAA,CAAA,GAAkB,iBAAA;AAOlB,EAAAA,gBAAA,cAAA,CAAA,GAAe,cAAA;AAEf,EAAAA,gBAAA,OAAA,CAAA,GAAQ,OAAA;AAMR,EAAAA,gBAAA,eAAA,CAAA,GAAgB,eAAA;AAShB,EAAAA,gBAAA,iBAAA,CAAA,GAAkB,iBAAA;AAOlB,EAAAA,gBAAA,iBAAA,CAAA,GAAkB,iBAAA;AAjDR,EAAA,OAAAA,eAAAA;AAAA,CAAA,EAAA,cAAA,IAAA,EAAA;AAgEL,IAAK,SAAA,qBAAAC,UAAAA,KAAL;AAEL,EAAAA,WAAA,cAAA,CAAA,GAAe,cAAA;AAEf,EAAAA,WAAA,UAAA,CAAA,GAAW,UAAA;AAEX,EAAAA,WAAA,OAAA,CAAA,GAAQ,OAAA;AACR,EAAAA,WAAA,OAAA,CAAA,GAAQ,OAAA;AAER,EAAAA,WAAA,MAAA,CAAA,GAAO,MAAA;AACP,EAAAA,WAAA,QAAA,CAAA,GAAS,QAAA;AAET,EAAAA,WAAA,cAAA,CAAA,GAAe,cAAA;AACf,EAAAA,WAAA,aAAA,CAAA,GAAc,aAAA;AACd,EAAAA,WAAA,YAAA,CAAA,GAAa,YAAA;AAEb,EAAAA,WAAA,oBAAA,CAAA,GAAqB,oBAAA;AAMrB,EAAAA,WAAA,cAAA,CAAA,GAAe,cAAA;AAtBL,EAAA,OAAAA,UAAAA;AAAA,CAAA,EAAA,SAAA,IAAA,EAAA","file":"chunk-7R6LOOAI.js","sourcesContent":["import type { Call, CallState, HangupReason, HoldOriginator } from './call.js';\r\nimport type { SoftphoneError } from './errors.js';\r\nimport type { PresenceEntry, SoftphoneState, TransferOutcomeEvent } from './types.js';\r\n\r\n/**\r\n * Typed events.\r\n *\r\n * Enums rather than magic strings: autocomplete, and rename-safety. Daily's magic strings are the\r\n * counter-example — a typo in `'participant-joined'` is a silent no-op forever.\r\n *\r\n * Each map narrows the listener payload PER EVENT, which is the thing that would have been painful\r\n * to express in JSDoc and is a large part of why this package is TypeScript (SPEC §2.2).\r\n */\r\n\r\nexport enum SoftphoneEvent {\r\n  /** Lifecycle. `online` = reachable, NOT SIP-registered — see SoftphoneState. */\r\n  StateChanged = 'stateChanged',\r\n  /** An INVITE landed. The Call is `ringing`; answer or reject it. */\r\n  IncomingCall = 'incomingCall',\r\n  /**\r\n   * The active call changed — a call began (inbound OR outbound) or ended. Fires for both\r\n   * directions, unlike IncomingCall. This is what a UI binds to in order to track \"the current call\"\r\n   * without threading the Call through every component.\r\n   */\r\n  ActiveCallChanged = 'activeCallChanged',\r\n  /**\r\n   * The browser refused to play audio (autoplay policy).\r\n   *\r\n   * This is the single most under-documented failure in the industry and it is how calls get MISSED:\r\n   * a blocked ringtone rings silently. Surface a button and call `startAudio()` from its click\r\n   * handler. Only Twilio and LiveKit document it properly.\r\n   */\r\n  PlaybackBlocked = 'playbackBlocked',\r\n  /**\r\n   * `softphone.audio` changed: a device was plugged/unplugged (`inputs`/`outputs`), or the selected\r\n   * input/output changed (`currentInputId`/`currentOutputId`). One event for all of it — re-read\r\n   * `softphone.audio` rather than inspecting the payload, which carries nothing (`useDevices` does\r\n   * exactly this).\r\n   */\r\n  DeviceChange = 'deviceChange',\r\n  /** Fatal or non-fatal — narrow on `error.fatal`. */\r\n  Error = 'error',\r\n  /**\r\n   * This tab's leadership changed (`multi-tab-leader-election.md`) — a DIFFERENT axis from\r\n   * `StateChanged`: `state` is reachability, this is whether this tab is even allowed to be\r\n   * reachable at all while another tab holding the same extension stays open.\r\n   */\r\n  LeaderChanged = 'leaderChanged',\r\n  /**\r\n   * `Completar` completed a transfer, and the target's SECOND ring either connected or didn't —\r\n   * `docs/specs/transfer-outcome-relay.md` (Phase A). Fires for BOTH outcomes so a host can react to\r\n   * either; only `'not-connected'` is worth surfacing to the agent (spec §5.5) — roughly a minute\r\n   * after the transfer for a target who never answers, seconds for a decline or the caller hanging up\r\n   * first. Requires a `TransferOutcomeSource` (from `coventia`/`apiBase`, or a host override); never\r\n   * fires at all when none is configured, since there is then nothing to poll.\r\n   */\r\n  TransferOutcome = 'transferOutcome',\r\n  /**\r\n   * `softphone.presence` changed — the live agent-presence list (Phase B,\r\n   * `docs/specs/transfer-presence-picker.md`) gained a snapshot or an updated entry. Requires a\r\n   * `PresenceSource` (from `coventia`/`apiBase`, or a host override) AND this tab currently being\r\n   * `online && isLeader`; never fires at all otherwise, same reasoning as `TransferOutcome`.\r\n   */\r\n  PresenceChanged = 'presenceChanged',\r\n}\r\n\r\nexport interface SoftphoneEventMap {\r\n  [SoftphoneEvent.StateChanged]: { readonly state: SoftphoneState; readonly previous: SoftphoneState };\r\n  [SoftphoneEvent.IncomingCall]: Call;\r\n  [SoftphoneEvent.ActiveCallChanged]: { readonly call: Call | null };\r\n  [SoftphoneEvent.PlaybackBlocked]: void;\r\n  [SoftphoneEvent.DeviceChange]: void;\r\n  [SoftphoneEvent.Error]: SoftphoneError;\r\n  [SoftphoneEvent.LeaderChanged]: { readonly isLeader: boolean };\r\n  [SoftphoneEvent.TransferOutcome]: TransferOutcomeEvent;\r\n  [SoftphoneEvent.PresenceChanged]: { readonly agents: readonly PresenceEntry[] };\r\n}\r\n\r\nexport enum CallEvent {\r\n  /** Any transition. The catch-all; the specific events below are conveniences. */\r\n  StateChanged = 'stateChanged',\r\n  /** Media is flowing. */\r\n  Accepted = 'accepted',\r\n  /** Terminal. Always fires exactly once, whatever the reason. */\r\n  Ended = 'ended',\r\n  Muted = 'muted',\r\n  /** `originator: 'remote'` means the OTHER party held US — new capability; today's softphone is blind to it. */\r\n  Held = 'held',\r\n  Unheld = 'unheld',\r\n  /** Media lost; an ICE restart is in flight. The call is NOT over — show a banner. */\r\n  Reconnecting = 'reconnecting',\r\n  Reconnected = 'reconnected',\r\n  DigitsSent = 'digitsSent',\r\n  /** The contact name resolved after the call was already ringing. */\r\n  RemotePartyUpdated = 'remotePartyUpdated',\r\n  /**\r\n   * The remote audio stream is available. Attach it to an `<audio>` element and play it — this is\r\n   * how the caller is actually HEARD. Core cannot do this itself (it must not touch `document` —\r\n   * SPEC §10.2); the UI layer or the host owns the audio element.\r\n   */\r\n  RemoteStream = 'remoteStream',\r\n}\r\n\r\nexport interface CallEventMap {\r\n  [CallEvent.StateChanged]: { readonly state: CallState; readonly previous: CallState };\r\n  [CallEvent.Accepted]: void;\r\n  [CallEvent.Ended]: { readonly reason: HangupReason; readonly error?: SoftphoneError };\r\n  [CallEvent.Muted]: { readonly muted: boolean };\r\n  [CallEvent.Held]: { readonly originator: HoldOriginator };\r\n  [CallEvent.Unheld]: { readonly originator: HoldOriginator };\r\n  [CallEvent.Reconnecting]: void;\r\n  [CallEvent.Reconnected]: void;\r\n  [CallEvent.DigitsSent]: { readonly digits: string };\r\n  [CallEvent.RemotePartyUpdated]: void;\r\n  [CallEvent.RemoteStream]: { readonly stream: MediaStream };\r\n}\r\n\r\n/**\r\n * `on()` returns an unsubscribe function.\r\n *\r\n * Deliberate: it makes the cleanup impossible to get wrong in a React effect\r\n * (`useEffect(() => call.on(...), [call])`) and it avoids Vonage's design, where `on()` returns an\r\n * opaque `symbol` you must retain in order to ever call `off()`.\r\n */\r\nexport interface TypedEmitter<M> {\r\n  on<E extends keyof M>(event: E, listener: (payload: M[E]) => void): () => void;\r\n  once<E extends keyof M>(event: E, listener: (payload: M[E]) => void): () => void;\r\n  off<E extends keyof M>(event: E, listener: (payload: M[E]) => void): void;\r\n}\r\n"]}