@useknest/widget-core 0.1.0-beta.8 → 0.1.0

package/dist/persistence.d.ts

@@ -0,0 +1,27 @@
+import { Message } from './types';
+export interface PersistedChatState {
+    threadId: string | undefined;
+    messages: Message[];
+    input: string;
+    savedAt: number;
+}
+/**
+ * Loads persisted chat state from localStorage.
+ * Returns null if missing, expired, or corrupt — callers should fall back to a fresh state.
+ */
+export declare function loadChatState(publishableApiKey: string): PersistedChatState | null;
+/**
+ * Writes chat state to localStorage immediately.
+ */
+export declare function saveChatState(publishableApiKey: string, state: PersistedChatState): void;
+/**
+ * Debounced variant of saveChatState (300ms trailing).
+ * Use during streaming to avoid excessive writes on every onContent callback.
+ */
+export declare function saveChatStateDebounced(publishableApiKey: string, state: PersistedChatState): void;
+/**
+ * Removes persisted state and cancels any pending debounced save.
+ * Call when the user explicitly resets the chat.
+ */
+export declare function clearChatState(publishableApiKey: string): void;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAOvC,MAAM,WAAW,kBAAkB;IAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AASD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,iBAAiB,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAgBlF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,iBAAiB,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAMxF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,iBAAiB,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAUjG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAW9D"}

package/dist/realtime.d.ts

