@delmaredigital/payload-puck 0.6.14 → 0.6.15

package/README.md

@@ -2,9 +2,21 @@
 
 A PayloadCMS plugin for integrating [Puck](https://puckeditor.com) visual page builder. Build pages visually with drag-and-drop components while leveraging Payload's content management capabilities.
 
-[![Demo](https://img.shields.io/badge/Demo-Live-blue)](https://demo.delmaredigital.com)
-[![Starter Template](https://img.shields.io/badge/Starter-Template-green)](https://github.com/delmaredigital/dd-starter)
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdelmaredigital%2Fdd-starter&project-name=my-payload-site&build-command=pnpm%20run%20ci&env=PAYLOAD_SECRET,BETTER_AUTH_SECRET&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22productSlug%22%3A%22neon%22%2C%22integrationSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22blob%22%7D%5D)
+<p align="center">
+  <a href="https://demo.delmaredigital.com"><img src="https://img.shields.io/badge/Live_Demo-Try_It_Now-2ea44f?style=for-the-badge&logo=vercel&logoColor=white" alt="Live Demo - Try It Now"></a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/delmaredigital/dd-starter"><img src="https://img.shields.io/badge/Starter_Template-Use_This-blue?style=for-the-badge&logo=github&logoColor=white" alt="Starter Template - Use This"></a>
+</p>
+
+<p align="center">
+  <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdelmaredigital%2Fdd-starter&project-name=my-payload-site&build-command=pnpm%20run%20ci&env=PAYLOAD_SECRET,BETTER_AUTH_SECRET&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22productSlug%22%3A%22neon%22%2C%22integrationSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22blob%22%7D%5D"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="32"></a>
+</p>
+
+---
+
+## Documentation
+
+For additional documentation, visit: [https://deepwiki.com/delmaredigital/payload-puck](https://deepwiki.com/delmaredigital/payload-puck)
 
 ---
 

package/dist/ai/createAiApiRoutes.js

@@ -75,8 +75,10 @@
                         puckTools[name] = tool({
                             description: toolDef.description,
                             inputSchema: toolDef.inputSchema,
+                            outputSchema: toolDef.outputSchema,
                             execute: toolDef.execute,
-                            name: toolDef.name
+                            name: toolDef.name,
+                            mode: toolDef.mode
                         });
                     }
                 }
@@ -86,7 +88,8 @@
                     host: ai?.host,
                     ai: {
                         context: ai?.context,
-                        tools: Object.keys(puckTools).length > 0 ? puckTools : undefined
+                        tools: Object.keys(puckTools).length > 0 ? puckTools : undefined,
+                        onFinish: ai?.onFinish
                     }
                 });
             } catch (error) {

package/dist/ai/createAiGenerate.js

@@ -80,8 +80,10 @@
                 puckTools[name] = tool({
                     description: toolDef.description,
                     inputSchema: toolDef.inputSchema,
+                    outputSchema: toolDef.outputSchema,
                     execute: toolDef.execute,
-                    name: toolDef.name
+                    name: toolDef.name,
+                    mode: toolDef.mode
                 });
             }
         }
@@ -93,7 +95,8 @@
             apiKey: ai?.apiKey,
             host: ai?.host,
             pageData,
