@overwolf/ow-electron-packages-types 1.1.12-beta.2 → 1.1.12-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@overwolf/ow-electron-packages-types",
-    "version": "1.1.12-beta.2",
+    "version": "1.1.12-beta.4",
     "description": "Type definition file for autocompletion and documentation purposes for ow-electron packages",
     "license": "MIT",
     "types": "types.d.ts",
@@ -34,7 +34,8 @@
     "scripts": {
         "combine": "node combine-dts.js ./modules",
         "beta": "node beta.js",
-        "release": "node release.js"
+        "release": "node release.js",
+        "prepare": "git config core.hooksPath .githooks || true"
     },
     "dependencies": {
         "glob": "^13.0.0"

package/types.d.ts

@@ -101,6 +101,46 @@ interface ElevatedInjectionCapability {
   readonly brokerInstalled: boolean;
 }
 
+/**
+ * The value a failed elevation call rejects with: `installHighElevationHelper()`,
+ * `isHighElevationHelperInstalled()`, `canInjectElevated()`,
+ * `installElevationBroker()` and `uninstallElevationBroker()`.
+ *
+ * It is a plain object, not an `Error` instance: `err instanceof Error` is
+ * `false`, and there is no stack trace.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await api.installElevationBroker();
+ * } catch (err) {
+ *   const { message, exitCode } = err as UtilityApiError;
+ *   if (exitCode === 1223) {
+ *     console.warn('User cancelled UAC prompt');
+ *   } else {
+ *     console.error('Broker install failed:', message, exitCode);
+ *   }
+ * }
+ * ```
+ */
+interface UtilityApiError {
+  /**
+   * Describes the failure.
+   */
+  readonly message: string;
+
+  /**
+   * Exit code of the elevated installer process. Only set by the calls that
+   * prompt for UAC (`installHighElevationHelper()`,
+   * `installElevationBroker()` and `uninstallElevationBroker()`), and only
+   * when the installer actually ran - it is absent when the call failed
+   * before that, e.g. a missing helper binary.
+   *
+   * `1223` (ERROR_CANCELLED) means the user cancelled the UAC prompt.
+   */
+  readonly exitCode?: number;
+}
+
 /**
  * Defines the API for managing game launch and utility operations.
  */
@@ -132,9 +172,9 @@ interface IOverwolfUtilityApi {
    * 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` `err.exitCode !== 1223` — the installer process failed. Log `err.exitCode` and investigate.
-   * @throws `HelperInstallError` any other non-zero exitCode — installation failed.
+   * @throws {@link UtilityApiError} `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
+   * @throws {@link UtilityApiError} any other `exitCode` — the installer process failed. Log `err.exitCode` and investigate.
+   * @throws {@link UtilityApiError} no `exitCode` — the call failed before the installer ran. Log `err.message`.
    *
    * @remarks
    * The helper binaries are installed to:
@@ -150,12 +190,13 @@ interface IOverwolfUtilityApi {
    * try {
    *   await api.installHighElevationHelper();
    *   console.log('Helper installed successfully');
-   * } catch (err: any) {
-   *   if (err.exitCode === 1223) {
+   * } catch (err) {
+   *   const { message, exitCode } = err as UtilityApiError;
+   *   if (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);
+   *     console.error('Installation failed:', message, exitCode);
    *   }
    * }
    * ```
@@ -179,6 +220,7 @@ interface IOverwolfUtilityApi {
    * `%CommonProgramFiles%\<app-name>\`.
    *
    * @returns `true` if the helper is installed and ready.
+   * @throws {@link UtilityApiError}
    *
    * @remarks
    * This only reports whether the binaries are present. On a standard
@@ -202,6 +244,7 @@ interface IOverwolfUtilityApi {
    *
    * @returns An {@link ElevatedInjectionCapability} describing what's
    * missing when elevated injection isn't currently possible.
+   * @throws {@link UtilityApiError}
    *
    * @remarks
    * `supported` is `false` with reason `'account-cannot-elevate'` on a
@@ -227,8 +270,9 @@ interface IOverwolfUtilityApi {
    * 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
+   * @throws {@link UtilityApiError} `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
+   * @throws {@link UtilityApiError} any other `exitCode` — installation failed
+   * @throws {@link UtilityApiError} no `exitCode` — the call failed before the installer ran
    *
    * @remarks
    * The service stays registered until `uninstallElevationBroker()` removes
@@ -242,6 +286,10 @@ interface IOverwolfUtilityApi {
    * Stops and removes the elevation broker service. Prompts for UAC once.
    * Succeeds when the service is already absent.
    *
+   * @throws {@link UtilityApiError} `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
+   * @throws {@link UtilityApiError} any other `exitCode` — removal failed
+   * @throws {@link UtilityApiError} no `exitCode` — the call failed before the uninstaller ran
+   *
    * @returns Resolves when removal completes.
    */
   uninstallElevationBroker?(): Promise<void>;
@@ -4232,6 +4280,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.
  */
@@ -4321,6 +4387,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.                                               |
@@ -4348,6 +4418,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'
@@ -4936,20 +5010,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.
    *