From 937363c9ee88d129ca2a5040cee995890c1a5c38 Mon Sep 17 00:00:00 2001
From: stringsplit <77242831+nbitzz@users.noreply.github.com>
Date: Tue, 3 Oct 2023 13:21:28 -0700
Subject: [PATCH] TSDoc: mail.ts, middleware.ts, ratelimit.ts

---
 src/server/lib/mail.ts       |  7 +++++++
 src/server/lib/middleware.ts | 17 +++++++++++++----
 src/server/lib/ratelimit.ts  |  9 +++++++--
 3 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/src/server/lib/mail.ts b/src/server/lib/mail.ts
index 4fdbb3e..bd9ce07 100644
--- a/src/server/lib/mail.ts
+++ b/src/server/lib/mail.ts
@@ -19,6 +19,13 @@ transport =
 
 // lazy but
 
+/**
+ * @description Sends an email
+ * @param to Target email address
+ * @param subject Email subject
+ * @param content Email content
+ * @returns Promise which resolves to the output from nodemailer.transport.sendMail
+ */
 export function sendMail(to: string, subject: string, content: string) {
     return new Promise((resolve,reject) => {
         transport.sendMail({
diff --git a/src/server/lib/middleware.ts b/src/server/lib/middleware.ts
index 9a1a542..2d312ad 100644
--- a/src/server/lib/middleware.ts
+++ b/src/server/lib/middleware.ts
@@ -3,11 +3,17 @@ import express, { type RequestHandler } from "express"
 import ServeError from "../lib/errors";
 import * as auth from "./auth";
 
+/**
+ * @description Middleware which adds an account, if any, to res.locals.acc 
+ */
 export const getAccount: RequestHandler = function(req, res, next) {
     res.locals.acc = Accounts.getFromToken(auth.tokenFor(req))
     next()
 }
 
+/**
+ * @description Middleware which blocks requests which do not have res.locals.acc set
+ */
 export const requiresAccount: RequestHandler = function(_req, res, next) {
     if (!res.locals.acc) {
         ServeError(res, 401, "not logged in")
@@ -16,6 +22,9 @@ export const requiresAccount: RequestHandler = function(_req, res, next) {
     next()
 }
 
+/**
+ * @description Middleware which blocks requests that have res.locals.acc.admin set to a falsy value
+ */
 export const requiresAdmin: RequestHandler = function(_req, res, next) {
     if (!res.locals.acc.admin) {
         ServeError(res, 403, "you are not an administrator")
@@ -25,10 +34,10 @@ export const requiresAdmin: RequestHandler = function(_req, res, next) {
 }
 
 /**
-     * @description Blocks requests based on the permissions which a token has. Does not apply to routes being accessed with a token of type `User`
-     * @param tokenPermissions Permissions which your route requires.
-     * @returns Express middleware
-     */
+ * @description Blocks requests based on the permissions which a token has. Does not apply to routes being accessed with a token of type `User`
+ * @param tokenPermissions Permissions which your route requires.
+ * @returns Express middleware
+ */
 
 export const requiresPermissions = function(...tokenPermissions: auth.TokenPermission[]): RequestHandler {
     return function(req, res, next) {
diff --git a/src/server/lib/ratelimit.ts b/src/server/lib/ratelimit.ts
index a53533a..94d9d32 100644
--- a/src/server/lib/ratelimit.ts
+++ b/src/server/lib/ratelimit.ts
@@ -2,14 +2,19 @@ import { RequestHandler } from "express"
 import { type Account } from "./accounts"
 import ServeError from "./errors"
 
-interface ratelimitSettings {
+interface RatelimitSettings {
 
     requests: number
     per: number
 
 }
 
-export function accountRatelimit( settings: ratelimitSettings ): RequestHandler {
+/**
+ * @description Ratelimits a route based on res.locals.acc
+ * @param settings Ratelimit settings
+ * @returns Express middleware
+ */
+export function accountRatelimit( settings: RatelimitSettings ): RequestHandler {
     let activeLimits: {
         [ key: string ]: {
             requests: number,