@canva/intents 2.0.1-beta.2 → 2.1.0

package/content/index.d.ts

@@ -1 +1,1440 @@
-export * from "./beta";
+/**
+ * @public
+ * {@link PublishContentError} indicating a custom error occurred in your app's implementation.
+ *
+ * Return this for application-specific errors such as:
+ *
+ * - Validation failures
+ * - Authentication errors
+ * - Rate limiting
+ * - Platform-specific restrictions
+ *
+ * @example Returning custom error with message
+ * ```ts
+ * if (userQuotaExceeded) {
+ *   return {
+ *     status: 'app_error',
+ *     message: 'You have reached your monthly publish limit. Please upgrade your plan.'
+ *   };
+ * }
+ * ```
+ */
+export declare type AppError = {
+    status: 'app_error';
+    /**
+     * (required) The raw error message, for logging purposes. It will not display in the UI.
+     * To display custom error messages in the UI use `localizedMessageId`.
+     *
+     * This should typically be the javascript error.message or a REST JSON error message
+     * body passed without modification.
+     *
+     * WARNING: Do not include personally identifiable information (PII) in this
+     * message, such as names, emails, usernames, etc.
+     */
+    message: string;
+    /**
+     * (optional) Message ID of the translated error message that will be
+     * displayed to the user. The message ID should be present and uploaded in
+     * your translation file. If omitted, Canva will display a generic error
+     * message.
+     */
+    localizedMessageId?: string;
+    /** HTTP status code, if applicable */
+    httpCode?: number;
+    /**
+     * Used only by app developer. Canva does not use this value. Use this to pass
+     * additional information like JSON to your settings frame.
+     */
+    appDefinedPayload?: string;
+    /**
+     * (optional) Source of the error if it relates to a component on the Canva
+     * UI. When present, the error may render near a relevant Canva component.
+     * When omitted, the cause is considered unspecified or "generic".
+     */
+    errorCause?: ErrorCause;
+};
+
+/**
+ * @public
+ * Base file requirement interface.
+ */
+declare interface BaseFileRequirement {
+    /**
+     * File format for this requirement.
+     */
+    format: PublishFileFormat;
+
+}
+
+/**
+ * @public
+ * Base interface for exported files.
+ */
+export declare interface BaseOutputFile {
+    /**
+     * File format.
+     */
+    format: PublishFileFormat;
+    /**
+     * URL to download the exported file.
+     *
+     * Your app should download from this URL and upload to your platform.
+     */
+    url: string;
+    /**
+     * Metadata about the source content used to create this exported file.
+     */
+    contentMetadata: ContentMetadata;
+}
+
+/**
+ * @public
+ * Base interface for all preview types.
+ *
+ * Contains common properties shared by all preview types.
+ */
+export declare interface BasePreview {
+    /**
+     * Unique identifier for this preview.
+     *
+     * Use this ID with `requestPreviewUpgrade` to upgrade video thumbnails.
+     */
+    id: string;
+    /**
+     * Type of media in this preview.
+     */
+    kind: PreviewKind;
+    /**
+     * Current state of the preview.
+     */
+    status: PreviewStatus;
+}
+
+/**
+ * @public
+ * Metadata about the source content used to create an exported file.
+ */
+export declare type ContentMetadata = DesignContentMetadata;
+
+/**
+ * @public
+ * Main interface for implementing the ContentPublisher intent.
+ *
+ * Implementing the ContentPublisher intent enables apps to publish contents to external platforms.
+ * This allows users to configure publish settings, preview their designs, and share with others.
+ *
+ * The publishing flow follows this process:
+ *
+ * 1. User initiates publish action
+ * 2. Your app provides publish configuration via `getPublishConfiguration`
+ * 3. User selects an output type
+ * 4. Your app renders settings UI via `renderSettingsUi`
+ * 5. Your app renders preview UI via `renderPreviewUi`
+ * 6. User reviews settings and preview
+ * 7. Your app publishes the content via `publishContent`
+ */
+export declare type ContentPublisherIntent = {
+    /**
+     * Provides the configuration for the publishing platform.
+     *
+     * This action is called when the user initiates the publish flow and needs to
+     * select an output type for the target platform.
+     *
+     * Use this to define different publishing configurations for your platform,
+     * such as social media posts, videos, or other output types.
+     *
+     * @returns A promise resolving to the publish configuration or an error
+     *
+     * @example Defining publish configuration for a social media platform
+     * ```ts
+     * import type { GetPublishConfigurationResponse } from '@canva/intents/content';
+     *
+     * async function getPublishConfiguration(): Promise<GetPublishConfigurationResponse> {
+     *   return {
+     *     status: 'completed',
+     *     outputTypes: [
+     *       {
+     *         id: 'instagram_post',
+     *         displayName: 'Instagram Post',
+     *         mediaSlots: [
+     *           {
+     *             id: 'main_image',
+     *             displayName: 'Post Image',
+     *             fileCount: { min: 1, max: 10 },
+     *             accepts: {
+     *               image: { format: 'jpg', aspectRatio: { min: 0.8, max: 1.91 } }
+     *             }
+     *           }
+     *         ]
+     *       }
+     *     ]
+     *   };
+     * }
+     * ```
+     */
+    getPublishConfiguration: () => Promise<GetPublishConfigurationResponse>;
+
+    /**
+     * Renders a user interface for configuring publish settings.
+     *
+     * This action is called after the user selects an output type. Your UI should
+     * allow users to configure platform-specific settings such as captions, tags,
+     * 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).
+     *
+     * @param request - Configuration and callbacks for the publish settings UI.
+     *
+     * @example Rendering a settings UI with publish configuration
+     * ```ts
+     * import { createRoot } from 'react-dom/client';
+     * import type { RenderSettingsUiRequest } from '@canva/intents/content';
+     *
+     * function renderSettingsUi(request: RenderSettingsUiRequest): void {
+     *   const SettingsUiApp = () => (
+     *      <AppUiProvider>
+     *       <SettingsUi request={request} />
+     *     </AppUiProvider>
+     *   );
+     *
+     *   createRoot().render(<SettingsUiApp />)
+     * }
+     * ```
+     */
+    renderSettingsUi: (request: RenderSettingsUiRequest) => void;
+    /**
+     * Renders a user interface for previewing the content.
+     *
+     * This action is called after the settings UI is rendered. Your UI should display
+     * a preview of how the content will appear on the target platform.
+     *
+     * Previews update dynamically as users modify their content or settings. For videos,
+     * start with lightweight thumbnails and use `requestPreviewUpgrade` to load full
+     * video previews on demand to optimize performance.
+     *
+     * @param request - Configuration and callbacks for the preview UI.
+     *
+     * @example Rendering a preview UI with video optimization
+     * ```ts
+     * import { createRoot } from 'react-dom/client';
+     * import type { RenderPreviewUiRequest } from '@canva/intents/content';
+     *
+     * function renderPreviewUi(request: RenderPreviewUiRequest): void {
+     *   const PreviewUiApp = () => (
+     *      <AppUiProvider>
+     *       <PreviewUi request={request} />
+     *     </AppUiProvider>
+     *   );
+     *
+     *   createRoot().render(<PreviewUiApp />)
+     * }
+     * ```
+     */
+    renderPreviewUi: (request: RenderPreviewUiRequest) => void;
+    /**
+     * Publishes the content to the external platform.
+     *
+     * This action is called when the user confirms the publish action after reviewing
+     * settings and preview. Your implementation should send the exported files
+     * to your platform's API.
+     *
+     * The `outputMedia` contains production-ready files that match the requirements
+     * specified in your output types. The `publishRef` contains the user's settings
+     * from the settings UI.
+     *
+     * @param request - Parameters for the publish operation.
+     * @returns A promise resolving to either a successful result with the published content details or an error.
+     *
+     * @example Publishing content to an external platform
+     * ```ts
+     * import type { PublishContentRequest, PublishContentResponse } from '@canva/intents/content';
+     *
+     * async function publishContent(request: PublishContentRequest): Promise<PublishContentResponse> {
+     *   const { publishRef, outputType, outputMedia } = request;
+     *
+     *   try {
+     *     // Parse settings from publishRef
+     *     const settings = publishRef ? JSON.parse(publishRef) : {};
+     *
+     *     // Upload files to your platform
+     *     const uploadedFiles = await Promise.all(
+     *       outputMedia.flatMap(media =>
+     *         media.files.map(file => uploadFile(file.url))
+     *       )
+     *     );
+     *
+     *     // Create post on your platform
+     *     const result = await createPost({
+     *       files: uploadedFiles,
+     *       caption: settings.caption
+     *     });
+     *
+     *     return {
+     *       status: 'completed',
+     *       externalId: result.id,
+     *       externalUrl: result.url
+     *     };
+     *   } catch (error) {
+     *     return {
+     *       status: 'remote_request_failed'
+     *     };
+     *   }
+     * }
+     * ```
+     */
+    publishContent: (request: PublishContentRequest) => Promise<PublishContentResponse>;
+
+};
+
+/**
+ * @public
+ * Metadata specific to design content.
+ */
+export declare interface DesignContentMetadata {
+    type: 'design';
+    /**
+     * A signed JWT token containing the design id
+     */
+    designToken: string;
+    /**
+     * The user given title of the design
+     */
+    title: string | undefined;
+    /**
+     * The pages that make up the exported metadata
+     */
+    pages: OutputPageMetadata[];
+}
+
+/**
+ * @public
+ * A function that can be called to dispose of a callback.
+ */
+export declare type Disposer = () => void;
+
+/**
+ * @public
+ * Exported PDF file ready for publishing.
+ *
+ * Contains the final PDF document that should be uploaded to your platform.
+ * The document format is `pdf_standard` and the file is ready to use.
+ */
+export declare type DocumentOutputFile = BaseOutputFile;
+
+/**
+ * @public
+ * Document preview in various states.
+ *
+ * Documents transition through states: `"loading"` → `"thumbnail"`.
+ * Start with a lightweight thumbnail of the first page for quick preview rendering.
+ */
+export declare type DocumentPreview = DocumentPreviewLoading | DocumentPreviewThumbnail | DocumentPreviewError;
+
+/**
+ * @public
+ * Document preview that failed to generate.
+ *
+ * Display an error state to the user.
+ */
+export declare interface DocumentPreviewError extends SizedPreview {
+    kind: 'document';
+    status: 'error';
+    /**
+     * The error message to display to the user.
+     */
+    message: string;
+}
+
+/**
+ * @public
+ * Document preview that is currently being generated.
+ *
+ * Display a loading state until the preview transitions to `"thumbnail"` or `"error"`.
+ */
+export declare interface DocumentPreviewLoading extends SizedPreview {
+    kind: 'document';
+    status: 'loading';
+}
+
+/**
+ * @public
+ * Document preview with first page thumbnail available.
+ *
+ * This is the initial state for document previews. Show the thumbnail image
+ * of the first page along with the page count to give users a preview of
+ * the document before publishing.
+ */
+export declare interface DocumentPreviewThumbnail extends SizedPreview {
+    kind: 'document';
+    status: 'thumbnail';
+    /**
+     * Format of the thumbnail image.
+     */
+    thumbnailFormat: 'png' | 'jpg';
+    /**
+     * URL to the first page thumbnail.
+     *
+     * Display this lightweight image to preview the document content.
+     */
+    thumbnailUrl: string;
+}
+
+/**
+ * @public
+ * Document file requirements for a media slot.
+ *
+ * Note: Document output types use image previews (PNG thumbnails) in the preview UI.
+ * The actual document file is only generated for the final output in OutputMedia.
+ *
+ * @example Document requirements
+ * ```ts
+ * const documentReq: DocumentRequirement = {
+ *   format: 'pdf_standard',
+ *   size: 'a4',
+ * };
+ * ```
+ */
+export declare interface DocumentRequirement extends BaseFileRequirement {
+    /**
+     * Supported document export format.
+     * Currently supports PDF standard format.
+     */
+    format: 'pdf_standard';
+    /**
+     * The document size of the export file.
+     */
+    size: DocumentSize;
+}
+
+/**
+ * @public
+ * Document size for document exports.
+ */
+export declare type DocumentSize = 'a4' | 'a3' | 'letter' | 'legal';
+
+/**
+ * @public
+ *
+ * The cause of an error
+ */
+export declare type ErrorCause = 'invalid_selection' | 'invalid_format';
+
+/**
+ * @public
+ * Exact value range constraint.
+ * @example Exact value range
+ * ```ts
+ * const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
+ * ```
+ */
+export declare type ExactValueRange = {
+    exact: number;
+};
+
+/**
+ * @public
+ * Successful response from getting publish configuration.
+ */
+export declare type GetPublishConfigurationCompleted = {
+    status: 'completed';
+    /**
+     * Array of available output types for your platform.
+     *
+     * Define different output types for various content formats that
+     * your platform supports (e.g., posts, stories, videos).
+     */
+    outputTypes: OutputType[];
+};
+
+/**
+ * @public
+ * {@link GetPublishConfigurationError} error indicating a custom error occurred.
+ */
+export declare type GetPublishConfigurationError = AppError;
+
+/**
+ * @public
+ * Response from getting publish configuration.
+ */
+export declare type GetPublishConfigurationResponse = GetPublishConfigurationCompleted | GetPublishConfigurationError;
+
+/**
+ * @public
+ * Exported image file ready for publishing.
+ */
+export declare interface ImageOutputFile extends BaseOutputFile {
+    /**
+     * Width of the image in pixels.
+     */
+    widthPx: number;
+    /**
+     * Height of the image in pixels.
+     */
+    heightPx: number;
+}
+
+/**
+ * @public
+ * Image preview in various states.
+ */
+export declare type ImagePreview = ImagePreviewLoading | ImagePreviewReady | ImagePreviewError;
+
+/**
+ * @public
+ * Image preview that failed to generate.
+ *
+ * Display an error state to the user.
+ */
+export declare interface ImagePreviewError extends SizedPreview {
+    kind: 'image';
+    status: 'error';
+
+    /**
+     * The error message to display to the user.
+     */
+    message: string;
+}
+
+/**
+ * @public
+ * Image preview that is currently being generated.
+ *
+ * Display a loading state until the preview transitions to `"ready"` or `"error"`.
+ */
+export declare interface ImagePreviewLoading extends SizedPreview {
+    kind: 'image';
+    status: 'loading';
+}
+
+/**
+ * @public
+ * Image preview that is ready to display.
+ *
+ * Contains the URL to the preview image.
+ */
+export declare interface ImagePreviewReady extends SizedPreview {
+    kind: 'image';
+    status: 'ready';
+    /**
+     * Image format of the preview.
+     */
+    format: 'png' | 'jpg';
+    /**
+     * URL to the preview image.
+     *
+     * Use this URL to display the preview to users.
+     */
+    url: string;
+}
+
+/**
+ * @public
+ * Image file requirements for a media slot.
+ *
+ * Specifies format, aspect ratio, and size constraints for images.
+ *
+ * @example Image requirements for social media post
+ * ```ts
+ * const imageReq: ImageRequirement = {
+ *   format: 'jpg',
+ *   aspectRatio: { min: 0.8, max: 1.91 },
+ * };
+ * ```
+ */
+export declare interface ImageRequirement extends BaseFileRequirement {
+    /**
+     * Supported image format.
+     */
+    format: 'png' | 'jpg';
+    /**
+     * Aspect ratio constraint (width / height).
+     *
+     * Examples:
+     * - `{ exact: 16/9 }`: Widescreen (16:9)
+     * - `{ min: 0.8, max: 1.91 }`: Instagram range
+     */
+    aspectRatio?: ValueRange;
+}
+
+/**
+ * @public
+ * Maximum value range constraint.
+ * @example Maximum value range
+ * ```ts
+ * const maxValue: ValueRange = { max: 10 }; // At most 10
+ * ```
+ */
+export declare type MaxValueRange = {
+    max: number;
+};
+
+/**
+ * @public
+ * Configuration for a media slot within an output type.
+ *
+ * Defines what type of media is accepted, requirements, and constraints.
+ *
+ * @example Image slot with aspect ratio requirements
+ * ```ts
+ * const thumbnailSlot: MediaSlot = {
+ *   id: 'thumbnail',
+ *   displayName: 'Video Thumbnail',
+ *   fileCount: { exact: 1 },
+ *   accepts: {
+ *     image: {
+ *       format: 'jpg',
+ *       aspectRatio: { exact: 16/9 },
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export declare type MediaSlot = {
+    /**
+     * Unique identifier for this media slot within the output type.
+     */
+    id: string;
+    /**
+     * User-facing name for this media slot.
+     *
+     * Examples: `"Post Image"`, `"Video Thumbnail"`, `"Main Video"`.
+     */
+    displayName: string;
+    /**
+     * Number of files accepted in this slot.
+     *
+     * Use this to specify single or multiple file requirements.
+     * Examples:
+     * - `{ exact: 1 }`: Exactly one file
+     * - `{ min: 1, max: 10 }`: Between 1 and 10 files
+     * - undefined: Any number of files
+     */
+    fileCount?: ValueRange;
+    /**
+     * File type requirements for this slot.
+     *
+     * Note the following behavior:
+     *
+     * - Provide at least one of `image` or `video`
+     * - If both are provided, files for this slot may be either images or videos; each file
+     *   must satisfy the corresponding requirement for its media type
+     * - To restrict the slot to a single media type, provide only that requirement
+     * - `fileCount` applies across all files accepted by the slot regardless of media type
+     * - Document output types will show image previews (PNG thumbnail) in preview UI
+     */
+    accepts: {
+        image?: ImageRequirement;
+        video?: VideoRequirement;
+        document?: DocumentRequirement;
+
+    };
+};
+
+/**
+ * @public
+ * Minimum and maximum value range constraint.
+ * Ranges are inclusive `(min ≤ value ≤ max)`.
+ * @example Minimum and maximum value range
+ * ```ts
+ * const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
+ * ```
+ */
+export declare type MinMaxValueRange = {
+    min: number;
+    max: number;
+};
+
+/**
+ * @public
+ * Minimum value range constraint.
+ * @example Minimum value range
+ * ```ts
+ * const minValue: ValueRange = { min: 3 }; // At least 3
+ * ```
+ */
+export declare type MinValueRange = {
+    min: number;
+};
+
+/** @public */
+export declare type OnContextChange = (context: SettingsUiContext) => void;
+
+/**
+ * @public
+ * Exported file ready for publishing.
+ */
+export declare type OutputFile = ImageOutputFile | VideoOutputFile | DocumentOutputFile;
+
+/**
+ * @public
+ * Production-ready exported files for a specific media slot.
+ *
+ * These are the final files that should be uploaded to your platform.
+ */
+export declare type OutputMedia = {
+    /**
+     * ID of the media slot these files belong to.
+     *
+     * Matches a media slot ID from your output type definition.
+     */
+    mediaSlotId: string;
+    /**
+     * Array of exported files for this media slot.
+     *
+     * Files match the requirements specified in your media slot configuration.
+     */
+    files: OutputFile[];
+};
+
+/**
+ * @public
+ * Metadata about a specific page in the exported content.
+ */
+export declare type OutputPageMetadata = {
+    /**
+     * The unique identifier for the page.
+     */
+    pageId: string | undefined;
+    /**
+     * The position of the page within the design, starting from 1 for the first page.
+     */
+    pageNumber: number;
+};
+
+/**
+ * @public
+ * Configuration for an output type.
+ *
+ * Defines a specific publishing format your platform supports,
+ * including what media is required and accepted file types.
+ *
+ * @example Defining an Instagram post output type
+ * ```ts
+ * const instagramPost: OutputType = {
+ *   id: 'instagram_post',
+ *   displayName: 'Instagram Post',
+ *   mediaSlots: [
+ *     {
+ *       id: 'main_image',
+ *       displayName: 'Post Image',
+ *       fileCount: { min: 1, max: 10 },
+ *       accepts: {
+ *         image: {
+ *           format: 'jpg',
+ *           aspectRatio: { min: 0.8, max: 1.91 },
+ *         }
+ *       }
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+export declare type OutputType = {
+    /**
+     * Unique identifier for this output type.
+     *
+     * Use descriptive IDs like `"instagram_post"` or `"youtube_video"`.
+     */
+    id: string;
+    /**
+     * User-facing name for this output type.
+     *
+     * This is displayed to users when selecting where to publish.
+     * Examples: `"Instagram Post"`, `"YouTube Video"`, `"Twitter Post"`.
+     */
+    displayName: string;
+    /**
+     * Array of media slots defining what content is needed.
+     *
+     * Each slot represents a piece of media required for publishing,
+     * such as a main image, thumbnail, or video.
+     */
+    mediaSlots: MediaSlot[];
+};
+
+/**
+ * @public
+ * Action to be taken after publishing completes successfully.
+ */
+export declare type PostPublishAction = PostPublishActionRedirect;
+
+/**
+ * @public
+ * Redirect action to navigate the user to a URL after publishing.
+ *
+ * @example Redirecting to content editor
+ * ```ts
+ * const postPublishAction: PostPublishActionRedirect = {
+ *   type: 'redirect',
+ *   url: 'https://example.com/posts/12345/edit'
+ * };
+ * ```
+ */
+export declare type PostPublishActionRedirect = {
+    type: 'redirect';
+    /**
+     * The URL to redirect the user to after publishing.
+     */
+    url: string;
+};
+
+/**
+ * @public
+ *
+ * Prepares a {@link ContentPublisherIntent|Content Publisher Intent}.
+ *
+ * @example
+ * ```tsx
+ * import { prepareContentPublisher } from "@canva/intents/content";
+ *
+ * prepareContentPublisher({
+ *  getPublishConfiguration: async (params) => {
+ *    // Implement the logic to get the publish configuration
+ *  },
+ *  renderSettingsUi: (params) => {
+ *    // Implement the UI for settings view
+ *  },
+ *  renderPreviewUi: (params) => {
+ *    // Implement the UI for preview view
+ *  },
+ *  publishContent: async (params) => {
+ *    // Implement the logic to publish the content
+ *  },
+ * });
+ * ```
+ */
+export declare const prepareContentPublisher: (implementation: ContentPublisherIntent) => void;
+
+/**
+ * @public
+ * Preview item for an image or video.
+ *
+ * Check the `kind` and `status` properties to determine the type and state.
+ */
+export declare type Preview = ImagePreview | VideoPreview | DocumentPreview | {
+    kind: 'email';
+};
+
+/**
+ * @public
+ * Type of preview media.
+ */
+export declare type PreviewKind = 'image' | 'video' | 'document' | 'email';
+
+/**
+ * @public
+ * Preview media for a specific media slot.
+ *
+ * Contains preview URLs and metadata for images or videos in the design.
+ */
+export declare type PreviewMedia = {
+    /**
+     * ID of the media slot this preview belongs to.
+     *
+     * Matches a media slot ID from your output type definition.
+     */
+    mediaSlotId: string;
+    /**
+     * Array of preview items for this media slot.
+     *
+     * May contain multiple previews if the media slot accepts multiple files.
+     */
+    previews: Preview[];
+};
+
+/**
+ * @public
+ * State of a preview item.
+ */
+export declare type PreviewStatus = 'loading' | 'thumbnail' | 'upgrading' | 'ready' | 'error';
+
+/**
+ * @public
+ * Successful response from publishing a content.
+ *
+ * @example Basic successful publish
+ * ```ts
+ * return {
+ *   status: 'completed',
+ *   externalId: 'post_12345',
+ *   externalUrl: 'https://example.com/posts/12345'
+ * };
+ * ```
+ *
+ * @example Successful publish with redirect
+ * ```ts
+ * return {
+ *   status: 'completed',
+ *   externalId: 'video_67890',
+ *   externalUrl: 'https://example.com/videos/67890',
+ *   postPublishAction: {
+ *     type: 'redirect',
+ *     url: 'https://example.com/videos/67890/edit'
+ *   }
+ * };
+ * ```
+ */
+export declare type PublishContentCompleted = {
+    status: 'completed';
+    /**
+     * Unique identifier returned from your external platform. You can use this for:
+     *
+     * - Tracking published content
+     * - Fetching insights data for the published content
+     * - Linking back to the content in future operations
+     */
+    externalId?: string;
+    /**
+     * Direct URL to the published content on your platform.
+     *
+     * Users can visit this URL to view their published content.
+     * This may be displayed to users or used for sharing.
+     */
+    externalUrl?: string;
+    /**
+     * Optional action to perform after publishing completes.
+     *
+     * Currently supports redirecting users to a specific URL after publishing.
+     */
+    postPublishAction?: PostPublishAction;
+};
+
+/**
+ * @public
+ * Error response from publishing a content.
+ *
+ * Return the appropriate error type based on the failure:
+ *
+ * - `"remote_request_failed"`: Network or API errors with your platform
+ * - `"app_error"`: Custom application errors with optional message
+ */
+export declare type PublishContentError = RemoteRequestFailedError | AppError;
+
+/**
+ * @public
+ * Parameters required for publishing the content.
+ * Contains all the information needed to send the content to your external platform.
+ */
+export declare type PublishContentRequest = {
+    /**
+     * Platform-specific settings reference containing user configurations.
+     *
+     * 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
+     */
+    publishRef?: string;
+    /**
+     * The output type selected by the user for this publish operation.
+     *
+     * This matches one of the output types you provided in `getPublishConfiguration`.
+     */
+    outputType: OutputType;
+    /**
+     * Production-ready exported files matching the requirements from your output type.
+     *
+     * These files are ready to upload to your platform and match the format, size,
+     * and aspect ratio requirements specified in your media slots.
+     */
+    outputMedia: OutputMedia[];
+};
+
+/**
+ * @public
+ * Response from a publish content operation.
+ *
+ * This can be either a successful completion or an error response.
+ */
+export declare type PublishContentResponse = PublishContentCompleted | PublishContentError;
+
+/** @public */
+export declare type PublishError = {
+    appDefinedPayload?: string;
+};
+
+/**
+ * @public
+ * Signals that the publish error was cleared.
+ */
+export declare type PublishErrorClearedSettingsUiContext = {
+    reason: 'publish_error_cleared';
+};
+
+/**
+ * @public
+ * Provides information about an error that occurred in publishContent.
+ */
+export declare type PublishErrorSettingsUiContext = {
+    reason: 'publish_error';
+    /**
+     * The error that occurred. Undefined means no error occurred or the previous
+     * error was cleared by Canva.
+     */
+    error: PublishError;
+};
+
+/**
+ * @public
+ * Supported file formats for publishing.
+ */
+export declare type PublishFileFormat = 'png' | 'jpg' | 'mp4' | 'pdf_standard' | 'html_bundle';
+
+/**
+ * @public
+ * Validation state indicating whether publish settings are complete and valid.
+ */
+export declare type PublishRefValidityState = 'valid' | 'invalid_missing_required_fields' | 'invalid_authentication_required';
+
+/**
+ * @public
+ * Configuration for publish settings.
+ *
+ * Contains the user's settings and their validation state. Use this to
+ * control whether the publish button is enabled.
+ */
+export declare type PublishSettings = {
+    /**
+     * Serialized platform-specific settings for publishing.
+     *
+     * Store all information your app needs to publish the content in this string.
+     * This might include:
+     *
+     * - Captions or descriptions
+     * - Tags or hashtags
+     * - Privacy settings
+     * - Publishing destination (account, page, etc.)
+     * - Scheduling information
+     *
+     * This reference will be provided to your `publishContent` method when publishing.
+     *
+     * Maximum size: 5KB
+     *
+     * @example Serializing settings
+     * ```ts
+     * const settings = {
+     *   caption: 'Check out my design!',
+     *   tags: ['design', 'creative'],
+     *   privacy: 'public'
+     * };
+     * const publishRef = JSON.stringify(settings);
+     * ```
+     */
+    publishRef?: string;
+    /**
+     * Validation state of the publish settings.
+     *
+     * Controls whether the publish button is enabled:
+     *
+     * - `"valid"`: Settings are complete and valid, publish button is enabled
+     * - `"invalid_missing_required_fields"`: Required settings are missing, publish button is disabled
+     * - `"invalid_authentication_required"`: User must authenticate before publishing can proceed
+     */
+    validityState: PublishRefValidityState;
+};
+
+/**
+ * @public
+ * Provides information about the current state of the settings UI to help
+ * you adapt the interface based on the selected output type.
+ */
+export declare type PublishSettingsSettingsUiContext = {
+    reason: 'publish_settings';
+    /**
+     * The currently selected output type.
+     *
+     * Use this to customize your settings UI based on the requirements
+     * of different output types.
+     */
+    outputType: OutputType;
+};
+
+/**
+ * @public
+ * {@link PublishContentError} indicating failure of the remote request to the external platform.
+ *
+ * Return this error for:
+ *
+ * - Network connectivity issues
+ * - API endpoint failures
+ * - HTTP errors from your platform
+ * - Timeout errors
+ *
+ * @example Handling network errors
+ * ```ts
+ * try {
+ *   await uploadToExternalPlatform(file);
+ * } catch (error) {
+ *   return { status: 'remote_request_failed' };
+ * }
+ * ```
+ */
+export declare type RemoteRequestFailedError = {
+    status: 'remote_request_failed';
+};
+
+/**
+ * @public
+ * Configuration required for rendering the preview UI.
+ *
+ * Provides callbacks for managing preview media and responding to preview updates.
+ */
+export declare type RenderPreviewUiRequest = {
+    /**
+     * Callback to upgrade video thumbnail previews to full video media.
+     *
+     * Call this function when you need full video previews instead of lightweight thumbnails.
+     * This helps optimize performance by deferring full video loading until needed.
+     *
+     * Upgrades may complete asynchronously; listen to `registerOnPreviewChange` for updates
+     * to receive the upgraded video previews.
+     *
+     * @param previewIds - Array of preview IDs to upgrade from thumbnail to full video
+     *
+     * @example Upgrading video previews on user interaction
+     * ```ts
+     * // When user clicks on a video thumbnail, upgrade to full video
+     * if (preview.kind === 'video' && preview.status === 'thumbnail') {
+     *   requestPreviewUpgrade([preview.id]);
+     * }
+     * ```
+     */
+    requestPreviewUpgrade: (previewIds: string[]) => void;
+    /**
+     * Registers a callback to be invoked when preview data changes.
+     *
+     * This callback is triggered when:
+     *
+     * - The design content changes
+     * - The output type changes
+     * - Preview media is upgraded from thumbnail to full video
+     * - Export settings are modified
+     *
+     * Use this to update your preview UI in real-time as users modify their design.
+     *
+     * @param callback - The callback invoked when preview data is updated
+     * @returns A disposer function that cleans up the registered callback
+     *
+     * @example Handling preview updates
+     * ```ts
+     * const disposer = registerOnPreviewChange(({ previewMedia, outputType, publishRef }) => {
+     *   // Update your preview UI with the new preview media
+     *   previewMedia.forEach((media) => {
+     *     media.previews.forEach((preview) => {
+     *       if (preview.status === 'ready') {
+     *         displayPreview(preview);
+     *       }
+     *     });
+     *   });
+     * });
+     *
+     * // Clean up when preview UI is unmounted
+     * onUnmount(() => disposer());
+     * ```
+     */
+    registerOnPreviewChange: (callback: (opts: {
+        previewMedia: PreviewMedia[];
+        /** The output type that the preview data is for */
+        outputType: OutputType;
+        /** The current publish settings reference, if available */
+        publishRef?: string;
+    }) => void) => Disposer;
+};
+
+/**
+ * @public
+ * Configuration for the publish settings UI.
+ *
+ * This type provides the necessary callbacks and configuration for rendering
+ * a custom publish settings interface where users configure platform-specific options.
+ */
+export declare type RenderSettingsUiRequest = {
+    /**
+     * Callback to save and validate the user's publish settings.
+     *
+     * Call this function whenever the user modifies their settings to:
+     *
+     * - Save the settings for later use in `publishContent`
+     * - Validate that required fields are filled
+     * - Enable or disable the publish button based on validity
+     *
+     * Store all necessary publishing information in the `publishRef` string.
+     * This will be provided to your `publishContent` method when the user publishes.
+     *
+     * @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.
+     *
+     * @example Updating settings as user types
+     * ```ts
+     * // As user fills in form fields, update settings
+     * function handleCaptionChange(caption: string) {
+     *   const settings = { caption, tags: currentTags };
+     *   const publishRef = JSON.stringify(settings);
+     *
+     *   updatePublishSettings({
+     *     publishRef,
+     *     validityState: caption ? 'valid' : 'invalid_missing_required_fields'
+     *   });
+     * }
+     * ```
+     */
+    updatePublishSettings: (publishSettings: PublishSettings) => Promise<UpdatePublishSettingsResponse>;
+
+    /**
+     * Registers a callback to be invoked when the settings UI context changes.
+     *
+     * This callback is triggered when:
+     * - the user changes the output type in the publish flow.
+     * - an error occurs in the publish flow.
+     *
+     * Use this to respond to Canva changes and update your settings UI accordingly.
+     *
+     * @param opts - The options for registering a callback.
+     * @returns A disposer function that cleans up the registered callback.
+     *
+     * @example Adapting UI for different output types
+     * ```ts
+     * registerOnContextChange({
+     *   onContextChange: (ctx) => {
+     *     if (ctx.reason === 'publish_settings') {
+     *       if (ctx.outputType.id === 'instagram_post') {
+     *         showHashtagField();
+     *       }
+     *     }
+     *     if (ctx.reason === 'publish_error') {
+     *       setError(ctx.error);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    registerOnContextChange: (opts: {
+        onContextChange: OnContextChange;
+    }) => Disposer;
+};
+
+/**
+ * @public
+ * Context information for the publish settings UI.
+ */
+export declare type SettingsUiContext = PublishSettingsSettingsUiContext | PublishErrorSettingsUiContext | PublishErrorClearedSettingsUiContext;
+
+/**
+ * @public
+ * Base interface for all preview types that have a fixed width and height.
+ */
+export declare interface SizedPreview extends BasePreview {
+    /**
+     * Width of the preview in pixels.
+     */
+    widthPx: number;
+    /**
+     * Height of the preview in pixels.
+     */
+    heightPx: number;
+}
+
+/**
+ * @public
+ * Successful response from updating the publish settings.
+ */
+export declare type UpdatePublishSettingsCompleted = {
+    status: 'completed';
+};
+
+/**
+ * @public
+ * Response from updating the publish settings.
+ */
+export declare type UpdatePublishSettingsResponse = UpdatePublishSettingsCompleted;
+
+/**
+ * @public
+ * Numeric value range constraint.
+ * Used to specify requirements for aspect ratios, durations, file counts, etc.
+ */
+export declare type ValueRange = ExactValueRange | MinValueRange | MaxValueRange | MinMaxValueRange;
+
+/**
+ * @public
+ * Exported video file ready for publishing.
+ */
+export declare interface VideoOutputFile extends BaseOutputFile {
+    /**
+     * Width of the video in pixels.
+     */
+    widthPx: number;
+    /**
+     * Height of the video in pixels.
+     */
+    heightPx: number;
+}
+
+/**
+ * @public
+ * Video preview in various states.
+ *
+ * Videos transition through states: `"loading"` → `"thumbnail"` → `"upgrading"` → `"ready"`.
+ * Start with thumbnails for better performance, then upgrade to full video using `requestPreviewUpgrade`.
+ */
+export declare type VideoPreview = VideoPreviewLoading | VideoPreviewThumbnail | VideoPreviewUpgrading | VideoPreviewReady | VideoPreviewError;
+
+/**
+ * @public
+ * Video preview that failed to generate.
+ *
+ * Display an error state to the user.
+ */
+export declare interface VideoPreviewError extends SizedPreview {
+    kind: 'video';
+    status: 'error';
+
+    /**
+     * The error message to display to the user.
+     */
+    message: string;
+}
+
+/**
+ * @public
+ * Video preview that is currently being generated.
+ *
+ * Display a loading state until the preview transitions to `"thumbnail"` or `"error"`.
+ */
+export declare interface VideoPreviewLoading extends SizedPreview {
+    kind: 'video';
+    status: 'loading';
+    /**
+     * Video duration in milliseconds.
+     */
+    durationMs?: number;
+}
+
+/**
+ * @public
+ * Video preview with full video ready to play.
+ *
+ * Contains URLs for both the video and thumbnail.
+ */
+export declare interface VideoPreviewReady extends SizedPreview {
+    kind: 'video';
+    status: 'ready';
+    /**
+     * Video format.
+     */
+    format: 'mp4';
+    /**
+     * URL to the full video.
+     *
+     * Use this URL in a video player.
+     */
+    url: string;
+    /**
+     * Format of the thumbnail image.
+     */
+    thumbnailFormat: 'png' | 'jpg';
+    /**
+     * URL to the thumbnail image.
+     *
+     * Can be used as a poster image for the video player.
+     */
+    thumbnailUrl: string;
+    /**
+     * Video duration in milliseconds.
+     */
+    durationMs?: number;
+}
+
+/**
+ * @public
+ * Video preview with lightweight thumbnail available.
+ *
+ * This is the initial state for video previews. Show the thumbnail image
+ * and call `requestPreviewUpgrade` when the user needs the full video.
+ */
+export declare interface VideoPreviewThumbnail extends SizedPreview {
+    kind: 'video';
+    status: 'thumbnail';
+    /**
+     * Format of the thumbnail image.
+     */
+    thumbnailFormat: 'png' | 'jpg';
+    /**
+     * URL to the thumbnail image.
+     *
+     * Display this lightweight image until full video is needed.
+     */
+    thumbnailUrl: string;
+    /**
+     * Video duration in milliseconds.
+     */
+    durationMs?: number;
+}
+
+/**
+ * @public
+ * Video preview that is being upgraded from thumbnail to full video.
+ *
+ * Display the thumbnail with a loading indicator until the video is ready.
+ */
+export declare interface VideoPreviewUpgrading extends SizedPreview {
+    kind: 'video';
+    status: 'upgrading';
+    /**
+     * Format of the thumbnail image.
+     */
+    thumbnailFormat: 'png' | 'jpg';
+    /**
+     * URL to the thumbnail image.
+     *
+     * Continue showing the thumbnail while the full video loads.
+     */
+    thumbnailUrl: string;
+    /**
+     * Video duration in milliseconds.
+     */
+    durationMs?: number;
+}
+
+/**
+ * @public
+ * Video file requirements for a media slot.
+ *
+ * Specifies format, aspect ratio, duration, and size constraints for videos.
+ *
+ * @example Video requirements for YouTube
+ * ```ts
+ * const videoReq: VideoRequirement = {
+ *   format: 'mp4',
+ *   aspectRatio: { exact: 16/9 },
+ *   durationMs: { min: 1000, max: 600000 },
+ * };
+ * ```
+ */
+export declare interface VideoRequirement extends BaseFileRequirement {
+    /**
+     * Supported video format.
+     */
+    format: 'mp4';
+    /**
+     * Aspect ratio constraint (width / height).
+     *
+     * Examples:
+     * - `{ exact: 16/9 }`: Widescreen
+     * - `{ exact: 9/16 }`: Vertical/Story format
+     */
+    aspectRatio?: ValueRange;
+    /**
+     * Duration constraint in milliseconds.
+     *
+     * Examples:
+     * - `{ max: 60000 }`: Maximum 60 seconds
+     * - `{ min: 3000, max: 600000 }`: Between 3 seconds and 10 minutes
+     */
+    durationMs?: ValueRange;
+
+}
+
+export { }