@@ -0,0 +1,24 @@
+export interface BroadcastMessage {
+    id: string;
+    thread_id: string;
+    role: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+export interface PresenceOptions {
+    role: 'visitor' | 'agent';
+    onPresenceChange: (isOtherOnline: boolean) => void;
+}
+/**
+ * Subscribes to broadcast messages on a thread channel.
+ * Optionally co-tracks presence on the same channel to show online indicators.
+ *
+ * Presence is fully best-effort: `track()` is fire-and-forget, the sync handler is
+ * guarded with try/catch, and the subscribe callback is kept synchronous so that no
+ * presence error can ever disrupt broadcast delivery.
+ *
+ * @returns Cleanup function — call on component destroy.
+ */
+export declare function subscribeToThread(threadId: string, onMessage: (message: BroadcastMessage) => void, presence?: PresenceOptions): () => void;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IAC1B,gBAAgB,EAAE,CAAC,aAAa,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,EAC9C,QAAQ,CAAC,EAAE,eAAe,GACxB,MAAM,IAAI,CAwCZ"}

package/dist/scroll-lock.d.ts

@@ -0,0 +1,4 @@
+export declare const MOBILE_BREAKPOINT_PX = 440;
+export declare function lockBodyScroll(): void;
+export declare function unlockBodyScroll(): void;
+//# sourceMappingURL=scroll-lock.d.ts.map

package/dist/scroll-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-lock.d.ts","sourceRoot":"","sources":["../src/scroll-lock.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,wBAAgB,cAAc,SAE7B;AAED,wBAAgB,gBAAgB,SAE/B"}

package/dist/streaming.d.ts

@@ -1,8 +1,11 @@
-import { Source } from './types';
+import { Source, WidgetUser } from './types';
 export interface StreamCallbacks {
     onInit?: (threadId: string) => void;
     onContent: (content: string) => void;
     onComplete?: (sources: Source[]) => void;
+    onDone?: (info: {
+        humanTakeover?: boolean;
+    }) => void;
     onError: (error: string) => void;
 }
 export interface StreamMessageOptions {
@@ -12,6 +15,10 @@ export interface StreamMessageOptions {
     callbacks: StreamCallbacks;
     /** Base URL for the API. Defaults to https://useknest.com. Pass empty string for relative paths. */
     baseUrl?: string;
+    /** Optional metadata to attach to the message (e.g. attachment info). */
+    metadata?: Record<string, unknown>;
+    /** Identifies the logged-in user on the customer's platform. Requires at least id or email. */
+    user?: WidgetUser;
 }
 /**
  * Sends a chat message and streams the response via SSE.

package/dist/streaming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAsB,MAAM,EAAY,MAAM,SAAS,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC/B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACzC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,eAAe,CAAC;IAC3B,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoGpF"}
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAsB,MAAM,EAAY,UAAU,EAAE,MAAM,SAAS,CAAC;AAEhF,MAAM,WAAW,eAAe;IAC/B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACzC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACrD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,eAAe,CAAC;IAC3B,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,+FAA+F;IAC/F,IAAI,CAAC,EAAE,UAAU,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyHpF"}

package/dist/types.d.ts

@@ -3,7 +3,7 @@
  * These align with the database schema and API contracts.
  */
 export type WidgetMode = 'inline' | 'bubble';
-export type MessageRole = 'user' | 'assistant' | 'system';
+export type MessageRole = 'user' | 'assistant' | 'system' | 'human';
 export interface Source {
     url: string;
     title: string;
@@ -11,21 +11,42 @@ export interface Source {
     snippet: string;
     score?: number;
 }
+export interface Attachment {
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+    storagePath: string;
+    url?: string;
+}
 export interface Message {
     id?: string;
     role: MessageRole;
     content: string;
     sources?: Source[];
+    attachments?: Attachment[];
     hasRagContext?: boolean;
     createdAt?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Identifies the logged-in user on the customer's platform.
+ * At least `id` or `email` must be provided; the backend enforces this via Zod refine.
+ */
+export interface WidgetUser {
+    /** External ID from the customer's system — used as the cross-device dedup key. */
+    id?: string;
+    email?: string;
+    fullName?: string;
+    /** Custom attributes (e.g. plan, company). Full-replace semantics per message. */
+    metadata?: Record<string, unknown>;
+}
 export interface ChatMessageRequest {
     threadId?: string;
     content: string;
     email?: string;
     fullName?: string;
     metadata?: Record<string, unknown>;
+    user?: WidgetUser;
 }
 export interface ChatMessageResponse {
     messageId: string;
@@ -47,10 +68,11 @@ export interface WidgetConfig {
     updatedAt: string;
 }
 export interface SSEEvent {
-    type: 'init' | 'content' | 'complete' | 'error';
+    type: 'init' | 'content' | 'complete' | 'error' | 'done' | 'status';
     threadId?: string;
     content?: string;
     sources?: Source[];
     error?: string;
+    humanTakeover?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,MAAM;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE,MAAM,WAAW,MAAM;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,OAAO;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,mFAAmF;IACnF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB"}

package/dist/utils.d.ts

@@ -4,4 +4,6 @@
  * Code blocks are syntax-highlighted using Prism.js.
  */
 export declare function formatContent(content: string): string;
+/** Formats a byte count as a human-readable string (B / KB / MB). */
+export declare function formatFileSize(bytes: number): string;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA,OAAO,iCAAiC,CAAC;AACzC,OAAO,qCAAqC,CAAC;AAC7C,OAAO,+BAA+B,CAAC;AACvC,OAAO,+BAA+B,CAAC;AACvC,OAAO,8BAA8B,CAAC;AACtC,OAAO,iCAAiC,CAAC;AACzC,OAAO,8BAA8B,CAAC;AAmCtC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA,OAAO,iCAAiC,CAAC;AACzC,OAAO,qCAAqC,CAAC;AAC7C,OAAO,+BAA+B,CAAC;AACvC,OAAO,+BAA+B,CAAC;AACvC,OAAO,8BAA8B,CAAC;AACtC,OAAO,iCAAiC,CAAC;AACzC,OAAO,8BAA8B,CAAC;AAmCtC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useknest/widget-core",
-  "version": "0.1.0-beta.8",
+  "version": "0.1.0",
   "type": "module",
   "description": "Core business logic for Knest chat widget",
   "files": [