@interopio/desktop 6.8.4 → 6.9.0

package/changelog.md

@@ -1,3 +1,9 @@
+6.9.0
+- feat: Enable executeJavaScript Method Access through External API
+- feat: Bulk update Notifications from Notification Panel
+- feat: Added the pinned tabs methods and properties
+- feat: Interception API
+- feat: Added fdc3 parsing options to the channels API
 6.8.4
 - chore: bump due to workspaces api release
 6.8.3

package/desktop.d.ts

@@ -224,6 +224,12 @@ export declare namespace IOConnectDesktop {
          * Cookies API.
          */
         cookies: IOConnectDesktop.Cookies.API;
+
+        /**
+         * Interception API.
+         * @since io.Connect Desktop 9.6
+         */
+        interception: IOConnectDesktop.Interception.API;
     }
 
     /**
@@ -5646,7 +5652,7 @@ export declare namespace IOConnectDesktop {
              * Refreshes the current window.
              * @param ignoreCache Flag indicating whether to use the Chromium cache (if `false`), or the server cache (if `true`) when refreshing the web page. Defaults to `false`.
              */
-            refresh(ignoreCache: boolean): Promise<IOConnectWindow>;
+            refresh(ignoreCache?: boolean): Promise<IOConnectWindow>;
 
             /**
              * Downloads a file.
@@ -5961,13 +5967,13 @@ export declare namespace IOConnectDesktop {
              * Pinned tab windows don't have a "Close"  button preventing the user from closing them. Available only for tab windows in web groups.
              * @since io.Connect Desktop 9.5
              */
-            pin(): Promise<void>;
+            pin(): Promise<IOConnectWindow>;
 
             /**
              * Unpins the tab of the current window. The previously pinned tab reverts to a normal tab window containing a "Close" button. Available only for tab windows in web groups.
              * @since io.Connect Desktop 9.5
              */
-            unpin(): Promise<void>;
+            unpin(): Promise<IOConnectWindow>;
 
             /**
              * Executes code in the context of the io.Connect Window.
@@ -6080,16 +6086,18 @@ export declare namespace IOConnectDesktop {
         export interface API {
             /**
              * Subscribes for data updates of the current Channel. Persisted after a Channel change. Returns an unsubscribe function.
-             * @param callback Callback function to handle the received data.
+             * @param callback Callback function for handling the received data. The callback receives as arguments the updated Channel data, the current Channel context and the ID of the updating app instance.
+             * @param options Settings for subscribing to an FDC3 context published in the io.Connect Channel. *Available since io.Connect Desktop 9.6.*
              */
-            subscribe(callback: (data: any, context: ChannelContext, updaterId: string) => void): () => void;
+            subscribe(callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options): () => void;
 
             /**
-             * Subscribes for data updates of a specified Channel. Returns a `Promise` that resolves with an unsubscribe function.
-             * @param name The Channel to track.
-             * @param callback Callback function to handle the received data.
+             * Subscribes for data updates of a specified Channel. Resolves with an unsubscribe function.
+             * @param name The Channel to which to subscribe.
+             * @param callback Callback function for handling the received data. The callback receives as arguments the updated Channel data, the current Channel context and the ID of the updating app instance.
+             * @param options Settings for subscribing to an FDC3 context published in the io.Connect Channel. *Available since io.Connect Desktop 9.6.*
              */
-            subscribeFor(name: string, callback: (data: any, context: ChannelContext, updaterId: string) => void): Promise<() => void>;
+            subscribeFor(name: string, callback: (data: any, context: ChannelContext, updaterId: string) => void, options?: FDC3Options): Promise<() => void>;
 
             /**
              * Updates the context of the current or a specified Channel.
@@ -6125,13 +6133,15 @@ export declare namespace IOConnectDesktop {
             /**
              * Retrieves the context of a specified Channel.
              * @param name The name of the Channel whose context to retrieve.
+             * @param options Settings for retrieving an FDC3 context published in the io.Connect Channel. *Available since io.Connect Desktop 9.6.*
              */
-            get(name: string): Promise<ChannelContext>;
+            get(name: string, options?: FDC3Options): Promise<ChannelContext>;
 
             /**
              * Retrieves the context of the current Channel.
+             * @param options Settings for retrieving an FDC3 context published in the io.Connect Channel. *Available since io.Connect Desktop 9.6.*
              */
