ogi-addon 2.3.1 → 2.4.0

package/src/main.ts

@@ -7,6 +7,9 @@ import EventResponse from './EventResponse';
 import type { SearchResult } from './SearchEngine';
 import Fuse, { IFuseOptions } from 'fuse.js';
 
+/**
+ * Exposed events that the programmer can use to listen to and emit events.
+ */
 export type OGIAddonEvent =
   | 'connect'
   | 'disconnect'
@@ -19,8 +22,12 @@ export type OGIAddonEvent =
   | 'exit'
   | 'check-for-updates'
   | 'request-dl'
-  | 'catalog';
+  | 'catalog'
+  | 'launch-app';
 
+/**
+ * The events that the client can send to the server and are handled by the server.
+ */
 export type OGIAddonClientSentEvent =
   | 'response'
   | 'authenticate'
@@ -33,10 +40,15 @@ export type OGIAddonClientSentEvent =
   | 'flag'
   | 'task-update';
 
+/**
+ * The events that the server sends to the client
+ * This is the events that the server can send to the client and are handled by the client.
+ */
 export type OGIAddonServerSentEvent =
   | 'authenticate'
   | 'configure'
   | 'config-update'
+  | 'launch-app'
   | 'search'
   | 'setup'
   | 'response'
@@ -122,7 +134,16 @@ export interface CatalogWithCarousel {
   carousel?: Record<string, CatalogCarouselItem> | CatalogCarouselItem[];
 }
 
-export type CatalogResponse = Record<string, CatalogSection> | CatalogWithCarousel;
+export type CatalogResponse =
+  | Record<string, CatalogSection>
+  | CatalogWithCarousel;
+
+/**
+ * UMU ID format: 'steam:${number}' or 'umu:${number}'
+ * - steam:${number} → maps to umu-${number} for Steam games
+ * - umu:${number} → maps to umu-${number} for non-Steam games
+ */
+export type UmuId = `steam:${number}` | `umu:${number}`;
 
 export type SetupEventResponse = Omit<
   LibraryInfo,
@@ -138,6 +159,35 @@ export type SetupEventResponse = Omit<
     name: string;
     path: string;
   }[];
