@aikaara/chat-sdk 0.1.4 → 0.3.0

package/dist/headless.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./headless-CrgIWcf7.cjs");exports.ActionCableClient=e.ActionCableClient;exports.AikaaraChatClient=e.AikaaraChatClient;exports.ApiClient=e.ApiClient;exports.ChannelSubscription=e.ChannelSubscription;exports.ConnectionManager=e.ConnectionManager;exports.ConversationManager=e.ConversationManager;exports.EventEmitter=e.EventEmitter;exports.MessageStore=e.MessageStore;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./AikaaraChatClient-kAu65hX-.cjs");class g extends s.EventEmitter{registration=null;pendingEdits=[];constructor(t){super(),this.setupListeners(t)}registerForm(t){this.registration=t;const e=this.pendingEdits.filter(i=>i.entity_type===t.entityType&&String(i.entity_id)===String(t.entityId));if(e.length>0){for(const i of e)t.onFieldUpdate(i.fields),this.emit("edit:applied",{entityType:i.entity_type,entityId:i.entity_id,fields:i.fields});this.pendingEdits=this.pendingEdits.filter(i=>!(i.entity_type===t.entityType&&String(i.entity_id)===String(t.entityId)))}}unregisterForm(t,e){this.registration?.entityType===t&&String(this.registration?.entityId)===String(e)&&(this.registration=null)}get currentForm(){return this.registration}pushFieldUpdates(t,e,i){this.registration&&this.registration.entityType===t&&String(this.registration.entityId)===String(e)?(this.registration.onFieldUpdate(i),this.emit("edit:applied",{entityType:t,entityId:e,fields:i})):(this.pendingEdits.push({action:"edit_entity",entity_type:t,entity_id:e,fields:i}),this.emit("edit:pending",{entityType:t,entityId:e,fields:i}))}async requestSave(){if(!this.registration)return{success:!1,error:"No form registered"};try{return await this.registration.onSave(),this.emit("save:success",{entityType:this.registration.entityType,entityId:this.registration.entityId}),{success:!0}}catch(t){const e=t instanceof Error?t.message:"Save failed";return this.emit("save:error",{entityType:this.registration.entityType,entityId:this.registration.entityId,error:e}),{success:!1,error:e}}}async requestTest(t){if(!this.registration?.onTest)return{success:!1,error:"Current form does not support testing"};try{return await this.registration.onTest(t),{success:!0}}catch(e){return{success:!1,error:e instanceof Error?e.message:"Test failed"}}}setupListeners(t){t.on("action:edit_entity",e=>{this.pushFieldUpdates(e.entity_type,e.entity_id,e.fields)}),t.on("action:save_entity",e=>{this.requestSave()}),t.on("action:test_tool",e=>{this.emit("test:triggered",{toolId:e.tool_id,parameters:e.parameters}),this.requestTest(e.parameters)})}}function m(n){return{async upload(t,e){const i=new FormData,p=n.fieldName??"file";i.append(p,t,t.name);const o=typeof n.extraFields=="function"?n.extraFields(e):n.extraFields;if(o)for(const[u,y]of Object.entries(o))i.append(u,y);i.append("conversationId",e.conversationId),i.append("userId",e.userId),e.projectId&&i.append("projectId",e.projectId);const c=typeof n.headers=="function"?await n.headers():n.headers??{},a=await fetch(n.endpoint,{method:n.method??"POST",body:i,headers:c,credentials:n.credentials});if(!a.ok)throw new Error(`Upload failed: ${a.status} ${a.statusText}`);const d=await a.json().catch(()=>({}));if(n.parseResponse)return n.parseResponse(d,e);const r=d,l=r.url??r.fileUrl??r.publicUrl,h=r.fileName??r.name??t.name;if(!l)throw new Error('Upload response missing "url" / "fileUrl" / "publicUrl"');return{url:l,fileName:h,cloudFileId:typeof r.cloudFileId=="string"?r.cloudFileId:void 0,relativePath:typeof r.path=="string"?r.path:void 0,contentType:typeof r.contentType=="string"?r.contentType:void 0,byteSize:typeof r.byteSize=="number"?r.byteSize:void 0,meta:r}}}}exports.ActionCableClient=s.ActionCableClient;exports.AikaaraChatClient=s.AikaaraChatClient;exports.ApiClient=s.ApiClient;exports.ChannelSubscription=s.ChannelSubscription;exports.ConnectionManager=s.ConnectionManager;exports.ConversationManager=s.ConversationManager;exports.EventEmitter=s.EventEmitter;exports.MessageStore=s.MessageStore;exports.TiledeskTransport=s.TiledeskTransport;exports.extractTiledeskFileEnvelope=s.extractTiledeskFileEnvelope;exports.inferTiledeskRole=s.inferTiledeskRole;exports.isTiledeskSelfEcho=s.isTiledeskSelfEcho;exports.parseTiledeskTemplate=s.parseTiledeskTemplate;exports.FormBridge=g;exports.createFetchUploadAdapter=m;

