screeps-connectivity 0.2.0

package/src/http/HttpClient.ts

@@ -0,0 +1,160 @@
+import { decompressGzip } from './decompress.js'
+import { Logger } from '../logger.js'
+import type { AuthStrategy } from './auth/AuthStrategy.js'
+import { createAuthEndpoints, type AuthEndpoints } from './endpoints/auth.js'
+import { createGameEndpoints, type GameEndpoints } from './endpoints/game.js'
+import { createUserEndpoints, type UserEndpoints } from './endpoints/user.js'
+import { createLeaderboardEndpoints, type LeaderboardEndpoints } from './endpoints/leaderboard.js'
+import { createExperimentalEndpoints, type ExperimentalEndpoints } from './endpoints/experimental.js'
+import { createRegisterEndpoints, type RegisterEndpoints } from './endpoints/register.js'
+import type { HttpClientEvents } from '../types/events.js'
+import type { Subscription } from '../subscription/index.js'
+
+export interface RateLimitInfo {
+  limit: number
+  remaining: number
+  reset: number
+}
+
+export class HttpClient extends EventTarget {
+  readonly baseUrl: string
+  private readonly authStrategy: AuthStrategy
+  private readonly logger: Logger
+  private readonly serverPassword: string | null
+  token: string | null = null
+  readonly rateLimits = new Map<string, RateLimitInfo>()
+  private authenticating = false
+
+  readonly auth: AuthEndpoints
+  readonly register: RegisterEndpoints
+  readonly game: GameEndpoints
+  readonly user: UserEndpoints
+  readonly leaderboard: LeaderboardEndpoints
+  readonly experimental: ExperimentalEndpoints
+
+  constructor(opts: { url: string; auth: AuthStrategy; logger?: Logger; serverPassword?: string }) {
+    super()
+    this.baseUrl = opts.url.endsWith('/') ? opts.url : `${opts.url}/`
+    this.authStrategy = opts.auth
+    this.logger = opts.logger ?? Logger.create()
+    this.serverPassword = opts.serverPassword ?? null
+    this.auth = createAuthEndpoints(this)
+    this.register = createRegisterEndpoints(this)
+    this.game = createGameEndpoints(this)
+    this.user = createUserEndpoints(this)
+    this.leaderboard = createLeaderboardEndpoints(this)
+    this.experimental = createExperimentalEndpoints(this)
+  }
+
+  emit<K extends string & keyof HttpClientEvents>(type: K, detail: HttpClientEvents[K]): void {
+    this.dispatchEvent(new CustomEvent(type, { detail }))
+  }
+
+  on<K extends string & keyof HttpClientEvents>(
+    type: K,
+    handler: (detail: HttpClientEvents[K]) => void,
+  ): Subscription {
+    const listener = (e: Event) => handler((e as CustomEvent<HttpClientEvents[K]>).detail)
+    this.addEventListener(type, listener)
+    return {
+      dispose: () => {
+        this.removeEventListener(type, listener)
+      },
+    }
+  }
+
+  async authenticate(): Promise<void> {
+    this.logger.log('authenticate')
+    this.authenticating = true
+    try {
+      this.token = await this.authStrategy.authenticate(this)
+      this.logger.log('authenticated')
+    } finally {
+      this.authenticating = false
+    }
+  }
+
+  /** Update the stored token. Used to keep HTTP and WS token in sync after a WS auth rotation. */
+  setToken(token: string): void {
+    this.token = token
+  }
+
+  async request<T>(method: string, path: string, body?: Record<string, unknown>, isRetry = false): Promise<T> {
+    this.logger.log(method, path)
+    const url = new URL(path.startsWith('/') ? path.slice(1) : path, this.baseUrl)
+    const headers: Record<string, string> = {}
+
+    if (this.token) {
+      headers['X-Token'] = this.token
+      // passport-token strategy requires both x-token and x-username to be present.
+      // The server ignores the username value but fails auth if the header is missing.
+      headers['X-Username'] = this.token
+    }
+    if (this.serverPassword) {
+      headers['X-Server-Password'] = this.serverPassword
+    }
+
+    const init: RequestInit = { method, headers }
+
+    if (method === 'GET' && body) {
+      for (const [k, v] of Object.entries(body)) {
+        if (v != null) url.searchParams.set(k, String(v))
+      }
+    } else if (body) {
+      headers['Content-Type'] = 'application/json'
+      init.body = JSON.stringify(body)
+    }
+
+    const res = await fetch(url.toString(), init)
+
+    const newToken = res.headers.get('x-token')
+    if (newToken) {
+      this.token = newToken
+      this.emit('http:tokenRefresh', { token: newToken })
+    }
+
+    this.updateRateLimit(path, res)
+
+    if (res.status === 401 && !isRetry && !this.authenticating) {
+      await this.authenticate()
+      return this.request<T>(method, path, body, true)
+    }
+
+    if (!res.ok) {
+      let body = ''
+      try { body = await res.text() } catch { /* ignore */ }
+      const error = new Error(`HTTP ${res.status}: ${body}`)
+      this.emit('http:error', { method, path, status: res.status, error })
+      throw error
+    }
+
+    this.emit('http:success', { method, path, status: res.status })
+
+    const data = await res.json() as Record<string, unknown>
+
+    if (typeof data['error'] === 'string') {
+      const error = new Error(`Screeps API error: ${data['error']}`)
+      this.emit('http:error', { method, path, status: res.status, error })
+      throw error
+    }
+
+    if (typeof data['data'] === 'string' && (data['data'] as string).startsWith('gz:')) {
+      data['data'] = await decompressGzip(data['data'] as string)
+    }
+
+    return data as T
+  }
+
+  private updateRateLimit(path: string, res: Response): void {
+    const limit = res.headers.get('x-ratelimit-limit')
+    const remaining = res.headers.get('x-ratelimit-remaining')
+    const reset = res.headers.get('x-ratelimit-reset')
+    if (limit && remaining && reset) {
+      this.rateLimits.set(path, {
+        limit: parseInt(limit, 10),
+        remaining: parseInt(remaining, 10),
+        reset: parseInt(reset, 10),
+      })
+    }
+  }
+}

