add docs and fix eslint issues

Author: sloanfinger

src/server/actions/signIn.ts

@@ -1,38 +1,23 @@
 "use server";
 
-import { headers } from "next/headers";
 import { notFound } from "next/navigation";
 import * as z from "zod";
-import { env } from "~/env";
 import { authenticate } from "../auth";
+import { getCallbackPath } from "../utilts";
 
-const callbackPathSchema = z.string().transform((path, ctx) => {
-  try {
-    const url = new URL(String(path), env.BASE_URL);
-    return url.toString().replace(url.origin, "");
-  } catch {
-    ctx.addIssue({
-      code: "custom",
-      message: "Provided string should be a path.",
-      input: path,
-    });
-    return z.NEVER;
-  }
-});
-
-const realmSchema = z.literal(["google", "discord", "github"]);
+const realmSchema = z.literal(["uga", "discord", "github"]);
 
+/**
+ * Begins the authentication flow for a user.
+ * @param formData Allows two fields.
+ * - `realm` is the authentication provider. Defaults to `"uga"`.
+ * - `callbackPath` is the path to redirect the user to after the action completes. Defaults to the value of the `referer` header if present or `/` if not.
+ */
 export default async function signIn(formData: FormData) {
+  const callbackPath = await getCallbackPath("/", formData);
   const realm = await realmSchema
     .parseAsync(formData.get("realm"))
-    .catch(() => "google" as const);
-    
-  const callbackPath = await callbackPathSchema
-    .parseAsync(formData.get("callbackPath"))
-    .catch(() =>
-      headers().then((h) => callbackPathSchema.parseAsync(h.get("referer"))),
-    )
-    .catch(() => undefined);
+    .catch(() => "uga" as const);
 
   await authenticate(realm, callbackPath);
 

src/server/auth/index.ts

@@ -42,8 +42,14 @@ export async function getSessionUser<
 const redirect_uri = new URL("/api/auth", env.BASE_URL).toString();
 const response_type = "code";
 
+/**
+ * Redirects the user to the appropriate OAuth consent URL.
+ * @param realm The authentication provider
+ * @param callbackPath Where to redirect the user after the authentication flow is complete (defaults to `/`)
+ * @see https://medium.com/codenx/oauth-2-0-4cddd6c7471f
+ */
 export async function authenticate(
-  realm: "google" | "discord" | "github",
+  realm: "uga" | "discord" | "github",
   callbackPath?: string,
 ) {
   const [insertedState] = await db
@@ -111,6 +117,20 @@ const searchParamsSchema = z
 
 const grant_type = "authorization_code";
 
+/**
+ * Next.js Route handler for an OAuth callback request.
+ * @param request The incoming request object, which expects two of three valid search parameters shown below.
+ *
+ * **Required always:**
+ * - `state` &mdash; The token identifying the current state of the authentication flow.
+ *
+ * **Requires exactly one of:**
+ * - `code` &mdash; During the standard OAuth flow, this value allows for retrieval of a user's `access_token`. The `access_token` will then be used to request profile information about the authenticated user, which will then be inserted into the database. If this is the user's first time signing in and they are using a realm other than `uga`, they will be redirected to authenticate with `uga` first. This second authentication request will use `/api/auth?state=...&linkProfile=...` as the callback path.
+ * - `linkProfile` &mdash; After a standard OAuth flow, this value allows for a user's non-`uga` profile to be linked to their newly created account.
+ *
+ * @returns never, when awaited (a `redirect()`, `notFound()`, or `unauthorized()` error will always be thrown)
+ * @see https://medium.com/codenx/oauth-2-0-4cddd6c7471f
+ */
 export async function handleOAuthRedirect(request: NextRequest) {
   const cookieStore = await cookies();
   const params = await searchParamsSchema
@@ -120,7 +140,9 @@ export async function handleOAuthRedirect(request: NextRequest) {
   const provider = providers[params.state.realm];
 
   if ("linkProfile" in params) {
-    if (provider.name === "google") {
+    // [Case 2] A user tried to sign in for the first time using a non-`uga` account. They've completed creaeting the UGA account, but we want to automatically link their non-`uga` profile to the `uga` user.
+
+    if (provider.name === "uga") {
       notFound();
     }
 
@@ -137,6 +159,7 @@ export async function handleOAuthRedirect(request: NextRequest) {
     redirect(params.state.callbackPath);
   }
 
+  // [Case 1] A user is following the standard OAuth flow. We request the `access_token` from the provider and get the associated profile data.
   const tokens = await fetch(provider.tokensRequest.url, {
     method: "POST",
     headers: {
@@ -154,14 +177,17 @@ export async function handleOAuthRedirect(request: NextRequest) {
     .then((res) => res.json())
     .then((obj) => tokenResultSchema.parseAsync(obj));
 
+  // We wait to parse the data so TypeScript can appropriately infer types.
   const profileData: unknown = await fetch(provider.profileRequest.url, {
     headers: {
       Accept: "application/json",
       Authorization: `Bearer ${tokens.accessToken}`,
     },
   }).then((res) => res.json());
 
-  if (provider.name === "google") {
+  if (provider.name === "uga") {
+    // [Case 1-1] The user is signing in with their `uga` account.
+
     const profile =
       await provider.profileRequest.validator.parseAsync(profileData);
 
@@ -172,6 +198,7 @@ export async function handleOAuthRedirect(request: NextRequest) {
             where: eq(users.email, profile.email),
             columns: { id: true },
           })) ??
+          // Case [1-1-1] The user does not already exist: insert them and return their ID.
           (await tx.insert(provider.table).values(profile).$returningId())[0];
 
         if (!user) {
@@ -204,6 +231,8 @@ export async function handleOAuthRedirect(request: NextRequest) {
     redirect(params.state.callbackPath);
   }
 
+  // [Case 1-2] The user is signing in with their non-`uga` account.
+
   const profile =
     await provider.profileRequest.validator.parseAsync(profileData);
   const sessionToken = cookieStore.get("session")?.value;
@@ -219,6 +248,7 @@ export async function handleOAuthRedirect(request: NextRequest) {
 
       const user =
         session?.user ??
+        // Case [1-2-1] The user does not currently have a session: find them using the linked profile ID.
         (await tx.query.users.findFirst({
           where: eq(users[provider.userRelationColumnName], profile.id),
         }));
@@ -234,6 +264,7 @@ export async function handleOAuthRedirect(request: NextRequest) {
         });
 
       if (!user) {
+        // Case [1-2-2] The user is signing in for the first time using a non-`uga` account: we can't create a session for them (yet) because there is no `user` to associate this profile with.
         return null;
       }
 
@@ -269,8 +300,9 @@ export async function handleOAuthRedirect(request: NextRequest) {
     });
 
   if (token === null) {
+    // Continued: [Case 1-2-2] Begin the authenticaiton flow using `uga`. See [Case 2].
     return await authenticate(
-      "google",
+      "uga",
       request.nextUrl.pathname +
         "?" +
         new URLSearchParams({

src/server/auth/providers.ts

@@ -8,34 +8,60 @@ import type { tokenResultSchema } from ".";
 interface OAuthProvider<
   Table extends Extract<(typeof schema)[keyof typeof schema], MySqlTable>,
 > {
+  /**
+   * Sent in consent and token requests as `client_id`.
+   */
   clientId: string;
+  /**
+   * Sent in token requests as `client_secret`.
+   */
   clientSecret: string;
+  /**
+   * Defines the base URL and additional search parameters (e.g., `scope`) for redirecting a user to begin the OAuth flow.
+   */
   consentRequest: {
     url: string;
     params: Record<string, string>;
   };
+  /**
+   * Defines the URL for requesting `access_token` (and, optionally, `refresh_token`) once a `code` has been provided.
+   */
   tokensRequest: {
     url: string;
   };
+  /**
+   * Defines the URL and response schema for requesting a user's profile information using `access_token`.
+   */
   profileRequest: {
     url: string;
     validator: z.ZodType<
       Omit<Table["$inferInsert"], keyof z.output<typeof tokenResultSchema>>
     >;
   };
+  /**
+   * Where to store a user's profile information.
+   */
   table: Table;
+  /**
+   * Which column to store the foreign-key relation between a user and the table where their profile information is stored.
+   */
   userRelationColumnName?: keyof (typeof schema)["users"]["$inferSelect"];
 }
 
+/**
+ * Helper function for defining compliant OAuth configurations.
+ * @param configuration The OAuth configuration.
+ * @returns `configuration`
+ */
 function OAuthProvider<
   const T extends Extract<(typeof schema)[keyof typeof schema], MySqlTable>,
   const C extends OAuthProvider<T>,
 >(configuration: C) {
   return configuration;
 }
 
-export const google = OAuthProvider({
-  name: "google",
+export const uga = OAuthProvider({
+  name: "uga",
   clientId: env.AUTH_GOOGLE_ID,
   clientSecret: env.AUTH_GOOGLE_SECRET,
   consentRequest: {

src/server/db/schema.ts

@@ -114,7 +114,7 @@ export const oauthStates = mysqlTable("oauth_states", (d) => ({
         "base64",
       ),
     ),
-  realm: d.mysqlEnum(["google", "discord", "github"]).notNull(),
+  realm: d.mysqlEnum(["uga", "discord", "github"]).notNull(),
   callbackPath: d.text().notNull().default("/"),
   createdAt: d.timestamp().defaultNow().notNull(),
 }));

src/server/discord/api.ts

@@ -1,13 +1,20 @@
 import { REST } from "@discordjs/rest";
 import { env } from "~/env";
 
+/**
+ * @param accessToken The access token for the user.
+ * @returns A discord.js REST API instance authenticated as a specific user.
+ */
 export function asUser(accessToken: string) {
   return new REST({
     authPrefix: "Bearer",
     version: "10",
   }).setToken(accessToken);
 }
 
+/**
+ * @returns A discord.js REST API instance authenticated as the RoboDog Discord bot.
+ */
 export function asBot() {
   return new REST({ version: "10" }).setToken(env.DISCORD_TOKEN);
 }

src/server/discord/index.ts

@@ -25,6 +25,9 @@ export function Command<T extends z.core.SomeType>(command: Command<T>) {
 
 const commands = [leaderboard] satisfies ReturnType<typeof Command>[];
 
+/**
+ * Registers all commands defined above in `commands`.
+ */
 export async function registerCommands() {
   const response = await fetch(
     `https://discord.com/api/v10/applications/${env.DISCORD_CLIENT_ID}/commands`,
@@ -49,6 +52,11 @@ export async function registerCommands() {
   }
 }
 
+/**
+ * A Next.js `POST` route handler.
+ * @param request The incoming request object.
+ * @returns The appropriate interaction response, considering all registered commands.
+ */
 export async function handleInteractionRequest(request: NextRequest) {
   const signature = request.headers.get("x-signature-ed25519");
   const timestamp = request.headers.get("x-signature-timestamp");

src/server/github/paginate.ts

@@ -2,10 +2,15 @@ import { requestInit } from ".";
 
 const nextPattern = /(?<=<)([\S]*)(?=>; rel="Next")/i;
 
+/**
+ * Paginate through resources in a fetch call to the GitHub API.
+ * @param fetchCall The initial fetch call to the GitHub API.
+ * @returns Async generator of Responses.
+ */
 export default async function* paginate(fetchCall: Promise<Response>) {
   let next: Promise<Response> | null = fetchCall;
 
-  while (next) {
+  while (next !== null) {
     const response: Response = await next;
     const nextUrl = response.headers.get("link")?.match(nextPattern)?.[0];
     yield response;

src/server/github/syncLeaderboard.ts

@@ -1,20 +1,19 @@
 import { sql } from "drizzle-orm";
 import { env } from "~/env";
+import isInRange from "~/lib/isBetween";
 import { requestInit } from ".";
 import { db } from "../db";
 import { githubProfiles } from "../db/schema";
 import paginate from "./paginate";
 import * as schema from "./schema";
-import { isBefore } from "date-fns";
-import isInRange from "~/lib/isBetween";
 
 function getProjectFields({ number }: { number: number }) {
   return fetch(
     `https://api.github.com/orgs/${env.GITHUB_ORG}/projectsV2/${number}/fields`,
     requestInit,
   )
     .then((res) => res.json())
-    .then(schema.fieldsResults.parseAsync)
+    .then((obj) => schema.fieldsResults.parseAsync(obj))
     .then((fields) => ({ number, fields }));
 }
 
@@ -56,7 +55,9 @@ async function calculatePoints({
   );
 
   for await (const response of pagination) {
-    const issues = await response.json().then(schema.issueResults.parseAsync);
+    const issues = await response
+      .json()
+      .then((obj) => schema.issueResults.parseAsync(obj));
 
     for (const { content, fields } of issues) {
       const points =
@@ -79,18 +80,16 @@ async function calculatePoints({
                 : 0),
             2024:
               (existingEntry?.points[2024] ?? 0) +
-              (isInRange([
-                env.AY2023_POINTS_CUTOFF,
-                env.AY2024_POINTS_CUTOFF],
+              (isInRange(
+                [env.AY2023_POINTS_CUTOFF, env.AY2024_POINTS_CUTOFF],
                 content.closed_at,
               )
                 ? points
                 : 0),
             2025:
               (existingEntry?.points[2025] ?? 0) +
-              (isInRange([
-                env.AY2024_POINTS_CUTOFF,
-                env.AY2025_POINTS_CUTOFF],
+              (isInRange(
+                [env.AY2024_POINTS_CUTOFF, env.AY2025_POINTS_CUTOFF],
                 content.closed_at,
               )
                 ? points
@@ -130,7 +129,7 @@ export default function syncLeaderboard() {
     requestInit,
   )
     .then((res) => res.json())
-    .then(schema.projectResults.parseAsync)
+    .then((obj) => schema.projectResults.parseAsync(obj))
     .then((projects) => Promise.allSettled(projects.map(getProjectFields)))
     .then((results) =>
       Promise.allSettled(

src/server/utilts.ts

@@ -16,6 +16,12 @@ const callbackPathSchema = z.string().transform((path, ctx) => {
   }
 });
 
+/**
+ * Extracts a callback path from either the `callbackPath` field in `formData` or the `referer` field in the incoming request headers.
+ * @param fallback Used if `callbackPath` is not present in `formData` or `referer` is not present in `headers()`.
+ * @param formData A `FormData` obect.
+ * @returns The extracted callback path.
+ */
 export async function getCallbackPath(
   fallback: string,
   formData?: FormData,