screeps-connectivity 0.2.0

package/src/types/game.ts

@@ -0,0 +1,160 @@
+export interface RoomMap2Data {
+    w?: [number, number][] | null    // player-built walls / ramparts
+    r?: [number, number][] | null    // roads
+    pb?: [number, number][] | null   // power banks / power
+    p?: [number, number][] | null    // portals
+    s?: [number, number][] | null    // sources
+    c?: [number, number][] | null    // controllers
+    m?: [number, number][] | null    // minerals
+    k?: [number, number][] | null    // source keeper lairs
+    [userId: string]: [number, number][] | null | undefined  // structures + creeps for that user
+}
+
+export enum TerrainType {
+    Plain = 0,
+    Wall = 1,
+    Swamp = 2,
+}
+
+export class RoomTerrain {
+    readonly raw: Uint8Array
+
+    constructor(data: Uint8Array) {
+        this.raw = data
+    }
+
+    static fromEncodedString(encoded: string): RoomTerrain {
+        const data = new Uint8Array(2500)
+        for (let i = 0; i < 2500; i++) {
+            const v = parseInt(encoded[i], 10)
+            data[i] = v === 3 ? TerrainType.Wall : (v as TerrainType)
+        }
+        return new RoomTerrain(data)
+    }
+
+    get(x: number, y: number): TerrainType {
+        return this.raw[y * 50 + x] as TerrainType
+    }
+}
+
+export interface Badge {
+    type: number | { path1: string; path2: string }
+    color1: string | number
+    color2: string | number
+    color3: string | number
+    param?: number
+    flip: boolean
+}
+
+export interface RoomObject {
+    _id: string
+    type: string
+    room: string
+    x: number
+    y: number
+
+    [key: string]: unknown
+}
+
+export type RoomObjectMap = Record<string, RoomObject>
+export type RoomObjectDiff = Record<string, Partial<RoomObject> | null>
+
+export interface UserInfo {
+    _id: string
+    username: string
+    email: string
+    cpu: number
+    gcl: number
+    credits: number
+    badge: Badge
+}
+
+export interface CpuStats {
+    cpu: number
+    memory: number
+}
+
+export type WorldStatus = 'normal' | 'lost' | 'empty'
+
+
+export interface ConsoleMessage {
+    log: string[]
+    results: string[]
+    error: string[]
+}
+
+export interface ServerFeature {
+    name: string
+    version?: string | number
+}
+
+export interface ScreepsmodAuthFeature extends ServerFeature {
+    name: 'screepsmod-auth'
+    version: string
+    authTypes: Array<'password' | 'steam' | 'github' | 'gitlab' | string>
+    menuData?: Array<{
+        section: number
+        start: number
+        item: { label: string; href: string }
+    }>
+}
+
+export interface ServerVersion {
+    ok: number
+    package: number
+    protocol: number
+    useNativeAuth?: boolean
+    users: number
+    serverData: {
+        historyChunkSize: number
+        features: ServerFeature[]
+        shards: Array<string | null>
+        welcomeText?: string
+        socketUpdateThrottle?: number
+        customObjectTypes?: unknown
+        renderer?: unknown
+    }
+}
+
+export interface ShardInfo {
+    name: string
+    lastTicks: number[]
+    cpuLimit: number
+    rooms: number
+    users: number
+    tick: number
+}
+
+export interface WorldInfo {
+    shard: string | null
+    width: number
+    height: number
+    // Inclusive coordinate bounds of valid rooms.
+    // Uses the internal system where W0 = x = -1, E0 = x = 0, N0 = y = -1, S0 = y = 0.
+    minX: number
+    maxX: number
+    minY: number
+    maxY: number
+}
+
+export interface VisualStyle {
+    opacity?: number
+    fill?: string
+    stroke?: string
+    strokeWidth?: number
+    color?: string
+    backgroundColor?: string
+    backgroundPadding?: number
+    align?: 'center' | 'left' | 'right'
+    lineStyle?: 'dashed' | 'dotted' | 'solid'
+    width?: number
+    radius?: number
+    font?: string | number
+}
+
+export type RoomVisualEntry =
+    | { t: 't'; x: number; y: number; text: string; s: VisualStyle }
+    | { t: 'c'; x: number; y: number; s: VisualStyle }
+    | { t: 'r'; x: number; y: number; w: number; h: number; s: VisualStyle }
+    | { t: 'p'; points: [number, number][]; s: VisualStyle }
+    | { t: 'l'; x1: number; y1: number; x2: number; y2: number; s: VisualStyle }

