@canva/platform 2.2.0-beta.1 → 2.2.1-beta.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# CHANGELOG
+
+## 2.2.1-beta.0 - 2025-12-18
+
+- Initial changelog for the Preview Platform SDK.

package/beta.d.ts

@@ -3,181 +3,175 @@
  * Provides methods for interacting with an app process.
  */
 export declare interface AppProcess {
-  /**
-   * The current app process.
-   */
-  readonly current: CurrentAppProcess;
-  /**
-   * @public
-   * Requests the termination of the specified app process.
-   *
-   * @param target - The ID of an app process.
-   * @param params - Parameters to pass to the `setOnDispose` callback. Any kind of structured data can be passed via this property.
-   *
-   * @remarks
-   * Once called, this method:
-   *
-   * 1. Transitions the state of the process to `"closing"`.
-   * 2. Invokes all registered `setOnDispose` callbacks.
-   * 3. Waits for the process to finish closing.
-   * 4. Transitions the state of the process to `"closed"`.
-   *
-   * Each time the state changes, all of the `registerOnStateChange` callbacks are called.
-   *
-   * @example Close a process
-   * ```typescript
-   * import { appProcess, type AppProcessId } from '@canva/platform';
-   *
-   * const placeholderProcessId = "PLACEHOLDER_PROCESS_ID" as AppProcessId;
-   *
-   * await appProcess.requestClose(placeholderProcessId, { reason: 'completed' });
-   * ```
-   *
-   * @example Pass structured data to a process as it closes
-   * ```typescript
-   * import { appProcess, type AppProcessId, type CloseParams } from '@canva/platform';
-   *
-   * type DetailedCloseParams = CloseParams & {
-   *   savePoint: string;
-   *   timestamp: number;
-   *   userInitiated: boolean;
-   * };
-   *
-   * const placeholderProcessId = "PLACEHOLDER_PROCESS_ID" as AppProcessId;
-   *
-   * await appProcess.requestClose<DetailedCloseParams>(placeholderProcessId, {
-   *   reason: 'completed',
-   *   savePoint: 'auto_backup_1',
-   *   timestamp: Date.now(),
-   *   userInitiated: true
-   * });
-   * ```
-   */
-  requestClose<T extends CloseParams>(
-    target: AppProcessId,
-    params: T,
-  ): Promise<void>;
-  /**
-   * @public
-   * Registers a callback that runs when the state of the specified app process changes.
-   *
-   * @param target - The ID of an app process.
-   * @param callback - The callback to run when the state of the process changes.
-   *
-   * @returns
-   * A disposer function that cleans up the registered callback.
-   *
-   * @example Listen for process state changes
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * const stateDisposer = appProcess.registerOnStateChange(
-   *   processId,
-   *   ({ state }) => {
-   *     switch (state) {
-   *       case 'opening':
-   *         // Process is starting up
-   *         break;
-   *       case 'open':
-   *         // Process is active and visible
-   *         break;
-   *       case 'closing':
-   *         // Process is about to close
-   *         // Save state, cleanup resources
-   *         break;
-   *       case 'closed':
-   *         // Process has been terminated
-   *         // Final cleanup if needed
-   *         break;
-   *     }
-   *   }
-   * );
-   *
-   * // Later: cleanup the listener
-   * await stateDisposer();
-   * ```
-   */
-  registerOnStateChange(
-    target: AppProcessId,
-    callback: OnStateChangeCallback,
-  ): () => Promise<void>;
-  /**
-   * @public
-   * Registers a callback that listens for broadcasted messages.
-   *
-   * @param callback - The callback that listens for broadcasted messages.
-   *
-   * @returns
-   * A disposer function that cleans up the registered callback.
-   *
-   * @example Listen for inter-process messages
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * const messageDisposer = appProcess.registerOnMessage(async (sender, message) => {
-   *   const { appProcessId, surface } = sender;
-   *   // Handle message from other process
-   * });
-   *
-   * // Later: cleanup the listener
-   * await messageDisposer();
-   * ```
-   */
-  registerOnMessage(callback: OnMessageCallback): () => Promise<void>;
-  /**
-   * @public
-   * Broadcasts a message to all of the app's active processes, not including the current process.
-   *
-   * @param message - The message to be broadcasted. This can be any kind of structured data.
-   *
-   * @example Broadcast primitive values
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * // Broadcasting a string
-   * appProcess.broadcastMessage('REFRESH_REQUESTED');
-   *
-   * // Broadcasting a number
-   * appProcess.broadcastMessage(42);
-   *
-   * // Broadcasting a boolean
-   * appProcess.broadcastMessage(true);
-   * ```
-   *
-   * @example Broadcast simple objects
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * appProcess.broadcastMessage({
-   *   id: 'user-123',
-   *   name: 'John Doe',
-   *   active: true
-   * });
-   * ```
-   *
-   * @example Broadcast complex objects
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * appProcess.broadcastMessage({
-   *   type: 'DOCUMENT_UPDATE',
-   *   timestamp: Date.now(),
-   *   payload: {
-   *     documentId: 'doc-123',
-   *     version: 2,
-   *     metadata: {
-   *       title: 'Project Alpha',
-   *       tags: ['draft', 'review-needed'],
-   *       collaborators: [
-   *         { id: 'user-1', role: 'editor' },
-   *         { id: 'user-2', role: 'viewer' }
-   *       ]
-   *     }
-   *   }
-   * });
-   * ```
-   */
-  broadcastMessage(message: any): void;
+    /**
+     * The current app process.
+     */
+    readonly current: CurrentAppProcess;
+    /**
+     * @public
+     * Requests the termination of the specified app process.
+     *
+     * @param target - The ID of an app process.
+     * @param params - Parameters to pass to the `setOnDispose` callback. Any kind of structured data can be passed via this property.
+     *
+     * @remarks
+     * Once called, this method:
+     *
+     * 1. Transitions the state of the process to `"closing"`.
+     * 2. Invokes all registered `setOnDispose` callbacks.
+     * 3. Waits for the process to finish closing.
+     * 4. Transitions the state of the process to `"closed"`.
+     *
+     * Each time the state changes, all of the `registerOnStateChange` callbacks are called.
+     *
+     * @example Close a process
+     * ```typescript
+     * import { appProcess, type AppProcessId } from '@canva/platform';
+     *
+     * const placeholderProcessId = "PLACEHOLDER_PROCESS_ID" as AppProcessId;
+     *
+     * await appProcess.requestClose(placeholderProcessId, { reason: 'completed' });
+     * ```
+     *
+     * @example Pass structured data to a process as it closes
+     * ```typescript
+     * import { appProcess, type AppProcessId, type CloseParams } from '@canva/platform';
+     *
+     * type DetailedCloseParams = CloseParams & {
+     *   savePoint: string;
+     *   timestamp: number;
+     *   userInitiated: boolean;
+     * };
+     *
+     * const placeholderProcessId = "PLACEHOLDER_PROCESS_ID" as AppProcessId;
+     *
+     * await appProcess.requestClose<DetailedCloseParams>(placeholderProcessId, {
+     *   reason: 'completed',
+     *   savePoint: 'auto_backup_1',
+     *   timestamp: Date.now(),
+     *   userInitiated: true
+     * });
+     * ```
+     */
+    requestClose<T extends CloseParams>(target: AppProcessId, params: T): Promise<void>;
+    /**
+     * @public
+     * Registers a callback that runs when the state of the specified app process changes.
+     *
+     * @param target - The ID of an app process.
+     * @param callback - The callback to run when the state of the process changes.
+     *
+     * @returns
+     * A disposer function that cleans up the registered callback.
+     *
+     * @example Listen for process state changes
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * const stateDisposer = appProcess.registerOnStateChange(
+     *   processId,
+     *   ({ state }) => {
+     *     switch (state) {
+     *       case 'opening':
+     *         // Process is starting up
+     *         break;
+     *       case 'open':
+     *         // Process is active and visible
+     *         break;
+     *       case 'closing':
+     *         // Process is about to close
+     *         // Save state, cleanup resources
+     *         break;
+     *       case 'closed':
+     *         // Process has been terminated
+     *         // Final cleanup if needed
+     *         break;
+     *     }
+     *   }
+     * );
+     *
+     * // Later: cleanup the listener
+     * await stateDisposer();
+     * ```
+     */
+    registerOnStateChange(target: AppProcessId, callback: OnStateChangeCallback): () => Promise<void>;
+    /**
+     * @public
+     * Registers a callback that listens for broadcasted messages.
+     *
+     * @param callback - The callback that listens for broadcasted messages.
+     *
+     * @returns
+     * A disposer function that cleans up the registered callback.
+     *
+     * @example Listen for inter-process messages
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * const messageDisposer = appProcess.registerOnMessage(async (sender, message) => {
+     *   const { appProcessId, surface } = sender;
+     *   // Handle message from other process
+     * });
+     *
+     * // Later: cleanup the listener
+     * await messageDisposer();
+     * ```
+     */
+    registerOnMessage(callback: OnMessageCallback): () => Promise<void>;
+    /**
+     * @public
+     * Broadcasts a message to all of the app's active processes, not including the current process.
+     *
+     * @param message - The message to be broadcasted. This can be any kind of structured data.
+     *
+     * @example Broadcast primitive values
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * // Broadcasting a string
+     * appProcess.broadcastMessage('REFRESH_REQUESTED');
+     *
+     * // Broadcasting a number
+     * appProcess.broadcastMessage(42);
+     *
+     * // Broadcasting a boolean
+     * appProcess.broadcastMessage(true);
+     * ```
+     *
+     * @example Broadcast simple objects
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * appProcess.broadcastMessage({
+     *   id: 'user-123',
+     *   name: 'John Doe',
+     *   active: true
+     * });
+     * ```
+     *
+     * @example Broadcast complex objects
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * appProcess.broadcastMessage({
+     *   type: 'DOCUMENT_UPDATE',
+     *   timestamp: Date.now(),
+     *   payload: {
+     *     documentId: 'doc-123',
+     *     version: 2,
+     *     metadata: {
+     *       title: 'Project Alpha',
+     *       tags: ['draft', 'review-needed'],
+     *       collaborators: [
+     *         { id: 'user-1', role: 'editor' },
+     *         { id: 'user-2', role: 'viewer' }
+     *       ]
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    broadcastMessage(message: any): void;
 }
 
 /**
@@ -191,7 +185,7 @@ export declare const appProcess: AppProcess;
  * The unique identifier of an app process.
  */
 export declare type AppProcessId = string & {
-  __appProcessId: never;
+    __appProcessId: never;
 };
 
 /**
@@ -199,18 +193,18 @@ export declare type AppProcessId = string & {
  * Information about an app process.
  */
 export declare type AppProcessInfo<T> = {
-  /**
-   * The surface on which the app process is running.
-   */
-  surface: AppSurface;
-  /**
-   * The unique identifier of the app process.
-   */
-  processId: AppProcessId;
-  /**
-   * Parameters passed to the app process when it was opened.
-   */
-  launchParams?: T;
+    /**
+     * The surface on which the app process is running.
+     */
+    surface: AppSurface;
+    /**
+     * The unique identifier of the app process.
+     */
+    processId: AppProcessId;
+    /**
+     * Parameters passed to the app process when it was opened.
+     */
+    launchParams?: T;
 };
 
 /**
@@ -224,20 +218,17 @@ export declare type AppProcessInfo<T> = {
  * - `"object_panel"` - A surface that renders a user interface in the side panel of the Canva editor.
  * - `"selected_image_overlay"` - A surface that can be opened on top of a selected image.
  */
-export declare type AppSurface =
-  | "object_panel"
-  | "selected_image_overlay"
-  | "headless";
+export declare type AppSurface = 'object_panel' | 'selected_image_overlay' | 'headless';
 
 /**
  * @public
  * Parameters passed to the `setOnDispose` callback when a process is about to close.
  */
 export declare type CloseParams = {
-  /**
-   * The reason the app process is closing.
-   */
-  reason: CloseReason;
+    /**
+     * The reason the app process is closing.
+     */
+    reason: CloseReason;
 };
 
 /**
@@ -250,134 +241,132 @@ export declare type CloseParams = {
  * - `"completed"` - Indicates that a workflow has been completed and unsaved changes should be saved.
  * - `"aborted"` - Indicates that a workflow has been abandoned and unsaved changes should be discarded.
  */
-export declare type CloseReason = "completed" | "aborted";
+export declare type CloseReason = 'completed' | 'aborted';
 
 /**
  * @public
  * Provides methods for interacting with the current app process.
  */
 export declare type CurrentAppProcess = {
-  /**
-   * @public
-   * Returns information about the current app process.
-   *
-   * @example Get current process information
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * const currentProcess = appProcess.current;
-   * const processInfo = currentProcess.getInfo();
-   * ```
-   *
-   * @example Check current process surface type
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * const currentProcess = appProcess.current;
-   * const { surface } = currentProcess.getInfo();
-   *
-   * if (surface === 'object_panel') {
-   *   // This app is running in the object panel
-   * }
-   * ```
-   *
-   * @example Read current process launch parameters
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * type MyLaunchParams ={
-   *   mode: 'edit' | 'view';
-   *   id: string;
-   * }
-   *
-   * const currentProcess = appProcess.current;
-   * const { launchParams } = currentProcess.getInfo<MyLaunchParams>();
-   *
-   * if (launchParams) {
-   *   const { mode, id } = launchParams;
-   *   // Use launch parameters
-   * }
-   * ```
-   */
-  getInfo<T>(): AppProcessInfo<T>;
-  /**
-   * @public
-   * Requests the termination of the current process.
-   *
-   * @param params - Parameters to pass to the `setOnDispose` callback. Any structured data can be passed via this property.
-   *
-   * @remarks
-   * Once called, this method:
-   *
-   * 1. Transitions the state of the process to `"closing"`.
-   * 2. Invokes all registered `setOnDispose` callbacks.
-   * 3. Waits for the process to finish closing.
-   * 4. Transitions the state of the process to `"closed"`.
-   *
-   * Each time the state changes, all of the `registerOnStateChange` callbacks are called.
-   *
-   * @example Close current process
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * await appProcess.current.requestClose({ reason: 'completed' });
-   * ```
-   *
-   * @example Pass structured data to current process as it closes
-   * ```typescript
-   * import { appProcess, type CloseParams } from '@canva/platform';
-   *
-   * type DetailedCloseParams = CloseParams & {
-   *   metadata: {
-   *     savePoint: string;
-   *     timestamp: number;
-   *     userInitiated: boolean;
-   *   }
-   * };
-   *
-   * await appProcess.current.requestClose<DetailedCloseParams>({
-   *   reason: 'completed',
-   *   metadata: {
-   *     savePoint: 'auto_backup_1',
-   *     timestamp: Date.now(),
-   *     userInitiated: true
-   *   }
-   * });
-   * ```
-   */
-  requestClose<T extends CloseParams>(params: T): Promise<void>;
-  /**
-   * @public
-   * Registers a callback that runs when the current app process is about to close.
-   *
-   * @param callback - The callback to run when the current app process is about to close.
-   *
-   * @returns
-   * A disposer function that cleans up the registered callback.
-   *
-   * @remarks
-   * - Apps can't register multiple callbacks.
-   * - If an app attempts to register multiple callbacks, only the last callback will be registered.
-   * - The app process will remain open until the callback resolves or a timeout error occurs.
-   * - The complete execution of the callback is not guaranteed as some user actions (e.g. closing tabs) may close the process prematurely.
-   *
-   * @example Handle process cleanup
-   * ```typescript
-   * import { appProcess } from '@canva/platform';
-   *
-   * const cleanupDisposer = appProcess.current.setOnDispose(async (params) => {
-   *   if (params.reason === 'completed') {
-   *     await saveChanges();
-   *   }
-   * });
-   *
-   * // Later: cleanup the listener
-   * await cleanupDisposer();
-   * ```
-   */
-  setOnDispose<T extends CloseParams>(
-    callback: OnDisposeCallback<T>,
-  ): () => Promise<void>;
+    /**
+     * @public
+     * Returns information about the current app process.
+     *
+     * @example Get current process information
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * const currentProcess = appProcess.current;
+     * const processInfo = currentProcess.getInfo();
+     * ```
+     *
+     * @example Check current process surface type
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * const currentProcess = appProcess.current;
+     * const { surface } = currentProcess.getInfo();
+     *
+     * if (surface === 'object_panel') {
+     *   // This app is running in the object panel
+     * }
+     * ```
+     *
+     * @example Read current process launch parameters
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * type MyLaunchParams ={
+     *   mode: 'edit' | 'view';
+     *   id: string;
+     * }
+     *
+     * const currentProcess = appProcess.current;
+     * const { launchParams } = currentProcess.getInfo<MyLaunchParams>();
+     *
+     * if (launchParams) {
+     *   const { mode, id } = launchParams;
+     *   // Use launch parameters
+     * }
+     * ```
+     */
+    getInfo<T>(): AppProcessInfo<T>;
+    /**
+     * @public
+     * Requests the termination of the current process.
+     *
+     * @param params - Parameters to pass to the `setOnDispose` callback. Any structured data can be passed via this property.
+     *
+     * @remarks
+     * Once called, this method:
+     *
+     * 1. Transitions the state of the process to `"closing"`.
+     * 2. Invokes all registered `setOnDispose` callbacks.
+     * 3. Waits for the process to finish closing.
+     * 4. Transitions the state of the process to `"closed"`.
+     *
+     * Each time the state changes, all of the `registerOnStateChange` callbacks are called.
+     *
+     * @example Close current process
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * await appProcess.current.requestClose({ reason: 'completed' });
+     * ```
+     *
+     * @example Pass structured data to current process as it closes
+     * ```typescript
+     * import { appProcess, type CloseParams } from '@canva/platform';
+     *
+     * type DetailedCloseParams = CloseParams & {
+     *   metadata: {
+     *     savePoint: string;
+     *     timestamp: number;
+     *     userInitiated: boolean;
+     *   }
+     * };
+     *
+     * await appProcess.current.requestClose<DetailedCloseParams>({
+     *   reason: 'completed',
+     *   metadata: {
+     *     savePoint: 'auto_backup_1',
+     *     timestamp: Date.now(),
+     *     userInitiated: true
+     *   }
+     * });
+     * ```
+     */
+    requestClose<T extends CloseParams>(params: T): Promise<void>;
+    /**
+     * @public
+     * Registers a callback that runs when the current app process is about to close.
+     *
+     * @param callback - The callback to run when the current app process is about to close.
+     *
+     * @returns
+     * A disposer function that cleans up the registered callback.
+     *
+     * @remarks
+     * - Apps can't register multiple callbacks.
+     * - If an app attempts to register multiple callbacks, only the last callback will be registered.
+     * - The app process will remain open until the callback resolves or a timeout error occurs.
+     * - The complete execution of the callback is not guaranteed as some user actions (e.g. closing tabs) may close the process prematurely.
+     *
+     * @example Handle process cleanup
+     * ```typescript
+     * import { appProcess } from '@canva/platform';
+     *
+     * const cleanupDisposer = appProcess.current.setOnDispose(async (params) => {
+     *   if (params.reason === 'completed') {
+     *     await saveChanges();
+     *   }
+     * });
+     *
+     * // Later: cleanup the listener
+     * await cleanupDisposer();
+     * ```
+     */
+    setOnDispose<T extends CloseParams>(callback: OnDisposeCallback<T>): () => Promise<void>;
 };
 
 /**
@@ -403,50 +392,50 @@ export declare const features: FeatureSupport;
  * Provides methods for checking if an SDK method is supported in the current context.
  */
 export declare interface FeatureSupport {
-  /**
-   * @public
-   * Checks if the specified SDK methods are supported in the current context.
-   *
-   * @param features - The SDK methods to be checked for support.
-   *
-   * @example Checking a single feature
-   * ```typescript
-   * import { features } from '@canva/platform';
-   * import { addElementAtPoint } from '@canva/design';
-   *
-   * const isSupported = features.isSupported(addElementAtPoint);
-   * ```
-   *
-   * @example Checking multiple features
-   * ```typescript
-   * import { features } from '@canva/platform';
-   * import { addElementAtPoint, addElementAtCursor } from '@canva/design';
-   *
-   * const areSupported = features.isSupported(addElementAtPoint, addElementAtCursor);
-   * ```
-   */
-  isSupported(...features: Feature[]): boolean;
-  /**
-   * @public
-   * Registers a callback that runs when the context changes and an SDK method becomes supported or unsupported.
-   *
-   * @param onSupportChange - The callback that runs when the support status of an SDK method changes.
-   *
-   * @example Monitoring feature support changes
-   * ```typescript
-   * import { features } from '@canva/platform';
-   * import { addElementAtPoint } from '@canva/design';
-   *
-   * const supportDisposer = features.registerOnSupportChange(() => {
-   *   const isNowSupported = features.isSupported(addElementAtPoint);
-   *   // Update UI based on new support status
-   * });
-   *
-   * // Later: cleanup the listener
-   * await supportDisposer();
-   * ```
-   */
-  registerOnSupportChange(onSupportChange: () => void): Disposer;
+    /**
+     * @public
+     * Checks if the specified SDK methods are supported in the current context.
+     *
+     * @param features - The SDK methods to be checked for support.
+     *
+     * @example Checking a single feature
+     * ```typescript
+     * import { features } from '@canva/platform';
+     * import { addElementAtPoint } from '@canva/design';
+     *
+     * const isSupported = features.isSupported(addElementAtPoint);
+     * ```
+     *
+     * @example Checking multiple features
+     * ```typescript
+     * import { features } from '@canva/platform';
+     * import { addElementAtPoint, addElementAtCursor } from '@canva/design';
+     *
+     * const areSupported = features.isSupported(addElementAtPoint, addElementAtCursor);
+     * ```
+     */
+    isSupported(...features: Feature[]): boolean;
+    /**
+     * @public
+     * Registers a callback that runs when the context changes and an SDK method becomes supported or unsupported.
+     *
+     * @param onSupportChange - The callback that runs when the support status of an SDK method changes.
+     *
+     * @example Monitoring feature support changes
+     * ```typescript
+     * import { features } from '@canva/platform';
+     * import { addElementAtPoint } from '@canva/design';
+     *
+     * const supportDisposer = features.registerOnSupportChange(() => {
+     *   const isNowSupported = features.isSupported(addElementAtPoint);
+     *   // Update UI based on new support status
+     * });
+     *
+     * // Later: cleanup the listener
+     * await supportDisposer();
+     * ```
+     */
+    registerOnSupportChange(onSupportChange: () => void): Disposer;
 }
 
 /**
@@ -487,27 +476,27 @@ export declare const notification: NotificationClient;
  * Provides methods for interacting with notifications.
  */
 export declare interface NotificationClient {
-  /**
-   * @public
-   *
-   * A method that shows a toast notification to the user.
-   *
-   * @example
-   * ```tsx
-   * import { notification } from '@canva/platform';
-   * import type { ToastRequest } from '@canva/platform';
-   *
-   * const showToast = () => {
-   *   const request: ToastRequest = {
-   *     messageText: "Hello world!",
-   *   };
-   *   notification.addToast(request);
-   * };
-   *
-   * <Button onClick={() => showToast()}>Show Toast</Button>
-   * ```
-   */
-  addToast: (request: ToastRequest) => Promise<ToastResponse>;
+    /**
+     * @public
+     *
+     * A method that shows a toast notification to the user.
+     *
+     * @example
+     * ```tsx
+     * import { notification } from '@canva/platform';
+     * import type { ToastRequest } from '@canva/platform';
+     *
+     * const showToast = () => {
+     *   const request: ToastRequest = {
+     *     messageText: "Hello world!",
+     *   };
+     *   notification.addToast(request);
+     * };
+     *
+     * <Button onClick={() => showToast()}>Show Toast</Button>
+     * ```
+     */
+    addToast: (request: ToastRequest) => Promise<ToastResponse>;
 }
 
 /**
@@ -515,9 +504,7 @@ export declare interface NotificationClient {
  * A callback that runs when an app process is about to close.
  * @param opts - Parameters passed to the `setOnDispose` callback when a process is about to close.
  */
-export declare type OnDisposeCallback<T extends CloseParams> = (
-  opts: T,
-) => Promise<void>;
+export declare type OnDisposeCallback<T extends CloseParams> = (opts: T) => Promise<void>;
 
 /**
  * @public
@@ -528,13 +515,10 @@ export declare type OnDisposeCallback<T extends CloseParams> = (
  *   - sender.surface - The surface of the process that sent the message.
  * @param message - The broadcasted message.
  */
-export declare type OnMessageCallback = (
-  sender: {
+export declare type OnMessageCallback = (sender: {
     appProcessId: AppProcessId;
     surface: AppSurface;
-  },
-  message: any,
-) => Promise<void>;
+}, message: any) => Promise<void>;
 
 /**
  * @public
@@ -544,7 +528,7 @@ export declare type OnMessageCallback = (
  *   - opts.state - The state of the process.
  */
 export declare type OnStateChangeCallback = (opts: {
-  state: ProcessState;
+    state: ProcessState;
 }) => void;
 
 /**
@@ -552,10 +536,10 @@ export declare type OnStateChangeCallback = (opts: {
  * The result when a user doesn't agree to navigate to an external URL.
  */
 export declare type OpenExternalUrlAborted = {
-  /**
-   * The status of the request.
-   */
-  status: "aborted";
+    /**
+     * The status of the request.
+     */
+    status: 'aborted';
 };
 
 /**
@@ -563,10 +547,10 @@ export declare type OpenExternalUrlAborted = {
  * The result when a user agrees to navigate to an external URL.
  */
 export declare type OpenExternalUrlCompleted = {
-  /**
-   * The status of the request.
-   */
-  status: "completed";
+    /**
+     * The status of the request.
+     */
+    status: 'completed';
 };
 
 /**
@@ -574,47 +558,45 @@ export declare type OpenExternalUrlCompleted = {
  * Options for prompting the user to open an external URL.
  */
 export declare type OpenExternalUrlRequest = {
-  /**
-   * The URL to open.
-   */
-  url: string;
+    /**
+     * The URL to open.
+     */
+    url: string;
 };
 
 /**
  * @public
  * The result of prompting the user to open an external URL.
  */
-export declare type OpenExternalUrlResponse =
-  | OpenExternalUrlCompleted
-  | OpenExternalUrlAborted;
+export declare type OpenExternalUrlResponse = OpenExternalUrlCompleted | OpenExternalUrlAborted;
 
 /**
  * @public
  * Information about the platform on which the app is running.
  */
 export declare type PlatformInfo = {
-  /**
-   * If `true`, the app is allowed to directly link to payment and upgrade flows.
-   *
-   * @remarks
-   * This property is always `true` when the app is running in a web browser, but may otherwise be `false` in
-   * order to comply with the policies of the platforms on which Canva is available. For example, some platforms
-   * only allow payment-related actions that use their own payment mechanisms and apps are therefore not allowed
-   * to render payment-related call-to-actions while running on those platforms.
-   *
-   * @example
-   * ```ts
-   * const info = getPlatformInfo();
-   *
-   * if (info.canAcceptPayments) {
-   *   // Display payment links and upgrade flows
-   * } else {
-   *   // Hide payment links and upgrade flows
-   *   // Optionally, show an appropriate message
-   * }
-   * ```
-   */
-  canAcceptPayments: boolean;
+    /**
+     * If `true`, the app is allowed to directly link to payment and upgrade flows.
+     *
+     * @remarks
+     * This property is always `true` when the app is running in a web browser, but may otherwise be `false` in
+     * order to comply with the policies of the platforms on which Canva is available. For example, some platforms
+     * only allow payment-related actions that use their own payment mechanisms and apps are therefore not allowed
+     * to render payment-related call-to-actions while running on those platforms.
+     *
+     * @example
+     * ```ts
+     * const info = getPlatformInfo();
+     *
+     * if (info.canAcceptPayments) {
+     *   // Display payment links and upgrade flows
+     * } else {
+     *   // Hide payment links and upgrade flows
+     *   // Optionally, show an appropriate message
+     * }
+     * ```
+     */
+    canAcceptPayments: boolean;
 };
 
 /**
@@ -631,7 +613,7 @@ export declare type PlatformInfo = {
  *
  * While a process is closing, it won't receive any events or messages from other processes.
  */
-export declare type ProcessState = "opening" | "open" | "closing" | "closed";
+export declare type ProcessState = 'opening' | 'open' | 'closing' | 'closed';
 
 /**
  * @public
@@ -677,19 +659,17 @@ export declare type ProcessState = "opening" | "open" | "closing" | "closed";
  * }
  * ```
  */
-export declare const requestOpenExternalUrl: (
-  request: OpenExternalUrlRequest,
-) => Promise<OpenExternalUrlResponse>;
+export declare const requestOpenExternalUrl: (request: OpenExternalUrlRequest) => Promise<OpenExternalUrlResponse>;
 
 /**
  * @public
  * The result when a toast notification is successfully added.
  */
 export declare type ToastCompleted = {
-  /**
-   * The status of the request.
-   */
-  status: "completed";
+    /**
+     * The status of the request.
+     */
+    status: 'completed';
 };
 
 /**
@@ -698,20 +678,20 @@ export declare type ToastCompleted = {
  * Options for configuring a toast notification.
  */
 export declare type ToastRequest = {
-  /**
-   * Text to show within the toast notification.
-   */
-  messageText: string;
-  /**
-   * The duration that the notification will be visible.
-   *
-   * If set to `"infinite"`, the notification will be displayed until manually dismissed by the user.
-   *
-   * If set to a number, the notification will automatically disappear after that duration (in milliseconds).
-   *
-   * @defaultValue 5000
-   */
-  timeoutMs?: number | "infinite";
+    /**
+     * Text to show within the toast notification.
+     */
+    messageText: string;
+    /**
+     * The duration that the notification will be visible.
+     *
+     * If set to `"infinite"`, the notification will be displayed until manually dismissed by the user.
+     *
+     * If set to a number, the notification will automatically disappear after that duration (in milliseconds).
+     *
+     * @defaultValue 5000
+     */
+    timeoutMs?: number | 'infinite';
 };
 
 /**
@@ -721,4 +701,4 @@ export declare type ToastRequest = {
  */
 export declare type ToastResponse = ToastCompleted;
 
-export {};
+export { }

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./beta";

package/lib/cjs/sdk/platform/beta.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
+const _version = require("./version");
 _export_star(require("./public"), exports);
 function _export_star(from, to) {
     Object.keys(from).forEach(function(k) {
@@ -16,5 +17,4 @@ function _export_star(from, to) {
     });
     return from;
 }
-var _window___canva___sdkRegistration, _window___canva__;
-(_window___canva__ = window.__canva__) === null || _window___canva__ === void 0 ? void 0 : (_window___canva___sdkRegistration = _window___canva__.sdkRegistration) === null || _window___canva___sdkRegistration === void 0 ? void 0 : _window___canva___sdkRegistration.registerPackageVersion('platform', '2.2.0', 'beta');
+window.__canva__?.sdkRegistration?.registerPackageVersion('platform', _version.LATEST_VERSION_BETA, 'beta');

package/lib/cjs/sdk/platform/fake/fake_app_process_client.js

@@ -34,8 +34,7 @@ class FakeAppProcessClient {
             },
             setOnDispose: (callback)=>async ()=>{
                     await Promise.resolve();
-                },
-            registerOnStateChangeInternal: (callback)=>()=>Promise.resolve()
+                }
         };
     }
 }

