@todesktop/shared 7.190.0 → 7.191.0

package/src/desktopify2.ts

@@ -1,24 +1,24 @@
-import { ISwitchableValue } from './toDesktop';
 import {
-  MenuItemConstructorOptions,
   BrowserWindowConstructorOptions,
-  WebPreferences,
-  NotificationConstructorOptions,
+  MenuItemConstructorOptions,
   MessageBoxOptions,
+  NotificationConstructorOptions,
+  WebPreferences,
 } from '@todesktop/client-electron-types';
 import { BaseApp } from './base';
 import { CustomPlugin, DesktopAppPlugin } from './plugin';
+import { ISwitchableValue } from './toDesktop';
 import { ValidTranslationKeys, ValidTranslationLanguages } from './translation';
 
 interface BaseAssetDetails {
-  /**
-   * Remote URL where the asset can be downloaded
-   */
-  url: string;
   /**
    * Local path where the asset is/should be stored. This path is relative to the app directory
    */
   relativeLocalPath: string;
+  /**
+   * Remote URL where the asset can be downloaded
+   */
+  url: string;
 }
 
 export interface AppIconAssetDetails extends BaseAssetDetails {
@@ -40,26 +40,26 @@ export interface FileAssetDetails extends BaseAssetDetails {
 
 export type AssetDetails =
   | AppIconAssetDetails
+  | FileAssetDetails
   | MenuIconAssetDetails
-  | TrayMenubarIconAssetDetails
-  | FileAssetDetails;
+  | TrayMenubarIconAssetDetails;
 
 /**
  * Custom ToDesktop Roles for Application & Tray Menus
  */
 type todesktopRoles =
-  | 'todesktop:launch-at-startup'
   | 'todesktop:check-for-updates'
-  | 'todesktop:quit'
-  | 'todesktop:quit-completely'
-  | 'todesktop:new-window'
-  | 'todesktop:new-tab'
   | 'todesktop:check-for-updates'
-  | 'todesktop:history-home'
+  | 'todesktop:hide-window'
   | 'todesktop:history-back'
   | 'todesktop:history-forward'
+  | 'todesktop:history-home'
+  | 'todesktop:launch-at-startup'
+  | 'todesktop:new-tab'
+  | 'todesktop:new-window'
+  | 'todesktop:quit-completely'
+  | 'todesktop:quit'
   | 'todesktop:show-window'
-  | 'todesktop:hide-window'
   | 'todesktop:toggle-window'
   | 'todesktop:toggle-window0'
   | 'todesktop:toggle-window1'
@@ -69,19 +69,19 @@ type todesktopRoles =
 
 export interface DesktopifyMenuItemConstructorOptions
   extends Omit<MenuItemConstructorOptions, 'role' | 'submenu'> {
-  platforms?: NodeJS.Platform[];
-  submenu?: DesktopifyMenuItemConstructorOptions[];
-  role?: MenuItemConstructorOptions['role'] | todesktopRoles;
-  useSystemLabel?: boolean;
-  event?: string;
-  targetWindowId?: string;
+  // 'none' is kept for legacy reasons
+  acceleratorBehaviour?: 'custom' | 'default' | 'explicit-none' | 'none';
   actionType?: 'jsEvent' | 'role';
-  iconUrl?: string;
   bundledIcon?: string;
+  event?: string;
   iconAssetDetails?: MenuIconAssetDetails;
+  iconUrl?: string;
+  platforms?: NodeJS.Platform[];
+  role?: MenuItemConstructorOptions['role'] | todesktopRoles;
+  submenu?: DesktopifyMenuItemConstructorOptions[];
+  targetWindowId?: string;
+  useSystemLabel?: boolean;
   useTemplateImage?: boolean;
-  // 'none' is kept for legacy reasons
-  acceleratorBehaviour?: 'none' | 'explicit-none' | 'default' | 'custom';
 }
 
 /**
@@ -100,8 +100,8 @@ export type DesktopifyAppTrayToggleWindowAction = {
  * @param menu - The menu to show when action triggered
  */
 export type DesktopifyAppTrayToggleMenuAction = {
-  role: 'toggleMenu';
   menu: DesktopifyMenuItemConstructorOptions[];
+  role: 'toggleMenu';
 };
 
 /**
@@ -110,8 +110,8 @@ export type DesktopifyAppTrayToggleMenuAction = {
  * @param event - The name of the event
  */
 export type DesktopifyAppTrayJSEventAction = {
-  role: 'jsEvent';
   event: string;
+  role: 'jsEvent';
 };
 
 /**
@@ -122,28 +122,28 @@ export type DesktopifyAppTrayNoAction = {
 };
 
 export type DesktopifyAppTrayAction =
-  | DesktopifyAppTrayToggleMenuAction
-  | DesktopifyAppTrayToggleWindowAction
   | DesktopifyAppTrayJSEventAction
-  | DesktopifyAppTrayNoAction;
+  | DesktopifyAppTrayNoAction
+  | DesktopifyAppTrayToggleMenuAction
+  | DesktopifyAppTrayToggleWindowAction;
 
 export interface DesktopifyAppTray {
-  id: string;
-  objectId?: string;
+  bundledIcon?: string;
   icon?: string;
-  useSeparateIcons?: boolean;
-  windowsIcon?: string;
-  windowsIconAssetDetails?: TrayMenubarIconAssetDetails;
-  macOSIcon?: string;
-  macOSIconAssetDetails?: TrayMenubarIconAssetDetails;
+  iconAssetDetails?: TrayMenubarIconAssetDetails;
+  id: string;
+  leftClick: DesktopifyAppTrayAction;
   linuxIcon?: string;
   linuxIconAssetDetails?: TrayMenubarIconAssetDetails;
-  bundledIcon?: string;
-  iconAssetDetails?: TrayMenubarIconAssetDetails;
+  macOSIcon?: string;
+  macOSIconAssetDetails?: TrayMenubarIconAssetDetails;
+  objectId?: string;
+  rightClick: DesktopifyAppTrayAction;
   swapClickHandlers?: boolean;
+  useSeparateIcons?: boolean;
   useTemplateImage?: boolean;
-  rightClick: DesktopifyAppTrayAction;
-  leftClick: DesktopifyAppTrayAction;
+  windowsIcon?: string;
+  windowsIconAssetDetails?: TrayMenubarIconAssetDetails;
 }
 
 export type DesktopifyAppMenu = DesktopifyMenuItemConstructorOptions;
@@ -242,47 +242,10 @@ export type whitelistedWebPreferencesOptions =
  * Interface for ToDesktop App Windows
  */
 export interface DesktopifyAppWindow {
-  /**
-   * A unique window id
-   */
-  id: string;
-  /**
-   * A *mutable* window object id
-   */
-  objectId?: string;
   /**
    * The window's background type
    */
-  backgroundType?: 'normal' | 'vibrant' | 'transparent' | 'color';
-  /**
-   * The window name. Only visible to developer
-   */
-  name: string;
-  /**
-   * The window's url
-   */
-  url: string;
-  /**
-   * Whether this is the main window. The main window handles deeplinks
-   */
-  isMain: boolean;
-  /**
-   * The type of window
-   */
-  type: 'menubar' | 'app' | 'panel' | 'desktop';
-  /**
-   * Keyboard shortcut to toggle window visibility
-   */
-  toggleVisibilityKeyboardShortcut?: string;
-  /**
-   * By default ToDesktop remembers window width & height between sessions.
-   * Setting to `true` disables behaviour
-   */
-  shouldResetDimensions?: boolean;
-  /**
-   * If `true` prevents the native window's title from changing when the document title changes
-   */
-  isTitleStatic?: boolean;
+  backgroundType?: 'color' | 'normal' | 'transparent' | 'vibrant';
   /**
    * Disables default rightClick menu
    */
@@ -292,93 +255,130 @@ export interface DesktopifyAppWindow {
    */
   disableContextMenuOpenInWindow: boolean;
   /**
-   * Allows user to `Cmd+F` or `Edit>Find` to search for text on page
+   * Don't allow tabs in window (macOS only)
    */
-  isFindInPageEnabled?: boolean;
+  disableTabs: boolean;
+  /**
+   * The path to the file to load if `shouldUseFileInsteadOfUrl` is `true`.
+   */
+  file?: string;
   /**
    * Configuration options for find in page
    */
   findInPageOptions?: {
     horizontalPlacement?: {
-      type: 'left' | 'default' | 'right';
-      left: FindInPagePlacement;
       default: FindInPagePlacement;
+      left: FindInPagePlacement;
       right: FindInPagePlacement;
+      type: 'default' | 'left' | 'right';
     };
     verticalPlacement?: {
-      type: 'top' | 'default' | 'bottom';
-      top: FindInPagePlacement;
-      default: FindInPagePlacement;
       bottom: FindInPagePlacement;
+      default: FindInPagePlacement;
+      top: FindInPagePlacement;
+      type: 'bottom' | 'default' | 'top';
     };
   };
   /**
-   * Inital visibility of window
+   * Does the window have a maximum height. Default is `false`
    */
-  visibility: 'visible' | 'hidden' | 'show-when-contents-loaded';
+  hasMaxHeight: boolean;
   /**
-   * MacOS option for whether the window should be visible on all workspaces
+   * Does the window have a maximum width. Default is `false`
    */
-  visibleOnAllWorkspaces: boolean;
+  hasMaxWidth: boolean;
+  /**
+   * Does the window have a minimum height. Default is `false`
+   */
+  hasMinHeight: boolean;
   /**
    * Does the window have a minimum width. Default is `false`
    */
   hasMinWidth: boolean;
   /**
-   * Does the window have a maximum width. Default is `false`
+   * A unique window id
    */
-  hasMaxWidth: boolean;
+  id: string;
   /**
-   * Does the window have a minimum height. Default is `false`
+   * Allows user to `Cmd+F` or `Edit>Find` to search for text on page
    */
-  hasMinHeight: boolean;
+  isFindInPageEnabled?: boolean;
   /**
-   * Does the window have a maximum height. Default is `false`
+   * Whether this is the main window. The main window handles deeplinks
    */
-  hasMaxHeight: boolean;
+  isMain: boolean;
   /**
-   * Don't allow tabs in window (macOS only)
+   * If `true` prevents the native window's title from changing when the document title changes
    */
-  disableTabs: boolean;
+  isTitleStatic?: boolean;
+  /**
+   * The window name. Only visible to developer
+   */
+  name: string;
+  /**
+   * A *mutable* window object id
+   */
+  objectId?: string;
   /**
    * BrowserWindow Constructor Options
    */
-  options: Pick<
-    BrowserWindowConstructorOptions,
-    whitelistedBrowserWindowConstructorOptions
-  > & {
+  options: {
     /**
      * Settings of web page's features.
      */
     webPreferences?: Pick<WebPreferences, whitelistedWebPreferencesOptions>;
-  };
+  } & Pick<
+    BrowserWindowConstructorOptions,
+    whitelistedBrowserWindowConstructorOptions
+  >;
+  /**
+   * By default ToDesktop remembers window width & height between sessions.
+   * Setting to `true` disables behaviour
+   */
+  shouldResetDimensions?: boolean;
   /**
    * The window should load a file instead of a URL.
    * The file property (below) should also be set if the value is `true`.
    */
   shouldUseFileInsteadOfUrl?: boolean;
   /**
-   * The path to the file to load if `shouldUseFileInsteadOfUrl` is `true`.
+   * Keyboard shortcut to toggle window visibility
    */
-  file?: string;
+  toggleVisibilityKeyboardShortcut?: string;
+  /**
+   * The type of window
+   */
+  type: 'app' | 'desktop' | 'menubar' | 'panel';
+  /**
+   * The window's url
+   */
+  url: string;
+  /**
+   * Inital visibility of window
+   */
+  visibility: 'hidden' | 'show-when-contents-loaded' | 'visible';
+  /**
+   * MacOS option for whether the window should be visible on all workspaces
+   */
+  visibleOnAllWorkspaces: boolean;
 }
 // TODO: Look into hasMinHeight, etc
 
 export type AutoUpdateConfiguration = {
+  autoCheckIntervalMins: number;
   autoUpdater: boolean;
-  shouldAutoCheckOnLaunch: boolean;
   shouldAutoCheckInterval: boolean;
-  autoCheckIntervalMins: number;
+  shouldAutoCheckOnLaunch: boolean;
   updateReadyAction: {
     showInstallAndRestartPrompt: {
-      mode: 'always' | 'whenInForeground' | 'never';
-      options: Omit<MessageBoxOptions, 'buttons'> & {
+      mode: 'always' | 'never' | 'whenInForeground';
+      options: {
         installOnNextLaunchButton: string;
         restartAndInstallButton: string;
-      };
+      } & Omit<MessageBoxOptions, 'buttons'>;
     };
     showNotification: {
-      mode: 'always' | 'whenInBackground' | 'never';
+      mode: 'always' | 'never' | 'whenInBackground';
       options: Omit<NotificationConstructorOptions, 'actions'>;
     };
   };
@@ -394,67 +394,96 @@ export interface DesktopifyApp2<Plugin = DesktopAppPlugin> {
    */
   appModelId?: string;
   /**
-   * Configure auto updates
+   * Registers an app protocol. Format should be `{APP_PROTOCOL}://` e.g. `example://`
    */
-  autoUpdates: AutoUpdateConfiguration;
+  appProtocol: ISwitchableValue<string>;
 
   /**
-   * App identifier
+   * Sets strings to be used in the app UI. Currently only supports English
    */
-  id: string;
+  appStrings?: {
+    [key in ValidTranslationKeys]?: {
+      [lang in ValidTranslationLanguages]?: string;
+    };
+  };
   /**
-   * Last desktopify version that was used to update the app
+   * Sets whether the window menu bar should hide itself automatically.
+   * Once set the menu bar will only show when users press the single Alt key.
    */
-  lastUsedDesktopifyVersion?: string;
+  autoHideMenuBar?: boolean;
   /**
-   * Last todesktop builder version that was used to update the app
+   * Configure auto updates
    */
-  lastUsedBuilderVersion?: string;
+  autoUpdates: AutoUpdateConfiguration;
   /**
-   * The name of the app
+   * The locally-bundled app icon.
    */
-  name: string;
+  bundledIcon?: string;
   /**
-   * The app icon url
+   * Command line switches
+   * Learn more {@link https://www.electronjs.org/docs/api/command-line-switches}
+   * @example
+   * {
+   *  'remote-debugging-port': '8315'
+   * }
    */
-  icon?: string;
+  commandLineSwitches?: {
+    [key: string]: string;
+  };
   /**
-   * The locally-bundled app icon.
+   * The name of the company that the app belongs to
    */
-  bundledIcon?: string;
+  companyName?: string;
   /**
-   * Details concerning how the app icon should be handled across ToDesktop services
+   * URL that crash reports will be POSTed to
    */
-  iconAssetDetails?: AppIconAssetDetails;
+  crashReporter?: string;
   /**
-   * Instead of using one icon for every platform, use a separate icon for different platforms
+   * Metadata about plugins that were manually linked into the app
    */
-  useSeparateIcons?: boolean;
-  windowsIcon?: string;
-  windowsIconAssetDetails?: AppIconAssetDetails;
+  customPlugins?: CustomPlugin[];
+  /**
+   * Disable devTools on all app windows
+   */
+  disableDevTools: boolean;
+  /**
+   * Disable error reporting (Sentry)
+   */
+  disableErrorTracking?: boolean;
 
-  macOSIcon?: string;
-  macOSIconAssetDetails?: AppIconAssetDetails;
+  /**
+   * Enables NEW push notifications — uses `@cuj1559/electron-push-receiver`
+   */
+  enableNewPushNotifications?: boolean;
+  /**
+   * Enables push notifications — uses `electron-push-receiver`
+   */
+  enablePushNotifications?: boolean;
 
-  linuxIcon?: string;
-  linuxIconAssetDetails?: AppIconAssetDetails;
   /**
-   * The name of the company that the app belongs to
+   * File assets that get bundled with the app and are available offline
    */
-  companyName?: string;
+  fileAssetDetailsList?: FileAssetDetails[];
   /**
-   * Whether the app should minimize to tray when all windows are closed. Requires at least one tray.
+   * Opens `accounts.google.com/o/oauth` in user's default browswer not as internal url
    */
-  shouldMinimizeToTray?: boolean;
+  googleOAuthIsExternal?: boolean;
   /**
-   * This option is only available when `shouldMinimizeToTray` is `true`.
-   * Always display the dock icon while the app is open. Even if there are no windows open.
+   * The app icon url
    */
-  shouldAlwaysDisplayDockIcon?: boolean;
+  icon?: string;
   /**
-   * Only allow a single instance of this app to run
+   * Details concerning how the app icon should be handled across ToDesktop services
    */
-  singleInstance: boolean;
+  iconAssetDetails?: AppIconAssetDetails;
+  /**
+   * App identifier
+   */
+  id: string;
+  /**
+   * Disables the same-origin policy
+   */
+  insecure?: boolean;
   /**
    * Regex patterns for internal app urls
    */
@@ -465,29 +494,49 @@ export interface DesktopifyApp2<Plugin = DesktopAppPlugin> {
    */
   isNativeWindowOpenDisabled?: boolean;
   /**
-   * Specifys the app's user agent
+   * Whether the app is secure i.e. using valid code signing certificates.
+   * Note: This value is not persisted in firestore, and is instead written locally at build time.
+   * @default false
    */
-  userAgent: ISwitchableValue<string>;
+  isSecure?: boolean;
   /**
-   * Disable devTools on all app windows
+   * Last todesktop builder version that was used to update the app
    */
-  disableDevTools: boolean;
+  lastUsedBuilderVersion?: string;
   /**
-   * Registers an app protocol. Format should be `{APP_PROTOCOL}://` e.g. `example://`
+   * Last desktopify version that was used to update the app
    */
-  appProtocol: ISwitchableValue<string>;
+  lastUsedDesktopifyVersion?: string;
+  linuxIcon?: string;
+  linuxIconAssetDetails?: AppIconAssetDetails;
+  macOSIcon?: string;
+  macOSIconAssetDetails?: AppIconAssetDetails;
   /**
-   * Disables the same-origin policy
+   * The app's menus
    */
-  insecure?: boolean;
+  menus: DesktopifyAppMenu[];
   /**
-   * Opens `accounts.google.com/o/oauth` in user's default browswer not as internal url
+   * The name of the app
    */
-  googleOAuthIsExternal?: boolean;
+  name: string;
   /**
-   * Removes electron from userAgent
+   * Sets whether an offline screen will be displayed if the internet is disconnected
+   * on initial page load. The color of the re-connect button that is shown is customizable.
    */
-  shouldUseRealUserAgent?: boolean;
+  offlineScreen?: {
+    buttonBackgroundColor: string;
+    buttonTextColor: string;
+    enabled: boolean;
+  };
+  /**
+   * An array of plugin modules. Can work with semver specificity
+   */
+  plugins?: (Plugin | string)[];
+  /**
+   * Unused currently
+   * @unused
+   */
+  pollForAppUpdatesEveryXMinutes?: number;
   /**
    * Runtime environment variables
    */
@@ -495,20 +544,27 @@ export interface DesktopifyApp2<Plugin = DesktopAppPlugin> {
     [key: string]: string;
   };
   /**
-   * Command line switches
-   * Learn more {@link https://www.electronjs.org/docs/api/command-line-switches}
-   * @example
-   * {
-   *  'remote-debugging-port': '8315'
-   * }
+   * This option is only available when `shouldMinimizeToTray` is `true`.
+   * Always display the dock icon while the app is open. Even if there are no windows open.
    */
-  commandLineSwitches?: {
-    [key: string]: string;
-  };
+  shouldAlwaysDisplayDockIcon?: boolean;
+  /**
+   * Whether the app should have full access to Electron APIs
+   * @default false
+   */
+  shouldHaveFullAccessToElectronAPIs?: boolean;
   /**
    * Launch App at startup
    */
   shouldLaunchAtStartupByDefault?: boolean;
+  /**
+   * Open same domain links in user's default browser
+   */
+  shouldMakeSameDomainAnExternalLink?: boolean;
+  /**
+   * Whether the app should minimize to tray when all windows are closed. Requires at least one tray.
+   */
+  shouldMinimizeToTray?: boolean;
   /**
    * If `true` the app will prevent app from opening any protocols that are not
    * already in a maybeAllowList or allowList (see `protocolLists.ts` in desktopify).
@@ -518,117 +574,61 @@ export interface DesktopifyApp2<Plugin = DesktopAppPlugin> {
    * Disables non-essential logs
    */
   shouldOnlySendAbsolutelyNecessaryRequests?: boolean;
+  /**
+   * Prevents the window contents from being captured by other apps.
+   */
+  shouldProtectContent?: boolean;
   /**
    * Disables electron overrides which ensure renderer process are restarted on each navigation.
    * Learn more {@link https://github.com/electron/electron/issues/18397}
    */
   shouldReuseRendererProcess?: boolean;
   /**
-   * Open same domain links in user's default browser
-   */
-  shouldMakeSameDomainAnExternalLink?: boolean;
-  /**
-   * Enables push notifications — uses `electron-push-receiver`
-   */
-  enablePushNotifications?: boolean;
-  /**
-   * Enables NEW push notifications — uses `@cuj1559/electron-push-receiver`
+   * Removes electron from userAgent
    */
-  enableNewPushNotifications?: boolean;
+  shouldUseRealUserAgent?: boolean;
   /**
-   * Disable error reporting (Sentry)
+   * Only allow a single instance of this app to run
    */
-  disableErrorTracking?: boolean;
+  singleInstance: boolean;
   /**
    * Sets theme for Electron UI elements and css.
    *
    * See {@link https://www.electronjs.org/docs/api/native-theme#nativethemethemesource}
    */
-  themeSource?: 'system' | 'light' | 'dark';
+  themeSource?: 'dark' | 'light' | 'system';
   /**
    * Sets theme source for only mac
    *
    * See {@link https://www.electronjs.org/docs/api/native-theme#nativethemethemesource}
    */
-  themeSourceMac?: 'system' | 'light' | 'dark';
-  /**
-   * URL that crash reports will be POSTed to
-   */
-  crashReporter?: string;
-  /**
-   * Unused currently
-   * @unused
-   */
-  pollForAppUpdatesEveryXMinutes?: number;
-  /**
-   * An array of plugin modules. Can work with semver specificity
-   */
-  plugins?: (Plugin | string)[];
-  /**
-   * Metadata about plugins that were manually linked into the app
-   */
-  customPlugins?: CustomPlugin[];
-  /**
-   * The app's windows
-   */
-  windows: DesktopifyAppWindow[];
+  themeSourceMac?: 'dark' | 'light' | 'system';
   /**
    * The app's trays
    */
   trays: DesktopifyAppTray[];
   /**
-   * The app's menus
+   * Specifys the app's user agent
    */
-  menus: DesktopifyAppMenu[];
+  userAgent: ISwitchableValue<string>;
   /**
    * Prevents a potential vulnerability in URL matching in Electron
    * https://linear.app/todesktop/issue/TD-1428/html-injection-due-to-regular-expression-bypass
    */
   useSafeInternalUrlMatcher?: boolean;
   /**
-   * Sets whether the window menu bar should hide itself automatically.
-   * Once set the menu bar will only show when users press the single Alt key.
-   */
-  autoHideMenuBar?: boolean;
-  /**
-   * Sets whether an offline screen will be displayed if the internet is disconnected
-   * on initial page load. The color of the re-connect button that is shown is customizable.
-   */
-  offlineScreen?: {
-    enabled: boolean;
-    buttonBackgroundColor: string;
-    buttonTextColor: string;
-  };
-  /**
-   * Sets strings to be used in the app UI. Currently only supports English
-   */
-  appStrings?: {
-    [key in ValidTranslationKeys]?: {
-      [lang in ValidTranslationLanguages]?: string;
-    };
-  };
-  /**
-   * File assets that get bundled with the app and are available offline
+   * Instead of using one icon for every platform, use a separate icon for different platforms
    */
-  fileAssetDetailsList?: FileAssetDetails[];
+  useSeparateIcons?: boolean;
 
   /**
-   * Whether the app should have full access to Electron APIs
-   * @default false
+   * The app's windows
    */
-  shouldHaveFullAccessToElectronAPIs?: boolean;
+  windows: DesktopifyAppWindow[];
 
-  /**
-   * Whether the app is secure i.e. using valid code signing certificates.
-   * Note: This value is not persisted in firestore, and is instead written locally at build time.
-   * @default false
-   */
-  isSecure?: boolean;
+  windowsIcon?: string;
 
-  /**
-   * Prevents the window contents from being captured by other apps.
-   */
-  shouldProtectContent?: boolean;
+  windowsIconAssetDetails?: AppIconAssetDetails;
 }
 
 export type FindInPagePlacement = { offset: number };