package/tests/ScreepsClient.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { ScreepsClient } from '../src/ScreepsClient.js'
+import { TokenAuth } from '../src/http/auth/TokenAuth.js'
+
+class MockWS {
+  static instances: MockWS[] = []
+  onopen: (() => void) | null = null
+  onclose: (() => void) | null = null
+  onerror: ((e: unknown) => void) | null = null
+  onmessage: ((e: MessageEvent) => void) | null = null
+  sent: string[] = []
+  constructor() { MockWS.instances.push(this) }
+  send(d: string) { this.sent.push(d) }
+  close() {}
+  simulateOpen() { this.onopen?.() }
+  simulateMessage(d: string) { this.onmessage?.({ data: d } as MessageEvent) }
+}
+
+beforeEach(() => {
+  MockWS.instances = []
+  vi.stubGlobal('fetch', vi.fn().mockImplementation((url: string) => {
+    const path = new URL(url).pathname
+
+    if (path === '/api/user/world-status') {
+      return Promise.resolve(
+        new Response(JSON.stringify({ ok: 1, status: 'normal' }), {
+          headers: { 'content-type': 'application/json' },
+        })
+      )
+    }
+
+    return Promise.resolve(
+      new Response(JSON.stringify({ ok: 1, token: 'authed', _id: 'uid1', username: 'user', serverData: { features: [], shards: [] } }), {
+        headers: { 'content-type': 'application/json' },
+      })
+    )
+  }))
+})
+afterEach(() => { vi.unstubAllGlobals() })
+
+describe('ScreepsClient', () => {
+  it('exposes http, socket, and stores properties', () => {
+    const client = new ScreepsClient({
+      url: 'http://test.local',
+      auth: new TokenAuth({ token: 'tok' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+    })
+    expect(client.http).toBeDefined()
+    expect(client.socket).toBeDefined()
+    expect(client.stores.room).toBeDefined()
+    expect(client.stores.user).toBeDefined()
+    expect(client.stores.server).toBeDefined()
+    expect(client.stores.map).toBeDefined()
+  })
+
+  it('connect() authenticates then opens WebSocket', async () => {
+    const client = new ScreepsClient({
+      url: 'http://test.local',
+      auth: new TokenAuth({ token: 'tok' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+    })
+    const connectPromise = client.connect()
+    await new Promise(r => setTimeout(r, 0))
+    const ws = MockWS.instances[0]
+    ws.simulateOpen()
+    ws.simulateMessage('auth ok tok')
+    await connectPromise
+    expect(client.isConnected).toBe(true)
+  })
+
+  it('isConnected is false before connect()', () => {
+    const client = new ScreepsClient({
+      url: 'http://test.local',
+      auth: new TokenAuth({ token: 'tok' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+    })
+    expect(client.isConnected).toBe(false)
+  })
+
+  it('connect() fetches user info, world status, and server version', async () => {
+    const fetchMock = fetch as unknown as ReturnType<typeof vi.fn>
+    const client = new ScreepsClient({
+      url: 'http://test.local',
+      auth: new TokenAuth({ token: 'tok' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+    })
+
+    const connectPromise = client.connect()
+    await new Promise(r => setTimeout(r, 0))
+    const ws = MockWS.instances[0]
+    ws.simulateOpen()
+    ws.simulateMessage('auth ok tok')
+    await connectPromise
+
+    const paths = fetchMock.mock.calls.map(([url]) => new URL(url as string).pathname)
+    expect(paths).toContain('/api/auth/me')
+    expect(paths).toContain('/api/user/world-status')
+    expect(paths).toContain('/api/version')
+    expect(client.stores.user.worldStatusValue).toBe('normal')
+  })
+})
+
+describe('ScreepsClient — token sync', () => {
+  it('rotates SocketClient token when an HTTP response carries x-token', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ ok: 1 }), {
+        headers: { 'content-type': 'application/json', 'x-token': 'http-rotated-token' },
+      })
+    ))
+
+    const client = new ScreepsClient({
+      url: 'http://test.local',
+      auth: new TokenAuth({ token: 'initial' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+      tokenRefresh: false,
+    })
+
+    const socketSetToken = vi.spyOn(client.socket, 'setToken')
+    await client.http.request('GET', '/api/auth/me')
+
+    expect(socketSetToken).toHaveBeenCalledWith('http-rotated-token')
+  })
+
+  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' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+      tokenRefresh: false,
+    })
+
+    const httpSetToken = vi.spyOn(client.http, 'setToken')
+
+    const connectPromise = client.connect()
+    await new Promise(r => setTimeout(r, 0))
+    const ws = MockWS.instances[0]
+    ws.simulateOpen()
+    ws.simulateMessage('auth ok ws-rotated-token')
+    await connectPromise
+
+    expect(httpSetToken).toHaveBeenCalledWith('ws-rotated-token')
+    expect(client.http.token).toBe('ws-rotated-token')
+  })
+})
+
+describe('ScreepsClient — idle token refresh', () => {
+  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' }),
+      storage: null,
+      WebSocket: MockWS as unknown as typeof WebSocket,
+      tokenRefresh: opts.tokenRefresh,
+    })
+    const connectPromise = client.connect()
+    await vi.advanceTimersByTimeAsync(0)
+    const ws = MockWS.instances[0]
+    ws.simulateOpen()
+    ws.simulateMessage('auth ok tok')
+    await connectPromise
+    return client
+  }
+
+  it('issues a world-status call after intervalMs of HTTP idleness', 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)
+
+    const paths = fetchMock.mock.calls.map(([url]) => new URL(url as string).pathname)
+    expect(paths).toContain('/api/user/world-status')
+
+    client.disconnect()
+  })
+
+  it('does NOT issue an auth/me call while HTTP traffic resets the idle clock', 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++) {
+      await client.http.request('GET', '/api/version')
+      await vi.advanceTimersByTimeAsync(400)
+    }
+
+    const paths = fetchMock.mock.calls.map(([url]) => new URL(url as string).pathname)
+    expect(paths).not.toContain('/api/auth/me')
+
+    client.disconnect()
+  })
+
+  it('does not start the refresh timer when tokenRefresh is false', async () => {
+    const client = await buildConnected({ tokenRefresh: false })
+    const fetchMock = fetch as unknown as ReturnType<typeof vi.fn>
+    fetchMock.mockClear()
+
+    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')
+
+    client.disconnect()
+  })
+
+  it('stops the refresh timer on disconnect()', async () => {
+    const client = await buildConnected({ tokenRefresh: { intervalMs: 1_000 } })
+    client.disconnect()
+
+    const fetchMock = fetch as unknown as ReturnType<typeof vi.fn>
+    fetchMock.mockClear()
+
+    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')
+  })
+})

