@canva/platform 0.0.1-rc.2 → 1.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @canva/platform
+
+A package for Canva's Apps SDK that provides utility methods.
+
+![](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
+
+## Table of contents
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API reference](#api-reference)
+- [Related packages](#related-packages)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Introduction
+
+`@canva/platform` is an npm package for Canva's [Apps SDK](https://www.canva.dev/docs/apps). It provides utility methods that are useful for a broad range of apps. For example, the `requestOpenExternalUrl` method opens an external web page.
+
+**Note:** To get up and running with the Apps SDK, check out [the quick start guide](https://www.canva.dev/docs/apps/quick-start).
+
+## Installation
+
+```bash
+npm install @canva/platform
+```
+
+## Usage
+
+1. Import a method or namespace from the `@canva/platform` package:
+
+   ```ts
+   import { getPlatformInfo } from '@canva/platform';
+   ```
+
+2. Call a method, passing in the required arguments (if any):
+
+   ```ts
+   getPlatformInfo();
+   ```
+
+## API reference
+
+- [`getPlatformInfo`](https://www.canva.dev/docs/apps/api/platform-get-platform-info)
+- [`requestOpenExternalUrl`](https://www.canva.dev/docs/apps/api/platform-request-open-external-url)
+
+## Related packages
+
+The Apps SDK is made up of the following packages:
+
+- [`@canva/app-ui-kit`](https://www.npmjs.com/package/@canva/app-ui-kit) - React-based component library for creating apps that mimic the look and feel of Canva.
+- [`@canva/asset`](https://www.npmjs.com/package/@canva/asset) - Provides methods for working with assets, such as image and video files.
+- [`@canva/design`](https://www.npmjs.com/package/@canva/design) - Provides methods for interacting with the user's design, such as creating elements.
+- [`@canva/error`](https://www.npmjs.com/package/@canva/error) - Provides a `CanvaError` class for handling errors.
+- [`@canva/platform`](https://www.npmjs.com/package/@canva/platform) - Provides utility methods, such as a method for opening external links.
+- [`@canva/user`](https://www.npmjs.com/package/@canva/user) - Provides methods for accessing user data and authenticating users.
+
+## Contributing
+
+We're actively developing this package but are not currently accepting third-party contributions. If you'd like to request any changes or additions to the package, submit a feature request via the [Canva Developers Community](https://community.canva.dev/).
+
+## License
+
+See the `LICENSE.md` file.

package/index.d.ts

@@ -1,9 +1,191 @@
+/**
+ * @public
+ * An API for interacting with the App Process.
+ */
+export declare interface AppProcess {
+  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.
+   * @remarks
+   * Once initiated, the closing process is irreversible and the process will NOT receive any events or messages from other processes.
+   */
+  requestClose<T extends CloseParams>(
+    target: AppProcessId,
+    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.
+   */
+  registerOnStateChange(
+    target: AppProcessId,
+    callback: (opts: { state: ProcessState }) => void
+  ): () => 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.
+   */
+  registerOnMessage(
+    callback: (
+      sender: {
+        appProcessId: AppProcessId;
+        surface: AppSurface;
+      },
+      message: any
+    ) => void
+  ): () => 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.
+   */
+  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 for 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 is running.
+   */
+  surface: AppSurface;
+  /**
+   * The unique identifier of the app process.
+   */
+  processId: AppProcessId;
+  /**
+   * The parameters provided to the app at the time of its process launch.
+   */
+  launchParams?: T;
+};
+
+/**
+ * @public
+ * The types of surfaces that can run an app process.
+ */
+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";
+
+/**
+ * @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'.
+ */
+export declare type CloseParams = {
+  reason: CloseReason;
+};
+
+/**
+ * @public
+ * The reasons why an app process is closed.
+ */
+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";
+
+/**
+ * @public
+ * Represents and exposes functionality specific to the currently running app process.
+ */
+export declare type CurrentAppProcess = {
+  /**
+   * @public
+   * Retrieves 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.
+   * @remarks
+   * Once initiated, the closing process is irreversible and the process will NOT receive any events or messages from other processes.
+   */
+  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.**
+   */
+  setOnDispose<T extends CloseParams>(
+    callback: OnDisposeCallback<T>
+  ): () => Promise<void>;
+};
+
 /**
  * @public
  * Returns information about the platform on which the app is running.
  */
 export declare function getPlatformInfo(): PlatformInfo;
 
+/**
+ * @public
+ * The type of a callback that is invoked when an app process is being closed.
+ * @returns a promise.
+ */
+export declare type OnDisposeCallback<T extends CloseParams> = (
+  opts: T
+) => Promise<void>;
+
 /**
  * @public
  * The result of opening an external URL when a user chooses to not navigate away from Canva.
@@ -54,12 +236,14 @@ export declare type PlatformInfo = {
    * If `true`, the app is allowed to directly link to payment and upgrade flows.
    *
    * @remarks
-   * An example of when this is `false` is when the app is opened in Canva's iOS app.
-   * This is because Apple's Human Interface Guidelines don't allow "calls to action that
-   * direct customers to purchasing mechanisms other than in-app purchase."
+   * 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
    * const info = getPlatformInfo();
+   *
    * if (info.canAcceptPayments) {
    *   // Display payment links and upgrade flows
    * } else {
@@ -70,6 +254,29 @@ export declare type PlatformInfo = {
   canAcceptPayments: boolean;
 };
 
+/**
+ * @public
+ * The states are an app process.
+ */
+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";
+
 /**
  * @public
  * Opens an external URL.

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

@@ -1,17 +1,19 @@
+// Copyright 2023 Canva Inc. All Rights Reserved.
 "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);
+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;
+}

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

@@ -1,25 +1,30 @@
+// Copyright 2023 Canva Inc. All Rights Reserved.
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPlatformInfo = exports.requestOpenExternalUrl = void 0;
+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;
+    },
+    requestOpenExternalUrl: function() {
+        return requestOpenExternalUrl;
+    },
+    getPlatformInfo: function() {
+        return getPlatformInfo;
+    }
+});
 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 appProcess = canva.appProcess;
 function requestOpenExternalUrl(request) {
     return canva.platform.requestOpenExternalUrl(request);
 }
-exports.requestOpenExternalUrl = requestOpenExternalUrl;
-/**
- * @public
- * Returns information about the platform on which the app is running.
- */
 function getPlatformInfo() {
     return canva.platform.getPlatformInfo();
 }
-exports.getPlatformInfo = getPlatformInfo;

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

@@ -1 +1,2 @@
+// Copyright 2023 Canva Inc. All Rights Reserved.
 export * from './public';

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

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

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@canva/platform",
-  "version": "0.0.1-rc.2",
-  "description": "The Canva Apps SDK App Platform Library",
+  "version": "1.1.0",
+  "description": "The Canva Apps SDK app platform library",
   "author": "Canva Pty Ltd.",
   "license": "SEE LICENSE IN LICENSE.md FILE",
   "peerDependencies": {
-    "@canva/error": "^0.0.1-rc.1"
+    "@canva/error": "^1.0.0"
   },
   "main": "lib/cjs/sdk/platform/index.js",
   "module": "lib/esm/sdk/platform/index.js",