@canva/platform 2.0.0 → 2.1.1-beta.1

package/index.d.ts

@@ -1,362 +0,0 @@
-/**
- * @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.
- */
-export declare function getPlatformInfo(): PlatformInfo;
-
-/**
- * @public
- * 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";
-};
-
-/**
- * @public
- * The result when a user agrees to navigate to an external URL.
- */
-export declare type OpenExternalUrlCompleted = {
-  /**
-   * The status of the request.
-   */
-  status: "completed";
-};
-
-/**
- * @public
- * Options for prompting the user to open an external URL.
- */
-export declare type OpenExternalUrlRequest = {
-  /**
-   * The URL to open.
-   */
-  url: string;
-};
-
-/**
- * @public
- * The result of prompting the user to open an external URL.
- */
-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
-   * ```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
-   * }
-   * ```
-   */
-  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.
- *
- * @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 declare function requestOpenExternalUrl(
-  request: OpenExternalUrlRequest
-): Promise<OpenExternalUrlResponse>;
-
-export {};

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

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