@aikaara/chat-sdk 0.3.0 → 0.4.0

package/dist/headless.d.ts

@@ -41,15 +41,21 @@ export declare class AikaaraChatClient extends EventEmitter<ChatEvents> {
     private config;
     private mode;
     private uploadAdapter;
+    private historyAdapter;
     private tiledeskUnsubs;
     constructor(config: ChatClientConfig, opts?: {
         uploadAdapter?: UploadAdapter;
+        historyAdapter?: ConversationHistoryAdapter;
     });
     private usesAikaara;
     private usesTiledesk;
     private initTiledeskTransport;
     connect(): Promise<void>;
-    sendMessage(content: string): Promise<void>;
+    private hydrateTiledeskHistory;
+    sendMessage(content: string, opts?: {
+        attributes?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
     /**
      * Upload a file via the configured UploadAdapter (client-side: file goes
      * to the tenant's own backend, never through Aikaara). Then publish the
@@ -102,6 +108,103 @@ export declare class AikaaraChatClient extends EventEmitter<ChatEvents> {
     private handleBroadcast;
 }
 
+declare class AikaaraChatClient_2 extends EventEmitter_2<ChatEvents_2> {
+    private connection;
+    private tiledesk;
+    private api;
+    private messageStore;
+    private conversationManager;
+    private subscription;
+    private config;
+    private mode;
+    private uploadAdapter;
+    private historyAdapter;
+    private tiledeskUnsubs;
+    constructor(config: ChatClientConfig_2, opts?: {
+        uploadAdapter?: UploadAdapter_2;
+        historyAdapter?: ConversationHistoryAdapter_2;
+    });
+    private usesAikaara;
+    private usesTiledesk;
+    private initTiledeskTransport;
+    connect(): Promise<void>;
+    private hydrateTiledeskHistory;
+    sendMessage(content: string, opts?: {
+        attributes?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Upload a file via the configured UploadAdapter (client-side: file goes
+     * to the tenant's own backend, never through Aikaara). Then publish the
+     * Tiledesk file-message envelope so hooks_controller picks it up.
+     */
+    sendFile(file: File | Blob, opts?: {
+        caption?: string;
+    }): Promise<void>;
+    /**
+     * Trigger Tiledesk's CHAT_INITIATED event — required to kick off a bot flow
+     * for newly-created Tiledesk request groups.
+     */
+    initiateTiledeskChat(extraAttributes?: Record<string, unknown>): void;
+    /** Mark a Tiledesk message as read (publishes status=300 update). */
+    markTiledeskRead(messageId: string): void;
+    setUploadAdapter(adapter: UploadAdapter_2): void;
+    sendUserEvent(eventKey: string, value?: object, source?: string): Promise<void>;
+    loadHistory(): Promise<Message_2[]>;
+    get messages(): Message_2[];
+    get conversationId(): string | null;
+    get isConnected(): boolean;
+    /**
+     * Update the agent's context with information about the host app's current state.
+     * Call this on route changes so the agent knows what page/entity the user is viewing.
+     *
+     * The context is stored in conversation metadata and interpolated into the system prompt.
+     *
+     * @example
+     * ```typescript
+     * // On route change
+     * client.setContext({
+     *   currentPage: '/products/42',
+     *   entityType: 'product',
+     *   entityId: '42',
+     *   availableRoutes: { products: '/products', orders: '/orders' },
+     * });
+     * ```
+     */
+    setContext(context: AppContext_2): Promise<void>;
+    disconnect(): Promise<void>;
+    private handleTiledeskMessage;
+    private handleTiledeskStatusUpdate;
+    /**
+     * Parse structured action results from tool execution output.
+     * When the agent calls tools like `edit_current_entity`, `save_current_entity`,
+     * `navigate_to`, or `test_tool_by_id`, the result contains an action payload
+     * that the SDK emits as a typed event for the host app to handle.
+     */
+    private parseActionResult;
+    private handleBroadcast;
+}
+
+declare class AikaaraChatWidget extends HTMLElement {
+    private shadow;
+    private controller;
+    private _config;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, oldVal: string, newVal: string): void;
+    configure(config: Partial<WidgetConfig>): void;
+    private getConfig;
+    setUploadAdapter(adapter: UploadAdapter): void;
+    setHistoryAdapter(adapter: ConversationHistoryAdapter): void;
+    private render;
+    private initController;
+    sendUserEvent(eventKey: string, value?: Record<string, unknown>, source?: string): void;
+    getClient(): AikaaraChatClient_2 | null;
+    private darkenColor;
+}
+
 export declare class ApiClient {
     private baseUrl;
     private apiKey?;
@@ -135,6 +238,21 @@ export declare interface AppContext {
     custom?: Record<string, unknown>;
 }
 
+declare interface AppContext_2 {
+    /** Current page/route path in the host app (e.g., '/products/42') */
+    currentPage: string;
+    /** Entity type on the current page (e.g., 'product', 'agent') */
+    entityType?: string;
+    /** Entity ID on the current page */
+    entityId?: string | number;
+    /** Project/workspace ID if applicable */
+    projectId?: string | number;
+    /** Routes the agent can navigate to — map of label → path */
+    availableRoutes?: Record<string, string>;
+    /** Additional context for the agent (e.g., form field names, entity schema) */
+    custom?: Record<string, unknown>;
+}
+
 export declare class ChannelSubscription {
     readonly identifier: string;
     private callbacks;
@@ -176,6 +294,13 @@ export declare interface ChatClientConfig extends ConnectionConfig {
         departmentId?: string;
         senderFullname?: string;
     };
+    /**
+     * Tenant-level defaults merged into the `action` object of every template
+     * postback (e.g. submit-action click). Useful for app-specific keys like
+     * `serviceType: 'ITR'` that the bot expects on every form submission.
+     * Per-submit values from the form take precedence over these defaults.
+     */
+    templateActionAttributes?: Record<string, unknown>;
     onMessage?: (message: Message) => void;
     onStatusChange?: (status: string) => void;
     onError?: (error: Error) => void;
@@ -184,6 +309,46 @@ export declare interface ChatClientConfig extends ConnectionConfig {
     onTemplateMessage?: (template: TemplateMessageEvent) => void;
 }
 
+declare interface ChatClientConfig_2 extends ConnectionConfig_2 {
+    apiKey?: string;
+    authToken?: string;
+    extUid?: string;
+    conversationId?: string;
+    systemPromptId?: number;
+    channel?: 'widget' | 'api' | 'sidekick';
+    /**
+     * Transport selection.
+     * - `aikaara` (default): ActionCable to Aikaara Rails (AI streaming).
+     * - `tiledesk`: MQTT direct to a self-hosted Tiledesk + chat21 stack.
+     * - `dual`: both — Aikaara cable for AI, Tiledesk MQTT for live-agent + file events.
+     */
+    transport?: TransportMode_2;
+    /**
+     * Tiledesk-side identity. Required when `transport` is `tiledesk` or `dual`.
+     * `userId` here is the Tiledesk user `_id` and is also used as the SDK conversation
+     * subject — Aikaara conversations bound to this user via ext_uid mapping.
+     */
+    tiledeskIdentity?: {
+        userId: string;
+        userName?: string;
+        departmentId?: string;
+        senderFullname?: string;
+    };
+    /**
+     * Tenant-level defaults merged into the `action` object of every template
+     * postback (e.g. submit-action click). Useful for app-specific keys like
+     * `serviceType: 'ITR'` that the bot expects on every form submission.
+     * Per-submit values from the form take precedence over these defaults.
+     */
+    templateActionAttributes?: Record<string, unknown>;
+    onMessage?: (message: Message_2) => void;
+    onStatusChange?: (status: string) => void;
+    onError?: (error: Error) => void;
+    onStreamUpdate?: (delta: string, fullContent: string) => void;
+    onConnectionStateChange?: (state: ConnectionState_2) => void;
+    onTemplateMessage?: (template: TemplateMessageEvent_2) => void;
+}
+
 export declare interface ChatEvents {
     'connection:state': ConnectionState;
     'message:received': Message;
@@ -222,6 +387,46 @@ export declare interface ChatEvents {
     };
 }
 
+declare interface ChatEvents_2 {
+    'connection:state': ConnectionState_2;
+    'message:received': Message_2;
+    'message:updated': Message_2;
+    'message:sent': Message_2;
+    'stream:start': {
+        messageId: string;
+    };
+    'stream:update': {
+        delta: string;
+        content: string;
+    };
+    'stream:end': {
+        messageId: string;
+        usage?: {
+            tokensInput: number;
+            tokensOutput: number;
+        };
+    };
+    'typing:start': void;
+    'typing:stop': void;
+    'error': Error;
+    'status': string;
+    'action:edit_entity': EditEntityAction_2;
+    'action:save_entity': SaveEntityAction_2;
+    'action:test_tool': TestToolAction_2;
+    'action:navigate': NavigateAction_2;
+    'tool:start': {
+        toolName: string;
+        args: Record<string, unknown>;
+    };
+    'tool:end': {
+        toolName: string;
+        result: unknown;
+        isError: boolean;
+    };
+}
+
+export declare function clearPersistedConversationId(userId: string, projectId: string): void;
+
 export declare interface ConnectionConfig {
     baseUrl: string;
     wsUrl?: string;
@@ -232,6 +437,16 @@ export declare interface ConnectionConfig {
     reconnectInterval?: number;
 }
 
+declare interface ConnectionConfig_2 {
+    baseUrl: string;
+    wsUrl?: string;
+    userToken: string;
+    tiledesk?: TiledeskTransportConfig_2;
+    reconnect?: boolean;
+    maxReconnectAttempts?: number;
+    reconnectInterval?: number;
+}
+
 export declare class ConnectionManager extends EventEmitter<ChatEvents> {
     private client;
     private config;
@@ -253,6 +468,34 @@ export declare class ConnectionManager extends EventEmitter<ChatEvents> {
 
 export declare type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
 
+declare type ConnectionState_2 = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+
+/**
+ * Pluggable adapter that hydrates prior conversation messages on connect.
+ * The SDK calls this once after MQTT subscribes so the user sees existing
+ * history before any new live messages arrive.
+ */
+export declare interface ConversationHistoryAdapter {
+    fetchMessages(conversationId: string, ctx: {
+        userId: string;
+        appId?: string;
+        projectId?: string;
+    }): Promise<TiledeskMessage[]>;
+}
+
+/**
+ * Pluggable adapter that hydrates prior conversation messages on connect.
+ * The SDK calls this once after MQTT subscribes so the user sees existing
+ * history before any new live messages arrive.
+ */
+declare interface ConversationHistoryAdapter_2 {
+    fetchMessages(conversationId: string, ctx: {
+        userId: string;
+        appId?: string;
+        projectId?: string;
+    }): Promise<TiledeskMessage_2[]>;
+}
+
 export declare class ConversationManager {
     private _conversationId;
     private persist;
@@ -271,6 +514,10 @@ declare interface CreateConversationResponse {
 
 export declare function createFetchUploadAdapter(config: FetchUploadAdapterConfig): UploadAdapter;
 
+export declare function createPresigned3StepUploadAdapter(config: Presigned3StepAdapterConfig): UploadAdapter;
+
+export declare function createTiledeskHistoryAdapter(config: TiledeskHistoryAdapterConfig): ConversationHistoryAdapter;
+
 export declare interface EditEntityAction {
     action: 'edit_entity';
     entity_type: string;
@@ -278,6 +525,13 @@ export declare interface EditEntityAction {
     fields: FieldUpdate[];
 }
 
+declare interface EditEntityAction_2 {
+    action: 'edit_entity';
+    entity_type: string;
+    entity_id: string | number;
+    fields: FieldUpdate_2[];
+}
+
 export declare class EventEmitter<Events extends Record<string, any>> {
     private handlers;
     on<K extends keyof Events & string>(event: K, handler: (data: Events[K]) => void): () => void;
@@ -286,6 +540,14 @@ export declare class EventEmitter<Events extends Record<string, any>> {
     removeAllListeners(): void;
 }
 
+declare class EventEmitter_2<Events extends Record<string, any>> {
+    private handlers;
+    on<K extends keyof Events & string>(event: K, handler: (data: Events[K]) => void): () => void;
+    off<K extends keyof Events & string>(event: K, handler: (data: Events[K]) => void): void;
+    emit<K extends keyof Events & string>(event: K, data: Events[K]): void;
+    removeAllListeners(): void;
+}
+
 export declare function extractTiledeskFileEnvelope(message: TiledeskMessage): TiledeskFileEnvelope | null;
 
 export declare interface FetchUploadAdapterConfig {
@@ -304,6 +566,12 @@ export declare interface FieldUpdate {
     previousValue?: unknown;
 }
 
+declare interface FieldUpdate_2 {
+    field: string;
+    value: unknown;
+    previousValue?: unknown;
+}
+
 export declare class FormBridge extends EventEmitter<FormBridgeEvents> {
     private registration;
     private pendingEdits;
@@ -455,6 +723,32 @@ export declare interface Message {
     }>;
 }
 
+declare interface Message_2 {
+    id: string;
+    conversationId: string;
+    role: 'user' | 'assistant' | 'system' | 'tool' | 'agent';
+    content: string;
+    toolCalls?: ToolCall_2[];
+    toolCallResults?: ToolCallResult_2;
+    tokensInput?: number;
+    tokensOutput?: number;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    status?: 'sending' | 'sent' | 'delivered' | 'read' | 'streaming' | 'complete' | 'error';
+    externalId?: string;
+    template?: {
+        contentType?: string;
+        templateId?: string;
+        payload?: unknown;
+    };
+    attachments?: Array<{
+        fileName: string;
+        fileUrl: string;
+        cloudFileId?: string;
+        contentType?: string;
+    }>;
+}
+
 export declare class MessageStore {
     private _messages;
     private optimisticCounter;
@@ -490,16 +784,182 @@ export declare class MessageStore {
     clear(): void;
 }
 
+export declare interface MountedTenantWidget {
+    widget: AikaaraChatWidget;
+    requestId: string;
+    config: WidgetConfig;
+    destroy: () => void;
+}
+
+/**
+ * Single-call mount. Pulls the descriptor from `widget_configs/:slug`, runs
+ * descriptor.auth to mint chat JWT + requestId, builds upload + history
+ * adapters from descriptor.upload, and mounts the web component. Host app
+ * supplies only the user id + their session JWT.
+ *
+ *   import { mountFromSlug } from '@aikaara/chat-sdk';
+ *
+ *   await mountFromSlug({
+ *     container: '#chat',
+ *     slug: 'bandhan-itr',
+ *     user: { id: '33568', token: () => getCognitoJwt() },
+ *   });
+ */
+export declare function mountFromSlug(opts: SlugMountOptions): Promise<SlugMountedWidget>;
+
+/**
+ * Standard tenant mount. Fetches the descriptor (when `configUrl` is set),
+ * merges per-mount overrides, builds default adapters from the descriptor's
+ * endpoint URLs (when no override is supplied), and mounts the widget.
+ */
+export declare function mountTenantWidget(opts: TenantMountOptions): Promise<MountedTenantWidget>;
+
 export declare interface NavigateAction {
     navigate_to: string;
 }
 
+declare interface NavigateAction_2 {
+    navigate_to: string;
+}
+
 export declare function parseTiledeskTemplate(message: TiledeskMessage): TiledeskParsedTemplate;
 
+/**
+ * Three-step presigned-S3 upload (sign → PUT → register). Driven entirely
+ * by descriptor — no tenant-specific code in host apps.
+ */
+export declare interface Presigned3StepAdapterConfig {
+    /** GET endpoint that returns a presigned URL. `{fileName}` placeholder. */
+    signEndpoint: string;
+    signMethod?: 'GET' | 'POST';
+    /** Dot path into the response JSON for the presigned URL. Default `data.s3SignedUrl`. */
+    signedUrlPath?: string;
+    /** Optional POST registering the upload (e.g. `/chatbuddy/file-upload`). */
+    registerEndpoint?: string;
+    /**
+     * Body JSON for the register POST. Tokens: `{fileName}`, `{userId}`,
+     * `{requestId}` (alias `{conversationId}`).
+     */
+    registerBody?: Record<string, unknown>;
+    /**
+     * Final URL the chat message will carry. Tokens: `{fileName}`, `{userId}`,
+     * `{requestId}`. When omitted the presigned URL itself is used.
+     */
+    viewerTemplate?: string;
+    /**
+     * Rewrite the host portion of the presigned URL before PUTting (used for
+     * dev proxies). E.g. `/s3-upload`. Leave empty for direct.
+     */
+    s3HostRewrite?: string;
+    /** Bearer token getter for sign + register calls. */
+    authHeader?: () => string | Promise<string>;
+    /** Static extra headers for sign + register. */
+    extraHeaders?: Record<string, string>;
+}
+
 export declare interface SaveEntityAction {
     action: 'save_entity';
 }
 
+declare interface SaveEntityAction_2 {
+    action: 'save_entity';
+}
+
+export declare class SessionAuthAdapter {
+    private readonly descriptor;
+    private readonly sessionToken;
+    private cache;
+    private inflight;
+    constructor(descriptor: SessionAuthDescriptor, sessionToken: SessionTokenProvider);
+    /** Force-refresh by clearing cache. Next `get()` call refetches. */
+    reset(): void;
+    get(): Promise<SessionAuthData>;
+    private fetchOnce;
+}
+
+export declare interface SessionAuthData {
+    token: string;
+    requestId: string;
+    fullName: string;
+    expiresAt: number;
+}
+
+/**
+ * Descriptor-driven session auth.
+ *
+ * The host app supplies a "session token" — typically a JWT issued by their
+ * own auth (Cognito/Auth0/firebase/etc) — and the descriptor declares how to
+ * exchange it for a chat-platform JWT + conversation requestId. The SDK runs
+ * the exchange itself, caches the result, and refreshes when the chat JWT
+ * approaches expiry. The original requestId is preserved across refreshes so
+ * the conversation thread is stable.
+ */
+export declare interface SessionAuthDescriptor {
+    /** Absolute or same-origin URL — POSTed with the session token as bearer. */
+    endpoint: string;
+    method?: 'POST' | 'GET';
+    /** JSON body for the request. POST only. */
+    body?: Record<string, unknown>;
+    /** Extra static headers (e.g. partnerid). */
+    headers?: Record<string, string>;
+    /** Header carrying the session token. Default `Authorization`. */
+    authHeader?: string;
+    /**
+     * Template for the session-token header value. `{token}` is replaced.
+     * Default: `Bearer {token}`. Use `JWT {token}` etc. when required.
+     */
+    authHeaderTemplate?: string;
+    /** Dot path into the response JSON for the chat JWT. Default `data.token`. */
+    tokenPath?: string;
+    /** Stripped from the extracted token before use (e.g. `JWT `). */
+    tokenStripPrefix?: string;
+    /** Dot path for the conversation requestId. Default `data.requestId`. */
+    requestIdPath?: string;
+    /** Dot path for the user display name. Default `data.fullName`. */
+    fullNamePath?: string;
+    /** Refetch when the JWT is within this many ms of expiry. Default 60_000. */
+    expiryBufferMs?: number;
+}
+
+export declare type SessionTokenProvider = string | (() => string | Promise<string>);
+
+export declare interface SlugMountedWidget extends MountedTenantWidget {
+    fullName: string;
+    /** Force a fresh /chatbuddy/auth-style refetch (clears cached requestId). */
+    refreshAuth(): Promise<void>;
+}
+
+export declare interface SlugMountOptions {
+    /** Container element or CSS selector (e.g. `#chat`). */
+    container: HTMLElement | string;
+    /** Tenant identifier — the SDK fetches `${configBase}/widget_configs/${slug}`. */
+    slug: string;
+    /** Defaults to `https://api.aikaara.com`. Override for self-hosted aikaara. */
+    configBase?: string;
+    /** Additional headers for the descriptor fetch. */
+    configHeaders?: Record<string, string>;
+    user: {
+        id: string;
+        /** Display name fallback when descriptor.auth doesn't return one. */
+        name?: string;
+        departmentId?: string;
+        /**
+         * Session JWT (Cognito/Auth0/firebase/etc) — passed as bearer to
+         * `descriptor.auth.endpoint`. Can be a string (static for the session)
+         * or a getter that re-resolves on each refresh.
+         */
+        token: SessionTokenProvider;
+    };
+    /** Optional escape hatches; merge over descriptor-driven defaults. */
+    hooks?: {
+        upload?: UploadAdapter;
+        history?: ConversationHistoryAdapter;
+        onError?: (err: Error) => void;
+    };
+    /** Per-mount visual overrides. */
+    overrides?: Partial<WidgetConfigDescriptor>;
+}
+
 declare type SubscriptionCallback = (data: unknown) => void;
 
 declare interface TemplateMessageEvent {
@@ -513,12 +973,66 @@ declare interface TemplateMessageEvent {
     raw: unknown;
 }
 
+declare interface TemplateMessageEvent_2 {
+    messageId: string;
+    conversationId: string;
+    role: 'user' | 'assistant' | 'system' | 'agent';
+    contentType?: string;
+    templateId?: string;
+    payload?: unknown;
+    innerMessage?: string;
+    raw: unknown;
+}
+
+export declare interface TenantMountOptions {
+    container: HTMLElement;
+    /** Fetched from this URL when `config` is omitted. */
+    configUrl?: string;
+    /** Pre-resolved descriptor — skip the fetch. */
+    config?: WidgetConfigDescriptor;
+    /** Headers attached when fetching `configUrl` (e.g. tenant-API auth). */
+    configHeaders?: Record<string, string>;
+    identity: {
+        userId: string;
+        userName?: string;
+        departmentId?: string;
+        senderFullname?: string;
+    };
+    /** Returns a raw Tiledesk JWT (no Bearer/JWT prefix) for MQTT password. */
+    tokenProvider: () => Promise<string>;
+    /** Authorization value for the history fetch. Defaults to `tokenProvider()`. */
+    historyTokenProvider?: () => Promise<string>;
+    /**
+     * Optional override adapters. If omitted and the descriptor specifies the
+     * matching endpoint, the SDK builds default fetch-based adapters.
+     */
+    uploadAdapter?: UploadAdapter;
+    historyAdapter?: ConversationHistoryAdapter;
+    /**
+     * Pin a conversationId. When omitted we look up
+     * `aikaara_chat:requestId:{userId}:{projectId}` in localStorage and reuse
+     * any persisted value; only mint a fresh `requestId` when nothing is stored.
+     */
+    conversationId?: string;
+    forceNewConversation?: boolean;
+    /** Per-mount overrides that take precedence over the descriptor. */
+    overrides?: Partial<WidgetConfigDescriptor>;
+    /** Surfaced from the SDK. */
+    onError?: (err: Error) => void;
+}
+
 export declare interface TestToolAction {
     action: 'test_tool';
     tool_id: number;
     parameters: Record<string, unknown>;
 }
 
+declare interface TestToolAction_2 {
+    action: 'test_tool';
+    tool_id: number;
+    parameters: Record<string, unknown>;
+}
+
 export declare interface TiledeskFileEnvelope {
     fileName?: string;
     fileUrl?: string;
@@ -546,6 +1060,39 @@ export declare interface TiledeskFileTemplateConfig {
     isDeepLink?: boolean;
 }
 
+declare interface TiledeskFileTemplateConfig_2 {
+    templateId: string;
+    headerImgSrc?: string;
+    type?: 'link' | 'image';
+    isDeepLink?: boolean;
+}
+
+export declare interface TiledeskHistoryAdapterConfig {
+    /**
+     * Base URL of the Tiledesk chat API, e.g. `https://uat-tiledesk.taxbuddy.com/chatapi/api`
+     * (no trailing slash). Final URL is composed as
+     *   `{apiBase}/tilechat/{userId}/conversations/{conversationId}/messages?pageSize={pageSize}`
+     */
+    apiBase: string;
+    pageSize?: number;
+    /**
+     * Async getter for the bearer token. Most Tiledesk-fronted gateways accept
+     * the same JWT used for the MQTT connection. Return `null` to omit the
+     * `Authorization` header.
+     */
+    getToken?: () => string | null | Promise<string | null>;
+    /** Override the path template. Default mirrors bandhan's chatapi route. */
+    pathTemplate?: string;
+    /** Extra static headers to attach (e.g. `partnerid`, `environment`). */
+    extraHeaders?: Record<string, string>;
+    /**
+     * Optional response shape mapper. Default expects
+     *   `{ success: true, result: TiledeskMessage[] }`
+     * which matches the bandhan `/chatapi/api/tilechat/.../messages` response.
+     */
+    parseResponse?: (raw: unknown) => TiledeskMessage[];
+}
+
 export declare interface TiledeskMessage {
     text?: string;
     type?: string;
@@ -564,6 +1111,24 @@ export declare interface TiledeskMessage {
     [key: string]: unknown;
 }
 
+declare interface TiledeskMessage_2 {
+    text?: string;
+    type?: string;
+    sender?: string;
+    senderFullname?: string;
+    sender_fullname?: string;
+    recipient?: string;
+    recipient_fullname?: string;
+    channel_type?: string;
+    timestamp?: number;
+    app_id?: string;
+    message_id?: string;
+    status?: number;
+    attributes?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
 export declare interface TiledeskMessageContext {
     topic: string;
     conversationId?: string;
@@ -581,6 +1146,16 @@ export declare interface TiledeskMessageDefaults {
     attributes?: Record<string, unknown>;
 }
 
+declare interface TiledeskMessageDefaults_2 {
+    channelType?: string;
+    channel?: string;
+    requestChannel?: string;
+    platform?: string;
+    medium?: string;
+    departmentId?: string;
+    attributes?: Record<string, unknown>;
+}
+
 export declare interface TiledeskParsedTemplate {
     contentType?: string;
     templateId?: string;
@@ -612,6 +1187,14 @@ export declare interface TiledeskTopicTemplates {
     wildcardSubscribe?: string;
 }
 
+declare interface TiledeskTopicTemplates_2 {
+    inbound?: string;
+    inboundUpdate?: string;
+    outbound?: string;
+    presence?: string;
+    wildcardSubscribe?: string;
+}
+
 export declare class TiledeskTransport {
     private client;
     private config;
@@ -632,6 +1215,7 @@ export declare class TiledeskTransport {
     private inboundUpdateRegex;
     constructor(config: TiledeskTransportConfig);
     connect(): Promise<void>;
+    private debugLog;
     subscribeWildcard(): void;
     subscribeToConversation(conversationId: string): void;
     unsubscribeFromConversation(conversationId: string): void;
@@ -693,6 +1277,64 @@ export declare interface TiledeskTransportConfig {
     fileTemplate?: TiledeskFileTemplateConfig;
     recipientFullnameResolver?: (conversationId: string) => string | undefined;
     senderFullname?: string;
+    /**
+     * If true (default), AikaaraChatClient publishes a `CHAT_INITIATED` event
+     * to the conversation's outbound topic on first connect — but only when
+     * the conversation history is empty (so reload of an in-flight chat
+     * doesn't replay the kickoff).
+     */
+    autoInitiateOnEmpty?: boolean;
+    /** Extra attributes merged into the auto-fired CHAT_INITIATED envelope. */
+    chatInitiatedAttributes?: Record<string, unknown>;
+    /**
+     * Log decoded MQTT frames to console as they're sent/received.
+     * Off by default — set true for debugging Tiledesk wire traffic.
+     */
+    debug?: boolean;
+}
+
+declare interface TiledeskTransportConfig_2 {
+    mqttEndpoint: string;
+    jwtToken: string;
+    userId: string;
+    userName?: string;
+    projectId: string;
+    appId?: string;
+    clientId?: string;
+    protocolVersion?: 3 | 4 | 5;
+    protocolId?: 'MQIsdp' | 'MQTT';
+    mqttUsername?: string;
+    connectTimeoutMs?: number;
+    keepAliveSec?: number;
+    maxReconnectAttempts?: number;
+    reconnectMaxDelayMs?: number;
+    tokenProvider?: () => Promise<string>;
+    wildcardSubscribe?: boolean;
+    subscribeQos?: 0 | 1 | 2;
+    publishQos?: 0 | 1 | 2;
+    publishRetain?: boolean;
+    enablePresence?: boolean;
+    presencePayloadConnected?: Record<string, unknown>;
+    presencePayloadDisconnected?: Record<string, unknown>;
+    topicTemplates?: TiledeskTopicTemplates_2;
+    messageDefaults?: TiledeskMessageDefaults_2;
+    fileTemplate?: TiledeskFileTemplateConfig_2;
+    recipientFullnameResolver?: (conversationId: string) => string | undefined;
+    senderFullname?: string;
+    /**
+     * If true (default), AikaaraChatClient publishes a `CHAT_INITIATED` event
+     * to the conversation's outbound topic on first connect — but only when
+     * the conversation history is empty (so reload of an in-flight chat
+     * doesn't replay the kickoff).
+     */
+    autoInitiateOnEmpty?: boolean;
+    /** Extra attributes merged into the auto-fired CHAT_INITIATED envelope. */
+    chatInitiatedAttributes?: Record<string, unknown>;
+    /**
+     * Log decoded MQTT frames to console as they're sent/received.
+     * Off by default — set true for debugging Tiledesk wire traffic.
+     */
+    debug?: boolean;
 }
 
 export declare interface ToolCall {
@@ -704,15 +1346,31 @@ export declare interface ToolCall {
     };
 }
 
+declare interface ToolCall_2 {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+
 export declare interface ToolCallResult {
     tool_call_id: string;
     content: string;
 }
 
+declare interface ToolCallResult_2 {
+    tool_call_id: string;
+    content: string;
+}
+
 export declare type TransportMessageHandler = (message: TiledeskMessage, ctx: TiledeskMessageContext) => void;
 
 declare type TransportMode = 'aikaara' | 'tiledesk' | 'dual';
 
+declare type TransportMode_2 = 'aikaara' | 'tiledesk' | 'dual';
+
 export declare type TransportStateHandler = (connected: boolean) => void;
 
 export declare type TransportStatusUpdateHandler = (update: TiledeskStatusUpdate) => void;
@@ -721,6 +1379,10 @@ export declare interface UploadAdapter {
     upload(file: File | Blob, ctx: UploadAdapterContext): Promise<UploadAdapterResult>;
 }
 
+declare interface UploadAdapter_2 {
+    upload(file: File | Blob, ctx: UploadAdapterContext_2): Promise<UploadAdapterResult_2>;
+}
+
 export declare interface UploadAdapterContext {
     conversationId: string;
     userId: string;
@@ -728,6 +1390,13 @@ export declare interface UploadAdapterContext {
     appId?: string;
 }
 
+declare interface UploadAdapterContext_2 {
+    conversationId: string;
+    userId: string;
+    projectId?: string;
+    appId?: string;
+}
+
 export declare interface UploadAdapterResult {
     url: string;
     fileName: string;
@@ -738,6 +1407,16 @@ export declare interface UploadAdapterResult {
     meta?: Record<string, unknown>;
 }
 
+declare interface UploadAdapterResult_2 {
+    url: string;
+    fileName: string;
+    cloudFileId?: string;
+    relativePath?: string;
+    contentType?: string;
+    byteSize?: number;
+    meta?: Record<string, unknown>;
+}
+
 export declare interface WidgetConfig extends ChatClientConfig {
     position?: 'bottom-right' | 'bottom-left';
     offset?: {
@@ -761,6 +1440,92 @@ export declare interface WidgetConfig extends ChatClientConfig {
     bubbleText?: string;
     bubbleIcon?: string;
     uploadAdapter?: UploadAdapter;
+    historyAdapter?: ConversationHistoryAdapter;
+    /**
+     * Display mode:
+     *   - `popup` (default): floating bubble in the corner, click to open panel.
+     *   - `embed`: render the chat panel inline at the host element's location,
+     *     filling its container. Bubble + open/close animation are skipped.
+     */
+    display?: 'popup' | 'embed';
+}
+
+export declare interface WidgetConfigDescriptor {
+    /** Visuals */
+    display?: 'popup' | 'embed';
+    position?: 'bottom-right' | 'bottom-left';
+    primaryColor?: string;
+    title?: string;
+    subtitle?: string;
+    avatarUrl?: string;
+    width?: number;
+    height?: number;
+    borderRadius?: number;
+    fontFamily?: string;
+    welcomeMessage?: string;
+    placeholder?: string;
+    showTimestamps?: boolean;
+    persistConversation?: boolean;
+    /** Transport selection */
+    transport?: TransportMode;
+    /** Tiledesk wire config (JSON-serializable subset of TiledeskTransportConfig) */
+    tiledesk?: {
+        mqttEndpoint: string;
+        appId?: string;
+        projectId: string;
+        mqttUsername?: string;
+        protocolId?: 'MQIsdp' | 'MQTT';
+        protocolVersion?: 3 | 4 | 5;
+        keepAliveSec?: number;
+        connectTimeoutMs?: number;
+        maxReconnectAttempts?: number;
+        reconnectMaxDelayMs?: number;
+        wildcardSubscribe?: boolean;
+        enablePresence?: boolean;
+        autoInitiateOnEmpty?: boolean;
+        chatInitiatedAttributes?: Record<string, unknown>;
+        messageDefaults?: TiledeskMessageDefaults;
+        fileTemplate?: TiledeskFileTemplateConfig;
+        topicTemplates?: TiledeskTopicTemplates;
+        debug?: boolean;
+        /**
+         * Pattern for `support-group-…` requestId minted on first chat. Use
+         * `{projectId}` and `{uuid}` placeholders. Defaults to bandhan's
+         * `support-group-{projectId}-{uuid}`.
+         */
+        requestIdTemplate?: string;
+    };
+    /** Defaults merged into every form-action postback */
+    templateActionAttributes?: Record<string, unknown>;
+    /** Adapter endpoints — SDK builds the actual fetch calls */
+    uploadEndpoint?: string;
+    uploadFieldName?: string;
+    uploadExtraFields?: Record<string, string>;
+    historyApiBase?: string;
+    historyPageSize?: number;
+    historyPathTemplate?: string;
+    /**
+     * Server-side session-token exchange. When set, the SDK exchanges the
+     * caller-supplied `sessionToken` for a chat JWT + conversation requestId
+     * itself — the host app no longer needs a `tokenProvider` callback.
+     */
+    auth?: SessionAuthDescriptor;
+    /**
+     * Built-in upload strategy. `mode: "presigned-3step"` runs sign → PUT →
+     * register entirely from descriptor config; `mode: "direct"` POSTs as
+     * multipart to a single endpoint; `mode: "none"` disables uploads. Host
+     * apps can still override with `opts.uploadAdapter`.
+     */
+    upload?: {
+        mode: 'none';
+    } | {
+        mode: 'direct';
+        endpoint: string;
+        fieldName?: string;
+        extraFields?: Record<string, string>;
+    } | ({
+        mode: 'presigned-3step';
+    } & Presigned3StepAdapterConfig);
 }
 
 export { }