feat #655: implements an error handling system with custom errors (#657)

* chore: adds custom error classes

* chore: adds error handling by throwing, catching, and logging errors

* fix: fixes typo in JSDocs

* fix: removes unused import

* chore: throws error for a BackendError

* fix: removes unused import

* chore: throws errors for BackendError and SupabaseErrors

* chore: throws errors for OpenAiError

* feat: function to identify and log errors

* chore: refactoring catch blocks to implement logError()

* test: fixes test to account for SupabaseError class

* test: fixes test to account for OpenAiError class and adjusts mock resolved value for bad open ai response

* fix: consolidates mockSupabase and adjusts the update status test

* fix: adds type string to SupabaseError's statusCode to allow postgrest error code

* fix: passes postgrest error code through SupabaseError class

* chore: added type to SupabaseError JSDocs

* fix: removes status from returned SupabaseError response

* fix: captures the stack trace instead of overwriting it to remove unnecessary lines in the log

* fix: improves readability by logging errors as a single object and adjusts log for unknown errors

---------

Co-authored-by: Shashi Lo <362527+shashilo@users.noreply.github.com>

Author: suzuhe481

app/api/cron/functions/fetchGiftExchanges/fetchGiftExchanges.test.ts

@@ -1,6 +1,7 @@
 import { createClient } from '@/lib/supabase/server';
 import { fetchGiftExchanges } from './fetchGiftExchanges';
 import { SupabaseClient } from '@supabase/supabase-js';
+import { SupabaseError } from '@/lib/errors/CustomErrors';
 
 jest.mock('@/lib/supabase/server');
 
@@ -32,11 +33,11 @@ describe('fetchGiftExchanges', () => {
   it('throws an error when fetch fails', async () => {
     mockSelect.mockResolvedValueOnce({
       data: null,
-      error: new Error('Something went wrong'),
+      error: new SupabaseError('Something went wrong', 500),
     });
 
     await expect(
       fetchGiftExchanges({ supabase: mockSupabase }),
-    ).rejects.toThrow('Something went wrong');
+    ).rejects.toThrow(SupabaseError);
   });
 });

app/api/cron/functions/fetchGiftExchanges/fetchGiftExchanges.ts

@@ -3,6 +3,7 @@
 
 import { GiftExchange } from '@/app/types/giftExchange';
 import { SupabaseClient } from '@supabase/supabase-js';
