@coventia/softphone 0.3.0 → 0.5.0

package/dist/{call-CaPDWVk3.d.cts → call-FqcvDg1t.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,44 @@ 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 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 SoftphoneState = 'stopped' | 'starting' | 'online' | 'offline' | 'reconnecting' | 'destroyed';
+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;
+}
+/** 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[];
     /**
@@ -240,6 +282,11 @@ interface CallHistoryEntry {
     readonly outcome?: CallOutcome;
     /** The org's own number that was dialled — present only (and only meaningful) for an inbound call. */
     readonly did?: string;
+    /**
+     * The org's own number an outbound call was made from (what the callee saw) — present only for outbound calls the
+     * backend recorded it for (outbound-number-per-agent.md §5.7). Digits, no `+`.
+     */
+    readonly from?: string;
     /** True when Coventia has at least one recording for this call. */
     readonly recorded: boolean;
     /**
@@ -344,6 +391,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
@@ -363,6 +422,13 @@ 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;
 }
 /**
  * Opens one live presence connection. Coventia-backed by default (mints a one-time ticket, opens
@@ -415,6 +481,64 @@ interface RingtoneSource {
      */
     cached?(): Promise<RingtoneSettings | null>;
 }
+/**
+ * What kind of number this is, for the tags next to it in "Llamar desde" (outbound-number-per-agent.md §5.5).
+ * Display only — it never blocks a choice. `mobile` must not be used for customer care or unsolicited commercial
+ * calls; `commercial` (the 400 range) is for outbound commercial calls only and receives no calls.
+ */
+type OutboundNumberKind = 'landline' | 'mobile' | 'commercial' | 'other';
+/** One of the organization's numbers an agent can call from. */
+interface OutboundNumber {
+    /** Stable id — what is stored as the agent's choice. */
+    readonly id: string;
+    /** International format, digits only, no `+` — e.g. `34960000001`. */
+    readonly number: string;
+    /** The name the organization gave the number, or `null`. */
+    readonly label: string | null;
+    readonly kind: OutboundNumberKind;
+}
+/**
+ * Where the agent's extension stands. `pending`/`failed`: an assignment change could not update it yet, so the
+ * extension may still present an earlier number. `unassigned`: the agent has no extension in this organization.
+ */
+type OutboundNumberState = 'applied' | 'pending' | 'failed' | 'unassigned';
+/** The organization's numbers and the caller's choice, as the backend resolves them. */
+interface OutboundNumberSettings {
+    /** The organization's active numbers, ordered by number. */
+    readonly numbers: readonly OutboundNumber[];
+    /** The organization default (an `OutboundNumber.id`), or `null`. */
+    readonly orgDefault: string | null;
+    /** This agent's own choice, or `null` = "use the organization default". */
+    readonly mine: string | null;
+    /** The number this agent's calls show: `mine`, else `orgDefault`. */
+    readonly effective: string | null;
+    /** The agent's extension ("100"), or `null` when they have none. */
+    readonly extension: string | null;
+    readonly state: OutboundNumberState;
+    /** 0 when a change could go out now; otherwise the seconds until it can. */
+    readonly changeAvailableInSeconds: number;
+}
+/**
+ * Why a change was refused before anything was sent. `platform`: the shared limit on number changes (nothing the
+ * agent did). `user`: the agent changed it moments ago. Either way the previous number stays in use.
+ */
+interface OutboundNumberRefusal {
+    readonly reason: 'platform' | 'user';
+    /** Seconds until a change can go out — always at least 1. */
+    readonly retryAfterSeconds: number;
+}
+/** The outbound number of the agent the softphone is signed in as, in its organization. */
+interface OutboundNumbersSource {
+    get(signal?: AbortSignal): Promise<OutboundNumberSettings>;
+    /**
+     * Changes this agent's number; `null` = back to the organization default. Resolves to the new settings once the
+     * change is in effect. When the request limits refuse it, rejects with an `Error` carrying
+     * `refusal: OutboundNumberRefusal` (check with `isOutboundNumberRefused`) — nothing was stored or sent.
+     */
+    setMine(id: string | null): Promise<OutboundNumberSettings>;
+    /** The settings this agent last had on this device, if remembered — instant, no network. Optional. */
+    cached?(): Promise<OutboundNumberSettings | null>;
+}
 
 /**
  * The error taxonomy.
@@ -535,6 +659,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.";
@@ -623,10 +757,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"
+    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.
+     */
+    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]: {
@@ -647,6 +796,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. */
@@ -873,4 +1029,4 @@ interface Call extends TypedEmitter<CallEventMap> {
     cancelConsult(): Promise<void>;
 }
 
-export { type AgentsDirectory as A, type PresenceSource as B, CALL_TRANSITIONS as C, type CallHistoryEntry as D, ERROR_CATALOGUE as E, type FatalErrorCode as F, type ContactsPage as G, type HangupReason as H, INITIAL_STATES as I, type LogLevel as L, type NonFatalErrorCode as N, type PresenceEntry as P, 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 RingtoneOption as k, type RingtoneSettings as l, type RingtoneSource as m, type SoftphoneError as n, type SoftphoneErrorCode as o, SoftphoneEvent as p, type SoftphoneEventMap as q, type SoftphoneState as r, type TokenSource as s, type TypedEmitter as t, canTransition as u, isFatal as v, isTerminal as w, type ContactsSource as x, type HistorySource as y, type TransferOutcomesPage 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 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-CaPDWVk3.d.ts → call-FqcvDg1t.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,44 @@ 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 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 SoftphoneState = 'stopped' | 'starting' | 'online' | 'offline' | 'reconnecting' | 'destroyed';
+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;
+}
+/** 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[];
     /**
@@ -240,6 +282,11 @@ interface CallHistoryEntry {
     readonly outcome?: CallOutcome;
     /** The org's own number that was dialled — present only (and only meaningful) for an inbound call. */
     readonly did?: string;
+    /**
+     * The org's own number an outbound call was made from (what the callee saw) — present only for outbound calls the
+     * backend recorded it for (outbound-number-per-agent.md §5.7). Digits, no `+`.
+     */
+    readonly from?: string;
     /** True when Coventia has at least one recording for this call. */
     readonly recorded: boolean;
     /**
@@ -344,6 +391,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
@@ -363,6 +422,13 @@ 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;
 }
 /**
  * Opens one live presence connection. Coventia-backed by default (mints a one-time ticket, opens
@@ -415,6 +481,64 @@ interface RingtoneSource {
      */
     cached?(): Promise<RingtoneSettings | null>;
 }
