@open-discord-bots/framework 0.2.3 → 0.2.5

package/README.md

@@ -45,7 +45,7 @@ We do currently <b>NOT</b> provide support for <b>3rd party implementations</b>
 
 - **Permissions** - An easy to use system for managing bot permissions for users, roles & channels at the same time.
 
-- **Stats** - Save, modify and keep track of statistics for users, channels, roles or custom entities.
+- **Statistics** - Save, modify and keep track of statistics for users, channels, roles or custom entities.
 
 - **Workers** - Many features use a worker-based system to allow extensible/overwritable code by plugins.
 

package/dist/api/index.d.ts

@@ -17,7 +17,7 @@ export * from "./modules/action";
 export * from "./modules/permission";
 export * from "./modules/helpmenu";
 export * from "./modules/session";
-export * from "./modules/stat";
+export * from "./modules/statistic";
 export * from "./modules/code";
 export * from "./modules/cooldown";
 export * from "./modules/post";

package/dist/api/index.js

@@ -35,7 +35,7 @@ __exportStar(require("./modules/action"), exports);
 __exportStar(require("./modules/permission"), exports);
 __exportStar(require("./modules/helpmenu"), exports);
 __exportStar(require("./modules/session"), exports);
-__exportStar(require("./modules/stat"), exports);
+__exportStar(require("./modules/statistic"), exports);
 __exportStar(require("./modules/code"), exports);
 __exportStar(require("./modules/cooldown"), exports);
 __exportStar(require("./modules/post"), exports);

package/dist/api/main.d.ts

@@ -16,7 +16,7 @@ import { ODVerifyBarManager } from "./modules/verifybar";
 import { ODPermissionManager } from "./modules/permission";
 import { ODCooldownManager } from "./modules/cooldown";
 import { ODHelpMenuManager } from "./modules/helpmenu";
-import { ODStatsManager } from "./modules/stat";
+import { ODStatisticManager } from "./modules/statistic";
 import { ODCodeManager } from "./modules/code";
 import { ODPostManager } from "./modules/post";
 import { ODClientManager } from "./modules/client";
@@ -71,7 +71,7 @@ export interface ODMainManagers {
     /**The manager that manages & renders the Open Discord help menu. (not the embed, but the text) */
     helpmenu: ODHelpMenuManager;
     /**The manager that manages, saves & renders the Open Discord statistics. (not the embed, but the text & database) */
-    stats: ODStatsManager;
+    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) */
     code: ODCodeManager;
     /**The manager that manages all posts (static discord channels) in the bot. (e.g. transcripts, logs, etc) */
