@interopio/browser/browser.d.ts

IOConnect Browser client application package

/* eslint-disable @typescript-eslint/no-unused-vars */
/* eslint-disable @typescript-eslint/no-explicit-any */
/* eslint-disable @typescript-eslint/no-empty-interface */
import { UnsubscribeFunction } from "callback-registry";
import { IOConnectCore } from "@interopio/core";
import { IOConnectDesktop } from "@interopio/desktop";
import { IOConnectWorkspaces } from "@interopio/workspaces-api";
import { IOConnectSearch } from "@interopio/search-api";
import { IOConnectModals } from "@interopio/modals-api";

/**
 * Factory function that creates a new ioconnect instance.
 * If your application is running in IOConnect Desktop this will return a Glue42.Glue API, which is a super-set of the IOConnectBrowser.API.
 */
export type IOConnectBrowserFactoryFunction = (config?: IOConnectBrowser.Config) => Promise<IOConnectBrowser.API | IOConnectDesktop.API>;
declare const IOConnectBrowserFactory: IOConnectBrowserFactoryFunction;
export default IOConnectBrowserFactory;

/**
 * @docname io.Connect Browser
 * @intro
 * **io.Connect Browser** allows web apps to integrate with other apps that are part of the same **io.Connect Browser** project via a set of APIs.
 * **io.Connect Browser** enables you to share data between apps, expose functionality, manage windows, notifications, and more.
 *
 * ## Referencing
 *
 * The [`&commat;interopio/browser`](https://www.npmjs.com/package/&commat;interopio/browser) library is available both as a single JavaScript file,
 * which you can include in your web apps using a `<script>` tag, and also as a module, which you can import in your apps:
 *
 * ```html
 * <script type="text/javascript" src="browser.umd.js"></script>
 * ```
 *
 * Or:
 *
 * ``` javascript
 * import IOBrowser from "&commat;interopio/browser";
 * ```
 *
 * ## Initialization
 *
 * The [`&commat;interopio/browser`](https://www.npmjs.com/package/&commat;interopio/browser) library attaches the `IOBrowser()` factory function
 * to the global `window` object. Invoke this function to initialize the library and connect to the **io.Connect Browser** environment.
 * The `IOBrowser()` factory function accepts an optional `Config` object as an argument, which you can use to provide settings for the library
 * (e.g., initialize additional io.Connect libraries, configure the library behavior or some of its APIs).
 * The factory function resolves with the initialized io.Connect API object, which you can use to access all available io.Connect APIs:
 *
 * ```javascript
 * import IOBrowser from "&commat;interopio/browser";
 * import IOWorkspaces from "&commat;interopio/workspaces-api";
 *
 * const initializeIOConnect = async () => {
 *
 *     // Initializing the Workspaces API.
 *     const initOptions = {
 *         libraries: [IOWorkspaces]
 *     };
 *
 *     // Use the initialized API object to access the io.Connect APIs.
 *     const io = await IOBrowser(initOptions);
 *
 *     // Here, the library is already initialized and you can access all available io.Connect APIs.
 *     const myWorkspace = await io.workspaces.restoreWorkspace("My Workspace");
 * };
 *
 * initializeIOConnect().catch(console.error);
 * ```
 */
export namespace IOConnectBrowser {

    export import Interop = IOConnectCore.Interop;
    export import Contexts = IOConnectCore.Contexts;
    export import Logger = IOConnectCore.Logger;

    /**
     * @ignore
     */
    export interface ProfileData {
        license: {
            type: "trial" | "paid";
            expiration: number;
        },
        productsInfo: {
            platform: {
                apiVersion: string;
            },
            client: {
                apiVersion: string;
            },
            workspaces?: {
                apiVersion: string;
                container?: {
                    type: string,
                    version: string;
                }
            },
            home?: {
                version: string
            },
            search?: {
                apiVersion: string;
            },
            modals?: {
                apiVersion: string;
            }
        },
        plugins: Array<{ name: string, version: string }>,
        user?: {
            id: string;
            username?: string;
            firstName?: string;
            lastName?: string;
            email?: string;
            type?: string;
            role?: string;
            meta?: any;
        }
    }

    /**
     * Describes the configuration for the `IOBrowser()` factory function.
     */
    export interface Config {

        /**
         * Configures the system logger. Used mostly during development.
         */
        systemLogger?: SystemLogger;

        /**
         * Connect with GW in memory.
         * Used for testing in node environment, where the GW isn't started by &commat;glue42/worker-web and an inproc GW is used instead.
         * @ignore
         */
        inproc?: IOConnectCore.InprocGWSettings;

        /**
         * Settings for the Notifications API.
         */
        notifications?: Notifications.Settings;

        /**
         * Settings for the Contexts API.
         */
        contexts?: IOConnectCore.ContextsConfig;

        /**
         * Configures whether the library will share the initialized API object upon request via a custom web event.
         * @default true
         */
        exposeAPI?: boolean;

