ogi-addon 2.2.0 → 2.3.1

package/build/main.d.cts

@@ -1,5 +1,476 @@
-import { r as ConfigurationBuilder } from "./ConfigurationBuilder-C83EP5v2.cjs";
-import { t as Configuration } from "./Configuration-DdkCGFMU.cjs";
-import { t as SearchResult } from "./SearchEngine-Cn_-M-at.cjs";
-import { _ as WebsocketMessageServer, a as LibraryInfo, c as OGIAddonConfiguration, d as SearchTool, f as SetupEventResponse, g as WebsocketMessageClient, h as VERSION, i as EventListenerTypes, l as OGIAddonEvent, m as Task, n as BasicLibraryInfo, o as OGIAddon, p as StoreData, r as ClientSentEventTypes, s as OGIAddonClientSentEvent, t as EventResponse, u as OGIAddonServerSentEvent, v as ZodLibraryInfo } from "./EventResponse-DrBsB9tW.cjs";
-export { BasicLibraryInfo, ClientSentEventTypes, Configuration, ConfigurationBuilder, EventListenerTypes, EventResponse, LibraryInfo, OGIAddonClientSentEvent, OGIAddonConfiguration, OGIAddonEvent, OGIAddonServerSentEvent, SearchResult, SearchTool, SetupEventResponse, StoreData, Task, VERSION, WebsocketMessageClient, WebsocketMessageServer, ZodLibraryInfo, OGIAddon as default };
+import { ConfigurationBuilder, ConfigurationFile } from "./config/ConfigurationBuilder.cjs";
+import { Configuration } from "./config/Configuration.cjs";
+import { SearchResult } from "./SearchEngine.cjs";
+import EventResponse from "./EventResponse.cjs";
+import events from "node:events";
+import { IFuseOptions } from "fuse.js";
+import { z } from "zod";
+
+//#region src/main.d.ts
+type OGIAddonEvent = 'connect' | 'disconnect' | 'configure' | 'authenticate' | 'search' | 'setup' | 'library-search' | 'game-details' | 'exit' | 'check-for-updates' | 'request-dl' | 'catalog';
+type OGIAddonClientSentEvent = 'response' | 'authenticate' | 'configure' | 'defer-update' | 'notification' | 'input-asked' | 'get-app-details' | 'search-app-name' | 'flag' | 'task-update';
+type OGIAddonServerSentEvent = 'authenticate' | 'configure' | 'config-update' | 'search' | 'setup' | 'response' | 'library-search' | 'check-for-updates' | 'task-run' | 'game-details' | 'request-dl' | 'catalog';
+declare const VERSION: string;
+interface ClientSentEventTypes {
+  response: any;
+  authenticate: {
+    name: string;
+    id: string;
+    description: string;
+    version: string;
+    author: string;
+  };
+  configure: ConfigurationFile;
+  'defer-update': {
+    logs: string[];
+    progress: number;
+  };
+  notification: Notification;
+  'input-asked': ConfigurationBuilder<Record<string, string | number | boolean>>;
+  'task-update': {
+    id: string;
+    progress: number;
+    logs: string[];
+    finished: boolean;
+    failed: string | undefined;
+  };
+  'get-app-details': {
+    appID: number;
+    storefront: string;
+  };
+  'search-app-name': {
+    query: string;
+    storefront: string;
+  };
+  flag: {
+    flag: string;
+    value: string | string[];
+  };
+}
+type BasicLibraryInfo = {
+  name: string;
+  capsuleImage: string;
+  appID: number;
+  storefront: string;
+};
+interface CatalogSection {
+  name: string;
+  description: string;
+  listings: BasicLibraryInfo[];
+}
+interface CatalogCarouselItem {
+  name: string;
+  description: string;
+  carouselImage: string;
+  fullBannerImage?: string;
+  appID?: number;
+  storefront?: string;
+  capsuleImage?: string;
+}
+interface CatalogWithCarousel {
+  sections: Record<string, CatalogSection>;
+  carousel?: Record<string, CatalogCarouselItem> | CatalogCarouselItem[];
+}
+type CatalogResponse = Record<string, CatalogSection> | CatalogWithCarousel;
+type SetupEventResponse = Omit<LibraryInfo, 'capsuleImage' | 'coverImage' | 'name' | 'appID' | 'storefront' | 'addonsource' | 'titleImage'> & {
+  redistributables?: {
+    name: string;
+    path: string;
+  }[];
+};
+interface EventListenerTypes {
+  /**
+   * This event is emitted when the addon connects to the OGI Addon Server. Addon does not need to resolve anything.
+   * @param event
+   * @returns
+   */
+  connect: (event: EventResponse<void>) => void;
+  /**
+   * This event is emitted when the client requests for the addon to disconnect. Addon does not need to resolve this event, but we recommend `process.exit(0)` so the addon can exit gracefully instead of by force by the addon server.
+   * @param reason
+   * @returns
+   */
+  disconnect: (reason: string) => void;
+  /**
+   * This event is emitted when the client requests for the addon to configure itself. Addon should resolve the event with the internal configuration. (See ConfigurationBuilder)
+   * @param config
+   * @returns
+   */
+  configure: (config: ConfigurationBuilder) => ConfigurationBuilder;
+  /**
+   * This event is called when the client provides a response to any event. This should be treated as middleware.
+   * @param response
+   * @returns
+   */
+  response: (response: any) => void;
+  /**
+   * This event is called when the client requests for the addon to authenticate itself. You don't need to provide any info.
+   * @param config
+   * @returns
+   */
+  authenticate: (config: any) => void;
+  /**
+   * This event is emitted when the client requests for a torrent/direct download search to be performed. Addon is given the gameID (could be a steam appID or custom store appID), along with the storefront type. Addon should resolve the event with the search results. (See SearchResult)
+   * @param query
+   * @param event
+   * @returns
+   */
+  search: (query: {
+    storefront: string;
+    appID: number;
+  } & ({
+    for: 'game' | 'task' | 'all';
+  } | {
+    for: 'update';
+    libraryInfo: LibraryInfo;
+  }), event: EventResponse<SearchResult[]>) => void;
+  /**
+   * This event is emitted when the client requests for app setup to be performed. Addon should resolve the event with the metadata for the library entry. (See LibraryInfo)
+   * @param data
+   * @param event
+   * @returns
+   */
+  setup: (data: {
+    path: string;
+    type: 'direct' | 'torrent' | 'magnet' | 'empty';
+    name: string;
+    usedRealDebrid: boolean;
+    clearOldFilesBeforeUpdate?: boolean;
+    multiPartFiles?: {
+      name: string;
+      downloadURL: string;
+    }[];
+    appID: number;
+    storefront: string;
+    manifest?: Record<string, unknown>;
+  } & ({
+    for: 'game';
+  } | {
+    for: 'update';
+    currentLibraryInfo: LibraryInfo;
+  }), event: EventResponse<SetupEventResponse>) => void;
+  /**
+   * This event is emitted when the client requires for a search to be performed. Input is the search query.
+   * @param query
+   * @param event
+   * @returns
+   */
+  'library-search': (query: string, event: EventResponse<BasicLibraryInfo[]>) => void;
+  /**
+   * This event is emitted when the client requests for a game details to be fetched. Addon should resolve the event with the game details. This is used to generate a store page for the game.
+   * @param appID
+   * @param event
+   * @returns
+   */
+  'game-details': (details: {
+    appID: number;
+    storefront: string;
+  }, event: EventResponse<StoreData | undefined>) => void;
+  /**
+   * This event is emitted when the client requests for the addon to exit. Use this to perform any cleanup tasks, ending with a `process.exit(0)`.
+   * @returns
+   */
+  exit: () => void;
+  /**
+   * This event is emitted when the client requests for a download to be performed with the 'request' type. Addon should resolve the event with a SearchResult containing the actual download info.
+   * @param appID
+   * @param info
+   * @param event
+   * @returns
+   */
+  'request-dl': (appID: number, info: SearchResult, event: EventResponse<SearchResult>) => void;
+  /**
+   * This event is emitted when the client requests for a catalog to be fetched. Addon should resolve the event with the catalog.
+   * @param event
+   * @returns
+   */
+  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.
+   * @param data
+   * @param event
+   * @returns
+   */
+  'check-for-updates': (data: {
+    appID: number;
+    storefront: string;
+    currentVersion: string;
+  }, event: EventResponse<{
+    available: true;
+    version: string;
+  } | {
+    available: false;
+  }>) => void;
+}
+interface StoreData {
+  name: string;
+  publishers: string[];
+  developers: string[];
+  appID: number;
+  releaseDate: string;
+  capsuleImage: string;
+  coverImage: string;
+  basicDescription: string;
+  description: string;
+  headerImage: string;
+  latestVersion: string;
+}
+interface WebsocketMessageClient {
+  event: OGIAddonClientSentEvent;
+  id?: string;
+  args: any;
+  statusError?: string;
+}
+interface WebsocketMessageServer {
+  event: OGIAddonServerSentEvent;
+  id?: string;
+  args: any;
+  statusError?: string;
+}
+/**
+ * The configuration for the addon. This is used to identify the addon and provide information about it.
+ * Storefronts is an array of names of stores that the addon supports.
+ */
+interface OGIAddonConfiguration {
+  name: string;
+  id: string;
+  description: string;
+  version: string;
+  author: string;
+  repository: string;
+  storefronts: string[];
+}
+/**
+ * The main class for the OGI Addon. This class is used to interact with the OGI Addon Server. The OGI Addon Server provides a `--addonSecret` to the addon so it can securely connect.
+ * @example
+ * ```typescript
+ * const addon = new OGIAddon({
+ *  name: 'Test Addon',
+ *   id: 'test-addon',
+ *  description: 'A test addon',
+ *  version: '1.0.0',
+ *  author: 'OGI Developers',
+ *  repository: ''
+ * });
+ * ```
+ *
+ */
+declare class OGIAddon {
+  eventEmitter: events<[never]>;
+  addonWSListener: OGIAddonWSListener;
+  addonInfo: OGIAddonConfiguration;
+  config: Configuration;
+  private eventsAvailable;
+  private registeredConnectEvent;
+  private taskHandlers;
+  constructor(addonInfo: OGIAddonConfiguration);
+  /**
+   * Register an event listener for the addon. (See EventListenerTypes)
+   * @param event {OGIAddonEvent}
+   * @param listener {EventListenerTypes[OGIAddonEvent]}
+   */
+  on<T extends OGIAddonEvent>(event: T, listener: EventListenerTypes[T]): void;
+  emit<T extends OGIAddonEvent>(event: T, ...args: Parameters<EventListenerTypes[T]>): void;
+  /**
+   * Notify the client using a notification. Provide the type of notification, the message, and an ID.
+   * @param notification {Notification}
+   */
+  notify(notification: Notification): void;
+  /**
+   * Get the app details for a given appID and storefront.
+   * @param appID {number}
+   * @param storefront {string}
+   * @returns {Promise<StoreData>}
+   */
+  getAppDetails(appID: number, storefront: string): Promise<StoreData | undefined>;
+  searchGame(query: string, storefront: string): Promise<BasicLibraryInfo[]>;
+  /**
+   * Notify the OGI Addon Server that you are performing a background task. This can be used to help users understand what is happening in the background.
+   * @returns {Promise<Task>} A Task instance for managing the background task.
+   */
+  task(): Promise<Task>;
+  /**
+   * Register a task handler for a specific task name. The task name should match the taskName field in SearchResult or ActionOption.
+   * @param taskName {string} The name of the task (should match taskName in SearchResult or ActionOption.setTaskName()).
+   * @param handler {(task: Task, data: { manifest: Record<string, unknown>; downloadPath: string; name: string; libraryInfo: LibraryInfo }) => Promise<void> | void} The handler function.
+   * @example
+   * ```typescript
+   * addon.onTask('clearCache', async (task) => {
+   *   task.log('Clearing cache...');
+   *   task.setProgress(50);
+   *   await clearCacheFiles();
+   *   task.setProgress(100);
+   *   task.complete();
+   * });
+   * ```
+   */
+  onTask(taskName: string, handler: (task: Task, data: {
+    manifest: Record<string, unknown>;
+    downloadPath: string;
+    name: string;
+    libraryInfo: LibraryInfo;
+  }) => Promise<void> | void): void;
+  /**
+   * Check if a task handler is registered for the given task name.
+   * @param taskName {string} The task name to check.
+   * @returns {boolean} True if a handler is registered.
+   */
+  hasTaskHandler(taskName: string): boolean;
+  /**
+   * Get a task handler for the given task name.
+   * @param taskName {string} The task name.
+   * @returns The handler function or undefined if not found.
+   */
+  getTaskHandler(taskName: string): ((task: Task, data: {
+    manifest: Record<string, unknown>;
+    downloadPath: string;
+    name: string;
+    libraryInfo?: LibraryInfo;
+  }) => Promise<void> | void) | undefined;
+  /**
+   * Extract a file using 7-Zip on Windows, unzip on Linux/Mac.
+   * @param path {string}
+   * @param outputPath {string}
+   * @param type {'unrar' | 'unzip'}
+   * @returns {Promise<void>}
+   */
+  extractFile(path: string, outputPath: string, type: 'unrar' | 'unzip'): Promise<void>;
+}
+/**
+ * A unified task API for both server-initiated tasks (via onTask handlers)
+ * and addon-initiated background tasks (via addon.task()).
+ * Provides chainable methods for logging, progress updates, and completion.
+ */
+declare class Task {
+  private event;
+  private ws;
+  private readonly id;
+  private progress;
+  private logs;
+  private finished;
+  private failed;
+  /**
+   * Construct a Task from an EventResponse (for onTask handlers).
+   * @param event {EventResponse<void>} The event response to wrap.
+   */
+  constructor(event: EventResponse<void>);
+  /**
+   * Construct a Task from WebSocket listener (for addon.task()).
+   * @param ws {OGIAddonWSListener} The WebSocket listener.
+   * @param id {string} The task ID.
+   * @param progress {number} Initial progress (0-100).
+   * @param logs {string[]} Initial logs array.
+   */
+  constructor(ws: OGIAddonWSListener, id: string, progress: number, logs: string[]);
+  /**
+   * Log a message to the task. Returns this for chaining.
+   * @param message {string} The message to log.
+   */
+  log(message: string): this;
+  /**
+   * Set the progress of the task (0-100). Returns this for chaining.
+   * @param progress {number} The progress value (0-100).
+   */
+  setProgress(progress: number): this;
+  /**
+   * Complete the task successfully.
+   */
+  complete(): void;
+  /**
+   * Fail the task with an error message.
+   * @param message {string} The error message.
+   */
+  fail(message: string): void;
+  /**
+   * Ask the user for input using a ConfigurationBuilder screen.
+   * Only available for EventResponse-based tasks (onTask handlers).
+   * The return type is inferred from the ConfigurationBuilder's accumulated option types.
+   * @param name {string} The name/title of the input prompt.
+   * @param description {string} The description of what input is needed.
+   * @param screen {ConfigurationBuilder<U>} The configuration builder for the input form.
+   * @returns {Promise<U>} The user's input with types matching the configuration options.
+   * @throws {Error} If called on a WebSocket-based task.
+   */
+  askForInput<U extends Record<string, string | number | boolean>>(name: string, description: string, screen: ConfigurationBuilder<U>): Promise<U>;
+  /**
+   * Update the task state (for WebSocket-based tasks only).
+   * Called automatically when using log(), setProgress(), complete(), or fail().
+   */
+  private update;
+}
+/**
+ * A search tool wrapper over Fuse.js for the OGI Addon. This tool is used to search for items in the library.
+ * @example
+ * ```typescript
+ * const searchTool = new SearchTool<LibraryInfo>([{ name: 'test', appID: 123 }, { name: 'test2', appID: 124 }], ['name']);
+ * const results = searchTool.search('test', 10);
+ * ```
+ */
+declare class SearchTool<T> {
+  private fuse;
+  constructor(items: T[], keys: string[], options?: Omit<IFuseOptions<T>, 'keys'>);
+  search(query: string, limit?: number): T[];
+  addItems(items: T[]): void;
+}
+/**
+ * Library Info is the metadata for a library entry after setting up a game.
+ */
+declare const ZodLibraryInfo: z.ZodObject<{
+  name: z.ZodString;
+  version: z.ZodString;
+  cwd: z.ZodString;
+  appID: z.ZodNumber;
+  launchExecutable: z.ZodString;
+  launchArguments: z.ZodOptional<z.ZodString>;
+  capsuleImage: z.ZodString;
+  storefront: z.ZodString;
+  addonsource: z.ZodString;
+  coverImage: z.ZodString;
+  titleImage: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  name: string;
+  version: string;
+  cwd: string;
+  appID: number;
+  launchExecutable: string;
+  capsuleImage: string;
+  storefront: string;
+  addonsource: string;
+  coverImage: string;
+  launchArguments?: string | undefined;
+  titleImage?: string | undefined;
+}, {
+  name: string;
+  version: string;
+  cwd: string;
+  appID: number;
+  launchExecutable: string;
+  capsuleImage: string;
+  storefront: string;
+  addonsource: string;
+  coverImage: string;
+  launchArguments?: string | undefined;
+  titleImage?: string | undefined;
+}>;
+type LibraryInfo = z.infer<typeof ZodLibraryInfo>;
+interface Notification {
+  type: 'warning' | 'error' | 'info' | 'success';
+  message: string;
+  id: string;
+}
+declare class OGIAddonWSListener {
+  private socket;
+  eventEmitter: events.EventEmitter;
+  addon: OGIAddon;
+  constructor(ogiAddon: OGIAddon, eventEmitter: events.EventEmitter);
+  private userInputAsked;
+  private registerMessageReceiver;
+  private waitForEventToRespond;
+  respondToMessage(messageID: string, response: any, originalEvent: EventResponse<any> | undefined): void;
+  waitForResponseFromServer<T>(messageID: string): Promise<T>;
+  send(event: OGIAddonClientSentEvent, args: ClientSentEventTypes[OGIAddonClientSentEvent]): string;
+  close(): void;
+}
+//#endregion
+export { BasicLibraryInfo, CatalogCarouselItem, CatalogResponse, CatalogSection, CatalogWithCarousel, ClientSentEventTypes, Configuration, ConfigurationBuilder, EventListenerTypes, EventResponse, LibraryInfo, OGIAddonClientSentEvent, OGIAddonConfiguration, OGIAddonEvent, OGIAddonServerSentEvent, type SearchResult, SearchTool, SetupEventResponse, StoreData, Task, VERSION, WebsocketMessageClient, WebsocketMessageServer, ZodLibraryInfo, OGIAddon as default };
+//# sourceMappingURL=main.d.cts.map