screeps-connectivity 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## Unreleased
+
+### Breaking Changes
+
+- **`RoomStore.subscribeMap2()` removed** — use `client.stores.map.subscribeMap2()` instead.
+- **`RoomStore.map2data()` removed** — use `client.stores.map.map2data()` instead.
+- **`room:map2update` event moved from `RoomStore` to `MapStore`** — update `store.on('room:map2update', ...)` calls to use `client.stores.map.on('room:map2update', ...)`. The payload now includes a `source: 'live' | 'cache'` field.
+
+### New Features
+
+#### `MapStore` (`client.stores.map`)
+
+- `subscribeMap2(room, shard)` returns a `Map2Subscription` with `status()`, `cachedData()`, and `onStatusChange()`.
+- Configurable subscription limit via `ScreepsClientOptions.map2.maxSubscriptions` (default 500). Rooms beyond the limit are placed on a FIFO waitlist and promoted automatically as slots free.
+- Diff detection: identical successive server messages do not emit `room:map2update`. Dedup uses a canonical JSON hash cached on the active entry, so each incoming message is canonicalized only once (not once per side).
+- `room:map2update` event now carries `source: 'live' | 'cache'`. On subscribe, cached data is emitted immediately (microtask) with `source: 'cache'` so subscribers can render stale state before the first live tick arrives.
+- `room:map2state` event emitted when a room transitions between `'pending'` and `'active'`, including on WebSocket reconnect.
+- Persistent two-tier cache via `Map2Storage` (memory + IndexedDB). Up to `map2.maxCacheEntries` rooms cached with LRU eviction (default 10 000).
+- Automatic reconnect handling: all active and pending subscriptions re-emit `room:map2state` after reconnect, and the per-room dedup hash is reset so the first live `room:map2update` after every reconnect is guaranteed to fire (even when the resent payload is identical to the last one seen).
+
+#### `NavigationStore` (`client.stores.navigation`)
+
+- `navigateTo(room, shard)` — append to bounded history (default 50 entries).
+- `back()` / `forward()` — move within history; return `false` at boundaries.
+- `canBack()` / `canForward()` — synchronous state queries for enabling/disabling UI buttons.
+- `current()` — snapshot of current room, shard, index, and history.
+- `navigation:change` event emitted on every navigation action.
+
+#### `ScreepsClientOptions`
+
+- New `map2` option: `{ maxSubscriptions?: number; maxCacheEntries?: number }`.
+- New `tokenRefresh` option: `{ intervalMs?: number } | false` (default `{ intervalMs: 30_000 }`). Issues a lightweight `auth/me` request after `intervalMs` of HTTP idleness to keep the session token alive; any real HTTP traffic resets the idle clock. Pass `false` to disable.
+
+#### Token lifecycle
+
+- `HttpClient` and `SocketClient` token are now kept in sync. `HttpClient` rotations (via `x-token` header) propagate to `SocketClient` via the new `socket.setToken()` method, and WS auth-token rotations propagate back via the new `socket:tokenRefresh` event. Previously the two could drift, causing the WS to attempt reconnects with stale tokens.
+- New public methods `HttpClient.setToken(token)` and `SocketClient.setToken(token)`.
+- New event `socket:tokenRefresh` emitted from `SocketClient` when the `auth ok` reply contains a token. `ScreepsClient` listens to both `http:tokenRefresh` and `socket:tokenRefresh` and forwards rotations to the other transport automatically.

package/eslint.config.js

@@ -0,0 +1,54 @@
+import globals from 'globals';
+import js from '@eslint/js'
+import tsParser from '@typescript-eslint/parser'
+import tsPlugin from '@typescript-eslint/eslint-plugin'
+
+export default [
+  {
+    ignores: ['node_modules/**', 'dist/**', '.gitkeep'],
+  },
+  js.configs.recommended,
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        RequestInit: 'readonly',
+        ResponseInit: 'readonly',
+        NodeJS: 'readonly',
+      },
+    },
+    plugins: { '@typescript-eslint': tsPlugin },
+    rules: {
+      ...tsPlugin.configs['recommended'].rules,
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    files: ['tests/**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        RequestInit: 'readonly',
+        ResponseInit: 'readonly',
+        NodeJS: 'readonly',
+        describe: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+      },
+    },
+    plugins: { '@typescript-eslint': tsPlugin },
+    rules: {
+      ...tsPlugin.configs['recommended'].rules,
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+    },
+  },
+]

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "screeps-connectivity",
+  "version": "0.2.0",
+  "license": "ISC",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bastianh/screeps-client.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./file-storage": {
+      "development": "./src/file-storage.ts",
+      "types": "./dist/file-storage.d.ts",
+      "import": "./dist/file-storage.js",
+      "require": "./dist/file-storage.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.7.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "fake-indexeddb": "^6.0.0",
+    "globals": "^17.6.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.6"
+  }
+}

package/src/ScreepsClient.ts

