feat: establish TypeScript-aware frontend tooling

tests/integration/auth-recovery.test.js

@@ -5,6 +5,7 @@ import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest
 import { createExternalAuthSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
 import { createHttpClient } from "../../src/adapters/http/client.js";
 
+/** @type {number[]} */
 let responseStatuses = [];
 const server = setupServer(
   http.get("https://api.test/api/sample/resources", () => {
@@ -36,16 +37,32 @@ afterAll(() => server.close());
 
 const clock = { now: () => 0, sleep: async () => {} };
 
+/**
+ * @param {Partial<Parameters<typeof createExternalAuthSessionAdapter>[0]>} overrides
+ * @returns {Parameters<typeof createExternalAuthSessionAdapter>[0]}
+ */
+function createOwner(overrides = {}) {
+  return {
+    readState: () => "authenticated",
+    subscribe: () => () => {},
+    beginSignIn: async () => {},
+    signOut: async () => {},
+    attachCredential: async (request) => request,
+    recoverSession: async () => "restored",
+    notifyUnauthenticated: () => {},
+    ...overrides,
+  };
+}
+
 describe("bounded 401 session recovery", () => {
   it("calls recovery once and replays a safe request once", async () => {
     responseStatuses = [401, 200];
-    const recoverSession = vi.fn(async () => "restored");
-    const authSession = createExternalAuthSessionAdapter({
-      readState: () => "authenticated",
+    const recoverSession = vi.fn(async () => /** @type {const} */ ("restored"));
+    const authSession = createExternalAuthSessionAdapter(createOwner({
       attachCredential: async (request) => request,
       recoverSession,
       notifyUnauthenticated: vi.fn(),
-    });
+    }));
     const client = createHttpClient({
       baseUrl: "https://api.test",
       authSession,
@@ -61,12 +78,11 @@ describe("bounded 401 session recovery", () => {
   it("stops after a second 401 and notifies unauthenticated once", async () => {
     responseStatuses = [401, 401];
     const notifyUnauthenticated = vi.fn();
-    const authSession = createExternalAuthSessionAdapter({
-      readState: () => "authenticated",
+    const authSession = createExternalAuthSessionAdapter(createOwner({
       attachCredential: async (request) => request,
       recoverSession: async () => "restored",
       notifyUnauthenticated,
-    });
+    }));
     const client = createHttpClient({
       baseUrl: "https://api.test",
       authSession,
@@ -81,14 +97,13 @@ describe("bounded 401 session recovery", () => {
   });
 
   it("normalizes attach and invalid recovery failures", async () => {
-    const attachFailure = createExternalAuthSessionAdapter({
-      readState: () => "authenticated",
+    const attachFailure = createExternalAuthSessionAdapter(createOwner({
       attachCredential: async () => {
         throw new Error("credential detail");
       },
       recoverSession: async () => "restored",
       notifyUnauthenticated: vi.fn(),
-    });
+    }));
     const client = createHttpClient({
       baseUrl: "https://api.test",
       authSession: attachFailure,