@coventia/softphone 0.1.0

package/dist/element/index.d.ts

@@ -0,0 +1,853 @@
+import { ReactNode } from 'react';
+
+/**
+ * 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';
+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[];
+}
+
+/** Contacts, history, caller ID and the agents directory, all from one config. */
+interface BackendSources {
+    readonly contacts: ContactsSource;
+    readonly history: HistorySource;
+    readonly resolveContact: (number: string) => Promise<Contact | null>;
+    /** The Historial tab's "filter by person" directory. Always Coventia's own org membership. */
+    readonly listAgents: () => Promise<AgentsDirectory>;
+}
+
+/**
+ * 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;
+
+/**
+ * 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';
+/**
+ * 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>;
+}
+
+/**
+ * Audio device control (SPEC §7 Phase 2). Reactive: `SoftphoneEvent.DeviceChange` fires whenever any
+ * field here changes — a device was plugged/unplugged, or a selection changed — so `useDevices()`
+ * (and any other listener) always reads a current snapshot rather than one frozen at mount.
+ */
+interface AudioDevices {
+    readonly inputs: readonly MediaDeviceInfo[];
+    readonly outputs: readonly MediaDeviceInfo[];
+    /**
+     * The currently-selected input/output, or `null` — no explicit choice made, the browser's own
+     * default is in use. Never a stale ID: if the selected device is unplugged, its selection is
+     * cleared back to `null` rather than pointing at a device that no longer exists.
+     */
+    readonly currentInputId: string | null;
+    readonly currentOutputId: string | null;
+    /**
+     * Re-enumerate. `inputs`/`outputs` already stay current on their own — a device physically
+     * plugged or unplugged fires the browser's own `devicechange` and needs no help — but a
+     * *permission* grant does not: the labels enumerate as blank strings until the microphone has been
+     * granted at least once, and granting it later fires no event at all. Call this when a UI surface
+     * that shows device names is about to become visible (SPEC §7 Phase 2 note: the settings tab calls
+     * it on mount for exactly this reason).
+     */
+    refresh(): Promise<void>;
+    /**
+     * Switches the microphone, or `null` to reset to the browser's own default device. Applies to the
+     * call in progress, if any — immediately, via `RTCRtpSender.replaceTrack`, no renegotiation and no
+     * interruption the far end can hear — and to every call placed or answered after this resolves.
+     */
+    setInput(deviceId: string | null): Promise<void>;
+    /**
+     * Switches where the REMOTE PARTY is heard, or `null` to reset to the browser's own default
+     * device. Applies instantly, live call or not — output routing needs no WebRTC renegotiation at
+     * all, unlike the input side.
+     *
+     * A no-op (resolves immediately) when `canSelectOutput` is false.
+     */
+    setOutput(deviceId: string | null): Promise<void>;
+    /**
+     * The RINGTONE output, separate from the call speaker.
+     *
+     * Of every SDK surveyed only Twilio ships this, and users want it: ring on the laptop speakers so
+     * you hear it across the room, take the call in the headset.
+     *
+     * **Not yet implemented** — still Phase 2 groundwork, like `NoopAudioDevices` before it. Calling it
+     * resolves without effect until a later pass wires it up.
+     */
+    setRingtoneOutput(deviceId: string | null): Promise<void>;
+    /** False when the browser lacks `setSinkId` (Safari, most of Firefox) — `setOutput` is then a no-op. */
+    readonly canSelectOutput: boolean;
+}
+/**
+ * The engine. Long-lived; owns registration, credentials, devices, and the provider.
+ *
+ * Implementation lands in S2.
+ */
+interface Softphone extends TypedEmitter<SoftphoneEventMap> {
+    readonly state: SoftphoneState;
+    /**
+     * The last **fatal** error, or `null` — the reason the phone cannot currently be used.
+     *
+     * State rather than only an event, because the common case is: the phone breaks, and *then* the
+     * user opens the panel to find out why. A widget that mounts after the failure would never see
+     * `SoftphoneEvent.Error`, and would render a dialpad with no explanation for why it does nothing.
+     *
+     * **Cleared when the softphone next reaches `online`** — the only evidence available that whatever
+     * was wrong no longer is. Non-fatal errors are emitted but never set this: a busy tone is a fact
+     * about one call, not a broken phone.
+     */
+    readonly lastError: FatalSoftphoneError | null;
+    /**
+     * Whether THIS tab is the one allowed to be reachable (`multi-tab-leader-election.md`).
+     *
+     * Zadarma's on-demand registration means two tabs open for the same extension race each other to
+     * register on every inbound push — confirmed live, exactly one tab rings, unpredictably which. At
+     * most one open tab is ever the leader at a time; leadership passes to the next tab automatically
+     * (no reload) the moment the current leader closes, reloads, or crashes.
+     *
+     * `false` by default and while waiting for another tab to release it — a host should show its own
+     * "active in another tab" state for that duration (the `/ui` widget already does).
+     */
+    readonly isLeader: boolean;
+    /**
+     * Start.
+     *
+     * **Call this from a user gesture.** Both the microphone permission prompt and the browser's
+     * autoplay policy key off user activation. Twilio's own docs name this as the cause of *missed
+     * calls*: with no activation, the incoming-call ringtone is silently blocked and the agent never
+     * knows anyone rang.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Idempotent. After this the instance is dead — construct a new one. */
+    destroy(): Promise<void>;
+    call(destination: string, options?: CallOptions): Promise<Call>;
+    /** The live call, or null. The consult leg of an attended transfer is reachable from it. */
+    readonly activeCall: Call | null;
+    /**
+     * Contacts + history, when `SoftphoneConfig.coventia` was given; `null` otherwise.
+     *
+     * The widget reads these rather than being handed a config, so there is exactly ONE set per
+     * softphone — one name cache, one of every request.
+     */
+    readonly sources: BackendSources | null;
+    readonly audio: AudioDevices;
+    /**
+     * False when the browser has blocked audio playback.
+     *
+     * When false, an incoming call RINGS SILENTLY. Surface a button; call `startAudio()` from its
+     * click handler. This is the failure mode almost every voice SDK leaves undocumented.
+     */
+    readonly canPlayAudio: boolean;
+    /** Must be called from within a user gesture. */
+    startAudio(): Promise<void>;
+}
+
+/**
+ * Shaped like a Lucide icon (`size`, `className`, both optional — every SVG prop Lucide's own icons
+ * take is optional too, so a real Lucide component satisfies this structurally) WITHOUT naming
+ * `lucide-react`'s own exported type. A host should not need that package installed just to satisfy
+ * ours — this accepts Lucide itself, or any icon set built the same shape.
+ */
+type ContactActionIcon = (props: {
+    readonly size?: number | string;
+    readonly className?: string;
+}) => ReactNode;
+/**
+ * The one customisable action on a contact's detail page — was the legacy's hard-wired "Ver
+ * mensajes" (`useNavigate('/chats?wa_id=…')`), now genuinely the host's: whatever `onClick` does,
+ * under whatever `label` fits it. "Open a support ticket," "Ver ficha en el CRM," anything.
+ *
+ * Omit `contactAction` entirely and the row simply does not exist — the detail page is then just
+ * the avatar, the name, the phone number, and the call button. A row with a hardcoded label and no
+ * handler would be worse than no row at all.
+ *
+ * Deliberately NOT a render prop (no arbitrary React node accepted here). Every other host-supplied
+ * piece of this widget is DATA — a contacts function, a history array, a callback — never a chunk of
+ * JSX to render as-is; that is what keeps the widget looking like one thing instead of drifting row
+ * by row. `icon` is optional so a partner without a natural icon for their action is not forced to
+ * pick one.
+ */
+interface ContactAction {
+    readonly label: string;
+    readonly icon?: ContactActionIcon;
+    readonly onClick: (contact: Contact) => void;
+}
+
+/**
+ * `'system'` (default) follows the OS via `prefers-color-scheme`. Pin it to match the HOST's theme
+ * instead — the CRM toggles dark with a class (next-themes), not the OS, so a dark OS + light app
+ * would otherwise render a dark widget inside a light page.
+ *
+ *   const { resolvedTheme } = useTheme();
+ *   <SoftphoneWidget theme={resolvedTheme} />
+ */
+type SoftphoneTheme = 'light' | 'dark' | 'system';
+
+/**
+ * Config that cannot be expressed as HTML attributes.
+ *
+ * Attributes are strings; `contacts`/`history`/`contactAction` carry FUNCTIONS. So this is set as a
+ * JS PROPERTY, not an attribute — one line in vanilla JS or a PHP-rendered page. (`theme` is a
+ * string, so it is also available as the `theme` attribute.)
+ */
+interface SoftphoneElementConfig {
+    /**
+     * Ask for the microphone before showing the dialer. **On by default** — see
+     * `SoftphoneWidgetProps.requireMic`. Set `false` only when the mic is somebody else's problem.
+     */
+    readonly requireMic?: boolean;
+    /**
+     * Play call audio — the remote party, the inbound ring, the outbound ringback. **On by default**;
+     * see `SoftphoneWidgetProps.sounds`.
+     *
+     * Turning this off makes a connected call silent in both directions, because nothing else attaches
+     * the remote `MediaStream`. Only correct when the host attaches `call.remoteStream` itself, or for
+     * a view that watches calls without listening to them.
+     */
+    readonly sounds?: boolean;
+    readonly contacts?: ContactsSource;
+    readonly history?: HistorySource;
+    /** The action row on a contact's detail page. See `ContactAction` from `@coventia/softphone/ui`. */
+    readonly contactAction?: ContactAction;
+    /**
+     * A second, independent action chip on the INCOMING call screen — see `ContactAction` and
+     * `SoftphoneWidgetProps.incomingCallAction`. A different value from `contactAction`, not the same
+     * one reused; a host may configure either, both, or neither.
+     */
+    readonly incomingCallAction?: ContactAction;
+    readonly theme?: SoftphoneTheme;
+}
+/**
+ * Every CustomEvent the element dispatches, with its payload. The single source of truth for both
+ * sides of the wire.
+ *
+ * **Emitting** (`#emit`): fully checked — a name outside this map, or a payload that does not match
+ * it, is a compile error.
+ *
+ * **Listening**: merged into the DOM's event maps below, so a TypeScript consumer gets the name
+ * autocompleted and `e.detail` narrowed, with no cast. One honest gap — a MISSPELLED name is not
+ * rejected outright: `addEventListener(type: string, …)` is a real DOM overload and must accept any
+ * string, or arbitrary CustomEvents would be unlistenable. The typo surfaces one step later, as
+ * "Property 'detail' does not exist on type 'Event'", since the fallback overload hands back a plain
+ * `Event`. So a typo is caught if the handler reads the payload, and silent if it ignores it.
+ */
+interface SoftphoneElementEventMap {
+    /** The connection state changed (registering, ready, reconnecting…). */
+    'cv-state-changed': CustomEvent<{
+        readonly state: SoftphoneState;
+    }>;
+    /** An inbound INVITE landed. `name` IS the number until a contact resolves (SPEC §5.4). */
+    'cv-incoming-call': CustomEvent<{
+        readonly number: string;
+        readonly name: string;
+    }>;
+    /** A call became the active one, in either direction. */
+    'cv-call-started': CustomEvent<{
+        readonly number: string;
+        readonly direction: CallDirection;
+    }>;
+    /** The active call ended, for `reason`. */
+    'cv-call-ended': CustomEvent<{
+        readonly number: string;
+        readonly reason: HangupReason;
+    }>;
+    /**
+     * Something failed. **The widget has already shown the user why** — a fatal error replaces the
+     * dialpad, a call outcome appears as a line under the number — so this is for the host's own
+     * logging, toasts or call records, not for building an error UI that would say it twice.
+     *
+     * `message` is the DEVELOPER's sentence and is English (see `ERROR_CATALOGUE`). It belongs in a log
+     * or a Sentry group, never on screen. The user's Spanish copy is the widget's business.
+     *
+     * `fatal` is the split worth branching on: `true` means calling is impossible until something
+     * changes, `false` means one call ended badly and the phone is still fine.
+     */
+    'cv-error': CustomEvent<{
+        readonly code: SoftphoneErrorCode;
+        readonly fatal: boolean;
+        readonly message: string;
+    }>;
+    /**
+     * This tab's leadership changed (`multi-tab-leader-election.md`) — a DIFFERENT axis from
+     * `cv-state-changed`: that is reachability, this is whether this tab is even allowed to be
+     * reachable while another open tab holds the same extension.
+     */
+    'cv-leadership-changed': CustomEvent<{
+        readonly isLeader: boolean;
+    }>;
+}
+declare global {
+    /** `document.querySelector('coventia-softphone')` returns the real type — no cast to set `.softphone`. */
+    interface HTMLElementTagNameMap {
+        'coventia-softphone': CoventiaSoftphoneElement;
+    }
+    /** Types `el.addEventListener` — and any ANCESTOR's, since these events bubble. */
+    interface HTMLElementEventMap extends SoftphoneElementEventMap {
+    }
+    /**
+     * Types `document.addEventListener` too. Needed separately: `DocumentEventMap` extends
+     * `GlobalEventHandlersEventMap`, NOT `HTMLElementEventMap` — so augmenting the element map alone
+     * would leave the most common listening spot for a `composed` event untyped.
+     */
+    interface DocumentEventMap extends SoftphoneElementEventMap {
+    }
+}
+declare class CoventiaSoftphoneElement extends HTMLElement {
+    #private;
+    /**
+     * `require-mic` and `sounds` are here so a host with **no JavaScript at all** can turn them off —
+     * a PHP/WordPress page or a CDN `<script>` drop-in, which is the whole point of this entry. The
+     * function-valued config (contacts, history, contactAction) can never be attributes; these two
+     * are booleans and have no such excuse.
+     */
+    static readonly observedAttributes: string[];
+    constructor();
+    /**
+     * The engine. REQUIRED — the host constructs it, so it owns the connection's lifetime and can keep
+     * a call alive across re-renders/navigations (SPEC §5.1).
+     *
+     *   el.softphone = createSoftphone({ tokenSource, provider: createZadarmaEngine({…}) });
+     */
+    get softphone(): Softphone | null;
+    set softphone(value: Softphone | null);
+    /** Config carrying functions (contacts/history/contactAction) — a property, not an attribute. */
+    get config(): SoftphoneElementConfig;
+    set config(value: SoftphoneElementConfig);
+    connectedCallback(): void;
+    /**
+     * Moving a node in the DOM fires disconnect→connect **synchronously**, so nothing may be torn down
+     * here: by the next microtask the element may be connected again. Deferring the decision — not just
+     * the unmount — is what makes a move survivable. Two things go wrong if you tear down eagerly:
+     *
+     *   - `#detach()` here kills the engine subscriptions, and `#attach()` would not run again → the
+     *     widget still renders but `cv-*` events stop forever. Silent, and invisible in the UI.
+     *   - Nulling `#root` here makes the reconnect's `??=` call `createRoot` on a container that
+     *     already has a root ("You are calling createRoot() on a container that has already been
+     *     passed to createRoot()") — two roots on one div.
+     *
+     * The unmount stays asynchronous regardless: React forbids unmounting synchronously from inside a
+     * lifecycle it may still be rendering.
+     */
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+}
+/** Register the element. Idempotent — a page may load the bundle more than once. */
+declare function defineSoftphoneElement(tagName?: string): void;
+
+export { CoventiaSoftphoneElement, type SoftphoneElementConfig, type SoftphoneElementEventMap, defineSoftphoneElement };