package/dist/headless.d.ts

@@ -22,6 +22,8 @@ export declare interface ActionCableMessage {
     message?: unknown;
 }
 
+export declare type AgentAction = EditEntityAction | SaveEntityAction | TestToolAction | NavigateAction;
+
 export declare interface AgentEvent {
     type: AgentEventType;
     [key: string]: unknown;
@@ -31,39 +33,108 @@ export declare type AgentEventType = 'status' | 'error' | 'agent_start' | 'agent
 
 export declare class AikaaraChatClient extends EventEmitter<ChatEvents> {
     private connection;
+    private tiledesk;
     private api;
     private messageStore;
     private conversationManager;
     private subscription;
     private config;
-    constructor(config: ChatClientConfig);
+    private mode;
+    private uploadAdapter;
+    private tiledeskUnsubs;
+    constructor(config: ChatClientConfig, opts?: {
+        uploadAdapter?: UploadAdapter;
+    });
+    private usesAikaara;
+    private usesTiledesk;
+    private initTiledeskTransport;
     connect(): Promise<void>;
     sendMessage(content: string): 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): void;
     sendUserEvent(eventKey: string, value?: object, source?: string): Promise<void>;
     loadHistory(): Promise<Message[]>;
     get messages(): Message[];
     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): 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;
 }
 
 export declare class ApiClient {
     private baseUrl;
     private apiKey?;
+    private authToken?;
     private userToken;
-    constructor(baseUrl: string, userToken: string, apiKey?: string);
+    constructor(baseUrl: string, userToken: string, apiKey?: string, authToken?: string);
     createConversation(params: {
         systemPromptId?: number;
         channel?: string;
         title?: string;
         extUid?: string;
     }): Promise<CreateConversationResponse>;
+    updateContext(conversationId: string, context: Record<string, unknown>): Promise<void>;
     getMessages(conversationId: string): Promise<Message[]>;
     private mapMessage;
     private request;
 }
 
