docs: rewrite the AOTW endpoint documentation (#6)

Author: wescopeland

docs/.vitepress/config.mts

@@ -43,10 +43,6 @@ export default defineConfig({
         text: "Feed",
         collapsible: true,
         items: [
-          {
-            text: "Achievement of the Week",
-            link: "/v1/feed/get-achievement-of-the-week",
-          },
           {
             text: "Claims",
             link: "/v1/feed/get-claims",
@@ -169,6 +165,15 @@ export default defineConfig({
           },
         ],
       },
+      {
+        text: "Events",
+        items: [
+          {
+            text: "Achievement of the Week",
+            link: "/v1/events/achievement-of-the-week",
+          },
+        ],
+      },
       {
         text: "Tickets",
         collapsible: true,

docs/components/SampleRequest.vue

@@ -0,0 +1,47 @@
+<script setup>
+import { computed, defineProps } from "vue";
+
+const props = defineProps({
+  httpVerb: {
+    type: String,
+    required: true,
+    validator: (value) =>
+      ["GET", "POST", "PUT", "PATCH", "DELETE"].includes(value),
+  },
+});
+
+const verbClass = computed(() => {
+  switch (props.httpVerb) {
+    case "GET":
+      return "bg-green-600";
+    case "POST":
+      return "bg-blue-600";
+    case "PUT":
+      return "bg-purple-600";
+    case "PATCH":
+      return "bg-yellow-600";
+    case "DELETE":
+      return "bg-red-600";
+    default:
+      return "bg-neutral-600";
+  }
+});
+</script>
+
+<template>
+  <div
+    class="-mx-6 overflow-y-auto px-5 py-2 sm:mx-0 sm:px-4 my-1 bg-neutral-100 sm:rounded-lg dark:bg-neutral-950"
+  >
+    <div class="flex gap-x-4 sm:gap-x-2 items-center text-sm">
+      <div
+        :class="`${verbClass} text-white text-xs font-bold rounded-full px-2 py-0.5`"
+      >
+        {{ props.httpVerb }}
+      </div>
+
+      <p class="font-semibold">
+        <slot></slot>
+      </p>
+    </div>
+  </div>
+</template>

docs/public/aotw.png

@@ -0,0 +1,125 @@
+<script setup>
+import SampleRequest from '../../components/SampleRequest.vue';
+</script>
+
+# Achievement of the Week
+
+A call to this endpoint will retrieve comprehensive metadata about the current Achievement of the Week. The current achievement of the week can be found on the site's home page:
+
+![AOTW](/aotw.png)
+
+## HTTP Request
+
+<SampleRequest httpVerb="GET">https://retroachievements.org/API/API_GetAchievementOfTheWeek.php</SampleRequest>
+
+### Query Parameters
+
+| Name | Description       |
+| :--- | :---------------- |
+| `z`  | Your username.    |
+| `y`  | Your web API key. |
+
+## Client Library
+
+::: code-group
+
+```ts [NodeJS]
+import {
+  buildAuthorization,
+  getAchievementOfTheWeek,
+} from "@retroachievements/api";
+
+// First, build your authorization object.
+const userName = "<your username on RA>";
+const webApiKey = "<your web API key>";
+
+const authorization = buildAuthorization({ userName, webApiKey });
+
+// Then, make the API call.
+const achievementOfTheWeek = await getAchievementOfTheWeek(authorization);
+```
+
+:::
+
+## Response
+
+::: code-group
+
+```json [HTTP Response]
+{
+  "Achievement": {
+    "ID": 178634,
+    "Title": "Saved Summer",
+    "Description": "Defeat the Flower and let Summer Get Busy",
+    "Points": 10,
+    "TrueRatio": 11,
+    "Type": null,
+    "Author": "StingX2",
+    "DateCreated": "2021-10-16 23:53:32",
+    "DateModified": "2021-10-17 19:26:09"
+  },
+  "Console": {
+    "ID": 3,
+    "Title": "SNES"
+  },
+  "ForumTopic": {
+    "ID": 19685
+  },
+  "Game": {
+    "ID": 2865,
+    "Title": "~Hack~ Plumber For All Seasons, A"
+  },
+  "StartAt": "2023-10-23T00:00:00.000000Z",
+  "TotalPlayers": 427,
+  "Unlocks": [
+    {
+      "User": "Agnam",
+      "RAPoints": 56120,
+      "DateAwarded": "2023-10-26T22:13:34.000000Z",
+      "HardcoreMode": 1
+    }
+    // ...
+  ],
+  "UnlocksCount": 280,
+  "UnlocksHardcoreCount": 268
+}
+```
+
+```json [NodeJS]
+{
+  "achievement": {
+    "id": "165062",
+    "title": "The True Hero",
+    "description": "Receive any Ending as Han [Normal or Hard]",
+    "points": "10",
+    "trueRatio": "22",
+    "author": "BigWeedSmokerMan",
+    "dateCreated": "2021-08-08 17:47:46",
+    "dateModified": "2021-08-09 12:20:05"
+  },
+  "console": { "id": "39", "title": "Saturn" },
+  "forumTopic": { "id": "14767" },
+  "game": { "id": "14513", "title": "Guardian Heroes" },
+  "startAt": "2022-10-10 00:00:00",
+  "totalPlayers": "219",
+  "unlocks": [
+    {
+      "user": "Tirbaba2",
+      "rAPoints": "72",
+      "dateAwarded": "2022-10-10 01:42:19",
+      "hardcoreMode": "1"
+    }
+    // ...
+  ],
+  "unlocksCount": "40"
+}
+```
+
+:::
+
+## Source
+
+| Repo                     | URL                                                                                               |
+| :----------------------- | :------------------------------------------------------------------------------------------------ |
+| RetroAchievements/RAWeb  | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementOfTheWeek.php |
+| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/feed/getAchievementOfTheWeek.ts         |

docs/v1/events/achievement-of-the-week.md

@@ -18,15 +18,16 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "vitepress": "^1.0.0-rc.32"
+    "vitepress": "^1.0.0-rc.32",
+    "vue": "^3.3.13"
   },
   "devDependencies": {
     "husky": "^8.0.3",
     "lint-staged": "^15.2.0",
-    "prettier": "^3.1.1",
-    "tailwindcss": "^3.4.0",
     "postcss-flexbugs-fixes": "^5.0.2",
-    "postcss-preset-env": "^7.7.2"
+    "postcss-preset-env": "^7.7.2",
+    "prettier": "^3.1.1",
+    "tailwindcss": "^3.4.0"
   },
   "lint-staged": {
     "*.{json,md,js,ts,tsx}": "prettier --write"

docs/v1/feed/get-achievement-of-the-week.md

@@ -2,6 +2,7 @@ module.exports = {
   darkMode: "class",
   content: [
     "./docs/**/*.{html,js,vue,ts,md,mdx}",
+    "./docs/components/**/*.{html,js,vue,ts,md,mdx}",
     "./docs/.vitepress/**/*.{html,js,vue,ts,md,mdx}",
   ],
 };