ai-input-react 1.0.0-beta.1

package/dist/index.d.ts

@@ -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 };