package/src/http/auth/AuthStrategy.ts

@@ -0,0 +1,5 @@
+import type { HttpClient } from '../HttpClient.js'
+
+export interface AuthStrategy {
+  authenticate(http: HttpClient): Promise<string>
+}

package/src/http/auth/GuestAuth.ts

@@ -0,0 +1,13 @@
+import type { AuthStrategy } from './AuthStrategy.js'
+import type { HttpClient } from '../HttpClient.js'
+
+/**
+ * Guest authentication strategy for xxscreeps-compatible private servers.
+ * Bypasses HTTP sign-in and sends the literal token "guest" to the WebSocket,
+ * granting read-only observer access without an account.
+ */
+export class GuestAuth implements AuthStrategy {
+  async authenticate(_http: HttpClient): Promise<string> {
+    return 'guest'
+  }
+}

package/src/http/auth/PasswordAuth.ts

@@ -0,0 +1,17 @@
+import type { AuthStrategy } from './AuthStrategy.js'
+import type { HttpClient } from '../HttpClient.js'
+
+export class PasswordAuth implements AuthStrategy {
+  private readonly email: string
+  private readonly password: string
+
+  constructor(opts: { email: string; password: string }) {
+    this.email = opts.email
+    this.password = opts.password
+  }
+
+  async authenticate(http: HttpClient): Promise<string> {
+    const res = await http.auth.signin(this.email, this.password)
+    return res.token
+  }
+}

package/src/http/auth/SteamTicketAuth.ts

