kol.js 0.0.1

package/dist/Cache.d.ts

@@ -0,0 +1,11 @@
+import { Client } from "./Client.js";
+import { Player } from "./Player.js";
+export declare class Cache<T> {
+    client: Client;
+    constructor(client: Client);
+    cache: T[];
+}
+export declare class PlayerCache extends Cache<Player<boolean>> {
+    fetch(identifier: string | number, full: true): Promise<Player<true>>;
+    fetch(identifier: string | number): Promise<Player<boolean>>;
+}

package/dist/Cache.js

@@ -0,0 +1,26 @@
+import { Player } from "./Player.js";
+export class Cache {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    cache = [];
+}
+export class PlayerCache extends Cache {
+    async fetch(identifier, full = false) {
+        const player = await (async () => {
+            const cached = this.cache.find(p => p.matchesIdentifier(identifier));
+            if (cached) {
+                return cached;
+            }
+            const fetched = await Player.from(this.client, identifier);
+            if (!fetched)
+                return null;
+            this.cache.push(fetched);
+            return fetched;
+        })();
+        if (!player)
+            return player;
+        return full ? await player.full() : player;
+    }
+}

package/dist/Client.d.ts

@@ -0,0 +1,78 @@
+import { Mutex } from "async-mutex";
+import TypedEventEmitter, { EventMap } from "typed-emitter";
+import { KoLMessage } from "./utils/kmail.js";
+import { PlayerCache } from "./Cache.js";
+type TypedEmitter<T extends EventMap> = TypedEventEmitter.default<T>;
+type FetchOptions<Result> = {
+    params?: Record<string, string | number>;
+    body?: Record<string, string | number>;
+    method?: "POST" | "GET";
+    fallback?: Result;
+};
+type MallPrice = {
+    formattedMallPrice: string;
+    formattedLimitedMallPrice: string;
+    formattedMinPrice: string;
+    mallPrice: number;
+    limitedMallPrice: number;
+    minPrice: number | null;
+};
+type Events = {
+    kmail: (message: KoLMessage) => void;
+    whisper: (message: KoLMessage) => void;
+    system: (message: KoLMessage) => void;
+    public: (message: KoLMessage) => void;
+    rollover: () => void;
+};
+declare const Client_base: new () => TypedEmitter<Events>;
+export declare class Client extends Client_base {
+    #private;
+    static loginMutex: Mutex;
+    actionMutex: Mutex;
+    session: import("fetch-cookie").FetchCookieImpl<string | URL | Request, RequestInit, Response>;
+    players: PlayerCache;
+    private lastFetchedMessages;
+    private postRolloverLatch;
+    constructor(username: string, password: string);
+    fetchText(path: string, options?: FetchOptions<string>): Promise<string>;
+    fetchJson<Result>(path: string, options?: FetchOptions<Result>): Promise<Result | null>;
+    login(): Promise<boolean>;
+    isRollover(): boolean;
+    checkLoggedIn(): Promise<boolean>;
+    startChatBot(): Promise<void>;
+    private loopChatBot;
+    checkMessages(): Promise<void>;
+    checkKmails(): Promise<void>;
+    sendChat(message: string): Promise<{
+        output: string;
+        msgs: string[];
+    } | null>;
+    useChatMacro(macro: string): Promise<{
+        output: string;
+        msgs: string[];
+    } | null>;
+    whisper(recipientId: number, message: string): Promise<void>;
+    kmail(recipientId: number, message: string): Promise<void>;
+    getMallPrice(itemId: number): Promise<MallPrice>;
+    getItemDescription(descId: number): Promise<{
+        melting: boolean;
+        singleEquip: boolean;
+        blueText: string;
+        effect?: {
+            name: string;
+            duration: number;
+            descid: string;
+        };
+    }>;
+    getEffectDescription(descId: string): Promise<{
+        blueText: string;
+    }>;
+    getSkillDescription(id: number): Promise<{
+        blueText: string;
+    }>;
+    joinClan(id: number): Promise<boolean>;
+    addToWhitelist(playerId: number, clanId: number): Promise<boolean>;
+    getLeaderboard(leaderboardId: number): Promise<import("./utils/leaderboard.js").LeaderboardInfo>;
+    useFamiliar(familiarId: number): Promise<void>;
+}
+export {};

package/dist/Client.js

