@canva/platform 1.0.1 → 2.0.0

package/index.d.ts

@@ -1,3 +1,222 @@
+/**
+ * @public
+ * 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..
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  broadcastMessage(message: any): void;
+}
+
+/**
+ * An alias for the AppProcess interface for interacting with the App Process.
+ * @public
+ */
+export declare const appProcess: AppProcess;
+
+/**
+ * @public
+ * The unique identifier of an app process.
+ */
+export declare type AppProcessId = string & {
+  __appProcessId: never;
+};
+
+/**
+ * @public
+ * 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;
+};
+
+/**
+ * @public
+ * 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 =
+  | "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;
+};
+
+/**
+ * @public
+ * 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 = "completed" | "aborted";
+
+/**
+ * @public
+ * Provides methods for interacting with the current app process.
+ */
+export declare type CurrentAppProcess = {
+  /**
+   * @public
+   * Returns information about the current app process.
+   */
+  getInfo<T extends any>(): 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.
+   */
+  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.
+   */
+  setOnDispose<T extends CloseParams>(
+    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.
@@ -6,40 +225,77 @@ export declare function getPlatformInfo(): PlatformInfo;
 
 /**
  * @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 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>;
+
+/**
+ * @public
+ * 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
@@ -60,18 +316,36 @@ 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 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 = "opening" | "open" | "closing" | "closed";
+
 /**
  * @public
  * Opens an external URL.

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

@@ -1,17 +1,21 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./public"), exports);
+"use strict"
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./public"), 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;
+}
+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.0.0', 'ga');

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

@@ -1,25 +1,33 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPlatformInfo = exports.requestOpenExternalUrl = void 0;
-const { canva } = window;
-/**
- * @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.
- */
+"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, {
+    appProcess: function() {
+        return appProcess;
+    },
+    features: function() {
+        return features;
+    },
+    requestOpenExternalUrl: function() {
+        return requestOpenExternalUrl;
+    },
+    getPlatformInfo: function() {
+        return getPlatformInfo;
+    }
+});
+const { canva_sdk } = window;
+const appProcess = canva_sdk.platform.v2.appProcess;
+const features = canva_sdk.platform.v2.features;
 function requestOpenExternalUrl(request) {
-    return canva.platform.requestOpenExternalUrl(request);
+    return canva_sdk.platform.v2.platform.requestOpenExternalUrl(request);
 }
-exports.requestOpenExternalUrl = requestOpenExternalUrl;
-/**
- * @public
- * Returns information about the platform on which the app is running.
- */
 function getPlatformInfo() {
-    return canva.platform.getPlatformInfo();
+    return canva_sdk.platform.v2.platform.getPlatformInfo();
 }
-exports.getPlatformInfo = getPlatformInfo;

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

@@ -1 +1,4 @@
+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.0.0', 'ga');

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

@@ -1,20 +1,9 @@
-const { canva } = window;
-/**
- * @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.
- */
+const { canva_sdk } = window;
+export const appProcess = canva_sdk.platform.v2.appProcess;
+export const features = canva_sdk.platform.v2.features;
 export function requestOpenExternalUrl(request) {
-    return canva.platform.requestOpenExternalUrl(request);
+    return canva_sdk.platform.v2.platform.requestOpenExternalUrl(request);
 }
-/**
- * @public
- * Returns information about the platform on which the app is running.
- */
 export function getPlatformInfo() {
-    return canva.platform.getPlatformInfo();
+    return canva_sdk.platform.v2.platform.getPlatformInfo();
 }

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "@canva/platform",
-  "version": "1.0.1",
+  "version": "2.0.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": {
     ".": {
-      "require": "./lib/cjs/sdk/platform/index.js",
-      "import": "./lib/esm/sdk/platform/index.js"
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./lib/cjs/sdk/platform/index.js"
+      },
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./lib/esm/sdk/platform/index.js"
+      }
     }
   },
   "typings": "./index.d.ts"