@overwolf/ow-electron-packages-types 1.1.1 → 1.1.2-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@overwolf/ow-electron-packages-types",
-    "version": "1.1.1",
+    "version": "1.1.2-beta.1",
     "description": "Type definition file for autocompletion and documentation purposes for ow-electron packages",
     "license": "MIT",
     "types": "types.d.ts",

package/types.d.ts

@@ -1,18 +1,18 @@
-import { overwolf } from '@overwolf/ow-electron';
-import type {
-  BrowserWindow,
-  BrowserWindowConstructorOptions,
-  Size,
-  WebContents,
-  Display,
-  Rectangle
-} from 'electron';
-
-import { EventEmitter } from 'events';
-
-// -----------------------------------------------------------------------------
-
-// --- modules\utility.d.ts ---
+import { overwolf } from '@overwolf/ow-electron';
+import type {
+  BrowserWindow,
+  BrowserWindowConstructorOptions,
+  Size,
+  WebContents,
+  Display,
+  Rectangle
+} from 'electron';
+
+import { EventEmitter } from 'events';
+
+// -----------------------------------------------------------------------------
+
+// --- modules\utility.d.ts ---
 /**
  * @packageDocumentation
  *
@@ -65,18 +65,66 @@ interface IOverwolfUtilityApi {
   scan(filter?: GamesFilter): Promise<InstalledGameInfo[]>;
 
    /**
-   * install ow-electron helpers to
-   * %CommonProgramFiles%\<app-name>\ with UAC elevation.
-   * will allow us to inject into high elevation games
+   * Install ow-electron helpers to
+   * `%CommonProgramFiles%\<app-name>\` with UAC elevation.
+   * Allows injection into high elevation games.
    * No-ops if files are already present.
-   * @throws {HelperInstallError} exitCode 1223 — user cancelled the UAC prompt (ERROR_CANCELLED)
-   * @throws {HelperInstallError} any other non-zero exitCode — installation failed
+   *
+   * @throws \{HelperInstallError\} `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
+   * @throws - {HelperInstallError} `err.exitCode !== 1223` — the installer process failed. Log `err.exitCode` and investigate.
+   * @throws \{HelperInstallError\} any other non-zero exitCode — installation failed.
+   *
+   * @remarks
+   * The helper binaries are installed to:
+   * - `%CommonProgramFiles%\<app-name>\owe-helper-ui.exe` (x64)
+   * - `%CommonProgramFiles%\<app-name>\owe-helper-ui-x86.exe` (x86)
+   *
+   * @example
+   * ```ts
+   * // Check whether the helper is already installed
+   * const installed: boolean = await api.isHighElevationHelperInstalled();
+   *
+   * // Trigger UAC-elevated installation (shows a UAC prompt to the user)
+   * try {
+   *   await api.installHighElevationHelper();
+   *   console.log('Helper installed successfully');
+   * } catch (err: any) {
+   *   if (err.exitCode === 1223) {
+   *     // User cancelled the UAC prompt — not an error, just inform the user
+   *     console.warn('User cancelled UAC prompt');
+   *   } else {
+   *     console.error('Installation failed, exitCode:', err.exitCode);
+   *   }
+   * }
+   * ```
+   *
+   * @example Typical integration flow
+   * ```ts
+   * async function ensureElevatedInjection(api: IOverwolfUtilityApi) {
+   *   const installed = await api.isHighElevationHelperInstalled();
+   *   if (!installed) {
+   *     await api.installHighElevationHelper(); // may throw — handle UAC cancel
+   *   }
+   *   // Injection into elevated games now happens automatically on game launch
+   * }
+   * ```
+   * @returns Resolves when installation completes.
    */
   installHighElevationHelper?(): Promise<void>;
 
-  /**
+   /**
    * Returns true if ow-electron helpers is already installed in
-   * %CommonProgramFiles%\<app-name>\.
+   * `%CommonProgramFiles%\<app-name>\`.
+   * 
+   * @returns `true` if the helper is installed and ready.
+   * 
+   * @example
+   * ```ts 
+   * const installed: boolean = await api.isHighElevationHelperInstalled();
+   * if (!installed) {
+   *   // Prompt the user to run the one-time setup before injecting into elevated games
+   * }
+   * ```
    */
   isHighElevationHelperInstalled?(): Promise<boolean>;
 
