@primoia/vocall-react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,530 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+declare enum FieldType {
+    Text = "text",
+    Number = "number",
+    Currency = "currency",
+    Date = "date",
+    Datetime = "datetime",
+    Email = "email",
+    Phone = "phone",
+    Masked = "masked",
+    Select = "select",
+    Autocomplete = "autocomplete",
+    Checkbox = "checkbox",
+    Radio = "radio",
+    Textarea = "textarea",
+    File = "file",
+    Hidden = "hidden"
+}
+interface SelectOption {
+    value: string;
+    label: string;
+}
+interface FieldDescriptor {
+    id: string;
+    type: FieldType | string;
+    label: string;
+    required?: boolean;
+    mask?: string;
+    placeholder?: string;
+    options?: SelectOption[];
+    source?: string;
+    min?: number;
+    max?: number;
+    maxLength?: number;
+    readOnly?: boolean;
+}
+interface ActionDescriptor {
+    id: string;
+    label: string;
+    destructive?: boolean;
+    requiresConfirmation?: boolean;
+    disabled?: boolean;
+}
+interface ModalDescriptor {
+    id: string;
+    label: string;
+    searchable?: boolean;
+}
+interface ScreenDescriptor {
+    id: string;
+    label: string;
+    route?: string;
+    fields?: FieldDescriptor[];
+    actions?: ActionDescriptor[];
+    modals?: ModalDescriptor[];
+}
+interface Persona {
+    name?: string;
+    role?: string;
+    instructions?: string;
+}
+interface UserInfo {
+    name?: string;
+    email?: string;
+    org?: string;
+    role?: string;
+}
+interface ManifestMessage {
+    type: 'manifest';
+    app: string;
+    screens: Record<string, ScreenDescriptor>;
+    version?: string;
+    currentScreen?: string;
+    user?: UserInfo;
+    context?: Record<string, unknown>;
+    persona?: Persona;
+}
+interface TextMessage {
+    type: 'text';
+    message: string;
+}
+interface ConfirmMessage {
+    type: 'confirm';
+    seq: number;
+    confirmed: boolean;
+}
+interface ActionResult {
+    index: number;
+    success: boolean;
+    error?: string;
+}
+interface FieldState {
+    value: unknown;
+    valid?: boolean;
+    error?: string;
+    dirty?: boolean;
+}
+interface StateMessage {
+    type: 'state';
+    screen: string;
+    fields?: Record<string, FieldState>;
+    canSubmit?: boolean;
+}
+interface ResultMessage {
+    type: 'result';
+    seq: number;
+    results: ActionResult[];
+    state?: StateMessage;
+}
+interface FeaturesConfig {
+    voice?: boolean;
+    chat?: boolean;
+}
+interface ConfigResponse {
+    type: 'config';
+    sessionId: string;
+    features?: FeaturesConfig;
+}
+interface UIAction {
+    do: string;
+    screen?: string;
+    field?: string;
+    action?: string;
+    modal?: string;
+    value?: unknown;
+    query?: string;
+    message?: string;
+    animate?: string;
+    speed?: number;
+    duration?: number;
+    level?: string;
+}
+interface CommandMessage {
+    type: 'command';
+    seq: number;
+    actions: UIAction[];
+}
+interface ChatMessageOut {
+    type: 'chat';
+    from: string;
+    message: string;
+    final?: boolean;
+}
+interface ChatTokenOut {
+    type: 'chat_token';
+    token: string;
+}
+interface ChatEndOut {
+    type: 'chat_end';
+}
+interface StatusOut {
+    type: 'status';
+    status: string;
+}
+interface ErrorOut {
+    type: 'error';
+    message: string;
+    code?: string;
+}
+declare enum ChatRole {
+    User = "user",
+    Agent = "agent",
+    System = "system"
+}
+interface ChatMessage {
+    role: ChatRole;
+    text: string;
+    timestamp: Date;
+}
+declare enum VocallStatus {
+    Disconnected = "disconnected",
+    Idle = "idle",
+    Listening = "listening",
+    Recording = "recording",
+    Thinking = "thinking",
+    Speaking = "speaking",
+    Executing = "executing"
+}
+type VoiceState$1 = 'idle' | 'listening' | 'recording' | 'thinking' | 'speaking';
+type ServerMessage = ConfigResponse | ChatMessageOut | ChatTokenOut | ChatEndOut | StatusOut | CommandMessage | ErrorOut | {
+    type: string;
+    [key: string]: unknown;
+};
+
+interface FieldEntry {
+    /** The HTML input/select/textarea element */
+    element: HTMLElement;
+    /** Setter to update the value programmatically (triggers change detection) */
+    setValue: (value: string) => void;
+    /** Getter for the current value */
+    getValue: () => string;
+}
+type ActionCallback = () => void | Promise<void>;
+type NavigateCallback = (screenId: string) => void;
+type ModalOpenCallback = (modalId: string, query?: string) => void;
+type ModalCloseCallback = () => void;
+type ToastCallback = (message: string, level: string, duration?: number) => void;
+type ConfirmCallback = (seq: number, message: string) => void;
+type VocallChangeListener = () => void;
+declare class VocallClient {
+    readonly serverUrl: string;
+    token?: string;
+    private _visitorId;
+    get visitorId(): string;
+    set visitorId(id: string);
+    private _status;
+    get status(): VocallStatus;
+    private _connected;
+    get connected(): boolean;
+    private _messages;
+    get messages(): readonly ChatMessage[];
+    private _sessionId;
+    get sessionId(): string | null;
+    private _voiceEnabled;
+    get voiceEnabled(): boolean;
+    /** Whether the platform supports voice capture (Web Audio API). */
+    get voiceSupported(): boolean;
+    private _voiceState;
+    get voiceState(): VoiceState$1;
+    private _recording;
+    get recording(): boolean;
+    private _partialTranscription;
+    get partialTranscription(): string | null;
+    private _audioLevel;
+    get audioLevel(): number;
+    private _voiceWs;
+    private _alwaysListening;
+    private _ttsActive;
+    private _ttsEndReceived;
+    private _llmDone;
+    private _pendingTtsChunks;
+    private _voice;
+    private _getVoice;
+    private _listeners;
+    subscribe(listener: VocallChangeListener): () => void;
+    private _notify;
+    onNavigate: NavigateCallback | null;
+    onToast: ToastCallback | null;
+    onConfirm: ConfirmCallback | null;
+    onOpenModal: ModalOpenCallback | null;
+    onCloseModal: ModalCloseCallback | null;
+    private _fields;
+    private _actions;
+    private _ws;
+    private _manifest;
+    private _tokenBuffer;
+    private _streamingMessage;
+    private _reconnectTimer;
+    private _reconnectAttempts;
+    private _intentionalDisconnect;
+    private _pendingConfirmSeq;
+    private static readonly MAX_RECONNECT_ATTEMPTS;
+    private static readonly RETRY_DELAY_MS;
+    private static readonly MAX_RETRIES;
+    private static readonly SEQUENTIAL_ACTIONS;
+    constructor(serverUrl: string, options?: {
+        token?: string;
+        visitorId?: string;
+    });
+    private static _generateUuid;
+    private static _loadOrCreateVisitorId;
+    registerField(screenId: string, fieldId: string, entry: FieldEntry): void;
+    unregisterField(screenId: string, fieldId: string): void;
+    unregisterScreen(screenId: string): void;
+    registerAction(screenId: string, actionId: string, callback: ActionCallback): void;
+    unregisterAction(screenId: string, actionId: string): void;
+    findField(fieldId: string): FieldEntry | undefined;
+    findAction(actionId: string): ActionCallback | undefined;
+    connect(manifest: ManifestMessage): void;
+    private _doConnect;
+    disconnect(intentional?: boolean): void;
+    sendText(text: string): void;
+    sendConfirm(seq: number, confirmed: boolean): void;
+    sendResult(seq: number, results: ActionResult[], state?: StateMessage): void;
+    sendState(state: StateMessage): void;
+    private _wsSend;
+    private _onMessage;
+    private _handleConfig;
+    private _handleHistory;
+    private _handleChat;
+    private _handleChatToken;
+    private _flushTokenBuffer;
+    private _handleStatus;
+    private _mapStatus;
+    private _handleError;
+    private _handleCommand;
+    private _executeAction;
+    private _execNavigate;
+    private _execFill;
+    private _typewriterFill;
+    private _execClear;
+    private _execSelect;
+    private _execClick;
+    private _execFocus;
+    private _execHighlight;
+    private _execScrollTo;
+    private _execShowToast;
+    private _execAskConfirm;
+    private _execOpenModal;
+    private _execCloseModal;
+    private _execEnable;
+    private _execDisable;
+    startAlwaysListening(): Promise<void>;
+    stopAlwaysListening(): void;
+    startRecording(): Promise<void>;
+    stopRecording(): void;
+    interrupt(): void;
+    private _openVoiceWs;
+    private _closeVoiceWs;
+    private _resetTtsState;
+    private _onVoiceStreamMessage;
+    private _onPlaybackComplete;
+    private _finalizeTts;
+    private _addMessage;
+    clearMessages(): void;
+    private _onDone;
+    private _onError;
+    private _scheduleReconnect;
+    private _sleep;
+    destroy(): void;
+}
+
+interface VocallProviderProps {
+    serverUrl: string;
+    token?: string;
+    visitorId?: string;
+    children: React.ReactNode;
+}
+declare function VocallProvider({ serverUrl, token, visitorId, children }: VocallProviderProps): react_jsx_runtime.JSX.Element;
+declare function useVocallClient(): VocallClient;
+
+interface UseVocallReturn {
+    client: ReturnType<typeof useVocallClient>;
+    status: VocallStatus;
+    messages: readonly ChatMessage[];
+    connected: boolean;
+    sessionId: string | null;
+    voiceEnabled: boolean;
+    voiceSupported: boolean;
+    voiceState: VoiceState$1;
+    recording: boolean;
+    partialTranscription: string | null;
+    sendText: (text: string) => void;
+    connect: (manifest: ManifestMessage) => void;
+    disconnect: () => void;
+    clearMessages: () => void;
+}
+declare function useVocall(): UseVocallReturn;
+
+interface UseVocallFieldReturn {
+    /** Attach to the field element via ref={ref} */
+    ref: (element: HTMLElement | null) => void;
+    /** Whether the field is currently registered with the client */
+    registered: boolean;
+}
+declare function useVocallField(screenId: string, fieldId: string, options?: {
+    /** Custom setter (e.g. for React state-controlled inputs) */
+    setValue?: (value: string) => void;
+    /** Custom getter */
+    getValue?: () => string;
+}): UseVocallFieldReturn;
+
+/**
+ * Registers an action callback with the Vocall client.
+ *
+ * @param screenId - Screen that owns this action
+ * @param actionId - Action identifier (matches manifest)
+ * @param callback - Function invoked when the server sends a `click` command
+ */
+declare function useVocallAction(screenId: string, actionId: string, callback: ActionCallback): void;
+
+declare class FrameSplitter {
+    private readonly frameSizeBytes;
+    private buffer;
+    private offset;
+    constructor(frameSizeBytes?: number);
+    /**
+     * Feed arbitrary-length PCM bytes into the splitter.
+     * Whenever a full frame is assembled, `emit` is called with a copy.
+     */
+    feed(pcmBytes: Uint8Array, emit: (frame: Uint8Array) => void): void;
+    /** Reset the internal buffer, discarding any partial frame. */
+    reset(): void;
+    /** Number of bytes currently buffered (incomplete frame). */
+    get buffered(): number;
+}
+
+type AudioLevelCallback = (level: number) => void;
+interface VoiceService {
+    /** Whether the browser supports getUserMedia / Web Audio API. */
+    readonly isSupported: boolean;
+    /** Whether audio capture is currently active. */
+    readonly isCapturing: boolean;
+    /** Whether audio playback is currently active. */
+    readonly isPlaying: boolean;
+    /** Whether monitor-only mode is active (capture without sending). */
+    readonly isMonitoring: boolean;
+    /** Called with the current RMS audio level (0-1) during capture. */
+    onAudioLevel: AudioLevelCallback | null;
+    /** Called when all queued audio chunks have finished playing. */
+    onPlaybackComplete: (() => void) | null;
+    /**
+     * Start capturing audio from the microphone.
+     * PCM S16LE 16kHz mono frames are delivered via `sendChunk`.
+     */
+    startCapture(sendChunk: (chunk: Uint8Array) => void): Promise<void>;
+    /** Stop capturing audio. */
+    stopCapture(): void;
+    /** Start monitor mode: capture pipeline runs but no data is sent. */
+    startMonitor(): Promise<void>;
+    /** Stop monitor mode. */
+    stopMonitor(): void;
+    /** Mute or unmute the microphone track. When muted, silent frames are sent. */
+    muteMic(muted: boolean): void;
+    /** Play a WAV audio chunk via the Web Audio API. Queues if already playing. */
+    playAudio(wavData: Uint8Array): void;
+    /** Stop all playback immediately. */
+    stopPlayback(): void;
+    /** Release all resources (streams, AudioContext, etc.). */
+    dispose(): void;
+}
+
+declare class WebVoiceService implements VoiceService {
+    onAudioLevel: AudioLevelCallback | null;
+    onPlaybackComplete: (() => void) | null;
+    private _isCapturing;
+    private _isPlaying;
+    private _isMonitoring;
+    private _isMuted;
+    get isSupported(): boolean;
+    get isCapturing(): boolean;
+    get isPlaying(): boolean;
+    get isMonitoring(): boolean;
+    private _audioCtx;
+    private _stream;
+    private _sourceNode;
+    private _scriptNode;
+    private _splitter;
+    private _sendChunk;
+    private _playbackCtx;
+    private _playbackQueue;
+    private _currentSource;
+    private _pendingDecodes;
+    startCapture(sendChunk: (chunk: Uint8Array) => void): Promise<void>;
+    stopCapture(): void;
+    startMonitor(): Promise<void>;
+    stopMonitor(): void;
+    muteMic(muted: boolean): void;
+    playAudio(wavData: Uint8Array): void;
+    stopPlayback(): void;
+    dispose(): void;
+    private _initCapturePipeline;
+    private _teardownCapturePipeline;
+    /**
+     * Downsample Float32 audio at native sample rate to S16LE at TARGET_SAMPLE_RATE
+     * using linear interpolation.
+     */
+    private _downsampleToS16LE;
+    /**
+     * Compute RMS level from Float32 audio samples.
+     * Result is scaled by 4 and clamped to [0, 1].
+     */
+    private _computeAndEmitLevel;
+    private _decodeAndEnqueue;
+    private _applyFadeIn;
+    private _playBuffer;
+    private _playNextChunk;
+    private _checkPlaybackComplete;
+}
+
+type VoiceState = 'idle' | 'listening' | 'recording' | 'thinking' | 'speaking';
+interface UseVocallVoiceReturn {
+    /** Whether the server indicated voice is available for this session. */
+    voiceEnabled: boolean;
+    /** Current state of the voice state machine. */
+    voiceState: VoiceState;
+    /** Whether audio is currently being captured (direct mode). */
+    recording: boolean;
+    /** Partial transcription text from the server (live). */
+    partialTranscription: string | null;
+    /** Current microphone audio level (0-1). */
+    audioLevel: number;
+    /** Start always-listening mode (wake-word activated). */
+    startAlwaysListening: () => Promise<void>;
+    /** Stop always-listening mode. */
+    stopAlwaysListening: () => void;
+    /** Start direct recording (click-to-talk). */
+    startRecording: () => Promise<void>;
+    /** Stop direct recording and send EOF. */
+    stopRecording: () => void;
+    /** Interrupt TTS playback and notify the server. */
+    interrupt: () => void;
+}
+declare function useVocallVoice(): UseVocallVoiceReturn;
+
+interface VocallChatProps {
+    /** Whether the chat panel is visible */
+    open: boolean;
+    /** Called when the user requests to close the panel */
+    onClose?: () => void;
+    /** Assistant name displayed in the header */
+    assistantName?: string;
+    /** CSS class for the container */
+    className?: string;
+    /** Inline styles for the container */
+    style?: React.CSSProperties;
+}
+declare function VocallChat({ open, onClose, assistantName, className, style, }: VocallChatProps): react_jsx_runtime.JSX.Element | null;
+
+interface VocallFabProps {
+    /** Called when the FAB is clicked */
+    onClick?: () => void;
+    /** CSS class */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+}
+declare function VocallFab({ onClick, className, style }: VocallFabProps): react_jsx_runtime.JSX.Element;
+
+interface VocallStatusProps {
+    /** CSS class */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+}
+declare function VocallStatusPill({ className, style }: VocallStatusProps): react_jsx_runtime.JSX.Element | null;
+
+export { type ActionCallback, type ActionDescriptor, type ActionResult, type AudioLevelCallback, type ChatEndOut, type ChatMessage, type ChatMessageOut, ChatRole, type ChatTokenOut, type CommandMessage, type ConfigResponse, type ConfirmCallback, type ConfirmMessage, type ErrorOut, type FeaturesConfig, type FieldDescriptor, type FieldEntry, type FieldState, FieldType, FrameSplitter, type ManifestMessage, type ModalCloseCallback, type ModalDescriptor, type ModalOpenCallback, type NavigateCallback, type Persona, type ResultMessage, type ScreenDescriptor, type SelectOption, type ServerMessage, type StateMessage, type StatusOut, type TextMessage, type ToastCallback, type UIAction, type UseVocallFieldReturn, type UseVocallReturn, type UseVocallVoiceReturn, type UserInfo, type VocallChangeListener, VocallChat, type VocallChatProps, VocallClient, VocallFab, type VocallFabProps, VocallProvider, type VocallProviderProps, VocallStatus, VocallStatusPill, type VocallStatusProps, type VoiceService, type VoiceState$1 as VoiceState, WebVoiceService, useVocall, useVocallAction, useVocallClient, useVocallField, useVocallVoice };