@speechos/core 0.2.0

package/dist/state.d.cts

@@ -0,0 +1,100 @@
+/**
+ * Reactive state management for SpeechOS SDK
+ * Provides a centralized state store with subscriptions (similar to Zustand pattern)
+ */
+import type { SpeechOSState, StateChangeCallback, UnsubscribeFn } from "./types.js";
+/**
+ * State manager class
+ */
+declare class StateManager {
+    private state;
+    private subscribers;
+    constructor(initialState: SpeechOSState);
+    /**
+     * Get the current state (returns a copy to prevent mutations)
+     */
+    getState(): SpeechOSState;
+    /**
+     * Update state with partial values
+     * @param partial - Partial state to merge with current state
+     */
+    setState(partial: Partial<SpeechOSState>): void;
+    /**
+     * Subscribe to state changes
+     * @param callback - Function to call when state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(callback: StateChangeCallback): UnsubscribeFn;
+    /**
+     * Reset state to initial values
+     */
+    reset(): void;
+    /**
+     * Show the widget
+     */
+    show(): void;
+    /**
+     * Hide the widget and reset expanded state
+     */
+    hide(): void;
+    /**
+     * Toggle the action bubbles expansion
+     */
+    toggleExpanded(): void;
+    /**
+     * Set the focused form element
+     * @param element - The form element that has focus
+     */
+    setFocusedElement(element: HTMLElement | null): void;
+    /**
+     * Set the active action
+     * @param action - The action to set as active
+     */
+    setActiveAction(action: SpeechOSState["activeAction"]): void;
+    /**
+     * Set the recording state
+     * @param recordingState - The recording state to set
+     */
+    setRecordingState(recordingState: SpeechOSState["recordingState"]): void;
+    /**
+     * Set the connection state
+     * @param isConnected - Whether connected to LiveKit
+     */
+    setConnected(isConnected: boolean): void;
+    /**
+     * Set the microphone enabled state
+     * @param isMicEnabled - Whether microphone is enabled
+     */
+    setMicEnabled(isMicEnabled: boolean): void;
+    /**
+     * Start recording flow (connecting → recording)
+     */
+    startRecording(): void;
+    /**
+     * Stop recording and start processing
+     */
+    stopRecording(): void;
+    /**
+     * Complete the recording flow and return to idle
+     */
+    completeRecording(): void;
+    /**
+     * Cancel recording and return to idle
+     */
+    cancelRecording(): void;
+    /**
+     * Set error state with a message
+     * @param message - Error message to display
+     */
+    setError(message: string): void;
+    /**
+     * Clear error state and return to idle
+     */
+    clearError(): void;
+}
+export declare const state: StateManager;
+/**
+ * Create a new state manager instance (useful for testing)
+ */
+export declare function createStateManager(initial?: Partial<SpeechOSState>): StateManager;
+export {};

package/dist/state.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Reactive state management for SpeechOS SDK
+ * Provides a centralized state store with subscriptions (similar to Zustand pattern)
+ */
+import type { SpeechOSState, StateChangeCallback, UnsubscribeFn } from "./types.js";
+/**
+ * State manager class
+ */
+declare class StateManager {
+    private state;
+    private subscribers;
+    constructor(initialState: SpeechOSState);
+    /**
+     * Get the current state (returns a copy to prevent mutations)
+     */
+    getState(): SpeechOSState;
+    /**
+     * Update state with partial values
+     * @param partial - Partial state to merge with current state
+     */
+    setState(partial: Partial<SpeechOSState>): void;
+    /**
+     * Subscribe to state changes
+     * @param callback - Function to call when state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(callback: StateChangeCallback): UnsubscribeFn;
+    /**
+     * Reset state to initial values
+     */
+    reset(): void;
+    /**
+     * Show the widget
+     */
+    show(): void;
+    /**
+     * Hide the widget and reset expanded state
+     */
+    hide(): void;
+    /**
+     * Toggle the action bubbles expansion
+     */
+    toggleExpanded(): void;
+    /**
+     * Set the focused form element
+     * @param element - The form element that has focus
+     */
+    setFocusedElement(element: HTMLElement | null): void;
+    /**
+     * Set the active action
+     * @param action - The action to set as active
+     */
+    setActiveAction(action: SpeechOSState["activeAction"]): void;
+    /**
+     * Set the recording state
+     * @param recordingState - The recording state to set
+     */
+    setRecordingState(recordingState: SpeechOSState["recordingState"]): void;
+    /**
+     * Set the connection state
+     * @param isConnected - Whether connected to LiveKit
+     */
+    setConnected(isConnected: boolean): void;
+    /**
+     * Set the microphone enabled state
+     * @param isMicEnabled - Whether microphone is enabled
+     */
+    setMicEnabled(isMicEnabled: boolean): void;
+    /**
+     * Start recording flow (connecting → recording)
+     */
+    startRecording(): void;
+    /**
+     * Stop recording and start processing
+     */
+    stopRecording(): void;
+    /**
+     * Complete the recording flow and return to idle
+     */
+    completeRecording(): void;
+    /**
+     * Cancel recording and return to idle
+     */
+    cancelRecording(): void;
+    /**
+     * Set error state with a message
+     * @param message - Error message to display
+     */
+    setError(message: string): void;
+    /**
+     * Clear error state and return to idle
+     */
+    clearError(): void;
+}
+export declare const state: StateManager;
+/**
+ * Create a new state manager instance (useful for testing)
+ */
+export declare function createStateManager(initial?: Partial<SpeechOSState>): StateManager;
+export {};

