@nonstrict/recordkit 0.87.2 → 0.97.0

package/src/IpcRecordKit.ts

@@ -22,6 +22,17 @@ export class IpcRecordKit {
       childProcess.on('spawn', () => { resolve(childProcess) })
     })
 
+    this.childProcess.on('close', (code, signal) => {
+      // No response can arrive anymore; fail all in-flight and future requests instead of letting
+      // them hang forever.
+      this.nsrpc.terminate(new Error(`RecordKit: [RPC] Process is gone (closed with code ${code} and signal ${signal}).`));
+    })
+    this.childProcess.stdin?.on('error', (error) => {
+      // Without an error listener, a failed write to a dead process would crash Node with an
+      // unhandled 'error' event. The 'close' handler above already fails all requests.
+      console.error(`RecordKit: [RPC] !! Failed to write to RPC process: ${error}`)
+    })
+
     const { stdout, stderr } = this.childProcess
     if (!stdout) { throw new Error('RecordKit: [RPC] !! No stdout stream on child process.') }
 
@@ -39,6 +50,7 @@ export class IpcRecordKit {
   private write(message: String) {
     const stdin = this.childProcess?.stdin;
     if (!stdin) { throw new Error('RecordKit: [RPC] !! Missing stdin stream.') }
+    if (stdin.destroyed) { throw new Error('RecordKit: [RPC] !! Process is gone, cannot write to its stdin.') }
     stdin.write(message + "\n")
   }
 }

package/src/NonstrictRPC.test.ts

