@overwolf/ow-electron-packages-types 1.1.12-beta.1 → 1.1.12-beta.3

package/package.json

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

package/types.d.ts

@@ -39,6 +39,68 @@ import { EventEmitter } from 'events';
  * ```
  */
 
+/**
+ * Reason `canInjectElevated()` reports {@link ElevatedInjectionCapability.supported} as `false`.
+ */
+type ElevatedInjectionUnsupportedReason =
+  /**
+   * `owe-helper-ui.exe` / `owe-helper-ui-x86.exe` are not installed yet in
+   * `%CommonProgramFiles%\<app-name>\`. Call `installHighElevationHelper()` to fix this.
+   */
+  | 'helper-not-installed'
+  /**
+   * The account running the app is a standard (non-administrator) user. A
+   * uiAccess helper launched from such an account only gets a MEDIUM+16
+   * integrity token, and Windows will not map a hook dll into a HIGH
+   * integrity (elevated) game.
+   *
+   * Call `installElevationBroker()` to inject anyway; without it the game has
+   * to run un-elevated, or the account needs administrator rights.
+   */
+  | 'account-cannot-elevate';
+
+/**
+ * Reports whether an elevated (HIGH integrity) game can actually be injected
+ * under the account the app is running as.
+ *
+ * @example
+ * ```ts
+ * const capability = await api.canInjectElevated();
+ * if (!capability.supported) {
+ *   console.warn('Cannot inject elevated games:', capability.reason);
+ * }
+ * ```
+ */
+interface ElevatedInjectionCapability {
+  /**
+   * `true` only when an elevated game can actually be injected right now.
+   */
+  readonly supported: boolean;
+
+  /**
+   * Set when {@link supported} is `false`.
+   */
+  readonly reason?: ElevatedInjectionUnsupportedReason;
+
+  /**
+   * `true` when the account can obtain a HIGH integrity token
+   * (administrator). When the check itself cannot run this is reported as
+   * `true`, so an undetermined account is attempted rather than blocked.
+   */
+  readonly accountCanElevate: boolean;
+
+  /**
+   * `true` when the uiAccess helper binaries are installed.
+   */
+  readonly helperInstalled: boolean;
+
+  /**
+   * `true` when the LocalSystem broker service is registered. It makes
+   * elevated injection possible regardless of {@link accountCanElevate}.
+   */
+  readonly brokerInstalled: boolean;
+}
+
 /**
  * Defines the API for managing game launch and utility operations.
  */
@@ -115,11 +177,17 @@ interface IOverwolfUtilityApi {
    /**
    * Returns true if ow-electron helpers is already installed in
    * `%CommonProgramFiles%\<app-name>\`.
-   * 
+   *
    * @returns `true` if the helper is installed and ready.
-   * 
+   *
+   * @remarks
+   * This only reports whether the binaries are present. On a standard
+   * (non-administrator) account they can be present and elevated injection
+   * still won't work — use `canInjectElevated()` to decide what to tell the
+   * user.
+   *
    * @example
-   * ```ts 
+   * ```ts
    * const installed: boolean = await api.isHighElevationHelperInstalled();
    * if (!installed) {
    *   // Prompt the user to run the one-time setup before injecting into elevated games
@@ -128,6 +196,56 @@ interface IOverwolfUtilityApi {
    */
   isHighElevationHelperInstalled?(): Promise<boolean>;
 
+  /**
+   * Whether an elevated (HIGH integrity) game can actually be injected under
+   * the account this app is running as.
+   *
+   * @returns An {@link ElevatedInjectionCapability} describing what's
+   * missing when elevated injection isn't currently possible.
+   *
+   * @remarks
+   * `supported` is `false` with reason `'account-cannot-elevate'` on a
+   * standard user account: Windows gives a uiAccess helper launched from such
+   * an account a MEDIUM+16 integrity token, which cannot get a dll mapped
+   * into an elevated game. The only workarounds are running the game
+   * un-elevated, granting the account administrator rights, or installing the
+   * elevation broker via `installElevationBroker()`.
+   *
+   * @example
+   * ```ts
+   * const capability = await api.canInjectElevated();
+   * if (!capability.supported) {
+   *   console.warn('Cannot inject elevated games:', capability.reason);
+   * }
+   * ```
+   */
+  canInjectElevated?(): Promise<ElevatedInjectionCapability>;
+
+  /**
+   * Installs the elevated injection broker: a LocalSystem service that
+   * injects into elevated games for accounts that cannot reach HIGH
+   * integrity, which is the only way an app running under a standard user
+   * account can overlay an elevated game. Prompts for UAC once.
+   *
+   * @throws `HelperInstallError` `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
+   * @throws `HelperInstallError` any other non-zero exitCode — installation failed
+   *
+   * @remarks
+   * The service stays registered until `uninstallElevationBroker()` removes
+   * it, so the app's uninstaller must call that.
+   *
+   * @returns Resolves when installation completes.
+   */
+  installElevationBroker?(): Promise<void>;
+
+  /**
+   * Stops and removes the elevation broker service. Prompts for UAC once.
+   * Succeeds when the service is already absent.
+   *
+   * @returns Resolves when removal completes.
+   */
+  uninstallElevationBroker?(): Promise<void>;
+
   /**
    * Fires when a tracked game is launched.
    *
@@ -4114,6 +4232,24 @@ type CrashDumpType = 'off' | 'mini' | 'full';
  */
 type ObsHostMode = 'process' | 'dll';
 
