ai-input-react 1.0.0-beta.1

package/README.md

@@ -0,0 +1,294 @@
+# ai-input-react
+
+[![npm version](https://img.shields.io/npm/v/ai-input-react.svg)](https://www.npmjs.com/package/ai-input-react)
+[![license](https://img.shields.io/npm/l/ai-input-react.svg)](https://github.com/Soptik1290/ai-input/blob/main/LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/ai-input-react.svg)](https://www.npmjs.com/package/ai-input-react)
+
+**A React input component with AI text/voice support.** Unified text and audio input with real-time waveform visualization, designed for AI-powered applications.
+
+## Why Use This?
+
+- 🎤 **Unified Input** – Text and audio in a single component
+- 🌊 **Real-time Waveform** – Audio visualization during recording  
+- 🎨 **Zero Config Styling** – Prepacked CSS, no Tailwind needed
+- 🔌 **Headless Mode** – Full control with render props
+- ⚡ **Framework Agnostic** – Next.js, Vite, Laravel, etc.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install ai-input-react
+
+# yarn
+yarn add ai-input-react
+
+# pnpm
+pnpm add ai-input-react
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { AiInput } from 'ai-input-react'
+import 'ai-input-react/styles.css'
+
+function App() {
+  return (
+    <AiInput
+      send={async (input) => {
+        const res = await fetch('/api/chat', {
+          method: 'POST',
+          body: JSON.stringify({ message: input }),
+        })
+        return res.json()
+      }}
+      onSuccess={(result) => console.log('Response:', result)}
+    />
+  )
+}
+```
+
+That's it! The component includes text input with a microphone button for audio recording.
+
+---
+
+## Framework Examples
+
+<details>
+<summary><strong>Next.js (App Router)</strong></summary>
+
+```tsx
+// app/page.tsx
+'use client'
+
+import { AiInput } from 'ai-input-react'
+import 'ai-input-react/styles.css'
+
+export default function Home() {
+  return (
+    <AiInput
+      send={async (input) => {
+        const res = await fetch('/api/chat', {
+          method: 'POST',
+          body: JSON.stringify({ message: input }),
+        })
+        return res.json()
+      }}
+    />
+  )
+}
+```
+</details>
+
+<details>
+<summary><strong>Laravel + Inertia</strong></summary>
+
+```tsx
+// resources/js/Pages/Chat.tsx
+import { AiInput } from 'ai-input-react'
+import 'ai-input-react/styles.css'
+
+export default function Chat({ csrfToken }: { csrfToken: string }) {
+  return (
+    <AiInput
+      send={async (input) => {
+        const res = await fetch('/api/chat', {
+          method: 'POST',
+          headers: {
+            'X-CSRF-TOKEN': csrfToken,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({ message: input }),
+        })
+        return res.json()
+      }}
+    />
+  )
+}
+```
+</details>
+
+<details>
+<summary><strong>Vite</strong></summary>
+
+```tsx
+// src/App.tsx
+import { AiInput } from 'ai-input-react'
+import 'ai-input-react/styles.css'
+
+export default function App() {
+  return (
+    <AiInput
+      send={async (input) => {
+        const res = await fetch('/api/chat', {
+          method: 'POST',
+          body: JSON.stringify({ message: input }),
+        })
+        return res.json()
+      }}
+    />
+  )
+}
+```
+</details>
+
+---
+
+## GPT + Whisper Example
+
+```tsx
+<AiInput
+  placeholder="Ask anything..."
+  send={async (input) => {
+    // Text → GPT
+    const response = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: input as string }],
+      }),
+    })
+    return response.json()
+  }}
+  sendAudio={async (blob) => {
+    // Audio → Whisper
+    const formData = new FormData()
+    formData.append('file', blob, 'audio.webm')
+    formData.append('model', 'whisper-1')
+
+    const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${token}` },
+      body: formData,
+    })
+    return response.json()
+  }}
+  onTranscription={(text) => console.log('Transcribed:', text)}
+/>
+```
+
+---
+
+## API Reference
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|:--------:|-------------|
+| `send` | `(input: string \| Blob) => Promise<any>` | ✅ | Transport function for sending input |
+| `sendAudio` | `(blob: Blob) => Promise<any>` | | Separate transport for audio (uses `send` if not provided) |
+| `placeholder` | `string` | | Input placeholder text |
+| `disabled` | `boolean` | | Disable the input |
+| `className` | `string` | | Additional CSS classes |
+| `rateLimit` | `{ cooldownMs, maxRequests, windowMs }` | | Rate limiting configuration |
+| `audioConfig` | `{ maxDurationMs, mimeTypes }` | | Audio recording settings |
+| `onSuccess` | `(result: any) => void` | | Called on successful response |
+| `onError` | `(error: Error) => void` | | Called on error |
+| `onTranscription` | `(text: string) => void` | | Called when audio is transcribed |
+| `children` | `(props: RenderProps) => ReactNode` | | Render prop for headless usage |
+
+### Render Props (Headless Mode)
+
+```tsx
+<AiInput send={sendFn}>
+  {(props) => (
+    // Full control over UI
+  )}
+</AiInput>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string` | Current text value |
+| `setText` | `(value: string) => void` | Update text |
+| `submit` | `() => void` | Submit current input |
+| `canSubmit` | `boolean` | Whether submit is allowed |
+| `state` | `'idle' \| 'loading' \| 'success' \| 'error' \| 'recording'` | Current state |
+| `isRecording` | `boolean` | Audio recording active |
+| `startRecording` | `() => Promise<void>` | Start recording |
+| `stopRecording` | `() => void` | Stop and send recording |
+| `cancelRecording` | `() => void` | Discard recording |
+| `audioLevels` | `number[]` | Waveform data (0-1) |
+| `recordingDuration` | `number` | Recording time in ms |
+| `error` | `Error \| null` | Current error |
+| `reset` | `() => void` | Reset to idle state |
+
+---
+
+## Styling
+
+### Prepacked CSS (Recommended)
+
+```tsx
+import 'ai-input-react/styles.css'
+```
+
+Includes dark theme with zinc/amber colors, waveform visualization, and smooth animations.
+
+### Custom Styling (Tailwind)
+
+If using Tailwind, don't import the CSS file. The component uses Tailwind utility classes that will be processed by your build.
+
+---
+
+## Security
+
+> ⚠️ **Never store API keys in frontend code!**
+
+Use short-lived tokens from your backend:
+
+```tsx
+// ❌ Dangerous
+const API_KEY = 'sk-...'
+
+// ✅ Safe
+const token = await getTokenFromBackend()
+```
+
+---
+
+## Browser Support
+
+| Browser | Version |
+|---------|---------|
+| Chrome | 49+ |
+| Firefox | 36+ |
+| Safari | 14.1+ |
+| Edge | 79+ |
+
+Audio recording requires HTTPS (or localhost) and microphone permission.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## Issues & Support
+
+- 🐛 **Bug Reports**: [Open an issue](https://github.com/Soptik1290/ai-input/issues/new)
+- 💡 **Feature Requests**: [Open an issue](https://github.com/Soptik1290/ai-input/issues/new)
+- 💬 **Questions**: [GitHub Discussions](https://github.com/Soptik1290/ai-input/discussions)
+
+---
+
+## License
+
+[MIT](LICENSE) © 2024

package/dist/index.d.mts

@@ -0,0 +1,255 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Current state of the AiInput component
+ */
+type AiInputState = 'idle' | 'loading' | 'success' | 'error' | 'rate-limited' | 'recording';
+/**
+ * Rate limiting configuration for UI protection
+ * Note: This is soft rate limiting for UX only.
+ * Actual rate limiting should be handled by the AI provider.
+ */
+interface RateLimitConfig {
+    /** Cooldown between requests in milliseconds */
+    cooldownMs: number;
+    /** Maximum number of requests allowed in the time window */
+    maxRequests: number;
+    /** Time window in milliseconds for counting requests */
+    windowMs: number;
+}
+/**
+ * Audio recording configuration
+ */
+interface AudioConfig {
+    /** Maximum recording duration in milliseconds */
+    maxDurationMs: number;
+    /**
+     * Allowed MIME types for recording
+     * @example ['audio/webm', 'audio/mp4', 'audio/ogg']
+     */
+    mimeTypes: string[];
+}
+/**
+ * Transport function for sending input to AI API.
+ * Must be provided by the host application.
+ *
+ * @param input - Text string or audio Blob to send
+ * @returns Promise resolving to the API response
+ */
+type SendFunction = (input: string | Blob) => Promise<unknown>;
+/**
+ * Props passed to render function for headless usage
+ */
+interface AiInputRenderProps {
+    /** Current component state */
+    state: AiInputState;
+    /** Error if state is 'error' */
+    error: Error | null;
+    /** Result from last successful request */
+    result: unknown;
+    /** Current text value (controlled) */
+    text: string;
+    /** Update text value */
+    setText: (value: string) => void;
+    /** Submit current text or audio */
+    submit: () => void;
+    /** Whether submit is currently allowed */
+    canSubmit: boolean;
+    /** Whether currently recording */
+    isRecording: boolean;
+    /** Start audio recording */
+    startRecording: () => Promise<void>;
+    /** Stop audio recording and send */
+    stopRecording: () => void;
+    /** Cancel audio recording (discard) */
+    cancelRecording: () => void;
+    /** Current recording duration in milliseconds */
+    recordingDuration: number;
+    /** Maximum recording duration in milliseconds */
+    maxRecordingDuration: number;
+    /** Audio levels for waveform visualization (0-1 normalized, 12 bars) */
+    audioLevels: number[];
+    /** Remaining cooldown time in milliseconds */
+    cooldownRemaining: number;
+    /** Remaining requests in current window */
+    requestsRemaining: number;
+    /** Reset component to idle state */
+    reset: () => void;
+}
+/**
+ * Props for the AiInput component
+ */
+interface AiInputProps {
+    /**
+     * Transport function for sending input to AI API.
+     * Must be provided by the host application.
+     */
+    send: SendFunction;
+    /**
+     * Transport function specifically for audio (optional).
+     * If provided, audio will be sent via this function.
+     * If not provided, audio will be sent via `send`.
+     */
+    sendAudio?: SendFunction;
+    /** Rate limiting configuration (optional) */
+    rateLimit?: Partial<RateLimitConfig>;
+    /** Audio configuration (optional) */
+    audioConfig?: Partial<AudioConfig>;
+    /** Callback when request succeeds */
+    onSuccess?: (result: unknown) => void;
+    /** Callback when request fails */
+    onError?: (error: Error) => void;
+    /**
+     * Callback when audio transcription is received.
+     * Use this to set the text in the input after transcription.
+     */
+    onTranscription?: (text: string) => void;
+    /**
+     * Render function for headless usage.
+     * When provided, default UI is not rendered.
+     */
+    children?: (props: AiInputRenderProps) => ReactNode;
+    /** Placeholder text for input */
+    placeholder?: string;
+    /** Additional CSS classes for the container */
+    className?: string;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+}
+/**
+ * Options for useRateLimiter hook
+ */
+interface UseRateLimiterOptions {
+    cooldownMs: number;
+    maxRequests: number;
+    windowMs: number;
+}
+/**
+ * Return type for useRateLimiter hook
+ */
+interface UseRateLimiterReturn {
+    canRequest: boolean;
+    cooldownRemaining: number;
+    requestsRemaining: number;
+    recordRequest: () => void;
+    reset: () => void;
+}
+/**
+ * Options for useAudioRecorder hook
+ */
+interface UseAudioRecorderOptions {
+    maxDurationMs: number;
+    mimeTypes: string[];
+    onRecordingComplete?: (blob: Blob) => void;
+}
+/**
+ * Return type for useAudioRecorder hook
+ */
+interface UseAudioRecorderReturn {
+    isRecording: boolean;
+    isSupported: boolean;
+    duration: number;
+    audioBlob: Blob | null;
+    audioLevels: number[];
+    error: Error | null;
+    startRecording: () => Promise<void>;
+    stopRecording: () => void;
+    cancelRecording: () => void;
+    reset: () => void;
+}
+/**
+ * Options for useAiInput hook
+ */
+interface UseAiInputOptions {
+    send: SendFunction;
+    sendAudio?: SendFunction;
+    rateLimit?: Partial<RateLimitConfig>;
+    audioConfig?: Partial<AudioConfig>;
+    onSuccess?: (result: unknown) => void;
+    onError?: (error: Error) => void;
+    onTranscription?: (text: string) => void;
+}
+/**
+ * Return type for useAiInput hook
+ */
+type UseAiInputReturn = AiInputRenderProps;
+/** @deprecated Use AiInputProps without mode */
+type AiInputMode = 'text' | 'audio';
+
+/**
+ * AiInput Component
+ *
+ * A React component for text/audio input with AI API integration.
+ * Unified design with text input and audio recording in a single component.
+ *
+ * @example
+ * // Basic usage
+ * <AiInput
+ *   send={async (input) => {
+ *     const response = await fetch('/api/chat', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ message: input }),
+ *     })
+ *     return response.json()
+ *   }}
+ *   onSuccess={(result) => console.log(result)}
+ * />
+ *
+ * @example
+ * // With separate audio handler and transcription
+ * <AiInput
+ *   send={sendTextFn}
+ *   sendAudio={sendAudioFn}
+ *   onTranscription={(text) => console.log('Transcribed:', text)}
+ * />
+ *
+ * @example
+ * // Headless mode with custom UI
+ * <AiInput send={sendFn}>
+ *   {({ text, setText, submit, state, isRecording, audioLevels }) => (
+ *     <div>
+ *       {isRecording ? (
+ *         <MyWaveform levels={audioLevels} />
+ *       ) : (
+ *         <input value={text} onChange={(e) => setText(e.target.value)} />
+ *       )}
+ *       <button onClick={submit}>Send</button>
+ *     </div>
+ *   )}
+ * </AiInput>
+ */
+declare function AiInput({ send, sendAudio, rateLimit, audioConfig, onSuccess, onError, onTranscription, children, placeholder, className, disabled, }: AiInputProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Main hook for AI input functionality.
+ * Combines rate limiting, audio recording, and API communication.
+ * Unified design - text and audio in single component.
+ *
+ * @param options - Configuration options
+ * @returns Complete state and controls for AI input
+ */
+declare function useAiInput(options: UseAiInputOptions): UseAiInputReturn;
+
+/**
+ * Hook for audio recording using Web APIs.
+ * Uses navigator.mediaDevices, MediaRecorder, and Web Audio API for visualization.
+ *
+ * @param options - Audio recording configuration
+ * @returns Audio recorder state and controls
+ */
+declare function useAudioRecorder(options?: Partial<UseAudioRecorderOptions>): UseAudioRecorderReturn;
+
+/**
+ * Hook for soft rate limiting at the UI level.
+ * Provides UX protection by tracking requests and enforcing cooldowns.
+ *
+ * Note: This is not a security measure. Actual rate limiting
+ * should be handled by the AI provider or backend.
+ *
+ * @param options - Rate limiting configuration
+ * @returns Rate limiter state and controls
+ */
+declare function useRateLimiter(options?: Partial<UseRateLimiterOptions>): UseRateLimiterReturn;
+
+export { AiInput, type AiInputMode, type AiInputProps, type AiInputRenderProps, type AiInputState, type AudioConfig, type RateLimitConfig, type SendFunction, type UseAiInputOptions, type UseAiInputReturn, type UseAudioRecorderOptions, type UseAudioRecorderReturn, type UseRateLimiterOptions, type UseRateLimiterReturn, useAiInput, useAudioRecorder, useRateLimiter };