@hsafa/ui-sdk 0.5.4 → 0.6.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as React$1 from 'react';
-import React__default, { ComponentType } from 'react';
+import React__default, { Dispatch, SetStateAction, ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -110,7 +110,7 @@ type AssistantContentPart = {
     type: 'tool-call';
     toolCallId: string;
     toolName?: string;
-    input?: any;
+    input?: unknown;
 };
 type ChatMessage = {
     id: string;
@@ -123,23 +123,31 @@ type ChatMessage = {
     id: string;
     role: 'assistant';
     content?: string | AssistantContentPart[];
-    items: any[];
+    items: unknown[];
     reasoning?: string;
     reasoningOpen?: boolean;
-    mainAgentActions?: any[];
+    mainAgentActions?: unknown[];
     createdAt?: number;
 };
-type HsafaTool = ((input: any) => any | Promise<any>) | {
-    tool: (input: any) => any | Promise<any>;
+type HsafaTool = ((input: unknown) => unknown | Promise<unknown>) | {
+    tool: (input: unknown) => unknown | Promise<unknown>;
     executeEachToken?: boolean;
+    inputting_start?: (input: unknown, ctx: {
+        toolCallId: string;
+        toolName: string;
+    }) => void;
+    running_start?: (input: unknown, ctx: {
+        toolCallId: string;
+        toolName: string;
+    }) => void;
 };
 type CustomToolUIRenderProps = {
     toolName: string;
     toolCallId: string;
-    input: any;
-    output: any;
+    input: unknown;
+    output: unknown;
     status?: string;
-    addToolResult: (result: any) => void;
+    addToolResult: (result: unknown) => void;
 };
 interface HsafaChatProps {
     agentId: string;
@@ -291,7 +299,7 @@ interface HsafaAgentAPI {
     /** Set messages directly (for loading history) */
     setMessages: (messages: any[]) => void;
     /** Notify that messages have changed (for edit operations) */
-    notifyMessagesChange: () => void;
+    notifyMessagesChange: (messagesOverride?: unknown[], chatIdOverride?: string) => void;
     /** Direct access to the underlying chat API */
     chatApi: any;
     /** Current chat ID */
@@ -520,10 +528,87 @@ interface MessageEditorAPI {
 }
 declare function useMessageEditor(config: UseMessageEditorConfig): MessageEditorAPI;
 
+type HsafaActiveChatIdSource = 'context' | 'storage' | 'none';
+interface UseHsafaActiveChatIdOptions {
+    agentId: string;
+    prefer?: 'context' | 'storage';
+}
+interface HsafaActiveChatIdResult {
+    chatId?: string;
+    isReady: boolean;
+    source: HsafaActiveChatIdSource;
+}
+declare function useHsafaActiveChatId(options: UseHsafaActiveChatIdOptions): HsafaActiveChatIdResult;
+
+type HsafaArtifactStoreBackend = 'opfs' | 'localStorage';
+interface HsafaArtifactStoreConfig<T> {
+    namespace: string;
+    serialize?: (value: T) => string;
+    deserialize?: (raw: string) => T;
+    storageOrder?: HsafaArtifactStoreBackend[];
+    legacyDecode?: (raw: string) => {
+        value: T;
+        chatId: string;
+        versionId: string;
+        updatedAt?: string;
+    } | null;
+}
+interface HsafaArtifactStore<T> {
+    saveLatest: (chatId: string, value: T) => Promise<void>;
+    loadLatest: (chatId: string) => Promise<T | null>;
+    saveVersion: (chatId: string, versionId: string, value: T) => Promise<void>;
+    loadVersion: (chatId: string, versionId: string) => Promise<T | null>;
+    hasVersion: (chatId: string, versionId: string) => Promise<boolean>;
+    findMostRecentChatId: () => Promise<string | null>;
+}
+declare function createHsafaArtifactStore<T>(config: HsafaArtifactStoreConfig<T>): HsafaArtifactStore<T>;
+
+type ChatArtifactStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface UseChatArtifactOptions<T> {
+    agentId: string;
+    chatId?: string;
+    initial: T;
+    store: HsafaArtifactStore<T>;
+    autoLoad?: boolean;
+    autoSave?: boolean;
+    saveDebounceMs?: number;
+}
+interface ChatArtifactResult<T> {
+    value: T;
+    setValue: Dispatch<SetStateAction<T>>;
+    status: ChatArtifactStatus;
+    error?: unknown;
+    reload: () => Promise<void>;
+    flushSave: () => Promise<void>;
+}
+declare function useChatArtifact<T>(options: UseChatArtifactOptions<T>): ChatArtifactResult<T>;
+
+interface UseChatArtifactVersioningOptions<T> {
+    chatId?: string;
+    store: HsafaArtifactStore<T>;
+    value: T;
+    setValue: Dispatch<SetStateAction<T>>;
+    initial: T;
+}
+interface ChatArtifactVersioningAPI {
+    onFinish: (payload: unknown) => Promise<void>;
+    onMessagesChange: (messages: unknown[], chatId?: string) => Promise<void>;
+}
+declare function useChatArtifactVersioning<T>(options: UseChatArtifactVersioningOptions<T>): ChatArtifactVersioningAPI;
+
+declare function useHsafaTools<TState, TTools extends Record<string, unknown>>(config: {
+    state: TState;
+    setState: React$1.Dispatch<React$1.SetStateAction<TState>>;
+    tools: (api: {
+        get: () => TState;
+        set: React$1.Dispatch<React$1.SetStateAction<TState>>;
+    }) => TTools;
+}): TTools;
+
 /**
  * Handler function for custom actions that can be triggered by the AI agent
  */
-type HsafaActionHandler = (params: any, meta: {
+type HsafaActionHandler = (params: unknown, meta: {
     /** Name of the action being called */
     name: string;
     /** When the action is being triggered */
@@ -534,7 +619,7 @@ type HsafaActionHandler = (params: any, meta: {
     assistantMessageId?: string;
     /** ID of the current chat session */
     chatId?: string;
-}) => Promise<any> | any;
+}) => Promise<unknown> | unknown;
 /**
  * Configuration options for the Hsafa SDK
  */
@@ -553,15 +638,15 @@ interface HsafaContextValue extends HsafaConfig {
     /** Registered custom actions */
     actions: Map<string, HsafaActionHandler>;
     /** Registered custom components */
-    components: Map<string, React__default.ComponentType<any>>;
+    components: Map<string, React__default.ComponentType<Record<string, unknown>>>;
     /** Register a custom action handler */
     registerAction: (name: string, handler: HsafaActionHandler) => () => void;
     /** Unregister a custom action handler */
     unregisterAction: (name: string, handler?: HsafaActionHandler) => void;
     /** Register a custom component */
-    registerComponent: (name: string, component: React__default.ComponentType<any>) => () => void;
+    registerComponent: (name: string, component: React__default.ComponentType<Record<string, unknown>>) => () => void;
     /** Unregister a custom component */
-    unregisterComponent: (name: string, component?: React__default.ComponentType<any>) => void;
+    unregisterComponent: (name: string, component?: React__default.ComponentType<Record<string, unknown>>) => void;
     /** Global streaming state - true if any chat is streaming */
     isAnyStreaming: boolean;
     /** Set streaming state for a specific chat instance */
@@ -574,6 +659,12 @@ interface HsafaContextValue extends HsafaConfig {
     currentChatId?: string;
     /** Setter for current chat id */
     setCurrentChatId: (chatId: string) => void;
+    tools: Map<string, HsafaTool>;
+    uiComponents: Map<string, React__default.ComponentType<Record<string, unknown>>>;
+    registerTool: (name: string, tool: HsafaTool) => () => void;
+    unregisterTool: (name: string, tool?: HsafaTool) => void;
+    registerUIComponent: (name: string, component: React__default.ComponentType<Record<string, unknown>>) => () => void;
+    unregisterUIComponent: (name: string, component?: React__default.ComponentType<Record<string, unknown>>) => void;
 }
 /**
  * Props for the HsafaProvider component
@@ -581,6 +672,8 @@ interface HsafaContextValue extends HsafaConfig {
 interface HsafaProviderProps extends HsafaConfig {
     /** Child components that will have access to the Hsafa context */
     children: React__default.ReactNode;
+    tools?: Record<string, HsafaTool>;
+    uiComponents?: Record<string, React__default.ComponentType<Record<string, unknown>>>;
 }
 /**
  * Provider component that sets up the Hsafa context for the SDK.
@@ -593,7 +686,7 @@ interface HsafaProviderProps extends HsafaConfig {
  * </HsafaProvider>
  * ```
  */
-declare function HsafaProvider({ baseUrl, dir, theme, children }: HsafaProviderProps): react_jsx_runtime.JSX.Element;
+declare function HsafaProvider({ baseUrl, dir, theme, children, tools: initialTools, uiComponents: initialUIComponents }: HsafaProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the Hsafa context.
  * Must be used within a HsafaProvider.
@@ -936,4 +1029,4 @@ type FillResult = {
 };
 declare function FillActiveInput(value: any, options?: FillInputOptions): Promise<FillResult>;
 
-export { type Anchor, type Attachment, Button, type ButtonProps, type ChatMessage, type ChatMetadata, type ChatStorageAPI, ContentContainer, type ContentContainerProps, CursorController, type CustomToolUIRenderProps, type DomComponent, type EditProcessContent, FillActiveInput, type FillInputOptions, type FillResult, FloatingChatButton, type GetDomComponentsOptions, type GetDomComponentsResult, type GuideAction, type GuideCursorOptions, type GuideOptions, type GuideRunResult, type GuideStep, type GuideStepResult, type GuideTarget, type HsafaAgentAPI, HsafaChat, type HsafaChatProps, HsafaProvider, type HsafaTool, type MessageEditorAPI, type SavedChat, type UIComponentProps, type UseChatStorageConfig, type UseHsafaAgentConfig, type UseMessageEditorConfig, registry as componentRegistry, guideCursor as controlCursor, getDomComponents, guideCursor, useAutoScroll, useChatStorage, useFileUpload, useHsafa, useHsafaAgent, useMessageEditor };
+export { type Anchor, type Attachment, Button, type ButtonProps, type ChatArtifactResult, type ChatArtifactStatus, type ChatArtifactVersioningAPI, type ChatMessage, type ChatMetadata, type ChatStorageAPI, ContentContainer, type ContentContainerProps, CursorController, type CustomToolUIRenderProps, type DomComponent, type EditProcessContent, FillActiveInput, type FillInputOptions, type FillResult, FloatingChatButton, type GetDomComponentsOptions, type GetDomComponentsResult, type GuideAction, type GuideCursorOptions, type GuideOptions, type GuideRunResult, type GuideStep, type GuideStepResult, type GuideTarget, type HsafaActiveChatIdResult, type HsafaActiveChatIdSource, type HsafaAgentAPI, type HsafaArtifactStore, type HsafaArtifactStoreBackend, type HsafaArtifactStoreConfig, HsafaChat, type HsafaChatProps, HsafaProvider, type HsafaTool, type MessageEditorAPI, type SavedChat, type UIComponentProps, type UseChatArtifactOptions, type UseChatArtifactVersioningOptions, type UseChatStorageConfig, type UseHsafaActiveChatIdOptions, type UseHsafaAgentConfig, type UseMessageEditorConfig, registry as componentRegistry, guideCursor as controlCursor, createHsafaArtifactStore, getDomComponents, guideCursor, useAutoScroll, useChatArtifact, useChatArtifactVersioning, useChatStorage, useFileUpload, useHsafa, useHsafaActiveChatId, useHsafaAgent, useHsafaTools, useMessageEditor };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as React$1 from 'react';
-import React__default, { ComponentType } from 'react';
+import React__default, { Dispatch, SetStateAction, ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -110,7 +110,7 @@ type AssistantContentPart = {
     type: 'tool-call';
     toolCallId: string;
     toolName?: string;
-    input?: any;
+    input?: unknown;
 };
 type ChatMessage = {
     id: string;
@@ -123,23 +123,31 @@ type ChatMessage = {
     id: string;
     role: 'assistant';
     content?: string | AssistantContentPart[];
-    items: any[];
+    items: unknown[];
     reasoning?: string;
     reasoningOpen?: boolean;
-    mainAgentActions?: any[];
+    mainAgentActions?: unknown[];
     createdAt?: number;
 };
-type HsafaTool = ((input: any) => any | Promise<any>) | {
-    tool: (input: any) => any | Promise<any>;
+type HsafaTool = ((input: unknown) => unknown | Promise<unknown>) | {
+    tool: (input: unknown) => unknown | Promise<unknown>;
     executeEachToken?: boolean;
+    inputting_start?: (input: unknown, ctx: {
+        toolCallId: string;
+        toolName: string;
+    }) => void;
+    running_start?: (input: unknown, ctx: {
+        toolCallId: string;
+        toolName: string;
+    }) => void;
 };
 type CustomToolUIRenderProps = {
     toolName: string;
     toolCallId: string;
-    input: any;
-    output: any;
+    input: unknown;
+    output: unknown;
     status?: string;
-    addToolResult: (result: any) => void;
+    addToolResult: (result: unknown) => void;
 };
 interface HsafaChatProps {
     agentId: string;
@@ -291,7 +299,7 @@ interface HsafaAgentAPI {
     /** Set messages directly (for loading history) */
     setMessages: (messages: any[]) => void;
     /** Notify that messages have changed (for edit operations) */
-    notifyMessagesChange: () => void;
+    notifyMessagesChange: (messagesOverride?: unknown[], chatIdOverride?: string) => void;
     /** Direct access to the underlying chat API */
     chatApi: any;
     /** Current chat ID */
@@ -520,10 +528,87 @@ interface MessageEditorAPI {
 }
 declare function useMessageEditor(config: UseMessageEditorConfig): MessageEditorAPI;
 
+type HsafaActiveChatIdSource = 'context' | 'storage' | 'none';
+interface UseHsafaActiveChatIdOptions {
+    agentId: string;
+    prefer?: 'context' | 'storage';
+}
+interface HsafaActiveChatIdResult {
+    chatId?: string;
+    isReady: boolean;
+    source: HsafaActiveChatIdSource;
+}
+declare function useHsafaActiveChatId(options: UseHsafaActiveChatIdOptions): HsafaActiveChatIdResult;
+
+type HsafaArtifactStoreBackend = 'opfs' | 'localStorage';
+interface HsafaArtifactStoreConfig<T> {
+    namespace: string;
+    serialize?: (value: T) => string;
+    deserialize?: (raw: string) => T;
+    storageOrder?: HsafaArtifactStoreBackend[];
+    legacyDecode?: (raw: string) => {
+        value: T;
+        chatId: string;
+        versionId: string;
+        updatedAt?: string;
+    } | null;
+}
+interface HsafaArtifactStore<T> {
+    saveLatest: (chatId: string, value: T) => Promise<void>;
+    loadLatest: (chatId: string) => Promise<T | null>;
+    saveVersion: (chatId: string, versionId: string, value: T) => Promise<void>;
+    loadVersion: (chatId: string, versionId: string) => Promise<T | null>;
+    hasVersion: (chatId: string, versionId: string) => Promise<boolean>;
+    findMostRecentChatId: () => Promise<string | null>;
+}
+declare function createHsafaArtifactStore<T>(config: HsafaArtifactStoreConfig<T>): HsafaArtifactStore<T>;
+
+type ChatArtifactStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface UseChatArtifactOptions<T> {
+    agentId: string;
+    chatId?: string;
+    initial: T;
+    store: HsafaArtifactStore<T>;
+    autoLoad?: boolean;
+    autoSave?: boolean;
+    saveDebounceMs?: number;
+}
+interface ChatArtifactResult<T> {
+    value: T;
+    setValue: Dispatch<SetStateAction<T>>;
+    status: ChatArtifactStatus;
+    error?: unknown;
+    reload: () => Promise<void>;
+    flushSave: () => Promise<void>;
+}
+declare function useChatArtifact<T>(options: UseChatArtifactOptions<T>): ChatArtifactResult<T>;
+
+interface UseChatArtifactVersioningOptions<T> {
+    chatId?: string;
+    store: HsafaArtifactStore<T>;
+    value: T;
+    setValue: Dispatch<SetStateAction<T>>;
+    initial: T;
+}
+interface ChatArtifactVersioningAPI {
+    onFinish: (payload: unknown) => Promise<void>;
+    onMessagesChange: (messages: unknown[], chatId?: string) => Promise<void>;
+}
+declare function useChatArtifactVersioning<T>(options: UseChatArtifactVersioningOptions<T>): ChatArtifactVersioningAPI;
+
+declare function useHsafaTools<TState, TTools extends Record<string, unknown>>(config: {
+    state: TState;
+    setState: React$1.Dispatch<React$1.SetStateAction<TState>>;
+    tools: (api: {
+        get: () => TState;
+        set: React$1.Dispatch<React$1.SetStateAction<TState>>;
+    }) => TTools;
+}): TTools;
+
 /**
  * Handler function for custom actions that can be triggered by the AI agent
  */
-type HsafaActionHandler = (params: any, meta: {
+type HsafaActionHandler = (params: unknown, meta: {
     /** Name of the action being called */
     name: string;
     /** When the action is being triggered */
@@ -534,7 +619,7 @@ type HsafaActionHandler = (params: any, meta: {
     assistantMessageId?: string;
     /** ID of the current chat session */
     chatId?: string;
-}) => Promise<any> | any;
+}) => Promise<unknown> | unknown;
 /**
  * Configuration options for the Hsafa SDK
  */
@@ -553,15 +638,15 @@ interface HsafaContextValue extends HsafaConfig {
     /** Registered custom actions */
     actions: Map<string, HsafaActionHandler>;
     /** Registered custom components */
-    components: Map<string, React__default.ComponentType<any>>;
+    components: Map<string, React__default.ComponentType<Record<string, unknown>>>;
     /** Register a custom action handler */
     registerAction: (name: string, handler: HsafaActionHandler) => () => void;
     /** Unregister a custom action handler */
     unregisterAction: (name: string, handler?: HsafaActionHandler) => void;
     /** Register a custom component */
-    registerComponent: (name: string, component: React__default.ComponentType<any>) => () => void;
+    registerComponent: (name: string, component: React__default.ComponentType<Record<string, unknown>>) => () => void;
     /** Unregister a custom component */
-    unregisterComponent: (name: string, component?: React__default.ComponentType<any>) => void;
+    unregisterComponent: (name: string, component?: React__default.ComponentType<Record<string, unknown>>) => void;
     /** Global streaming state - true if any chat is streaming */
     isAnyStreaming: boolean;
     /** Set streaming state for a specific chat instance */
@@ -574,6 +659,12 @@ interface HsafaContextValue extends HsafaConfig {
     currentChatId?: string;
     /** Setter for current chat id */
     setCurrentChatId: (chatId: string) => void;
+    tools: Map<string, HsafaTool>;
+    uiComponents: Map<string, React__default.ComponentType<Record<string, unknown>>>;
+    registerTool: (name: string, tool: HsafaTool) => () => void;
+    unregisterTool: (name: string, tool?: HsafaTool) => void;
+    registerUIComponent: (name: string, component: React__default.ComponentType<Record<string, unknown>>) => () => void;
+    unregisterUIComponent: (name: string, component?: React__default.ComponentType<Record<string, unknown>>) => void;
 }
 /**
  * Props for the HsafaProvider component
@@ -581,6 +672,8 @@ interface HsafaContextValue extends HsafaConfig {
 interface HsafaProviderProps extends HsafaConfig {
     /** Child components that will have access to the Hsafa context */
     children: React__default.ReactNode;
+    tools?: Record<string, HsafaTool>;
+    uiComponents?: Record<string, React__default.ComponentType<Record<string, unknown>>>;
 }
 /**
  * Provider component that sets up the Hsafa context for the SDK.
@@ -593,7 +686,7 @@ interface HsafaProviderProps extends HsafaConfig {
  * </HsafaProvider>
  * ```
  */
-declare function HsafaProvider({ baseUrl, dir, theme, children }: HsafaProviderProps): react_jsx_runtime.JSX.Element;
+declare function HsafaProvider({ baseUrl, dir, theme, children, tools: initialTools, uiComponents: initialUIComponents }: HsafaProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the Hsafa context.
  * Must be used within a HsafaProvider.
@@ -936,4 +1029,4 @@ type FillResult = {
 };
 declare function FillActiveInput(value: any, options?: FillInputOptions): Promise<FillResult>;
 
-export { type Anchor, type Attachment, Button, type ButtonProps, type ChatMessage, type ChatMetadata, type ChatStorageAPI, ContentContainer, type ContentContainerProps, CursorController, type CustomToolUIRenderProps, type DomComponent, type EditProcessContent, FillActiveInput, type FillInputOptions, type FillResult, FloatingChatButton, type GetDomComponentsOptions, type GetDomComponentsResult, type GuideAction, type GuideCursorOptions, type GuideOptions, type GuideRunResult, type GuideStep, type GuideStepResult, type GuideTarget, type HsafaAgentAPI, HsafaChat, type HsafaChatProps, HsafaProvider, type HsafaTool, type MessageEditorAPI, type SavedChat, type UIComponentProps, type UseChatStorageConfig, type UseHsafaAgentConfig, type UseMessageEditorConfig, registry as componentRegistry, guideCursor as controlCursor, getDomComponents, guideCursor, useAutoScroll, useChatStorage, useFileUpload, useHsafa, useHsafaAgent, useMessageEditor };
+export { type Anchor, type Attachment, Button, type ButtonProps, type ChatArtifactResult, type ChatArtifactStatus, type ChatArtifactVersioningAPI, type ChatMessage, type ChatMetadata, type ChatStorageAPI, ContentContainer, type ContentContainerProps, CursorController, type CustomToolUIRenderProps, type DomComponent, type EditProcessContent, FillActiveInput, type FillInputOptions, type FillResult, FloatingChatButton, type GetDomComponentsOptions, type GetDomComponentsResult, type GuideAction, type GuideCursorOptions, type GuideOptions, type GuideRunResult, type GuideStep, type GuideStepResult, type GuideTarget, type HsafaActiveChatIdResult, type HsafaActiveChatIdSource, type HsafaAgentAPI, type HsafaArtifactStore, type HsafaArtifactStoreBackend, type HsafaArtifactStoreConfig, HsafaChat, type HsafaChatProps, HsafaProvider, type HsafaTool, type MessageEditorAPI, type SavedChat, type UIComponentProps, type UseChatArtifactOptions, type UseChatArtifactVersioningOptions, type UseChatStorageConfig, type UseHsafaActiveChatIdOptions, type UseHsafaAgentConfig, type UseMessageEditorConfig, registry as componentRegistry, guideCursor as controlCursor, createHsafaArtifactStore, getDomComponents, guideCursor, useAutoScroll, useChatArtifact, useChatArtifactVersioning, useChatStorage, useFileUpload, useHsafa, useHsafaActiveChatId, useHsafaAgent, useHsafaTools, useMessageEditor };