@@ -7,7 +7,30 @@ import v8 from 'v8';
 // eval('%CollectGarbage(true)');
 
 describe('NonstrictRPC', () => {
-    it('needs tests', () => { });
+    describe('terminate', () => {
+        it('rejects all in-flight requests', async () => {
+            const rpc = new NSRPC(() => { });
+            const pending = rpc.perform({ type: 'Recorder', action: 'getDisplays' });
+            rpc.terminate(new Error('RPC process is gone'));
+            await expect(pending).rejects.toThrow('RPC process is gone');
+        });
+
+        it('fails future requests immediately instead of letting them hang', async () => {
+            const rpc = new NSRPC(() => { });
+            rpc.terminate(new Error('RPC process is gone'));
+            await expect(rpc.perform({ type: 'Recorder', action: 'getDisplays' })).rejects.toThrow('RPC process is gone');
+        });
+
+        it('does not affect requests that already completed', async () => {
+            const sent: string[] = [];
+            const rpc = new NSRPC((data) => sent.push(data));
+            const pending = rpc.perform({ type: 'Recorder', action: 'getDisplays' });
+            const request = JSON.parse(sent[0]);
+            rpc.receive(JSON.stringify({ nsrpc: 1, id: request.id, status: 200, result: ['display'] }));
+            await expect(pending).resolves.toEqual(['display']);
+            rpc.terminate(new Error('RPC process is gone'));
+        });
+    });
 
 //     beforeAll(() => {
 //         v8.setFlagsFromString('--allow-natives-syntax');

package/src/NonstrictRPC.ts

@@ -116,11 +116,28 @@ export class NSRPC {
 
   private responseHandlers: Map<string, PromiseSource> = new Map();
   private closureTargets: Map<string, ClosureTarget> = new Map();
+  private terminationError?: Error;
 
   constructor(send: (data: string) => void) {
     this.send = send;
   }
 
+  /**
+   * Marks the RPC connection as permanently gone, e.g. because the external process exited.
+   *
+   * All in-flight requests are rejected with the given error and any future request fails
+   * immediately with the same error, instead of waiting forever for a response that can no
+   * longer arrive.
+   */
+  terminate(error: Error) {
+    this.terminationError = error;
+    const pendingHandlers = [...this.responseHandlers.values()];
+    this.responseHandlers.clear();
+    for (const handler of pendingHandlers) {
+      handler.reject(error);
+    }
+  }
+
   receive(data: string) {
     // TODO: For now we just assume the message is a valid NSRPC message, but we should:
     // - Check if the nsrpc property is set to a number in the range of 1..<2
@@ -181,6 +198,9 @@ export class NSRPC {
   private async sendRequest(
     request: NSRPCRequestBody
   ): Promise<unknown> {
+    if (this.terminationError !== undefined) {
+      throw this.terminationError;
+    }
     const id = "req_" + randomUUID();
     const response = new Promise((resolve, reject) => {
       this.responseHandlers.set(id, { resolve, reject });
@@ -273,17 +293,21 @@ export class NSRPC {
     params?: Record<string, unknown>;
     lifecycle: Object;
   }) {
-    const target = args.target
-    finalizationRegistry.register(args.lifecycle, async () => {
-      await this.release(target);
-    });
-
     await this.sendRequest({
       target: args.target,
       type: args.type,
       params: args.params,
       procedure: "init",
     });
+
+    // Register the GC release only after a successful init; registering earlier would later send a
+    // release for a target the external process never knew about.
+    const target = args.target
+    finalizationRegistry.register(args.lifecycle, () => {
+      // Swallow rejections: the external process may already be gone, in which case there is
+      // nothing left to release.
+      this.release(target).catch(() => { });
+    });
   }
 
   async perform(body: { // TODO: Add support for static method calls.

package/src/RecordKit.ts

@@ -1,9 +1,34 @@
 import { IpcRecordKit } from "./IpcRecordKit.js";
 import { Recorder, RecorderSchemaItem } from "./Recorder.js";
-import type { SystemAudioBackend } from "./Recorder.js";
+import type { SystemAudioBackend, RecorderSettings, Size } from "./Recorder.js";
 import { EventEmitter } from "events";
 import { existsSync } from "node:fs";
 
+/** @internal */
+function windowIdOf(window: Window | number): number {
+  return typeof window == 'number' ? window : window.id
+}
+/** @internal */
+function displayIdOf(display: Display | number | undefined): number | undefined {
+  return display == null ? undefined : (typeof display == 'number' ? display : display.id)
+}
+/** @internal */
+function cameraIdOf(camera: Camera | string): string {
+  return typeof camera == 'string' ? camera : camera.id
+}
+/** @internal */
+function microphoneIdOf(microphone: Microphone | string): string {
+  return typeof microphone == 'string' ? microphone : microphone.id
+}
+/** @internal */
+function appleDeviceIdOf(device: AppleDevice | string): string {
+  return typeof device == 'string' ? device : device.id
+}
+/** @internal */
+function applicationIdOf(application: RunningApplication | number): number {
+  return typeof application == 'number' ? application : application.id
+}
+
 /**
  * Entry point for the RecordKit SDK, an instance is available as `recordkit` that can be imported from the module. Do not instantiate this class directly.
  *
@@ -15,6 +40,15 @@ import { existsSync } from "node:fs";
  *
  * @groupDescription Logging
  * Log what's going on to the console for easy debugging and troubleshooting. See the [Logging and Error Handling guide](https://recordkit.dev/guides/logging-and-errors) for more information.
+ *
+ * @groupDescription Preferred Devices
+ * Read and update the user's preferred devices, so you can pre-select sensible defaults in your UI.
+ *
+ * @groupDescription Window Control
+ * Move, resize, center and maximize windows of other applications (requires Accessibility Control permission).
+ *
+ * @groupDescription Device Control
+ * Configure capture devices, such as selecting a camera's active format or fetching an application's icon.
  */
 export class RecordKit extends EventEmitter {
   private ipcRecordKit = new IpcRecordKit()
@@ -61,8 +95,9 @@ export class RecordKit extends EventEmitter {
 
     const logHandlerInstance = this.ipcRecordKit.nsrpc.registerClosure({
       handler: (params) => {
-        console.log('RecordKit:', params.formattedMessage)
-        this.emit('log', params)
+        const message = params as unknown as LogMessage
+        console.log('RecordKit:', message.formattedMessage)
+        this.emit('log', message)
       },
       prefix: 'RecordKit.logHandler',
       lifecycle: this
@@ -76,9 +111,9 @@ export class RecordKit extends EventEmitter {
 
   /**
    * Set the global log level. Defaults to `debug`.
-   * 
+   *
    * Messages with a lower level than this will be ignored and not passed to any log handlers.
-   * 
+   *
    * @group Logging
    */
   async setLogLevel(logLevel: LogLevel): Promise<void> {
@@ -87,9 +122,9 @@ export class RecordKit extends EventEmitter {
 
   /**
    * Overrides the global log level for a specific category. Defaults to the global log level.
-   * 
+   *
    * Messages in the given category with a lower level than this will be ignored and not passed to any log handlers.
-   * 
+   *
    * @group Logging
    */
   async setCategoryLogLevel(params: { category: string, logLevel?: LogLevel }): Promise<void> {
@@ -151,6 +186,191 @@ export class RecordKit extends EventEmitter {
     return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getRunningApplications' }) as RunningApplication[]
   }
 
+  /**
+   * The user's preferred devices for each source type, ordered most-preferred first.
+   *
+   * RecordKit remembers which devices the user last recorded with (unless disabled via the recorder's
+   * `updatesUserPreferred` setting). Use this to pre-select a sensible default device in your UI.
+   *
+   * @group Preferred Devices
+   */
+  async getUserPreferred(): Promise<UserPreferred> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'UserPreferred', action: 'getPreferred' }) as UserPreferred
+  }
+
+  /**
+   * Records the given microphone as the user's most-preferred microphone.
+   *
+   * Call this whenever the user manually selects a microphone, so it can be pre-selected later via
+   * {@link getUserPreferred}. The selection moves to the front of {@link UserPreferred.microphoneIDs}.
+   *
+   * @param microphone - The microphone to prefer, either a {@link Microphone} or its {@link Microphone.id}.
+   * @group Preferred Devices
+   */
+  async updatePreferredMicrophone(microphone: Microphone | string): Promise<void> {
+    const id = microphoneIdOf(microphone)
+    await this.ipcRecordKit.nsrpc.perform({ type: 'UserPreferred', action: 'updateMicrophone', params: { id } })
+  }
+
+  /**
+   * Records the given camera as the user's most-preferred camera.
+   *
+   * Call this whenever the user manually selects a camera, so it can be pre-selected later via
+   * {@link getUserPreferred}. The selection moves to the front of {@link UserPreferred.cameraIDs}.
+   *
+   * @param camera - The camera to prefer, either a {@link Camera} or its {@link Camera.id}.
+   * @group Preferred Devices
+   */
+  async updatePreferredCamera(camera: Camera | string): Promise<void> {
+    const id = cameraIdOf(camera)
+    await this.ipcRecordKit.nsrpc.perform({ type: 'UserPreferred', action: 'updateCamera', params: { id } })
+  }
+
+  /**
+   * Records the given display as the user's most-preferred display.
+   *
+   * Call this whenever the user manually selects a display, so it can be pre-selected later via
+   * {@link getUserPreferred}. The selection moves to the front of {@link UserPreferred.displayIDs}.
+   *
+   * @param display - The display to prefer, either a {@link Display} or its {@link Display.id}.
+   * @group Preferred Devices
+   */
+  async updatePreferredDisplay(display: Display | number): Promise<void> {
+    const id = displayIdOf(display)
+    await this.ipcRecordKit.nsrpc.perform({ type: 'UserPreferred', action: 'updateDisplay', params: { id } })
+  }
+
+  /**
+   * Records the given Apple device as the user's most-preferred Apple device.
+   *
+   * Call this whenever the user manually selects an Apple device, so it can be pre-selected later via
+   * {@link getUserPreferred}. The selection moves to the front of {@link UserPreferred.appleDeviceIDs}.
+   *
+   * @param device - The Apple device to prefer, either an {@link AppleDevice} or its {@link AppleDevice.id}.
+   * @group Preferred Devices
+   */
+  async updatePreferredAppleDevice(device: AppleDevice | string): Promise<void> {
+    const id = appleDeviceIdOf(device)
+    await this.ipcRecordKit.nsrpc.perform({ type: 'UserPreferred', action: 'updateAppleDevice', params: { id } })
+  }
+
+  /**
+   * Maximizes the given window, resizing it to fill the display's visible area (excluding the menu bar and Dock)
+   * and centering it on that display.
+   *
+   * Requires Accessibility Control permission (see {@link getAccessibilityControlAccess}).
+   *
+   * @remarks
+   * Rejects if the window cannot be maximized — typically because Accessibility permission is missing,
+   * the target display cannot be found, or the window is minimized or closed.
+   *
+   * @param window - The window to maximize, either a {@link Window} or its {@link Window.id}.
+   * @param options.display - The display to maximize onto, either a {@link Display} or its {@link Display.id}. Defaults to the window's current display.
+   * @group Window Control
+   */
+  async maximizeWindow(window: Window | number, options?: { display?: Display | number }): Promise<void> {
+    await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'windowMaximize', params: { window: windowIdOf(window), display: displayIdOf(options?.display) } })
+  }
+
+  /**
+   * Resizes the given window to the given size (in points), keeping it centered on its display.
+   *
+   * Requires Accessibility Control permission (see {@link getAccessibilityControlAccess}).
+   *
+   * @remarks
+   * The requested size is clipped to the display's visible frame if it would be larger. After resizing,
+   * the window is re-centered so that a window which could not shrink/grow to the requested size still
+   * ends up centered. Rejects if Accessibility permission is missing, the target display cannot be found,
+   * or the window is minimized, closed, or does not support resizing.
+   *
+   * @param window - The window to resize, either a {@link Window} or its {@link Window.id}.
+   * @param size - The new size in points.
+   * @param options.display - The display to center on, either a {@link Display} or its {@link Display.id}. Defaults to the window's current display.
+   * @group Window Control
+   */
+  async resizeWindow(window: Window | number, size: Size, options?: { display?: Display | number }): Promise<void> {
+    await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'windowResize', params: { window: windowIdOf(window), width: size.width, height: size.height, display: displayIdOf(options?.display) } })
+  }
+
+  /**
+   * Centers the given window within the visible area (excluding the menu bar and Dock) of its display,
+   * keeping its current size.
+   *
+   * Requires Accessibility Control permission (see {@link getAccessibilityControlAccess}).
+   *
+   * @remarks
+   * Rejects if Accessibility permission is missing, the target display cannot be found, or the window is
+   * minimized, closed, or does not support moving.
+   *
+   * @param window - The window to center, either a {@link Window} or its {@link Window.id}.
+   * @param options.display - The display to center on, either a {@link Display} or its {@link Display.id}. Defaults to the window's current display.
+   * @group Window Control
+   */
+  async centerWindow(window: Window | number, options?: { display?: Display | number }): Promise<void> {
+    await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'windowCenter', params: { window: windowIdOf(window), display: displayIdOf(options?.display) } })
+  }
+
+  /**
+   * Moves the given window so its top-left corner is at the given position (in points, top-left origin).
+   *
+   * Requires Accessibility Control permission (see {@link getAccessibilityControlAccess}).
+   *
+   * @remarks
+   * Rejects if Accessibility permission is missing, or the window is minimized, closed, or does not
+   * support moving.
+   *
+   * @param window - The window to move, either a {@link Window} or its {@link Window.id}.
+   * @param position - The new top-left origin for the window, in points (top-left coordinate space).
+   * @group Window Control
+   */
+  async moveWindow(window: Window | number, position: { x: number, y: number }): Promise<void> {
+    await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'windowMove', params: { window: windowIdOf(window), x: position.x, y: position.y } })
+  }
+
+  /**
+   * Selects the camera's active capture format that best matches the given dimensions (in pixels).
+   *
+   * Use this when you want the camera to deliver a specific resolution — typically before recording or
+   * before showing a live preview, so the preview renders at the intended resolution. The format stays
+   * in effect until something else changes it.
+   *
+   * The chosen format is the smallest format whose dimensions are ≥ the target, preferring biplanar YUV
+   * pixel formats, and falling back to the largest available format if nothing meets the target.
+   *
+   * @remarks
+   * Rejects if the camera is unavailable, has no usable video format, or its configuration is locked by
+   * another process.
+   *
+   * @param camera - The camera to configure, either a {@link Camera} or its {@link Camera.id}.
+   * @param dimensions - Target dimensions in pixels.
+   * @group Device Control
+   */
+  async setCameraActiveFormat(camera: Camera | string, dimensions: Size): Promise<void> {
+    await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'cameraSetActiveFormat', params: { camera: cameraIdOf(camera), width: dimensions.width, height: dimensions.height } })
+  }
+
+  /**
+   * Returns the camera capture format that {@link setCameraActiveFormat} would select for the given
+   * dimensions (in pixels), without applying it. Returns `undefined` if the camera has no suitable format.
+   *
+   * @group Device Control
+   */
+  async getCameraBestFormat(camera: Camera | string, dimensions: Size): Promise<CameraFormat | undefined> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'cameraBestFormat', params: { camera: cameraIdOf(camera), width: dimensions.width, height: dimensions.height } }) as CameraFormat | undefined
+  }
+
+  /**
+   * Returns the icon of the given running application as a `data:image/png;base64,...` URL,
+   * usable directly as the `src` of an HTML `<img>` tag.
+   *
+   * @group Device Control
+   */
+  async getApplicationIcon(application: RunningApplication | number): Promise<string> {
+    const id = applicationIdOf(application)
+    const result = await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getApplicationIcon', params: { application: id } }) as { icon: string }
+    return result.icon
+  }
+
   /**
    * Indicates if camera can be used.
    *
@@ -197,6 +417,26 @@ export class RecordKit extends EventEmitter {
     }) as boolean
   }
 
+  /**
+   * Probes whether system audio can actually be recorded with the given backend by attempting a short silent capture.
+   *
+   * Unlike {@link getSystemAudioRecordingAccess}, which reads the recorded permission state, this verifies the
+   * permission is truly usable, immediately detecting cases where the OS reports a permission as granted but
+   * capture would still fail (e.g. after the user revokes it).
+   *
+   * @remarks If the permission state is still undetermined, this may trigger the system audio permission prompt.
+   * @group Permissions
+   */
+  async probeSystemAudioRecordingAccess(options?: { backend?: SystemAudioPermissionBackend }): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({
+      type: 'AuthorizationStatus',
+      action: 'probeSystemAudioRecordingAccess',
+      params: {
+        backend: options?.backend ?? 'default'
+      }
+    }) as boolean
+  }
+
   /**
    * Indicates if keystroke events of other apps can be recorded via Input Monitoring.
    *
@@ -258,7 +498,9 @@ export class RecordKit extends EventEmitter {
    * - `screenCaptureKit`: Screen Recording permission
    * - `_beta_coreAudio`: deprecated alias for `coreAudio`
    *
-   * Afterwards, the users needs to restart this app, for the permission to become active in the app.
+   * For the `screenCaptureKit` backend the user must restart the app before the granted permission
+   * becomes active. The `default` and `coreAudio` backends return the live granted/denied result
+   * with no restart required (macOS 14.2+).
    *
    * @returns Boolean value that indicates whether the user granted or denied access to your app.
    * @group Permissions
@@ -301,18 +543,43 @@ export class RecordKit extends EventEmitter {
     return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestAccessibilityControlAccess' }) as void
   }
 
+  /**
+   * Creates a {@link Recorder} for the given schema.
+   *
+   * The schema describes what to record (its `items`, e.g. a webcam, display, microphone or system audio),
+   * where to write the resulting RecordKit bundle (`output_directory`), and optional session-wide
+   * {@link RecorderSettings}. Call {@link Recorder.prepare} then {@link Recorder.start} on the returned recorder.
+   *
+   * @remarks The given `schema` is consumed: device/window objects in its `items` are replaced by their IDs and
+   * any callbacks are registered internally. Pass a fresh schema object per call rather than reusing one.
+   *
+   * @group Recording
+   */
   async createRecorder(
     schema: {
       output_directory?: string
       items: RecorderSchemaItem[]
-      settings?: {
-        allowFrameReordering?: boolean
-      }
+      settings?: RecorderSettings
     }): Promise<Recorder> {
     return Recorder.newInstance(this.ipcRecordKit.nsrpc, schema);
   }
 }
 