        /**
         * If `true`, when the io.Connect API factory function is invoked more than once in the same app,
         * it will return the already initialized API object instead of throwing an error.
         * @default false
         * @since io.Connect Browser 3.5
         */
        memoizeAPI?: boolean;

        /**
         * List of references to the factory functions of additional io.Connect libraries to be initialized internally (e.g., `&commat;interopio/workspaces-api`, `&commat;interopio/search-api`).
         * The APIs provided by these libraries can then be accessed via the initialized io.Connect API object (e.g., `io.workspaces`, `io.search`).
         */
        libraries?: Array<(io: IOConnectBrowser.API, config?: IOConnectBrowser.Config | IOConnectDesktop.Config) => Promise<void>>;

        /**
         * Deprecated. Settings for the legacy Intents Resolver UI in **io.Connect Browser**.
         * @ignore
         */
        intents?: IOConnectBrowser.Intents.Config;

        /**
         * Settings for the io.Connect widget.
         * @since io.Connect Browser 3.5
         */
        widget?: WidgetConfig;

        /**
         * Settings for the io.Connect modals.
         * @since io.Connect Browser 4.0
         */
        modals?: ModalsUIConfig;

        /**
         * Settings for the Intents Resolver UI.
         * @since io.Connect Browser 4.0
         */
        intentResolver?: IntentResolverUIConfig;
    }

    /**
     * Type of the Channel Selector to use in the widget.
     */
    export type WidgetChannelSelectorType = "directional" | "default";

    /**
     * Determines which of the available Channels to display (all or only FDC3 ones).
     */
    export type WidgetChannelsDisplayMode = "all" | "fdc3";

    /**
     * Initial position for the widget within the window.
     */
    export type WidgetPosition = "top" | "bottom" | "left" | "right";

    /**
     * Mode for displaying the widget.
     */
    export type WidgetMode = "compact" | "default";

    /**
     * Settings for the Widget Channel Selector UI.
     */
    export interface WidgetChannelSelectorConfig {
        /**
         * If `true`, will enable the Channel Selector UI in the widget.
         * @default true
         */
        enable?: boolean;

        /**
         * Type of the Channel Selector UI.
         * @default "default"
         */
        type?: WidgetChannelSelectorType;
    }

    /**
     * Settings for the Channel Selector UI.
     */
    export interface WidgetChannels {

        /**
         * Settings for the Channel Selector UI.
         */
        selector?: WidgetChannelSelectorConfig;

        /**
         * Determines which of the available Channels to display (all or only FDC3 ones).
         * @default "all"
         */
        displayMode?: WidgetChannelsDisplayMode;
    }

    /**
     * Describes the configuration for the io.Connect widget.
     */
    export interface WidgetConfig {
        /**
         *  If `true`, will enable the widget for the Browser Client unless the app origin has been blocked in the Main app configuration.
         */
        enable: boolean;

        /**
         * Settings for the Channel Selector UI.
         */
        channels?: WidgetChannels;

        /**
         * Initial position for the widget within the window.
         * @default "bottom"
         */
        position?: WidgetPosition;

        /**
         * Mode for displaying the widget.
         * @default "default"
         */
        mode?: WidgetMode;

        /**
         * If `true`, the widget will be visible in the app even if the app is currently in a Workspace.
         * @default false
         */
        displayInWorkspace?: boolean;

        /**
         * If `true`, the `&commat;interopio/browser` library will wait for the `IOBrowserWidget()` factory function to resolve before completing its initialization.
         * @default true
         */
        awaitFactory?: boolean;

        /**
         * Interval in milliseconds to wait for the `IOBrowserWidget()` factory function to be fetched from the remote source.
         * @default 5000
         */
        timeout?: number;
    }

    /**
     * Settings for the Intents Resolver UI.
     */
    export interface IntentResolverUIConfig {

        /**
         * If `true`, will enable the Intents Resolver UI for the Browser Client unless the app origin has been blocked in the Main app configuration.
         */
        enable: boolean;

        /**
         * If `true`, the `&commat;interopio/browser` library will wait for the `IOBrowserIntentResolverUI()` factory function
         * to resolve before completing its initialization.
         * @default true
         */
        awaitFactory?: boolean;

        /**
         * Interval in milliseconds to wait for the `IOBrowserIntentResolverUI()` factory function to be fetched from the remote source.
         * @default 5000
         */
        timeout?: number;
    }

    /**
     * @ignore
     */
    export namespace IntentResolverUI {
        export interface API {
            open: (config: OpenConfig) => OpenResult;
            close: (config: CloseConfig) => void;
        }

        export interface OpenConfigWithIntentRequest {
            intentRequest: IOConnectBrowser.Intents.IntentRequest;
            handlerFilter?: never;
        }

        export interface OpenConfigWithHandlerFilter {
            handlerFilter: IOConnectBrowser.Intents.HandlerFilter;
            intentRequest?: never;
        }

        export interface UISettings {
            showCloseButton?: boolean;
        }