package/tests/badge/generateSvg.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect } from 'vitest'
+import { badgeToSvg } from '../../src/badge/generateSvg.js'
+import type { Badge } from '../../src/types/game.js'
+
+describe('badgeToSvg', () => {
+  it('generates an SVG for a numeric badge type', () => {
+    const badge: Badge = {
+      type: 24,
+      color1: '#000077',
+      color2: '#5555dd',
+      color3: '#9999ff',
+      param: 0,
+      flip: false,
+    }
+
+    const svg = badgeToSvg(badge)
+    expect(svg).toContain('<svg')
+    expect(svg).toContain('</svg>')
+    expect(svg).toContain('fill="#000077"')
+    expect(svg).toContain('fill="#5555dd"')
+    expect(svg).toContain('fill="#9999ff"')
+  })
+
+  it('generates an SVG for a custom path badge type', () => {
+    const badge: Badge = {
+      type: {
+        path1: 'M 0 0 L 50 100 L 100 0 Z',
+        path2: 'M 0 100 L 50 0 L 100 100 Z',
+      },
+      color1: '#ff0000',
+      color2: '#00ff00',
+      color3: '#0000ff',
+      flip: false,
+    }
+
+    const svg = badgeToSvg(badge)
+    expect(svg).toContain('d="M 0 0 L 50 100 L 100 0 Z"')
+    expect(svg).toContain('d="M 0 100 L 50 0 L 100 100 Z"')
+    expect(svg).toContain('fill="#ff0000"')
+    expect(svg).toContain('fill="#00ff00"')
+    expect(svg).toContain('fill="#0000ff"')
+  })
+
+  it('resolves numeric color indices', () => {
+    const badge: Badge = {
+      type: 1,
+      color1: 0,
+      color2: 20,
+      color3: 40,
+      param: 0,
+      flip: false,
+    }
+
+    const svg = badgeToSvg(badge)
+    expect(svg).toContain('fill="#cccccc"')
+    expect(svg).toContain('fill="#808080"')
+    expect(svg).toContain('fill="#4d4d4d"')
+  })
+
+  it('applies rotation when flip is true for badges with flip property', () => {
+    const badge: Badge = {
+      type: 3,
+      color1: '#ffffff',
+      color2: '#000000',
+      color3: '#ff0000',
+      param: 0,
+      flip: true,
+    }
+
+    const svg = badgeToSvg(badge)
+    expect(svg).toContain('rotate(180 50 50)')
+  })
+
+  it('does not rotate when flip is false', () => {
+    const badge: Badge = {
+      type: 3,
+      color1: '#ffffff',
+      color2: '#000000',
+      color3: '#ff0000',
+      param: 0,
+      flip: false,
+    }
+
+    const svg = badgeToSvg(badge)
+    expect(svg).toContain('rotate(0 50 50)')
+  })
+
+  it('always renders a black circular border and uses a generous clip radius', () => {
+    const badge: Badge = {
+      type: 1,
+      color1: '#ffffff',
+      color2: '#000000',
+      color3: '#ff0000',
+      param: 0,
+      flip: false,
+    }
+
+    const svg = badgeToSvg(badge)
+    expect(svg).toContain('stroke="#000"')
+    expect(svg).toContain('r="47.5"')
+    expect(svg).toContain('r="50"')
+  })
+
+  it('handles badges without path2', () => {
+    const badge: Badge = {
+      type: 4,
+      color1: '#ffffff',
+      color2: '#000000',
+      color3: '#ff0000',
+      param: -100,
+      flip: false,
+    }
+
+    const svg = badgeToSvg(badge)
+    // type 4 with param -100 produces empty path2
+    expect(svg).toContain('<svg')
+    expect(svg).toContain('</svg>')
+  })
+
+  it('falls back to black for missing colors', () => {
+    const badge: Badge = {
+      type: 1,
+      color1: undefined as unknown as string,
+      color2: undefined as unknown as string,
+      color3: undefined as unknown as string,
+      flip: false,
+    }
+
+    const svg = badgeToSvg(badge)
+    expect(svg).toContain('fill="#000000"')
+  })
+
+  it('generates all 24 badge types without throwing', () => {
+    for (let type = 1; type <= 24; type++) {
+      const badge: Badge = {
+        type,
+        color1: '#111111',
+        color2: '#222222',
+        color3: '#333333',
+        param: 0,
+        flip: false,
+      }
+      expect(() => badgeToSvg(badge)).not.toThrow()
+    }
+  })
+
+  it('generates all 24 badge types with param=-100 without throwing', () => {
+    for (let type = 1; type <= 24; type++) {
+      const badge: Badge = {
+        type,
+        color1: '#111111',
+        color2: '#222222',
+        color3: '#333333',
+        param: -100,
+        flip: false,
+      }
+      expect(() => badgeToSvg(badge)).not.toThrow()
+    }
+  })
+
+  it('generates all 24 badge types with param=100 without throwing', () => {
+    for (let type = 1; type <= 24; type++) {
+      const badge: Badge = {
+        type,
+        color1: '#111111',
+        color2: '#222222',
+        color3: '#333333',
+        param: 100,
+        flip: false,
+      }
+      expect(() => badgeToSvg(badge)).not.toThrow()
+    }
+  })
+})

