ogi-addon 1.0.0 → 1.1.5

package/build/main.d.cts

@@ -5,13 +5,20 @@ import { Configuration } from './config/Configuration.cjs';
 import EventResponse from './EventResponse.cjs';
 import { SearchResult } from './SearchEngine.cjs';
 
-type OGIAddonEvent = 'connect' | 'disconnect' | 'configure' | 'authenticate' | 'search' | 'setup' | 'library-search' | 'game-details' | 'exit';
-type OGIAddonClientSentEvent = 'response' | 'authenticate' | 'configure' | 'defer-update' | 'notification' | 'input-asked';
-type OGIAddonServerSentEvent = 'authenticate' | 'configure' | 'config-update' | 'search' | 'setup' | 'response' | 'library-search' | 'game-details';
+type OGIAddonEvent = 'connect' | 'disconnect' | 'configure' | 'authenticate' | 'search' | 'setup' | 'library-search' | 'game-details' | 'exit' | 'request-dl';
+type OGIAddonClientSentEvent = 'response' | 'authenticate' | 'configure' | 'defer-update' | 'notification' | 'input-asked' | 'steam-search' | 'task-update';
+type OGIAddonServerSentEvent = 'authenticate' | 'configure' | 'config-update' | 'search' | 'setup' | 'response' | 'library-search' | 'game-details' | 'request-dl';
 