        export type OpenConfig = (OpenConfigWithIntentRequest | OpenConfigWithHandlerFilter) & { onUserResponse: (response: { response: IntentResolverResponse }) => void, uiSettings?: UISettings };

        export interface UserSettings {
            preserveChoice: boolean;
        }

        export interface UserChoiceResponse {
            intent: string;
            handler: IOConnectBrowser.Intents.IntentHandler;
            userSettings: UserSettings;
        }
        export interface IntentResolverResponse {
            isExpired?: boolean;
            isClosed?: boolean;
            userChoice?: UserChoiceResponse;
        }

        export interface OpenResult {
            id: string;
        }

        export interface CloseConfig {
            id: string;
        }
    }

    /**
     * The [`&commat;interopio/modals-ui`](https://www.npmjs.com/package/&commat;interopio/modals-ui) library provides components and APIs used
     * in **io.Connect Browser** for displaying dialogs and alerts. When initializing the [`&commat;interopio/browser`](https://www.npmjs.com/package/&commat;interopio/browser) library,
     * you can provide configuration for the Modals UI library (e.g., disable alerts and/or dialogs, and more).
     */
    export interface ModalsUIConfig {

        /**
         * Settings for the io.Connect alerts.
         */
        alerts?: {

            /**
             * If `true`, will enable the io.Connect alerts.
             */
            enabled: boolean;
        };

        /**
         * Settings for the io.Connect dialogs.
         */
        dialogs?: {

            /**
             * If `true`, will enable the io.Connect dialogs.
             */
            enabled: boolean;
        };

        /**
         * If `true`, the `&commat;interopio/browser` library will wait for the `IOBrowserModalsUI()` factory function to resolve before completing its initialization.
         * @default true
         */
        awaitFactory?: boolean;

        /**
         * Interval in milliseconds to wait for the `IOBrowserModalsUI()` factory function to be fetched from the remote source.
         * @default 5000
         */
        timeout?: number;
    }

    /**
     * @ignore
     */
    export namespace ModalsUI {

        /**
         * @ignore
         */
        export interface API {
            alerts: Alerts.API;
            dialogs: Dialogs.API;
        }

        /**
         * @ignore
         */
        export namespace Alerts {
            export interface API {
                open: (config: OpenConfig) => OpenResult;
                close: (config: CloseConfig) => void;
            }

            export interface InteropAction {
                name: string;
                settings: IOConnectModals.InteropSettings;
            }

            export type OpenConfig = Omit<IOConnectModals.AlertRequestConfig, "target" | "ttl"> & {
                onClose: () => void;
                onClick: (config: OnClickConfig) => void;
            }

            export interface OpenResult {
                id: string;
            }

            export interface CloseConfig {
                id: string;
            }

            export interface OnClickConfig {
                interopAction: InteropAction;
            }
        }

        /**
         * @ignore
         */
        export namespace Dialogs {
            export interface API {
                open: (config: OpenConfig) => OpenResult;
                close: (config: CloseConfig) => void;
            }

            export interface OpenConfig<Name extends string = string, Variables = any> {
                templateName: Name;
                onCompletion: (config: OnCompletionConfig) => void;
                size?: IOConnectModals.DialogRequestConfig["size"];
                variables: Variables;
            }

            export interface OpenResult {
                id: string;
            }

            export interface CloseConfig {
                id: string;
            }

            export interface OnCompletionConfig {
                response: IOConnectModals.DialogResponse;
            }
        }
    }

    export interface SystemLogger {
        level?: IOConnectCore.Logger.LogLevel;
        callback?: (logInfo: any) => void;
    }

    /**
     * Describes an instance of the initialized io.Connect library.
     */
    export interface API extends IOConnectCore.API {

        /**
         * Window Management API.
         */
        windows: IOConnectBrowser.Windows.API;

        /**
         * Layouts API.
         */
        layouts: IOConnectBrowser.Layouts.API;

        /**
         * Notifications API.
         */
        notifications: IOConnectBrowser.Notifications.API;

        /**
         * Channels API.
         */
        channels: IOConnectBrowser.Channels.API;

        /**
         * App Management API.
         */
        appManager: IOConnectBrowser.AppManager.API;

        /**
         * Intents API.
         */
        intents: IOConnectBrowser.Intents.API;

        /**
         * Themes API.
         */
        themes?: IOConnectBrowser.Themes.API;

        /**
         * Workspaces API.
         */
        workspaces?: IOConnectWorkspaces.API;

        /**
         * Search API.
         */
        search?: IOConnectSearch.API;

        /**
         * @ignore
         */
        webPlatform?: IOConnectBrowser.WebPlatform.API;

        /**
         * App Preferences API.
         */
        prefs: IOConnectBrowser.Prefs.API;

        /**
         * Modals API.
         * @since io.Connect Browser 4.0
         */
        modals?: IOConnectModals.API;
    }

