@canva/platform 1.1.0 → 2.1.0

package/index.d.ts

@@ -1,57 +1,62 @@
 /**
  * @public
- * An API for interacting with the App Process.
+ * Provides methods for interacting with an app process.
  */
 export declare interface AppProcess {
+  /**
+   * The current app process.
+   */
   readonly current: CurrentAppProcess;
   /**
    * @public
-   * Request the termination of an app process.
-   * @param target - The id of the app process to close.
-   * @param params - A parameters object passed to all callback functions registered via registerOnBeforeClose API for the provided AppProcessId.
-   * In addition to the required 'reason' field, app can choose to pass any structured data via params.
-   * {@link https://html.spec.whatwg.org/multipage/structured-data.html#safe-passing-of-structured-data | safe passing of structured data}
-   * @remarks
-   * A successful invocation indicates the platform has begun shutdown following procedure for the target AppProcessId, which:
-   * 1. Transitions process state to `CLOSING`, triggering all registered state change callbacks.
-   * 2. Invokes all registered onBeforeClose callbacks.
-   * 3. Waits for the process to close.
-   * 4. Transitions process state to `CLOSED`, triggering all registered state change callbacks.
+   * 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 initiated, the closing process is irreversible and the process will NOT receive any events or messages from other processes.
+   * 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..
    */
   requestClose<T extends CloseParams>(
     target: AppProcessId,
-    params: T
+    params: T,
   ): Promise<void>;
   /**
    * @public
-   * Registers a callback to be executed when the state of the specified app process changes.
-   * @param target - The id of the app process for which to register the callback.
-   * @param callback - Callback function triggered on state change
-   * @returns a disposer function to unsubscribe the callback.
+   * 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.
    */
   registerOnStateChange(
     target: AppProcessId,
-    callback: (opts: { state: ProcessState }) => void
+    callback: OnStateChangeCallback,
   ): () => Promise<void>;
   /**
-   * Registers a handler to receive messages sent from other app processes.
-   * @param callback - Handler function to receive incoming messages.
-   * @returns a disposer function to unsubscribe the handler.
+   * @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.
    */
-  registerOnMessage(
-    callback: (
-      sender: {
-        appProcessId: AppProcessId;
-        surface: AppSurface;
-      },
-      message: any
-    ) => void
-  ): () => Promise<void>;
+  registerOnMessage(callback: OnMessageCallback): () => Promise<void>;
   /**
-   * Broadcasts a message to all other running app processes which share the caller's AppId.
-   * @param message - app-defined message to be broadcast. message needs to be structured data.
+   * @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.
    */
   broadcastMessage(message: any): void;
 }