-            getMy(): Promise<ChannelContext>;
+            getMy(options?: FDC3Options): Promise<ChannelContext>;
 
             /**
              * Joins a new Channel by name. Leaves the current Channel.
@@ -6215,6 +6225,17 @@ export declare namespace IOConnectDesktop {
             onChanged(callback: (channel: string) => void): () => void;
         }
 
+        /**
+         * Settings for retrieving and subscribing for FDC3 contexts published in an io.Connect Channel.
+         * @since io.Connect Desktop 9.6
+         */
+        export interface FDC3Options {
+            /**
+             * Type of the FDC3 context to retrieve or to which to subscribe.
+             */
+            contextType?: string;
+        }
+
         /**
          * Describes an io.Connect Window that can use Channels.
          */
@@ -6433,6 +6454,20 @@ export declare namespace IOConnectDesktop {
              */
             addIntentListener(intent: string | AddIntentListenerRequest, handler: (context: IntentContext) => any): { unsubscribe: UnsubscribeFunction };
 
+            /**
+             * Notifies when a handler for an Intent is added. Returns an unsubscribe function.
+             * @param callback Callback function for handling the event. Receives an object describing the added Intent handler as an argument.
+             * @since io.Connect Desktop 9.6
+             */
+            onHandlerAdded(callback: (handler: IOConnectDesktop.Intents.IntentHandler) => void, intentName: string): UnsubscribeFunction;
+
+            /**
+             * Notifies when a handler for an Intent is removed. Returns an unsubscribe function.
+             * @param callback Callback function for handling the event. Receives an object describing the removed Intent handler as an argument.
+             * @since io.Connect Desktop 9.6
+             */
+            onHandlerRemoved(callback: (handler: IOConnectDesktop.Intents.IntentHandler)=> void, intentName: string): UnsubscribeFunction;
+
             /**
              * Registers an Intent handler. If your app is already registered as an Intent handler through its configuration,
              * use this method to supply a handler for the specified Intent. Otherwise, you can use it to register your app as an Intent handler
@@ -7014,6 +7049,14 @@ export declare namespace IOConnectDesktop {
              */
             snoozeMany(notifications: string[], duration: number): Promise<void>;
 
+            /**
+             * Imports a list of notifications into the platform. Only imported notifications with state `"Active"` will be shown as notification toasts.
+             * All imported notifications will be available in the Notification Panel. An event for raising a notification will be triggered for all imported notifications.
+             * @param notificationOptions List of objects each describing a notification to import. The notification options for importing notifications are identical to the ones for raising a notification.
+             * @since io.Connect Desktop 9.6
+             */
+            import(notificationOptions: IOConnectNotificationOptions[]): Promise<IOConnectDesktop.Notifications.NotificationData[]>;
+
             /**
              * Notifies when a new notification is raised.
              * @param callback Callback function for handling the event.
@@ -7095,6 +7138,12 @@ export declare namespace IOConnectDesktop {
              * Array of names of apps not allowed to raise notifications.
              */
             blocked?: string[];
+
+            /**
+             * Array of names of apps that are currently muted.
+             * @since io.Connect Desktop 9.6
+             */
+            muted?: string[];
         }
 
         /**
@@ -7382,6 +7431,20 @@ export declare namespace IOConnectDesktop {
              * Settings for invoking an Interop method when the notification action is clicked.
              */
             interop?: InteropActionSettings;
+
+            /**
+             * Unique ID for the notification action. This ID can be used in the `displayPath` property of another notification action to determine the position of the latter within the notification action menu.
+             * @since io.Connect Desktop 9.6
+             */
+            displayId?: string;
+
+            /**
+             * List of `displayId` values or titles of other notification actions describing the path within the notification action menu where the current notification action will be placed (e.g., `[ "main-action-id", "My Nested Action" ]`).
+             * The display ID takes precedence over the title when the framework searches for the respective item. If the provided display ID or title doesn't exist, an empty notification action will be created
+             * (the action will have a dropdown menu that will contain other actions, but when the user clicks on the action itself, nothing will happen).
+             * @since io.Connect Desktop 9.6
+             */
+            displayPath?: string[];
         }
 
         /**
@@ -7449,6 +7512,13 @@ export declare namespace IOConnectDesktop {
              * Describes the placement settings for the Notification Panel and the notification toasts.
              */
             placement?: NotificationPlacement;
+
+            /**
+             * If `true`, when the user clicks on the body of a notification in the Notification Panel, the notification will be removed from the list.
+             * Set to `false` if you want users to be able to click on the notification body (e.g., to copy text) without the notification disappearing from the Notification Panel.
+             * @since io.Connect Desktop 9.6
+             */
+            closeNotificationOnClick?: boolean;
         }
 
 
@@ -7877,4 +7947,132 @@ export declare namespace IOConnectDesktop {
             value: string;
         }
     }
