@interopio/desktop 6.2.2 → 6.4.0

package/changelog.md

@@ -1,3 +1,16 @@
+6.4.0
+- feat: channels - add support for channel restrictions
+- chore: update types
+- chore: update schemas to 9.3.0 (was 9.2.0)
+6.3.1
+- chore: update core to 6.2.1 (was 6.1.0)
+6.3.0
+- feat: notifications - add support for snooze
+- feat: windows - add showPopup method to the group object
+- feat: windows - two new methods - create and close group
+- feat: appManager - introduce new method - instance.startedBy
+- feat: channels - introduce new methods - restrict, restrictAll, getRestrictions
+- chore: prefs - fix typings - getAll
 6.2.2
 - feat: notifications - click method now accepts a third optional argument - options
 6.2.1

package/desktop.d.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-shadow */
-import { ApplicationConfig } from "@glue42/schemas";
+import { ApplicationConfig } from "@interopio/schemas";
 import { IOConnectCore } from "@interopio/core";
 import { IOConnectWorkspaces } from "@interopio/workspaces-api";
 import { UnsubscribeFunction } from "callback-registry";
@@ -1070,7 +1070,7 @@ export declare namespace IOConnectDesktop {
              * Retrieves an app by name.
              * @param name Name of the desired app.
              */
-            application(name: string): Application;
+            application(name: string): Application | undefined;
 
             /**
              * Retrieves a collection of the available apps.
@@ -1513,6 +1513,12 @@ export declare namespace IOConnectDesktop {
              */
             getWindow(): Promise<Windows.IOConnectWindow>;
 
+            /**
+             * Retrieves information about how the current app instance was started, and about the identity of the initiator.
+             * @since io.Connect Desktop 9.3
+             */
+            startedBy(): Promise<StartedByInfo>;
+
             /**
              * Notifies when the Interop library is ready to be used.
              * @param callback Callback function for handling the event.
@@ -1533,6 +1539,26 @@ export declare namespace IOConnectDesktop {
             onStopped(callback: (instance: Instance) => any): UnsubscribeFunction;
         }
 
+        /**
+         * Describes how the current app instance was started and provides details about the app that started it.
+         */
+        export interface StartedByInfo {
+            /**
+             * Indicates how the current app instance was started. Apps can be started by other apps, by a raised Intent, or can be auto started by the system.
+             */
+            startedBy: "application" | "intent" | "autoStart";
+
+            /**
+             * Name of the app that started the current app instance.
+             */
+            applicationName: string;
+
+            /**
+             * ID of the app instance that started the current app instance.
+             */
+            instanceID: string;
+        }
+
         /**
          * @ignore
          */
@@ -1588,6 +1614,16 @@ export declare namespace IOConnectDesktop {
              * @default false
              */
             ignoreSavedLayout?: boolean;
+
+            /**
+             * Key/value pairs that will be merged with the `process.env` object when spawning a new process for an executable app from the Node.js environment.
+             */
+            env?: Record<string, (string)>;
+
+            /**
+             * Optional parameters that will be passed to the executable app that is to be started. The value will be used as is and no validation will be performed on it.
+             */
+            parameters?: string;
         }
 
         /**
@@ -2626,16 +2662,23 @@ export declare namespace IOConnectDesktop {
             borderColor?: string;
 
             /**
-             * Name of the Channel which the window will join.
+             * Deprecated. Use `channelSelector` instead. Name of the Channel which the window will join.
+             * @ignore
              */
             channelId?: string;
 
             /**
-             * If `true`, Channels will be enabled for the window and it will show the Channel Selector.
+             * Deprecated. Use `channelSelector` instead. If `true`, Channels will be enabled for the window and it will show the Channel Selector.
              * @default false
+             * @ignore
              */
             allowChannels?: boolean;
 
+            /**
+             * Settings for the Channel Selector UI.
+             */
+            channelSelector?: ChannelSelector;
+
             /**
              * Defines the height of the window when collapsed.
              * @default -1
@@ -2926,6 +2969,36 @@ export declare namespace IOConnectDesktop {
             preloadScripts?: string[];
         }
 
+        /**
+         * Settings for the Channel Selector UI.
+         */
+        export interface ChannelSelector {
+            /**
+             * If `true`, will allow showing the Channel Selector.
+             * @default false
+             */
+            enabled?: boolean;
+
+            /**
+             * Type of the Channel Selector to show on the io.Connect Windows. A single Channel Selector (default) allows the window to join a single Channel
+             * to which it can subscribe and publish data unrestrictedly. A directional single Channel Selector allows the window to join a single Channel,
+             * but also enables the user to restrict the window from publishing or from subscribing to the current Channel.
+             * @default "single"
+             */
+            type?: "single" | "directionalSingle";
+
+            /**
+             * Name of the Channel to which the window will be joined by default when it's started.
+             */
+            channelId: string;
+
+            /**
+             * If `true`, the Channel Selector will be visible, but the user won't be able to switch between Channels from it.
+             * @default false
+             */
+            readOnly: boolean;
+        }
+
         /**
          * Options for loading a window URL.
          */
@@ -2946,8 +3019,7 @@ export declare namespace IOConnectDesktop {
             extraHeaders?: string;
 
             /**
-             * Data for the POST request. Either an array of `UploadFile` objects describing the location and other properties of the file to upload,
-             * or an array of `UploadBase64Data` objects containing data encoded as a Base64 string.
+             * Data for the POST request. The list can contain both `UploadFile` objects (describing the location and other properties of the file to upload) and `UploadBase64Data` objects (containing data encoded as a Base64 string).
              */
             postData?: ((UploadBase64Data) | (UploadFile))[];
 
@@ -2955,6 +3027,11 @@ export declare namespace IOConnectDesktop {
              * Base URL for files loaded by a data URL. Must end with a trailing path separator. This property is necessary only when the loaded URL is a data URL.
              */
             baseURLForDataURL?: string;
+
+            /**
+             * Query string that will be appended to the URL when starting the app. If the string doesn't start with a `?`, one will be prepended to it. Note that the query string must be URL encoded.
+             */
+            queryString?: string;
         }
 
         /**
@@ -4133,6 +4210,66 @@ export declare namespace IOConnectDesktop {
             showDialog?: boolean
         }
 
+        /**
+         * Options for creating window groups.
+         */
+        export interface CreateGroupsOptions {
+            /**
+             * List of window groups to be created.
+             */
+            groups: GroupDefinition[];
+            /**
+             * Context for the created window groups.
+             */
+            context?: unknown;
+        }
+
+        /**
+         * Describes a window group that will be created.
+         */
+        export interface GroupDefinition {
+            /**
+             * Title for the created window group.
+             */
+            title?: string;
+            /**
+             * State for the created window group.
+             */
+            state?: string;
+            /**
+             * List of window frames that will be part of the created window group.
+             */
+            frames: FrameDefinition[];
+        }
+
+        /**
+         * Describes a window frame that will be part of a created window group.
+         */
+        export interface FrameDefinition {
+            /**
+             * Bounds for the window frame.
+             */
+            bounds: Bounds;
+            /**
+             * Mode for the window frame.
+             */
+            mode?: WindowMode;
+            /**
+             * List of objects containing the names of the apps to be started and loaded in the window frames of the created window group, as well as additional app settings.
+             */
+            applications: CreateGroupApplicationOptions[];
+        }
+
+        /**
+         * Options for the app that will be started and loaded in a window frame of a created window group.
+         */
+        export interface CreateGroupApplicationOptions extends IOConnectDesktop.Windows.WindowSettings {
+            /**
+             * App name as specified in its definition.
+             */
+            name: string;
+        }
+
         /**
          * API for managing window groups.
          */
@@ -4142,6 +4279,21 @@ export declare namespace IOConnectDesktop {
              */
             my: Group;
 
+            /**
+             * Creates window groups.
+             * @param options Options for creating window groups.
+             * @since io.Connect Desktop 9.3
+             */
+            create(options: CreateGroupsOptions): Promise<Group[]>;
+
+            /**
+             * Closes a window group.
+             * @param group The `Group` object or the ID of the window group to be closed.
+             * @param options Options for closing the group that can be used to prevent closing the group and control whether to show a confirmation dialog before closing it.
+             * @since io.Connect Desktop 9.3
+             */
+            close(group: Group | string, options?: CloseOptions): Promise<void>;
+
             /**
              * Lists all window groups.
              * @param success Callback function for handling the successfully returned result.
@@ -4162,6 +4314,12 @@ export declare namespace IOConnectDesktop {
              */
             waitForGroup(groupId: string): Promise<IOConnectDesktop.Windows.Group>;
 
+            /**
+             * Retrieves the current window group.
+             * @since io.Connect Desktop 9.3
+             */
+            getMyGroup(): Promise<IOConnectDesktop.Windows.Group>;
+
             /**
              * Hibernates a window group.
              * @param groupId ID of the window group to hibernate.
@@ -4254,6 +4412,11 @@ export declare namespace IOConnectDesktop {
              */
             message: string;
 
+            /**
+             * Title for the message that will be displayed in the dialog.
+             */
+            messageTitle: string;
+
             /**
              * If `true`, the user will be able to move the dialog.
              * @default true
@@ -4267,7 +4430,7 @@ export declare namespace IOConnectDesktop {
             transparent?: boolean;
 
             /**
-             * Title for the dialog to show.
+             * Title for the dialog that will be displayed in the dialog header.
              */
             title?: string;
 
@@ -4445,7 +4608,7 @@ export declare namespace IOConnectDesktop {
              * @param window Window ID or a window object by which to find a window in the group.
              * @param success Callback function for handling the successfully returned result.
              */
-            find(window: string | IOConnectWindow, success?: (window: IOConnectWindow) => void): IOConnectWindow;
+            find(window: string | IOConnectWindow, success?: (window: IOConnectWindow) => void): IOConnectWindow | undefined;
 
             /**
              * Restores a window group.
@@ -4492,7 +4655,6 @@ export declare namespace IOConnectDesktop {
              */
             capture(options?: CaptureOptions): Promise<string>;
 
-
             /**
              * Shows a previously hidden window group.
              * @param activate Flag indicating whether to activate the group and focus the last focused app window.
@@ -4504,6 +4666,20 @@ export declare namespace IOConnectDesktop {
              */
             hide(): Promise<void>;
 
+            /**
+             * Closes the window group.
+             * @param options Options for closing the group that can be used to prevent closing the group and control whether to show a confirmation dialog before closing it.
+             * @since io.Connect Desktop 9.3
+             */
+            close(options?: CloseOptions): Promise<void>;
+
+            /**
+             * Creates a popup window.
+             * @param config Options for creating a popup window.
+             * @since io.Connect Desktop 9.3
+             */
+            showPopup(config: PopupOptions): Promise<void>;
+
             /**
              * Notifies when the visibility of the window group header is changed.
              * @param callback Callback function for handling the event.
@@ -4548,7 +4724,7 @@ export declare namespace IOConnectDesktop {
             /**
              * Retrieves the current window.
              */
-            my(): IOConnectWindow;
+            my(): IOConnectWindow | undefined;
 
             /**
              * Opens a new io.Connect Window.
@@ -4566,7 +4742,7 @@ export declare namespace IOConnectDesktop {
              * @param success Callback function for handling the successfully returned result.
              * @param error Callback function for handling errors.
              */
-            find(name: string, success?: (window: IOConnectWindow) => void, error?: (error: string) => void): IOConnectWindow;
+            find(name: string, success?: (window: IOConnectWindow) => void, error?: (error: string) => void): IOConnectWindow | undefined;
 
             /**
              * Finds a window by ID.
@@ -4574,7 +4750,7 @@ export declare namespace IOConnectDesktop {
              * @param success Callback function for handling the successfully returned result.
              * @param error Callback function for handling errors.
              */
-            findById(id: string, success?: (window: IOConnectWindow) => void, error?: (error: string) => void): IOConnectWindow;
+            findById(id: string, success?: (window: IOConnectWindow) => void, error?: (error: string) => void): IOConnectWindow | undefined;
 
             /**
              * Lists all windows.
@@ -5841,6 +6017,27 @@ export declare namespace IOConnectDesktop {
              */
             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 Desktop 9.3
+             */
+            restrict(restrictions: ChannelRestrictions): Promise<void>;
+
+            /**
+             * 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 Desktop 9.3
+             */
+            restrictAll(restrictions: RestrictionsConfig): 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 Desktop 9.3
+             */
+            getRestrictions(windowId?: string): Promise<Restrictions>;
+
             /**
              * Notifies when a Channel is changed.
              * @param callback Callback function for handling the event.
@@ -5914,6 +6111,44 @@ export declare namespace IOConnectDesktop {
              */
             data: any;
         }
+
+        /**
+         * All restrictions applied to a window for publishing or subscribing to Channels.
+         */
+        export interface Restrictions {
+            /**
+             * List of restrictions for publishing or subscribing to Channels.
+             */
+            channels: ChannelRestrictions[];
+        }
+
+        /**
+         * Restrictions applied to a window for publishing or subscribing to a specific Channel.
+         */
+        export interface ChannelRestrictions extends RestrictionsConfig {
+            /**
+             * Name of the Channel for which the restrictions apply.
+             */
+            name: string;
+        }
+
+        /**
+         * Restrictions applied to a window for publishing or subscribing to all Channels.
+         */
+        export interface RestrictionsConfig {
+            /**
+             * If `true`, the window will be able to subscribe to the specified Channel.
+             */
+            read: boolean;
+            /**
+             * If `true`, the window will be able to publish to the specified Channel.
+             */
+            write: boolean;
+            /**
+             * ID of the window for which apply the restrictions for publishing or subscribing to Channels.
+             */
+            windowId?: string;
+        }
     }
 
     /**
@@ -6496,6 +6731,13 @@ export declare namespace IOConnectDesktop {
              */
             updateData(id: string, data: unknown): Promise<void>;
 
+            /**
+             * Snoozes a notification.
+             * @param id ID of the notification to snooze.
+             * @param duration Interval in milliseconds for which to snooze the notification.
+             */
+            snooze(id: string, duration: number): Promise<void>;
+
             /**
              * Notifies when a new notification is raised.
              * @param callback Callback function for handling the event.
@@ -6621,15 +6863,16 @@ export declare namespace IOConnectDesktop {
         }
 
         /**
-         * Notification state.
-         * - `"Active"` - based on configuration, the notification is either visible as a toast, or is raised only in the Notification Panel, but the user hasn't seen it yet.
-         * When the toast is hidden, the user clicks on the toast, or sees the notification in the Notification Panel, the state will change;
-         * - `"Acknowledged"` - the user has seen the notification in the Notification Panel;
-         * - `"Closed"` - the notification has either been closed from its "Close" button, or the user has clicked on it or on an action in it;
-         * - `"Stale"` - the time specified in `toastExpiry` has elapsed;
+         * 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" | "Closed" | "Stale";
-
+        export type State = "Active" | "Acknowledged" | "Seen" | "Closed" | "Stale" | "Snoozed" | "Processing";
         /**
          * Options for the clicked notification.
          */
@@ -7068,7 +7311,7 @@ export declare namespace IOConnectDesktop {
             /**
              * Retrieves all preferences stored for the current user.
              */
-            getAll(): Promise<AppPreferences[]>;
+            getAll(): Promise<{ all: AppPreferences[]; }>;
 
             /**
              * Removes all preferences stored for the current user.
@@ -7106,7 +7349,7 @@ export declare namespace IOConnectDesktop {
             /**
              * Timestamp of the last update of the user preferences.
              */
-            lastUpdate: string;
+            lastUpdate?: string;
         }
     }