@@ -98,9 +146,9 @@ interface IOverwolfUtilityApi {
    */
   on(eventName: 'game-exit', listener: (gameInfo: GameInfo) => void): this;
 }
-
-
-// --- modules\recorder.d.ts ---
+
+
+// --- modules\recorder.d.ts ---
 /**
  * 
  * The Overwolf Electron recording APIs integrate recording into the Overwolf Electron framework allowing you to record both audio and video.
@@ -3052,7 +3100,7 @@ interface EncoderSettingsNVENC extends VideoEncoderSettingsBase {
    * If `true`, the encoder dynamically determines the number of B-frames up to `bf`.
    * Improves quality but increases GPU usage.
    *
-   * @default false
+   * @default true
    */
   lookahead?: boolean;
 
@@ -4464,9 +4512,9 @@ interface IOverwolfRecordingApi {
    */
   on(eventName: 'stats', listener: (args: RecorderStats) => void): this;
 }
-
-
-// --- modules\packages.d.ts ---
+
+
+// --- modules\packages.d.ts ---
 // -----------------------------------------------------------------------------
 //
 /**
@@ -4528,9 +4576,9 @@ interface OWPackages extends overwolf.packages.OverwolfPackageManager {
    */
   gep: OverwolfGameEventPackage;
 }
-
-
-// --- modules\overlay.d.ts ---
+
+
+// --- modules\overlay.d.ts ---
 /**
  * APIs for controlling and creating overlays in games. Overlay is the ability to show windows on top of the current game window.
  * 
@@ -4891,10 +4939,47 @@ interface IOverlayHotkey {
   /**
    * Primary key code for the hotkey.
    *
-   * Accepts a numeric Windows Virtual-Key code or, since 1.13.3, a W3C
-   * `KeyboardEvent.code` string (e.g. `'KeyA'`, `'F10'`, `'ArrowUp'`).
-   * String values are resolved to VK codes at registration time; an unknown
-   * string throws an error.
+   * Accepts a numeric Windows Virtual-Key (VK) code or a W3C {@link https://www.w3.org/TR/uievents-code/ | KeyboardEvent.code}
+   * string (e.g. `'KeyF'`, `'F10'`, `'ArrowUp'`).
+   *
+   * @remarks
+   * Numeric VK codes are layout-dependent — the same physical key produces a different
+   * VK number on non-QWERTY keyboards. Passing a `KeyboardEvent.code` string identifies
+   * the physical key unambiguously regardless of the user's keyboard layout.
+   *
+   * String values are resolved to VK codes at registration time. An unrecognized string
+   * throws immediately so misconfigured hotkeys are caught early.
+   *
+   * **Supported string codes include:** `KeyA`–`KeyZ`, `Digit0`–`Digit9`,
+   * `F1`–`F24`, `Numpad0`–`Numpad9`, `ArrowUp`/`Down`/`Left`/`Right`, `Tab`, `Enter`,
+   * `Space`, `Backspace`, `Delete`, `Escape`, `Home`, `End`, `PageUp`, `PageDown`,
+   * `ShiftLeft`/`Right`, `ControlLeft`/`Right`, `AltLeft`/`Right`, `Backquote`,
+   * `Minus`, `Equal`, `BracketLeft`/`Right`, `Semicolon`, `Quote`, `Comma`,
+   * `Period`, `Slash`, `Backslash`, and media/browser/launch keys.
+   *
+   * @throws `Error('Unknown hotkey code: "<value>". Pass a valid KeyboardEvent.code string…')`
+   * thrown at registration time when the string does not map to a known VK code.
+   * Validate the string before calling `register` if the value comes from user input.
+   *
+   * @example
+   * ```ts
+   * // Preferred: physical key position, layout-independent
+   * api.hotkeys.register({ name: 'toggle', keyCode: 'KeyF' }, callback);
+   *
+   * // With modifier using string code
+   * api.hotkeys.register({
+   *   name: 'screenshot',
+   *   keyCode: 'KeyP',
+   *   modifiers: { ctrl: true }
+   * }, callback);
+   *
+   * // Legacy: numeric VK code (still valid)
+   * api.hotkeys.register({ name: 'toggle-legacy', keyCode: 70 }, callback);
+   *
+   * // Throws at registration — unknown string
+   * api.hotkeys.register({ name: 'bad', keyCode: 'Bogus' }, callback);
+   * // Error: Unknown hotkey code: "Bogus". Pass a valid KeyboardEvent.code string…
+   * ```
    */
   keyCode: number | string;
 