-            tools: Object.keys(puckTools).length > 0 ? puckTools : undefined
+            tools: Object.keys(puckTools).length > 0 ? puckTools : undefined,
+            onFinish: ai?.onFinish
         });
         if (!result) {
             throw new Error('AI generation failed: no result returned');

package/dist/ai/createAiPlugin.js

@@ -34,7 +34,7 @@
  * <PuckEditor plugins={[aiPlugin]} />
  * ```
  */ export function createAiPlugin(options = {}) {
-    const { host = '/api/puck', examplePrompts, onSubmit } = options;
+    const { host = '/api/puck', examplePrompts, onSubmit, prepareRequest, scrollTracking } = options;
     // Dynamic import to avoid build errors if plugin-ai not installed
     // Also allows for tree-shaking when AI is not used
     try {
@@ -45,7 +45,9 @@
             chat: {
                 examplePrompts,
                 onSubmit
-            }
+            },
+            prepareRequest,
+            scrollTracking
         });
     } catch (e) {
         // Return a placeholder plugin if @puckeditor/plugin-ai is not installed

package/dist/ai/types.d.ts

@@ -58,6 +58,18 @@ export interface AiTool<TInput = unknown, TOutput = unknown> {
      * Optional name for the tool
      */
     name?: string;
+    /**
+     * Controls how the tool interacts with the AI agent.
+     * - "auto": Agent decides when to use the tool (default)
+     * - "preload": Tool result is fetched before generation starts
+     * - "inline": Tool runs inline during generation
+     */
+    mode?: 'auto' | 'preload' | 'inline';
+    /**
+     * Optional output schema for the tool's return value.
+     * Must be a Zod schema.
+     */
+    outputSchema?: import('zod').ZodTypeAny;
 }
 /**
  * AI-specific configuration options for the server-side handler
@@ -97,6 +109,27 @@ export interface AiOptions {
      * Custom Puck Cloud host URL
      */
     host?: string;
+    /**
+     * Callback invoked when AI generation finishes.
+     * Provides usage metrics for cost tracking and analytics.
+     *
+     * @example
+     * ```typescript
+     * onFinish: ({ totalCost, tokenUsage }) => {
+     *   console.log(`Used ${tokenUsage.totalTokens} tokens, cost: ${totalCost}`)
+     * }
+     * ```
+     */
+    onFinish?: (result: {
+        totalCost: number;
+        tokenUsage: {
+            inputTokens: number | undefined;
+            outputTokens: number | undefined;
+            totalTokens: number | undefined;
+            reasoningTokens?: number | undefined;
+            cachedInputTokens?: number | undefined;
+        };
+    }) => void;
 }
 /**
  * AI configuration for a Puck field
@@ -140,6 +173,25 @@ export interface AiFieldConfig {
         type: string;
         [key: string]: unknown;
     };
+    /**
+     * Bind this field to a named tool. The tool runs during generation
+     * and its result populates this field deterministically.
+     *
+     * @example
+     * ```typescript
+     * fields: {
+     *   src: {
+     *     type: 'text',
+     *     ai: { bind: 'getImageUrl' },
+     *   },
+     * }
+     * ```
+     */
+    bind?: string;
+    /**
+     * Whether this field's value should be streamed during AI generation.
+     */
+    stream?: boolean;
 }
 /**
  * AI configuration for a Puck component
@@ -161,8 +213,21 @@ export interface AiComponentConfig {
      */
     instructions?: string;
     /**
-     * Custom JSON schema for the entire component.
-     * For when Puck can't infer from fields.
+     * Exclude this component from AI generation.
+     * The component remains available for manual use in the editor.
+     */
+    exclude?: boolean;
+    /**
+     * Controls which components are allowed/disallowed in the default slot zone
+     * during AI generation.
+     */
+    defaultZone?: {
+        allow?: string[];
+        disallow?: string[];
+        disabled?: boolean;
+    };
+    /**
+     * @deprecated Removed in Puck AI 0.4. Use field-level `schema` on `AiFieldConfig` instead.
      */
     schema?: {
         type: 'object';
@@ -319,6 +384,34 @@ export interface AiPluginOptions {
      * Callback when user submits a prompt
      */
     onSubmit?: (prompt: string) => void;
+    /**
+     * Intercept and modify outgoing AI requests before they are sent.
+     * Use this to add custom headers, credentials, or body data.
+     *
+     * @example
+     * ```typescript
+     * prepareRequest: (opts) => ({
+     *   ...opts,
+     *   headers: { ...opts.headers, Authorization: 'Bearer token' },
+     *   credentials: 'include',
+     * })
+     * ```
+     */
+    prepareRequest?: (opts: {
+        body?: {
+            chatId?: string;
+            trigger?: string;
+            [key: string]: any;
+        };
+        headers?: HeadersInit;
+        credentials?: RequestCredentials;
+    }) => any | Promise<any>;
+    /**
+     * Enable automatic scroll tracking during AI generation.
+     * When true, the editor scrolls to follow new content as it streams in.
+     * @default true (in @puckeditor/plugin-ai 0.4+)
+     */
+    scrollTracking?: boolean;
 }
 /**
  * AI configuration overrides for components
@@ -503,4 +596,18 @@ export interface PuckPluginAiConfig {
      * ```
      */
     componentInstructions?: ComponentAiOverrides;
+    /**
+     * Callback invoked when AI generation finishes.
+     * Provides usage metrics for cost tracking and analytics.
+     */
+    onFinish?: (result: {
+        totalCost: number;
+        tokenUsage: {
+            inputTokens: number | undefined;
+            outputTokens: number | undefined;
+            totalTokens: number | undefined;
+            reasoningTokens?: number | undefined;
+            cachedInputTokens?: number | undefined;
+        };
+    }) => void;
 }