@@ -0,0 +1,17 @@
+import type { AuthStrategy } from './AuthStrategy.js'
+import type { HttpClient } from '../HttpClient.js'
+
+export class SteamTicketAuth implements AuthStrategy {
+  private readonly ticket: string
+  private readonly useNativeAuth: boolean | undefined
+
+  constructor(opts: { ticket: string; useNativeAuth?: boolean }) {
+    this.ticket = opts.ticket
+    this.useNativeAuth = opts.useNativeAuth
+  }
+
+  async authenticate(http: HttpClient): Promise<string> {
+    const res = await http.auth.steamTicket(this.ticket, this.useNativeAuth)
+    return res.token
+  }
+}

package/src/http/auth/TokenAuth.ts

@@ -0,0 +1,14 @@
+import type { AuthStrategy } from './AuthStrategy.js'
+import type { HttpClient } from '../HttpClient.js'
+
+export class TokenAuth implements AuthStrategy {
+  private readonly token: string
+
+  constructor(opts: { token: string }) {
+    this.token = opts.token
+  }
+
+  async authenticate(_http: HttpClient): Promise<string> {
+    return this.token
+  }
+}

package/src/http/decompress.ts

@@ -0,0 +1,37 @@
+async function decompress(data: string, format: 'gzip' | 'deflate'): Promise<unknown> {
+  const b64 = data.slice(3) // strip 'gz:' prefix
+  const binary = Uint8Array.from(atob(b64), c => c.charCodeAt(0))
+  const ds = new DecompressionStream(format)
+  const writer = ds.writable.getWriter()
+  await writer.write(binary)
+  await writer.close()
+  const reader = ds.readable.getReader()
+  const chunks: Uint8Array[] = []
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      chunks.push(value)
+    }
+  } catch (e) {
+    reader.cancel()
+    throw e
+  }
+  let totalLength = 0
+  for (const chunk of chunks) totalLength += chunk.length
+  const result = new Uint8Array(totalLength)
+  let offset = 0
+  for (const chunk of chunks) {
+    result.set(chunk, offset)
+    offset += chunk.length
+  }
+  return JSON.parse(new TextDecoder().decode(result))
+}
+
+export function decompressGzip(data: string): Promise<unknown> {
+  return decompress(data, 'gzip')
+}
+
+export function decompressZlib(data: string): Promise<unknown> {
+  return decompress(data, 'deflate')
+}

package/src/http/endpoints/auth.ts

@@ -0,0 +1,23 @@
+import type { HttpClient } from '../HttpClient.js'
+import type { ApiAuthSigninResponse, ApiAuthMeResponse, ApiAuthQueryTokenResponse, ApiAuthSteamTicketResponse, ApiAuthModInfoResponse } from '../../types/api.js'
+
+export interface AuthEndpoints {
+  /** @mmonly Not available on private servers (backend-local). Use steamTicket() instead. */
+  signin(email: string, password: string): Promise<ApiAuthSigninResponse>
+  me(): Promise<ApiAuthMeResponse>
+  /** @mmonly Not available on private servers (backend-local). */
+  queryToken(token: string): Promise<ApiAuthQueryTokenResponse>
+  steamTicket(ticket: string, useNativeAuth?: boolean): Promise<ApiAuthSteamTicketResponse>
+  /** Query screepsmod-auth capabilities (allowRegistration, available OAuth providers). Only available on servers running screepsmod-auth. */
+  modInfo(): Promise<ApiAuthModInfoResponse>
+}
+
+export function createAuthEndpoints(http: HttpClient): AuthEndpoints {
+  return {
+    signin: (email, password) => http.request('POST', '/api/auth/signin', { email, password }),
+    me: () => http.request('GET', '/api/auth/me'),
+    queryToken: (token) => http.request('GET', '/api/auth/query-token', { token }),
+    steamTicket: (ticket, useNativeAuth) => http.request('POST', '/api/auth/steam-ticket', { ticket, ...(useNativeAuth != null ? { useNativeAuth } : {}) }),
+    modInfo: () => http.request('GET', '/api/authmod'),
+  }
+}

package/src/http/endpoints/experimental.ts

