@coventia/softphone 0.4.0 → 0.5.1

package/dist/{call-C6YpT6uR.d.cts → call-iGvr2ZnO.d.cts}

@@ -86,10 +86,10 @@ interface TokenEndpointOptions {
  */
 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.
+     * Coventia's domain, like `SoftphoneConfig.apiBase`: no path, the SDK builds every route.
+     * **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;
     /**
@@ -104,7 +104,10 @@ interface CoventiaBackendConfig {
      * That is the CRM today.
      */
     readonly organizationId?: string;
-    /** `/phone` today; `/api/v1/phone` once the partner API ships (SPEC §6.6). */
+    /**
+     * Where the phone routes sit under the base URL. Internal: leave it unset (`/phone`). The routes are
+     * the SDK's to build, which is why `apiBase` is the domain only.
+     */
     readonly basePath?: string;
     /**
      * **The one thing a provider customises**: their own contact list, searched on their own backend.
@@ -134,8 +137,11 @@ interface CoventiaBackendConfig {
 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.
+     * Coventia's domain — **only the domain**, e.g. `https://backend.example.com`, with no path: the SDK
+     * builds every route itself. Not the Partner API URL your backend calls: that one ends in `/api/v1`,
+     * which does not belong here (it is ignored, with a console warning). **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
@@ -188,8 +194,62 @@ interface CallOptions {
  * 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.
+ *
+ * `standby` means started, and this browser's leader, but ANOTHER softphone of the same extension has
+ * the line — a tab in another browser, the desktop app, a partner page (`docs/specs/line-owner.md` §5).
+ * Its push socket is closed on purpose, so nothing here registers or rings: `line` says where the calls
+ * go, and `takeLine()` — or a `call()` — brings them here. A host that reads `online` as "ready"
+ * correctly reads this as not ready.
+ */
+type SoftphoneState = 'stopped' | 'starting' | 'online' | 'standby' | 'offline' | 'reconnecting' | 'destroyed';
+/**
+ * Where this extension's incoming calls ring, as far as this softphone knows. `here`: it has the line.
+ * `elsewhere`: another softphone of the same extension has it, and this one waits in `standby`. `unknown`:
+ * nobody has said — no presence source, a backend that predates the line owner, a presence socket that is
+ * down — and this softphone listens, exactly as before the line owner existed (§5.1 R7, fail-open).
  */
-type SoftphoneState = 'stopped' | 'starting' | 'online' | 'offline' | 'reconnecting' | 'destroyed';
+type LineState = 'here' | 'elsewhere' | 'unknown';
+/** Who has the line when it is `elsewhere`: the desktop app, or any other softphone (a browser tab). */
+type LineLocation = 'desktop' | 'browser';
+/**
+ * The last attempt to bring the line here — `takeLine()`, or a `call()` from `standby`, whoever made it:
+ * `claiming` while it is in flight, `refused` when the user is on a call where the line is, `failed` when
+ * nothing could decide. `idle` before any attempt, once the line comes here, and after a `stop()`.
+ */
+type LineClaim = 'idle' | 'claiming' | 'refused' | 'failed';
+/** The server's word on this softphone's line, as a `PresenceSource` hands it over (`PresenceCallbacks.onLine`). */
+interface LineUpdate {
+    readonly state: 'here' | 'elsewhere';
+    /** Who has the line when it is `elsewhere`; `null` when it is here, or the server did not say. */
+    readonly where: LineLocation | null;
+}
+/**
+ * A call offered to this user's line, as the backend announces it over the presence socket
+ * (incoming-call-reliability.md §5): `start` each time the call is offered to the extension (a re-offer of the
+ * same call repeats it, same `callId`), `end` when the call is over. `callId` is opaque; `from` is the caller,
+ * `null` (or, on an `end`, absent) when the backend did not say.
+ *
+ * The softphone uses it for one thing: after a decline, to know when the declined call's re-offers stop, so a
+ * new call from the same number rings (§4.4). A presence source that never sends it loses nothing but that.
+ */
+type CallOffer = {
+    readonly state: 'start';
+    readonly callId: string;
+    readonly from: string | null;
+} | {
+    readonly state: 'end';
+    readonly callId: string;
+    readonly from?: string | null;
+};
+/** The answer to `PresenceConnection.claimLine()`. */
+interface LineClaimResult {
+    readonly ok: boolean;
+    /**
+     * Why it was refused: `'on_call'` while the user is on a call (the line never moves during one). Any
+     * other value means nothing was decided. Absent when `ok`.
+     */
+    readonly reason?: string;
+}
 interface ContactsPage {
     readonly items: readonly Contact[];
     /**
@@ -349,6 +409,18 @@ interface PresenceConnection {
      * own source that has no such message simply omits it and gets the grace. Sent just before `close()`.
      */
     readonly bye?: () => void;
+    /**
+     * The line owner (`docs/specs/line-owner.md` §5.2): says which softphone this connection speaks for, so
+     * the server can tell it whether it has the line — through `PresenceCallbacks.onLine`, right after this
+     * and on every change. Sent as the FIRST message of every connection. Optional: a source without it never
+     * takes part, and its softphone listens exactly as before (fail-open), reading its line as `unknown`.
+     */
+    readonly hello?: (clientId: string) => void;
+    /**
+     * "Recibir aquí": asks for the line. Answered through `PresenceCallbacks.onClaimResult` — and, when it
+     * succeeds, by `onLine` saying `here` first. Optional, like `hello`.
+     */
+    readonly claimLine?: () => void;
     /**
      * Ends this connection deliberately. Never causes the SAME callbacks' `onClose` to fire — that is
      * reserved for the connection ending on its OWN (a network drop, a server-side close, a rejected
@@ -368,6 +440,19 @@ interface PresenceCallbacks {
      * identical from here, and both get the same treatment (spec §4.4 — quiet retry, nothing surfaced).
      */
     readonly onClose: () => void;
+    /**
+     * The line, as the server says it — right after `PresenceConnection.hello`, and on every change after
+     * that. Optional, so callbacks written before the line owner existed still type-check.
+     */
+    readonly onLine?: (update: LineUpdate) => void;
+    /** The answer to `PresenceConnection.claimLine()`. Optional, like `onLine`. */
+    readonly onClaimResult?: (result: LineClaimResult) => void;
+    /**
+     * A call offered to this line started or ended (`CallOffer`). Sent only to the line's owner. Optional, like
+     * `onLine`: callbacks written before it existed still type-check, and a source that never calls it leaves the
+     * softphone on its fallback after a decline (incoming-call-reliability.md §4.4).
+     */
+    readonly onOffer?: (offer: CallOffer) => void;
 }
 /**
  * Opens one live presence connection. Coventia-backed by default (mints a one-time ticket, opens
@@ -598,6 +683,16 @@ declare const ERROR_CATALOGUE: {
         readonly message: "The provider does not support this operation.";
         readonly solution: "Guard the UI on the operation before offering it.";
     };
+    readonly 'line/claim-refused': {
+        readonly fatal: false;
+        readonly message: "The line was not moved here: the user is on a call on the softphone that has it.";
+        readonly solution: "Nothing to fix. The line never moves during a call; take it again once that call has ended. Incoming calls keep ringing where they ring now.";
+    };
+    readonly 'line/unavailable': {
+        readonly fatal: false;
+        readonly message: "The line could not be taken: nothing decided where it is.";
+        readonly solution: "The presence connection is down, the backend predates the line owner, or it did not answer in time. Retry in a moment; incoming calls keep ringing where they ring now.";
+    };
     readonly 'provider/provision-failed': {
         readonly fatal: true;
         readonly message: "The provider could not issue SIP credentials.";
@@ -686,10 +781,25 @@ declare enum SoftphoneEvent {
     /**
      * `softphone.presence` changed — the live agent-presence list (Phase B,
      * `docs/specs/transfer-presence-picker.md`) gained a snapshot or an updated entry. Requires a
-     * `PresenceSource` (from `coventia`/`apiBase`, or a host override) AND this tab currently being
-     * `online && isLeader`; never fires at all otherwise, same reasoning as `TransferOutcome`.
+     * `PresenceSource` (from `coventia`/`apiBase`, or a host override) AND this tab currently being a
+     * started leader — `online`, or waiting in `standby` for the line; never fires at all otherwise,
+     * same reasoning as `TransferOutcome`.
+     */
+    PresenceChanged = "presenceChanged",
+    /**
+     * `softphone.line` / `lineWhere` changed (`docs/specs/line-owner.md` §5): this softphone got the line,
+     * lost it to another softphone of the same extension, or stopped knowing (`unknown` — it then listens,
+     * as before the line owner existed). A third axis beside `StateChanged` and `LeaderChanged`: losing the
+     * line is what takes the softphone to `standby`, but not at once while a call is in progress — the line
+     * can read `elsewhere` while the state is still `online`, until that call ends.
      */
-    PresenceChanged = "presenceChanged"
+    LineChanged = "lineChanged",
+    /**
+     * `softphone.lineClaim` changed: an attempt to bring the line here started, was refused, failed, or ended
+     * (the line came here, or the softphone stopped). Kept apart from `LineChanged`, which only ever means the
+     * line itself moved.
+     */
+    LineClaimChanged = "lineClaimChanged"
 }
 interface SoftphoneEventMap {
     [SoftphoneEvent.StateChanged]: {
@@ -710,6 +820,13 @@ interface SoftphoneEventMap {
     [SoftphoneEvent.PresenceChanged]: {
         readonly agents: readonly PresenceEntry[];
     };
+    [SoftphoneEvent.LineChanged]: {
+        readonly line: LineState;
+        readonly where: LineLocation | null;
+    };
+    [SoftphoneEvent.LineClaimChanged]: {
+        readonly claim: LineClaim;
+    };
 }
 declare enum CallEvent {
     /** Any transition. The catch-all; the specific events below are conveniences. */
@@ -810,7 +927,7 @@ interface TypedEmitter<M> {
  *
  *   - **`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
+ *     `providers/zadarma.ts` as `quirks.declinedCallerGuardMs`, 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
@@ -936,4 +1053,4 @@ interface Call extends TypedEmitter<CallEventMap> {
     cancelConsult(): Promise<void>;
 }
 
-export { isFatal as A, isTerminal as B, CALL_TRANSITIONS as C, type ContactsSource as D, ERROR_CATALOGUE as E, type FatalErrorCode as F, type HistorySource as G, type HangupReason as H, INITIAL_STATES as I, type AgentsDirectory as J, type TransferOutcomesPage as K, type LogLevel as L, type PresenceSource as M, type NonFatalErrorCode as N, type OutboundNumberRefusal as O, type PresenceEntry as P, type CallHistoryEntry as Q, type RemoteParty as R, type SoftphoneConfig as S, type TokenEndpointOptions as T, type ContactsPage as U, 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 OutboundNumber as k, type OutboundNumberKind as l, type OutboundNumberSettings as m, type OutboundNumberState as n, type OutboundNumbersSource as o, type RingtoneOption as p, type RingtoneSettings as q, type RingtoneSource as r, type SoftphoneError as s, type SoftphoneErrorCode as t, SoftphoneEvent as u, type SoftphoneEventMap as v, type SoftphoneState as w, type TokenSource as x, type TypedEmitter as y, canTransition as z };
+export { type TokenSource as A, type TypedEmitter as B, CALL_TRANSITIONS as C, canTransition as D, ERROR_CATALOGUE as E, type FatalErrorCode as F, isFatal as G, type HangupReason as H, INITIAL_STATES as I, isTerminal as J, type ContactsSource as K, type LineClaim as L, type HistorySource as M, type NonFatalErrorCode as N, type OutboundNumberRefusal as O, type PresenceEntry as P, type AgentsDirectory as Q, type RemoteParty as R, type SoftphoneConfig as S, type TokenEndpointOptions as T, type TransferOutcomesPage as U, type VoiceToken as V, type PresenceSource as W, type CallHistoryEntry as X, type ContactsPage as Y, type CallOffer as Z, 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 LineLocation as j, type LineState as k, type LogLevel as l, type NonFatalSoftphoneError as m, type OutboundNumber as n, type OutboundNumberKind as o, type OutboundNumberSettings as p, type OutboundNumberState as q, type OutboundNumbersSource as r, type RingtoneOption as s, type RingtoneSettings as t, type RingtoneSource as u, type SoftphoneError as v, type SoftphoneErrorCode as w, SoftphoneEvent as x, type SoftphoneEventMap as y, type SoftphoneState as z };

package/dist/{call-C6YpT6uR.d.ts → call-iGvr2ZnO.d.ts}

@@ -86,10 +86,10 @@ interface TokenEndpointOptions {
  */
 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.
+     * Coventia's domain, like `SoftphoneConfig.apiBase`: no path, the SDK builds every route.
+     * **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;
     /**
@@ -104,7 +104,10 @@ interface CoventiaBackendConfig {
      * That is the CRM today.
      */
     readonly organizationId?: string;
-    /** `/phone` today; `/api/v1/phone` once the partner API ships (SPEC §6.6). */
+    /**
+     * Where the phone routes sit under the base URL. Internal: leave it unset (`/phone`). The routes are
+     * the SDK's to build, which is why `apiBase` is the domain only.
+     */
     readonly basePath?: string;
     /**
      * **The one thing a provider customises**: their own contact list, searched on their own backend.
@@ -134,8 +137,11 @@ interface CoventiaBackendConfig {
 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.
+     * Coventia's domain — **only the domain**, e.g. `https://backend.example.com`, with no path: the SDK
+     * builds every route itself. Not the Partner API URL your backend calls: that one ends in `/api/v1`,
+     * which does not belong here (it is ignored, with a console warning). **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
@@ -188,8 +194,62 @@ interface CallOptions {
  * 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.
+ *
+ * `standby` means started, and this browser's leader, but ANOTHER softphone of the same extension has
+ * the line — a tab in another browser, the desktop app, a partner page (`docs/specs/line-owner.md` §5).
+ * Its push socket is closed on purpose, so nothing here registers or rings: `line` says where the calls
+ * go, and `takeLine()` — or a `call()` — brings them here. A host that reads `online` as "ready"
+ * correctly reads this as not ready.
+ */
+type SoftphoneState = 'stopped' | 'starting' | 'online' | 'standby' | 'offline' | 'reconnecting' | 'destroyed';
+/**
+ * Where this extension's incoming calls ring, as far as this softphone knows. `here`: it has the line.
+ * `elsewhere`: another softphone of the same extension has it, and this one waits in `standby`. `unknown`:
+ * nobody has said — no presence source, a backend that predates the line owner, a presence socket that is
+ * down — and this softphone listens, exactly as before the line owner existed (§5.1 R7, fail-open).
  */
-type SoftphoneState = 'stopped' | 'starting' | 'online' | 'offline' | 'reconnecting' | 'destroyed';
+type LineState = 'here' | 'elsewhere' | 'unknown';
+/** Who has the line when it is `elsewhere`: the desktop app, or any other softphone (a browser tab). */
+type LineLocation = 'desktop' | 'browser';
+/**
+ * The last attempt to bring the line here — `takeLine()`, or a `call()` from `standby`, whoever made it:
+ * `claiming` while it is in flight, `refused` when the user is on a call where the line is, `failed` when
+ * nothing could decide. `idle` before any attempt, once the line comes here, and after a `stop()`.
+ */
+type LineClaim = 'idle' | 'claiming' | 'refused' | 'failed';
+/** The server's word on this softphone's line, as a `PresenceSource` hands it over (`PresenceCallbacks.onLine`). */
+interface LineUpdate {
+    readonly state: 'here' | 'elsewhere';
+    /** Who has the line when it is `elsewhere`; `null` when it is here, or the server did not say. */
+    readonly where: LineLocation | null;
+}
+/**
+ * A call offered to this user's line, as the backend announces it over the presence socket
+ * (incoming-call-reliability.md §5): `start` each time the call is offered to the extension (a re-offer of the
+ * same call repeats it, same `callId`), `end` when the call is over. `callId` is opaque; `from` is the caller,
+ * `null` (or, on an `end`, absent) when the backend did not say.
+ *
+ * The softphone uses it for one thing: after a decline, to know when the declined call's re-offers stop, so a
+ * new call from the same number rings (§4.4). A presence source that never sends it loses nothing but that.
+ */
+type CallOffer = {
+    readonly state: 'start';
+    readonly callId: string;
+    readonly from: string | null;
+} | {
+    readonly state: 'end';
+    readonly callId: string;
+    readonly from?: string | null;
+};
+/** The answer to `PresenceConnection.claimLine()`. */
+interface LineClaimResult {
+    readonly ok: boolean;
+    /**
+     * Why it was refused: `'on_call'` while the user is on a call (the line never moves during one). Any
+     * other value means nothing was decided. Absent when `ok`.
+     */
+    readonly reason?: string;
+}
 interface ContactsPage {
     readonly items: readonly Contact[];
     /**
@@ -349,6 +409,18 @@ interface PresenceConnection {
      * own source that has no such message simply omits it and gets the grace. Sent just before `close()`.
      */
     readonly bye?: () => void;
+    /**
+     * The line owner (`docs/specs/line-owner.md` §5.2): says which softphone this connection speaks for, so
+     * the server can tell it whether it has the line — through `PresenceCallbacks.onLine`, right after this
+     * and on every change. Sent as the FIRST message of every connection. Optional: a source without it never
+     * takes part, and its softphone listens exactly as before (fail-open), reading its line as `unknown`.
+     */
+    readonly hello?: (clientId: string) => void;
+    /**
+     * "Recibir aquí": asks for the line. Answered through `PresenceCallbacks.onClaimResult` — and, when it
+     * succeeds, by `onLine` saying `here` first. Optional, like `hello`.
+     */
+    readonly claimLine?: () => void;
     /**
      * Ends this connection deliberately. Never causes the SAME callbacks' `onClose` to fire — that is
      * reserved for the connection ending on its OWN (a network drop, a server-side close, a rejected
@@ -368,6 +440,19 @@ interface PresenceCallbacks {
      * identical from here, and both get the same treatment (spec §4.4 — quiet retry, nothing surfaced).
      */
     readonly onClose: () => void;
+    /**
+     * The line, as the server says it — right after `PresenceConnection.hello`, and on every change after
+     * that. Optional, so callbacks written before the line owner existed still type-check.
+     */
+    readonly onLine?: (update: LineUpdate) => void;
+    /** The answer to `PresenceConnection.claimLine()`. Optional, like `onLine`. */
+    readonly onClaimResult?: (result: LineClaimResult) => void;
+    /**
+     * A call offered to this line started or ended (`CallOffer`). Sent only to the line's owner. Optional, like
+     * `onLine`: callbacks written before it existed still type-check, and a source that never calls it leaves the
+     * softphone on its fallback after a decline (incoming-call-reliability.md §4.4).
+     */
+    readonly onOffer?: (offer: CallOffer) => void;
 }
 /**
  * Opens one live presence connection. Coventia-backed by default (mints a one-time ticket, opens
@@ -598,6 +683,16 @@ declare const ERROR_CATALOGUE: {
         readonly message: "The provider does not support this operation.";
         readonly solution: "Guard the UI on the operation before offering it.";
     };
+    readonly 'line/claim-refused': {
+        readonly fatal: false;
+        readonly message: "The line was not moved here: the user is on a call on the softphone that has it.";
+        readonly solution: "Nothing to fix. The line never moves during a call; take it again once that call has ended. Incoming calls keep ringing where they ring now.";
+    };
+    readonly 'line/unavailable': {
+        readonly fatal: false;
+        readonly message: "The line could not be taken: nothing decided where it is.";
+        readonly solution: "The presence connection is down, the backend predates the line owner, or it did not answer in time. Retry in a moment; incoming calls keep ringing where they ring now.";
+    };
     readonly 'provider/provision-failed': {
         readonly fatal: true;
         readonly message: "The provider could not issue SIP credentials.";
@@ -686,10 +781,25 @@ declare enum SoftphoneEvent {
     /**
      * `softphone.presence` changed — the live agent-presence list (Phase B,
      * `docs/specs/transfer-presence-picker.md`) gained a snapshot or an updated entry. Requires a
-     * `PresenceSource` (from `coventia`/`apiBase`, or a host override) AND this tab currently being
-     * `online && isLeader`; never fires at all otherwise, same reasoning as `TransferOutcome`.
+     * `PresenceSource` (from `coventia`/`apiBase`, or a host override) AND this tab currently being a
+     * started leader — `online`, or waiting in `standby` for the line; never fires at all otherwise,
+     * same reasoning as `TransferOutcome`.
+     */
+    PresenceChanged = "presenceChanged",
+    /**
+     * `softphone.line` / `lineWhere` changed (`docs/specs/line-owner.md` §5): this softphone got the line,
+     * lost it to another softphone of the same extension, or stopped knowing (`unknown` — it then listens,
+     * as before the line owner existed). A third axis beside `StateChanged` and `LeaderChanged`: losing the
+     * line is what takes the softphone to `standby`, but not at once while a call is in progress — the line
+     * can read `elsewhere` while the state is still `online`, until that call ends.
      */
-    PresenceChanged = "presenceChanged"
+    LineChanged = "lineChanged",
+    /**
+     * `softphone.lineClaim` changed: an attempt to bring the line here started, was refused, failed, or ended
+     * (the line came here, or the softphone stopped). Kept apart from `LineChanged`, which only ever means the
+     * line itself moved.
+     */
+    LineClaimChanged = "lineClaimChanged"
 }
 interface SoftphoneEventMap {
     [SoftphoneEvent.StateChanged]: {
@@ -710,6 +820,13 @@ interface SoftphoneEventMap {
     [SoftphoneEvent.PresenceChanged]: {
         readonly agents: readonly PresenceEntry[];
     };
+    [SoftphoneEvent.LineChanged]: {
+        readonly line: LineState;
+        readonly where: LineLocation | null;
+    };
+    [SoftphoneEvent.LineClaimChanged]: {
+        readonly claim: LineClaim;
+    };
 }
 declare enum CallEvent {
     /** Any transition. The catch-all; the specific events below are conveniences. */
@@ -810,7 +927,7 @@ interface TypedEmitter<M> {
  *
  *   - **`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
+ *     `providers/zadarma.ts` as `quirks.declinedCallerGuardMs`, 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
@@ -936,4 +1053,4 @@ interface Call extends TypedEmitter<CallEventMap> {
     cancelConsult(): Promise<void>;
 }
 
-export { isFatal as A, isTerminal as B, CALL_TRANSITIONS as C, type ContactsSource as D, ERROR_CATALOGUE as E, type FatalErrorCode as F, type HistorySource as G, type HangupReason as H, INITIAL_STATES as I, type AgentsDirectory as J, type TransferOutcomesPage as K, type LogLevel as L, type PresenceSource as M, type NonFatalErrorCode as N, type OutboundNumberRefusal as O, type PresenceEntry as P, type CallHistoryEntry as Q, type RemoteParty as R, type SoftphoneConfig as S, type TokenEndpointOptions as T, type ContactsPage as U, 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 OutboundNumber as k, type OutboundNumberKind as l, type OutboundNumberSettings as m, type OutboundNumberState as n, type OutboundNumbersSource as o, type RingtoneOption as p, type RingtoneSettings as q, type RingtoneSource as r, type SoftphoneError as s, type SoftphoneErrorCode as t, SoftphoneEvent as u, type SoftphoneEventMap as v, type SoftphoneState as w, type TokenSource as x, type TypedEmitter as y, canTransition as z };
+export { type TokenSource as A, type TypedEmitter as B, CALL_TRANSITIONS as C, canTransition as D, ERROR_CATALOGUE as E, type FatalErrorCode as F, isFatal as G, type HangupReason as H, INITIAL_STATES as I, isTerminal as J, type ContactsSource as K, type LineClaim as L, type HistorySource as M, type NonFatalErrorCode as N, type OutboundNumberRefusal as O, type PresenceEntry as P, type AgentsDirectory as Q, type RemoteParty as R, type SoftphoneConfig as S, type TokenEndpointOptions as T, type TransferOutcomesPage as U, type VoiceToken as V, type PresenceSource as W, type CallHistoryEntry as X, type ContactsPage as Y, type CallOffer as Z, 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 LineLocation as j, type LineState as k, type LogLevel as l, type NonFatalSoftphoneError as m, type OutboundNumber as n, type OutboundNumberKind as o, type OutboundNumberSettings as p, type OutboundNumberState as q, type OutboundNumbersSource as r, type RingtoneOption as s, type RingtoneSettings as t, type RingtoneSource as u, type SoftphoneError as v, type SoftphoneErrorCode as w, SoftphoneEvent as x, type SoftphoneEventMap as y, type SoftphoneState as z };