@aikaara/chat-sdk 0.1.4 → 0.3.0

package/dist/ui.d.ts

@@ -6,6 +6,77 @@ export declare class AikaaraChatBubble extends HTMLElement {
     setIcon(svgOrText: string): void;
 }
 
+declare class AikaaraChatClient extends EventEmitter<ChatEvents> {
+    private connection;
+    private tiledesk;
+    private api;
+    private messageStore;
+    private conversationManager;
+    private subscription;
+    private config;
+    private mode;
+    private uploadAdapter;
+    private tiledeskUnsubs;
+    constructor(config: ChatClientConfig_2, opts?: {
+        uploadAdapter?: UploadAdapter_2;
+    });
+    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_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): 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 AikaaraChatHeader extends HTMLElement {
     private shadow;
     static get observedAttributes(): string[];
@@ -43,8 +114,11 @@ export declare class AikaaraChatWidget extends HTMLElement {
     attributeChangedCallback(_name: string, oldVal: string, newVal: string): void;
     configure(config: Partial<WidgetConfig>): void;
     private getConfig;
+    setUploadAdapter(adapter: UploadAdapter): void;
     private render;
     private initController;
+    sendUserEvent(eventKey: string, value?: Record<string, unknown>, source?: string): void;
+    getClient(): AikaaraChatClient | null;
     private darkenColor;
 }
 
@@ -60,11 +134,19 @@ export declare class AikaaraErrorBanner extends HTMLElement {
 
 export declare class AikaaraMessageBubble extends HTMLElement {
     private shadow;
+    private templatePayload;
+    private attachments;
     static get observedAttributes(): string[];
     constructor();
     connectedCallback(): void;
     attributeChangedCallback(): void;
+    setTemplatePayload(payload: unknown): void;
+    setAttachments(attachments: Array<{
+        fileName: string;
+        fileUrl: string;
+    }>): void;
     private render;
+    private renderAttachments;
 }
 
 export declare class AikaaraMessageList extends HTMLElement {
@@ -83,6 +165,13 @@ export declare class AikaaraMessageList extends HTMLElement {
     showTypingIndicator(): void;
     removeTypingIndicator(): void;
     private appendMessageElement;
+    /**
+     * Replace an existing rendered message (matched by id or externalId) in place.
+     * Used when a Tiledesk self-echo reconciles with an optimistic bubble or when
+     * a status update flips delivered → read.
+     */
+    upsertMessage(message: Message): void;
+    private findRenderedMessage;
     private scrollToBottom;
     private formatTime;
 }
@@ -96,6 +185,27 @@ export declare class AikaaraStreamingMessage extends HTMLElement {
     finalize(): void;
 }
 
+/**
+ * Renders Tiledesk contentType=300 template payloads.
+ *
+ * Slot-based override system — tenants ship a cloud-hosted bundle that
+ * registers `<aikaara-template-{templateId}>` custom elements; this component
+ * looks one up by `template-id` attribute and mounts it as a child. If no
+ * tenant override is registered, a no-op fallback renders the inner message
+ * (TaxBuddy-style nested envelope) so the chat at least shows readable text.
+ */
+export declare class AikaaraTemplateRenderer extends HTMLElement {
+    private shadow;
+    private payloadData;
+    private innerMessage;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    setPayload(payload: unknown, innerMessage?: string): void;
+    private render;
+}
+
 export declare class AikaaraTypingIndicator extends HTMLElement {
     private shadow;
     constructor();
@@ -104,23 +214,140 @@ export declare class AikaaraTypingIndicator extends HTMLElement {
     hide(): void;
 }
 
+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>;
+}
+
 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;
+}
+
+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;
+    };
+    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;
+}
+
+declare interface ChatEvents {
+    '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;
+    '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;
+    };
 }
 
 declare interface ConnectionConfig {
     baseUrl: string;
     wsUrl?: string;
     userToken: string;
+    tiledesk?: TiledeskTransportConfig;
+    reconnect?: boolean;
+    maxReconnectAttempts?: number;
+    reconnectInterval?: number;
+}
+
+declare interface ConnectionConfig_2 {
+    baseUrl: string;
+    wsUrl?: string;
+    userToken: string;
+    tiledesk?: TiledeskTransportConfig_2;
     reconnect?: boolean;
     maxReconnectAttempts?: number;
     reconnectInterval?: number;
@@ -128,10 +355,33 @@ declare interface ConnectionConfig {
 
 declare type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
 
+declare type ConnectionState_2 = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+
+declare interface EditEntityAction {
+    action: 'edit_entity';
+    entity_type: string;
+    entity_id: string | number;
+    fields: FieldUpdate[];
+}
+
+declare class EventEmitter<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;
+}
+
+declare interface FieldUpdate {
+    field: string;
+    value: unknown;
+    previousValue?: unknown;
+}
+
 declare interface Message {
     id: string;
     conversationId: string;
-    role: 'user' | 'assistant' | 'system' | 'tool';
+    role: 'user' | 'assistant' | 'system' | 'tool' | 'agent';
     content: string;
     toolCalls?: ToolCall[];
     toolCallResults?: ToolCallResult;
@@ -139,11 +389,195 @@ 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;
+    }>;
+}
+
+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;
+    }>;
+}
+
+declare interface NavigateAction {
+    navigate_to: string;
 }
 
 export declare function registerComponents(): void;
 