@@ -0,0 +1,13 @@
+import type { HttpClient } from '../HttpClient.js'
+
+export interface ExperimentalEndpoints {
+  pvp(interval?: number): Promise<unknown>
+  nukes(): Promise<unknown>
+}
+
+export function createExperimentalEndpoints(http: HttpClient): ExperimentalEndpoints {
+  return {
+    pvp: (interval = 100) => http.request('GET', '/api/experimental/pvp', { interval }),
+    nukes: () => http.request('GET', '/api/experimental/nukes'),
+  }
+}

package/src/http/endpoints/game.ts

@@ -0,0 +1,103 @@
+import type { HttpClient } from '../HttpClient.js'
+import type {
+  ApiRoomTerrainResponse,
+  ApiRoomObjectsResponse,
+  ApiShardsInfoResponse,
+  ApiMapStatsResponse,
+  ApiGameRoomsResponse,
+  ApiCreateFlagResponse,
+  ApiGenUniqueFlagNameResponse,
+  ApiCheckUniqueFlagNameResponse,
+  ApiChangeFlagColorResponse,
+  ApiRemoveFlagResponse,
+  ApiGenUniqueObjectNameResponse,
+  ApiCheckUniqueObjectNameResponse,
+  ApiGameTickResponse,
+} from '../../types/api.js'
+import { createPowerCreepsEndpoints, type PowerCreepsEndpoints } from './power-creeps.js'
+
+export interface GameEndpoints {
+  roomTerrain(room: string, shard?: string | null): Promise<ApiRoomTerrainResponse>
+  /** @deprecated Not available on private servers (backend-local). Room objects are delivered via the `room:<name>` WebSocket channel. */
+  roomObjects(room: string, shard?: string | null): Promise<ApiRoomObjectsResponse>
+  roomStatus(room: string, shard?: string | null): Promise<{ ok: number; status: string; novice?: string }>
+  roomOverview(room: string, interval?: number, shard?: string | null): Promise<unknown>
+  time(shard?: string | null): Promise<{ ok: number; time: number }>
+  tick(): Promise<ApiGameTickResponse>
+  worldSize(shard?: string | null): Promise<unknown>
+  mapStats(rooms: string[], statName: string, shard?: string | null): Promise<ApiMapStatsResponse>
+  roomsTerrain(rooms: string[], shard?: string | null): Promise<ApiGameRoomsResponse>
+  createFlag(room: string, x: number, y: number, name: string, color: number, secondaryColor: number, shard?: string | null): Promise<ApiCreateFlagResponse>
+  genUniqueFlagName(): Promise<ApiGenUniqueFlagNameResponse>
+  checkUniqueFlagName(name: string): Promise<ApiCheckUniqueFlagNameResponse>
+  changeFlagColor(room: string, name: string, color: number, secondaryColor: number): Promise<ApiChangeFlagColorResponse>
+  removeFlag(room: string, name: string): Promise<ApiRemoveFlagResponse>
+  genUniqueObjectName(type: string): Promise<ApiGenUniqueObjectNameResponse>
+  checkUniqueObjectName(type: string, name: string): Promise<ApiCheckUniqueObjectNameResponse>
+  placeSpawn(room: string, x: number, y: number, name?: string, shard?: string | null): Promise<{ ok: number }>
+  createConstruction(room: string, x: number, y: number, structureType: string, name?: string, shard?: string | null): Promise<{ ok: number }>
+  removeConstructionSite(room: string, ids: string[], shard?: string | null): Promise<{ ok: number }>
+  addObjectIntent(id: string, room: string, name: string, intent: unknown): Promise<{ ok: number }>
+  addGlobalIntent(name: string, intent: unknown): Promise<{ ok: number }>
+  setNotifyWhenAttacked(id: string, enabled: boolean): Promise<{ ok: number }>
+  createInvader(room: string, x: number, y: number, size: number, type: string, boosted?: boolean): Promise<{ ok: number }>
+  removeInvader(id: string): Promise<{ ok: number }>
+  powerCreeps: PowerCreepsEndpoints
+  market: {
+    ordersIndex(shard?: string | null): Promise<unknown>
+    myOrders(): Promise<unknown>
+    orders(resourceType: string, shard?: string | null): Promise<unknown>
+    stats(resourceType: string, shard?: string | null): Promise<unknown>
+  }
+  shards: {
+    info(): Promise<ApiShardsInfoResponse>
+  }
+}
+
+function withShard(params: Record<string, unknown>, shard?: string | null): Record<string, unknown> {
+  if (shard) params.shard = shard
+  return params
+}
+
+export function createGameEndpoints(http: HttpClient): GameEndpoints {
+  return {
+    roomTerrain: (room, shard) => http.request('GET', '/api/game/room-terrain', withShard({ room, encoded: 1 }, shard)),
+    roomObjects: (room, shard) => http.request('GET', '/api/game/room-objects', withShard({ room }, shard)),
+    roomStatus: (room, shard) => http.request('GET', '/api/game/room-status', withShard({ room }, shard)),
+    roomOverview: (room, interval = 8, shard) => http.request('GET', '/api/game/room-overview', withShard({ room, interval }, shard)),
+    time: (shard) => http.request('GET', '/api/game/time', withShard({}, shard)),
+    worldSize: (shard) => http.request('GET', '/api/game/world-size', withShard({}, shard)),
+    mapStats: (rooms, statName, shard) => http.request('POST', '/api/game/map-stats', withShard({ rooms, statName }, shard)),
+    roomsTerrain: (rooms, shard) => {
+      const params = new URLSearchParams({ encoded: 'true' })
+      if (shard) params.set('shard', shard)
+      return http.request('POST', `/api/game/rooms?${params}`, { rooms })
+    },
+    createFlag: (room, x, y, name, color, secondaryColor, shard) => http.request('POST', '/api/game/create-flag', withShard({ room, x, y, name, color, secondaryColor }, shard)),
+    genUniqueFlagName: () => http.request('POST', '/api/game/gen-unique-flag-name'),
+    checkUniqueFlagName: (name) => http.request('POST', '/api/game/check-unique-flag-name', { name }),
+    changeFlagColor: (room, name, color, secondaryColor) => http.request('POST', '/api/game/change-flag-color', { room, name, color, secondaryColor }),
+    removeFlag: (room, name) => http.request('POST', '/api/game/remove-flag', { room, name }),
+    genUniqueObjectName: (type) => http.request('POST', '/api/game/gen-unique-object-name', { type }),
+    checkUniqueObjectName: (type, name) => http.request('POST', '/api/game/check-unique-object-name', { type, name }),
+    placeSpawn: (room, x, y, name, shard) => http.request('POST', '/api/game/place-spawn', withShard({ room, x, y, ...(name ? { name } : {}) }, shard)),
+    createConstruction: (room, x, y, structureType, name, shard) => http.request('POST', '/api/game/create-construction', withShard({ room, x, y, structureType, ...(name ? { name } : {}) }, shard)),
+    removeConstructionSite: (room, ids, shard) => http.request('POST', '/api/game/add-object-intent', withShard({ _id: 'room', room, name: 'removeConstructionSite', intent: ids.map(id => ({ id, roomName: room })) }, shard)),
+    addObjectIntent: (id, room, name, intent) => http.request('POST', '/api/game/add-object-intent', { _id: id, room, name, intent }),
+    addGlobalIntent: (name, intent) => http.request('POST', '/api/game/add-global-intent', { name, intent }),
+    setNotifyWhenAttacked: (id, enabled) => http.request('POST', '/api/game/set-notify-when-attacked', { _id: id, enabled }),
+    createInvader: (room, x, y, size, type, boosted) => http.request('POST', '/api/game/create-invader', { room, x, y, size, type, ...(boosted != null ? { boosted } : {}) }),
+    removeInvader: (id) => http.request('POST', '/api/game/remove-invader', { _id: id }),
+    tick: () => http.request('GET', '/api/game/tick'),
+    powerCreeps: createPowerCreepsEndpoints(http),
+    market: {
+      ordersIndex: (shard) => http.request('GET', '/api/game/market/orders-index', withShard({}, shard)),
+      myOrders: () => http.request('GET', '/api/game/market/my-orders'),
+      orders: (resourceType, shard) => http.request('GET', '/api/game/market/orders', withShard({ resourceType }, shard)),
+      stats: (resourceType, shard) => http.request('GET', '/api/game/market/stats', withShard({ resourceType }, shard)),
+    },
+    shards: {
+      info: () => http.request('GET', '/api/game/shards/info'),
+    },
+  }
+}

