@coventia/softphone 0.1.0 → 0.2.1

package/dist/{call-BTYlT2SU.d.cts → call-VKq1I8yP.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,104 @@ 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;
+    /**
+     * Says this phone is going away ON PURPOSE (the user turned it off, the app is quitting), so the backend
+     * drops it at once instead of waiting out the close grace it gives every ordinary close. Optional: a host's
+     * own source that has no such message simply omits it and gets the grace. Sent just before `close()`.
+     */
+    readonly bye?: () => 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 +567,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 +600,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 +794,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-VKq1I8yP.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,104 @@ 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;
+    /**
+     * Says this phone is going away ON PURPOSE (the user turned it off, the app is quitting), so the backend
+     * drops it at once instead of waiting out the close grace it gives every ordinary close. Optional: a host's
+     * own source that has no such message simply omits it and gets the grace. Sent just before `close()`.
+     */
+    readonly bye?: () => 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 +567,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 +600,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 +794,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"]}