chore: begin work on documenting client side requests code

src/components/BeerById/BeerPostLikeButton.tsx

@@ -3,7 +3,7 @@ import useCheckIfUserLikesBeerPost from '@/hooks/data-fetching/beer-likes/useChe
 import { FC, useEffect, useState } from 'react';
 
 import useGetBeerPostLikeCount from '@/hooks/data-fetching/beer-likes/useBeerPostLikeCount';
-import sendBeerPostLikeRequest from '@/requests/BeerPost/sendBeerPostLikeRequest';
+import sendBeerPostLikeRequest from '@/requests/BeerPostLike/sendBeerPostLikeRequest';
 import LikeButton from '../ui/LikeButton';
 
 const BeerPostLikeButton: FC<{

src/requests/BeerComment/sendCreateBeerCommentRequest.ts

@@ -8,6 +8,17 @@ const BeerCommentValidationSchemaWithId = CreateCommentValidationSchema.extend({
   beerPostId: z.string().cuid(),
 });
 
+/**
+ * Sends a POST request to the server to create a new beer comment.
+ *
+ * @param data The data to be sent to the server.
+ * @param data.beerPostId The ID of the beer post to comment on.
+ * @param data.content The content of the comment.
+ * @param data.rating The rating of the beer.
+ * @returns A promise that resolves to the created comment.
+ * @throws An error if the request fails, the API response is invalid, or the API response
+ *   payload is invalid.
+ */
 const sendCreateBeerCommentRequest = async ({
   beerPostId,
   content,

src/requests/BeerImage/sendUploadBeerImageRequest.ts

@@ -1,4 +1,5 @@
 import BeerPostQueryResult from '@/services/BeerPost/schema/BeerPostQueryResult';
+import APIResponseValidationSchema from '@/validation/APIResponseValidationSchema';
 import { z } from 'zod';
 
 interface SendUploadBeerImagesRequestArgs {
@@ -6,6 +7,15 @@ interface SendUploadBeerImagesRequestArgs {
   images: FileList;
 }
 
+/**
+ * Sends a POST request to the server to upload images for a beer post.
+ *
+ * @param beerPost The beer post object.
+ * @param images The list of images to upload.
+ * @returns A promise that resolves to the response from the server.
+ * @throws An error if the upload fails or the API response is invalid.
+ */
+
 const sendUploadBeerImagesRequest = async ({
   beerPost,
   images,
@@ -28,7 +38,14 @@ const sendUploadBeerImagesRequest = async ({
     throw new Error('Failed to upload images');
   }
 
-  return uploadResponse.json();
+  const json = await uploadResponse.json();
+  const parsed = APIResponseValidationSchema.safeParse(json);
+
+  if (!parsed.success) {
+    throw new Error('Invalid API response');
+  }
+
+  return parsed.data;
 };
 
 export default sendUploadBeerImagesRequest;

src/requests/BeerPost/deleteBeerPostRequest.ts

@@ -1,5 +1,12 @@
 import APIResponseValidationSchema from '@/validation/APIResponseValidationSchema';
 
+/**
+ * Sends a DELETE request to the server to delete a beer post with the given ID.
+ *
+ * @param id The ID of the beer post to delete.
+ * @returns A Promise that resolves to the parsed API response.
+ * @throws An error if the response fails or the API response is invalid.
+ */
 const deleteBeerPostRequest = async (id: string) => {
   const response = await fetch(`/api/beers/${id}`, {
     method: 'DELETE',

src/requests/BeerPost/sendCreateBeerPostRequest.ts

@@ -3,14 +3,45 @@ import CreateBeerPostValidationSchema from '@/services/BeerPost/schema/CreateBee
 import APIResponseValidationSchema from '@/validation/APIResponseValidationSchema';
 import { z } from 'zod';
 
-const sendCreateBeerPostRequest = async (
-  data: z.infer<typeof CreateBeerPostValidationSchema>,
-) => {
+/**
+ * Sends a POST request to the server to create a new beer post.
+ *
+ * @param data Data containing the beer post information to be sent to the server.
+ * @param abv The alcohol by volume of the beer.
+ * @param breweryId The ID of the brewery that produces the beer.
+ * @param description The description of the beer.
+ * @param ibu The International Bitterness Units of the beer.
+ * @param name The name of the beer.
+ * @param styleId The ID of the beer style.
+ * @returns A Promise that resolves to the created beer post.
+ * @throws An error if the request fails, the API response is invalid, or the API response
+ *   payload is invalid.
+ */
+const sendCreateBeerPostRequest = async ({
+  abv,
+  breweryId,
+  description,
+  ibu,
+  name,
+  styleId,
+}: z.infer<typeof CreateBeerPostValidationSchema>) => {
   const response = await fetch('/api/beers/create', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(data),
+    body: JSON.stringify({
+      abv,
+      breweryId,
+      description,
+      ibu,
+      name,
+      styleId,
+    }),
   });
+
+  if (!response.ok) {
+    throw new Error(response.statusText);
+  }
+
   const json = await response.json();
   const parsed = APIResponseValidationSchema.safeParse(json);
 

src/requests/BeerPost/sendEditBeerPostRequest.ts

@@ -2,13 +2,30 @@ import EditBeerPostValidationSchema from '@/services/BeerPost/schema/EditBeerPos
 import APIResponseValidationSchema from '@/validation/APIResponseValidationSchema';
 import { z } from 'zod';
 
-async function sendEditBeerPostRequest(
-  data: z.infer<typeof EditBeerPostValidationSchema>,
-) {
-  const response = await fetch(`/api/beers/${data.id}`, {
+/**
+ * Sends a PUT request to the server to update a beer post.
+ *
+ * @param data Data containing the updated beer post information to be sent to the server.
+ * @param data.abv The updated ABV of the beer.
+ * @param data.description The updated description of the beer.
+ * @param data.ibu The updated IBU of the beer.
+ * @param data.id The ID of the beer post to be updated.
+ * @param data.name The updated name of the beer.
+ * @param data.styleId The updated style ID of the beer.
+ * @throws If the response status is not ok or the API response is not successful.
+ */
+const sendEditBeerPostRequest = async ({
+  abv,
+  description,
+  ibu,
+  id,
+  name,
+  styleId,
+}: z.infer<typeof EditBeerPostValidationSchema>) => {
+  const response = await fetch(`/api/beers/${id}`, {
     method: 'PUT',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(data),
+    body: JSON.stringify({ abv, description, ibu, name, styleId, id }),
   });
 
   if (!response.ok) {
@@ -21,6 +38,6 @@ async function sendEditBeerPostRequest(
   if (!parsed.success) {
     throw new Error(parsed.error.message);
   }
-}
+};
 
 export default sendEditBeerPostRequest;

src/requests/BeerPostLike/sendBeerPostLikeRequest.ts

@@ -1,5 +1,12 @@
 import APIResponseValidationSchema from '@/validation/APIResponseValidationSchema';
 
+/**
+ * Sends a POST request to the server to like or unlike a beer post.
+ *
+ * @param beerPostId The ID of the beer post to like or unlike.
+ * @returns An object containing a success boolean and a message string.
+ * @throws An error if the response is not ok or if the API response is invalid.
+ */
 const sendBeerPostLikeRequest = async (beerPostId: string) => {
   const response = await fetch(`/api/beers/${beerPostId}/like`, {
     method: 'POST',
@@ -10,7 +17,6 @@ const sendBeerPostLikeRequest = async (beerPostId: string) => {
   }
 
   const data = await response.json();
-
   const parsed = APIResponseValidationSchema.safeParse(data);
 
   if (!parsed.success) {