    /**
     * @intro
     * Using the Window Management API, your app can easily open and manipulate browser windows.
     * This allows you to transform your traditional single-window web app into a multi-window native-like web application.
     * The Window Management API enables apps to:
     *
     * - open multiple windows;
     * - manipulate the position and size of opened windows;
     * - pass context data upon opening new windows;
     * - listen for and handle events related to opening and closing windows;
     *
     * The Window Management API is accessible via the [`io.windows`](#API) object.
     */
    export namespace Windows {
        export interface API {
            list(): WebWindow[];

            /** Returns the current window. */
            my(): WebWindow;

            /**
             * Finds a window by ID.
             * @param id Window ID.
             */
            findById(id: string): WebWindow | undefined;

            /**
             * Opens a new IO Connect Browser Window.
             * @param name The name for the window
             * @param url The window URL.
             * @param options Options for creating a window.
             */
            open(name: string, url: string, options?: Settings): Promise<WebWindow>;

            /**
             * Notifies when a new window is opened.
             * @param callback Callback function to handle the event. Receives the added window as a parameter. Returns an unsubscribe function.
             */
            onWindowAdded(callback: (window: WebWindow) => void): UnsubscribeFunction;

            /**
             * Notifies when a window is closed. For backwards compatibility, you can also use `windowRemoved`.
             * @param callback Callback function to handle the event. Receives the removed window as a parameter. Returns an unsubscribe function.
             */
            onWindowRemoved(callback: (window: WebWindow) => void): UnsubscribeFunction;

            /**
             * Notifies when a window receives focus.
             * @param callback Callback function to handle the event. Receives the window instance as a parameter. Returns an unsubscribe function.
             */
            onWindowGotFocus(callback: (window: WebWindow) => void): UnsubscribeFunction;

            /**
             * Notifies when a window loses focus.
             * @param callback Callback function to handle the event. Receives the window instance as a parameter. Returns an unsubscribe function.
             */
            onWindowLostFocus(callback: (window: WebWindow) => void): UnsubscribeFunction;
        }

        export interface WebWindow {
            id: string;

            name: string;

            isFocused: boolean;

            /**
             * Gets the current URL of the window.
             */
            getURL(): Promise<string>;

            /**
             * Sets new location and size for the window. The accepted settings are absolute.
             * @param dimension The object containing the desired absolute size and location.
             */
            moveResize(dimension: Partial<Bounds>): Promise<WebWindow>;

            /**
             * Sets a new size of the window. The accepted settings are relative.
             * @param width Relative width of the window.
             * @param height Relative height of the window.
             */
            resizeTo(width?: number, height?: number): Promise<WebWindow>;

            /**
             * Sets a new location of the window. The accepted settings are relative.
             * @param top Relative distance top coordinates.
             * @param left Relative distance left coordinates.
             */
            moveTo(top?: number, left?: number): Promise<WebWindow>;

            /**
             * Attempts to activate and bring to foreground the window. It is possible to fail due to client browser settings.
             */
            focus(): Promise<WebWindow>;

            /**
             * Closes the window
             * @default 0
             */
            close(): Promise<WebWindow>;

            /**
             * Returns the title of the window.
             * @default 0
             */
            getTitle(): Promise<string>;

            /**
             * Sets a new title for the window
             * @param title The new title value.
             */
            setTitle(title: string): Promise<WebWindow>;

            /**
             * Returns the current location and size of the window.
             */
            getBounds(): Promise<Bounds>;

            /**
             * Gets the current context object of the window.
             */
            getContext(): Promise<any>;

            /**
             * Updates the context object of the window
             * @param context The new context object for the window.
             */
            updateContext(context: any): Promise<WebWindow>;

            /**
             * Sets new context for the window.
             * @param context The new context object for the window.
             */
            setContext(context: any): Promise<WebWindow>;

            /**
             * Notifies when a change to the window's context has been made.
             * @param callback The function which will be invoked when a change to the window's context happens. The function will be called with the new context and window as arguments.
             */
            onContextUpdated(callback: (context: any, window: WebWindow) => void): UnsubscribeFunction;

            /**
             * Notifies when the window focus is changed.
             * @param callback Callback function to handle the event. Returns an unsubscribe function.
             */
            onFocusChanged(callback: (window: WebWindow) => void): UnsubscribeFunction;

            /**
             * Retrieves the current Channel of the window, if any.
             */
            getChannel(): Promise<string>;

            /**
             * Notifies when the current Channels of the window have changed. Returns a function you can use to unsubscribe from the event.
             * @param callback Callback for handling the event. Receives the names of the current Channels as an argument.
             */
            onChannelsChanged(callback: (names: string[]) => void): UnsubscribeFunction;
        }
        export interface Settings {

            /**
             * Distance of the top left window corner from the top edge of the screen.
             * @default 0
             */
            top?: number;

            /**
             * Distance of the top left window corner from the left edge of the screen.
             * @default 0
             */
            left?: number;

            /**
             * Window width.
             * @default 400
             */
            width?: number;

            /**
             * Window height.
             * @default 400
             */
            height?: number;

            /**
             * The initial window context. Accessible from {@link WebWindow#getContext}
             */
            context?: any;

