@canva/platform 2.1.0 → 2.1.1

package/index.d.ts

@@ -22,7 +22,36 @@ export declare interface AppProcess {
    * 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..
+   * 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,
@@ -37,6 +66,36 @@ export declare interface AppProcess {
    *
    * @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,
@@ -50,6 +109,19 @@ export declare interface AppProcess {
    *
    * @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>;
   /**
@@ -57,13 +129,60 @@ export declare interface AppProcess {
    * 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;
 }
 
 /**
- * An alias for the AppProcess interface for interacting with the App Process.
  * @public
+ * Provides methods for interacting with app processes.
  */
 export declare const appProcess: AppProcess;
 
@@ -141,8 +260,46 @@ 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 extends any>(): AppProcessInfo<T>;
+  getInfo<T>(): AppProcessInfo<T>;
   /**
    * @public
    * Requests the termination of the current process.
@@ -158,6 +315,35 @@ export declare type CurrentAppProcess = {
    * 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>;
   /**
@@ -174,6 +360,20 @@ export declare type CurrentAppProcess = {
    * - 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>,
@@ -193,26 +393,58 @@ declare type Disposer = () => void;
 export declare type Feature = (...args: any[]) => unknown;
 
 /**
- * An alias for the FeatureSupport interface for interacting with feature controls.
  * @public
+ * Provides methods for checking if a feature is supported.
  */
 export declare const features: FeatureSupport;
 
 /**
  * @public
- * Client interface for checking if a given SDK method is supported the currently presented context.
+ * Provides methods for checking if an SDK method is supported in the current context.
  */
 export declare interface FeatureSupport {
   /**
    * @public
-   * Checks whether a given SDK method is supported under the current context.
-   * @param features - Canva SDK methods to be checked for support.
+   * 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 an event listener for changes in what SDK methods are currently supported.
-   * @param onSupportChange - A callback that gets fired upon any change to the feature support context.
+   * 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;
 }
@@ -220,6 +452,26 @@ export declare interface FeatureSupport {
 /**
  * @public
  * Returns information about the platform on which the app is running.
+ *
+ * @example Get platform information
+ * ```typescript
+ * import { getPlatformInfo } from '@canva/platform';
+ *
+ * const platformInfo = await getPlatformInfo();
+ * ```
+ *
+ * @example Check if app is running on platform that allows payments
+ * ```typescript
+ * import { getPlatformInfo } from '@canva/platform';
+ *
+ * const platformInfo = await getPlatformInfo();
+ *
+ * if (platformInfo.canAcceptPayments) {
+ *   // Show payment-related UI elements
+ * } else {
+ *   // Hide payment-related UI elements
+ * }
+ * ```
  */
 export declare const getPlatformInfo: () => PlatformInfo;
 
@@ -354,6 +606,41 @@ export declare type ProcessState = "opening" | "open" | "closing" | "closed";
  * The URL is opened natively, such as in a new browser tab on desktop or in a browser sheet on mobile.
  *
  * In some browsers, the user must enable popup permissions before any URL can be opened.
+ *
+ * @example Open an external URL
+ * ```typescript
+ * import { requestOpenExternalUrl } from '@canva/platform';
+ *
+ * await requestOpenExternalUrl({
+ *   url: 'https://www.example.com',
+ * });
+ * ```
+ *
+ * @example Detect when a user navigates to the external URL
+ * ```typescript
+ * import { requestOpenExternalUrl } from '@canva/platform';
+ *
+ * const response = await requestOpenExternalUrl({
+ *   url: 'https://www.example.com',
+ * });
+ *
+ * if (response.status === 'completed') {
+ *   // URL opened successfully
+ * }
+ * ```
+ *
+ * @example Detect when a user doesn't navigate to the external URL
+ * ```typescript
+ * import { requestOpenExternalUrl } from '@canva/platform';
+ *
+ * const response = await requestOpenExternalUrl({
+ *   url: 'https://www.example.com',
+ * });
+ *
+ * if (response.status === 'aborted') {
+ *   // User declined to open URL
+ * }
+ * ```
  */
 export declare const requestOpenExternalUrl: (
   request: OpenExternalUrlRequest,

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

@@ -10,11 +10,13 @@ Object.defineProperty(exports, "createFakePlatformClients", {
 });
 const _fake_app_process_client = require("./fake_app_process_client");
 const _fake_feature_support_client = require("./fake_feature_support_client");
+const _fake_notification_client = require("./fake_notification_client");
 const _fake_platform_client = require("./fake_platform_client");
 function createFakePlatformClients() {
     const appProcess = new _fake_app_process_client.FakeAppProcessClient();
     const platform = new _fake_platform_client.FakePlatformClient();
     const features = new _fake_feature_support_client.FakeFeatureSupportClient();
+    const notification = new _fake_notification_client.FakeNotificationClient();
     const i18n = undefined;
     return {
         platform: {
@@ -22,7 +24,8 @@ function createFakePlatformClients() {
                 platform,
                 appProcess,
                 i18n,
-                features
+                features,
+                notification
             }
         }
     };

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

@@ -0,0 +1,17 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "FakeNotificationClient", {
+    enumerable: true,
+    get: function() {
+        return FakeNotificationClient;
+    }
+});
+class FakeNotificationClient {
+    async addToast(options) {
+        return {
+            status: 'completed'
+        };
+    }
+}

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

@@ -17,4 +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.1.0', 'ga');
+(_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.1.1', 'ga');

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

@@ -15,11 +15,11 @@ _export(exports, {
     features: function() {
         return features;
     },
-    requestOpenExternalUrl: function() {
-        return requestOpenExternalUrl;
-    },
     getPlatformInfo: function() {
         return getPlatformInfo;
+    },
+    requestOpenExternalUrl: function() {
+        return requestOpenExternalUrl;
     }
 });
 const { canva_sdk } = window;

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

@@ -9,12 +9,15 @@ function _export(target, all) {
     });
 }
 _export(exports, {
-    getCanvaSdk: function() {
-        return getCanvaSdk;
-    },
     assertIsTestCanvaSdk: function() {
         return assertIsTestCanvaSdk;
     },
+    bindMethodsToClients: function() {
+        return bindMethodsToClients;
+    },
+    getCanvaSdk: function() {
+        return getCanvaSdk;
+    },
     injectFakeAPIClients: function() {
         return injectFakeAPIClients;
     }
@@ -34,8 +37,29 @@ function assertIsTestCanvaSdk() {
     }
 }
 function injectFakeAPIClients(clients) {
+    bindMethodsToClients(clients);
     window.canva_sdk = {
         ...getCanvaSdk(),
         ...clients
     };
 }
+function bindMethodsToClients(objectToBind) {
+    if (typeof objectToBind !== 'object' || objectToBind == null)
+        return;
+    const classMethods = new Set();
+    let currentPrototype = Object.getPrototypeOf(objectToBind);
+    while(currentPrototype && currentPrototype !== Object.prototype){
+        Object.getOwnPropertyNames(currentPrototype).forEach((method)=>classMethods.add(method));
+        currentPrototype = Object.getPrototypeOf(currentPrototype);
+    }
+    classMethods.delete('constructor');
+    for (const method of classMethods) {
+        const originalFn = objectToBind[method];
+        if (typeof originalFn === 'function') Object.defineProperty(objectToBind, method, {
+            value: (...args)=>{
+                return originalFn.call(objectToBind, ...args);
+            }
+        });
+    }
+    Object.values(objectToBind).forEach(bindMethodsToClients);
+}

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

@@ -1,10 +1,12 @@
 import { FakeAppProcessClient } from './fake_app_process_client';
 import { FakeFeatureSupportClient } from './fake_feature_support_client';
+import { FakeNotificationClient } from './fake_notification_client';
 import { FakePlatformClient } from './fake_platform_client';
 export function createFakePlatformClients() {
     const appProcess = new FakeAppProcessClient();
     const platform = new FakePlatformClient();
     const features = new FakeFeatureSupportClient();
+    const notification = new FakeNotificationClient();
     const i18n = undefined;
     return {
         platform: {
@@ -12,7 +14,8 @@ export function createFakePlatformClients() {
                 platform,
                 appProcess,
                 i18n,
-                features
+                features,
+                notification
             }
         }
     };

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

@@ -0,0 +1,7 @@
+export class FakeNotificationClient {
+    async addToast(options) {
+        return {
+            status: 'completed'
+        };
+    }
+}

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

@@ -1,3 +1,3 @@
 var _window___canva___sdkRegistration, _window___canva__;
 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.1.0', 'ga');
+(_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.1.1', 'ga');

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

@@ -13,8 +13,29 @@ export function assertIsTestCanvaSdk() {
     }
 }
 export function injectFakeAPIClients(clients) {
+    bindMethodsToClients(clients);
     window.canva_sdk = {
         ...getCanvaSdk(),
         ...clients
     };
 }
+export function bindMethodsToClients(objectToBind) {
+    if (typeof objectToBind !== 'object' || objectToBind == null)
+        return;
+    const classMethods = new Set();
+    let currentPrototype = Object.getPrototypeOf(objectToBind);
+    while(currentPrototype && currentPrototype !== Object.prototype){
+        Object.getOwnPropertyNames(currentPrototype).forEach((method)=>classMethods.add(method));
+        currentPrototype = Object.getPrototypeOf(currentPrototype);
+    }
+    classMethods.delete('constructor');
+    for (const method of classMethods) {
+        const originalFn = objectToBind[method];
+        if (typeof originalFn === 'function') Object.defineProperty(objectToBind, method, {
+            value: (...args)=>{
+                return originalFn.call(objectToBind, ...args);
+            }
+        });
+    }
+    Object.values(objectToBind).forEach(bindMethodsToClients);
+}

package/package.json

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