+
+    /**
+     * @intro
+     * @since io.Connect Desktop 9.6
+     * The Interception API enables apps to register interception handlers with which to modify the low-level platform operations.
+     * Interception handlers can be executed before and/or after the default implementations of the platform operations,
+     * and the execution of the default implementation for a platform operation can be prevented entirely.
+     * This allows for finer control over the platform operations.
+     * It's possible to register only a single interception handler per platform operation within an API domain.
+     *
+     * For an app to be able to register interception handlers, interception must be enabled in the system configuration of **io.Connect Desktop**.
+     *
+     * *Available since io.Connect Desktop 9.6.*
+     */
+    export namespace Interception {
+        /**
+         * Interception API.
+         * @since io.Connect Desktop 9.6
+         */
+        export interface API {
+            /**
+             * Registers an interception handler. It's possible to register only a single interception handler per platform operation within an API domain.
+             * @param config Object containing the interception handler to register and settings describing the platform operations to intercept.
+             */
+            register(config: InterceptionRegistrationConfig): Promise<void>;
+            /**
+             * Unregisters all interception handlers for the specified platform operations.
+             * @param config Object specifying the platform operations which to stop intercepting.
+             */
+            unregister(config: InterceptionUnregistrationConfig): Promise<void>;
+        }
+
+        /**
+         * Settings for registering an interception handler for the targeted platform operations.
+         */
+        export interface InterceptionRegistrationConfig {
+            /**
+             * Method implementation to be registered as a handler for the specified platform operations.
+             * It's possible to register only a single interception handler per platform operation within an API domain.
+             * @param message Object describing the intercepted platform operation.
+             */
+            handler: (message: InterceptionMessage) => Promise<InterceptionResponse | void>;
+            /**
+             * List of objects each describing a platform operation to intercept.
+             */
+            interceptions: Interception[];
+        }
+
+        /**
+         * Settings for unregistering the interception handlers for the targeted platform operations.
+         */
+        export interface InterceptionUnregistrationConfig {
+            /**
+             * List of objects each describing a platform operation which to stop intercepting.
+             */
+            interceptions: Interception[];
+        }
+
+        /**
+         * Describes an intercepted platform operation.
+         */
+        export interface InterceptionMessage {
+            /**
+             * The io.Connect API domain in which the platform operation has been intercepted.
+             */
+            domain: string;
+            /**
+             * The io.Connect platform operation that has been intercepted.
+             */
+            operation: string;
+            /**
+             * ID of the app that has invoked the platform operation. Can be used for tracking purposes.
+             */
+            callerId: string;
+            /**
+             * Specifies whether the platform operation has been intercepted before or after the execution of its default implementation.
+             */
+            phase: "before" | "after";
+            /**
+             * In the `"before"` phase, this property will contain the arguments with which the calling app has invoked the intercepted operation.
+             * In the `"after"` phase, this property will contain the result returned from executing the default platform implementation of the intercepted operation
+             * (or the result from the decorated operation, if the interception handler was invoked also in the `"before"` phase to modify the default operation).
+             */
+            operationArgs?: any[];
+        }
+
+        /**
+         * Describes the response returned by an interception handler.
+         * If the platform operation has been intercepted before the execution of its default implementation and the interception handler returns `undefined` or an empty object,
+         * the platform will proceed with the execution of the default operation implementation.
+         * If the platform operation has been intercepted after the execution of its default implementation and the interception handler returns `undefined` or an empty object,
+         * the platform will return the already calculated result.
+         */
+        export interface InterceptionResponse {
+            /**
+             * Arguments with which to proceed the execution of the intercepted platform operation.
+             * This property is taken into account only when the platform operation is intercepted before the execution of its default implementation.
+             */
+            operationArgs?: any[];
+            /**
+             * Result from the platform operation. Use this property to return a result from your interception handler
+             * when the platform operation has been intercepted after the execution of its default implementation.
+             * If the platform operation has been intercepted before the execution of its default implementation and this property is set,
+             * the execution of the default implementation will be prevented and the platform will return the specified result.
+             */
+            operationResult?: any;
+        }
+
+        /**
+         * Describes a platform operation to intercept and provides settings for its interception.
+         */
+        export interface Interception {
+            /**
+             * io.Connect API domain of the platform operation.
+             */
+            domain: string | "all";
+            /**
+             * Name of the io.Connect platform operation within the specified io.Connect API domain.
+             * Set to `"all"` to intercept all operations within the domain.
+             */
+            operation: string | "all";
+            /**
+             * Specifies whether to intercept the platform operation before or after the execution of its default implementation.
+             * Set to `"all"` to intercept the platform operation both before and after the execution of its default implementation.
+             */
+            phase?: "before" | "after" | "all";
+        }
+    }
 }