@informedai/react 0.2.5 → 0.3.0

package/dist/index.d.mts

@@ -76,8 +76,27 @@ 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;
     /** Callback when a field value is applied */
     onFieldApply?: (fieldName: string, value: unknown) => void;
     /** Callback when session state changes */
@@ -91,6 +110,11 @@ interface InformedAssistantConfig {
     /** Initial collapsed state */
     defaultCollapsed?: boolean;
 }
+interface WidgetReadyContext {
+    session: Session;
+    document: Document;
+    documentType: DocumentType;
+}
 interface WidgetTheme {
     /** Primary accent color */
     primaryColor: string;
@@ -149,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;
@@ -206,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.
      */
@@ -234,4 +265,4 @@ declare class InformedAIClient {
     private processSSEStream;
 }
 
-export { type ChatMessage, type Document, type DocumentType, type DocumentTypeSchema, type FieldDefinition, InformedAIClient, InformedAIProvider, InformedAssistant, type InformedAssistantConfig, type QuickAction, type SSEEvent, type Session, type TaskConfig, type TaskState, type UseSessionReturn, type WidgetMessage, type WidgetTheme, useInformedAI, useSession };
+export { type ChatMessage, type Document, type DocumentType, type DocumentTypeSchema, type FieldDefinition, InformedAIClient, InformedAIProvider, InformedAssistant, type InformedAssistantConfig, type QuickAction, type SSEEvent, type Session, type TaskConfig, type TaskState, type UseSessionReturn, type WidgetMessage, type WidgetReadyContext, type WidgetTheme, useInformedAI, useSession };

package/dist/index.d.ts

@@ -76,8 +76,27 @@ 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;
     /** Callback when a field value is applied */
     onFieldApply?: (fieldName: string, value: unknown) => void;
     /** Callback when session state changes */
@@ -91,6 +110,11 @@ interface InformedAssistantConfig {
     /** Initial collapsed state */
     defaultCollapsed?: boolean;
 }
+interface WidgetReadyContext {
+    session: Session;
+    document: Document;
+    documentType: DocumentType;
+}
 interface WidgetTheme {
     /** Primary accent color */
     primaryColor: string;
@@ -149,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;
@@ -206,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.
      */
@@ -234,4 +265,4 @@ declare class InformedAIClient {
     private processSSEStream;
 }
 
-export { type ChatMessage, type Document, type DocumentType, type DocumentTypeSchema, type FieldDefinition, InformedAIClient, InformedAIProvider, InformedAssistant, type InformedAssistantConfig, type QuickAction, type SSEEvent, type Session, type TaskConfig, type TaskState, type UseSessionReturn, type WidgetMessage, type WidgetTheme, useInformedAI, useSession };
+export { type ChatMessage, type Document, type DocumentType, type DocumentTypeSchema, type FieldDefinition, InformedAIClient, InformedAIProvider, InformedAssistant, type InformedAssistantConfig, type QuickAction, type SSEEvent, type Session, type TaskConfig, type TaskState, type UseSessionReturn, type WidgetMessage, type WidgetReadyContext, type WidgetTheme, useInformedAI, useSession };

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,39 +211,94 @@ 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;
+          }
+        }
+        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 });
+          }
         }
-        setSession(sess);
-        if (doc) setDocument(doc);
-        if (dt) setDocumentType(dt);
-        config.onSessionChange?.(sess);
       } catch (err) {
         const error2 = err instanceof Error ? err : new Error("Initialization failed");
         setError(error2);
@@ -245,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);
@@ -327,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);
   }, []);
@@ -342,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,39 +181,94 @@ 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;
+          }
+        }
+        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 });
+          }
         }
-        setSession(sess);
-        if (doc) setDocument(doc);
-        if (dt) setDocumentType(dt);
-        config.onSessionChange?.(sess);
       } catch (err) {
         const error2 = err instanceof Error ? err : new Error("Initialization failed");
         setError(error2);
@@ -215,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);
@@ -297,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);
   }, []);
@@ -312,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.5",
+  "version": "0.3.0",
   "description": "React SDK for InformedAI Assistant - AI-powered content creation widget",
   "main": "dist/index.js",
   "module": "dist/index.mjs",