screeps-connectivity 0.2.0

package/src/http/fetchServerVersion.ts

@@ -0,0 +1,151 @@
+import type { ServerVersion } from '../types/game.js'
+import type { ScreepsmodAuthFeature, ServerFeature } from '../types/game.js'
+import type { ApiAuthModInfoResponse, ApiRegisterCheckResponse } from '../types/api.js'
+
+export type { ApiAuthModInfoResponse }
+
+const SESSION_CACHE_TTL_MS = 5 * 60_000
+
+interface CachedEntry<T> {
+  data: T
+  expires: number
+}
+
+function sessionKey(suffix: string, url: string): string {
+  try {
+    return `screeps:${suffix}:${new URL(url).hostname}`
+  } catch {
+    return `screeps:${suffix}:${url}`
+  }
+}
+
+function readFromSession<T>(key: string): T | null {
+  if (typeof sessionStorage === 'undefined') return null
+  try {
+    const raw = sessionStorage.getItem(key)
+    if (!raw) return null
+    const entry = JSON.parse(raw) as CachedEntry<T>
+    if (Date.now() > entry.expires) {
+      sessionStorage.removeItem(key)
+      return null
+    }
+    return entry.data
+  } catch {
+    return null
+  }
+}
+
+function writeToSession<T>(key: string, data: T): void {
+  if (typeof sessionStorage === 'undefined') return
+  try {
+    sessionStorage.setItem(key, JSON.stringify({ data, expires: Date.now() + SESSION_CACHE_TTL_MS }))
+  } catch { /* quota exceeded or SSR — ignore */ }
+}
+
+function baseUrl(url: string): string {
+  return url.endsWith('/') ? url : `${url}/`
+}
+
+/**
+ * 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 fetch(`${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
+}
+
+/**
+ * Fetch screepsmod-auth capabilities from `/api/authmod` without authentication.
+ * Returns `null` if the server does not run screepsmod-auth.
+ * The result is cached in `sessionStorage` for 5 minutes (per server hostname).
+ */
+export async function fetchAuthModInfo(url: string): Promise<ApiAuthModInfoResponse | null> {
+  const key = sessionKey('authmod', url)
+  const cached = readFromSession<ApiAuthModInfoResponse>(key)
+  if (cached) return cached
+
+  const res = await fetch(`${baseUrl(url)}api/authmod`)
+  if (!res.ok) return null
+  const data = await res.json() as ApiAuthModInfoResponse
+  if (!data.ok) return null
+  writeToSession(key, data)
+  return data
+}
+
+/**
+ * Check whether a username is available on a screepsmod-auth server.
+ * Returns `{ ok: 1 }` if available, `{ ok: 0, error: 'User Exists' }` if taken.
+ */
+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}`)
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  return res.json() as Promise<ApiRegisterCheckResponse>
+}
+
+/**
+ * Check whether an email address is available on a screepsmod-auth server.
+ * Returns `{ ok: 1 }` if available, `{ ok: 0, error: 'User Exists' }` if taken.
+ */
+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}`)
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  return res.json() as Promise<ApiRegisterCheckResponse>
+}
+
+/**
+ * Register a new user account on a screepsmod-auth private server.
+ * No authentication required. Throws if the server returns an error response.
+ */
+export async function registerUser(
+  url: string,
+  username: string,
+  email: string,
+  password: string,
+): Promise<{ ok: number; error?: string }> {
+  const res = await fetch(`${baseUrl(url)}api/register/submit`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ username, email, password }),
+  })
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  return res.json() as Promise<{ ok: number; error?: string }>
+}
+
+/**
+ * Extract a specific feature entry from a `ServerVersion` response by name.
+ * Returns `undefined` if the feature is not present.
+ *
+ * @example
+ * const authMod = getServerFeature<ScreepsmodAuthFeature>(version, 'screepsmod-auth')
+ * if (authMod) console.log('Auth types:', authMod.authTypes)
+ */
+export function getServerFeature<T extends ServerFeature = ServerFeature>(
+  version: ServerVersion,
+  name: string,
+): T | undefined {
+  return version.serverData.features.find(f => f.name === name) as T | undefined
+}
+
+/**
+ * Returns the `screepsmod-auth` feature entry if present, otherwise `undefined`.
+ * Use this to check whether the server supports password login, registration,
+ * Steam auth, etc., before showing those UI options.
+ *
+ * @example
+ * const auth = getScreepsmodAuth(version)
+ * if (auth?.authTypes.includes('password')) showPasswordForm()
+ */
+export function getScreepsmodAuth(version: ServerVersion): ScreepsmodAuthFeature | undefined {
+  return getServerFeature<ScreepsmodAuthFeature>(version, 'screepsmod-auth')
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+export { ScreepsClient } from './ScreepsClient.js'
+export type { ScreepsClientOptions } from './ScreepsClient.js'
+
+export { Logger } from './logger.js'
+export type { LogFn } from './logger.js'
+
+export { TokenAuth } from './http/auth/TokenAuth.js'
+export { PasswordAuth } from './http/auth/PasswordAuth.js'
+export { GuestAuth } from './http/auth/GuestAuth.js'
+export { SteamTicketAuth } from './http/auth/SteamTicketAuth.js'
+export type { AuthStrategy } from './http/auth/AuthStrategy.js'
+
+export { IndexedDBStorage } from './storage/IndexedDBStorage.js'
+export { NullStorage } from './storage/NullStorage.js'
+export type { StorageAdapter } from './storage/StorageAdapter.js'
+
+export { SubscriptionGroup } from './subscription/index.js'
+export type { Subscription } from './subscription/index.js'
+
+export { TerrainType, RoomTerrain } from './types/game.js'
+export type {
+  RoomObject,
+  RoomObjectMap,
+  RoomObjectDiff,
+  RoomMap2Data,
+  UserInfo,
+  CpuStats,
+  WorldStatus,
+  ConsoleMessage,
+  ServerVersion,
+  ServerFeature,
+  ScreepsmodAuthFeature,
+  ShardInfo,
+  WorldInfo,
+  Badge,
+  VisualStyle,
+  RoomVisualEntry,
+} from './types/game.js'
+
+export { fetchServerVersion, fetchAuthModInfo, checkUsername, checkEmail, registerUser, getServerFeature, getScreepsmodAuth } from './http/fetchServerVersion.js'
+export type { ApiAuthModInfoResponse } from './http/fetchServerVersion.js'
+
+export { badgeToSvg } from './badge/index.js'
+export type { RoomStoreEvents, UserStoreEvents, ServerStoreEvents, MapStoreEvents, Map2SubscriptionStatus, HttpClientEvents } from './types/events.js'
+
+export type { UserMessagesEndpoints } from './http/endpoints/user-messages.js'
+export type { PowerCreepsEndpoints } from './http/endpoints/power-creeps.js'
+export type { RegisterEndpoints } from './http/endpoints/register.js'
+export type { HttpClient, RateLimitInfo } from './http/HttpClient.js'
+export type { SocketClient } from './socket/SocketClient.js'
+export type { RoomStore } from './stores/RoomStore.js'
+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'

package/src/logger.ts

@@ -0,0 +1,25 @@
+export type LogFn = (...args: unknown[]) => void
+
+export class Logger {
+  private readonly fn: LogFn | null
+
+  private constructor(fn: LogFn | null) {
+    this.fn = fn
+  }
+
+  static create(debug?: boolean | LogFn): Logger {
+    if (debug === true) return new Logger(console.debug.bind(console))
+    if (typeof debug === 'function') return new Logger(debug)
+    return new Logger(null)
+  }
+
+  child(namespace: string): Logger {
+    if (!this.fn) return this
+    const parent = this.fn
+    return new Logger((...args: unknown[]) => parent(`[screeps:${namespace}]`, ...args))
+  }
+
+  log(...args: unknown[]): void {
+    this.fn?.(...args)
+  }
+}

package/src/socket/MessageParser.ts

@@ -0,0 +1,44 @@
+import { decompressZlib } from '../http/decompress.js'
+
+export type ServerCommand =
+  | { type: 'auth'; status: 'ok' | 'failed'; token: string | undefined }
+  | { type: 'time'; time: number }
+  | { type: 'protocol'; protocol: number }
+  | { type: 'package'; package: number }
+
+export interface ChannelMessage {
+  channel: string
+  data: unknown
+}
+
+export type ParsedMessage =
+  | { kind: 'server'; command: ServerCommand }
+  | { kind: 'channel'; message: ChannelMessage }
+
+export async function parseMessage(raw: string | MessageEvent): Promise<ParsedMessage> {
+  let msg = typeof raw === 'string' ? raw : (raw.data as string)
+
+  if (msg.startsWith('gz:')) {
+    msg = JSON.stringify(await decompressZlib(msg))
+  }
+
+  if (msg.startsWith('[')) {
+    const [channel, data] = JSON.parse(msg) as [string, unknown]
+    return { kind: 'channel', message: { channel, data } }
+  }
+
+  const [cmd, ...rest] = msg.split(' ')
+
+  switch (cmd) {
+    case 'auth':
+      return { kind: 'server', command: { type: 'auth', status: rest[0] as 'ok' | 'failed', token: rest[1] } }
+    case 'time':
+      return { kind: 'server', command: { type: 'time', time: parseInt(rest[0], 10) } }
+    case 'protocol':
+      return { kind: 'server', command: { type: 'protocol', protocol: parseInt(rest[0], 10) } }
+    case 'package':
+      return { kind: 'server', command: { type: 'package', package: parseInt(rest[0], 10) } }
+    default:
+      throw new Error(`Unknown server command: ${cmd}`)
+  }
+}

package/src/socket/SocketClient.ts

@@ -0,0 +1,203 @@
+import { parseMessage } from './MessageParser.js'
+import { Logger } from '../logger.js'
+import type { Subscription } from '../subscription/index.js'
+
+type WsConstructor = typeof globalThis.WebSocket
+
+export class SocketClient {
+  private readonly wsUrl: string
+  private readonly WS: WsConstructor
+  private readonly logger: Logger
+  private ws: WebSocket | null = null
+  private token: string | null = null
+  private authed = false
+  private _connected = false
+  private reconnecting = false
+  private authSub: Subscription | null = null
+  private readonly queue: string[] = []
+  private readonly subs = new Map<string, number>()
+  private readonly listeners = new Map<string, Set<(data: unknown) => void>>()
+
+  private readonly MAX_RETRIES = 10
+  private readonly MAX_DELAY_MS = 60_000
+  private _intentionalClose = false
+
+  constructor(opts: { url: string; WebSocket?: WsConstructor; logger?: Logger }) {
+    const base = opts.url.replace(/^http/, 'ws').replace(/\/$/, '')
+    this.wsUrl = `${base}/socket/websocket`
+    this.WS = opts.WebSocket ?? globalThis.WebSocket
+    this.logger = opts.logger ?? Logger.create()
+  }
+
+  get isConnected(): boolean {
+    return this._connected
+  }
+
+  /** Update the stored token. Used to keep WS and HTTP token in sync after an HTTP rotation. */
+  setToken(token: string): void {
+    this.token = token
+  }
+
+  connect(token: string): Promise<void> {
+    this.logger.log('connect', this.wsUrl)
+    // Note: do NOT reset _intentionalClose here. If disconnect() ran while a
+    // reconnect attempt was awaiting this connect(), resetting the flag would
+    // silently re-open the socket the user already asked to close. The flag
+    // is only cleared on an explicit external connect (see below).
+    if (!this.reconnecting) this._intentionalClose = false
+    this.token = token
+    this.authSub?.dispose()
+    this.authSub = null
+    return new Promise((resolve, reject) => {
+      this.ws = new this.WS(this.wsUrl) as WebSocket
+      this.ws.onopen = () => {
+        this.logger.log('WebSocket opened')
+        this._connected = true
+        this.reconnecting = false
+        this.rawSend(`auth ${this.token}`)
+        this.authSub = this.once('auth', (data) => {
+          const cmd = data as { status: string; token?: string }
+          if (cmd.status === 'ok') {
+            this.logger.log('auth ok')
+            this.authed = true
+            if (cmd.token) {
+              this.token = cmd.token
+              this.emit('socket:tokenRefresh', { token: cmd.token })
+            }
+            while (this.queue.length) this.rawSend(this.queue.shift()!)
+            this.emit('connected', {})
+            resolve()
+          } else {
+            this.logger.log('auth failed')
+            reject(new Error('WebSocket auth failed'))
+          }
+        })
+      }
+      this.ws.onclose = () => {
+        this.logger.log('WebSocket closed')
+        this._connected = false
+        this.authed = false
+        this.authSub?.dispose()
+        this.authSub = null
+        this.emit('disconnected', { willReconnect: this.reconnecting })
+        void this.scheduleReconnect()
+      }
+      this.ws.onerror = (err) => {
+        if (!this._connected) reject(err)
+      }
+      this.ws.onmessage = (event) => {
+        this.handleMessage(event).catch(err => {
+          this.logger.log('message parse error', err)
+          this.emit('socket:error', err instanceof Error ? err : new Error(String(err)))
+        })
+      }
+    })
+  }
+
+  disconnect(): void {
+    this.logger.log('disconnect')
+    this._intentionalClose = true
+    this.reconnecting = false
+    this.ws?.close()
+    this.ws = null
+    this._connected = false
+    this.authed = false
+    this.queue.length = 0
+  }
+
+  private activeSubs(): string {
+    return Array.from(this.subs.entries())
+      .map(([ch, count]) => `${ch}(${count})`)
+      .join(', ') || '(none)'
+  }
+
+  subscribe(channel: string): Subscription {
+    const count = this.subs.get(channel) ?? 0
+    this.subs.set(channel, count + 1)
+    if (count === 0) {
+      this.logger.log('subscribe', channel, 'active:', this.activeSubs())
+      this.sendOrQueue(`subscribe ${channel}`)
+    } else {
+      this.logger.log('subscribe', channel, `(refs: ${count + 1})`, 'active:', this.activeSubs())
+    }
+    return { dispose: () => this.doUnsubscribe(channel) }
+  }
+
+  on(channel: string, cb: (data: unknown) => void): Subscription {
+    let set = this.listeners.get(channel)
+    if (!set) { set = new Set(); this.listeners.set(channel, set) }
+    set.add(cb)
+    return { dispose: () => { this.listeners.get(channel)?.delete(cb) } }
+  }
+
+  private once(channel: string, cb: (data: unknown) => void): Subscription {
+    const sub = this.on(channel, (data) => { sub.dispose(); cb(data) })
+    return sub
+  }
+
+  private doUnsubscribe(channel: string): void {
+    const count = this.subs.get(channel) ?? 0
+    if (count <= 1) {
+      this.subs.delete(channel)
+      if (this.authed) this.rawSend(`unsubscribe ${channel}`)
+      this.logger.log('unsubscribe', channel, 'active:', this.activeSubs())
+    } else {
+      this.subs.set(channel, count - 1)
+      this.logger.log('unsubscribe', channel, `(refs: ${count - 1})`, 'active:', this.activeSubs())
+    }
+  }
+
+  private rawSend(data: string): void {
+    this.ws?.send(data)
+  }
+
+  private sendOrQueue(data: string): void {
+    if (this.authed) this.rawSend(data)
+    else this.queue.push(data)
+  }
+
+  private emit(channel: string, data: unknown): void {
+    this.listeners.get(channel)?.forEach(cb => cb(data))
+  }
+
+  private async handleMessage(event: MessageEvent): Promise<void> {
+    const parsed = await parseMessage(event)
+    if (parsed.kind === 'server') {
+      this.emit(parsed.command.type, parsed.command)
+    } else {
+      this.emit(parsed.message.channel, parsed.message.data)
+    }
+  }
+
+  private async scheduleReconnect(): Promise<void> {
+    if (this.reconnecting || this._intentionalClose) return
+    if (!this.token) { this.reconnecting = false; return }
+    this.reconnecting = true
+    let retries = 0
+    while (retries < this.MAX_RETRIES && this.reconnecting && !this._intentionalClose) {
+      const delay = Math.min(Math.pow(2, retries) * 100, this.MAX_DELAY_MS)
+      this.logger.log(`reconnect attempt ${retries + 1}/${this.MAX_RETRIES} in ${delay}ms`)
+      await new Promise(r => setTimeout(r, delay))
+      if (!this.reconnecting || this._intentionalClose) return
+      try {
+        await this.connect(this.token!)
+        // disconnect() may have run while connect() was in flight — honor it
+        if (this._intentionalClose) {
+          this.ws?.close()
+          this.ws = null
+          return
+        }
+        for (const channel of this.subs.keys()) {
+          this.rawSend(`subscribe ${channel}`)
+        }
+        return
+      } catch {
+        retries++
+      }
+    }
+    this.reconnecting = false
+    if (retries >= this.MAX_RETRIES && !this._intentionalClose) {
+      this.emit('socket:error', new Error(`WebSocket reconnection failed after ${this.MAX_RETRIES} retries`))
+    }
+  }
+}

package/src/storage/FileStorage.ts

@@ -0,0 +1,44 @@
+import { mkdir, readFile, writeFile, unlink, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { StorageAdapter } from './StorageAdapter.js'
+
+export class FileStorage implements StorageAdapter {
+  private readonly dir: string
+
+  constructor(baseDir: string, namespace: string) {
+    const sanitized = namespace.replace(/[^a-zA-Z0-9.-]/g, '_')
+    this.dir = join(baseDir, sanitized)
+  }
+
+  private keyPath(key: string): string {
+    const hex = Buffer.from(key).toString('hex')
+    return join(this.dir, `${hex}.bin`)
+  }
+
+  async get(key: string): Promise<Uint8Array | null> {
+    try {
+      const buf = await readFile(this.keyPath(key))
+      return new Uint8Array(buf)
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
+      throw err
+    }
+  }
+
+  async set(key: string, data: Uint8Array): Promise<void> {
+    await mkdir(this.dir, { recursive: true })
+    await writeFile(this.keyPath(key), data)
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      await unlink(this.keyPath(key))
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+    }
+  }
+
+  async clear(): Promise<void> {
+    await rm(this.dir, { recursive: true, force: true })
+  }
+}

package/src/storage/IndexedDBStorage.ts

@@ -0,0 +1,77 @@
+import type { StorageAdapter } from './StorageAdapter.js'
+
+const DB_VERSION = 1
+const STORE_NAME = 'data'
+
+export class IndexedDBStorage implements StorageAdapter {
+  private readonly namespace: string
+  private db: IDBDatabase | null = null
+  private openPromise: Promise<IDBDatabase> | null = null
+
+  constructor(namespace: string) {
+    this.namespace = namespace
+  }
+
+  private get dbName(): string {
+    return `screeps:${this.namespace}`
+  }
+
+  private open(): Promise<IDBDatabase> {
+    if (this.db) return Promise.resolve(this.db)
+    if (this.openPromise) return this.openPromise
+    this.openPromise = new Promise((resolve, reject) => {
+      const req = indexedDB.open(this.dbName, DB_VERSION)
+      req.onupgradeneeded = () => {
+        req.result.createObjectStore(STORE_NAME)
+      }
+      req.onsuccess = () => {
+        this.db = req.result
+        this.openPromise = null
+        resolve(req.result)
+      }
+      req.onerror = () => reject(req.error)
+      req.onblocked = () => reject(new Error(`IndexedDB open blocked: ${this.dbName}`))
+    })
+    return this.openPromise
+  }
+
+  async get(key: string): Promise<Uint8Array | null> {
+    const db = await this.open()
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readonly')
+      const req = tx.objectStore(STORE_NAME).get(key)
+      req.onsuccess = () => resolve((req.result as Uint8Array | undefined) ?? null)
+      req.onerror = () => reject(req.error)
+    })
+  }
+
+  async set(key: string, data: Uint8Array): Promise<void> {
+    const db = await this.open()
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readwrite')
+      const req = tx.objectStore(STORE_NAME).put(data, key)
+      req.onsuccess = () => resolve()
+      req.onerror = () => reject(req.error)
+    })
+  }
+
+  async delete(key: string): Promise<void> {
+    const db = await this.open()
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readwrite')
+      const req = tx.objectStore(STORE_NAME).delete(key)
+      req.onsuccess = () => resolve()
+      req.onerror = () => reject(req.error)
+    })
+  }
+
+  async clear(): Promise<void> {
+    const db = await this.open()
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readwrite')
+      const req = tx.objectStore(STORE_NAME).clear()
+      req.onsuccess = () => resolve()
+      req.onerror = () => reject(req.error)
+    })
+  }
+}

package/src/storage/NullStorage.ts

@@ -0,0 +1,8 @@
+import type { StorageAdapter } from './StorageAdapter.js'
+
+export class NullStorage implements StorageAdapter {
+  async get(_key: string): Promise<Uint8Array | null> { return null }
+  async set(_key: string, _data: Uint8Array): Promise<void> {}
+  async delete(_key: string): Promise<void> {}
+  async clear(): Promise<void> {}
+}

package/src/storage/StorageAdapter.ts

@@ -0,0 +1,6 @@
+export interface StorageAdapter {
+  get(key: string): Promise<Uint8Array | null>
+  set(key: string, data: Uint8Array): Promise<void>
+  delete(key: string): Promise<void>
+  clear(): Promise<void>
+}