@channlize/react 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,422 @@
+# @channlize/react
+
+React components and hooks for the Channlize platform. Build customer support experiences that route directly to Slack.
+
+## Installation
+
+```bash
+npm install @channlize/react
+```
+
+Note: This package has peer dependencies on `react` and `react-dom` (>=16.8.0).
+
+## Quick Start (Plug & Play)
+
+The easiest way to add live chat to your React app:
+
+```tsx
+import { ChannlizeChat } from '@channlize/react';
+
+function App() {
+  return (
+    <div>
+      <YourAppContent />
+      
+      {/* That's it! Floating chat widget with everything included */}
+      <ChannlizeChat
+        config={{
+          apiKey: 'your-widget-key',
+          projectId: 'your-project-id',
+        }}
+        position="bottom-right"
+        chatProps={{
+          title: "Customer Support",
+          placeholder: "How can we help you today?"
+        }}
+      />
+    </div>
+  );
+}
+```
+
+The `ChannlizeChat` component includes:
+- ✅ Provider (no need to wrap your app)
+- ✅ Floating button with customizable position
+- ✅ Chat window with real-time messaging
+- ✅ Animations and responsive design
+- ✅ Extensive styling options
+
+## Advanced Usage
+
+For more control, use the individual components:
+
+### Manual Setup
+
+Wrap your app with the `ChannlizeProvider`:
+
+```tsx
+import { ChannlizeProvider } from '@channlize/react';
+
+function App() {
+  return (
+    <ChannlizeProvider
+      config={{
+        apiKey: 'your-api-key',
+        projectId: 'your-project-id',
+      }}
+    >
+      <YourAppContent />
+    </ChannlizeProvider>
+  );
+}
+```
+
+### Contact Form Component
+
+```tsx
+import { ContactForm } from '@channlize/react';
+
+function ContactPage() {
+  return (
+    <ContactForm
+      onSuccess={() => alert('Message sent!')}
+      onError={(error) => console.error(error)}
+      customFields={[
+        {
+          name: 'department',
+          label: 'Department',
+          type: 'select',
+          required: true,
+          options: ['Sales', 'Support', 'Billing'],
+        },
+        {
+          name: 'priority',
+          label: 'Priority',
+          type: 'select',
+          options: ['Low', 'Medium', 'High'],
+        },
+      ]}
+      styles={{
+        form: { maxWidth: '500px' },
+        button: { background: '#007bff', color: 'white' },
+      }}
+    />
+  );
+}
+```
+
+### Support Chat Component
+
+```tsx
+import { SupportChat } from '@channlize/react';
+
+function SupportPage() {
+  return (
+    <SupportChat
+      autoStart={true}
+      title="Customer Support"
+      placeholder="How can we help you?"
+      onMessage={(message) => {
+        console.log('New message:', message);
+      }}
+      styles={{
+        container: { 
+          width: '400px', 
+          height: '500px',
+          border: '1px solid #ccc',
+          borderRadius: '8px',
+        },
+        header: { 
+          background: '#007bff', 
+          color: 'white' 
+        },
+      }}
+    />
+  );
+}
+```
+
+### Custom Hook Usage
+
+#### useContactForm
+
+```tsx
+import { useContactForm } from '@channlize/react';
+
+function CustomContactForm() {
+  const { submit, isSubmitting, isSuccess, error, reset } = useContactForm({
+    onSuccess: (response) => {
+      console.log('Form submitted:', response);
+    },
+    onError: (error) => {
+      console.error('Submission failed:', error);
+    },
+  });
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    await submit({
+      name: 'John Doe',
+      email: 'john@example.com',
+      message: 'Hello!',
+    });
+  };
+
+  if (isSuccess) {
+    return (
+      <div>
+        <p>Thank you! Your message has been sent.</p>
+        <button onClick={reset}>Send another message</button>
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Your form fields */}
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Sending...' : 'Send'}
+      </button>
+      {error && <p>Error: {error.message}</p>}
+    </form>
+  );
+}
+```
+
+#### useChatSession
+
+```tsx
+import { useChatSession } from '@channlize/react';
+
+function CustomChat() {
+  const {
+    session,
+    messages,
+    isConnecting,
+    isConnected,
+    error,
+    sendMessage,
+    startSession,
+    endSession,
+  } = useChatSession({
+    autoConnect: false,
+    metadata: { page: 'support' },
+    onMessage: (message) => {
+      console.log('New message:', message);
+    },
+  });
+
+  const handleSendMessage = async () => {
+    await sendMessage('Hello from custom chat!');
+  };
+
+  if (!session) {
+    return (
+      <div>
+        <button onClick={startSession} disabled={isConnecting}>
+          {isConnecting ? 'Connecting...' : 'Start Chat'}
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <div>Status: {isConnected ? 'Connected' : 'Disconnected'}</div>
+      <div>
+        {messages.map((message) => (
+          <div key={message.id}>
+            <strong>{message.author}:</strong> {message.content}
+          </div>
+        ))}
+      </div>
+      <button onClick={handleSendMessage}>Send Message</button>
+      <button onClick={endSession}>End Chat</button>
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
+## Components
+
+### ChannlizeChat (Recommended)
+
+**All-in-one floating chat widget** - The easiest way to add live chat to any React app. Includes provider, button, and chat window.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `ChannlizeConfig` | required | API configuration (apiKey, projectId, baseUrl) |
+| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Position of the floating button |
+| `offset` | `{ x?: number; y?: number }` | `{ x: 24, y: 24 }` | Offset from edges in pixels |
+| `buttonElement` | `ReactNode` | - | Custom button (overrides default) |
+| `buttonIcon` | `ReactNode` | - | Custom icon (used if buttonElement not provided) |
+| `buttonSize` | `number` | `56` | Button size in pixels |
+| `buttonColors` | `{ background?: string; hover?: string; text?: string }` | Blue gradient | Button colors |
+| `chatProps` | `SupportChatProps` | `{}` | Props passed to internal SupportChat component |
+| `defaultOpen` | `boolean` | `false` | Whether to start open |
+| `showBadge` | `boolean` | `false` | Whether to show unread count badge |
+| `unreadCount` | `number` | `0` | Unread message count |
+| `zIndex` | `number` | `1000` | CSS z-index |
+| `showOnMobile` | `boolean` | `true` | Whether to show on mobile devices |
+| `onOpen` | `() => void` | - | Callback when chat opens |
+| `onClose` | `() => void` | - | Callback when chat closes |
+| `enableAnimations` | `boolean` | `true` | Enable smooth animations |
+| `buttonClassName` | `string` | `''` | Custom class for button container |
+| `chatClassName` | `string` | `''` | Custom class for chat container |
+
+**Examples:**
+
+```tsx
+// Minimal setup
+<ChannlizeChat
+  config={{
+    apiKey: 'your-widget-key',
+    projectId: 'your-project-id',
+  }}
+/>
+
+// Custom positioning and colors
+<ChannlizeChat
+  config={{ apiKey: 'key', projectId: 'id' }}
+  position="bottom-left"
+  offset={{ x: 16, y: 80 }}
+  buttonColors={{
+    background: '#10b981',
+    hover: '#059669',
+    text: '#ffffff',
+  }}
+/>
+
+// With custom chat options
+<ChannlizeChat
+  config={{ apiKey: 'key', projectId: 'id' }}
+  chatProps={{
+    title: "24/7 Support",
+    placeholder: "Ask us anything...",
+    showTimestamps: true,
+    styles: {
+      header: {
+        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+      },
+    },
+  }}
+/>
+
+// With unread badge
+<ChannlizeChat
+  config={{ apiKey: 'key', projectId: 'id' }}
+  showBadge={true}
+  unreadCount={3}
+  onOpen={() => console.log('Chat opened')}
+/>
+
+// Custom button
+<ChannlizeChat
+  config={{ apiKey: 'key', projectId: 'id' }}
+  buttonElement={
+    <div style={{ 
+      padding: '12px 24px',
+      background: '#000',
+      color: '#fff',
+      borderRadius: '8px',
+      cursor: 'pointer',
+    }}>
+      Need Help? 💬
+    </div>
+  }
+/>
+```
+
+### ContactForm
+
+A complete contact form component with validation and submission handling.
+
+**Props:**
+- `customFields?: Array<CustomField>` - Additional form fields
+- `onSuccess?: () => void` - Success callback
+- `onError?: (error: Error) => void` - Error callback
+- `className?: string` - CSS class name
+- `styles?: ContactFormStyles` - Custom styles object
+- `submitText?: string` - Submit button text
+- `successMessage?: string` - Success message text
+
+### SupportChat
+
+A real-time chat widget with message history and file attachments.
+
+**Props:**
+- `autoStart?: boolean` - Auto-start chat session
+- `metadata?: Record<string, unknown>` - Session metadata
+- `onMessage?: (message: ChatMessage) => void` - New message callback
+- `onError?: (error: Error) => void` - Error callback
+- `className?: string` - CSS class name
+- `styles?: SupportChatStyles` - Custom styles object
+- `title?: string` - Chat header title
+- `placeholder?: string` - Input placeholder text
+- `maxHeight?: string` - Maximum container height
+
+## Hooks
+
+### useContactForm
+
+Hook for managing contact form submission state.
+
+**Options:**
+- `onSuccess?: (response: CreateContactResponse) => void`
+- `onError?: (error: ChannlizeError) => void`
+
+**Returns:**
+- `submit: (data: ContactFormData) => Promise<void>`
+- `isSubmitting: boolean`
+- `isSuccess: boolean`
+- `error: ChannlizeError | null`
+- `reset: () => void`
+
+### useChatSession
+
+Hook for managing chat sessions with real-time messaging.
+
+**Options:**
+- `autoConnect?: boolean`
+- `metadata?: Record<string, unknown>`
+- `onMessage?: (message: ChatMessage) => void`
+- `onError?: (error: ChannlizeError) => void`
+
+**Returns:**
+- `session: ChatSession | null`
+- `messages: ChatMessage[]`
+- `isConnecting: boolean`
+- `isConnected: boolean`
+- `error: ChannlizeError | null`
+- `sendMessage: (content: string, attachments?: File[]) => Promise<void>`
+- `startSession: () => Promise<void>`
+- `endSession: () => Promise<void>`
+
+## Styling
+
+All components accept a `styles` prop for custom styling. You can also use CSS classes with the `className` prop. Components use semantic class names prefixed with `channlize-`.
+
+### CSS Classes
+
+- `.channlize-contact-form`
+- `.channlize-contact-form-success`
+- `.channlize-field`
+- `.channlize-error`
+- `.channlize-chat-container`
+- `.channlize-chat-header`
+- `.channlize-chat-messages`
+- `.channlize-message`
+- `.channlize-message-user`
+- `.channlize-message-agent`
+- `.channlize-chat-input-container`
+
+## TypeScript
+
+This package is written in TypeScript and includes full type definitions. All components, hooks, and utilities are fully typed.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,203 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { ChannlizeConfig, ChannlizeClient, CreateContactResponse, ChannlizeError, ContactFormData, ChatMessage, ChatSession } from '@channlize/core';
+export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, FileAttachment, RateLimitError, SendMessageResponse, ValidationError } from '@channlize/core';
+
+interface ChannlizeContextValue {
+    client: ChannlizeClient;
+    config: ChannlizeConfig;
+}
+interface ChannlizeProviderProps {
+    config: ChannlizeConfig;
+    children: ReactNode;
+}
+/**
+ * Provider component that makes Channlize client available to all child components
+ */
+declare function ChannlizeProvider({ config, children }: ChannlizeProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the Channlize client and configuration
+ */
+declare function useChannlize(): ChannlizeContextValue;
+
+interface UseContactFormOptions {
+    onSuccess?: (response: CreateContactResponse) => void;
+    onError?: (error: ChannlizeError) => void;
+}
+interface UseContactFormReturn {
+    submit: (data: ContactFormData) => Promise<void>;
+    isSubmitting: boolean;
+    isSuccess: boolean;
+    error: ChannlizeError | null;
+    reset: () => void;
+}
+/**
+ * Hook for handling contact form submissions
+ */
+declare function useContactForm(options?: UseContactFormOptions): UseContactFormReturn;
+
+interface UseChatSessionOptions {
+    autoConnect?: boolean;
+    metadata?: Record<string, unknown>;
+    onMessage?: (message: ChatMessage) => void;
+    onError?: (error: ChannlizeError) => void;
+    sessionId?: string;
+    persistSession?: boolean;
+    storageKey?: string;
+}
+interface UseChatSessionReturn {
+    session: ChatSession | null;
+    messages: ChatMessage[];
+    isConnecting: boolean;
+    isConnected: boolean;
+    error: ChannlizeError | null;
+    sendMessage: (content: string, attachments?: File[]) => Promise<void>;
+    startSession: () => Promise<void>;
+    endSession: () => Promise<void>;
+}
+/**
+ * Hook for managing chat sessions with real-time messaging
+ */
+declare function useChatSession(options?: UseChatSessionOptions): UseChatSessionReturn;
+
+interface FormProps {
+    /** Custom fields to include in the form */
+    customFields?: Array<{
+        name: string;
+        label: string;
+        type: 'text' | 'email' | 'textarea' | 'select';
+        required?: boolean;
+        options?: string[];
+    }>;
+    /** Callback when form is successfully submitted */
+    onSuccess?: () => void;
+    /** Callback when form submission fails */
+    onError?: (error: Error) => void;
+    /** Custom CSS classes */
+    className?: string;
+    /** Custom styles for form elements */
+    styles?: {
+        form?: React.CSSProperties;
+        field?: React.CSSProperties;
+        label?: React.CSSProperties;
+        input?: React.CSSProperties;
+        textarea?: React.CSSProperties;
+        button?: React.CSSProperties;
+        error?: React.CSSProperties;
+        success?: React.CSSProperties;
+    };
+    /** Button text */
+    submitText?: string;
+    /** Success message */
+    successMessage?: string;
+}
+
+/**
+ * ContactForm component - Alias for Form component
+ * Provides a form for collecting contact information and messages
+ */
+declare function ContactForm(props: FormProps): react_jsx_runtime.JSX.Element;
+
+interface SupportChatProps extends UseChatSessionOptions {
+    /** Custom CSS classes */
+    className?: string;
+    /** Custom styles for chat elements */
+    styles?: {
+        container?: React.CSSProperties;
+        header?: React.CSSProperties;
+        messagesContainer?: React.CSSProperties;
+        message?: React.CSSProperties;
+        userMessage?: React.CSSProperties;
+        agentMessage?: React.CSSProperties;
+        inputContainer?: React.CSSProperties;
+        input?: React.CSSProperties;
+        button?: React.CSSProperties;
+        error?: React.CSSProperties;
+        timestamp?: React.CSSProperties;
+    };
+    /** Placeholder text for message input */
+    placeholder?: string;
+    /** Header title */
+    title?: string;
+    /** Button text */
+    sendButtonText?: string;
+    /** Show timestamps on messages */
+    showTimestamps?: boolean;
+    /** Allow file attachments */
+    allowAttachments?: boolean;
+}
+/**
+ * SupportChat component - Real-time chat interface
+ * Provides a complete chat UI with message history and real-time updates
+ */
+declare function SupportChat({ autoConnect, metadata, onMessage, onError, sessionId, persistSession, storageKey, className, styles, placeholder, title, sendButtonText, showTimestamps, allowAttachments, }: SupportChatProps): react_jsx_runtime.JSX.Element;
+
+interface ChannlizeChatProps {
+    /** Channlize configuration */
+    config: ChannlizeConfig;
+    /** Position of the floating button */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Offset from edges in pixels */
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    /** Custom button element (overrides default button) */
+    buttonElement?: ReactNode;
+    /** Custom button icon (only used if buttonElement is not provided) */
+    buttonIcon?: ReactNode;
+    /** Button size in pixels */
+    buttonSize?: number;
+    /** Button colors */
+    buttonColors?: {
+        background?: string;
+        hover?: string;
+        text?: string;
+    };
+    /** Chat window props (passed to SupportChat) */
+    chatProps?: Omit<SupportChatProps, 'autoConnect'>;
+    /** Whether to start closed or open */
+    defaultOpen?: boolean;
+    /** Whether to show badge with unread count */
+    showBadge?: boolean;
+    /** Unread count (for badge) */
+    unreadCount?: number;
+    /** Custom z-index */
+    zIndex?: number;
+    /** Whether to show on mobile */
+    showOnMobile?: boolean;
+    /** Callback when chat opens */
+    onOpen?: () => void;
+    /** Callback when chat closes */
+    onClose?: () => void;
+    /** Whether to enable animations */
+    enableAnimations?: boolean;
+    /** Custom class for button container */
+    buttonClassName?: string;
+    /** Custom class for chat container */
+    chatClassName?: string;
+}
+/**
+ * ChannlizeChat - All-in-one floating chat widget with provider
+ *
+ * Drop this component anywhere in your React app for instant live chat support.
+ * Includes the provider, floating button, and chat window.
+ *
+ * @example
+ * ```tsx
+ * <ChannlizeChat
+ *   config={{
+ *     apiKey: "your-widget-key",
+ *     projectId: "your-project-id",
+ *   }}
+ *   position="bottom-right"
+ *   chatProps={{
+ *     title: "Customer Support",
+ *     placeholder: "How can we help?"
+ *   }}
+ * />
+ * ```
+ */
+declare function ChannlizeChat({ config, position, offset, buttonElement, buttonIcon, buttonSize, buttonColors, chatProps, defaultOpen, showBadge, unreadCount, zIndex, showOnMobile, onOpen, onClose, enableAnimations, buttonClassName, chatClassName, }: ChannlizeChatProps): react_jsx_runtime.JSX.Element | null;
+
+export { ChannlizeChat, ChannlizeProvider, ContactForm, SupportChat, useChannlize, useChatSession, useContactForm };