kol.js 0.3.0 → 0.4.0

package/src/{utils/leaderboard.test.ts → domains/Leaderboard.test.ts}

@@ -1,11 +1,14 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { loadFixture } from "../testUtils.js";
-import { parseLeaderboard } from "./leaderboard.js";
+import { Leaderboard } from "./Leaderboard.js";
 
 describe("Leaderboards", () => {
   it("can parse a regular path leaderboard", async () => {
-    const page = await loadFixture(__dirname, "leaderboard_wotsf.html");
-    const leaderboard = parseLeaderboard(page);
+    const page = await loadFixture(
+      import.meta.dirname,
+      "leaderboard_wotsf.html",
+    );
+    const leaderboard = Leaderboard.parse(page);
 
     // Group name
     expect(leaderboard.name).toBe(
@@ -45,3 +48,20 @@ describe("Leaderboards", () => {
     );
   });
 });
+
+describe("boardIdForStandardYear", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns 999 for the current year", () => {
+    vi.useFakeTimers({ now: new Date("2026-06-15") });
+    expect(Leaderboard.boardIdForStandardYear(2026)).toBe(999);
+  });
+
+  it("returns the correct id for a past year", () => {
+    expect(Leaderboard.boardIdForStandardYear(2015)).toBe(998);
+    expect(Leaderboard.boardIdForStandardYear(2016)).toBe(997);
+    expect(Leaderboard.boardIdForStandardYear(2020)).toBe(993);
+  });
+});

package/src/domains/Leaderboard.ts

@@ -0,0 +1,173 @@
+import { selectAll, selectOne } from "css-select";
+import { parseDocument } from "htmlparser2";
+import { Element, isComment, Text } from "domhandler";
+import { innerText } from "domutils";
+
+import type { Client } from "../Client.js";
+
+export type LeaderboardInfo = {
+  name: string;
+  boards: SubboardInfo[];
+};
+
+export type SubboardInfo = {
+  name: string;
+  runs: RunInfo[];
+  updated: Date | null;
+};
+
+export type RunInfo = {
+  playerName: string;
+  playerId: number;
+  days: string;
+  turns: string;
+};
+
+const BOARD_MAPPINGS = {
+  "Clan Dungeons": 8,
+  "Bees Hate You": 9,
+  "Way of the Surprising Fist": 10,
+  Trendy: 11,
+  "Avatar of Boris": 12,
+  "Bugbear Invasion": 13,
+  "Zombie Slayer": 14,
+  "Class Act": 15,
+  "Avatar of Jarlsberg": 16,
+  "BIG!": 17,
+  KOLHS: 18,
+  "Class Act II": 19,
+  "Avatar of Sneaky Pete": 20,
+  "Slow and Steady": 21,
+  "Heavy Rains": 22,
+  Picky: 23,
+  "Actually Ed the Undying": 24,
+  "One Crazy Random Summer": 25,
+  "Community Service": 26,
+  Batfellow: 27,
+  "Avatar of West of Loathing": 28,
+  "The Source": 29,
+  "Nuclear Autumn": 30,
+  "Gelatinous Noob": 31,
+  "License to Adventure": 32,
+  "Live. Ascend. Repeat.": 33,
+  "Pocket Familiars": 34,
+  "G Lover": 35,
+  "Disguises Delimit": 36,
+  "Dark Gyffte": 37,
+  "Two Crazy Random Summer": 38,
+  "Kingdom of Exploathing": 39,
+  "Path of the Plumber": 40,
+  "Low Key Summer": 41,
+  "Grey Goo": 42,
+  "You, Robot": 43,
+  "Quantum Terrarium": 44,
+  "Wild Fire": 45,
+  "Grey You": 46,
+  Journeyman: 47,
+  "Fall of the Dinosaurs": 48,
+  "Avatars of Shadows Over Loathing": 49,
+  "Legacy of Loathing": 50,
+  "A Shrunken Adventurer am I": 51,
+  WereProfessor: 52,
+  "11 Things I Hate About U": 53,
+  "Avant Guard": 54,
+  "Z is for Zootomist": 55,
+  "Hat Trick": 56,
+  "11,037 Leagues Under the Sea": 57,
+  Standard: 999,
+  "Elf Gratitude": 900,
+} as const;
+
+export { BOARD_MAPPINGS };
+
+export type BoardName = keyof typeof BOARD_MAPPINGS;
+
+const blankNode = new Text("");
+
+export class Leaderboard {
+  #client: Client;
+
+  constructor(client: Client) {
+    this.#client = client;
+  }
+
+  static get boardNames(): BoardName[] {
+    return Object.keys(BOARD_MAPPINGS) as BoardName[];
+  }
+
+  static boardIdFor(name: BoardName): number {
+    return BOARD_MAPPINGS[name];
+  }
+
+  static boardIdForStandardYear(year: number): number {
+    if (year === new Date().getFullYear()) return 999;
+    return 998 + 2015 - year;
+  }
+
+  static parse(page: string): LeaderboardInfo {
+    const doc = parseDocument(page);
+    const [container, ...boards] = selectAll("table", doc);
+
+    return {
+      name: innerText(selectOne("tr", container) ?? blankNode)
+        .replace(/\s+/g, " ")
+        .trim(),
+      boards: boards
+        .slice(1)
+        .filter((board) => {
+          if (selectAll(":scope > tr, :scope > tbody > tr", board).length <= 1)
+            return false;
+          const text = innerText(selectOne("tr", board) ?? blankNode);
+          return text.match(/^((Fast|Funn|B)est|Most (Goo|Elf))/);
+        })
+        .map((subboard) => {
+          const rows = selectAll("tr", subboard);
+
+          return {
+            name: innerText(rows[0]),
+            runs: selectAll("td tr", rows[1])
+              .slice(2)
+              .map((node) => {
+                const rowText = selectAll("td", node).map((col) =>
+                  innerText(col).replace(/&amp;nbsp;/g, ""),
+                );
+                const playerLink = (selectOne("a", node) as Element | null)
+                  ?.attribs.href;
+                const hasTwoNumbers = !!parseInt(rowText[rowText.length - 2]);
+                return {
+                  playerName: rowText
+                    .slice(0, rowText.length - (hasTwoNumbers ? 2 : 1))
+                    .join("")
+                    .trim()
+                    .toString(),
+                  playerId: Number(
+                    playerLink?.substring(playerLink.indexOf("who=") + 4) ??
+                      "0",
+                  ),
+                  days: hasTwoNumbers
+                    ? rowText[rowText.length - 2].toString() || "0"
+                    : "",
+                  turns: rowText[rowText.length - 1].toString() || "0",
+                };
+              }),
+            updated:
+              subboard.nextSibling && isComment(subboard.nextSibling)
+                ? new Date(subboard.nextSibling.data.slice(9, -1))
+                : null,
+          };
+        }),
+    };
+  }
+
+  async getLeaderboard(boardId: number): Promise<LeaderboardInfo> {
+    const page = await this.#client.fetchText("museum.php", {
+      query: {
+        floor: 1,
+        place: "leaderboards",
+        whichboard: boardId,
+      },
+    });
+
+    return Leaderboard.parse(page);
+  }
+}

