@coventia/softphone 0.1.0

package/dist/ui/index.d.cts

@@ -0,0 +1,188 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { g as Contact, u as ContactsSource, v as HistorySource, a as Call } from '../call-BTYlT2SU.cjs';
+export { w as CallHistoryEntry, x as ContactsPage } from '../call-BTYlT2SU.cjs';
+
+/**
+ * Shaped like a Lucide icon (`size`, `className`, both optional — every SVG prop Lucide's own icons
+ * take is optional too, so a real Lucide component satisfies this structurally) WITHOUT naming
+ * `lucide-react`'s own exported type. A host should not need that package installed just to satisfy
+ * ours — this accepts Lucide itself, or any icon set built the same shape.
+ */
+type ContactActionIcon = (props: {
+    readonly size?: number | string;
+    readonly className?: string;
+}) => ReactNode;
+/**
+ * The one customisable action on a contact's detail page — was the legacy's hard-wired "Ver
+ * mensajes" (`useNavigate('/chats?wa_id=…')`), now genuinely the host's: whatever `onClick` does,
+ * under whatever `label` fits it. "Open a support ticket," "Ver ficha en el CRM," anything.
+ *
+ * Omit `contactAction` entirely and the row simply does not exist — the detail page is then just
+ * the avatar, the name, the phone number, and the call button. A row with a hardcoded label and no
+ * handler would be worse than no row at all.
+ *
+ * Deliberately NOT a render prop (no arbitrary React node accepted here). Every other host-supplied
+ * piece of this widget is DATA — a contacts function, a history array, a callback — never a chunk of
+ * JSX to render as-is; that is what keeps the widget looking like one thing instead of drifting row
+ * by row. `icon` is optional so a partner without a natural icon for their action is not forced to
+ * pick one.
+ */
+interface ContactAction {
+    readonly label: string;
+    readonly icon?: ContactActionIcon;
+    readonly onClick: (contact: Contact) => void;
+}
+
+/**
+ * `'system'` (default) follows the OS via `prefers-color-scheme`. Pin it to match the HOST's theme
+ * instead — the CRM toggles dark with a class (next-themes), not the OS, so a dark OS + light app
+ * would otherwise render a dark widget inside a light page.
+ *
+ *   const { resolvedTheme } = useTheme();
+ *   <SoftphoneWidget theme={resolvedTheme} />
+ */
+type SoftphoneTheme = 'light' | 'dark' | 'system';
+interface SoftphoneWidgetProps {
+    /** Light, dark, or follow the OS (default). See `SoftphoneTheme`. */
+    readonly theme?: SoftphoneTheme;
+    /**
+     * Override the Contactos tab with your own source. Rarely needed — `coventia` already supplies it.
+     * Passing this WITHOUT `coventia` also works, and is how a non-Coventia host would drive the tab.
+     */
+    readonly contacts?: ContactsSource;
+    /**
+     * Override the Historial tab. Rarely correct: Coventia receives the Zadarma events and stores the
+     * calls, so a host-built history is a different, smaller thing than the real one (SPEC §6.6).
+     *
+     * The tab's own "Todas"/"Perdidas" and person filters call this with `missed`/`userId` — an
+     * override that ignores them still works, it just always returns everything regardless of which
+     * filter is selected, which reads as the filter UI being broken. The person filter itself has no
+     * override point: it always reads `softphone.sources.listAgents`, Coventia's own org directory.
+     */
+    readonly history?: HistorySource;
+    /**
+     * Ask for the microphone before showing the dialer. **On by default.**
+     *
+     * A softphone without a microphone is not a softphone, so this is not a feature to opt into — an
+     * integrator who does not know to add a gate would otherwise ship a dialer that looks fine and
+     * fails on the first call, with the browser's permission modal appearing over a ringing
+     * conversation. Being on by default means the failure mode requires a deliberate choice.
+     *
+     * Set `false` when the mic is somebody else's problem: a demo driven by `MockProvider`, a
+     * supervisor view that only watches, or a host that already prompted and wraps the widget itself
+     * (see `MicPermissionGate`).
+     */
+    readonly requireMic?: boolean;
+    /**
+     * Play call audio: the remote party, the inbound ring, the outbound ringback, and a short cue when
+     * a connected call ends — by either side. **On by default.**
+     *
+     * The remote-party half is not a nicety — nothing else attaches the `MediaStream`, so with this
+     * off a connected call is silent in both directions. Turn it off only if the host attaches
+     * `call.remoteStream` itself (see `CallEvent.RemoteStream`), or for a supervisor view that watches
+     * without listening.
+     */
+    readonly sounds?: boolean;
+    /**
+     * The action row on a contact's detail page. Tapping a contact in the list always opens that page
+     * now (avatar, name, phone, `Llamar`) — this is the one optional extra row on it. See
+     * `ContactAction`. Renamed from `onContactAction`, which fired directly on tap with no detail page
+     * in between; that page is what this replaces "open a contact" with (SPEC §4).
+     */
+    readonly contactAction?: ContactAction;
+    /**
+     * A second, independent action chip — this one on the INCOMING call screen, next to the
+     * "Dispositivos" chip, while the phone is ringing. Only shown once the caller resolves to a real
+     * contact (`resolveContact` has to have actually matched them; SPEC §4) — the legacy softphone's
+     * own "Ver mensajes" button used the identical "known contacts only" gate, for the same reason:
+     * there is nothing useful to open for a number that isn't anyone yet.
+     *
+     * Deliberately a SEPARATE prop from `contactAction`, not the same value reused — what is worth
+     * surfacing while someone is actively calling you is not necessarily the same thing that belongs
+     * on that contact's static detail page days later. Same `ContactAction` shape (label, optional
+     * icon, `onClick(contact)`) because it is the same KIND of thing, just a different instance a host
+     * can configure independently, or omit entirely to show only "Dispositivos" there, as today.
+     */
+    readonly incomingCallAction?: ContactAction;
+    /** Extra class on the root, for host layout. */
+    readonly className?: string;
+}
+
+/**
+ * The softphone widget (legacy ZadarmaWidget) — the drop-in call UI. Wrap it in a
+ * `<SoftphoneProvider softphone={…}>` and that is all: it asks for the microphone ITSELF
+ * (`requireMic`, on by default), so no integrator has to know that a phone needs one.
+ *
+ * When a call is live, the call screen takes the whole body and the tabs hide. Otherwise the tabbed
+ * interface (Teclado / Contactos / Historial) shows. Contactos/Historial appear only when their data
+ * source is provided — the widget stays useful as a bare dialer with no backend at all.
+ */
+declare function SoftphoneWidget(props: SoftphoneWidgetProps): react.JSX.Element;
+
+/**
+ * Gate arbitrary children on microphone permission.
+ *
+ * **`SoftphoneWidget` now gates itself** (`requireMic`, on by default), so most integrations need
+ * nothing here — a softphone without a microphone is not a softphone, and making the gate opt-in
+ * meant every integrator had to know to opt in or ship something that fails mid-call.
+ *
+ * This stays exported for hosts that want the prompt somewhere else: their own modal, a page-level
+ * onboarding step, or wrapping something larger than the widget.
+ */
+declare function MicPermissionGate({ children }: Readonly<{
+    children: ReactNode;
+}>): react.JSX.Element;
+
+/**
+ * The keypad view (legacy IdleView). Strings are Spanish (SPEC §2.4).
+ *
+ * Layout is three flex rows — head (fixed) / keypad (flex:1) / foot (fixed) — so the keypad absorbs
+ * whatever height is left. Sizing keys by aspect-ratio instead would overflow the shell and push the
+ * call button under the tab bar.
+ */
+interface DialpadProps {
+    /** The outcome of the last attempt — "Sin respuesta", "Llamada rechazada". Non-fatal only. */
+    readonly outcome?: {
+        readonly code: string;
+        readonly text: string;
+    } | null;
+    /** Called on any action that supersedes that outcome: a digit, a backspace, a dial. */
+    readonly onIntent?: () => void;
+}
+declare function Dialpad({ outcome, onIntent }?: DialpadProps): react.JSX.Element;
+
+/** The active-call view: incoming, outgoing and in-call in one, switched on call.state. */
+declare function CallScreen({ call, incomingCallAction, }: Readonly<{
+    call: Call;
+    incomingCallAction?: ContactAction;
+}>): react.JSX.Element | null;
+
+/**
+ * The Contactos tab — decoupled. Data comes from an injected `ContactsSource`; contacts are
+ * `Contact { id, name, phone }` (never `wa_id`, SPEC §4). Tapping a contact always opens its detail
+ * page (`ContactDetail`) — `contactAction` customises the ONE extra row on it, not what tapping the
+ * list itself does; there is no bypass of the detail page from here.
+ */
+declare function ContactsTab({ source, contactAction, }: Readonly<{
+    source: ContactsSource;
+    contactAction?: ContactAction;
+}>): react.JSX.Element;
+
+/**
+ * The Historial tab — decoupled. Entries come from an injected `HistorySource` (SPEC §4). Tapping a
+ * row always opens its detail page (`HistoryDetail`) — the row's own call button places a call
+ * directly, without opening it. Same split `ContactsTab`/`ContactDetail` already settled on, for the
+ * same reason: a row-wide tap target and a specific, separate action live at different button.
+ *
+ * The two filters (status, person) are local UI state — `HistorySource` merely accepts them as
+ * optional params, same as `ContactsSource` accepts `search`, so a host's own override can honour
+ * them or ignore them. The person directory behind the second filter is different: it is always
+ * Coventia's own org membership (there is no partner override point for it, unlike `contacts`), so
+ * it is read straight off `softphone.sources` rather than threaded through as a prop.
+ */
+declare function HistoryTab({ source }: Readonly<{
+    source: HistorySource;
+}>): react.JSX.Element;
+
+export { CallScreen, ContactsSource, ContactsTab, Dialpad, HistorySource, HistoryTab, MicPermissionGate, type SoftphoneTheme, SoftphoneWidget, type SoftphoneWidgetProps };