package/src/http/endpoints/leaderboard.ts

@@ -0,0 +1,16 @@
+import type { HttpClient } from '../HttpClient.js'
+import type { ApiLeaderboardListResponse, ApiLeaderboardSeasonsResponse } from '../../types/api.js'
+
+export interface LeaderboardEndpoints {
+  list(limit?: number, mode?: 'world' | 'power', offset?: number, season?: string): Promise<ApiLeaderboardListResponse>
+  find(username: string, mode?: string, season?: string): Promise<unknown>
+  seasons(): Promise<ApiLeaderboardSeasonsResponse>
+}
+
+export function createLeaderboardEndpoints(http: HttpClient): LeaderboardEndpoints {
+  return {
+    list: (limit = 10, mode = 'world', offset = 0, season) => http.request('GET', '/api/leaderboard/list', { limit, mode, offset, season }),
+    find: (username, mode = 'world', season = '') => http.request('GET', '/api/leaderboard/find', { username, mode, season }),
+    seasons: () => http.request('GET', '/api/leaderboard/seasons'),
+  }
+}

package/src/http/endpoints/power-creeps.ts

@@ -0,0 +1,24 @@
+import type { HttpClient } from '../HttpClient.js'
+import type { ApiPowerCreepsListResponse } from '../../types/api.js'
+
+export interface PowerCreepsEndpoints {
+  list(): Promise<ApiPowerCreepsListResponse>
+  create(name: string, className: string): Promise<{ ok: number }>
+  delete(id: string): Promise<{ ok: number }>
+  cancelDelete(id: string): Promise<{ ok: number }>
+  upgrade(id: string, powers: Record<string, number>): Promise<{ ok: number }>
+  rename(id: string, name: string): Promise<{ ok: number }>
+  experimentation(): Promise<{ ok: number }>
+}
+
+export function createPowerCreepsEndpoints(http: HttpClient): PowerCreepsEndpoints {
+  return {
+    list: () => http.request('GET', '/api/game/power-creeps/list'),
+    create: (name, className) => http.request('POST', '/api/game/power-creeps/create', { name, className }),
+    delete: (id) => http.request('POST', '/api/game/power-creeps/delete', { id }),
+    cancelDelete: (id) => http.request('POST', '/api/game/power-creeps/cancel-delete', { id }),
+    upgrade: (id, powers) => http.request('POST', '/api/game/power-creeps/upgrade', { id, powers }),
+    rename: (id, name) => http.request('POST', '/api/game/power-creeps/rename', { id, name }),
+    experimentation: () => http.request('POST', '/api/game/power-creeps/experimentation'),
+  }
+}

