@aigentyc/chat-sdk 0.1.0

package/dist/core.d.ts

@@ -0,0 +1,455 @@
+import { a as ChatConfig } from './types-DKJ_-nbG.js';
+export { b as ChatEventCallbacks, c as ChatMessage, C as ChatProviderProps, d as ComponentAction, L as Language, e as LiveChatMessage, f as LiveChatState, Q as QuestionConfig, S as SlotMap, i as SlotProps, T as ThemeConfig, g as ToolRendererProps, h as ToolResult } from './types-DKJ_-nbG.js';
+import { ClassValue } from 'clsx';
+import * as ai from 'ai';
+export { I as InteractionMetadata, a as InteractionType, T as TrackInteractionParams, U as UseInteractionTrackerOptions, g as generateSessionId, u as useInteractionTracker } from './interaction-tracker-D9P1Oq4j.js';
+import 'react';
+
+/**
+ * Merge Tailwind CSS class names with conflict resolution.
+ *
+ * Combines `clsx` (conditional classes) with `tailwind-merge` (deduplication).
+ *
+ * @example
+ * cn("px-2 py-1", condition && "bg-red-500", "px-4")
+ * // → "py-1 px-4 bg-red-500"  (px-2 is overridden by px-4)
+ */
+declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Append UTM parameters to a URL for analytics tracking.
+ *
+ * If the URL is malformed, it is returned unchanged.
+ *
+ * @param url - The target URL
+ * @returns The URL with `utm_source=chat` and `utm_medium=referral` appended
+ */
+declare function addUtmParams(url: string): string;
+/**
+ * Returns `true` when running in a server-side rendering context
+ * (i.e. `window` is not available).
+ */
+declare function isSsr(): boolean;
+
+/** Shape of a single persisted message. */
+interface StoredMessage {
+    /** Message identifier */
+    id: string;
+    /** Role: user / assistant / system */
+    role: string;
+    /** Structured parts array (text, tool calls, etc.) */
+    parts: unknown[];
+    /** ISO-8601 creation timestamp */
+    createdAt?: string;
+}
+/**
+ * Load persisted messages for a session.
+ *
+ * Returns an empty array when nothing is stored, the data is expired
+ * or corrupted, or when running on the server.
+ *
+ * @param projectId - Aigentyc project ID
+ * @param sessionId - Current chat session ID
+ */
+declare function loadMessages(projectId: string, sessionId: string): StoredMessage[];
+/**
+ * Save messages to localStorage.
+ *
+ * Trims to the last 20 messages if the serialized payload exceeds
+ * `MAX_SIZE_BYTES`.
+ *
+ * @param projectId - Aigentyc project ID
+ * @param sessionId - Current chat session ID
+ * @param messages  - Messages to persist
+ */
+declare function saveMessages(projectId: string, sessionId: string, messages: StoredMessage[]): void;
+/**
+ * Clear stored messages for a session.
+ *
+ * @param projectId - Aigentyc project ID
+ * @param sessionId - Current chat session ID
+ */
+declare function clearMessages(projectId: string, sessionId: string): void;
+/**
+ * Prune all expired message entries from localStorage.
+ *
+ * Call once on widget / provider initialisation to prevent stale data
+ * from accumulating.
+ */
+declare function pruneExpiredMessages(): void;
+/**
+ * Debounced save — call on every `messages` change.
+ *
+ * Coalesces rapid updates (e.g. during streaming) into a single write.
+ *
+ * @param projectId - Aigentyc project ID
+ * @param sessionId - Current chat session ID
+ * @param messages  - Current messages array
+ * @param delay     - Debounce delay in ms (default `500`)
+ */
+declare function debouncedSaveMessages(projectId: string, sessionId: string, messages: StoredMessage[], delay?: number): void;
+
+/**
+ * Options for creating a chat transport instance.
+ */
+interface CreateChatTransportOptions {
+    /** Maximum number of messages to include in a single request (default `20`) */
+    maxMessages?: number;
+    /** Current session identifier */
+    sessionId?: string;
+    /** Pre-set user type / persona key */
+    userType?: string;
+    /** Current page URL (for contextual answers) */
+    pageUrl?: string;
+    /** Current page title */
+    pageTitle?: string;
+    /** Signed WP user identity token */
+    wpUserToken?: string;
+    /**
+     * Mutable ref-like getter for the analytics message ID.
+     * Called inside `prepareSendMessagesRequest` to read the latest value.
+     */
+    getAnalyticsMessageId?: () => string | null;
+    /**
+     * Mutable ref-like getter for the current user type.
+     * Called inside `prepareSendMessagesRequest` to read the latest value.
+     */
+    getUserType?: () => string | null;
+    /**
+     * Mutable ref-like getter for the current session ID.
+     * Called inside `prepareSendMessagesRequest` in case it changes at runtime.
+     */
+    getSessionId?: () => string;
+}
+/**
+ * Minify a tool output before sending it back to the LLM.
+ *
+ * Display tools use `_displayData` for the UI — the LLM only needs the
+ * summary / context portion. Large outputs are truncated.
+ *
+ * @internal
+ */
+declare function minifyToolOutput(output: unknown): unknown;
+/**
+ * Prune and minify a messages array for sending to the API.
+ *
+ * 1. Keeps the first message (system / context) and the last `maxMessages - 1`.
+ * 2. Deep-clones messages so the local UI state is not mutated.
+ * 3. Strips large tool outputs via `minifyToolOutput`.
+ *
+ * @internal
+ */
+declare function prepareMessages(messages: any[], maxMessages: number): any[];
+/**
+ * Create a configured `DefaultChatTransport` instance from the AI SDK.
+ *
+ * The transport handles authentication, message pruning, tool-output
+ * minification, and attaches project / session metadata to every request.
+ *
+ * Uses a dynamic `import("ai")` so that `ai` stays an optional peer
+ * dependency — the import is only resolved at call time.
+ *
+ * @param config  - Chat backend configuration
+ * @param options - Transport options
+ * @returns A `DefaultChatTransport` instance ready for `useChat()`
+ *
+ * @example
+ * ```ts
+ * const transport = await createChatTransport(
+ *   { projectId: "abc", apiEndpoint: "https://api.example.com", apiKey: "key" },
+ *   { maxMessages: 20, getSessionId: () => sessionIdRef.current },
+ * );
+ * const { messages } = useChat({ transport });
+ * ```
+ */
+declare function createChatTransport(config: ChatConfig, options?: CreateChatTransportOptions): Promise<ai.DefaultChatTransport<ai.UIMessage<unknown, ai.UIDataTypes, ai.UITools>>>;
+/**
+ * Synchronous variant of `createChatTransport` for use when `ai`
+ * is already bundled (i.e. not dynamically imported).
+ *
+ * Requires the caller to pass in the `DefaultChatTransport` constructor.
+ *
+ * @param DefaultChatTransport - The `DefaultChatTransport` class from `"ai"`
+ * @param config  - Chat backend configuration
+ * @param options - Transport options
+ * @returns A configured `DefaultChatTransport` instance
+ */
+declare function createChatTransportSync(DefaultChatTransport: any, config: ChatConfig, options?: CreateChatTransportOptions): any;
+
+/**
+ * Live Chat Transport
+ *
+ * Socket.IO client for real-time communication with human operators.
+ * Lazy-loaded only when live chat is triggered to avoid bundling
+ * `socket.io-client` for AI-only use cases.
+ *
+ * All browser API access is guarded against SSR.
+ */
+/**
+ * State machine for live-chat sessions.
+ *
+ * @see {@link LiveChatTransport.getState}
+ */
+type LiveChatState = "ai" | "requesting" | "queued" | "live" | "ended";
+/**
+ * Configuration required to establish a live-chat connection.
+ */
+interface LiveChatConfig {
+    /** Socket.IO endpoint URL */
+    chatServiceUrl: string;
+    /** Bearer API key */
+    apiKey: string;
+    /** Aigentyc project ID */
+    projectId: string;
+    /** Visitor session identifier (matches the AI chat session) */
+    visitorSessionId: string;
+}
+/**
+ * A single message exchanged during a live-chat session.
+ */
+interface LiveChatMessage {
+    /** Server-assigned message ID */
+    id: number;
+    /** Message body (plain text or HTML) */
+    content: string;
+    /** Who sent the message */
+    senderType: "visitor" | "operator" | "system";
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    /** Optional system-message sub-type */
+    systemMessageType?: string;
+}
+/**
+ * Typed event map for live-chat transport listeners.
+ */
+type LiveChatEventMap = {
+    /** Fired when the state machine transitions */
+    "state-change": (state: LiveChatState) => void;
+    /** Fired when the request is queued */
+    queued: (data: {
+        liveChatSessionId: string;
+        position: number;
+    }) => void;
+    /** Fired when the queue position updates */
+    "queue-update": (data: {
+        position: number;
+    }) => void;
+    /** Fired when an operator accepts the chat */
+    accepted: (data: {
+        operatorName: string;
+    }) => void;
+    /** Fired on every incoming message */
+    message: (data: LiveChatMessage) => void;
+    /** Fired when the live-chat session ends */
+    ended: (data: {
+        endedBy: string;
+    }) => void;
+    /** Fired when the operator hands the visitor back to AI */
+    "handback-ai": () => void;
+    /** System-level notification */
+    system: (data: {
+        message: string;
+        type: string;
+    }) => void;
+    /** Error notification */
+    error: (data: {
+        code: string;
+        message: string;
+    }) => void;
+    /** Operator typing indicator */
+    typing: (data: {
+        isTyping: boolean;
+    }) => void;
+    /** Successful session rejoin (after page refresh) */
+    "rejoin-success": (data: {
+        state: string;
+        operatorName?: string;
+        position?: number;
+        messages: LiveChatMessage[];
+    }) => void;
+    /** Failed session rejoin */
+    "rejoin-failed": (data: {
+        reason: string;
+    }) => void;
+};
+/**
+ * Manages the Socket.IO connection for live-chat sessions.
+ *
+ * Lazily imports `socket.io-client` on first `connect()` call so the
+ * dependency is never loaded for AI-only deployments.
+ *
+ * @example
+ * ```ts
+ * const transport = new LiveChatTransport({
+ *   chatServiceUrl: "https://api.example.com",
+ *   apiKey: "key",
+ *   projectId: "abc",
+ *   visitorSessionId: "sess-123",
+ * });
+ *
+ * transport.on("message", (msg) => console.log(msg));
+ * await transport.connect();
+ * transport.requestHandoff({ aiChatHistory: messages });
+ * ```
+ */
+declare class LiveChatTransport {
+    private socket;
+    private config;
+    private state;
+    private liveChatSessionId;
+    private listeners;
+    constructor(config: LiveChatConfig);
+    /**
+     * Establish the Socket.IO connection and wire up all server events.
+     *
+     * Safe to call in SSR — will resolve immediately without connecting.
+     */
+    connect(): Promise<void>;
+    /**
+     * Request a handoff from AI to a human operator.
+     *
+     * @param params - Visitor info and AI conversation history
+     */
+    requestHandoff(params: {
+        visitorName?: string;
+        visitorEmail?: string;
+        aiChatHistory: unknown[];
+    }): void;
+    /**
+     * Send a message to the operator.
+     *
+     * @param content - Message text
+     */
+    sendMessage(content: string): void;
+    /**
+     * Send a typing indicator to the operator.
+     *
+     * @param isTyping - `true` if the visitor is currently typing
+     */
+    sendTyping(isTyping: boolean): void;
+    /**
+     * Cancel a pending handoff request.
+     *
+     * @param liveChatSessionId - The session to cancel
+     */
+    cancelRequest(liveChatSessionId: string): void;
+    /**
+     * End the current live-chat session.
+     */
+    endChat(): void;
+    /**
+     * Submit a satisfaction rating for the ended session.
+     *
+     * @param rating  - `"positive"` or `"negative"`
+     * @param comment - Optional free-text feedback
+     */
+    submitRating(rating: "positive" | "negative", comment?: string): void;
+    /**
+     * Rejoin an existing session (e.g. after a page refresh).
+     *
+     * @param liveChatSessionId - The session to rejoin
+     */
+    rejoinSession(liveChatSessionId: string): void;
+    /**
+     * Disconnect the socket and reset state.
+     */
+    disconnect(): void;
+    /**
+     * Get the current live-chat state.
+     */
+    getState(): LiveChatState;
+    /**
+     * Get the current live-chat session ID (if any).
+     */
+    getSessionId(): string | null;
+    private setState;
+    /**
+     * Subscribe to a live-chat event.
+     *
+     * @param event   - Event name
+     * @param handler - Callback
+     */
+    on<K extends keyof LiveChatEventMap>(event: K, handler: LiveChatEventMap[K]): void;
+    /**
+     * Unsubscribe from a live-chat event.
+     *
+     * @param event   - Event name
+     * @param handler - The same callback reference passed to `on()`
+     */
+    off<K extends keyof LiveChatEventMap>(event: K, handler: LiveChatEventMap[K]): void;
+    private emit;
+}
+
+/**
+ * Process `<img>` tags in an HTML string:
+ *
+ * - Detect and optionally replace oversized base64 images with SVG placeholders.
+ * - Add `loading="lazy"` to every image that does not already have it.
+ *
+ * All DOM / `btoa` calls are guarded against SSR — when `window` is
+ * unavailable the function returns the input unchanged.
+ *
+ * @param html    - Raw HTML string to process
+ * @param options - Processing options
+ * @returns The processed HTML string
+ */
+declare function processImagesInHtml(html: string, options?: {
+    /** Replace base64 images exceeding the size limit with placeholders (default `true`) */
+    replaceLargeBase64?: boolean;
+    /** Size limit in bytes for base64 images (default 100 KB) */
+    maxBase64Size?: number;
+    /** Add `loading="lazy"` to images (default `true`) */
+    addLazyLoading?: boolean;
+}): string;
+
+/**
+ * User type constants and helpers.
+ *
+ * Defines the available visitor personas that the `AgentDetection` tool
+ * can assign. These are generic defaults — consumers can extend them via
+ * configuration.
+ */
+/**
+ * A visitor persona / user type definition.
+ */
+interface UserType {
+    /** Machine-readable identifier (e.g. `"Guest"`) */
+    id: string;
+    /** Human-readable label */
+    label: string;
+    /** Short description of this persona */
+    description: string;
+    /**
+     * Icon identifier.
+     *
+     * In the SDK this is a string key (e.g. `"User"`, `"Shield"`, `"Zap"`)
+     * rather than a Lucide component to avoid coupling core logic to a
+     * specific icon library.
+     */
+    icon: string;
+}
+/**
+ * Default user types available for the `AgentDetection` tool.
+ */
+declare const USER_TYPES: UserType[];
+/**
+ * Map from display label to user-type ID.
+ *
+ * Used to normalise user-type strings that come from the AI
+ * (which may use the label rather than the ID).
+ */
+declare const USER_TYPE_LABEL_MAP: Record<string, string>;
+/**
+ * Prefix for internal / hidden messages.
+ *
+ * Messages starting with this string are never rendered in the UI.
+ */
+declare const INTERNAL_MESSAGE_PREFIX = "[internal]";
+/**
+ * Check whether a message should be hidden from the UI.
+ *
+ * @param text - The raw message text
+ * @returns `true` if the message is internal
+ */
+declare function isInternalMessage(text: string): boolean;
+
+export { ChatConfig, type CreateChatTransportOptions, INTERNAL_MESSAGE_PREFIX, type LiveChatConfig, type LiveChatEventMap, LiveChatTransport, type StoredMessage, USER_TYPES, USER_TYPE_LABEL_MAP, type UserType, addUtmParams, clearMessages, cn, createChatTransport, createChatTransportSync, debouncedSaveMessages, isInternalMessage, isSsr, loadMessages, minifyToolOutput, prepareMessages, processImagesInHtml, pruneExpiredMessages, saveMessages };

