@canva/intents 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## 2.5.0 - 2026-04-09
+
+### Changed
+
+- Increased the `publishRef` size limit from 5KB to 32KB, allowing apps to store more complex publishing settings.
+
+### Added
+
+- Add selection metadata in MediaSelection
+- Enable apps to support transparent PNG exports in publish flow by adding optional allowTransparentBackground capability to ImageRequirement
+
 ## 2.4.0 - 2026-03-23
 
 ### Added

package/content/index.d.ts

@@ -110,6 +110,20 @@ export declare interface BasePreview {
     status: PreviewStatus;
 }
 
+/**
+ * @public
+ * Base metadata available for a selected media item in a media slot.
+ *
+ * Canva populates this when returning {@link OutputType} in Settings UI contexts.
+ * Apps should not set this value.
+ */
+export declare interface BaseSelection {
+    /**
+     * Metadata about the source content represented by this selection.
+     */
+    selectionMetadata?: readonly SelectionMetadata[];
+}
+
 /**
  * @public
  * Metadata about the source content used to create an exported file.
@@ -182,7 +196,7 @@ export declare type ContentPublisherIntent = {
      * privacy settings, or publishing destinations.
      *
      * Use the `updatePublishSettings` callback to save user settings and validate them.
-     * Settings are stored in the `publishRef` string (maximum 5KB).
+     * Settings are stored in the `publishRef` string (maximum 32KB).
      *
      * @param request - Configuration and callbacks for the publish settings UI.
      *
@@ -412,9 +426,9 @@ export declare interface DocumentRequirement extends BaseFileRequirement {
  * @public
  * Selection metadata for a document media item.
  */
-export declare type DocumentSelection = {
+export declare interface DocumentSelection extends BaseSelection {
     kind: 'document';
-};
+}
 
 /**
  * @public
@@ -498,9 +512,9 @@ export declare interface EmailRequirement extends BaseFileRequirement {
  * @public
  * Selection metadata for an email media item.
  */
-export declare type EmailSelection = {
+export declare interface EmailSelection extends BaseSelection {
     kind: 'email';
-};
+}
 
 /**
  * @public
@@ -631,11 +645,7 @@ export declare interface ImagePreviewReady extends SizedPreview {
  * };
  * ```
  */
-export declare interface ImageRequirement extends BaseFileRequirement {
-    /**
-     * Supported image format.
-     */
-    format: 'png' | 'jpg';
+export declare type ImageRequirement = BaseFileRequirement & {
     /**
      * Aspect ratio constraint (width / height).
      *
@@ -644,15 +654,37 @@ export declare interface ImageRequirement extends BaseFileRequirement {
      * - `{ min: 0.8, max: 1.91 }`: Instagram range
      */
     aspectRatio?: ValueRange;
-}
+} & ({
+    /**
+     * JPG image export.
+     */
+    format: 'jpg';
+} | {
+    /**
+     * PNG image export.
+     */
+    format: 'png';
+    /**
+     * Controls transparent-background support for PNG exports.
+     *
+     * @remarks
+     * - Only applies when `format` is `'png'`
+     * - If omitted or `false`, Canva exports a standard opaque PNG
+     * - If `true`, Canva shows a `Transparent background` toggle in the publish flow
+     * - Users without the required Canva entitlement may be prompted to upgrade before a transparent export is produced
+     *
+     * @defaultValue false
+     */
+    allowTransparentBackground?: boolean;
+});
 
 /**
  * @public
  * Selection metadata for an image media item.
  */
-export declare type ImageSelection = {
+export declare interface ImageSelection extends BaseSelection {
     kind: 'image';
-};
+}
 
 /**
  * @public
@@ -669,9 +701,6 @@ export declare type MaxValueRange = {
 /**
  * @public
  * Metadata about a selected media item in a media slot.
- *
- * Canva populates this when returning {@link OutputType} in Settings UI contexts.
- * Apps should not set this value.
  */
 export declare type MediaSelection = ImageSelection | VideoSelection | DocumentSelection | EmailSelection;
 