            /**
             * The ID of the window that will be used to relatively position the new window.
             * Can be combined with `relativeDirection`.
             */
            relativeTo?: string;

            /**
             * Direction (`"bottom"`, `"top"`, `"left"`, `"right"`) of positioning the window relatively to the `relativeTo` window. Considered only if `relativeTo` is supplied.
             * @default "right"
             */
            relativeDirection?: RelativeDirection;
        }

        export type RelativeDirection = "top" | "left" | "right" | "bottom";

        export interface Bounds {
            top: number;
            left: number;
            width: number;
            height: number;
        }
    }

    /**
     * @intro
     * **io.Connect Browser** enables you to to save and later restore the exact arrangement and context of your environment
     * - windows, apps, Workspaces, and their respective bounds and context.
     *
     * The Layouts API offers the following features:
     *
     * - importing, exporting, removing. and retrieving Layouts;
     * - saving and restoring Layouts;
     * - events related to adding, removing, changing, or saving Layouts;
     * - requesting browser permission for the Multi-Screen Window Placement API;
     *
     * The Layouts API is accessible via the [`io.layouts`](#API) object.
     */
    namespace Layouts {

        /**
         *
         * Type of the Layout. Supported Layouts are `"Global"` and `"Workspace"`.
         *
         */
        export type LayoutType = "Global" | "Activity" | "ApplicationDefault" | "Swimlane" | "Workspace";

        /**
         * Controls the import behavior. If `"replace"` (default), all existing Layouts will be removed.
         * If `"merge"`, the Layouts will be added to the existing ones.
         */
        export type ImportMode = "replace" | "merge";

        /**
         * Layouts API.
         */
        export interface API {

            /**
             * Fetches a saved Layout if a Layout with the provided name and type exists.
             * @param type Type of the Layout to fetch.
             * @param name Name of the Layout to fetch.
             */
            get(name: string, type: LayoutType): Promise<Layout | undefined>;

            /**
             * Retrieves the last restored Global Layout (if any).
             * @since io.Connect Browser 4.0
             */
            getCurrentLayout(): Promise<Layout | undefined>;

            /**
             * Returns a lightweight description of all Layouts of the provided type, without the extensive objects describing the Layout components.
             * @param type Type of the Layouts to fetch.
             */
            getAll(type: LayoutType): Promise<LayoutSummary[]>;

            /**
             * Returns a collection of all available `Layout` objects of the provided type.
             * @param type Type of the Layouts to export.
             */
            export(layoutType: LayoutType): Promise<Layout[]>;

            /**
             * Imports a collection of `Layout` objects.
             * @param layouts An array of `Layout` objects to be imported.
             * @param mode If `"replace"` (default), all existing Layouts will be removed. If `"merge"`, the Layouts will be added to the existing ones.
             */
            import(layouts: Layout[], mode?: ImportMode): Promise<void>;

            /**
             * Saves a new Layout.
             * @param layout Options for saving a Layout.
             */
            save(layout: NewLayoutOptions): Promise<Layout>;

            /**
             * Restores a Layout.
             * @param options Options for restoring a Layout.
             */
            restore(options: RestoreOptions): Promise<void>;

            /**
             * Removes a Layout.
             * @param type Type of the Layout to remove.
             * @param name Name of the Layout to remove.
             */
            remove(type: LayoutType, name: string): Promise<void>;

            /**
             * Notifies when a new Layout is added.
             * @param callback Callback function to handle the event. Receives the `Layout` object as an argument and returns an unsubscribe function.
             */
            onAdded(callback: (layout: Layout) => void): () => void;

            /**
             * Notifies when a Layout is modified.
             * @param callback Callback function to handle the event. Receives the `Layout` object as an argument and returns an unsubscribe function.
             */
            onChanged(callback: (layout: Layout) => void): () => void;

            /**
             * Notifies when a new default Global Layout has been selected or when the current one has been cleared.
             * @param callback Callback function for handling the event. Receives as an argument an object with a `name` property
             * holding the name of the newly selected default Global Layout. If the default Global Layout has been cleared, the argument will be `undefined`.
             * @since io.Connect Browser 4.0
             */
            onDefaultGlobalChanged(callback: (layout?: { name: string }) => void): () => void;

            /**
             * Notifies when a Layout is removed.
             * @param callback Callback function to handle the event. Receives the `Layout` object as an argument and returns an unsubscribe function.
             */
            onRemoved(callback: (layout: Layout) => void): () => void;

            /**
             * Subscribes for Layout save requests.
             * @param callback The callback passed as an argument will be invoked when a Layout save operation is requested.
             * You have the option to save data (context) which will be restored when the Layout is restored.
             * Returns an unsubscribe function.
             */
            onSaveRequested(callback: (info?: SaveRequestContext) => SaveRequestResponse): () => void;

            /**
             * Retrieves the browser Multi-Screen Window Placement permission state for the **io.Connect Browser** environment.
             */
            getMultiScreenPermissionState(): Promise<{ state: "prompt" | "granted" | "denied" }>;

