From 83acd19c3687b5bef9fcd78530d7704b089a9e0d Mon Sep 17 00:00:00 2001
From: "Dr. Dvorak" <171316552+DocDvorak@users.noreply.github.com>
Date: Tue, 16 Jun 2026 20:56:42 -0700
Subject: [PATCH] feat: Add `GET /api/seasons` endpoint method

---
 src/ScreepsHttpClient.ts | 19 +++++++++++++++++--
 src/http/seasons.ts      | 38 ++++++++++++++++++++++++++++++++++----
 2 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/src/ScreepsHttpClient.ts b/src/ScreepsHttpClient.ts
index 9ed7d30..d325cb1 100644
--- a/src/ScreepsHttpClient.ts
+++ b/src/ScreepsHttpClient.ts
@@ -1231,8 +1231,23 @@ export class ScreepsHttpClient extends EventEmitter {
   }
 
   /**
-   * Fetch metadata for the current season. Only works on official servers
-   * when a Seasonal World competition is active or about to start.
+   * Fetch a list of all past, current, and upcoming
+   * {@link https://screeps.com/season/#!/seasons/chronicle | Seasonal World} competitions.
+   *
+   * Only works on official servers.
+   * @throws {@link ScreepsApiError} HTTP 404 if called on an unofficial server
+   * @category Endpoints: /seasons
+   */
+  seasonsList(): Promise<Http.SeasonsListResponse> {
+    return this.req(ScreepsHttpMethods.Get, '/api/seasons')
+  }
+
+  /**
+   * Fetch metadata for the current
+   * {@link https://screeps.com/season/#!/seasons/chronicle | Seasonal World} competition.
+   *
+   * Only works on official servers when a Seasonal World competition
+   * is active or about to start.
    *
    * Endpoint: `GET /api/seasons/current`
    * @throws {@link ScreepsApiError} HTTP 404 if called on an unofficial server
diff --git a/src/http/seasons.ts b/src/http/seasons.ts
index f7acb75..29e9a0c 100644
--- a/src/http/seasons.ts
+++ b/src/http/seasons.ts
@@ -1,17 +1,47 @@
 import { ScreepsResponse } from './base'
 
+/**
+ * `GET /api/seasons` response
+ * @see {@link ScreepsHttpClient.seasonsList}
+ * @category HTTP API - Seasons
+ */
+export interface SeasonsListResponse extends ScreepsResponse {
+  /**
+   * A list of all past, current, and upcoming Seasonal World competitions,
+   * ordered by {@link SeasonalWorldCompetition.index} (ascending).
+   */
+  list: SeasonalWorldCompetition[]
+}
+
 /**
  * `GET /api/seasons/current` response
  * @see {@link ScreepsHttpClient.seasonsCurrent}
  * @category HTTP API - Seasons
  */
-export interface SeasonsCurrentResponse extends ScreepsResponse {
+export interface SeasonsCurrentResponse extends ScreepsResponse, SeasonalWorldCompetition {
+  /** The authenticated user's current ranking on the seasonal leaderboard */
+  rank: number
+}
+
+/**
+ * Metadata for a
+ * {@link https://screeps.com/season/#!/seasons/chronicle | Seasonal World} competition.
+ * @category HTTP API - Seasons
+ */
+export interface SeasonalWorldCompetition {
+  _id: string
   /** Name of the season (ex: "Season 8") */
   title: string
-  /** Your current ranking on the seasonal leaderboard */
-  rank: number
-  /** The season ordinal (ex: 5 for season 5, 8 for season 8) */
+  /** The season ordinal (ex: 5 for season 5, 8 for season 8, etc) */
   index: number
+  /**
+   * Ostensibly reports the number of participants in the season, but instead,
+   * this is almost always 0
+   *
+   * The only known exception is Season 1, which reports 2121 players.
+   * @see {@link ScoreboardListResponse.meta.length} for an actual player count
+   */
+  players: number
   /** Season start date/time (ISO 8601 UTC) */
   startDate: string
   /** Season end date/time (ISO 8601 UTC) */