package/dist/core.js

@@ -0,0 +1,241 @@
+"use client";
+export { generateSessionId, useInteractionTracker } from './chunk-MT2AMINB.js';
+export { LiveChatTransport } from './chunk-BKDV2H6Z.js';
+export { processImagesInHtml } from './chunk-PS3U7T37.js';
+export { addUtmParams, cn, isSsr } from './chunk-3RW7O444.js';
+
+// src/core/message-store.ts
+var STORAGE_PREFIX = "chat-messages-";
+var MAX_SIZE_BYTES = 200 * 1024;
+var MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+function getKey(projectId, sessionId) {
+  return `${STORAGE_PREFIX}${projectId}-${sessionId}`;
+}
+function loadMessages(projectId, sessionId) {
+  if (typeof window === "undefined") return [];
+  try {
+    const raw = localStorage.getItem(getKey(projectId, sessionId));
+    if (!raw) return [];
+    const data = JSON.parse(raw);
+    if (Date.now() - data.timestamp > MAX_AGE_MS) {
+      localStorage.removeItem(getKey(projectId, sessionId));
+      return [];
+    }
+    return data.messages || [];
+  } catch {
+    return [];
+  }
+}
+function saveMessages(projectId, sessionId, messages) {
+  if (typeof window === "undefined") return;
+  try {
+    let toStore = messages;
+    const data = { messages: toStore, timestamp: Date.now() };
+    let serialized = JSON.stringify(data);
+    if (serialized.length > MAX_SIZE_BYTES && toStore.length > 20) {
+      toStore = toStore.slice(-20);
+      data.messages = toStore;
+      serialized = JSON.stringify(data);
+    }
+    localStorage.setItem(getKey(projectId, sessionId), serialized);
+  } catch {
+  }
+}
+function clearMessages(projectId, sessionId) {
+  if (typeof window === "undefined") return;
+  try {
+    localStorage.removeItem(getKey(projectId, sessionId));
+  } catch {
+  }
+}
+function pruneExpiredMessages() {
+  if (typeof window === "undefined") return;
+  try {
+    const keysToRemove = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (!key?.startsWith(STORAGE_PREFIX)) continue;
+      try {
+        const raw = localStorage.getItem(key);
+        if (!raw) continue;
+        const data = JSON.parse(raw);
+        if (Date.now() - data.timestamp > MAX_AGE_MS) {
+          keysToRemove.push(key);
+        }
+      } catch {
+        keysToRemove.push(key);
+      }
+    }
+    for (const key of keysToRemove) {
+      localStorage.removeItem(key);
+    }
+  } catch {
+  }
+}
+var saveTimeout = null;
+function debouncedSaveMessages(projectId, sessionId, messages, delay = 500) {
+  if (typeof window === "undefined") return;
+  if (saveTimeout) clearTimeout(saveTimeout);
+  saveTimeout = setTimeout(() => {
+    saveMessages(projectId, sessionId, messages);
+  }, delay);
+}
+
+// src/core/transport.ts
+function minifyToolOutput(output) {
+  if (!output || typeof output !== "object") return output;
+  const obj = output;
+  if ("_displayData" in obj) {
+    const { _displayData: _, ...contextData } = obj;
+    return contextData;
+  }
+  if ("sources" in obj && Array.isArray(obj.sources)) {
+    return { _searched: true, totalResults: obj.totalResults };
+  }
+  const outputStr = JSON.stringify(obj);
+  if (outputStr.length > 1500) {
+    const summary = { _truncated: true };
+    if (Array.isArray(obj)) {
+      summary.itemCount = obj.length;
+    } else {
+      for (const [k, v] of Object.entries(obj)) {
+        if (typeof v === "string" && v.length < 100) summary[k] = v;
+        else if (typeof v === "number" || typeof v === "boolean") summary[k] = v;
+      }
+    }
+    return summary;
+  }
+  return output;
+}
+function prepareMessages(messages, maxMessages) {
+  let pruned = messages;
+  if (messages.length > maxMessages) {
+    pruned = [messages[0], ...messages.slice(-(maxMessages - 1))];
+  }
+  const cloned = JSON.parse(JSON.stringify(pruned));
+  for (const msg of cloned) {
+    if (msg.role === "assistant" && msg.parts) {
+      for (const part of msg.parts) {
+        if (part.type?.startsWith("tool-") && part.output !== void 0) {
+          part.output = minifyToolOutput(part.output);
+        }
+      }
+    }
+  }
+  return cloned;
+}
+async function createChatTransport(config, options = {}) {
+  const { DefaultChatTransport } = await import('ai');
+  const {
+    maxMessages = 20,
+    pageUrl,
+    pageTitle,
+    wpUserToken,
+    getAnalyticsMessageId,
+    getUserType,
+    getSessionId
+  } = options;
+  return new DefaultChatTransport({
+    api: `${config.apiEndpoint}/api/kb/chat`,
+    headers: () => {
+      const headers = {};
+      if (config.apiKey) {
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+      }
+      return headers;
+    },
+    credentials: "include",
+    prepareSendMessagesRequest: ({ id, messages, trigger }) => {
+      const prepared = prepareMessages(messages, maxMessages);
+      return {
+        body: {
+          id,
+          messages: prepared,
+          trigger,
+          projectId: config.projectId,
+          sessionId: getSessionId?.() ?? options.sessionId,
+          analyticsMessageId: getAnalyticsMessageId?.() ?? null,
+          userType: getUserType?.() ?? options.userType ?? void 0,
+          pageUrl,
+          pageTitle,
+          ...wpUserToken ? { wpUserToken } : {}
+        }
+      };
+    }
+  });
+}
+function createChatTransportSync(DefaultChatTransport, config, options = {}) {
+  const {
+    maxMessages = 20,
+    pageUrl,
+    pageTitle,
+    wpUserToken,
+    getAnalyticsMessageId,
+    getUserType,
+    getSessionId
+  } = options;
+  return new DefaultChatTransport({
+    api: `${config.apiEndpoint}/api/kb/chat`,
+    headers: () => {
+      const headers = {};
+      if (config.apiKey) {
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+      }
+      return headers;
+    },
+    credentials: "include",
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    prepareSendMessagesRequest: ({ id, messages, trigger }) => {
+      const prepared = prepareMessages(messages, maxMessages);
+      return {
+        body: {
+          id,
+          messages: prepared,
+          trigger,
+          projectId: config.projectId,
+          sessionId: getSessionId?.() ?? options.sessionId,
+          analyticsMessageId: getAnalyticsMessageId?.() ?? null,
+          userType: getUserType?.() ?? options.userType ?? void 0,
+          pageUrl,
+          pageTitle,
+          ...wpUserToken ? { wpUserToken } : {}
+        }
+      };
+    }
+  });
+}
+
+// src/core/constants/user-types.ts
+var USER_TYPES = [
+  {
+    id: "Guest",
+    label: "Guest",
+    description: "Just browsing",
+    icon: "User"
+  },
+  {
+    id: "Customer",
+    label: "Customer",
+    description: "Existing customer with questions",
+    icon: "Shield"
+  },
+  {
+    id: "Partner",
+    label: "Partner",
+    description: "Business partner or professional",
+    icon: "Zap"
+  }
+];
+var USER_TYPE_LABEL_MAP = {
+  Guest: "Guest",
+  Customer: "Customer",
+  Partner: "Partner"
+};
+var INTERNAL_MESSAGE_PREFIX = "[internal]";
+function isInternalMessage(text) {
+  return text.startsWith(INTERNAL_MESSAGE_PREFIX);
+}
+
+export { INTERNAL_MESSAGE_PREFIX, USER_TYPES, USER_TYPE_LABEL_MAP, clearMessages, createChatTransport, createChatTransportSync, debouncedSaveMessages, isInternalMessage, loadMessages, minifyToolOutput, prepareMessages, pruneExpiredMessages, saveMessages };
+//# sourceMappingURL=core.js.map
+//# sourceMappingURL=core.js.map