screeps-connectivity 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screeps-connectivity",
-  "version": "0.9.0",
+  "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

@@ -117,7 +117,7 @@ export class HttpClient extends EventTarget {
     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/index.ts

@@ -25,6 +25,7 @@ export type {
   RoomObjectDiff,
   RoomMap2Data,
   UserInfo,
+  NotifyPrefs,
   CpuStats,
   WorldStatus,
   ConsoleMessage,
@@ -41,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' }) })