@cuekit-ai/react 1.0.0

package/README.md

@@ -0,0 +1,289 @@
+# CueKit Web SDK
+
+A powerful voice-controlled navigation and interaction SDK for React applications. CueKit enables users to navigate and interact with web applications using natural voice commands, providing an accessible and intuitive user experience.
+
+## 🚀 Features
+
+- **Voice Recognition**: Real-time speech-to-text using Web Speech API
+- **Text-to-Speech**: Built-in TTS for audio feedback
+- **Smart Navigation**: Automatic route detection and navigation
+- **Element Interaction**: Click buttons and interact with UI elements via voice commands
+- **Screen Context Awareness**: Captures and analyzes current screen elements
+- **Cross-Platform**: Works with any React application (Next.js, Create React App, etc.)
+- **Customizable UI**: Flexible microphone button with multiple positioning options
+- **TypeScript Support**: Full TypeScript support with comprehensive type definitions
+
+## 📦 Installation
+
+```bash
+npm install cuekit-web-sdk
+# or
+yarn add cuekit-web-sdk
+```
+
+## 🏗️ Quick Start
+
+### 1. Initialize CueKit
+
+Wrap your app with the `CuekitProvider`:
+
+```tsx
+import { CuekitProvider } from 'cuekit-web-sdk'
+
+function App() {
+  return (
+    <CuekitProvider apiKey="your-api-key" appId="your-app-id" deviceId="optional-device-id">
+      <YourApp />
+    </CuekitProvider>
+  )
+}
+```
+
+### 2. Add Voice Control Button
+
+Add the `MicButton` component to enable voice interactions:
+
+```tsx
+import { MicButton } from 'cuekit-web-sdk'
+
+function YourApp() {
+  return (
+    <div>
+      {/* Your app content */}
+      <MicButton screenPosition="bottom-right" buttonSize={60} hasText={false} />
+    </div>
+  )
+}
+```
+
+### 3. Initialize the SDK
+
+Call `InitCuekit` with your API key:
+
+```tsx
+import { InitCuekit } from 'cuekit-web-sdk'
+
+// Initialize with API key
+InitCuekit('your-api-key')
+```
+
+## 🎯 Core Components
+
+### CuekitProvider
+
+The main provider component that sets up the voice control context.
+
+```tsx
+<CuekitProvider
+  apiKey="your-api-key"
+  appId="your-app-id"
+  deviceId="optional-device-id"
+  navigator={router} // Optional: Pass your router instance
+>
+  {children}
+</CuekitProvider>
+```
+
+**Props:**
+
+- `apiKey` (required): Your CueKit API key
+- `appId` (required): Your application ID
+- `deviceId` (optional): Unique device identifier
+- `navigator` (optional): Router instance for navigation
+- `children`: React components to wrap
+
+### MicButton
+
+A customizable microphone button for voice input.
+
+```tsx
+<MicButton
+  hasText={false}
+  text="Voice Control"
+  screenPosition="bottom-right"
+  buttonSize={60}
+  imageSource="path/to/mic-icon.png"
+  buttonStyle={{ backgroundColor: '#007bff' }}
+/>
+```
+
+**Props:**
+
+- `hasText` (optional): Show text instead of icon
+- `text` (optional): Button text when `hasText` is true
+- `textStyle` (optional): Custom styles for text
+- `imageSource` (optional): Custom microphone icon URL
+- `imageStyle` (optional): Custom styles for image
+- `buttonStyle` (optional): Custom button styles
+- `screenPosition` (optional): Button position (`'bottom-right'`, `'bottom-left'`, `'bottom-center'`)
+- `buttonSize` (optional): Button size in pixels
+
+## 🎤 Voice Recognition
+
+### useVoice Hook
+
+Custom hook for voice recognition functionality:
+
+```tsx
+import { useVoice } from 'cuekit-web-sdk'
+
+function VoiceComponent() {
+  const { isListening, start, stop, transcript } = useVoice()
+
+  const handleVoiceToggle = async () => {
+    if (isListening) {
+      await stop()
+    } else {
+      await start('Hello, how can I help you?')
+    }
+  }
+
+  return <button onClick={handleVoiceToggle}>{isListening ? 'Stop' : 'Start'} Voice</button>
+}
+```
+
+### useVoiceRecognition Hook
+
+Lower-level hook for speech recognition:
+
+```tsx
+import { useVoiceRecognition } from 'cuekit-web-sdk'
+
+function CustomVoiceComponent() {
+  const { isListening, startListening, stopListening, speechText } = useVoiceRecognition('en-US')
+
+  // Custom voice recognition logic
+}
+```
+
+## 🔧 Advanced Usage
+
+### Custom Voice Processing
+
+Process voice input manually:
+
+```tsx
+import { processVoice } from 'cuekit-web-sdk'
+
+const handleVoiceInput = async (transcript: string) => {
+  const result = await processVoice(transcript, 'your-api-key', 'your-app-id', 'device-id')
+
+  console.log('Voice processing result:', result)
+}
+```
+
+### Audio Controller
+
+Manage text-to-speech functionality:
+
+```tsx
+import { useAudioController } from 'cuekit-web-sdk'
+
+function AudioComponent() {
+  const { speak, stop, isSpeaking } = useAudioController()
+
+  const handleSpeak = () => {
+    speak('Hello, this is a test message')
+  }
+
+  return (
+    <div>
+      <button onClick={handleSpeak}>Speak</button>
+      <button onClick={stop}>Stop</button>
+      {isSpeaking && <span>Speaking...</span>}
+    </div>
+  )
+}
+```
+
+### Navigation Integration
+
+For custom navigation handling:
+
+```tsx
+import { onStateChange } from 'cuekit-web-sdk'
+
+// Call this when your app's route changes
+onStateChange()
+```
+
+## 🎨 Customization
+
+### Styling the MicButton
+
+```tsx
+<MicButton
+  buttonStyle={{
+    backgroundColor: '#ff6b6b',
+    boxShadow: '0 4px 12px rgba(0,0,0,0.3)',
+    border: '2px solid #fff',
+  }}
+  textStyle={{
+    fontSize: '16px',
+    fontWeight: 'bold',
+    color: '#fff',
+  }}
+/>
+```
+
+### Custom Positioning
+
+```tsx
+// Bottom right (default)
+<MicButton screenPosition="bottom-right" />
+
+// Bottom left
+<MicButton screenPosition="bottom-left" />
+
+// Bottom center
+<MicButton screenPosition="bottom-center" />
+```
+
+## 🔌 API Integration
+
+The SDK automatically sends component data to the CueKit API for intelligent voice processing. The API analyzes:
+
+- Current screen elements (buttons, links, etc.)
+- User voice input
+- Screen context
+- Navigation patterns
+
+### API Response Format
+
+```typescript
+interface CueKitResponse {
+  actionType: 'navigate' | 'click' | 'audio_only'
+  routeName?: string
+  component?: {
+    hash: string
+    text: string
+    componentType: string
+  }
+  text?: string
+  claudeError?: boolean
+  errorMessage?: string
+}
+```
+
+## 🔒 Security
+
+- API keys are stored securely in the global context
+- Device IDs are automatically generated and persisted
+- Network requests are validated and error-handled
+- No sensitive data is logged to console
+
+## 🌐 Browser Support
+
+- Chrome/Chromium (recommended)
+- Firefox
+- Safari (limited TTS support)
+- Edge
+
+**Note**: Voice recognition requires HTTPS in production environments.
+
+## 📝 License
+
+This project is licensed under the MIT License.
+
+
+**CueKit Web SDK** - Making web applications voice-controlled and accessible.

