feat: some more docs

packages/website-ue/src/components/ApiMacroType.astro

@@ -29,12 +29,11 @@ interface Props {
 const { value, locale } = Astro.props;
 const strings = await api.strings(locale);
 
+const lang = "ts";
 const roots = ["src/protos", "../closed/protos"];
 
-const lang = "ts";
-
-const name = "Avatar";
-const path = resolve(`${roots[0]}/${value}.ts`);
+const [route, name] = value.split(".");
+const path = resolve(`${roots[0]}/${route}.ts`);
 
 const program = createProgram([path], {});
 const source = program.getSourceFile(path);

packages/website-ue/src/core/api/abstract.ts

@@ -1,6 +1,7 @@
 import type { Strings } from "@blitzkit/i18n";
 import locales from "@blitzkit/i18n/locales.json";
 import type { Avatar } from "../../protos/avatar";
+import type { AvatarList } from "../../protos/avatar_list";
 import type { Avatars } from "../../protos/avatars";
 import type { Background } from "../../protos/background";
 import type { Backgrounds } from "../../protos/backgrounds";
@@ -130,6 +131,16 @@ export abstract class AbstractAPI {
     return this._avatarsCache;
   }
 
+  private _avatarListCache: AvatarList | undefined;
+  protected abstract _avatarList(): Promise<AvatarList>;
+  async avatarList() {
+    if (this._avatarListCache === undefined) {
+      this._avatarListCache = await this._avatarList();
+    }
+
+    return this._avatarListCache;
+  }
+
   private _backgroundCache: Record<string, Background> = {};
   protected abstract _background(id: string): Promise<Background>;
   async background(id: string) {

packages/website-ue/src/core/api/server.ts

@@ -193,6 +193,13 @@ export class ServerAPI extends AbstractAPI {
     return { avatars };
   }
 
+  protected async _avatarList() {
+    const avatars = await this.avatars();
+    const list = Object.keys(avatars.avatars);
+
+    return { list };
+  }
+
   protected async _avatar(id: string) {
     const avatar = this.metadata.item(`ProfileAvatarEntity.${id}`);
     const name = avatar.name;

packages/website-ue/src/pages/api/avatars/[id].json.ts

@@ -16,7 +16,7 @@ export const getStaticPaths = (async () => {
  *
  * @see avatars/list.json for all avatar ids.
  * @see avatars/[id].webp for avatar images.
- * @type avatar
+ * @type avatar.Avatar
  */
 export async function GET({ params }: APIContext<never, { id: string }>) {
   const avatar = await api.avatar(params.id);

packages/website-ue/src/pages/api/avatars/[id].webp.ts

@@ -4,6 +4,12 @@ import { imageProxy } from "../../../core/api/imageProxy";
 
 export { getStaticPaths } from "./[id].json";
 
+/**
+ * Returns an avatar image based on its `id` in the `webp` format.
+ *
+ * @see avatars/list.json for all avatar ids.
+ * @see avatars/[id].json for data on all avatar.
+ */
 export async function GET({ params }: APIContext<never, { id: string }>) {
   const avatar = await api.avatar(params.id);
   return await imageProxy(avatar.profile_avatar!.avatar);

packages/website-ue/src/pages/api/avatars/all.json.ts

@@ -1,5 +1,11 @@
 import { api } from "../../../core/api/dynamic";
 
+/**
+ * Identical to `avatars/[id].json`, but returns data on all avatars at once,
+ * mapped by `id`. Beware, the returned `JSON` is large.
+ *
+ * @type avatars.Avatars
+ */
 export async function GET() {
   const avatars = await api.avatars();
   return Response.json(avatars);

packages/website-ue/src/pages/api/avatars/list.json.ts

@@ -1,7 +1,9 @@
 import { api } from "../../../core/api/dynamic";
 
+/**
+ * @type avatar_list.AvatarList
+ */
 export async function GET() {
-  const { avatars } = await api.avatars();
-  const list = avatars.map((avatar) => avatar.name);
+  const list = await api.avatarList();
   return Response.json(list);
 }

packages/website-ue/src/protos/avatar_list.proto

@@ -0,0 +1,7 @@
+syntax = "proto3";
+
+package blitzkit;
+
+message AvatarList {
+  repeated string list = 1;
+}