@open-discord-bots/framework 0.0.1 → 0.0.2

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

@@ -0,0 +1,85 @@
+import { ODManager, ODManagerData, ODPromiseVoid, ODValidId } from "./base";
+import { ODDebugger } from "./console";
+/**## ODLanguageMetadata `interface`
+ * This interface contains all metadata available in the language files.
+ */
+export interface ODLanguageMetadata {
+    /**The version of Open Discord this translation is made for. */
+    otversion: string;
+    /**The name of the language in english (with capital letter). */
+    language: string;
+    /**A list of translators (discord/github username) who've contributed to this language. */
+    translators: string[];
+    /**The last date that this translation has been modified (format: DD/MM/YYYY) */
+    lastedited: string;
+    /**When `true`, the translator made use of some sort of automation while creating the translation. (e.g. ChatGPT, Google Translate, DeepL, ...) */
+    automated: boolean;
+}
+/**## ODLanguageManager `class`
+ * This is an Open Discord language manager.
+ *
+ * It manages all languages in the bot and manages translation for you!
+ * Get a translation via the `getTranslation()` or `getTranslationWithParams()` methods.
+ *
+ * Add new languages using the `ODlanguage` class in your plugin!
+ */
+export declare class ODLanguageManager extends ODManager<ODLanguage> {
+    #private;
+    /**The currently selected language. */
+    current: ODLanguage | null;
+    /**The currently selected backup language. (used when translation missing in current language) */
+    backup: ODLanguage | null;
+    constructor(debug: ODDebugger, presets: boolean);
+    /**Set the current language by providing the ID of a language which is registered in this manager. */
+    setCurrentLanguage(id: ODValidId): void;
+    /**Get the current language (same as `this.current`) */
+    getCurrentLanguage(): ODLanguage | null;
+    /**Set the backup language by providing the ID of a language which is registered in this manager. */
+    setBackupLanguage(id: ODValidId): void;
+    /**Get the backup language (same as `this.backup`) */
+    getBackupLanguage(): ODLanguage | null;
+    /**Get the metadata of the current/backup language. */
+    getLanguageMetadata(frombackup?: boolean): ODLanguageMetadata | null;
+    /**Get the ID (string) of the current language. (Not backup language) */
+    getCurrentLanguageId(): string;
+    /**Get a translation string by JSON location. (e.g. `"checker.system.typeError"`) */
+    getTranslation(id: string): string | null;
+    /**Get a backup translation string by JSON location and replace `{0}`,`{1}`,`{2}`,... with the provided parameters. */
+    getTranslationWithParams(id: string, params: string[]): string | null;
+    /**Init all language files. */
+    init(): Promise<void>;
+}
+/**## ODLanguage `class`
+ * This is an Open Discord language file.
+ *
+ * It contains metadata and all translation strings available in this language.
+ * Register this class to an `ODLanguageManager` to use it!
+ *
+ * JSON languages should be created using the `ODJsonLanguage` class instead!
+ */
+export declare class ODLanguage extends ODManagerData {
+    /**The name of the file with extension. */
+    file: string;
+    /**The path to the file relative to the main directory. */
+    path: string;
+    /**The raw object data of the translation. */
+    data: any;
+    /**The metadata of the language if available. */
+    metadata: ODLanguageMetadata | null;
+    constructor(id: ODValidId, data: any);
+    /**Init the language. */
+    init(): ODPromiseVoid;
+}
+/**## ODJsonLanguage `class`
+ * This is an Open Discord JSON language file.
+ *
+ * It contains metadata and all translation strings from a certain JSON file (in `./languages/`).
+ * Register this class to an `ODLanguageManager` to use it!
+ *
+ * Use the `ODLanguage` class to use translations from non-JSON files!
+ */
+export declare class ODJsonLanguage extends ODLanguage {
+    constructor(id: ODValidId, file: string, customPath?: string);
+    /**Init the langauge. */
+    init(): ODPromiseVoid;
+}

package/dist/api/modules/language.js

