/**
 * @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 const 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 const requestOpenExternalUrl: (
  request: OpenExternalUrlRequest,
) => Promise<OpenExternalUrlResponse>;

export {};