package/dist/editor/PuckEditor.d.ts

@@ -177,6 +177,24 @@ export interface PuckEditorProps {
          * Users can click these to quickly send common prompts.
          */
         examplePrompts?: AiExamplePrompt[];
+        /**
+         * Intercept and modify outgoing AI requests before they are sent.
+         * Use this to add custom headers, credentials, or body data.
+         */
+        prepareRequest?: (opts: {
+            body?: {
+                chatId?: string;
+                trigger?: string;
+                [key: string]: any;
+            };
+            headers?: HeadersInit;
+            credentials?: RequestCredentials;
+        }) => any | Promise<any>;
+        /**
+         * Enable automatic scroll tracking during AI generation.
+         * @default true
+         */
+        scrollTracking?: boolean;
     };
     /**
      * Example prompts from plugin config.

package/dist/editor/PuckEditorImpl.client.d.ts

@@ -126,6 +126,16 @@ export interface PuckEditorImplProps {
     aiOptions?: {
         host?: string;
         examplePrompts?: AiExamplePrompt[];
+        prepareRequest?: (opts: {
+            body?: {
+                chatId?: string;
+                trigger?: string;
+                [key: string]: any;
+            };
+            headers?: HeadersInit;
+            credentials?: RequestCredentials;
+        }) => any | Promise<any>;
+        scrollTracking?: boolean;
     };
     /**
      * Whether the puck-ai-prompts collection is enabled.

package/dist/editor/PuckEditorImpl.client.js

@@ -532,7 +532,9 @@ import { useAiPrompts } from '../ai/hooks/useAiPrompts.js';
             host: aiOptions?.host || '/api/puck/ai',
             chat: {
                 examplePrompts: convertedPrompts.length > 0 ? convertedPrompts : undefined
-            }
+            },
+            prepareRequest: aiOptions?.prepareRequest,
+            scrollTracking: aiOptions?.scrollTracking
         });
     // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally omit prompt arrays to prevent recreation
     }, [

package/dist/endpoints/ai.d.ts

@@ -15,6 +15,19 @@ export interface AiEndpointOptions {
      * These allow AI to perform actions like database lookups, API calls, etc.
      */
     tools?: Record<string, AiTool>;
