@grapesjs/studio-sdk-plugins 1.0.33-rc.1 → 1.0.33

package/dist/aiChat/server/types.d.ts

@@ -1,8 +1,22 @@
 import { LanguageModelV3 } from '@ai-sdk/provider';
-import { ModelMessage, Tool, UIMessage, UIMessageStreamOptions, UIMessageStreamWriter, streamText } from 'ai';
-import { JSONSchema7 } from 'json-schema';
+import { FinishReason, LanguageModelUsage, Tool, UIMessage, UIMessageStreamOptions, UIMessageStreamWriter, streamText } from 'ai';
 import { ProjectContext } from '../types';
 export type StreamTextOptions = Parameters<typeof streamText>[0];
+/**
+ * Callback invoked when a streamText call finishes, useful for tracking LLM usage.
+ */
+export interface OnEndCallback {
+    (props: {
+        /** Token usage for this call. */
+        usage: LanguageModelUsage;
+        /** Reason the model stopped generating. */
+        finishReason: FinishReason;
+        /** Model used for this call. */
+        model: LanguageModelV3;
+        /** The agent code tool name, when the call originates from a built-in agent tool. */
+        toolName?: string;
+    }): void;
+}
 /**
  * Options for configuring an agent that generates code (e.g., add/edit components).
  */
@@ -12,9 +26,43 @@ export interface AgentCodeOptions {
      */
     model: LanguageModelV3;
     /**
-     * Project context containing information about the current project
+     * Additional stream text options passed to the agent's internal streamText calls
      */
-    projectContext: ProjectContext;
+    streamOptions?: Partial<Omit<StreamTextOptions, 'model' | 'system' | 'prompt' | 'abortSignal' | 'toolChoice' | 'messages' | 'tools' | 'onToolCall'>>;
+}
+/**
+ * Return type of createToolStatusWriter function
+ */
+export interface ToolStatusWriter {
+    /** Write in-progress status when tool starts */
+    start(): void;
+    /** Write streaming status with content chunk */
+    update(content: string, props?: {
+        replace?: boolean;
+    }): void;
+    /** Write done status */
+    done(): void;
+    /** Write complete status (persisted) with metadata */
+    complete(metadata: Record<string, unknown>): void;
+    /** Write error status */
+    error(err: unknown): void;
+}
+/**
+ * Options for creating a tool status writer
+ */
+export interface CreateToolStatusWriterOptions {
+    writer: UIMessageStreamWriter;
+    /** The tool call ID from ToolExecutionOptions */
+    toolCallId: string;
+    /** The name of the tool */
+    name: string;
+    /** The input passed to the tool */
+    input: unknown;
+}
+/**
+ * Options for creating a tool status writer
+ */
+export interface CreateToolStatusWriterOptionsFactory extends Omit<CreateToolStatusWriterOptions, 'writer'> {
 }
 /**
  * Options passed to the tools callback function
@@ -32,6 +80,37 @@ export interface ToolsCallbackOptions {
      * Abort signal passed from the request, useful for cancelling long-running tool operations
      */
     abortSignal?: AbortSignal;
+    /**
+     * Create a tool status writer for sending progress updates.
+     * Use this in custom tool execute functions to report status.
+     *
+     * @example
+     * ```ts
+     * execute: async (input, { toolCallId }) => {
+     *   const statusWriter = createToolStatusWriter({ toolCallId, name: 'myTool', input });
+     *   statusWriter.writeStart();
+     *   try {
+     *     // ... do work ...
+     *     statusWriter.writeDone();
+     *     return result;
+     *   } catch (err) {
+     *     statusWriter.writeError(err);
+     *     throw err;
+     *   }
+     * }
+     * ```
+     */
+    createToolStatusWriter: (options: CreateToolStatusWriterOptionsFactory) => ToolStatusWriter;
+}
+export interface ChatSystemPrompt {
+    /**
+     * Initial part of the system prompt that sets the overall context and instructions for the AI assistant.
+     */
+    preamble?: string;
+    /**
+     * Additional instructions or information that can be appended to the system prompt.
+     */
+    postamble?: string;
 }
 /**
  * Options for creating a streaming response
@@ -42,13 +121,17 @@ export interface CreateStreamResponseOptions extends Pick<StreamTextOptions, 'to
      */
     model: LanguageModelV3;
     /**
-     * Messages from the conversation
+     * Messages from the UI conversation
      */
     messages: UIMessage[];
