@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";

/**
 * 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 and notifications.
 *
 * ## 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 as a Node.js module:
 *
 * ```html
 * <script type="text/javascript" src="browser.umd.js"></script>
 * ```
 *
 * Or:
 *
 * ``` javascript
 * import IOBrowser from "&commat;interopio/browser";
 * ```
 *
 * When deploying your app in production, it's recommended to always reference a specific minified version:
 *
 * ```html
 * <script type="text/javascript" src="browser.umd.min.js"></script>
 * ```
 *
 * ## Initialization
 *
 * The [`&commat;interopio/browser`](https://www.npmjs.com/package/&commat;interopio/browser) library attaches a factory function to the global `window` object at runtime - `IOBrowser()`.
 * It can be invoked with an optional configuration object to initialize the library and connect to the **io.Connect Browser** environment. The factory function resolves with the `io` API object:
 *
 * ```javascript
 * const initializeIOConnect = async () => {
 *
 *     // Initializing the Workspaces library.
 *     const initOptions = {
 *         libraries: [IOWorkspaces]
 *     };
 *
 *     // Use the object returned from the factory function
 *     // to access the IOConnect Browser APIs.
 *     const io = await IOBrowser(initOptions);
 *
 *     // Here the library is initialized and you can access all io.Connect Browser APIs.
 * };
 *
 * initializeIOConnect().catch(console.error);
 * ```
 */
export namespace IOConnectBrowser {

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

    export interface Config {
        /**
         * Configure the system logger. Used mostly for 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;

        /**
         * Configure the system logger. Used mostly for during development.
         */
        notifications?: Notifications.Settings;

        /** Enable, disable and configure the Contexts API. Enabled by default */
        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
         */
        memoizeAPI?: boolean;

        /**
         * A list of io.Connect libraries which will be initiated internally and provide access to specific functionalities
         */
        libraries?: Array<(io: IOConnectBrowser.API, config?: IOConnectBrowser.Config | IOConnectDesktop.Config) => Promise<void>>;

        /* Enable and configure Intents Resolver UI */
        intents?: IOConnectBrowser.Intents.Config;

        /* Configure widget */
        widget?: Widget;
    }

    export namespace Widget {
        export type ChannelSelectorType = "directional" | "default";

        export type ChannelsDisplayMode = "all" | "fdc3";

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

        export type Mode = "compact" | "default";

        export interface ChannelSelectorConfig {
            /**
             * Configure whether Channel Selector will be added to the Widget component
             * @default true
             */
            enable?: boolean;
    
            type?: ChannelSelectorType;
        }

        export interface Channels {
            selector?: ChannelSelectorConfig;
            /**
            * Configure whether to show only fdc3-enabled channels or all
            * @default all
            */
            displayMode?: ChannelsDisplayMode;
        }

        export interface DefaultConfig {
            enable: boolean;

            channels?: Channels;

            /**
             * Starting position
             * @default bottom
             */
            position?: Position;

            /**
             * Widget mode
             * @default default
             */
            mode?: Mode;

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


    export interface Widget extends Widget.DefaultConfig {
        /**
         * Whether to wait for IOBrowserWidget factory to resolve
         * @default true
         */
        awaitFactory?: boolean;
        /**
         * Timeout to wait for the IOBrowserWidget factory to be fetched from the remote source
         * @default 5000
         */
        timeout?: number;
    }

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

    export interface API extends IOConnectCore.API {
        windows: IOConnectBrowser.Windows.API;
        layouts: IOConnectBrowser.Layouts.API;
        notifications: IOConnectBrowser.Notifications.API;
        channels: IOConnectBrowser.Channels.API;
        appManager: IOConnectBrowser.AppManager.API;
        intents: IOConnectBrowser.Intents.API;
        themes?: IOConnectBrowser.Themes.API;
        workspaces?: IOConnectWorkspaces.API;
        search?: IOConnectSearch.API;
        webPlatform?: IOConnectBrowser.WebPlatform.API;
        prefs: IOConnectBrowser.Prefs.API;
    }