package/src/http/endpoints/register.ts

@@ -0,0 +1,19 @@
+import type { HttpClient } from '../HttpClient.js'
+import type { ApiRegisterCheckResponse } from '../../types/api.js'
+
+export interface RegisterEndpoints {
+  checkEmail(email: string): Promise<ApiRegisterCheckResponse>
+  checkUsername(username: string): Promise<ApiRegisterCheckResponse>
+  setUsername(username: string, email?: string): Promise<{ ok: number }>
+  /** Register a new user account (screepsmod-auth private servers only). */
+  submit(username: string, email: string, password: string, modules?: Record<string, string>): Promise<{ ok: number }>
+}
+
+export function createRegisterEndpoints(http: HttpClient): RegisterEndpoints {
+  return {
+    checkEmail: (email) => http.request('GET', '/api/register/check-email', { email }),
+    checkUsername: (username) => http.request('GET', '/api/register/check-username', { username }),
+    setUsername: (username, email) => http.request('POST', '/api/register/set-username', { username, ...(email != null ? { email } : {}) }),
+    submit: (username, email, password, modules) => http.request('POST', '/api/register/submit', { username, email, password, ...(modules != null ? { modules } : {}) }),
+  }
+}

package/src/http/endpoints/user-messages.ts

@@ -0,0 +1,20 @@
+import type { HttpClient } from '../HttpClient.js'
+import type { ApiUserMessagesListResponse, ApiUserMessagesIndexResponse, ApiUserMessagesUnreadCountResponse } from '../../types/api.js'
+
+export interface UserMessagesEndpoints {
+  send(respondent: string, text: string): Promise<{ ok: number }>
+  list(respondent: string): Promise<ApiUserMessagesListResponse>
+  index(): Promise<ApiUserMessagesIndexResponse>
+  markRead(id: string): Promise<{ ok: number }>
+  unreadCount(): Promise<ApiUserMessagesUnreadCountResponse>
+}
+
+export function createUserMessagesEndpoints(http: HttpClient): UserMessagesEndpoints {
+  return {
+    send: (respondent, text) => http.request('POST', '/api/user/messages/send', { respondent, text }),
+    list: (respondent) => http.request('GET', '/api/user/messages/list', { respondent }),
+    index: () => http.request('GET', '/api/user/messages/index'),
+    markRead: (id) => http.request('POST', '/api/user/messages/mark-read', { id }),
+    unreadCount: () => http.request('GET', '/api/user/messages/unread-count'),
+  }
+}