            /**
             * Opens the browser permission prompt requesting Multi-Screen Window Placement permission from the user for the **io.Connect Browser** environment.
             * This can only be requested from the Main app (Web Platform) due to the transient activation restrictions of the browsers.
             */
            requestMultiScreenPermission(): Promise<{ permissionGranted: boolean }>;

            /**
             * Checks whether Global Layouts are activated in the **io.Connect Browser** environment.
             */
            getGlobalTypeState(): Promise<{ activated: boolean }>;

            /**
             * Retrieves the default Global Layout, if any.
             */
            getDefaultGlobal(): Promise<Layout | undefined>;

            /**
             * Sets a new default Global Layout.
             * @param name Name of the Global Layout to set as default.
             */
            setDefaultGlobal(name: string): Promise<void>;

            /**
             * Removes the default Global Layout.
             */
            clearDefaultGlobal(): Promise<void>;

            /**
             * Renames a Layout.
             * @param layout Existing Layout to rename.
             * @param newName New name for the Layout.
             */
            rename(layout: Layout, newName: string): Promise<LayoutResult>;

            /**
             * Notifies when a Layout is renamed. Returns an unsubscribe function.
             * @param callback Callback function for handling the event. Receives as a first argument the `Layout` object describing the renamed Layout.
             * Receives as a second argument an object with a `name` property holding the previous Layout name.
             */
            onRenamed(callback: (layout: Layout, previous: { name: string }) => void): () => void;

            /**
             * Notifies when a Layout is restored.
             * @param callback Callback function for handling the event. Receives as an argument the `Layout` object that was restored.
             * @since io.Connect Browser 4.0
             */
            onRestored(callback: (layout: Layout) => void): () => void;

            /**
             * Updates the metadata of a Layout.
             * @param layout Existing Layout to update.
             */
            updateMetadata(layout: Layout): Promise<void>;
        }

        /**
         * Describes a Layout and its components.
         */
        export interface Layout {
            /** Name of the Layout. The name is unique per Layout type. */
            name: string;

            /** Type of the Layout. */
            type: LayoutType;

            /** Array of component objects describing the apps and Workspaces saved in the Layout. */
            components: Array<WindowComponent | WorkspaceFrameComponent | IOConnectWorkspaces.WorkspaceComponent>;

            /**
            * Used internally to audit operations.
            * @ignore
            */
            token?: string;

            /** Context object passed when the Layout was saved. */
            context?: any;

            /** Metadata passed when the Layout was saved. */
            metadata?: any;

            /** Version of the Layout. */
            version?: number;
        }

        /**
         * @ignore
         */
        export type ComponentType = "application" | "activity";

        /**
         * @ignore
         */
        export interface WorkspaceFrameComponent {
            type: "workspaceFrame";

            /** The name of the workspace application. This is supported only in Enterprise */
            application: string;

            /** Type of the component - can be application or activity. */
            componentType?: ComponentType;

            /** Object describing the application bounds, name, context, etc. */
            state: WorkspaceFrameComponentState;
        }

        /**
         * @ignore
         */
        export interface WorkspaceFrameComponentState {
            bounds: IOConnectBrowser.Windows.Bounds;
            instanceId: string;
            selectedWorkspace: number;
            workspaces: IOConnectWorkspaces.WorkspaceLayoutComponentState[];
            windowState?: string;
            restoreState?: string;
            context?: any;
        }

        /**
         * @ignore
         */
        export interface WindowComponent {
            type: "window";

            /** Type of the component - can be application or activity. */
            componentType?: ComponentType;

            /** The name of the originating application for the instance or "no-app-window" if it was not started as an application instance */
            application: string;

            /** Object describing the application bounds, name, context, etc. */
            state: WindowComponentState;
        }

        /**
         * @ignore
         */
        export interface WindowComponentState {
            context?: any;
            bounds: IOConnectBrowser.Windows.Bounds;
            createArgs: WindowComponentCreateArgs;
            windowState?: string,
            restoreState?: string,
            restoreSettings?: {
                groupId?: string,
                groupZOrder?: number
            },
            instanceId: string,
            isSticky?: boolean,
            isCollapsed?: boolean
        }

        /**
         * @ignore
         */
        export interface WindowComponentCreateArgs {
            name?: string;
            url?: string;
            context?: any;
        }

        /**
         * A lightweight description of a Layout, without the extensive objects describing its components.
         */
        export interface LayoutSummary {
            /** Name of the Layout. The name is unique per Layout type. */
            name: string;

            /** Type of the Layout. */
            type: LayoutType;

            /** Context object passed when the Layout was saved. */
            context?: any;

            /** Metadata passed when the Layout was saved. */
            metadata?: any;
        }

        /**
         * Options for saving a Layout.
         */
        export interface NewLayoutOptions {
            /** Name for the Layout. */
            name: string;

            /**
             * Context to be saved with the Layout. Used for transferring data to the apps when restoring a Layout.
             */
            context?: any;

