@open-discord-bots/framework 0.0.1 → 0.0.2

package/dist/api/modules/startscreen.js

@@ -0,0 +1,293 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ODStartScreenLogCategoryComponent = exports.ODStartScreenLiveStatusCategoryComponent = exports.ODStartScreenPluginsCategoryComponent = exports.ODStartScreenFlagsCategoryComponent = exports.ODStartScreenPropertiesCategoryComponent = exports.ODStartScreenCategoryComponent = exports.ODStartScreenHeaderComponent = exports.ODStartScreenLogoComponent = exports.ODStartScreenComponent = exports.ODStartScreenManager = void 0;
+///////////////////////////////////////
+//STARTSCREEN MODULE
+///////////////////////////////////////
+const base_1 = require("./base");
+const console_1 = require("./console");
+const ansis_1 = __importDefault(require("ansis"));
+/**## ODStartScreenManager `class`
+ * This is an Open Discord startscreen manager.
+ *
+ * This class is responsible for managing & rendering the startscreen of the bot.
+ * The startscreen is the part you see when the bot has started up successfully. (e.g. the Open Discord logo, logs, livestatus, flags, ...)
+ */
+class ODStartScreenManager extends base_1.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. */
+    getSortedComponents(priority) {
+        return this.getAll().sort((a, b) => {
+            if (priority == "ascending")
+                return a.priority - b.priority;
+            else
+                return b.priority - a.priority;
+        });
+    }
+    /**Render all startscreen components in priority order. */
+    async renderAllComponents() {
+        const components = this.getSortedComponents("descending");
+        let location = 0;
+        for (const component of components) {
+            try {
+                const renderedText = await component.renderAll(location);
+                console.log(renderedText);
+                this.#debug.console.debugfile.writeText("[STARTSCREEN] Component: \"" + component.id + "\"\n" + ansis_1.default.strip(renderedText));
+            }
+            catch (e) {
+                this.#debug.console.log("Unable to render \"" + component.id + "\" startscreen component!", "error");
+                this.#debug.console.debugfile.writeErrorMessage(new console_1.ODError(e, "uncaughtException"));
+            }
+            location++;
+        }
+    }
+}
+exports.ODStartScreenManager = ODStartScreenManager;
+/**## ODStartScreenComponent `class`
+ * This is an Open Discord startscreen component.
+ *
+ * This component can be rendered to the start screen of the bot.
+ * An optional priority can be specified to choose the location of the component.
+ *
+ * It's recommended to use pre-built components except if you really need a custom one.
+ */
+class ODStartScreenComponent extends base_1.ODManagerData {
+    /**The priority of this component. */
+    priority;
+    /**An optional render function which will be inserted before the default renderer. */
+    renderBefore = null;
+    /**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) {
+        super(id);
+        this.priority = priority;
+        this.render = render;
+    }
+    /**Render this component and combine it with the `renderBefore` & `renderAfter` contents. */
+    async renderAll(location) {
+        const textBefore = (this.renderBefore) ? await this.renderBefore(location) : "";
+        const text = await this.render(location);
+        const textAfter = (this.renderAfter) ? await this.renderAfter(location) : "";
+        return (textBefore ? textBefore + "\n" : "") + text + (textAfter ? "\n" + textAfter : "");
+    }
+}
+exports.ODStartScreenComponent = ODStartScreenComponent;
+/**## ODStartScreenLogoComponent `class`
+ * This is an Open Discord startscreen logo component.
+ *
+ * This component will render an ASCII art logo (from an array) to the startscreen. Every property in the array is another row.
+ * An optional priority can be specified to choose the location of the component.
+ */
+class ODStartScreenLogoComponent extends ODStartScreenComponent {
+    /**The ASCII logo contents. */
+    logo;
+    /**When enabled, the component will add a new line above the logo. */
+    topPadding;
+    /**When enabled, the component will add a new line below the logo. */
+    bottomPadding;
+    /**The color of the logo in hex format. */
+    logoHexColor;
+    constructor(id, priority, logo, topPadding, bottomPadding, logoHexColor) {
+        super(id, priority, () => {
+            const renderedTop = (this.topPadding ? "\n" : "");
+            const renderedLogo = this.logo.join("\n");
+            const renderedBottom = (this.bottomPadding ? "\n" : "");
+            return ansis_1.default.hex(this.logoHexColor)(renderedTop + renderedLogo + renderedBottom);
+        });
+        this.logo = logo;
+        this.topPadding = topPadding ?? false;
+        this.bottomPadding = bottomPadding ?? false;
+        this.logoHexColor = logoHexColor ?? "#f8ba00";
+    }
+}
+exports.ODStartScreenLogoComponent = ODStartScreenLogoComponent;
+/**## ODStartScreenHeaderComponent `class`
+ * This is an Open Discord startscreen header component.
+ *
+ * This component will render a header to the startscreen. Properties can be aligned left, right or centered.
+ * An optional priority can be specified to choose the location of the component.
+ */
+class ODStartScreenHeaderComponent extends ODStartScreenComponent {
+    /**All properties of this header component. */
+    properties;
+    /**The spacer used between properties. */
+    spacer;
+    /**The alignment settings of this header component. */
+    align;
+    constructor(id, priority, properties, spacer, align) {
+        super(id, priority, async () => {
+            const renderedProperties = ansis_1.default.bold(this.properties.map((prop) => prop.key + ": " + prop.value).join(this.spacer));
+            if (!this.align || this.align.align == "left") {
+                return renderedProperties;
+            }
+            else if (this.align.align == "right") {
+                const width = (typeof this.align.width == "number") ? this.align.width : (ansis_1.default.strip(await this.align.width.renderAll(0)).split("\n").map((row) => row.length).reduce((prev, curr) => {
+                    if (prev < curr)
+                        return curr;
+                    else
+                        return prev;
+                }, 0));
+                const offset = width - ansis_1.default.strip(renderedProperties).length;
+                if (offset < 0)
+                    return renderedProperties;
+                else {
+                    return (" ".repeat(offset) + renderedProperties);
+                }
+            }
+            else if (this.align.align == "center") {
+                const width = (typeof this.align.width == "number") ? this.align.width : (ansis_1.default.strip(await this.align.width.renderAll(0)).split("\n").map((row) => row.length).reduce((prev, curr) => {
+                    if (prev < curr)
+                        return curr;
+                    else
+                        return prev;
+                }));
+                const offset = Math.round((width - ansis_1.default.strip(renderedProperties).length) / 2);
+                if (offset < 0)
+                    return renderedProperties;
+                else {
+                    return (" ".repeat(offset) + renderedProperties);
+                }
+            }
+            return renderedProperties;
+        });
+        this.properties = properties;
+        this.spacer = spacer ?? "  -  ";
+        this.align = align ?? null;
+    }
+}
+exports.ODStartScreenHeaderComponent = ODStartScreenHeaderComponent;
+/**## ODStartScreenCategoryComponent `class`
+ * This is an Open Discord startscreen category component.
+ *
+ * This component will render a category to the startscreen. This will only render the category name. You'll need to provide your own renderer for the contents.
+ * An optional priority can be specified to choose the location of the component.
+ */
+class ODStartScreenCategoryComponent extends ODStartScreenComponent {
+    /**The name of this category. */
+    name;
+    /**When enabled, this category will still be rendered when the contents are empty. (enabled by default) */
+    renderIfEmpty;
+    constructor(id, priority, name, render, renderIfEmpty) {
+        super(id, priority, async (location) => {
+            const contents = await render(location);
+            if (contents != "" || this.renderIfEmpty) {
+                return ansis_1.default.bold.underline("\n" + name.toUpperCase() + (contents != "" ? ":\n" : ":")) + contents;
+            }
+            else
+                return "";
+        });
+        this.name = name;
+        this.renderIfEmpty = renderIfEmpty ?? true;
+    }
+}
+exports.ODStartScreenCategoryComponent = ODStartScreenCategoryComponent;
+/**## ODStartScreenPropertiesCategoryComponent `class`
+ * This is an Open Discord startscreen properties category component.
+ *
+ * This component will render a properties category to the startscreen. This will list the properties in the category.
+ * An optional priority can be specified to choose the location of the component.
+ */
+class ODStartScreenPropertiesCategoryComponent extends ODStartScreenCategoryComponent {
+    /**The properties of this category component. */
+    properties;
+    /**The hex color for the key/name of all the properties. */
+    propertyHexColor;
+    constructor(id, priority, name, properties, propertyHexColor, renderIfEmpty) {
+        super(id, priority, name, () => {
+            return this.properties.map((prop) => ansis_1.default.hex(this.propertyHexColor)(prop.key + ": ") + prop.value).join("\n");
+        }, renderIfEmpty);
+        this.properties = properties;
+        this.propertyHexColor = propertyHexColor ?? "#f8ba00";
+    }
+}
+exports.ODStartScreenPropertiesCategoryComponent = ODStartScreenPropertiesCategoryComponent;
+/**## ODStartScreenFlagsCategoryComponent `class`
+ * This is an Open Discord startscreen flags category component.
+ *
+ * This component will render a flags category to the startscreen. This will list the enabled flags in the category.
+ * An optional priority can be specified to choose the location of the component.
+ */
+class ODStartScreenFlagsCategoryComponent extends ODStartScreenCategoryComponent {
+    /**A list of all flags to render. */
+    flags;
+    constructor(id, priority, flags) {
+        super(id, priority, "flags", () => {
+            return this.flags.filter((flag) => (flag.value == true)).map((flag) => ansis_1.default.blue("[" + flag.name + "] " + flag.description)).join("\n");
+        }, false);
+        this.flags = flags;
+    }
+}
+exports.ODStartScreenFlagsCategoryComponent = ODStartScreenFlagsCategoryComponent;
+/**## ODStartScreenPluginsCategoryComponent `class`
+ * This is an Open Discord startscreen plugins category component.
+ *
+ * This component will render a plugins category to the startscreen. This will list the enabled, disabled & crashed plugins in the category.
+ * An optional priority can be specified to choose the location of the component.
+ */
+class ODStartScreenPluginsCategoryComponent extends ODStartScreenCategoryComponent {
+    /**A list of all plugins to render. */
+    plugins;
+    /**A list of all crashed plugins to render. */
+    unknownCrashedPlugins;
+    constructor(id, priority, plugins, unknownCrashedPlugins) {
+        super(id, priority, "plugins", () => {
+            const disabledPlugins = this.plugins.filter((plugin) => !plugin.enabled);
+            const renderedActivePlugins = this.plugins.filter((plugin) => plugin.enabled && plugin.executed).sort((a, b) => b.priority - a.priority).map((plugin) => ansis_1.default.green("✅ [" + plugin.name + "] " + plugin.details.shortDescription));
+            const renderedCrashedPlugins = this.plugins.filter((plugin) => plugin.enabled && plugin.crashed).sort((a, b) => b.priority - a.priority).map((plugin) => ansis_1.default.red("❌ [" + plugin.name + "] " + plugin.details.shortDescription));
+            const renderedDisabledPlugins = (disabledPlugins.length > 4) ? [ansis_1.default.gray("💤 (+" + disabledPlugins.length + " disabled plugins)")] : disabledPlugins.sort((a, b) => b.priority - a.priority).map((plugin) => ansis_1.default.gray("💤 [" + plugin.name + "] " + plugin.details.shortDescription));
+            const renderedUnknownPlugins = unknownCrashedPlugins.map((plugin) => ansis_1.default.red("❌ [" + plugin.name + "] " + plugin.description));
+            return [
+                ...renderedActivePlugins,
+                ...renderedDisabledPlugins,
+                ...renderedCrashedPlugins,
+                ...renderedUnknownPlugins
+            ].join("\n");
+        }, false);
+        this.plugins = plugins;
+        this.unknownCrashedPlugins = unknownCrashedPlugins;
+    }
+}
+exports.ODStartScreenPluginsCategoryComponent = ODStartScreenPluginsCategoryComponent;
+/**## ODStartScreenLiveStatusCategoryComponent `class`
+ * This is an Open Discord startscreen livestatus category component.
+ *
+ * This component will render a livestatus category to the startscreen. This will list the livestatus messages in the category.
+ * An optional priority can be specified to choose the location of the component.
+ */
+class ODStartScreenLiveStatusCategoryComponent extends ODStartScreenCategoryComponent {
+    /**A reference to the Open Discord livestatus manager. */
+    livestatus;
+    constructor(id, priority, livestatus) {
+        super(id, priority, "livestatus", async () => {
+            const messages = await this.livestatus.getAllMessages();
+            return this.livestatus.renderer.render(messages);
+        }, false);
+        this.livestatus = livestatus;
+    }
+}
+exports.ODStartScreenLiveStatusCategoryComponent = ODStartScreenLiveStatusCategoryComponent;
+/**## ODStartScreenLogsCategoryComponent `class`
+ * This is an Open Discord startscreen logs category component.
+ *
+ * This component will render a logs category to the startscreen. This will only render the logs category name.
+ * An optional priority can be specified to choose the location of the component.
+ */
+class ODStartScreenLogCategoryComponent extends ODStartScreenCategoryComponent {
+    constructor(id, priority) {
+        super(id, priority, "logs", () => "", true);
+    }
+}
+exports.ODStartScreenLogCategoryComponent = ODStartScreenLogCategoryComponent;

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

