@hokkiai/djs-level-importer 1.1.0 → 1.2.0

package/README.md

@@ -1,7 +1,11 @@
-# `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.
+<div align="center">
+<br><h1>Discord Level Importer</h1>
+  <br>An open, JavaScript-based library for importing leveling data from MEE6 and other bots.<br>
+  <br><br><a href="https://www.hokki.app"><img height="100" src="https://raw.githubusercontent.com/hokkiai/djs-level-importer/refs/heads/master/assets/sokoraXhokki.png?raw=true"></a>
+  <br>Made jointly by the <a href="https://sokora.org">Sokora</a> and <a href="https://www.hokki.app">Hokki</a> Discord bots.
+</div>
+<br>
+<br>
 
 ## Usage
 
@@ -60,15 +64,16 @@ This interface division is not the most intuitive, but the best thing we can do
 
 ## Bot support
 
-As of now, MEE6, Lurkr, 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.
+As of now, MEE6, Lurkr, Tatsu and Amari 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. You can check `TODO.txt` at the root of this repo for a list of planned (or discarded) bots, and you may suggest any bot you know about that isn't listed there by opening an issue.
 
-**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:
+**Bots are selected using integers** when calling `GetLeaderboard`. You can check integer-bot associations by looking at the exported `SupportedBots` TypeScript enum. Or just look at it here:
 
 ```ts
 export enum SupportedBots {
   MEE6 = 0,
   TATSU = 1,
   LURKR = 2,
+  AMARI = 3,
 }
 ```
 
@@ -104,6 +109,16 @@ Lastly, you need to manually change `Choose the visibility for the web leaderboa
 
 Nothing is required. -->
 
+#### Amari
+
+You need an API key, obtained by manually requesting it from Amari's Discord server at [this link](https://amaribot.com/support) and passed to the constructor via the `amari_api` parameter.
+
+```ts
+new Leveler({ guild: "...", amari_api: "123ABC..." });
+```
+
+> It's worth noting we tried to get it ourselves to test and were told that they're currently not issuing API keys as they're redoing the system or something like that.
+
 ## 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).

package/dist/lurkr.d.ts

@@ -0,0 +1,56 @@
+/** Lurkr API docs have a "copy TypeScript definitions" for this */
+export interface LURKRResponse {
+    guild: {
+        icon: string | null;
+        id: string;
+        memberCount: number;
+        name: string;
+    };
+    isManager: boolean;
+    levels: {
+        level: number;
+        messageCount: number;
+        nextLevelXp: number;
+        progress: number;
+        rank: number;
+        user: {
+            accentColour: string | null;
+        } & any;
+        userId: string;
+        xp: number;
+    }[];
+    multipliers: {
+        id: string;
+        multiplier: number;
+        targets: any[];
+        type: "Channel" | "Role";
+    }[];
+    roleRewards: {
+        id: string;
+        level: number;
+        roles: any[];
+    }[];
+    vanity: string | null;
+    /**
+     * The cooldown period for XP gain in seconds
+     */
+    xpGainInterval: number;
+    xpGlobalMultiplier: number;
+    /**
+     * Maximum XP to gain per message
+     */
+    xpPerMessageMax: number;
+    /**
+     * Minimum XP to gain per message
+     */
+    xpPerMessageMin: number;
+}
+/**
+ * Get the leaderboard of a guild.
+ *
+ * @async
+ * @param {(string | null)} tkn API token for Lurkr.
+ * @param {string} guildId Guild to get the leaderboard from.
+ * @returns {Promise<LURKRResponse["levels"]>} Leaderboard of the guild.
+ */
+export declare function LURKRGetLeaderboard(tkn: string | null, guildId: string): Promise<LURKRResponse["levels"]>;

package/dist/lurkr.js

@@ -0,0 +1,27 @@
+/**
+ * Get the leaderboard of a guild.
+ *
+ * @async
+ * @param {(string | null)} tkn API token for Lurkr.
+ * @param {string} guildId Guild to get the leaderboard from.
+ * @returns {Promise<LURKRResponse["levels"]>} Leaderboard of the guild.
+ */
+export async function LURKRGetLeaderboard(tkn, guildId) {
+    if (!tkn)
+        throw "No Lurkr API key provided. Cannot use Lurkr API.";
+    const leaderboard = [];
+    let pageNumber = 1;
+    while (true) {
+        const page = await fetch(`https://api.lurkr.gg/v2/levels/${guildId}?page=${pageNumber}`, {
+            method: "GET",
+        });
+        const content = (await page.json());
+        if (!page.ok)
+            throw `Failed to import from Lurkr: ${content.message}`;
+        leaderboard.push(...content.levels);
+        if (content.levels.length < 1000)
+            break;
+        pageNumber += 1;
+    }
+    return leaderboard;
+}

package/dist/main.d.ts