            /**
             * Metadata to be saved with the Layout.
             */
            metadata?: any;

            /**
             * Window or app instance IDs of the instances to be saved in the Layout.
             */
            instances?: string[];

            /**
             * Window or app instance IDs of the instances to be ignored when saving the Layout.
             */
            ignoreInstances?: string[];
        }

        /**
         * Options for restoring a Layout.
         */
        export interface RestoreOptions {

            /**
             * Name of the Layout to restore.
             */
            name: string;

            /**
             * Context object that will be passed to the restored apps. It will be merged with the saved context object.
             */
            context?: object;

            /**
             * If `true`, will close all visible running instances before restoring the Layout.
             * The only exception is the Main app (Web Platform) - it will never be closed when restoring a Layout.
             * @default true
             */
            closeRunningInstances?: boolean;

            /**
             * If `true`, will close the current app before restoring a Layout. If `closeRunningInstances` is set to `false`, this will default to `false` too.
             * @default true
             */
            closeMe?: boolean;

            /**
             * Timeout in milliseconds for restoring the Layout. If the time limit is hit, all apps opened up to this point will be closed and an error will be thrown.
             * @default 60000
             */
            timeout?: number;
        }

        /**
         * Object returned by the handler for a save Layout request.
         */
        export interface SaveRequestResponse {
            /** Context to be saved for the specific app in the Layout. */
            windowContext: object;
        }

        /**
         * Object passed as an argument to the handler for a save Layout request.
         */
        export interface SaveRequestContext {
            /** Context for the Layout. */
            context?: unknown;
            /** Name of the Layout. */
            layoutName: string;
            /** Type of the Layout. */
            layoutType: LayoutType;
        }

        /**
         * Describes the base result returned by methods for manipulating Layouts - e.g., renaming, hibernating, updating default context.
         */
        export interface LayoutResult {
            /** Status of the Layout operation. If successful, will be set to "Success", otherwise, will contain the returned error message. */
            status: string;
        }
    }

    /**
     * @intro
     * The Notifications API provides a way to display native notifications with actions and to handle notification and action clicks.
     * **io.Connect Browser** supports all available notification settings as defined in the [DOM Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API).
     *
     * The **io.Connect Browser** Notifications API extends the DOM Notifications API with the option to handle notification and action clicks using Interop methods.
     *
     * The Notifications API is accessible via the [`io.notifications`](#API) object.
     */
    export namespace Notifications {
        export interface API {
            /**
             * Raises a new notification
             * @param notification notification options
             */
            raise(notification: RaiseOptions): Promise<Notification>;

            /**
             * **io.Connect Browser** only. Retrieves the state of the native browser notification permission for the platform.
             */
            getPermission?(): Promise<"default" | "granted" | "denied">;

            /**
             * **io.Connect Browser** only. Triggers the native browser permission dialog. Must only be called from within a platform.
             */
            requestPermission?(): Promise<boolean>;

            /** Returns a list of all known notifications. */
            list(): Promise<NotificationData[]>;

            /**
             * Notifies the user of any new raised notifications via the Notifications API.
             * @param callback A function which will be called when a new notification is raised.
             */
            onRaised(callback: (notification: NotificationData) => void): UnsubscribeFunction;

            /**
             * Notifies the user when a notification was removed via the Notifications API.
             * @param callback A function which will be called when a notification is removed.
             */
            onClosed(callback: (notification: { id: string }) => void): UnsubscribeFunction;

            /**
             * Notifies when the global notification settings are changed.
             * @param callback Callback function for handling the event.
             */
            onConfigurationChanged(callback: (configuration: Configuration) => void): UnsubscribeFunction;

            /**
             * Notifies when the number of active notification is changed.
             * @param callback Callback function for handling the event.
             */
            onActiveCountChanged(callback: (info: { count: number; }) => void): UnsubscribeFunction;

            /**
             * Alias for `onActiveCountChanged()` for compatibility with **io.Connect Desktop**.
             * @param callback Callback function for handling the event.
             * @since io.Connect Browser 4.0
             */
            onCounterChanged(callback: (info: { count: number; }) => void): UnsubscribeFunction;

            /** Notifies when the state of a notification is changed.
             * @param callback Callback function for handling the event.
             */
            onStateChanged(callback: (notification: { id: string; }, state: State) => void): UnsubscribeFunction;

            /**
             * Issues a programmatic click on a notification.
             * @param id The id of the notification to click on.
             * @param actions Optional action value to click on.
             */
            click(id: string, action?: string): Promise<void>;

            /**
             * Clears a specified notification.
             * @param id The id of the notification to be removed.
             */
            clear(id: string): Promise<void>;

            /** Removes all known notifications from the system. */
            clearAll(): Promise<void>;

            /** Clears all notifications that the user has already seen. */
            clearOld(): Promise<void>;

            /**
             * Configures the Global notification settings.
             * @param options configuration options
             */
            configure(options: Configuration): Promise<void>;

