@weldsuite/helpdesk-widget-sdk 1.0.2

package/dist/react.d.ts

@@ -0,0 +1,666 @@
+import React from 'react';
+
+/**
+ * Weld SDK - Configuration Types
+ * Type definitions for SDK initialization and configuration
+ */
+/**
+ * Event types for widget events
+ */
+type WidgetEventType = 'ready' | 'open' | 'close' | 'error' | 'message' | 'minimize' | 'maximize' | 'destroy';
+/**
+ * Widget event structure
+ */
+interface WidgetEvent {
+    type: WidgetEventType;
+    data?: any;
+    timestamp: number;
+}
+/**
+ * Event handler function type
+ */
+type WidgetEventHandler = (event?: WidgetEvent | any) => void;
+/**
+ * Position configuration
+ */
+interface PositionConfig {
+    bottom?: string;
+    right?: string;
+    left?: string;
+    top?: string;
+}
+/**
+ * Customization configuration
+ */
+interface CustomizationConfig {
+    primaryColor?: string;
+    accentColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    fontFamily?: string;
+    fontSize?: string;
+    borderRadius?: string;
+}
+/**
+ * Feature flags
+ */
+interface FeatureConfig {
+    attachments?: boolean;
+    reactions?: boolean;
+    typing?: boolean;
+    readReceipts?: boolean;
+    offlineMode?: boolean;
+    fileUpload?: boolean;
+    imageUpload?: boolean;
+    voiceMessages?: boolean;
+    videoMessages?: boolean;
+}
+/**
+ * Mobile configuration
+ */
+interface MobileConfig {
+    fullScreen?: boolean;
+    scrollLock?: boolean;
+    keyboardHandling?: 'auto' | 'manual';
+    safeAreaInsets?: boolean;
+}
+/**
+ * Iframe configuration
+ */
+interface IframeConfig {
+    launcher: {
+        url: string;
+        name: string;
+        position: PositionConfig;
+        size: string;
+    };
+    widget: {
+        url: string;
+        name: string;
+        position: PositionConfig;
+        width: string;
+        height: string;
+    };
+    backdrop?: {
+        enabled: boolean;
+        closeOnClick: boolean;
+    };
+}
+/**
+ * API configuration
+ */
+interface ApiConfig {
+    baseUrl: string;
+    widgetId: string;
+    endpoints?: {
+        messages?: string;
+        users?: string;
+        conversations?: string;
+        upload?: string;
+    };
+    timeout?: number;
+    retries?: number;
+}
+/**
+ * Authentication configuration
+ */
+interface AuthConfig {
+    enabled?: boolean;
+    mode?: 'anonymous' | 'identified';
+    userId?: string;
+    email?: string;
+    name?: string;
+    avatar?: string;
+    metadata?: Record<string, any>;
+    token?: string;
+}
+/**
+ * Locale configuration
+ */
+interface LocaleConfig {
+    locale?: string;
+    translations?: Record<string, Record<string, string>>;
+    dateFormat?: string;
+    timeFormat?: string;
+    timezone?: string;
+}
+/**
+ * Logging configuration
+ */
+interface LogConfig {
+    enabled?: boolean;
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    prefix?: string;
+    includeTimestamp?: boolean;
+}
+/**
+ * Performance configuration
+ */
+interface PerformanceConfig {
+    lazyLoad?: boolean;
+    preload?: boolean;
+    caching?: boolean;
+    prefetch?: boolean;
+}
+/**
+ * Security configuration
+ */
+interface SecurityConfig {
+    allowedOrigins?: string[];
+    validateMessages?: boolean;
+    sanitizeInput?: boolean;
+    contentSecurityPolicy?: string;
+}
+/**
+ * Main SDK configuration
+ */
+interface WeldConfig {
+    widgetId: string;
+    api?: Partial<ApiConfig>;
+    iframes?: Partial<IframeConfig>;
+    position?: {
+        launcher?: PositionConfig;
+        widget?: PositionConfig;
+    };
+    customization?: CustomizationConfig;
+    features?: FeatureConfig;
+    mobile?: MobileConfig;
+    auth?: AuthConfig;
+    locale?: LocaleConfig;
+    logging?: LogConfig;
+    performance?: PerformanceConfig;
+    security?: SecurityConfig;
+    onReady?: () => void;
+    onError?: (error: Error) => void;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onMessage?: (message: any) => void;
+    onMinimize?: () => void;
+    onMaximize?: () => void;
+    onDestroy?: () => void;
+}
+/**
+ * Runtime configuration (resolved from WeldConfig)
+ */
+interface ResolvedConfig {
+    widgetId: string;
+    api: ApiConfig;
+    iframes: IframeConfig;
+    customization: CustomizationConfig;
+    features: FeatureConfig;
+    mobile: MobileConfig;
+    auth: AuthConfig;
+    locale: LocaleConfig;
+    logging: LogConfig;
+    performance: PerformanceConfig;
+    security: SecurityConfig;
+    onReady?: () => void;
+    onError?: (error: Error) => void;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onMessage?: (message: any) => void;
+    onMinimize?: () => void;
+    onMaximize?: () => void;
+    onDestroy?: () => void;
+}
+/**
+ * Device detection
+ */
+type DeviceType = 'mobile' | 'tablet' | 'desktop';
+interface DeviceInfo {
+    type: DeviceType;
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+    isTouchDevice: boolean;
+    screenWidth: number;
+    screenHeight: number;
+    orientation: 'portrait' | 'landscape';
+    userAgent: string;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: Omit<ResolvedConfig, 'widgetId'>;
+
+/**
+ * Weld SDK - State Types
+ * Type definitions for state management across iframes
+ */
+/**
+ * Widget visibility state
+ */
+declare enum WidgetVisibility {
+    HIDDEN = "hidden",
+    VISIBLE = "visible",
+    MINIMIZED = "minimized"
+}
+/**
+ * Widget view types
+ */
+declare enum WidgetView {
+    HOME = "home",
+    CONVERSATION = "conversation",
+    CONVERSATIONS = "conversations",
+    HELP = "help",
+    SETTINGS = "settings",
+    SEARCH = "search"
+}
+/**
+ * Connection status
+ */
+declare enum ConnectionStatus {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    RECONNECTING = "reconnecting",
+    ERROR = "error"
+}
+/**
+ * Message status
+ */
+declare enum MessageStatus {
+    SENDING = "sending",
+    SENT = "sent",
+    DELIVERED = "delivered",
+    READ = "read",
+    FAILED = "failed"
+}
+/**
+ * User state
+ */
+interface UserState {
+    id?: string;
+    email?: string;
+    name?: string;
+    avatar?: string;
+    metadata?: Record<string, any>;
+    isAuthenticated: boolean;
+    isAnonymous: boolean;
+}
+/**
+ * Conversation state
+ */
+interface ConversationState {
+    id?: string;
+    messages: Message[];
+    participants: Participant[];
+    unreadCount: number;
+    lastMessageAt?: number;
+    isTyping: boolean;
+    typingUsers: string[];
+}
+/**
+ * Message interface
+ */
+interface Message {
+    id: string;
+    conversationId: string;
+    text: string;
+    sender: {
+        id: string;
+        name: string;
+        avatar?: string;
+        type: 'user' | 'agent' | 'bot';
+    };
+    status: MessageStatus;
+    timestamp: number;
+    createdAt: number;
+    updatedAt?: number;
+    attachments?: Attachment[];
+    reactions?: Reaction[];
+    metadata?: Record<string, any>;
+}
+/**
+ * Attachment interface
+ */
+interface Attachment {
+    id: string;
+    type: 'image' | 'file' | 'video' | 'audio';
+    url: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    thumbnail?: string;
+}
+/**
+ * Reaction interface
+ */
+interface Reaction {
+    emoji: string;
+    count: number;
+    users: string[];
+}
+/**
+ * Participant interface
+ */
+interface Participant {
+    id: string;
+    name: string;
+    avatar?: string;
+    type: 'user' | 'agent' | 'bot';
+    isOnline: boolean;
+    lastSeenAt?: number;
+}
+/**
+ * Widget state
+ */
+interface WidgetState {
+    visibility: WidgetVisibility;
+    view: WidgetView;
+    isOpen: boolean;
+    isMinimized: boolean;
+    dimensions: {
+        width: string;
+        height: string;
+    };
+    position: {
+        bottom: string;
+        right: string;
+    };
+}
+/**
+ * Launcher state
+ */
+interface LauncherState {
+    isVisible: boolean;
+    badge: {
+        count: number;
+        text?: string;
+        show: boolean;
+    };
+    customColor?: string;
+    tooltip?: string;
+}
+/**
+ * Backdrop state
+ */
+interface BackdropState {
+    isVisible: boolean;
+    closeOnClick: boolean;
+    opacity: number;
+}
+/**
+ * Mobile state
+ */
+interface MobileState {
+    isFullScreen: boolean;
+    isScrollLocked: boolean;
+    keyboardHeight: number;
+    orientation: 'portrait' | 'landscape';
+    safeAreaInsets: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/**
+ * Network state
+ */
+interface NetworkState {
+    status: ConnectionStatus;
+    lastConnected?: number;
+    retryCount: number;
+    latency?: number;
+}
+/**
+ * UI state
+ */
+interface UIState {
+    theme: 'light' | 'dark' | 'auto';
+    locale: string;
+    isLoading: boolean;
+    error?: {
+        code: string;
+        message: string;
+        recoverable: boolean;
+    };
+}
+/**
+ * Main application state
+ */
+interface WeldState {
+    user: UserState;
+    conversation: ConversationState;
+    widget: WidgetState;
+    launcher: LauncherState;
+    backdrop: BackdropState;
+    mobile: MobileState;
+    network: NetworkState;
+    ui: UIState;
+    initialized: boolean;
+    lastUpdated: number;
+}
+
+/**
+ * User identification data
+ */
+interface UserIdentity {
+    userId: string;
+    email?: string;
+    name?: string;
+    avatar?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * WeldSDK class
+ * Main SDK interface for embedding the widget
+ */
+declare class WeldSDK {
+    private config;
+    private logger;
+    private iframeManager;
+    private messageBroker;
+    private stateCoordinator;
+    private status;
+    private readyPromise;
+    private readyResolve;
+    constructor(config: WeldConfig);
+    /**
+     * Initialize the SDK and render widget
+     */
+    init(): Promise<void>;
+    /**
+     * Setup ready message handlers
+     */
+    private setupReadyHandlers;
+    /**
+     * Map iframe name to type
+     */
+    private mapIframeNameToType;
+    /**
+     * Wait for all iframes to be ready
+     */
+    private waitForIframesReady;
+    /**
+     * Wait for SDK to be ready
+     */
+    ready(): Promise<void>;
+    /**
+     * Check if SDK is ready
+     */
+    isReady(): boolean;
+    /**
+     * Open the widget
+     */
+    open(): void;
+    /**
+     * Close the widget
+     */
+    close(): void;
+    /**
+     * Toggle widget open/close
+     */
+    toggle(): void;
+    /**
+     * Minimize the widget
+     */
+    minimize(): void;
+    /**
+     * Maximize the widget
+     */
+    maximize(): void;
+    /**
+     * Show the launcher
+     */
+    showLauncher(): void;
+    /**
+     * Hide the launcher
+     */
+    hideLauncher(): void;
+    /**
+     * Set badge count
+     */
+    setBadgeCount(count: number): void;
+    /**
+     * Clear badge
+     */
+    clearBadge(): void;
+    /**
+     * Send a message
+     */
+    sendMessage(text: string, metadata?: Record<string, any>): void;
+    /**
+     * Identify user
+     */
+    identify(identity: UserIdentity): void;
+    /**
+     * Logout user
+     */
+    logout(): void;
+    /**
+     * Update configuration
+     */
+    updateConfig(updates: Partial<WeldConfig>): void;
+    /**
+     * Update theme
+     */
+    setTheme(theme: 'light' | 'dark' | 'auto'): void;
+    /**
+     * Update locale
+     */
+    setLocale(locale: string): void;
+    /**
+     * Track custom event
+     */
+    track(eventName: string, properties?: Record<string, any>): void;
+    /**
+     * Get current state
+     */
+    getState(): WeldState;
+    /**
+     * Subscribe to state changes
+     */
+    onStateChange<T = any>(path: string, listener: (newValue: T, oldValue: T) => void): () => void;
+    /**
+     * Get device info
+     */
+    getDeviceInfo(): DeviceInfo;
+    /**
+     * Get SDK status
+     */
+    getStatus(): string;
+    /**
+     * Get SDK version
+     */
+    getVersion(): string;
+    /**
+     * Enable debug mode
+     */
+    enableDebug(): void;
+    /**
+     * Disable debug mode
+     */
+    disableDebug(): void;
+    /**
+     * Ensure SDK is ready before operation
+     */
+    private ensureReady;
+    /**
+     * Destroy SDK and cleanup
+     */
+    destroy(): void;
+}
+
+interface HelpdeskWidgetReactProps extends WeldConfig {
+    /**
+     * Children are not rendered (widget loads in iframe)
+     * This component exists for declarative usage
+     */
+    children?: never;
+}
+/**
+ * React component for the Helpdesk Widget
+ *
+ * This component provides a declarative way to add the widget to your app.
+ * The widget loads in an iframe and doesn't render any visible children.
+ *
+ * @example
+ * ```tsx
+ * import { HelpdeskWidgetReact } from '@weldsuite/helpdesk-widget-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <div>
+ *       <h1>My App</h1>
+ *       <HelpdeskWidgetReact widgetId="your-widget-id" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With event handlers
+ * ```tsx
+ * <HelpdeskWidgetReact
+ *   widgetId="your-widget-id"
+ *   onReady={() => console.log('Widget ready')}
+ *   onOpen={() => console.log('Widget opened')}
+ * />
+ * ```
+ */
+declare const HelpdeskWidgetReact: React.FC<HelpdeskWidgetReactProps>;
+
+/**
+ * React hook for the Helpdesk Widget
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const widget = useHelpdeskWidget({ widgetId: 'your-widget-id' });
+ *
+ *   return (
+ *     <button onClick={() => widget?.open()}>
+ *       Show Support
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useHelpdeskWidget(config: WeldConfig): WeldSDK | null;
+/**
+ * Hook that provides widget control methods
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { open, close, toggle } = useHelpdeskWidgetControls({
+ *     widgetId: 'your-widget-id'
+ *   });
+ *
+ *   return (
+ *     <button onClick={open}>Show Support</button>
+ *   );
+ * }
+ * ```
+ */
+declare function useHelpdeskWidgetControls(config: WeldConfig): {
+    widget: WeldSDK | null;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    sendMessage: (message: string) => void;
+};
+
+export { DEFAULT_CONFIG, WeldSDK as HelpdeskWidget, HelpdeskWidgetReact, WeldSDK, HelpdeskWidgetReact as default, useHelpdeskWidget, useHelpdeskWidgetControls };
+export type { WeldConfig as HelpdeskWidgetConfig, WeldConfig, WidgetEvent, WidgetEventHandler, WidgetEventType };