@speechos/react 1.0.0

package/dist/hooks/useSpeechOSEvents.d.cts

@@ -0,0 +1,32 @@
+/**
+ * useSpeechOSEvents - Hook for subscribing to SpeechOS events
+ *
+ * Automatically handles subscription lifecycle tied to component mount/unmount.
+ */
+import { type SpeechOSEventMap, type UnsubscribeFn } from "@speechos/core";
+/**
+ * Hook to subscribe to SpeechOS events
+ *
+ * Automatically subscribes on mount and unsubscribes on unmount.
+ * The callback is stable - changes to it will update the subscription.
+ *
+ * @example
+ * ```tsx
+ * function TranscriptionListener() {
+ *   useSpeechOSEvents('transcription:complete', (payload) => {
+ *     console.log('Transcription received:', payload.text);
+ *   });
+ *
+ *   useSpeechOSEvents('error', (payload) => {
+ *     console.error('Error:', payload.message);
+ *   });
+ *
+ *   return <div>Listening for events...</div>;
+ * }
+ * ```
+ *
+ * @param event - The event name to subscribe to
+ * @param callback - The callback to invoke when the event fires
+ * @returns Cleanup function (automatically called on unmount)
+ */
+export declare function useSpeechOSEvents<K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void): UnsubscribeFn;

package/dist/hooks/useSpeechOSEvents.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useSpeechOSEvents - Hook for subscribing to SpeechOS events
+ *
+ * Automatically handles subscription lifecycle tied to component mount/unmount.
+ */
+import { type SpeechOSEventMap, type UnsubscribeFn } from "@speechos/core";
+/**
+ * Hook to subscribe to SpeechOS events
+ *
+ * Automatically subscribes on mount and unsubscribes on unmount.
+ * The callback is stable - changes to it will update the subscription.
+ *
+ * @example
+ * ```tsx
+ * function TranscriptionListener() {
+ *   useSpeechOSEvents('transcription:complete', (payload) => {
+ *     console.log('Transcription received:', payload.text);
+ *   });
+ *
+ *   useSpeechOSEvents('error', (payload) => {
+ *     console.error('Error:', payload.message);
+ *   });
+ *
+ *   return <div>Listening for events...</div>;
+ * }
+ * ```
+ *
+ * @param event - The event name to subscribe to
+ * @param callback - The callback to invoke when the event fires
+ * @returns Cleanup function (automatically called on unmount)
+ */
+export declare function useSpeechOSEvents<K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void): UnsubscribeFn;

package/dist/hooks/useSpeechOSState.d.cts

@@ -0,0 +1,30 @@
+/**
+ * useSpeechOSState - Hook for accessing just the SpeechOS state
+ *
+ * A lightweight hook when you only need to read state,
+ * not call any API methods.
+ */
+import type { SpeechOSState } from "@speechos/core";
+/**
+ * Hook to access just the SpeechOS state
+ *
+ * Use this when you only need to read state values like
+ * isConnected, recordingState, etc. without needing the API methods.
+ *
+ * @example
+ * ```tsx
+ * function RecordingIndicator() {
+ *   const state = useSpeechOSState();
+ *
+ *   return (
+ *     <div>
+ *       {state.recordingState === 'recording' && <span>Recording...</span>}
+ *       {state.isConnected && <span>Connected</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns The current SpeechOS state
+ */
+export declare function useSpeechOSState(): SpeechOSState;

package/dist/hooks/useSpeechOSState.d.ts

@@ -0,0 +1,30 @@
+/**
+ * useSpeechOSState - Hook for accessing just the SpeechOS state
+ *
+ * A lightweight hook when you only need to read state,
+ * not call any API methods.
+ */
+import type { SpeechOSState } from "@speechos/core";
+/**
+ * Hook to access just the SpeechOS state
+ *
+ * Use this when you only need to read state values like
+ * isConnected, recordingState, etc. without needing the API methods.
+ *
+ * @example
+ * ```tsx
+ * function RecordingIndicator() {
+ *   const state = useSpeechOSState();
+ *
+ *   return (
+ *     <div>
+ *       {state.recordingState === 'recording' && <span>Recording...</span>}
+ *       {state.isConnected && <span>Connected</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns The current SpeechOS state
+ */
+export declare function useSpeechOSState(): SpeechOSState;

package/dist/hooks/useTranscription.d.cts