@@ -64,7 +69,7 @@ export declare const appProcess: AppProcess;
 
 /**
  * @public
- * The unique identifier for an app process.
+ * The unique identifier of an app process.
  */
 export declare type AppProcessId = string & {
   __appProcessId: never;
@@ -76,7 +81,7 @@ export declare type AppProcessId = string & {
  */
 export declare type AppProcessInfo<T> = {
   /**
-   * The surface on which the app is running.
+   * The surface on which the app process is running.
    */
   surface: AppSurface;
   /**
@@ -84,144 +89,213 @@ export declare type AppProcessInfo<T> = {
    */
   processId: AppProcessId;
   /**
-   * The parameters provided to the app at the time of its process launch.
+   * Parameters passed to the app process when it was opened.
    */
   launchParams?: T;
 };
 
 /**
  * @public
- * The types of surfaces that can run an app process.
+ * The type of surface on which an app process can run.
+ *
+ * @remarks
+ * The possible surfaces include:
+ *
+ * - `"headless"` - A surface for when there is no visible user interface.
+ * - `"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 =
-  /**
-   * The object panel on the left side of the editing UI.
-   */
   | "object_panel"
-  /**
-   * The overlay surface on top of a selected image in the design.
-   */
-  | "selected_image_overlay";
+  | "selected_image_overlay"
+  | "headless";
 
 /**
  * @public
- * The parameters specified when closing an app process.
- * @remarks
- * CloseParams are passed on to the callback function registered for handling the termination of an app process,
- * and provide additional context for ending the process.
- * For example, Apps should persist unsaved changes when the close reason is 'completed'.
+ * 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;
 };
 
 /**
  * @public
- * The reasons why an app process is closed.
+ * The reason why an app process is closing.
+ *
+ * @remarks
+ * The possible reasons include:
+ *
+ * - `"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 =
-  /**
-   * Indicates the workflow is completed, for example, when user clicks a 'Save and Close' in the App.
-   * Any unsaved changes should be saved before closing.
-   */
-  | "completed"
-  /**
-   * Indicates user has aborted the workflow, for example, when user clicked the 'cancel' button in the App.
-   * App should be closed without saving any current changes.
-   */
-  | "aborted";
+export declare type CloseReason = "completed" | "aborted";
 
 /**
  * @public
- * Represents and exposes functionality specific to the currently running app process.
+ * Provides methods for interacting with the current app process.
  */
 export declare type CurrentAppProcess = {
   /**
    * @public
-   * Retrieves information about the current app process.
+   * Returns information about the current app process.
    */
   getInfo<T extends any>(): AppProcessInfo<T>;
   /**
    * @public
-   * Requests the current app process be closed.
-   * @param params - A parameters object passed to all callback functions registered via registerOnBeforeClose API for the current process.
-   * In addition to the required 'reason' field, app can choose to pass any structured data via params.
-   * @remarks
-   * A successful invocation indicates the platform has begun shutdown following procedure for the current process, which:
-   * 1. Transitions process state to `CLOSING`, triggering all registered state change callbacks.
-   * 2. Invokes all registered onBeforeClose callbacks.
-   * 3. Waits for the process to close.
-   * 4. Transitions process state to `CLOSED`, triggering all registered state change callbacks.
+   * 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 initiated, the closing process is irreversible and the process will NOT receive any events or messages from other processes.
+   * 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.
    */
   requestClose<T extends CloseParams>(params: T): Promise<void>;
   /**
    * @public
-   * Registers a callback to be executed when the current app process is about to close.
-   * @remarks Only allow registering one callback.
-   * Subsequential invokes of the API will override the existing callback.
-   * The process remains open until the callback resolve or a timeout occurs.
-   * @param callback -  The callback function to be invoked before closure.
-   * @returns a disposer function to unsubscribe the callback.
-   * @remarks Complete execution of the callback is not guaranteed. Certain user actions (e.g. closing tabs, top level navigation) may terminate app processes prematurely. Consider these callbacks **best effort only.**
+   * 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.
    */
   setOnDispose<T extends CloseParams>(
-    callback: OnDisposeCallback<T>
+    callback: OnDisposeCallback<T>,
   ): () => Promise<void>;
 };
 
+/**
+ * @public
+ * Disposes an event listener.
+ */
+declare type Disposer = () => void;
+
+/**
+ * @public
+ * An SDK method that can be inspected for feature support.
+ */
+export declare type Feature = (...args: any[]) => unknown;
+
+/**
+ * An alias for the FeatureSupport interface for interacting with feature controls.
+ * @public
+ */
+export declare const features: FeatureSupport;
+
+/**
+ * @public
+ * Client interface for checking if a given SDK method is supported the currently presented 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.
+   */
+  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.
+   */
+  registerOnSupportChange(onSupportChange: () => void): Disposer;
+}
+
 /**
  * @public
  * Returns information about the platform on which the app is running.
  */
-export declare function getPlatformInfo(): PlatformInfo;
+export declare const getPlatformInfo: () => PlatformInfo;
 
 /**
  * @public
- * The type of a callback that is invoked when an app process is being closed.
- * @returns a promise.
+ * 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
+  opts: T,
 ) => Promise<void>;
 
 /**
  * @public
- * The result of opening an external URL when a user chooses to not navigate away from Canva.
+ * A callback that runs when an app process receives a broadcasted message.
+ *
+ * @param sender - Information about the process that sent the message.
+ *   - sender.appProcessId - The ID of the process that sent the message.
+ *   - sender.surface - The surface of the process that sent the message.
+ * @param message - The broadcasted message.
+ */
+export declare type OnMessageCallback = (
+  sender: {
+    appProcessId: AppProcessId;
+    surface: AppSurface;
+  },
+  message: any,
+) => Promise<void>;
+
+/**
+ * @public
+ * A callback that runs when the state of a process changes.
+ *
+ * @param opts - Information about the state change.
+ *   - opts.state - The state of the process.
+ */
+export declare type OnStateChangeCallback = (opts: {
+  state: ProcessState;
+}) => void;
+
+/**
+ * @public
+ * 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";
+  status: "aborted";
 };
 
 /**
  * @public
- * The result of opening an external URL when a user agrees to navigate away from Canva.
+ * The result when a user agrees to navigate to an external URL.
  */
 export declare type OpenExternalUrlCompleted = {
   /**
    * The status of the request.
    */
-  status: "COMPLETED";
+  status: "completed";
 };
 
 /**
  * @public
- * The options for opening an external URL.
+ * Options for prompting the user to open an external URL.
  */
 export declare type OpenExternalUrlRequest = {
   /**
-   * The URL to open in a new window
+   * The URL to open.
    */
   url: string;
 };
 
 /**
  * @public
- * The result of opening an external URL.
+ * The result of prompting the user to open an external URL.
  */
 export declare type OpenExternalUrlResponse =
   | OpenExternalUrlCompleted
@@ -242,40 +316,35 @@ export declare type PlatformInfo = {
    * 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
+   *   // Optionally, show an appropriate message
    * }
+   * ```
    */
   canAcceptPayments: boolean;
 };
 
 /**
  * @public
- * The states are an app process.
+ * The state of an app process.
+ *
+ * @remarks
+ * The possible states include:
+ *
+ * - `"opening"` - The app process is opening.
+ * - `"open"` - The app process is open, active, and visible on the designated surface.
+ * - `"closing"` - The app process is closing.
+ * - `"closed"` - The app process has been closed and is no longer active.
+ *
+ * While a process is closing, it won't receive any events or messages from other processes.
  */
-export declare type ProcessState =
-  /**
-   * The app process is in the process of opening.
-   */
-  | "opening"
-  /**
-   * The app process is active and visible to the user on its designated surface.
-   */
-  | "open"
-  /**
-   * The app process is in the process of closing.
-   * At this state, the process becomes non-interactive and won't receive any events and messages from other processes.
-   */
-  | "closing"
-  /**
-   * The app process has been terminated and is no longer running.
-   */
-  | "closed";
+export declare type ProcessState = "opening" | "open" | "closing" | "closed";
 
 /**
  * @public
@@ -286,8 +355,8 @@ export declare type ProcessState =
  *
  * In some browsers, the user must enable popup permissions before any URL can be opened.
  */
-export declare function requestOpenExternalUrl(
-  request: OpenExternalUrlRequest
-): Promise<OpenExternalUrlResponse>;
+export declare const requestOpenExternalUrl: (
+  request: OpenExternalUrlRequest,
+) => Promise<OpenExternalUrlResponse>;
 
 export {};

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

@@ -0,0 +1,29 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "createFakePlatformClients", {
+    enumerable: true,
+    get: function() {
+        return createFakePlatformClients;
+    }
+});
+const _fake_app_process_client = require("./fake_app_process_client");
+const _fake_feature_support_client = require("./fake_feature_support_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 i18n = undefined;
+    return {
+        platform: {
+            v2: {
+                platform,
+                appProcess,
+                i18n,
+                features
+            }
+        }
+    };
+}

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

@@ -0,0 +1,41 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "FakeAppProcessClient", {
+    enumerable: true,
+    get: function() {
+        return FakeAppProcessClient;
+    }
+});
+class FakeAppProcessClient {
+    async requestClose(target, params) {
+        await Promise.resolve();
+    }
+    registerOnStateChange(target, callback) {
+        return async ()=>{
+            await Promise.resolve();
+        };
+    }
+    registerOnMessage(callback) {
+        return async ()=>{
+            await Promise.resolve();
+        };
+    }
+    broadcastMessage(message) {}
+    constructor(){
+        this.current = {
+            getInfo: ()=>({
+                    processId: 'test-process-id',
+                    surface: 'object_panel'
+                }),
+            requestClose: async (params)=>{
+                await Promise.resolve();
+            },
+            setOnDispose: (callback)=>async ()=>{
+                    await Promise.resolve();
+                },
+            registerOnStateChangeInternal: (callback)=>()=>Promise.resolve()
+        };
+    }
+}

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

@@ -0,0 +1,19 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "FakeFeatureSupportClient", {
+    enumerable: true,
+    get: function() {
+        return FakeFeatureSupportClient;
+    }
+});
+class FakeFeatureSupportClient {
+    isSupported(...features) {
+        return true;
+    }
+    registerOnSupportChange(onSupportChange) {
+        onSupportChange();
+        return ()=>{};
+    }
+}

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

@@ -0,0 +1,23 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "FakePlatformClient", {
+    enumerable: true,
+    get: function() {
+        return FakePlatformClient;
+    }
+});
+class FakePlatformClient {
+    async requestOpenExternalUrl(options) {
+        await Promise.resolve();
+        return {
+            status: 'completed'
+        };
+    }
+    getPlatformInfo() {
+        return {
+            canAcceptPayments: true
+        };
+    }
+}

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

@@ -1,5 +1,4 @@
-// Copyright 2023 Canva Inc. All Rights Reserved.
-"use strict";
+"use strict"
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
@@ -17,3 +16,5 @@ 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');

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

@@ -1,5 +1,4 @@
-// Copyright 2023 Canva Inc. All Rights Reserved.
-"use strict";
+"use strict"
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
@@ -13,6 +12,9 @@ _export(exports, {
     appProcess: function() {
         return appProcess;
     },
+    features: function() {
+        return features;
+    },
     requestOpenExternalUrl: function() {
         return requestOpenExternalUrl;
     },
@@ -20,11 +22,8 @@ _export(exports, {
         return getPlatformInfo;
     }
 });
-const { canva } = window;
-const appProcess = canva.appProcess;
-function requestOpenExternalUrl(request) {
-    return canva.platform.requestOpenExternalUrl(request);
-}
-function getPlatformInfo() {
-    return canva.platform.getPlatformInfo();
-}
+const { canva_sdk } = window;
+const appProcess = canva_sdk.platform.v2.appProcess;
+const features = canva_sdk.platform.v2.features;
+const requestOpenExternalUrl = canva_sdk.platform.v2.platform.requestOpenExternalUrl;
+const getPlatformInfo = canva_sdk.platform.v2.platform.getPlatformInfo;

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

@@ -0,0 +1,16 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "initTestEnvironment", {
+    enumerable: true,
+    get: function() {
+        return initTestEnvironment;
+    }
+});
+const _create = require('../fake/create');
+const _canva_sdk = require('../../utils/canva_sdk');
+function initTestEnvironment() {
+    (0, _canva_sdk.assertIsTestCanvaSdk)();
+    (0, _canva_sdk.injectFakeAPIClients)((0, _create.createFakePlatformClients)());
+}

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

@@ -0,0 +1,41 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    getCanvaSdk: function() {
+        return getCanvaSdk;
+    },
+    assertIsTestCanvaSdk: function() {
+        return assertIsTestCanvaSdk;
+    },
+    injectFakeAPIClients: function() {
+        return injectFakeAPIClients;
+    }
+});
+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;
+        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/"
+        });
+    }
+}
+function injectFakeAPIClients(clients) {
+    window.canva_sdk = {
+        ...getCanvaSdk(),
+        ...clients
+    };
+}

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

@@ -0,0 +1,19 @@
+import { FakeAppProcessClient } from './fake_app_process_client';
+import { FakeFeatureSupportClient } from './fake_feature_support_client';
+import { FakePlatformClient } from './fake_platform_client';
+export function createFakePlatformClients() {
+    const appProcess = new FakeAppProcessClient();
+    const platform = new FakePlatformClient();
+    const features = new FakeFeatureSupportClient();
+    const i18n = undefined;
+    return {
+        platform: {
+            v2: {
+                platform,
+                appProcess,
+                i18n,
+                features
+            }
+        }
+    };
+}

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

@@ -0,0 +1,31 @@
+export class FakeAppProcessClient {
+    async requestClose(target, params) {
+        await Promise.resolve();
+    }
+    registerOnStateChange(target, callback) {
+        return async ()=>{
+            await Promise.resolve();
+        };
+    }
+    registerOnMessage(callback) {
+        return async ()=>{
+            await Promise.resolve();
+        };
+    }
+    broadcastMessage(message) {}
+    constructor(){
+        this.current = {
+            getInfo: ()=>({
+                    processId: 'test-process-id',
+                    surface: 'object_panel'
+                }),
+            requestClose: async (params)=>{
+                await Promise.resolve();
+            },
+            setOnDispose: (callback)=>async ()=>{
+                    await Promise.resolve();
+                },
+            registerOnStateChangeInternal: (callback)=>()=>Promise.resolve()
+        };
+    }
+}

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

@@ -0,0 +1,9 @@
+export class FakeFeatureSupportClient {
+    isSupported(...features) {
+        return true;
+    }
+    registerOnSupportChange(onSupportChange) {
+        onSupportChange();
+        return ()=>{};
+    }
+}

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

@@ -0,0 +1,13 @@
+export class FakePlatformClient {
+    async requestOpenExternalUrl(options) {
+        await Promise.resolve();
+        return {
+            status: 'completed'
+        };
+    }
+    getPlatformInfo() {
+        return {
+            canAcceptPayments: true
+        };
+    }
+}

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

@@ -1,2 +1,3 @@
-// Copyright 2023 Canva Inc. All Rights Reserved.
+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');

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

@@ -1,23 +1,5 @@
-// Copyright 2023 Canva Inc. All Rights Reserved.
-const { canva } = window;
-/**
- * An alias for the AppProcess interface for interacting with the App Process.
- * @public
- */ export const appProcess = canva.appProcess;
-/**
- * @public
- * Opens an external URL.
- *
- * @remarks
- * 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.
- */ export function requestOpenExternalUrl(request) {
-    return canva.platform.requestOpenExternalUrl(request);
-}
-/**
- * @public
- * Returns information about the platform on which the app is running.
- */ export function getPlatformInfo() {
-    return canva.platform.getPlatformInfo();
-}
+const { canva_sdk } = window;
+export const appProcess = canva_sdk.platform.v2.appProcess;
+export const features = canva_sdk.platform.v2.features;
+export const requestOpenExternalUrl = canva_sdk.platform.v2.platform.requestOpenExternalUrl;
+export const getPlatformInfo = canva_sdk.platform.v2.platform.getPlatformInfo;

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

@@ -0,0 +1,6 @@
+import { createFakePlatformClients } from '../fake/create';
+import { assertIsTestCanvaSdk, injectFakeAPIClients } from '../../utils/canva_sdk';
+export function initTestEnvironment() {
+    assertIsTestCanvaSdk();
+    injectFakeAPIClients(createFakePlatformClients());
+}

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

@@ -0,0 +1,20 @@
+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;
+        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/"
+        });
+    }
+}
+export function injectFakeAPIClients(clients) {
+    window.canva_sdk = {
+        ...getCanvaSdk(),
+        ...clients
+    };
+}

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "@canva/platform",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "description": "The Canva Apps SDK app platform library",
   "author": "Canva Pty Ltd.",
   "license": "SEE LICENSE IN LICENSE.md FILE",
   "peerDependencies": {
-    "@canva/error": "^1.0.0"
+    "@canva/error": "^2.0.0"
   },
-  "main": "lib/cjs/sdk/platform/index.js",
-  "module": "lib/esm/sdk/platform/index.js",
+  "main": "./lib/cjs/sdk/platform/index.js",
+  "module": "./lib/esm/sdk/platform/index.js",
   "exports": {
     ".": {
+      "types": "./index.d.ts",
       "require": "./lib/cjs/sdk/platform/index.js",
       "import": "./lib/esm/sdk/platform/index.js"
+    },
+    "./test": {
+      "types": "./test/index.d.ts",
+      "require": "./lib/cjs/sdk/platform/test/index.js",
+      "import": "./lib/esm/sdk/platform/test/index.js"
     }
   },
   "typings": "./index.d.ts"

package/test/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @public
+ * Initializes a test environment for the `@canva/platform` package, enabling unit tests to mock Canva's APIs.
+ * @remarks
+ * This method should only be called once in a test environment, such as in a Jest setup file.
+ * @see
+ * https://www.canva.dev/docs/apps/testing/
+ */
+export declare function initTestEnvironment(): void;
+
+export {};