+/**
+ * Lifecycle of the recording or replays output.
+ *
+ * | Value        | Meaning                                                              |
+ * | ------------ | -------------------------------------------------------------------- |
+ * | `idle`       | Not started.                                                         |
+ * | `starting`   | Start accepted, output not running yet - OBS waits for a capture source to hook. |
+ * | `active`     | Running and producing frames.                                        |
+ *
+ * An output stays `starting` for as long as its capture source fails to hook,
+ * with no timeout. Operations that need a running output - `captureReplay`,
+ * `splitRecording` - fail with `CaptureSourceNotHooked` while it does.
+ *
+ * @see {@link IOverwolfRecordingApi.getRecordingState}
+ * @see {@link IOverwolfRecordingApi.getReplayState}
+ */
+type OutputState = 'idle' | 'starting' | 'active';
+
 /**
  * Crash dump configuration for the OBS host process.
  */
@@ -4203,6 +4339,10 @@ interface RecordingAppOptions {
  * | `-998`  | `ConnectionOBSError`         | Failed to connect to the OBS process.                                            |
  * | `-997`  | `AlreadyRunning`             | Operation attempted while recording is already running.                          |
  * | `-996`  | `ElevationHelperMissing`     | Elevated game capture requested while the High Elevation Helper isn't installed. |
+ * | `-995`  | `CaptureSourceNotHooked`     | Output accepted by OBS but not running yet - waiting for a capture source.       |
+ * | `-994`  | `CaptureSourceNotFound`      | A game or window capture source's target process wasn't found. Retryable.        |
+ * | `-993`  | `CaptureSourceCreationFailed`| OBS refused to create the capture source. Not retryable.                         |
+ * | `-992`  | `OBSNotReady`                | OBS accepted the connection but its core isn't initialized yet. Retryable.       |
  * | `-12`   | `SplitRecordingDisabled`     | Attempted to split recording when split recording is disabled.                   |
  * | `-11`   | `MissingOrInvalidParameters` | One or more required parameters are missing or invalid.                          |
  * | `-10`   | `NoActiveRecording`          | No active recording session found.                                               |
@@ -4230,6 +4370,10 @@ type ErrorCode =
   | -998  // Failed to connect to the OBS process. 'ConnectionOBSError'
   | -997  // Operation attempted while recording is already running. 'AlreadyRunning'
   | -996  // Elevated game capture requested while the High Elevation Helper isn't installed. 'ElevationHelperMissing'
+  | -995  // Output accepted by OBS but not running yet - waiting for a capture source. 'CaptureSourceNotHooked'
+  | -994  // A game or window capture source's target process wasn't found. Retryable. 'CaptureSourceNotFound'
+  | -993  // OBS refused to create the capture source. 'CaptureSourceCreationFailed'
+  | -992  // OBS accepted the connection but its core isn't initialized yet. Retryable. 'OBSNotReady'
   | -12   // Attempted to split recording when split recording is disabled. 'SplitRecordingDisabled'
   | -11   // One or more required parameters are missing or invalid. 'MissingOrInvalidParameters'
   | -10   // No active recording session found. 'NoActiveRecording'
@@ -4818,20 +4962,60 @@ interface IOverwolfRecordingApi {
   readonly binFolderPath: string;
 
   /**
-   * Checks if either recording or replays are currently active.
+   * Whether a recording or a replays service has been started and not yet
+   * stopped - `true` for both the `starting` and `active` states.
+   *
+   * @see {@link getRecordingState}
+   * @see {@link getReplayState}
    */
   isActive(): Promise<boolean>;
 
   /**
-   * Checks if a recording is currently active.
+   * Whether a recording has been started and not yet stopped.
+   *
+   * `true` from the moment {@link startRecording} resolves, including while the
+   * output is still `starting` - waiting for a capture source to hook - so it
+   * does not mean frames are being written.
+   *
+   * @see {@link getRecordingState} to tell those apart.
    */
   isRecordingActive(): Promise<boolean>;
 
   /**
-   * Checks if a replay session is currently active.
+   * Whether a replays service has been started and not yet stopped.
+   *
+   * `true` from the moment {@link startReplays} resolves, including while the
+   * buffer is still `starting` - waiting for a capture source to hook - so it
+   * does not mean the buffer holds any footage.
+   *
+   * @see {@link getReplayState} to tell those apart.
    */
   isReplayActive(): Promise<boolean>;
 
+  /**
+   * The recording output's current state.
+   *
+   * @example
+   * ```ts
+   * if (await recorder.getRecordingState() === 'starting') {
+   *   // started, but no capture source has hooked yet - nothing is written
+   * }
+   * ```
+   *
+   * @see {@link OutputState}
+   */
+  getRecordingState(): Promise<OutputState>;
+
+  /**
+   * The replays buffer's current state.
+   *
+   * {@link captureReplay} fails with `CaptureSourceNotHooked` while this is
+   * `starting`, since the buffer holds no footage yet.
+   *
+   * @see {@link OutputState}
+   */
+  getReplayState(): Promise<OutputState>;
+
   /**
    * Queries supported encoders, audio/video devices, and configuration options.
    *