+/**
+ * What kind of number this is, for the tags next to it in "Llamar desde" (outbound-number-per-agent.md §5.5).
+ * Display only — it never blocks a choice. `mobile` must not be used for customer care or unsolicited commercial
+ * calls; `commercial` (the 400 range) is for outbound commercial calls only and receives no calls.
+ */
+type OutboundNumberKind = 'landline' | 'mobile' | 'commercial' | 'other';
+/** One of the organization's numbers an agent can call from. */
+interface OutboundNumber {
+    /** Stable id — what is stored as the agent's choice. */
+    readonly id: string;
+    /** International format, digits only, no `+` — e.g. `34960000001`. */
+    readonly number: string;
+    /** The name the organization gave the number, or `null`. */
+    readonly label: string | null;
+    readonly kind: OutboundNumberKind;
+}
+/**
+ * Where the agent's extension stands. `pending`/`failed`: an assignment change could not update it yet, so the
+ * extension may still present an earlier number. `unassigned`: the agent has no extension in this organization.
+ */
+type OutboundNumberState = 'applied' | 'pending' | 'failed' | 'unassigned';
+/** The organization's numbers and the caller's choice, as the backend resolves them. */
+interface OutboundNumberSettings {
+    /** The organization's active numbers, ordered by number. */
+    readonly numbers: readonly OutboundNumber[];
+    /** The organization default (an `OutboundNumber.id`), or `null`. */
+    readonly orgDefault: string | null;
+    /** This agent's own choice, or `null` = "use the organization default". */
+    readonly mine: string | null;
+    /** The number this agent's calls show: `mine`, else `orgDefault`. */
+    readonly effective: string | null;
+    /** The agent's extension ("100"), or `null` when they have none. */
+    readonly extension: string | null;
+    readonly state: OutboundNumberState;
+    /** 0 when a change could go out now; otherwise the seconds until it can. */
+    readonly changeAvailableInSeconds: number;
+}
+/**
+ * Why a change was refused before anything was sent. `platform`: the shared limit on number changes (nothing the
+ * agent did). `user`: the agent changed it moments ago. Either way the previous number stays in use.
+ */
+interface OutboundNumberRefusal {
+    readonly reason: 'platform' | 'user';
+    /** Seconds until a change can go out — always at least 1. */
+    readonly retryAfterSeconds: number;
+}
+/** The outbound number of the agent the softphone is signed in as, in its organization. */
+interface OutboundNumbersSource {
+    get(signal?: AbortSignal): Promise<OutboundNumberSettings>;
+    /**
+     * Changes this agent's number; `null` = back to the organization default. Resolves to the new settings once the
+     * change is in effect. When the request limits refuse it, rejects with an `Error` carrying
+     * `refusal: OutboundNumberRefusal` (check with `isOutboundNumberRefused`) — nothing was stored or sent.
+     */
+    setMine(id: string | null): Promise<OutboundNumberSettings>;
+    /** The settings this agent last had on this device, if remembered — instant, no network. Optional. */
+    cached?(): Promise<OutboundNumberSettings | null>;
+}
 
 /**
  * The error taxonomy.
@@ -535,6 +659,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.";
@@ -623,10 +757,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"
+    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.
+     */
+    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]: {
@@ -647,6 +796,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. */
@@ -873,4 +1029,4 @@ interface Call extends TypedEmitter<CallEventMap> {
     cancelConsult(): Promise<void>;
 }
 
-export { type AgentsDirectory as A, type PresenceSource as B, CALL_TRANSITIONS as C, type CallHistoryEntry as D, ERROR_CATALOGUE as E, type FatalErrorCode as F, type ContactsPage as G, type HangupReason as H, INITIAL_STATES as I, type LogLevel as L, type NonFatalErrorCode as N, type PresenceEntry as P, 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 RingtoneOption as k, type RingtoneSettings as l, type RingtoneSource as m, type SoftphoneError as n, type SoftphoneErrorCode as o, SoftphoneEvent as p, type SoftphoneEventMap as q, type SoftphoneState as r, type TokenSource as s, type TypedEmitter as t, canTransition as u, isFatal as v, isTerminal as w, type ContactsSource as x, type HistorySource as y, type TransferOutcomesPage 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 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/chunk-5E5OEXS2.js

@@ -0,0 +1,14 @@
+// src/core/outbound-numbers.ts
+function isOutboundNumberRefused(value) {
+  const refusal = value?.refusal;
+  return value instanceof Error && !!refusal && (refusal.reason === "platform" || refusal.reason === "user") && typeof refusal.retryAfterSeconds === "number";
+}
+function outboundNumberRefused(refusal) {
+  const error = new Error(`Outbound number change refused (${refusal.reason}); retry in ${refusal.retryAfterSeconds}s`);
+  error.name = "OutboundNumberRefused";
+  return Object.assign(error, { refusal });
+}
+
+export { isOutboundNumberRefused, outboundNumberRefused };
+//# sourceMappingURL=chunk-5E5OEXS2.js.map
+//# sourceMappingURL=chunk-5E5OEXS2.js.map

package/dist/chunk-5E5OEXS2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/outbound-numbers.ts"],"names":[],"mappings":";AAWO,SAAS,wBAAwB,KAAA,EAAqD;AAC3F,EAAA,MAAM,UAAW,KAAA,EAA+D,OAAA;AAChF,EAAA,OACE,KAAA,YAAiB,KAAA,IACjB,CAAC,CAAC,OAAA,KACD,OAAA,CAAQ,MAAA,KAAW,UAAA,IAAc,OAAA,CAAQ,MAAA,KAAW,MAAA,CAAA,IACrD,OAAO,QAAQ,iBAAA,KAAsB,QAAA;AAEzC;AAGO,SAAS,sBAAsB,OAAA,EAA4D;AAChG,EAAA,MAAM,KAAA,GAAQ,IAAI,KAAA,CAAM,CAAA,gCAAA,EAAmC,QAAQ,MAAM,CAAA,YAAA,EAAe,OAAA,CAAQ,iBAAiB,CAAA,CAAA,CAAG,CAAA;AACpH,EAAA,KAAA,CAAM,IAAA,GAAO,uBAAA;AACb,EAAA,OAAO,MAAA,CAAO,MAAA,CAAO,KAAA,EAAO,EAAE,SAAS,CAAA;AACzC","file":"chunk-5E5OEXS2.js","sourcesContent":["import type { OutboundNumberRefusal } from './types.js';\r\n\r\n/**\r\n * A change of outbound number the request limits refused (outbound-number-per-agent.md §5.3–§5.5). Structural,\r\n * like `isSoftphoneError`: the concrete error is a plain `Error` with a `refusal`, so a host — or a second copy\r\n * of the SDK on the page — can recognise it without sharing a class.\r\n */\r\nexport interface OutboundNumberRefusedError extends Error {\r\n  readonly refusal: OutboundNumberRefusal;\r\n}\r\n\r\nexport function isOutboundNumberRefused(value: unknown): value is OutboundNumberRefusedError {\r\n  const refusal = (value as { refusal?: Partial<OutboundNumberRefusal> } | null)?.refusal;\r\n  return (\r\n    value instanceof Error &&\r\n    !!refusal &&\r\n    (refusal.reason === 'platform' || refusal.reason === 'user') &&\r\n    typeof refusal.retryAfterSeconds === 'number'\r\n  );\r\n}\r\n\r\n/** @internal — raised by the Coventia source; hosts only read these. */\r\nexport function outboundNumberRefused(refusal: OutboundNumberRefusal): OutboundNumberRefusedError {\r\n  const error = new Error(`Outbound number change refused (${refusal.reason}); retry in ${refusal.retryAfterSeconds}s`);\r\n  error.name = 'OutboundNumberRefused';\r\n  return Object.assign(error, { refusal });\r\n}\r\n"]}