jan/web/plugin/facade.ts

/**
 * Helper functions to access the plugin management in the main process.
 * Note that the facade needs to be imported separately as "pluggable-electron/facade" as described above.
 * It is then available on the global window object as describe in the {@link https://www.electronjs.org/docs/api/context-bridge|Electron documentation}
 * @namespace plugins
 */

import Plugin from './Plugin'
import { register } from './activation-manager'

/**
 * @typedef {Object.<string, any>} installOptions The {@link https://www.npmjs.com/package/pacote|pacote options}
 * used to install the plugin.
 * @param {string} specifier the NPM specifier that identifies the package.
 * @param {boolean} [activate=true] Whether this plugin should be activated after installation.
 */

/**
 * Install a new plugin.
 * @param {Array.<installOptions | string>} plugins A list of NPM specifiers, or installation configuration objects.
 * @returns {Promise.<Array.<Plugin> | false>} plugin as defined by the main process. Has property cancelled set to true if installation was cancelled in the main process.
 * @alias plugins.install
 */
export async function install(plugins: any[]) {
  if (typeof window === 'undefined') {
    return
  }
  // eslint-disable-next-line no-undef
  const plgList = await window.pluggableElectronIpc.install(plugins)
  if (plgList.cancelled) return false
  return plgList.map((plg: any) => {
    const plugin = new Plugin(
      plg.name,
      plg.url,
      plg.activationPoints,
      plg.active
    )
    register(plugin)
    return plugin
  })
}

/**
 * Uninstall provided plugins
 * @param {Array.<string>} plugins List of names of plugins to uninstall.
 * @param {boolean} reload Whether to reload all renderers after updating the plugins.
 * @returns {Promise.<boolean>} Whether uninstalling the plugins was successful.
 * @alias plugins.uninstall
 */
export function uninstall(plugins: string[], reload = true) {
  if (typeof window === 'undefined') {
    return
  }
  // eslint-disable-next-line no-undef
  return window.pluggableElectronIpc.uninstall(plugins, reload)
}

/**
 * Fetch a list of all the active plugins.
 * @returns {Promise.<Array.<Plugin>>} List of plugins as defined by the main process.
 * @alias plugins.getActive
 */
export async function getActive() {
  if (typeof window === 'undefined') {
    return []
  }
  // eslint-disable-next-line no-undef
  const plgList =
    (await window.pluggableElectronIpc?.getActive()) ??
    (await import(
      // eslint-disable-next-line no-undef
      /* webpackIgnore: true */ PLUGIN_CATALOG + `?t=${Date.now()}`
    ).then((data) => data.default.filter((e: any) => e.supportCloudNative)))
  return plgList.map(
    (plugin: any) =>
      new Plugin(
        plugin.name,
        plugin.url,
        plugin.activationPoints,
        plugin.active,
        plugin.description,
        plugin.version,
        plugin.icon
      )
  )
}

/**
 * Register all the active plugins.
 * @returns {Promise.<Array.<Plugin>>} List of plugins as defined by the main process.
 * @alias plugins.registerActive
 */
export async function registerActive() {
  if (typeof window === 'undefined') {
    return
  }
  // eslint-disable-next-line no-undef
  const plgList = await getActive()
  plgList.forEach((plugin: Plugin) =>
    register(
      new Plugin(
        plugin.name,
        plugin.url,
        plugin.activationPoints,
        plugin.active
      )
    )
  )
}

/**
 * Update provided plugins to its latest version.
 * @param {Array.<string>} plugins List of plugins to update by name.
 * @param {boolean} reload Whether to reload all renderers after updating the plugins.
 * @returns {Promise.<Array.<Plugin>>} Updated plugin as defined by the main process.
 * @alias plugins.update
 */
export async function update(plugins: Plugin[], reload = true) {
  if (typeof window === 'undefined') {
    return
  }
  // eslint-disable-next-line no-undef
  const plgList = await window.pluggableElectronIpc.update(plugins, reload)
  return plgList.map(
    (plugin: any) =>
      new Plugin(
        plugin.name,
        plugin.url,
        plugin.activationPoints,
        plugin.active
      )
  )
}

/**
 * Check if an update is available for provided plugins.
 * @param {Array.<string>} plugin List of plugin names to check for available updates.
 * @returns {Object.<string | false>} Object with plugins as keys and new version if update is available or false as values.
 * @alias plugins.updatesAvailable
 */
export function updatesAvailable(plugin: Plugin) {
  if (typeof window === 'undefined') {
    return
  }
  // eslint-disable-next-line no-undef
  return window.pluggableElectronIpc.updatesAvailable(plugin)
}

/**
 * Toggle a plugin's active state. This determines if a plugin should be loaded in initialisation.
 * @param {String} plugin Plugin to toggle.
 * @param {boolean} active Whether plugin should be activated (true) or deactivated (false).
 * @returns {Promise.<Plugin>} Updated plugin as defined by the main process.
 * @alias plugins.toggleActive
 */
export async function toggleActive(plugin: Plugin, active: boolean) {
  if (typeof window === 'undefined') {
    return
  }
  // eslint-disable-next-line no-undef
  const plg = await window.pluggableElectronIpc.toggleActive(plugin, active)
  return new Plugin(plg.name, plg.url, plg.activationPoints, plg.active)
}