@knowbl_ai/nexus-chat 1.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2025 Knowbl AI
+
+All rights reserved. This software and associated documentation files
+(the "Software") may not be used, copied, modified, merged, published,
+distributed, sublicensed, or sold without prior written permission from
+Knowbl AI.
+
+For licensing inquiries, contact: support@knowbl.com

package/README.md

@@ -0,0 +1,126 @@
+# @knowbl_ai/nexus-chat
+
+Embeddable AI chat widget for Nexus AI Platform.
+
+For full documentation, visit: https://docs.nexus.knowbl.com/
+
+## Installation
+
+```bash
+npm install @knowbl_ai/nexus-chat
+```
+
+Or via CDN:
+
+```html
+<script src="https://unpkg.com/@knowbl_ai/nexus-chat"></script>
+```
+
+## Quick Start
+
+### Script Tag (Recommended for most users)
+
+```html
+<script
+  src="https://unpkg.com/@knowbl_ai/nexus-chat"
+  data-experience-id="your-experience-id"
+></script>
+```
+
+The widget auto-initializes when loaded with the `data-experience-id` attribute.
+
+### ES Module
+
+```typescript
+import { initWidget } from "@knowbl_ai/nexus-chat";
+
+const widget = initWidget({
+  experienceId: "your-experience-id",
+  apiUrl: "https://nexus-api.knowbl.com/api/v2",
+  theme: {
+    primaryColor: "#007bff",
+  },
+});
+
+// Widget API
+widget.open();
+widget.close();
+widget.toggle();
+widget.sendMessage("Hello!");
+```
+
+### UMD (Browser Global)
+
+```html
+<script src="https://unpkg.com/@knowbl_ai/nexus-chat"></script>
+<script>
+  const widget = window.NexusChatWidget.init({
+    experienceId: "your-experience-id",
+  });
+</script>
+```
+
+## Configuration
+
+```typescript
+interface WidgetConfig {
+  experienceId: string;
+  apiUrl?: string; // Defaults to https://nexus-api.knowbl.com/api/v2
+  theme?: {
+    primaryColor?: string;
+    fontFamily?: string;
+  };
+  position?: "bottom-right" | "bottom-left";
+  messages?: {
+    welcomeMessage?: string;
+    placeholder?: string;
+  };
+  // See full documentation for all options
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support included. Types are automatically loaded when you import the package.
+
+```typescript
+import { initWidget } from "@knowbl_ai/nexus-chat";
+import type { WidgetConfig, WidgetAPI } from "@knowbl_ai/nexus-chat";
+
+const config: WidgetConfig = {
+  experienceId: "your-id",
+};
+
+const api: WidgetAPI = initWidget(config);
+```
+
+## Documentation
+
+For complete documentation including:
+
+- Full configuration options
+- Theming and customization
+- Event handling
+- Message interceptors
+- Authentication
+
+Visit: https://docs.nexus.knowbl.com/
+
+## Browser Support
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Bundle Size
+
+~30KB gzipped (all dependencies bundled)
+
+## License
+
+Proprietary - see LICENSE file
+
+## Support
+
+For support inquiries, contact: support@knowbl.com

package/dist/types/services/actionStateManager.d.ts

@@ -0,0 +1,21 @@
+import type { ActionConfig, ActionState, ChatEvent } from "../types";
+export declare class ActionStateManager {
+    /**
+     * Create initial action states for a message
+     */
+    static initializeActionStates(messageId: string, actions: ActionConfig[]): ActionState[];
+    /**
+     * Mark action as used (for oneTimeUse behavior)
+     */
+    static markActionUsed(actionStates: ActionState[], actionId: string): ActionState[];
+    /**
+     * Update action states based on new turn
+     * This implements auto-disabling of previous turn actions
+     */
+    static updateStatesOnNewTurn(allEvents: ChatEvent[], currentTurnIndex: number): ChatEvent[];
+    /**
+     * Get current turn index (last assistant message index)
+     */
+    static getCurrentTurnIndex(events: ChatEvent[]): number;
+}
+//# sourceMappingURL=actionStateManager.d.ts.map

package/dist/types/services/actionStateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionStateManager.d.ts","sourceRoot":"","sources":["../../../src/services/actionStateManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErE,qBAAa,kBAAkB;IAC7B;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,EAAE,GACtB,WAAW,EAAE;IAUhB;;OAEG;IACH,MAAM,CAAC,cAAc,CACnB,YAAY,EAAE,WAAW,EAAE,EAC3B,QAAQ,EAAE,MAAM,GACf,WAAW,EAAE;IAchB;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CAC1B,SAAS,EAAE,SAAS,EAAE,EACtB,gBAAgB,EAAE,MAAM,GACvB,SAAS,EAAE;IA2Dd;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM;CAYxD"}

package/dist/types/services/tabCoordinator.d.ts

@@ -0,0 +1,90 @@
+import type { ChatEvent } from "../types";
+export type TabMessage = {
+    type: "session_created";
+    experienceId: string;
+    sessionId: string;
+    timestamp: number;
+} | {
+    type: "session_cleared";
+    experienceId: string;
+    timestamp: number;
+} | {
+    type: "event_added";
+    experienceId: string;
+    event: ChatEvent;
+    timestamp: number;
+} | {
+    type: "event_updated";
+    experienceId: string;
+    eventId: string;
+    updates: Partial<ChatEvent>;
+    timestamp: number;
+} | {
+    type: "state_changed";
+    experienceId: string;
+    state: TabSyncState;
+    timestamp: number;
+} | {
+    type: "request_sync";
+    experienceId: string;
+    tabId: string;
+} | {
+    type: "sync_response";
+    experienceId: string;
+    targetTabId: string;
+    state: FullSyncState;
+};
+export interface TabSyncState {
+    isOpen: boolean;
+    isLoading: boolean;
+}
+export interface FullSyncState {
+    sessionId: string | null;
+    events: ChatEvent[];
+    isOpen: boolean;
+    isLoading: boolean;
+    timestamp: number;
+}
+export interface TabCoordinatorOptions {
+    experienceId: string;
+    onSessionCreated?: (sessionId: string) => void;
+    onSessionCleared?: () => void;
+    onEventAdded?: (event: ChatEvent) => void;
+    onEventUpdated?: (eventId: string, updates: Partial<ChatEvent>) => void;
+    onStateChanged?: (state: TabSyncState) => void;
+    onFullSync?: (state: FullSyncState) => void;
+}
+export declare class TabCoordinator {
+    private experienceId;
+    private tabId;
+    private channel;
+    private options;
+    private isDestroyed;
+    private updateDebounceTimers;
+    private pendingUpdates;
+    private visibilityHandler;
+    private storageHandler;
+    constructor(options: TabCoordinatorOptions);
+    private initBroadcastChannel;
+    private initVisibilityListener;
+    private initStorageListener;
+    private handleMessage;
+    private broadcast;
+    private getStorageKey;
+    private getFromStorage;
+    private setInStorage;
+    private removeFromStorage;
+    notifySessionCreated(sessionId: string): void;
+    notifySessionCleared(): void;
+    notifyEventAdded(event: ChatEvent): void;
+    notifyEventUpdated(eventId: string, updates: Partial<ChatEvent>): void;
+    notifyStateChanged(state: TabSyncState): void;
+    reconcileFromStorage(): FullSyncState | null;
+    getStoredSessionId(): string | null;
+    getStoredEvents(): ChatEvent[];
+    updateCallbacks(callbacks: Omit<TabCoordinatorOptions, "experienceId">): void;
+    destroy(): void;
+}
+export declare function getTabCoordinator(experienceId: string, options?: Omit<TabCoordinatorOptions, "experienceId">): TabCoordinator;
+export declare function destroyTabCoordinator(experienceId: string): void;
+//# sourceMappingURL=tabCoordinator.d.ts.map

package/dist/types/services/tabCoordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabCoordinator.d.ts","sourceRoot":"","sources":["../../../src/services/tabCoordinator.ts"],"names":[],"mappings":"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"}

package/dist/types/store/chatStore.d.ts

@@ -0,0 +1,68 @@
+import type { FullSyncState, TabCoordinator, TabSyncState } from "../services/tabCoordinator";
+import type { ActionsConfig, ChatEvent, DisclaimerEvent } from "../types";
+import type { WidgetEventEmitter } from "../utils/eventEmitter";
+export declare function createChatStore(eventEmitter?: WidgetEventEmitter, tabCoordinator?: TabCoordinator): {
+    isOpen: import("@preact/signals").Signal<boolean>;
+    events: import("@preact/signals").Signal<ChatEvent[]>;
+    isLoading: import("@preact/signals").Signal<boolean>;
+    currentSessionId: import("@preact/signals").Signal<string | null>;
+    currentUserId: import("@preact/signals").Signal<string | null>;
+    sessionStartTime: import("@preact/signals").Signal<Date | null>;
+    isExplicitSession: import("@preact/signals").Signal<boolean>;
+    isExplicitUser: import("@preact/signals").Signal<boolean>;
+    inputValue: import("@preact/signals").Signal<string>;
+    hasMessages: import("@preact/signals").ReadonlySignal<boolean>;
+    isTTSEnabled: import("@preact/signals").Signal<boolean>;
+    isTTSAvailable: import("@preact/signals").Signal<boolean>;
+    isTTSSpeaking: import("@preact/signals").Signal<boolean>;
+    spokenMessageIds: import("@preact/signals").Signal<Set<string>>;
+    windowSizeMode: import("@preact/signals").Signal<string>;
+    toggleChat: () => void;
+    openChat: () => void;
+    closeChat: () => void;
+    addEvent: (event: Omit<ChatEvent, "id" | "timestamp"> & {
+        timestamp?: Date;
+    }) => ChatEvent;
+    updateEvent: (id: string, updates: Partial<ChatEvent>) => void;
+    clearEvents: () => void;
+    createPersistentWelcomeEvent: (welcomeMessage: string, displayMode?: "static" | "bubble", welcomeActions?: ActionsConfig) => {
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        kind: "message";
+        timestamp: Date;
+        role: "assistant";
+        content: string;
+        format: "markdown";
+        metadata: {
+            isPersistentWelcome: boolean;
+            isWelcomeBubble: boolean;
+            actions: ActionsConfig | undefined;
+            actionStates: import("../types").ActionState[] | undefined;
+        };
+    };
+    createPersistentDisclaimerEvent: (content: string, contentFormat?: "markdown" | "html" | "text", requiresAcceptance?: boolean, acceptButtonText?: string, accepted?: boolean, acceptedAt?: string) => DisclaimerEvent;
+    acceptDisclaimer: () => void;
+    isDisclaimerEventAccepted: () => boolean;
+    setSessionId: (id: string | null, explicit?: boolean) => void;
+    setInputValue: (value: string) => void;
+    clearInput: () => void;
+    initializeEvents: (initialEvents?: ChatEvent[]) => void;
+    resetChat: () => void;
+    startNewSession: (sessionId?: string, message?: string) => string;
+    toggleTTS: () => void;
+    setTTSEnabled: (enabled: boolean) => void;
+    setTTSAvailable: (available: boolean) => void;
+    setTTSSpeaking: (speaking: boolean) => void;
+    markMessageAsSpoken: (messageId: string) => void;
+    isMessageSpoken: (messageId: string) => boolean;
+    setWindowSizeMode: (mode: string) => void;
+    cycleWindowSize: (modes?: string[]) => void;
+    setLoading: (loading: boolean) => void;
+    applyRemoteSessionCreated: (sessionId: string) => void;
+    applyRemoteSessionCleared: () => void;
+    applyRemoteEventAdded: (event: ChatEvent) => void;
+    applyRemoteEventUpdated: (eventId: string, updates: Partial<ChatEvent>) => void;
+    applyRemoteStateChanged: (state: TabSyncState) => void;
+    applyFullSync: (syncState: FullSyncState) => void;
+};
+export type ChatStore = ReturnType<typeof createChatStore>;
+//# sourceMappingURL=chatStore.d.ts.map

package/dist/types/store/chatStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatStore.d.ts","sourceRoot":"","sources":["../../../src/store/chatStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACb,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,eAAe,EAEhB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAKhE,wBAAgB,eAAe,CAC7B,YAAY,CAAC,EAAE,kBAAkB,EACjC,cAAc,CAAC,EAAE,cAAc;;;;;;;;;;;;;;;;;;;sBA4GtB,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,IAAI,CAAA;KAAE;sBAiB1C,MAAM,WAAW,OAAO,CAAC,SAAS,CAAC;;mDA8C1C,MAAM,gBACR,QAAQ,GAAG,QAAQ,mBAChB,aAAa;;;;;;;;;;;;;;+CA0BrB,MAAM,kBACA,UAAU,GAAG,MAAM,GAAG,MAAM,uBACvB,OAAO,qBACR,MAAM,aACf,OAAO,eACJ,MAAM,KAClB,eAAe;;qCAuCoB,OAAO;uBAgBnB,MAAM,GAAG,IAAI,aAAY,OAAO;2BAkB5B,MAAM;;uCA4CM,SAAS,EAAE;;kCA0FhB,MAAM,YAAY,MAAM;;6BAoH7B,OAAO;iCAIH,OAAO;+BAIT,OAAO;qCAID,MAAM;iCAKV,MAAM,KAAG,OAAO;8BAKnB,MAAM;8BA0EN,MAAM,EAAE;0BAUZ,OAAO;2CAOU,MAAM;;mCA6Cd,SAAS;uCAcpC,MAAM,WACN,OAAO,CAAC,SAAS,CAAC;qCAYW,YAAY;+BAUlB,aAAa;EA4GhD;AAGD,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/types/types/exports.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public type exports for @knowbl_ai/nexus-chat package
+ * This file is used to generate the TypeScript declarations
+ */
+export type { ActionConfig, ActionType, ActionsConfig, AgentHandoverEvent, ChatEvent, ChatSession, InterceptorAssistantMessage, InterceptorMessage, MessageEvent, MessageInterceptor, MessageInterceptorContext, MessageInterceptorResult, SessionEndEvent, SessionStartEvent, SpeechSynthesisConfig, SystemEvent, TTSConfig, TypingEvent, VoiceConfig, WidgetAPI, WidgetConfig, } from "./index";
+//# sourceMappingURL=exports.d.ts.map

package/dist/types/types/exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.d.ts","sourceRoot":"","sources":["../../../src/types/exports.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAEV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,kBAAkB,EAElB,SAAS,EAET,WAAW,EACX,2BAA2B,EAC3B,kBAAkB,EAClB,YAAY,EAEZ,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EAEjB,qBAAqB,EACrB,WAAW,EACX,SAAS,EACT,WAAW,EACX,WAAW,EACX,SAAS,EAET,YAAY,GACb,MAAM,SAAS,CAAC"}