@open-discord-bots/framework 0.0.1 → 0.0.2

package/dist/api/modules/stat.js

@@ -0,0 +1,293 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ODDynamicStat = exports.ODBasicStat = exports.ODStat = exports.ODStatGlobalScope = exports.ODStatScope = exports.ODStatsManager = void 0;
+///////////////////////////////////////
+//STAT MODULE
+///////////////////////////////////////
+const base_1 = require("./base");
+/**## ODStatsManager `class`
+ * This is an Open Discord stats manager.
+ *
+ * This class is responsible for managing all stats of the bot.
+ * Stats are categorized in "scopes" which can be accessed in this manager.
+ *
+ * Stats can be accessed in the individual scopes.
+ */
+class ODStatsManager extends base_1.ODManager {
+    /**Alias to Open Discord debugger. */
+    #debug;
+    /**Alias to Open Discord stats database. */
+    database = null;
+    /**All the listeners for the init event. */
+    #initListeners = [];
+    constructor(debug) {
+        super(debug, "stat scope");
+        this.#debug = debug;
+    }
+    /**Select the database to use to read/write all stats from/to. */
+    useDatabase(database) {
+        this.database = database;
+    }
+    add(data, overwrite) {
+        data.useDebug(this.#debug, "stat");
+        if (this.database)
+            data.useDatabase(this.database);
+        return super.add(data, overwrite);
+    }
+    /**Init all stats and run `onInit()` listeners. */
+    async init() {
+        if (!this.database)
+            throw new base_1.ODSystemError("Unable to initialize stats scopes due to missing database!");
+        //get all valid categories
+        const validCategories = [];
+        for (const scope of this.getAll()) {
+            validCategories.push(...scope.init());
+        }
+        //filter out the deletable stats
+        const deletableStats = [];
+        const data = await this.database.getAll();
+        data.forEach((data) => {
+            if (!validCategories.includes(data.category))
+                deletableStats.push(data);
+        });
+        //do additional deletion
+        for (const cb of this.#initListeners) {
+            await cb(data, deletableStats);
+        }
+        //delete all deletable stats
+        for (const data of deletableStats) {
+            if (!this.database)
+                return;
+            await this.database.delete(data.category, data.key);
+        }
+    }
+    /**Reset all stats. (clears the entire database) */
+    async reset() {
+        if (!this.database)
+            return;
+        const data = await this.database.getAll();
+        for (const d of data) {
+            if (!this.database)
+                return;
+            await this.database.delete(d.category, d.key);
+        }
+    }
+    /**Run a function when the stats are initialized. This can be used to clear stats from users that left the server or tickets which don't exist anymore. */
+    onInit(callback) {
+        this.#initListeners.push(callback);
+    }
+}
+exports.ODStatsManager = ODStatsManager;
+/**## ODStatScope `class`
+ * This is an Open Discord stat scope.
+ *
+ * A scope can contain multiple stats. Every scope is seperated from other scopes.
+ * Here, you can read & write the values of all stats.
+ *
+ * The built-in Open Discord scopes are: `global`, `user`, `ticket`
+ */
+class ODStatScope extends base_1.ODManager {
+    /**The id of this statistics scope. */
+    id;
+    /**Is this stat scope already initialized? */
+    ready = false;
+    /**Alias to Open Discord stats database. */
+    database = null;
+    /**The name of this scope (used in embed title) */
+    name;
+    constructor(id, name) {
+        super();
+        this.id = new base_1.ODId(id);
+        this.name = name;
+    }
+    /**Select the database to use to read/write all stats from/to. (Automatically assigned when used in `ODStatsManager`) */
+    useDatabase(database) {
+        this.database = database;
+    }
+    /**Get the value of a statistic. The `scopeId` is the unique id of the user, channel, role, etc that the stats are related to. */
+    async getStat(id, scopeId) {
+        if (!this.database)
+            return null;
+        const newId = new base_1.ODId(id);
+        const data = await this.database.get(this.id.value + "_" + newId.value, scopeId);
+        if (typeof data == "undefined") {
+            //set stats to default value & return
+            return this.resetStat(id, scopeId);
+        }
+        else if (typeof data == "string" || typeof data == "boolean" || typeof data == "number") {
+            //return value received from database
+            return data;
+        }
+        //return null on error
+        return null;
+    }
+    /**Get the value of a statistic for all `scopeId`'s. The `scopeId` is the unique id of the user, channel, role, etc that the stats are related to. */
+    async getAllStats(id) {
+        if (!this.database)
+            return [];
+        const newId = new base_1.ODId(id);
+        const data = await this.database.getCategory(this.id.value + "_" + newId.value) ?? [];
+        const output = [];
+        for (const stat of data) {
+            if (typeof stat.value == "string" || typeof stat.value == "boolean" || typeof stat.value == "number") {
+                //return value received from database
+                output.push({ id: stat.key, value: stat.value });
+            }
+        }
+        //return null on error
+        return output;
+    }
+    /**Set, increase or decrease the value of a statistic. The `scopeId` is the unique id of the user, channel, role, etc that the stats are related to. */
+    async setStat(id, scopeId, value, mode) {
+        if (!this.database)
+            return false;
+        const stat = this.get(id);
+        if (!stat)
+            return false;
+        if (mode == "set" || typeof value != "number") {
+            await this.database.set(this.id.value + "_" + stat.id.value, scopeId, value);
+        }
+        else if (mode == "increase") {
+            const currentValue = await this.getStat(id, scopeId);
+            if (typeof currentValue != "number")
+                await this.database.set(this.id.value + "_" + stat.id.value, scopeId, 0 + value);
+            else
+                await this.database.set(this.id.value + "_" + stat.id.value, scopeId, currentValue + value);
+        }
+        else if (mode == "decrease") {
+            const currentValue = await this.getStat(id, scopeId);
+            if (typeof currentValue != "number")
+                await this.database.set(this.id.value + "_" + stat.id.value, scopeId, 0 - value);
+            else
+                await this.database.set(this.id.value + "_" + stat.id.value, scopeId, currentValue - value);
+        }
+        return true;
+    }
+    /**Reset the value of a statistic to the initial value. The `scopeId` is the unique id of the user, channel, role, etc that the stats are related to. */
+    async resetStat(id, scopeId) {
+        if (!this.database)
+            return null;
+        const stat = this.get(id);
+        if (!stat)
+            return null;
+        if (stat.value != null)
+            await this.database.set(this.id.value + "_" + stat.id.value, scopeId, stat.value);
+        return stat.value;
+    }
+    /**Initialize this stat scope & return a list of all statistic ids in the following format: `<scopeid>_<statid>`  */
+    init() {
+        //get all valid stats categories
+        this.ready = true;
+        return this.getAll().map((stat) => this.id.value + "_" + stat.id.value);
+    }
+    /**Render all stats in this scope for usage in a discord message/embed. */
+    async render(scopeId, guild, channel, user) {
+        //sort from high priority to low
+        const derefArray = [...this.getAll()];
+        derefArray.sort((a, b) => {
+            return b.priority - a.priority;
+        });
+        const result = [];
+        for (const stat of derefArray) {
+            try {
+                if (stat instanceof ODDynamicStat) {
+                    //dynamic render (without value)
+                    result.push(await stat.render("", scopeId, guild, channel, user));
+                }
+                else {
+                    //normal render (with value)
+                    const value = await this.getStat(stat.id, scopeId);
+                    if (value != null)
+                        result.push(await stat.render(value, scopeId, guild, channel, user));
+                }
+            }
+            catch (err) {
+                process.emit("uncaughtException", err);
+            }
+        }
+        return result.filter((stat) => stat !== "").join("\n");
+    }
+}
+exports.ODStatScope = ODStatScope;
+/**## ODStatGlobalScope `class`
+ * This is an Open Discord stat global scope.
+ *
+ * A scope can contain multiple stats. Every scope is seperated from other scopes.
+ * Here, you can read & write the values of all stats.
+ *
+ * This scope is made specifically for the global stats of Open Discord.
+ */
+class ODStatGlobalScope extends ODStatScope {
+    getStat(id) {
+        return super.getStat(id, "GLOBAL");
+    }
+    getAllStats(id) {
+        return super.getAllStats(id);
+    }
+    setStat(id, value, mode) {
+        return super.setStat(id, "GLOBAL", value, mode);
+    }
+    resetStat(id) {
+        return super.resetStat(id, "GLOBAL");
+    }
+    render(scopeId, guild, channel, user) {
+        return super.render("GLOBAL", guild, channel, user);
+    }
+}
+exports.ODStatGlobalScope = ODStatGlobalScope;
+/**## ODStat `class`
+ * This is an Open Discord statistic.
+ *
+ * This single statistic doesn't do anything except defining the rules of this statistic.
+ * Use it in a stats scope to register a new statistic. A statistic can also include a priority to choose the render priority.
+ *
+ * It's recommended to use the `ODBasicStat` & `ODDynamicStat` classes instead of this one!
+ */
+class ODStat extends base_1.ODManagerData {
+    /**The priority of this statistic. */
+    priority;
+    /**The render function of this statistic. */
+    render;
+    /**The value of this statistic. */
+    value;
+    constructor(id, priority, render, value) {
+        super(id);
+        this.priority = priority;
+        this.render = render;
+        this.value = value ?? null;
+    }
+}
+exports.ODStat = ODStat;
+/**## ODBasicStat `class`
+ * This is an Open Discord basic statistic.
+ *
+ * This single statistic will store a number, boolean or string in the database.
+ * Use it to create a simple statistic for any stats scope.
+ */
+class ODBasicStat extends ODStat {
+    /**The name of this stat. Rendered in discord embeds/messages. */
+    name;
+    constructor(id, priority, name, value) {
+        super(id, priority, (value) => {
+            return "" + name + ": `" + value.toString() + "`";
+        }, value);
+        this.name = name;
+    }
+}
+exports.ODBasicStat = ODBasicStat;
+/**## ODDynamicStat `class`
+ * This is an Open Discord dynamic statistic.
+ *
+ * A dynamic statistic does not store anything in the database! Instead, it will execute a function to return a custom result.
+ * This can be used to show statistics which are not stored in the database.
+ *
+ * This is used in Open Discord for the live ticket status, participants & system status.
+ */
+class ODDynamicStat extends ODStat {
+    constructor(id, priority, render) {
+        super(id, priority, (value, scopeId, guild, channel, user) => {
+            return render(scopeId, guild, channel, user);
+        });
+    }
+}
+exports.ODDynamicStat = ODDynamicStat;

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

@@ -0,0 +1,54 @@
+import { ODManager, ODManagerData, ODValidId } from "./base";
+import { ODMessage } from "./builder";
+import { ODDebugger } from "./console";
+import { ODButtonResponderInstance } from "./responder";
+import * as discord from "discord.js";
+import { ODWorkerManager } from "./worker";
+/**## ODVerifyBar `class`
+ * This is an Open Discord 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 declare class ODVerifyBar extends ODManagerData {
+    /**All workers that will run when the verifybar is accepted. */
+    success: ODWorkerManager<ODButtonResponderInstance, "verifybar", {
+        data: string | null;
+        verifybarMessage: discord.Message<boolean> | null;
+    }>;
+    /**All workers that will run when the verifybar is stopped. */
+    failure: ODWorkerManager<ODButtonResponderInstance, "verifybar", {
+        data: string | null;
+        verifybarMessage: discord.Message<boolean> | 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<boolean>;
+    }>;
+    /**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<boolean>;
+    }>, enabled?: boolean);
+    /**Build the message and reply to a button with this verifybar. */
+    activate(responder: ODButtonResponderInstance): Promise<void>;
+}
+/**## ODVerifyBarManager `class`
+ * This is an Open Discord 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 declare class ODVerifyBarManager extends ODManager<ODVerifyBar> {
+    constructor(debug: ODDebugger);
+}

package/dist/api/modules/verifybar.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ODVerifyBarManager = exports.ODVerifyBar = void 0;
+///////////////////////////////////////
+//VERIFYBAR MODULE
+///////////////////////////////////////
+const base_1 = require("./base");
+const worker_1 = require("./worker");
+/**## ODVerifyBar `class`
+ * This is an Open Discord 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!
+ */
+class ODVerifyBar extends base_1.ODManagerData {
+    /**All workers that will run when the verifybar is accepted. */
+    success;
+    /**All workers that will run when the verifybar is stopped. */
+    failure;
+    /**The message that will be built wen activating this verifybar. */
+    message;
+    /**When disabled, it will skip the verifybar and instantly fire the `success` workers. */
+    enabled;
+    constructor(id, message, enabled) {
+        super(id);
+        this.success = new worker_1.ODWorkerManager("descending");
+        this.failure = new worker_1.ODWorkerManager("descending");
+        this.message = message;
+        this.enabled = enabled ?? true;
+    }
+    /**Build the message and reply to a button with this verifybar. */
+    async activate(responder) {
+        if (this.enabled) {
+            //show verifybar
+            const { guild, channel, user, message } = responder;
+            await responder.update(await this.message.build("verifybar", { guild, channel, user, verifybar: this, originalMessage: message }));
+        }
+        else {
+            //instant success
+            if (this.success)
+                await this.success.executeWorkers(responder, "verifybar", { data: null, verifybarMessage: null });
+        }
+    }
+}
+exports.ODVerifyBar = ODVerifyBar;
+/**## ODVerifyBarManager `class`
+ * This is an Open Discord 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.
+ */
+class ODVerifyBarManager extends base_1.ODManager {
+    constructor(debug) {
+        super(debug, "verifybar");
+    }
+}
+exports.ODVerifyBarManager = ODVerifyBarManager;

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