package/dist/transcript-store.d.cts

@@ -0,0 +1,35 @@
+/**
+ * Transcript history store
+ * Persists transcripts to localStorage for viewing in the settings modal
+ */
+export type TranscriptAction = "dictate" | "edit";
+export interface TranscriptEntry {
+    id: string;
+    text: string;
+    timestamp: number;
+    action: TranscriptAction;
+    /** Original text before edit (only for edit actions) */
+    originalText?: string;
+}
+/**
+ * Get all transcripts from localStorage
+ */
+export declare function getTranscripts(): TranscriptEntry[];
+/**
+ * Save a new transcript entry
+ */
+export declare function saveTranscript(text: string, action: TranscriptAction, originalText?: string): TranscriptEntry;
+/**
+ * Clear all transcript history
+ */
+export declare function clearTranscripts(): void;
+/**
+ * Delete a single transcript by ID
+ */
+export declare function deleteTranscript(id: string): void;
+export declare const transcriptStore: {
+    getTranscripts: typeof getTranscripts;
+    saveTranscript: typeof saveTranscript;
+    clearTranscripts: typeof clearTranscripts;
+    deleteTranscript: typeof deleteTranscript;
+};

package/dist/transcript-store.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Transcript history store
+ * Persists transcripts to localStorage for viewing in the settings modal
+ */
+export type TranscriptAction = "dictate" | "edit";
+export interface TranscriptEntry {
+    id: string;
+    text: string;
+    timestamp: number;
+    action: TranscriptAction;
+    /** Original text before edit (only for edit actions) */
+    originalText?: string;
+}
+/**
+ * Get all transcripts from localStorage
+ */
+export declare function getTranscripts(): TranscriptEntry[];
+/**
+ * Save a new transcript entry
+ */
+export declare function saveTranscript(text: string, action: TranscriptAction, originalText?: string): TranscriptEntry;
+/**
+ * Clear all transcript history
+ */
+export declare function clearTranscripts(): void;
+/**
+ * Delete a single transcript by ID
+ */
+export declare function deleteTranscript(id: string): void;
+export declare const transcriptStore: {
+    getTranscripts: typeof getTranscripts;
+    saveTranscript: typeof saveTranscript;
+    clearTranscripts: typeof clearTranscripts;
+    deleteTranscript: typeof deleteTranscript;
+};

package/dist/types.d.cts

