ci: update api (#16)

Co-authored-by: CI <ci@rman.dev>

Author: github-actions[bot]

specs/lichess-api.yaml

@@ -1,6 +1,6 @@
 openapi: "3.1.0"
 info:
-  version: 2.0.120
+  version: 2.0.123
   title: Lichess.org API reference
   contact:
     name: "Lichess.org API"
@@ -538,6 +538,9 @@ paths:
   /api/fide/player/{playerId}:
     $ref: "./tags/fide/api-fide-player-playerId.yaml"
 
+  /api/fide/player/{playerId}/ratings:
+    $ref: "./tags/fide/api-fide-player-playerId-ratings.yaml"
+
   /api/fide/player:
     $ref: "./tags/fide/api-fide-player-search.yaml"
 

specs/schemas/FIDEPlayerRatings.yaml

@@ -0,0 +1,38 @@
+type: object
+description: |
+  Data points are encoded. Each number contains a year, a month, and an ELO rating.
+
+  `2015081568` -> `August 2015: 1568`
+
+  Here's an example decoding implementation in JS:
+
+  ```js
+    const decodePoint = point => {
+      const elo = point % 10000;
+      const dateNum = Math.floor(point / 10000);
+      const year = Math.floor(dateNum / 100);
+      const month = dateNum % 100;
+      return [year, month, elo];
+    };
+  ```
+
+  Consecutive months with same ELO are omitted. For a given ELO, only the first and last month are provided.
+
+properties:
+  standard:
+    type: array
+    items:
+      type: number
+  rapid:
+    type: array
+    items:
+      type: number
+  blitz:
+    type: array
+    items:
+      type: number
+
+required:
+  - standard
+  - rapid
+  - blitz

specs/tags/broadcasts/api-broadcast-broadcastTournamentId-pgn.yaml

@@ -19,6 +19,22 @@ get:
         type: string
         minLength: 8
         maxLength: 8
+    - in: query
+      name: clocks
+      description: |
+        Include clock comments in the PGN moves, when available.
+        Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`
+      schema:
+        type: boolean
+        default: true
+    - in: query
+      name: comments
+      description: |
+        Include analysis comments in the PGN moves, when available.
+        Example: `12. Bxf6 { [%eval 0.23] }`
+      schema:
+        type: boolean
+        default: true
   responses:
     "200":
       description: The PGN representation of the broadcast.

specs/tags/broadcasts/api-broadcast-round-broadcastRoundId-pgn.yaml

@@ -19,6 +19,22 @@ get:
         type: string
         minLength: 8
         maxLength: 8
+    - in: query
+      name: clocks
+      description: |
+        Include clock comments in the PGN moves, when available.
+        Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`
+      schema:
+        type: boolean
+        default: true
+    - in: query
+      name: comments
+      description: |
+        Include analysis comments in the PGN moves, when available.
+        Example: `12. Bxf6 { [%eval 0.23] }`
+      schema:
+        type: boolean
+        default: true
   responses:
     "200":
       description: The PGN representation of the round.

specs/tags/broadcasts/api-stream-broadcast-round-broadcastRoundId-pgn.yaml

@@ -19,6 +19,22 @@ get:
         type: string
         minLength: 8
         maxLength: 8
+    - in: query
+      name: clocks
+      description: |
+        Include clock comments in the PGN moves, when available.
+        Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`
+      schema:
+        type: boolean
+        default: true
+    - in: query
+      name: comments
+      description: |
+        Include analysis comments in the PGN moves, when available.
+        Example: `12. Bxf6 { [%eval 0.23] }`
+      schema:
+        type: boolean
+        default: true
   responses:
     "200":
       description: The PGN representation of the round games, then the PGNs of games as they are updated.

specs/tags/fide/api-fide-player-playerId-ratings.yaml

@@ -0,0 +1,25 @@
+get:
+  operationId: fidePlayerRatings
+  summary: Get ratings history of a FIDE player
+  description: |
+    Historical standard, rapid and blitz ratings of a FIDE player
+  tags:
+    - FIDE
+  security: []
+  parameters:
+    - in: path
+      name: playerId
+      description: The FIDE player ID.
+      required: true
+      schema:
+        type: integer
+  responses:
+    "200":
+      description: The rating histories
+      content:
+        application/json:
+          schema:
+            $ref: "../../schemas/FIDEPlayerRatings.yaml"
+          examples:
+            example player:
+              $ref: "../../examples/fide-getFidePlayerRatings.json.yaml"

src/client/index.ts

@@ -2177,26 +2177,50 @@ export class Lichess {
   /**
    * Stream an ongoing broadcast round as PGN
    */
-  async broadcastStreamRoundPgn(params: { broadcastRoundId: string }) {
+  async broadcastStreamRoundPgn(
+    params: { broadcastRoundId: string } & {
+      clocks?: boolean;
+      comments?: boolean;
+    },
+  ) {
     const path =
       `/api/stream/broadcast/round/${params.broadcastRoundId}.pgn` as const;
-    return await this.requestor.get({ path }, { 200: { kind: "chess-pgn" } });
+    return await this.requestor.get(
+      { path, query: { clocks: params.clocks, comments: params.comments } },
+      { 200: { kind: "chess-pgn" } },
+    );
   }
 
   /**
    * Export one round as PGN
    */
-  async broadcastRoundPgn(params: { broadcastRoundId: string }) {
+  async broadcastRoundPgn(
+    params: { broadcastRoundId: string } & {
+      clocks?: boolean;
+      comments?: boolean;
+    },
+  ) {
     const path = `/api/broadcast/round/${params.broadcastRoundId}.pgn` as const;
-    return await this.requestor.get({ path }, { 200: { kind: "chess-pgn" } });
+    return await this.requestor.get(
+      { path, query: { clocks: params.clocks, comments: params.comments } },
+      { 200: { kind: "chess-pgn" } },
+    );
   }
 
   /**
    * Export all rounds as PGN
    */
-  async broadcastAllRoundsPgn(params: { broadcastTournamentId: string }) {
+  async broadcastAllRoundsPgn(
+    params: { broadcastTournamentId: string } & {
+      clocks?: boolean;
+      comments?: boolean;
+    },
+  ) {
     const path = `/api/broadcast/${params.broadcastTournamentId}.pgn` as const;
-    return await this.requestor.get({ path }, { 200: { kind: "chess-pgn" } });
+    return await this.requestor.get(
+      { path, query: { clocks: params.clocks, comments: params.comments } },
+      { 200: { kind: "chess-pgn" } },
+    );
   }
 
   /**
@@ -2221,6 +2245,17 @@ export class Lichess {
     );
   }
 
+  /**
+   * Get ratings history of a FIDE player
+   */
+  async fidePlayerRatings(params: { playerId: number }) {
+    const path = `/api/fide/player/${params.playerId}/ratings` as const;
+    return await this.requestor.get(
+      { path },
+      { 200: { kind: "json", schema: schemas.FIDEPlayerRatings } },
+    );
+  }
+
   /**
    * Search FIDE players
    */

src/schemas/FIDEPlayerRatings.ts

@@ -0,0 +1,11 @@
+import * as z from "zod/mini";
+
+const FIDEPlayerRatings = z.object({
+  standard: z.array(z.number()),
+  rapid: z.array(z.number()),
+  blitz: z.array(z.number()),
+});
+
+type FIDEPlayerRatings = z.infer<typeof FIDEPlayerRatings>;
+
+export { FIDEPlayerRatings };

src/schemas/index.ts

@@ -62,6 +62,7 @@ export { ExternalEngineWork } from "./ExternalEngineWork";
 export { ExternalEngineWorkCommon } from "./ExternalEngineWorkCommon";
 export { FIDEPlayer } from "./FIDEPlayer";
 export { FIDEPlayerPhoto } from "./FIDEPlayerPhoto";
+export { FIDEPlayerRatings } from "./FIDEPlayerRatings";
 export { FideTimeControl } from "./FideTimeControl";
 export { Flair } from "./Flair";
 export { FromPositionFEN } from "./FromPositionFEN";