@@ -0,0 +1,87 @@
+/**
+ * useTranscription - Low-level hook for granular transcription control
+ *
+ * Provides direct access to the LiveKit connection lifecycle
+ * for advanced use cases that need fine-grained control.
+ */
+import type { SpeechOSState } from "@speechos/core";
+/**
+ * Return type for useTranscription hook
+ */
+export interface UseTranscriptionResult {
+    /** Connect to LiveKit (establishes WebRTC connection) */
+    connect: () => Promise<void>;
+    /** Wait until the agent is ready to receive audio */
+    waitUntilReady: () => Promise<void>;
+    /** Enable microphone (start capturing audio) */
+    enableMicrophone: () => Promise<void>;
+    /** Stop recording and get the transcript */
+    getTranscript: () => Promise<string>;
+    /** Stop recording and get edited text */
+    getEdit: (originalText: string) => Promise<string>;
+    /** Disconnect from LiveKit */
+    disconnect: () => Promise<void>;
+    /** Cancel any ongoing operation */
+    cancel: () => Promise<void>;
+    /** Current connection state */
+    isConnected: boolean;
+    /** Current microphone state */
+    isMicEnabled: boolean;
+    /** Current recording state */
+    recordingState: SpeechOSState["recordingState"];
+}
+/**
+ * Low-level hook for granular transcription control
+ *
+ * Use this when you need fine-grained control over the LiveKit
+ * connection lifecycle. For most use cases, prefer useDictation()
+ * or useEdit() which provide simpler interfaces.
+ *
+ * @example
+ * ```tsx
+ * function CustomVoiceUI() {
+ *   const {
+ *     connect,
+ *     waitUntilReady,
+ *     enableMicrophone,
+ *     getTranscript,
+ *     disconnect,
+ *     isConnected,
+ *     isMicEnabled,
+ *     recordingState,
+ *   } = useTranscription();
+ *
+ *   const handleRecord = async () => {
+ *     // Step 1: Connect to LiveKit
+ *     await connect();
+ *
+ *     // Step 2: Wait for agent to be ready
+ *     await waitUntilReady();
+ *
+ *     // Step 3: Enable microphone
+ *     await enableMicrophone();
+ *
+ *     // ... user speaks ...
+ *
+ *     // Step 4: Get transcript
+ *     const text = await getTranscript();
+ *     console.log('Transcribed:', text);
+ *
+ *     // Step 5: Cleanup
+ *     await disconnect();
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Connected: {isConnected ? 'Yes' : 'No'}</p>
+ *       <p>Mic: {isMicEnabled ? 'On' : 'Off'}</p>
+ *       <p>State: {recordingState}</p>
+ *       <button onClick={handleRecord}>Record</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns Low-level transcription controls and state
+ */
+export declare function useTranscription(): UseTranscriptionResult;

package/dist/hooks/useTranscription.d.ts

@@ -0,0 +1,87 @@
+/**
+ * useTranscription - Low-level hook for granular transcription control
+ *
+ * Provides direct access to the LiveKit connection lifecycle
+ * for advanced use cases that need fine-grained control.
+ */
+import type { SpeechOSState } from "@speechos/core";
+/**
+ * Return type for useTranscription hook
+ */
+export interface UseTranscriptionResult {
+    /** Connect to LiveKit (establishes WebRTC connection) */
+    connect: () => Promise<void>;
+    /** Wait until the agent is ready to receive audio */
+    waitUntilReady: () => Promise<void>;
+    /** Enable microphone (start capturing audio) */
+    enableMicrophone: () => Promise<void>;
+    /** Stop recording and get the transcript */
+    getTranscript: () => Promise<string>;
+    /** Stop recording and get edited text */
+    getEdit: (originalText: string) => Promise<string>;
+    /** Disconnect from LiveKit */
+    disconnect: () => Promise<void>;
+    /** Cancel any ongoing operation */
+    cancel: () => Promise<void>;
+    /** Current connection state */
+    isConnected: boolean;
+    /** Current microphone state */
+    isMicEnabled: boolean;
+    /** Current recording state */
+    recordingState: SpeechOSState["recordingState"];
+}
+/**
+ * Low-level hook for granular transcription control
+ *
+ * Use this when you need fine-grained control over the LiveKit
+ * connection lifecycle. For most use cases, prefer useDictation()
+ * or useEdit() which provide simpler interfaces.
+ *
+ * @example
+ * ```tsx
+ * function CustomVoiceUI() {
+ *   const {
+ *     connect,
+ *     waitUntilReady,
+ *     enableMicrophone,
+ *     getTranscript,
+ *     disconnect,
+ *     isConnected,
+ *     isMicEnabled,
+ *     recordingState,
+ *   } = useTranscription();
+ *
+ *   const handleRecord = async () => {
+ *     // Step 1: Connect to LiveKit
+ *     await connect();
+ *
+ *     // Step 2: Wait for agent to be ready
+ *     await waitUntilReady();
+ *
+ *     // Step 3: Enable microphone
+ *     await enableMicrophone();
+ *
+ *     // ... user speaks ...
+ *
+ *     // Step 4: Get transcript
+ *     const text = await getTranscript();
+ *     console.log('Transcribed:', text);
+ *
+ *     // Step 5: Cleanup
+ *     await disconnect();
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Connected: {isConnected ? 'Yes' : 'No'}</p>
+ *       <p>Mic: {isMicEnabled ? 'On' : 'Off'}</p>
+ *       <p>State: {recordingState}</p>
+ *       <button onClick={handleRecord}>Record</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns Low-level transcription controls and state
+ */
+export declare function useTranscription(): UseTranscriptionResult;