@@ -0,0 +1,41 @@
+import { ODManager, ODManagerData, ODValidId } from "./base";
+/**## ODWorkerCallback `type`
+ * This is the callback used in `ODWorker`!
+ */
+export type ODWorkerCallback<Instance, Source extends string, Params> = (instance: Instance, params: Params, source: Source, cancel: () => void) => void | Promise<void>;
+/**## ODWorker `class`
+ * This is an Open Discord worker.
+ *
+ * You can compare it with a normal javascript callback, but slightly more advanced!
+ *
+ * - It has an `id` for identification of the function
+ * - A `priority` to know when to execute this callback (related to others)
+ * - It knows who called this callback (`source`)
+ * - And much more!
+ */
+export declare class ODWorker<Instance, Source extends string, Params> extends ODManagerData {
+    /**The priority of this worker */
+    priority: number;
+    /**The main callback of this worker */
+    callback: ODWorkerCallback<Instance, Source, Params>;
+    constructor(id: ODValidId, priority: number, callback: ODWorkerCallback<Instance, Source, Params>);
+}
+/**## ODWorker `class`
+ * This is an Open Discord worker manager.
+ *
+ * It manages & executes `ODWorker`'s in the correct order.
+ *
+ * You can register a custom worker in this class to create a message or button.
+ */
+export declare class ODWorkerManager<Instance, Source extends string, Params> extends ODManager<ODWorker<Instance, Source, Params>> {
+    #private;
+    /**The backup worker will be executed when one of the workers fails or cancels execution. */
+    backupWorker: ODWorker<{
+        reason: "error" | "cancel";
+    }, Source, Params> | null;
+    constructor(priorityOrder: "ascending" | "descending");
+    /**Get all workers in sorted order. */
+    getSortedWorkers(priority: "ascending" | "descending"): ODWorker<Instance, Source, Params>[];
+    /**Execute all workers on an instance using the given source & parameters. */
+    executeWorkers(instance: Instance, source: Source, params: Params): Promise<void>;
+}