+    /**
+     * Project context containing information about the current project
+     */
+    projectContext: ProjectContext;
     /**
      * System prompt for the chat
      */
-    systemPrompt?: string;
+    systemPrompt?: string | ChatSystemPrompt;
     /**
      * Abort signal for cancelling the stream and tool operations
      */
@@ -65,11 +148,6 @@ export interface CreateStreamResponseOptions extends Pick<StreamTextOptions, 'to
      * @see https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data
      */
     tools?: Record<string, Tool> | ((options: ToolsCallbackOptions) => Record<string, Tool>);
-    /**
-     * Image URLs to add to the last user message
-     * These will be formatted as image content parts for vision models
-     */
-    imageUrls?: string[];
     /**
      * Additional stream text options
      */
@@ -78,6 +156,25 @@ export interface CreateStreamResponseOptions extends Pick<StreamTextOptions, 'to
      * Additional response options
      */
     responseOptions?: Partial<UIMessageStreamOptions<UIMessage>>;
+    /**
+     * Whether to prune messages before sending to the model.
+     * When true (default), removes reasoning/tool calls from older messages to reduce token usage.
+     * @default true
+     * @see https://ai-sdk.dev/docs/reference/ai-sdk-ui/prune-messages
+     */
+    pruneMessages?: boolean;
+    /**
+     * Callback invoked when a stream call finishes (including built-in agent code tools).
+     * Useful for tracking LLM model usage.
+     */
+    onEnd?: OnEndCallback;
+    /**
+     * Extract metadata to attach to each message.
+     * Called on `start` and `finish` stream events.
+     */
+    getMessageMetadata?: (options: Parameters<NonNullable<UIMessageStreamOptions<UIMessage>['messageMetadata']>>[0] & {
+        model: LanguageModelV3;
+    }) => ReturnType<NonNullable<UIMessageStreamOptions<UIMessage>['messageMetadata']>>;
 }
 /**
  * Options for creating a text streaming response (using toTextStreamResponse)
@@ -105,61 +202,8 @@ export interface CreateStreamTextResponseOptions extends Pick<StreamTextOptions,
      */
     streamOptions?: Partial<Omit<StreamTextOptions, 'toolChoice' | 'providerOptions' | 'model' | 'system' | 'prompt' | 'messages' | 'tools' | 'abortSignal' | 'onFinish' | 'onAbort' | 'onError'>>;
 }
-export interface StreamFinishResult {
-    text: string;
-    usage: {
-        promptTokens: number;
-        completionTokens: number;
-        totalTokens: number;
-    };
-    model: string;
-    /**
-     * Uses AI SDK's official type to ensure compatibility
-     * Extracted from streamText's onFinish callback parameter type
-     */
-    finishReason: Parameters<NonNullable<Parameters<typeof streamText>[0]['onFinish']>>[0]['finishReason'];
-    toolCalls?: ToolCallInfo[];
-}
-export interface ToolCallInfo {
-    toolCallId: string;
-    toolName: string;
-    args: Record<string, unknown>;
-}
 export interface CreateModelOptions {
     apiKey?: string;
     baseURL?: string;
     [key: string]: unknown;
 }