@@ -0,0 +1,325 @@
+import { Mutex } from "async-mutex";
+import { EventEmitter } from "node:events";
+import { sanitiseBlueText, wait } from "./utils/utils.js";
+import { Player } from "./Player.js";
+import { createBody, createSession, formatQuerystring } from "./utils/visit.js";
+import { parseLeaderboard } from "./utils/leaderboard.js";
+import { isValidMessage, } from "./utils/kmail.js";
+import { PlayerCache } from "./Cache.js";
+export class Client extends EventEmitter {
+    static loginMutex = new Mutex();
+    actionMutex = new Mutex();
+    session = createSession();
+    players = new PlayerCache(this);
+    #username;
+    #password;
+    #isRollover = false;
+    #chatBotStarted = false;
+    #pwd = "";
+    lastFetchedMessages = "0";
+    postRolloverLatch = false;
+    constructor(username, password) {
+        super();
+        this.#username = username;
+        this.#password = password;
+    }
+    async #fetch(path, options = {}) {
+        const { params, body, method } = {
+            params: {},
+            body: undefined,
+            method: "POST",
+            ...options,
+        };
+        const qs = formatQuerystring(params);
+        return await this.session(`https://www.kingdomofloathing.com/${path}${qs ? `?${qs}` : ""}`, {
+            method,
+            body: body ? createBody({ ...body, pwd: this.#pwd }) : undefined,
+        });
+    }
+    async fetchText(path, options = {}) {
+        if (!await this.login())
+            return options.fallback ?? "";
+        return (await this.#fetch(path, options)).text();
+    }
+    async fetchJson(path, options = {}) {
+        if (!await this.login())
+            return options.fallback ?? null;
+        return (await this.#fetch(path, options)).json();
+    }
+    async login() {
+        if (this.#isRollover)
+            return false;
+        return Client.loginMutex.runExclusive(async () => {
+            if (await this.checkLoggedIn())
+                return true;
+            if (this.#isRollover)
+                return false;
+            try {
+                const response = await this.#fetch("login.php", {
+                    body: {
+                        loggingin: "Yup.",
+                        loginname: this.#username,
+                        password: this.#password,
+                        secure: "0",
+                        submitbutton: "Log In",
+                    },
+                });
+                await response.text();
+                if (!(await this.checkLoggedIn()))
+                    return false;
+                if (this.postRolloverLatch) {
+                    this.postRolloverLatch = false;
+                    this.emit("rollover");
+                }
+                return true;
+            }
+            catch (error) {
+                console.log("error", error);
+                // Login failed, let's check if it is due to rollover
+                await this.#checkForRollover();
+                return false;
+            }
+        });
+    }
+    isRollover() {
+        return this.#isRollover;
+    }
+    async checkLoggedIn() {
+        try {
+            const response = await this.#fetch("api.php", {
+                params: { what: "status", for: `${this.#username} bot` },
+            });
+            const api = (await response.json());
+            this.#pwd = api.pwd;
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    async #checkForRollover() {
+        const isRollover = /The system is currently down for nightly maintenance/.test(await this.fetchText("/"));
+        if (this.#isRollover && !isRollover) {
+            // Set the post-rollover latch so the bot can react on next log in.
+            this.postRolloverLatch = true;
+        }
+        this.#isRollover = isRollover;
+        if (this.#isRollover) {
+            // Rollover appears to be in progress. Check again in one minute.
+            setTimeout(() => this.#checkForRollover(), 60000);
+        }
+    }
+    async startChatBot() {
+        if (this.#chatBotStarted)
+            return;
+        await this.useChatMacro("/join talkie");
+        this.loopChatBot();
+        this.#chatBotStarted = true;
+    }
+    async loopChatBot() {
+        await Promise.all([this.checkMessages(), this.checkKmails()]);
+        await wait(3000);
+        await this.loopChatBot();
+    }
+    async checkMessages() {
+        const newChatMessagesResponse = await this.fetchJson("newchatmessages.php", {
+            params: {
+                j: 1,
+                lasttime: this.lastFetchedMessages,
+            },
+        });
+        if (!newChatMessagesResponse || typeof newChatMessagesResponse !== "object")
+            return;
+        this.lastFetchedMessages = newChatMessagesResponse["last"];
+        newChatMessagesResponse["msgs"]
+            .filter(isValidMessage)
+            .map((msg) => ({
+            type: msg.type,
+            who: new Player(this, Number(msg.who.id), msg.who.name),
+            msg: msg.msg,
+            time: new Date(Number(msg.time) * 1000),
+        }))
+            .forEach((message) => {
+            switch (message.type) {
+                case "public":
+                    return void this.emit("public", message);
+                case "private":
+                    return void this.emit("whisper", message);
+                case "system":
+                    return void this.emit("system", message);
+            }
+        });
+    }
+    async checkKmails() {
+        const newKmailsResponse = await this.fetchJson("api.php", {
+            params: {
+                what: "kmail",
+                for: `${this.#username} bot`,
+            },
+        });
+        if (!Array.isArray(newKmailsResponse) || newKmailsResponse.length === 0)
+            return;
+        const newKmails = newKmailsResponse.map((msg) => ({
+            type: "kmail",
+            who: new Player(this, Number(msg.fromid), msg.fromname),
+            msg: msg.message,
+            time: new Date(Number(msg.azunixtime) * 1000),
+        }));
+        const data = {
+            the_action: "delete",
+            box: "Inbox",
+            ...Object.fromEntries(newKmailsResponse.map(({ id }) => [`sel${id}`, "on"])),
+        };
+        await this.fetchText("messages.php", { params: data });
+        newKmails.forEach((m) => this.emit("kmail", m));
+    }
+    async sendChat(message) {
+        return await this.fetchJson("submitnewchat.php", {
+            params: {
+                graf: message,
+                j: 1,
+            },
+        });
+    }
+    async useChatMacro(macro) {
+        return await this.sendChat(`/clan ${macro}`);
+    }
+    async whisper(recipientId, message) {
+        await this.useChatMacro(`/w ${recipientId} ${message}`);
+    }
+    async kmail(recipientId, message) {
+        await this.fetchText("sendmessage.php", {
+            params: {
+                action: "send",
+                j: 1,
+                towho: recipientId,
+                contact: 0,
+                message: message,
+                howmany1: 1,
+                whichitem1: 0,
+                sendmeat: 0,
+            },
+        });
+    }
+    async getMallPrice(itemId) {
+        const prices = await this.fetchText("backoffice.php", {
+            params: {
+                action: "prices",
+                ajax: 1,
+                iid: itemId,
+            },
+        });
+        const unlimitedMatch = prices.match(/<td>unlimited:<\/td><td><b>(?<unlimitedPrice>[\d,]+)/);
+        const limitedMatch = prices.match(/<td>limited:<\/td><td><b>(?<limitedPrice>[\d,]+)/);
+        const unlimitedPrice = unlimitedMatch
+            ? parseInt(unlimitedMatch[1].replace(/,/g, ""))
+            : 0;
+        const limitedPrice = limitedMatch
+            ? parseInt(limitedMatch[1].replace(/,/g, ""))
+            : 0;
+        let minPrice = limitedMatch ? limitedPrice : null;
+        minPrice = unlimitedMatch
+            ? !minPrice || unlimitedPrice < minPrice
+                ? unlimitedPrice
+                : minPrice
+            : minPrice;
+        const formattedMinPrice = minPrice
+            ? (minPrice === unlimitedPrice
+                ? unlimitedMatch?.[1]
+                : limitedMatch?.[1]) ?? ""
+            : "";
+        return {
+            mallPrice: unlimitedPrice,
+            limitedMallPrice: limitedPrice,
+            formattedMinPrice: formattedMinPrice,
+            minPrice: minPrice,
+            formattedMallPrice: unlimitedMatch ? unlimitedMatch[1] : "",
+            formattedLimitedMallPrice: limitedMatch ? limitedMatch[1] : "",
+        };
+    }
+    async getItemDescription(descId) {
+        const description = await this.fetchText("desc_item.php", {
+            params: {
+                whichitem: descId,
+            },
+        });
+        const blueText = description.match(/<center>\s*<b>\s*<font color="?[\w]+"?>(?<description>[\s\S]+)<\/center>/i);
+        const effect = description.match(/Effect: \s?<b>\s?<a[^>]+href="desc_effect\.php\?whicheffect=(?<descid>[^"]+)[^>]+>(?<effect>[\s\S]+)<\/a>[^(]+\((?<duration>[\d]+)/);
+        const melting = description.match(/This item will disappear at the end of the day\./);
+        const singleEquip = description.match(/ You may not equip more than one of these at a time\./);
+        return {
+            melting: !!melting,
+            singleEquip: !!singleEquip,
+            blueText: sanitiseBlueText(blueText?.groups?.description),
+            effect: effect?.groups
+                ? {
+                    name: effect.groups?.name,
+                    duration: Number(effect.groups?.duration) || 0,
+                    descid: effect.groups?.descid,
+                }
+                : undefined,
+        };
+    }
+    async getEffectDescription(descId) {
+        const description = await this.fetchText("desc_effect.php", {
+            params: {
+                whicheffect: descId,
+            },
+        });
+        const blueText = description.match(/<center><font color="?[\w]+"?>(?<description>[\s\S]+)<\/div>/m);
+        return { blueText: sanitiseBlueText(blueText?.groups?.description) };
+    }
+    async getSkillDescription(id) {
+        const description = await this.fetchText("desc_skill.php", {
+            params: {
+                whichskill: String(id),
+            },
+        });
+        const blueText = description.match(/<blockquote[\s\S]+<[Cc]enter>(?<description>[\s\S]+)<\/[Cc]enter>/);
+        return { blueText: sanitiseBlueText(blueText?.groups?.description) };
+    }
+    async joinClan(id) {
+        const result = await this.fetchText("showclan.php", {
+            params: {
+                whichclan: id,
+                action: "joinclan",
+                confirm: "on",
+            },
+        });
+        return (result.includes("clanhalltop.gif") ||
+            result.includes("a clan you're already in"));
+    }
+    async addToWhitelist(playerId, clanId) {
+        return await this.actionMutex.runExclusive(async () => {
+            if (!(await this.joinClan(clanId)))
+                return false;
+            await this.fetchText("clan_whitelist.php", {
+                params: {
+                    addwho: playerId,
+                    level: 2,
+                    title: "",
+                    action: "add",
+                },
+            });
+            return true;
+        });
+    }
+    async getLeaderboard(leaderboardId) {
+        const page = await this.fetchText("museum.php", {
+            params: {
+                floor: 1,
+                place: "leaderboards",
+                whichboard: leaderboardId,
+            },
+        });
+        return parseLeaderboard(page);
+    }
+    async useFamiliar(familiarId) {
+        await this.fetchText("familiar.php", {
+            params: {
+                action: "newfam",
+                newfam: familiarId.toFixed(0),
+            },
+        });
+    }
+}

package/dist/Client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Client.test.js

@@ -0,0 +1,132 @@
+import { describe, expect, test, vi } from "vitest";
+import { Client } from "./Client.js";
+import { loadFixture } from "./testUtils.js";
+const { json, text } = vi.hoisted(() => ({ json: vi.fn(), text: vi.fn() }));
+vi.mock("./utils/visit.js", () => ({
+    createSession: vi.fn().mockReturnValue({ json, text }),
+}));
+const client = new Client("", "");
+describe("LoathingChat", () => {
+    test("Can parse a regular message", async () => {
+        json.mockResolvedValue({});
+        json.mockResolvedValueOnce({
+            msgs: [
+                {
+                    msg: "testing",
+                    type: "public",
+                    mid: "1538072797",
+                    who: { name: "gAUSIE", id: "1197090", color: "black" },
+                    format: "0",
+                    channel: "talkie",
+                    channelcolor: "green",
+                    time: "1698787642",
+                },
+            ],
+        });
+        const messageSpy = vi.fn();
+        client.on("public", messageSpy);
+        await client.checkMessages();
+        expect(messageSpy).toHaveBeenCalledOnce();
+        const [message] = messageSpy.mock.calls[0];
+        expect(message).toMatchObject({
+            type: "public",
+            msg: "testing",
+            time: new Date(1698787642000),
+            who: { id: 1197090, name: "gAUSIE" },
+        });
+    });
+    test("Can parse a system message for rollover in 5 minutes", async () => {
+        json.mockResolvedValueOnce({
+            msgs: [
+                {
+                    msg: "The system will go down for nightly maintenance in 5 minutes.",
+                    type: "system",
+                    mid: "1538084998",
+                    who: { name: "System Message", id: "-1", color: "" },
+                    format: "2",
+                    channelcolor: "green",
+                    time: "1698809101",
+                },
+            ],
+        });
+        const messageSpy = vi.fn();
+        client.on("system", messageSpy);
+        await client.checkMessages();
+        expect(messageSpy).toHaveBeenCalledOnce();
+        const [message] = messageSpy.mock.calls[0];
+        expect(message).toMatchObject({
+            type: "system",
+            who: { id: -1, name: "System Message" },
+            msg: "The system will go down for nightly maintenance in 5 minutes.",
+            time: new Date(1698809101000),
+        });
+    });
+    test("Can parse a system message for rollover in one minute", async () => {
+        json.mockResolvedValueOnce({
+            msgs: [
+                {
+                    msg: "The system will go down for nightly maintenance in 1 minute.",
+                    type: "system",
+                    mid: "1538084998",
+                    who: { name: "System Message", id: "-1", color: "" },
+                    format: "2",
+                    channelcolor: "green",
+                    time: "1698809101",
+                },
+            ],
+        });
+        const messageSpy = vi.fn();
+        client.on("system", messageSpy);
+        await client.checkMessages();
+        expect(messageSpy).toHaveBeenCalledOnce();
+        const [message] = messageSpy.mock.calls[0];
+        expect(message).toMatchObject({
+            type: "system",
+            who: { id: -1, name: "System Message" },
+            msg: "The system will go down for nightly maintenance in 1 minute.",
+            time: new Date(1698809101000),
+        });
+    });
+    test("Can parse a system message for rollover complete", async () => {
+        json.mockResolvedValueOnce({
+            msgs: [
+                {
+                    msg: "Rollover is over.",
+                    type: "system",
+                    mid: "1538085619",
+                    who: { name: "System Message", id: "-1", color: "" },
+                    format: "2",
+                    channelcolor: "green",
+                    time: "1698809633",
+                },
+            ],
+        });
+        const messageSpy = vi.fn();
+        client.on("system", messageSpy);
+        await client.checkMessages();
+        expect(messageSpy).toHaveBeenCalledOnce();
+        const [message] = messageSpy.mock.calls[0];
+        expect(message).toMatchObject({
+            type: "system",
+            who: { id: -1, name: "System Message" },
+            msg: "Rollover is over.",
+            time: new Date(1698809633000),
+        });
+    });
+});
+describe("Skill descriptions", () => {
+    test("can describe a Skill with no bluetext", async () => {
+        text.mockResolvedValueOnce(await loadFixture(__dirname, "desc_skill_overload_discarded_refridgerator.html"));
+        const description = await client.getSkillDescription(7017);
+        expect(description).toStrictEqual({
+            blueText: "",
+        });
+    });
+    test("can describe a Skill with bluetext", async () => {
+        text.mockResolvedValueOnce(await loadFixture(__dirname, "desc_skill_impetuous_sauciness.html"));
+        const description = await client.getSkillDescription(4015);
+        expect(description).toStrictEqual({
+            blueText: "Makes Sauce Potions last longer",
+        });
+    });
+});

package/dist/Player.d.ts

@@ -0,0 +1,28 @@
+import { Client } from "./Client.js";
+export type If<Value extends boolean, TrueResult, FalseResult = null> = Value extends true ? TrueResult : Value extends false ? FalseResult : TrueResult | FalseResult;
+export declare class Player<IsFull extends boolean = boolean> {
+    #private;
+    id: number;
+    name: string;
+    level: If<IsFull, number>;
+    kolClass: If<IsFull, string>;
+    avatar: If<IsFull, string>;
+    ascensions: If<IsFull, number>;
+    trophies: If<IsFull, number>;
+    tattoos: If<IsFull, number>;
+    favoriteFood: If<IsFull, string | null>;
+    favoriteBooze: If<IsFull, string | null>;
+    createdDate: If<IsFull, Date>;
+    lastLogin: If<IsFull, Date>;
+    hasDisplayCase: If<IsFull, boolean>;
+    constructor(client: Client, id: number, name: string, level?: number | null, kolClass?: string | null);
+    isFull(): this is Player<true>;
+    isPartial(): this is Player<false>;
+    static getNameFromId(client: Client, id: number): Promise<string | null>;
+    static fromName(client: Client, name: string): Promise<Player<false> | null>;
+    static fromId(client: Client, id: number): Promise<Player<false> | null>;
+    static from(client: Client, identifier: string | number): Promise<Player<false> | null>;
+    matchesIdentifier(identifier: string | number): boolean;
+    full(): Promise<Player<true> | null>;
+    isOnline(): Promise<boolean>;
+}

package/dist/Player.js

@@ -0,0 +1,136 @@
+import { generateAvatarSvg } from "./utils/avatar.js";
+import { parsePlayerDate } from "./utils/utils.js";
+export class Player {
+    #client;
+    id;
+    name;
+    level;
+    kolClass;
+    avatar;
+    ascensions;
+    trophies;
+    tattoos;
+    favoriteFood;
+    favoriteBooze;
+    createdDate;
+    lastLogin;
+    hasDisplayCase;
+    constructor(client, id, name, level = null, kolClass = null) {
+        this.#client = client;
+        this.id = id;
+        this.name = name;
+        this.level = level;
+        this.kolClass = kolClass;
+        this.avatar = null;
+        this.ascensions = null;
+        this.trophies = null;
+        this.tattoos = null;
+        this.favoriteFood = null;
+        this.favoriteBooze = null;
+        this.createdDate = null;
+        this.lastLogin = null;
+        this.hasDisplayCase = null;
+    }
+    isFull() {
+        return this.createdDate !== null;
+    }
+    isPartial() {
+        return this.createdDate === null;
+    }
+    static async getNameFromId(client, id) {
+        try {
+            const profile = await client.fetchText("showplayer.php", {
+                params: { who: id },
+            });
+            const name = profile.match(/<b>([^>]*?)<\/b> \(#(\d+)\)<br>/)?.[1];
+            return name || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    static async fromName(client, name) {
+        try {
+            const matcher = /href="showplayer.php\?who=(?<playerId>\d+)">(?<playerName>.*?)<\/a>\D+(clan=\d+[^<]+\D+)?\d+\D*(?<level>(\d+)|(inf_large\.gif))\D+valign=top>(?<class>[^<]*)<\/td>/i;
+            const search = await client.fetchText("searchplayer.php", {
+                params: {
+                    searchstring: name.replace(/_/g, "\\_"),
+                    searching: "Yep.",
+                    for: "",
+                    startswith: 1,
+                    hardcoreonly: 0,
+                },
+            });
+            const match = matcher.exec(search)?.groups;
+            if (!match) {
+                return null;
+            }
+            return new Player(client, Number(match.playerId), match.playerName, parseInt(match.level), match.class);
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    static async fromId(client, id) {
+        const name = await Player.getNameFromId(client, id);
+        if (!name)
+            return null;
+        return await Player.fromName(client, name);
+    }
+    static async from(client, identifier) {
+        const id = Number(identifier);
+        if (!Number.isNaN(id) || typeof identifier === "number") {
+            return await Player.fromId(client, id);
+        }
+        return await Player.fromName(client, identifier);
+    }
+    matchesIdentifier(identifier) {
+        const id = Number(identifier);
+        if (!Number.isNaN(id) || typeof identifier === "number") {
+            return this.id === identifier;
+        }
+        return this.name.toLowerCase() === identifier.toLowerCase();
+    }
+    async full() {
+        const t = this;
+        if (this.isFull())
+            return this;
+        try {
+            const profile = await this.#client.fetchText("showplayer.php", {
+                params: {
+                    who: this.id,
+                },
+            });
+            const header = profile.match(/<center><table><tr><td><center>.*?<img.*?src="(.*?)".*?<b>([^>]*?)<\/b> \(#(\d+)\)<br>/);
+            if (!header)
+                return null;
+            t.avatar = (await generateAvatarSvg(profile)) || header[1];
+            t.ascensions =
+                Number(profile
+                    .match(/>Ascensions<\/a>:<\/b><\/td><td>(.*?)<\/td>/)?.[1]
+                    ?.replace(/,/g, "")) || 0;
+            t.trophies = Number(profile.match(/>Trophies Collected:<\/b><\/td><td>(.*?)<\/td>/)?.[1] ??
+                0);
+            t.tattoos = Number(profile.match(/>Tattoos Collected:<\/b><\/td><td>(.*?)<\/td>/)?.[1] ??
+                0);
+            t.favoriteFood =
+                profile.match(/>Favorite Food:<\/b><\/td><td>(.*?)<\/td>/)?.[1] ?? null;
+            t.favoriteBooze =
+                profile.match(/>Favorite Booze:<\/b><\/td><td>(.*?)<\/td>/)?.[1] ??
+                    null;
+            t.createdDate = parsePlayerDate(profile.match(/>Account Created:<\/b><\/td><td>(.*?)<\/td>/)?.[1]);
+            t.lastLogin = parsePlayerDate(profile.match(/>Last Login:<\/b><\/td><td>(.*?)<\/td>/)?.[1]);
+            t.hasDisplayCase =
+                profile.match(/Display Case<\/b><\/a> in the Museum<\/td>/) !== null;
+            return t;
+        }
+        catch (error) {
+            console.error(error);
+            return null;
+        }
+    }
+    async isOnline() {
+        const response = await this.#client.useChatMacro(`/whois ${this.name}`);
+        return response?.output.includes("This player is currently online") ?? false;
+    }
+}

package/dist/Player.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Player.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, test, vi } from "vitest";
+import { resolveKoLImage } from "./utils/utils.js";
+import { Player } from "./Player.js";
+import { expectNotNull, loadFixture } from "./testUtils.js";
+import { Client } from "./Client.js";
+const { json, text } = vi.hoisted(() => ({ json: vi.fn(), text: vi.fn() }));
+vi.mock("./utils/visit.js", () => ({
+    createSession: vi.fn().mockReturnValue({ json, text }),
+}));
+const client = new Client("", "");
+test("Can search for a player by name", async () => {
+    vi.mocked(text).mockResolvedValueOnce(await loadFixture(__dirname, "searchplayer_mad_carew.html"));
+    const player = await Player.fromName(client, "mad carew");
+    expectNotNull(player);
+    expect(player.id).toBe(263717);
+    // Learns correct capitalisation
+    expect(player.name).toBe("Mad Carew");
+});
+describe("Profile parsing", () => {
+    test("Can parse a profile picture", async () => {
+        vi.mocked(text).mockResolvedValueOnce(await loadFixture(__dirname, "showplayer_regular.html"));
+        const player = await new Player(client, 2264486, "SSBBHax", 1, "Sauceror").full();
+        expectNotNull(player);
+        expect(player.avatar).toContain("<svg");
+    });
+    test("Can parse a profile picture on dependence day", async () => {
+        vi.mocked(text).mockResolvedValueOnce(await loadFixture(__dirname, "showplayer_dependence_day.html"));
+        const player = await new Player(client, 3019702, "Name Guy Man", 1, "Sauceror").full();
+        expectNotNull(player);
+        expect(player.avatar).toContain("<svg");
+    });
+    test("Can parse an avatar when the player has been painted gold", async () => {
+        vi.mocked(text).mockResolvedValueOnce(await loadFixture(__dirname, "showplayer_golden_gun.html"));
+        const player = await new Player(client, 1197090, "gAUSIE", 15, "Sauceror").full();
+        expectNotNull(player);
+        expect(player.avatar).toContain("<svg");
+    });
+    test("Can resolve KoL images", () => {
+        expect(resolveKoLImage("/iii/otherimages/classav31_f.gif")).toBe("https://s3.amazonaws.com/images.kingdomofloathing.com/otherimages/classav31_f.gif");
+        expect(resolveKoLImage("/itemimages/oaf.gif")).toBe("https://s3.amazonaws.com/images.kingdomofloathing.com/itemimages/oaf.gif");
+        expect(resolveKoLImage("https://s3.amazonaws.com/images.kingdomofloathing.com/itemimages/oaf.gif")).toBe("https://s3.amazonaws.com/images.kingdomofloathing.com/itemimages/oaf.gif");
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Player } from "./Player.js";
+export { Client } from "./Client.js";
+export { createSession } from "./utils/visit.js";
+export { resolveKoLImage } from "./utils/utils.js";
+export type { KoLMessage } from "./utils/kmail.js";
+export type { SubboardInfo } from "./utils/leaderboard.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Player } from "./Player.js";
+export { Client } from "./Client.js";
+export { createSession } from "./utils/visit.js";
+export { resolveKoLImage } from "./utils/utils.js";

package/dist/start.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/start.js

@@ -0,0 +1,4 @@
+import { Client } from "./Client.js";
+const client = new Client("onweb", "beer146beef31");
+const gausie = await client.players.fetch("gausie", true);
+console.log(gausie);

package/dist/testUtils.d.ts

@@ -0,0 +1,2 @@
+export declare function loadFixture(dirname: string, name: string): Promise<string>;
+export declare function expectNotNull<T>(value: T | null): asserts value is T;

package/dist/testUtils.js

@@ -0,0 +1,10 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { expect } from "vitest";
+export async function loadFixture(dirname, name) {
+    const file = path.join(dirname, `__fixtures__/${name}`);
+    return await fs.readFile(file, { encoding: "utf-8" });
+}
+export function expectNotNull(value) {
+    expect(value).not.toBeNull();
+}

package/dist/utils/avatar.d.ts

@@ -0,0 +1 @@
+export declare function generateAvatarSvg(profile: string): Promise<string | null>;

package/dist/utils/avatar.js

@@ -0,0 +1,70 @@
+import { parse } from "node-html-parser";
+import { resolveKoLImage } from "./utils.js";
+import { imageSize } from "image-size";
+import { dedent } from "ts-dedent";
+export async function generateAvatarSvg(profile) {
+    const header = profile.match(/<center><table><tr><td><center>.*?(<div.*?>.*?<\/div>).*?<b>([^>]*?)<\/b> \(#(\d+)\)<br>/);
+    const blockHtml = header?.[1];
+    if (!blockHtml)
+        return null;
+    const block = parse(blockHtml).querySelector("div");
+    if (!block)
+        return null;
+    const ocrsColour = ["gold", "red"].find((k) => block.classList.contains(k)) ?? "black";
+    const images = [];
+    for (const imgElement of block.querySelectorAll("img")) {
+        const src = imgElement.getAttribute("src");
+        if (!src)
+            continue;
+        const result = await fetch(resolveKoLImage(src));
+        const buffer = Buffer.from(await result.arrayBuffer());
+        const { width = 0, height = 0 } = imageSize(buffer);
+        const href = `data:image/png;base64,${buffer.toString("base64")}`;
+        const style = imgElement.getAttribute("style");
+        const top = Number(style?.match(/top: ?(-?\d+)px/i)?.[1] || "0");
+        const left = Number(style?.match(/left: ?(-?\d+)px/i)?.[1] || "0");
+        const rotate = Number(style?.match(/rotate\((-?\d+)deg\)/)?.[1] || "0");
+        images.push({
+            href,
+            top,
+            left,
+            rotate,
+            width,
+            height,
+        });
+    }
+    const width = Math.max(...images.map((i) => i.left + i.width));
+    return dedent `
+    <svg width="${width}" height="100" xmlns="http://www.w3.org/2000/svg">
+      <defs>
+        <filter id="colorMask">
+          <feComponentTransfer in="SourceGraphic" out="f1">
+            <feFuncR type="discrete" tableValues="1 0"/>
+            <feFuncG type="discrete" tableValues="1 0"/>
+            <feFuncB type="discrete" tableValues="1 0"/>
+          </feComponentTransfer>
+          <feColorMatrix type="matrix" values="1 0 0 0 0
+                                              0 1 0 0 0
+                                              0 0 1 0 0
+                                              1 1 1 1 -3" result="selectedColor"/>
+          <feFlood flood-color="${ocrsColour}"/>
+          <feComposite operator="in" in2="selectedColor"/>
+          <feComposite operator="over" in2="SourceGraphic"/>
+        </filter>
+      </defs>
+      ${images
+        .map((i) => dedent `
+              <image
+                filter="url(#colorMask)"
+                href="${i.href}"
+                width="${i.width}"
+                height="${i.height}"
+                x="${i.left}"
+                y="${i.top}"
+                transform="rotate(${i.rotate},${i.width / 2 + i.left},${i.height / 2 + i.top})"
+              />
+            `)
+        .join("\n")}
+    </svg>
+  `;
+}

package/dist/utils/kmail.d.ts

@@ -0,0 +1,32 @@
+import { Player } from "../Player.js";
+export type KoLChatMessage = {
+    who?: Player<false>;
+    type?: string;
+    msg?: string;
+    link?: string;
+    channel?: string;
+    time: string;
+};
+type KoLMessageType = "private" | "system" | "public" | "kmail";
+export declare const isValidMessage: (msg: KoLChatMessage) => msg is KoLChatMessage & {
+    type: KoLMessageType;
+    who: Player<false>;
+    msg: string;
+};
+export type KoLKmail = {
+    id: string;
+    type: string;
+    fromid: string;
+    fromname: string;
+    azunixtime: string;
+    message: string;
+    localtime: string;
+};
+export type KoLMessage = {
+    type: KoLMessageType;
+    who: Player<false>;
+    msg: string;
+    time: Date;
+    channel?: string;
+};
+export {};

package/dist/utils/kmail.js

@@ -0,0 +1 @@
+export const isValidMessage = (msg) => msg.who !== undefined && msg.msg !== undefined;

package/dist/utils/leaderboard.d.ts

@@ -0,0 +1,16 @@
+export type LeaderboardInfo = {
+    name: string;
+    boards: SubboardInfo[];
+};
+export type SubboardInfo = {
+    name: string;
+    runs: RunInfo[];
+    updated: Date | null;
+};
+type RunInfo = {
+    player: string;
+    days: string;
+    turns: string;
+};
+export declare function parseLeaderboard(page: string): LeaderboardInfo;
+export {};

package/dist/utils/leaderboard.js

@@ -0,0 +1,56 @@
+import xpath, { select } from "xpath";
+import { DOMParser } from "@xmldom/xmldom";
+const parser = new DOMParser({
+    locator: {},
+    errorHandler: {
+        warning: () => { },
+        error: () => { },
+        fatalError: console.error,
+    },
+});
+const selectMulti = (expression, node) => {
+    const selection = select(expression, node);
+    if (Array.isArray(selection))
+        return selection;
+    return selection instanceof Node ? [selection] : [];
+};
+export function parseLeaderboard(page) {
+    const document = parser.parseFromString(page);
+    const [board, ...boards] = selectMulti("//table", document);
+    return {
+        name: selectMulti(".//text()", board.firstChild)
+            .map((node) => node.nodeValue)
+            .join("")
+            .replace(/\s+/g, " ")
+            .trim(),
+        boards: boards
+            .slice(1)
+            .filter((board) => selectMulti("./tr//text()", board)[0]?.nodeValue?.match(/^((Fast|Funn|B)est|Most (Goo|Elf))/) && selectMulti("./tr", board).length > 1)
+            .map((subboard) => {
+            const rows = selectMulti("./tr", subboard);
+            return {
+                name: (selectMulti(".//text()", rows[0])[0]?.nodeValue || "").trim(),
+                runs: selectMulti("./td//tr", rows[1])
+                    .slice(2)
+                    .map((node) => {
+                    const rowText = selectMulti(".//text()", node).map((text) => text.toString().replace(/ /g, ""));
+                    const hasTwoNumbers = !!parseInt(rowText[rowText.length - 2]);
+                    return {
+                        player: rowText
+                            .slice(0, rowText.length - (hasTwoNumbers ? 2 : 1))
+                            .join("")
+                            .trim()
+                            .toString(),
+                        days: hasTwoNumbers
+                            ? rowText[rowText.length - 2].toString() || "0"
+                            : "",
+                        turns: rowText[rowText.length - 1].toString() || "0",
+                    };
+                }),
+                updated: xpath.isComment(subboard.nextSibling)
+                    ? new Date(subboard.nextSibling.data.slice(9, -1))
+                    : null,
+            };
+        }),
+    };
+}

package/dist/utils/utils.d.ts

@@ -0,0 +1,4 @@
+export declare function parsePlayerDate(input?: string): Date;
+export declare function sanitiseBlueText(blueText: string | undefined): string;
+export declare function resolveKoLImage(path: string): string;
+export declare function wait(ms: number): Promise<unknown>;

package/dist/utils/utils.js

@@ -0,0 +1,27 @@
+import { parse as parseDate } from "date-fns";
+import { decode } from "html-entities";
+export function parsePlayerDate(input) {
+    if (!input)
+        return new Date();
+    return parseDate(input, "MMMM dd, yyyy", new Date());
+}
+export function sanitiseBlueText(blueText) {
+    if (!blueText)
+        return "";
+    return decode(blueText
+        .replace(/\r/g, "")
+        .replace(/\r/g, "")
+        .replace(/(<p><\/p>)|(<br>)|(<Br>)|(<br \/>)|(<Br \/>)/g, "\n")
+        .replace(/<[^<>]+>/g, "")
+        .replace(/(\n+)/g, "\n")
+        .replace(/(\n)+$/, "")).trim();
+}
+export function resolveKoLImage(path) {
+    if (!/^https?:\/\//i.test(path))
+        return ("https://s3.amazonaws.com/images.kingdomofloathing.com" +
+            path.replace(/^\/(iii|images)/, ""));
+    return path;
+}
+export function wait(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/utils/visit.d.ts

@@ -0,0 +1,3 @@
+export declare function createBody(data: Record<string, string | number>): URLSearchParams;
+export declare function formatQuerystring(params: Record<string, string | number>): URLSearchParams;
+export declare const createSession: () => import("fetch-cookie").FetchCookieImpl<string | URL | Request, RequestInit, Response>;

package/dist/utils/visit.js

@@ -0,0 +1,10 @@
+import makeFetchCookie from "fetch-cookie";
+export function createBody(data) {
+    const formData = new FormData();
+    Object.entries(data).forEach(([key, value]) => formData.append(key, String(value)));
+    return new URLSearchParams(formData);
+}
+export function formatQuerystring(params) {
+    return new URLSearchParams(Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)])));
+}
+export const createSession = () => makeFetchCookie(fetch);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "kol.js",
+  "version": "0.0.1",
+  "main": "dist/index.js",
+  "type": "module",
+  "files": [
+    "/dist"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "format": "prettier --write ."
+  },
+  "devDependencies": {
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "@xmldom/xmldom": "^0.8.10",
+    "async-mutex": "^0.5.0",
+    "date-fns": "^3.6.0",
+    "fetch-cookie": "^3.0.1",
+    "node-html-parser": "^6.1.13",
+    "querystring": "^0.2.1",
+    "typed-emitter": "^2.1.0",
+    "xpath": "^0.0.34"
+  }
+}