kol.js 0.2.1 → 0.4.0

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "kol.js",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./domains/*": "./src/domains/*.ts"
+  },
   "type": "module",
   "files": [
     "/src"
@@ -14,9 +18,9 @@
     "format": "prettier --write ."
   },
   "devDependencies": {
-    "prettier": "^3.7.4",
+    "prettier": "^3.8.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.18"
   },
   "dependencies": {
     "async-mutex": "^0.5.0",
@@ -24,13 +28,14 @@
     "date-fns": "^4.1.0",
     "domhandler": "^5.0.3",
     "domutils": "^3.2.2",
-    "got": "^14.6.5",
-    "html-entities": "^2.6.0",
-    "htmlparser2": "^10.0.0",
+    "emittery": "^1.1.0",
+    "entities": "^7.0.1",
+    "fetch-cookie": "^3.2.0",
+    "htmlparser2": "^10.1.0",
     "image-size": "^2.0.2",
-    "querystring": "^0.2.1",
+    "kol-rng": "3",
+    "ofetch": "^1.5.1",
     "tough-cookie": "^6.0.0",
-    "ts-dedent": "^2.2.0",
-    "typed-emitter": "^2.1.0"
+    "ts-dedent": "^2.2.0"
   }
 }

package/src/Client.test.ts

@@ -1,25 +1,22 @@
 import { describe, expect, it, test, vi } from "vitest";
 
-import { Client } from "./Client.js";
+import { AuthError, Client, RolloverError } from "./Client.js";
 import { loadFixture } from "./testUtils.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("", "");
+function mockSession(fn: () => unknown) {
+  return Object.assign(fn, {
+    raw: vi.fn(),
+    native: fetch,
+    create: vi.fn(),
+  }) as unknown as Client["session"];
+}
 
 describe("LoathingChat", () => {
+  const client = new Client("", "");
+
   test("Can parse a regular message", async () => {
-    json.mockResolvedValue({});
-    json.mockResolvedValueOnce({
+    vi.spyOn(client, "fetchJson").mockResolvedValue({});
+    vi.spyOn(client, "fetchJson").mockResolvedValueOnce({
       msgs: [
         {
           msg: "testing",
@@ -51,7 +48,7 @@ describe("LoathingChat", () => {
   });
 
   test("Can parse a system message for rollover in 5 minutes", async () => {
-    json.mockResolvedValueOnce({
+    vi.spyOn(client, "fetchJson").mockResolvedValueOnce({
       msgs: [
         {
           msg: "The system will go down for nightly maintenance in 5 minutes.",
@@ -82,7 +79,7 @@ describe("LoathingChat", () => {
   });
 
   test("Can parse a system message for rollover in one minute", async () => {
-    json.mockResolvedValueOnce({
+    vi.spyOn(client, "fetchJson").mockResolvedValueOnce({
       msgs: [
         {
           msg: "The system will go down for nightly maintenance in 1 minute.",
@@ -113,7 +110,7 @@ describe("LoathingChat", () => {
   });
 
   test("Can parse a system message for rollover complete", async () => {
-    json.mockResolvedValueOnce({
+    vi.spyOn(client, "fetchJson").mockResolvedValueOnce({
       msgs: [
         {
           msg: "Rollover is over.",
@@ -144,7 +141,7 @@ describe("LoathingChat", () => {
   });
 
   test("Can parse updates", async () => {
-    json.mockResolvedValueOnce({
+    vi.spyOn(client, "fetchJson").mockResolvedValueOnce({
       output:
         '<hr><center><font color=green><b>Recent Announcements:</b></font></center><p><b>August 21</b> - That pocast you like is back in style.  Get it on iTunes, or from the <A style="text-decoration: underline" target=_blank href=http://radio.kingdomofloathing.com/podcast.php>direct RSS feed</a> or <a style="text-decoration: underline" target=_blank href=http://shows.kingdomofloathing.com/The_KoL_Show_20250819.mp3>download the mp3 directly</a>.<p><b>August 15</b> - On September 1st commendations will be given out for softcore Under the Sea runs. The we\'ll be making some nerfs and the leaderboards will be reset for phase 2. <p><b>August 14</b> - Swim into the fall challenge path, 11,037 Leagues Under the Sea!<p><b>March 07</b> - Check out Jick\'s entry in the 2025 7-Day Roguelike Challenge.  It\'s called Catacombo and you can <a href=https://zapjackson.itch.io/catacombo target=_blank style="text-decoration: underline">play it here on itch dot eye oh</a>.<p><b>March 06</b> - KoL\'s own Jick wrote a book, a choose-your-own-adventure about escaping from a wizard.  You can <a style="text-decoration: underline" target=_blank href=https://www.amazon.com/Escape-Prison-Tower-Wizard-Adventures/dp/B0CTW34JV1/>buy it on Amazon dot com</a>. <p><hr>',
       msgs: [],
@@ -158,8 +155,10 @@ describe("LoathingChat", () => {
 });
 
 describe("Skill descriptions", () => {
+  const client = new Client("", "");
+
   test("can describe a Skill with no bluetext", async () => {
-    text.mockResolvedValueOnce(
+    vi.spyOn(client, "fetchText").mockResolvedValueOnce(
       await loadFixture(
         __dirname,
         "desc_skill_overload_discarded_refridgerator.html",
@@ -174,7 +173,7 @@ describe("Skill descriptions", () => {
   });
 
   test("can describe a Skill with bluetext", async () => {
-    text.mockResolvedValueOnce(
+    vi.spyOn(client, "fetchText").mockResolvedValueOnce(
       await loadFixture(__dirname, "desc_skill_impetuous_sauciness.html"),
     );
 
@@ -187,21 +186,21 @@ describe("Skill descriptions", () => {
 });
 
 describe("Familiars", () => {
+  const client = new Client("", "");
+
   test("can fetch all familiars", async () => {
-    text.mockResolvedValueOnce(
+    vi.spyOn(client, "fetchText").mockResolvedValueOnce(
       await loadFixture(__dirname, "familiar_in_standard_run.html"),
     );
 
     const familiars = await client.getFamiliars();
 
-    // Current
     expect(familiars).toContainEqual({
       id: 294,
       name: "Jill-of-All-Trades",
       image: "itemimages/darkjill2f.gif",
     });
 
-    // Problematic
     expect(familiars).toContainEqual({
       id: 278,
       name: "Left-Hand Man",
@@ -213,50 +212,232 @@ describe("Familiars", () => {
       image: "otherimages/camelfam_left.gif",
     });
 
-    // Just to be sure
     expect(familiars).toHaveLength(206);
   });
 });
 
-describe("Raffle", () => {
-  it("can fetch the current raffle", async () => {
-    text.mockResolvedValueOnce(await loadFixture(__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 -->");
-
-    const raffle = await client.getRaffle();
-
-    expect(raffle).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,
-        },
-      ],
+describe("fetchJson error handling", () => {
+  it("throws on non-login errors", async () => {
+    const client = new Client("", "");
+    vi.spyOn(client, "login").mockResolvedValue(true);
+    client.session = mockSession(() => {
+      throw new Error("500 Internal Server Error");
+    });
+    await expect(client.fetchJson("api.php")).rejects.toThrow(
+      "500 Internal Server Error",
+    );
+  });
+
+  it("does not retry more than once on non-login errors", async () => {
+    const client = new Client("", "");
+    vi.spyOn(client, "login").mockResolvedValue(true);
+    let calls = 0;
+    client.session = mockSession(() => {
+      calls++;
+      throw new Error("persistent error");
+    });
+    await expect(client.fetchJson("test.php")).rejects.toThrow(
+      "persistent error",
+    );
+    expect(calls).toBe(1);
+  });
+
+  it("propagates RolloverError", async () => {
+    const client = new Client("", "");
+    vi.spyOn(client, "login").mockResolvedValue(true);
+    client.session = mockSession(() => {
+      throw new RolloverError();
+    });
+    await expect(client.fetchJson("test.php")).rejects.toBeInstanceOf(
+      RolloverError,
+    );
+  });
+
+  it("throws AuthError when login fails", async () => {
+    const client = new Client("", "");
+    vi.spyOn(client, "login").mockResolvedValue(false);
+    await expect(client.fetchJson("test.php")).rejects.toBeInstanceOf(
+      AuthError,
+    );
+  });
+});
+
+describe("fetchText error handling", () => {
+  it("throws on non-login errors instead of retrying", async () => {
+    const client = new Client("", "");
+    vi.spyOn(client, "login").mockResolvedValue(true);
+    client.session = mockSession(() => {
+      throw new Error("Network timeout");
+    });
+    await expect(client.fetchText("familiar.php")).rejects.toThrow(
+      "Network timeout",
+    );
+  });
+
+  it("does not retry more than once on non-login errors", async () => {
+    const client = new Client("", "");
+    vi.spyOn(client, "login").mockResolvedValue(true);
+    let calls = 0;
+    client.session = mockSession(() => {
+      calls++;
+      throw new Error("persistent error");
+    });
+    await expect(client.fetchText("test.php")).rejects.toThrow(
+      "persistent error",
+    );
+    expect(calls).toBe(1);
+  });
+});
+
+describe("rollover handling", () => {
+  it("detects rollover from login.php response", async () => {
+    const client = new Client("", "");
+    client.session = mockSession(
+      () => "The system is currently down for nightly maintenance.",
+    );
+    await client.login();
+    expect(client.isRollover()).toBe(true);
+
+    // All fetch methods should fail fast
+    await expect(client.fetchText("test.php")).rejects.toBeInstanceOf(
+      RolloverError,
+    );
+    await expect(client.fetchJson("test.php")).rejects.toBeInstanceOf(
+      RolloverError,
+    );
+  });
+
+  it("fetchText throws RolloverError immediately when in rollover", async () => {
+    const client = new Client("", "");
+    client.session = mockSession(
+      () => "The system is currently down for nightly maintenance",
+    );
+    await client.login();
+
+    let sessionCalled = false;
+    client.session = mockSession(() => {
+      sessionCalled = true;
+      return "";
     });
+    await expect(client.fetchText("test.php")).rejects.toBeInstanceOf(
+      RolloverError,
+    );
+    expect(sessionCalled).toBe(false);
+  });
+
+  it("fetchJson throws RolloverError immediately when in rollover", async () => {
+    const client = new Client("", "");
+    client.session = mockSession(
+      () => "The system is currently down for nightly maintenance",
+    );
+    await client.login();
+
+    let sessionCalled = false;
+    client.session = mockSession(() => {
+      sessionCalled = true;
+      return {};
+    });
+    await expect(client.fetchJson("test.php")).rejects.toBeInstanceOf(
+      RolloverError,
+    );
+    expect(sessionCalled).toBe(false);
+  });
+
+  it("recovers from rollover when server comes back", async () => {
+    vi.useFakeTimers();
+    const client = new Client("", "");
+
+    client.session = mockSession(
+      () => "The system is currently down for nightly maintenance",
+    );
+    await client.login();
+    expect(client.isRollover()).toBe(true);
+
+    client.session = mockSession(() => "<html>normal login page</html>");
+    await vi.advanceTimersByTimeAsync(60_000);
+
+    expect(client.isRollover()).toBe(false);
+    vi.useRealTimers();
+  });
+
+  it("emits rollover event after recovery when login succeeds", async () => {
+    vi.useFakeTimers();
+    const client = new Client("", "");
+
+    // Enter rollover
+    client.session = mockSession(
+      () => "The system is currently down for nightly maintenance",
+    );
+    await client.login();
+
+    // Recover: checkForRollover sees normal page, then login flow works
+    let callCount = 0;
+    client.session = mockSession(() => {
+      callCount++;
+      // Call 1: #checkForRollover fetches login.php (normal)
+      if (callCount === 1) return "<html>normal login page</html>";
+      // Call 2+: checkLoggedIn/login succeed
+      return { pwd: "abc123" };
+    });
+
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(client.isRollover()).toBe(false);
+
+    // login needs checkLoggedIn to FAIL first so it goes through the
+    // full login flow where the latch is checked. Make first checkLoggedIn
+    // fail (no session yet), then login POST + second checkLoggedIn succeed.
+    callCount = 0;
+    client.session = mockSession(() => {
+      callCount++;
+      // Call 1: checkLoggedIn → returns non-object (fails validation)
+      if (callCount === 1) return "<html>not logged in</html>";
+      // Call 2: login POST → success (no rollover pattern)
+      if (callCount === 2) return "<html>game frameset</html>";
+      // Call 3: second checkLoggedIn → success
+      return { pwd: "def456" };
+    });
+
+    const rolloverSpy = vi.fn();
+    client.on("rollover", rolloverSpy);
+    const loggedIn = await client.login();
+    expect(loggedIn).toBe(true);
+    expect(rolloverSpy).toHaveBeenCalledOnce();
+
+    vi.useRealTimers();
+  });
+
+  it("stays in rollover if server is unreachable", async () => {
+    vi.useFakeTimers();
+    const client = new Client("", "");
+
+    client.session = mockSession(
+      () => "The system is currently down for nightly maintenance",
+    );
+    await client.login();
+    expect(client.isRollover()).toBe(true);
+
+    client.session = mockSession(() => {
+      throw new Error("Network error");
+    });
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(client.isRollover()).toBe(true);
+
+    client.session = mockSession(() => "<html>normal login page</html>");
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(client.isRollover()).toBe(false);
+
+    vi.useRealTimers();
+  });
+
+  it("does not recurse through fetchText/login during rollover check", async () => {
+    const client = new Client("", "");
+    let sessionCallCount = 0;
+    client.session = mockSession(() => {
+      sessionCallCount++;
+      return "The system is currently down for nightly maintenance";
+    });
+
+    await client.login();
+    expect(sessionCallCount).toBeLessThanOrEqual(3);
   });
 });