speedruncom.js 1.2.8 → 1.2.10

package/README.md

@@ -1,49 +1,49 @@
-## `npm i retrozy1/speedruncom.js`
-
-# About
-
-Speedrun.com has two API versions. Version 1 is officially documented, REST, public and directly exposed to users. Version 2 is a pre-production RPC API designed only for internal use of site functions, and is much more complicated and less user-friendly, especially regarding authentication and browser CORS.
-
-Version 1 is mainly read-only, and when it isn't read only it may just be broken. If you want to use any of the modern features of the site now, you'll use version 2. This is a NodeJS wrapper for Speedrun API version 2, with parameters and responses all documented in TypeScript and JSDoc.
-
-# Usage
-
-## Installation
-
-**`npm i retrozy1/speedruncom.js`**
-
-## Importing
-
-`Client` is the default export, and enums and interfaces are available in named exports for TypeScript users.
-
-```js
-import SpeedrunClient from 'speedruncom.js';
-
-const client = new SpeedrunClient({
-  userAgent: 'RunCollabGetter'
-});
-
-const getCollabs = async (userUrl) => {
-  // Fetch user summary
-  const {
-    user: { id: userId, name }
-  } = await client.GetUserSummary({ url: userUrl });
-
-  // Fetch leaderboard and extract player names
-  const { players } = await client.GetUserLeaderboard({ userId });
-  const otherPlayerNames = players.map(player => player.name).filter(n => n !== name); // Exclude self
-
-  if (otherPlayerNames.length === 0) {
-    return `${name} hasn't ran with anyone.`;
-  }
-
-  const formattedNames =
-    otherPlayerNames.length === 1
-      ? otherPlayerNames[0]
-      : `${otherPlayerNames.slice(0, -1).join(', ')} and ${otherPlayerNames.slice(-1)}`;
-
-  return `${name} has ran with ${formattedNames}.`;
-};
-
-console.log(await getCollabs('retrozy'));
-```
+## `npm i retrozy1/speedruncom.js`
+
+# About
+
+Speedrun.com has two API versions. Version 1 is officially documented, REST, public and directly exposed to users. Version 2 is a pre-production RPC API designed only for internal use of site functions, and is much more complicated and less user-friendly, especially regarding authentication and browser CORS.
+
+Version 1 is mainly read-only, and when it isn't read only it may just be broken. If you want to use any of the modern features of the site now, you'll use version 2. This is a NodeJS wrapper for Speedrun API version 2, with parameters and responses all documented in TypeScript and JSDoc.
+
+# Usage
+
+## Installation
+
+**`npm i retrozy1/speedruncom.js`**
+
+## Importing
+
+`Client` is the default export, and enums and interfaces are available in named exports for TypeScript users.
+
+```js
+import SpeedrunClient from 'speedruncom.js';
+
+const client = new SpeedrunClient({
+  userAgent: 'RunCollabGetter'
+});
+
+const getCollabs = async (userUrl) => {
+  // Fetch user summary
+  const {
+    user: { id: userId, name }
+  } = await client.GetUserSummary({ url: userUrl });
+
+  // Fetch leaderboard and extract player names
+  const { players } = await client.GetUserLeaderboard({ userId });
+  const otherPlayerNames = players.map(player => player.name).filter(n => n !== name); // Exclude self
+
+  if (otherPlayerNames.length === 0) {
+    return `${name} hasn't ran with anyone.`;
+  }
+
+  const formattedNames =
+    otherPlayerNames.length === 1
+      ? otherPlayerNames[0]
+      : `${otherPlayerNames.slice(0, -1).join(', ')} and ${otherPlayerNames.slice(-1)}`;
+
+  return `${name} has ran with ${formattedNames}.`;
+};
+
+console.log(await getCollabs('retrozy'));
+```

package/dist/endpoints/endpoints.get.d.ts

@@ -172,6 +172,10 @@ export interface GetLatestLeaderboard {
      * @default 25
      */
     limit?: number;
+    /**
+     * The run list page, in relation to `limit`.
+     */
+    page?: number;
 }
 /**
  * Gets a single run.
@@ -309,6 +313,10 @@ export interface GetGameList {
      * @default 500
      */
     limit?: number;
+    /**
+     * The game list page, in relation to `limit`.
+     */
+    page?: number;
 }
 /**
  * Gets a list of Platforms in the site.
@@ -336,6 +344,10 @@ export interface GetSeriesList {
      * @default 500
      */
     limit?: number;
+    /**
+     * The leaderboard page, in relation to `limit`.
+     */
+    page?: number;
 }
 /**
  * Gets most information pertinent to a series.
@@ -356,10 +368,6 @@ export interface GetGameLevelSummary {
      * When not included, `runList[]` will be empty.
      */
     params?: Interfaces.LeaderboardParams;
-    /**
-     * The leaderboard page, in relation to `limit`.
-     */
-    page?: number;
     /**
      * The limit of Runs per page.
      *
@@ -367,6 +375,10 @@ export interface GetGameLevelSummary {
      * @default Unknown - likely around 99999.
      */
     limit?: number;
+    /**
+     * The leaderboard page, in relation to `limit`.
+     */
+    page?: number;
 }
 /**
  * Gets a random Game.

package/dist/endpoints/endpoints.post.d.ts

@@ -428,9 +428,9 @@ export interface GetModerationRuns {
     search?: string;
     verified?: Enums.RunStatus;
     verifiedById?: string;
-    ideoState?: Enums.VideoState;
-    page?: number;
+    videoState?: Enums.VideoState;
     limit?: number;
+    page?: number;
 }
 /**
  * Assigns a verifier to a run.
@@ -449,6 +449,7 @@ export interface PutRunDelete {
 export interface PutRunVerification {
     runId: string;
     verified: Enums.RunStatus;
+    reason?: string;
 }
 /**
  * Assigns a video-at-risk state to a run.

package/package.json

@@ -1,30 +1,30 @@
-{
-  "name": "speedruncom.js",
-  "version": "1.2.8",
-  "description": "WIP NodeJS module for Speedrun's version 2 API.",
-  "type": "module",
-  "author": {
-    "name": "retrozy"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "axios": "^1.9.0",
-    "ts-morph": "^26.0.0"
-  },
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "clean": "rimraf dist src/Client.ts",
-    "build": "tsc",
-    "render": "tsx src/build-client.ts",
-    "prepare": "npm run render && npm run build"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.24",
-    "rimraf": "^6.0.1",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.8.3"
-  },
-  "main": "dist/index.js"
-}
+{
+  "name": "speedruncom.js",
+  "version": "1.2.10",
+  "description": "WIP NodeJS module for Speedrun's version 2 API.",
+  "type": "module",
+  "author": {
+    "name": "retrozy"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "axios": "^1.9.0",
+    "ts-morph": "^26.0.0"
+  },
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc",
+    "render": "tsx src/build-client.ts",
+    "prepare": "npm run render && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.24",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  },
+  "main": "dist/index.js"
+}

package/src/BaseClient.ts

@@ -1,108 +1,108 @@
-import axios, { AxiosResponse, AxiosInstance, AxiosError } from 'axios';
-import * as GetEndpoints from './endpoints/endpoints.get.js';
-import * as PostEndpoints from './endpoints/endpoints.post.js'
-import * as Responses from './responses.js';
-
-const BASE_USER_AGENT = 'speedruncom.js';
-const BASE_URL = 'https://www.speedrun.com/api/v2/';
-const HEADERS = {
-    'Accept-Language': 'en',
-    'Accept': 'application/json'
-}
-
-const isBrowser = typeof window !== 'undefined';
-
-const objectToBase64 = (obj: object) => {
-    const jsonString = JSON.stringify(obj).replace(/\s+/g, '');
-    return Buffer.from(jsonString).toString('base64');
-}
-
-export interface config {
-    PHPSESSID?: string;
-    userAgent?: string;
-}
-
-export class APIError extends Error {
-    status: number;
-
-    constructor(message: string, status: number) {
-        super(message);
-        this.message = message;
-        this.status = status;
-    }
-}
-
-export default class Client {
-
-    /**
-     * `AxiosInstance` used on instance-called methods (called with `POST`).
-     */
-    axiosClient = axios.create({
-        baseURL: BASE_URL,
-        method: 'POST',
-        withCredentials: true,
-        headers: HEADERS
-    });
-
-    /**
-     * `AxiosInstance` used on Client-called methods (called with `GET`).
-     */
-    static axiosClient = axios.create({
-        baseURL: BASE_URL,
-        method: 'GET',
-        headers: HEADERS
-    });
-
-    private username!: string;
-    private password!: string;
-
-    private headers = this.axiosClient.defaults.headers.common;
-
-    constructor(config?: config) {
-        if (config) this.config(config);
-
-        this.axiosClient.interceptors.response.use(
-            (response: AxiosResponse) => response,
-            (error: AxiosError) => {
-                const data = error.response.data as { error?: string };
-                throw new APIError(data.error || 'Unknown error', error.response.status);
-            }
-        );
-    }
-
-    config(config: config) {
-        if (!isBrowser) this.headers['User-Agent'] = BASE_USER_AGENT + (config.userAgent ? `/${config.userAgent}` : '');
-
-        if (config.PHPSESSID) {
-            if (isBrowser) {
-                console.error('You cannot use a PHPSESSID to authenticate in a browser environment.');
-            } else {
-                this.headers['Cookie'] = `PHPSESSID=${config.PHPSESSID}`;
-            }
-        }
-    }
-
-    async request<T>(endpoint: string, params: object = {}): Promise<T> {
-        const response = await this.axiosClient.post<T>(endpoint, params);
-        
-        const cookie = response.headers['set-cookie'];
-        if (cookie && !isBrowser) this.headers['Cookie'] = cookie[0].split(';')[0];
-
-        return response.data;
-    }
-
-    static async request<T>(endpoint: string, params: object = {}): Promise<T> {
-        return (await this.axiosClient.get(`${endpoint}?_r=${objectToBase64(params)}`)).data;
-    }
-
-    /**
-     * Attempts to remove the PHPSESSID cookie if using a browser, otherwise removes your Client's authentication.
-     */
-    async logout() {
-        if (isBrowser) return await this.request('PutAuthLogout');
-
-        delete this.headers['Cookie'];
-    }
-
-    // Endpoints (auto-generated with build-client)
+import axios, { AxiosResponse, AxiosInstance, AxiosError } from 'axios';
+import * as GetEndpoints from './endpoints/endpoints.get.js';
+import * as PostEndpoints from './endpoints/endpoints.post.js'
+import * as Responses from './responses.js';
+
+const BASE_USER_AGENT = 'speedruncom.js';
+const BASE_URL = 'https://www.speedrun.com/api/v2/';
+const HEADERS = {
+    'Accept-Language': 'en',
+    'Accept': 'application/json'
+}
+
+const isBrowser = typeof window !== 'undefined';
+
+const objectToBase64 = (obj: object) => {
+    const jsonString = JSON.stringify(obj).replace(/\s+/g, '');
+    return Buffer.from(jsonString).toString('base64');
+}
+
+export interface config {
+    PHPSESSID?: string;
+    userAgent?: string;
+}
+
+export class APIError extends Error {
+    status: number;
+
+    constructor(message: string, status: number) {
+        super(message);
+        this.message = message;
+        this.status = status;
+    }
+}
+
+export default class Client {
+
+    /**
+     * `AxiosInstance` used on instance-called methods (called with `POST`).
+     */
+    axiosClient = axios.create({
+        baseURL: BASE_URL,
+        method: 'POST',
+        withCredentials: true,
+        headers: HEADERS
+    });
+
+    /**
+     * `AxiosInstance` used on Client-called methods (called with `GET`).
+     */
+    static axiosClient = axios.create({
+        baseURL: BASE_URL,
+        method: 'GET',
+        headers: HEADERS
+    });
+
+    private username!: string;
+    private password!: string;
+
+    private headers = this.axiosClient.defaults.headers.common;
+
+    constructor(config?: config) {
+        if (config) this.config(config);
+
+        this.axiosClient.interceptors.response.use(
+            (response: AxiosResponse) => response,
+            (error: AxiosError) => {
+                const data = error.response.data as { error?: string };
+                throw new APIError(data.error || 'Unknown error', error.response.status);
+            }
+        );
+    }
+
+    config(config: config) {
+        if (!isBrowser) this.headers['User-Agent'] = BASE_USER_AGENT + (config.userAgent ? `/${config.userAgent}` : '');
+
+        if (config.PHPSESSID) {
+            if (isBrowser) {
+                console.error('You cannot use a PHPSESSID to authenticate in a browser environment.');
+            } else {
+                this.headers['Cookie'] = `PHPSESSID=${config.PHPSESSID}`;
+            }
+        }
+    }
+
+    async request<T>(endpoint: string, params: object = {}): Promise<T> {
+        const response = await this.axiosClient.post<T>(endpoint, params);
+        
+        const cookie = response.headers['set-cookie'];
+        if (cookie && !isBrowser) this.headers['Cookie'] = cookie[0].split(';')[0];
+
+        return response.data;
+    }
+
+    static async request<T>(endpoint: string, params: object = {}): Promise<T> {
+        return (await this.axiosClient.get(`${endpoint}?_r=${objectToBase64(params)}`)).data;
+    }
+
+    /**
+     * Attempts to remove the PHPSESSID cookie if using a browser, otherwise removes your Client's authentication.
+     */
+    async logout() {
+        if (isBrowser) return await this.request('PutAuthLogout');
+
+        delete this.headers['Cookie'];
+    }
+
+    // Endpoints (auto-generated with build-client)
 }

package/src/build-client.ts

@@ -1,80 +1,80 @@
-import { Project, SourceFile, Node, OptionalKind, MethodDeclarationStructure } from 'ts-morph';
-
-const project = new Project({
-    tsConfigFilePath: "tsconfig.json",
-});
-
-const isInterfaceEmpty = (interfaceName: string, sourceFile: SourceFile) => {
-    const declarations = sourceFile.getExportedDeclarations().get(interfaceName);
-    if (!declarations || declarations.length === 0) return false;
-
-    const decl = declarations[0];
-    if (!Node.isInterfaceDeclaration(decl)) return false;
-
-    const type = decl.getType();
-    const allProperties = type.getProperties();
-
-    return allProperties.length === 0;
-};
-
-
-const isInterfaceAllOptional = (name: string, sourceFile: SourceFile) => {
-    const iface = sourceFile.getInterface(name);
-    if (iface) {
-        return iface.getType().getProperties().every(p => p.isOptional());
-    }
-
-    const typeNode = sourceFile.getTypeAliasOrThrow(name).getType();
-    return typeNode
-        .getProperties()
-        .every(p => p.isOptional());
-};
-
-const baseClient = project.getSourceFileOrThrow('src/BaseClient.ts');
-const clientFile = project.createSourceFile('src/Client.ts', baseClient.getFullText(), { overwrite: true });
-const clientClass = clientFile.getClasses()[1];
-
-const getEndpointsFile = project.getSourceFileOrThrow('src/endpoints/endpoints.get.ts');
-const postEndpointsFile = project.getSourceFileOrThrow('src/endpoints/endpoints.post.ts');
-const responsesFile = project.getSourceFileOrThrow('src/responses.ts');
-
-const getEndpointNames = Array.from(getEndpointsFile.getExportedDeclarations().keys());
-const postEndpointNames = Array.from(postEndpointsFile.getExportedDeclarations().keys());
-
-const responseNames = new Set(Array.from(responsesFile.getExportedDeclarations().keys()));
-
-const makeMethod = (name: string, isStatic: boolean, returnType: string, isEmpty: boolean, interfaces: string, isOptional: boolean) => {
-    const method: OptionalKind<MethodDeclarationStructure> = {
-        name,
-        isStatic,
-        isAsync: true,
-        returnType,
-        statements: [`return await this.request('${name}'${!isEmpty ? ', params' : ''});`]
-    }
-    if (!isEmpty) method.parameters = [{
-        name: 'params',
-        type: `${interfaces}.${name}`,
-        hasQuestionToken: isOptional
-    }];
-
-    clientClass.addMethod(method);
-}
-
-for (const endpointName of getEndpointNames) {
-    const returnType = responseNames.has(endpointName) ? `Promise<Readonly<Responses.${endpointName}>>` : 'Promise<void>';
-    const isEmpty = isInterfaceEmpty(endpointName, getEndpointsFile);
-    const isAllOptional = isInterfaceAllOptional(endpointName, getEndpointsFile);
-
-    makeMethod(endpointName, false, returnType, isEmpty, 'GetEndpoints', isAllOptional);
-    makeMethod(endpointName, true, returnType, isEmpty, 'GetEndpoints', isAllOptional);
-}
-
-for (const endpointName of postEndpointNames) {
-    const returnType = responseNames.has(endpointName) ? `Promise<Readonly<Responses.${endpointName}>>` : 'Promise<void>';
-    const isEmpty = isInterfaceEmpty(endpointName, postEndpointsFile);
-    const isAllOptional = isInterfaceAllOptional(endpointName, postEndpointsFile);
-
-    makeMethod(endpointName, false, returnType, isEmpty, 'PostEndpoints', isAllOptional);
-}
-
+import { Project, SourceFile, Node, OptionalKind, MethodDeclarationStructure } from 'ts-morph';
+
+const project = new Project({
+    tsConfigFilePath: "tsconfig.json",
+});
+
+const isInterfaceEmpty = (interfaceName: string, sourceFile: SourceFile) => {
+    const declarations = sourceFile.getExportedDeclarations().get(interfaceName);
+    if (!declarations || declarations.length === 0) return false;
+
+    const decl = declarations[0];
+    if (!Node.isInterfaceDeclaration(decl)) return false;
+
+    const type = decl.getType();
+    const allProperties = type.getProperties();
+
+    return allProperties.length === 0;
+};
+
+
+const isInterfaceAllOptional = (name: string, sourceFile: SourceFile) => {
+    const iface = sourceFile.getInterface(name);
+    if (iface) {
+        return iface.getType().getProperties().every(p => p.isOptional());
+    }
+
+    const typeNode = sourceFile.getTypeAliasOrThrow(name).getType();
+    return typeNode
+        .getProperties()
+        .every(p => p.isOptional());
+};
+
+const baseClient = project.getSourceFileOrThrow('src/BaseClient.ts');
+const clientFile = project.createSourceFile('src/Client.ts', baseClient.getFullText(), { overwrite: true });
+const clientClass = clientFile.getClasses()[1];
+
+const getEndpointsFile = project.getSourceFileOrThrow('src/endpoints/endpoints.get.ts');
+const postEndpointsFile = project.getSourceFileOrThrow('src/endpoints/endpoints.post.ts');
+const responsesFile = project.getSourceFileOrThrow('src/responses.ts');
+
+const getEndpointNames = Array.from(getEndpointsFile.getExportedDeclarations().keys());
+const postEndpointNames = Array.from(postEndpointsFile.getExportedDeclarations().keys());
+
+const responseNames = new Set(Array.from(responsesFile.getExportedDeclarations().keys()));
+
+const makeMethod = (name: string, isStatic: boolean, returnType: string, isEmpty: boolean, interfaces: string, isOptional: boolean) => {
+    const method: OptionalKind<MethodDeclarationStructure> = {
+        name,
+        isStatic,
+        isAsync: true,
+        returnType,
+        statements: [`return await this.request('${name}'${!isEmpty ? ', params' : ''});`]
+    }
+    if (!isEmpty) method.parameters = [{
+        name: 'params',
+        type: `${interfaces}.${name}`,
+        hasQuestionToken: isOptional
+    }];
+
+    clientClass.addMethod(method);
+}
+
+for (const endpointName of getEndpointNames) {
+    const returnType = responseNames.has(endpointName) ? `Promise<Readonly<Responses.${endpointName}>>` : 'Promise<void>';
+    const isEmpty = isInterfaceEmpty(endpointName, getEndpointsFile);
+    const isAllOptional = isInterfaceAllOptional(endpointName, getEndpointsFile);
+
+    makeMethod(endpointName, false, returnType, isEmpty, 'GetEndpoints', isAllOptional);
+    makeMethod(endpointName, true, returnType, isEmpty, 'GetEndpoints', isAllOptional);
+}
+
+for (const endpointName of postEndpointNames) {
+    const returnType = responseNames.has(endpointName) ? `Promise<Readonly<Responses.${endpointName}>>` : 'Promise<void>';
+    const isEmpty = isInterfaceEmpty(endpointName, postEndpointsFile);
+    const isAllOptional = isInterfaceAllOptional(endpointName, postEndpointsFile);
+
+    makeMethod(endpointName, false, returnType, isEmpty, 'PostEndpoints', isAllOptional);
+}
+
 clientFile.saveSync();