@dimensional-innovations/electron-background 2.3.0 → 3.0.0

package/dist/init.d.ts

@@ -1,98 +1,16 @@
-import { BrowserWindow, BrowserWindowConstructorOptions } from 'electron';
-/**
- * The context object passed to each plugin during the init process.
- */
-export declare class InitContext {
-    /**
-     * The url used to load the application.
-     */
-    appUrl: string;
-    /**
-     * Options used to create the BrowserWindow. These can be modified in `beforeReady` or
-     * `beforeLoad` methods to change the created BrowserWindow.
-     */
-    browserWindowOptions: BrowserWindowConstructorOptions;
-    /**
-     * The log instance. This should be used over `console` in plugin implementations.
-     */
-    log: Pick<Console, 'error' | 'warn' | 'info' | 'debug'>;
-    constructor(
-    /**
-     * The url used to load the application.
-     */
-    appUrl: string, 
-    /**
-     * Options used to create the BrowserWindow. These can be modified in `beforeReady` or
-     * `beforeLoad` methods to change the created BrowserWindow.
-     */
-    browserWindowOptions: BrowserWindowConstructorOptions, 
-    /**
-     * The log instance. This should be used over `console` in plugin implementations.
-     */
-    log: Pick<Console, 'error' | 'warn' | 'info' | 'debug'>);
-    /**
-       * The main browser window that the app is loaded into. This is available in the context
-       * in the `beforeLoad` and `afterLoad` method.
-       */
-    browserWindow?: BrowserWindow;
-}
-/**
- * Represents the InitContext before the BrowserWindow has been set. Used in the
- * "beforeReady" and "afterReady" methods.
- */
-export type NonBrowserWindowInitContext = Omit<InitContext, 'browserWindow'>;
-/**
- * Represents the InitContext after the BrowserWindow has been set. Used in the
- * "beforeLoad" and "afterLoad" methods.
- */
-export type BrowserWindowInitContext = Omit<InitContext, 'browserWindow'> & Required<Pick<InitContext, 'browserWindow'>>;
-/**
- * A plugin is used to execute logic at various stages during the init process.
- *
- * Implementations can define one or more of the optional methods to customize
- * application instance.
- */
-export interface InitPlugin {
-    /**
-     * beforeReady is executed before the `app.whenReady()` promise resolves.
-     *
-     * @param context - The current InitContext instance.
-     */
-    beforeReady?(context: NonBrowserWindowInitContext): Promise<void>;
-    /**
-     * afterReady is executed after the `app.whenReady()` promise resolves, but before the
-     * BrowserWindow is created.
-     *
-     * @param context - The current InitContext instance.
-     */
-    afterReady?(context: NonBrowserWindowInitContext): Promise<void>;
+import { NonBrowserWindowInitContext } from './InitContext';
+import { InitPlugin } from './InitPlugin';
+import { AppBrowserWindow } from './windows/AppBrowserWindow';
+export interface InitOptions<T> {
+    config: () => T | Promise<T>;
     /**
-     * beforeLoad is executed after the browserWindow is created, but before the application
-     * has been loaded into the window.
-     *
-     * @param context - The current InitContext instance.
-     */
-    beforeLoad?(context: BrowserWindowInitContext): Promise<void>;
-    /**
-     * afterLoad is executed after the application has been loaded into the browserWindow.
-     *
-     * @param context - The current InitContext instance.
-     */
-    afterLoad?(context: BrowserWindowInitContext): Promise<void>;
-}
-export interface InitOptions {
-    /**
-     * The url to load once the the app has been created.
-     */
-    appUrl: string;
-    /**
-     * The default browser window options
+     * The list of plugins to load with the application.
      */
-    browserWindowOptions?: BrowserWindowConstructorOptions;
+    plugins?: Array<InitPlugin<T>>;
     /**
-     * The list of plugins to load with the application.
+     * The windows to create during the init process.
      */
-    plugins?: Array<InitPlugin>;
+    windows: Array<(context: NonBrowserWindowInitContext<T>) => AppBrowserWindow>;
 }
 /**
  * Initializes the application, creating a browser window, and loads the provided app url.
@@ -100,4 +18,4 @@ export interface InitOptions {
  * @param options - Options used to define how the application is initialized.
  * @returns - The final state of the init context, including the created browser window for additional setup.
  */
-export declare function init({ appUrl, browserWindowOptions, plugins, }: InitOptions): Promise<InitContext>;
+export declare function init<T>({ config, windows, plugins, }: InitOptions<T>): Promise<void>;

package/dist/init.js

@@ -12,38 +12,61 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.init = exports.InitContext = void 0;
+exports.init = init;
 const electron_1 = require("electron");
 const electron_log_1 = __importDefault(require("electron-log"));
+const InitContext_1 = require("./InitContext");
 /**
- * The context object passed to each plugin during the init process.
+ * Initializes the application, creating a browser window, and loads the provided app url.
+ *
+ * @param options - Options used to define how the application is initialized.
+ * @returns - The final state of the init context, including the created browser window for additional setup.
  */
-class InitContext {
-    constructor(
-    /**
-     * The url used to load the application.
-     */
-    appUrl, 
-    /**
-     * Options used to create the BrowserWindow. These can be modified in `beforeReady` or
-     * `beforeLoad` methods to change the created BrowserWindow.
-     */
-    browserWindowOptions, 
-    /**
-     * The log instance. This should be used over `console` in plugin implementations.
-     */
-    log) {
-        this.appUrl = appUrl;
-        this.browserWindowOptions = browserWindowOptions;
-        this.log = log;
-    }
+function init(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ config, windows, plugins = [], }) {
+        if (windows.length === 0) {
+            throw new Error('At least 1 window must be defined.');
+        }
+        process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = 'true';
+        electron_1.app.on('window-all-closed', electron_1.app.quit);
+        process.on('message', (data) => {
+            if (data === 'graceful-exit')
+                electron_1.app.quit();
+        });
+        process.on('SIGTERM', electron_1.app.quit);
+        let context = new InitContext_1.InitContext(electron_log_1.default);
+        for (const plugin of plugins) {
+            if (plugin.beforeReady) {
+                try {
+                    plugin.beforeReady(context);
+                }
+                catch (err) {
+                    context.log.error(`[init] Plugin "${getPluginName(plugin)}" threw during beforeReady:`, err);
+                }
+            }
+        }
+        yield electron_1.app.whenReady();
+        context = new InitContext_1.InitContext(electron_log_1.default, yield config());
+        yield runPluginPhase(plugins, 'afterReady', context);
+        for (const windowFactory of windows) {
+            const window = windowFactory(context);
+            const windowContext = new InitContext_1.InitContext(context.log, context.config, window);
+            yield runPluginPhase(plugins, 'beforeLoad', windowContext);
+            try {
+                yield windowContext.browserWindow.loadApp();
+            }
+            catch (err) {
+                electron_log_1.default.error('[init] Failed to load app URL:', err);
+            }
+            yield runPluginPhase(plugins, 'afterLoad', windowContext);
+        }
+    });
 }