package/src/http/endpoints/user.ts

@@ -0,0 +1,95 @@
+import type { HttpClient } from '../HttpClient.js'
+import type {
+  ApiUserBranchesResponse,
+  ApiUserFindResponse,
+  ApiUserMoneyHistoryResponse,
+} from '../../types/api.js'
+import { createUserMessagesEndpoints, type UserMessagesEndpoints } from './user-messages.js'
+
+export interface NotifyPrefs {
+  disabled: boolean
+  disabledOnMessages: boolean
+  sendOnline: boolean
+  interval: number
+  errorsInterval: number
+}
+
+export interface UserEndpoints {
+  branches(): Promise<ApiUserBranchesResponse>
+  code: {
+    get(branch?: string): Promise<unknown>
+    set(branch: string, modules: Record<string, string>): Promise<unknown>
+  }
+  memory: {
+    get(path: string, shard?: string | null): Promise<{ ok: number; data: unknown }>
+    set(path: string, value: unknown, shard?: string | null): Promise<unknown>
+    segment: {
+      get(segment: number, shard?: string | null): Promise<{ ok: number; data: string }>
+      set(segment: number, data: string, shard?: string | null): Promise<unknown>
+    }
+  }
+  console(expression: string, shard?: string | null): Promise<unknown>
+  stats(interval: number): Promise<unknown>
+  rooms(id: string): Promise<unknown>
+  overview(interval: number, statName: string): Promise<unknown>
+  worldStatus(): Promise<{ ok: number; status: 'normal' | 'lost' | 'empty' }>
+  worldStartRoom(shard?: string | null): Promise<unknown>
+  find(query: { username: string } | { id: string }): Promise<ApiUserFindResponse>
+  moneyHistory(page?: number): Promise<ApiUserMoneyHistoryResponse>
+  respawn(): Promise<{ ok: number }>
+  respawnProhibitedRooms(): Promise<{ ok: number; rooms: string[] }>
+  badge(badge: unknown): Promise<{ ok: number }>
+  setActiveBranch(activeName: 'activeWorld' | 'activeSim', branch: string): Promise<{ ok: number }>
+  cloneBranch(newName: string, branch?: string, defaultModules?: boolean): Promise<{ ok: number }>
+  deleteBranch(branch: string): Promise<{ ok: number }>
+  notifyPrefs(prefs: Partial<NotifyPrefs>): Promise<{ ok: number }>
+  tutorialDone(): Promise<{ ok: number }>
+  email(email: string): Promise<{ ok: number }>
+  setSteamVisible(visible: boolean): Promise<{ ok: number }>
+  /** Change the current user's password (screepsmod-auth private servers only). Pass oldPassword when the account already has a password set. */
+  password(newPassword: string, oldPassword?: string): Promise<{ ok: number }>
+  messages: UserMessagesEndpoints
+}
+
+function withShard(params: Record<string, unknown>, shard?: string | null): Record<string, unknown> {
+  if (shard) params.shard = shard
+  return params
+}
+
+export function createUserEndpoints(http: HttpClient): UserEndpoints {
+  return {
+    branches: () => http.request('GET', '/api/user/branches'),
+    code: {
+      get: (branch) => http.request('GET', '/api/user/code', branch ? { branch } : {}),
+      set: (branch, modules) => http.request('POST', '/api/user/code', { branch, modules, _hash: Date.now() }),
+    },
+    memory: {
+      get: (path, shard) => http.request('GET', '/api/user/memory', withShard({ path }, shard)),
+      set: (path, value, shard) => http.request('POST', '/api/user/memory', withShard({ path, value }, shard)),
+      segment: {
+        get: (segment, shard) => http.request('GET', '/api/user/memory-segment', withShard({ segment }, shard)),
+        set: (segment, data, shard) => http.request('POST', '/api/user/memory-segment', withShard({ segment, data }, shard)),
+      },
+    },
+    console: (expression, shard) => http.request('POST', '/api/user/console', withShard({ expression }, shard)),
+    stats: (interval) => http.request('GET', '/api/user/stats', { interval }),
+    rooms: (id) => http.request('GET', '/api/user/rooms', { id }),
+    overview: (interval, statName) => http.request('GET', '/api/user/overview', { interval, statName }),
+    worldStatus: () => http.request('GET', '/api/user/world-status'),
+    worldStartRoom: (shard) => http.request('GET', '/api/user/world-start-room', withShard({}, shard)),
+    find: (query) => http.request('GET', '/api/user/find', query as Record<string, unknown>),
+    moneyHistory: (page) => http.request('GET', '/api/user/money-history', page != null ? { page } : {}),
+    respawn: () => http.request('POST', '/api/user/respawn'),
+    respawnProhibitedRooms: () => http.request('GET', '/api/user/respawn-prohibited-rooms'),
+    badge: (badge) => http.request('POST', '/api/user/badge', { badge }),
+    setActiveBranch: (activeName, branch) => http.request('POST', '/api/user/set-active-branch', { activeName, branch }),
+    cloneBranch: (newName, branch, defaultModules) => http.request('POST', '/api/user/clone-branch', { newName, ...(branch ? { branch } : {}), ...(defaultModules != null ? { defaultModules } : {}) }),
+    deleteBranch: (branch) => http.request('POST', '/api/user/delete-branch', { branch }),
+    notifyPrefs: (prefs) => http.request('POST', '/api/user/notify-prefs', prefs as Record<string, unknown>),
+    tutorialDone: () => http.request('POST', '/api/user/tutorial-done'),
+    email: (email) => http.request('POST', '/api/user/email', { email }),
+    setSteamVisible: (visible) => http.request('POST', '/api/user/set-steam-visible', { visible }),
+    password: (newPassword, oldPassword) => http.request('POST', '/api/user/password', { password: newPassword, ...(oldPassword != null ? { oldPassword } : {}) }),
+    messages: createUserMessagesEndpoints(http),
+  }
+}