-export interface ToolDefinition<TArgs = Record<string, unknown>, TResult = unknown> {
-    description: string;
-    /**
-     * JSON schema for the tool's input parameters (ai-sdk v6)
-     */
-    inputSchema: JSONSchema7;
-    execute?: (args: TArgs, context: ToolExecuteContext) => Promise<TResult>;
-}
-export interface ToolExecuteContext {
-    toolCallId: string;
-    messages: ModelMessage[];
-    abortSignal?: AbortSignal;
-}
-/**
- * Options for creating the chat system prompt
- */
-export interface CreateSystemPromptChatOptions {
-    /**
-     * Project context from the client
-     */
-    projectContext?: ProjectContext;
-}
-export interface PromptConfig {
-    currentSiteCode?: string;
-    currentSelectedCode?: string;
-    userPrompt?: string;
-    projectType?: 'web' | 'email';
-    globalStyles?: string;
-    devices?: ProjectContext['devices'];
-    availablePages?: ProjectContext['availablePages'];
-    installedPlugins?: ProjectContext['installedPlugins'];
-    imageUrls?: string[];
-}

package/dist/aiChat/types.d.ts

@@ -1,13 +1,13 @@
-import { UIMessage, useChat, UseChatHelpers } from '@ai-sdk/react';
-import { ChatInit, HttpChatTransportInitOptions } from 'ai';
-import { Editor } from 'grapesjs';
-import { ReactNode, CSSProperties } from 'react';
-import { PluginWithInit, SDKPluginOptions } from '../utils';
-import { AiChatHeaderProps } from './components/AiChatHeader';
-import { AiChatInputProps } from './components/AiChatInput';
+import { Chat, UIMessage, useChat, UseChatHelpers } from '@ai-sdk/react';
+import { ChatInit, DynamicToolUIPart, HttpChatTransportInitOptions, ToolUIPart } from 'ai';
+import { Component, Editor } from 'grapesjs';
+import { LicenseCheckResult } from '../utils';
+import { StudioLayoutComponentsConfig } from '../types';
+import { AiChatLayoutComponentsRegistryEntries } from './components/index';
+import { ToolStatusProgressMap } from './clientToolsProcessors';
+import { AiChatOptions as AiChatOptionsSchema, CommonComponentPropsSchema } from './typesSchema';
 /**
  * ChatMessage is a direct alias of AI SDK's UIMessage
- * This keeps us aligned with AI SDK types - we only extend when necessary
  */
 export type ChatMessage = UIMessage;
 /**
@@ -38,6 +38,11 @@ export declare enum AvailablePanels {
     IMPORT_HTML = "importHTML",
     PREVIEW = "preview"
 }
+export declare enum AiChatCommands {
+    getChatManager = "aiChat:getChatManager",
+    getChatState = "aiChat:getChatState",
+    getChatApi = "aiChat:getChatApi"
+}
 export interface AiChatToolsArguments {
     [AiChatToolName.ADD_NEW_COMPONENT]: {
         name: string;
@@ -90,12 +95,19 @@ export interface ProjectContext {
         content?: string;
     };
     /**
-     * Selected component information
+     * Last selected component information
      */
     selectedComponent?: {
         id: string;
         content: string;
     };
+    /**
+     * Selected components
+     */
+    selectedComponents: {
+        id: string;
+        content: string;
+    }[];
     /**
      * Project type (web, email, etc.)
      */
