@canva/intents 0.0.0-beta.2 → 2.0.0-beta.1

package/data/beta.d.ts

@@ -1,6 +1,46 @@
 /**
- * @beta
- * {@link FetchDataTableError} indicating custom error occurred in the app's implementation.
+ * @public
+ * A disclosure identifying if the app generated this asset using AI.
+ *
+ * @remarks
+ * Helps users make informed decisions about the content they interact with.
+ *
+ * AI is generally defined as any machine system that, given an objective, infers how to generate an output from an input.
+ * Some examples include "generative AI", "large language models", and "machine learning".
+ *
+ * **App Generated**
+ *
+ * 'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
+ * the app makes a request to a third-party service to do so.
+ *
+ * A significantly altered asset means the AI changes key information or details, such as
+ * removing or replacing key components in the original content, which can include applying style transfer, or changing facial expressions.
+ *
+ * Label this asset as 'app_generated' under these conditions:
+ *
+ * The following is true:
+ *
+ * - The app generates the asset in response to a user's request (including past requests), for example, the asset is not from an asset library.
+ *
+ * And any of these conditions are also true:
+ *
+ *  - The AI creates entirely new content from scratch.
+ *  - The AI introduces new multimedia, details, or creative elements not originally present.
+ *  - The AI removes and replaces the asset's key components.
+ *  - The AI alters the asset's appearance, meaning, or context in a way that conveys a different message than the original.
+ *
+ * **None**
+ *
+ * 'none' indicates when the asset wasn't generated by the app as a part of any user's specific request, for example, a third-party
+ * request, or when the asset wasn't significantly altered by AI.
+ */
+declare type AiDisclosure = "app_generated" | "none";
+
+declare type AllOrNone<T> = T | Never<T>;
+
+/**
+ * @public
+ * {@link GetDataTableError} indicating custom error occurred in the app's implementation.
  * This can be used to indicate specific issues that are not covered by other error types.
  */
 declare type AppError = {
@@ -19,16 +59,16 @@ declare type AppError = {
 };
 
 /**
- * @beta
+ * @public
  * {@link InvocationContext} indicating a custom error occurred during data refresh.
- * Triggered when fetchDataTable returned 'app_error' status.
+ * Triggered when getDataTable returned 'app_error' status.
  * UI should display the error message and help users recover.
  */
 declare type AppErrorInvocationContext = {
   /**
    * A custom error occurred during data refresh.
    *
-   * This occurs when `fetchDataTable` returned 'app_error' during a refresh attempt.
+   * This occurs when `getDataTable` returned 'app_error' during a refresh attempt.
    * Your UI should display the error message and help users recover from the specific
    * issue.
    */
@@ -44,7 +84,7 @@ declare type AppErrorInvocationContext = {
 };
 
 /**
- * @beta
+ * @public
  * Cell containing a boolean value.
  *
  * @example Creating a boolean cell
@@ -91,7 +131,7 @@ export declare type BooleanDataTableCell = {
 };
 
 /**
- * @beta
+ * @public
  * Configuration for a table column.
  */
 export declare type ColumnConfig = {
@@ -111,7 +151,7 @@ export declare type ColumnConfig = {
 };
 
 /**
- * @beta
+ * @public
  * Main interface for implementing the Data Connector intent.
  *
  * Implementing the Data Connector intent enables apps to import external data into Canva.
@@ -119,22 +159,22 @@ export declare type ColumnConfig = {
  */
 export declare type DataConnectorIntent = {
   /**
-   * Fetches structured data from an external source.
+   * Gets structured data from an external source.
    *
    * This action is called in two scenarios:
    *
-   * - During data selection to preview data before import (when {@link RenderSelectionUiParams.updateDataRef} is called).
+   * - During data selection to preview data before import (when {@link RenderSelectionUiRequest.updateDataRef} is called).
    * - When refreshing previously imported data (when the user requests an update).
    *
-   * @param params - Parameters for the data fetching operation.
+   * @param request - Parameters for the data fetching operation.
    * @returns A promise resolving to either a successful result with data or an error.
    *
-   * @example Fetching data from an external source
+   * @example Getting data from an external source
    * ```ts
-   * import type { FetchDataTableParams, FetchDataTableResult } from '@canva/intents/data';
+   * import type { GetDataTableRequest, GetDataTableResponse } from '@canva/intents/data';
    *
-   * async function fetchDataTable(params: FetchDataTableParams): Promise<FetchDataTableResult> {
-   *   const { dataSourceRef, limit, signal } = params;
+   * async function getDataTable(request: GetDataTableRequest): Promise<GetDataTableResponse> {
+   *   const { dataSourceRef, limit, signal } = request;
    *
    *   // Check if the operation has been aborted.
    *   if (signal.aborted) {
@@ -151,24 +191,23 @@ export declare type DataConnectorIntent = {
    * }
    * ```
    */
-  fetchDataTable: (
-    params: FetchDataTableParams,
-  ) => Promise<FetchDataTableResult>;
+  getDataTable: (request: GetDataTableRequest) => Promise<GetDataTableResponse>;
+
   /**
    * Renders a user interface for selecting and configuring data from your external sources.
    *
-   * @param params - Configuration and callbacks for the data selection UI.
+   * @param request - Configuration and callbacks for the data selection UI.
    *
    * @example Rendering a data selection UI
    * ```ts
-   * import type { RenderSelectionUiParams } from '@canva/intents/data';
+   * import type { RenderSelectionUiRequest } from '@canva/intents/data';
    *
-   * async function renderSelectionUi(params: RenderSelectionUiParams): Promise<void> {
+   * async function renderSelectionUi(request: RenderSelectionUiRequest): Promise<void> {
    *   // UI rendering logic.
    *   // Example: if user selects data 'ref123'.
    *   const selectedRef = { source: 'ref123', title: 'My Selected Table' };
    *   try {
-   *     const result = await params.updateDataRef(selectedRef);
+   *     const result = await request.updateDataRef(selectedRef);
    *     if (result.status === 'completed') {
    *       console.log('Selection valid and preview updated.');
    *     } else {
@@ -180,11 +219,11 @@ export declare type DataConnectorIntent = {
    * }
    * ```
    */
-  renderSelectionUi: (params: RenderSelectionUiParams) => void;
+  renderSelectionUi: (request: RenderSelectionUiRequest) => void;
 };
 
 /**
- * @beta
+ * @public
  * {@link InvocationContext} indicating initial data selection flow or edit of existing data.
  */
 declare type DataSelectionInvocationContext = {
@@ -207,7 +246,7 @@ declare type DataSelectionInvocationContext = {
 };
 
 /**
- * @beta
+ * @public
  * Reference to an external data source that can be used to fetch data.
  * Created by Data Connector apps and stored by Canva for data refresh operations.
  *
@@ -253,33 +292,7 @@ export declare type DataSourceRef = {
 };
 
 /**
- * @beta
- * {@link ValidationError} indicating the data source reference {@link DataSourceRef} exceeds the 5KB size limit.
- */
-declare type DataSourceRefLimitExceeded = {
-  /**
-   * The data source reference exceeds the 5KB size limit.
-   *
-   * Your app should reduce the size of the `DataSourceRef.source` string.
-   */
-  status: "data_source_ref_limit_exceeded";
-};
-
-/**
- * @beta
- * {@link ValidationError} indicating the data source title {@link DataSourceRef.title} exceeds the 255 character limit.
- */
-declare type DataSourceTitleLimitExceed = {
-  /**
-   * The data source title exceeds the 255 character limit.
-   *
-   * Your app should provide a shorter title for the data source.
-   */
-  status: "data_source_title_limit_exceeded";
-};
-
-/**
- * @beta
+ * @public
  * Structured tabular data for import into Canva.
  *
  * This format allows you to provide typed data with proper formatting
@@ -333,7 +346,7 @@ export declare type DataTable = {
 };
 
 /**
- * @beta
+ * @public
  * Generic type for table cells that resolves to a specific cell type.
  */
 export declare type DataTableCell<T extends DataType = DataType> = {
@@ -341,35 +354,25 @@ export declare type DataTableCell<T extends DataType = DataType> = {
   string: StringDataTableCell;
   number: NumberDataTableCell;
   boolean: BooleanDataTableCell;
+  media: MediaCollectionDataTableCell;
 }[T];
 
 /**
- * @beta
- * {@link ValidationError} indicating the data table format is invalid.
- *
- * This can happen due to:
- *
- * - {@link DataType} mismatches (e.g., a number in a string-typed column, a number value in a string cell type)
- * - Unsupported cell types
- * - Inconsistent column configurations (e.g., the number of columns in the data table does not match the number of {@link ColumnConfig})
+ * @public
+ * Options for uploading an image asset to the user's private media library.
  */
-declare type DataTableInvalidFormat = {
+export declare type DataTableImageUpload = Omit<
+  ImageUploadOptions,
+  "type" | "parentRef"
+> & {
   /**
-   * The data table format is invalid.
-   *
-   * This error occurs due to:
-   *
-   * - Data type mismatches (e.g., number in string column)
-   * - Unsupported cell types
-   * - Inconsistent column configurations
-   *
-   * Your app should ensure the data conforms to the expected format.
+   * Indicates this value contains options for image uploading.
    */
-  status: "data_table_invalid_format";
+  type: "image_upload";
 };
 
 /**
- * @beta
+ * @public
  * Maximum dimensions for imported data tables.
  */
 export declare type DataTableLimit = {
@@ -388,32 +391,7 @@ export declare type DataTableLimit = {
 };
 
 /**
- * @beta
- * {@link ValidationError} indicating that the data table exceeds the allowed limits.
- *
- * This can happen when:
- * - Number of rows exceeds the row limit
- * - Number of columns exceeds the column limit
- * - Total data size exceeds 200KB
- */
-declare type DataTableLimitExceeded = {
-  /**
-   * The data exceeds the maximum allowed limits.
-   *
-   * This error occurs when:
-   *
-   * - Number of rows exceeds the row limit
-   * - Number of columns exceeds the column limit
-   * - Total data size exceeds the allowed size limit
-   *
-   * Your app should help users select a subset of their data,
-   * or provide filtering options to reduce the data size.
-   */
-  status: "data_table_limit_exceeded";
-};
-
-/**
- * @beta
+ * @public
  * Metadata providing additional context about the imported data.
  */
 export declare type DataTableMetadata = {
@@ -439,20 +417,7 @@ export declare type DataTableMetadata = {
 };
 
 /**
- * @beta
- * {@link ValidationError} indicating the provided data table metadata is invalid (e.g not a valid OXML formatting string in {@link NumberCellMetadata.formatting}).
- */
-declare type DataTableMetadataInvalid = {
-  /**
-   * The provided metadata is invalid.
-   *
-   * This typically happens with invalid formatting patterns in {@link NumberCellMetadata.formatting} strings.
-   */
-  status: "data_table_metadata_invalid";
-};
-
-/**
- * @beta
+ * @public
  * A row in the data table.
  *
  * @example Creating a single row of data cells
@@ -478,13 +443,32 @@ export declare type DataTableRow = {
 };
 
 /**
- * @beta
+ * @public
+ * Options for uploading a video asset to the user's private media library.
+ */
+export declare type DataTableVideoUpload = Omit<
+  VideoUploadOptions,
+  "type" | "parentRef"
+> & {
+  /**
+   * Indicates this value contains options for video uploading.
+   */
+  type: "video_upload";
+};
+
+/**
+ * @public
  * Data types supported for table cells.
  */
-export declare type DataType = "string" | "number" | "date" | "boolean";
+export declare type DataType =
+  | "string"
+  | "number"
+  | "date"
+  | "boolean"
+  | "media";
 
 /**
- * @beta
+ * @public
  * Cell containing a date value.
  *
  * @example Creating a date cell
@@ -516,12 +500,27 @@ export declare type DateDataTableCell = {
 };
 
 /**
- * @beta
- * Successful result from `fetchDataTable` action.
+ * @public
+ * A set of dimensions.
  */
-export declare type FetchDataTableCompleted = {
+declare type Dimensions = {
+  /**
+   * A width, in pixels.
+   */
+  width: number;
   /**
-   * Indicates the fetch operation completed successfully
+   * A height, in pixels.
+   */
+  height: number;
+};
+
+/**
+ * @public
+ * Successful result from `getDataTable` action.
+ */
+export declare type GetDataTableCompleted = {
+  /**
+   * Indicates the operation completed successfully
    */
   status: "completed";
   /**
@@ -535,19 +534,19 @@ export declare type FetchDataTableCompleted = {
 };
 
 /**
- * @beta
- * Error results that can be returned from `fetchDataTable` method.
+ * @public
+ * Error results that can be returned from `getDataTable` method.
  */
-export declare type FetchDataTableError =
+export declare type GetDataTableError =
   | OutdatedSourceRefError
   | RemoteRequestFailedError
   | AppError;
 
 /**
- * @beta
- * Parameters for the fetchDataTable action.
+ * @public
+ * Parameters for the getDataTable action.
  */
-export declare type FetchDataTableParams = {
+export declare type GetDataTableRequest = {
   /**
    * Reference to the data source to fetch.
    *
@@ -577,33 +576,186 @@ export declare type FetchDataTableParams = {
 };
 
 /**
- * @beta
- * Result returned from the `fetchDataTable` action.
+ * @public
+ * Result returned from the `getDataTable` action.
+ */
+export declare type GetDataTableResponse =
+  | GetDataTableCompleted
+  | GetDataTableError;
+
+/**
+ * @public
+ * The MIME type of an image file that's supported by Canva's backend.
  */
-export declare type FetchDataTableResult =
-  | FetchDataTableCompleted
-  | FetchDataTableError;
+declare type ImageMimeType =
+  | "image/jpeg"
+  | "image/heic"
+  | "image/png"
+  | "image/svg+xml"
+  | "image/webp"
+  | "image/tiff";
 
 /**
- * @beta
- * System errors that may occur during data operations.
+ * @public
+ * A unique identifier that points to an image asset in Canva's backend.
  */
-export declare type InternalError = {
+declare type ImageRef = string & {
+  __imageRef: never;
+};
+
+/**
+ * @public
+ * Options for uploading an image asset to the user's private media library.
+ */
+declare type ImageUploadOptions = {
   /**
-   * An unexpected system error occurred.
+   * The type of asset.
+   */
+  type: "image";
+  /**
+   * The ref of the original asset from which this new asset was derived.
    *
-   * These errors are typically not related to your app's implementation
-   * but indicate issues with the platform.
+   * @remarks
+   * For example, if an app applies an effect to an image, `parentRef` should contain the ref of the original image.
    */
-  status: "internal_error";
+  parentRef?: ImageRef;
   /**
-   * The cause of the error.
+   * The URL of the image file to upload.
+   * This can be an external URL or a data URL.
+   *
+   * @remarks
+   * Requirements for external URLs:
+   *
+   * - Must use HTTPS
+   * - Must return a `200` status code
+   * - `Content-Type` must match the file's MIME type
+   * - Must be publicly accessible (i.e. not a localhost URL)
+   * - Must not redirect
+   * - Must not contain an IP address
+   * - Maximum length: 4096 characters
+   * - Must not contain whitespace
+   * - Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
+   * - Maximum file size: 50MB
+   *
+   * Requirements for data URLs:
+   *
+   * - Must include `;base64` for base64-encoded data
+   * - Maximum size: 10MB (10 × 1024 × 1024 characters)
+   *
+   * Requirements for SVGs:
+   *
+   * - Disallowed elements:
+   *    - `a`
+   *    - `altglyph`
+   *    - `altglyphdef`
+   *    - `altglyphitem`
+   *    - `animate`
+   *    - `animatemotion`
+   *    - `animatetransform`
+   *    - `cursor`
+   *    - `discard`
+   *    - `font`
+   *    - `font-face`
+   *    - `font-face-format`
+   *    - `font-face-name`
+   *    - `font-face-src`
+   *    - `font-face-uri`
+   *    - `foreignobject`
+   *    - `glyph`
+   *    - `glyphref`
+   *    - `missing-glyph`
+   *    - `mpath`
+   *    - `script`
+   *    - `set`
+   *    - `switch`
+   *    - `tref`
+   * - Disallowed attributes:
+   *    - `crossorigin`
+   *    - `lang`
+   *    - `media`
+   *    - `onload`
+   *    - `ping`
+   *    - `referrerpolicy`
+   *    - `rel`
+   *    - `rendering-intent`
+   *    - `requiredextensions`
+   *    - `requiredfeatures`
+   *    - `systemlanguage`
+   *    - `tabindex`
+   *    - `transform-origin`
+   *    - `unicode`
+   *    - `vector-effect`
+   * - The `href` attribute of an `image` element only supports data URLs for PNG and JPEG images.
+   * - The URL in the `href` attribute must not point to a location outside of the SVG.
+   * - The `style` attribute must not use the `mix-blend-mode` property.
    */
-  cause?: unknown;
-};
+  url: string;
+  /**
+   * The MIME type of the image file.
+   */
+  mimeType: ImageMimeType;
+  /**
+   * The URL of a thumbnail image to display while the image is queued for upload.
+   * This can be an external URL or a data URL.
+   *
+   * @remarks
+   * Requirements for external URLs:
+   *
+   * - Must use HTTPS
+   * - Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
+   * - Must be a PNG, JPEG, or SVG file
+   * - Maximum length: 4096 characters
+   *
+   * Requirements for data URLs:
+   *
+   * - Must include `;base64` for base64-encoded data
+   * - Maximum size: 10MB (10 × 1024 × 1024 characters)
+   */
+  thumbnailUrl: string;
+  /**
+   * A disclosure identifying if the app generated this image using AI
+   *
+   * @remarks
+   * Helps users make informed decisions about the content they interact with.
+   * See {@link AiDisclosure} for the full definition.
+   *
+   * **App Generated**
+   *
+   * 'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
+   * the app requests a third-party service to take similar action on an image using AI.
+   *
+   *  Required for the following cases (this list is not exhaustive):
+   *  | Case                                                            | Reason                               |
+   *  | --                                                              | --                                   |
+   *  | AI generates a new image from scratch                           | Creates new creative content         |
+   *  | AI changes the style of the image e.g. makes it cartoon         | Significantly alters the style       |
+   *  | AI removes an object and replaces it with new content           | Creates new creative content         |
+   *  | AI changes the facial expression of a person in an image        | Can alter content's original meaning |
+   *  | AI composites multiple images together                          | Significantly alters context         |
+   *  | AI expands an image by generating new content to fill the edges | Creates new creative content         |
+   *  | AI replaces background by generating new content                | Creates new creative content         |
+   *
+   * **None**
+   *
+   * 'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request
+   * to third-party hosted content.
+   *
+   * Required for the following cases (this list is not exhaustive):
+   *  | Case                                                    | Reason                                    |
+   *  | --                                                      | --                                        |
+   *  | Asset comes from an asset library                       | Didn't generate the asset itself          |
+   *  | AI corrects red eyes                                    | A minor correction                        |
+   *  | AI removes background without replacement               | Doesn't change original meaning by itself |
+   *  | AI changes the color of an object in an image           | Doesn't change original meaning by itself |
+   *  | AI detects image defects and suggests manual fixes      | Didn't change the asset itself            |
+   *  | AI adjusts brightness and contrast on an image          | Doesn't change original meaning by itself |
+   *  | AI upscales an image                                    | Doesn't change original meaning by itself |
+   */
+  aiDisclosure: AiDisclosure;
+} & AllOrNone<Dimensions>;
 
 /**
- * @beta
+ * @public
  * Information explaining why the data selection UI was launched.
  */
 export declare type InvocationContext =
@@ -612,7 +764,54 @@ export declare type InvocationContext =
   | AppErrorInvocationContext;
 
 /**
- * @beta
+ * @public
+ * Cell containing a media collection (images) value.
+ *
+ * @example Creating a media cell with an image
+ * ```ts
+ * import type { MediaCollectionDataTableCell } from '@canva/intents/data';
+ *
+ * const mediaCell: MediaCollectionDataTableCell = {
+ *   type: 'media',
+ *   value: [{
+ *     type: 'image_upload',
+ *     url: 'https://www.canva.dev/example-assets/image-import/image.jpg',
+ *     mimeType: 'image/jpeg',
+ *     thumbnailUrl: 'https://www.canva.dev/example-assets/image-import/thumbnail.jpg',
+ *     aiDisclosure: 'none'
+ *   }]
+ * };
+ * ```
+ *
+ * @example Creating an empty media cell
+ * ```ts
+ * import type { MediaCollectionDataTableCell } from '@canva/intents/data';
+ *
+ * const emptyMediaCell: MediaCollectionDataTableCell = {
+ *   type: 'media',
+ *   value: []
+ * };
+ * ```
+ */
+export declare type MediaCollectionDataTableCell = {
+  /**
+   * Indicates this cell contains a media collection.
+   */
+  type: "media";
+  /**
+   * Media collection values.
+   *
+   * Use empty array for an empty cell.
+   */
+  value: (DataTableImageUpload | DataTableVideoUpload)[];
+};
+
+declare type Never<T> = {
+  [key in keyof T]?: never;
+};
+
+/**
+ * @public
  * Formatting metadata for number cells.
  *
  * @example Formatting as currency
@@ -659,7 +858,7 @@ export declare type NumberCellMetadata = {
 };
 
 /**
- * @beta
+ * @public
  * Cell containing a numeric value.
  *
  * @example Creating a number cell
@@ -718,8 +917,8 @@ export declare type NumberDataTableCell = {
 };
 
 /**
- * @beta
- * {@link FetchDataTableError} indicating the data source reference is no longer valid.
+ * @public
+ * {@link GetDataTableError} indicating the data source reference is no longer valid.
  * This will trigger a re-selection flow for the user.
  */
 declare type OutdatedSourceRefError = {
@@ -740,16 +939,16 @@ declare type OutdatedSourceRefError = {
 };
 
 /**
- * @beta
+ * @public
  * {@link InvocationContext} indicating an error occurred because the previously selected data source reference is no longer valid.
- * Triggered when fetchDataTable returned 'outdated_source_ref' during data refresh.
+ * Triggered when getDataTable returned 'outdated_source_ref' during data refresh.
  * UI should guide the user to reselect or reconfigure their data.
  */
 declare type OutdatedSourceRefInvocationContext = {
   /**
    * Previously selected data source reference is no longer valid.
    *
-   * This occurs when `fetchDataTable` returned 'outdated_source_ref' during a
+   * This occurs when `getDataTable` returned 'outdated_source_ref' during a
    * refresh attempt. Your UI should guide the user to select a new data source
    * or update their selection.
    *
@@ -763,17 +962,31 @@ declare type OutdatedSourceRefInvocationContext = {
 };
 
 /**
- * @beta
+ * @public
+ *
+ * Prepares a {@link DataConnectorIntent|DataConnector Intent}.
+ *
+ * @example
+ * ```tsx
+ * import { prepareDataConnector } from "@canva/intents/data";
  *
- * Prepares the `DataConnectorIntent`.
+ * prepareDataConnector({
+ *  getDataTable: async (params) => {
+ *    // Implement the logic to fetch the data table
+ *  },
+ *  renderSelectionUi: (params) => {
+ *    // Implement the UI for the data table selection
+ *  },
+ * });
+ * ```
  */
 export declare const prepareDataConnector: (
   implementation: DataConnectorIntent,
 ) => void;
 
 /**
- * @beta
- * {@link FetchDataTableError} indicating failure to fetch data from the external source.
+ * @public
+ * {@link GetDataTableError} indicating failure to fetch data from the external source.
  * Typically due to network issues or API failures.
  */
 declare type RemoteRequestFailedError = {
@@ -787,10 +1000,10 @@ declare type RemoteRequestFailedError = {
 };
 
 /**
- * @beta
+ * @public
  * Parameters for rendering the data selection UI.
  */
-export declare type RenderSelectionUiParams = {
+export declare type RenderSelectionUiRequest = {
   /**
    * Context information about why the data selection UI is being launched.
    *
@@ -819,17 +1032,23 @@ export declare type RenderSelectionUiParams = {
    * 1. Show a preview of the selected data to the user
    * 2. Validate that the selection meets system requirements
    *
-   * Calling this function will trigger your `fetchDataTable` implementation.
+   * Calling this function will trigger your `getDataTable` implementation.
    * Wait for the promise to resolve to determine if the selection is valid.
    *
    * @param dataSourceRef - Reference object identifying the selected data
    * @returns Promise resolving to success or an error result
+   * @throws Will throw CanvaError('bad_request') if
+   *  1. {@link DataSourceRef.source} exceeds 5kb.
+   *  2. {@link DataSourceRef.title} exceeds 255 characters.
+   *  3. {@link GetDataTableCompleted.dataTable} exceeds {@link DataTableLimit} or contains invalid data.
    */
-  updateDataRef: (dataSourceRef: DataSourceRef) => Promise<UpdateDataRefResult>;
+  updateDataRef: (
+    dataSourceRef: DataSourceRef,
+  ) => Promise<UpdateDataRefResponse>;
 };
 
 /**
- * @beta
+ * @public
  * Cell containing a text value.
  *
  * @example Creating a string cell
@@ -863,8 +1082,8 @@ export declare type StringDataTableCell = {
 };
 
 /**
- * @beta
- * Successful result from the {@link RenderSelectionUiParams.updateDataRef} callback.
+ * @public
+ * Successful result from the {@link RenderSelectionUiRequest.updateDataRef} callback.
  */
 declare type UpdateDataRefCompleted = {
   /**
@@ -874,25 +1093,150 @@ declare type UpdateDataRefCompleted = {
 };
 
 /**
- * @beta
- * Result returned from the {@link RenderSelectionUiParams.updateDataRef} callback.
+ * @public
+ * Result returned from the {@link RenderSelectionUiRequest.updateDataRef} callback.
  * Indicates whether {@link DataSourceRef} update succeeded or failed.
  */
-export declare type UpdateDataRefResult =
+export declare type UpdateDataRefResponse =
   | UpdateDataRefCompleted
-  | FetchDataTableError
-  | ValidationError
-  | InternalError;
+  | GetDataTableError;
+
+/**
+ * @public
+ * The MIME type of a video file that's supported by Canva's backend.
+ *
+ * @remarks
+ * - GIFs are treated as videos, not images.
+ * - `"application/json"` is only used for Lottie files.
+ */
+declare type VideoMimeType =
+  | "video/avi"
+  | "video/x-msvideo"
+  | "image/gif"
+  | "video/x-m4v"
+  | "video/x-matroska"
+  | "video/quicktime"
+  | "video/mp4"
+  | "video/mpeg"
+  | "video/webm"
+  | "application/json";
+
+/**
+ * @public
+ * A unique identifier that points to a video asset in Canva's backend.
+ */
+declare type VideoRef = string & {
+  __videoRef: never;
+};
 
 /**
- * @beta
- * Validation errors that can occur when processing data.
+ * @public
+ * Options for uploading a video asset to the user's private media library.
  */
-export declare type ValidationError =
-  | DataTableLimitExceeded
-  | DataTableInvalidFormat
-  | DataTableMetadataInvalid
-  | DataSourceRefLimitExceeded
-  | DataSourceTitleLimitExceed;
+declare type VideoUploadOptions = {
+  /**
+   * The type of asset.
+   */
+  type: "video";
+  /**
+   * The ref of the original asset from which this new asset was derived.
+   *
+   * @remarks
+   * For example, if an app applies an effect to a video, `parentRef` should contain the ref of the original video.
+   */
+  parentRef?: VideoRef;
+  /**
+   * The URL of the video file to upload.
+   *
+   * @remarks
+   * Requirements:
+   *
+   * - Must use HTTPS
+   * - Must return a `200` status code
+   * - `Content-Type` must match the file's MIME type
+   * - Must be publicly accessible (i.e. not a localhost URL)
+   * - Must not redirect
+   * - Must not contain an IP address
+   * - Maximum length: 4096 characters
+   * - Must not contain whitespace
+   * - Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
+   * - Maximum file size: 100MB
+   */
+  url: string;
+  /**
+   * The MIME type of the video file.
+   */
+  mimeType: VideoMimeType;
+  /**
+   * The URL of a thumbnail video to display while the video is queued for upload.
+   *
+   * @remarks
+   * Requirements:
+   *
+   * - Must use HTTPS
+   * - Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
+   * - Maximum length: 4096 characters
+   * - The dimensions of the thumbnail video must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
+   * - Must not be an AVI file. Although our APIs support uploading AVI videos, Canva can't preview them because of native support of browsers
+   */
+  thumbnailVideoUrl?: string;
+  /**
+   * The URL of a thumbnail image to use as a fallback if `thumbnailVideoUrl` isn't provided.
+   * This can be an external URL or a data URL.
+   *
+   * @remarks
+   * Requirements for external URLs:
+   *
+   * - Must use HTTPS
+   * - Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
+   * - Must be a PNG, JPEG, or SVG file
+   * - Maximum length: 4096 characters
+   *
+   * Requirements for data URLs:
+   *
+   * - Must include `;base64` for base64-encoded data
+   * - Maximum size: 10MB (10 × 1024 × 1024 characters)
+   * - The dimensions of the thumbnail must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
+   */
+  thumbnailImageUrl: string;
+  /**
+   * A disclosure identifying if the app generated this video using AI.
+   *
+   * @remarks
+   * Helps users make informed decisions about the content they interact with.
+   * See {@link AiDisclosure} for the full definition.
+   *
+   * **App Generated**
+   *
+   * 'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
+   * the app requests a third-party service to take similar action on a video using AI.
+   *
+   *  Required for the following cases (this list is not exhaustive):
+   *  | Case                                                             | Reason                               |
+   *  | --                                                               | --                                   |
+   *  | AI generates a new video from scratch                            | Creates new creative content         |
+   *  | AI changes the style of the video e.g. makes it cartoon          | Significantly alters the style       |
+   *  | AI adds subtitles that rely on subjective interpretation         | Creates new creative content         |
+   *  | AI expands a video by generating new content to fill the edges   | Creates new creative content         |
+   *  | AI animates an image                                             | Creates new creative content         |
+   *  | AI fixes defects e.g. blur in a video by generating details      | Creates new creative content         |
+   *  | AI generates a talking head presenter                            | Creates new creative content         |
+   *
+   * **None**
+   *
+   * 'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of
+   * a request to third-party hosted content.
+   *
+   * Required for the following cases (this list is not exhaustive):
+   *  | Case                                                     | Reason                                    |
+   *  | --                                                       | --                                        |
+   *  | Asset comes from an asset library                        | Didn't generate the asset itself          |
+   *  | AI corrects red eyes                                     | A minor correction                        |
+   *  | AI adjusts brightness and contrast on a video            | Doesn't change original meaning by itself |
+   *  | AI creates a slow motion effect in a video               | Doesn't change original meaning by itself |
+   *  | AI adds AI word-by-word transcribed subtitles to a video | Doesn't change original meaning by itself |
+   */
+  aiDisclosure: AiDisclosure;
+} & AllOrNone<Dimensions>;
 
 export {};