+declare interface SaveEntityAction {
+    action: 'save_entity';
+}
+
+declare interface TemplateMessageEvent {
+    messageId: string;
+    conversationId: string;
+    role: 'user' | 'assistant' | 'system' | 'agent';
+    contentType?: string;
+    templateId?: string;
+    payload?: unknown;
+    innerMessage?: string;
+    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;
+}
+
+declare interface TestToolAction {
+    action: 'test_tool';
+    tool_id: number;
+    parameters: Record<string, unknown>;
+}
+
+declare interface TiledeskFileTemplateConfig {
+    templateId: string;
+    headerImgSrc?: string;
+    type?: 'link' | 'image';
+    isDeepLink?: boolean;
+}
+
+declare interface TiledeskFileTemplateConfig_2 {
+    templateId: string;
+    headerImgSrc?: string;
+    type?: 'link' | 'image';
+    isDeepLink?: boolean;
+}
+
+declare interface TiledeskMessageDefaults {
+    channelType?: string;
+    channel?: string;
+    requestChannel?: string;
+    platform?: string;
+    medium?: string;
+    departmentId?: string;
+    attributes?: Record<string, unknown>;
+}
+
+declare interface TiledeskMessageDefaults_2 {
+    channelType?: string;
+    channel?: string;
+    requestChannel?: string;
+    platform?: string;
+    medium?: string;
+    departmentId?: string;
+    attributes?: Record<string, unknown>;
+}
+
+declare interface TiledeskTopicTemplates {
+    inbound?: string;
+    inboundUpdate?: string;
+    outbound?: string;
+    presence?: string;
+    wildcardSubscribe?: string;
+}
+
+declare interface TiledeskTopicTemplates_2 {
+    inbound?: string;
+    inboundUpdate?: string;
+    outbound?: string;
+    presence?: string;
+    wildcardSubscribe?: string;
+}
+
+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;
+}
+
+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;
+}
+
 declare interface ToolCall {
     id: string;
     type: 'function';
@@ -153,11 +587,71 @@ declare interface ToolCall {
     };
 }
 
+declare interface ToolCall_2 {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+
 declare interface ToolCallResult {
     tool_call_id: string;
     content: string;
 }
 
+declare interface ToolCallResult_2 {
+    tool_call_id: string;
+    content: string;
+}
+
+declare type TransportMode = 'aikaara' | 'tiledesk' | 'dual';
+
+declare type TransportMode_2 = 'aikaara' | 'tiledesk' | 'dual';
+
+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>;
+}
+
+declare interface UploadAdapterContext {
+    conversationId: string;
+    userId: string;
+    projectId?: string;
+    appId?: string;
+}
+
+declare interface UploadAdapterContext_2 {
+    conversationId: string;
+    userId: string;
+    projectId?: string;
+    appId?: string;
+}
+
+declare interface UploadAdapterResult {
+    url: string;
+    fileName: string;
+    cloudFileId?: string;
+    relativePath?: string;
+    contentType?: string;
+    byteSize?: number;
+    meta?: Record<string, unknown>;
+}
+
+declare interface UploadAdapterResult_2 {
+    url: string;
+    fileName: string;
+    cloudFileId?: string;
+    relativePath?: string;
+    contentType?: string;
+    byteSize?: number;
+    meta?: Record<string, unknown>;
+}
+
 declare interface WidgetConfig extends ChatClientConfig {
     position?: 'bottom-right' | 'bottom-left';
     offset?: {
@@ -180,6 +674,7 @@ declare interface WidgetConfig extends ChatClientConfig {
     showBubble?: boolean;
     bubbleText?: string;
     bubbleIcon?: string;
+    uploadAdapter?: UploadAdapter;
 }
 
 export { }