-exports.InitContext = InitContext;
 function getPluginName(plugin) {
     var _a;
     return ((_a = plugin.constructor) === null || _a === void 0 ? void 0 : _a.name) || 'UnknownPlugin';
 }
-function runPluginPhase(plugins, phase, context, logger) {
+function runPluginPhase(plugins, phase, context) {
     return __awaiter(this, void 0, void 0, function* () {
         for (const plugin of plugins) {
             const method = plugin[phase];
@@ -52,45 +75,9 @@ function runPluginPhase(plugins, phase, context, logger) {
                     yield method.call(plugin, context);
                 }
                 catch (err) {
-                    logger.error(`[init] Plugin "${getPluginName(plugin)}" threw during ${phase}:`, err);
+                    context.log.error(`[init] Plugin "${getPluginName(plugin)}" threw during ${phase}:`, err);
                 }
             }
         }
     });
 }
-/**
- * Initializes the application, creating a browser window, and loads the provided app url.
- *
- * @param options - Options used to define how the application is initialized.
- * @returns - The final state of the init context, including the created browser window for additional setup.
- */
-function init({ appUrl, browserWindowOptions = { height: 1920, width: 1080, backgroundColor: '#000' }, plugins = [], }) {
-    return __awaiter(this, void 0, void 0, function* () {
-        process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = 'true';
-        electron_1.app.on('window-all-closed', electron_1.app.quit);
-        process.on('message', (data) => {
-            if (data === 'graceful-exit')
-                electron_1.app.quit();
-        });
-        process.on('SIGTERM', electron_1.app.quit);
-        const context = new InitContext(appUrl, browserWindowOptions, electron_log_1.default);
-        yield runPluginPhase(plugins, 'beforeReady', context, electron_log_1.default);
-        yield electron_1.app.whenReady();
-        yield runPluginPhase(plugins, 'afterReady', context, electron_log_1.default);
-        context.browserWindow = new electron_1.BrowserWindow(context.browserWindowOptions);
-        yield runPluginPhase(plugins, 'beforeLoad', context, electron_log_1.default);
-        try {
-            yield context.browserWindow.loadURL(context.appUrl);
-        }
-        catch (err) {
-            electron_log_1.default.error('[init] Failed to load app URL:', err);
-        }
-        if (context.browserWindow && !context.browserWindow.isDestroyed() && !context.browserWindow.isVisible()) {
-            context.browserWindow.show();
-        }
-        yield runPluginPhase(plugins, 'afterLoad', context, electron_log_1.default);
-        context.browserWindow.on('closed', () => context.browserWindow = undefined);
-        return context;
-    });
-}
-exports.init = init;

