ogi-addon 1.0.0 → 1.1.0

package/src/config/ConfigurationBuilder.ts

@@ -24,6 +24,12 @@ export function isBooleanOption(option: ConfigurationOption): option is BooleanO
 
 export class ConfigurationBuilder {
   private options: ConfigurationOption[] = [];
+
+  /**
+   * Add a number option to the configuration builder and return the builder for chaining. You must provide a name, display name, and description for the option.
+   * @param option { (option: NumberOption) => NumberOption }
+   * @returns 
+   */
   public addNumberOption(option: (option: NumberOption) => NumberOption): ConfigurationBuilder {
     let newOption = new NumberOption();
     newOption = option(newOption);
@@ -31,6 +37,10 @@ export class ConfigurationBuilder {
     return this;
   }
 
+  /**
+   * Add a string option to the configuration builder and return the builder for chaining. You must provide a name, display name, and description for the option.
+   * @param option { (option: StringOption) => StringOption }
+  */
   public addStringOption(option: (option: StringOption) => StringOption) {
     let newOption = new StringOption();
     newOption = option(newOption);
@@ -38,6 +48,10 @@ export class ConfigurationBuilder {
     return this;
   }
 
+  /**
+   * Add a boolean option to the configuration builder and return the builder for chaining. You must provide a name, display name, and description for the option.
+   * @param option { (option: BooleanOption) => BooleanOption }
+  */
   public addBooleanOption(option: (option: BooleanOption) => BooleanOption) {
     let newOption = new BooleanOption();
     newOption = option(newOption);
@@ -74,22 +88,39 @@ export class ConfigurationOption {
   public description: string = '';
   public type: ConfigurationOptionType = 'unset'
   
+  /**
+   * Set the name of the option. **REQUIRED**
+   * @param name {string} The name of the option. This is used to reference the option in the configuration file.
+   */
   setName(name: string) {
     this.name = name;
     return this;
   }
 
+  /**
+   * Set the display name of the option. This is used to show the user a human readable version of what the option is. **REQUIRED** 
+   * @param displayName {string} The display name of the option. 
+   * @returns 
+   */
   setDisplayName(displayName: string) {
     this.displayName = displayName;
     return this;
   }
 
+  /**
+   * Set the description of the option. This is to show the user a brief description of what this option does. **REQUIRED**
+   * @param description {string} The description of the option. 
+   * @returns 
+   */
   setDescription(description: string) {
     this.description = description;
     return this;
   }
 
-
+  /**
+   * Validation code for the option. This is called when the user provides input to the option. If the validation fails, the user will be prompted to provide input again.
+   * @param input {unknown} The input to validate
+   */
   validate(input: unknown): [ boolean, string ] {
     throw new Error('Validation code not implemented. Value: ' + input)
   };
@@ -103,26 +134,46 @@ export class StringOption extends ConfigurationOption {
   public inputType: 'text' | 'file' | 'password' | 'folder' = 'text';
   public type: ConfigurationOptionType = 'string'
 
+  /**
+   * Set the allowed values for the string. If the array is empty, any value is allowed. When provided, the client will act like this option is a dropdown.  
+   * @param allowedValues {string[]} An array of allowed values for the string. If the array is empty, any value is allowed.
+   */
   setAllowedValues(allowedValues: string[]): this {
     this.allowedValues = allowedValues;
     return this;
   }
 
+  /**
+   * Set the default value for the string. This value will be used if the user does not provide a value. **HIGHLY RECOMMENDED**
+   * @param defaultValue {string} The default value for the string.
+   */
   setDefaultValue(defaultValue: string): this {
     this.defaultValue = defaultValue;
     return this;
   }
 
+  /**
+   * Set the minimum text length for the string. If the user provides a string that is less than this value, the validation will fail. 
+   * @param minTextLength {number} The minimum text length for the string. 
+   */
   setMinTextLength(minTextLength: number): this {
     this.minTextLength = minTextLength;
     return this;
   }
 
+  /**
+   * Set the maximum text length for the string. If the user provides a string that is greater than this value, the validation will fail. 
+   * @param maxTextLength {number} The maximum text length for the string.
+   */
   setMaxTextLength(maxTextLength: number): this {
     this.maxTextLength = maxTextLength;
     return this;
   }
 
+  /**
+   * Set the input type for the string. This will change how the client renders the input. 
+   * @param inputType {'text' | 'file' | 'password' | 'folder'} The input type for the string. 
+   */
   setInputType(inputType: 'text' | 'file' | 'password' | 'folder'): this {
     this.inputType = inputType;
     return this;
@@ -148,21 +199,38 @@ export class NumberOption extends ConfigurationOption {
   public defaultValue: number = 0;
   public type: ConfigurationOptionType = 'number'
   public inputType: 'range' | 'number' = 'number';
+
+  /**
+   * Set the minimum value for the number. If the user provides a number that is less than this value, the validation will fail.
+   * @param min {number} The minimum value for the number.
+   */
   setMin(min: number): this {
     this.min = min;
     return this;
   }
 
+  /**
+   * Set the input type for the number. This will change how the client renders the input. 
+   * @param type {'range' | 'number'} The input type for the number. 
+   */
   setInputType(type: 'range' | 'number'): this {
     this.inputType = type;
     return this;
   }
 
+  /**
+   * Set the maximum value for the number. If the user provides a number that is greater than this value, the validation will fail.
+   * @param max {number} The maximum value for the number.
+   */
   setMax(max: number): this {
     this.max = max;
     return this
   }
 
+  /**
+   * Set the default value for the number. This value will be used if the user does not provide a value. **HIGHLY RECOMMENDED**
+   * @param defaultValue {number} The default value for the number.
+   */
   setDefaultValue(defaultValue: number): this {
     this.defaultValue = defaultValue;
     return this;
@@ -184,6 +252,10 @@ export class BooleanOption extends ConfigurationOption {
   public type: ConfigurationOptionType = 'boolean'
   public defaultValue: boolean = false;
 
+  /**
+   * Set the default value for the boolean. This value will be used if the user does not provide a value. **HIGHLY RECOMMENDED**
+   * @param defaultValue {boolean} The default value for the boolean.
+   */
   setDefaultValue(defaultValue: boolean): this {
     this.defaultValue = defaultValue;
     return this;

package/src/main.ts

@@ -5,14 +5,14 @@ import { Configuration } from './config/Configuration';
 import EventResponse from './EventResponse';
 import { SearchResult } from './SearchEngine';
 
-export type OGIAddonEvent = 'connect' | 'disconnect' | 'configure' | 'authenticate' | 'search' | 'setup' | 'library-search' | 'game-details' | 'exit';
+export type OGIAddonEvent = 'connect' | 'disconnect' | 'configure' | 'authenticate' | 'search' | 'setup' | 'library-search' | 'game-details' | 'exit' | 'request-dl';
 export type OGIAddonClientSentEvent = 'response' | 'authenticate' | 'configure' | 'defer-update' | 'notification' | 'input-asked';
 
-export type OGIAddonServerSentEvent = 'authenticate' | 'configure' | 'config-update' | 'search' | 'setup' | 'response' | 'library-search' | 'game-details';
+export type OGIAddonServerSentEvent = 'authenticate' | 'configure' | 'config-update' | 'search' | 'setup' | 'response' | 'library-search' | 'game-details' | 'request-dl';
 export { ConfigurationBuilder, Configuration, EventResponse, SearchResult };
 const defaultPort = 7654;
 import pjson from '../package.json';
-const version = pjson.version;
+export const version = pjson.version;
 
 export interface ClientSentEventTypes {
   response: any;
@@ -33,12 +33,51 @@ export type BasicLibraryInfo = {
 }
 
 export 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, 
@@ -53,9 +92,17 @@ export interface EventListenerTypes {
       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;
 }
 
 export interface StoreData {
@@ -89,6 +136,22 @@ export 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: ''
+ * });
+ * ```
+ * 
+ */
 export default class OGIAddon {
   public eventEmitter = new events.EventEmitter();
   public addonWSListener: OGIAddonWSListener;
@@ -100,6 +163,11 @@ export default class OGIAddon {
     this.addonWSListener = new OGIAddonWSListener(this, this.eventEmitter);
   }
   
+  /**
+   * Register an event listener for the addon. (See EventListenerTypes) 
+   * @param event {OGIAddonEvent}
+   * @param listener {EventListenerTypes[OGIAddonEvent]} 
+   */
   public on<T extends OGIAddonEvent>(event: T, listener: EventListenerTypes[T]) {
     this.eventEmitter.on(event, listener);
   }
@@ -108,11 +176,18 @@ export default class OGIAddon {
     this.eventEmitter.emit(event, ...args);
   }
 
+  /**
+   * Notify the client using a notification. Provide the type of notification, the message, and an ID. 
+   * @param notification {Notification}
+   */
   public notify(notification: Notification) {
     this.addonWSListener.send('notification', [ notification ]);
   }
 }
 
+/**
+ * Library Info is the metadata for a library entry after setting up a game.
+ */
 export interface LibraryInfo {
   name: string;
   version: string;
@@ -266,8 +341,21 @@ class OGIAddonWSListener {
           const gameDetailsResult = await this.waitForEventToRespond(gameDetailsEvent);
           this.respondToMessage(message.id!!, gameDetailsResult.data);
           break
-      }
-    });
+        case 'request-dl':
+          let requestDLEvent = new EventResponse<SearchResult>((screen, name, description) => this.userInputAsked(screen, name, description, this.socket));
+          if (this.eventEmitter.listenerCount('request-dl') === 0) {
+            this.respondToMessage(message.id!!, { error: 'No event listener for request-dl' });
+            break;
+          }
+          this.eventEmitter.emit('request-dl', message.args.appID, message.args.info, requestDLEvent);
+          const requestDLResult = await this.waitForEventToRespond(requestDLEvent);
+          if (requestDLEvent.data === null || requestDLEvent.data?.downloadType === 'request') {
+            throw new Error('Request DL event did not return a valid result. Please ensure that the event does not resolve with another `request` download type.');
+          }
+          this.respondToMessage(message.id!!, requestDLResult.data);
+          break
+        }
+      });
   }
 
   private waitForEventToRespond<T>(event: EventResponse<T>): Promise<EventResponse<T>> {

package/tsconfig.json

@@ -5,7 +5,7 @@
       "ESNext",
       "DOM"
     ], // specifies which default set of type definitions to use ("DOM", "ES6", etc)
-    "removeComments": true, // Strips all comments from TypeScript files when converting into JavaScript- you rarely read compiled code so this saves space
+    "removeComments": false, // Strips all comments from TypeScript files when converting into JavaScript- you rarely read compiled code so this saves space
     "target": "ESNext", // Target environment. Most modern browsers support ES6, but you may want to set it to newer or older. (defaults to ES3)
     "declaration": true,