@coventia/softphone 0.1.0 → 0.2.0

package/dist/{call-BTYlT2SU.d.cts → call-DUVnDxsz.d.cts}

@@ -117,6 +117,19 @@ interface CoventiaBackendConfig {
      * (SPEC §6.6).
      */
     readonly contacts?: ContactsSource;
+    /**
+     * Transfer outcomes, overriding Coventia's own polling — for a `MockProvider`-style test double, or
+     * a future non-Zadarma provider that computes outcomes differently. Not a per-partner customisation
+     * point the way `contacts` is: unlike a contact list, a transfer outcome is not a partner's own
+     * data, so there is normally no reason to set this (`docs/specs/transfer-outcome-relay.md`, Phase A).
+     */
+    readonly transferOutcomes?: TransferOutcomeSource;
+    /**
+     * Live agent presence, overriding Coventia's own WebSocket — for a `MockProvider`-style test
+     * double, or a host with its own presence transport. Not a per-partner customisation point the way
+     * `contacts` is (`docs/specs/transfer-presence-picker.md`, Phase B).
+     */
+    readonly presence?: PresenceSource;
 }
 interface SoftphoneConfig {
     readonly tokenSource: TokenSource;
@@ -261,6 +274,98 @@ interface AgentsDirectory {
     readonly me: PhoneAgent | null;
     readonly people: readonly PhoneAgent[];
 }
+/**
+ * `'connected'` | `'not-connected'` — whether an attended transfer's second ring, after `Completar`,
+ * actually reached the target. Kebab-case to match `HangupReason` (`'no-answer'`, `'transferred'`);
+ * the backend's own wire value stays `not_connected` — this is the one place that gets translated.
+ */
+type TransferOutcomeStatus = 'connected' | 'not-connected';
+/** One resolved transfer, as `GET /phone/transfers/outcomes` reports it. */
+interface TransferOutcomeEntry {
+    /** Opaque, strictly increasing per organization, never re-issued. The cursor for the NEXT poll. */
+    readonly id: string;
+    /** The extension the call was transferred to. */
+    readonly target: string;
+    readonly status: TransferOutcomeStatus;
+    readonly at: Date;
+}
+interface TransferOutcomesPage {
+    /** The newest `id` currently retained, or `'0'` when there are none — pass back as `since`. */
+    readonly cursor: string;
+    readonly outcomes: readonly TransferOutcomeEntry[];
+}
+/**
+ * Poll for transfer outcomes. `since` omitted ⇒ everything currently retained — used for the FIRST
+ * poll after starting a watch, which exists only to learn the current cursor (spec §5.3's
+ * no-mis-attribution rule: that first poll's own outcomes are discarded, only `cursor` is kept).
+ */
+type TransferOutcomeSource = (params: {
+    readonly since?: string;
+}) => Promise<TransferOutcomesPage>;
+/**
+ * `SoftphoneEvent.TransferOutcome`'s payload. Unlike `TransferOutcomeEntry`, this never carries `id`
+ * (a polling-internal concern) and adds `caller` — the backend never stores a caller number (spec
+ * §5.3: "no caller number, nothing about other users"), so this is filled in locally, from the `Call`
+ * that was transferred, at the moment an outcome is matched to it.
+ */
+interface TransferOutcomeEvent {
+    readonly status: TransferOutcomeStatus;
+    readonly target: string;
+    /** The original caller's number, for "Llamar de vuelta" — null if it was never known. */
+    readonly caller: string | null;
+    readonly at: Date;
+}
+/**
+ * `'disponible'` | `'en_llamada'` | `'desconectado'` — Spanish because this is what the picker shows,
+ * not an internal code (spec §4.1). `derivePresence` (the backend's own reducer, mirrored nowhere in
+ * the SDK — the SDK only ever receives an already-derived state, never `onCall`/`onlineFresh` apart).
+ */
+type PresenceState = 'disponible' | 'en_llamada' | 'desconectado';
+/** One org member with a phone extension, as the picker lists them. */
+interface PresenceEntry {
+    readonly userId: string;
+    readonly extension: string;
+    /** `null` when the backend has no name to offer — the picker falls back to the extension. */
+    readonly name: string | null;
+    readonly state: PresenceState;
+}
+/** What a live presence connection hands back once open. */
+interface PresenceConnection {
+    /**
+     * Report this softphone's own on-call-ness, so a colleague transferring TO this agent sees it
+     * without a round trip through the webhook path (spec §4.1's `onCall` OR-combine). Calling this
+     * before the connection is genuinely open is never required of an implementation — a caller (see
+     * `presence-socket.ts`) that reports early is expected to wait for the connection to exist first.
+     */
+    readonly reportCallState: (onCall: boolean) => 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
+     * ticket), which is the only thing a caller should ever treat as "reconnect now".
+     */
+    readonly close: () => void;
+}
+interface PresenceCallbacks {
+    /** Once, right after connecting — the full current roster (spec §4.3). */
+    readonly onSnapshot: (agents: readonly PresenceEntry[]) => void;
+    /** Zero or more times after that — one agent whose state just changed. */
+    readonly onDelta: (agent: PresenceEntry) => void;
+    /**
+     * The connection ended on its own. Never called after the CALLER's own `close()` — see
+     * `PresenceConnection.close`'s own note. The only signal a watch layer needs to know it must
+     * reconnect, deliberately carrying no reason: a dropped connection and a rejected ticket look
+     * identical from here, and both get the same treatment (spec §4.4 — quiet retry, nothing surfaced).
+     */
+    readonly onClose: () => void;
+}
+/**
+ * Opens one live presence connection. Coventia-backed by default (mints a one-time ticket, opens
+ * `wss://…/phone/presence`); a host may override it entirely, or omit it — omitted, or while the
+ * connection is down, the picker simply has no live data to show (spec §4.4, success criterion #5:
+ * no error surfaces). Unlike `TransferOutcomeSource` (poll, get a page, done), this is push-based and
+ * long-lived — the returned promise resolves once, when the connection opens, not once per update.
+ */
+type PresenceSource = (callbacks: PresenceCallbacks) => Promise<PresenceConnection>;
 
 /**
  * The error taxonomy.
@@ -456,7 +561,23 @@ declare enum SoftphoneEvent {
      * `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"
+    LeaderChanged = "leaderChanged",
+    /**
+     * `Completar` completed a transfer, and the target's SECOND ring either connected or didn't —
+     * `docs/specs/transfer-outcome-relay.md` (Phase A). Fires for BOTH outcomes so a host can react to
+     * either; only `'not-connected'` is worth surfacing to the agent (spec §5.5) — roughly a minute
+     * after the transfer for a target who never answers, seconds for a decline or the caller hanging up
+     * first. Requires a `TransferOutcomeSource` (from `coventia`/`apiBase`, or a host override); never
+     * fires at all when none is configured, since there is then nothing to poll.
+     */
+    TransferOutcome = "transferOutcome",
+    /**
+     * `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`.
+     */
+    PresenceChanged = "presenceChanged"
 }
 interface SoftphoneEventMap {
     [SoftphoneEvent.StateChanged]: {
@@ -473,6 +594,10 @@ interface SoftphoneEventMap {
     [SoftphoneEvent.LeaderChanged]: {
         readonly isLeader: boolean;
     };
+    [SoftphoneEvent.TransferOutcome]: TransferOutcomeEvent;
+    [SoftphoneEvent.PresenceChanged]: {
+        readonly agents: readonly PresenceEntry[];
+    };
 }
 declare enum CallEvent {
     /** Any transition. The catch-all; the specific events below are conveniences. */
@@ -663,18 +788,40 @@ interface Call extends TypedEmitter<CallEventMap> {
     hold(): Promise<void>;
     unhold(): Promise<void>;
     sendDigits(digits: string): void;
-    /** Blind transfer (SIP REFER). Ends this call. */
+    /**
+     * Blind transfer (SIP REFER). Ends this call — but **whether the transfer itself succeeded or
+     * failed is unknowable from here**: against Zadarma, a REFER's outcome is not reported back to the
+     * browser at all (confirmed on real calls — `docs/specs/transfer-availability.md` §2), so a REFER to
+     * an unreachable target ends this call exactly the same way a successful one does. Prefer
+     * `startConsult`/`completeTransfer` (below) when the caller must not be put at risk — that path
+     * correctly reports busy/no-answer/failed because the consult leg is an ordinary outbound call, not
+     * a REFER.
+     */
     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.
+     * Returns the consult leg — itself a Call, with its own state machine and events. Unlike blind
+     * `transfer()`, a consult leg that goes unanswered reports a real reason (busy/no-answer/rejected/
+     * failed) and never puts this call at risk — see `docs/specs/transfer-availability.md` §5.
      */
     startConsult(target: string): Promise<Call>;
-    /** Attended transfer, part 2: bridge the two, ending both. (REFER … Replaces) */
+    /**
+     * Attended transfer, part 2: bridge the two, ending both. (REFER … Replaces)
+     *
+     * **Confirmed non-functional against Zadarma, on real calls, three times
+     * (`docs/specs/transfer-availability.md` §12.3).** Zadarma accepts the REFER…Replaces but never
+     * actually bridges the two legs — the consult leg is silently orphaned and the caller is lost, with
+     * no error thrown here to signal it. The pattern that DOES work (the same one `/ui`'s own
+     * `ConsultScreen` uses): hang up the consult leg, then call `transfer(target)` on THIS call, to the
+     * same already-confirmed-answering target — a blind transfer to a target already known to be there
+     * works, even though `completeTransfer()` itself does not. Left in the type for hosts against a
+     * different (non-Zadarma) SIP provider where REFER…Replaces may work as specified; do not reach for
+     * it against Zadarma.
+     */
     completeTransfer(): Promise<void>;
     /** Abandon the consult and resume this call. */
     cancelConsult(): Promise<void>;
 }
 
-export { type AgentsDirectory as A, CALL_TRANSITIONS as C, ERROR_CATALOGUE as E, type FatalErrorCode as F, type HangupReason as H, INITIAL_STATES as I, type LogLevel as L, type NonFatalErrorCode as N, type RemoteParty as R, type SoftphoneConfig as S, type TokenEndpointOptions as T, type VoiceToken as V, type Call as a, type CallDirection as b, CallEvent as c, type CallEventMap as d, type CallOptions as e, type CallState as f, type Contact as g, type FatalSoftphoneError as h, type HoldOriginator as i, type NonFatalSoftphoneError as j, type SoftphoneError as k, type SoftphoneErrorCode as l, SoftphoneEvent as m, type SoftphoneEventMap as n, type SoftphoneState as o, type TokenSource as p, type TypedEmitter as q, canTransition as r, isFatal as s, isTerminal as t, type ContactsSource as u, type HistorySource as v, type CallHistoryEntry as w, type ContactsPage as x };
+export { type AgentsDirectory as A, CALL_TRANSITIONS as C, ERROR_CATALOGUE as E, type FatalErrorCode as F, type HangupReason as H, INITIAL_STATES as I, type LogLevel as L, type NonFatalErrorCode as N, type 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 SoftphoneError as k, type SoftphoneErrorCode as l, SoftphoneEvent as m, type SoftphoneEventMap as n, type SoftphoneState as o, type TokenSource as p, type TypedEmitter as q, canTransition as r, isFatal as s, isTerminal as t, type ContactsSource as u, type HistorySource as v, type TransferOutcomesPage as w, type PresenceSource as x, type CallHistoryEntry as y, type ContactsPage as z };

package/dist/{call-BTYlT2SU.d.ts → call-DUVnDxsz.d.ts}

@@ -117,6 +117,19 @@ interface CoventiaBackendConfig {
      * (SPEC §6.6).
      */
     readonly contacts?: ContactsSource;
+    /**
+     * Transfer outcomes, overriding Coventia's own polling — for a `MockProvider`-style test double, or
+     * a future non-Zadarma provider that computes outcomes differently. Not a per-partner customisation
+     * point the way `contacts` is: unlike a contact list, a transfer outcome is not a partner's own
+     * data, so there is normally no reason to set this (`docs/specs/transfer-outcome-relay.md`, Phase A).
+     */
+    readonly transferOutcomes?: TransferOutcomeSource;
+    /**
+     * Live agent presence, overriding Coventia's own WebSocket — for a `MockProvider`-style test
+     * double, or a host with its own presence transport. Not a per-partner customisation point the way
+     * `contacts` is (`docs/specs/transfer-presence-picker.md`, Phase B).
+     */
+    readonly presence?: PresenceSource;
 }
 interface SoftphoneConfig {
     readonly tokenSource: TokenSource;
@@ -261,6 +274,98 @@ interface AgentsDirectory {
     readonly me: PhoneAgent | null;
     readonly people: readonly PhoneAgent[];
 }
+/**
+ * `'connected'` | `'not-connected'` — whether an attended transfer's second ring, after `Completar`,
+ * actually reached the target. Kebab-case to match `HangupReason` (`'no-answer'`, `'transferred'`);
+ * the backend's own wire value stays `not_connected` — this is the one place that gets translated.
+ */
+type TransferOutcomeStatus = 'connected' | 'not-connected';
+/** One resolved transfer, as `GET /phone/transfers/outcomes` reports it. */
+interface TransferOutcomeEntry {
+    /** Opaque, strictly increasing per organization, never re-issued. The cursor for the NEXT poll. */
+    readonly id: string;
+    /** The extension the call was transferred to. */
+    readonly target: string;
+    readonly status: TransferOutcomeStatus;
+    readonly at: Date;
+}
+interface TransferOutcomesPage {
+    /** The newest `id` currently retained, or `'0'` when there are none — pass back as `since`. */
+    readonly cursor: string;
+    readonly outcomes: readonly TransferOutcomeEntry[];
+}
+/**
+ * Poll for transfer outcomes. `since` omitted ⇒ everything currently retained — used for the FIRST
+ * poll after starting a watch, which exists only to learn the current cursor (spec §5.3's
+ * no-mis-attribution rule: that first poll's own outcomes are discarded, only `cursor` is kept).
+ */
+type TransferOutcomeSource = (params: {
+    readonly since?: string;
+}) => Promise<TransferOutcomesPage>;
+/**
+ * `SoftphoneEvent.TransferOutcome`'s payload. Unlike `TransferOutcomeEntry`, this never carries `id`
+ * (a polling-internal concern) and adds `caller` — the backend never stores a caller number (spec
+ * §5.3: "no caller number, nothing about other users"), so this is filled in locally, from the `Call`
+ * that was transferred, at the moment an outcome is matched to it.
+ */
+interface TransferOutcomeEvent {
+    readonly status: TransferOutcomeStatus;
+    readonly target: string;
+    /** The original caller's number, for "Llamar de vuelta" — null if it was never known. */
+    readonly caller: string | null;
+    readonly at: Date;
+}
+/**
+ * `'disponible'` | `'en_llamada'` | `'desconectado'` — Spanish because this is what the picker shows,
+ * not an internal code (spec §4.1). `derivePresence` (the backend's own reducer, mirrored nowhere in
+ * the SDK — the SDK only ever receives an already-derived state, never `onCall`/`onlineFresh` apart).
+ */
+type PresenceState = 'disponible' | 'en_llamada' | 'desconectado';
+/** One org member with a phone extension, as the picker lists them. */
+interface PresenceEntry {
+    readonly userId: string;
+    readonly extension: string;
+    /** `null` when the backend has no name to offer — the picker falls back to the extension. */
+    readonly name: string | null;
+    readonly state: PresenceState;
+}
+/** What a live presence connection hands back once open. */
+interface PresenceConnection {
+    /**
+     * Report this softphone's own on-call-ness, so a colleague transferring TO this agent sees it
+     * without a round trip through the webhook path (spec §4.1's `onCall` OR-combine). Calling this
+     * before the connection is genuinely open is never required of an implementation — a caller (see
+     * `presence-socket.ts`) that reports early is expected to wait for the connection to exist first.
+     */
+    readonly reportCallState: (onCall: boolean) => 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
+     * ticket), which is the only thing a caller should ever treat as "reconnect now".
+     */
+    readonly close: () => void;
+}
+interface PresenceCallbacks {
+    /** Once, right after connecting — the full current roster (spec §4.3). */
+    readonly onSnapshot: (agents: readonly PresenceEntry[]) => void;
+    /** Zero or more times after that — one agent whose state just changed. */
+    readonly onDelta: (agent: PresenceEntry) => void;
+    /**
+     * The connection ended on its own. Never called after the CALLER's own `close()` — see
+     * `PresenceConnection.close`'s own note. The only signal a watch layer needs to know it must
+     * reconnect, deliberately carrying no reason: a dropped connection and a rejected ticket look
+     * identical from here, and both get the same treatment (spec §4.4 — quiet retry, nothing surfaced).
+     */
+    readonly onClose: () => void;
+}
+/**
+ * Opens one live presence connection. Coventia-backed by default (mints a one-time ticket, opens
+ * `wss://…/phone/presence`); a host may override it entirely, or omit it — omitted, or while the
+ * connection is down, the picker simply has no live data to show (spec §4.4, success criterion #5:
+ * no error surfaces). Unlike `TransferOutcomeSource` (poll, get a page, done), this is push-based and
+ * long-lived — the returned promise resolves once, when the connection opens, not once per update.
+ */
+type PresenceSource = (callbacks: PresenceCallbacks) => Promise<PresenceConnection>;
 
 /**
  * The error taxonomy.
@@ -456,7 +561,23 @@ declare enum SoftphoneEvent {
      * `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"
+    LeaderChanged = "leaderChanged",
+    /**
+     * `Completar` completed a transfer, and the target's SECOND ring either connected or didn't —
+     * `docs/specs/transfer-outcome-relay.md` (Phase A). Fires for BOTH outcomes so a host can react to
+     * either; only `'not-connected'` is worth surfacing to the agent (spec §5.5) — roughly a minute
+     * after the transfer for a target who never answers, seconds for a decline or the caller hanging up
+     * first. Requires a `TransferOutcomeSource` (from `coventia`/`apiBase`, or a host override); never
+     * fires at all when none is configured, since there is then nothing to poll.
+     */
+    TransferOutcome = "transferOutcome",
+    /**
+     * `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`.
+     */
+    PresenceChanged = "presenceChanged"
 }
 interface SoftphoneEventMap {
     [SoftphoneEvent.StateChanged]: {
@@ -473,6 +594,10 @@ interface SoftphoneEventMap {
     [SoftphoneEvent.LeaderChanged]: {
         readonly isLeader: boolean;
     };
+    [SoftphoneEvent.TransferOutcome]: TransferOutcomeEvent;
+    [SoftphoneEvent.PresenceChanged]: {
+        readonly agents: readonly PresenceEntry[];
+    };
 }
 declare enum CallEvent {
     /** Any transition. The catch-all; the specific events below are conveniences. */
@@ -663,18 +788,40 @@ interface Call extends TypedEmitter<CallEventMap> {
     hold(): Promise<void>;
     unhold(): Promise<void>;
     sendDigits(digits: string): void;
-    /** Blind transfer (SIP REFER). Ends this call. */
+    /**
+     * Blind transfer (SIP REFER). Ends this call — but **whether the transfer itself succeeded or
+     * failed is unknowable from here**: against Zadarma, a REFER's outcome is not reported back to the
+     * browser at all (confirmed on real calls — `docs/specs/transfer-availability.md` §2), so a REFER to
+     * an unreachable target ends this call exactly the same way a successful one does. Prefer
+     * `startConsult`/`completeTransfer` (below) when the caller must not be put at risk — that path
+     * correctly reports busy/no-answer/failed because the consult leg is an ordinary outbound call, not
+     * a REFER.
+     */
     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.
+     * Returns the consult leg — itself a Call, with its own state machine and events. Unlike blind
+     * `transfer()`, a consult leg that goes unanswered reports a real reason (busy/no-answer/rejected/
+     * failed) and never puts this call at risk — see `docs/specs/transfer-availability.md` §5.
      */
     startConsult(target: string): Promise<Call>;
-    /** Attended transfer, part 2: bridge the two, ending both. (REFER … Replaces) */
+    /**
+     * Attended transfer, part 2: bridge the two, ending both. (REFER … Replaces)
+     *
+     * **Confirmed non-functional against Zadarma, on real calls, three times
+     * (`docs/specs/transfer-availability.md` §12.3).** Zadarma accepts the REFER…Replaces but never
+     * actually bridges the two legs — the consult leg is silently orphaned and the caller is lost, with
+     * no error thrown here to signal it. The pattern that DOES work (the same one `/ui`'s own
+     * `ConsultScreen` uses): hang up the consult leg, then call `transfer(target)` on THIS call, to the
+     * same already-confirmed-answering target — a blind transfer to a target already known to be there
+     * works, even though `completeTransfer()` itself does not. Left in the type for hosts against a
+     * different (non-Zadarma) SIP provider where REFER…Replaces may work as specified; do not reach for
+     * it against Zadarma.
+     */
     completeTransfer(): Promise<void>;
     /** Abandon the consult and resume this call. */
     cancelConsult(): Promise<void>;
 }
 
-export { type AgentsDirectory as A, CALL_TRANSITIONS as C, ERROR_CATALOGUE as E, type FatalErrorCode as F, type HangupReason as H, INITIAL_STATES as I, type LogLevel as L, type NonFatalErrorCode as N, type RemoteParty as R, type SoftphoneConfig as S, type TokenEndpointOptions as T, type VoiceToken as V, type Call as a, type CallDirection as b, CallEvent as c, type CallEventMap as d, type CallOptions as e, type CallState as f, type Contact as g, type FatalSoftphoneError as h, type HoldOriginator as i, type NonFatalSoftphoneError as j, type SoftphoneError as k, type SoftphoneErrorCode as l, SoftphoneEvent as m, type SoftphoneEventMap as n, type SoftphoneState as o, type TokenSource as p, type TypedEmitter as q, canTransition as r, isFatal as s, isTerminal as t, type ContactsSource as u, type HistorySource as v, type CallHistoryEntry as w, type ContactsPage as x };
+export { type AgentsDirectory as A, CALL_TRANSITIONS as C, ERROR_CATALOGUE as E, type FatalErrorCode as F, type HangupReason as H, INITIAL_STATES as I, type LogLevel as L, type NonFatalErrorCode as N, type 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 SoftphoneError as k, type SoftphoneErrorCode as l, SoftphoneEvent as m, type SoftphoneEventMap as n, type SoftphoneState as o, type TokenSource as p, type TypedEmitter as q, canTransition as r, isFatal as s, isTerminal as t, type ContactsSource as u, type HistorySource as v, type TransferOutcomesPage as w, type PresenceSource as x, type CallHistoryEntry as y, type ContactsPage as z };

package/dist/{chunk-N2N2EQQJ.js → chunk-7R6LOOAI.js}

@@ -7,6 +7,8 @@ var SoftphoneEvent = /* @__PURE__ */ ((SoftphoneEvent2) => {
   SoftphoneEvent2["DeviceChange"] = "deviceChange";
   SoftphoneEvent2["Error"] = "error";
   SoftphoneEvent2["LeaderChanged"] = "leaderChanged";
+  SoftphoneEvent2["TransferOutcome"] = "transferOutcome";
+  SoftphoneEvent2["PresenceChanged"] = "presenceChanged";
   return SoftphoneEvent2;
 })(SoftphoneEvent || {});
 var CallEvent = /* @__PURE__ */ ((CallEvent2) => {
@@ -25,5 +27,5 @@ var CallEvent = /* @__PURE__ */ ((CallEvent2) => {
 })(CallEvent || {});
 
 export { CallEvent, SoftphoneEvent };
-//# sourceMappingURL=chunk-N2N2EQQJ.js.map
-//# sourceMappingURL=chunk-N2N2EQQJ.js.map
+//# sourceMappingURL=chunk-7R6LOOAI.js.map
+//# sourceMappingURL=chunk-7R6LOOAI.js.map

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

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

package/dist/{chunk-3V2L6UTK.js → chunk-LMJXX4YM.js}

@@ -51,6 +51,20 @@ function useActiveCall() {
     useCallback(() => phone.activeCall, [phone])
   );
 }
+function usePresence(active) {
+  const phone = useSoftphone();
+  return useSyncExternalStore(
+    useCallback(
+      (cb) => {
+        if (!active) return () => {
+        };
+        return phone.on("presenceChanged" /* PresenceChanged */, () => cb());
+      },
+      [phone, active]
+    ),
+    useCallback(() => phone.presence, [phone])
+  );
+}
 var CALL_EVENTS = [
   "stateChanged" /* StateChanged */,
   "muted" /* Muted */,
@@ -124,6 +138,6 @@ function useDevices() {
   return useSyncExternalStore(subscribe, getSnapshot);
 }
 
-export { SoftphoneProvider, useActiveCall, useCall, useDevices, useIsLeader, useLastError, useSoftphone, useSoftphoneState };
-//# sourceMappingURL=chunk-3V2L6UTK.js.map
-//# sourceMappingURL=chunk-3V2L6UTK.js.map
+export { SoftphoneProvider, useActiveCall, useCall, useDevices, useIsLeader, useLastError, usePresence, useSoftphone, useSoftphoneState };
+//# sourceMappingURL=chunk-LMJXX4YM.js.map
+//# sourceMappingURL=chunk-LMJXX4YM.js.map

package/dist/chunk-LMJXX4YM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/context.tsx","../src/react/hooks.ts"],"names":[],"mappings":"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","file":"chunk-LMJXX4YM.js","sourcesContent":["import { createContext, useContext, type ReactNode } from 'react';\r\nimport type { Softphone } from '../core/softphone.js';\r\n\r\n/**\r\n * The provider takes an INSTANCE the host constructed — not config props.\r\n *\r\n * This is LiveKit's hard-won lesson (SPEC §5.1): they are deprecating their config-props\r\n * `<LiveKitRoom>` in favour of a provider that accepts an instance. Holding the `Softphone` above the\r\n * React tree lets the app own the connection, survive route changes and unmounts without dropping a\r\n * call, and unit-test the engine with no React at all. Config-props would rebuild the engine on\r\n * every prop change — catastrophic for something holding a live `RTCPeerConnection`.\r\n */\r\nconst SoftphoneContext = createContext<Softphone | null>(null);\r\n\r\nexport interface SoftphoneProviderProps {\r\n  readonly softphone: Softphone;\r\n  readonly children: ReactNode;\r\n}\r\n\r\nexport function SoftphoneProvider({ softphone, children }: SoftphoneProviderProps) {\r\n  return <SoftphoneContext.Provider value={softphone}>{children}</SoftphoneContext.Provider>;\r\n}\r\n\r\n/** The `Softphone` instance from context. Stable — does not re-render on state changes. */\r\nexport function useSoftphone(): Softphone {\r\n  const softphone = useContext(SoftphoneContext);\r\n  if (!softphone) {\r\n    throw new Error('useSoftphone() must be used within a <SoftphoneProvider>.');\r\n  }\r\n  return softphone;\r\n}\r\n","// Built-in, no shim: the peer floor is React 18 (SPEC §2.7), which ships useSyncExternalStore.\r\nimport { useCallback, useRef, useSyncExternalStore } from 'react';\r\nimport { useSoftphone } from './context.js';\r\nimport { SoftphoneEvent, CallEvent } from '../core/events.js';\r\nimport type { Call, CallState } from '../core/call.js';\r\nimport type { PresenceEntry, RemoteParty, SoftphoneState } from '../core/types.js';\r\nimport type { AudioDevices } from '../core/softphone.js';\r\nimport type { FatalSoftphoneError } from '../core/errors.js';\r\n\r\n/** Reactive softphone lifecycle state (`stopped` → `online` → …). */\r\n/**\r\n * The reason the phone cannot currently be used, or `null`.\r\n *\r\n * Reads `softphone.lastError`, which is STATE rather than only an event — the widget is usually\r\n * opened *after* something broke, and a listener mounted at that point would have missed the event\r\n * entirely and rendered a dialpad with no explanation.\r\n *\r\n * Re-reads on both channels because both can change it: `Error` sets it, and `StateChanged` clears it\r\n * on reaching `online`. Subscribing to only the first would leave a stale gate on screen after the\r\n * phone recovered.\r\n */\r\nexport function useLastError(): FatalSoftphoneError | null {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback(\r\n      (cb: () => void) => {\r\n        const offError = phone.on(SoftphoneEvent.Error, () => cb());\r\n        const offState = phone.on(SoftphoneEvent.StateChanged, () => cb());\r\n        return () => {\r\n          offError();\r\n          offState();\r\n        };\r\n      },\r\n      [phone],\r\n    ),\r\n    useCallback(() => phone.lastError, [phone]),\r\n  );\r\n}\r\n\r\nexport function useSoftphoneState(): SoftphoneState {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback((cb: () => void) => phone.on(SoftphoneEvent.StateChanged, () => cb()), [phone]),\r\n    useCallback(() => phone.state, [phone]),\r\n  );\r\n}\r\n\r\n/**\r\n * Whether THIS tab is the one allowed to be reachable (`multi-tab-leader-election.md`). `false` by\r\n * default and while waiting for another open tab to release it — show your own \"active in another\r\n * tab\" state for that duration; the `/ui` widget already does.\r\n */\r\nexport function useIsLeader(): boolean {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback((cb: () => void) => phone.on(SoftphoneEvent.LeaderChanged, () => cb()), [phone]),\r\n    useCallback(() => phone.isLeader, [phone]),\r\n  );\r\n}\r\n\r\n/**\r\n * The current call, or null. Re-renders when it changes — inbound, outbound, or ended.\r\n *\r\n * `phone.activeCall` returns a stable reference for a given call, so it is a safe snapshot.\r\n */\r\nexport function useActiveCall(): Call | null {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback((cb: () => void) => phone.on(SoftphoneEvent.ActiveCallChanged, () => cb()), [phone]),\r\n    useCallback(() => phone.activeCall, [phone]),\r\n  );\r\n}\r\n\r\n/**\r\n * The live agent-presence list (`phone.presence`, Phase B) — reactive on `SoftphoneEvent.\r\n * PresenceChanged`. `active` gates the SUBSCRIPTION only, not the underlying connection: the socket\r\n * itself stays governed entirely by `online && isLeader` inside the softphone (spec's own\r\n * always-connected decision), so passing `false` here does not close it — it only stops this\r\n * particular component from re-rendering on every update while it has no reason to care, e.g. the\r\n * transfer step being closed (spec §4.5: \"subscribe when the step opens... unsubscribe when it\r\n * closes\"). `phone.presence` is still read fresh on every call, so flipping `active` back to `true`\r\n * never shows a stale snapshot.\r\n */\r\nexport function usePresence(active: boolean): readonly PresenceEntry[] {\r\n  const phone = useSoftphone();\r\n  return useSyncExternalStore(\r\n    useCallback(\r\n      (cb: () => void) => {\r\n        if (!active) return () => {};\r\n        return phone.on(SoftphoneEvent.PresenceChanged, () => cb());\r\n      },\r\n      [phone, active],\r\n    ),\r\n    useCallback(() => phone.presence, [phone]),\r\n  );\r\n}\r\n\r\n/** An immutable snapshot of a call's reactive fields. */\r\nexport interface CallView {\r\n  readonly state: CallState;\r\n  readonly isMuted: boolean;\r\n  readonly isOnHold: boolean;\r\n  readonly remote: RemoteParty;\r\n  readonly remoteStream: MediaStream | null;\r\n  readonly answeredAt: Date | null;\r\n}\r\n\r\nconst CALL_EVENTS: readonly CallEvent[] = [\r\n  CallEvent.StateChanged,\r\n  CallEvent.Muted,\r\n  CallEvent.Held,\r\n  CallEvent.Unheld,\r\n  CallEvent.RemotePartyUpdated,\r\n  CallEvent.RemoteStream,\r\n  CallEvent.Ended,\r\n];\r\n\r\n/**\r\n * Reactive view of a specific call. Re-renders only when one of the call's own events fires — no\r\n * polling, no re-render storms.\r\n *\r\n * The snapshot is CACHED and invalidated only on an event, so `useSyncExternalStore` gets a stable\r\n * reference between changes (returning a fresh object every render would infinite-loop).\r\n */\r\nexport function useCall(call: Call | null): CallView | null {\r\n  const cache = useRef<{ call: Call; view: CallView } | null>(null);\r\n\r\n  const subscribe = useCallback(\r\n    (cb: () => void) => {\r\n      if (!call) return () => {};\r\n      const unsubs = CALL_EVENTS.map((event) =>\r\n        call.on(event, () => {\r\n          cache.current = null; // invalidate; getSnapshot rebuilds on the next read\r\n          cb();\r\n        }),\r\n      );\r\n      return () => {\r\n        for (const off of unsubs) off();\r\n      };\r\n    },\r\n    [call],\r\n  );\r\n\r\n  const getSnapshot = useCallback((): CallView | null => {\r\n    if (!call) return null;\r\n    if (cache.current?.call === call) return cache.current.view;\r\n    const view: CallView = {\r\n      state: call.state,\r\n      isMuted: call.isMuted,\r\n      isOnHold: call.isOnHold,\r\n      remote: call.remote,\r\n      remoteStream: call.remoteStream,\r\n      answeredAt: call.answeredAt,\r\n    };\r\n    cache.current = { call, view };\r\n    return view;\r\n  }, [call]);\r\n\r\n  return useSyncExternalStore(subscribe, getSnapshot);\r\n}\r\n\r\n/**\r\n * The audio device surface (`phone.audio`) — reactive. Re-renders on `SoftphoneEvent.DeviceChange`: a\r\n * device plugged/unplugged, or a selection changed (SPEC §7 Phase 2).\r\n *\r\n * The snapshot is CACHED and invalidated only on that event, same reasoning as `useCall`'s own\r\n * `CallView`: `phone.audio` is ONE stable object whose fields mutate in place, so returning it\r\n * directly would never change by reference and `useSyncExternalStore` would never re-render. A fresh\r\n * object, rebuilt only when something actually changed, is what makes this reactive without polling.\r\n */\r\nexport function useDevices(): AudioDevices {\r\n  const phone = useSoftphone();\r\n  const cache = useRef<{ audio: AudioDevices; view: AudioDevices } | null>(null);\r\n\r\n  const subscribe = useCallback(\r\n    (cb: () => void) =>\r\n      phone.on(SoftphoneEvent.DeviceChange, () => {\r\n        cache.current = null; // invalidate; getSnapshot rebuilds on the next read\r\n        cb();\r\n      }),\r\n    [phone],\r\n  );\r\n\r\n  const getSnapshot = useCallback((): AudioDevices => {\r\n    const audio = phone.audio;\r\n    if (cache.current?.audio === audio) return cache.current.view;\r\n    const view: AudioDevices = {\r\n      inputs: audio.inputs,\r\n      outputs: audio.outputs,\r\n      currentInputId: audio.currentInputId,\r\n      currentOutputId: audio.currentOutputId,\r\n      canSelectOutput: audio.canSelectOutput,\r\n      setInput: (deviceId) => audio.setInput(deviceId),\r\n      setOutput: (deviceId) => audio.setOutput(deviceId),\r\n      setRingtoneOutput: (deviceId) => audio.setRingtoneOutput(deviceId),\r\n      refresh: () => audio.refresh(),\r\n    };\r\n    cache.current = { audio, view };\r\n    return view;\r\n  }, [phone]);\r\n\r\n  return useSyncExternalStore(subscribe, getSnapshot);\r\n}\r\n"]}

package/dist/{chunk-5BGEHMPP.js → chunk-YWI6EQYS.js}

@@ -259,6 +259,14 @@ var SipCallEngine = class {
   #uaInFlight = null;
   #domain = "";
   #activeCall = null;
+  /**
+   * The consult leg from `startConsult` (SPEC §5.6), if one is live on this UA right now.
+   *
+   * Tracked separately from `#activeCall` so `#maybeTeardownUA` can tell "both legs are actually gone"
+   * apart from "the main leg ended, but a consult is still up" — see that method's own comment for the
+   * bug this exists to prevent.
+   */
+  #consultCall = null;
   /** The chosen microphone, or `null` for the browser default. Read fresh by every new leg's
    *  `mediaConstraints`, and pushed live to `#activeCall` by `setInputDevice`. */
   #inputDeviceId = null;
@@ -377,9 +385,7 @@ var SipCallEngine = class {
     const ms = this.provider.quirks?.noInviteTeardownMs;
     if (!ms) return;
     this.#clearNoInviteTimer();
-    this.#noInviteTimer = setTimeout(() => {
-      if (!this.#activeCall) this.#teardownUA();
-    }, ms);
+    this.#noInviteTimer = setTimeout(() => this.#maybeTeardownUA(), ms);
   }
   /**
    * Rebuild the incoming-signal channel with fresh credentials, after a registration failure.
@@ -501,6 +507,7 @@ var SipCallEngine = class {
     }
     this.#ua = null;
     this.#activeCall = null;
+    this.#consultCall = null;
   }
   /** Place a call once the UA is registered (its 200 OK for REGISTER has arrived). */
   /**
@@ -543,7 +550,7 @@ var SipCallEngine = class {
         const code = missed ? "call/missed" : CALL_END_CODES[event.reason];
         if (code) this.#reportError(code, event.cause);
         if (this.#activeCall === call) this.#activeCall = null;
-        if (this.provider.registrationMode === "on-demand") this.#teardownUA();
+        this.#maybeTeardownUA();
       }
     });
     return call;
@@ -554,12 +561,38 @@ var SipCallEngine = class {
       mediaConstraints: buildAudioConstraints(this.#inputDeviceId),
       pcConfig: PC_CONFIG
     });
-    return new SipEngineCall(consultSession, {
+    const consultCall = new SipEngineCall(consultSession, {
       id: nextCallId(),
       buildTarget: (x) => this.#buildTarget(x),
       placeConsult: () => Promise.reject(new Error("cannot consult from a consult leg")),
       iceGatheringCapMs: this.provider.quirks?.iceGatheringCapMs ?? DEFAULT_ICE_CAP_MS
     });
+    this.#consultCall = consultCall;
+    consultCall.onEvent((event) => {
+      if (event.type === "ended") {
+        if (this.#consultCall === consultCall) this.#consultCall = null;
+        this.#maybeTeardownUA();
+      }
+    });
+    return consultCall;
+  }
+  /**
+   * On-demand registration (SPEC §3.3): the UA is disposable once NOTHING is left on it — but "the
+   * main leg ended" (or "no INVITE followed this push") is not the same fact as "nothing is left."
+   * `completeTransfer()` (SPEC §5.6) ends the main leg via a REFER…Replaces BYE *while the consult leg
+   * is still what the PBX needs to bridge the caller onto* — tearing the UA down (and with it, EVERY
+   * session on it, via `terminateSessions`) the instant the main leg's `ended` fires killed that
+   * consult leg out from under the transfer before the bridge could use it, and the caller was simply
+   * gone. Two real call sites hit this independently (found live, 2026-08-04): the main leg's own
+   * `ended` handler, and `#armNoInviteTeardown`'s 5s timer — the latter re-arms on EVERY push,
+   * including unrelated "answered" pushes Zadarma sends around other account activity, so it can fire
+   * minutes after a transfer with no `#activeCall` and no idea a consult leg is mid-handoff. Both now
+   * route through here rather than checking `#activeCall` alone.
+   */
+  #maybeTeardownUA() {
+    if (this.provider.registrationMode !== "on-demand") return;
+    if (this.#activeCall || this.#consultCall) return;
+    this.#teardownUA();
   }
   #startRejectGuard() {
     const ms = this.provider.quirks?.rejectGuardMs;
@@ -941,5 +974,5 @@ function createZadarmaEngine(config) {
 }
 
 export { ZADARMA_QUIRKS, createZadarmaEngine };
-//# sourceMappingURL=chunk-5BGEHMPP.js.map
-//# sourceMappingURL=chunk-5BGEHMPP.js.map
+//# sourceMappingURL=chunk-YWI6EQYS.js.map
+//# sourceMappingURL=chunk-YWI6EQYS.js.map