@@ -0,0 +1,172 @@
+import { HttpClient } from './http/HttpClient.js'
+import { SocketClient } from './socket/SocketClient.js'
+import { Cache } from './cache/Cache.js'
+import { RoomStore } from './stores/RoomStore.js'
+import { UserStore } from './stores/UserStore.js'
+import { ServerStore } from './stores/ServerStore.js'
+import { MapStore } from './stores/MapStore.js'
+import { MapStatsStore } from './stores/MapStatsStore.js'
+import { NavigationStore } from './stores/NavigationStore.js'
+import { Map2Storage } from './cache/Map2Storage.js'
+import { Logger } from './logger.js'
+import type { LogFn } from './logger.js'
+import type { AuthStrategy } from './http/auth/AuthStrategy.js'
+import type { StorageAdapter } from './storage/StorageAdapter.js'
+import type { Subscription } from './subscription/index.js'
+
+type WsConstructor = typeof globalThis.WebSocket
+
+export interface TokenRefreshOptions {
+  /** Milliseconds of idleness before issuing a keep-alive request. Default 30_000. */
+  intervalMs?: number
+}
+
+export interface ScreepsClientOptions {
+  url: string
+  auth: AuthStrategy
+  storage?: StorageAdapter | null
+  WebSocket?: WsConstructor
+  debug?: boolean | LogFn
+  /** Required when the server is started with `SERVER_PASSWORD`. Sent as `X-Server-Password` on every HTTP request. */
+  serverPassword?: string
+  map2?: {
+    maxSubscriptions?: number
+    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.
+   */
+  tokenRefresh?: TokenRefreshOptions | false
+}
+
+export class ScreepsClient {
+  readonly http: HttpClient
+  readonly socket: SocketClient
+  readonly stores: {
+    readonly room: RoomStore
+    readonly user: UserStore
+    readonly server: ServerStore
+    readonly map: MapStore
+    readonly mapStats: MapStatsStore
+    readonly navigation: NavigationStore
+  }
+  private readonly cache: Cache
+  private readonly logger: Logger
+  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) {
+    let namespace: string
+    try {
+      namespace = new URL(opts.url).hostname
+    } catch {
+      throw new TypeError(`ScreepsClient: invalid url "${opts.url}"`)
+    }
+    this.logger = Logger.create(opts.debug)
+    this.logger.log(`[screeps:client] init ${opts.url}`)
+    this.cache = new Cache(namespace, opts.storage ?? null)
+    this.http = new HttpClient({ url: opts.url, auth: opts.auth, logger: this.logger.child('http'), serverPassword: opts.serverPassword })
+    this.socket = new SocketClient({ url: opts.url, WebSocket: opts.WebSocket, logger: this.logger.child('socket') })
+    const map2Storage = new Map2Storage({
+      adapter: opts.storage ?? null,
+      namespace,
+      maxEntries: opts.map2?.maxCacheEntries ?? 10000,
+    })
+    this.stores = {
+      room: new RoomStore(this.http, this.socket, this.cache, this.logger.child('room')),
+      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')),
+      navigation: new NavigationStore(50, this.logger.child('navigation')),
+    }
+
+    this.tokenRefreshIntervalMs = opts.tokenRefresh === false
+      ? null
+      : (opts.tokenRefresh?.intervalMs ?? 30_000)
+
+    this.wireTokenSync()
+  }
+
+  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()
+    }))
+  }
+
+  get isConnected(): boolean {
+    return this.socket.isConnected
+  }
+
+  async connect(): Promise<void> {
+    this.logger.log('[screeps:client] connect')
+    await this.http.authenticate()
+    await this.socket.connect(this.http.token!)
+    await Promise.all([
+      this.stores.user.me(),
+      this.stores.user.worldStatus(),
+      this.stores.server.version(),
+    ])
+    this.startTokenRefresh()
+  }
+
+  disconnect(): void {
+    this.logger.log('[screeps:client] disconnect')
+    this.stopTokenRefresh()
+    this.socket.disconnect()
+  }
+
+  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)
+  }
+
+  private stopTokenRefresh(): void {
+    if (this.tokenRefreshTimer !== null) {
+      clearInterval(this.tokenRefreshTimer)
+      this.tokenRefreshTimer = null
+    }
+  }
+
+  private async refreshTokenNow(): Promise<void> {
+    if (this.refreshInFlight) return
+    this.refreshInFlight = true
+    try {
+      this.logger.log('[screeps:client] token refresh (idle)')
+      await this.stores.user.refreshWorldStatus()
+    } catch (err) {
+      this.logger.log('[screeps:client] token refresh failed', err)
+    } finally {
+      this.refreshInFlight = false
+    }
+  }
+
+  async clearCache(): Promise<void> {
+    this.logger.log('[screeps:client] clearCache')
+    await this.cache.clearAll()
+  }
+}

package/src/badge/colors.ts