@@ -0,0 +1,142 @@
+import { ODId, ODManager, ODManagerData, ODValidId } from "./base";
+import { ODDebugger } from "./console";
+import { ODDatabase, ODJsonDatabaseStructure } from "./database";
+import * as discord from "discord.js";
+/**## ODValidStatValue `type`
+ * These are the only allowed types for a stat value to improve compatibility with different database systems.
+ */
+export type ODValidStatValue = string | number | boolean;
+/**## ODStatsManagerInitCallback `type`
+ * This callback can be used to execute something when the stats have been initiated.
+ *
+ * By default this is used to clear stats from users that left the server or tickets which don't exist anymore.
+ */
+export type ODStatsManagerInitCallback = (database: ODJsonDatabaseStructure, deletables: ODJsonDatabaseStructure) => void | Promise<void>;
+/**## ODStatScopeSetMode `type`
+ * This type contains all valid methods for changing the value of a stat.
+ */
+export type ODStatScopeSetMode = "set" | "increase" | "decrease";
+/**## 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.
+ */
+export declare class ODStatsManager extends ODManager<ODStatScope> {
+    #private;
+    /**Alias to Open Discord stats database. */
+    database: ODDatabase | null;
+    constructor(debug: ODDebugger);
+    /**Select the database to use to read/write all stats from/to. */
+    useDatabase(database: ODDatabase): void;
+    add(data: ODStatScope, overwrite?: boolean): boolean;
+    /**Init all stats and run `onInit()` listeners. */
+    init(): Promise<void>;
+    /**Reset all stats. (clears the entire database) */
+    reset(): Promise<void>;
+    /**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: ODStatsManagerInitCallback): void;
+}
+/**## 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`
+ */
+export declare class ODStatScope extends ODManager<ODStat> {
+    /**The id of this statistics scope. */
+    id: ODId;
+    /**Is this stat scope already initialized? */
+    ready: boolean;
+    /**Alias to Open Discord stats database. */
+    database: ODDatabase | null;
+    /**The name of this scope (used in embed title) */
+    name: string;
+    constructor(id: ODValidId, name: string);
+    /**Select the database to use to read/write all stats from/to. (Automatically assigned when used in `ODStatsManager`) */
+    useDatabase(database: ODDatabase): void;
+    /**Get the value of a statistic. The `scopeId` is the unique id of the user, channel, role, etc that the stats are related to. */
+    getStat(id: ODValidId, scopeId: string): Promise<ODValidStatValue | 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. */
+    getAllStats(id: ODValidId): Promise<{
+        id: string;
+        value: ODValidStatValue;
+    }[]>;
+    /**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. */
+    setStat(id: ODValidId, scopeId: string, value: ODValidStatValue, mode: ODStatScopeSetMode): Promise<boolean>;
+    /**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. */
+    resetStat(id: ODValidId, scopeId: string): Promise<ODValidStatValue | null>;
+    /**Initialize this stat scope & return a list of all statistic ids in the following format: `<scopeid>_<statid>`  */
+    init(): string[];
+    /**Render all stats in this scope for usage in a discord message/embed. */
+    render(scopeId: string, guild: discord.Guild, channel: discord.TextBasedChannel, user: discord.User): Promise<string>;
+}
+/**## 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.
+ */
+export declare class ODStatGlobalScope extends ODStatScope {
+    getStat(id: ODValidId): Promise<ODValidStatValue | null>;
+    getAllStats(id: ODValidId): Promise<{
+        id: string;
+        value: ODValidStatValue;
+    }[]>;
+    setStat(id: ODValidId, value: ODValidStatValue, mode: ODStatScopeSetMode): Promise<boolean>;
+    resetStat(id: ODValidId): Promise<ODValidStatValue | null>;
+    render(scopeId: "GLOBAL", guild: discord.Guild, channel: discord.TextBasedChannel, user: discord.User): Promise<string>;
+}
+/**## ODStatRenderer `type`
+ * This callback will render a single statistic for a discord embed/message.
+ */
+export type ODStatRenderer = (value: ODValidStatValue, scopeId: string, guild: discord.Guild, channel: discord.TextBasedChannel, user: discord.User) => string | Promise<string>;
+/**## 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!
+ */
+export declare class ODStat extends ODManagerData {
+    /**The priority of this statistic. */
+    priority: number;
+    /**The render function of this statistic. */
+    render: ODStatRenderer;
+    /**The value of this statistic. */
+    value: ODValidStatValue | null;
+    constructor(id: ODValidId, priority: number, render: ODStatRenderer, value?: ODValidStatValue);
+}
+/**## 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.
+ */
+export declare class ODBasicStat extends ODStat {
+    /**The name of this stat. Rendered in discord embeds/messages. */
+    name: string;
+    constructor(id: ODValidId, priority: number, name: string, value: ODValidStatValue);
+}
+/**## ODDynamicStatRenderer `type`
+ * This callback will render a single dynamic statistic for a discord embed/message.
+ */
+export type ODDynamicStatRenderer = (scopeId: string, guild: discord.Guild, channel: discord.TextBasedChannel, user: discord.User) => string | Promise<string>;
+/**## 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.
+ */
+export declare class ODDynamicStat extends ODStat {
+    constructor(id: ODValidId, priority: number, render: ODDynamicStatRenderer);
+}