@@ -5489,18 +5574,70 @@ interface IOverwolfOverlayApi extends EventEmitter {
   exitExclusiveMode(): void;
 
    /**
-   * install ow-electron helpers to
-   * %CommonProgramFiles%\<app-name>\ with UAC elevation.
-   * will allow us to inject into high elevation games
+   * Install ow-electron helpers to
+   * `%CommonProgramFiles%\<app-name>\` with UAC elevation.
+   * Allows injection into high elevation games.
    * No-ops if files are already present.
-   * @throws {HelperInstallError} exitCode 1223 — user cancelled the UAC prompt (ERROR_CANCELLED)
-   * @throws {HelperInstallError} any other non-zero exitCode — installation failed
+   *
+   * @throws \{HelperInstallError\}
+   *  - `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
+   *  - `err.exitCode !== 1223` — the installer process failed. Log `err.exitCode` and investigate.
+   *  - any other non-zero exitCode — installation failed.
+   *
+   * @remarks
+   * The helper binaries are installed to:
+   * - `%CommonProgramFiles%\<app-name>\owe-helper-ui.exe` (x64)
+   * - `%CommonProgramFiles%\<app-name>\owe-helper-ui-x86.exe` (x86)
+   *
+   * @example
+   * ```ts
+   * // Check whether the helper is already installed
+   * const installed: boolean = await api.isHighElevationHelperInstalled();
+   *
+   * // Trigger UAC-elevated installation (shows a UAC prompt to the user)
+   * try {
+   *   await api.installHighElevationHelper();
+   *   console.log('Helper installed successfully');
+   * } catch (err: any) {
+   *   if (err.exitCode === 1223) {
+   *     // User cancelled the UAC prompt — not an error, just inform the user
+   *     console.warn('User cancelled UAC prompt');
+   *   } else {
+   *     console.error('Installation failed, exitCode:', err.exitCode);
+   *   }
+   * }
+   * ```
+   *
+   * @example Typical integration flow
+   * ```ts
+   * async function ensureElevatedInjection(api: IOverwolfOverlayApi) {
+   *   const installed = await api.isHighElevationHelperInstalled();
+   *   if (!installed) {
+   *     await api.installHighElevationHelper(); // may throw — handle UAC cancel
+   *   }
+   *   // Injection into elevated games now happens automatically on game launch
+   * }
+   * ```
+   * @returns Resolves when installation completes.
+   * 
+   * 
+   * 
    */
   installHighElevationHelper?(): Promise<void>;
 
   /**
    * Returns true if ow-electron helpers is already installed in
-   * %CommonProgramFiles%\<app-name>\.
+   * `%CommonProgramFiles%\<app-name>\`.
+   * 
+   * @returns `true` if the helper is installed and ready.
+   * 
+   * @example
+   * ```ts 
+   * const installed: boolean = await api.isHighElevationHelperInstalled();
+   * if (!installed) {
+   *   // Prompt the user to run the one-time setup before injecting into elevated games
+   * }
+   * ```
    */
   isHighElevationHelperInstalled?(): Promise<boolean>;
 
@@ -5620,9 +5757,9 @@ interface IOverwolfOverlayApi extends EventEmitter {
     listener: (info: GameInputInterception) => void
   ): this;
 }
-
-
-// --- modules\gep.d.ts ---
+
+
+// --- modules\gep.d.ts ---
 /**
  * The *Game Events Provider* (GEP) APIs allow your app to subscribe to real-time in-game events and info updates
  * from supported games. GEP detects when a supported game launches, tracks gameplay state, and emits structured
@@ -5821,9 +5958,9 @@ interface OverwolfGameEventPackage extends NodeJS.EventEmitter {
      */
     category: string;
   }
-}
-
-// --- modules\crn.d.ts ---
+}
+
+// --- modules\crn.d.ts ---
 /**
  * The *Content Recommendation Notification* (CRN) APIs give you tools to help manage the content notification settings in your app. 
  * 
@@ -5960,4 +6097,4 @@ export interface IOverwolfCRNApi {
     eventName: 'notification-action',
     listener: (event: CRNActionType) => void
   ): this;
-}
+}