package/dist/index.d.mts

@@ -0,0 +1,58 @@
+import React, { ReactNode } from 'react';
+
+declare const processVoice: (transcript: string, apiKey?: string, appId?: string, deviceId?: string) => Promise<any | null>;
+
+declare global {
+    interface CueKitGlobalStore {
+        intent: string | null;
+        lastText: string;
+        lastClickedLabel: string;
+        apiKey?: string;
+        appId?: string;
+        deviceId?: string;
+        update: (data: Partial<CueKitGlobalStore>) => void;
+    }
+    var CuekitStore: CueKitGlobalStore;
+}
+type Props = {
+    apiKey: string;
+    deviceId?: string;
+    appId: string;
+    children: ReactNode;
+    navigator?: any;
+};
+declare const CuekitProvider: React.FC<Props>;
+
+declare const useAudioController: () => {
+    stop: () => void;
+    isPlaying: () => boolean;
+    play: (url: string) => Promise<void>;
+};
+
+declare function onStateChange(): void;
+
+type ScreenPosition = 'bottom-center' | 'bottom-left' | 'bottom-right';
+type MicButtonProps = {
+    hasText?: boolean;
+    text?: string;
+    textStyle?: React.CSSProperties;
+    imageSource?: string;
+    imageStyle?: React.CSSProperties;
+    buttonStyle?: React.CSSProperties;
+    screenPosition?: ScreenPosition;
+    bottomSpace?: number;
+    buttonSize?: number;
+};
+
+declare const MicButton: React.FC<MicButtonProps>;
+
+declare function InitCuekit(apiKey: string, navigator?: any): void;
+
+declare const useVoiceRecognition: (lang?: string) => {
+    isListening: boolean;
+    startListening: () => Promise<string>;
+    stopListening: () => Promise<void>;
+    speechText: string;
+};
+
+export { CuekitProvider, InitCuekit, MicButton, onStateChange, processVoice, useAudioController, useVoiceRecognition };

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import React, { ReactNode } from 'react';
+
+declare const processVoice: (transcript: string, apiKey?: string, appId?: string, deviceId?: string) => Promise<any | null>;
+
+declare global {
+    interface CueKitGlobalStore {
+        intent: string | null;
+        lastText: string;
+        lastClickedLabel: string;
+        apiKey?: string;
+        appId?: string;
+        deviceId?: string;
+        update: (data: Partial<CueKitGlobalStore>) => void;
+    }
+    var CuekitStore: CueKitGlobalStore;
+}
+type Props = {
+    apiKey: string;
+    deviceId?: string;
+    appId: string;
+    children: ReactNode;
+    navigator?: any;
+};
+declare const CuekitProvider: React.FC<Props>;
+
+declare const useAudioController: () => {
+    stop: () => void;
+    isPlaying: () => boolean;
+    play: (url: string) => Promise<void>;
+};
+
+declare function onStateChange(): void;
+
+type ScreenPosition = 'bottom-center' | 'bottom-left' | 'bottom-right';
+type MicButtonProps = {
+    hasText?: boolean;
+    text?: string;
+    textStyle?: React.CSSProperties;
+    imageSource?: string;
+    imageStyle?: React.CSSProperties;
+    buttonStyle?: React.CSSProperties;
+    screenPosition?: ScreenPosition;
+    bottomSpace?: number;
+    buttonSize?: number;
+};
+
+declare const MicButton: React.FC<MicButtonProps>;
+
+declare function InitCuekit(apiKey: string, navigator?: any): void;
+
+declare const useVoiceRecognition: (lang?: string) => {
+    isListening: boolean;
+    startListening: () => Promise<string>;
+    stopListening: () => Promise<void>;
+    speechText: string;
+};
+
+export { CuekitProvider, InitCuekit, MicButton, onStateChange, processVoice, useAudioController, useVoiceRecognition };