@canva/intents 2.5.1-beta.0 → 2.5.1-beta.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## 2.5.1-beta.1 - 2026-05-12
+
+### Added
+
+- Promote requestAiContent from alpha to beta
+
 ## 2.5.1-beta.0 - 2026-04-10
 
 ### Changed

package/beta.d.ts

@@ -1,3 +1,49 @@
+/**
+ * @beta
+ * Cancelled response where the generation was not completed.
+ * We use only 'cancelled' since we don't expect app developers to handle any statuses further (e.g. blocked, failed).
+ * These will be handled on Canva's AI generation surface.
+ */
+declare type AiContentCancelledResponse = {
+    status: 'cancelled';
+};
+
+/**
+ * @beta
+ * Completed response for AI content generation.
+ * The value is the AI content generated for the app.
+ */
+declare type AiContentCompletedResponse = {
+    status: 'completed';
+    value: string;
+};
+
+/**
+ * @beta
+ * All possible AI content request types.
+ */
+declare type AiContentRequest = SocialCaptionRequest;
+
+/**
+ * @beta
+ * All possible AI content response types.
+ */
+declare type AiContentResponse = AiContentCompletedResponse | AiContentCancelledResponse;
+
+/**
+ * @beta
+ * All possible statuses for an AI content response.
+ *
+ */
+declare type AiContentResponseStatus = 'completed' | 'cancelled';
+
+/**
+ * @beta
+ * Possible content type for AI content generation.
+ * Future types will be added here, e.g. 'hashtags'.
+ */
+declare type AiContentType = 'social_caption';
+
 /**
  * @public
  * A disclosure identifying if the app generated this asset using AI.
@@ -139,6 +185,31 @@ declare type AppErrorInvocationContext = {
     message?: string;
 };
 
+/**
+ * @beta
+ * Base interface for AI content requests.
+ */
+declare type BaseAiContentRequest = {
+    /**
+     * The type of AI content generation which determines
+     * the kind of content the AI will generate.
+     */
+    type: AiContentType;
+    /**
+     * If a current value exists in the field, the AI content generation
+     * will be an edit-first experience.
+     * i.e. When the user has already entered a value in the field, the AI will
+     * generate a new value using the existing value as a starting point.
+     */
+    currentValue?: string;
+    /**
+     * The label chosen by the app developer for the field.
+     * It will be used in the UI to customize the copy.
+     * Required since it is essential context for the AI to generate the content.
+     */
+    fieldLabel: string;
+};
+
 /**
  * @public
  * Base file requirement interface.
@@ -364,7 +435,15 @@ declare namespace content {
         EmailOutputFile,
         ContentMetadata,
         DesignContentMetadata,
-        OutputPageMetadata
+        OutputPageMetadata,
+        AiContentType,
+        SocialCaptionRequest,
+        AiContentRequest,
+        AiContentResponseStatus,
+        AiContentCompletedResponse,
+        AiContentCancelledResponse,
+        AiContentResponse,
+        RequestAiContent
     }
 }
 export { content }
@@ -2682,9 +2761,47 @@ declare type RenderSettingsUiRequest = {
     registerOnContextChange: (opts: {
         onContextChange: OnContextChange;
     }) => Disposer;
-
+    /**
+     * @beta
+     * Function to trigger a request for AI content.
+     *
+     * Use this function to trigger a request for AI content.
+     *
+     * @param request - The request for AI content.
+     * @returns A promise resolving to the AI content response with a status of 'completed' or 'cancelled'.
+     * @example Requesting AI content
+     * ```ts
+     * async function onGenerateCaption() {
+     *   const result = await requestAiContent({
+     *     type: 'social_caption',
+     *     currentValue: settings.caption,
+     *     fieldLabel: 'Caption',
+     *     hints: {
+     *       maxLength: 2200,
+     *     },
+     *   });
+     *
+     *   if (result.status !== 'completed') {
+     *     return;
+     *   }
+     *   const nextSettings = { ...settings, caption: result.value };
+     *   // ... set local state
+     *   await updatePublishSettings({
+     *     publishRef: JSON.stringify(nextSettings),
+     *     validityState: 'valid',
+     *   });
+     * }
+     * ```
+     */
+    requestAiContent: RequestAiContent;
 };
 
