@informedai/react 0.2.6 → 0.4.0

package/dist/index.d.mts

@@ -11,6 +11,7 @@ interface Session {
     taskStates: Record<string, TaskState>;
     activeTask: string | null;
     aiConversations: Record<string, ChatMessage[]>;
+    status: 'active' | 'ended' | 'abandoned';
 }
 interface WidgetMessage {
     id: string;
@@ -76,7 +77,24 @@ interface InformedAssistantConfig {
     documentTypeId: string;
     /** API base URL (defaults to https://api.informedassistant.ai/api/v1) */
     apiUrl?: string;
-    /** Optional: Existing session ID to resume */
+    /**
+     * External ID for idempotency - your object's ID in your system.
+     * If provided, the widget will find or create a document linked to this ID.
+     * This allows resuming work on the same document across sessions.
+     */
+    externalId?: string;
+    /**
+     * Your current field values to sync before starting.
+     * Since you're the source of truth, this data will be written to our document.
+     * Use this to ensure the assistant sees your latest data.
+     */
+    initialData?: Record<string, unknown>;
+    /**
+     * Whether to persist sessions in localStorage for resumption.
+     * Defaults to true when externalId is provided, false otherwise.
+     */
+    persistSession?: boolean;
+    /** Optional: Existing session ID to resume (overrides localStorage) */
     sessionId?: string;
     /** Callback when widget is ready with document type schema */
     onReady?: (context: WidgetReadyContext) => void;
@@ -116,6 +134,20 @@ interface SSEEvent {
     session?: Session;
     error?: string;
 }
+/**
+ * Response from GET /widget/sessions/:id
+ * Includes the session with embedded document and documentType
+ */
+interface GetSessionResponse extends Session {
+    document: Document & {
+        documentType: {
+            id: string;
+            name: string;
+            displayName: string;
+            schema: DocumentTypeSchema;
+        };
+    };
+}
 interface UseSessionReturn {
     session: Session | null;
     isLoading: boolean;
@@ -156,6 +188,8 @@ interface InformedAIContextValue {
     sendQuickAction: (action: string, payload?: Record<string, unknown>) => Promise<void>;
     applyPendingValue: () => Promise<void>;
     skipTask: () => Promise<void>;
+    startNewSession: () => Promise<void>;
+    endSession: () => Promise<void>;
     clearError: () => void;
 }
 declare function useInformedAI(): InformedAIContextValue;
@@ -213,13 +247,19 @@ declare class InformedAIClient {
     private request;
     /**
      * Create a new session for a document type.
-     * This automatically creates a document with default values.
+     *
+     * @param documentTypeId - The document type to create a session for
+     * @param options.externalId - Your object's ID for idempotency (finds or creates document)
+     * @param options.initialData - Your current field values to sync (you're the source of truth)
      */
-    createSession(documentTypeId: string): Promise<CreateSessionResponse>;
+    createSession(documentTypeId: string, options?: {
+        externalId?: string;
+        initialData?: Record<string, unknown>;
+    }): Promise<CreateSessionResponse>;
     /**
-     * Get an existing session.
+     * Get an existing session with its document and documentType.
      */
-    getSession(id: string): Promise<Session>;
+    getSession(id: string): Promise<GetSessionResponse>;
     /**
      * Send a message to the session with SSE streaming.
      */
@@ -238,6 +278,26 @@ declare class InformedAIClient {
      * Skip the active task.
      */
     skipTask(sessionId: string): Promise<Session>;
+    /**
+     * Send a heartbeat to keep the session active.
+     * Call this every 30 seconds while the session is in use.
+     */
+    sendHeartbeat(sessionId: string): Promise<void>;
+    /**
+     * Resume an abandoned session with a new chatbot.
+     * Preserves conversation history.
+     */
+    resumeSession(sessionId: string): Promise<Session>;
+    /**
+     * Explicitly end a session and release resources.
+     * Conversation history is preserved but session cannot be resumed.
+     */
+    endSession(sessionId: string): Promise<void>;
+    /**
+     * Send end session via sendBeacon (for beforeunload).
+     * Returns true if sendBeacon was used, false if fetch fallback was attempted.
+     */
+    endSessionBeacon(sessionId: string): boolean;
     private processSSEStream;
 }
 

package/dist/index.d.ts

@@ -11,6 +11,7 @@ interface Session {
     taskStates: Record<string, TaskState>;
     activeTask: string | null;
     aiConversations: Record<string, ChatMessage[]>;
+    status: 'active' | 'ended' | 'abandoned';
 }
 interface WidgetMessage {
     id: string;
@@ -76,7 +77,24 @@ interface InformedAssistantConfig {
     documentTypeId: string;
     /** API base URL (defaults to https://api.informedassistant.ai/api/v1) */
     apiUrl?: string;
-    /** Optional: Existing session ID to resume */
+    /**
+     * External ID for idempotency - your object's ID in your system.
+     * If provided, the widget will find or create a document linked to this ID.
+     * This allows resuming work on the same document across sessions.
+     */
+    externalId?: string;
+    /**
+     * Your current field values to sync before starting.
+     * Since you're the source of truth, this data will be written to our document.
+     * Use this to ensure the assistant sees your latest data.
+     */
+    initialData?: Record<string, unknown>;
+    /**
+     * Whether to persist sessions in localStorage for resumption.
+     * Defaults to true when externalId is provided, false otherwise.
+     */
+    persistSession?: boolean;
+    /** Optional: Existing session ID to resume (overrides localStorage) */
     sessionId?: string;
     /** Callback when widget is ready with document type schema */
     onReady?: (context: WidgetReadyContext) => void;
@@ -116,6 +134,20 @@ interface SSEEvent {
     session?: Session;
     error?: string;
 }
+/**
+ * Response from GET /widget/sessions/:id
+ * Includes the session with embedded document and documentType
+ */
+interface GetSessionResponse extends Session {
+    document: Document & {
+        documentType: {
+            id: string;
+            name: string;
+            displayName: string;
+            schema: DocumentTypeSchema;
+        };
+    };
+}
 interface UseSessionReturn {
     session: Session | null;
     isLoading: boolean;
@@ -156,6 +188,8 @@ interface InformedAIContextValue {
     sendQuickAction: (action: string, payload?: Record<string, unknown>) => Promise<void>;
     applyPendingValue: () => Promise<void>;
     skipTask: () => Promise<void>;
+    startNewSession: () => Promise<void>;
+    endSession: () => Promise<void>;
     clearError: () => void;
 }
 declare function useInformedAI(): InformedAIContextValue;
@@ -213,13 +247,19 @@ declare class InformedAIClient {
     private request;
     /**
      * Create a new session for a document type.
-     * This automatically creates a document with default values.
+     *
+     * @param documentTypeId - The document type to create a session for
+     * @param options.externalId - Your object's ID for idempotency (finds or creates document)
+     * @param options.initialData - Your current field values to sync (you're the source of truth)
      */
-    createSession(documentTypeId: string): Promise<CreateSessionResponse>;
+    createSession(documentTypeId: string, options?: {
+        externalId?: string;
+        initialData?: Record<string, unknown>;
+    }): Promise<CreateSessionResponse>;
     /**
-     * Get an existing session.
+     * Get an existing session with its document and documentType.
      */
-    getSession(id: string): Promise<Session>;
+    getSession(id: string): Promise<GetSessionResponse>;
     /**
      * Send a message to the session with SSE streaming.
      */
@@ -238,6 +278,26 @@ declare class InformedAIClient {
      * Skip the active task.
      */
     skipTask(sessionId: string): Promise<Session>;
+    /**
+     * Send a heartbeat to keep the session active.
+     * Call this every 30 seconds while the session is in use.
+     */
+    sendHeartbeat(sessionId: string): Promise<void>;
+    /**
+     * Resume an abandoned session with a new chatbot.
+     * Preserves conversation history.
+     */
+    resumeSession(sessionId: string): Promise<Session>;
+    /**
+     * Explicitly end a session and release resources.
+     * Conversation history is preserved but session cannot be resumed.
+     */
+    endSession(sessionId: string): Promise<void>;
+    /**
+     * Send end session via sendBeacon (for beforeunload).
+     * Returns true if sendBeacon was used, false if fetch fallback was attempted.
+     */
+    endSessionBeacon(sessionId: string): boolean;
     private processSSEStream;
 }
 

package/dist/index.js

@@ -67,16 +67,23 @@ var InformedAIClient = class {
   // ========================================================================
   /**
    * Create a new session for a document type.
-   * This automatically creates a document with default values.
+   *
+   * @param documentTypeId - The document type to create a session for
+   * @param options.externalId - Your object's ID for idempotency (finds or creates document)
+   * @param options.initialData - Your current field values to sync (you're the source of truth)
    */
-  async createSession(documentTypeId) {
+  async createSession(documentTypeId, options) {
     return this.request("/widget/sessions", {
       method: "POST",
-      body: JSON.stringify({ documentTypeId })
+      body: JSON.stringify({
+        documentTypeId,
+        externalId: options?.externalId,
+        initialData: options?.initialData
+      })
     });
   }
   /**
-   * Get an existing session.
+   * Get an existing session with its document and documentType.
    */
   async getSession(id) {
     return this.request(`/widget/sessions/${id}`);
@@ -144,6 +151,51 @@ var InformedAIClient = class {
       method: "POST"
     });
   }
+  /**
+   * Send a heartbeat to keep the session active.
+   * Call this every 30 seconds while the session is in use.
+   */
+  async sendHeartbeat(sessionId) {
+    await this.request(`/widget/sessions/${sessionId}/heartbeat`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Resume an abandoned session with a new chatbot.
+   * Preserves conversation history.
+   */
+  async resumeSession(sessionId) {
+    return this.request(`/widget/sessions/${sessionId}/resume`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Explicitly end a session and release resources.
+   * Conversation history is preserved but session cannot be resumed.
+   */
+  async endSession(sessionId) {
+    await this.request(`/widget/sessions/${sessionId}/end`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Send end session via sendBeacon (for beforeunload).
+   * Returns true if sendBeacon was used, false if fetch fallback was attempted.
+   */
+  endSessionBeacon(sessionId) {
+    const url = `${this.apiUrl}/widget/sessions/${sessionId}/end`;
+    if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+      const blob = new Blob([JSON.stringify({})], { type: "application/json" });
+      return navigator.sendBeacon(url, blob);
+    }
+    fetch(url, {
+      method: "POST",
+      headers: this.getHeaders(),
+      keepalive: true
+    }).catch(() => {
+    });
+    return false;
+  }
   // ========================================================================
   // SSE Stream Processing
   // ========================================================================
@@ -186,6 +238,15 @@ var InformedAIClient = class {
 
 // src/context/InformedAIContext.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
+var getStorageKey = (documentTypeId, externalId) => `informedai_session_${documentTypeId}${externalId ? `_${externalId}` : ""}`;
+var HEARTBEAT_INTERVAL = 30 * 1e3;
+function isSessionNotFoundError(error) {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return message.includes("session not found") || message.includes("404") || message.includes("not found");
+  }
+  return false;
+}
 var InformedAIContext = (0, import_react.createContext)(null);
 function useInformedAI() {
   const context = (0, import_react.useContext)(InformedAIContext);
@@ -203,41 +264,140 @@ function InformedAIProvider({ config, children }) {
   const [error, setError] = (0, import_react.useState)(null);
   const [streamingContent, setStreamingContent] = (0, import_react.useState)("");
   const clientRef = (0, import_react.useRef)(null);
+  const initRef = (0, import_react.useRef)(false);
+  const heartbeatIntervalRef = (0, import_react.useRef)(null);
+  const sessionIdRef = (0, import_react.useRef)(null);
+  const shouldPersist = config.persistSession ?? !!config.externalId;
+  const storageKey = getStorageKey(config.documentTypeId, config.externalId);
   (0, import_react.useEffect)(() => {
     clientRef.current = new InformedAIClient(config.apiUrl);
   }, [config.apiUrl]);
+  const createNewSession = (0, import_react.useCallback)(async () => {
+    if (!clientRef.current) return null;
+    const result = await clientRef.current.createSession(
+      config.documentTypeId,
+      {
+        externalId: config.externalId,
+        initialData: config.initialData
+      }
+    );
+    const dt = {
+      id: result.documentType.id,
+      name: result.documentType.name,
+      displayName: result.documentType.displayName,
+      schema: result.documentType.schema,
+      workspaceId: "",
+      taskConfigs: {},
+      createdAt: "",
+      updatedAt: ""
+    };
+    if (shouldPersist && typeof window !== "undefined") {
+      try {
+        localStorage.setItem(storageKey, result.session.id);
+      } catch (e) {
+      }
+    }
+    return { session: result.session, document: result.document, documentType: dt };
+  }, [config.documentTypeId, config.externalId, config.initialData, shouldPersist, storageKey]);
+  const clearPersistedSession = (0, import_react.useCallback)(() => {
+    if (shouldPersist && typeof window !== "undefined") {
+      try {
+        localStorage.removeItem(storageKey);
+      } catch (e) {
+      }
+    }
+  }, [shouldPersist, storageKey]);
+  const handleSessionDeleted = (0, import_react.useCallback)(async () => {
+    console.warn("[InformedAI] Session was deleted, starting new session...");
+    clearPersistedSession();
+    if (heartbeatIntervalRef.current) {
+      clearInterval(heartbeatIntervalRef.current);
+      heartbeatIntervalRef.current = null;
+    }
+    sessionIdRef.current = null;
+    try {
+      const result = await createNewSession();
+      if (result) {
+        setSession(result.session);
+        setDocument(result.document);
+        setDocumentType(result.documentType);
+        setError(null);
+        config.onSessionChange?.(result.session);
+        config.onReady?.({
+          session: result.session,
+          document: result.document,
+          documentType: result.documentType
+        });
+        return true;
+      }
+    } catch (err) {
+      console.error("[InformedAI] Failed to create new session after deletion:", err);
+      const error2 = err instanceof Error ? err : new Error("Failed to recover session");
+      setError(error2);
+      config.onError?.(error2);
+    }
+    return false;
+  }, [createNewSession, clearPersistedSession, config]);
   (0, import_react.useEffect)(() => {
+    if (initRef.current) return;
+    initRef.current = true;
     async function initialize() {
       if (!clientRef.current) return;
       try {
         setIsLoading(true);
         setError(null);
-        let sess;
+        let sess = null;
         let doc = null;
         let dt = null;
-        if (config.sessionId) {
-          sess = await clientRef.current.getSession(config.sessionId);
-        } else {
-          const result = await clientRef.current.createSession(config.documentTypeId);
-          sess = result.session;
-          doc = result.document;
-          dt = {
-            id: result.documentType.id,
-            name: result.documentType.name,
-            displayName: result.documentType.displayName,
-            schema: result.documentType.schema,
-            workspaceId: "",
-            taskConfigs: {},
-            createdAt: "",
-            updatedAt: ""
-          };
+        let sessionIdToResume = config.sessionId;
+        if (!sessionIdToResume && shouldPersist && typeof window !== "undefined") {
+          try {
+            sessionIdToResume = localStorage.getItem(storageKey) || void 0;
+          } catch (e) {
+          }
         }
-        setSession(sess);
-        if (doc) setDocument(doc);
-        if (dt) setDocumentType(dt);
-        config.onSessionChange?.(sess);
-        if (doc && dt) {
-          config.onReady?.({ session: sess, document: doc, documentType: dt });
+        if (sessionIdToResume) {
+          try {
+            const resumedSession = await clientRef.current.getSession(sessionIdToResume);
+            sess = resumedSession;
+            doc = resumedSession.document;
+            const embeddedDt = resumedSession.document.documentType;
+            dt = {
+              id: embeddedDt.id,
+              name: embeddedDt.name,
+              displayName: embeddedDt.displayName,
+              schema: embeddedDt.schema,
+              workspaceId: "",
+              taskConfigs: {},
+              createdAt: "",
+              updatedAt: ""
+            };
+          } catch (e) {
+            console.warn("Failed to resume session, creating new one");
+            if (shouldPersist && typeof window !== "undefined") {
+              try {
+                localStorage.removeItem(storageKey);
+              } catch (e2) {
+              }
+            }
+          }
+        }
+        if (!sess) {
+          const result = await createNewSession();
+          if (result) {
+            sess = result.session;
+            doc = result.document;
+            dt = result.documentType;
+          }
+        }
+        if (sess) {
+          setSession(sess);
+          if (doc) setDocument(doc);
+          if (dt) setDocumentType(dt);
+          config.onSessionChange?.(sess);
+          if (doc && dt) {
+            config.onReady?.({ session: sess, document: doc, documentType: dt });
+          }
         }
       } catch (err) {
         const error2 = err instanceof Error ? err : new Error("Initialization failed");
@@ -248,7 +408,64 @@ function InformedAIProvider({ config, children }) {
       }
     }
     initialize();
-  }, [config.documentTypeId, config.sessionId]);
+  }, [config.documentTypeId, config.sessionId, config.externalId]);
+  const startHeartbeat = (0, import_react.useCallback)((sessionId) => {
+    if (heartbeatIntervalRef.current) {
+      clearInterval(heartbeatIntervalRef.current);
+    }
+    sessionIdRef.current = sessionId;
+    clientRef.current?.sendHeartbeat(sessionId).catch((err) => {
+      console.warn("Heartbeat failed:", err);
+    });
+    heartbeatIntervalRef.current = setInterval(() => {
+      if (clientRef.current && sessionIdRef.current) {
+        clientRef.current.sendHeartbeat(sessionIdRef.current).catch((err) => {
+          console.warn("Heartbeat failed:", err);
+        });
+      }
+    }, HEARTBEAT_INTERVAL);
+  }, []);
+  const stopHeartbeat = (0, import_react.useCallback)(() => {
+    if (heartbeatIntervalRef.current) {
+      clearInterval(heartbeatIntervalRef.current);
+      heartbeatIntervalRef.current = null;
+    }
+  }, []);
+  (0, import_react.useEffect)(() => {
+    if (session?.id && session.status === "active") {
+      startHeartbeat(session.id);
+    } else {
+      stopHeartbeat();
+    }
+    return () => {
+      stopHeartbeat();
+    };
+  }, [session?.id, session?.status, startHeartbeat, stopHeartbeat]);
+  (0, import_react.useEffect)(() => {
+    if (typeof window === "undefined") return;
+    const handleVisibilityChange = () => {
+      if (window.document.hidden) {
+        stopHeartbeat();
+      } else if (session?.id && session.status === "active") {
+        startHeartbeat(session.id);
+      }
+    };
+    window.document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      window.document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [session?.id, session?.status, startHeartbeat, stopHeartbeat]);
+  (0, import_react.useEffect)(() => {
+    const handleBeforeUnload = () => {
+      if (clientRef.current && sessionIdRef.current) {
+        clientRef.current.endSessionBeacon(sessionIdRef.current);
+      }
+    };
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => {
+      window.removeEventListener("beforeunload", handleBeforeUnload);
+    };
+  }, []);
   const handleSSEEvent = (0, import_react.useCallback)((event) => {
     if (event.type === "content" && event.content) {
       setStreamingContent((prev) => prev + event.content);
@@ -276,12 +493,17 @@ function InformedAIProvider({ config, children }) {
       setError(null);
       await clientRef.current.sendMessage(session.id, message, handleSSEEvent);
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        setIsStreaming(false);
+        await handleSessionDeleted();
+        return;
+      }
       const error2 = err instanceof Error ? err : new Error("Failed to send message");
       setError(error2);
       config.onError?.(error2);
       setIsStreaming(false);
     }
-  }, [session, handleSSEEvent, config]);
+  }, [session, handleSSEEvent, handleSessionDeleted, config]);
   const sendQuickAction = (0, import_react.useCallback)(async (action) => {
     if (!clientRef.current || !session) return;
     try {
@@ -296,13 +518,18 @@ function InformedAIProvider({ config, children }) {
       setSession(newSession);
       config.onSessionChange?.(newSession);
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        setIsStreaming(false);
+        await handleSessionDeleted();
+        return;
+      }
       const error2 = err instanceof Error ? err : new Error("Failed to send quick action");
       setError(error2);
       config.onError?.(error2);
     } finally {
       setIsStreaming(false);
     }
-  }, [session, handleSSEEvent, config]);
+  }, [session, handleSSEEvent, handleSessionDeleted, config]);
   const applyPendingValue = (0, import_react.useCallback)(async () => {
     if (!clientRef.current || !session) return;
     try {
@@ -312,11 +539,15 @@ function InformedAIProvider({ config, children }) {
       config.onSessionChange?.(result.session);
       config.onFieldApply?.(result.appliedField, result.appliedValue);
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        await handleSessionDeleted();
+        return;
+      }
       const error2 = err instanceof Error ? err : new Error("Failed to apply value");
       setError(error2);
       config.onError?.(error2);
     }
-  }, [session, config]);
+  }, [session, handleSessionDeleted, config]);
   const skipTask = (0, import_react.useCallback)(async () => {
     if (!clientRef.current || !session) return;
     try {
@@ -325,11 +556,55 @@ function InformedAIProvider({ config, children }) {
       setSession(newSession);
       config.onSessionChange?.(newSession);
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        await handleSessionDeleted();
+        return;
+      }
       const error2 = err instanceof Error ? err : new Error("Failed to skip task");
       setError(error2);
       config.onError?.(error2);
     }
-  }, [session, config]);
+  }, [session, handleSessionDeleted, config]);
+  const startNewSession = (0, import_react.useCallback)(async () => {
+    if (!clientRef.current) return;
+    try {
+      setIsLoading(true);
+      setError(null);
+      clearPersistedSession();
+      const result = await createNewSession();
+      if (result) {
+        setSession(result.session);
+        setDocument(result.document);
+        setDocumentType(result.documentType);
+        config.onSessionChange?.(result.session);
+        config.onReady?.({
+          session: result.session,
+          document: result.document,
+          documentType: result.documentType
+        });
+      }
+    } catch (err) {
+      const error2 = err instanceof Error ? err : new Error("Failed to start new session");
+      setError(error2);
+      config.onError?.(error2);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [createNewSession, clearPersistedSession, config]);
+  const endSession = (0, import_react.useCallback)(async () => {
+    if (!clientRef.current || !session) return;
+    try {
+      setError(null);
+      stopHeartbeat();
+      await clientRef.current.endSession(session.id);
+      clearPersistedSession();
+      setSession((prev) => prev ? { ...prev, status: "ended" } : null);
+    } catch (err) {
+      const error2 = err instanceof Error ? err : new Error("Failed to end session");
+      setError(error2);
+      config.onError?.(error2);
+    }
+  }, [session, clearPersistedSession, stopHeartbeat, config]);
   const clearError = (0, import_react.useCallback)(() => {
     setError(null);
   }, []);
@@ -345,6 +620,8 @@ function InformedAIProvider({ config, children }) {
     sendQuickAction,
     applyPendingValue,
     skipTask,
+    startNewSession,
+    endSession,
     clearError
   };
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(InformedAIContext.Provider, { value, children });

package/dist/index.mjs

@@ -37,16 +37,23 @@ var InformedAIClient = class {
   // ========================================================================
   /**
    * Create a new session for a document type.
-   * This automatically creates a document with default values.
+   *
+   * @param documentTypeId - The document type to create a session for
+   * @param options.externalId - Your object's ID for idempotency (finds or creates document)
+   * @param options.initialData - Your current field values to sync (you're the source of truth)
    */
-  async createSession(documentTypeId) {
+  async createSession(documentTypeId, options) {
     return this.request("/widget/sessions", {
       method: "POST",
-      body: JSON.stringify({ documentTypeId })
+      body: JSON.stringify({
+        documentTypeId,
+        externalId: options?.externalId,
+        initialData: options?.initialData
+      })
     });
   }
   /**
-   * Get an existing session.
+   * Get an existing session with its document and documentType.
    */
   async getSession(id) {
     return this.request(`/widget/sessions/${id}`);
@@ -114,6 +121,51 @@ var InformedAIClient = class {
       method: "POST"
     });
   }
+  /**
+   * Send a heartbeat to keep the session active.
+   * Call this every 30 seconds while the session is in use.
+   */
+  async sendHeartbeat(sessionId) {
+    await this.request(`/widget/sessions/${sessionId}/heartbeat`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Resume an abandoned session with a new chatbot.
+   * Preserves conversation history.
+   */
+  async resumeSession(sessionId) {
+    return this.request(`/widget/sessions/${sessionId}/resume`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Explicitly end a session and release resources.
+   * Conversation history is preserved but session cannot be resumed.
+   */
+  async endSession(sessionId) {
+    await this.request(`/widget/sessions/${sessionId}/end`, {
+      method: "POST"
+    });
+  }
+  /**
+   * Send end session via sendBeacon (for beforeunload).
+   * Returns true if sendBeacon was used, false if fetch fallback was attempted.
+   */
+  endSessionBeacon(sessionId) {
+    const url = `${this.apiUrl}/widget/sessions/${sessionId}/end`;
+    if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+      const blob = new Blob([JSON.stringify({})], { type: "application/json" });
+      return navigator.sendBeacon(url, blob);
+    }
+    fetch(url, {
+      method: "POST",
+      headers: this.getHeaders(),
+      keepalive: true
+    }).catch(() => {
+    });
+    return false;
+  }
   // ========================================================================
   // SSE Stream Processing
   // ========================================================================
@@ -156,6 +208,15 @@ var InformedAIClient = class {
 
 // src/context/InformedAIContext.tsx
 import { jsx } from "react/jsx-runtime";
+var getStorageKey = (documentTypeId, externalId) => `informedai_session_${documentTypeId}${externalId ? `_${externalId}` : ""}`;
+var HEARTBEAT_INTERVAL = 30 * 1e3;
+function isSessionNotFoundError(error) {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return message.includes("session not found") || message.includes("404") || message.includes("not found");
+  }
+  return false;
+}
 var InformedAIContext = createContext(null);
 function useInformedAI() {
   const context = useContext(InformedAIContext);
@@ -173,41 +234,140 @@ function InformedAIProvider({ config, children }) {
   const [error, setError] = useState(null);
   const [streamingContent, setStreamingContent] = useState("");
   const clientRef = useRef(null);
+  const initRef = useRef(false);
+  const heartbeatIntervalRef = useRef(null);
+  const sessionIdRef = useRef(null);
+  const shouldPersist = config.persistSession ?? !!config.externalId;
+  const storageKey = getStorageKey(config.documentTypeId, config.externalId);
   useEffect(() => {
     clientRef.current = new InformedAIClient(config.apiUrl);
   }, [config.apiUrl]);
+  const createNewSession = useCallback(async () => {
+    if (!clientRef.current) return null;
+    const result = await clientRef.current.createSession(
+      config.documentTypeId,
+      {
+        externalId: config.externalId,
+        initialData: config.initialData
+      }
+    );
+    const dt = {
+      id: result.documentType.id,
+      name: result.documentType.name,
+      displayName: result.documentType.displayName,
+      schema: result.documentType.schema,
+      workspaceId: "",
+      taskConfigs: {},
+      createdAt: "",
+      updatedAt: ""
+    };
+    if (shouldPersist && typeof window !== "undefined") {
+      try {
+        localStorage.setItem(storageKey, result.session.id);
+      } catch (e) {
+      }
+    }
+    return { session: result.session, document: result.document, documentType: dt };
+  }, [config.documentTypeId, config.externalId, config.initialData, shouldPersist, storageKey]);
+  const clearPersistedSession = useCallback(() => {
+    if (shouldPersist && typeof window !== "undefined") {
+      try {
+        localStorage.removeItem(storageKey);
+      } catch (e) {
+      }
+    }
+  }, [shouldPersist, storageKey]);
+  const handleSessionDeleted = useCallback(async () => {
+    console.warn("[InformedAI] Session was deleted, starting new session...");
+    clearPersistedSession();
+    if (heartbeatIntervalRef.current) {
+      clearInterval(heartbeatIntervalRef.current);
+      heartbeatIntervalRef.current = null;
+    }
+    sessionIdRef.current = null;
+    try {
+      const result = await createNewSession();
+      if (result) {
+        setSession(result.session);
+        setDocument(result.document);
+        setDocumentType(result.documentType);
+        setError(null);
+        config.onSessionChange?.(result.session);
+        config.onReady?.({
+          session: result.session,
+          document: result.document,
+          documentType: result.documentType
+        });
+        return true;
+      }
+    } catch (err) {
+      console.error("[InformedAI] Failed to create new session after deletion:", err);
+      const error2 = err instanceof Error ? err : new Error("Failed to recover session");
+      setError(error2);
+      config.onError?.(error2);
+    }
+    return false;
+  }, [createNewSession, clearPersistedSession, config]);
   useEffect(() => {
+    if (initRef.current) return;
+    initRef.current = true;
     async function initialize() {
       if (!clientRef.current) return;
       try {
         setIsLoading(true);
         setError(null);
-        let sess;
+        let sess = null;
         let doc = null;
         let dt = null;
-        if (config.sessionId) {
-          sess = await clientRef.current.getSession(config.sessionId);
-        } else {
-          const result = await clientRef.current.createSession(config.documentTypeId);
-          sess = result.session;
-          doc = result.document;
-          dt = {
-            id: result.documentType.id,
-            name: result.documentType.name,
-            displayName: result.documentType.displayName,
-            schema: result.documentType.schema,
-            workspaceId: "",
-            taskConfigs: {},
-            createdAt: "",
-            updatedAt: ""
-          };
+        let sessionIdToResume = config.sessionId;
+        if (!sessionIdToResume && shouldPersist && typeof window !== "undefined") {
+          try {
+            sessionIdToResume = localStorage.getItem(storageKey) || void 0;
+          } catch (e) {
+          }
         }
-        setSession(sess);
-        if (doc) setDocument(doc);
-        if (dt) setDocumentType(dt);
-        config.onSessionChange?.(sess);
-        if (doc && dt) {
-          config.onReady?.({ session: sess, document: doc, documentType: dt });
+        if (sessionIdToResume) {
+          try {
+            const resumedSession = await clientRef.current.getSession(sessionIdToResume);
+            sess = resumedSession;
+            doc = resumedSession.document;
+            const embeddedDt = resumedSession.document.documentType;
+            dt = {
+              id: embeddedDt.id,
+              name: embeddedDt.name,
+              displayName: embeddedDt.displayName,
+              schema: embeddedDt.schema,
+              workspaceId: "",
+              taskConfigs: {},
+              createdAt: "",
+              updatedAt: ""
+            };
+          } catch (e) {
+            console.warn("Failed to resume session, creating new one");
+            if (shouldPersist && typeof window !== "undefined") {
+              try {
+                localStorage.removeItem(storageKey);
+              } catch (e2) {
+              }
+            }
+          }
+        }
+        if (!sess) {
+          const result = await createNewSession();
+          if (result) {
+            sess = result.session;
+            doc = result.document;
+            dt = result.documentType;
+          }
+        }
+        if (sess) {
+          setSession(sess);
+          if (doc) setDocument(doc);
+          if (dt) setDocumentType(dt);
+          config.onSessionChange?.(sess);
+          if (doc && dt) {
+            config.onReady?.({ session: sess, document: doc, documentType: dt });
+          }
         }
       } catch (err) {
         const error2 = err instanceof Error ? err : new Error("Initialization failed");
@@ -218,7 +378,64 @@ function InformedAIProvider({ config, children }) {
       }
     }
     initialize();
-  }, [config.documentTypeId, config.sessionId]);
+  }, [config.documentTypeId, config.sessionId, config.externalId]);
+  const startHeartbeat = useCallback((sessionId) => {
+    if (heartbeatIntervalRef.current) {
+      clearInterval(heartbeatIntervalRef.current);
+    }
+    sessionIdRef.current = sessionId;
+    clientRef.current?.sendHeartbeat(sessionId).catch((err) => {
+      console.warn("Heartbeat failed:", err);
+    });
+    heartbeatIntervalRef.current = setInterval(() => {
+      if (clientRef.current && sessionIdRef.current) {
+        clientRef.current.sendHeartbeat(sessionIdRef.current).catch((err) => {
+          console.warn("Heartbeat failed:", err);
+        });
+      }
+    }, HEARTBEAT_INTERVAL);
+  }, []);
+  const stopHeartbeat = useCallback(() => {
+    if (heartbeatIntervalRef.current) {
+      clearInterval(heartbeatIntervalRef.current);
+      heartbeatIntervalRef.current = null;
+    }
+  }, []);
+  useEffect(() => {
+    if (session?.id && session.status === "active") {
+      startHeartbeat(session.id);
+    } else {
+      stopHeartbeat();
+    }
+    return () => {
+      stopHeartbeat();
+    };
+  }, [session?.id, session?.status, startHeartbeat, stopHeartbeat]);
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const handleVisibilityChange = () => {
+      if (window.document.hidden) {
+        stopHeartbeat();
+      } else if (session?.id && session.status === "active") {
+        startHeartbeat(session.id);
+      }
+    };
+    window.document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      window.document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [session?.id, session?.status, startHeartbeat, stopHeartbeat]);
+  useEffect(() => {
+    const handleBeforeUnload = () => {
+      if (clientRef.current && sessionIdRef.current) {
+        clientRef.current.endSessionBeacon(sessionIdRef.current);
+      }
+    };
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => {
+      window.removeEventListener("beforeunload", handleBeforeUnload);
+    };
+  }, []);
   const handleSSEEvent = useCallback((event) => {
     if (event.type === "content" && event.content) {
       setStreamingContent((prev) => prev + event.content);
@@ -246,12 +463,17 @@ function InformedAIProvider({ config, children }) {
       setError(null);
       await clientRef.current.sendMessage(session.id, message, handleSSEEvent);
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        setIsStreaming(false);
+        await handleSessionDeleted();
+        return;
+      }
       const error2 = err instanceof Error ? err : new Error("Failed to send message");
       setError(error2);
       config.onError?.(error2);
       setIsStreaming(false);
     }
-  }, [session, handleSSEEvent, config]);
+  }, [session, handleSSEEvent, handleSessionDeleted, config]);
   const sendQuickAction = useCallback(async (action) => {
     if (!clientRef.current || !session) return;
     try {
@@ -266,13 +488,18 @@ function InformedAIProvider({ config, children }) {
       setSession(newSession);
       config.onSessionChange?.(newSession);
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        setIsStreaming(false);
+        await handleSessionDeleted();
+        return;
+      }
       const error2 = err instanceof Error ? err : new Error("Failed to send quick action");
       setError(error2);
       config.onError?.(error2);
     } finally {
       setIsStreaming(false);
     }
-  }, [session, handleSSEEvent, config]);
+  }, [session, handleSSEEvent, handleSessionDeleted, config]);
   const applyPendingValue = useCallback(async () => {
     if (!clientRef.current || !session) return;
     try {
@@ -282,11 +509,15 @@ function InformedAIProvider({ config, children }) {
       config.onSessionChange?.(result.session);
       config.onFieldApply?.(result.appliedField, result.appliedValue);
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        await handleSessionDeleted();
+        return;
+      }
       const error2 = err instanceof Error ? err : new Error("Failed to apply value");
       setError(error2);
       config.onError?.(error2);
     }
-  }, [session, config]);
+  }, [session, handleSessionDeleted, config]);
   const skipTask = useCallback(async () => {
     if (!clientRef.current || !session) return;
     try {
@@ -295,11 +526,55 @@ function InformedAIProvider({ config, children }) {
       setSession(newSession);
       config.onSessionChange?.(newSession);
     } catch (err) {
+      if (isSessionNotFoundError(err)) {
+        await handleSessionDeleted();
+        return;
+      }
       const error2 = err instanceof Error ? err : new Error("Failed to skip task");
       setError(error2);
       config.onError?.(error2);
     }
-  }, [session, config]);
+  }, [session, handleSessionDeleted, config]);
+  const startNewSession = useCallback(async () => {
+    if (!clientRef.current) return;
+    try {
+      setIsLoading(true);
+      setError(null);
+      clearPersistedSession();
+      const result = await createNewSession();
+      if (result) {
+        setSession(result.session);
+        setDocument(result.document);
+        setDocumentType(result.documentType);
+        config.onSessionChange?.(result.session);
+        config.onReady?.({
+          session: result.session,
+          document: result.document,
+          documentType: result.documentType
+        });
+      }
+    } catch (err) {
+      const error2 = err instanceof Error ? err : new Error("Failed to start new session");
+      setError(error2);
+      config.onError?.(error2);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [createNewSession, clearPersistedSession, config]);
+  const endSession = useCallback(async () => {
+    if (!clientRef.current || !session) return;
+    try {
+      setError(null);
+      stopHeartbeat();
+      await clientRef.current.endSession(session.id);
+      clearPersistedSession();
+      setSession((prev) => prev ? { ...prev, status: "ended" } : null);
+    } catch (err) {
+      const error2 = err instanceof Error ? err : new Error("Failed to end session");
+      setError(error2);
+      config.onError?.(error2);
+    }
+  }, [session, clearPersistedSession, stopHeartbeat, config]);
   const clearError = useCallback(() => {
     setError(null);
   }, []);
@@ -315,6 +590,8 @@ function InformedAIProvider({ config, children }) {
     sendQuickAction,
     applyPendingValue,
     skipTask,
+    startNewSession,
+    endSession,
     clearError
   };
   return /* @__PURE__ */ jsx(InformedAIContext.Provider, { value, children });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@informedai/react",
-  "version": "0.2.6",
+  "version": "0.4.0",
   "description": "React SDK for InformedAI Assistant - AI-powered content creation widget",
   "main": "dist/index.js",
   "module": "dist/index.mjs",