@puckeditor/plugin-ai 0.9.0-canary.e2b15643 → 0.9.0-canary.e72fdf32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,8 +1,9 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode } from 'react';
3
3
  import * as react_jsx_runtime from 'react/jsx-runtime';
4
+ import * as ai from 'ai';
5
+ import { LanguageModelUsage, UIMessage, DataUIPart, ChatOnFinishCallback, CreateUIMessage, ChatStatus } from 'ai';
4
6
  import { PuckAction, Data, Config } from '@puckeditor/core';
5
- import { LanguageModelUsage, UIMessage, CreateUIMessage, DataUIPart, ChatStatus, ChatOnFinishCallback } from 'ai';
6
7
 
7
8
  type _JSONSchema = boolean | JSONSchema;
8
9
  type JSONSchema = {
@@ -203,6 +204,20 @@ type SubagentEvent = {
203
204
  kind: "finish";
204
205
  toolCallId: string;
205
206
  };
207
+ /** A request for data from the agent. */
208
+ type ClientRequest = {
209
+ requestId: string;
210
+ action: "getPageData";
211
+ params: {
212
+ id: string;
213
+ };
214
+ } | {
215
+ requestId: string;
216
+ action: "takeScreenshot";
217
+ params: {
218
+ putUrl: string;
219
+ };
220
+ };
206
221
  type PuckDataParts = {
207
222
  "new-chat-created": {
208
223
  chatId: string;
@@ -219,11 +234,7 @@ type PuckDataParts = {
219
234
  input: any;
220
235
  }[];
221
236
  };
222
- "client-request": {
223
- requestId: string;
224
- action: string;
225
- params?: Record<string, any>;
226
- };
237
+ "client-request": ClientRequest;
227
238
  "send-screenshot": {
228
239
  id: string;
229
240
  urls: {
@@ -261,6 +272,96 @@ type RequestOptions = {
261
272
  headers?: HeadersInit;
262
273
  credentials?: RequestCredentials;
263
274
  };
275
+ type UsePuckAiOptions = {
276
+ /** The API host to call. This should be your server. */
277
+ host?: string;
278
+ /**
279
+ * The mode used for generating the page. Can be `"assembly"` (default),
280
+ * to generate pages based on the provided components, or `"design"`, to
281
+ * design new components, incorporating existing components where possible.
282
+ */
283
+ mode?: Mode;
284
+ apiVersion?: string;
285
+ /**
286
+ * A callback to customize every request the hook makes before it's sent,
287
+ * such as to add custom headers, add metadata to the body, or change
288
+ * credentials.
289
+ */
290
+ prepareRequest?: (opts: RequestOptions) => RequestOptions | Promise<RequestOptions>;
291
+ /** A function called when a chat turn finishes. */
292
+ onFinish?: ChatOnFinishCallback<PuckMessage>;
293
+ /** A function called when a chat turn fails. `generate` rejects instead. */
294
+ onError?: (error: Error) => void;
295
+ };
296
+ type SendMessageOptions = {
297
+ /** Overrides the hook's `mode` for this turn. */
298
+ mode?: Mode;
299
+ /** Files to send with the prompt, as AI SDK file parts. */
300
+ files?: Extract<PuckMessage["parts"][number], {
301
+ type: "file";
302
+ }>[];
303
+ };
304
+ type GenerateOptions = {
305
+ /**
306
+ * The mode for this generation. `"design"` needs
307
+ * `ai.designMode.allowed` on the handler.
308
+ */
309
+ mode?: Mode;
310
+ /** An `AbortSignal` that cancels the generation. */
311
+ signal?: AbortSignal;
312
+ };
313
+ /**
314
+ * AI Parts represent discrete chunks of data sent by Puck AI. They are
315
+ * produced via `generate`'s `onPart` callback.
316
+ */
317
+ type AIPart = DataUIPart<PuckDataParts>;
318
+ type ApplyPartOptions = {
319
+ /**
320
+ * Whether to record the page as one undo step, covering every change since
321
+ * the last one recorded. Defaults to `false`.
322
+ */
323
+ recordHistory?: boolean;
324
+ };
325
+ /**
326
+ * Access Puck AI's internal behavior to create your own agent UI, or implement Puck AI as a client subagent.
327
+ *
328
+ * @param options.host The API host to call. This should be your server.
329
+ * @param options.mode The mode used for generating the page: `"assembly"` (default) or `"design"`.
330
+ * @param options.apiVersion The Puck Cloud API version. Defaults to `v2`.
331
+ * @param options.prepareRequest A callback to customize every request the hook makes before it's sent.
332
+ * @param options.onFinish A function called when a chat turn finishes.
333
+ * @param options.onError A function called when a chat turn fails. `generate` rejects instead.
334
+ * @returns An object containing `chat`, `generate` and `applyPart`.
335
+ */
336
+ declare function usePuckAi(options?: UsePuckAiOptions): {
337
+ chat: {
338
+ /** Send a new message to the agent. */
339
+ sendMessage: (prompt: string, opts?: SendMessageOptions) => Promise<void>;
340
+ /** Run the conversation's last turn again. */
341
+ regenerate: (args_0?: ({
342
+ messageId?: string;
343
+ } & ai.ChatRequestOptions) | undefined) => Promise<void>;
344
+ /** Stop the running turn. */
345
+ stop: () => Promise<void>;
346
+ /** The conversation's AI SDK status. */
347
+ status: ai.ChatStatus;
348
+ /** The last chat error's message, or `undefined`. Also passed to `onError`. */
349
+ error: string | undefined;
350
+ /** The conversation, as AI SDK `UIMessage`s. */
351
+ messages: PuckMessage[];
352
+ /** The live progress of the agent's tools, keyed by tool call id. */
353
+ toolStatus: Record<string, ToolStatus>;
354
+ };
355
+ /**
356
+ * Run a generation against the current page. Returns the page's Data once
357
+ * it's applied. Iterates once, unless the handler's `ai.maxIterations`
358
+ * allows more.
359
+ */
360
+ generate: (prompt: string, opts?: GenerateOptions) => Promise<Data>;
361
+ /** Apply and process an AI Part. */
362
+ applyPart: (part: AIPart, { recordHistory }?: ApplyPartOptions) => Promise<void>;
363
+ };
364
+
264
365
  type AiPluginProps = {
265
366
  host?: string;
266
367
  chat?: {
@@ -306,7 +407,15 @@ declare global {
306
407
  }
307
408
  }
308
409
 
410
+ /**
411
+ * Add a page's designed components to a config, to render the page.
412
+ *
413
+ * @param config Your Puck config.
414
+ * @param data The page, with its designed components in `root.props._dynamicConfig`.
415
+ * @returns The config, with the page's designed components and globals.
416
+ */
309
417
  declare function withDynamicConfig<UserConfig extends Config>(config: UserConfig, data: Data): UserConfig;
418
+
310
419
  declare function createAiPlugin(opts?: AiPluginProps): {
311
420
  label: string;
312
421
  name: string;
@@ -363,4 +472,4 @@ declare module "@puckeditor/core" {
363
472
  }
364
473
  }
365
474
 
366
- export { type AiDictionaryKey, type ComponentAiParams, type FieldAiParams, createAiPlugin, defaultDictionary, withDynamicConfig };
475
+ export { type AIPart, type AiDictionaryKey, type ApplyPartOptions, type ComponentAiParams, type FieldAiParams, type GenerateOptions, type SendMessageOptions, type UsePuckAiOptions, createAiPlugin, defaultDictionary, usePuckAi, withDynamicConfig };
package/dist/index.d.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode } from 'react';
3
3
  import * as react_jsx_runtime from 'react/jsx-runtime';
4
+ import * as ai from 'ai';
5
+ import { LanguageModelUsage, UIMessage, DataUIPart, ChatOnFinishCallback, CreateUIMessage, ChatStatus } from 'ai';
4
6
  import { PuckAction, Data, Config } from '@puckeditor/core';
5
- import { LanguageModelUsage, UIMessage, CreateUIMessage, DataUIPart, ChatStatus, ChatOnFinishCallback } from 'ai';
6
7
 
7
8
  type _JSONSchema = boolean | JSONSchema;
8
9
  type JSONSchema = {
@@ -203,6 +204,20 @@ type SubagentEvent = {
203
204
  kind: "finish";
204
205
  toolCallId: string;
205
206
  };
207
+ /** A request for data from the agent. */
208
+ type ClientRequest = {
209
+ requestId: string;
210
+ action: "getPageData";
211
+ params: {
212
+ id: string;
213
+ };
214
+ } | {
215
+ requestId: string;
216
+ action: "takeScreenshot";
217
+ params: {
218
+ putUrl: string;
219
+ };
220
+ };
206
221
  type PuckDataParts = {
207
222
  "new-chat-created": {
208
223
  chatId: string;
@@ -219,11 +234,7 @@ type PuckDataParts = {
219
234
  input: any;
220
235
  }[];
221
236
  };
222
- "client-request": {
223
- requestId: string;
224
- action: string;
225
- params?: Record<string, any>;
226
- };
237
+ "client-request": ClientRequest;
227
238
  "send-screenshot": {
228
239
  id: string;
229
240
  urls: {
@@ -261,6 +272,96 @@ type RequestOptions = {
261
272
  headers?: HeadersInit;
262
273
  credentials?: RequestCredentials;
263
274
  };
275
+ type UsePuckAiOptions = {
276
+ /** The API host to call. This should be your server. */
277
+ host?: string;
278
+ /**
279
+ * The mode used for generating the page. Can be `"assembly"` (default),
280
+ * to generate pages based on the provided components, or `"design"`, to
281
+ * design new components, incorporating existing components where possible.
282
+ */
283
+ mode?: Mode;
284
+ apiVersion?: string;
285
+ /**
286
+ * A callback to customize every request the hook makes before it's sent,
287
+ * such as to add custom headers, add metadata to the body, or change
288
+ * credentials.
289
+ */
290
+ prepareRequest?: (opts: RequestOptions) => RequestOptions | Promise<RequestOptions>;
291
+ /** A function called when a chat turn finishes. */
292
+ onFinish?: ChatOnFinishCallback<PuckMessage>;
293
+ /** A function called when a chat turn fails. `generate` rejects instead. */
294
+ onError?: (error: Error) => void;
295
+ };
296
+ type SendMessageOptions = {
297
+ /** Overrides the hook's `mode` for this turn. */
298
+ mode?: Mode;
299
+ /** Files to send with the prompt, as AI SDK file parts. */
300
+ files?: Extract<PuckMessage["parts"][number], {
301
+ type: "file";
302
+ }>[];
303
+ };
304
+ type GenerateOptions = {
305
+ /**
306
+ * The mode for this generation. `"design"` needs
307
+ * `ai.designMode.allowed` on the handler.
308
+ */
309
+ mode?: Mode;
310
+ /** An `AbortSignal` that cancels the generation. */
311
+ signal?: AbortSignal;
312
+ };
313
+ /**
314
+ * AI Parts represent discrete chunks of data sent by Puck AI. They are
315
+ * produced via `generate`'s `onPart` callback.
316
+ */
317
+ type AIPart = DataUIPart<PuckDataParts>;
318
+ type ApplyPartOptions = {
319
+ /**
320
+ * Whether to record the page as one undo step, covering every change since
321
+ * the last one recorded. Defaults to `false`.
322
+ */
323
+ recordHistory?: boolean;
324
+ };
325
+ /**
326
+ * Access Puck AI's internal behavior to create your own agent UI, or implement Puck AI as a client subagent.
327
+ *
328
+ * @param options.host The API host to call. This should be your server.
329
+ * @param options.mode The mode used for generating the page: `"assembly"` (default) or `"design"`.
330
+ * @param options.apiVersion The Puck Cloud API version. Defaults to `v2`.
331
+ * @param options.prepareRequest A callback to customize every request the hook makes before it's sent.
332
+ * @param options.onFinish A function called when a chat turn finishes.
333
+ * @param options.onError A function called when a chat turn fails. `generate` rejects instead.
334
+ * @returns An object containing `chat`, `generate` and `applyPart`.
335
+ */
336
+ declare function usePuckAi(options?: UsePuckAiOptions): {
337
+ chat: {
338
+ /** Send a new message to the agent. */
339
+ sendMessage: (prompt: string, opts?: SendMessageOptions) => Promise<void>;
340
+ /** Run the conversation's last turn again. */
341
+ regenerate: (args_0?: ({
342
+ messageId?: string;
343
+ } & ai.ChatRequestOptions) | undefined) => Promise<void>;
344
+ /** Stop the running turn. */
345
+ stop: () => Promise<void>;
346
+ /** The conversation's AI SDK status. */
347
+ status: ai.ChatStatus;
348
+ /** The last chat error's message, or `undefined`. Also passed to `onError`. */
349
+ error: string | undefined;
350
+ /** The conversation, as AI SDK `UIMessage`s. */
351
+ messages: PuckMessage[];
352
+ /** The live progress of the agent's tools, keyed by tool call id. */
353
+ toolStatus: Record<string, ToolStatus>;
354
+ };
355
+ /**
356
+ * Run a generation against the current page. Returns the page's Data once
357
+ * it's applied. Iterates once, unless the handler's `ai.maxIterations`
358
+ * allows more.
359
+ */
360
+ generate: (prompt: string, opts?: GenerateOptions) => Promise<Data>;
361
+ /** Apply and process an AI Part. */
362
+ applyPart: (part: AIPart, { recordHistory }?: ApplyPartOptions) => Promise<void>;
363
+ };
364
+
264
365
  type AiPluginProps = {
265
366
  host?: string;
266
367
  chat?: {
@@ -306,7 +407,15 @@ declare global {
306
407
  }
307
408
  }
308
409
 
410
+ /**
411
+ * Add a page's designed components to a config, to render the page.
412
+ *
413
+ * @param config Your Puck config.
414
+ * @param data The page, with its designed components in `root.props._dynamicConfig`.
415
+ * @returns The config, with the page's designed components and globals.
416
+ */
309
417
  declare function withDynamicConfig<UserConfig extends Config>(config: UserConfig, data: Data): UserConfig;
418
+
310
419
  declare function createAiPlugin(opts?: AiPluginProps): {
311
420
  label: string;
312
421
  name: string;
@@ -363,4 +472,4 @@ declare module "@puckeditor/core" {
363
472
  }
364
473
  }
365
474
 
366
- export { type AiDictionaryKey, type ComponentAiParams, type FieldAiParams, createAiPlugin, defaultDictionary, withDynamicConfig };
475
+ export { type AIPart, type AiDictionaryKey, type ApplyPartOptions, type ComponentAiParams, type FieldAiParams, type GenerateOptions, type SendMessageOptions, type UsePuckAiOptions, createAiPlugin, defaultDictionary, usePuckAi, withDynamicConfig };