package/tests/cache/Cache.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from 'vitest'
+import { Cache } from '../../src/cache/Cache.js'
+import { NullStorage } from '../../src/storage/NullStorage.js'
+
+describe('Cache — memory tier', () => {
+  it('stores and retrieves a value', () => {
+    const cache = new Cache('ns', null)
+    cache.set('key', { x: 1 })
+    expect(cache.get('key')).toEqual({ x: 1 })
+  })
+
+  it('returns undefined for missing key', () => {
+    const cache = new Cache('ns', null)
+    expect(cache.get('missing')).toBeUndefined()
+  })
+
+  it('expires entries after TTL', async () => {
+    const cache = new Cache('ns', null)
+    cache.set('key', 'val', 1)
+    await new Promise(r => setTimeout(r, 10))
+    expect(cache.get('key')).toBeUndefined()
+  })
+
+  it('does not expire entries without TTL', async () => {
+    const cache = new Cache('ns', null)
+    cache.set('key', 'val')
+    await new Promise(r => setTimeout(r, 10))
+    expect(cache.get('key')).toBe('val')
+  })
+
+  it('namespaces are isolated', () => {
+    const c1 = new Cache('ns1', null)
+    const c2 = new Cache('ns2', null)
+    c1.set('key', 'from-ns1')
+    expect(c2.get('key')).toBeUndefined()
+  })
+
+  it('delete removes entry', () => {
+    const cache = new Cache('ns', null)
+    cache.set('key', 'val')
+    cache.delete('key')
+    expect(cache.get('key')).toBeUndefined()
+  })
+})
+
+describe('Cache — persistent tier', () => {
+  it('delegates getPersistent with namespaced key', async () => {
+    const storage = new NullStorage()
+    const spy = vi.spyOn(storage, 'get').mockResolvedValue(null)
+    const cache = new Cache('myns', storage)
+    await cache.getPersistent('terrain/W7N7')
+    expect(spy).toHaveBeenCalledWith('myns/terrain/W7N7')
+  })
+
+  it('delegates setPersistent with namespaced key', async () => {
+    const storage = new NullStorage()
+    const spy = vi.spyOn(storage, 'set').mockResolvedValue()
+    const cache = new Cache('myns', storage)
+    const data = new Uint8Array([1, 2, 3])
+    await cache.setPersistent('terrain/W7N7', data)
+    expect(spy).toHaveBeenCalledWith('myns/terrain/W7N7', data)
+  })
+
+  it('returns null when storage is null', async () => {
+    const cache = new Cache('ns', null)
+    expect(await cache.getPersistent('key')).toBeNull()
+  })
+
+  it('setPersistent is a no-op when storage is null', async () => {
+    const cache = new Cache('ns', null)
+    await expect(cache.setPersistent('key', new Uint8Array([1]))).resolves.toBeUndefined()
+  })
+
+  it('deletePersistent delegates to adapter', async () => {
+    const adapter = new NullStorage()
+    const spy = vi.spyOn(adapter, 'delete').mockResolvedValue(undefined)
+    const cache = new Cache('myns', adapter)
+    await cache.deletePersistent('terrain/W7N7')
+    expect(spy).toHaveBeenCalledWith('myns/terrain/W7N7')
+  })
+
+  it('clearPersistent delegates to adapter', async () => {
+    const adapter = new NullStorage()
+    const spy = vi.spyOn(adapter, 'clear').mockResolvedValue(undefined)
+    const cache = new Cache('myns', adapter)
+    await cache.clearPersistent()
+    expect(spy).toHaveBeenCalledOnce()
+  })
+
+  it('deletePersistent is a no-op when storage is null', async () => {
+    const cache = new Cache('myns', null)
+    await expect(cache.deletePersistent('key')).resolves.toBeUndefined()
+  })
+
+  it('clearPersistent is a no-op when storage is null', async () => {
+    const cache = new Cache('myns', null)
+    await expect(cache.clearPersistent()).resolves.toBeUndefined()
+  })
+})