@@ -0,0 +1,137 @@
+/**
+ * Shared TypeScript types for SpeechOS Core SDK
+ */
+/**
+ * Server error message structure received via LiveKit data channel
+ */
+export interface ServerErrorMessage {
+    type: "error";
+    /** Error code identifying the type of error (e.g., "transcription_failed", "edit_failed") */
+    code?: string;
+    /** User-facing error message */
+    message: string;
+    /** Optional technical details for debugging */
+    details?: string;
+}
+/**
+ * Error source indicating where the error originated
+ */
+export type ErrorSource = "init" | "connection" | "timeout" | "server";
+/**
+ * Configuration options for initializing SpeechOS
+ */
+export interface SpeechOSConfig {
+    /** API key for authentication with SpeechOS backend */
+    apiKey?: string;
+    /** Optional user identifier for tracking which end user is using the SDK */
+    userId?: string;
+    /** Backend host URL for API calls (default: https://app.speechos.ai) */
+    host?: string;
+    /** Position of the widget on screen (used by client package) */
+    position?: "bottom-center" | "bottom-right" | "bottom-left";
+    /** Custom z-index for widget overlay (used by client package) */
+    zIndex?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * LiveKit token response from the backend
+ */
+export interface LiveKitTokenResponse {
+    token: string;
+    ws_url: string;
+    room: string;
+    identity: string;
+}
+/**
+ * Available actions that can be triggered from the widget
+ */
+export type SpeechOSAction = "dictate" | "edit";
+/**
+ * Recording/dictation states
+ */
+export type RecordingState = "idle" | "connecting" | "recording" | "processing" | "error";
+/**
+ * Internal state of the SpeechOS SDK
+ */
+export interface SpeechOSState {
+    /** Whether the widget is visible on screen */
+    isVisible: boolean;
+    /** Whether the action bubbles are expanded */
+    isExpanded: boolean;
+    /** Whether connected to LiveKit room */
+    isConnected: boolean;
+    /** Whether microphone is enabled and publishing */
+    isMicEnabled: boolean;
+    /** Currently active action, if any */
+    activeAction: SpeechOSAction | null;
+    /** The form field element that currently has focus (set by client) */
+    focusedElement: HTMLElement | null;
+    /** Current recording state */
+    recordingState: RecordingState;
+    /** Error message to display (if any) */
+    errorMessage: string | null;
+}
+/**
+ * Event payload types for SpeechOS events
+ *
+ * Events are organized into categories:
+ * - Core events: Emitted by @speechos/core (no DOM dependencies)
+ * - Client events: Emitted by @speechos/client (DOM-specific)
+ */
+export interface SpeechOSEventMap {
+    /** Emitted when a text input field receives focus */
+    "form:focus": {
+        element: HTMLElement;
+    };
+    /** Emitted when focus leaves a text input field */
+    "form:blur": {
+        element: HTMLElement | null;
+    };
+    /** Emitted when the widget becomes visible */
+    "widget:show": void;
+    /** Emitted when the widget is hidden */
+    "widget:hide": void;
+    /** Emitted when user selects an action (dictate/edit) */
+    "action:select": {
+        action: SpeechOSAction;
+    };
+    /** Emitted when internal state changes */
+    "state:change": {
+        state: SpeechOSState;
+    };
+    /** Emitted when transcription is received from the server */
+    "transcription:complete": {
+        text: string;
+    };
+    /** Emitted when edited text is received from the server */
+    "edit:complete": {
+        text: string;
+        originalText: string;
+    };
+    /** Emitted when transcribed text is inserted into a form field */
+    "transcription:inserted": {
+        text: string;
+        element: HTMLElement;
+    };
+    /** Emitted when edited text is applied to a form field */
+    "edit:applied": {
+        originalContent: string;
+        editedContent: string;
+        element: HTMLElement;
+    };
+    /** Emitted when an error occurs */
+    error: {
+        code: string;
+        message: string;
+        source: ErrorSource;
+    };
+}
+/**
+ * Callback function for state changes
+ */
+export type StateChangeCallback = (newState: SpeechOSState, prevState: SpeechOSState) => void;
+/**
+ * Unsubscribe function returned by event listeners
+ */
+export type UnsubscribeFn = () => void;

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared TypeScript types for SpeechOS Core SDK
+ */
+/**
+ * Server error message structure received via LiveKit data channel
+ */
+export interface ServerErrorMessage {
+    type: "error";
+    /** Error code identifying the type of error (e.g., "transcription_failed", "edit_failed") */
+    code?: string;
+    /** User-facing error message */
+    message: string;
+    /** Optional technical details for debugging */
+    details?: string;
+}
+/**
+ * Error source indicating where the error originated
+ */
+export type ErrorSource = "init" | "connection" | "timeout" | "server";
+/**
+ * Configuration options for initializing SpeechOS
+ */
+export interface SpeechOSConfig {
+    /** API key for authentication with SpeechOS backend */
+    apiKey?: string;
+    /** Optional user identifier for tracking which end user is using the SDK */
+    userId?: string;
+    /** Backend host URL for API calls (default: https://app.speechos.ai) */
+    host?: string;
+    /** Position of the widget on screen (used by client package) */
+    position?: "bottom-center" | "bottom-right" | "bottom-left";
+    /** Custom z-index for widget overlay (used by client package) */
+    zIndex?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * LiveKit token response from the backend
+ */
+export interface LiveKitTokenResponse {
+    token: string;
+    ws_url: string;
+    room: string;
+    identity: string;
+}
+/**
+ * Available actions that can be triggered from the widget
+ */
+export type SpeechOSAction = "dictate" | "edit";
+/**
+ * Recording/dictation states
+ */
+export type RecordingState = "idle" | "connecting" | "recording" | "processing" | "error";
+/**
+ * Internal state of the SpeechOS SDK
+ */
+export interface SpeechOSState {
+    /** Whether the widget is visible on screen */
+    isVisible: boolean;
+    /** Whether the action bubbles are expanded */
+    isExpanded: boolean;
+    /** Whether connected to LiveKit room */
+    isConnected: boolean;
+    /** Whether microphone is enabled and publishing */
+    isMicEnabled: boolean;
+    /** Currently active action, if any */
+    activeAction: SpeechOSAction | null;
+    /** The form field element that currently has focus (set by client) */
+    focusedElement: HTMLElement | null;
+    /** Current recording state */
+    recordingState: RecordingState;
+    /** Error message to display (if any) */
+    errorMessage: string | null;
+}
+/**
+ * Event payload types for SpeechOS events
+ *
+ * Events are organized into categories:
+ * - Core events: Emitted by @speechos/core (no DOM dependencies)
+ * - Client events: Emitted by @speechos/client (DOM-specific)
+ */
+export interface SpeechOSEventMap {
+    /** Emitted when a text input field receives focus */
+    "form:focus": {
+        element: HTMLElement;
+    };
+    /** Emitted when focus leaves a text input field */
+    "form:blur": {
+        element: HTMLElement | null;
+    };
+    /** Emitted when the widget becomes visible */
+    "widget:show": void;
+    /** Emitted when the widget is hidden */
+    "widget:hide": void;
+    /** Emitted when user selects an action (dictate/edit) */
+    "action:select": {
+        action: SpeechOSAction;
+    };
+    /** Emitted when internal state changes */
+    "state:change": {
+        state: SpeechOSState;
+    };
+    /** Emitted when transcription is received from the server */
+    "transcription:complete": {
+        text: string;
+    };
+    /** Emitted when edited text is received from the server */
+    "edit:complete": {
+        text: string;
+        originalText: string;
+    };
+    /** Emitted when transcribed text is inserted into a form field */
+    "transcription:inserted": {
+        text: string;
+        element: HTMLElement;
+    };
+    /** Emitted when edited text is applied to a form field */
+    "edit:applied": {
+        originalContent: string;
+        editedContent: string;
+        element: HTMLElement;
+    };
+    /** Emitted when an error occurs */
+    error: {
+        code: string;
+        message: string;
+        source: ErrorSource;
+    };
+}
+/**
+ * Callback function for state changes
+ */
+export type StateChangeCallback = (newState: SpeechOSState, prevState: SpeechOSState) => void;
+/**
+ * Unsubscribe function returned by event listeners
+ */
+export type UnsubscribeFn = () => void;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@speechos/core",
+  "version": "0.2.0",
+  "description": "Headless core SDK for SpeechOS - state, events, LiveKit integration",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/speechos-org/speechos.git",
+    "directory": "speechos-client/packages/core"
+  },
+  "homepage": "https://speechos.ai",
+  "bugs": {
+    "url": "https://github.com/speechos-org/speechos/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "speechos",
+    "sdk",
+    "core",
+    "voice",
+    "ai",
+    "headless"
+  ],
+  "author": "SpeechOS",
+  "license": "MIT",
+  "devDependencies": {
+    "tsdown": "^0.2.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "livekit-client": "^2.16.1"
+  }
+}