@retroachievements/api 0.0.0-development

package/src/utils/internal/serializeProperties.ts

@@ -0,0 +1,75 @@
+/* eslint-disable sonarjs/cognitive-complexity */
+/* eslint-disable sonarjs/prefer-immediate-return */
+
+export const serializeProperties = (
+  originalData: any,
+  options: Partial<{
+    shouldCastToNumbers: string[];
+    shouldMapToBooleans: string[];
+  }> = {}
+) => {
+  const { shouldCastToNumbers, shouldMapToBooleans } = options;
+
+  let returnValue = originalData;
+
+  if (Array.isArray(originalData)) {
+    const cleanedArray: any[] = [];
+
+    for (const entity of originalData) {
+      cleanedArray.push(serializeProperties(entity, options));
+    }
+
+    returnValue = cleanedArray;
+  } else if (!Array.isArray(originalData) && originalData instanceof Object) {
+    let cleanedObject: Record<string, any> = {};
+
+    for (const [originalKey, originalValue] of Object.entries(originalData)) {
+      let sanitizedValue = originalValue;
+      if (shouldCastToNumbers?.includes(originalKey)) {
+        sanitizedValue = Number(originalValue);
+      }
+
+      if (shouldMapToBooleans?.includes(originalKey)) {
+        if (originalValue === null) {
+          sanitizedValue = null;
+        } else {
+          sanitizedValue = originalValue === "1" ? true : false;
+        }
+      }
+
+      cleanedObject = {
+        ...cleanedObject,
+        [naiveCamelCase(originalKey)]: serializeProperties(
+          sanitizedValue,
+          options
+        )
+      };
+    }
+
+    returnValue = cleanedObject;
+  }
+
+  return returnValue;
+};
+
+const naiveCamelCase = (originalValue: string) => {
+  // "ID" --> "id", "URL" --> "url"
+  if (originalValue.toUpperCase() === originalValue) {
+    return originalValue.toLowerCase();
+  }
+
+  // "GameID" -> "gameID"
+  let camelCased =
+    originalValue.charAt(0).toLowerCase() + originalValue.slice(1);
+
+  // "gameID" -> "gameId"
+  camelCased = camelCased.replace(/ID/g, "Id");
+
+  // "badgeURL" --> "badgeUrl"
+  camelCased = camelCased.replace(/URL/g, "Url");
+
+  // "rAPoints" -> "raPoints"
+  camelCased = camelCased.replace(/rA/g, "ra");
+
+  return camelCased;
+};

package/src/utils/public/buildAuthorization.test.ts

@@ -0,0 +1,36 @@
+import { buildAuthorization } from "./buildAuthorization";
+
+describe("Util: buildAuthorization", () => {
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(buildAuthorization).toBeDefined();
+  });
+
+  it("returns the same object it is given", () => {
+    // ARRANGE
+    const myAuth = {
+      userName: "myUserName",
+      webApiKey: "myWebApiKey"
+    };
+
+    // ACT
+    const authorization = buildAuthorization(myAuth);
+
+    // ASSERT
+    expect(authorization).toEqual(myAuth);
+  });
+
+  it("throws an error if missing a userName", () => {
+    // ASSERT
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore - We're assuming the user is not using a TypeScript project.
+    expect(() => buildAuthorization({ webApiKey: "mockWebApiKey" })).toThrow();
+  });
+
+  it("throws an error if missing a webApiKey", () => {
+    // ASSERT
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore - We're assuming the user is not using a TypeScript project.
+    expect(() => buildAuthorization({ userName: "mockUserName" })).toThrow();
+  });
+});

package/src/utils/public/buildAuthorization.ts

@@ -0,0 +1,40 @@
+import type { AuthObject } from "./models";
+
+/**
+ * Accepts your RetroAchievements.org userName and web API key. After
+ * receiving these inputs, the function returns you a value that can be
+ * used for the authentication parameter by any of the async calls in this
+ * library.
+ *
+ * Your account's personal Web API Key can be found on the Settings page
+ * of RetroAchievements.org. Do not use a Web API Key that is not associated
+ * with your account.
+ *
+ * @returns An `AuthObject` that you can pass to any of the API call functions.
+ *
+ * @example
+ * ```
+ * const authorization = buildAuthorization({
+ *   userName: "Scott",
+ *   webApiKey: "LtjCwW16nJI7cqOyPIQtXk8v1cfF0tmO"
+ * });
+ * ```
+ */
+export const buildAuthorization = (options: AuthObject): AuthObject => {
+  if (!options.userName || !options.webApiKey) {
+    throw new Error(`
+      buildAuthorization() requires an object containing a
+      userName and webApiKey. eg:
+
+      const authorization = buildAuthorization({
+        userName: "myUserName",
+        webApiKey: "myWebApiKey"
+      })
+    `);
+  }
+
+  return options;
+};
+
+// This function simply returns what it's given, however the return
+// value has the added benefit of type safety.

package/src/utils/public/index.ts

@@ -0,0 +1,3 @@
+export { call as unsafe_call } from "../internal/call";
+export * from "./buildAuthorization";
+export * from "./models";

package/src/utils/public/models/auth-object.model.ts

@@ -0,0 +1,20 @@
+/**
+ * Each RetroAchievements API call is uniquely authenticated
+ * using a userName + API key combination. Your account's personal
+ * Web API Key can be found on the Settings page.
+ */
+export interface AuthObject {
+  /**
+   * You or your app's exact username on the RetroAchievements.org website.
+   * For example, https://retroachievements.org/user/Scott would have a value
+   * of "Scott".
+   */
+  userName: string;
+
+  /**
+   * This can be found in the "Keys" section of your Settings page on the
+   * RetroAchievements.org website. This is a 32-digit alphanumeric key
+   * that is case-sensitive.
+   */
+  webApiKey: string;
+}

package/src/utils/public/models/index.ts

@@ -0,0 +1 @@
+export * from "./auth-object.model";