@hokkiai/djs-level-importer 1.0.0

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "tatsu","sokora","hokki","zakahacecosas","amari","lurkr"
+    ]
+}

package/CHANGELOG.md

@@ -0,0 +1,156 @@
+<!-- markdownlint-disable md024 -->
+<!-- preserve old changelogs here -->
+
+# Sokora Changelog
+
+## 0.3.2
+
+## Changed
+
+- User can't use any commands in DMs (thanks @userandaname)
+- You can use /user info for people outside of the server
+
+## Fixed
+
+- Top.gg reminders are fixed once more, now they should send **only** when you didn't vote
+- Attempt to fix tempbans not unbanning the user due to Sokora not finding them through the cache (by fetching the ban list instead)
+- "Unknown guild" error in serverboard
+
+## Removed
+
+- Executor in message delete events
+
+## 0.3.1
+
+## Changed
+
+- Made /help, /about, /changelog, /credits, /ping, /settings and /user settings ephemeral (only visible to you)
+- Sokora alerts server owners if they enable but misconfigure showing a server invite in serverboard
+
+## Fixed
+
+- Fixed issues with timestamps
+- Fixed some moderation commands "failing" (even though they did the job)
+- Fixed invites for serverboard sometimes silently failing to create or crashing /serverboard
+- Fixed topgg reminders
+- Some internal fixes
+
+## 0.3.0
+
+### Added
+
+- New commands.
+  - Added a new `/games` category.
+    - Added `/games rps` to play Rock, Paper, Scissors.
+    - Added `/games coin` to flip a coin.
+  - Added a new `/math` category.
+    - Added `/math graph` to graphically represent a function.
+    - Added `/math calc` to execute a mathematical expression.
+  - Added `/help variables` to show help with _Dynamic (variables)_.
+  - Added `/ping` to view bot ping and latency.
+- Dynamic (variables)
+  - Gave a proper name to replaceable variables (`Dynamic (variables)`), and added more options:
+  - - `(serverowner)` - Server owner's name
+  - - `(currentdate)` - Current date in the 'July 10, 2025' format
+  - - `(currentdate, simple)` - Current date in the '7/10/25' format
+  - - `(currentdate, detailed)` - Current date in the 'July 10, 2025, at 1:11 PM' format
+- User settings
+  - Added user settings as a feature.
+    - Added TopGG reminders setting.
+- Moderation
+  - Added the ability to clear messages for a single user.
+  - Added reason field to `/moderation unmute`.
+  - Added the ability to silently perform moderation actions.
+  - Added the ability to view all cases of a server, and to filter by case type.
+- Other additions
+  - Added a starboard. It can be configured from `/settings starboard`.
+  - Added unique member count to `/about`.
+  - Added the ability for server owners to display an invite link to their servers from the serverboard.
+- Easter eggs
+  - Added two new easter eggs.
+- Settings
+  - Enable/disable specific easter eggs.
+  - Enable easter eggs in specific channels only.
+  - Give roles to users when they join.
+  - Now you can set different channels for join and leave messages.
+  - Whether to show an invite to your server or not in serverboard.
+    - What channel the invite should point to.
+  - Whether all moderation actions should be silent or not.
+  - What kind of moderation events should be logged.
+  - Settings for the new starboard feature.
+    - Channel to send starred messages to, emoji to be reacted, and reaction threshold.
+
+### Changed
+
+- Settings were rebuilt into completely new settings panes that allow to change settings from the own embed, without using commands.
+
+### Fixed
+
+- News
+  - Fixed not being able to delete the first new you create.
+- Moderation
+  - Fixed the bot crashing because of too large messages being deleted.
+  - Fixed a `Jump to message` option being shown on deleted messages (you cannot jump to a deleted message).
+  - Fixed the bot showing "Application didn't respond" when unmuting someone muted by another bot.
+  - Fixed the bot unable to send a moderation log when a deleted / edited message is too large. It will instead upload two text files containing old and new messages.
+- _Many other fixes were made, not all of them are tracked._
+
+### Removed
+
+- Moderation
+  - Removed the ability to add notes on users.
+- Settings
+  - Commands to change settings. Use the new embeds to change settings from there.
+- Changelog
+  - Changelog itself won't be shown in embeds anymore (it's too long). `/changelog` will show a link to this file.
+
+---
+
+## 0.2.0
+
+### Added
+
+#### Commands
+
+- `/changelog`
+- `/credits`
+- `/moderation notes`
+
+### Changed
+
+- The bot will remove levels when an admin changed the leveling difficulty
+- Now `/leaderboard` shows 6 users per page instead of 5
+- When you add the bot, it sends a message in the system channel
+- Remade the message logs
+- Edit logs will let you jump to the message that got edited
+
+#### /settings
+
+- Autocompletes with channels/users/roles (you don't have to copy IDs now :tada:)
+- In the embed it will show links to channels/users/roles instead of showing IDs
+
+#### /about
+
+- Vote button added
+- Moved credits into a different command to reduce the height of the embed
+
+### Fixed
+
+#### News
+
+- Major issue related to the database, where the guild wasn't provided to ensure that news would be unique to every server, **thank you @Golem642!!!!**
+- `/news` edit's modal errored when sending
+
+#### Moderation commands
+
+- `/moderation clear` removed one more message than the user provided
+- `/moderation unban` errored internally (it should send an error embed) when the user didn\'t have the "Ban Members" permission
+
+### Typos
+
+- warn mentions in `/moderation warn` are now warning to be more consistent
+- Removed old markdown remnants from `/moderation slowdown`
+
+## 0.1.0
+
+### Initial release :)

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2025 ZakaHaceCosas
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# `djs-level-importer`
+
+An open, JavaScript-based library to import leveling data from MEE6 and other bots. Made jointly by the [Sokora](https://sokora.org) and [Hokki](https://www.hokki.app) Discord bots.
+
+## Usage
+
+Instantiate the `Leveler` class (exported by this package) providing the ID of the guild you want to import data from. Then, call the `GetLeaderboard` method, passing, for example, a `0` for MEE6 (more onto this later on).
+
+```ts
+const leveler = new Leveler({
+  guild: "903852579837059113", // your server's ID
+});
+
+const leveling_data = await leveler.GetLeaderboard(0);
+```
+
+You will be given an array of objects matching either of these interfaces:
+
+```ts
+export interface BaseUserLevels {
+  /** User ID. */
+  uid: string;
+  /** Current XP **in total**. */
+  current_xp: number;
+}
+
+export interface FullUserLevels extends BaseUserLevels {
+  /** Current XP **relative to the level**. */
+  current_lvl_xp: number;
+  /** Current level. */
+  lvl: number;
+  /** XP required to level up. */
+  next_lvl_xp: number;
+}
+```
+
+> [!IMPORTANT]
+> **`BaseUserLevels`** objects are returned when importing data from **Tatsu**, and **`FullUserLevels`** are returned when importing data from **MEE6**.
+>
+> This is not the most intuitive, but the best thing we can do to provide you with all _possible_ data despite Tatsu not providing these extra fields that other bots provide.
+>
+> **Bear in mind that extensions to bot support may or may not result in breaking changes to these interfaces** (we'll try to avoid them as much as we can).
+
+## Bot support
+
+As of now, MEE6 and Tatsu are supported. Most bots don't document their APIs and it's therefore difficult to add new bots, so no guarantees are made; however we do try to add new bots to this library.
+
+**Bots are selected using integers** when calling `GetLeaderboard`. You can check int-bot associations by looking at the exported `SupportedBots` enum. Or just look at it here:
+
+```ts
+export enum SupportedBots {
+  MEE6 = 0,
+  TATSU = 1,
+}
+```
+
+### Per bot requirements
+
+#### MEE6
+
+You need to enable leaderboard visibility from your dashboard. Open the leaderboard settings in the MEE6 dashboard and enable the option `Make my server's leaderboard public`. Otherwise data cannot be imported.
+
+#### Tatsu
+
+You need an API key, obtained from [this link](https://dev.tatsu.gg/api/reference#authentication) and passed to the constructor via the `tatsu_api` parameter.
+
+```ts
+new Leveler({ guild: "...", tatsu_api: "123ABC..." });
+```
+
+<!-- #### Atlas
+
+Nothing is required. -->
+
+## Credits and license
+
+Originally made by [ZakaHaceCosas](https://zakahacecosas.github.io/) for the [Hokki](https://www.hokki.app) and [Sokora](https://sokora.org) Discord bots. Made open source under the MIT license for everyone to use, so long as our work is attributed (which'd make us really happy as reverse engineering some APIs was a true pain, to be fair).
+
+---
+
+Copyright (c) 2025 ZakaHaceCosas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/TODO.txt

@@ -0,0 +1,15 @@
+[DONE] indicates the bot being supported.
+>[WIP] indicates the bot being actively worked on.
+*[NXT] indicates the bot is to be added. Asterisk can be:
+    + likely to be worked on at some point
+    ? wanted to implement, but viability is not fully investigated
+    - unlikely to be implemented, but noted here as a known and not-yet-discarded leveling bot
+
+[DONE] MEE6
+[DONE] Tatsu
+>[WIP] Atlas
++[NXT] Polaris
+?[NXT] Amari
+?[NXT] Arcane
+?[NXT] Lurkr
+-[NXT] CarlBot

package/bun.lock

@@ -0,0 +1,30 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "djs-level-importer",
+      "dependencies": {
+        "tatsu": "latest",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.3", "", { "dependencies": { "bun-types": "1.3.3" } }, "sha512-ogrKbJ2X5N0kWLLFKeytG0eHDleBYtngtlbu9cyBKFtNL3cnpDZkNdQj8flVf6WTZUX5ulI9AY1oa7ljhSrp+g=="],
+
+    "@types/node": ["@types/node@16.18.126", "", {}, "sha512-OTcgaiwfGFBKacvfwuHzzn1KLxH/er8mluiy8/uM3sGXHaRe73RrSIj01jow9t4kJEW633Ov+cOexXeiApTyAw=="],
+
+    "bun-types": ["bun-types@1.3.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-z3Xwlg7j2l9JY27x5Qn3Wlyos8YAp0kKRlrePAOjgjMGS5IG6E7Jnlx736vH9UVI4wUICwwhC9anYL++XeOgTQ=="],
+
+    "tatsu": ["tatsu@1.2.0", "", { "dependencies": { "@types/node": "^16.11.19", "typescript": "^4.5.4" } }, "sha512-7iN50ZvwVisD1e8Q4NPboOE2UzwxB+Ex9N5UZIrWvC1N2giauw68gcU+pOExjOwgLiDy83PP2i7J6mGN4AM3HQ=="],
+
+    "typescript": ["typescript@4.9.5", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
+    "bun-types/@types/node": ["@types/node@24.10.1", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ=="],
+  }
+}

package/fknode.yaml

@@ -0,0 +1,3 @@
+prettyScript: "prettier"
+flagless:
+  flaglessPretty: true

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@hokkiai/djs-level-importer",
+  "version": "1.0.0",
+  "description": "An open, JavaScript-based library to import leveling data from MEE6 and other bots. Made jointly by the Sokora and Hokki Discord bots.",
+  "type": "module",
+  "homepage": "https://github.com/hokkiai/djs-level-importer",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "discord",
+    "discord.js",
+    "levels",
+    "importer",
+    "discord leveling"
+  ],
+  "author": {
+    "name": "ZakaHaceCosas",
+    "email": "zakahacecosas@protonmail.com",
+    "url": "https://zakahacecosas.github.io"
+  },
+  "contributors": [
+    {
+      "name": "The Sokora Discord bot",
+      "url": "https://sokora.org"
+    },
+    {
+      "name": "The Hokki Discord bot",
+      "url": "https://www.hokki.app"
+    }
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "tatsu": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/main.ts

@@ -0,0 +1,108 @@
+import { MEE6GetLeaderboard } from "./mee6.js";
+import { TATSUGetLeaderboard } from "./tatsu.js";
+
+/** A user/guild ID. MEE6 has a slightly inconsistent way of telling you this, as far as I know. */
+export type Identifier = string | { id: string };
+
+/**
+ * Resolves a user/guild ID from the MEE6 (or any) API.
+ *
+ * @param {Identifier} id ID
+ * @returns {string} Resolved ID
+ */
+export function GET_ID(id: Identifier): string {
+  if (typeof id === "string") return id;
+  else if (typeof id.id === "string") return id.id;
+  else throw new Error("Invalid Identifier specified: " + id);
+}
+
+/**
+ * A user's leveling information, in a common format **with minimal data**. Required for compat with lesser capable bots like Tatsu.
+ *
+ * @interface BaseUserLevels
+ */
+export interface BaseUserLevels {
+  /** User ID. */
+  uid: string;
+  /** Current XP **in total**. */
+  current_xp: number;
+}
+
+/**
+ * A user's leveling information, in a common format **with levels and rank up**.
+ *
+ * @interface FullUserLevels
+ */
+export interface FullUserLevels extends BaseUserLevels {
+  /** Current XP **relative to the level**. */
+  current_lvl_xp: number;
+  /** Current level. */
+  lvl: number;
+  /** XP required to level up. */
+  next_lvl_xp: number;
+}
+
+/** Type-guards if you're on MEE6, basically. */
+export function SUPPORTS_LEVELS(a: any): a is FullUserLevels {
+  return a.lvl && a.lvl !== undefined && typeof a.lvl === "number";
+}
+
+/**
+ * Supported Discord bots
+ *
+ * ```ts
+ * MEE6 = 0,
+ * TATSU = 1
+ * ```
+ * @enum {number}
+ */
+export enum SupportedBots {
+  MEE6 = 0,
+  TATSU = 1,
+}
+
+export class Leveler {
+  private guild: string;
+  private tatsu_api: string | null = null;
+
+  /**
+   * Creates an instance of a Leveler, with which you'll be able to import leveling data from supported bots.
+   *
+   * @constructor
+   * @param {string} guild Guild ID.
+   * @param {?string} tatsu_api If importing from Tatsu, you need to bring in your own API key. This is free and pretty easy to get from the Tatsu bot itself.
+   */
+  constructor(options: { guild: string; tatsu_api?: string }) {
+    this.guild = options.guild;
+    if (options.tatsu_api) this.tatsu_api = options.tatsu_api;
+  }
+
+  /** Gets the whole server leaderboard from MEE6. Throws if unable to get it. */
+  public async GetLeaderboard(
+    target: SupportedBots.MEE6,
+  ): Promise<FullUserLevels[]>;
+  /** Gets the whole server leaderboard from Tatsu. Throws if unable to get it. */
+  public async GetLeaderboard(target: SupportedBots.TATSU): Promise<BaseUserLevels[]>;
+  public async GetLeaderboard(target: SupportedBots): Promise<BaseUserLevels[] | FullUserLevels[]> {
+    if (target === SupportedBots.MEE6) {
+      const levels = await MEE6GetLeaderboard(this.guild);
+      return levels.map(u => {
+        return {
+          uid: u.id,
+          lvl: u.level,
+          current_xp: u.xp.totalXp,
+          current_lvl_xp: u.xp.userXp,
+          next_lvl_xp: u.xp.levelXp,
+        };
+      });
+    } else {
+      const levels = await TATSUGetLeaderboard(this.tatsu_api, this.guild);
+      return levels.rankings.map(r => {
+        return {
+          uid: r.user_id,
+          current_xp: r.score,
+        };
+      });
+    } 
+  }
+}

package/src/mee6.ts

@@ -0,0 +1,61 @@
+import { GET_ID, Identifier } from "./main.js";
+
+interface MEE6User {
+  id: string;
+  level: number;
+  xp: {
+    userXp: number;
+    levelXp: number;
+    totalXp: number;
+  };
+}
+
+/**
+ * Get a page of the leaderboard of a guild.
+ * @param {Identifier} guild Guild to get the leaderboard from.
+ * @param {number} limit Limit of users to fetch per page. Maximum 1000.
+ * @param {number} page Number of pages to skip.
+ * @returns {Promise<MEE6User[]>} Leaderboard page.
+ */
+async function getLeaderboardPage(
+  guild: Identifier,
+  limit: number = 1000,
+  page: number = 0,
+): Promise<MEE6User[]> {
+  const guildId = GET_ID(guild);
+  const response = await fetch(
+    `https://mee6.xyz/api/plugins/levels/leaderboard/${guildId}?limit=${limit}&page=${page}`,
+    { method: "GET" },
+  );
+  const j = (await response.json()) as any;
+  if (response.status !== 200) {
+    if (j.error && j.error.message) throw new Error(`${response.status}: ${j.error.message}`);
+    else throw new Error(`${response.status}: ${response.statusText}`);
+  }
+  return j.players.map((user: any) => {
+    const { id, level } = user;
+    const [userXp, levelXp, totalXp] = user.detailed_xp;
+    return {
+      id,
+      level,
+      xp: { userXp, levelXp, totalXp },
+    };
+  });
+}
+
+/**
+ * Get the leaderboard of a guild.
+ * @param {Identifier} guild Guild to get the leaderboard from.
+ * @returns {Promise<MEE6User[]>} Leaderboard of the guild.
+ */
+export async function MEE6GetLeaderboard(guild: Identifier): Promise<MEE6User[]> {
+  const leaderboard = [];
+  let pageNumber = 0;
+  while (true) {
+    const page = await getLeaderboardPage(guild, 1000, pageNumber);
+    leaderboard.push(...page);
+    if (page.length < 1000) break;
+    pageNumber += 1;
+  }
+  return leaderboard;
+}

package/src/tatsu.ts

@@ -0,0 +1,19 @@
+// thanks tatsu for caring to make a package
+import { GuildRankings, Tatsu } from "tatsu";
+
+/**
+ * Get the leaderboard of a guild.
+ *
+ * @async
+ * @param {(string | null)} tkn API token for Tatsu.
+ * @param {string} guildId Guild to get the leaderboard from.
+ * @returns {Promise<GuildRankings>} Leaderboard of the guild.
+ */
+export async function TATSUGetLeaderboard(
+  tkn: string | null,
+  guildId: string,
+): Promise<GuildRankings> {
+  if (!tkn) throw `No Tatsu API key provided. Cannot use Tatsu API.`;
+  const tatsu = new Tatsu(tkn);
+  return await tatsu.getGuildRankings(guildId);
+}

package/tsconfig.json

@@ -0,0 +1,43 @@
+{
+    "compilerOptions": {
+        "target": "ES2024",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+
+        "outDir": "dist",
+        "declaration": true,
+
+        "strict": true,
+        "esModuleInterop": true,
+        "strictNullChecks": true,
+        "strictBindCallApply": true,
+        "strictFunctionTypes": true,
+        "strictBuiltinIteratorReturn": true,
+        "strictPropertyInitialization": true,
+        "noImplicitAny": true,
+        "noImplicitOverride": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noPropertyAccessFromIndexSignature": true,
+        "noUncheckedIndexedAccess": true,
+        "noUncheckedSideEffectImports": true,
+        "noImplicitThis": true,
+        "noImplicitReturns": true,
+        "noFallthroughCasesInSwitch": true,
+        "forceConsistentCasingInFileNames": true,
+        "exactOptionalPropertyTypes": true,
+        "useUnknownInCatchVariables": true,
+        "allowArbitraryExtensions": true,
+        "skipLibCheck": true,
+        "lib": [
+            "ES2024"
+        ]
+    },
+    "include": [
+        "src/"
+    ],
+    "exclude": ["node_modules/"],
+    "buildOptions": {
+        "incremental": true
+    }
+}