@@ -1092,7 +1121,7 @@ export declare type PublishContentRequest = {
      * This is the same reference you saved via `updatePublishSettings` in the settings UI.
      * Parse this string to retrieve the user's publish settings (e.g., captions, tags, privacy).
      *
-     * Maximum size: 5KB
+     * Maximum size: 32KB
      */
     publishRef?: string;
     /**
@@ -1198,7 +1227,7 @@ export declare type PublishSettings = {
      *
      * This reference will be provided to your `publishContent` method when publishing.
      *
-     * Maximum size: 5KB
+     * Maximum size: 32KB
      *
      * @example Serializing settings
      * ```ts
@@ -1398,7 +1427,7 @@ export declare type RenderSettingsUiRequest = {
      *
      * @param settings - The new publish settings to save
      * @returns A promise that resolves when the settings are successfully saved
-     * @throws Will throw `CanvaError('bad_request')` if {@link PublishSettings.publishRef} exceeds 5KB.
+     * @throws Will throw `CanvaError('bad_request')` if {@link PublishSettings.publishRef} exceeds 32KB.
      *
      * @example Updating settings as user types
      * ```ts
@@ -1450,6 +1479,28 @@ export declare type RenderSettingsUiRequest = {
 
 };
 
+/**
+ * @public
+ * Metadata specific to design content represented by a media selection.
+ */
+export declare interface SelectionDesignMetadata {
+    type: 'design';
+    /**
+     * A signed JWT token containing the design id
+     */
+    designToken: string;
+    /**
+     * The user given title of the design
+     */
+    title: string | undefined;
+}
+
+/**
+ * @public
+ * Metadata about the source content represented by a media selection.
+ */
+export declare type SelectionMetadata = SelectionDesignMetadata;
+
 /**
  * @public
  * Context information for the publish settings UI.
@@ -1676,12 +1727,12 @@ export declare interface VideoRequirement extends BaseFileRequirement {
  * @public
  * Selection metadata for a video media item.
  */
-export declare type VideoSelection = {
+export declare interface VideoSelection extends BaseSelection {
     kind: 'video';
     /**
      * Duration of the selected video in milliseconds.
      */
     durationMs: number;
-};
+}
 
 export { }

package/index.d.ts

@@ -195,6 +195,20 @@ declare interface BasePreview {
     status: PreviewStatus;
 }
 
+/**
+ * @public
+ * Base metadata available for a selected media item in a media slot.
+ *
+ * Canva populates this when returning {@link OutputType} in Settings UI contexts.
+ * Apps should not set this value.
+ */
+declare interface BaseSelection {
+    /**
+     * Metadata about the source content represented by this selection.
+     */
+    selectionMetadata?: readonly SelectionMetadata[];
+}
+
 /**
  * @public
  * Cell containing a boolean value.
@@ -304,11 +318,14 @@ declare namespace content {
         VideoRequirement,
         DocumentRequirement,
         EmailRequirement,
+        BaseSelection,
         MediaSelection,
         ImageSelection,
         VideoSelection,
         DocumentSelection,
         EmailSelection,
+        SelectionMetadata,
+        SelectionDesignMetadata,
         DocumentSize,
         PublishFileFormat,
         ExactValueRange,
@@ -424,7 +441,7 @@ declare type ContentPublisherIntent = {
      * privacy settings, or publishing destinations.
      *
      * Use the `updatePublishSettings` callback to save user settings and validate them.
-     * Settings are stored in the `publishRef` string (maximum 5KB).
+     * Settings are stored in the `publishRef` string (maximum 32KB).
      *
      * @param request - Configuration and callbacks for the publish settings UI.
      *
@@ -1068,9 +1085,9 @@ declare interface DocumentRequirement extends BaseFileRequirement {
  * @public
  * Selection metadata for a document media item.
  */
-declare type DocumentSelection = {
+declare interface DocumentSelection extends BaseSelection {
     kind: 'document';
-};
+}
 
 /**
  * @public
@@ -1154,9 +1171,9 @@ declare interface EmailRequirement extends BaseFileRequirement {
  * @public
  * Selection metadata for an email media item.
  */
-declare type EmailSelection = {
+declare interface EmailSelection extends BaseSelection {
     kind: 'email';
-};
+}
 
 /**
  * @public
@@ -1365,11 +1382,7 @@ declare type ImageRef = string & {
  * };
  * ```
  */
-declare interface ImageRequirement extends BaseFileRequirement {
-    /**
-     * Supported image format.
-     */
-    format: 'png' | 'jpg';
+declare type ImageRequirement = BaseFileRequirement & {
     /**
      * Aspect ratio constraint (width / height).
      *
@@ -1378,15 +1391,37 @@ declare interface ImageRequirement extends BaseFileRequirement {
      * - `{ min: 0.8, max: 1.91 }`: Instagram range
      */
     aspectRatio?: ValueRange;
-}
+} & ({
+    /**
+     * JPG image export.
+     */
+    format: 'jpg';
+} | {
+    /**
+     * PNG image export.
+     */
+    format: 'png';
+    /**
+     * Controls transparent-background support for PNG exports.
+     *
+     * @remarks
+     * - Only applies when `format` is `'png'`
+     * - If omitted or `false`, Canva exports a standard opaque PNG
+     * - If `true`, Canva shows a `Transparent background` toggle in the publish flow
+     * - Users without the required Canva entitlement may be prompted to upgrade before a transparent export is produced
+     *
+     * @defaultValue false
+     */
+    allowTransparentBackground?: boolean;
+});
 
 /**
  * @public
  * Selection metadata for an image media item.
  */
-declare type ImageSelection = {
+declare interface ImageSelection extends BaseSelection {
     kind: 'image';
-};
+}
 
 /**
  * @public
@@ -1617,9 +1652,6 @@ declare type MediaCollectionDataTableCell = {
 /**
  * @public
  * Metadata about a selected media item in a media slot.
- *
- * Canva populates this when returning {@link OutputType} in Settings UI contexts.
- * Apps should not set this value.
  */
 declare type MediaSelection = ImageSelection | VideoSelection | DocumentSelection | EmailSelection;
 
@@ -2234,7 +2266,7 @@ declare type PublishContentRequest = {
      * This is the same reference you saved via `updatePublishSettings` in the settings UI.
      * Parse this string to retrieve the user's publish settings (e.g., captions, tags, privacy).
      *
-     * Maximum size: 5KB
+     * Maximum size: 32KB
      */
     publishRef?: string;
     /**
@@ -2340,7 +2372,7 @@ declare type PublishSettings = {
      *
      * This reference will be provided to your `publishContent` method when publishing.
      *
-     * Maximum size: 5KB
+     * Maximum size: 32KB
      *
      * @example Serializing settings
      * ```ts
@@ -2601,7 +2633,7 @@ declare type RenderSettingsUiRequest = {
      *
      * @param settings - The new publish settings to save
      * @returns A promise that resolves when the settings are successfully saved
-     * @throws Will throw `CanvaError('bad_request')` if {@link PublishSettings.publishRef} exceeds 5KB.
+     * @throws Will throw `CanvaError('bad_request')` if {@link PublishSettings.publishRef} exceeds 32KB.
      *
      * @example Updating settings as user types
      * ```ts
@@ -2653,6 +2685,28 @@ declare type RenderSettingsUiRequest = {
 
 };
 
+/**
+ * @public
+ * Metadata specific to design content represented by a media selection.
+ */
+declare interface SelectionDesignMetadata {
+    type: 'design';
+    /**
+     * A signed JWT token containing the design id
+     */
+    designToken: string;
+    /**
+     * The user given title of the design
+     */
+    title: string | undefined;
+}
+
+/**
+ * @public
+ * Metadata about the source content represented by a media selection.
+ */
+declare type SelectionMetadata = SelectionDesignMetadata;
+
 /**
  * @public
  * Context information for the publish settings UI.
@@ -2949,13 +3003,13 @@ declare interface VideoRequirement extends BaseFileRequirement {
  * @public
  * Selection metadata for a video media item.
  */
-declare type VideoSelection = {
+declare interface VideoSelection extends BaseSelection {
     kind: 'video';
     /**
      * Duration of the selected video in milliseconds.
      */
     durationMs: number;
-};
+}
 
 /**
  * @public

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

@@ -19,6 +19,6 @@ _export(exports, {
         return LATEST_VERSION_BETA;
     }
 });
-const LATEST_VERSION = '2.4.0';
-const LATEST_VERSION_BETA = '2.2.1-beta.1';
+const LATEST_VERSION = '2.5.0';
+const LATEST_VERSION_BETA = '2.4.1-beta.0';
 const LATEST_VERSION_ALPHA = 'NONE';

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

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

package/package.json

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