@intentai/react 2.2.0 → 2.3.0

package/dist/index.d.mts

@@ -1,80 +1,189 @@
-import React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
 
-interface WidgetConfig {
-    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-    primaryColor?: string;
-    accentColor?: string;
-    theme?: 'light' | 'dark' | 'auto';
-    categories?: Category[];
-    allowVoice?: boolean;
-    allowText?: boolean;
-    allowScreenshot?: boolean;
-    maxRecordingDuration?: number;
-    onSubmit?: (feedback: FeedbackData) => Promise<void>;
-    onOpen?: () => void;
-    onClose?: () => void;
-}
-interface Category {
+/**
+ * User identity for feedback attribution
+ */
+interface UserIdentity {
+    /** Unique user identifier */
     id: string;
-    label: string;
-    icon: string;
+    /** User email address */
+    email?: string;
+    /** User display name */
+    name?: string;
+    /** User avatar URL */
+    avatar?: string;
+    /** Subscription plan */
+    plan?: string;
+    /** Company name */
+    company?: string;
+    /** Custom properties */
+    [key: string]: string | number | boolean | undefined;
 }
+/**
+ * Widget position on screen
+ */
+type WidgetPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/**
+ * Widget color theme
+ */
+type WidgetTheme = 'light' | 'dark' | 'auto';
+/**
+ * Feedback type categories
+ */
+type FeedbackType = 'bug' | 'feature' | 'question' | 'praise' | 'other';
+/**
+ * Sentiment analysis result
+ */
+type Sentiment = 'positive' | 'neutral' | 'negative';
+/**
+ * Data returned when feedback is submitted
+ */
 interface FeedbackData {
-    type: 'voice' | 'text';
+    /** Feedback ID */
+    id: string;
+    /** Type of feedback */
+    type: FeedbackType;
+    /** Text content */
     content: string;
-    audioBlob?: Blob;
-    transcription?: string;
-    category: string;
+    /** Voice recording URL */
+    voiceUrl?: string;
+    /** Screenshot data URL */
     screenshot?: string;
-    sentiment?: string;
+    /** AI-analyzed sentiment */
+    sentiment?: Sentiment;
+    /** Submission timestamp */
+    createdAt: string;
+}
+/**
+ * Options for opening the widget
+ */
+interface OpenOptions {
+    /** Pre-select feedback type */
+    type?: FeedbackType;
+    /** Prefill text content */
+    prefill?: {
+        text?: string;
+    };
+    /** Additional metadata for this feedback */
     metadata?: Record<string, unknown>;
 }
-declare const PremiumVoiceWidget: React.FC<WidgetConfig>;
-
-interface IntentAIProviderConfig {
-    /** Your Intent AI API key (required) */
-    apiKey: string;
-    /** API URL (defaults to production) */
-    apiUrl?: string;
-    /** User information for identifying feedback */
-    user?: IntentAIUser$1;
-    /** Additional metadata to attach to all feedback */
+/**
+ * Configuration options for the Intent AI widget
+ */
+interface IntentAIConfig {
+    /**
+     * Your Intent AI public key (pk_live_* or pk_test_*)
+     * Can also be set via environment variables:
+     * - NEXT_PUBLIC_INTENT_AI_KEY
+     * - REACT_APP_INTENT_AI_KEY
+     * - VITE_INTENT_AI_KEY
+     */
+    apiKey?: string;
+    /**
+     * Widget position on screen
+     * @default "bottom-right"
+     */
+    position?: WidgetPosition;
+    /**
+     * Color theme
+     * @default "auto"
+     */
+    theme?: WidgetTheme;
+    /**
+     * Primary brand color (hex)
+     * @default "#6366f1"
+     */
+    primaryColor?: string;
+    /**
+     * Show widget button automatically
+     * @default true
+     */
+    autoShow?: boolean;
+    /**
+     * Initial user identification
+     */
+    user?: UserIdentity;
+    /**
+     * Custom metadata attached to all feedback
+     */
     metadata?: Record<string, unknown>;
+    /**
+     * Callback when widget is ready
+     */
+    onReady?: () => void;
+    /**
+     * Callback when widget opens
+     */
+    onOpen?: () => void;
+    /**
+     * Callback when widget closes
+     */
+    onClose?: () => void;
+    /**
+     * Callback when feedback is submitted
+     */
+    onSubmit?: (feedback: FeedbackData) => void;
+    /**
+     * Callback when an error occurs
+     */
+    onError?: (error: Error) => void;
 }
-interface IntentAIUser$1 {
-    id?: string;
-    email?: string;
-    name?: string;
-    [key: string]: unknown;
+/**
+ * Props for IntentAIProvider component
+ */
+interface IntentAIProviderProps extends IntentAIConfig {
+    children: React.ReactNode;
 }
+/**
+ * Context value for IntentAI provider
+ */
 interface IntentAIContextValue {
-    /** Identify the current user */
-    identify: (user: IntentAIUser$1) => void;
-    /** Set metadata to attach to feedback */
+    /** Whether the widget is loaded and ready */
+    isReady: boolean;
+    /** Error if widget failed to load */
+    error: Error | null;
+    /** Open the feedback widget */
+    open: (options?: OpenOptions) => void;
+    /** Close the feedback widget */
+    close: () => void;
+    /** Identify a user */
+    identify: (user: UserIdentity) => void;
+    /** Track a custom event */
+    track: (event: string, properties?: Record<string, unknown>) => void;
+    /** Set custom metadata */
     setMetadata: (metadata: Record<string, unknown>) => void;
-    /** Clear the current user */
-    clearUser: () => void;
-    /** Whether the provider is configured */
-    isConfigured: boolean;
 }
 /**
- * Hook to access Intent AI context for user identification and metadata
+ * Intent AI widget instance methods
  */
-declare function useIntentAI(): IntentAIContextValue;
-interface IntentAIProviderProps extends IntentAIProviderConfig {
-    /** Widget configuration options */
-    widgetConfig?: Omit<WidgetConfig, 'onSubmit'>;
-    /** Children components */
-    children?: React.ReactNode;
-    /** Disable the widget (only provide context) */
-    disableWidget?: boolean;
-    /** Callback when feedback is submitted successfully */
-    onFeedbackSubmitted?: () => void;
-    /** Callback when there's an error */
-    onError?: (error: Error) => void;
+interface IntentAIInstance {
+    open: (options?: OpenOptions) => void;
+    close: () => void;
+    identify: (user: UserIdentity) => void;
+    track: (event: string, properties?: Record<string, unknown>) => void;
+    setMetadata: (metadata: Record<string, unknown>) => void;
+    destroy: () => void;
+}
+/**
+ * Window augmentation for Intent AI global
+ */
+declare global {
+    interface Window {
+        IntentAI?: IntentAIInstance;
+        IntentAIConfig?: IntentAIConfig;
+    }
+    interface WindowEventMap {
+        'intentai:ready': CustomEvent;
+        'intentai:open': CustomEvent;
+        'intentai:close': CustomEvent;
+        'intentai:submit': CustomEvent<FeedbackData>;
+        'intentai:error': CustomEvent<Error>;
+    }
 }
+
 /**
- * Intent AI Provider - Wraps your app with feedback collection capabilities
+ * Provider component for Intent AI widget
  *
  * @example
  * ```tsx
@@ -82,193 +191,189 @@ interface IntentAIProviderProps extends IntentAIProviderConfig {
  *
  * function App() {
  *   return (
- *     <IntentAIProvider
- *       apiKey="your-api-key"
- *       user={{ id: 'user-123', email: 'user@example.com' }}
- *     >
+ *     <IntentAIProvider apiKey="pk_live_xxxxx">
  *       <YourApp />
  *     </IntentAIProvider>
  *   );
  * }
  * ```
  */
-declare function IntentAIProvider({ apiKey, apiUrl, user: initialUser, metadata: initialMetadata, widgetConfig, children, disableWidget, onFeedbackSubmitted, onError, }: IntentAIProviderProps): React.ReactElement;
+declare function IntentAIProvider({ children, apiKey, user, position, theme, primaryColor, autoShow, metadata, onReady, onOpen, onClose, onSubmit, onError, }: IntentAIProviderProps): react_jsx_runtime.JSX.Element;
 /**
- * Hook to identify users - convenience wrapper around useIntentAI
+ * Hook to access Intent AI widget controls
  *
  * @example
  * ```tsx
- * function UserProfile({ user }) {
- *   const identify = useIdentify();
+ * import { useIntentAI } from '@intentai/react';
  *
- *   useEffect(() => {
- *     identify({ id: user.id, email: user.email, name: user.name });
- *   }, [user]);
+ * function FeedbackButton() {
+ *   const { open, isReady } = useIntentAI();
  *
- *   return <div>...</div>;
+ *   return (
+ *     <button onClick={() => open()} disabled={!isReady}>
+ *       Give Feedback
+ *     </button>
+ *   );
  * }
  * ```
  */
-declare function useIdentify(): (user: IntentAIUser$1) => void;
+declare function useIntentAI(): IntentAIContextValue;
 /**
- * Hook to set metadata - convenience wrapper around useIntentAI
+ * Hook to automatically identify a user when they're available
  *
  * @example
  * ```tsx
- * function Dashboard({ plan }) {
- *   const setMetadata = useSetMetadata();
- *
- *   useEffect(() => {
- *     setMetadata({ plan, feature: 'dashboard' });
- *   }, [plan]);
+ * import { useIdentify } from '@intentai/react';
  *
+ * function Profile({ user }) {
+ *   useIdentify(user ? { id: user.id, email: user.email } : null);
  *   return <div>...</div>;
  * }
  * ```
  */
-declare function useSetMetadata(): (metadata: Record<string, unknown>) => void;
+declare function useIdentify(user: UserIdentity | null | undefined): void;
 
-interface FeedbackButtonProps {
-    /** Button variant style */
-    variant?: 'primary' | 'secondary' | 'ghost' | 'minimal';
-    /** Button size */
-    size?: 'sm' | 'md' | 'lg';
-    /** Show icon */
-    showIcon?: boolean;
-    /** Custom icon (React element) */
-    icon?: React.ReactNode;
-    /** Button label */
-    label?: string;
-    /** Additional class name */
-    className?: string;
-    /** Custom styles */
-    style?: React.CSSProperties;
-    /** Primary color */
-    primaryColor?: string;
-    /** Click handler - if provided, will be called instead of opening widget */
-    onClick?: () => void;
-    /** Disabled state */
-    disabled?: boolean;
+/**
+ * Props for FeedbackButton component
+ */
+interface FeedbackButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Options to pass when opening the widget */
+    openOptions?: OpenOptions;
+    /** Custom children to render */
+    children?: React$1.ReactNode;
 }
 /**
- * Customizable feedback button that can trigger the widget or custom actions
+ * Pre-built button component to open the feedback widget
  *
  * @example
  * ```tsx
- * // Basic usage - triggers widget
- * <FeedbackButton />
- *
- * // Custom label and style
- * <FeedbackButton
- *   label="Give Feedback"
- *   variant="secondary"
- *   size="lg"
- * />
+ * import { FeedbackButton } from '@intentai/react';
  *
- * // With custom click handler
- * <FeedbackButton
- *   label="Report Issue"
- *   onClick={() => console.log('clicked')}
- * />
+ * function App() {
+ *   return (
+ *     <FeedbackButton className="my-custom-class">
+ *       Send Feedback
+ *     </FeedbackButton>
+ *   );
+ * }
  * ```
  */
-declare function FeedbackButton({ variant, size, showIcon, icon, label, className, style, primaryColor, onClick, disabled, }: FeedbackButtonProps): React.ReactElement;
-
-interface IntentAIUser {
-    id?: string;
-    email?: string;
-    name?: string;
-}
-interface IntentAIConfig {
-    /** Your Intent AI API key (required) */
-    apiKey: string;
-    /** API URL for feedback submission (required for production) */
-    apiUrl: string;
-    /** Widget script URL (required for production) */
-    widgetUrl: string;
-    /** Widget position on screen */
-    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-    /** Widget theme */
-    theme?: 'light' | 'dark';
-    /** Primary color for the widget */
-    primaryColor?: string;
-    /** Enable/disable voice feedback */
-    allowVoice?: boolean;
-    /** Enable/disable text feedback */
-    allowText?: boolean;
-    /** Enable/disable screenshot capture */
-    allowScreenshot?: boolean;
-    /** Custom metadata to attach to feedback */
-    customMetadata?: Record<string, any>;
-    /** User information */
-    user?: IntentAIUser;
-}
-interface IntentAIProps extends IntentAIConfig {
-    /** Called when widget is opened */
-    onOpen?: () => void;
-    /** Called when widget is closed */
-    onClose?: () => void;
-    /** Called when feedback is submitted successfully */
-    onFeedbackSubmitted?: () => void;
-    /** Called when there's an error */
-    onError?: (error: Error) => void;
-}
-interface FeedbackIQInstance {
-    open: () => void;
-    close: () => void;
-    identify: (user: IntentAIUser) => void;
-    setMetadata: (metadata: Record<string, any>) => void;
-    destroy: () => void;
-}
-declare global {
-    interface Window {
-        FeedbackIQ: new (config: IntentAIConfig) => FeedbackIQInstance;
-    }
+declare const FeedbackButton: React$1.ForwardRefExoticComponent<FeedbackButtonProps & React$1.RefAttributes<HTMLButtonElement>>;
+/**
+ * Props for FeedbackTrigger component
+ */
+interface FeedbackTriggerProps {
+    /** Render function or element */
+    children: React$1.ReactElement | ((props: {
+        open: (options?: OpenOptions) => void;
+        isReady: boolean;
+        error: Error | null;
+    }) => React$1.ReactElement);
+    /** Options to pass when opening */
+    openOptions?: OpenOptions;
 }
 /**
- * Intent AI Feedback Widget for React
+ * Headless component for custom feedback triggers
  *
  * @example
  * ```tsx
- * import { IntentAIWidget } from '@intent-ai/react';
+ * import { FeedbackTrigger } from '@intentai/react';
  *
  * function App() {
  *   return (
- *     <IntentAIWidget
- *       apiKey="your-api-key"
- *       position="bottom-right"
- *       theme="dark"
- *     />
+ *     <FeedbackTrigger>
+ *       {({ open, isReady }) => (
+ *         <MyCustomButton onClick={() => open()} disabled={!isReady}>
+ *           Feedback
+ *         </MyCustomButton>
+ *       )}
+ *     </FeedbackTrigger>
+ *   );
+ * }
+ * ```
+ */
+declare function FeedbackTrigger({ children, openOptions }: FeedbackTriggerProps): React$1.ReactElement<any, string | React$1.JSXElementConstructor<any>>;
+/**
+ * Props for IdentifyUser component
+ */
+interface IdentifyUserProps {
+    /** User to identify */
+    user: UserIdentity | null | undefined;
+    /** Children to render */
+    children?: React$1.ReactNode;
+}
+/**
+ * Component to identify a user declaratively
+ *
+ * @example
+ * ```tsx
+ * import { IdentifyUser } from '@intentai/react';
+ *
+ * function App({ user }) {
+ *   return (
+ *     <IdentifyUser user={user ? { id: user.id, email: user.email } : null}>
+ *       <YourApp />
+ *     </IdentifyUser>
  *   );
  * }
  * ```
  */
-declare function IntentAIWidget({ apiKey, apiUrl, widgetUrl, position, theme, primaryColor, allowVoice, allowText, allowScreenshot, customMetadata, user, onOpen: _onOpen, onClose: _onClose, onFeedbackSubmitted: _onFeedbackSubmitted, onError, }: IntentAIProps): null;
+declare function IdentifyUser({ user, children }: IdentifyUserProps): react_jsx_runtime.JSX.Element;
+/**
+ * Props for SetMetadata component
+ */
+interface SetMetadataProps {
+    /** Metadata to set */
+    metadata: Record<string, unknown>;
+    /** Children to render */
+    children?: React$1.ReactNode;
+}
 /**
- * Hook to control the script-tag widget programmatically
- * @deprecated Use useIntentAI from IntentAIProvider instead for React apps
+ * Component to set metadata declaratively
  *
  * @example
  * ```tsx
- * import { IntentAIWidget, useWidgetControls } from '@intentai/react';
+ * import { SetMetadata } from '@intentai/react';
  *
- * function App() {
- *   const { open, close, identify } = useWidgetControls();
+ * function PricingPage() {
+ *   return (
+ *     <SetMetadata metadata={{ page: 'pricing', plan: 'pro' }}>
+ *       <PricingContent />
+ *     </SetMetadata>
+ *   );
+ * }
+ * ```
+ */
+declare function SetMetadata({ metadata, children }: SetMetadataProps): react_jsx_runtime.JSX.Element;
+/**
+ * Props for TrackEvent component
+ */
+interface TrackEventProps {
+    /** Event name to track */
+    event: string;
+    /** Event properties */
+    properties?: Record<string, unknown>;
+    /** When to track: 'mount' (default) or 'render' */
+    trigger?: 'mount' | 'render';
+    /** Children to render */
+    children?: React$1.ReactNode;
+}
+/**
+ * Component to track events declaratively
  *
+ * @example
+ * ```tsx
+ * import { TrackEvent } from '@intentai/react';
+ *
+ * function CheckoutPage() {
  *   return (
- *     <>
- *       <IntentAIWidget apiKey="your-api-key" widgetUrl="..." apiUrl="..." />
- *       <button onClick={open}>Open Feedback</button>
- *     </>
+ *     <TrackEvent event="checkout_viewed" properties={{ items: 3 }}>
+ *       <CheckoutContent />
+ *     </TrackEvent>
  *   );
  * }
  * ```
  */
-declare function useWidgetControls(): {
-    open: () => void;
-    close: () => void;
-    identify: (user: IntentAIUser) => void;
-    setMetadata: (metadata: Record<string, any>) => void;
-};
+declare function TrackEvent({ event, properties, trigger, children, }: TrackEventProps): react_jsx_runtime.JSX.Element;
 
-export { FeedbackButton, type FeedbackButtonProps, type IntentAIConfig, type IntentAIContextValue, type IntentAIProps, IntentAIProvider, type IntentAIProviderConfig, type IntentAIProviderProps, type IntentAIUser, IntentAIWidget, PremiumVoiceWidget, type WidgetConfig as PremiumWidgetConfig, IntentAIWidget as default, useIdentify, useIntentAI, useSetMetadata, useWidgetControls };
+export { FeedbackButton, type FeedbackButtonProps, type FeedbackData, FeedbackTrigger, type FeedbackTriggerProps, type FeedbackType, IdentifyUser, type IdentifyUserProps, type IntentAIConfig, type IntentAIContextValue, type IntentAIInstance, IntentAIProvider, type IntentAIProviderProps, type OpenOptions, type Sentiment, SetMetadata, type SetMetadataProps, TrackEvent, type TrackEventProps, type UserIdentity, type WidgetPosition, type WidgetTheme, useIdentify, useIntentAI };