package/src/domains/Players.test.ts

@@ -0,0 +1,141 @@
+import * as path from "node:path";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import { loadFixture } from "../testUtils.js";
+import { Client } from "../Client.js";
+import { Player } from "../Player.js";
+
+const fixturesDir = path.resolve(import.meta.dirname, "..");
+
+const { json, text } = vi.hoisted(() => ({ json: vi.fn(), text: vi.fn() }));
+
+vi.mock("../Client.js", async (importOriginal) => {
+  const client = await importOriginal<typeof import("../Client.js")>();
+  client.Client.prototype.login = async () => true;
+  client.Client.prototype.checkLoggedIn = async () => true;
+  client.Client.prototype.fetchText = text;
+  client.Client.prototype.fetchJson = json;
+  return client;
+});
+
+let client: Client;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  client = new Client("", "");
+});
+
+describe("Players.resolve", () => {
+  test("resolves a player by name via search", async () => {
+    text.mockResolvedValueOnce(
+      await loadFixture(fixturesDir, "searchplayer_mad_carew.html"),
+    );
+
+    const player = await client.players.resolve("mad carew");
+
+    expect(player).not.toBeNull();
+    expect(player!.id).toBe(263717);
+    expect(player!.name).toBe("Mad Carew");
+    expect(player).toBeInstanceOf(Player);
+    expect(player).not.toBeInstanceOf(Player.Profiled);
+  });
+
+  test("returns null for unknown player", async () => {
+    text.mockResolvedValueOnce("<html>No results</html>");
+
+    const player = await client.players.resolve("nonexistent");
+
+    expect(player).toBeNull();
+  });
+
+  test("returns cached player on second call", async () => {
+    text.mockResolvedValueOnce(
+      await loadFixture(fixturesDir, "searchplayer_mad_carew.html"),
+    );
+
+    const first = await client.players.resolve("mad carew");
+    const second = await client.players.resolve("Mad Carew");
+
+    expect(first).toBe(second);
+    expect(text).toHaveBeenCalledTimes(1);
+  });
+
+  test("can resolve by id after resolving by name", async () => {
+    text.mockResolvedValueOnce(
+      await loadFixture(fixturesDir, "searchplayer_mad_carew.html"),
+    );
+
+    const byName = await client.players.resolve("mad carew");
+    const byId = await client.players.resolve(263717);
+
+    expect(byName).toBe(byId);
+    expect(text).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("Players.fetch", () => {
+  test("fetches a full profile", async () => {
+    // First call: search
+    text.mockResolvedValueOnce(
+      await loadFixture(fixturesDir, "searchplayer_mad_carew.html"),
+    );
+    // Second call: whois (for id resolution)
+    // Third call: profile
+    text.mockResolvedValueOnce(
+      await loadFixture(fixturesDir, "showplayer_regular.html"),
+    );
+
+    const profiled = await client.players.fetch("mad carew");
+
+    expect(profiled).not.toBeNull();
+    expect(profiled).toBeInstanceOf(Player.Profiled);
+    expect(profiled!.id).toBe(263717);
+    expect(profiled!.avatar).toContain("<svg");
+    expect(profiled!.ascensions).toBeGreaterThan(0);
+  });
+
+  test("returns cached Profiled on second call", async () => {
+    text.mockResolvedValueOnce(
+      await loadFixture(fixturesDir, "searchplayer_mad_carew.html"),
+    );
+    text.mockResolvedValueOnce(
+      await loadFixture(fixturesDir, "showplayer_regular.html"),
+    );
+
+    const first = await client.players.fetch("mad carew");
+    const second = await client.players.fetch(263717);
+
+    expect(first).toBe(second);
+  });
+
+  test("returns null when profile parsing fails", async () => {
+    text.mockResolvedValueOnce(
+      await loadFixture(fixturesDir, "searchplayer_mad_carew.html"),
+    );
+    text.mockResolvedValueOnce("<html>Not a profile</html>");
+
+    const profiled = await client.players.fetch("mad carew");
+
+    expect(profiled).toBeNull();
+  });
+});
+
+describe("Players.getNameFromId", () => {
+  test("parses name from whois response", async () => {
+    text.mockResolvedValueOnce(
+      '<a target=mainpane href="showplayer.php?who=263717"><b>Mad Carew (#263717)</b></a>',
+    );
+
+    const name = await client.players.getNameFromId(263717);
+
+    expect(name).toBe("Mad Carew");
+  });
+
+  test("returns null on error", async () => {
+    text.mockRejectedValueOnce(new Error("network error"));
+
+    const name = await client.players.getNameFromId(999);
+
+    expect(name).toBeNull();
+  });
+});

package/src/domains/Players.ts

@@ -0,0 +1,108 @@
+import type { Client } from "../Client.js";
+import { Player } from "../Player.js";
+
+type SearchData = { level: number; kolClass: string };
+
+export class Players {
+  #client: Client;
+  #byId = new Map<number, Player>();
+  #nameToId = new Map<string, number>();
+  #searchData = new Map<number, SearchData>();
+
+  constructor(client: Client) {
+    this.#client = client;
+  }
+
+  #getCached(identifier: string | number): Player | undefined {
+    const id = Number(identifier);
+    if (!Number.isNaN(id) || typeof identifier === "number") {
+      return this.#byId.get(id);
+    }
+    const resolvedId = this.#nameToId.get(String(identifier).toLowerCase());
+    return resolvedId !== undefined ? this.#byId.get(resolvedId) : undefined;
+  }
+
+  #cache(player: Player, searchData?: SearchData): void {
+    this.#byId.set(player.id, player);
+    this.#nameToId.set(player.name.toLowerCase(), player.id);
+    if (searchData) this.#searchData.set(player.id, searchData);
+  }
+
+  async resolve(identifier: string | number): Promise<Player | null> {
+    return this.#getCached(identifier) ?? this.#resolveUncached(identifier);
+  }
+
+  async fetch(identifier: string | number): Promise<Player.Profiled | null> {
+    const cached = this.#getCached(identifier);
+    if (cached instanceof Player.Profiled) return cached;
+
+    const identity = cached ?? (await this.#resolveUncached(identifier));
+    if (!identity) return null;
+
+    const html = await this.#client.fetchText("showplayer.php", {
+      query: { who: identity.id },
+    });
+
+    const profileData = await Player.Profiled.parseProfile(html);
+    if (!profileData) return null;
+
+    const search = this.#searchData.get(identity.id);
+
+    const profiled = new Player.Profiled(this.#client, {
+      id: identity.id,
+      name: identity.name,
+      level: search?.level ?? 0,
+      kolClass: search?.kolClass ?? "Unknown",
+      ...profileData,
+    });
+
+    this.#cache(profiled);
+    return profiled;
+  }
+
+  async getNameFromId(id: number): Promise<string | null> {
+    try {
+      const html = await this.#client.fetchText("submitnewchat.php", {
+        query: { graf: `/whois ${id}` },
+      });
+      return Player.parseNameFromWhois(html);
+    } catch {
+      return null;
+    }
+  }
+
+  async #resolveUncached(identifier: string | number): Promise<Player | null> {
+    const id = Number(identifier);
+
+    if (!Number.isNaN(id) || typeof identifier === "number") {
+      const name = await this.getNameFromId(id);
+      if (!name) return null;
+      return this.#resolveByName(name);
+    }
+
+    return this.#resolveByName(identifier as string);
+  }
+
+  async #resolveByName(name: string): Promise<Player | null> {
+    try {
+      const html = await this.#client.fetchText("searchplayer.php", {
+        query: {
+          searchstring: name.replace(/_/g, "\\_"),
+          searching: "Yep.",
+          for: "",
+          startswith: 1,
+          hardcoreonly: 0,
+        },
+      });
+
+      const result = Player.parseSearch(html);
+      if (!result) return null;
+
+      const player = new Player(this.#client, result.id, result.name);
+      this.#cache(player, { level: result.level, kolClass: result.kolClass });
+      return player;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/domains/Raffle.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { Client } from "../Client.js";
+import { loadFixture } from "../testUtils.js";
+import { Raffle } from "./Raffle.js";
+
+const { json, text } = vi.hoisted(() => ({ json: vi.fn(), text: vi.fn() }));
+
+vi.mock("../Client.js", async (importOriginal) => {
+  const client = await importOriginal<typeof import("../Client.js")>();
+  client.Client.prototype.login = async () => true;
+  client.Client.prototype.checkLoggedIn = async () => true;
+  client.Client.prototype.fetchText = text;
+  client.Client.prototype.fetchJson = json;
+  return client;
+});
+
+const client = new Client("", "");
+
+describe("Raffle", () => {
+  it("can fetch the current raffle", async () => {
+    text.mockResolvedValueOnce(
+      await loadFixture(import.meta.dirname, "raffle.html"),
+    );
+    text.mockResolvedValueOnce("<!-- itemid: 1 -->");
+    text.mockResolvedValueOnce("<!-- itemid: 2 -->");
+    text.mockResolvedValueOnce("<!-- itemid: 3 -->");
+    text.mockResolvedValueOnce("<!-- itemid: 4 -->");
+    text.mockResolvedValueOnce("<!-- itemid: 4 -->");
+    text.mockResolvedValueOnce("<!-- itemid: 4 -->");
+    json.mockResolvedValueOnce({ daynumber: "100" });
+
+    const raffle = new Raffle(client);
+    const result = await raffle.getRaffle();
+
+    expect(result).toMatchObject({
+      today: {
+        first: 1,
+        second: 2,
+      },
+      yesterday: [
+        {
+          player: { id: 809337, name: "Collective Consciousness" },
+          item: 3,
+          tickets: 3333,
+        },
+        {
+          player: { id: 852958, name: "Ryo_Sangnoir" },
+          item: 4,
+          tickets: 1011,
+        },
+        {
+          player: { id: 1765063, name: "SSpectre_Karasu" },
+          item: 4,
+          tickets: 1000,
+        },
+        {
+          player: { id: 1652370, name: "yueli7" },
+          item: 4,
+          tickets: 2040,
+        },
+      ],
+    });
+  });
+});

package/src/domains/Raffle.ts

@@ -0,0 +1,60 @@
+import type { Client } from "../Client.js";
+import { Player } from "../Player.js";
+
+export type RaffleWinner = {
+  player: Player;
+  item: number;
+  tickets: number;
+  place: number;
+};
+
+export type RaffleResult = {
+  today: { first: number | null; second: number | null };
+  yesterday: RaffleWinner[];
+  gameday: number;
+};
+
+export class Raffle {
+  #client: Client;
+
+  constructor(client: Client) {
+    this.#client = client;
+  }
+
+  async getRaffle(): Promise<RaffleResult> {
+    const page = await this.#client.fetchText("raffle.php");
+
+    const todayMatches = page.matchAll(
+      /<tr><td align=right>(?:First|Second) Prize:<\/td>.*?descitem\((\d+)\)/g,
+    );
+    const [first, second] = await Promise.all(
+      todayMatches
+        ? [...todayMatches].map(
+            async (p) => await this.#client.descIdToId(Number(p[1])),
+          )
+        : [null, null],
+    );
+
+    const winnerMatches = page.matchAll(
+      /<tr><td class=small><a href='showplayer\.php\?who=\d+'>(.*?) \(#(\d+)\).*?descitem\((\d+)\).*?([\d,]+)<\/td><\/tr>/g,
+    );
+    const yesterday = await Promise.all(
+      winnerMatches
+        ? [...winnerMatches].map(async (w, i) => ({
+            player: new Player(this.#client, Number(w[2]), w[1]),
+            item: await this.#client.descIdToId(Number(w[3])),
+            tickets: Number(w[4].replace(",", "")),
+            place: Math.min(i + 1, 2),
+          }))
+        : [],
+    );
+
+    const { daynumber } = await this.#client.fetchStatus();
+
+    return {
+      today: { first: first ?? null, second: second ?? null },
+      yesterday,
+      gameday: Number(daynumber),
+    };
+  }
+}

package/src/domains/SkeletonOfCrimboPast.test.ts

@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { Client } from "../Client.js";
+import { loadFixture } from "../testUtils.js";
+import { SkeletonOfCrimboPast } from "./SkeletonOfCrimboPast.js";
+
+const { text } = vi.hoisted(() => ({ text: vi.fn() }));
+
+vi.mock("../Client.js", async (importOriginal) => {
+  const client = await importOriginal<typeof import("../Client.js")>();
+  client.Client.prototype.login = async () => true;
+  client.Client.prototype.checkLoggedIn = async () => true;
+  client.Client.prototype.fetchText = text;
+  return client;
+});
+
+const client = new Client("", "");
+
+const terrariumWithSocp = `onClick='fam(326)'><img src="https://d2uyhvukfffg5a.cloudfront.net/itemimages/socp.gif" 1-pound Skeleton of Crimbo Past (`;
+
+describe("SkeletonOfCrimboPast", () => {
+  beforeEach(() => text.mockReset());
+
+  it("returns null if player has no familiar", async () => {
+    text.mockResolvedValueOnce(""); // empty terrarium
+    const socp = new SkeletonOfCrimboPast(client);
+    expect(await socp.getDailySpecial()).toBeNull();
+  });
+
+  it("caches the familiar check", async () => {
+    text.mockResolvedValueOnce(""); // empty terrarium
+    const socp = new SkeletonOfCrimboPast(client);
+    await socp.getDailySpecial();
+    await socp.getDailySpecial();
+    // getFamiliars only called once
+    expect(text).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns null if page does not match", async () => {
+    text.mockResolvedValueOnce(terrariumWithSocp);
+    text.mockResolvedValueOnce("<html>no match here</html>");
+    const socp = new SkeletonOfCrimboPast(client);
+    expect(await socp.getDailySpecial()).toBeNull();
+  });
+
+  it("parses the daily special", async () => {
+    text.mockResolvedValueOnce(terrariumWithSocp);
+    text.mockResolvedValueOnce(
+      await loadFixture(import.meta.dirname, "socp.html"),
+    );
+    const socp = new SkeletonOfCrimboPast(client);
+    const special = await socp.getDailySpecial();
+    expect(special).toEqual({ descId: 153919945, price: 1388 });
+  });
+});

package/src/domains/SkeletonOfCrimboPast.ts

@@ -0,0 +1,38 @@
+import type { Client } from "../Client.js";
+
+export interface DailySpecial {
+  descId: number;
+  price: number;
+}
+
+export class SkeletonOfCrimboPast {
+  #client: Client;
+  #hasFamiliar: boolean | null = null;
+
+  constructor(client: Client) {
+    this.#client = client;
+  }
+
+  async hasFamiliar(): Promise<boolean> {
+    if (this.#hasFamiliar === null) {
+      const fams = await this.#client.getFamiliars();
+      this.#hasFamiliar = fams.some((f) => f.id === 326);
+    }
+    return this.#hasFamiliar;
+  }
+
+  async getDailySpecial(): Promise<DailySpecial | null> {
+    if (!(await this.hasFamiliar())) return null;
+
+    const page = await this.#client.fetchText("main.php", {
+      query: { talktosocp: "1" },
+    });
+
+    const match = page.match(
+      /Daily Special:.*?descitem\((\d+)\).*?\((\d+) knucklebones\)/,
+    );
+
+    if (!match) return null;
+    return { descId: Number(match[1]), price: Number(match[2]) };
+  }
+}