    /**
     * @intro
     * Using the Window Management API, your application 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 applications 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 through the `io.windows` 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
     * The Layouts library has the following capabilities:
     *
     * - importing, exporting, removing and getting 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 through the `io.layouts` 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>;

            /**
             * 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 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.
             * @param callback Callback function to handle the event. Receives the `Layout` object as an argument and returns an unsubscribe function.
             */
            onRenamed(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 through the `io.notifications` 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;

            /** 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;
        }

        /** 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:
     *
     * - discover Channels - get the names and contexts of all Channels;
     * - navigate through Channels - get the current Channel, join and leave Channels, subscribe for the event which fires when the current Channel has changed;
     * - publish and subscribe - publish data to other apps on the same Channel and subscribe for Channel updates to react to data published by other apps;
     *
     * The Channels API is accessible through the `io.channels` object.
     */
    namespace Channels {
        /**
         * Channels API.
         */
        export interface API {
            /**
             * Retrieves the current Channel mode (single or multi Channel). Set by the io.Connect framework based on configuration.
             * @default "single"
             * @since io.Connect Browser 3.5
             */
            mode: Mode;

            /**
             * Tracks the data in the current channel. Persisted after a channel change.
             * The callback isn't called when you publish the data.
             * @param callback Callback function to handle the received data.
             * @param options Settings for subscribing to an FDC3 context published in the io.Connect Channel.
             * @returns Unsubscribe function.
             */
            subscribe(callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options): UnsubscribeFunction;

            /**
             * Tracks the data in a given channel.
             * @param name The channel to track.
             * @param callback Callback function to handle the received data.
             * @param options Settings for subscribing to an FDC3 context published in the io.Connect Channel.
             * @returns Promise that resolves with an unsubscribe function.
             */
            subscribeFor(name: string, callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options): Promise<UnsubscribeFunction>;

            /**
             * Updates the context of the current or a given channel.
             * @param data Data object with which to update the channel context.
             * @param options The name of the Channel to update, or an object containing the name of the Channel to update and a flag indicating whether the published data is an FDC3 context. If no options are provided, the current Channel will be updated.
             * @returns Promise that resolves when the data has been published.
             */
            publish(data: any, options?: string | PublishOptions): Promise<void>;

            /**
             * Returns a list of all channel names.
             * @returns Promise that resolves with the list of all channel names.
             */
            all(): Promise<string[]>;

            /**
             * Returns a list of all channel contexts.
             * @returns Promise that resolves with the list of all channel contexts.
             */
            list(): Promise<ChannelContext[]>;

            /**
             * Returns the context of a given channel.
             * @param name The name of the channel whose context to return.
             * @param options Settings for retrieving an FDC3 context published in the io.Connect Channel.
             * @returns Promise that resolves with the context of the given channel.
             */
            get(name: string, options?: FDC3Options): Promise<ChannelContext>;

            /**
             * Retrieves a list with the contexts of the current Channels. Can be used both in single and in multi Channel mode.
             * If used in single Channel mode, the returned array will always contain a single member if the window is joined to a Channel, or will be empty otherwise.
             * @since io.Connect Browser 3.5
             */
            getMyChannels(): Promise<ChannelContext[]>;

            /**
             * Retrieves a list with the names of the current Channels. Can be used both in single and in multi Channel mode.
             * If used in single Channel mode, the returned array will always contain a single member if the window is joined to a Channel, or will be empty otherwise.
             * @since io.Connect Browser 3.5
             */
            myChannels(): string[];

            /**
             * Joins a new channel by name. Leaves the current channel.
             * @param name The name of the channel to join.
             * @param windowId ID of a window which to join to a Channel. If not provided, will join the current window to the specified Channel.
             * @returns Promise that resolves when the channel has been joined.
             */
            join(name: string, windowId?: string): Promise<void>;

            /**
             * Removes the current or a specified window from the current or a specified Channel.
             * @param options Options for leaving Channels.
             */
            leave(options?: LeaveOptions): Promise<void>;

            /**
             * Returns the name of the current channel.
             * @ignore
             * @returns The name of the current channel.
             */
            current(): string;

            /**
             * Retrieves the name of the current Channel.
             * It's recommended to use the `myChannels()` method instead, which can retrieve the names of the currently joined Channels both in single and in multi Channel mode.
             */
            my(): string;

            /**
             * Subscribes for the event which fires when a channel is changed.
             * @ignore
             * @param callback Callback function to handle channel changes.
             * @returns Unsubscribe function.
             */
            changed(callback: (channel: string) => void): UnsubscribeFunction;

            /**
             * Notifies when the current window joins or leaves a Channel. Returns an unsubscribe function.
             * It's recommended to use the `onChannelsChanged()` method instead, which can handle Channel changes both in single and in multi Channel mode.
             * @param callback Callback function for handling the event. Receives as an argument the name of the Channel which the window has joined or left.
             */
            onChanged(callback: (channel: string) => void): UnsubscribeFunction;

            /**
             * Notifies when the current window joins or leaves a Channel. Can be used both in single and in multi Channel mode. 
             * If used in single Channel mode, when the window joins a Channel, the array argument passed to the callback for handling the event
             * will always contain a single member; when the window leaves the current Channel, the array will be empty. Returns an unsubscribe function.
             * @param callback Callback function for handling the event. Receives a list with the names of the currently joined Channels as an argument.
             * @since io.Connect Browser 3.5
             */
            onChannelsChanged(callback: (channels: string[]) => void): UnsubscribeFunction;

            /**
             * Adds a new Channel.
             * @param info Initial Channel context.
             */
            add(info: ChannelDefinition): Promise<ChannelContext>;

            /**
             * Removes a Channel.
             * @param name The name of the Channel to remove.
             */
            remove(name: string): Promise<void>;

            /**
             * Retrieves the context of the current Channel.
             * It's recommended to use the `getMyChannels()` method instead, which can retrieve the contexts of the currently joined Channels both in single and in multi Channel mode.
             * @param options Settings for retrieving an FDC3 context published in the io.Connect Channel.
             */
            getMy(options?: FDC3Options): Promise<ChannelContext | undefined>;

            /**
             * Retrieves all windows on a specified Channel.
             * @param channel The name of the Channel for which windows should be returned.
             * @returns Promise that resolves with the list of all windows on a specified Channel.
             */
            getWindowsOnChannel(channel: string): Promise<IOConnectBrowser.Windows.WebWindow[]>

            /**
             * Retrieves all windows that can use Channels together with their current Channel.
             * @param filter Filter describing which windows to retrieve. If no filter is supplied, will return all windows that can use Channels.
             * @returns Promise that resolves with the list of all windows that can use Channels together with their current Channel.
             */
            getWindowsWithChannels(filter?: WindowWithChannelFilter): Promise<WindowOnChannelInfo[]>;

            /**
             * Prevents or allows the current or another window to publish or subscribe to a specific Channel.
             * @param restrictions Restrictions for publishing or subscribing to a specific Channel.
             * @since io.Connect Browser 3.3
             */
            restrict(config: ChannelRestrictions): Promise<void>;

            /**
             * Retrieves the restrictions applied to the current window for publishing or subscribing to Channels. Pass a window ID to retrieve the restrictions for the specified window.
             * @param windowId ID of the window for which to retrieve the applied restrictions for publishing or subscribing to Channels.
             * @since io.Connect Browser 3.3
             */
            getRestrictions(windowId?: string): Promise<Restrictions>;

            /**
             * Prevents or allows the current or another window to publish or subscribe to all Channels.
             * @param restrictions Restrictions for publishing or subscribing to all Channels.
             * @since io.Connect Browser 3.3
             */
            restrictAll(restrictions: RestrictionsConfig): Promise<void>;
        }

        /**
         * Channel mode. In single Channel mode, io.Connect Windows can join or leave only one Channel at a time.
         * In multi Channel mode, io.Connect Windows can join or leave multiple Channels simultaneously.
         * The Channel mode is set by the io.Connect framework based on configuration.
         */
        export type Mode = "single" | "multi";

        /**
         * Settings for retrieving and subscribing for FDC3 contexts published in an io.Connect Channel.
         */
        export interface FDC3Options {
            /**
             * Type of the FDC3 context to retrieve or to which to subscribe.
             */
            contextType?: string;
        }

        /**
         * Options for leaving Channels.
         * If only a window ID is provided, the specified window will be removed from the current Channel if in single Channel mode,
         * or from all currently joined Channels if in multi Channel mode.
         * If you provide only the name of the Channel to leave, the current window will be removed from the specified Channel.
         * If you don't provide an argument, the current window will be removed from the current Channel if in single Channel mode,
         * or from all currently joined Channels if in multi Channel mode.
         * @since io.Connect Browser 3.5
         */
        export interface LeaveOptions {
            /**
             * ID of an io.Connect Window which to remove from a Channel.
             */
            windowId?: string;

            /**
             * Name of a Channel from which to remove the current or a specified window.
             */
            channel?: string;
        }

        /**
         * Options for updating a Channel context with the `publis