+/**
+ * Typed event overloads for {@link RecordKit}. Declaration-merges with the class so that
+ * `recordkit.on('log', message => …)` receives a typed {@link LogMessage} instead of `any`.
+ *
+ * @group Logging
+ */
+export interface RecordKit {
+  /** Fires for every log message emitted by RecordKit. See {@link LogMessage}. */
+  on(event: 'log', listener: (message: LogMessage) => void): this;
+  /** @see {@link RecordKit.on} */
+  once(event: 'log', listener: (message: LogMessage) => void): this;
+  /** @see {@link RecordKit.on} */
+  off(event: 'log', listener: (message: LogMessage) => void): this;
+}
+
 /** @ignore */
 export let recordkit = new RecordKit();
 
@@ -400,6 +667,9 @@ export interface Camera {
   /** An identifier that uniquely identifies the camera. */
   id: string;
 
+  /** Indicates whether this is a virtual camera (e.g. provided by software rather than physical hardware). */
+  isVirtual: boolean;
+
   /** A localized camera name for display in the user interface. */
   name: string;
 
@@ -428,6 +698,20 @@ export interface Camera {
   preview_url?: string;
 }
 
+/**
+ * A camera capture format, as returned by {@link RecordKit.getCameraBestFormat}.
+ *
+ * @group Discovery
+ */
+export interface CameraFormat {
+  /** Width of the format, in pixels. */
+  width: number
+  /** Height of the format, in pixels. */
+  height: number
+  /** Highest frame rate supported by this format, in frames per second. */
+  maxFrameRate: number
+}
+
 /**
  * A microphone whose audio can be recorded.
  * 
@@ -437,6 +721,9 @@ export interface Microphone {
   /** An identifier that uniquely identifies the microphone. */
   id: string;
 
+  /** Indicates whether this is a virtual microphone (e.g. provided by software rather than physical hardware). */
+  isVirtual: boolean;
+
   /** A localized microphone name for display in the user interface. */
   name: string;
 
@@ -469,9 +756,15 @@ export interface Display {
   /** Name of this display. */
   localizedName?: string;
 
+  /** SF Symbol name representing this display (e.g. `laptopcomputer`, `display`), suitable for use in the UI. */
+  symbolName: string;
+
   /** Frame of the display, relative to the main display. Uses top-left coordinate space. */
   frame: Bounds
 
+  /** Visible frame of the display (excluding the menu bar and Dock), relative to the main display. Top-left coordinate space. */
+  visibleFrame?: Bounds
+
   /** Indicates if this is the main display. */
   isMain: boolean
 
@@ -522,7 +815,50 @@ export interface Bounds {
   height: number;
 }
 
+/**
+ * The user's preferred device IDs for each source type, ordered most-preferred first.
+ *
+ * @group Preferred Devices
+ */
+export interface UserPreferred {
+  /** Preferred microphone IDs (matching {@link Microphone.id}), most-preferred first. */
+  microphoneIDs: string[]
+  /** Preferred camera IDs (matching {@link Camera.id}), most-preferred first. */
+  cameraIDs: string[]
+  /** Preferred display IDs (matching {@link Display.id}), most-preferred first. */
+  displayIDs: number[]
+  /** Preferred Apple device IDs (matching {@link AppleDevice.id}), most-preferred first. */
+  appleDeviceIDs: string[]
+}
+
 /**
  * @group Logging
  */
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warning' | 'error' | 'critical'
+
+/**
+ * A structured log message emitted by RecordKit, delivered as the payload of the `'log'` event.
+ *
+ * @example
+ * ```ts
+ * recordkit.on('log', (message) => {
+ *   if (message.level === 'error') myLogger.error(message.category, message.message, message.metadata)
+ * })
+ * ```
+ *
+ * @group Logging
+ */
+export interface LogMessage {
+  /** Time the message was logged, in milliseconds since the Unix epoch. Use `new Date(timestamp)` to get a `Date`. */
+  timestamp: number
+  /** Severity level of the message. */
+  level: LogLevel
+  /** Category the message belongs to (e.g. the subsystem that emitted it). */
+  category: string
+  /** The log message text. */
+  message: string
+  /** Additional structured key/value metadata attached to the message. */
+  metadata: Record<string, string>
+  /** Pre-formatted, human-readable representation of the message (timestamp, level, category, message and metadata). */
+  formattedMessage: string
+}