+export declare interface AppContext {
+    /** 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;
@@ -82,15 +153,35 @@ export declare class ChannelSubscription {
 
 export declare interface ChatClientConfig extends ConnectionConfig {
     apiKey?: string;
+    authToken?: string;
     extUid?: string;
     conversationId?: string;
     systemPromptId?: number;
-    channel?: 'widget' | 'api';
+    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;
+    /**
+     * 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;
+    };
     onMessage?: (message: Message) => void;
     onStatusChange?: (status: string) => void;
     onError?: (error: Error) => void;
     onStreamUpdate?: (delta: string, fullContent: string) => void;
     onConnectionStateChange?: (state: ConnectionState) => void;
+    onTemplateMessage?: (template: TemplateMessageEvent) => void;
 }
 
 export declare interface ChatEvents {
@@ -116,12 +207,26 @@ export declare interface ChatEvents {
     'typing:stop': void;
     'error': Error;
     'status': string;
+    'action:edit_entity': EditEntityAction;
+    'action:save_entity': SaveEntityAction;
+    'action:test_tool': TestToolAction;
+    'action:navigate': NavigateAction;
+    'tool:start': {
+        toolName: string;
+        args: Record<string, unknown>;
+    };
+    'tool:end': {
+        toolName: string;
+        result: unknown;
+        isError: boolean;
+    };
 }
 
 export declare interface ConnectionConfig {
     baseUrl: string;
     wsUrl?: string;
     userToken: string;
+    tiledesk?: TiledeskTransportConfig;
     reconnect?: boolean;
     maxReconnectAttempts?: number;
     reconnectInterval?: number;
@@ -164,6 +269,15 @@ declare interface CreateConversationResponse {
     status: string;
 }
 
+export declare function createFetchUploadAdapter(config: FetchUploadAdapterConfig): UploadAdapter;
+
+export declare interface EditEntityAction {
+    action: 'edit_entity';
+    entity_type: string;
+    entity_id: string | number;
+    fields: FieldUpdate[];
+}
+
 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;
@@ -172,10 +286,153 @@ export declare class EventEmitter<Events extends Record<string, any>> {
     removeAllListeners(): void;
 }
 
+export declare function extractTiledeskFileEnvelope(message: TiledeskMessage): TiledeskFileEnvelope | null;
+
+export declare interface FetchUploadAdapterConfig {
+    endpoint: string;
+    method?: 'POST' | 'PUT';
+    fieldName?: string;
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    credentials?: RequestCredentials;
+    extraFields?: Record<string, string> | ((ctx: UploadAdapterContext) => Record<string, string>);
+    parseResponse?: (raw: unknown, ctx: UploadAdapterContext) => UploadAdapterResult;
+}
+
+export declare interface FieldUpdate {
+    field: string;
+    value: unknown;
+    previousValue?: unknown;
+}
+
+export declare class FormBridge extends EventEmitter<FormBridgeEvents> {
+    private registration;
+    private pendingEdits;
+    constructor(client: AikaaraChatClient);
+    /**
+     * Register a form to receive AI-driven edits.
+     * Only one form can be registered at a time (the active page).
+     */
+    registerForm(reg: FormRegistration): void;
+    /**
+     * Unregister the form (call on unmount).
+     */
+    unregisterForm(entityType: string, entityId: string | number): void;
+    /**
+     * Get the current form registration (if any).
+     */
+    get currentForm(): FormRegistration | null;
+    /**
+     * Manually push field updates (for custom tool handling).
+     */
+    pushFieldUpdates(entityType: string, entityId: string | number, fields: FieldUpdate[]): void;
+    /**
+     * Request the current form to save.
+     */
+    requestSave(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Request the current form to run a test.
+     */
+    requestTest(params?: Record<string, unknown>): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    private setupListeners;
+}
+
+/**
+ * FormBridge — Enables AI agents to visually edit forms in the host application.
+ *
+ * This bridges the gap between AI tool results and UI form state. When the agent
+ * calls tools like `edit_current_entity`, the FormBridge receives the action and
+ * pushes field updates to the registered form.
+ *
+ * ## Usage (any framework)
+ *
+ * ```typescript
+ * import { AikaaraChatClient, FormBridge } from '@aikaara/chat-sdk/headless';
+ *
+ * const client = new AikaaraChatClient({ baseUrl, userToken, authToken });
+ * const bridge = new FormBridge(client);
+ *
+ * // Register a form (call when your form mounts)
+ * bridge.registerForm({
+ *   entityType: 'product',
+ *   entityId: 42,
+ *   onFieldUpdate: (fields) => {
+ *     for (const { field, value } of fields) {
+ *       formState[field] = value; // update your form framework
+ *     }
+ *   },
+ *   onSave: async () => await api.saveProduct(42, formState),
+ *   getCurrentValues: () => ({ ...formState }),
+ * });
+ *
+ * // Unregister when form unmounts
+ * bridge.unregisterForm('product', 42);
+ * ```
+ *
+ * ## React hook (provided by dashboard, but easy to replicate)
+ *
+ * ```tsx
+ * function useFormBridge(bridge, { entityType, entityId, onFieldUpdate, onSave }) {
+ *   useEffect(() => {
+ *     bridge.registerForm({ entityType, entityId, onFieldUpdate, onSave, getCurrentValues });
+ *     return () => bridge.unregisterForm(entityType, entityId);
+ *   }, [entityType, entityId]);
+ * }
+ * ```
+ */
+export declare interface FormBridgeEvents {
+    'edit:applied': {
+        entityType: string;
+        entityId: string | number;
+        fields: FieldUpdate[];
+    };
+    'edit:pending': {
+        entityType: string;
+        entityId: string | number;
+        fields: FieldUpdate[];
+    };
+    'save:success': {
+        entityType: string;
+        entityId: string | number;
+    };
+    'save:error': {
+        entityType: string;
+        entityId: string | number;
+        error: string;
+    };
+    'test:triggered': {
+        toolId: number;
+        parameters: Record<string, unknown>;
+    };
+}
+
+export declare interface FormRegistration {
+    entityType: string;
+    entityId: string | number;
+    onFieldUpdate: (fields: FieldUpdate[]) => void;
+    onSave: () => Promise<void>;
+    onTest?: (params?: Record<string, unknown>) => Promise<void>;
+    getCurrentValues: () => Record<string, unknown>;
+}
+
+export declare function inferTiledeskRole(message: TiledeskMessage, cfg: TiledeskRoleConfig): TiledeskRole;
+
+/**
+ * Self-echo detector — Tiledesk fans the user's outgoing publish back
+ * as a `clientadded` event on the same connection. UI must dedupe against
+ * the optimistic local message rather than rendering twice.
+ */
+export declare function isTiledeskSelfEcho(message: TiledeskMessage, userId: string): boolean;
+
 export declare interface Message {
     id: string;
     conversationId: string;
-    role: 'user' | 'assistant' | 'system' | 'tool';
+    role: 'user' | 'assistant' | 'system' | 'tool' | 'agent';
     content: string;
     toolCalls?: ToolCall[];
     toolCallResults?: ToolCallResult;
@@ -183,7 +440,19 @@ export declare interface Message {
     tokensOutput?: number;
     metadata?: Record<string, unknown>;
     createdAt: string;
-    status?: 'sending' | 'sent' | 'streaming' | 'complete' | 'error';
+    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 {
@@ -191,6 +460,22 @@ export declare class MessageStore {
     private optimisticCounter;
     get messages(): Message[];
     addOptimistic(role: 'user', content: string, conversationId: string): Message;
+    /**
+     * Reconcile a remote message against an outstanding optimistic message.
+     * Tiledesk fans the user's outgoing publish back as an inbound clientadded —
+     * dedupe by exact content + recency window so the optimistic bubble keeps
+     * its position and we don't render duplicates.
+     */
+    reconcileOptimistic(remote: Message, recencyMs?: number): Message | null;
+    /**
+     * Append a remote-originated message (e.g. from Tiledesk MQTT). If a matching
+     * optimistic message exists it is reconciled in place; otherwise appended.
+     */
+    upsertRemoteMessage(remote: Message): {
+        message: Message;
+        deduped: boolean;
+    };
+    updateMessageStatus(externalId: string, status: Message['status']): Message | undefined;
     confirmOptimistic(tempId: string): void;
     addStreamingMessage(conversationId: string): Message;
     updateStreaming(content: string): void;
@@ -205,8 +490,211 @@ export declare class MessageStore {
     clear(): void;
 }
 
+export declare interface NavigateAction {
+    navigate_to: string;
+}
+
+export declare function parseTiledeskTemplate(message: TiledeskMessage): TiledeskParsedTemplate;
+
+export declare interface SaveEntityAction {
+    action: 'save_entity';
+}
+
 declare type SubscriptionCallback = (data: unknown) => void;
 
+declare interface TemplateMessageEvent {
+    messageId: string;
+    conversationId: string;
+    role: 'user' | 'assistant' | 'system' | 'agent';
+    contentType?: string;
+    templateId?: string;
+    payload?: unknown;
+    innerMessage?: string;
+    raw: unknown;
+}
+
+export declare interface TestToolAction {
+    action: 'test_tool';
+    tool_id: number;
+    parameters: Record<string, unknown>;
+}
+
+export declare interface TiledeskFileEnvelope {
+    fileName?: string;
+    fileUrl?: string;
+    cloudFileId?: string;
+    templateId?: string;
+}
+
+export declare interface TiledeskFileMessageInput {
+    fileName: string;
+    fileUrl: string;
+    cloudFileId?: string;
+    templateId?: string;
+    headerImgSrc?: string;
+    type?: 'link' | 'image';
+    isDeepLink?: boolean;
+    description?: string;
+    attributes?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+
+export declare interface TiledeskFileTemplateConfig {
+    templateId: string;
+    headerImgSrc?: string;
+    type?: 'link' | 'image';
+    isDeepLink?: boolean;
+}
+
+export declare interface TiledeskMessage {
+    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;
+    messageId?: string;
+    kind: 'clientadded' | 'update' | 'unknown';
+}
+
+export declare interface TiledeskMessageDefaults {
+    channelType?: string;
+    channel?: string;
+    requestChannel?: string;
+    platform?: string;
+    medium?: string;
+    departmentId?: string;
+    attributes?: Record<string, unknown>;
+}
+
+export declare interface TiledeskParsedTemplate {
+    contentType?: string;
+    templateId?: string;
+    payload?: unknown;
+    innerMessage?: string;
+    raw: TiledeskMessage;
+}
+
+export declare type TiledeskRole = 'user' | 'assistant' | 'system' | 'agent';
+
+export declare interface TiledeskRoleConfig {
+    userId: string;
+    systemSenders?: string[];
+    botSenderPrefix?: string;
+}
+
+export declare interface TiledeskStatusUpdate {
+    conversationId: string;
+    messageId: string;
+    status: number;
+    raw: Record<string, unknown>;
+}
+
+export declare interface TiledeskTopicTemplates {
+    inbound?: string;
+    inboundUpdate?: string;
+    outbound?: string;
+    presence?: string;
+    wildcardSubscribe?: string;
+}
+
+export declare class TiledeskTransport {
+    private client;
+    private config;
+    private currentToken;
+    private clientId;
+    private appId;
+    private topics;
+    private messageHandlers;
+    private stateHandlers;
+    private statusUpdateHandlers;
+    private subscribedTopics;
+    private reconnectAttempt;
+    private maxReconnectAttempts;
+    private reconnectMaxDelayMs;
+    private disposed;
+    private reconnectTimer;
+    private inboundRegex;
+    private inboundUpdateRegex;
+    constructor(config: TiledeskTransportConfig);
+    connect(): Promise<void>;
+    subscribeWildcard(): void;
+    subscribeToConversation(conversationId: string): void;
+    unsubscribeFromConversation(conversationId: string): void;
+    publishMessage(conversationId: string, text: string, overrides?: Partial<TiledeskMessage>): void;
+    publishFileMessage(conversationId: string, file: TiledeskFileMessageInput): void;
+    publishRaw(conversationId: string, message: TiledeskMessage): void;
+    /**
+     * Send a read receipt for a message. Tiledesk widgets publish
+     * `{"status":300}` to apps/{appId}/users/{userId}/messages/{convId}/{msgId}/update.
+     */
+    publishReadReceipt(conversationId: string, messageId: string, status?: number): void;
+    /**
+     * Trigger conversation kickoff. Tiledesk bot routing waits for the
+     * widget to publish a CHAT_INITIATED event before the bot replies.
+     */
+    publishChatInitiated(conversationId: string, extraAttributes?: Record<string, unknown>): void;
+    onMessage(handler: TransportMessageHandler): () => void;
+    onStateChange(handler: TransportStateHandler): () => void;
+    onStatusUpdate(handler: TransportStatusUpdateHandler): () => void;
+    disconnect(): void;
+    get isConnected(): boolean;
+    private scheduleReconnect;
+    private notifyStateChange;
+    private dispatchInbound;
+    private buildOutgoingEnvelope;
+    private publishEnvelope;
+    private renderInboundTopic;
+    private renderOutboundTopic;
+    private renderPresenceTopic;
+    private renderTemplate;
+    private buildTopicRegex;
+}
+
+export declare interface TiledeskTransportConfig {
+    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;
+    messageDefaults?: TiledeskMessageDefaults;
+    fileTemplate?: TiledeskFileTemplateConfig;
+    recipientFullnameResolver?: (conversationId: string) => string | undefined;
+    senderFullname?: string;
+}
+
 export declare interface ToolCall {
     id: string;
     type: 'function';
@@ -221,6 +709,35 @@ export declare interface ToolCallResult {
     content: string;
 }
 
+export declare type TransportMessageHandler = (message: TiledeskMessage, ctx: TiledeskMessageContext) => void;
+
+declare type TransportMode = 'aikaara' | 'tiledesk' | 'dual';
+
+export declare type TransportStateHandler = (connected: boolean) => void;
+
+export declare type TransportStatusUpdateHandler = (update: TiledeskStatusUpdate) => void;
+
+export declare interface UploadAdapter {
+    upload(file: File | Blob, ctx: UploadAdapterContext): Promise<UploadAdapterResult>;
+}
+
+export declare interface UploadAdapterContext {
+    conversationId: string;
+    userId: string;
+    projectId?: string;
+    appId?: string;
+}
+
+export declare interface UploadAdapterResult {
+    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?: {
@@ -243,6 +760,7 @@ export declare interface WidgetConfig extends ChatClientConfig {
     showBubble?: boolean;
     bubbleText?: string;
     bubbleIcon?: string;
+    uploadAdapter?: UploadAdapter;
 }
 
 export { }