@@ -0,0 +1,195 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ODJsonLanguage = exports.ODLanguage = exports.ODLanguageManager = void 0;
+///////////////////////////////////////
+//LANGUAGE MODULE
+///////////////////////////////////////
+const base_1 = require("./base");
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+/**## ODLanguageManager `class`
+ * This is an Open Discord language manager.
+ *
+ * It manages all languages in the bot and manages translation for you!
+ * Get a translation via the `getTranslation()` or `getTranslationWithParams()` methods.
+ *
+ * Add new languages using the `ODlanguage` class in your plugin!
+ */
+class ODLanguageManager extends base_1.ODManager {
+    /**The currently selected language. */
+    current = null;
+    /**The currently selected backup language. (used when translation missing in current language) */
+    backup = null;
+    /**An alias to Open Discord debugger. */
+    #debug;
+    constructor(debug, presets) {
+        super(debug, "language");
+        if (presets)
+            this.add(new ODLanguage("english", "english.json"));
+        this.current = presets ? new ODLanguage("english", "english.json") : null;
+        this.backup = presets ? new ODLanguage("english", "english.json") : null;
+        this.#debug = debug;
+    }
+    /**Set the current language by providing the ID of a language which is registered in this manager. */
+    setCurrentLanguage(id) {
+        this.current = this.get(id);
+        const languageId = this.current?.id.value ?? "<unknown-id>";
+        const languageAutomated = this.current?.metadata?.automated.toString() ?? "<unknown-metadata>";
+        this.#debug.debug("Selected current language", [
+            { key: "id", value: languageId },
+            { key: "automated", value: languageAutomated },
+        ]);
+    }
+    /**Get the current language (same as `this.current`) */
+    getCurrentLanguage() {
+        return (this.current) ? this.current : null;
+    }
+    /**Set the backup language by providing the ID of a language which is registered in this manager. */
+    setBackupLanguage(id) {
+        this.backup = this.get(id);
+        const languageId = this.backup?.id.value ?? "<unknown-id>";
+        const languageAutomated = this.backup?.metadata?.automated.toString() ?? "<unknown-metadata>";
+        this.#debug.debug("Selected backup language", [
+            { key: "id", value: languageId },
+            { key: "automated", value: languageAutomated },
+        ]);
+    }
+    /**Get the backup language (same as `this.backup`) */
+    getBackupLanguage() {
+        return (this.backup) ? this.backup : null;
+    }
+    /**Get the metadata of the current/backup language. */
+    getLanguageMetadata(frombackup) {
+        if (frombackup)
+            return (this.backup) ? this.backup.metadata : null;
+        return (this.current) ? this.current.metadata : null;
+    }
+    /**Get the ID (string) of the current language. (Not backup language) */
+    getCurrentLanguageId() {
+        return (this.current) ? this.current.id.value : "";
+    }
+    /**Get a translation string by JSON location. (e.g. `"checker.system.typeError"`) */
+    getTranslation(id) {
+        if (!this.current)
+            return this.#getBackupTranslation(id);
+        const splitted = id.split(".");
+        let currentObject = this.current.data;
+        let result = false;
+        splitted.forEach((id) => {
+            if (typeof currentObject[id] == "object") {
+                currentObject = currentObject[id];
+            }
+            else if (typeof currentObject[id] == "string") {
+                result = currentObject[id];
+            }
+        });
+        if (typeof result == "string")
+            return result;
+        else
+            return this.#getBackupTranslation(id);
+    }
+    /**Get a backup  translation string by JSON location. (system only) */
+    #getBackupTranslation(id) {
+        if (!this.backup)
+            return null;
+        const splitted = id.split(".");
+        let currentObject = this.backup.data;
+        let result = false;
+        splitted.forEach((id) => {
+            if (typeof currentObject[id] == "object") {
+                currentObject = currentObject[id];
+            }
+            else if (typeof currentObject[id] == "string") {
+                result = currentObject[id];
+            }
+        });
+        if (typeof result == "string")
+            return result;
+        else
+            return null;
+    }
+    /**Get a backup translation string by JSON location and replace `{0}`,`{1}`,`{2}`,... with the provided parameters. */
+    getTranslationWithParams(id, params) {
+        let translation = this.getTranslation(id);
+        if (!translation)
+            return translation;
+        params.forEach((value, index) => {
+            if (!translation)
+                return;
+            translation = translation.replace(`{${index}}`, value);
+        });
+        return translation;
+    }
+    /**Init all language files. */
+    async init() {
+        for (const language of this.getAll()) {
+            try {
+                await language.init();
+            }
+            catch (err) {
+                process.emit("uncaughtException", new base_1.ODSystemError(err));
+            }
+        }
+    }
+}
+exports.ODLanguageManager = ODLanguageManager;
+/**## ODLanguage `class`
+ * This is an Open Discord language file.
+ *
+ * It contains metadata and all translation strings available in this language.
+ * Register this class to an `ODLanguageManager` to use it!
+ *
+ * JSON languages should be created using the `ODJsonLanguage` class instead!
+ */
+class ODLanguage extends base_1.ODManagerData {
+    /**The name of the file with extension. */
+    file = "";
+    /**The path to the file relative to the main directory. */
+    path = "";
+    /**The raw object data of the translation. */
+    data;
+    /**The metadata of the language if available. */
+    metadata = null;
+    constructor(id, data) {
+        super(id);
+        this.data = data;
+    }
+    /**Init the language. */
+    init() {
+        //nothing
+    }
+}
+exports.ODLanguage = ODLanguage;
+/**## ODJsonLanguage `class`
+ * This is an Open Discord JSON language file.
+ *
+ * It contains metadata and all translation strings from a certain JSON file (in `./languages/`).
+ * Register this class to an `ODLanguageManager` to use it!
+ *
+ * Use the `ODLanguage` class to use translations from non-JSON files!
+ */
+class ODJsonLanguage extends ODLanguage {
+    constructor(id, file, customPath) {
+        super(id, {});
+        this.file = (file.endsWith(".json")) ? file : file + ".json";
+        this.path = customPath ? path_1.default.join("./", customPath, this.file) : path_1.default.join("./languages/", this.file);
+    }
+    /**Init the langauge. */
+    init() {
+        if (!fs_1.default.existsSync(this.path))
+            throw new base_1.ODSystemError("Unable to parse language \"" + path_1.default.join("./", this.path) + "\", the file doesn't exist!");
+        try {
+            this.data = JSON.parse(fs_1.default.readFileSync(this.path).toString());
+        }
+        catch (err) {
+            process.emit("uncaughtException", err);
+            throw new base_1.ODSystemError("Unable to parse language \"" + path_1.default.join("./", this.path) + "\"!");
+        }
+        if (this.data["_TRANSLATION"])
+            this.metadata = this.data["_TRANSLATION"];
+    }
+}
+exports.ODJsonLanguage = ODJsonLanguage;

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

