@informedai/react 0.3.0 → 0.4.1

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;
@@ -133,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;
@@ -174,6 +189,7 @@ interface InformedAIContextValue {
     applyPendingValue: () => Promise<void>;
     skipTask: () => Promise<void>;
     startNewSession: () => Promise<void>;
+    endSession: () => Promise<void>;
     clearError: () => void;
 }
 declare function useInformedAI(): InformedAIContextValue;
@@ -241,9 +257,9 @@ declare class InformedAIClient {
         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.
      */
@@ -262,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;
@@ -133,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;
@@ -174,6 +189,7 @@ interface InformedAIContextValue {
     applyPendingValue: () => Promise<void>;
     skipTask: () => Promise<void>;
     startNewSession: () => Promise<void>;
+    endSession: () => Promise<void>;
     clearError: () => void;
 }
 declare function useInformedAI(): InformedAIContextValue;
@@ -241,9 +257,9 @@ declare class InformedAIClient {
         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.
      */
@@ -262,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

@@ -83,7 +83,7 @@ var InformedAIClient = class {
     });
   }
   /**
-   * Get an existing session.
+   * Get an existing session with its document and documentType.
    */
   async getSession(id) {
     return this.request(`/widget/sessions/${id}`);
@@ -151,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
   // ========================================================================
@@ -194,6 +239,14 @@ 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);
@@ -212,6 +265,8 @@ function InformedAIProvider({ config, children }) {
   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)(() => {
@@ -244,6 +299,45 @@ function InformedAIProvider({ config, children }) {
     }
     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;
@@ -264,7 +358,20 @@ function InformedAIProvider({ config, children }) {
         }
         if (sessionIdToResume) {
           try {
-            sess = await clientRef.current.getSession(sessionIdToResume);
+            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") {
@@ -282,13 +389,6 @@ function InformedAIProvider({ config, children }) {
             doc = result.document;
             dt = result.documentType;
           }
-        } else {
-          const result = await createNewSession();
-          if (result) {
-            sess = result.session;
-            doc = result.document;
-            dt = result.documentType;
-          }
         }
         if (sess) {
           setSession(sess);
@@ -309,6 +409,85 @@ function InformedAIProvider({ config, children }) {
     }
     initialize();
   }, [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 = async () => {
+      if (window.document.hidden) {
+        stopHeartbeat();
+      } else if (session?.id && clientRef.current) {
+        try {
+          const refreshedSession = await clientRef.current.getSession(session.id);
+          if (refreshedSession.status === "abandoned") {
+            console.log("[InformedAI] Session was abandoned, resuming...");
+            try {
+              const resumedSession = await clientRef.current.resumeSession(session.id);
+              setSession(resumedSession);
+              config.onSessionChange?.(resumedSession);
+              startHeartbeat(session.id);
+            } catch (resumeErr) {
+              console.error("[InformedAI] Failed to resume session:", resumeErr);
+              await handleSessionDeleted();
+            }
+          } else if (refreshedSession.status === "active") {
+            setSession(refreshedSession);
+            startHeartbeat(session.id);
+          } else {
+            setSession(refreshedSession);
+          }
+        } catch (err) {
+          console.warn("[InformedAI] Session not found on return, creating new...");
+          await handleSessionDeleted();
+        }
+      }
+    };
+    window.document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      window.document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [session?.id, startHeartbeat, stopHeartbeat, handleSessionDeleted, config]);
+  (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);
@@ -336,12 +515,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 {
@@ -356,13 +540,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 {
@@ -372,11 +561,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 {
@@ -385,22 +578,21 @@ 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);
-      if (shouldPersist && typeof window !== "undefined") {
-        try {
-          localStorage.removeItem(storageKey);
-        } catch (e) {
-        }
-      }
+      clearPersistedSession();
       const result = await createNewSession();
       if (result) {
         setSession(result.session);
@@ -420,7 +612,21 @@ function InformedAIProvider({ config, children }) {
     } finally {
       setIsLoading(false);
     }
-  }, [createNewSession, shouldPersist, storageKey, config]);
+  }, [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);
   }, []);
@@ -437,6 +643,7 @@ function InformedAIProvider({ config, children }) {
     applyPendingValue,
     skipTask,
     startNewSession,
+    endSession,
     clearError
   };
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(InformedAIContext.Provider, { value, children });

package/dist/index.mjs

@@ -53,7 +53,7 @@ var InformedAIClient = class {
     });
   }
   /**
-   * Get an existing session.
+   * Get an existing session with its document and documentType.
    */
   async getSession(id) {
     return this.request(`/widget/sessions/${id}`);
@@ -121,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
   // ========================================================================
@@ -164,6 +209,14 @@ 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);
@@ -182,6 +235,8 @@ function InformedAIProvider({ config, children }) {
   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(() => {
@@ -214,6 +269,45 @@ function InformedAIProvider({ config, children }) {
     }
     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;
@@ -234,7 +328,20 @@ function InformedAIProvider({ config, children }) {
         }
         if (sessionIdToResume) {
           try {
-            sess = await clientRef.current.getSession(sessionIdToResume);
+            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") {
@@ -252,13 +359,6 @@ function InformedAIProvider({ config, children }) {
             doc = result.document;
             dt = result.documentType;
           }
-        } else {
-          const result = await createNewSession();
-          if (result) {
-            sess = result.session;
-            doc = result.document;
-            dt = result.documentType;
-          }
         }
         if (sess) {
           setSession(sess);
@@ -279,6 +379,85 @@ function InformedAIProvider({ config, children }) {
     }
     initialize();
   }, [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 = async () => {
+      if (window.document.hidden) {
+        stopHeartbeat();
+      } else if (session?.id && clientRef.current) {
+        try {
+          const refreshedSession = await clientRef.current.getSession(session.id);
+          if (refreshedSession.status === "abandoned") {
+            console.log("[InformedAI] Session was abandoned, resuming...");
+            try {
+              const resumedSession = await clientRef.current.resumeSession(session.id);
+              setSession(resumedSession);
+              config.onSessionChange?.(resumedSession);
+              startHeartbeat(session.id);
+            } catch (resumeErr) {
+              console.error("[InformedAI] Failed to resume session:", resumeErr);
+              await handleSessionDeleted();
+            }
+          } else if (refreshedSession.status === "active") {
+            setSession(refreshedSession);
+            startHeartbeat(session.id);
+          } else {
+            setSession(refreshedSession);
+          }
+        } catch (err) {
+          console.warn("[InformedAI] Session not found on return, creating new...");
+          await handleSessionDeleted();
+        }
+      }
+    };
+    window.document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      window.document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [session?.id, startHeartbeat, stopHeartbeat, handleSessionDeleted, config]);
+  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);
@@ -306,12 +485,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 {
@@ -326,13 +510,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 {
@@ -342,11 +531,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 {
@@ -355,22 +548,21 @@ 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);
-      if (shouldPersist && typeof window !== "undefined") {
-        try {
-          localStorage.removeItem(storageKey);
-        } catch (e) {
-        }
-      }
+      clearPersistedSession();
       const result = await createNewSession();
       if (result) {
         setSession(result.session);
@@ -390,7 +582,21 @@ function InformedAIProvider({ config, children }) {
     } finally {
       setIsLoading(false);
     }
-  }, [createNewSession, shouldPersist, storageKey, config]);
+  }, [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);
   }, []);
@@ -407,6 +613,7 @@ function InformedAIProvider({ config, children }) {
     applyPendingValue,
     skipTask,
     startNewSession,
+    endSession,
     clearError
   };
   return /* @__PURE__ */ jsx(InformedAIContext.Provider, { value, children });

package/package.json

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