+declare const VERSION: string;
 interface ClientSentEventTypes {
     response: any;
-    authenticate: any;
+    authenticate: {
+        name: string;
+        id: string;
+        description: string;
+        version: string;
+        author: string;
+    };
     configure: ConfigurationFile;
     'defer-update': {
         logs: string[];
@@ -19,6 +26,16 @@ interface ClientSentEventTypes {
     };
     notification: Notification;
     'input-asked': ConfigurationBuilder;
+    'steam-search': {
+        query: string;
+        strict: boolean;
+    };
+    'task-update': {
+        id: string;
+        progress: number;
+        logs: string[];
+        finished: boolean;
+    };
 }
 type BasicLibraryInfo = {
     name: string;
@@ -26,15 +43,52 @@ type BasicLibraryInfo = {
     appID: number;
 };
 interface EventListenerTypes {
+    /**
+     * This event is emitted when the addon connects to the OGI Addon Server. Addon does not need to resolve anything.
+     * @param socket
+     * @returns
+     */
     connect: (socket: ws) => 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: {
         type: 'steamapp' | 'internal';
         text: string;
     }, 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';
@@ -47,9 +101,16 @@ interface EventListenerTypes {
         appID: number;
         storefront: 'steam' | 'internal';
     }, event: EventResponse<LibraryInfo>) => 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;
     'game-details': (appID: number, event: EventResponse<StoreData>) => void;
     exit: () => void;
+    'request-dl': (appID: number, info: SearchResult, event: EventResponse<SearchResult>) => void;
 }
 interface StoreData {
     name: string;
@@ -81,16 +142,82 @@ interface OGIAddonConfiguration {
     author: string;
     repository: 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;
     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;
+    /**
+     * Search for items in the OGI Steam-Synced Library. Query can either be a Steam AppID or a Steam Game Name.
+     * @param query {string}
+     * @param event {EventResponse<BasicLibraryInfo[]>}
+     */
+    steamSearch(query: string, strict?: boolean): Promise<Omit<BasicLibraryInfo, "capsuleImage">[]>;
+    /**
+     * 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.
+     * @param id {string}
+     * @param progress {number}
+     * @param logs {string[]}
+     */
+    task(): Promise<CustomTask>;
+}
+declare class CustomTask {
+    readonly id: string;
+    progress: number;
+    logs: string[];
+    finished: boolean;
+    ws: OGIAddonWSListener;
+    constructor(ws: OGIAddonWSListener, id: string, progress: number, logs: string[]);
+    log(log: string): void;
+    finish(): void;
+    setProgress(progress: number): void;
+    update(): void;
+}
+/**
+ * A search tool for the OGI Addon. This tool is used to search for items in the library. Powered by Fuse.js, bundled into OGI.
+ * @example
+ * ```typescript
+ * const searchTool = new SearchTool<LibraryInfo>([], ['name']);
+ * const results = searchTool.search('test', 10);
+ * ```
+ */
+declare class SearchTool<T> {
+    private fuse;
+    constructor(items: T[], keys: string[]);
+    search(query: string, limit?: number): T[];
+    addItems(items: T[]): void;
 }
+/**
+ * Library Info is the metadata for a library entry after setting up a game.
+ */
 interface LibraryInfo {
     name: string;
     version: string;
@@ -119,8 +246,8 @@ declare class OGIAddonWSListener {
     private waitForEventToRespond;
     respondToMessage(messageID: string, response: any): void;
     waitForResponseFromServer<T>(messageID: string): Promise<T>;
-    send(event: OGIAddonClientSentEvent, args: Parameters<ClientSentEventTypes[OGIAddonClientSentEvent]>): void;
+    send(event: OGIAddonClientSentEvent, args: ClientSentEventTypes[OGIAddonClientSentEvent]): string;
     close(): void;
 }
 
-export { type BasicLibraryInfo, type ClientSentEventTypes, Configuration, ConfigurationBuilder, type EventListenerTypes, EventResponse, type LibraryInfo, type OGIAddonClientSentEvent, type OGIAddonConfiguration, type OGIAddonEvent, type OGIAddonServerSentEvent, SearchResult, type StoreData, type WebsocketMessageClient, type WebsocketMessageServer, OGIAddon as default };
+export { type BasicLibraryInfo, type ClientSentEventTypes, Configuration, ConfigurationBuilder, type EventListenerTypes, EventResponse, type LibraryInfo, type OGIAddonClientSentEvent, type OGIAddonConfiguration, type OGIAddonEvent, type OGIAddonServerSentEvent, SearchResult, SearchTool, type StoreData, VERSION, type WebsocketMessageClient, type WebsocketMessageServer, OGIAddon as default };

package/build/main.d.ts

@@ -5,13 +5,20 @@ import { Configuration } from './config/Configuration.js';
 import EventResponse from './EventResponse.js';
 import { SearchResult } from './SearchEngine.js';
 
-type OGIAddonEvent = 'connect' | 'disconnect' | 'configure' | 'authenticate' | 'search' | 'setup' | 'library-search' | 'game-details' | 'exit';
-type OGIAddonClientSentEvent = 'response' | 'authenticate' | 'configure' | 'defer-update' | 'notification' | 'input-asked';
-type OGIAddonServerSentEvent = 'authenticate' | 'configure' | 'config-update' | 'search' | 'setup' | 'response' | 'library-search' | 'game-details';
+type OGIAddonEvent = 'connect' | 'disconnect' | 'configure' | 'authenticate' | 'search' | 'setup' | 'library-search' | 'game-details' | 'exit' | 'request-dl';
+type OGIAddonClientSentEvent = 'response' | 'authenticate' | 'configure' | 'defer-update' | 'notification' | 'input-asked' | 'steam-search' | 'task-update';
+type OGIAddonServerSentEvent = 'authenticate' | 'configure' | 'config-update' | 'search' | 'setup' | 'response' | 'library-search' | 'game-details' | 'request-dl';
 
+declare const VERSION: string;
 interface ClientSentEventTypes {
     response: any;
-    authenticate: any;
+    authenticate: {
+        name: string;
+        id: string;
+        description: string;
+        version: string;
+        author: string;
+    };
     configure: ConfigurationFile;
     'defer-update': {
         logs: string[];
@@ -19,6 +26,16 @@ interface ClientSentEventTypes {
     };
     notification: Notification;
     'input-asked': ConfigurationBuilder;
+    'steam-search': {
+        query: string;
+        strict: boolean;
+    };
+    'task-update': {
+        id: string;
+        progress: number;
+        logs: string[];
+        finished: boolean;
+    };
 }
 type BasicLibraryInfo = {
     name: string;
@@ -26,15 +43,52 @@ type BasicLibraryInfo = {
     appID: number;
 };
 interface EventListenerTypes {
+    /**
+     * This event is emitted when the addon connects to the OGI Addon Server. Addon does not need to resolve anything.
+     * @param socket
+     * @returns
+     */
     connect: (socket: ws) => 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: {
         type: 'steamapp' | 'internal';
         text: string;
     }, 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';
@@ -47,9 +101,16 @@ interface EventListenerTypes {
         appID: number;
         storefront: 'steam' | 'internal';
     }, event: EventResponse<LibraryInfo>) => 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;
     'game-details': (appID: number, event: EventResponse<StoreData>) => void;
     exit: () => void;
+    'request-dl': (appID: number, info: SearchResult, event: EventResponse<SearchResult>) => void;
 }
 interface StoreData {
     name: string;
@@ -81,16 +142,82 @@ interface OGIAddonConfiguration {
     author: string;
     repository: 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;
     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;
+    /**
+     * Search for items in the OGI Steam-Synced Library. Query can either be a Steam AppID or a Steam Game Name.
+     * @param query {string}
+     * @param event {EventResponse<BasicLibraryInfo[]>}
+     */
+    steamSearch(query: string, strict?: boolean): Promise<Omit<BasicLibraryInfo, "capsuleImage">[]>;
+    /**
+     * 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.
+     * @param id {string}
+     * @param progress {number}
+     * @param logs {string[]}
+     */
+    task(): Promise<CustomTask>;
+}
+declare class CustomTask {
+    readonly id: string;
+    progress: number;
+    logs: string[];
+    finished: boolean;
+    ws: OGIAddonWSListener;
+    constructor(ws: OGIAddonWSListener, id: string, progress: number, logs: string[]);
+    log(log: string): void;
+    finish(): void;
+    setProgress(progress: number): void;
+    update(): void;
+}
+/**
+ * A search tool for the OGI Addon. This tool is used to search for items in the library. Powered by Fuse.js, bundled into OGI.
+ * @example
+ * ```typescript
+ * const searchTool = new SearchTool<LibraryInfo>([], ['name']);
+ * const results = searchTool.search('test', 10);
+ * ```
+ */
+declare class SearchTool<T> {
+    private fuse;
+    constructor(items: T[], keys: string[]);
+    search(query: string, limit?: number): T[];
+    addItems(items: T[]): void;
 }
+/**
+ * Library Info is the metadata for a library entry after setting up a game.
+ */
 interface LibraryInfo {
     name: string;
     version: string;
@@ -119,8 +246,8 @@ declare class OGIAddonWSListener {
     private waitForEventToRespond;
     respondToMessage(messageID: string, response: any): void;
     waitForResponseFromServer<T>(messageID: string): Promise<T>;
-    send(event: OGIAddonClientSentEvent, args: Parameters<ClientSentEventTypes[OGIAddonClientSentEvent]>): void;
+    send(event: OGIAddonClientSentEvent, args: ClientSentEventTypes[OGIAddonClientSentEvent]): string;
     close(): void;
 }
 
-export { type BasicLibraryInfo, type ClientSentEventTypes, Configuration, ConfigurationBuilder, type EventListenerTypes, EventResponse, type LibraryInfo, type OGIAddonClientSentEvent, type OGIAddonConfiguration, type OGIAddonEvent, type OGIAddonServerSentEvent, SearchResult, type StoreData, type WebsocketMessageClient, type WebsocketMessageServer, OGIAddon as default };
+export { type BasicLibraryInfo, type ClientSentEventTypes, Configuration, ConfigurationBuilder, type EventListenerTypes, EventResponse, type LibraryInfo, type OGIAddonClientSentEvent, type OGIAddonConfiguration, type OGIAddonEvent, type OGIAddonServerSentEvent, SearchResult, SearchTool, type StoreData, VERSION, type WebsocketMessageClient, type WebsocketMessageServer, OGIAddon as default };