@open-discord-bots/framework 0.2.17 → 0.3.1

package/dist/api/modules/session.d.ts

@@ -41,16 +41,25 @@ export type ODSessionTimeoutCallback = (id: string, timeout: "default" | "custom
 /**## ODSession `class`
  * This is an Open Discord session.
  *
- * It can be used to create 100% unique id's for usage in the bot. An id can also store additional data which isn't saved to the filesystem.
+ * It can be used to create unique user sessions with an ID. Each session can store additional data which isn't saved to the filesystem.
  * You can almost compare it to the PHP session system.
  */
 export declare class ODSession extends ODManagerData {
-    #private;
+    /**The history of previously generated instance ids. Used to reduce the risk of generating the same id twice. */
+    protected idHistory: string[];
+    /**The max length of the instance id history. */
+    protected maxIdHistoryLength: number;
     /**An array of all the currently active session instances. */
     sessions: ODSessionInstance[];
     /**The default amount of minutes before a session automatically stops. */
     timeoutMinutes: number;
+    /**The id of the auto-timeout session checker interval */
+    protected intervalId: NodeJS.Timeout;
+    /**Listeners for when a session times-out. */
+    protected timeoutListeners: ODSessionTimeoutCallback[];
     constructor(id: ODValidId, intervalSeconds?: number);
+    /**Create a unique hex id of 8 characters and add it to the instance id history */
+    protected createUniqueId(): string;
     /**Stop the global interval that automatically deletes timed-out sessions. (This action can't be reverted!) */
     stopAutoTimeout(): void;
     /**Start a session instance with data. Returns the unique id required to access the session. */

package/dist/api/modules/session.js

@@ -28,26 +28,26 @@ export class ODSessionManager extends ODManager {
 /**## ODSession `class`
  * This is an Open Discord session.
  *
- * It can be used to create 100% unique id's for usage in the bot. An id can also store additional data which isn't saved to the filesystem.
+ * It can be used to create unique user sessions with an ID. Each session can store additional data which isn't saved to the filesystem.
  * You can almost compare it to the PHP session system.
  */
 export class ODSession extends ODManagerData {
     /**The history of previously generated instance ids. Used to reduce the risk of generating the same id twice. */
-    #idHistory = [];
+    idHistory = [];
     /**The max length of the instance id history. */
-    #maxIdHistoryLength = 500;
+    maxIdHistoryLength = 500;
     /**An array of all the currently active session instances. */
     sessions = [];
     /**The default amount of minutes before a session automatically stops. */
     timeoutMinutes = 30;
     /**The id of the auto-timeout session checker interval */
-    #intervalId;
+    intervalId;
     /**Listeners for when a session times-out. */
-    #timeoutListeners = [];
+    timeoutListeners = [];
     constructor(id, intervalSeconds) {
         super(id);
         //create the auto-timeout session checker
-        this.#intervalId = setInterval(() => {
+        this.intervalId = setInterval(() => {
             const deletableSessions = [];
             //collect all deletable sessions
             this.sessions.forEach((session) => {
@@ -65,30 +65,30 @@ export class ODSession extends ODManagerData {
                 const index = this.sessions.findIndex((s) => s.id === session.instance.id);
                 this.sessions.splice(index, 1);
                 //emit timeout listeners
-                this.#timeoutListeners.forEach((cb) => cb(session.instance.id, session.reason, session.instance.data, new Date(session.instance.creation)));
+                this.timeoutListeners.forEach((cb) => cb(session.instance.id, session.reason, session.instance.data, new Date(session.instance.creation)));
             });
         }, ((intervalSeconds) ? (intervalSeconds * 1000) : 60000));
     }
     /**Create a unique hex id of 8 characters and add it to the instance id history */
-    #createUniqueId() {
+    createUniqueId() {
         const hex = crypto.randomBytes(4).toString("hex");
-        if (this.#idHistory.includes(hex)) {
-            return this.#createUniqueId();
+        if (this.idHistory.includes(hex)) {
+            return this.createUniqueId();
         }
         else {
-            this.#idHistory.push(hex);
-            if (this.#idHistory.length > this.#maxIdHistoryLength)
-                this.#idHistory.shift();
+            this.idHistory.push(hex);
+            if (this.idHistory.length > this.maxIdHistoryLength)
+                this.idHistory.shift();
             return hex;
         }
     }
     /**Stop the global interval that automatically deletes timed-out sessions. (This action can't be reverted!) */
     stopAutoTimeout() {
-        clearInterval(this.#intervalId);
+        clearInterval(this.intervalId);
     }
     /**Start a session instance with data. Returns the unique id required to access the session. */
     start(data) {
-        const id = this.#createUniqueId();
+        const id = this.createUniqueId();
         this.sessions.push({
             id, data,
             creation: new Date().getTime(),
@@ -137,6 +137,6 @@ export class ODSession extends ODManagerData {
     }
     /**Listen for a session timeout (default or custom) */
     onTimeout(callback) {
-        this.#timeoutListeners.push(callback);
+        this.timeoutListeners.push(callback);
     }
 }

package/dist/api/modules/startscreen.d.ts

@@ -17,7 +17,6 @@ export type ODStartScreenManagerIdConstraint = Record<string, ODStartScreenCompo
  * The startscreen is the part you see when the bot has started up successfully. (e.g. the Open Discord logo, logs, livestatus, flags, ...)
  */
 export declare class ODStartScreenManager<IdList extends ODStartScreenManagerIdConstraint = ODStartScreenManagerIdConstraint, LiveStatus extends ODLiveStatusManager = ODLiveStatusManager> extends ODManager<ODStartScreenComponent> {
-    #private;
     /**Alias to the livestatus manager. */
     livestatus: LiveStatus;
     constructor(debug: ODDebugger, livestatus: LiveStatus);
@@ -40,7 +39,7 @@ export declare class ODStartScreenManager<IdList extends ODStartScreenManagerIdC
  *
  * It's recommended to use pre-built components except if you really need a custom one.
  */
-export declare class ODStartScreenComponent extends ODManagerData {
+export declare abstract class ODStartScreenComponent extends ODManagerData {
     /**The priority of this component. */
     priority: number;
     /**An optional render function which will be inserted before the default renderer. */
@@ -49,7 +48,7 @@ export declare class ODStartScreenComponent extends ODManagerData {
     render: ODStartScreenComponentRenderCallback;
     /**An optional render function which will be inserted behind the default renderer. */
     renderAfter: ODStartScreenComponentRenderCallback | null;
-    constructor(id: ODValidId, priority: number, render: ODStartScreenComponentRenderCallback);
+    constructor(id: ODValidId, priority: number, render: ODStartScreenComponentRenderCallback, renderBefore?: ODStartScreenComponentRenderCallback, renderAfter?: ODStartScreenComponentRenderCallback);
     /**Render this component and combine it with the `renderBefore` & `renderAfter` contents. */
     renderAll(location: number): Promise<string>;
 }

package/dist/api/modules/startscreen.js

@@ -11,13 +11,10 @@ import ansis from "ansis";
  * The startscreen is the part you see when the bot has started up successfully. (e.g. the Open Discord logo, logs, livestatus, flags, ...)
  */
 export class ODStartScreenManager extends ODManager {
-    /**Alias to the Open Discord debugger. */
-    #debug;
     /**Alias to the livestatus manager. */
     livestatus;
     constructor(debug, livestatus) {
         super(debug, "startscreen component");
-        this.#debug = debug;
         this.livestatus = livestatus;
     }
     /**Get all components in sorted order. */
@@ -37,11 +34,11 @@ export class ODStartScreenManager extends ODManager {
             try {
                 const renderedText = await component.renderAll(location);
                 console.log(renderedText);
-                this.#debug.console.debugfile.writeText("[STARTSCREEN] Component: \"" + component.id + "\"\n" + ansis.strip(renderedText));
+                this.debug?.console.debugfile.writeText("[STARTSCREEN] Component: \"" + component.id + "\"\n" + ansis.strip(renderedText));
             }
             catch (e) {
-                this.#debug.console.log("Unable to render \"" + component.id + "\" startscreen component!", "error");
-                this.#debug.console.debugfile.writeErrorMessage(new ODError(e, "uncaughtException"));
+                this.debug?.console.log("Unable to render \"" + component.id + "\" startscreen component!", "error");
+                this.debug?.console.debugfile.writeErrorMessage(new ODError(e, "uncaughtException"));
             }
             location++;
         }
@@ -68,15 +65,17 @@ export class ODStartScreenComponent extends ODManagerData {
     /**The priority of this component. */
     priority;
     /**An optional render function which will be inserted before the default renderer. */
-    renderBefore = null;
+    renderBefore;
     /**The render function which will render the contents of this component. */
     render;
     /**An optional render function which will be inserted behind the default renderer. */
-    renderAfter = null;
-    constructor(id, priority, render) {
+    renderAfter;
+    constructor(id, priority, render, renderBefore, renderAfter) {
         super(id);
         this.priority = priority;
         this.render = render;
+        this.renderBefore = renderBefore ?? null;
+        this.renderAfter = renderAfter ?? null;
     }
     /**Render this component and combine it with the `renderBefore` & `renderAfter` contents. */
     async renderAll(location) {

package/dist/api/modules/statistic.d.ts

@@ -29,9 +29,10 @@ export type ODStatisticManagerIdConstraint = Record<string, ODStatisticScope>;
  * Statistic can be accessed in the individual scopes.
  */
 export declare class ODStatisticManager<IdList extends ODStatisticManagerIdConstraint = ODStatisticManagerIdConstraint> extends ODManager<ODStatisticScope> {
-    #private;
     /**Alias to Open Discord statistics database. */
     database: ODDatabase<ODDatabaseIdConstraint> | null;
+    /**All the listeners for the init event. */
+    protected initListeners: ODStatisticManagerInitCallback[];
     constructor(debug: ODDebugger);
     /**Select the database to use to read/write all statistics from/to. */
     useDatabase(database: ODDatabase<ODDatabaseIdConstraint>): void;

package/dist/api/modules/statistic.js

@@ -11,22 +11,19 @@ import { ODId, ODManager, ODManagerData, ODSystemError } from "./base.js";
  * Statistic can be accessed in the individual scopes.
  */
 export class ODStatisticManager extends ODManager {
-    /**Alias to Open Discord debugger. */
-    #debug;
     /**Alias to Open Discord statistics database. */
     database = null;
     /**All the listeners for the init event. */
-    #initListeners = [];
+    initListeners = [];
     constructor(debug) {
         super(debug, "statistic scope");
-        this.#debug = debug;
     }
     /**Select the database to use to read/write all statistics from/to. */
     useDatabase(database) {
         this.database = database;
     }
     add(data, overwrite) {
-        data.useDebug(this.#debug, "stat");
+        data.useDebug(this.debug, "stat");
         if (this.database)
             data.useDatabase(this.database);
         return super.add(data, overwrite);
@@ -48,7 +45,7 @@ export class ODStatisticManager extends ODManager {
                 deletableStats.push(data);
         });
         //do additional deletion
-        for (const cb of this.#initListeners) {
+        for (const cb of this.initListeners) {
             await cb(data, deletableStats);
         }
         //delete all deletable statistics
@@ -69,7 +66,7 @@ export class ODStatisticManager extends ODManager {
     }
     /**Run a function when the statistics are initialized. This can be used to clear statistics from users that left the server or tickets which don't exist anymore. */
     onInit(callback) {
-        this.#initListeners.push(callback);
+        this.initListeners.push(callback);
     }
     get(id) {
         return super.get(id);

package/dist/api/modules/worker.d.ts

@@ -28,7 +28,8 @@ export declare class ODWorker<Instance, Origin extends string, Params> extends O
  * You can register a custom worker in this class to create a message or button.
  */
 export declare class ODWorkerManager<Instance, Origin extends string, Params, WorkerIds extends string = string> extends ODManager<ODWorker<Instance, Origin, Params>> {
-    #private;
+    /**The order of execution for workers inside this manager. */
+    protected priorityOrder: "ascending" | "descending";
     /**The backup worker will be executed when one of the workers fails or cancels execution. */
     backupWorker: ODWorker<{
         reason: "error" | "cancel";

package/dist/api/modules/worker.js

@@ -32,12 +32,12 @@ export class ODWorker extends ODManagerData {
  */
 export class ODWorkerManager extends ODManager {
     /**The order of execution for workers inside this manager. */
-    #priorityOrder;
+    priorityOrder;
     /**The backup worker will be executed when one of the workers fails or cancels execution. */
     backupWorker = null;
     constructor(priorityOrder) {
         super();
-        this.#priorityOrder = priorityOrder;
+        this.priorityOrder = priorityOrder;
     }
     /**Get all workers in sorted order. */
     getSortedWorkers(priority) {
@@ -52,7 +52,7 @@ export class ODWorkerManager extends ODManager {
     /**Execute all workers on an instance using the given origin & parameters. */
     async executeWorkers(instance, origin, params) {
         const derefParams = { ...params };
-        const workers = this.getSortedWorkers(this.#priorityOrder);
+        const workers = this.getSortedWorkers(this.priorityOrder);
         let didCancel = false;
         let didCrash = false;
         for (const worker of workers) {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@open-discord-bots/framework",
     "author": "DJj123dj",
-    "version": "0.2.17",
+    "version": "0.3.1",
     "description": "The core framework of the popular open-source discord bots: Open Ticket & Open Moderation.",
     "main": "dist/index.js",
     "module": "dist/index.js",
@@ -16,7 +16,8 @@
         "@types/terminal-kit": "^2.5.7",
         "ansis": "^4.2.0",
         "discord.js": "^14.26.3",
-        "formatted-json-stringify": "^1.3.0",
+        "formatted-json-stringify": "^1.3.1",
+        "jsonc": "^2.0.0",
         "terminal-kit": "^3.1.2",
         "typescript": "^6.0.3"
     },

package/src/api/index.ts

@@ -2,28 +2,29 @@
 export * from "./main.js"
 
 //BASE MODULES
+export * from "./modules/action.js"
 export * from "./modules/base.js"
-export * from "./modules/event.js"
+export * from "./modules/builder.js"
+export * from "./modules/checker.js"
+export * from "./modules/client.js"
+export * from "./modules/code.js"
+export * from "./modules/component.js"
 export * from "./modules/config.js"
+export * from "./modules/console.js"
+export * from "./modules/cooldown.js"
 export * from "./modules/database.js"
-export * from "./modules/language.js"
+export * from "./modules/event.js"
 export * from "./modules/flag.js"
-export * from "./modules/console.js"
 export * from "./modules/fuse.js"
+export * from "./modules/helpmenu.js"
+export * from "./modules/language.js"
+export * from "./modules/permission.js"
 export * from "./modules/plugin.js"
-export * from "./modules/checker.js"
-export * from "./modules/client.js"
-export * from "./modules/worker.js"
-export * from "./modules/builder.js"
+export * from "./modules/post.js"
+export * from "./modules/progressbar.js"
 export * from "./modules/responder.js"
-export * from "./modules/action.js"
-export * from "./modules/permission.js"
-export * from "./modules/helpmenu.js"
 export * from "./modules/session.js"
+export * from "./modules/startscreen.js"
 export * from "./modules/statistic.js"
-export * from "./modules/code.js"
-export * from "./modules/cooldown.js"
-export * from "./modules/post.js"
 export * from "./modules/verifybar.js"
-export * from "./modules/progressbar.js"
-export * from "./modules/startscreen.js"
+export * from "./modules/worker.js"

package/src/api/main.ts

@@ -23,12 +23,13 @@ import { ODPostManager } from "./modules/post.js"
 import { ODClientManager } from "./modules/client.js"
 import { ODSharedFuseManager } from "./modules/fuse.js"
 import { ODStartScreenManager } from "./modules/startscreen.js"
+import { ODComponentManager } from "./modules/component.js"
 
 /**## ODMainManagers `interface`
  * The global properties for the main class of the bot.
  */
 export interface ODMainManagers {
-    /**The manager that handles all versions in the bot. */
+    /**A collection of versions of the bot, systems, frameworks & services. */
     versions: ODVersionManager
 
     /**The timestamp that the (node.js) process of the bot started. */
@@ -49,49 +50,55 @@ export interface ODMainManagers {
     plugins: ODPluginManager
     /**The manager that manages & checks all the console flags of the bot. (like `--debug`) */
     flags: ODFlagManager
-    /**The manager responsible for progress bars in the console. */
+    /**The manager responsible for displaying progress bars in the console. */
     progressbars: ODProgressBarManager
-    /**The manager that manages & contains all the config files of the bot. (like `config/general.json`) */
+    /**A collection of all the config files of the bot and plugins. (like `config/general.json`) */
     configs: ODConfigManager
-    /**The manager that manages & contains all the databases of the bot. (like `database/global.json`) */
+    /**A collection of all the databases of the bot and plugins. (like `database/global.json`) */
     databases: ODDatabaseManager
-    /**The manager that manages all the data sessions of the bot. (it's a temporary database) */
+    /**A collection of all the sessions of the bot. (Sessions are temporary objects stored in memory) */
     sessions: ODSessionManager
-    /**The manager that manages all languages & translations of the bot. (but not for plugins) */
+    /**The global translation manager which manges all language files, translations & switches between them. (Does not manage translations for plugins) */
     languages: ODLanguageManager
     
-    /**The manager that handles & executes all config checkers in the bot. (the code that checks if you have something wrong in your config) */
+    /**The manager responsible for checking the bot & plugin configs. (it checks for mistakes in your config) */
     checkers: ODCheckerManager
-    /**The manager that manages all builders in the bot. (e.g. buttons, dropdowns, messages, modals, etc) */
+    /**A collection of button, dropdown, embed, ... templates which can be used to construct messages and modals.
+     * ### (🚨 Better alternative: `opendiscord.components (ODComponentManager)`)
+     */
     builders: ODBuilderManager
-    /**The manager that manages all responders in the bot. (e.g. commands, buttons, dropdowns, modals) */
+    /**A collection of building blocks and templates for messages & modals with native support for Discord Components v2. (e.g. buttons, dropdowns, checkboxes, radio groups, file uploads, ...)
+     * ### (✅ New replacement for: `opendiscord.builders (ODBuilderManager)`)
+     */
+    components: ODComponentManager
+    /**The manager that handles responses to all interactions of the bot. (e.g. slash/text commands, buttons, dropdowns, modals) */
     responders: ODResponderManager
-    /**The manager that manages all actions or procedures in the bot. (e.g. ticket-creation, ticket-deletion, ticket-claiming, etc) */
+    /**A collection of procedures. A procedure is a complex task which can be executed from multiple responders or events. (e.g. ticket-creation, ticket-deletion, ticket-claiming, ...) */
     actions: ODActionManager
-    /**The manager that manages all verify bars in the bot. (the ✅ ❌ buttons) */
+    /**A collection of verify bars from the bot. (the ✅ ❌ buttons in messages) */
     verifybars: ODVerifyBarManager
-    /**The manager that contains all permissions for commands & actions in the bot. (use it to check if someone has admin perms or not) */
+    /**A manager which will help with calculating permissions for commands & actions. */
     permissions: ODPermissionManager
-    /**The manager that contains all cooldowns of the bot. (e.g. ticket-cooldowns) */
+    /**The manager which will manage cooldowns in the bot. (e.g. ticket-create cooldowns) */
     cooldowns: ODCooldownManager
-    /**The manager that manages & renders the Open Discord help menu. (not the embed, but the text) */
+    /**The manager that collects & renders the Open Discord help menu contents. (not the final embed) */
     helpmenu: ODHelpMenuManager
-    /**The manager that manages, saves & renders the Open Discord statistics. (not the embed, but the text & database) */
+    /**The manager that registers, saves & updates statistics in the database. */
     statistics: ODStatisticManager
-    /**This manager is a place where you can put code that executes when the bot almost finishes the setup. (can be used for less important stuff that doesn't require an exact time-order) */
+    /**A place where you can put general-purpose code which will start on startup of the bot. (Perfect for background tasks) */
     code: ODCodeManager
-    /**The manager that manages all posts (static discord channels) in the bot. (e.g. transcripts, logs, etc) */
+    /**A collection of static Discord post channels. It allows the bot to find back log, transcript or configured channels based on a linked ID. */
     posts: ODPostManager
     
-    /**The manager responsible for everything related to the client. (e.g. status, login, slash & text commands, etc) */
+    /**A wrapper around the `discord.Client` class. It handles client login, activity and registering text/slash commands. */
     client: ODClientManager
-    /**Shared fuses between Open Discord bots. With these fuses/switches, you can turn off "default behaviours" from the bot. Useful for replacing default behaviour with a custom implementation.  */
+    /**Shared fuses between Open Discord bots. Turn off "default behaviours" from the bot which is useful for replacing default behaviour with a custom implementation.  */
     sharedFuses: ODSharedFuseManager
-    /**This manager manages all the variables in the ENV. It reads from both the `.env` file & the `process.env`. (these 2 will be combined)  */
+    /**A manager which collects variables from the Process ENV and `.env` file. */
     env: ODEnvHelper
-    /**The manager responsible for the livestatus system. (remote console logs) */
+    /**LiveStatus is a protocol which displays live updates from DJdj Development in the startscreen of the bot. (e.g. new version available) */
     livestatus: ODLiveStatusManager
-    /**The manager responsible for the livestatus system. (remote console logs) */
+    /**The manager responsible for rendering the startscreen of the bot. */
     startscreen: ODStartScreenManager
 }
 
@@ -101,7 +108,7 @@ export interface ODMainManagers {
  * 
  * This class can't be overwritten or extended & is available as the global variable `opendiscord`!
  */
-export class ODMain implements ODMainManagers {
+export abstract class ODMain implements ODMainManagers {
     readonly project: ODProjectType
 
     readonly versions: ODVersionManager
@@ -123,6 +130,7 @@ export class ODMain implements ODMainManagers {
     
     readonly checkers: ODCheckerManager
     readonly builders: ODBuilderManager
+    readonly components: ODComponentManager
     readonly responders: ODResponderManager
     readonly actions: ODActionManager
     readonly verifybars: ODVerifyBarManager
@@ -142,7 +150,7 @@ export class ODMain implements ODMainManagers {
     constructor(managers:ODMainManagers,project:ODProjectType){
         this.project = project
         this.versions = managers.versions
-        this.versions.add(ODVersion.fromString("opendiscord:api","v0.2.17"))
+        this.versions.add(ODVersion.fromString("opendiscord:api","v0.3.1"))
         this.versions.add(ODVersion.fromString("opendiscord:livestatus","v2.0.0"))
 
         this.debugfile = managers.debugfile
@@ -160,6 +168,7 @@ export class ODMain implements ODMainManagers {
         
         this.checkers = managers.checkers
         this.builders = managers.builders
+        this.components = managers.components
         this.client = managers.client
         this.responders = managers.responders
         this.actions = managers.actions

package/src/api/modules/action.ts

@@ -12,7 +12,7 @@ import { ODDebugger } from "./console.js"
  * 
  * This class can't be used stand-alone & needs to be extended from!
  */
-export class ODActionImplementation<Origin extends string,Params extends object,Result extends object,WorkerIds extends string = string> extends ODManagerData {
+export abstract class ODActionImplementation<Origin extends string,Params extends object,Result extends object,WorkerIds extends string = string> extends ODManagerData {
     /**The manager that has all workers of this implementation */
     workers: ODWorkerManager<Partial<Result>,Origin,Params,WorkerIds>
 
@@ -22,9 +22,7 @@ export class ODActionImplementation<Origin extends string,Params extends object,
         if (callback) this.workers.add(new ODWorker(callbackId ? callbackId : id,priority ?? 0,callback))
     }
     /**Execute all workers & return the result. */
-    async run(origin:Origin, params:Params): Promise<Partial<Result>> {
-        throw new ODSystemError("Tried to build an unimplemented ODResponderImplementation")
-    }
+    abstract run(origin:Origin, params:Params): Promise<Partial<Result>>
 }
 
 /**## ODActionManagerIdConstraint `type`