@@ -117,7 +117,7 @@ export declare class ODMain implements ODMainManagers {
     readonly permissions: ODPermissionManager;
     readonly cooldowns: ODCooldownManager;
     readonly helpmenu: ODHelpMenuManager;
-    readonly stats: ODStatsManager;
+    readonly statistics: ODStatisticManager;
     readonly code: ODCodeManager;
     readonly posts: ODPostManager;
     readonly client: ODClientManager;

package/dist/api/main.js

@@ -34,7 +34,7 @@ class ODMain {
     permissions;
     cooldowns;
     helpmenu;
-    stats;
+    statistics;
     code;
     posts;
     client;
@@ -67,7 +67,7 @@ class ODMain {
         this.permissions = managers.permissions;
         this.cooldowns = managers.cooldowns;
         this.helpmenu = managers.helpmenu;
-        this.stats = managers.stats;
+        this.statistics = managers.statistics;
         this.code = managers.code;
         this.posts = managers.posts;
         this.sharedFuses = managers.sharedFuses;

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

@@ -7,7 +7,7 @@ import { ODDebugger } from "./console";
  * You can also specify a priority to change the execution order.
  * In Open Discord, this is used for the following processes:
  * - Autoclose/delete
- * - Database syncronisation (with tickets, stats & used options)
+ * - Database syncronisation (with tickets, statistics & used options)
  * - Panel auto-update
  * - Database Garbage Collection (removing tickets that don't exist anymore)
  * - And more!

package/dist/api/modules/code.js

@@ -12,7 +12,7 @@ const base_1 = require("./base");
  * You can also specify a priority to change the execution order.
  * In Open Discord, this is used for the following processes:
  * - Autoclose/delete
- * - Database syncronisation (with tickets, stats & used options)
+ * - Database syncronisation (with tickets, statistics & used options)
  * - Panel auto-update
  * - Database Garbage Collection (removing tickets that don't exist anymore)
  * - And more!

package/dist/api/modules/console.js

@@ -334,7 +334,7 @@ class ODDebugFileManager {
             fs_1.default.writeFileSync(this.path, newtext);
         }
     }
-    /**Generate the stats/header of the debug file (containing the version) */
+    /**Generate the statistics/header of the debug file (containing the version) */
     #createStatsText() {
         const date = new Date();
         const dstring = `${date.getDate()}/${date.getMonth() + 1}/${date.getFullYear()} ${date.getHours()}:${date.getMinutes()}:${date.getSeconds()}`;
@@ -346,7 +346,7 @@ class ODDebugFileManager {
             "=========================\n\n"
         ].join("\n");
     }
-    /**Write the stats/header to the debug file on startup */
+    /**Write the statistics/header to the debug file on startup */
     #writeStartupStats() {
         const currenttext = this.#readDebugFile();
         if (currenttext) {

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

@@ -182,12 +182,12 @@ export interface ODSharedFuseList {
     helpMenuCategoryLoading: boolean;
     /**Load the default Open Discord help menu components. */
     helpMenuComponentLoading: boolean;
-    /**Load the default Open Discord stat scopes. */
-    statScopesLoading: boolean;
-    /**Load the default Open Discord stats. */
-    statLoading: boolean;
-    /**Initiate the default Open Discord stats. */
-    statInitiating: boolean;
+    /**Load the default Open Discord statistic scopes. */
+    statisticScopesLoading: boolean;
+    /**Load the default Open Discord statistics. */
+    statisticLoading: boolean;
+    /**Initiate the default Open Discord statistics. */
+    statisticInitiating: boolean;
     /**Load the default Open Discord code/functions. */
     codeLoading: boolean;
     /**Execute the default Open Discord code/functions. */

package/dist/api/modules/fuse.js

@@ -106,9 +106,9 @@ class ODSharedFuseManager extends ODFuseManager {
             cooldownsInitiating: true,
             helpMenuCategoryLoading: true,
             helpMenuComponentLoading: true,
-            statScopesLoading: true,
-            statLoading: true,
-            statInitiating: true,
+            statisticScopesLoading: true,
+            statisticLoading: true,
+            statisticInitiating: true,
             codeLoading: true,
             codeExecution: true,
             liveStatusLoading: true,

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

@@ -1,5 +1,5 @@
 import { ODManager, ODManagerData, ODValidId } from "./base";
-import { ODDebugger } from "./console";
+import { ODDebugger, ODValidConsoleColor } from "./console";
 /**## ODProgressBarRendererManagerIdConstraint `type`
  * The constraint/layout for id mappings/interfaces of the `ODProgressBarRendererManager` class.
  */
@@ -127,3 +127,48 @@ export declare class ODManualProgressBar extends ODProgressBar {
     /**Decrease the value of the progress bar. */
     decrease(amount: number, stop?: boolean): void;
 }
+/**## ODDefaultProgressBarRendererLabel `type`
+ * All available label types for the default progress bar renderer
+ */
+export type ODDefaultProgressBarRendererLabel = "value" | "percentage" | "fraction" | "time-ms" | "time-sec" | "time-min";
+/**## ODDefaultProgressBarRendererSettings `interface`
+ * All settings for the default progress bar renderer.
+ */
+export interface ODDefaultProgressBarRendererSettings {
+    /**The color of the progress bar border. */
+    borderColor: ODValidConsoleColor | "openticket" | "openmoderation";
+    /**The color of the progress bar (filled side). */
+    filledBarColor: ODValidConsoleColor | "openticket" | "openmoderation";
+    /**The color of the progress bar (empty side). */
+    emptyBarColor: ODValidConsoleColor | "openticket" | "openmoderation";
+    /**The color of the text before the progress bar. */
+    prefixColor: ODValidConsoleColor | "openticket" | "openmoderation";
+    /**The color of the text after the progress bar. */
+    suffixColor: ODValidConsoleColor | "openticket" | "openmoderation";
+    /**The color of the progress bar label. */
+    labelColor: ODValidConsoleColor | "openticket" | "openmoderation";
+    /**The character used in the left border. */
+    leftBorderChar: string;
+    /**The character used in the right border. */
+    rightBorderChar: string;
+    /**The character used in the filled side of the progress bar. */
+    filledBarChar: string;
+    /**The character used in the empty side of the progress bar. */
+    emptyBarChar: string;
+    /**The label type. (will show a number related to the progress) */
+    labelType: ODDefaultProgressBarRendererLabel;
+    /**The position of the label. */
+    labelPosition: "start" | "end";
+    /**The width of the bar. (50 characters by default) */
+    barWidth: number;
+    /**Show the bar. */
+    showBar: boolean;
+    /**Show the label. */
+    showLabel: boolean;
+    /**Show the border. */
+    showBorder: boolean;
+}
+export declare class ODDefaultProgressBarRenderer extends ODProgressBarRenderer<ODDefaultProgressBarRendererSettings> {
+    #private;
+    constructor(id: ODValidId, settings: ODDefaultProgressBarRendererSettings);
+}

package/dist/api/modules/progressbar.js

@@ -3,12 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ODManualProgressBar = exports.ODTimedProgressBar = exports.ODProgressBar = exports.ODProgressBarRenderer = exports.ODProgressBarManager = exports.ODProgressBarRendererManager = void 0;
+exports.ODDefaultProgressBarRenderer = exports.ODManualProgressBar = exports.ODTimedProgressBar = exports.ODProgressBar = exports.ODProgressBarRenderer = exports.ODProgressBarManager = exports.ODProgressBarRendererManager = void 0;
 ///////////////////////////////////////
 //PROGRESS BAR MODULE
 ///////////////////////////////////////
 const base_1 = require("./base");
 const readline_1 = __importDefault(require("readline"));
+const ansis_1 = __importDefault(require("ansis"));
 /**## ODProgressBarRendererManager `class`
  * This is an Open Discord progress bar renderer manager.
  *
@@ -250,3 +251,44 @@ class ODManualProgressBar extends ODProgressBar {
     }
 }
 exports.ODManualProgressBar = ODManualProgressBar;
+class ODDefaultProgressBarRenderer extends ODProgressBarRenderer {
+    constructor(id, settings) {
+        super(id, (settings, min, max, value, rawPrefix, rawSuffix) => {
+            const percentage = (value - min) / (max - min);
+            const barLevel = Math.round(percentage * settings.barWidth);
+            const borderAnsis = this.#switchColorAnsis(settings.borderColor);
+            const filledBarAnsis = this.#switchColorAnsis(settings.filledBarColor);
+            const emptyBarAnsis = this.#switchColorAnsis(settings.emptyBarColor);
+            const labelAnsis = this.#switchColorAnsis(settings.labelColor);
+            const prefixAnsis = this.#switchColorAnsis(settings.prefixColor);
+            const suffixAnsis = this.#switchColorAnsis(settings.suffixColor);
+            const leftBorder = (settings.showBorder) ? borderAnsis(settings.leftBorderChar) : "";
+            const rightBorder = (settings.showBorder) ? borderAnsis(settings.rightBorderChar) : "";
+            const bar = (settings.showBar) ? filledBarAnsis(settings.filledBarChar.repeat(barLevel)) + emptyBarAnsis(settings.emptyBarChar.repeat(settings.barWidth - barLevel)) : "";
+            const prefix = (rawPrefix) ? prefixAnsis(rawPrefix) + " " : "";
+            const suffix = (rawSuffix) ? " " + suffixAnsis(rawSuffix) : "";
+            let label;
+            if (!settings.showLabel)
+                label = "";
+            if (settings.labelType == "fraction")
+                label = labelAnsis(value + "/" + max);
+            else if (settings.labelType == "percentage")
+                label = labelAnsis(Math.round(percentage * 100) + "%");
+            else if (settings.labelType == "time-ms")
+                label = labelAnsis(value + "ms");
+            else if (settings.labelType == "time-sec")
+                label = labelAnsis(Math.round(value * 10) / 10 + "sec");
+            else if (settings.labelType == "time-min")
+                label = labelAnsis(Math.round(value * 10) / 10 + "min");
+            else
+                label = labelAnsis(value.toString());
+            const labelWithPrefixAndSuffix = prefix + label + suffix;
+            return (settings.labelPosition == "start") ? labelWithPrefixAndSuffix + " " + leftBorder + bar + rightBorder : leftBorder + bar + rightBorder + " " + labelWithPrefixAndSuffix;
+        }, settings);
+    }
+    /**Switch between Ansis functions based on the specified color. */
+    #switchColorAnsis(c) {
+        return (c === "openticket") ? ansis_1.default.hex("#f8ba00") : (c === "openmoderation") ? ansis_1.default.hex("#1690ff") : ansis_1.default[c];
+    }
+}
+exports.ODDefaultProgressBarRenderer = ODDefaultProgressBarRenderer;

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

@@ -0,0 +1,176 @@
+import { ODId, ODManager, ODManagerData, ODValidId } from "./base";
+import { ODDebugger } from "./console";
+import { ODDatabase, ODDatabaseIdConstraint, ODJsonDatabaseStructure } from "./database";
+import * as discord from "discord.js";
+/**## ODValidStatisticValue `type`
+ * These are the only allowed types for a statistic value to improve compatibility with different database systems.
+ */
+export type ODValidStatisticValue = string | number | boolean;
+/**## ODStatisticManagerInitCallback `type`
+ * This callback can be used to execute something when the statistics have been initiated.
+ *
+ * By default this is used to clear statistics from users that left the server or tickets which don't exist anymore.
+ */
+export type ODStatisticManagerInitCallback = (database: ODJsonDatabaseStructure, deletables: ODJsonDatabaseStructure) => void | Promise<void>;
+/**## ODStatisticScopeSetMode `type`
+ * This type contains all valid methods for changing the value of a statistic.
+ */
+export type ODStatisticScopeSetMode = "set" | "increase" | "decrease";
+/**## ODStatisticManagerIdConstraint `type`
+ * The constraint/layout for id mappings/interfaces of the `ODStatisticManager` class.
+ */
+export type ODStatisticManagerIdConstraint = Record<string, ODStatisticScope>;
+/**## ODStatisticManager `class`
+ * This is an Open Discord statistics manager.
+ *
+ * This class is responsible for managing all statistics of the bot.
+ * Statistic are categorized in "scopes" which can be accessed in this manager.
+ *
+ * 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;
+    constructor(debug: ODDebugger);
+    /**Select the database to use to read/write all statistics from/to. */
+    useDatabase(database: ODDatabase<ODDatabaseIdConstraint>): void;
+    add(data: ODStatisticScope, overwrite?: boolean): boolean;
+    /**Init all statistics and run `onInit()` listeners. */
+    init(): Promise<void>;
+    /**Reset all statistics. (clears the entire database) */
+    reset(): Promise<void>;
+    /**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: ODStatisticManagerInitCallback): void;
+    get<ScopeId extends keyof IdList>(id: ScopeId): IdList[ScopeId];
+    get(id: ODValidId): ODStatisticScope | null;
+    remove<ScopeId extends keyof IdList>(id: ScopeId): IdList[ScopeId];
+    remove(id: ODValidId): ODStatisticScope | null;
+    exists(id: keyof IdList): boolean;
+    exists(id: ODValidId): boolean;
+}
+/**## ODStatisticScopeIdConstraint `type`
+ * The constraint/layout for id mappings/interfaces of the `ODStatisticScope` class.
+ */
+export type ODStatisticScopeIdConstraint = Record<string, ODStatistic>;
+/**## ODStatisticScope `class`
+ * This is an Open Discord statistic scope.
+ *
+ * A scope can contain multiple statistics. Every scope is seperated from other scopes.
+ * Here, you can read & write the values of all statistics.
+ *
+ * The built-in Open Discord scopes are: `global`, `user`, `ticket`
+ */
+export declare class ODStatisticScope<IdList extends ODStatisticScopeIdConstraint = ODStatisticScopeIdConstraint> extends ODManager<ODStatistic> {
+    /**The id of this statistics scope. */
+    id: ODId;
+    /**Is this scope already initialized? */
+    ready: boolean;
+    /**Alias to Open Discord statistics database. */
+    database: ODDatabase<ODDatabaseIdConstraint> | 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 statistics from/to. (Automatically assigned when used in `ODStatisticManager`) */
+    useDatabase(database: ODDatabase<ODDatabaseIdConstraint>): void;
+    /**Get the value of a statistic. The `scopeId` is the unique id of the user, channel, role, etc that the statistics are related to. */
+    getStat<StatisticId extends keyof IdList>(id: StatisticId, scopeId: string): Promise<ODValidStatisticValue | null>;
+    getStat(id: ODValidId, scopeId: string): Promise<ODValidStatisticValue | 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 statistics are related to. */
+    getAllStats<StatisticId extends keyof IdList>(id: StatisticId): Promise<{
+        id: string;
+        value: ODValidStatisticValue;
+    }[]>;
+    getAllStats(id: ODValidId): Promise<{
+        id: string;
+        value: ODValidStatisticValue;
+    }[]>;
+    /**Set, increase or decrease the value of a statistic. The `scopeId` is the unique id of the user, channel, role, etc that the statistics are related to. */
+    setStat<StatisticId extends keyof IdList>(id: StatisticId, scopeId: string, value: ODValidStatisticValue, mode: ODStatisticScopeSetMode): Promise<boolean>;
+    setStat(id: ODValidId, scopeId: string, value: ODValidStatisticValue, mode: ODStatisticScopeSetMode): 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 statistics are related to. */
+    resetStat<StatisticId extends keyof IdList>(id: ODValidId, scopeId: string): Promise<ODValidStatisticValue | null>;
+    resetStat(id: ODValidId, scopeId: string): Promise<ODValidStatisticValue | null>;
+    /**Initialize this statistic scope & return a list of all statistic ids in the following format: `<scopeid>_<statid>`  */
+    init(): string[];
+    /**Render all statistics in this scope for usage in a discord message/embed. */
+    render(scopeId: string, guild: discord.Guild, channel: discord.TextBasedChannel, user: discord.User): Promise<string>;
+    get<StatisticId extends keyof IdList>(id: StatisticId): IdList[StatisticId];
+    get(id: ODValidId): ODStatistic | null;
+    remove<StatisticId extends keyof IdList>(id: StatisticId): IdList[StatisticId];
+    remove(id: ODValidId): ODStatistic | null;
+    exists(id: keyof IdList): boolean;
+    exists(id: ODValidId): boolean;
+}
+/**## ODStatisticGlobalScope `class`
+ * This is an Open Discord statistic global scope.
+ *
+ * A scope can contain multiple statistics. Every scope is seperated from other scopes.
+ * Here, you can read & write the values of all statistics.
+ *
+ * This scope is made specifically for the global statistics of Open Discord.
+ */
+export declare class ODStatisticGlobalScope<IdList extends ODStatisticScopeIdConstraint = ODStatisticScopeIdConstraint> extends ODStatisticScope<IdList> {
+    getStat<StatisticId extends keyof IdList>(id: StatisticId): Promise<ODValidStatisticValue | null>;
+    getStat(id: ODValidId): Promise<ODValidStatisticValue | null>;
+    getAllStats<StatisticId extends keyof IdList>(id: StatisticId): Promise<{
+        id: string;
+        value: ODValidStatisticValue;
+    }[]>;
+    getAllStats(id: ODValidId): Promise<{
+        id: string;
+        value: ODValidStatisticValue;
+    }[]>;
+    setStat<StatisticId extends keyof IdList>(id: StatisticId, value: ODValidStatisticValue, mode: ODStatisticScopeSetMode): Promise<boolean>;
+    setStat(id: ODValidId, value: ODValidStatisticValue, mode: ODStatisticScopeSetMode): Promise<boolean>;
+    resetStat<StatisticId extends keyof IdList>(id: ODValidId): Promise<ODValidStatisticValue | null>;
+    resetStat(id: ODValidId): Promise<ODValidStatisticValue | null>;
+    render(scopeId: "GLOBAL", guild: discord.Guild, channel: discord.TextBasedChannel, user: discord.User): Promise<string>;
+}
+/**## ODStatisticRenderer `type`
+ * This callback will render a single statistic for a discord embed/message.
+ */
+export type ODStatisticRenderer = (value: ODValidStatisticValue, scopeId: string, guild: discord.Guild, channel: discord.TextBasedChannel, user: discord.User) => string | Promise<string>;
+/**## ODStatistic `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 statistics scope to register a new statistic. A statistic can also include a priority to choose the render priority.
+ *
+ * It's recommended to use the `ODBaseStatistic` & `ODDynamicStatistic` classes instead of this one!
+ */
+export declare class ODStatistic extends ODManagerData {
+    /**The priority of this statistic. */
+    priority: number;
+    /**The render function of this statistic. */
+    render: ODStatisticRenderer;
+    /**The value of this statistic. */
+    value: ODValidStatisticValue | null;
+    constructor(id: ODValidId, priority: number, render: ODStatisticRenderer, value?: ODValidStatisticValue);
+}
+/**## ODBaseStatistic `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 statistics scope.
+ */
+export declare class ODBaseStatistic extends ODStatistic {
+    /**The name of this statistic. Rendered in discord embeds/messages. */
+    name: string;
+    constructor(id: ODValidId, priority: number, name: string, value: ODValidStatisticValue);
+}
+/**## ODDynamicStatisticRenderer `type`
+ * This callback will render a single dynamic statistic for a discord embed/message.
+ */
+export type ODDynamicStatisticRenderer = (scopeId: string, guild: discord.Guild, channel: discord.TextBasedChannel, user: discord.User) => string | Promise<string>;
+/**## ODDynamicStatistic `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 ODDynamicStatistic extends ODStatistic {
+    constructor(id: ODValidId, priority: number, render: ODDynamicStatisticRenderer);
+}