@@ -0,0 +1,83 @@
+function pad(v: number): string {
+  const hex = Math.round(v).toString(16)
+  return hex.length < 2 ? '0' + hex : hex
+}
+
+function hsl2rgb(H: number, S: number, L: number): string {
+  const C = (1 - Math.abs(2 * L - 1)) * S
+  const H_ = H / 60
+  const X = C * (1 - Math.abs((H_ % 2) - 1))
+
+  let R1 = 0
+  let G1 = 0
+  let B1 = 0
+
+  if (!Number.isNaN(H) && H !== null && H !== undefined) {
+    if (H_ >= 0 && H_ < 1) {
+      R1 = C
+      G1 = X
+      B1 = 0
+    } else if (H_ >= 1 && H_ < 2) {
+      R1 = X
+      G1 = C
+      B1 = 0
+    } else if (H_ >= 2 && H_ < 3) {
+      R1 = 0
+      G1 = C
+      B1 = X
+    } else if (H_ >= 3 && H_ < 4) {
+      R1 = 0
+      G1 = X
+      B1 = C
+    } else if (H_ >= 4 && H_ < 5) {
+      R1 = X
+      G1 = 0
+      B1 = C
+    } else if (H_ >= 5 && H_ < 6) {
+      R1 = C
+      G1 = 0
+      B1 = X
+    }
+  }
+
+  const m = L - C / 2
+  const R = (R1 + m) * 255
+  const G = (G1 + m) * 255
+  const B = (B1 + m) * 255
+
+  return '#' + pad(R) + pad(G) + pad(B)
+}
+
+export interface ColorEntry {
+  index: number
+  rgb: string
+}
+
+function buildPalette(): ColorEntry[] {
+  const colors: ColorEntry[] = []
+  let index = 0
+
+  colors.push({ index: index++, rgb: hsl2rgb(0, 0, 0.8) })
+  for (let i = 0; i < 19; i++) {
+    colors.push({ index: index++, rgb: hsl2rgb(i * 360 / 19, 0.6, 0.8) })
+  }
+
+  colors.push({ index: index++, rgb: hsl2rgb(0, 0, 0.5) })
+  for (let i = 0; i < 19; i++) {
+    colors.push({ index: index++, rgb: hsl2rgb(i * 360 / 19, 0.7, 0.5) })
+  }
+
+  colors.push({ index: index++, rgb: hsl2rgb(0, 0, 0.3) })
+  for (let i = 0; i < 19; i++) {
+    colors.push({ index: index++, rgb: hsl2rgb(i * 360 / 19, 0.4, 0.3) })
+  }
+
+  colors.push({ index: index++, rgb: hsl2rgb(0, 0, 0.1) })
+  for (let i = 0; i < 19; i++) {
+    colors.push({ index: index++, rgb: hsl2rgb(i * 360 / 19, 0.5, 0.1) })
+  }
+
+  return colors
+}
+
+export const BadgeColors = buildPalette()

package/src/badge/generateSvg.ts

@@ -0,0 +1,70 @@
+import type { Badge } from '../types/game.js'
+import { BadgePaths } from './paths.js'
+import { BadgeColors } from './colors.js'
+
+function resolveColor(value: string | number | undefined): string {
+  if (typeof value === 'string') return value
+  if (typeof value === 'number') {
+    const entry = BadgeColors[value]
+    return entry ? entry.rgb : '#000000'
+  }
+  return '#000000'
+}
+
+export function badgeToSvg(badge: Badge): string {
+  const color1 = resolveColor(badge.color1)
+  const color2 = resolveColor(badge.color2)
+  const color3 = resolveColor(badge.color3)
+
+  const param = badge.param ?? 0
+
+  if (typeof badge.type === 'number') {
+    const def = BadgePaths[badge.type]
+    if (def) {
+      def.calc(param)
+    }
+  }
+
+  let rotate = 0
+  if (badge.flip && typeof badge.type === 'number') {
+    const def = BadgePaths[badge.type]
+    if (def?.flip === 'rotate180') rotate = 180
+    if (def?.flip === 'rotate90') rotate = 90
+    if (def?.flip === 'rotate45') rotate = 45
+  }
+
+  let path1: string
+  let path2: string
+
+  if (typeof badge.type === 'number') {
+    const def = BadgePaths[badge.type]
+    path1 = def?.path1 ?? ''
+    path2 = def?.path2 ?? ''
+  } else {
+    path1 = badge.type.path1
+    path2 = badge.type.path2
+  }
+
+  // Clip exactly at the visible circle edge (matches the black border stroke).
+  const clipRadius = 50
+
+  let svg = `<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 100 100" shape-rendering="geometricPrecision">`
+  svg += `<defs><clipPath id="clip"><circle cx="50" cy="50" r="${clipRadius}"/></clipPath></defs>`
+  svg += `<g transform="rotate(${rotate} 50 50)">`
+  svg += `<rect x="0" y="0" width="100" height="100" fill="${color1}" clip-path="url(#clip)"/>`
+
+  if (path1) {
+    svg += `<path d="${path1}" fill="${color2}" clip-path="url(#clip)"/>`
+  }
+
+  if (path2) {
+    svg += `<path d="${path2}" fill="${color3}" clip-path="url(#clip)"/>`
+  }
+
+  // Black circular border
+  svg += `<circle cx="50" cy="50" r="47.5" fill="transparent" stroke="#000" stroke-width="5"/>`
+
+  svg += `</g></svg>`
+
+  return svg
+}

package/src/badge/index.ts

@@ -0,0 +1 @@
+export { badgeToSvg } from './generateSvg.js'