From 02e8b7d0a1212aad17f823a273bd9005f43038b6 Mon Sep 17 00:00:00 2001 From: DJj123dj <80536295+DJj123dj@users.noreply.github.com> Date: Thu, 9 Jan 2025 19:42:11 +0100 Subject: [PATCH] Added new API comments (part 3) --- src/core/api/modules/plugin.ts | 69 ++++++++++++++++++++++++++++++- src/core/api/modules/verifybar.ts | 22 +++++++++- 2 files changed, 88 insertions(+), 3 deletions(-) diff --git a/src/core/api/modules/plugin.ts b/src/core/api/modules/plugin.ts index 864f6fe..6bd03df 100644 --- a/src/core/api/modules/plugin.ts +++ b/src/core/api/modules/plugin.ts @@ -5,13 +5,29 @@ import { ODId, ODManager, ODManagerData, ODSystemError, ODValidId, ODVersion } f import nodepath from "path" import { ODConsolePluginMessage, ODConsoleWarningMessage, ODDebugger } from "./console" +/**## ODUnknownCrashedPlugin `interface` + * Basic details for a plugin that crashed while loading the `plugin.json` file. + */ export interface ODUnknownCrashedPlugin { + /**The name of the plugin. (path when plugin crashed before `name` was loaded) */ name:string, + /**The description of the plugin. (when found before crashing) */ description:string } +/**## ODPluginManager `class` + * This is an open ticket plugin manager. + * + * It manages all active plugins in the bot! + * It also contains all "plugin classes" which are managers registered by plugins. + * These are accessible via the `openticket.plugins.classes` global. + * + * Use `isPluginLoaded()` to check if a plugin has been loaded. + */ export class ODPluginManager extends ODManager { + /**A manager for all custom managers registered by plugins. */ classes: ODPluginClassManager + /**A list of basic details from all plugins that crashed while loading the `plugin.json` file. */ unknownCrashedPlugins: ODUnknownCrashedPlugin[] = [] constructor(debug:ODDebugger){ @@ -19,7 +35,7 @@ export class ODPluginManager extends ODManager { this.classes = new ODPluginClassManager(debug) } - /**Check if a plugin has loaded successfully.*/ + /**Check if a plugin has been loaded successfully and is available for usage.*/ isPluginLoaded(id:ODValidId): boolean { const newId = new ODId(id) const plugin = this.get(newId) @@ -27,43 +43,84 @@ export class ODPluginManager extends ODManager { } } +/**## ODPluginData `interface` + * Parsed data from the `plugin.json` file in a plugin. + */ export interface ODPluginData { + /**The name of this plugin (shown on startup) */ name:string, + /**The id of this plugin. (Must be identical to directory name) */ id:string, + /**The version of this plugin. */ version:string, + /**The location of the start file of the plugin relative to the rootDir of the plugin */ startFile:string, + /**Is this plugin enabled? */ enabled:boolean, + /**The priority of this plugin. Higher priority will load before lower priority. */ priority:number, + /**A list of events to register to the `openticket.events` global before loading any plugins. This way, plugins with a higher priority are able to use events from this plugin as well! */ events:string[] + /**Npm dependencies which are required for this plugin to work. */ npmDependencies:string[], + /**Plugins which are required for this plugin to work. */ requiredPlugins:string[], + /**Plugins which are incompatible with this plugin. */ incompatiblePlugins:string[], + /**Additional details about this plugin. */ details:ODPluginDetails } +/**## ODPluginDetails `interface` + * Additional details in the `plugin.json` file from a plugin. + */ export interface ODPluginDetails { + /**The author of the plugin. */ author:string, + /**A short description of this plugin. */ shortDescription:string, + /**A large description of this plugin. */ longDescription:string, + /**A URL to a cover image of this plugin. (currently unused) */ imageUrl:string, + /**A URL to the website/project page of this plugin. (currently unused) */ projectUrl:string, + /**A list of tags/categories that this plugin affects. */ tags:string[] } +/**## ODPlugin `class` + * This is an open ticket plugin. + * + * It represents a single plugin in the `./plugins/` directory. + * All plugins are accessible via the `openticket.plugins` global. + * + * Don't re-execute plugins which are already enabled! It might break the bot or plugin. + */ export class ODPlugin extends ODManagerData { + /**The name of the directory of this plugin. (same as id) */ dir: string + /**All plugin data found in the `plugin.json` file. */ data: ODPluginData + /**The name of this plugin. */ name: string + /**The priority of this plugin. */ priority: number + /**The version of this plugin. */ version: ODVersion + /**The additional details of this plugin. */ details: ODPluginDetails + /**Is this plugin enabled? */ enabled: boolean + /**Did this plugin execute successfully?. */ executed: boolean + /**Did this plugin crash? (A reason is available in the `crashReason`) */ crashed: boolean + /**The reason which caused this plugin to crash. */ crashReason: null|"incompatible.plugin"|"missing.plugin"|"missing.dependency"|"executed" = null constructor(dir:string, jsondata:ODPluginData){ @@ -160,6 +217,16 @@ export class ODPlugin extends ODManagerData { } } +/**## ODPluginClassManager `class` + * This is an open ticket plugin class manager. + * + * It manages all managers registered by plugins! + * Plugins are able to register their own managers, handlers, functions, classes, ... here. + * By doing this, other plugins are also able to make use of it. + * This can be useful for plugins that want to extend other plugins. + * + * Use `isPluginLoaded()` to check if a plugin has been loaded before trying to access the manager. + */ export class ODPluginClassManager extends ODManager { constructor(debug:ODDebugger){ super(debug,"plugin class") diff --git a/src/core/api/modules/verifybar.ts b/src/core/api/modules/verifybar.ts index 6d8a914..037d6d4 100644 --- a/src/core/api/modules/verifybar.ts +++ b/src/core/api/modules/verifybar.ts @@ -8,12 +8,21 @@ import { ODButtonResponderInstance } from "./responder" import * as discord from "discord.js" import { ODWorkerManager } from "./worker" -export type ODVerifyBarCallback = (responder:ODButtonResponderInstance,customData?:string) => void|Promise - +/**## ODVerifyBar `class` + * This is an open ticket verifybar. + * + * It is contains 2 sets of workers and a lot of utilities for the (✅ ❌) verifybars in the bot. + * + * It doesn't contain the code which activates or spawns the verifybars! + */ export class ODVerifyBar extends ODManagerData { + /**All workers that will run when the verifybar is accepted. */ success: ODWorkerManager|null}> + /**All workers that will run when the verifybar is stopped. */ failure: ODWorkerManager|null}> + /**The message that will be built wen activating this verifybar. */ message: ODMessage<"verifybar",{guild:discord.Guild|null,channel:discord.TextBasedChannel,user:discord.User,verifybar:ODVerifyBar,originalMessage:discord.Message}> + /**When disabled, it will skip the verifybar and instantly fire the `success` workers. */ enabled: boolean constructor(id:ODValidId, message:ODMessage<"verifybar",{guild:discord.Guild|null,channel:discord.TextBasedChannel,user:discord.User,originalMessage:discord.Message}>, enabled?:boolean){ @@ -24,6 +33,7 @@ export class ODVerifyBar extends ODManagerData { this.enabled = enabled ?? true } + /**Build the message and reply to a button with this verifybar. */ async activate(responder:ODButtonResponderInstance){ if (this.enabled){ //show verifybar @@ -36,6 +46,14 @@ export class ODVerifyBar extends ODManagerData { } } +/**## ODVerifyBarManager `class` + * This is an open ticket verifybar manager. + * + * It contains all (✅ ❌) verifybars in the bot. + * The `ODVerifyBar` classes contain `ODWorkerManager`'s that will be fired when the continue/stop buttons are pressed. + * + * It doesn't contain the code which activates the verifybars! This should be implemented by your own. + */ export class ODVerifyBarManager extends ODManager { constructor(debug:ODDebugger){ super(debug,"verifybar")