package/lib/cjs/sdk/platform/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./beta"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

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

@@ -0,0 +1,24 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get LATEST_VERSION () {
+        return LATEST_VERSION;
+    },
+    get LATEST_VERSION_ALPHA () {
+        return LATEST_VERSION_ALPHA;
+    },
+    get LATEST_VERSION_BETA () {
+        return LATEST_VERSION_BETA;
+    }
+});
+const LATEST_VERSION = '2.2.0';
+const LATEST_VERSION_BETA = '2.2.1-beta.0';
+const LATEST_VERSION_ALPHA = 'NONE';

package/lib/cjs/sdk/utils/canva_sdk.js

@@ -26,10 +26,8 @@ function getCanvaSdk() {
     return window.canva_sdk;
 }
 function assertIsTestCanvaSdk() {
-    var _window___canva__;
-    if ((_window___canva__ = window.__canva__) === null || _window___canva__ === void 0 ? void 0 : _window___canva__.uiKit) {
-        var _getCanvaSdk_error, _getCanvaSdk;
-        const CanvaError = (_getCanvaSdk = getCanvaSdk()) === null || _getCanvaSdk === void 0 ? void 0 : (_getCanvaSdk_error = _getCanvaSdk.error) === null || _getCanvaSdk_error === void 0 ? void 0 : _getCanvaSdk_error.v2.CanvaError;
+    if (window.__canva__?.uiKit) {
+        const CanvaError = getCanvaSdk()?.error?.v2.CanvaError;
         throw new CanvaError({
             code: 'failed_precondition',
             message: "Canva App SDK: You're attempting to call `initTestEnvironment` in a non-test environment, such as in production. This method should be called in test environments, once and only once. For more info refer to https://canva.dev/docs/apps/testing/"

package/lib/esm/sdk/platform/beta.js

@@ -1,3 +1,3 @@
-var _window___canva___sdkRegistration, _window___canva__;
+import { LATEST_VERSION_BETA } from './version';
 export * from './public';
-(_window___canva__ = window.__canva__) === null || _window___canva__ === void 0 ? void 0 : (_window___canva___sdkRegistration = _window___canva__.sdkRegistration) === null || _window___canva___sdkRegistration === void 0 ? void 0 : _window___canva___sdkRegistration.registerPackageVersion('platform', '2.2.0', 'beta');
+window.__canva__?.sdkRegistration?.registerPackageVersion('platform', LATEST_VERSION_BETA, 'beta');

package/lib/esm/sdk/platform/fake/fake_app_process_client.js

@@ -24,8 +24,7 @@ export class FakeAppProcessClient {
             },
             setOnDispose: (callback)=>async ()=>{
                     await Promise.resolve();
-                },
-            registerOnStateChangeInternal: (callback)=>()=>Promise.resolve()
+                }
         };
     }
 }

package/lib/esm/sdk/platform/index.js

@@ -0,0 +1 @@
+export * from './beta';

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

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

package/lib/esm/sdk/utils/canva_sdk.js

@@ -2,10 +2,8 @@ export function getCanvaSdk() {
     return window.canva_sdk;
 }
 export function assertIsTestCanvaSdk() {
-    var _window___canva__;
-    if ((_window___canva__ = window.__canva__) === null || _window___canva__ === void 0 ? void 0 : _window___canva__.uiKit) {
-        var _getCanvaSdk_error, _getCanvaSdk;
-        const CanvaError = (_getCanvaSdk = getCanvaSdk()) === null || _getCanvaSdk === void 0 ? void 0 : (_getCanvaSdk_error = _getCanvaSdk.error) === null || _getCanvaSdk_error === void 0 ? void 0 : _getCanvaSdk_error.v2.CanvaError;
+    if (window.__canva__?.uiKit) {
+        const CanvaError = getCanvaSdk()?.error?.v2.CanvaError;
         throw new CanvaError({
             code: 'failed_precondition',
             message: "Canva App SDK: You're attempting to call `initTestEnvironment` in a non-test environment, such as in production. This method should be called in test environments, once and only once. For more info refer to https://canva.dev/docs/apps/testing/"

package/package.json

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

package/test/beta.d.ts

@@ -8,4 +8,4 @@
  */
 export declare function initTestEnvironment(): void;
 
-export {};
+export { }

package/test/index.d.ts

@@ -0,0 +1 @@
+export * from "./beta";