+  /**
+   * UMU Proton integration configuration
+   */
+  umu?: {
+    /**
+     * UMU ID for the game. Format: 'steam:${number}' or 'umu:${number}'
+     * - steam:${number} → maps to umu-${number} for Steam games
+     * - umu:${number} → maps to umu-${number} for non-Steam games
+     */
+    umuId: UmuId;
+    /**
+     * Optional DLL overrides. These are relative to the game's cwd.
+     * System automatically prepends cwd and sets WINEDLLOVERRIDES="dll=n,b"
+     */
+    dllOverrides?: string[];
+    /**
+     * Optional Proton version to use (e.g., 'GE-Proton9-5', 'GE-Proton')
+     * If not specified, uses latest UMU-Proton
+     */
+    protonVersion?: string;
+    /**
+     * Optional store identifier for protonfixes (e.g., 'gog', 'egs', 'none')
+     */
+    store?: string;
+    /**
+     * Cached Steam shortcut app ID after adding UMU game to Steam (avoids re-adding on each launch)
+     */
+    steamShortcutId?: number;
+  };
 };
 
 export interface EventListenerTypes {
@@ -272,12 +322,7 @@ export interface EventListenerTypes {
    * @param event
    * @returns
    */
-  catalog: (
-    event: Omit<
-      EventResponse<CatalogResponse>,
-      'askForInput'
-    >
-  ) => void;
+  catalog: (event: Omit<EventResponse<CatalogResponse>, 'askForInput'>) => void;
 
   /**
    * This event is emitted when the client requests for an addon to check for updates. Addon should resolve the event with the update information.
@@ -297,6 +342,17 @@ export interface EventListenerTypes {
         }
     >
   ) => void;
+
+  /**
+   * This event is emitted when the client is going to launch an app. Addon should use this to perform any pre or post launch tasks.
+   * @param data {LibraryInfo} The library information for the app to be launched.
+   * @param launchType { 'pre' | 'post' } The type of launch task to perform.
+   * @param event {EventResponse<void>} The event response from the server.
+   */
+  'launch-app': (
+    data: { libraryInfo: LibraryInfo; launchType: 'pre' | 'post' },
+    event: EventResponse<void>
+  ) => void;
 }
 
 export interface StoreData {
@@ -835,6 +891,36 @@ export const ZodLibraryInfo = z.object({
   addonsource: z.string(),
   coverImage: z.string(),
   titleImage: z.string().optional(),
+  /**
+   * UMU Proton integration configuration (Linux only)
+   */
+  umu: z
+    .object({
+      umuId: z
+        .string()
+        .regex(/^(steam|umu):\d+$/, 'Must be in format steam:{number} or umu:{number}'),
+      dllOverrides: z.array(z.string()).optional(),
+      protonVersion: z.string().optional(),
+      store: z.string().optional(),
+      winePrefixPath: z.string().optional(),
+      steamShortcutId: z.number().optional(),
+    })
+    .optional(),
+  /**
+   * Legacy mode flag for games using old Steam/flatpak wine system
+   */
+  legacyMode: z.boolean().optional(),
+  /**
+   * Redistributables to install (for backward compatibility)
+   */
+  redistributables: z
+    .array(
+      z.object({
+        name: z.string(),
+        path: z.string(),
+      })
+    )
+    .optional(),
 });
 export type LibraryInfo = z.infer<typeof ZodLibraryInfo>;
 interface Notification {
@@ -963,6 +1049,9 @@ class OGIAddonWSListener {
     return await this.waitForResponseFromServer<U>(id);
   }
 
+  /**
+   * Registers the message receiver for the socket. This is used to receive messages from the server and handle them.
+   */
   private registerMessageReceiver() {
     this.socket.on('message', async (data: string) => {
       const message: WebsocketMessageServer = JSON.parse(data);
@@ -983,17 +1072,8 @@ class OGIAddonWSListener {
           }
           break;
         case 'search':
-          let searchResultEvent = new EventResponse<SearchResult[]>(
-            (screen, name, description) =>
-              this.userInputAsked(screen, name, description, this.socket)
-          );
-          this.eventEmitter.emit('search', message.args, searchResultEvent);
-          const searchResult =
-            await this.waitForEventToRespond(searchResultEvent);
-          this.respondToMessage(
-            message.id!!,
-            searchResult.data,
-            searchResultEvent
+          await this.handleEventWithResponse<SearchResult[]>(message, (event) =>
+            this.eventEmitter.emit('search', message.args, event)
           );
           break;
         case 'setup': {
@@ -1019,74 +1099,28 @@ class OGIAddonWSListener {
           break;
         }
         case 'library-search':
-          let librarySearchEvent = new EventResponse<BasicLibraryInfo[]>(
-            (screen, name, description) =>
-              this.userInputAsked(screen, name, description, this.socket)
-          );
-          this.eventEmitter.emit(
-            'library-search',
-            message.args,
-            librarySearchEvent
-          );
-          const librarySearchResult =
-            await this.waitForEventToRespond(librarySearchEvent);
-          this.respondToMessage(
-            message.id!!,
-            librarySearchResult.data,
-            librarySearchEvent
+          await this.handleEventWithResponse<BasicLibraryInfo[]>(
+            message,
+            (event) =>
+              this.eventEmitter.emit('library-search', message.args, event)
           );
           break;
         case 'game-details':
-          let gameDetailsEvent = new EventResponse<StoreData | undefined>(
-            (screen, name, description) =>
-              this.userInputAsked(screen, name, description, this.socket)
-          );
-          if (this.eventEmitter.listenerCount('game-details') === 0) {
-            this.respondToMessage(
-              message.id!!,
-              {
-                error: 'No event listener for game-details',
-              },
-              gameDetailsEvent
-            );
-            break;
-          }
-          this.eventEmitter.emit(
-            'game-details',
-            message.args,
-            gameDetailsEvent
-          );
-          const gameDetailsResult =
-            await this.waitForEventToRespond(gameDetailsEvent);
-          this.respondToMessage(
-            message.id!!,
-            gameDetailsResult.data,
-            gameDetailsEvent
+          await this.handleEventWithResponse<StoreData | undefined>(
+            message,
+            (event) =>
+              this.eventEmitter.emit('game-details', message.args, event),
+            {
+              requireListener: 'game-details',
+              noListenerError: 'No event listener for game-details',
+            }
           );
           break;
         case 'check-for-updates':
-          let checkForUpdatesEvent = new EventResponse<
-            | {
-                available: true;
-                version: string;
-              }
-            | {
-                available: false;
-              }
-          >((screen, name, description) =>
-            this.userInputAsked(screen, name, description, this.socket)
-          );
-          this.eventEmitter.emit(
-            'check-for-updates',
-            message.args,
-            checkForUpdatesEvent
-          );
-          const checkForUpdatesResult =
-            await this.waitForEventToRespond(checkForUpdatesEvent);
-          this.respondToMessage(
-            message.id!!,
-            checkForUpdatesResult.data,
-            checkForUpdatesEvent
+          await this.handleEventWithResponse<
+            { available: true; version: string } | { available: false }
+          >(message, (event) =>
+            this.eventEmitter.emit('check-for-updates', message.args, event)
           );
           break;
         case 'request-dl':
@@ -1131,10 +1165,10 @@ class OGIAddonWSListener {
           );
           break;
         case 'catalog':
-          let catalogEvent = new EventResponse<CatalogResponse>();
-          this.eventEmitter.emit('catalog', catalogEvent);
-          const catalogResult = await this.waitForEventToRespond(catalogEvent);
-          this.respondToMessage(message.id!!, catalogResult.data, catalogEvent);
+          await this.handleEventWithResponseNoInput<CatalogResponse>(
+            message,
+            (event) => this.eventEmitter.emit('catalog', event)
+          );
           break;
         case 'task-run': {
           let taskRunEvent = new EventResponse<void>(
@@ -1202,6 +1236,11 @@ class OGIAddonWSListener {
           this.respondToMessage(message.id!!, taskRunResult.data, taskRunEvent);
           break;
         }
+        case 'launch-app':
+          await this.handleEventWithResponse<void>(message, (event) =>
+            this.eventEmitter.emit('launch-app', message.args, event)
+          );
+          break;
       }
     });
   }
@@ -1234,6 +1273,47 @@ class OGIAddonWSListener {
     });
   }
 
+  /**
+   * Common flow for events that use EventResponse with userInputAsked: create event, emit via callback, wait, respond.
+   * If options.requireListener is set and that event has no listeners, responds with options.noListenerError and returns.
+   */
+  private async handleEventWithResponse<T>(
+    message: WebsocketMessageServer,
+    emit: (event: EventResponse<T>) => void,
+    options?: { requireListener: string; noListenerError: string }
+  ): Promise<void> {
+    const event = new EventResponse<T>((screen, name, description) =>
+      this.userInputAsked(screen, name, description, this.socket)
+    );
+    if (
+      options &&
+      this.eventEmitter.listenerCount(options.requireListener) === 0
+    ) {
+      this.respondToMessage(
+        message.id!!,
+        { error: options.noListenerError },
+        event
+      );
+      return;
+    }
+    emit(event);
+    const result = await this.waitForEventToRespond(event);
+    this.respondToMessage(message.id!!, result.data, event);
+  }
+
+  /**
+   * Same as handleEventWithResponse but for events that don't need userInputAsked (e.g. catalog).
+   */
+  private async handleEventWithResponseNoInput<T>(
+    message: WebsocketMessageServer,
+    emit: (event: EventResponse<T>) => void
+  ): Promise<void> {
+    const event = new EventResponse<T>();
+    emit(event);
+    const result = await this.waitForEventToRespond(event);
+    this.respondToMessage(message.id!!, result.data, event);
+  }
+
   public respondToMessage(
     messageID: string,
     response: any,