screeps-connectivity 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.10.0
+
+### Minor Changes
+
+- 1539f52: Add NotifyPrefs type and notifyPrefs field on UserInfo for email notification preference support.
+- de39cf0: Expose public-profile data through the API: `power` on the `user.find` response, an optional `id` argument on `user.stats`, and a typed `leaderboard.find` response.
+- 4b8f9d9: Add `setFetch()` to `screeps-connectivity` so consumers can supply a custom fetch implementation (e.g. Tauri's HTTP plugin) without patching `window.fetch`. `screeps-client` uses this to enable CORS-free HTTP in the standalone Tauri desktop app without affecting the browser runtime.
+
+### Patch Changes
+
+- 882bea5: Fix `TokenAuth` always using its static token — server-issued `X-Token` headers, WebSocket token rotation, and the idle keep-alive timer are now skipped when the auth strategy sets `supportsTokenRefresh: false`.
+
+## 0.9.0
+
+### Minor Changes
+
+- e73c85f: Add `setFetch()` to `screeps-connectivity` so consumers can supply a custom fetch implementation (e.g. Tauri's HTTP plugin) without patching `window.fetch`. `screeps-client` uses this to enable CORS-free HTTP in the standalone Tauri desktop app without affecting the browser runtime.
+
 ## 0.8.1
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,182 @@
+# screeps-connectivity
+
+TypeScript library for connecting to [Screeps](https://screeps.com) servers. Handles HTTP, WebSocket, authentication, data stores, caching, and persistent storage — with **zero production dependencies**.
+
+Works in the browser and Node.js. Ships as ESM + CJS via tsup.
+
+---
+
+## Install
+
+```sh
+npm install screeps-connectivity
+```
+
+`FileStorage` (Node.js only) is a separate entry point so browser bundles stay clean:
+
+```ts
+import { FileStorage } from 'screeps-connectivity/file-storage'
+```
+
+---
+
+## Quick start
+
+```ts
+import { ScreepsClient, TokenAuth, IndexedDBStorage } from 'screeps-connectivity'
+
+const client = new ScreepsClient({
+  url: 'https://screeps.com',
+  auth: new TokenAuth({ token: 'your-auth-token' }),
+  storage: new IndexedDBStorage('my-app'),
+})
+
+// Subscribe before connecting — fires once the eager fetch completes
+client.stores.user.on('user:me', (info) => {
+  console.log('Connected as', info.username)
+})
+
+await client.connect()
+
+// Load terrain
+const terrain = await client.stores.room.terrain('W7N7', 'shard0')
+
+// Subscribe to live room updates
+const roomSub = client.stores.room.subscribe('W7N7', 'shard0')
+client.stores.room.on('room:update', ({ gameTime, objects }) => {
+  console.log('Tick', gameTime, '— objects:', Object.keys(objects).length)
+})
+
+// Cleanup
+roomSub.dispose()
+client.disconnect()
+```
+
+---
+
+## Features
+
+### Authentication
+
+Three built-in strategies, or implement your own via the `AuthStrategy` interface:
+
+```ts
+// Pre-issued token (official server, private servers with token auth)
+new TokenAuth({ token: 'your-token' })
+
+// Email + password — exchanged for a token on connect
+new PasswordAuth({ email: 'user@example.com', password: 'secret' })
+
+// Read-only guest access (xxscreeps-compatible private servers only)
+new GuestAuth()
+```
+
+Screeps servers rotate the session token on every request. `ScreepsClient` tracks the latest token across both HTTP and WebSocket transports, keeps them in sync, and issues an idle keep-alive if no traffic has been seen for 30 seconds.
+
+### Stores (event-based data layer)
+
+All stores extend `EventTarget`. `store.on(type, handler)` returns a `Subscription` with a `dispose()` method. `SubscriptionGroup` composes multiple subscriptions for batch teardown.
+
+| Store | `client.stores.*` | What it manages |
+|---|---|---|
+| `UserStore` | `user` | Identity, CPU stats, console output, code change events |
+| `ServerStore` | `server` | Server version, shard list, world bounds, connection lifecycle |
+| `RoomStore` | `room` | Terrain (binary), live object state + diffs, subscriptions |
+| `MapStore` | `map` | `roomMap2` mini-map data, diff detection, LRU cache |
+| `NavigationStore` | `navigation` | Bounded room-navigation history with back/forward |
+
+### Room subscriptions
+
+```ts
+// Terrain — Uint8Array(2500), one byte per tile (values 0–3)
+const terrain = await client.stores.room.terrain('W7N7', 'shard0')
+
+// Live objects — first message is full state; subsequent messages are diffs
+const sub = client.stores.room.subscribe('W7N7', 'shard0')
+client.stores.room.on('room:update', ({ gameTime, objects, diff }) => { /* … */ })
+```
+
+### World map subscriptions
+
+```ts
+// Subscribe up to 500 concurrent roomMap2 channels (configurable)
+// Excess rooms queue on a FIFO waitlist and are promoted as slots free
+client.stores.map.subscribe('W7N7', 'shard0')
+client.stores.map.on('map:roomMap2', ({ roomName, data }) => { /* … */ })
+```
+
+### World bounds
+
+```ts
+// Detects which quadrants (E/W, N/S) actually contain rooms
+// Works for standard servers, private servers, and single-quadrant maps
+const info = await client.stores.server.worldInfo()
+// → { width, height, minX, maxX, minY, maxY }
+```
+
+### Storage adapters
+
+| Adapter | Environment | Notes |
+|---|---|---|
+| `IndexedDBStorage` | Browser | Persists terrain and map cache across reloads |
+| `FileStorage` | Node.js | Import from `screeps-connectivity/file-storage` |
+| `NullStorage` | Any | Disables persistence (in-memory only) |
+
+Implement `StorageAdapter` (`get`, `set`, `delete`, `keys`) to plug in any backend.
+
+### Pre-login server info
+
+```ts
+import { fetchServerVersion, getScreepsmodAuth } from 'screeps-connectivity'
+
+const version = await fetchServerVersion('http://my-server:21025')
+const auth = getScreepsmodAuth(version)
+// auth?.authTypes → ['password', 'steam']
+```
+
+---
+
+## Architecture
+
+```
+ScreepsClient           — facade; wires everything together
+  ├─ HttpClient         — fetch wrapper, auth headers, rate limiting, gzip
+  │    └─ endpoints/    — auth · game · user · leaderboard · experimental
+  └─ SocketClient       — WebSocket lifecycle, exponential-backoff reconnect
+       └─ MessageParser — plain-text commands + JSON-array messages, gzip
+DataStores              — UserStore · ServerStore · RoomStore · MapStore · NavigationStore
+Cache                   — two-tier: in-memory Map + optional StorageAdapter
+StorageAdapter          — binary interface (Uint8Array)
+```
+
+---
+
+## Node.js usage
+
+Pass a custom `WebSocket` constructor for Node 18/20 compatibility:
+
+```ts
+import { WebSocket } from 'ws'
+import { ScreepsClient, TokenAuth, FileStorage } from 'screeps-connectivity'
+// FileStorage is a separate entry point:
+// import { FileStorage } from 'screeps-connectivity/file-storage'
+
+const client = new ScreepsClient({
+  url: 'https://screeps.com',
+  auth: new TokenAuth({ token: 'your-token' }),
+  storage: new FileStorage('./screeps-cache'),
+  WebSocket,
+})
+```
+
+---
+
+## API reference
+
+Full documentation — all stores, events, options, and types — is in [`docs/screeps-connectivity.md`](../docs/screeps-connectivity.md).
+
+---
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screeps-connectivity",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "license": "ISC",
   "type": "module",
   "repository": {

package/src/ScreepsClient.ts

@@ -18,7 +18,7 @@ import type { ApiRoomDecorationsResponse } from './types/api.js'
 type WsConstructor = typeof globalThis.WebSocket
 
 export interface TokenRefreshOptions {
-  /** Milliseconds of idleness before issuing a keep-alive request. Default 30_000. */
+  /** Interval in milliseconds between world-status polls. Default 30_000. */
   intervalMs?: number
 }
 
@@ -35,9 +35,8 @@ export interface ScreepsClientOptions {
     maxCacheEntries?: number
   }
   /**
-   * Idle keep-alive that refreshes the auth token via a lightweight `auth/me` call when no
-   * authenticated traffic has happened for `intervalMs`. Default `{ intervalMs: 30_000 }`.
-   * Pass `false` to disable.
+   * Polls `/api/user/world-status` on a fixed interval to keep world status current.
+   * Default `{ intervalMs: 30_000 }`. Pass `false` to disable.
    */
   tokenRefresh?: TokenRefreshOptions | false
   /** Override the /api/game/room-decorations response with static data (useful for dev/testing when the server doesn't support the endpoint). */
@@ -60,7 +59,6 @@ export class ScreepsClient {
   private readonly tokenRefreshIntervalMs: number | null
   private readonly tokenSyncSubs: Subscription[] = []
   private tokenRefreshTimer: ReturnType<typeof setInterval> | null = null
-  private lastHttpActivity = 0
   private refreshInFlight = false
 
   constructor(opts: ScreepsClientOptions) {
@@ -93,23 +91,21 @@ export class ScreepsClient {
       ? null
       : (opts.tokenRefresh?.intervalMs ?? 30_000)
 
-    this.wireTokenSync()
+    this.wireTokenSync(opts.auth.supportsTokenRefresh ?? true)
   }
 
-  private wireTokenSync(): void {
-    // HTTP rotates token via X-Token → propagate to WS so a later reconnect uses the fresh one.
-    this.tokenSyncSubs.push(this.http.on('http:tokenRefresh', ({ token }) => {
-      this.socket.setToken(token)
-    }))
-    // WS issues a new token on auth → keep HTTP side in sync.
-    this.tokenSyncSubs.push(this.socket.on('socket:tokenRefresh', (data) => {
-      const detail = data as { token: string }
-      this.http.setToken(detail.token)
-    }))
-    // Any successful HTTP response counts as activity — defers the next idle refresh.
-    this.tokenSyncSubs.push(this.http.on('http:success', () => {
-      this.lastHttpActivity = Date.now()
-    }))
+  private wireTokenSync(supportsRefresh: boolean): void {
+    if (supportsRefresh) {
+      // HTTP rotates token via X-Token → propagate to WS so a later reconnect uses the fresh one.
+      this.tokenSyncSubs.push(this.http.on('http:tokenRefresh', ({ token }) => {
+        this.socket.setToken(token)
+      }))
+      // WS issues a new token on auth → keep HTTP side in sync.
+      this.tokenSyncSubs.push(this.socket.on('socket:tokenRefresh', (data) => {
+        const detail = data as { token: string }
+        this.http.setToken(detail.token)
+      }))
+    }
   }
 
   get isConnected(): boolean {
@@ -137,15 +133,9 @@ export class ScreepsClient {
   private startTokenRefresh(): void {
     if (this.tokenRefreshIntervalMs === null) return
     if (this.tokenRefreshTimer !== null) return
-    const intervalMs = this.tokenRefreshIntervalMs
-    this.lastHttpActivity = Date.now()
-    // Tick at half the interval so we react within intervalMs of idleness.
-    const tickMs = Math.max(1_000, Math.floor(intervalMs / 2))
     this.tokenRefreshTimer = setInterval(() => {
-      const idleFor = Date.now() - this.lastHttpActivity
-      if (idleFor < intervalMs) return
       void this.refreshTokenNow()
-    }, tickMs)
+    }, this.tokenRefreshIntervalMs)
   }
 
   private stopTokenRefresh(): void {
@@ -159,10 +149,10 @@ export class ScreepsClient {
     if (this.refreshInFlight) return
     this.refreshInFlight = true
     try {
-      this.logger.log('[screeps:client] token refresh (idle)')
+      this.logger.log('[screeps:client] world status refresh')
       await this.stores.user.refreshWorldStatus()
     } catch (err) {
-      this.logger.log('[screeps:client] token refresh failed', err)
+      this.logger.log('[screeps:client] world status refresh failed', err)
     } finally {
       this.refreshInFlight = false
     }

package/src/http/HttpClient.ts

@@ -1,4 +1,5 @@
 import { decompressGzip } from './decompress.js'
+import { getFetch } from './fetchFn.js'
 import { Logger } from '../logger.js'
 import type { AuthStrategy } from './auth/AuthStrategy.js'
 import { createAuthEndpoints, type AuthEndpoints } from './endpoints/auth.js'
@@ -113,10 +114,10 @@ export class HttpClient extends EventTarget {
       init.body = JSON.stringify(body)
     }
 
-    const res = await fetch(url.toString(), init)
+    const res = await getFetch()(url.toString(), init)
 
     const newToken = res.headers.get('x-token')
-    if (newToken) {
+    if (newToken && (this.authStrategy.supportsTokenRefresh ?? true)) {
       this.token = newToken
       this.emit('http:tokenRefresh', { token: newToken })
     }

package/src/http/auth/AuthStrategy.ts

@@ -2,4 +2,6 @@ import type { HttpClient } from '../HttpClient.js'
 
 export interface AuthStrategy {
   authenticate(http: HttpClient): Promise<string>
+  /** False means the token is static and must never be replaced by server-issued tokens. Default: true. */
+  readonly supportsTokenRefresh?: boolean
 }

package/src/http/auth/TokenAuth.ts

@@ -2,6 +2,7 @@ import type { AuthStrategy } from './AuthStrategy.js'
 import type { HttpClient } from '../HttpClient.js'
 
 export class TokenAuth implements AuthStrategy {
+  readonly supportsTokenRefresh = false
   private readonly token: string
 
   constructor(opts: { token: string }) {

package/src/http/endpoints/leaderboard.ts

@@ -1,16 +1,18 @@
 import type { HttpClient } from '../HttpClient.js'
-import type { ApiLeaderboardListResponse, ApiLeaderboardSeasonsResponse } from '../../types/api.js'
+import type { ApiLeaderboardFindResponse, ApiLeaderboardListResponse, ApiLeaderboardSeasonsResponse } from '../../types/api.js'
 
 export interface LeaderboardEndpoints {
   list(limit?: number, mode?: 'world' | 'power', offset?: number, season?: string): Promise<ApiLeaderboardListResponse>
-  find(username: string, mode?: string, season?: string): Promise<unknown>
+  find(username: string, mode?: string, season?: string): Promise<ApiLeaderboardFindResponse>
   seasons(): Promise<ApiLeaderboardSeasonsResponse>
 }
 
 export function createLeaderboardEndpoints(http: HttpClient): LeaderboardEndpoints {
   return {
     list: (limit = 10, mode = 'world', offset = 0, season) => http.request('GET', '/api/leaderboard/list', { limit, mode, offset, season }),
-    find: (username, mode = 'world', season = '') => http.request('GET', '/api/leaderboard/find', { username, mode, season }),
+    // Best-effort: ranks feed the public profile and not every server implements
+    // them, so a miss shouldn't raise a user-facing toast.
+    find: (username, mode = 'world', season = '') => http.request('GET', '/api/leaderboard/find', { username, mode, season }, { silent: true }),
     seasons: () => http.request('GET', '/api/leaderboard/seasons'),
   }
 }

package/src/http/endpoints/user.ts

@@ -5,17 +5,11 @@ import type {
   ApiUserMoneyHistoryResponse,
   ApiUserOverviewResponse,
   ApiUserRoomsResponse,
+  ApiUserStatsResponse,
 } from '../../types/api.js'
+import type { NotifyPrefs } from '../../types/game.js'
 import { createUserMessagesEndpoints, type UserMessagesEndpoints } from './user-messages.js'
 
-export interface NotifyPrefs {
-  disabled: boolean
-  disabledOnMessages: boolean
-  sendOnline: boolean
-  interval: number
-  errorsInterval: number
-}
-
 export interface UserEndpoints {
   branches(): Promise<ApiUserBranchesResponse>
   code: {
@@ -31,7 +25,7 @@ export interface UserEndpoints {
     }
   }
   console(expression: string, shard?: string | null): Promise<unknown>
-  stats(interval: number): Promise<unknown>
+  stats(interval: number, id?: string): Promise<ApiUserStatsResponse>
   rooms(id: string): Promise<ApiUserRoomsResponse>
   overview(interval: number, statName: string): Promise<ApiUserOverviewResponse>
   worldStatus(): Promise<{ ok: number; status: 'normal' | 'lost' | 'empty' }>
@@ -74,7 +68,7 @@ export function createUserEndpoints(http: HttpClient): UserEndpoints {
       },
     },
     console: (expression, shard) => http.request('POST', '/api/user/console', withShard({ expression }, shard)),
-    stats: (interval) => http.request('GET', '/api/user/stats', { interval }),
+    stats: (interval, id) => http.request('GET', '/api/user/stats', id != null ? { interval, id } : { interval }, { silent: true }),
     // Best-effort dashboard data: not every server implements these, and the
     // Overview page degrades gracefully (zeros / no tiles), so a failure here
     // shouldn't raise a user-facing error toast — mark them silent.

package/src/http/fetchFn.ts

@@ -0,0 +1,17 @@
+let _fetch: typeof globalThis.fetch | undefined
+
+/**
+ * Override the fetch implementation used by all screeps-connectivity HTTP calls.
+ * Call this once at app startup when the platform requires a custom transport
+ * (e.g. Tauri desktop, where the native WKWebView fetch cannot reach cross-origin
+ * Screeps servers and the Tauri HTTP plugin must be used instead).
+ *
+ * When not called, screeps-connectivity uses `globalThis.fetch`.
+ */
+export function setFetch(fetchFn: typeof globalThis.fetch): void {
+  _fetch = fetchFn
+}
+
+export function getFetch(): typeof globalThis.fetch {
+  return _fetch ?? globalThis.fetch
+}

package/src/http/fetchServerVersion.ts

@@ -1,6 +1,7 @@
 import type { ServerVersion } from '../types/game.js'
 import type { ScreepsmodAuthFeature, ServerFeature } from '../types/game.js'
 import type { ApiAuthModInfoResponse, ApiRegisterCheckResponse } from '../types/api.js'
+import { getFetch } from './fetchFn.js'
 
 export type { ApiAuthModInfoResponse }
 
@@ -56,7 +57,7 @@ export async function fetchServerVersion(url: string): Promise<ServerVersion> {
   const cached = readFromSession<ServerVersion>(key)
   if (cached) return cached
 
-  const res = await fetch(`${baseUrl(url)}api/version`)
+  const res = await getFetch()(`${baseUrl(url)}api/version`)
   if (!res.ok) throw new Error(`HTTP ${res.status}`)
   const data = await res.json() as ServerVersion
   writeToSession(key, data)
@@ -73,7 +74,7 @@ export async function fetchAuthModInfo(url: string): Promise<ApiAuthModInfoRespo
   const cached = readFromSession<ApiAuthModInfoResponse>(key)
   if (cached) return cached
 
-  const res = await fetch(`${baseUrl(url)}api/authmod`)
+  const res = await getFetch()(`${baseUrl(url)}api/authmod`)
   if (!res.ok) return null
   const data = await res.json() as ApiAuthModInfoResponse
   if (!data.ok) return null
@@ -87,7 +88,7 @@ export async function fetchAuthModInfo(url: string): Promise<ApiAuthModInfoRespo
  */
 export async function checkUsername(url: string, username: string): Promise<ApiRegisterCheckResponse> {
   const params = new URLSearchParams({ username })
-  const res = await fetch(`${baseUrl(url)}api/register/check-username?${params}`)
+  const res = await getFetch()(`${baseUrl(url)}api/register/check-username?${params}`)
   if (!res.ok) throw new Error(`HTTP ${res.status}`)
   return res.json() as Promise<ApiRegisterCheckResponse>
 }
@@ -98,7 +99,7 @@ export async function checkUsername(url: string, username: string): Promise<ApiR
  */
 export async function checkEmail(url: string, email: string): Promise<ApiRegisterCheckResponse> {
   const params = new URLSearchParams({ email })
-  const res = await fetch(`${baseUrl(url)}api/register/check-email?${params}`)
+  const res = await getFetch()(`${baseUrl(url)}api/register/check-email?${params}`)
   if (!res.ok) throw new Error(`HTTP ${res.status}`)
   return res.json() as Promise<ApiRegisterCheckResponse>
 }
@@ -113,7 +114,7 @@ export async function registerUser(
   email: string,
   password: string,
 ): Promise<{ ok: number; error?: string }> {
-  const res = await fetch(`${baseUrl(url)}api/register/submit`, {
+  const res = await getFetch()(`${baseUrl(url)}api/register/submit`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ username, email, password }),

package/src/index.ts

@@ -1,4 +1,5 @@
 export { ScreepsClient } from './ScreepsClient.js'
+export { setFetch } from './http/fetchFn.js'
 export type { ScreepsClientOptions } from './ScreepsClient.js'
 
 export { Logger } from './logger.js'
@@ -24,6 +25,7 @@ export type {
   RoomObjectDiff,
   RoomMap2Data,
   UserInfo,
+  NotifyPrefs,
   CpuStats,
   WorldStatus,
   ConsoleMessage,
@@ -40,7 +42,7 @@ export type {
 
 export { fetchServerVersion, fetchAuthModInfo, checkUsername, checkEmail, registerUser, getServerFeature, getScreepsmodAuth } from './http/fetchServerVersion.js'
 export type { ApiAuthModInfoResponse } from './http/fetchServerVersion.js'
-export type { RoomHistoryChunk, ApiRoomDecorationsResponse, ApiRoomDecorationItem, ApiRoomDecorationDef, ApiRoomDecorationGraphic, ApiRoomDecorationActive, ApiUserOverviewResponse, ApiUserOverviewTotals, ApiUserRoomsResponse, ApiUserMoneyHistoryResponse, ApiMarketOrder, ApiMarketOrdersIndexResponse, ApiMarketOrdersResponse, ApiMarketMyOrdersResponse, ApiMarketStat, ApiMarketStatsResponse, ApiPowerCreep, ApiPowerCreepsListResponse } from './types/api.js'
+export type { RoomHistoryChunk, ApiRoomDecorationsResponse, ApiRoomDecorationItem, ApiRoomDecorationDef, ApiRoomDecorationGraphic, ApiRoomDecorationActive, ApiUserOverviewResponse, ApiUserOverviewTotals, ApiUserRoomsResponse, ApiUserStatsResponse, ApiLeaderboardFindResponse, ApiUserMoneyHistoryResponse, ApiMarketOrder, ApiMarketOrdersIndexResponse, ApiMarketOrdersResponse, ApiMarketMyOrdersResponse, ApiMarketStat, ApiMarketStatsResponse, ApiPowerCreep, ApiPowerCreepsListResponse, ApiUserMessage, ApiUserMessagesListResponse, ApiUserMessagesIndexEntry, ApiUserMessagesIndexResponse, ApiUserMessagesUnreadCountResponse, ApiUserFindResponse } from './types/api.js'
 export { ROOM_DECORATIONS_MOCK } from './mocks/roomDecorations.js'
 
 export { badgeToSvg } from './badge/index.js'

package/src/types/api.ts

@@ -239,9 +239,28 @@ export interface ApiUserFindResponse {
     username: string
     badge: import('./game.js').Badge
     gcl: number
+    // Lifetime power (GPL) — present in the public lookup alongside gcl.
+    power?: number
   }
 }
 
+/** Response of GET /api/user/stats?id=&interval=. `stats` maps a metric to per-tick buckets; consumers sum the bucket values over the interval. */
+export interface ApiUserStatsResponse {
+  ok: number
+  stats?: Record<string, Array<{ value: number; endTime?: number }>>
+  statsMax?: Record<string, number>
+}
+
+/** Response of GET /api/leaderboard/find?username=&mode=&season=. Servers return either a flat list of per-season records or a single season-scoped record at the top level. */
+export interface ApiLeaderboardFindResponse {
+  ok: number
+  list?: Array<{ season: string; rank: number; score: number; user: string }>
+  rank?: number
+  score?: number
+  season?: string
+  user?: string
+}
+
 export interface ApiUserMoneyHistoryResponse {
   ok: number
   page: number
@@ -318,6 +337,7 @@ export interface ApiUserMessage {
   respondent: string
   user: string
   text: string
+  type?: 'in' | 'out'
   unread: boolean
 }
 
@@ -329,12 +349,12 @@ export interface ApiUserMessagesListResponse {
 export interface ApiUserMessagesIndexEntry {
   _id: string
   message: ApiUserMessage
-  user: { _id: string; username: string; badge: import('./game.js').Badge }
 }
 
 export interface ApiUserMessagesIndexResponse {
   ok: number
-  list: ApiUserMessagesIndexEntry[]
+  messages: ApiUserMessagesIndexEntry[]
+  users: Record<string, { _id: string; username: string; badge: import('./game.js').Badge }>
 }
 
 export interface ApiUserMessagesUnreadCountResponse {

package/src/types/game.ts

@@ -60,6 +60,14 @@ export interface RoomObject {
 export type RoomObjectMap = Record<string, RoomObject>
 export type RoomObjectDiff = Record<string, Partial<RoomObject> | null>
 
+export interface NotifyPrefs {
+    disabled: boolean
+    disabledOnMessages: boolean
+    sendOnline: boolean
+    interval: number
+    errorsInterval: number
+}
+
 export interface UserInfo {
     _id: string
     username: string
@@ -72,6 +80,7 @@ export interface UserInfo {
     badge: Badge
     /** True when the account has a password set. Absent for password-less accounts (e.g. Steam-only logins). Only present for the authenticated user's own info. */
     password?: boolean
+    notifyPrefs?: Partial<NotifyPrefs>
 }
 
 export interface CpuStats {

package/tests/ScreepsClient.test.ts

@@ -104,6 +104,9 @@ describe('ScreepsClient', () => {
   })
 })
 
+// Dynamic-token auth strategy (supportsTokenRefresh defaults to true) used for token-rotation tests.
+const dynamicAuth = (initial = 'initial') => ({ authenticate: async () => initial })
+
 describe('ScreepsClient — token sync', () => {
   it('rotates SocketClient token when an HTTP response carries x-token', async () => {
     vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
@@ -114,7 +117,7 @@ describe('ScreepsClient — token sync', () => {
 
     const client = new ScreepsClient({
       url: 'http://test.local',
-      auth: new TokenAuth({ token: 'initial' }),
+      auth: dynamicAuth(),
       storage: null,
       WebSocket: MockWS as unknown as typeof WebSocket,
       tokenRefresh: false,
@@ -129,7 +132,7 @@ describe('ScreepsClient — token sync', () => {
   it('rotates HttpClient token when WS auth response carries a new token', async () => {
     const client = new ScreepsClient({
       url: 'http://test.local',
-      auth: new TokenAuth({ token: 'initial' }),
+      auth: dynamicAuth(),
       storage: null,
       WebSocket: MockWS as unknown as typeof WebSocket,
       tokenRefresh: false,
@@ -147,16 +150,36 @@ describe('ScreepsClient — token sync', () => {
     expect(httpSetToken).toHaveBeenCalledWith('ws-rotated-token')
     expect(client.http.token).toBe('ws-rotated-token')
   })
+
+  it('does NOT sync tokens when using TokenAuth (static token)', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ ok: 1 }), {
+        headers: { 'content-type': 'application/json', 'x-token': 'server-issued' },
+      })
+    ))
+
+    const client = new ScreepsClient({
+      url: 'http://test.local',
+      auth: new TokenAuth({ token: 'my-static-token' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+    })
+
+    const socketSetToken = vi.spyOn(client.socket, 'setToken')
+    await client.http.request('GET', '/api/auth/me')
+
+    expect(socketSetToken).not.toHaveBeenCalled()
+  })
 })
 
-describe('ScreepsClient — idle token refresh', () => {
+describe('ScreepsClient — world status polling', () => {
   beforeEach(() => { vi.useFakeTimers() })
   afterEach(() => { vi.useRealTimers() })
 
   async function buildConnected(opts: { tokenRefresh?: { intervalMs?: number } | false } = {}) {
     const client = new ScreepsClient({
       url: 'http://test.local',
-      auth: new TokenAuth({ token: 'tok' }),
+      auth: dynamicAuth('tok'),
       storage: null,
       WebSocket: MockWS as unknown as typeof WebSocket,
       tokenRefresh: opts.tokenRefresh,
@@ -170,13 +193,12 @@ describe('ScreepsClient — idle token refresh', () => {
     return client
   }
 
-  it('issues a world-status call after intervalMs of HTTP idleness', async () => {
+  it('polls world-status on a fixed interval', async () => {
     const client = await buildConnected({ tokenRefresh: { intervalMs: 1_000 } })
     const fetchMock = fetch as unknown as ReturnType<typeof vi.fn>
     fetchMock.mockClear()
 
-    // Idle for 1.5s — exceeds 1s interval, refresh should fire on next tick (every 500ms).
-    await vi.advanceTimersByTimeAsync(1_500)
+    await vi.advanceTimersByTimeAsync(1_000)
 
     const paths = fetchMock.mock.calls.map(([url]) => new URL(url as string).pathname)
     expect(paths).toContain('/api/user/world-status')
@@ -184,19 +206,19 @@ describe('ScreepsClient — idle token refresh', () => {
     client.disconnect()
   })
 
-  it('does NOT issue an auth/me call while HTTP traffic resets the idle clock', async () => {
+  it('polls world-status even while other HTTP traffic is ongoing', async () => {
     const client = await buildConnected({ tokenRefresh: { intervalMs: 1_000 } })
     const fetchMock = fetch as unknown as ReturnType<typeof vi.fn>
     fetchMock.mockClear()
 
-    // Make a request every 400ms, well below the 1s threshold.
-    for (let i = 0; i < 5; i++) {
+    // Continuous HTTP traffic every 200ms should not suppress the fixed poll.
+    for (let i = 0; i < 6; i++) {
       await client.http.request('GET', '/api/version')
-      await vi.advanceTimersByTimeAsync(400)
+      await vi.advanceTimersByTimeAsync(200)
     }
 
     const paths = fetchMock.mock.calls.map(([url]) => new URL(url as string).pathname)
-    expect(paths).not.toContain('/api/auth/me')
+    expect(paths).toContain('/api/user/world-status')
 
     client.disconnect()
   })
@@ -209,11 +231,37 @@ describe('ScreepsClient — idle token refresh', () => {
     await vi.advanceTimersByTimeAsync(60_000)
 
     const paths = fetchMock.mock.calls.map(([url]) => new URL(url as string).pathname)
-    expect(paths).not.toContain('/api/auth/me')
+    expect(paths).not.toContain('/api/user/world-status')
 
     client.disconnect()
   })
 
+  it('still polls world-status when using TokenAuth (token is never replaced)', async () => {
+    const client = new ScreepsClient({
+      url: 'http://test.local',
+      auth: new TokenAuth({ token: 'tok' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+      tokenRefresh: { intervalMs: 1_000 },
+    })
+    const connectPromise = client.connect()
+    await vi.advanceTimersByTimeAsync(0)
+    const ws = MockWS.instances[MockWS.instances.length - 1]
+    ws.simulateOpen()
+    ws.simulateMessage('auth ok tok')
+    await connectPromise
+
+    const fetchMock = fetch as unknown as ReturnType<typeof vi.fn>
+    fetchMock.mockClear()
+    await vi.advanceTimersByTimeAsync(1_500)
+
+    const paths = fetchMock.mock.calls.map(([url]) => new URL(url as string).pathname)
+    expect(paths).toContain('/api/user/world-status')
+    // Token must not have changed despite the response
+    expect(client.http.token).toBe('tok')
+    client.disconnect()
+  })
+
   it('stops the refresh timer on disconnect()', async () => {
     const client = await buildConnected({ tokenRefresh: { intervalMs: 1_000 } })
     client.disconnect()
@@ -224,6 +272,6 @@ describe('ScreepsClient — idle token refresh', () => {
     await vi.advanceTimersByTimeAsync(5_000)
 
     const paths = fetchMock.mock.calls.map(([url]) => new URL(url as string).pathname)
-    expect(paths).not.toContain('/api/auth/me')
+    expect(paths).not.toContain('/api/user/world-status')
   })
 })

package/tests/http/HttpClient.test.ts

@@ -81,12 +81,23 @@ describe('HttpClient', () => {
     fetchMock.mockResolvedValue(mockResponse({ ok: 1 }, {
       headers: { 'content-type': 'application/json', 'x-token': 'refreshed' },
     }))
-    const http = new HttpClient({ url: 'http://test.local', auth: new TokenAuth({ token: 'old' }) })
+    // Use a plain object (supportsTokenRefresh defaults to true) to verify rotation works for dynamic-token strategies
+    const http = new HttpClient({ url: 'http://test.local', auth: { authenticate: async () => 'old' } })
     http.token = 'old'
     await http.request('GET', '/api/version')
     expect(http.token).toBe('refreshed')
   })
 
+  it('does NOT update token from x-token header when using TokenAuth (static token)', async () => {
+    fetchMock.mockResolvedValue(mockResponse({ ok: 1 }, {
+      headers: { 'content-type': 'application/json', 'x-token': 'server-issued' },
+    }))
+    const http = new HttpClient({ url: 'http://test.local', auth: new TokenAuth({ token: 'my-static-token' }) })
+    http.token = 'my-static-token'
+    await http.request('GET', '/api/version')
+    expect(http.token).toBe('my-static-token')
+  })
+
   it('retries once on 401 after re-authenticating', async () => {
     let calls = 0
     fetchMock.mockImplementation(() => {
@@ -136,13 +147,25 @@ describe('HttpClient', () => {
     fetchMock.mockResolvedValue(mockResponse({ ok: 1 }, {
       headers: { 'content-type': 'application/json', 'x-token': 'new-tok' },
     }))
-    const http = new HttpClient({ url: 'http://test.local', auth: new TokenAuth({ token: 'old' }) })
+    // Use a plain object (supportsTokenRefresh defaults to true) to verify the event fires for dynamic-token strategies
+    const http = new HttpClient({ url: 'http://test.local', auth: { authenticate: async () => 'old' } })
     const handler = vi.fn()
     http.on('http:tokenRefresh', handler)
     await http.request('GET', '/api/version')
     expect(handler).toHaveBeenCalledWith({ token: 'new-tok' })
   })
 
+  it('does NOT emit http:tokenRefresh when using TokenAuth (static token)', async () => {
+    fetchMock.mockResolvedValue(mockResponse({ ok: 1 }, {
+      headers: { 'content-type': 'application/json', 'x-token': 'server-issued' },
+    }))
+    const http = new HttpClient({ url: 'http://test.local', auth: new TokenAuth({ token: 'my-static-token' }) })
+    const handler = vi.fn()
+    http.on('http:tokenRefresh', handler)
+    await http.request('GET', '/api/version')
+    expect(handler).not.toHaveBeenCalled()
+  })
+
   it('emits http:success on 200 response', async () => {
     fetchMock.mockResolvedValue(mockResponse({ ok: 1 }))
     const http = new HttpClient({ url: 'http://test.local', auth: new TokenAuth({ token: 't' }) })