@@ -0,0 +1,121 @@
+import { ODValidId, ODManager, ODManagerData } from "./base";
+import * as discord from "discord.js";
+import { ODDebugger } from "./console";
+import { ODClientManager } from "./client";
+/**## ODPermissionType `type`
+ * All available permission types/levels. Can be used in the `ODPermission` class.
+ */
+export type ODPermissionType = "member" | "support" | "moderator" | "admin" | "owner" | "developer";
+/**## ODPermissionScope `type`
+ * The scope in which a certain permission is active.
+ */
+export type ODPermissionScope = "global-user" | "channel-user" | "global-role" | "channel-role";
+/**## ODPermissionResult `interface`
+ * The result returned by `ODPermissionManager.getPermissions()`.
+ */
+export interface ODPermissionResult {
+    /**The permission type. */
+    type: ODPermissionType;
+    /**The permission scope. */
+    scope: ODPermissionScope | "default";
+    /**The highest level available for this scope. */
+    level: ODPermissionLevel;
+    /**The permission which returned this level. */
+    source: ODPermission | null;
+}
+/**## ODPermissionLevel `enum`
+ * All available permission types/levels. But as `enum` instead of `type`. Used to calculate the level.
+ */
+export declare enum ODPermissionLevel {
+    /**A normal member. (Default for everyone) */
+    member = 0,
+    /**Support team. Higher than a normal member. (Used for ticket-admins) */
+    support = 1,
+    /**Moderator. Higher than the support team. (Unused) */
+    moderator = 2,
+    /**Admin. Higher than a moderator. (Used for global-admins) */
+    admin = 3,
+    /**Server owner. (Able to use all commands including `/stats reset`) */
+    owner = 4,
+    /**Bot owner or all users from dev team. (Able to use all commands including `/stats reset`) */
+    developer = 5
+}
+/**## ODPermission `class`
+ * This is an Open Discord permission.
+ *
+ * It defines a single permission level for a specific scope (global/channel & user/role)
+ * These permissions only apply to commands & interactions.
+ * They are not related to channel permissions in the ticket system.
+ *
+ * Register this class to an `ODPermissionManager` to use it!
+ */
+export declare class ODPermission extends ODManagerData {
+    /**The scope of this permission. */
+    readonly scope: ODPermissionScope;
+    /**The type/level of this permission. */
+    readonly permission: ODPermissionType;
+    /**The user/role of this permission. */
+    readonly value: discord.Role | discord.User;
+    /**The channel that this permission applies to. (`null` when global) */
+    readonly channel: discord.Channel | null;
+    constructor(id: ODValidId, scope: "global-user", permission: ODPermissionType, value: discord.User);
+    constructor(id: ODValidId, scope: "global-role", permission: ODPermissionType, value: discord.Role);
+    constructor(id: ODValidId, scope: "channel-user", permission: ODPermissionType, value: discord.User, channel: discord.Channel);
+    constructor(id: ODValidId, scope: "channel-role", permission: ODPermissionType, value: discord.Role, channel: discord.Channel);
+}
+/**## ODPermissionSettings `interface`
+ * Optional settings for the `getPermissions()` method in the `ODPermissionManager`.
+ */
+export interface ODPermissionSettings {
+    /**Include permissions from the global user scope. */
+    allowGlobalUserScope?: boolean;
+    /**Include permissions from the global role scope. */
+    allowGlobalRoleScope?: boolean;
+    /**Include permissions from the channel user scope. */
+    allowChannelUserScope?: boolean;
+    /**Include permissions from the channel role scope. */
+    allowChannelRoleScope?: boolean;
+    /**Only include permissions of which the id matches this regex. */
+    idRegex?: RegExp;
+}
+/**## ODPermissionCalculationCallback `type`
+ * The callback of the permission calculation. (Used in `ODPermissionManager`)
+ */
+export type ODPermissionCalculationCallback = (user: discord.User, channel?: discord.Channel | null, guild?: discord.Guild | null, settings?: ODPermissionSettings | null) => Promise<ODPermissionResult>;
+/**## ODPermissionCommandResult `type`
+ * The result of calculating permissions for a command.
+ */
+export type ODPermissionCommandResult = {
+    /**Returns `true` when the user has valid permissions. */
+    hasPerms: false;
+    reason: "no-perms" | "disabled" | "not-in-server";
+} | {
+    /**Returns `true` when the user has valid permissions. */
+    hasPerms: true;
+    /**Is the user a server admin or a normal member? This does not decide if the user has permissions or not. */
+    isAdmin: boolean;
+};
+/**## ODPermissionManager `class`
+ * This is an Open Discord permission manager.
+ *
+ * It manages all permissions in the bot!
+ * Use the `getPermissions()` and `hasPermissions()` methods to get user perms.
+ *
+ * Add new permissions using the `ODPermission` class in your plugin!
+ */
+export declare class ODPermissionManager extends ODManager<ODPermission> {
+    #private;
+    /**The result which is returned when no other permissions match. (`member` by default) */
+    defaultResult: ODPermissionResult;
+    constructor(debug: ODDebugger, client: ODClientManager, useDefaultCalculation?: boolean);
+    /**Edit the permission calculation function in this manager. */
+    setCalculation(calculation: ODPermissionCalculationCallback): void;
+    /**Edit the result which is returned when no other permissions match. (`member` by default) */
+    setDefaultResult(result: ODPermissionResult): void;
+    /**Get an `ODPermissionResult` based on a few context factors. Use `hasPermissions()` to simplify the result. */
+    getPermissions(user: discord.User, channel?: discord.Channel | null, guild?: discord.Guild | null, settings?: ODPermissionSettings | null): Promise<ODPermissionResult>;
+    /**Simplifies the `ODPermissionResult` returned from `getPermissions()` and returns a boolean to check if the user matches the required permissions. */
+    hasPermissions(minimum: ODPermissionType, data: ODPermissionResult): boolean;
+    /**Check the permissions for a certain command of the bot. */
+    checkCommandPerms(permissionMode: string, requiredLevel: ODPermissionType, user: discord.User, member?: discord.GuildMember | null, channel?: discord.Channel | null, guild?: discord.Guild | null, settings?: ODPermissionSettings): Promise<ODPermissionCommandResult>;
+}