@yellowdotai/yellow-chat-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1623 @@
+/**
+ * YellowChat Configuration Types
+ */
+/**
+ * Public SDK Configuration - Options exposed to end users
+ *
+ * Only includes options that end users need to configure.
+ * Internal details like XMPP domains, WebSocket routes, etc. are hidden.
+ */
+interface SDKConfig {
+    /** Bot ID (required) - Your Yellow.ai bot identifier */
+    bot: string;
+    /** API host URL (default: 'https://cloud.yellow.ai') */
+    host?: string;
+    /**
+     * Message source identifier (default: 'yellowmessenger')
+     *
+     * This determines how messages are routed through Yellow.ai's backend.
+     *
+     * Options:
+     * - 'yellowmessenger' (default): Use for fully headless SDK-only integrations.
+     *   The SDK handles all communication via WebSocket/XMPP. Best for custom chat
+     *   widgets where the SDK is the primary communication channel.
+     *
+     * - 'syncApi': Use when integrating with the /integrations/sync/v1/message REST API.
+     *   Required for hybrid mode where you start with REST API calls and switch to
+     *   WebSocket when a live agent connects. This ensures ticket consistency between
+     *   REST and WebSocket channels.
+     *
+     * @example
+     * // Fully headless - SDK only
+     * sdk.init({ bot: 'your-bot', source: 'yellowmessenger' });
+     *
+     * @example
+     * // Hybrid mode - REST API + SDK for live agent
+     * sdk.init({ bot: 'your-bot', source: 'syncApi' });
+     */
+    source?: string;
+    /** User identifier (optional - SDK will auto-generate if not provided) */
+    userId?: string;
+    /** User display name */
+    name?: string;
+    /** Custom payload to send with messages */
+    payload?: Record<string, unknown>;
+    /** Authentication token (if required by your bot) */
+    ymAuthenticationToken?: string;
+    /** Device token for push notifications */
+    deviceToken?: string;
+    /** Journey to trigger on connect */
+    triggerJourney?: string;
+    /** Trigger event name */
+    trigger?: string;
+    /**
+     * Suppress welcome messages on connect (default: false)
+     *
+     * Set to true in hybrid mode when connecting to WebSocket after already
+     * having a conversation via REST API. This prevents duplicate welcome messages.
+     *
+     * @example
+     * // Hybrid mode - conversation already started via REST
+     * sdk.init({
+     *   bot: 'your-bot',
+     *   source: 'syncApi',
+     *   disableWelcomeMessage: true  // Suppress welcome since REST chat already started
+     * });
+     */
+    disableWelcomeMessage?: boolean;
+    /** UTM parameters for analytics */
+    utmSource?: string;
+    utmCampaign?: string;
+    utmMedium?: string;
+    utmTerm?: string;
+    utmContent?: string;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+
+/**
+ * YellowChat Message Types
+ *
+ * This module contains type definitions for all message-related data
+ * in the SDK, including incoming messages from bots/agents and outgoing
+ * messages from users.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Type of message content.
+ *
+ * Determines how the message should be rendered in the UI.
+ *
+ * - `text` - Plain text message
+ * - `image` - Image with optional caption
+ * - `file` - Downloadable file attachment
+ * - `video` - Video with playback controls
+ * - `audio` - Audio clip
+ * - `cards` - Carousel of cards with actions
+ * - `quickReplies` - Quick reply buttons
+ * - `webView` - Embedded web view
+ * - `rating` - Rating request (stars, emoji, thumbs)
+ * - `location` - Map location
+ * - `multiSelect` - Multi-selection options
+ * - `date` - Date picker
+ * - `feedback` - Text feedback input
+ * - `system` - System notification
+ */
+type MessageType = 'text' | 'image' | 'file' | 'video' | 'audio' | 'cards' | 'quickReplies' | 'webView' | 'webViews' | 'rating' | 'location' | 'flightDetails' | 'boardingPass' | 'docSearchCards' | 'notification' | 'question' | 'multiSelect' | 'date' | 'feedback' | 'system';
+/**
+ * Who sent the message.
+ *
+ * - `bot` - Automated bot response
+ * - `agent` - Live human agent
+ * - `user` - The current user (echoed back)
+ * - `system` - System notification
+ */
+type MessageSender = 'bot' | 'agent' | 'user' | 'system';
+/**
+ * Message received from the server (from bot, agent, or system).
+ *
+ * Incoming messages are delivered via the `message:received` event.
+ * The `type` field determines what content is available.
+ *
+ * @example
+ * ```typescript
+ * sdk.on('message:received', (message: IncomingMessage) => {
+ *   console.log(`[${message.sender}]: ${message.content.text}`);
+ *
+ *   if (message.type === 'quickReplies') {
+ *     // Show quick reply buttons
+ *     renderQuickReplies(message.content.quickReplies);
+ *   }
+ * });
+ * ```
+ */
+interface IncomingMessage {
+    /** Unique message ID */
+    id: string;
+    /** Trace ID for debugging */
+    traceId?: string;
+    /** Message timestamp */
+    timestamp: Date;
+    /** Message type */
+    type: MessageType;
+    /** Message content */
+    content: MessageContent;
+    /** Who sent the message */
+    sender: MessageSender;
+    /** Agent profile if sent by agent */
+    agentProfile?: AgentProfile;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Journey slug for analytics */
+    journeySlug?: string;
+    /** Step slug for analytics */
+    stepSlug?: string;
+}
+/**
+ * Message sent by the user.
+ *
+ * Outgoing messages are created when calling `sdk.sendMessage()`.
+ * The `message:sent` event includes this structure.
+ *
+ * @example
+ * ```typescript
+ * sdk.on('message:sent', (message: OutgoingMessage) => {
+ *   console.log('Sent:', message.message);
+ * });
+ * ```
+ */
+interface OutgoingMessage {
+    /** Unique message ID */
+    id: string;
+    /** Message text */
+    message: string;
+    /** Message timestamp */
+    timestamp: Date;
+    /** Optional title */
+    title?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Container for message content.
+ *
+ * Only one content type is typically populated based on `MessageType`.
+ * For example, a `type: 'image'` message will have `content.image` set.
+ *
+ * @example
+ * ```typescript
+ * // Handle different content types
+ * if (message.content.text) {
+ *   renderText(message.content.text);
+ * } else if (message.content.image) {
+ *   renderImage(message.content.image.url, message.content.image.caption);
+ * } else if (message.content.cards) {
+ *   renderCardCarousel(message.content.cards);
+ * }
+ * ```
+ */
+interface MessageContent {
+    /** Text content */
+    text?: string;
+    /** Image content */
+    image?: ImageContent;
+    /** File content */
+    file?: FileContent;
+    /** Video content */
+    video?: VideoContent;
+    /** Audio content */
+    audio?: AudioContent;
+    /** Card carousel */
+    cards?: CardContent[];
+    /** Quick reply buttons */
+    quickReplies?: QuickReplyContent;
+    /** Web view configuration */
+    webView?: WebViewContent;
+    /** Multiple web views */
+    webViews?: WebViewContent[];
+    /** Rating request */
+    rating?: RatingContent;
+    /** Location data */
+    location?: LocationContent;
+    /** Multi-select options */
+    multiSelect?: MultiSelectContent;
+    /** Date picker */
+    date?: DateContent;
+    /** Feedback request */
+    feedback?: FeedbackContent;
+}
+/**
+ * Image message content.
+ */
+interface ImageContent {
+    /** Image URL */
+    url: string;
+    /** Optional caption text */
+    caption?: string;
+    /** Alt text for accessibility */
+    altText?: string;
+}
+/**
+ * File attachment content.
+ */
+interface FileContent {
+    /** Download URL */
+    url: string;
+    /** Original file name */
+    name: string;
+    /** File size in bytes */
+    size?: number;
+    /** MIME type (e.g., 'application/pdf') */
+    mimeType?: string;
+}
+/**
+ * Video message content with playback options.
+ */
+interface VideoContent {
+    /** Video URL */
+    url: string;
+    /** Thumbnail image URL */
+    thumbnail?: string;
+    /** Duration in seconds */
+    duration?: number;
+    /** Show playback controls */
+    controls?: boolean;
+    /** Auto-play on load */
+    autoplay?: boolean;
+    /** Loop playback */
+    loop?: boolean;
+    /** Start muted */
+    muted?: boolean;
+    /** Allow download */
+    downloadable?: boolean;
+}
+/**
+ * Audio message content.
+ */
+interface AudioContent {
+    /** Audio URL */
+    url: string;
+    /** Duration in seconds */
+    duration?: number;
+}
+/**
+ * Card in a carousel.
+ *
+ * Cards can have an image, title, description, and action buttons.
+ * Multiple cards are displayed as a horizontal carousel.
+ */
+interface CardContent {
+    /** Card title */
+    title: string;
+    /** Card description text */
+    description?: string;
+    /** Card image URL */
+    image?: string;
+    /** Link URL when card is clicked */
+    url?: string;
+    /** Action buttons on the card */
+    actions?: CardAction[];
+}
+/**
+ * Action button on a card.
+ */
+interface CardAction {
+    /** Button label */
+    title: string;
+    /** Action type: 'url' opens link, 'postback' sends value to bot, 'call' initiates call, 'share' shares content */
+    type: 'url' | 'postback' | 'call' | 'share';
+    /** Value to send for postback actions */
+    payload?: string;
+    /** URL for url/call actions */
+    url?: string;
+}
+/**
+ * Quick reply buttons shown below a message.
+ *
+ * Quick replies provide predefined response options for the user.
+ */
+interface QuickReplyContent {
+    /** Optional prompt text above buttons */
+    title?: string;
+    /** Quick reply button options */
+    options: QuickReply[];
+}
+/**
+ * A quick reply button option.
+ */
+interface QuickReply {
+    /** Button label text */
+    title: string;
+    /** Value sent to bot when selected (defaults to title) */
+    value?: string;
+    /** Optional icon URL or emoji */
+    icon?: string;
+}
+/**
+ * Web view (iframe) content configuration.
+ *
+ * Used to embed external web pages within the chat.
+ */
+interface WebViewContent {
+    /** Web page URL to embed */
+    url: string;
+    /** Title shown in header */
+    title?: string;
+    /** Height of web view: 'compact' (50%), 'tall' (75%), 'full' (100%) */
+    height?: 'compact' | 'tall' | 'full';
+    /** Close web view when form is submitted */
+    closeOnSubmit?: boolean;
+}
+/**
+ * Rating/feedback request configuration.
+ *
+ * Prompts user to rate the conversation or experience.
+ */
+interface RatingContent {
+    /** Prompt text */
+    title?: string;
+    /** Minimum rating value (default: 1) */
+    minRating?: number;
+    /** Maximum rating value (default: 5) */
+    maxRating?: number;
+    /** Visual style: 'star', 'emoji', or 'thumbs' */
+    ratingType?: 'star' | 'emoji' | 'thumbs';
+}
+/**
+ * Geographic location content.
+ */
+interface LocationContent {
+    /** Latitude coordinate */
+    latitude: number;
+    /** Longitude coordinate */
+    longitude: number;
+    /** Location name */
+    name?: string;
+    /** Full address text */
+    address?: string;
+}
+/**
+ * Multi-select options content.
+ *
+ * Allows user to select multiple options from a list.
+ */
+interface MultiSelectContent {
+    /** Prompt text */
+    title?: string;
+    /** Selectable options */
+    options: MultiSelectOption[];
+    /** Minimum required selections */
+    minSelection?: number;
+    /** Maximum allowed selections */
+    maxSelection?: number;
+}
+/**
+ * An option in a multi-select list.
+ */
+interface MultiSelectOption {
+    /** Display label */
+    label: string;
+    /** Value sent to bot when selected */
+    value: string;
+    /** Pre-selected state */
+    selected?: boolean;
+}
+/**
+ * Date picker content configuration.
+ */
+interface DateContent {
+    /** Prompt text */
+    title?: string;
+    /** Minimum selectable date (ISO format) */
+    minDate?: string;
+    /** Maximum selectable date (ISO format) */
+    maxDate?: string;
+    /** Date format string */
+    format?: string;
+}
+/**
+ * Text feedback input configuration.
+ */
+interface FeedbackContent {
+    /** Prompt text */
+    title?: string;
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Submit button text */
+    submitText?: string;
+}
+/**
+ * Live agent profile information.
+ *
+ * Available when a live agent is assigned to the conversation.
+ */
+interface AgentProfile {
+    /** Agent username/ID */
+    username: string;
+    /** Agent display name */
+    name: string;
+    /** Profile picture URL */
+    profilePicture?: string;
+    /** Agent description/title */
+    description?: string;
+    /** WebRTC username for voice/video calls */
+    webrtcUsername?: string;
+    /** Agent's organization/team owner */
+    owner?: string;
+}
+/**
+ * Welcome message configuration.
+ */
+interface WelcomeMessage {
+    /** Welcome message text */
+    message: string;
+    /** Delay before showing (milliseconds) */
+    delay?: number;
+}
+/**
+ * Message from conversation history.
+ *
+ * Extends `IncomingMessage` with delivery status information.
+ */
+interface HistoryMessage extends IncomingMessage {
+    /** Message delivery status */
+    status?: 'sent' | 'delivered' | 'read';
+}
+/**
+ * Options for sending a message.
+ *
+ * @example
+ * ```typescript
+ * await sdk.sendMessage('Option 1', {
+ *   metadata: { selectedOption: 'opt-1' }
+ * });
+ * ```
+ */
+interface SendMessageOptions {
+    /** Optional title for the message */
+    title?: string;
+    /** Additional metadata to send with the message */
+    metadata?: Record<string, unknown>;
+    /** Skip rate limiting check (use with caution) */
+    skipRateLimit?: boolean;
+}
+/**
+ * Response returned after successfully sending a message.
+ */
+interface MessageResponse {
+    /** Message ID assigned by server */
+    id: string;
+    /** Trace ID for debugging and tracking */
+    traceId?: string;
+    /** Server timestamp when message was received */
+    timestamp: Date;
+}
+/**
+ * Response returned after successfully uploading a file.
+ */
+interface FileUploadResponse {
+    /** Uploaded file URL (CDN hosted) */
+    url: string;
+    /** Original file name */
+    name: string;
+    /** File size in bytes */
+    size: number;
+}
+
+/**
+ * YellowChat Bot Types
+ *
+ * This module contains type definitions for bot configuration and
+ * customization options loaded during SDK initialization.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Bot information and configuration.
+ *
+ * Available after `sdk.init()` completes via `sdk.getBotInfo()`.
+ * Contains bot identity, UI theme, and feature flags.
+ *
+ * @example
+ * ```typescript
+ * const botInfo = sdk.getBotInfo();
+ * if (botInfo) {
+ *   document.title = botInfo.name;
+ *   if (botInfo.icon) {
+ *     setFavicon(botInfo.icon);
+ *   }
+ * }
+ * ```
+ */
+interface BotInfo {
+    /** Bot ID */
+    botId: string;
+    /** Bot display name */
+    name: string;
+    /** Bot icon URL */
+    icon?: string;
+    /** Bot description */
+    description?: string;
+    /** Bot type */
+    botType?: string;
+    /** Subscription ID */
+    subscriptionId?: string;
+    /** Whether secure UID is required */
+    useSecureUid?: boolean;
+    /** Frontend UID */
+    feUID?: string;
+    /** Whether bot is turned off */
+    turnOff?: boolean;
+    /** Bot skin/theme configuration */
+    skin?: BotSkin;
+    /** Bot features */
+    features?: BotFeatures;
+    /** Available languages */
+    languages?: string[];
+    /** Default language */
+    defaultLanguage?: string;
+}
+/**
+ * Bot UI theme and styling configuration.
+ *
+ * Use these values to customize your chat UI to match the bot's branding.
+ * All colors are CSS color strings (hex, rgb, etc.).
+ *
+ * @example
+ * ```typescript
+ * const skin = sdk.getBotInfo()?.skin;
+ * if (skin) {
+ *   document.documentElement.style.setProperty('--primary-color', skin.primaryColor);
+ *   document.documentElement.style.setProperty('--bot-bubble', skin.botBubbleColor);
+ * }
+ * ```
+ */
+interface BotSkin {
+    /** Primary brand color */
+    primaryColor?: string;
+    /** Secondary color */
+    secondaryColor?: string;
+    /** Bot bubble color */
+    botBubbleColor?: string;
+    /** Bot text color */
+    botTextColor?: string;
+    /** User bubble color */
+    userBubbleColor?: string;
+    /** User text color */
+    userTextColor?: string;
+    /** Header background color */
+    headerColor?: string;
+    /** Header text color */
+    headerTextColor?: string;
+    /** Font family */
+    fontFamily?: string;
+    /** Font size */
+    fontSize?: string;
+    /** Border radius */
+    borderRadius?: string;
+    /** Show typing indicator */
+    showTyping?: boolean;
+    /** Enable sound */
+    enableSound?: boolean;
+    /** Show branding */
+    showBranding?: boolean;
+}
+/**
+ * Feature flags indicating what capabilities are enabled for the bot.
+ *
+ * Use these to conditionally show/hide UI elements based on bot configuration.
+ *
+ * @example
+ * ```typescript
+ * const features = sdk.getBotInfo()?.features;
+ *
+ * if (features?.fileUpload) {
+ *   showAttachmentButton();
+ * }
+ * if (features?.voiceInput) {
+ *   showMicrophoneButton();
+ * }
+ * if (features?.liveAgent) {
+ *   showRequestAgentButton();
+ * }
+ * ```
+ */
+interface BotFeatures {
+    /** File upload allowed */
+    fileUpload?: boolean;
+    /** Enable voice input */
+    voiceInput?: boolean;
+    /** Enable location sharing */
+    locationSharing?: boolean;
+    /** Enable message history */
+    messageHistory?: boolean;
+    /** Enable typing indicator */
+    typingIndicator?: boolean;
+    /** Enable read receipts */
+    readReceipts?: boolean;
+    /** Enable push notifications */
+    pushNotifications?: boolean;
+    /** Enable live agent support */
+    liveAgent?: boolean;
+    /** Enable feedback */
+    feedback?: boolean;
+    /** Enable emoji */
+    emoji?: boolean;
+    /** Enable attachments */
+    attachments?: boolean;
+    /** Enable multi-language */
+    multiLanguage?: boolean;
+}
+/**
+ * Response from bot load API.
+ *
+ * Internal type returned when loading bot details during initialization.
+ */
+interface BotLoadResponse {
+    /** Bot configuration */
+    botConfig: BotInfo;
+    /** Welcome messages */
+    welcomeMessages?: Array<{
+        message: string;
+        delay?: number;
+    }>;
+    /** Banners configuration */
+    banners?: BannerConfig[];
+    /** User information */
+    userInfo?: {
+        uid: string;
+        name?: string;
+        email?: string;
+    };
+    /** Session information */
+    session?: {
+        sessionId: string;
+        expiresAt?: number;
+    };
+}
+/**
+ * Banner/announcement configuration.
+ *
+ * Banners can be displayed at the top or bottom of the chat interface
+ * to show important messages, promotions, or alerts.
+ */
+interface BannerConfig {
+    /** Unique banner ID */
+    id: string;
+    /** Banner title */
+    title: string;
+    /** Banner message */
+    message?: string;
+    /** Banner image URL */
+    image?: string;
+    /** Banner action URL */
+    actionUrl?: string;
+    /** Banner action text */
+    actionText?: string;
+    /** Banner position */
+    position?: 'top' | 'bottom';
+    /** Banner type */
+    type?: 'info' | 'warning' | 'error' | 'success';
+    /** Auto dismiss time in ms */
+    autoDismiss?: number;
+}
+
+/**
+ * YellowChat Error Types
+ *
+ * This module contains error type definitions and utility functions
+ * for handling SDK errors.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Error codes returned by the SDK.
+ *
+ * Use the error code to determine the type of error and how to handle it.
+ *
+ * **Connection Errors:**
+ * - `CONNECTION_FAILED` - Could not connect to server
+ * - `CONNECTION_TIMEOUT` - Connection attempt timed out
+ * - `CONNECTION_CLOSED` - Connection was closed unexpectedly
+ *
+ * **Authentication Errors:**
+ * - `AUTH_FAILED` - Authentication failed
+ * - `AUTH_TOKEN_EXPIRED` - Auth token has expired
+ * - `AUTH_TOKEN_INVALID` - Auth token is invalid
+ *
+ * **Message Errors:**
+ * - `MESSAGE_SEND_FAILED` - Failed to send message
+ * - `MESSAGE_TIMEOUT` - Message send timed out
+ * - `MESSAGE_RATE_LIMITED` - Too many messages sent
+ *
+ * **File Errors:**
+ * - `FILE_UPLOAD_FAILED` - File upload failed
+ * - `FILE_TOO_LARGE` - File exceeds size limit
+ * - `FILE_TYPE_NOT_ALLOWED` - File type not supported
+ *
+ * **Other Errors:**
+ * - `BOT_LOAD_FAILED` - Could not load bot configuration
+ * - `HISTORY_LOAD_FAILED` - Could not load chat history
+ * - `NETWORK_ERROR` - Network connectivity issue
+ * - `INVALID_CONFIG` - Invalid SDK configuration
+ * - `INVALID_MESSAGE` - Invalid message format
+ * - `API_ERROR` - REST API error
+ * - `UNKNOWN_ERROR` - Unexpected error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.sendMessage('Hello');
+ * } catch (error) {
+ *   if (error instanceof YellowChatError) {
+ *     switch (error.code) {
+ *       case 'MESSAGE_RATE_LIMITED':
+ *         showToast('Please wait before sending another message');
+ *         break;
+ *       case 'CONNECTION_CLOSED':
+ *         await sdk.connect();
+ *         break;
+ *       default:
+ *         console.error('Error:', error.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type SDKErrorCode = 'CONNECTION_FAILED' | 'CONNECTION_TIMEOUT' | 'CONNECTION_CLOSED' | 'AUTH_FAILED' | 'AUTH_TOKEN_EXPIRED' | 'AUTH_TOKEN_INVALID' | 'MESSAGE_SEND_FAILED' | 'MESSAGE_TIMEOUT' | 'MESSAGE_RATE_LIMITED' | 'FILE_UPLOAD_FAILED' | 'FILE_TOO_LARGE' | 'FILE_TYPE_NOT_ALLOWED' | 'BOT_LOAD_FAILED' | 'HISTORY_LOAD_FAILED' | 'NETWORK_ERROR' | 'INVALID_CONFIG' | 'INVALID_MESSAGE' | 'XMPP_ERROR' | 'STREAM_ERROR' | 'API_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Structured error object returned by SDK operations.
+ *
+ * Provides detailed error information including error code, message,
+ * and whether the error is recoverable (can be retried).
+ */
+interface SDKError {
+    /** Error code identifying the type of error */
+    code: SDKErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details (varies by error type) */
+    details?: Record<string, unknown>;
+    /** Original error if this error wraps another */
+    originalError?: Error;
+    /** Timestamp when error occurred */
+    timestamp: Date;
+    /** Whether the operation can be retried */
+    recoverable: boolean;
+}
+/**
+ * Create a new SDK error object.
+ *
+ * Use this to create error objects for event payloads or logging.
+ * For throwing errors, use `new YellowChatError()` instead.
+ *
+ * @param code - Error code identifying the type of error
+ * @param message - Human-readable error message
+ * @param options - Optional additional error details
+ * @returns A structured SDKError object
+ *
+ * @example
+ * ```typescript
+ * const error = createSDKError('MESSAGE_SEND_FAILED', 'Failed to send message', {
+ *   details: { messageId: '123' },
+ *   recoverable: true
+ * });
+ * ```
+ */
+declare function createSDKError(code: SDKErrorCode, message: string, options?: {
+    details?: Record<string, unknown>;
+    originalError?: Error;
+    recoverable?: boolean;
+}): SDKError;
+/**
+ * Error class thrown by SDK operations.
+ *
+ * Extends the standard `Error` class with additional properties for
+ * error categorization and handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.init({ bot: '' });
+ * } catch (error) {
+ *   if (error instanceof YellowChatError) {
+ *     console.error(`[${error.code}] ${error.message}`);
+ *
+ *     if (error.code === 'INVALID_CONFIG') {
+ *       // Show configuration error to user
+ *     }
+ *
+ *     if (error.recoverable) {
+ *       // Can retry the operation
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class YellowChatError extends Error {
+    /** Error code identifying the type of error */
+    readonly code: SDKErrorCode;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    /** Whether the operation can be retried */
+    readonly recoverable: boolean;
+    /** When the error occurred */
+    readonly timestamp: Date;
+    /**
+     * Create a new YellowChatError.
+     *
+     * @param code - Error code
+     * @param message - Human-readable error message
+     * @param options - Optional additional details
+     */
+    constructor(code: SDKErrorCode, message: string, options?: {
+        details?: Record<string, unknown>;
+        recoverable?: boolean;
+    });
+    /**
+     * Convert this error to an SDKError object.
+     *
+     * Useful for passing error data to event handlers or serialization.
+     *
+     * @returns SDKError representation of this error
+     */
+    toSDKError(): SDKError;
+}
+
+/**
+ * YellowChat Event Types
+ *
+ * This module defines all events emitted by the SDK. Use `sdk.on(eventName, handler)`
+ * to subscribe to events, and `sdk.off(eventName, handler)` to unsubscribe.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Current state of the WebSocket connection.
+ *
+ * Use `connection:stateChange` event to monitor state transitions.
+ *
+ * - `disconnected` - Not connected to server
+ * - `connecting` - Connection attempt in progress
+ * - `connected` - Successfully connected and ready
+ * - `reconnecting` - Connection lost, attempting to reconnect
+ * - `failed` - Connection failed and will not retry
+ *
+ * @example
+ * ```typescript
+ * sdk.on('connection:stateChange', (state: ConnectionState) => {
+ *   switch (state) {
+ *     case 'connected':
+ *       showConnectedIndicator();
+ *       break;
+ *     case 'reconnecting':
+ *       showReconnectingSpinner();
+ *       break;
+ *     case 'failed':
+ *       showErrorMessage();
+ *       break;
+ *   }
+ * });
+ * ```
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed';
+/**
+ * Information about why a disconnection occurred.
+ *
+ * Provided in the `connection:disconnected` event payload.
+ */
+interface DisconnectReason {
+    /** Disconnect code (e.g., 'NETWORK_ERROR', 'USER_INITIATED') */
+    code: string;
+    /** Human-readable disconnect message */
+    message: string;
+    /** Whether the connection was closed cleanly (vs. dropped unexpectedly) */
+    wasClean: boolean;
+}
+/**
+ * Configuration for the chat input field.
+ *
+ * Sent via `ui:showInput` event to control input behavior.
+ */
+interface InputOptions {
+    /** Whether input is enabled/disabled */
+    enabled: boolean;
+    /** Placeholder text in input field */
+    placeholder?: string;
+    /** Maximum input length */
+    maxLength?: number;
+    /** Input type for mobile keyboards */
+    inputType?: 'text' | 'number' | 'email' | 'tel';
+    /** Show file attachment button */
+    showAttachment?: boolean;
+    /** Show microphone button for voice input */
+    showMic?: boolean;
+}
+/**
+ * Configuration for file upload prompt.
+ *
+ * Sent via `ui:showFilePrompt` event to configure file picker.
+ */
+interface FilePromptOptions {
+    /** Accepted file types (MIME types or extensions) */
+    accept?: string[];
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Allow multiple file selection */
+    multiple?: boolean;
+}
+/**
+ * SDK Event Map - All events emitted by the YellowChat SDK.
+ *
+ * Subscribe to events using `sdk.on(eventName, handler)`. The handler function
+ * signature is typed based on the event name.
+ *
+ * ## Event Categories
+ *
+ * **Connection Events** (`connection:*`)
+ * - Manage WebSocket connection lifecycle
+ * - `connection:connected` - Ready to send/receive messages
+ * - `connection:disconnected` - Connection closed
+ * - `connection:reconnecting` - Auto-reconnect in progress
+ *
+ * **Message Events** (`message:*`)
+ * - Handle incoming and outgoing messages
+ * - `message:received` - New message from bot/agent
+ * - `message:sent` - Message successfully sent
+ * - `message:failed` - Message send failed
+ *
+ * **Agent Events** (`agent:*`)
+ * - Live agent status updates
+ * - `agent:assigned` - Agent joined conversation
+ * - `agent:typing` - Agent typing indicator
+ *
+ * **UI Control Events** (`ui:*`)
+ * - SDK suggestions for UI updates
+ * - `ui:showQuickReplies` - Display quick reply buttons
+ * - `ui:showCards` - Display card carousel
+ *
+ * **File Events** (`file:*`)
+ * - File upload progress
+ * - `file:uploadStarted` - Upload began
+ * - `file:uploadCompleted` - Upload successful
+ *
+ * @example
+ * ```typescript
+ * // Connection events
+ * sdk.on('connection:connected', ({ userId }) => {
+ *   console.log('Connected as:', userId);
+ * });
+ *
+ * // Message events
+ * sdk.on('message:received', (message) => {
+ *   console.log('New message:', message.content.text);
+ * });
+ *
+ * // Agent events
+ * sdk.on('agent:assigned', (agent) => {
+ *   console.log('Agent joined:', agent.name);
+ * });
+ * ```
+ */
+interface SDKEvents {
+    /** Connection attempt started */
+    'connection:connecting': () => void;
+    /** Successfully connected to server */
+    'connection:connected': (data: {
+        userId: string;
+    }) => void;
+    /** Disconnected from server */
+    'connection:disconnected': (reason: DisconnectReason) => void;
+    /** Attempting to reconnect after connection loss */
+    'connection:reconnecting': (data: {
+        attempt: number;
+        delay: number;
+    }) => void;
+    /** Successfully reconnected after connection loss */
+    'connection:reconnected': (data: {
+        userId: string | null;
+    }) => void;
+    /** All reconnection attempts failed */
+    'connection:reconnectFailed': () => void;
+    /** Connection error occurred */
+    'connection:error': (error: SDKError) => void;
+    /** Connection state changed */
+    'connection:stateChange': (state: ConnectionState) => void;
+    /** Server assigned a user ID (for anonymous users) */
+    'connection:uidAssigned': (uid: string) => void;
+    /** New message received from bot or agent */
+    'message:received': (message: IncomingMessage) => void;
+    /** Message successfully sent */
+    'message:sent': (data: {
+        id: string;
+        message: string;
+    }) => void;
+    /** Message acknowledged by server */
+    'message:acknowledged': (data: {
+        messageId: string;
+    }) => void;
+    /** Message send failed */
+    'message:failed': (data: {
+        messageId: string;
+        error: SDKError;
+    }) => void;
+    /** User typing indicator state changed */
+    'message:typing': (isTyping: boolean) => void;
+    /** Message delivery status updated */
+    'message:status': (data: {
+        messageId: string;
+        status: 'sent' | 'delivered' | 'read';
+    }) => void;
+    /** Bot details are being loaded */
+    'bot:loading': () => void;
+    /** Bot details loaded successfully */
+    'bot:loaded': (botInfo: BotInfo) => void;
+    /** Failed to load bot details */
+    'bot:loadFailed': (error: SDKError) => void;
+    /** Welcome messages to display */
+    'bot:welcomeMessages': (messages: WelcomeMessage[]) => void;
+    /** Bot is typing indicator */
+    'bot:typing': (isTyping: boolean) => void;
+    /** Live agent assigned to conversation */
+    'agent:assigned': (agentProfile: AgentProfile) => void;
+    /** Agent left the conversation */
+    'agent:left': () => void;
+    /** Agent typing indicator */
+    'agent:typing': (isTyping: boolean) => void;
+    /** Live agents are available */
+    'agent:available': () => void;
+    /** No live agents available */
+    'agent:unavailable': () => void;
+    /** Joined queue for live agent */
+    'queue:joined': (data: {
+        position: number;
+        estimatedWait?: number;
+    }) => void;
+    /** Queue position updated */
+    'queue:position': (data: {
+        position: number;
+        message?: string;
+    }) => void;
+    /** Left the queue */
+    'queue:left': () => void;
+    /** History is being loaded */
+    'history:loading': () => void;
+    /** History loaded successfully */
+    'history:loaded': (data: {
+        messages: HistoryMessage[];
+        hasMore: boolean;
+    }) => void;
+    /** Failed to load history */
+    'history:error': (error: SDKError) => void;
+    /** Previous conversation messages received (from fetchPreviousConversation) */
+    'history:previousMessages': (messages: unknown[]) => void;
+    /** Show/configure input field */
+    'ui:showInput': (options: InputOptions) => void;
+    /** Hide input field */
+    'ui:hideInput': () => void;
+    /** Show quick reply buttons */
+    'ui:showQuickReplies': (quickReplies: QuickReply[]) => void;
+    /** Hide quick reply buttons */
+    'ui:hideQuickReplies': () => void;
+    /** Show card carousel */
+    'ui:showCards': (cards: CardContent[]) => void;
+    /** Show web view modal */
+    'ui:showWebView': (webView: WebViewContent) => void;
+    /** Close web view modal */
+    'ui:closeWebView': () => void;
+    /** Show file picker */
+    'ui:showFilePrompt': (options: FilePromptOptions) => void;
+    /** Show rating prompt */
+    'ui:showRating': (options: RatingContent) => void;
+    /** Show notification toast */
+    'ui:showNotification': (data: {
+        title: string;
+        message: string;
+    }) => void;
+    /** Authentication required to continue */
+    'auth:required': () => void;
+    /** Authentication verified successfully */
+    'auth:verified': () => void;
+    /** Authentication failed */
+    'auth:failed': (error: SDKError) => void;
+    /** Auth token needs refresh */
+    'auth:tokenRefreshNeeded': () => void;
+    /** Support ticket created */
+    'ticket:created': (data: {
+        ticketId: string;
+    }) => void;
+    /** Ticket status updated */
+    'ticket:updated': (data: {
+        ticketId: string;
+        status: string;
+    }) => void;
+    /** Ticket closed */
+    'ticket:closed': () => void;
+    /** Ticket resolved */
+    'ticket:resolved': () => void;
+    /** Ticket transferred to new agent */
+    'ticket:transferred': (data: {
+        newAgent: AgentProfile;
+    }) => void;
+    /** Ticket details received */
+    'ticket:details': (data: unknown) => void;
+    /** Campaigns loaded from server */
+    'campaigns:loaded': (campaigns: unknown[]) => void;
+    /** User info updated on server */
+    'user:infoUpdated': (data: unknown) => void;
+    /** File upload started */
+    'file:uploadStarted': (data: {
+        fileId: string;
+        fileName: string;
+    }) => void;
+    /** File upload progress (0-100) */
+    'file:uploadProgress': (data: {
+        fileId: string;
+        progress: number;
+    }) => void;
+    /** File upload completed */
+    'file:uploadCompleted': (data: {
+        fileId: string;
+        file: FileContent;
+    }) => void;
+    /** File upload failed */
+    'file:uploadFailed': (data: {
+        fileId: string;
+        error: SDKError;
+    }) => void;
+    /** Device went online */
+    'network:online': () => void;
+    /** Device went offline */
+    'network:offline': () => void;
+    /** Debug log message (when debug mode enabled) */
+    'debug:log': (data: {
+        level: 'info' | 'warn' | 'error';
+        message: string;
+        data?: unknown;
+    }) => void;
+}
+/**
+ * Type helper to get the handler function type for a specific event.
+ *
+ * @example
+ * ```typescript
+ * // Get the handler type for 'message:received'
+ * type MessageHandler = SDKEventHandler<'message:received'>;
+ * // Result: (message: IncomingMessage) => void
+ *
+ * const handler: MessageHandler = (message) => {
+ *   console.log(message.content.text);
+ * };
+ * ```
+ */
+type SDKEventHandler<K extends keyof SDKEvents> = SDKEvents[K];
+/**
+ * Union type of all valid event names.
+ *
+ * TypeScript will autocomplete event names when using `sdk.on()`.
+ *
+ * @example
+ * ```typescript
+ * const eventName: SDKEventName = 'message:received';
+ * sdk.on(eventName, handler);
+ * ```
+ */
+type SDKEventName = keyof SDKEvents;
+
+/**
+ * YellowChat - Main SDK Class
+ *
+ * The primary interface for integrating Yellow Messenger chat functionality.
+ * Provides event-based communication between the SDK and UI layer.
+ */
+
+/**
+ * YellowChat - Main SDK class
+ *
+ * @example
+ * ```typescript
+ * import { YellowChat } from '@yellowdotai/yellow-true-sdk';
+ *
+ * const sdk = new YellowChat();
+ *
+ * // Subscribe to events
+ * sdk.on('message:received', (message) => {
+ *   console.log('New message:', message);
+ * });
+ *
+ * sdk.on('connection:connected', ({ userId }) => {
+ *   console.log('Connected as:', userId);
+ * });
+ *
+ * // Initialize and connect
+ * await sdk.init({ bot: 'your-bot-id' });
+ * await sdk.connect();
+ *
+ * // Send a message
+ * await sdk.sendMessage('Hello!');
+ * ```
+ */
+declare class YellowChat {
+    private eventEmitter;
+    private config;
+    private connectionManager;
+    private messageHandler;
+    private restTransport;
+    private botLoadAPI;
+    private ticketAPI;
+    private campaignAPI;
+    private userAPI;
+    private isInitialized;
+    private botInfo;
+    private storedUid;
+    private authenticatedFeUID;
+    private isReconnecting;
+    private lastSeenMessageTimestamp;
+    constructor();
+    /**
+     * Get UID from localStorage
+     */
+    private getStoredUid;
+    /**
+     * Store UID in localStorage
+     */
+    private storeUid;
+    /**
+     * Initialize the SDK with configuration.
+     *
+     * This must be called before any other SDK methods. It loads bot details
+     * from the server and sets up internal components.
+     *
+     * @param config - SDK configuration options including bot ID and optional settings
+     * @returns Promise that resolves when initialization is complete
+     * @throws {YellowChatError} INVALID_CONFIG - If bot ID is missing
+     * @throws {YellowChatError} BOT_LOAD_FAILED - If bot details cannot be loaded from server
+     *
+     * @example
+     * ```typescript
+     * const sdk = new YellowChat();
+     *
+     * // Basic initialization
+     * await sdk.init({ bot: 'your-bot-id' });
+     *
+     * // With authentication token
+     * await sdk.init({
+     *   bot: 'your-bot-id',
+     *   ymAuthenticationToken: 'user-auth-token',
+     *   debug: true
+     * });
+     * ```
+     */
+    init(config: SDKConfig): Promise<void>;
+    /**
+     * Connect to the messaging server.
+     *
+     * Establishes a WebSocket connection to the Yellow.ai messaging server.
+     * Must be called after `init()` completes successfully.
+     *
+     * @param userId - Optional user ID for the connection. Behavior depends on mode:
+     *   - **Headless mode**: If `ymAuthenticationToken` was provided during init and server
+     *     returned a `feUID`, that takes priority and this parameter is ignored.
+     *   - **Hybrid mode** (`source: 'syncApi'`): This userId MUST match the sender ID
+     *     used in your REST API calls to ensure ticket continuity.
+     *   - If omitted, SDK uses stored UID from localStorage or server assigns one.
+     * @returns Promise that resolves when connection is established
+     * @throws {YellowChatError} INVALID_CONFIG - If SDK is not initialized
+     * @throws {YellowChatError} CONNECTION_FAILED - If connection cannot be established
+     *
+     * @example
+     * ```typescript
+     * // Anonymous connection (server assigns user ID)
+     * await sdk.connect();
+     *
+     * // With specific user ID
+     * await sdk.connect('user-123');
+     *
+     * // Hybrid mode - match REST API sender
+     * await sdk.connect(restApiSenderId);
+     * ```
+     */
+    connect(userId?: string): Promise<void>;
+    /**
+     * Set up internal event handlers for reconnection etc.
+     */
+    private setupInternalListeners;
+    /**
+     * Get timestamp from a message object
+     */
+    private getMessageTimestamp;
+    /**
+     * Update the last seen message timestamp from a list of messages
+     */
+    private updateLastSeenTimestamp;
+    /**
+     * Fetch post-reconnection data:
+     * 1. Active ticket details (to restore agent state)
+     * 2. Fetch previous/dropped messages
+     * 3. Update user info (to sync context with server)
+     *
+     * Unlike initial connection, does NOT call:
+     * - campaigns (already loaded)
+     */
+    private fetchPostReconnectionData;
+    /**
+     * Fetch post-connection data in sequence:
+     * 1. Active ticket + campaigns (parallel)
+     * 2. Fetch previous conversation history (via REST, response via XMPP)
+     * 3. Update user info
+     */
+    private fetchPostConnectionData;
+    /**
+     * Fetch previous conversation history.
+     *
+     * Requests conversation history from the server. Messages are delivered
+     * via the `history:previousMessages` event, not as a direct return value.
+     *
+     * @param limit - Maximum number of messages to fetch (default: 50)
+     * @param offset - Pagination offset for fetching older messages. Use the offset
+     *                 from previous response to load more history.
+     * @returns Promise that resolves when the request is sent (not when messages arrive)
+     * @throws {YellowChatError} INVALID_CONFIG - If SDK is not initialized
+     *
+     * @example
+     * ```typescript
+     * // Listen for history messages
+     * sdk.on('history:previousMessages', (messages) => {
+     *   console.log('Received history:', messages);
+     * });
+     *
+     * // Fetch last 50 messages
+     * await sdk.fetchPreviousConversation();
+     *
+     * // Fetch with custom limit
+     * await sdk.fetchPreviousConversation(100);
+     *
+     * // Paginate through history
+     * await sdk.fetchPreviousConversation(50, lastMessageOffset);
+     * ```
+     */
+    fetchPreviousConversation(limit?: number, offset?: string): Promise<void>;
+    /**
+     * Disconnect from the messaging server.
+     *
+     * Gracefully closes the WebSocket connection and cleans up resources.
+     * Safe to call even if not currently connected. After disconnecting,
+     * you can call `connect()` again to reconnect.
+     *
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * // Disconnect when user closes chat
+     * sdk.disconnect();
+     *
+     * // Reconnect later
+     * await sdk.connect();
+     * ```
+     */
+    disconnect(): void;
+    /**
+     * Send a text message to the bot or agent.
+     *
+     * Messages are sent via the WebSocket connection. The response includes
+     * a message ID that can be used for tracking. Listen to `message:sent`
+     * event for confirmation or `message:failed` for errors.
+     *
+     * @param message - The message text to send
+     * @param options - Optional send options (e.g., quick reply data, metadata)
+     * @returns Promise resolving to message response with message ID
+     * @throws {YellowChatError} INVALID_CONFIG - If SDK is not initialized
+     * @throws {YellowChatError} MESSAGE_SEND_FAILED - If message cannot be sent
+     *
+     * @example
+     * ```typescript
+     * // Send a simple text message
+     * const response = await sdk.sendMessage('Hello!');
+     * console.log('Message ID:', response.messageId);
+     *
+     * // Send with quick reply payload
+     * await sdk.sendMessage('Option 1', {
+     *   payload: { selectedOption: 'option-1' }
+     * });
+     * ```
+     */
+    sendMessage(message: string, options?: SendMessageOptions): Promise<MessageResponse>;
+    /**
+     * Send an event to the bot (internal use)
+     */
+    private sendEventInternal;
+    /**
+     * Upload and send a file to the conversation.
+     *
+     * Files are first uploaded to the server, then a file message is sent.
+     * Progress and completion events are emitted during the upload process:
+     * - `file:uploadStarted` - Upload has begun
+     * - `file:uploadProgress` - Upload progress update (if supported)
+     * - `file:uploadCompleted` - Upload successful
+     * - `file:uploadFailed` - Upload failed
+     *
+     * @param file - The File object to upload and send
+     * @returns Promise resolving to file upload response with URL, name, and size
+     * @throws {YellowChatError} INVALID_CONFIG - If SDK is not initialized
+     * @throws {YellowChatError} FILE_UPLOAD_FAILED - If file upload fails
+     * @throws {YellowChatError} FILE_TOO_LARGE - If file exceeds size limit
+     * @throws {YellowChatError} FILE_TYPE_NOT_ALLOWED - If file type is not supported
+     *
+     * @example
+     * ```typescript
+     * // Handle file input
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0];
+     *
+     * try {
+     *   const result = await sdk.sendFile(file);
+     *   console.log('File uploaded:', result.url);
+     * } catch (error) {
+     *   console.error('Upload failed:', error.message);
+     * }
+     *
+     * // Listen for upload events
+     * sdk.on('file:uploadStarted', ({ fileId, fileName }) => {
+     *   console.log('Uploading:', fileName);
+     * });
+     * ```
+     */
+    sendFile(file: File): Promise<FileUploadResponse>;
+    /**
+     * Check if currently connected to the messaging server.
+     *
+     * @returns `true` if connected, `false` if disconnected or connecting
+     *
+     * @example
+     * ```typescript
+     * if (sdk.isConnected()) {
+     *   await sdk.sendMessage('Hello!');
+     * } else {
+     *   console.log('Not connected, attempting to reconnect...');
+     *   await sdk.connect();
+     * }
+     * ```
+     */
+    isConnected(): boolean;
+    /**
+     * Get the current user ID for this session.
+     *
+     * The user ID depends on the connection mode:
+     * - **Authenticated users**: Returns `feUID` from `ymAuthenticationToken` validation
+     * - **Hybrid mode**: Returns the user ID passed to `connect()` (REST API sender)
+     * - **Anonymous users**: Returns server-assigned user ID
+     *
+     * @returns The current user ID, or `null` if not connected
+     *
+     * @example
+     * ```typescript
+     * const userId = sdk.getUserId();
+     * if (userId) {
+     *   console.log('Connected as:', userId);
+     * }
+     * ```
+     */
+    getUserId(): string | null;
+    /**
+     * Get bot information loaded during initialization.
+     *
+     * Returns bot configuration including name, welcome message, features,
+     * and UI customization options. Available after `init()` completes.
+     *
+     * @returns Bot information object, or `null` if not initialized
+     *
+     * @example
+     * ```typescript
+     * const botInfo = sdk.getBotInfo();
+     * if (botInfo) {
+     *   console.log('Bot name:', botInfo.name);
+     *   console.log('Welcome message:', botInfo.welcomeMessage);
+     *
+     *   // Use bot skin for UI customization
+     *   if (botInfo.skin) {
+     *     document.body.style.setProperty('--primary-color', botInfo.skin.primaryColor);
+     *   }
+     * }
+     * ```
+     */
+    getBotInfo(): BotInfo | null;
+    /**
+     * Subscribe to an SDK event.
+     *
+     * The SDK uses an event-driven architecture. All events are typed,
+     * so TypeScript will provide autocomplete for event names and handlers.
+     *
+     * **Common Events:**
+     * - `connection:connected` - Successfully connected to server
+     * - `connection:disconnected` - Disconnected from server
+     * - `message:received` - New message from bot or agent
+     * - `message:sent` - Message successfully sent
+     * - `agent:assigned` - Live agent connected to chat
+     * - `typing:start` / `typing:stop` - Typing indicators
+     *
+     * @param event - Event name (e.g., 'message:received', 'connection:connected')
+     * @param handler - Event handler function. Parameters depend on event type.
+     * @returns Unsubscribe function - call it to stop listening
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to messages
+     * const unsubscribe = sdk.on('message:received', (message) => {
+     *   console.log('New message:', message.text);
+     *   console.log('From:', message.sender);
+     * });
+     *
+     * // Subscribe to connection events
+     * sdk.on('connection:connected', ({ userId }) => {
+     *   console.log('Connected as:', userId);
+     * });
+     *
+     * sdk.on('connection:disconnected', ({ reason }) => {
+     *   console.log('Disconnected:', reason);
+     * });
+     *
+     * // Unsubscribe when done
+     * unsubscribe();
+     * ```
+     */
+    on<K extends SDKEventName>(event: K, handler: SDKEvents[K]): () => void;
+    /**
+     * Unsubscribe from an SDK event.
+     *
+     * Removes a previously registered event handler. You must pass the exact
+     * same function reference that was used when calling `on()`.
+     *
+     * **Tip:** Prefer using the unsubscribe function returned by `on()` instead.
+     *
+     * @param event - Event name to unsubscribe from
+     * @param handler - The exact same handler function that was passed to `on()`
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * // Define handler as a named function
+     * const messageHandler = (message) => {
+     *   console.log('Message:', message);
+     * };
+     *
+     * // Subscribe
+     * sdk.on('message:received', messageHandler);
+     *
+     * // Unsubscribe later
+     * sdk.off('message:received', messageHandler);
+     * ```
+     */
+    off<K extends SDKEventName>(event: K, handler: SDKEvents[K]): void;
+    /**
+     * Ensure SDK is initialized before operations
+     */
+    private ensureInitialized;
+}
+/**
+ * Create a new YellowChat SDK instance.
+ *
+ * Factory function alternative to `new YellowChat()`. Use this when you
+ * prefer functional-style instantiation or want to avoid the `new` keyword.
+ *
+ * @returns A new YellowChat instance ready for initialization
+ *
+ * @example
+ * ```typescript
+ * import { createYellowChat } from '@yellowdotai/yellow-chat-sdk';
+ *
+ * const sdk = createYellowChat();
+ *
+ * await sdk.init({ bot: 'your-bot-id' });
+ * await sdk.connect();
+ *
+ * sdk.on('message:received', (message) => {
+ *   console.log('New message:', message);
+ * });
+ * ```
+ */
+declare function createYellowChat(): YellowChat;
+
+export { YellowChat, YellowChatError, createSDKError, createYellowChat, YellowChat as default };
+export type { AgentProfile, AudioContent, BannerConfig, BotFeatures, BotInfo, BotLoadResponse, BotSkin, CardAction, CardContent, ConnectionState, DateContent, DisconnectReason, FeedbackContent, FileContent, FilePromptOptions, FileUploadResponse, HistoryMessage, ImageContent, IncomingMessage, InputOptions, LocationContent, MessageContent, MessageResponse, MessageSender, MessageType, MultiSelectContent, MultiSelectOption, OutgoingMessage, QuickReply, QuickReplyContent, RatingContent, SDKConfig, SDKError, SDKErrorCode, SDKEventHandler, SDKEventName, SDKEvents, SendMessageOptions, VideoContent, WebViewContent, WelcomeMessage };