chore: add getGitHubUser() JSDocs and test (denoland#545)

TSIA

plugins/kv_oauth.ts

@@ -18,22 +18,44 @@ import { isStripeEnabled, stripe } from "@/utils/stripe.ts";
 
 const oauth2Client = createGitHubOAuth2Client();
 
-// deno-lint-ignore no-explicit-any
-async function getGitHubUser(accessToken: string): Promise<any> {
+interface GitHubUser {
+  login: string;
+  email: string;
+}
+
+/**
+ * Returns the GitHub profile information of the user with the given access
+ * token.
+ *
+ * @see {@link https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user}
+ *
+ * @example
+ * ```ts
+ * import { getGitHubUser } from "@/plugins/kv_oauth.ts";
+ *
+ * const user = await getGitHubUser("<access token>");
+ * user.login; // Returns "octocat"
+ * user.email; // Returns "[email protected]"
+ * ```
+ */
+export async function getGitHubUser(accessToken: string) {
   const response = await fetch("https://api.github.com/user", {
     headers: { authorization: `Bearer ${accessToken}` },
   });
   if (!response.ok) {
     const { message } = await response.json();
     throw new Error(message);
   }
-  return await response.json();
+  return await response.json() as Promise<GitHubUser>;
 }
 
 /**
- * This custom plugin centralizes all authentication logic using the {@link https://deno.land/x/deno_kv_oauth|Deno KV OAuth} module.
+ * This custom plugin centralizes all authentication logic using the
+ * {@link https://deno.land/x/deno_kv_oauth|Deno KV OAuth} module.
  *
- * The implementation is based off Deno KV OAuth's own {@link https://deno.land/x/deno_kv_oauth/src/fresh_plugin.ts?source|Fresh plugin implementation}.
+ * The implementation is based off Deno KV OAuth's own
+ * {@link https://deno.land/x/deno_kv_oauth/src/fresh_plugin.ts?source|Fresh plugin}
+ * implementation.
  */
 export default {
   name: "kv-oauth",

plugins/kv_oauth_test.ts

@@ -0,0 +1,11 @@
+// Copyright 2023 the Deno authors. All rights reserved. MIT license.
+import { assertRejects } from "std/assert/assert_rejects.ts";
+import { getGitHubUser } from "./kv_oauth.ts";
+
+Deno.test("[plugins] getGitHubUser()", async () => {
+  await assertRejects(
+    async () => await getGitHubUser("access token"),
+    Error,
+    "Bad credentials",
+  );
+});