package/dist/ui/index.d.ts

@@ -0,0 +1,188 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { g as Contact, u as ContactsSource, v as HistorySource, a as Call } from '../call-BTYlT2SU.js';
+export { w as CallHistoryEntry, x as ContactsPage } from '../call-BTYlT2SU.js';
+
+/**
+ * Shaped like a Lucide icon (`size`, `className`, both optional — every SVG prop Lucide's own icons
+ * take is optional too, so a real Lucide component satisfies this structurally) WITHOUT naming
+ * `lucide-react`'s own exported type. A host should not need that package installed just to satisfy
+ * ours — this accepts Lucide itself, or any icon set built the same shape.
+ */
+type ContactActionIcon = (props: {
+    readonly size?: number | string;
+    readonly className?: string;
+}) => ReactNode;
+/**
+ * The one customisable action on a contact's detail page — was the legacy's hard-wired "Ver
+ * mensajes" (`useNavigate('/chats?wa_id=…')`), now genuinely the host's: whatever `onClick` does,
+ * under whatever `label` fits it. "Open a support ticket," "Ver ficha en el CRM," anything.
+ *
+ * Omit `contactAction` entirely and the row simply does not exist — the detail page is then just
+ * the avatar, the name, the phone number, and the call button. A row with a hardcoded label and no
+ * handler would be worse than no row at all.
+ *
+ * Deliberately NOT a render prop (no arbitrary React node accepted here). Every other host-supplied
+ * piece of this widget is DATA — a contacts function, a history array, a callback — never a chunk of
+ * JSX to render as-is; that is what keeps the widget looking like one thing instead of drifting row
+ * by row. `icon` is optional so a partner without a natural icon for their action is not forced to
+ * pick one.
+ */
+interface ContactAction {
+    readonly label: string;
+    readonly icon?: ContactActionIcon;
+    readonly onClick: (contact: Contact) => void;
+}
+
+/**
+ * `'system'` (default) follows the OS via `prefers-color-scheme`. Pin it to match the HOST's theme
+ * instead — the CRM toggles dark with a class (next-themes), not the OS, so a dark OS + light app
+ * would otherwise render a dark widget inside a light page.
+ *
+ *   const { resolvedTheme } = useTheme();
+ *   <SoftphoneWidget theme={resolvedTheme} />
+ */
+type SoftphoneTheme = 'light' | 'dark' | 'system';
+interface SoftphoneWidgetProps {
+    /** Light, dark, or follow the OS (default). See `SoftphoneTheme`. */
+    readonly theme?: SoftphoneTheme;
+    /**
+     * Override the Contactos tab with your own source. Rarely needed — `coventia` already supplies it.
+     * Passing this WITHOUT `coventia` also works, and is how a non-Coventia host would drive the tab.
+     */
+    readonly contacts?: ContactsSource;
+    /**
+     * Override the Historial tab. Rarely correct: Coventia receives the Zadarma events and stores the
+     * calls, so a host-built history is a different, smaller thing than the real one (SPEC §6.6).
+     *
+     * The tab's own "Todas"/"Perdidas" and person filters call this with `missed`/`userId` — an
+     * override that ignores them still works, it just always returns everything regardless of which
+     * filter is selected, which reads as the filter UI being broken. The person filter itself has no
+     * override point: it always reads `softphone.sources.listAgents`, Coventia's own org directory.
+     */
+    readonly history?: HistorySource;
+    /**
+     * Ask for the microphone before showing the dialer. **On by default.**
+     *
+     * A softphone without a microphone is not a softphone, so this is not a feature to opt into — an
+     * integrator who does not know to add a gate would otherwise ship a dialer that looks fine and
+     * fails on the first call, with the browser's permission modal appearing over a ringing
+     * conversation. Being on by default means the failure mode requires a deliberate choice.
+     *
+     * Set `false` when the mic is somebody else's problem: a demo driven by `MockProvider`, a
+     * supervisor view that only watches, or a host that already prompted and wraps the widget itself
+     * (see `MicPermissionGate`).
+     */
+    readonly requireMic?: boolean;
+    /**
+     * Play call audio: the remote party, the inbound ring, the outbound ringback, and a short cue when
+     * a connected call ends — by either side. **On by default.**
+     *
+     * The remote-party half is not a nicety — nothing else attaches the `MediaStream`, so with this
+     * off a connected call is silent in both directions. Turn it off only if the host attaches
+     * `call.remoteStream` itself (see `CallEvent.RemoteStream`), or for a supervisor view that watches
+     * without listening.
+     */
+    readonly sounds?: boolean;
+    /**
+     * The action row on a contact's detail page. Tapping a contact in the list always opens that page
+     * now (avatar, name, phone, `Llamar`) — this is the one optional extra row on it. See
+     * `ContactAction`. Renamed from `onContactAction`, which fired directly on tap with no detail page
+     * in between; that page is what this replaces "open a contact" with (SPEC §4).
+     */
+    readonly contactAction?: ContactAction;
+    /**
+     * A second, independent action chip — this one on the INCOMING call screen, next to the
+     * "Dispositivos" chip, while the phone is ringing. Only shown once the caller resolves to a real
+     * contact (`resolveContact` has to have actually matched them; SPEC §4) — the legacy softphone's
+     * own "Ver mensajes" button used the identical "known contacts only" gate, for the same reason:
+     * there is nothing useful to open for a number that isn't anyone yet.
+     *
+     * Deliberately a SEPARATE prop from `contactAction`, not the same value reused — what is worth
+     * surfacing while someone is actively calling you is not necessarily the same thing that belongs
+     * on that contact's static detail page days later. Same `ContactAction` shape (label, optional
+     * icon, `onClick(contact)`) because it is the same KIND of thing, just a different instance a host
+     * can configure independently, or omit entirely to show only "Dispositivos" there, as today.
+     */
+    readonly incomingCallAction?: ContactAction;
+    /** Extra class on the root, for host layout. */
+    readonly className?: string;
+}
+
+/**
+ * The softphone widget (legacy ZadarmaWidget) — the drop-in call UI. Wrap it in a
+ * `<SoftphoneProvider softphone={…}>` and that is all: it asks for the microphone ITSELF
+ * (`requireMic`, on by default), so no integrator has to know that a phone needs one.
+ *
+ * When a call is live, the call screen takes the whole body and the tabs hide. Otherwise the tabbed
+ * interface (Teclado / Contactos / Historial) shows. Contactos/Historial appear only when their data
+ * source is provided — the widget stays useful as a bare dialer with no backend at all.
+ */
+declare function SoftphoneWidget(props: SoftphoneWidgetProps): react.JSX.Element;
+
+/**
+ * Gate arbitrary children on microphone permission.
+ *
+ * **`SoftphoneWidget` now gates itself** (`requireMic`, on by default), so most integrations need
+ * nothing here — a softphone without a microphone is not a softphone, and making the gate opt-in
+ * meant every integrator had to know to opt in or ship something that fails mid-call.
+ *
+ * This stays exported for hosts that want the prompt somewhere else: their own modal, a page-level
+ * onboarding step, or wrapping something larger than the widget.
+ */
+declare function MicPermissionGate({ children }: Readonly<{
+    children: ReactNode;
+}>): react.JSX.Element;
+
+/**
+ * The keypad view (legacy IdleView). Strings are Spanish (SPEC §2.4).
+ *
+ * Layout is three flex rows — head (fixed) / keypad (flex:1) / foot (fixed) — so the keypad absorbs
+ * whatever height is left. Sizing keys by aspect-ratio instead would overflow the shell and push the
+ * call button under the tab bar.
+ */
+interface DialpadProps {
+    /** The outcome of the last attempt — "Sin respuesta", "Llamada rechazada". Non-fatal only. */
+    readonly outcome?: {
+        readonly code: string;
+        readonly text: string;
+    } | null;
+    /** Called on any action that supersedes that outcome: a digit, a backspace, a dial. */
+    readonly onIntent?: () => void;
+}
+declare function Dialpad({ outcome, onIntent }?: DialpadProps): react.JSX.Element;
+
+/** The active-call view: incoming, outgoing and in-call in one, switched on call.state. */
+declare function CallScreen({ call, incomingCallAction, }: Readonly<{
+    call: Call;
+    incomingCallAction?: ContactAction;
+}>): react.JSX.Element | null;
+
+/**
+ * The Contactos tab — decoupled. Data comes from an injected `ContactsSource`; contacts are
+ * `Contact { id, name, phone }` (never `wa_id`, SPEC §4). Tapping a contact always opens its detail
+ * page (`ContactDetail`) — `contactAction` customises the ONE extra row on it, not what tapping the
+ * list itself does; there is no bypass of the detail page from here.
+ */
+declare function ContactsTab({ source, contactAction, }: Readonly<{
+    source: ContactsSource;
+    contactAction?: ContactAction;
+}>): react.JSX.Element;
+
+/**
+ * The Historial tab — decoupled. Entries come from an injected `HistorySource` (SPEC §4). Tapping a
+ * row always opens its detail page (`HistoryDetail`) — the row's own call button places a call
+ * directly, without opening it. Same split `ContactsTab`/`ContactDetail` already settled on, for the
+ * same reason: a row-wide tap target and a specific, separate action live at different button.
+ *
+ * The two filters (status, person) are local UI state — `HistorySource` merely accepts them as
+ * optional params, same as `ContactsSource` accepts `search`, so a host's own override can honour
+ * them or ignore them. The person directory behind the second filter is different: it is always
+ * Coventia's own org membership (there is no partner override point for it, unlike `contacts`), so
+ * it is read straight off `softphone.sources` rather than threaded through as a prop.
+ */
+declare function HistoryTab({ source }: Readonly<{
+    source: HistorySource;
+}>): react.JSX.Element;
+
+export { CallScreen, ContactsSource, ContactsTab, Dialpad, HistorySource, HistoryTab, MicPermissionGate, type SoftphoneTheme, SoftphoneWidget, type SoftphoneWidgetProps };