@@ -133,9 +145,9 @@ export interface ProjectContext {
      */
     isEmail: boolean;
     /**
-     * Is this a new project (no existing content).
+     * Indicates if the project is empty.
      */
-    isNewProject?: boolean;
+    isNewProject: boolean;
     /**
      * Image URLs associated with the project
      */
@@ -149,17 +161,34 @@ export interface ChatRequestBody {
     userPrompt: string;
     [key: string]: unknown;
 }
-export interface ChatContext extends Pick<UseChatHelpers<UIMessage>, 'id' | 'setMessages' | 'messages' | 'sendMessage' | 'status' | 'stop' | 'addToolApprovalResponse' | 'addToolOutput' | 'clearError' | 'error'> {
+export interface ChatContext extends Pick<UseChatHelpers<UIMessage>, 'id' | 'setMessages' | 'messages' | 'sendMessage' | 'status' | 'stop' | 'addToolApprovalResponse' | 'addToolOutput' | 'clearError' | 'error'>, Pick<ChatState, 'toolStatusProgress' | 'contextComponents'> {
     setError: (error: Error | string | undefined) => void;
 }
+export interface AiChatMessageLayoutProps {
+    editor: Editor;
+    chatContext: ChatContext;
+    message: UIMessage;
+}
+export interface AiChatMessagePartLayoutProps extends AiChatMessageLayoutProps {
+    part: ChatMessage['parts'][0];
+    partIndex: number;
+}
+export interface AiChatMessageToolDetailLayoutProps extends AiChatMessagePartLayoutProps {
+    part: ToolUIPart | DynamicToolUIPart;
+    toolName: string;
+}
 /**
  * Client-side tool definition
  */
-export interface AiChatClientTool<Args extends Record<string, unknown> = any> {
+export interface AiChatClientTool<TInput extends Record<string, unknown> = any> {
     /**
      * Execute the tool on the client side
      */
-    execute: (args: Args, context: AiChatToolContext) => Promise<string | Record<string, unknown>>;
+    execute?: (input: TInput, context: AiChatToolContext) => Promise<string | Record<string, unknown>>;
+    /**
+     * Custom layout for tool in the message.
+     */
+    layoutToolResult?: (props: AiChatMessageToolDetailLayoutProps) => StudioLayoutComponentsConfig | undefined | void;
 }
 /**
  * Context passed to client-side tools
@@ -187,82 +216,77 @@ export type AiChatToolsFn = (props: {
     editor: Editor;
 }) => AiChatTools;
 /**
- * API endpoints for built-in tools that make sub-calls
+ * Props for custom message component
  */
-export interface AiChatToolApis {
-    /**
-     * Endpoint for adding new components
-     * @default '/api/ai/add-component-stream'
-     */
-    addComponent?: string;
-    /**
-     * Endpoint for editing components
-     * @default '/api/ai/edit-component-stream'
-     */
-    editComponent?: string;
+export interface AiChatMessageProps {
+    editor: Editor;
+    message: UIMessage;
+    isStreaming?: boolean;
+}
+export interface AiChatSuggestion {
     /**
-     * Endpoint for adding new pages
-     * @default '/api/ai/add-page-stream'
+     * Unique identifier for the suggestion. Used as i18n key suffix.
      */
-    addPage?: string;
+    id: string;
     /**
-     * Endpoint for generating projects
-     * @default '/api/ai/generate-project-stream'
+     * Label to display if i18n key is not found.
      */
-    generateProject?: string;
+    label?: string;
     /**
-     * Endpoint for scraping websites
-     * @default '/api/ai/scrape-website'
+     * Prompt to send when clicked. If not provided, uses the resolved label.
      */
-    scrapeWebsite?: string;
+    prompt?: string;
 }
 /**
- * Props for custom message component
+ * Props for custom empty state component
  */
-export interface AiChatMessageProps {
+export interface AiChatEmptyStateProps {
     editor: Editor;
-    message: ChatMessage;
-    isStreaming?: boolean;
+    onSuggestionClick?: (suggestion: string) => void;
 }
 /**
- * Props for custom empty state component
+ * Context passed to layout component customizers
  */
-export interface AiChatEmptyStateProps {
+export interface LayoutComponentContext<T> {
     editor: Editor;
-    onSuggestionClick?: (suggestion: string) => void;
+    props: Omit<T, 'chatContext' | 'type'>;
 }
+type CustomLayoutComponentPropsFn<T> = (props: LayoutComponentContext<T>) => Partial<Omit<T, 'chatContext' | 'type'>>;
 /**
  * Customizable layout components
+ * @example
+ * layoutComponents: {
+ *   aiChatInput: ({ editor, props }) => ({
+ *     ...props,
+ *     maxImages: 3,
+ *   })
+ * }
  */
 export interface AiChatLayoutComponents {
     /**
-     * Custom message component
+     * Custom aiChatInput component props
      */
-    chatMessage?: (props: AiChatMessageProps) => {
-        type: 'custom';
-        component: () => ReactNode;
-    };
+    aiChatInput?: CustomLayoutComponentPropsFn<AiChatLayoutComponentsRegistryEntries['aiChatInput']>;
     /**
-     * Custom input component
+     * Custom aiChatMessage component props
      */
-    chatInput?: (props: AiChatInputProps) => {
-        type: 'custom';
-        component: () => ReactNode;
-    };
+    aiChatMessage?: CustomLayoutComponentPropsFn<AiChatLayoutComponentsRegistryEntries['aiChatMessage']>;
     /**
-     * Custom header component
+     * Custom aiChatLoadingState component props
      */
-    chatHeader?: (props: AiChatHeaderProps) => {
-        type: 'custom';
-        component: () => ReactNode;
-    };
+    aiChatLoadingState?: CustomLayoutComponentPropsFn<AiChatLayoutComponentsRegistryEntries['aiChatLoadingState']>;
     /**
-     * Custom empty state component
+     * Custom aiChatHeader component props
      */
-    chatEmptyState?: (props: AiChatEmptyStateProps) => {
-        type: 'custom';
-        component: () => ReactNode;
-    };
+    aiChatHeader?: CustomLayoutComponentPropsFn<AiChatLayoutComponentsRegistryEntries['aiChatHeader']>;
+    /**
+     * Custom aiChatError component props
+     */
+    aiChatError?: CustomLayoutComponentPropsFn<AiChatLayoutComponentsRegistryEntries['aiChatError']>;
+    /**
+     * Custom aiChatEmptyState component props
+     */
+    aiChatEmptyState?: CustomLayoutComponentPropsFn<AiChatLayoutComponentsRegistryEntries['aiChatEmptyState']>;
 }
 export type ChatOptions = Partial<Omit<Parameters<typeof useChat>[0], 'api' | 'transport'>>;
 /**
@@ -276,19 +300,16 @@ export interface UploadedAsset {
     size: number;
     type?: string;
 }
-export interface CommonComponentProps {
+export interface CommonComponentProps extends CommonComponentPropsSchema {
     editor: Editor;
     chatContext: ChatContext;
-    className?: string;
-    style?: CSSProperties;
 }
 /**
  * AI Chat plugin options
  */
-export interface AiChatOptions extends SDKPluginOptions {
+export interface AiChatOptions extends Omit<AiChatOptionsSchema, 'getAccessToken' | 'chatOptions' | 'chatApi' | 'tools' | 'onTool' | 'layoutComponents' | 'messages' | 'onMessagesUpdate' | 'body'> {
     /**
      * Custom endpoint for the chat API
-     * @default '/api/ai/chat'
      */
     chatApi?: string | (() => string);
     /**
@@ -310,36 +331,34 @@ export interface AiChatOptions extends SDKPluginOptions {
      */
     onTool?: ChatInit<UIMessage>['onToolCall'];
     /**
-     * Customize API endpoints for built-in tools
-     */
-    toolApis?: AiChatToolApis;
-    /**
-     * Customize layout components
+     * Customize UI layout component props
+     * layoutComponents: {
+     *  aiChatInput: () => ({
+     *    maxImages: 3,
+     *  }),
+     * }
      */
     layoutComponents?: AiChatLayoutComponents;
     /**
      * Initial messages or async function to load messages
      * @example
-     * // Static messages
-     * messages: [{ id: '1', role: 'user', content: 'Hello' }]
      * // Dynamic loading
-     * messages: async ({ editor }) => {
-     *   const msgs = await loadFromDatabase();
-     *   return msgs;
+     * messages: async () => {
+     *   return await loadFromDatabase();
      * }
      */
-    messages?: ChatMessage[] | ((props: {
+    messages?: UIMessage[] | ((props: {
         editor: Editor;
-    }) => Promise<ChatMessage[]>);
+    }) => Promise<UIMessage[]>);
     /**
      * Callback when messages are updated (for persistence)
      * @example
-     * onMessagesUpdate: async ({ messages, editor }) => {
+     * onMessagesUpdate: async ({ messages }) => {
      *   await saveToDatabase(messages);
      * }
      */
     onMessagesUpdate?: (props: {
-        messages: ChatMessage[];
+        messages: UIMessage[];
         editor: Editor;
     }) => void | Promise<void>;
     /**
@@ -351,36 +370,40 @@ export interface AiChatOptions extends SDKPluginOptions {
         messages: UIMessage[];
     }) => Record<string, unknown>);
     /**
-     * Custom suggestions to show
-     */
-    suggestions?: string[];
-    /**
-     * Maximum number of images per message. Set to 0 to disable images.
-     * @default 5
-     */
-    maxImages?: number;
-    /**
-     * Upload project assets (images) to server
-     * Consumer must implement this function to handle file uploads
+     * Additional chat options.
+     * Refer to https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat
      * @example
-     * uploadProjectAssets: async ({ files }) => {
-     *   const uploaded = await uploadToServer(files);
-     *   return uploaded.map(asset => ({ id: asset.id, src: asset.url, ... }));
+     * chatOptions: {
+     *  onData: data => console.log('onData:', data),
+     *  onError: error => console.log('onError:', error),
+     *  onFinish: result => console.log('onFinish:', result)
      * }
      */
-    uploadProjectAssets?: (props: {
-        files: File[];
-    }) => Promise<UploadedAsset[]>;
-    /**
-     * Additional chat options for ai-sdk
-     * Uses AI SDK's UseChatOptions directly to stay aligned with their interface
-     * @see https://ai-sdk.dev/docs/ai-sdk-ui/chatbot
-     */
     chatOptions?: Partial<ChatInit<UIMessage>>;
     /**
      * Default transport options for chat API calls
      */
     defaultTransportOptions?: Partial<Omit<HttpChatTransportInitOptions<UIMessage>, 'prepareSendMessagesRequest'>>;
+    /**
+     * Function to get the access token
+     * @example
+     * getAccessToken: async () => {
+     *   const response = await fetch('/api/access-tokens');
+     *   const result = await response.json();
+     *   return result;
+     * }
+     */
+    getAccessToken?: () => Promise<AccessTokenData>;
+}
+export interface AccessTokenData {
+    accessToken: string;
+    expiresAt?: string;
+}
+export interface AccessTokenStore {
+    accessToken: string;
+    timeout?: NodeJS.Timeout;
+    license?: LicenseCheckResult;
+    getAccessToken?: () => Promise<AccessTokenData>;
 }
 export interface ToolDataAddComponentCommon {
     name: typeof ChatToolAgentCode.ADD_COMPONENT_CODE;
@@ -463,8 +486,25 @@ export interface ToolDataAddProjectPage {
     data: ToolDataAddProjectPageStreaming | ToolDataAddProjectPageDone | ToolDataAddProjectPageError;
 }
 export type ToolDataTypes = ToolDataAddComponent | ToolDataEditComponent | ToolDataAddPage | ToolDataAddProjectPage;
-/**
- * Plugin with init method
- */
-export interface SDKPluginWithAiChat extends PluginWithInit<AiChatOptions> {
-}
+export interface ChatApi {
+    readonly messages: UIMessage[];
+    readonly lastMessage: UIMessage | undefined;
+    readonly status: Chat<UIMessage>['status'];
+    readonly error: Error | undefined;
+    sendMessage: Chat<UIMessage>['sendMessage'];
+    setMessages: (messages: UIMessage[]) => void;
+    clearError: () => void;
+    stop: () => Promise<void>;
+    setError: (error: Error | string) => void;
+}
+export interface ChatState {
+    chat: Chat<UIMessage>;
+    chatApi: ChatApi;
+    isMessagesLoaded: boolean;
+    toolStatusProgress: ToolStatusProgressMap;
+    toolAbortControllers: Set<AbortController>;
+    contextComponents: Set<Component>;
+    onUpdate: (listener: () => void) => () => void;
+    emitUpdate: () => void;
+}
+export {};