+    /**
+     * Callback invoked when AI generation finishes with usage metrics.
+     */
+    onFinish?: (result: {
+        totalCost: number;
+        tokenUsage: {
+            inputTokens: number | undefined;
+            outputTokens: number | undefined;
+            totalTokens: number | undefined;
+            reasoningTokens?: number | undefined;
+            cachedInputTokens?: number | undefined;
+        };
+    }) => void;
 }
 /**
  * Creates a Payload endpoint handler for Puck AI

package/dist/endpoints/ai.js

@@ -201,6 +201,8 @@ import { pagePatternSystemContext } from '../ai/presets/index.js';
                         name: tool.name,
                         description: tool.description,
                         inputSchema: tool.inputSchema,
+                        outputSchema: tool.outputSchema,
+                        mode: tool.mode,
                         // Wrap execute to inject Payload context
                         execute: (input)=>tool.execute(input, toolContext)
                     };
@@ -208,7 +210,10 @@ import { pagePatternSystemContext } from '../ai/presets/index.js';
                 aiOptions.tools = wrappedTools;
             }
             const response = await puckHandler(webRequest, {
-                ai: aiOptions,
+                ai: {
+                    ...aiOptions,
+                    onFinish: options.onFinish
+                },
                 apiKey
             });
             if (!response.ok) {

package/dist/plugin/index.js

@@ -293,7 +293,8 @@ import { createContextListHandler, createContextCreateHandler, createContextUpda
                     method: 'post',
                     handler: createAiEndpointHandler({
                         context: aiConfig.context,
-                        tools: aiConfig.tools
+                        tools: aiConfig.tools,
+                        onFinish: aiConfig.onFinish
                     })
                 }
             ] : [],

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.6.14";
+export declare const VERSION = "0.6.15";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.js - do not edit manually
-export const VERSION = '0.6.14';
+export const VERSION = '0.6.15';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-puck",
-  "version": "0.6.14",
+  "version": "0.6.15",
   "description": "Puck visual page builder plugin for Payload CMS",
   "type": "module",
   "license": "MIT",
@@ -141,36 +141,36 @@
     }
   },
   "dependencies": {
-    "@puckeditor/cloud-client": "^0.5.0",
-    "@puckeditor/plugin-ai": "^0.5.0",
+    "@puckeditor/cloud-client": "^0.6.0",
+    "@puckeditor/plugin-ai": "^0.6.0",
     "@puckeditor/plugin-heading-analyzer": "^0.21.1",
     "@radix-ui/react-popover": "^1.1.15",
-    "@tiptap/core": "^3.18.0",
-    "@tiptap/extension-color": "^3.18.0",
-    "@tiptap/extension-highlight": "^3.18.0",
-    "@tiptap/extension-link": "^3.18.0",
-    "@tiptap/extension-subscript": "^3.18.0",
-    "@tiptap/extension-superscript": "^3.18.0",
-    "@tiptap/extension-text-align": "^3.18.0",
-    "@tiptap/extension-text-style": "^3.18.0",
-    "@tiptap/extension-underline": "^3.18.0",
-    "@tiptap/react": "^3.18.0",
-    "@tiptap/starter-kit": "^3.18.0",
-    "html-react-parser": "^5.2.13",
+    "@tiptap/core": "^3.20.0",
+    "@tiptap/extension-color": "^3.20.0",
+    "@tiptap/extension-highlight": "^3.20.0",
+    "@tiptap/extension-link": "^3.20.0",
+    "@tiptap/extension-subscript": "^3.20.0",
+    "@tiptap/extension-superscript": "^3.20.0",
+    "@tiptap/extension-text-align": "^3.20.0",
+    "@tiptap/extension-text-style": "^3.20.0",
+    "@tiptap/extension-underline": "^3.20.0",
+    "@tiptap/react": "^3.20.0",
+    "@tiptap/starter-kit": "^3.20.0",
+    "html-react-parser": "^5.2.17",
     "lucide-react": "^0.469.0"
   },
   "devDependencies": {
-    "@payloadcms/next": "^3.73.0",
-    "@payloadcms/ui": "^3.73.0",
+    "@payloadcms/next": "^3.77.0",
+    "@payloadcms/ui": "^3.77.0",
     "@puckeditor/core": "^0.21.1",
     "@swc/cli": "^0.6.0",
     "@swc/core": "^1.15.11",
-    "@types/node": "^25.1.0",
-    "@types/react": "^19.2.10",
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "copyfiles": "^2.4.1",
     "next": "^16.1.6",
-    "payload": "^3.73.0",
+    "payload": "^3.77.0",
     "react": "^19.2.4",
     "typescript": "^5.9.3"
   },