+import { SupabaseError } from '@/lib/errors/CustomErrors';
 
 /**
  * Fetches all gift exchanges in the database.
@@ -17,11 +18,15 @@ export const fetchGiftExchanges = async ({
   const { data, error } = await supabase.from('gift_exchanges').select('*');
 
   if (error) {
-    throw new Error(error.message);
+    throw new SupabaseError(
+      'Failed to fetch gift exchanges',
+      error.code,
+      error,
+    );
   }
 
   if (data.length === 0) {
-    throw new Error('No gift exchanges found.');
+    throw new SupabaseError('No gift exchanges found', 500, error);
   }
 
   return data;

app/api/cron/functions/processGiftExchanges/processGiftExchanges.test.ts

@@ -5,16 +5,12 @@ import { SupabaseClient } from '@supabase/supabase-js';
 jest.mock('@/lib/drawGiftExchange', () => ({
   drawGiftExchange: jest.fn(),
 }));
-
-const mockEq = jest.fn();
-const mockUpdate = jest.fn(() => ({
-  eq: mockEq,
-}));
-
 const mockSupabase = {
-  from: jest.fn(() => ({
-    update: mockUpdate,
-  })),
+  from: jest.fn().mockReturnValue({
+    update: jest.fn().mockReturnValue({
+      eq: jest.fn().mockResolvedValue({}),
+    }),
+  }),
 } as unknown as SupabaseClient;
 
 describe('processGiftExchanges', () => {
@@ -67,8 +63,12 @@ describe('processGiftExchanges', () => {
     });
 
     expect(mockSupabase.from).toHaveBeenCalledWith('gift_exchanges');
-    expect(mockUpdate).toHaveBeenCalledWith({ status: 'completed' });
-    expect(mockEq).toHaveBeenCalledWith('id', '456');
+    expect(mockSupabase.from('gift_exchanges').update).toHaveBeenCalledWith({
+      status: 'completed',
+    });
+    expect(
+      mockSupabase.from('gift_exchanges').update({ status: 'completed' }).eq,
+    ).toHaveBeenCalledWith('id', '456');
     expect(drawnCount).toBe(0);
     expect(completedCount).toBe(1);
   });

app/api/cron/functions/processGiftExchanges/processGiftExchanges.ts

@@ -6,6 +6,7 @@ import {
   IGiftProcess,
   IProcessGiftExchangesResult,
 } from '@/app/types/giftExchange';
+import { SupabaseError } from '@/lib/errors/CustomErrors';
 
 /**
  * Checks the dates to know how to update gift exchange status.
@@ -28,18 +29,30 @@ export const processGiftExchanges = async ({
   let drawnCount = 0;
   let completedCount = 0;
 
-  if (drawDate === currentDate && exchange.status === 'pending') {
-    await drawGiftExchange(supabase, exchange.id);
-    drawnCount += 1;
-  }
+  try {
+    if (drawDate === currentDate && exchange.status === 'pending') {
+      await drawGiftExchange(supabase, exchange.id);
+      drawnCount += 1;
+    }
 
-  if (currentDate > exchangeDate && exchange.status === 'active') {
-    await supabase
-      .from('gift_exchanges')
-      .update({ status: 'completed' })
-      .eq('id', exchange.id);
-    completedCount += 1;
-  }
+    if (currentDate > exchangeDate && exchange.status === 'active') {
+      const { error } = await supabase
+        .from('gift_exchanges')
+        .update({ status: 'completed' })
+        .eq('id', exchange.id);
+      completedCount += 1;
 
-  return { drawnCount, completedCount };
+      if (error) {
+        throw new SupabaseError(
+          'Failed to process gift exchange',
+          error.code,
+          error,
+        );
+      }
+    }
+
+    return { drawnCount, completedCount };
+  } catch (error) {
+    throw error;
+  }
 };

app/api/cron/route.ts

@@ -6,18 +6,20 @@ import { createClient } from '@/lib/supabase/server';
 import { fetchGiftExchanges } from './functions/fetchGiftExchanges/fetchGiftExchanges';
 import { NextResponse } from 'next/server';
 import { processGiftExchanges } from './functions/processGiftExchanges/processGiftExchanges';
+import { BackendError } from '@/lib/errors/CustomErrors';
+import logError from '@/lib/errors/logError';
 
 /**
  * API function that gets the cron job header to execute once daily.
  * @param {Request} request - API request.
  * @returns {Promise<Response>} The rendered weekly picks page.
  */
 export async function GET(request: Request): Promise<Response> {
-  if (!checkCronAuthorization(request)) {
-    return NextResponse.json({ status: false });
-  }
-
   try {
+    if (!checkCronAuthorization(request)) {
+      throw new BackendError('Invalid authoritzation header', 500);
+    }
+
     const supabase = await createClient();
 
     const giftExchanges = await fetchGiftExchanges({ supabase });
@@ -48,6 +50,6 @@ export async function GET(request: Request): Promise<Response> {
 
     return NextResponse.json({ success: true, drawnMessage, completedMessage });
   } catch (error) {
-    return NextResponse.json({ error });
+    return logError(error);
   }
 }

app/api/getUserAvatar/route.ts

@@ -3,23 +3,42 @@
 
 import { NextResponse } from 'next/server';
 import { createClient } from '../../../lib/supabase/server';
+import { SupabaseError } from '@/lib/errors/CustomErrors';
+import { BackendError } from '@/lib/errors/CustomErrors';
+import logError from '@/lib/errors/logError';
 
 /**
  * Get user avatar URL
  * @returns {Promise<NextResponse>} Promise that resolved to a Response object
  */
 export async function GET(): Promise<NextResponse> {
-  const supabase = await createClient();
-  const {
-    data: { user },
-    error: userError,
-  } = await supabase.auth.getUser();
-
-  if (userError) {
-    return NextResponse.json({ error: 'Unable to retrieve user avatar URL' });
-  }
+  try {
+    const supabase = await createClient();
+
+    const {
+      data: { user },
+      error: userError,
+    } = await supabase.auth.getUser();
+
+    if (userError) {
+      const statusCode = userError.status || 500;
+      throw new SupabaseError('Failed to fetch user', statusCode, userError);
+    }
+
+    if (!user) {
+      throw new SupabaseError('User is not authenticated or exists', 500);
+    }
 
-  const avatarUrl = user?.user_metadata.avatar_url;
+    if (!user.user_metadata.avatar_url) {
+      console.error('User has no avatar');
 
-  return NextResponse.json(avatarUrl);
+      throw new BackendError('User has no avatar', 500);
+    }
+
+    const avatarUrl = user.user_metadata.avatar_url;
+
+    return NextResponse.json({ avatarUrl });
+  } catch (error) {
+    return logError(error);
+  }
 }

app/api/gift-exchanges/[id]/draw/route.ts

@@ -1,6 +1,8 @@
 import { createClient } from '@/lib/supabase/server';
 import { NextResponse } from 'next/server';
 import { drawGiftExchange } from '@/lib/drawGiftExchange';
+import { SupabaseError } from '@/lib/errors/CustomErrors';
+import logError from '@/lib/errors/logError';
 
 /**
  * API Route for drawing gift exchange names
@@ -16,30 +18,24 @@ export async function POST(
 
   try {
     const supabase = await createClient();
+
     const {
       data: { user },
+      error: userError,
     } = await supabase.auth.getUser();
 
+    if (userError) {
+      const statusCode = userError.status || 500;
+      throw new SupabaseError('Failed to fetch user', statusCode, userError);
+    }
+
     if (!user) {
-      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      throw new SupabaseError('User is not authenticated or exists', 500);
     }
 
     await drawGiftExchange(supabase, id);
     return NextResponse.json({ success: true });
   } catch (error) {
-    console.error(error);
-    const message =
-      error instanceof Error ? error.message : 'Internal server error';
-    let status = 500; // default status
-    if (message.includes('not found')) {
-      status = 404;
-    } else if (
-      message.includes('already been drawn') ||
-      message.includes('3 members')
-    ) {
-      status = 400;
-    }
-
-    return NextResponse.json({ error: message }, { status });
+    return logError(error);
   }
 }

app/api/gift-exchanges/[id]/giftSuggestions/route.ts

@@ -1,5 +1,7 @@
 import { createClient } from '@/lib/supabase/server';
 import { NextResponse } from 'next/server';
+import { SupabaseError } from '@/lib/errors/CustomErrors';
+import logError from '@/lib/errors/logError';
 
 export async function GET(
   req: Request,
@@ -10,12 +12,19 @@ export async function GET(
 
   try {
     const supabase = await createClient();
+
     const {
       data: { user },
+      error: userError,
     } = await supabase.auth.getUser();
 
+    if (userError) {
+      const statusCode = userError.status || 500;
+      throw new SupabaseError('Failed to fetch user', statusCode, userError);
+    }
+
     if (!user) {
-      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      throw new SupabaseError('User is not authenticated or exists', 500);
     }
 
     // Get match with full profile info
@@ -45,9 +54,10 @@ export async function GET(
       .single();
 
     if (matchError) {
-      return NextResponse.json(
-        { error: 'Failed to fetch match' },
-        { status: 500 },
+      throw new SupabaseError(
+        'Failed to fetch match',
+        matchError.code,
+        matchError,
       );
     }
 
@@ -59,9 +69,10 @@ export async function GET(
       .eq('giver_id', user.id);
 
     if (suggestionsError) {
-      return NextResponse.json(
-        { error: 'Failed to fetch suggestions' },
-        { status: 500 },
+      throw new SupabaseError(
+        'Failed to fetch suggestions',
+        suggestionsError.code,
+        suggestionsError,
       );
     }
 
@@ -74,10 +85,6 @@ export async function GET(
       })),
     });
   } catch (error) {
-    console.log(error);
-    return NextResponse.json(
-      { error: 'Internal server error' },
-      { status: 500 },
-    );
+    return logError(error);
   }
 }