@@ -26,8 +26,13 @@ export interface BaseUserLevels {
  * @interface FullUserLevels
  */
 export interface FullUserLevels extends BaseUserLevels {
-    /** Current XP **relative to the level**. */
-    current_lvl_xp: number;
+    /** Current XP **relative to the level**.
+     *
+     * Not all APIs return this, therefore it's optional.
+     *
+     * @deprecated Should've thought about this when initially designing the API. Next major release will probably just remove this property entirely, as it's not that useful anyway. Try not to depend on it.
+     */
+    current_lvl_xp?: number;
     /** Current level. */
     lvl: number;
     /** XP required to level up. */
@@ -40,30 +45,33 @@ export declare function SUPPORTS_LEVELS(a: any): a is FullUserLevels;
  *
  * ```ts
  * MEE6 = 0,
- * TATSU = 1
+ * TATSU = 1,
+ * LURKR = 2,
  * ```
  * @enum {number}
  */
 export declare enum SupportedBots {
     MEE6 = 0,
-    TATSU = 1
+    TATSU = 1,
+    LURKR = 2
 }
 export declare class Leveler {
     private guild;
     private tatsu_api;
+    private lurkr_api;
     /**
      * 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.
+     * @param {?string} lurkr_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;
+        lurkr_api?: string;
     });
-    /** Gets the whole server leaderboard from MEE6. Throws if unable to get it. */
-    GetLeaderboard(target: SupportedBots.MEE6): Promise<FullUserLevels[]>;
-    /** Gets the whole server leaderboard from Tatsu. Throws if unable to get it. */
-    GetLeaderboard(target: SupportedBots.TATSU): Promise<BaseUserLevels[]>;
+    /** Gets the whole server leaderboard from a supported bot. Throws if unable to get it. */
+    GetLeaderboard(target: SupportedBots): Promise<BaseUserLevels[] | FullUserLevels[]>;
 }

package/dist/main.js

@@ -1,3 +1,4 @@
+import { LURKRGetLeaderboard } from "./lurkr.js";
 import { MEE6GetLeaderboard } from "./mee6.js";
 import { TATSUGetLeaderboard } from "./tatsu.js";
 /**
@@ -23,7 +24,8 @@ export function SUPPORTS_LEVELS(a) {
  *
  * ```ts
  * MEE6 = 0,
- * TATSU = 1
+ * TATSU = 1,
+ * LURKR = 2,
  * ```
  * @enum {number}
  */
@@ -31,26 +33,32 @@ export var SupportedBots;
 (function (SupportedBots) {
     SupportedBots[SupportedBots["MEE6"] = 0] = "MEE6";
     SupportedBots[SupportedBots["TATSU"] = 1] = "TATSU";
+    SupportedBots[SupportedBots["LURKR"] = 2] = "LURKR";
 })(SupportedBots || (SupportedBots = {}));
 export class Leveler {
     guild;
     tatsu_api = null;
+    lurkr_api = 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.
+     * @param {?string} lurkr_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) {
         this.guild = options.guild;
         if (options.tatsu_api)
             this.tatsu_api = options.tatsu_api;
+        if (options.lurkr_api)
+            this.lurkr_api = options.lurkr_api;
     }
+    /** Gets the whole server leaderboard from a supported bot. Throws if unable to get it. */
     async GetLeaderboard(target) {
         if (target === SupportedBots.MEE6) {
             const levels = await MEE6GetLeaderboard(this.guild);
-            return levels.map(u => {
+            return levels.map((u) => {
                 return {
                     uid: u.id,
                     lvl: u.level,
@@ -60,12 +68,23 @@ export class Leveler {
                 };
             });
         }
+        else if (target === SupportedBots.LURKR) {
+            const levels = await LURKRGetLeaderboard(this.lurkr_api, this.guild);
+            return levels.map((u) => {
+                return {
+                    uid: u.userId,
+                    lvl: u.level,
+                    current_xp: u.xp,
+                    next_lvl_xp: u.nextLevelXp,
+                };
+            });
+        }
         else {
             const levels = await TATSUGetLeaderboard(this.tatsu_api, this.guild);
-            return levels.rankings.map(r => {
+            return levels.rankings.map((u) => {
                 return {
-                    uid: r.user_id,
-                    current_xp: r.score,
+                    uid: u.user_id,
+                    current_xp: u.score,
                 };
             });
         }

package/dist/tatsu.js

@@ -10,7 +10,7 @@ import { Tatsu } from "tatsu";
  */
 export async function TATSUGetLeaderboard(tkn, guildId) {
     if (!tkn)
-        throw `No Tatsu API key provided. Cannot use Tatsu API.`;
+        throw "No Tatsu API key provided. Cannot use Tatsu API.";
     const tatsu = new Tatsu(tkn);
     return await tatsu.getGuildRankings(guildId);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hokkiai/djs-level-importer",
-  "version": "1.1.0",
+  "version": "1.2.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",