screeps-connectivity 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- 8fd1a08: Fix Steam login failing with "auth failed" on brand-new accounts (e.g. xxscreeps). Some servers hand back a provisional token for a first-time OAuth signup that can't authenticate the websocket until a username is chosen; the login flow now detects this via `/api/auth/me` and prompts for a username before connecting. Adds `fetchAuthMeWithToken` and `completeProviderRegistration` to `screeps-connectivity`.
+- b26940a: xxscreeps-mod-client now publishes an `xxscreeps-mod-client` server feature at `/api/version` reflecting `.screepsrc.yaml`'s `backend.allowGuestAccess`, `backend.allowEmailRegistration`, and `backend.steamApiKey`. screeps-client reads this via the new `getXxscreepsModClientFeature` helper (screeps-connectivity) to show or hide the Guest, "Create account", and "Login with Steam" options to match what the server actually allows, instead of guessing.
+
+### Patch Changes
+
+- 594073a: Fix cache/storage namespace collision when two distinct game worlds are hosted under the same domain via a path (e.g. Screeps World vs Screeps Season on screeps.com) — terrain and other cached data no longer bleed between them.
+- 15d0c1f: Show a dismissable popup (reload/logout) instead of silently bouncing to the login screen when an already-connected session hits a fatal socket error or disconnect. Add a similar popup for 429 rate-limit responses from official servers, with a button to open the server's "disable rate limiting" link (opens the OS browser in the desktop app). Fix the map view not reloading terrain when switching shards — room names collide across shards, so the renderer's terrain cache was serving stale terrain from the previously viewed shard. Also removes the 5-minute sessionStorage cache on `fetchServerVersion` so the pre-login welcome screen always reflects the server's current `/api/version`.
+
+## 0.11.0
+
+### Minor Changes
+
+- cc7f5be: Add `MapStatName`, `MapStatPrefix`, `MapStatInterval` const objects and `mapStat()` helper for typed map-stats API access; add `TerrainColors` interface and decoration fields to `MapStatsRoomData`; expose `MapStatsStoreEvents` and `statName` in room events.
+
+  Client: world map shard selector, "out of borders" black overlay, reveal-when-ready terrain/stats sync, mineral overlay on demand, room terrain decorations from player themes.
+
 ## 0.10.0
 
 ### Minor Changes

package/package.json

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

package/src/ScreepsClient.ts

