screeps-connectivity 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- 94a6658: Add Discord OAuth login: getDiscordFeature() helper in screeps-connectivity, and a "Login with Discord" button in the web and desktop login forms.
+
+### Patch Changes
+
+- 46b5e2d: Fix Steam/password logins silently expiring after ~5 minutes on screepsmod-auth servers. These logins reconnect via a rotating, TTL-limited session token, but `TokenAuth` was hard-coded to ignore the server-issued `X-Token`, so the client kept replaying the original token until the server expired it — surfacing as a sudden `401` on `/api/user/world-status` (and every other authed request) even while actively using the client.
+
+  `TokenAuth` now accepts `supportsTokenRefresh` (default `false`, preserving durable personal-API-token behavior). The client enables it for Steam/password-derived session tokens so the rotated `X-Token` is adopted on every response, keeping the session alive.
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screeps-connectivity",
-  "version": "0.11.0",
+  "version": "0.13.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}"`)
     }

package/src/http/auth/TokenAuth.ts

@@ -2,11 +2,19 @@ import type { AuthStrategy } from './AuthStrategy.js'
 import type { HttpClient } from '../HttpClient.js'
 
 export class TokenAuth implements AuthStrategy {
-  readonly supportsTokenRefresh = false
+  readonly supportsTokenRefresh: boolean
   private readonly token: string
 
-  constructor(opts: { token: string }) {
+  /**
+   * @param opts.supportsTokenRefresh Set true when the token is a rotating,
+   *   TTL-limited session token (e.g. obtained from a screepsmod-auth steam/password
+   *   exchange) so the client adopts the server-issued `X-Token` and the session
+   *   stays alive. Leave false (default) for a durable personal API token, which
+   *   must never be replaced by a server-issued token.
+   */
+  constructor(opts: { token: string; supportsTokenRefresh?: boolean }) {
     this.token = opts.token
+    this.supportsTokenRefresh = opts.supportsTokenRefresh ?? false
   }
 
   async authenticate(_http: HttpClient): Promise<string> {

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 { DiscordFeature, 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,30 @@ 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')
+}
+
+/**
+ * Returns the `discord` feature entry (published by `xxscreeps-mod-discord`) if
+ * present, otherwise `undefined`. Use `discordLogin` to gate the "Login with
+ * Discord" button before showing it.
+ *
+ * @example
+ * const discord = getDiscordFeature(version)
+ * if (discord?.discordLogin) showDiscordButton()
+ */
+export function getDiscordFeature(version: ServerVersion): DiscordFeature | undefined {
+  return getServerFeature<DiscordFeature>(version, 'discord')
+}

package/src/index.ts

@@ -32,6 +32,8 @@ export type {
   ServerVersion,
   ServerFeature,
   ScreepsmodAuthFeature,
+  XxscreepsModClientFeature,
+  DiscordFeature,
   ShardInfo,
   WorldInfo,
   Badge,
@@ -40,9 +42,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, getDiscordFeature } 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'

package/src/types/game.ts

@@ -113,6 +113,30 @@ 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
+}
+
+/**
+ * Published by `xxscreeps-mod-discord` at `/api/version` when Discord login is
+ * configured. `discordLogin` gates the UI; `loginUrl` is the OAuth entry point
+ * (a popup navigates there to start the flow).
+ */
+export interface DiscordFeature extends ServerFeature {
+    name: 'discord'
+    version: number
+    discordLogin: boolean
+    loginUrl: string
+}
+
 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({

package/tests/http/HttpClient.test.ts

@@ -98,6 +98,16 @@ describe('HttpClient', () => {
     expect(http.token).toBe('my-static-token')
   })
 
+  it('DOES update token from x-token header when TokenAuth opts into refresh (session token)', async () => {
+    fetchMock.mockResolvedValue(mockResponse({ ok: 1 }, {
+      headers: { 'content-type': 'application/json', 'x-token': 'rotated' },
+    }))
+    const http = new HttpClient({ url: 'http://test.local', auth: new TokenAuth({ token: 'session-token', supportsTokenRefresh: true }) })
+    http.token = 'session-token'
+    await http.request('GET', '/api/version')
+    expect(http.token).toBe('rotated')
+  })
+
   it('retries once on 401 after re-authenticating', async () => {
     let calls = 0
     fetchMock.mockImplementation(() => {