@canva/platform 0.0.1-rc.1 → 1.0.1

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,3 +1,9 @@
+/**
+ * @public
+ * Returns information about the platform on which the app is running.
+ */
+export declare function getPlatformInfo(): PlatformInfo;
+
 /**
  * @public
  * The result of opening an external URL when a user chooses to not navigate away from Canva.
@@ -39,6 +45,33 @@ 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
+   * 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;
+};
+
 /**
  * @public
  * Opens an external URL.

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requestOpenExternalUrl = void 0;
+exports.getPlatformInfo = exports.requestOpenExternalUrl = void 0;
 const { canva } = window;
 /**
  * @public
@@ -15,3 +15,11 @@ 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/public.js

@@ -11,3 +11,10 @@ const { canva } = window;
 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();
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@canva/platform",
-  "version": "0.0.1-rc.1",
-  "description": "The Canva Apps SDK App Platform Library",
+  "version": "1.0.1",
+  "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",