@coventia/softphone 0.1.0 → 0.2.1

package/dist/element/index.d.ts

@@ -143,14 +143,111 @@ 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[];
+}
+/**
+ * `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>;
 
-/** Contacts, history, caller ID and the agents directory, all from one config. */
+/** Contacts, history, caller ID, the agents directory, transfer outcomes and presence, all from one
+ *  config. */
 interface BackendSources {
     readonly contacts: ContactsSource;
     readonly history: HistorySource;
     readonly resolveContact: (number: string) => Promise<Contact | null>;
     /** The Historial tab's "filter by person" directory. Always Coventia's own org membership. */
     readonly listAgents: () => Promise<AgentsDirectory>;
+    /** Phase A (transfer outcome relay) — polled by the transfer watch, never by UI directly. */
+    readonly transferOutcomes: (params: {
+        readonly since?: string;
+    }) => Promise<TransferOutcomesPage>;
+    /** Phase B (presence-gated transfer picker) — opened by `presence-socket.ts`, never by UI directly. */
+    readonly presence: PresenceSource;
 }
 
 /**
@@ -345,7 +442,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]: {
@@ -362,6 +475,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. */
@@ -528,15 +645,37 @@ 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>;
@@ -647,6 +786,14 @@ interface Softphone extends TypedEmitter<SoftphoneEventMap> {
      */
     readonly sources: BackendSources | null;
     readonly audio: AudioDevices;
+    /**
+     * The live agent-presence list (Phase B, `docs/specs/transfer-presence-picker.md`) — every org
+     * member with a phone extension, whatever their state. Empty when there is no `PresenceSource`
+     * (no Coventia backend, or a host that omitted one), or while this tab is not `online && isLeader`
+     * — never an error, just nothing to show (spec §4.4's own success criterion). Updates fire
+     * `SoftphoneEvent.PresenceChanged`; `usePresence()` is the reactive read.
+     */
+    readonly presence: readonly PresenceEntry[];
     /**
      * False when the browser has blocked audio playback.
      *
@@ -713,8 +860,8 @@ interface SoftphoneElementConfig {
      */
     readonly requireMic?: boolean;
     /**
-     * Play call audio — the remote party, the inbound ring, the outbound ringback. **On by default**;
-     * see `SoftphoneWidgetProps.sounds`.
+     * Play call audio — the remote party, the inbound ring, the outbound ringback, the end-of-call cue
+     * and the keypad's key tones. **On by default**; see `SoftphoneWidgetProps.sounds`.
      *
      * Turning this off makes a connected call silent in both directions, because nothing else attaches
      * the remote `MediaStream`. Only correct when the host attaches `call.remoteStream` itself, or for
@@ -791,6 +938,14 @@ interface SoftphoneElementEventMap {
     'cv-leadership-changed': CustomEvent<{
         readonly isLeader: boolean;
     }>;
+    /**
+     * A transfer's final handoff step resolved — `status` says whether the caller actually reached
+     * `target`. Polled, not instant (Phase A, `docs/specs/transfer-outcome-relay.md`); only for that
+     * handoff, never for the consult leg itself, which already reports its own outcome in real time via
+     * `cv-call-ended` on that leg. **The widget already shows its own dismissable notice for this** —
+     * listen here only for your own logging, or if you are replacing the built-in UI.
+     */
+    'cv-transfer-outcome': CustomEvent<TransferOutcomeEvent>;
 }
 declare global {
     /** `document.querySelector('coventia-softphone')` returns the real type — no cast to set `.softphone`. */