            /** Retrieves the current global notification settings. */
            getConfiguration(): Promise<Configuration>;

            /** Retrieves the current filter with apps allowed or not allowed to raise notifications. */
            getFilter(): Promise<NotificationFilter>;

            /**
             * Sets a filter with apps allowed or not allowed to raise notifications.
             * @param filter Filter with names of apps allowed or not allowed to raise notifications.
             */
            setFilter(filter: NotificationFilter): Promise<NotificationFilter>;

            /**
             * Sets the state of a notification.
             * @param id ID of the notification to change.
             * @param state Value for the new notification state.
             */
            setState(id: string, state: State): Promise<void>;
        }

        /**
         * Notification states that are used by the platform when handling notifications. These states can also be used in your custom logic for processing notifications on the client or on the server side. Defaults to `"Active"`.
         * - `"Active"` - a notification can be marked as active when it is raised, but the user hasn't seen it, or interacted in any way with it yet;
         * - `"Acknowledged"` - a notification can be marked as acknowledged when the user has interacted with it by clicking on the notification or on an action in it;
         * - `"Seen"` - a notification can be marked as seen when the user has seen it (e.g., by opening the Notification Panel);
         * - `"Closed"` - a notification can be marked as closed when the user has closed the notification in the Notification Panel;
         * - `"Stale"` - a notification can be marked as stale after a predefined period of time;
         * - `"Snoozed"` - a notification can be marked as snoozed when the user snoozes it from the UI;
         * - `"Processing"` - a notification can be marked as `"Processing"` when its state is in the process of changing (e.g., the user interacts with a notification from the UI, you make a request to a remote service to update the notification state, and you are still waiting for a response);
         */
        export type State = "Active" | "Acknowledged" | "Seen" | "Closed" | "Stale" | "Snoozed" | "Processing";

        export interface NotificationDefinition {
            badge?: string;
            body?: string;
            data?: any;
            dir?: "auto" | "ltr" | "rtl";
            icon?: string;
            image?: string;
            lang?: string;
            renotify?: boolean;
            requireInteraction?: boolean;
            silent?: boolean;
            tag?: string;
            timestamp?: number;
            vibrate?: number[];
        }

        export interface RaiseOptions extends NotificationDefinition {
            /** The title of the notification */
            title: string;
            /** Set to make the notification click invoke an interop method with specific arguments */
            clickInterop?: InteropActionSettings;
            /** List of action attached to the notification. Those will appear as buttons in the notification UI */
            actions?: NotificationAction[];
            /** **io.Connect Browser** only. If set to `true`, the platform app will be focused when the user clicks on the notification. Defaults to false. */
            focusPlatformOnDefaultClick?: boolean;
            /** Severity of the alert */
            severity?: "Low" | "Medium" | "High" | "Critical" | "None";
            /** Indicates whether a native toast will be shown or not. Defaults to `true` */
            showToast?: boolean;
            /** Indicates whether the notification should appear in notification panels. Defaults to `true` */
            showInPanel?: boolean;
            /** Notification state. Defaults to `"Active"` */
            state?: State;
        }

        export interface NotificationData extends RaiseOptions {
            id: string;
        }

        export interface Notification extends NotificationData {
            onclick: () => any;
            onshow: () => any;
        }

        export interface NotificationAction {
            action: string;
            title: string;
            icon?: string;
            /** set to make the action invoke an interop method with specific arguments */
            interop?: InteropActionSettings;
        }

        export interface InteropActionSettings {
            method: string;
            arguments?: any;
            target?: "all" | "best";
        }

        export type NotificationClickHandler = (io: IOConnectBrowser.API, notificationDefinition: NotificationDefinition) => void;

        export interface ActionClickHandler {
            action: string;
            handler: NotificationClickHandler;
        }

        export interface Settings {
            defaultClick: NotificationClickHandler;
            actionClicks: ActionClickHandler[];
        }

        /** Global notification settings */
        export interface Configuration {
            /** If `true`, will enable all notifications. */
            enable?: boolean;
            /** If `true`, will enable notification toasts. */
            enableToasts?: boolean;
            /** Filter with names of apps that are allowed or not allowed to raise notifications. */
            sourceFilter?: NotificationFilter;
            /**
             * If `true`, will enable showing a notification badge in the io.Connect Home App.
             * @default true
             * @since io.Connect Browser 4.0
             */
            showNotificationBadge?: boolean;
        }

        /** Filter with names of apps that are allowed or not allowed to raise notifications. */
        export interface NotificationFilter {
            /** Array of names of apps allowed to raise notifications. */
            allowed?: string[];
            /** Array of names of apps not allowed to raise notifications. */
            blocked?: string[];
        }
    }

    /**
     * @intro
     * Channels are globally accessed named contexts that allow users to dynamically group apps, instructing them to work over the same shared data object.
     *
     * The Channels API enables you to:
     *
     * - retrieve the names and contexts of all Channels;
     * - retrieve the current Channel, join and leave Channels, subscribe for the event which fires when the