Add return types for api methods, update some docs/comments

Author: DayKev

src/plugins/api/account-api.ts

@@ -8,9 +8,7 @@ import type {
 } from "#types/api-types";
 import { removeCookie, setCookie } from "#utils/app-utils";
 
-/**
- * A wrapper for the account API requests.
- */
+/** A wrapper for the account API requests. */
 export class AccountApi extends ApiBase {
   //#region Public
 
@@ -39,7 +37,7 @@ export class AccountApi extends ApiBase {
    * @param registerData The {@linkcode AccountRegisterRequest} to send
    * @returns An error message if something went wrong
    */
-  public async register(registerData: AccountRegisterRequest) {
+  public async register(registerData: AccountRegisterRequest): Promise<string | null> {
     try {
       const response = await this.doPost("/account/register", registerData, "form-urlencoded");
 
@@ -60,7 +58,7 @@ export class AccountApi extends ApiBase {
    * @param loginData The {@linkcode AccountLoginRequest} to send
    * @returns An error message if something went wrong
    */
-  public async login(loginData: AccountLoginRequest) {
+  public async login(loginData: AccountLoginRequest): Promise<string | null> {
     try {
       const response = await this.doPost("/account/login", loginData, "form-urlencoded");
 
@@ -82,7 +80,7 @@ export class AccountApi extends ApiBase {
    * Send a logout request.
    * **Always** (no matter if failed or not) removes the session cookie.
    */
-  public async logout() {
+  public async logout(): Promise<void> {
     try {
       const response = await this.doGet("/account/logout");
 
@@ -95,4 +93,6 @@ export class AccountApi extends ApiBase {
 
     removeCookie(SESSION_ID_COOKIE); // we are always clearing the cookie.
   }
+
+  //#endregion
 }

src/plugins/api/admin-api.ts

@@ -16,7 +16,7 @@ export class AdminApi extends ApiBase {
    * @param params The {@linkcode LinkAccountToDiscordIdRequest} to send
    * @returns `null` if successful, error message if not
    */
-  public async linkAccountToDiscord(params: LinkAccountToDiscordIdRequest) {
+  public async linkAccountToDiscord(params: LinkAccountToDiscordIdRequest): Promise<string | null> {
     try {
       const response = await this.doPost("/admin/account/discordLink", params, "form-urlencoded");
 
@@ -40,7 +40,7 @@ export class AdminApi extends ApiBase {
    * @param params The {@linkcode UnlinkAccountFromDiscordIdRequest} to send
    * @returns `null` if successful, error message if not
    */
-  public async unlinkAccountFromDiscord(params: UnlinkAccountFromDiscordIdRequest) {
+  public async unlinkAccountFromDiscord(params: UnlinkAccountFromDiscordIdRequest): Promise<string | null> {
     try {
       const response = await this.doPost("/admin/account/discordUnlink", params, "form-urlencoded");
 
@@ -64,7 +64,7 @@ export class AdminApi extends ApiBase {
    * @param params The {@linkcode LinkAccountToGoogledIdRequest} to send
    * @returns `null` if successful, error message if not
    */
-  public async linkAccountToGoogleId(params: LinkAccountToGoogledIdRequest) {
+  public async linkAccountToGoogleId(params: LinkAccountToGoogledIdRequest): Promise<string | null> {
     try {
       const response = await this.doPost("/admin/account/googleLink", params, "form-urlencoded");
 
@@ -88,7 +88,7 @@ export class AdminApi extends ApiBase {
    * @param params The {@linkcode UnlinkAccountFromGoogledIdRequest} to send
    * @returns `null` if successful, error message if not
    */
-  public async unlinkAccountFromGoogleId(params: UnlinkAccountFromGoogledIdRequest) {
+  public async unlinkAccountFromGoogleId(params: UnlinkAccountFromGoogledIdRequest): Promise<string | null> {
     try {
       const response = await this.doPost("/admin/account/googleUnlink", params, "form-urlencoded");
 

src/plugins/api/api-base.ts

@@ -10,19 +10,21 @@ export abstract class ApiBase {
 
   protected readonly base: string;
 
+  //#endregion
   //#region Public
 
   constructor(base: string) {
     this.base = base;
   }
 
+  //#endregion
   //#region Protected
 
   /**
    * Send a GET request.
    * @param path The path to send the request to.
    */
-  protected async doGet(path: string) {
+  protected async doGet(path: string): Promise<Response> {
     return this.doFetch(path, { method: "GET" });
   }
 
@@ -32,7 +34,7 @@ export abstract class ApiBase {
    * @param bodyData The body-data to send.
    * @param dataType The data-type of the {@linkcode bodyData}.
    */
-  protected async doPost<D = undefined>(path: string, bodyData?: D, dataType: DataType = "json") {
+  protected async doPost<D = undefined>(path: string, bodyData?: D, dataType: DataType = "json"): Promise<Response> {
     let body: string | undefined;
     const headers: HeadersInit = {};
 
@@ -83,11 +85,13 @@ export abstract class ApiBase {
    * @param data the data to transform to {@linkcode URLSearchParams}
    * @returns a {@linkcode URLSearchParams} representaton of {@linkcode data}
    */
-  protected toUrlSearchParams<D extends Record<string, any>>(data: D) {
+  protected toUrlSearchParams<D extends Record<string, any>>(data: D): URLSearchParams {
     const arr = Object.entries(data)
       .map(([key, value]) => [key, String(value ?? "")])
       .filter(([, value]) => value !== "");
 
     return new URLSearchParams(arr);
   }
+
+  //#endregion
 }

src/plugins/api/api.ts

@@ -5,9 +5,7 @@ import { DailyApi } from "#api/daily-api";
 import { SavedataApi } from "#api/savedata-api";
 import type { TitleStatsResponse } from "#types/api-types";
 
-/**
- * A wrapper for API requests.
- */
+/** A wrapper for API requests. */
 class Api extends ApiBase {
   //#region Fields
 
@@ -21,6 +19,7 @@ class Api extends ApiBase {
   /** Whether the server/api is connected. By default we assume `true`. */
   private _isConnected: boolean;
 
+  //#endregion
   //#region Public
 
   constructor(base: string) {
@@ -32,14 +31,14 @@ class Api extends ApiBase {
   }
 
   /** Whether the server/api is connected. By default we assume `true`. */
-  public get isConnected() {
+  public get isConnected(): boolean {
     return this._isConnected;
   }
 
   /**
    * Request game title-stats.
    */
-  public async getGameTitleStats() {
+  public async getGameTitleStats(): Promise<TitleStatsResponse | null> {
     if (!this.isConnected) {
       this.printServerNotConnectedWarning();
       return null;
@@ -58,7 +57,7 @@ class Api extends ApiBase {
    * Unlink the currently logged in user from Discord.
    * @returns `true` if unlinking was successful, `false` if not
    */
-  public async unlinkDiscord() {
+  public async unlinkDiscord(): Promise<boolean> {
     if (!this.isConnected) {
       this.printServerNotConnectedWarning();
       return false;
@@ -81,7 +80,7 @@ class Api extends ApiBase {
    * Unlink the currently logged in user from Google.
    * @returns `true` if unlinking was successful, `false` if not
    */
-  public async unlinkGoogle() {
+  public async unlinkGoogle(): Promise<boolean> {
     if (!this.isConnected) {
       this.printServerNotConnectedWarning();
       return false;
@@ -105,7 +104,7 @@ class Api extends ApiBase {
    * @remarks
    * We have no dedicated ping/status endpoint yet, so we ping the game title stats endpoint, but without printing any errors by default.
    */
-  async ping() {
+  public async ping(): Promise<void> {
     try {
       const response = await this.doGet("/game/titlestats");
       const data = await response.json();
@@ -125,7 +124,7 @@ class Api extends ApiBase {
   //#endregion
   //#region Private
 
-  private printServerNotConnectedWarning() {
+  private printServerNotConnectedWarning(): void {
     if (import.meta.env.VITE_API_DEBUG === "1") {
       console.warn(this.ERR_SERVER_NOT_CONNECTED);
     }

src/plugins/api/daily-api.ts

@@ -1,16 +1,14 @@
 import { ApiBase } from "#api/api-base";
 
-/**
- * A wrapper for daily-run API requests.
- */
+/** A wrapper for daily-run API requests. */
 export class DailyApi extends ApiBase {
   //#region Public
 
   /**
    * Request the daily-run seed.
    * @returns The active daily-run seed as `string`.
    */
-  public async getSeed() {
+  public async getSeed(): Promise<string | null> {
     try {
       const response = await this.doGet("/daily/seed");
       return response.text();
@@ -19,4 +17,6 @@ export class DailyApi extends ApiBase {
       return null;
     }
   }
+
+  //#endregion
 }

src/plugins/api/savedata-api.ts

@@ -4,15 +4,14 @@ import { SystemSavedataApi } from "#api/system-savedata-api";
 import { MAX_INT_ATTR_VALUE } from "#constants/game-constants";
 import type { UpdateAllSavedataRequest } from "#types/api-types";
 
-/**
- * A wrapper for savedata API requests.
- */
+/** A wrapper for savedata API requests. */
 export class SavedataApi extends ApiBase {
   //#region Fields
 
   public readonly system: SystemSavedataApi;
   public readonly session: SessionSavedataApi;
 
+  //#endregion
   //#region Public
 
   constructor(base: string) {
@@ -26,7 +25,7 @@ export class SavedataApi extends ApiBase {
    * @param bodyData The {@linkcode UpdateAllSavedataRequest | request data} to send
    * @returns An error message if something went wrong
    */
-  public async updateAll(bodyData: UpdateAllSavedataRequest) {
+  public async updateAll(bodyData: UpdateAllSavedataRequest): Promise<string> {
     try {
       const rawBodyData = JSON.stringify(bodyData, (_k: any, v: any) => {
         if (typeof v === "bigint") {
@@ -41,4 +40,6 @@ export class SavedataApi extends ApiBase {
       return "Unknown error";
     }
   }
+
+  //#endregion
 }

src/plugins/api/session-savedata-api.ts

@@ -9,9 +9,7 @@ import type {
 } from "#types/api-types";
 import type { SessionSaveData } from "#types/session-data";
 
-/**
- * A wrapper for session savedata API requests.
- */
+/** A wrapper for session savedata API requests. */
 export class SessionSavedataApi extends ApiBase {
   //#region Public
 
@@ -40,7 +38,7 @@ export class SessionSavedataApi extends ApiBase {
    * @param params The {@linkcode GetSessionSavedataRequest} to send
    * @returns The session as `string`
    */
-  public async get(params: GetSessionSavedataRequest) {
+  public async get(params: GetSessionSavedataRequest): Promise<string | null> {
     try {
       const urlSearchParams = this.toUrlSearchParams(params);
       const response = await this.doGet(`/savedata/session/get?${urlSearchParams}`);
@@ -58,7 +56,7 @@ export class SessionSavedataApi extends ApiBase {
    * @param rawSavedata The raw savedata (as `string`)
    * @returns An error message if something went wrong
    */
-  public async update(params: UpdateSessionSavedataRequest, rawSavedata: string) {
+  public async update(params: UpdateSessionSavedataRequest, rawSavedata: string): Promise<string> {
     try {
       const urlSearchParams = this.toUrlSearchParams(params);
       const response = await this.doPost(`/savedata/session/update?${urlSearchParams}`, rawSavedata);
@@ -76,7 +74,7 @@ export class SessionSavedataApi extends ApiBase {
    * @param params The {@linkcode DeleteSessionSavedataRequest} to send
    * @returns An error message if something went wrong
    */
-  public async delete(params: DeleteSessionSavedataRequest) {
+  public async delete(params: DeleteSessionSavedataRequest): Promise<string | null> {
     try {
       const urlSearchParams = this.toUrlSearchParams(params);
       const response = await this.doGet(`/savedata/session/delete?${urlSearchParams}`);
@@ -98,7 +96,10 @@ export class SessionSavedataApi extends ApiBase {
    * @param params The {@linkcode ClearSessionSavedataRequest} to send
    * @param sessionData The {@linkcode SessionSaveData} object
    */
-  public async clear(params: ClearSessionSavedataRequest, sessionData: SessionSaveData) {
+  public async clear(
+    params: ClearSessionSavedataRequest,
+    sessionData: SessionSaveData,
+  ): Promise<ClearSessionSavedataResponse> {
     try {
       const urlSearchParams = this.toUrlSearchParams(params);
       const response = await this.doPost(`/savedata/session/clear?${urlSearchParams}`, sessionData);
@@ -113,4 +114,6 @@ export class SessionSavedataApi extends ApiBase {
       success: false,
     } as ClearSessionSavedataResponse;
   }
+
+  //#endregion
 }

src/plugins/api/system-savedata-api.ts

@@ -5,19 +5,18 @@ import type {
   VerifySystemSavedataRequest,
   VerifySystemSavedataResponse,
 } from "#types/api-types";
+import type { SystemSaveData } from "#types/system-data";
 
-/**
- * A wrapper for system savedata API requests.
- */
+/** A wrapper for system savedata API requests. */
 export class SystemSavedataApi extends ApiBase {
   //#region Public
 
   /**
-   * Get a system savedata.
-   * @param params The {@linkcode GetSystemSavedataRequest} to send
-   * @returns The system savedata as `string` or `null` on error
+   * Get the system savedata.
+   * @param params - The {@linkcode GetSystemSavedataRequest} to send
+   * @returns The system savedata as `string`, or `null` on error
    */
-  public async get(params: GetSystemSavedataRequest) {
+  public async get(params: GetSystemSavedataRequest): Promise<string | null> {
     try {
       const urlSearchParams = this.toUrlSearchParams(params);
       const response = await this.doGet(`/savedata/system/get?${urlSearchParams}`);
@@ -32,13 +31,12 @@ export class SystemSavedataApi extends ApiBase {
 
   /**
    * Verify if the session is valid.
-   * If not the {@linkcode SystemSaveData} is returned.
-   * @param params The {@linkcode VerifySystemSavedataRequest} to send
+   * If not, the `SystemSaveData` is returned.
+   * @param params - The {@linkcode VerifySystemSavedataRequest} to send
    * @returns A {@linkcode SystemSaveData} if **NOT** valid, otherwise `null`.
-   *
-   * TODO: add handling for errors
    */
-  public async verify(params: VerifySystemSavedataRequest) {
+  // TODO: add handling for errors
+  public async verify(params: VerifySystemSavedataRequest): Promise<SystemSaveData | null> {
     const urlSearchParams = this.toUrlSearchParams(params);
     const response = await this.doGet(`/savedata/system/verify?${urlSearchParams}`);
 
@@ -57,12 +55,12 @@ export class SystemSavedataApi extends ApiBase {
   }
 
   /**
-   * Update a system savedata.
-   * @param params The {@linkcode UpdateSystemSavedataRequest} to send
-   * @param rawSystemData The raw {@linkcode SystemSaveData}
+   * Update the system savedata.
+   * @param params - The {@linkcode UpdateSystemSavedataRequest} to send
+   * @param rawSystemData - The raw {@linkcode SystemSaveData}
    * @returns An error message if something went wrong
    */
-  public async update(params: UpdateSystemSavedataRequest, rawSystemData: string) {
+  public async update(params: UpdateSystemSavedataRequest, rawSystemData: string): Promise<string> {
     try {
       const urSearchParams = this.toUrlSearchParams(params);
       const response = await this.doPost(`/savedata/system/update?${urSearchParams}`, rawSystemData);
@@ -74,4 +72,6 @@ export class SystemSavedataApi extends ApiBase {
 
     return "Unknown Error";
   }
+
+  //#endregion
 }