package/dist/api/modules/worker.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ODWorkerManager = exports.ODWorker = void 0;
+///////////////////////////////////////
+//WORKER MODULE
+///////////////////////////////////////
+const base_1 = require("./base");
+/**## ODWorker `class`
+ * This is an Open Discord worker.
+ *
+ * You can compare it with a normal javascript callback, but slightly more advanced!
+ *
+ * - It has an `id` for identification of the function
+ * - A `priority` to know when to execute this callback (related to others)
+ * - It knows who called this callback (`source`)
+ * - And much more!
+ */
+class ODWorker extends base_1.ODManagerData {
+    /**The priority of this worker */
+    priority;
+    /**The main callback of this worker */
+    callback;
+    constructor(id, priority, callback) {
+        super(id);
+        this.priority = priority;
+        this.callback = callback;
+    }
+}
+exports.ODWorker = ODWorker;
+/**## ODWorker `class`
+ * This is an Open Discord worker manager.
+ *
+ * It manages & executes `ODWorker`'s in the correct order.
+ *
+ * You can register a custom worker in this class to create a message or button.
+ */
+class ODWorkerManager extends base_1.ODManager {
+    /**The order of execution for workers inside this manager. */
+    #priorityOrder;
+    /**The backup worker will be executed when one of the workers fails or cancels execution. */
+    backupWorker = null;
+    constructor(priorityOrder) {
+        super();
+        this.#priorityOrder = priorityOrder;
+    }
+    /**Get all workers in sorted order. */
+    getSortedWorkers(priority) {
+        const derefArray = [...this.getAll()];
+        return derefArray.sort((a, b) => {
+            if (priority == "ascending")
+                return a.priority - b.priority;
+            else
+                return b.priority - a.priority;
+        });
+    }
+    /**Execute all workers on an instance using the given source & parameters. */
+    async executeWorkers(instance, source, params) {
+        const derefParams = { ...params };
+        const workers = this.getSortedWorkers(this.#priorityOrder);
+        let didCancel = false;
+        let didCrash = false;
+        for (const worker of workers) {
+            if (didCancel)
+                break;
+            try {
+                await worker.callback(instance, derefParams, source, () => {
+                    didCancel = true;
+                });
+            }
+            catch (err) {
+                process.emit("uncaughtException", err);
+                didCrash = true;
+            }
+        }
+        if (didCancel && this.backupWorker) {
+            try {
+                await this.backupWorker.callback({ reason: "cancel" }, derefParams, source, () => { });
+            }
+            catch (err) {
+                process.emit("uncaughtException", err);
+            }
+        }
+        else if (didCrash && this.backupWorker) {
+            try {
+                await this.backupWorker.callback({ reason: "error" }, derefParams, source, () => { });
+            }
+            catch (err) {
+                process.emit("uncaughtException", err);
+            }
+        }
+    }
+}
+exports.ODWorkerManager = ODWorkerManager;

package/dist/api/utils.d.ts

@@ -0,0 +1,61 @@
+import * as api from "./api";
+/**## sharedFuses `utility variable`
+ * All shared fuses from Open Discord. Please use `opendiscord.sharedFuses` instead!
+ */
+export declare const sharedFuses: api.ODSharedFuseManager;
+/**## checkNodeVersion `utility function`
+ * Check if the node.js version is v20 or higher.
+ */
+export declare function checkNodeVersion(project: api.ODProjectType): void;
+/**## moduleInstalled `utility function`
+ * Use this function to check if an npm package is installed or not!
+ * @example utilities.moduleInstalled("discord.js") //check if discord.js is installed
+ */
+export declare function moduleInstalled(id: string, throwError?: boolean): boolean;
+/**## initialStartupLogs `utility function`
+ * Use this function to check if an npm package is installed or not!
+ * @example utilities.moduleInstalled("discord.js") //check if discord.js is installed
+ */
+export declare function initialStartupLogs(opendiscord: api.ODMain, project: api.ODProjectType): void;
+/**## timer `utility function`
+ * Use this to wait for a certain amount of milliseconds. This only works when using `await`
+ * @example await utilities.timer(1000) //wait 1sec
+ */
+export declare function timer(ms: number): Promise<void>;
+/**## emojiTitle `utility function`
+ * Use this function to create a title with an emoji before/after the text. The style & divider are set in `opendiscord.sharedFuses`
+ * @example utilities.emojiTitle("📎","Links") //create a title with an emoji based on the bot emoji style
+ */
+export declare function emojiTitle(emoji: string, text: string): string;
+/**## runAsync `utility function`
+ * Use this function to run a snippet of code asyncronous without creating a separate function for it!
+ */
+export declare function runAsync(func: () => Promise<void>): Promise<void>;
+/**## timedAwait `utility function`
+ * Use this function to await a promise but reject after the certain timeout has been reached.
+ */
+export declare function timedAwait<ReturnValue>(promise: ReturnValue, timeout: number, onError: (err: Error) => void): ReturnValue;
+/**## dateString `utility function`
+ * Use this function to create a short date string in the following format: `DD/MM/YYYY HH:MM:SS`
+ */
+export declare function dateString(date: any): string;
+/**## asyncReplace `utility function`
+ * Same as `string.replace(search, value)` but with async compatibility
+ */
+export declare function asyncReplace(text: string, regex: RegExp, func: (value: string, ...args: any[]) => Promise<string>): Promise<string>;
+/**## getLongestLength `utility function`
+ * Get the length of the longest string in the array.
+ */
+export declare function getLongestLength(texts: string[]): number;
+/**## ordinalNumber `utility function`
+ * Get a human readable ordinal number (e.g. 1st, 2nd, 3rd, 4th, ...) from a Javascript number.
+ */
+export declare function ordinalNumber(num: number): string;
+/**## trimEmojis `utility function`
+ * Trim/remove all emoji's from a Javascript string.
+ */
+export declare function trimEmojis(text: any): any;
+/**## easterEggs `utility object`
+ * Object containing data for Open Ticket easter eggs.
+ */
+export declare const easterEggs: api.ODEasterEggs;