+/**
+ * @beta
+ * Function to trigger a request for AI content.
+ */
+declare type RequestAiContent = (request: AiContentRequest) => Promise<AiContentResponse>;
+
 /**
  * @public
  * Metadata specific to design content represented by a media selection.
@@ -2728,6 +2845,23 @@ declare interface SizedPreview extends BasePreview {
     heightPx: number;
 }
 
+/**
+ * @beta
+ * Request for social caption generation.
+ */
+declare type SocialCaptionRequest = BaseAiContentRequest & {
+    type: 'social_caption';
+    /**
+     * Hints for how the AI should generate the caption.
+     */
+    hints?: {
+        /**
+         * The maximum length of the caption.
+         */
+        maxLength?: number;
+    };
+};
+
 /**
  * @public
  * Cell containing a text value.

package/content/beta.d.ts

@@ -1,3 +1,49 @@
+/**
+ * @beta
+ * Cancelled response where the generation was not completed.
+ * We use only 'cancelled' since we don't expect app developers to handle any statuses further (e.g. blocked, failed).
+ * These will be handled on Canva's AI generation surface.
+ */
+export declare type AiContentCancelledResponse = {
+    status: 'cancelled';
+};
+
+/**
+ * @beta
+ * Completed response for AI content generation.
+ * The value is the AI content generated for the app.
+ */
+export declare type AiContentCompletedResponse = {
+    status: 'completed';
+    value: string;
+};
+
+/**
+ * @beta
+ * All possible AI content request types.
+ */
+export declare type AiContentRequest = SocialCaptionRequest;
+
+/**
+ * @beta
+ * All possible AI content response types.
+ */
+export declare type AiContentResponse = AiContentCompletedResponse | AiContentCancelledResponse;
+
+/**
+ * @beta
+ * All possible statuses for an AI content response.
+ *
+ */
+export declare type AiContentResponseStatus = 'completed' | 'cancelled';
+
+/**
+ * @beta
+ * Possible content type for AI content generation.
+ * Future types will be added here, e.g. 'hashtags'.
+ */
+export declare type AiContentType = 'social_caption';
+
 /**
  * @public
  * {@link PublishContentError} indicating a custom error occurred in your app's implementation.
@@ -54,6 +100,31 @@ export declare type AppError = {
     errorCause?: ErrorCause;
 };
 
+/**
+ * @beta
+ * Base interface for AI content requests.
+ */
+declare type BaseAiContentRequest = {
+    /**
+     * The type of AI content generation which determines
+     * the kind of content the AI will generate.
+     */
+    type: AiContentType;
+    /**
+     * If a current value exists in the field, the AI content generation
+     * will be an edit-first experience.
+     * i.e. When the user has already entered a value in the field, the AI will
+     * generate a new value using the existing value as a starting point.
+     */
+    currentValue?: string;
+    /**
+     * The label chosen by the app developer for the field.
+     * It will be used in the UI to customize the copy.
+     * Required since it is essential context for the AI to generate the content.
+     */
+    fieldLabel: string;
+};
+
 /**
  * @public
  * Base file requirement interface.
@@ -1476,9 +1547,47 @@ export declare type RenderSettingsUiRequest = {
     registerOnContextChange: (opts: {
         onContextChange: OnContextChange;
     }) => Disposer;
-
+    /**
+     * @beta
+     * Function to trigger a request for AI content.
+     *
+     * Use this function to trigger a request for AI content.
+     *
+     * @param request - The request for AI content.
+     * @returns A promise resolving to the AI content response with a status of 'completed' or 'cancelled'.
+     * @example Requesting AI content
+     * ```ts
+     * async function onGenerateCaption() {
+     *   const result = await requestAiContent({
+     *     type: 'social_caption',
+     *     currentValue: settings.caption,
+     *     fieldLabel: 'Caption',
+     *     hints: {
+     *       maxLength: 2200,
+     *     },
+     *   });
+     *
+     *   if (result.status !== 'completed') {
+     *     return;
+     *   }
+     *   const nextSettings = { ...settings, caption: result.value };
+     *   // ... set local state
+     *   await updatePublishSettings({
+     *     publishRef: JSON.stringify(nextSettings),
+     *     validityState: 'valid',
+     *   });
+     * }
+     * ```
+     */
+    requestAiContent: RequestAiContent;
 };
 
+/**
+ * @beta
+ * Function to trigger a request for AI content.
+ */
+export declare type RequestAiContent = (request: AiContentRequest) => Promise<AiContentResponse>;
+
 /**
  * @public
  * Metadata specific to design content represented by a media selection.
@@ -1522,6 +1631,23 @@ export declare interface SizedPreview extends BasePreview {
     heightPx: number;
 }
 
+/**
+ * @beta
+ * Request for social caption generation.
+ */
+export declare type SocialCaptionRequest = BaseAiContentRequest & {
+    type: 'social_caption';
+    /**
+     * Hints for how the AI should generate the caption.
+     */
+    hints?: {
+        /**
+         * The maximum length of the caption.
+         */
+        maxLength?: number;
+    };
+};
+
 /**
  * @public
  * Successful response from updating the publish settings.

package/lib/cjs/sdk/intents/version.js

@@ -20,5 +20,5 @@ _export(exports, {
     }
 });
 const LATEST_VERSION = '2.5.0';
-const LATEST_VERSION_BETA = '2.5.1-beta.0';
+const LATEST_VERSION_BETA = '2.5.1-beta.1';
 const LATEST_VERSION_ALPHA = 'NONE';

package/lib/esm/sdk/intents/version.js

@@ -1,3 +1,3 @@
 export const LATEST_VERSION = '2.5.0';
-export const LATEST_VERSION_BETA = '2.5.1-beta.0';
+export const LATEST_VERSION_BETA = '2.5.1-beta.1';
 export const LATEST_VERSION_ALPHA = 'NONE';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canva/intents",
-  "version": "2.5.1-beta.0",
+  "version": "2.5.1-beta.1",
   "description": "The Canva Apps SDK Intents library",
   "author": "Canva Pty Ltd.",
   "license": "SEE LICENSE IN LICENSE.md FILE",