@@ -64,7 +64,12 @@ export class ScreepsClient {
   constructor(opts: ScreepsClientOptions) {
     let namespace: string
     try {
-      namespace = new URL(opts.url).hostname
+      const parsed = new URL(opts.url)
+      const path = parsed.pathname.replace(/\/+$/, '')
+      // Hostname alone isn't enough: some servers host multiple distinct worlds under one
+      // domain via a path (e.g. Screeps World at screeps.com vs Screeps Season at
+      // screeps.com/season) — including the path keeps their caches from colliding.
+      namespace = path ? `${parsed.hostname}${path}` : parsed.hostname
     } catch {
       throw new TypeError(`ScreepsClient: invalid url "${opts.url}"`)
     }
@@ -83,7 +88,7 @@ export class ScreepsClient {
       user: new UserStore(this.http, this.socket, this.cache, this.logger.child('user')),
       server: new ServerStore(this.http, this.socket, this.cache, this.logger.child('server')),
       map: new MapStore(this.socket, map2Storage, { maxSubscriptions: opts.map2?.maxSubscriptions ?? 500 }, this.logger.child('map')),
-      mapStats: new MapStatsStore(this.http, 100, 500, this.logger.child('mapStats')),
+      mapStats: new MapStatsStore(this.http, 100, 100, this.logger.child('mapStats')),
       navigation: new NavigationStore(50, this.logger.child('navigation')),
     }
 

package/src/http/fetchServerVersion.ts

@@ -1,6 +1,6 @@
 import type { ServerVersion } from '../types/game.js'
-import type { ScreepsmodAuthFeature, ServerFeature } from '../types/game.js'
-import type { ApiAuthModInfoResponse, ApiRegisterCheckResponse } from '../types/api.js'
+import type { ScreepsmodAuthFeature, ServerFeature, XxscreepsModClientFeature } from '../types/game.js'
+import type { ApiAuthMeResponse, ApiAuthModInfoResponse, ApiRegisterCheckResponse } from '../types/api.js'
 import { getFetch } from './fetchFn.js'
 
 export type { ApiAuthModInfoResponse }
@@ -49,19 +49,12 @@ function baseUrl(url: string): string {
 
 /**
  * Fetch `/api/version` from a Screeps server without authentication.
- * The result is cached in `sessionStorage` for 5 minutes (per server hostname).
  * Useful for pre-login UI: showing the welcome text and detecting installed mods.
  */
 export async function fetchServerVersion(url: string): Promise<ServerVersion> {
-  const key = sessionKey('version', url)
-  const cached = readFromSession<ServerVersion>(key)
-  if (cached) return cached
-
   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)
-  return data
+  return res.json() as Promise<ServerVersion>
 }
 
 /**
@@ -123,6 +116,42 @@ export async function registerUser(
   return res.json() as Promise<{ ok: number; error?: string }>
 }
 
+/**
+ * Fetch `/api/auth/me` using a bare token, without going through a full `ScreepsClient`.
+ * Used right after an OAuth popup (Steam, GitHub, ...) hands back a token, to check whether
+ * the account still needs to finish registration — servers like xxscreeps issue a provisional
+ * token for brand-new provider signups that has no `username` yet until one is chosen.
+ */
+export async function fetchAuthMeWithToken(url: string, token: string): Promise<ApiAuthMeResponse | null> {
+  const res = await getFetch()(`${baseUrl(url)}api/auth/me`, {
+    headers: { 'X-Token': token, 'X-Username': token },
+  })
+  if (!res.ok) return null
+  return res.json() as Promise<ApiAuthMeResponse>
+}
+
+/**
+ * Finish an OAuth provider signup (Steam, GitHub, ...) by choosing a username for the
+ * provisional account. Requires the provisional token handed back from the OAuth popup.
+ * Returns the upgraded token (a real, non-expiring-in-2-minutes user token) taken from the
+ * `X-Token` response header — the provisional token cannot authenticate anything else.
+ */
+export async function completeProviderRegistration(
+  url: string,
+  token: string,
+  username: string,
+  email?: string,
+): Promise<{ token: string }> {
+  const res = await getFetch()(`${baseUrl(url)}api/register/set-username`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Token': token, 'X-Username': token },
+    body: JSON.stringify({ username, ...(email ? { email } : {}) }),
+  })
+  const data = await res.json() as { ok?: number; error?: string }
+  if (!res.ok || data.error) throw new Error(data.error ?? `HTTP ${res.status}`)
+  return { token: res.headers.get('x-token') ?? token }
+}
+
 /**
  * Extract a specific feature entry from a `ServerVersion` response by name.
  * Returns `undefined` if the feature is not present.
@@ -150,3 +179,17 @@ export function getServerFeature<T extends ServerFeature = ServerFeature>(
 export function getScreepsmodAuth(version: ServerVersion): ScreepsmodAuthFeature | undefined {
   return getServerFeature<ScreepsmodAuthFeature>(version, 'screepsmod-auth')
 }
+
+/**
+ * Returns the `xxscreeps-mod-client` feature entry if present, otherwise `undefined`.
+ * This feature reflects the server's `.screepsrc.yaml` `backend` settings
+ * (`allowGuestAccess`, `allowEmailRegistration`, `steamApiKey`), letting the client
+ * gate guest/registration/Steam UI without an extra request.
+ *
+ * @example
+ * const caps = getXxscreepsModClientFeature(version)
+ * if (caps && !caps.allowGuestAccess) hideGuestButton()
+ */
+export function getXxscreepsModClientFeature(version: ServerVersion): XxscreepsModClientFeature | undefined {
+  return getServerFeature<XxscreepsModClientFeature>(version, 'xxscreeps-mod-client')
+}

package/src/index.ts

@@ -32,6 +32,7 @@ export type {
   ServerVersion,
   ServerFeature,
   ScreepsmodAuthFeature,
+  XxscreepsModClientFeature,
   ShardInfo,
   WorldInfo,
   Badge,
@@ -40,9 +41,9 @@ export type {
   MapVisualEntry,
 } from './types/game.js'
 
-export { fetchServerVersion, fetchAuthModInfo, checkUsername, checkEmail, registerUser, getServerFeature, getScreepsmodAuth } from './http/fetchServerVersion.js'
+export { fetchServerVersion, fetchAuthModInfo, checkUsername, checkEmail, registerUser, fetchAuthMeWithToken, completeProviderRegistration, getServerFeature, getScreepsmodAuth, getXxscreepsModClientFeature } from './http/fetchServerVersion.js'
 export type { ApiAuthModInfoResponse } from './http/fetchServerVersion.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 type { ApiAuthMeResponse, 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'
@@ -60,3 +61,6 @@ export type { UserStore } from './stores/UserStore.js'
 export type { ServerStore } from './stores/ServerStore.js'
 export type { MapStore, Map2Subscription, MapStoreOptions } from './stores/MapStore.js'
 export type { NavigationStore, NavigationState, NavigationStoreEvents } from './stores/NavigationStore.js'
+export { MapStatName, MapStatPrefix, MapStatInterval, mapStat } from './stores/MapStatsStore.js'
+export type { MapStatsRoomData, MapStatsStoreEvents, TerrainColors } from './stores/MapStatsStore.js'
+

package/src/stores/MapStatsStore.ts

@@ -3,6 +3,41 @@ import type { Logger } from '../logger.js'
 import type { HttpClient } from '../http/HttpClient.js'
 import type { ApiMapStatsRoomStat, ApiMapStatsBadge } from '../types/api.js'
 
+/** Fixed stat names for the map-stats API (no interval parameter). */
+export const MapStatName = {
+  owner:    'owner0',
+  minerals: 'minerals0',
+  power:    'power0',
+} as const
+
+/** Stat name prefixes that take an interval suffix — combine with {@link MapStatInterval} via {@link mapStat}. */
+export const MapStatPrefix = {
+  energyControl:      'energyControl',
+  energyHarvested:    'energyHarvested',
+  energyConstruction: 'energyConstruction',
+  energyCreeps:       'energyCreeps',
+  creepsProduced:     'creepsProduced',
+  creepsLost:         'creepsLost',
+  powerProcessed:     'powerProcessed',
+} as const
+
+/** Tick-bucket intervals supported by the Screeps API for parameterised stats. */
+export const MapStatInterval = {
+  hour1:   8,
+  hours24: 180,
+  days7:   1440,
+} as const
+
+/** Build a parameterised stat name, e.g. `mapStat(MapStatPrefix.energyControl, MapStatInterval.hours24)` → `"energyControl180"`. */
+export const mapStat = (prefix: string, interval: number): string => `${prefix}${interval}`
+
+/** Custom terrain palette extracted from a room's active world-map decoration. */
+export interface TerrainColors {
+  plain?: string  // CSS color string, e.g. "#68DFFF"
+  swamp?: string
+  road?: string
+}
+
 export interface MapStatsRoomData {
   own?: { user: string; level: number }
   mineral?: string
@@ -16,10 +51,12 @@ export interface MapStatsRoomData {
    * response's user map and may be absent if the signer isn't included there.
    */
   sign?: { user: string; text: string; datetime: number; username?: string; badge?: ApiMapStatsBadge }
+  /** Custom terrain colors from an active world-map decoration, if any. */
+  terrainColors?: TerrainColors
 }
 
 export interface MapStatsStoreEvents {
-  'mapStats:room': { room: string; shard: string | null; stat: MapStatsRoomData }
+  'mapStats:room': { room: string; shard: string | null; stat: MapStatsRoomData; statName: string }
 }
 
 interface PendingBatch {
@@ -79,15 +116,16 @@ export class MapStatsStore extends TypedStore<MapStatsStoreEvents> {
 
         const userMap = res.users ?? {}
 
+        const shardKey = batch.shard === 'shard0' ? null : batch.shard
         for (const [room, stat] of Object.entries(res.stats)) {
           const data = this.buildData(stat, userMap)
-          this.emit('mapStats:room', { room, shard: batch.shard === 'shard0' ? null : batch.shard, stat: data })
+          this.emit('mapStats:room', { room, shard: shardKey, stat: data, statName: batch.statName })
         }
 
         // Emit empty data for rooms that don't exist on server
         for (const room of allRooms) {
           if (!res.stats[room]) {
-            this.emit('mapStats:room', { room, shard: batch.shard === 'shard0' ? null : batch.shard, stat: {} })
+            this.emit('mapStats:room', { room, shard: shardKey, stat: {}, statName: batch.statName })
           }
         }
       } catch (err) {
@@ -97,19 +135,19 @@ export class MapStatsStore extends TypedStore<MapStatsStoreEvents> {
   }
 
   private buildData(stat: ApiMapStatsRoomStat, userMap: Record<string, { username: string; badge: ApiMapStatsBadge }>): MapStatsRoomData {
-    let mineral: string | undefined
-    let density: number | undefined
-    for (let i = 0; i < 3; i++) {
-      const mineralKey = `minerals${i}` as `minerals${number}`
-      const mineralData = stat[mineralKey]
-      if (mineralData) {
-        mineral = mineralData.type
-        density = mineralData.density
-        break
-      }
-    }
+    const mineral = stat.minerals0?.type
+    const density = stat.minerals0?.density
     const ownerId = stat.own?.user
     const signUserId = stat.sign?.user
+
+    // Find the terrain-theme decoration (world=true + floor/swamp color properties).
+    const terrainDeco = stat.decorations?.find(d => d.active.world && (d.active.floorBackgroundColor || d.active.swampColor))
+    const terrainColors: TerrainColors | undefined = terrainDeco ? {
+      plain: terrainDeco.active.floorBackgroundColor,
+      swamp: terrainDeco.active.swampColor,
+      road: terrainDeco.active.roadsColor,
+    } : undefined
+
     return {
       own: stat.own,
       mineral,
@@ -127,6 +165,7 @@ export class MapStatsStore extends TypedStore<MapStatsStoreEvents> {
             badge: signUserId ? userMap[signUserId]?.badge : undefined,
           }
         : undefined,
+      terrainColors,
     }
   }
 }

package/src/types/api.ts

@@ -142,6 +142,25 @@ export interface ApiLeaderboardSeasonsResponse {
   seasons: Array<{ _id: string; name: string; date: string }>
 }
 
+export interface ApiDecorationActive {
+  world?: boolean
+  tileScale?: number | string
+  // terrain theme
+  floorBackgroundColor?: string
+  floorForegroundColor?: string
+  floorForegroundAlpha?: string | number
+  swampColor?: string
+  swampStrokeColor?: string
+  roadsColor?: string
+  roadsBrightness?: number | string
+  // room overlay (not used on world map yet)
+  foregroundColor?: string
+  foregroundAlpha?: number | string
+  backgroundColor?: string
+  strokeColor?: string
+  [key: string]: unknown
+}
+
 export interface ApiMapStatsRoomStat {
   status: string
   novice: number | null
@@ -150,7 +169,8 @@ export interface ApiMapStatsRoomStat {
   own?: { user: string; level: number }
   sign?: { user: string; text: string; time: number; datetime: number }
   safeMode?: boolean
-  [mineral: `minerals${number}`]: { type: string; density: number } | undefined
+  minerals0?: { type: string; density: number }
+  decorations?: Array<{ _id: string; user: string; decoration: string; active: ApiDecorationActive }>
 }
 
 export interface ApiMapStatsBadge {

package/src/types/game.ts

@@ -113,6 +113,18 @@ export interface ScreepsmodAuthFeature extends ServerFeature {
     }>
 }
 
+/**
+ * Published by `xxscreeps-mod-client` at `/api/version`, reflecting the
+ * `backend` settings from the server's `.screepsrc.yaml`.
+ */
+export interface XxscreepsModClientFeature extends ServerFeature {
+    name: 'xxscreeps-mod-client'
+    version: number
+    allowGuestAccess: boolean
+    allowEmailRegistration: boolean
+    steamLogin: boolean
+}
+
 export interface ServerVersion {
     ok: number
     package: number

package/tests/ScreepsClient.test.ts

@@ -1,6 +1,15 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { ScreepsClient } from '../src/ScreepsClient.js'
 import { TokenAuth } from '../src/http/auth/TokenAuth.js'
+import type { StorageAdapter } from '../src/storage/StorageAdapter.js'
+
+class MemoryStorage implements StorageAdapter {
+  readonly data = new Map<string, Uint8Array>()
+  async get(key: string): Promise<Uint8Array | null> { return this.data.get(key) ?? null }
+  async set(key: string, value: Uint8Array): Promise<void> { this.data.set(key, value) }
+  async delete(key: string): Promise<void> { this.data.delete(key) }
+  async clear(): Promise<void> { this.data.clear() }
+}
 
 class MockWS {
   static instances: MockWS[] = []
@@ -38,6 +47,49 @@ beforeEach(() => {
 })
 afterEach(() => { vi.unstubAllGlobals() })
 
+describe('ScreepsClient — cache namespace', () => {
+  it('does not collide between two worlds hosted under the same hostname (e.g. Screeps World vs Season)', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockImplementation((url: string) => {
+      const { pathname } = new URL(url)
+      const digit = pathname.startsWith('/season/') ? '1' : '0'
+      return Promise.resolve(
+        new Response(JSON.stringify({ ok: 1, terrain: [{ _id: 'id', room: 'W5N5', terrain: digit.repeat(2500), type: 'terrain' }] }), {
+          headers: { 'content-type': 'application/json' },
+        })
+      )
+    }))
+
+    const storage = new MemoryStorage()
+    const worldClient = new ScreepsClient({
+      url: 'https://test.local',
+      auth: new TokenAuth({ token: 'tok' }),
+      storage,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+    })
+    const seasonClient = new ScreepsClient({
+      url: 'https://test.local/season',
+      auth: new TokenAuth({ token: 'tok' }),
+      storage,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+    })
+
+    const worldTerrain = await worldClient.stores.room.terrain('W5N5', 'shard0')
+    const seasonTerrain = await seasonClient.stores.room.terrain('W5N5', 'shard0')
+
+    // Same room name + shard on both worlds must resolve to distinct terrain and
+    // distinct persisted cache keys — the path (/season) has to disambiguate them
+    // since hostname alone is identical.
+    expect(worldTerrain.get(0, 0)).toBe(0)
+    expect(seasonTerrain.get(0, 0)).toBe(1)
+    expect([...storage.data.keys()]).toEqual([
+      'test.local/terrain/shard0/W5N5',
+      'test.local/season/terrain/shard0/W5N5',
+    ])
+
+    vi.unstubAllGlobals()
+  })
+})
+
 describe('ScreepsClient', () => {
   it('exposes http, socket, and stores properties', () => {
     const client = new ScreepsClient({