API ReferenceAICloud Clientchat

chat

Create a chat stream between the AI plugin and the Puck Cloud, and intercept chat requests made by the plugin.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      context: "We are Google",
    },
  });
}

Returns a Response object.

Args

Param	Example	Type	Status
`chatParams`	`{ config: {}, pageData: {} }`	ChatParams	Required
`cloudOptions`	`{ ai: {} }`	CloudOptions	-

Chat Params

Param	Example	Type	Status
`config`	`{ components: {} }`	Config	Required
`pageData`	`{ root: {}, content: [] }`	Data	Required
`messages`	`[]`	UIMessage[]	Required

`config`

The Puck config for the page. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    config: {
      components: {
        HeadingBlock: {
          fields: {
            title: { type: "text" },
          },
          render: ({ title }) => <h1>{title}</h1>,
        },
      },
    },
  });
}

`pageData`

The current page data. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    pageData: {
      root: { props: { title: "My page" } },
      content: [],
    },
  });
}

`messages`

The entire message history for the chat, as an array of AI SDK UIMessages. Automatically provided by the AI plugin, but can be modified if necessary.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat({
    ...body,
    messages: [
      {
        id: "message-id",
        role: "user",
        parts: [{ text: "Create a landing page about dogs" }],
      },
    ],
  });
}

Cloud Options

Param	Example	Type	Status
`ai.context`	`"We are Google"`	String	-
`ai.onFinish`	`({ totalCost }) => {}`	Function	-
`ai.tools`	`{}`	Object	-
`apiKey`	`"SECRET"`	String	-
`host`	`"https://www.example.com/api/"`	String	-

`ai.context`

Provide system context and instructions to the agent.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      context: "We are Google. Your job is to create Google landing pages.",
    },
  });
}

`ai.onFinish`

A callback triggered when the request is complete. Provides usage information.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      onFinish: ({ totalCost, tokenUsage }) => {
        console.log(`Used ${totalCost} credit`);
      },
    },
  });
}

OnFinish Params

Param	Example	Type
`totalCost`	`0.2`	number
`tokenUsage`	`{}`	Object

`totalCost`

A number representing the total cost of the request.

`tokenUsage`

An object containing a breakdown of token consumption:

inputTokens
outputTokens
totalTokens
reasoningTokens
cachedInputTokens

`ai.tools`

Define tools that enable the agent to execute functions on your server and retrieve data. The result of the tool will be factored into the request.

import { chat, tool } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    ai: {
      tools: {
        getProducts: tool({
          description: "Get a list of product codes",
          inputSchema: z.object(),
          execute: async () => {
            return [
              {
                name: "Google Maps",
                product_code: "maps",
              },
              {
                name: "Google Calendar",
                product_code: "calendar",
              },
            ];
          },
        }),
      },
    },
  });
}

`apiKey`

Set your API key. Will use the PUCK_API_KEY environment variable by default.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    apiKey: process.env.MY_PUCK_KEY,
  });
}

`host`

Set a custom Puck Cloud host.

import { chat } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  const body = await request.json();
 
  return chat(body, {
    host: "https://www.example.com/api",
  });
}

Installation

generate