@informedai/react 0.2.6 → 0.3.0

package/dist/index.d.mts

@@ -76,7 +76,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;
@@ -156,6 +173,7 @@ interface InformedAIContextValue {
     sendQuickAction: (action: string, payload?: Record<string, unknown>) => Promise<void>;
     applyPendingValue: () => Promise<void>;
     skipTask: () => Promise<void>;
+    startNewSession: () => Promise<void>;
     clearError: () => void;
 }
 declare function useInformedAI(): InformedAIContextValue;
@@ -213,9 +231,15 @@ 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.
      */

package/dist/index.d.ts

@@ -76,7 +76,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;
@@ -156,6 +173,7 @@ interface InformedAIContextValue {
     sendQuickAction: (action: string, payload?: Record<string, unknown>) => Promise<void>;
     applyPendingValue: () => Promise<void>;
     skipTask: () => Promise<void>;
+    startNewSession: () => Promise<void>;
     clearError: () => void;
 }
 declare function useInformedAI(): InformedAIContextValue;
@@ -213,9 +231,15 @@ 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.
      */

package/dist/index.js

@@ -67,12 +67,19 @@ 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
+      })
     });
   }
   /**
@@ -186,6 +193,7 @@ 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 InformedAIContext = (0, import_react.createContext)(null);
 function useInformedAI() {
   const context = (0, import_react.useContext)(InformedAIContext);
@@ -203,41 +211,93 @@ 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 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]);
   (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);
+        let sessionIdToResume = config.sessionId;
+        if (!sessionIdToResume && shouldPersist && typeof window !== "undefined") {
+          try {
+            sessionIdToResume = localStorage.getItem(storageKey) || void 0;
+          } catch (e) {
+          }
+        }
+        if (sessionIdToResume) {
+          try {
+            sess = await clientRef.current.getSession(sessionIdToResume);
+          } 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;
+          }
         } 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: ""
-          };
+          const result = await createNewSession();
+          if (result) {
+            sess = result.session;
+            doc = result.document;
+            dt = result.documentType;
+          }
         }
-        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 (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 +308,7 @@ function InformedAIProvider({ config, children }) {
       }
     }
     initialize();
-  }, [config.documentTypeId, config.sessionId]);
+  }, [config.documentTypeId, config.sessionId, config.externalId]);
   const handleSSEEvent = (0, import_react.useCallback)((event) => {
     if (event.type === "content" && event.content) {
       setStreamingContent((prev) => prev + event.content);
@@ -330,6 +390,37 @@ function InformedAIProvider({ config, children }) {
       config.onError?.(error2);
     }
   }, [session, 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) {
+        }
+      }
+      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, shouldPersist, storageKey, config]);
   const clearError = (0, import_react.useCallback)(() => {
     setError(null);
   }, []);
@@ -345,6 +436,7 @@ function InformedAIProvider({ config, children }) {
     sendQuickAction,
     applyPendingValue,
     skipTask,
+    startNewSession,
     clearError
   };
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(InformedAIContext.Provider, { value, children });

package/dist/index.mjs

@@ -37,12 +37,19 @@ 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
+      })
     });
   }
   /**
@@ -156,6 +163,7 @@ var InformedAIClient = class {
 
 // src/context/InformedAIContext.tsx
 import { jsx } from "react/jsx-runtime";
+var getStorageKey = (documentTypeId, externalId) => `informedai_session_${documentTypeId}${externalId ? `_${externalId}` : ""}`;
 var InformedAIContext = createContext(null);
 function useInformedAI() {
   const context = useContext(InformedAIContext);
@@ -173,41 +181,93 @@ function InformedAIProvider({ config, children }) {
   const [error, setError] = useState(null);
   const [streamingContent, setStreamingContent] = useState("");
   const clientRef = useRef(null);
+  const initRef = useRef(false);
+  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]);
   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);
+        let sessionIdToResume = config.sessionId;
+        if (!sessionIdToResume && shouldPersist && typeof window !== "undefined") {
+          try {
+            sessionIdToResume = localStorage.getItem(storageKey) || void 0;
+          } catch (e) {
+          }
+        }
+        if (sessionIdToResume) {
+          try {
+            sess = await clientRef.current.getSession(sessionIdToResume);
+          } 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;
+          }
         } 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: ""
-          };
+          const result = await createNewSession();
+          if (result) {
+            sess = result.session;
+            doc = result.document;
+            dt = result.documentType;
+          }
         }
-        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 (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 +278,7 @@ function InformedAIProvider({ config, children }) {
       }
     }
     initialize();
-  }, [config.documentTypeId, config.sessionId]);
+  }, [config.documentTypeId, config.sessionId, config.externalId]);
   const handleSSEEvent = useCallback((event) => {
     if (event.type === "content" && event.content) {
       setStreamingContent((prev) => prev + event.content);
@@ -300,6 +360,37 @@ function InformedAIProvider({ config, children }) {
       config.onError?.(error2);
     }
   }, [session, 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) {
+        }
+      }
+      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, shouldPersist, storageKey, config]);
   const clearError = useCallback(() => {
     setError(null);
   }, []);
@@ -315,6 +406,7 @@ function InformedAIProvider({ config, children }) {
     sendQuickAction,
     applyPendingValue,
     skipTask,
+    startNewSession,
     clearError
   };
   return /* @__PURE__ */ jsx(InformedAIContext.Provider, { value, children });

package/package.json

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