package/dist/{AutoUpdater.d.ts → plugins/AutoUpdater.d.ts}

@@ -1,4 +1,5 @@
-import { BrowserWindowInitContext, InitPlugin } from './init';
+import { InitPlugin } from '../InitPlugin';
+import { NonBrowserWindowInitContext } from '../InitContext';
 /**
  * Options for configuring the AutoUpdater plugin.
  */
@@ -15,15 +16,17 @@ export interface AutoUpdaterOptions {
  *
  * For more info, see https://www.electron.build/auto-update
  */
-export declare class AutoUpdater implements InitPlugin {
-    private readonly enabled;
+export declare class AutoUpdater<T extends {
+    autoUpdateChannel?: string;
+}> implements InitPlugin<T> {
     private readonly options;
+    private readonly enabled;
     /**
      * @constructor
      *
      * @param enabled - Indicates if the plugin is enabled. Used to disable the plugin in development. Defaults to `app.isPackaged`.
      */
-    constructor(enabled?: boolean, options?: AutoUpdaterOptions);
-    afterLoad({ log }: BrowserWindowInitContext): Promise<void>;
+    constructor(options?: AutoUpdaterOptions, enabled?: boolean);
+    afterReady({ config, log }: NonBrowserWindowInitContext<T>): Promise<void>;
     private startAutoUpdater;
 }

package/dist/{AutoUpdater.js → plugins/AutoUpdater.js}

@@ -28,13 +28,13 @@ class AutoUpdater {
      *
      * @param enabled - Indicates if the plugin is enabled. Used to disable the plugin in development. Defaults to `app.isPackaged`.
      */
-    constructor(enabled = electron_1.app.isPackaged, options = {}) {
-        this.enabled = enabled;
+    constructor(options = {}, enabled = electron_1.app.isPackaged) {
         this.options = options;
+        this.enabled = enabled;
     }
-    afterLoad({ log }) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const { channel } = this.options;
+    afterReady(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ config, log }) {
+            const channel = this.options.channel || config.autoUpdateChannel;
             if (this.enabled && channel) {
                 this.startAutoUpdater(channel);
             }

package/dist/{DevTools.d.ts → plugins/DevTools.d.ts}

@@ -1,5 +1,6 @@
 import { ExtensionReference } from 'electron-devtools-installer';
-import { BrowserWindowInitContext, InitPlugin } from './init';
+import { InitPlugin } from '../InitPlugin';
+import { BrowserWindowInitContext } from '../InitContext';
 export type Extension = ExtensionReference;
 export declare const DevToolExtensions: {
     readonly EMBER_INSPECTOR: ExtensionReference;
@@ -13,7 +14,7 @@ export declare const DevToolExtensions: {
 /**
  * Installs dev tools extensions and opens the devTools panel.
  */
-export declare class DevTools implements InitPlugin {
+export declare class DevTools implements InitPlugin<unknown> {
     private readonly devTools;
     private readonly enabled;
     /**
@@ -23,5 +24,5 @@ export declare class DevTools implements InitPlugin {
      * @param enabled - Indicates if the plugin is enabled. Used to disable the plugin when the app is packaged. Defaults to `!app.isPackaged`.
      */
     constructor(devTools: Array<ExtensionReference>, enabled?: boolean);
-    beforeLoad({ browserWindow }: BrowserWindowInitContext): Promise<void>;
+    beforeLoad({ browserWindow }: BrowserWindowInitContext<unknown>): Promise<void>;
 }

package/dist/{DevTools.js → plugins/DevTools.js}

@@ -35,8 +35,8 @@ class DevTools {
         this.devTools = devTools;
         this.enabled = enabled;
     }
-    beforeLoad({ browserWindow }) {
-        return __awaiter(this, void 0, void 0, function* () {
+    beforeLoad(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ browserWindow }) {
             if (!this.enabled) {
                 return;
             }

package/dist/{NodeHeartbeat.d.ts → plugins/NodeHeartbeat.d.ts}

@@ -1,4 +1,5 @@
-import { InitContext, InitPlugin } from './init';
+import { InitContext, NonBrowserWindowInitContext } from '../InitContext';
+import { InitPlugin } from '../InitPlugin';
 /**
  * Options used to define the request used to monitor the app.
  */
@@ -16,7 +17,7 @@ export interface HeartbeatOptions {
 /**
  * Starts a "heartbeat", which sends a request to the provided url on an interval.
  */
-export declare class Heartbeat implements InitPlugin {
+export declare class Heartbeat<T> implements InitPlugin<T> {
     private readonly options;
     private readonly enabled;
     /**
@@ -26,7 +27,7 @@ export declare class Heartbeat implements InitPlugin {
      * @param enabled - Indicates if the plugin is enabled. Used to disable the plugin during development. Defaults to `app.isPackaged`.
      */
     constructor(options: HeartbeatOptions, enabled?: boolean);
-    afterLoad(context: InitContext): Promise<void>;
+    afterReady(context: NonBrowserWindowInitContext<T>): Promise<void>;
 }
 export interface BetterStackHeartbeatOptions {
     /**
@@ -45,7 +46,9 @@ export interface BetterStackHeartbeatOptions {
 /**
  * Starts a "heartbeat" by sending a request to https://betterstack.com on an interval. Requires the apiKey to be in the app config.
  */
-export declare class BetterStackHeartbeat implements InitPlugin {
+export declare class BetterStackHeartbeat<T extends {
+    heartbeatApiKey?: string;
+}> implements InitPlugin<T> {
     private readonly enabled;
     private readonly options;
     /**
@@ -55,5 +58,5 @@ export declare class BetterStackHeartbeat implements InitPlugin {
      * @param options - Options that used to start the heartbeat.
      */
     constructor(enabled?: boolean, options?: BetterStackHeartbeatOptions);
-    afterLoad(context: InitContext): Promise<void>;
+    afterReady(context: NonBrowserWindowInitContext<T>): Promise<void>;
 }

package/dist/{NodeHeartbeat.js → plugins/NodeHeartbeat.js}

@@ -29,7 +29,7 @@ class Heartbeat {
         this.options = options;
         this.enabled = enabled;
     }
-    afterLoad(context) {
+    afterReady(context) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.enabled)
                 return;
@@ -55,9 +55,9 @@ class BetterStackHeartbeat {
         this.enabled = enabled;
         this.options = options;
     }
-    afterLoad(context) {
+    afterReady(context) {
         return __awaiter(this, void 0, void 0, function* () {
-            const heartbeatApiKey = this.options.heartbeatApiKey;
+            const heartbeatApiKey = this.options.heartbeatApiKey || context.config.heartbeatApiKey;
             if (this.enabled && heartbeatApiKey && typeof heartbeatApiKey === 'string') {
                 const url = this.options.isBetterStack
                     ? `https://uptime.betterstack.com/api/v1/heartbeat/${heartbeatApiKey}`

package/dist/{PrivilegedSchemes.d.ts → plugins/PrivilegedSchemes.d.ts}

@@ -1,4 +1,4 @@
-import { InitPlugin } from './init';
+import { InitPlugin } from '../InitPlugin';
 /**
  * Registers schemes as privileged.
  */
@@ -10,5 +10,5 @@ export declare class PrivilegedSchemes implements InitPlugin {
      * @param schemes - The schemes to register as privileged.
      */
     constructor(schemes: Array<string>);
-    beforeReady(): Promise<void>;
+    beforeReady(): false;
 }

package/dist/plugins/PrivilegedSchemes.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrivilegedSchemes = void 0;
+const electron_1 = require("electron");
+/**
+ * Registers schemes as privileged.
+ */
+class PrivilegedSchemes {
+    /**
+     * @constructor
+     *
+     * @param schemes - The schemes to register as privileged.
+     */
+    constructor(schemes) {
+        this.schemes = schemes;
+    }
+    beforeReady() {
+        const customSchemes = this.schemes
+            .map((scheme) => ({
+            scheme,
+            privileges: { secure: true, standard: true, supportFetchAPI: true },
+        }));
+        electron_1.protocol.registerSchemesAsPrivileged(customSchemes);
+        return false;
+    }
+}
+exports.PrivilegedSchemes = PrivilegedSchemes;

package/dist/{SingleInstance.d.ts → plugins/SingleInstance.d.ts}

@@ -1,10 +1,11 @@
-import { InitContext, InitPlugin } from './init';
+import { InitContext } from '../InitContext';
+import { InitPlugin } from '../InitPlugin';
 /**
  * Enforces that only a single instance of the app can run at the same time.
  * If a second instance of the is opened, the second instance is closed and
  * the first instance is brought back into focus.
  */
 export declare class SingleInstance implements InitPlugin {
-    beforeReady(): Promise<void>;
+    beforeReady(): false;
     afterReady(context: InitContext): Promise<void>;
 }

package/dist/{SingleInstance.js → plugins/SingleInstance.js}

@@ -18,12 +18,11 @@ const electron_1 = require("electron");
  */
 class SingleInstance {
     beforeReady() {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (electron_1.app.requestSingleInstanceLock())
-                return;
+        if (!electron_1.app.requestSingleInstanceLock()) {
             electron_1.app.quit();
             process.exit(0);
-        });
+        }
+        return false;
     }
     afterReady(context) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/plugins/StaticFileDir.d.ts

@@ -0,0 +1,16 @@
+import { InitPlugin } from '../InitPlugin';
+/**
+ * Registers a custom scheme to serve static files.
+ */
+export declare class StaticFileDir implements InitPlugin {
+    private readonly scheme;
+    private readonly dir;
+    /**
+     * @constructor
+     *
+     * @param scheme - The scheme to serve the files from.
+     * @param dir - The directory where the static files are located.
+     */
+    constructor(scheme: string, dir: string);
+    afterReady(): Promise<void>;
+}

package/dist/{StaticFileDir.js → plugins/StaticFileDir.js}

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createFileProtocol = exports.StaticFileDir = void 0;
+exports.StaticFileDir = void 0;
 const electron_1 = require("electron");
 const path_1 = require("path");
 /**
@@ -51,4 +51,3 @@ function createFileProtocol(scheme, sourceDirectory) {
         respond({ path });
     });
 }
-exports.createFileProtocol = createFileProtocol;

package/dist/{TouchEvents.d.ts → plugins/TouchEvents.d.ts}

@@ -1,7 +1,7 @@
-import { InitPlugin } from './init';
+import { InitPlugin } from '../InitPlugin';
 /**
  * Enables touch events in the app.
  */
 export declare class TouchEvents implements InitPlugin {
-    afterReady(): Promise<void>;
+    beforeReady(): false;
 }

package/dist/plugins/TouchEvents.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TouchEvents = void 0;
+const electron_1 = require("electron");
+/**
+ * Enables touch events in the app.
+ */
+class TouchEvents {
+    beforeReady() {
+        electron_1.app.commandLine.appendSwitch('touch-events', 'enabled');
+        return false;
+    }
+}
+exports.TouchEvents = TouchEvents;

package/dist/windows/AppBrowserWindow.d.ts

@@ -0,0 +1,28 @@
+import { BrowserWindow, BrowserWindowConstructorOptions } from "electron";
+/**
+ * Options used to create a new Application Window.
+ *
+ * AppBrowserWindow extends Electron's BrowserWindow and so any options for the BrowserWindow
+ * are accepted here. For more info see: https://electronjs.org/docs/api/structures/browser-window-options
+ */
+export interface AppBrowserWindowConstructorOptions extends BrowserWindowConstructorOptions {
+    /**
+     * The url to the application to load. This loaded by the AppBrowserWindow whenever loadApp
+     * is called.
+     */
+    appUrl: string;
+}
+/**
+ * Extends Electron's BrowserWindow to add support for loading a single app through a url
+ * provided when the window is constructed.
+ */
+export declare class AppBrowserWindow extends BrowserWindow {
+    private readonly appUrl;
+    constructor(options: AppBrowserWindowConstructorOptions);
+    /**
+     * Loads the predefined app.
+     *
+     * @returns - A promise that is resolved as the app is loaded.
+     */
+    loadApp(): Promise<void>;
+}

package/dist/{TouchEvents.js → windows/AppBrowserWindow.js}

@@ -9,16 +9,26 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TouchEvents = void 0;
+exports.AppBrowserWindow = void 0;
 const electron_1 = require("electron");
 /**
- * Enables touch events in the app.
+ * Extends Electron's BrowserWindow to add support for loading a single app through a url
+ * provided when the window is constructed.
  */
-class TouchEvents {
-    afterReady() {
+class AppBrowserWindow extends electron_1.BrowserWindow {
+    constructor(options) {
+        super(options);
+        this.appUrl = options.appUrl;
+    }
+    /**
+     * Loads the predefined app.
+     *
+     * @returns - A promise that is resolved as the app is loaded.
+     */
+    loadApp() {
         return __awaiter(this, void 0, void 0, function* () {
-            electron_1.app.commandLine.appendSwitch('touch-events', 'enabled');
+            return yield this.loadURL(this.appUrl);
         });
     }
 }
-exports.TouchEvents = TouchEvents;
+exports.AppBrowserWindow = AppBrowserWindow;

package/dist/windows/FullScreenBrowserWindow.d.ts

@@ -0,0 +1,17 @@
+import { AppBrowserWindow, AppBrowserWindowConstructorOptions } from "./AppBrowserWindow";
+export interface FullScreenBrowserWindowConstructorOptions extends AppBrowserWindowConstructorOptions {
+    /**
+     * The screen the window should occupy. Use 'primary' for the primary display,
+     * 'secondary' for the first non-primary display, or a number for the display
+     * at that index in the list returned by screen.getAllDisplays(). Defaults to 'primary'.
+     */
+    screen?: 'primary' | 'secondary' | number;
+}
+/**
+ * Ensures the browser window will always be fullscreen. Generally, KioskBrowserWindow is preferred
+ * over this window. However in cases where there are multiple windows, or a window needs to span
+ * multiple screens, the FullScreenBrowserWindow can be a better fit.
+ */
+export declare class FullScreenBrowserWindow extends AppBrowserWindow {
+    constructor({ screen: target, ...options }: FullScreenBrowserWindowConstructorOptions, enabled?: boolean);
+}