@coventia/softphone 0.1.0

package/dist/call-BTYlT2SU.d.cts

@@ -0,0 +1,680 @@
+/**
+ * Shared public types.
+ *
+ * Nothing here may reference Zadarma, WhatsApp, Supabase or React. If a concept from any of those
+ * appears in this file, a boundary has been breached — see SPEC §5.4 and §10.1.
+ */
+/**
+ * A callable contact.
+ *
+ * Deliberately NOT `wa_id`. Today's softphone keys contacts on a WhatsApp ID all the way down into
+ * the dial function (SPEC §4); a telephony SDK cannot ship that. The mapping from whatever the
+ * backend returns to this shape happens in the API client, at the boundary, and WhatsApp's data
+ * model stops there.
+ */
+interface Contact {
+    /**
+     * Opaque. Whatever the host's source produced — **the SDK never parses, formats, or reasons about
+     * it**, and neither should the UI; it is a React key and a thing to hand back to `onContactAction`.
+     *
+     * An earlier draft said "never a `wa_id`", which reality did not allow: the contacts collection has
+     * no other key (`_id` is projected away). What matters is that no WhatsApp SEMANTICS ride along —
+     * and they don't, because the backend serves callable contacts only (`wa_id: /^[0-9]+$/`), so the
+     * value there is literally the phone digits and tells you nothing `phone` doesn't. The boundary
+     * removes the SHAPE, not the digits. See `coventia/contacts.ts`.
+     */
+    readonly id: string;
+    /** Display name, or null when only the number is known. */
+    readonly name: string | null;
+    /** E.164 where possible. */
+    readonly phone: string;
+}
+/** Who is on the other end. */
+interface RemoteParty {
+    /** The number as the provider gave it to us. */
+    readonly number: string;
+    /**
+     * Best available name. Falls back to `number`.
+     *
+     * The provider's own SIP display name is the *line label*, not the caller — so we resolve the
+     * name from the host's contacts via `resolveContact` and prefer that.
+     */
+    readonly displayName: string;
+    /** Populated asynchronously by `resolveContact`; null when unknown or not configured. */
+    readonly contact: Contact | null;
+}
+type CallDirection = 'inbound' | 'outbound';
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/** A short-lived, org-scoped credential minted by Coventia's backend (SPEC §6.1). */
+interface VoiceToken {
+    /**
+     * The **raw** credential — no `Bearer ` prefix. The SDK sends it as the entire `Authorization`
+     * header value when it fetches the WebRTC key (SPEC §6.6, hop ③), matching what the CRM does today.
+     *
+     * Stated because `string` cannot: an integrator returning `'Bearer eyJ…'` is sending
+     * `Authorization: Bearer Bearer eyJ…`. Coventia's backend happens to tolerate both
+     * (`token.startsWith('Bearer ') ? token.slice(7) : token`) — a partner's own proxy may not.
+     */
+    readonly token: string;
+    readonly expiresAt: Date;
+    readonly identity: string;
+}
+/**
+ * How the SDK obtains a voice token.
+ *
+ * The SDK — not the integrator — owns fetch, retry and refresh (LiveKit's `TokenSource` model). A
+ * reseller points this at their own backend, which proxies to Coventia's; the trust relationship,
+ * and the Zadarma credentials behind it, stay ours (SPEC §6.1).
+ *
+ * Refresh must never drop a live call: the token authenticates connect and reconnect, not the media
+ * session.
+ */
+interface TokenSource {
+    getToken(signal?: AbortSignal): Promise<VoiceToken>;
+}
+interface TokenEndpointOptions {
+    /** Called per request, so a rotating host-app session token is always current. */
+    readonly headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * Coventia's phone service — the ONE place a host configures contacts, history and caller ID.
+ *
+ * `tokenSource` is deliberately absent: it is already on `SoftphoneConfig`, and repeating it was the
+ * tell that this config was in the wrong place. Nothing here names a route; a host never imports an
+ * adapter, and there is no "coventia" module to know about.
+ */
+interface CoventiaBackendConfig {
+    /**
+     * e.g. `https://api.coventia.es`. **Optional** — falls back to `SoftphoneConfig.apiBase`, which
+     * exists precisely so this and the default call engine name the same backend once instead of
+     * twice. Set it here only when contacts/history genuinely live on a DIFFERENT host than calling
+     * does, which is not the normal case.
+     */
+    readonly baseUrl?: string | undefined;
+    /**
+     * **Omit this when authenticating with a voice token** — which is what a partner does.
+     *
+     * A voice token names exactly one (user, organization, extension) triple, and the backend pins the
+     * organization from that claim: anything sent here is overwritten server-side. Setting it would be
+     * a second source of truth for the tenant that silently loses, which is worse than no field at all.
+     *
+     * It is still required for a host that authenticates with a **session** instead, because a session
+     * spans every organization its user belongs to — so there the org genuinely is caller-supplied.
+     * That is the CRM today.
+     */
+    readonly organizationId?: string;
+    /** `/phone` today; `/api/v1/phone` once the partner API ships (SPEC §6.6). */
+    readonly basePath?: string;
+    /**
+     * **The one thing a provider customises**: their own contact list, searched on their own backend.
+     *
+     * Supplying it is enough for everything — it drives the Contactos tab, and caller ID is derived
+     * from it by searching for the incoming number. One source means the tab, a live call and a
+     * history row can never disagree about who a number belongs to.
+     *
+     * History and recordings are never here: Coventia receives the Zadarma events and stores them
+     * (SPEC §6.6).
+     */
+    readonly contacts?: ContactsSource;
+}
+interface SoftphoneConfig {
+    readonly tokenSource: TokenSource;
+    /**
+     * The Coventia backend, e.g. `https://api.coventia.es`. **The one field to set** if you want the
+     * default call engine (see `provider` below) and are not overriding `coventia.baseUrl` separately.
+     *
+     * Named once here rather than requiring it on both `coventia` and the engine you construct: they
+     * are two independent subsystems (contacts/history/caller ID vs. SIP credential provisioning) that
+     * happen to share a backend host, and a value that must be typed in two places is a value that can
+     * silently drift apart in one of them.
+     */
+    readonly apiBase?: string;
+    /**
+     * Coventia's phone service — for OVERRIDING something, not for switching it on.
+     *
+     * `apiBase` alone already gives you contacts, history and caller ID — including on an incoming
+     * call that arrives before any UI is mounted, which is why this lives here and not on the widget.
+     * Set `coventia` when you need to say more: your own `contacts` function, an `organizationId` a
+     * session-authenticated host must supply, or a `baseUrl` that genuinely differs from the engine's.
+     */
+    readonly coventia?: CoventiaBackendConfig;
+    /**
+     * Caller ID, overriding whatever `coventia` would derive.
+     *
+     * Rarely needed: `coventia.contacts` already derives it by searching for the number. Worth setting
+     * when a dedicated lookup is cheaper than a search, or when the number lives on a record the
+     * search does not return.
+     */
+    readonly resolveContact?: (number: string) => Promise<Contact | null>;
+    readonly logLevel?: LogLevel;
+    /**
+     * The call engine. **Optional** — omit it and a Zadarma engine is built for you from `apiBase`
+     * (and `coventia.organizationId`, for a host authenticating with a session). Building it is
+     * deferred until the softphone actually starts, so omitting `provider` costs nothing at import
+     * time or in a server-rendered page.
+     *
+     * Pass it explicitly for a `MockProvider` from `@coventia/softphone/testing` (tests, playgrounds),
+     * or to construct `createZadarmaEngine({ apiBase, tokenSource })` from `@coventia/softphone/zadarma`
+     * yourself — e.g. because you need `organizationId` set independently of `coventia`'s. An explicit
+     * `provider` always wins; `apiBase` is only consulted when this is omitted entirely.
+     *
+     * Zadarma is presently the ONLY built-in default — see SPEC §5.4. A different provider is still
+     * only reachable by constructing it yourself and passing it here.
+     */
+    readonly provider?: unknown;
+}
+interface CallOptions {
+    /** Extra SIP headers. Provider-specific; most consumers never need this. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Softphone lifecycle state.
+ *
+ * `online` means REACHABLE — the provider's presence channel is up. It does NOT mean SIP-registered.
+ * Zadarma registers on-demand, per call, in response to a push (SPEC §3.2); a persistent UA is
+ * ignored by its PBX. Leaking "registered" into the public API would force every future provider —
+ * including our own SIP infrastructure, which registers persistently — to fake it.
+ */
+type SoftphoneState = 'stopped' | 'starting' | 'online' | 'offline' | 'reconnecting' | 'destroyed';
+interface ContactsPage {
+    readonly items: readonly Contact[];
+    /**
+     * The count across ALL pages for this `search` — not `items.length`. Drives the Contactos tab's
+     * scroll-to-load-more: it fetches the next page once `skip + items.length < total`. Too low (e.g.
+     * always returning `items.length`) silently strands the rest of the list; too high sends one
+     * wasted empty request per further scroll once the real data runs out.
+     */
+    readonly total: number;
+}
+/** Load a page of contacts. `search` empty ⇒ the full (paged) list. */
+type ContactsSource = (params: {
+    readonly search: string;
+    readonly skip: number;
+    readonly limit: number;
+}) => Promise<ContactsPage>;
+/**
+ * WHY a call went unanswered — the SDK's own vocabulary, never the PBX's raw disposition string
+ * ("no answer", "busy", "cancel", "congestion", …). `unavailable` is the open-ended catch-all: an
+ * unrecognised or future PBX value maps here rather than being dropped, the same reasoning
+ * `missed` itself already uses ("any disposition other than 'answered' counts").
+ */
+type CallOutcome = 'no-answer' | 'busy' | 'cancelled' | 'failed' | 'unavailable';
+/** One hop that handled a call — the primary answerer, or one leg of a transfer, in order. */
+interface CallHandler {
+    readonly extension: string;
+    /** `null` when the extension could not be resolved to an org member. */
+    readonly userId: string | null;
+    /** Resolved only via `CallHistoryEntry.loadDetail` — always `null` on the plain list entry. */
+    readonly name: string | null;
+}
+/** The call detail page's one enrichment fetch — see `CallHistoryEntry.loadDetail`. */
+interface CallDetail {
+    readonly recordingUrls: readonly string[];
+    /** The same chain `CallHistoryEntry.handledBy` has, with `name` resolved for each hop. */
+    readonly handledBy: readonly CallHandler[];
+}
+interface CallHistoryEntry {
+    readonly id: string;
+    readonly direction: CallDirection;
+    /** E.164 where known. */
+    readonly number: string;
+    readonly name: string | null;
+    readonly at: Date;
+    readonly durationSec: number;
+    readonly missed: boolean;
+    /** Present only when `missed` is true — why. Absent for an answered call, not `undefined` noise. */
+    readonly outcome?: CallOutcome;
+    /** The org's own number that was dialled — present only (and only meaningful) for an inbound call. */
+    readonly did?: string;
+    /** True when Coventia has at least one recording for this call. */
+    readonly recorded: boolean;
+    /**
+     * Who handled the call, in order — extension only, before any name is resolved. Empty when nobody
+     * did (a missed inbound call never got a chain) or the org has no chain recorded for it at all.
+     */
+    readonly handledBy: readonly CallHandler[];
+    /**
+     * The detail page's one enrichment fetch: signed recording URLs, and the SAME `handledBy` chain
+     * with names resolved. Absent when there is nothing to enrich (`!recorded && handledBy.length ===
+     * 0`) — lazy for the same reason a single recording URL used to be: minting N signed URLs and
+     * resolving N sets of names for a page of 30 calls nobody opens is pure waste. Coventia only builds
+     * this from `/phone/calls/:id`, one call at a time; that is not an accident of our backend.
+     */
+    readonly loadDetail?: () => Promise<CallDetail>;
+}
+type HistorySource = (params: {
+    readonly skip: number;
+    readonly limit: number;
+    /** Only calls that went unanswered (any disposition other than "answered") — the Historial tab's "Perdidas" filter. */
+    readonly missed?: boolean;
+    /** Only calls this person handled — the primary handler OR any hop in a transfer chain. From `PhoneAgent.userId`. */
+    readonly userId?: string;
+}) => Promise<readonly CallHistoryEntry[]>;
+/** One member of the org with a phone extension — an option in the Historial tab's "filter by person". */
+interface PhoneAgent {
+    readonly userId: string;
+    readonly name: string | null;
+}
+interface AgentsDirectory {
+    /** The caller themselves, if they have a phone extension — drives "Mis llamadas". `null` otherwise. */
+    readonly me: PhoneAgent | null;
+    readonly people: readonly PhoneAgent[];
+}
+
+/**
+ * The error taxonomy.
+ *
+ * Two things make this worth more than `onError(Error)`:
+ *
+ *  1. **Fatal vs non-fatal, as a discriminated union.** A fatal error means the call (or the engine)
+ *     is over and the host must react. A non-fatal one is a warning the host may surface or ignore.
+ *     Collapsing them into one channel — which is what almost every SDK does — forces every
+ *     integrator to re-derive the distinction from string matching. Daily's split is the model.
+ *
+ *  2. **A coded catalogue with a `solution` per code.** Twilio and Telnyx both ship this and
+ *     integrators love it, because the support conversation becomes "send me the code" instead of
+ *     "send me your logs".
+ *
+ * The catalogue below is the SINGLE source of truth: `fatal` is derived from it at the type level,
+ * so a code cannot be fatal in the table and non-fatal in a type, and adding a code without deciding
+ * its severity is a compile error.
+ */
+declare const ERROR_CATALOGUE: {
+    readonly 'engine/duplicate-instance': {
+        readonly fatal: true;
+        readonly message: "A Softphone instance is already running on this page.";
+        readonly solution: "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.";
+    };
+    readonly 'engine/not-started': {
+        readonly fatal: false;
+        readonly message: "The softphone has not been started.";
+        readonly solution: "Await softphone.start() before placing or answering a call.";
+    };
+    readonly 'engine/destroyed': {
+        readonly fatal: true;
+        readonly message: "This Softphone has been destroyed and cannot be reused.";
+        readonly solution: "Construct a new Softphone.";
+    };
+    readonly 'auth/token-fetch-failed': {
+        readonly fatal: true;
+        readonly message: "Could not obtain a voice token from the token endpoint.";
+        readonly solution: "Check that the token endpoint is reachable and that the headers callback returns a valid host-app session token.";
+    };
+    readonly 'auth/token-rejected': {
+        readonly fatal: true;
+        readonly message: "The voice token was rejected.";
+        readonly solution: "The token is expired, malformed, or scoped to a different organization. Mint a fresh one.";
+    };
+    readonly 'media/permission-denied': {
+        readonly fatal: true;
+        readonly message: "Microphone permission was denied.";
+        readonly 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.";
+    };
+    readonly 'media/no-input-device': {
+        readonly fatal: true;
+        readonly message: "No microphone is available.";
+        readonly solution: "Ask the user to connect a microphone, then retry.";
+    };
+    readonly 'media/webrtc-unsupported': {
+        readonly fatal: true;
+        readonly message: "This browser does not expose the WebRTC APIs.";
+        readonly solution: "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.";
+    };
+    readonly 'media/playback-blocked': {
+        readonly fatal: false;
+        readonly message: "The browser blocked audio playback (autoplay policy).";
+        readonly solution: "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.";
+    };
+    readonly 'net/registration-failed': {
+        readonly fatal: true;
+        readonly message: "SIP registration failed.";
+        readonly solution: "Usually a stale credential. The engine refreshes and retries; if it persists, the extension may not exist.";
+    };
+    readonly 'net/transport-failed': {
+        readonly fatal: true;
+        readonly message: "The signalling transport could not be established.";
+        readonly solution: "Check the CSP connect-src directive and any corporate proxy blocking WSS.";
+    };
+    readonly 'net/ice-failed': {
+        readonly fatal: false;
+        readonly message: "Media connectivity was lost; attempting an ICE restart.";
+        readonly solution: "Usually a network handoff (wifi → cellular). The engine recovers on its own; surface a \"reconnecting\" banner rather than ending the call.";
+    };
+    readonly 'call/not-answerable': {
+        readonly fatal: false;
+        readonly message: "This call cannot be answered in its current state.";
+        readonly solution: "Only a call in `ringing` may be answered. Check call.state first.";
+    };
+    readonly 'call/busy': {
+        readonly fatal: false;
+        readonly message: "The remote party is busy.";
+        readonly solution: string;
+    };
+    readonly 'call/no-answer': {
+        readonly fatal: false;
+        readonly message: "The remote party did not answer.";
+        readonly solution: "Nothing to fix. Surface it to the user.";
+    };
+    readonly 'call/rejected': {
+        readonly fatal: false;
+        readonly message: "The remote party rejected the call.";
+        readonly solution: "Nothing to fix. Surface it to the user.";
+    };
+    readonly 'call/missed': {
+        readonly fatal: false;
+        readonly message: "An incoming call was cancelled before it was answered.";
+        readonly solution: "Nothing to fix — the caller gave up while it rang. Surface it, and log it as a missed call.";
+    };
+    readonly 'call/failed': {
+        readonly fatal: false;
+        readonly message: "The call could not be completed.";
+        readonly solution: string;
+    };
+    readonly 'call/transfer-failed': {
+        readonly fatal: false;
+        readonly message: "The transfer could not be completed.";
+        readonly solution: "The original call is still up. Let the user retry or resume.";
+    };
+    readonly 'call/unsupported': {
+        readonly fatal: false;
+        readonly message: "The provider does not support this operation.";
+        readonly solution: "Guard the UI on the operation before offering it.";
+    };
+    readonly 'provider/provision-failed': {
+        readonly fatal: true;
+        readonly message: "The provider could not issue SIP credentials.";
+        readonly solution: "The backend reached the carrier but got no usable credential. Check the org has a SIP extension provisioned.";
+    };
+};
+type SoftphoneErrorCode = keyof typeof ERROR_CATALOGUE;
+/** Codes whose spec says `fatal: true`. Derived — cannot drift from the catalogue. */
+type FatalErrorCode = {
+    [K in SoftphoneErrorCode]: (typeof ERROR_CATALOGUE)[K]['fatal'] extends true ? K : never;
+}[SoftphoneErrorCode];
+type NonFatalErrorCode = Exclude<SoftphoneErrorCode, FatalErrorCode>;
+/**
+ * A fatal error: the call, or the engine, is over.
+ *
+ * `if (err.fatal)` narrows `err.code` to the fatal codes — which is the entire point of the split,
+ * and the thing JSDoc could not have expressed (SPEC §2.2).
+ */
+interface FatalSoftphoneError extends Error {
+    readonly fatal: true;
+    readonly code: FatalErrorCode;
+    readonly solution: string;
+}
+/** A non-fatal error: a warning. The call, if any, continues. */
+interface NonFatalSoftphoneError extends Error {
+    readonly fatal: false;
+    readonly code: NonFatalErrorCode;
+    readonly solution: string;
+}
+type SoftphoneError = FatalSoftphoneError | NonFatalSoftphoneError;
+/** Type guard, for hosts that would rather not rely on structural narrowing. */
+declare function isFatal(error: SoftphoneError): error is FatalSoftphoneError;
+
+/**
+ * Typed events.
+ *
+ * Enums rather than magic strings: autocomplete, and rename-safety. Daily's magic strings are the
+ * counter-example — a typo in `'participant-joined'` is a silent no-op forever.
+ *
+ * Each map narrows the listener payload PER EVENT, which is the thing that would have been painful
+ * to express in JSDoc and is a large part of why this package is TypeScript (SPEC §2.2).
+ */
+declare enum SoftphoneEvent {
+    /** Lifecycle. `online` = reachable, NOT SIP-registered — see SoftphoneState. */
+    StateChanged = "stateChanged",
+    /** An INVITE landed. The Call is `ringing`; answer or reject it. */
+    IncomingCall = "incomingCall",
+    /**
+     * The active call changed — a call began (inbound OR outbound) or ended. Fires for both
+     * directions, unlike IncomingCall. This is what a UI binds to in order to track "the current call"
+     * without threading the Call through every component.
+     */
+    ActiveCallChanged = "activeCallChanged",
+    /**
+     * The browser refused to play audio (autoplay policy).
+     *
+     * This is the single most under-documented failure in the industry and it is how calls get MISSED:
+     * a blocked ringtone rings silently. Surface a button and call `startAudio()` from its click
+     * handler. Only Twilio and LiveKit document it properly.
+     */
+    PlaybackBlocked = "playbackBlocked",
+    /**
+     * `softphone.audio` changed: a device was plugged/unplugged (`inputs`/`outputs`), or the selected
+     * input/output changed (`currentInputId`/`currentOutputId`). One event for all of it — re-read
+     * `softphone.audio` rather than inspecting the payload, which carries nothing (`useDevices` does
+     * exactly this).
+     */
+    DeviceChange = "deviceChange",
+    /** Fatal or non-fatal — narrow on `error.fatal`. */
+    Error = "error",
+    /**
+     * This tab's leadership changed (`multi-tab-leader-election.md`) — a DIFFERENT axis from
+     * `StateChanged`: `state` is reachability, this is whether this tab is even allowed to be
+     * reachable at all while another tab holding the same extension stays open.
+     */
+    LeaderChanged = "leaderChanged"
+}
+interface SoftphoneEventMap {
+    [SoftphoneEvent.StateChanged]: {
+        readonly state: SoftphoneState;
+        readonly previous: SoftphoneState;
+    };
+    [SoftphoneEvent.IncomingCall]: Call;
+    [SoftphoneEvent.ActiveCallChanged]: {
+        readonly call: Call | null;
+    };
+    [SoftphoneEvent.PlaybackBlocked]: void;
+    [SoftphoneEvent.DeviceChange]: void;
+    [SoftphoneEvent.Error]: SoftphoneError;
+    [SoftphoneEvent.LeaderChanged]: {
+        readonly isLeader: boolean;
+    };
+}
+declare enum CallEvent {
+    /** Any transition. The catch-all; the specific events below are conveniences. */
+    StateChanged = "stateChanged",
+    /** Media is flowing. */
+    Accepted = "accepted",
+    /** Terminal. Always fires exactly once, whatever the reason. */
+    Ended = "ended",
+    Muted = "muted",
+    /** `originator: 'remote'` means the OTHER party held US — new capability; today's softphone is blind to it. */
+    Held = "held",
+    Unheld = "unheld",
+    /** Media lost; an ICE restart is in flight. The call is NOT over — show a banner. */
+    Reconnecting = "reconnecting",
+    Reconnected = "reconnected",
+    DigitsSent = "digitsSent",
+    /** The contact name resolved after the call was already ringing. */
+    RemotePartyUpdated = "remotePartyUpdated",
+    /**
+     * The remote audio stream is available. Attach it to an `<audio>` element and play it — this is
+     * how the caller is actually HEARD. Core cannot do this itself (it must not touch `document` —
+     * SPEC §10.2); the UI layer or the host owns the audio element.
+     */
+    RemoteStream = "remoteStream"
+}
+interface CallEventMap {
+    [CallEvent.StateChanged]: {
+        readonly state: CallState;
+        readonly previous: CallState;
+    };
+    [CallEvent.Accepted]: void;
+    [CallEvent.Ended]: {
+        readonly reason: HangupReason;
+        readonly error?: SoftphoneError;
+    };
+    [CallEvent.Muted]: {
+        readonly muted: boolean;
+    };
+    [CallEvent.Held]: {
+        readonly originator: HoldOriginator;
+    };
+    [CallEvent.Unheld]: {
+        readonly originator: HoldOriginator;
+    };
+    [CallEvent.Reconnecting]: void;
+    [CallEvent.Reconnected]: void;
+    [CallEvent.DigitsSent]: {
+        readonly digits: string;
+    };
+    [CallEvent.RemotePartyUpdated]: void;
+    [CallEvent.RemoteStream]: {
+        readonly stream: MediaStream;
+    };
+}
+/**
+ * `on()` returns an unsubscribe function.
+ *
+ * Deliberate: it makes the cleanup impossible to get wrong in a React effect
+ * (`useEffect(() => call.on(...), [call])`) and it avoids Vonage's design, where `on()` returns an
+ * opaque `symbol` you must retain in order to ever call `off()`.
+ */
+interface TypedEmitter<M> {
+    on<E extends keyof M>(event: E, listener: (payload: M[E]) => void): () => void;
+    once<E extends keyof M>(event: E, listener: (payload: M[E]) => void): () => void;
+    off<E extends keyof M>(event: E, listener: (payload: M[E]) => void): void;
+}
+
+/**
+ * THE call state machine. Singular.
+ *
+ * Today there are three competing representations (SPEC §5.3):
+ *   - `callStateRef`   — a ref, read synchronously in guards to dodge stale closures
+ *   - `status`         — a useState that can lag a render behind it
+ *   - `consultStatus`  — the attended-transfer leg, tracked separately
+ * They can disagree. Collapsing them into one is the single biggest correctness win in this
+ * refactor, and the consult leg simply becomes its own Call.
+ *
+ *
+ *   INBOUND                                    OUTBOUND
+ *   ───────                                    ────────
+ *   ringing ──answer()──► answering            dialing ──180/183──► early
+ *      │                      │                   │                    │
+ *      │                      ▼                   └────────┬───────────┘
+ *      │  reject()        ┌───────┐                        │ 200 OK
+ *      └──────────────┐   │       ▼                        ▼
+ *                     │   │    active ◄─────────────────────
+ *                     │   │    ▲   │  ▲   │
+ *                     │   │    │   │  │   └──hold()/remote──► held ──unhold()──┐
+ *                     │   │    │   │  └───────────────────────────────────────-┘
+ *                     │   │    │   └──ICE fail──► reconnecting ──recovered──┐
+ *                     │   │    └────────────────────────────────────────────┘
+ *                     ▼   ▼         │
+ *                    ┌──────────────▼────┐
+ *                    │       ended        │   TERMINAL. Reachable from every state.
+ *                    └────────────────────┘
+ *
+ * NOT modelled here, deliberately:
+ *
+ *   - **`rejecting`.** Today's engine has one, purely to swallow Zadarma's `return_timeout` retries
+ *     for 35 s after a decline (SPEC §3.4). That is a PROVIDER quirk — it belongs in
+ *     `providers/zadarma.ts` as `quirks.rejectGuardMs`, not in the shared state machine. A rejected
+ *     call is simply `ended`. Our own SIP infrastructure would not need it at all (SPEC §2.3).
+ *
+ *   - **A pre-INVITE state.** A Call exists only once an INVITE has landed. The "user answered
+ *     before the INVITE arrived" case (SPEC §3.1) is an *intent* held on `Softphone`, above the
+ *     call — because there is no call yet to hold it. Same for a pre-INVITE reject, which registers
+ *     a UA specifically so it has something to send the 486 from.
+ */
+type CallState = 
+/** Inbound, INVITE received, not yet answered. */
+'ringing'
+/** Outbound, INVITE sent, no provisional response yet. */
+ | 'dialing'
+/** Outbound, remote is ringing (180/183). May carry early media. */
+ | 'early'
+/** Local answer in flight — 200 OK not yet confirmed. */
+ | 'answering'
+/** Media flowing. */
+ | 'active'
+/** Real SIP hold (`a=sendonly`), by either party. */
+ | 'held'
+/** Media lost, ICE restart in flight. The call is NOT over. */
+ | 'reconnecting'
+/** Terminal. */
+ | 'ended';
+type HoldOriginator = 'local' | 'remote';
+type HangupReason = 'local' | 'remote' | 'rejected' | 'busy' | 'no-answer' | 'transferred' | 'failed';
+/**
+ * The legal transitions, as data.
+ *
+ * A table rather than scattered `if`s: it is testable in isolation, it is the thing a reviewer can
+ * actually check against the diagram above, and an illegal transition becomes a caught bug instead
+ * of a silently wrong UI.
+ */
+declare const CALL_TRANSITIONS: {
+    readonly ringing: readonly ["answering", "ended"];
+    readonly dialing: readonly ["early", "active", "ended"];
+    readonly early: readonly ["active", "ended"];
+    readonly answering: readonly ["active", "ended"];
+    readonly active: readonly ["held", "reconnecting", "ended"];
+    readonly held: readonly ["active", "reconnecting", "ended"];
+    readonly reconnecting: readonly ["active", "held", "ended"];
+    readonly ended: readonly [];
+};
+/** The states a call can start in. Everything else is reached by transition. */
+declare const INITIAL_STATES: {
+    readonly inbound: "ringing";
+    readonly outbound: "dialing";
+};
+declare function canTransition(from: CallState, to: CallState): boolean;
+declare function isTerminal(state: CallState): boolean;
+/**
+ * A single call. Exists only while there is one — there is no `idle`.
+ *
+ * The attended-transfer consult leg is *also* a Call. That is what lets one state machine cover
+ * both, instead of today's separate `consultStatus`.
+ *
+ * Implementation lands in S2 (against MockProvider) and S3–S4 (against JsSIP/Zadarma).
+ */
+interface Call extends TypedEmitter<CallEventMap> {
+    readonly id: string;
+    readonly direction: CallDirection;
+    readonly state: CallState;
+    readonly remote: RemoteParty;
+    /** Wall-clock start of media. Null until `active`. */
+    readonly answeredAt: Date | null;
+    readonly isMuted: boolean;
+    readonly isOnHold: boolean;
+    /**
+     * The remote party's audio stream, once media is flowing (null before). Attach it to an
+     * `<audio autoplay>` element to hear the call. Also delivered via `CallEvent.RemoteStream`.
+     */
+    readonly remoteStream: MediaStream | null;
+    /** Only legal from `ringing`. Throws `call/not-answerable` otherwise. */
+    answer(): Promise<void>;
+    /** Only legal from `ringing`. Sends 486 Busy Here. */
+    reject(): Promise<void>;
+    /** Legal from any non-terminal state. Idempotent. */
+    hangup(): Promise<void>;
+    mute(muted: boolean): void;
+    /**
+     * Real SIP hold — a re-INVITE with `a=sendonly`, so the PBX can play hold music.
+     *
+     * Today this is FAKED by muting (SPEC §5.6): the held caller hears dead silence and cannot tell
+     * hold from a dropped call. JsSIP implements the real thing natively, so this is a handful of
+     * lines rather than the SIP work it looks like.
+     */
+    hold(): Promise<void>;
+    unhold(): Promise<void>;
+    sendDigits(digits: string): void;
+    /** Blind transfer (SIP REFER). Ends this call. */
+    transfer(target: string): Promise<void>;
+    /**
+     * Attended transfer, part 1: call the target while holding this call.
+     *
+     * Returns the consult leg — itself a Call, with its own state machine and events.
+     */
+    startConsult(target: string): Promise<Call>;
+    /** Attended transfer, part 2: bridge the two, ending both. (REFER … Replaces) */
+    completeTransfer(): Promise<void>;
+    /** Abandon the consult and resume this call. */
+    cancelConsult(): Promise<void>;
+}
+
+export { type AgentsDirectory as A, CALL_TRANSITIONS as C, ERROR_CATALOGUE as E, type FatalErrorCode as F, type HangupReason as H, INITIAL_STATES as I, type LogLevel as L, type NonFatalErrorCode as N, type RemoteParty as R, type SoftphoneConfig as S, type TokenEndpointOptions as T, type VoiceToken as V, type Call as a, type CallDirection as b, CallEvent as c, type CallEventMap as d, type CallOptions as e, type CallState as f, type Contact as g, type FatalSoftphoneError as h, type HoldOriginator as i, type NonFatalSoftphoneError as j, type SoftphoneError as k, type SoftphoneErrorCode as l, SoftphoneEvent as m, type SoftphoneEventMap as n, type SoftphoneState as o, type TokenSource as p, type TypedEmitter as q, canTransition as r, isFatal as s, isTerminal as t, type ContactsSource as u, type HistorySource as v, type CallHistoryEntry as w, type ContactsPage as x };