feat: Improve error handling by creating error boundries and improving API error handling

wzrdx · aledefra · commit 7cb249f1edcc · 2025-12-15T18:43:54.000+01:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,21 +1,25 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-The Vite + React app lives in `src/` with `main.tsx` mounting `App.tsx`. Feature-specific UI is grouped under `src/components` (e.g., `create-project`, `deeploys`), while route screens sit in `src/pages`. Shared hooks/utilities are in `src/lib` and `src/shared`, smart-contract adapters in `src/blockchain`, and schema/types in `src/schemas`, `src/data`, and `src/typedefs`. Static assets live in `public/` and `src/assets/`; builds land in `dist/`.
+This is a Next.js App Router project. Routes and layouts live in `app/` (file-based routing via `page.tsx`, `layout.tsx`, `not-found.tsx`, and dynamic segments like `[id]`). The codebase uses route groups for organization, e.g. `app/(public)` and `app/(protected)` (the protected group is gated by `app/(protected)/protected-layout.tsx`).
+
+Most feature UI remains in `src/`: feature-specific components are grouped under `src/components` (e.g., `create-project`, `deeploys`, `tunnels`), shared UI/logic in `src/shared`, hooks/utilities/contexts/providers in `src/lib`, smart-contract adapters in `src/blockchain`, and schema/types in `src/schemas`, `src/data`, and `src/typedefs`. Static assets live in `public/` and `src/assets/`. Next build output is `.next/` (a legacy `dist/` directory may exist from pre-Next builds and should not be treated as the Next build output).
 
 ## Build, Test, and Development Commands
 Run all commands from the repo root:
-- `npm run dev` launches the Vite dev server with HMR.
-- `npm run dev:logs` adds verbose Vite diagnostics for debugging config issues.
-- `npm run build` type-checks through `tsc -b` then emits a production bundle to `dist/`.
+- `npm run dev` launches the Next.js dev server (`next dev --turbo --experimental-https`).
+- `npm run dev:logs` enables verbose Next.js diagnostics (`NEXT_DEBUG=1 next dev --turbo --experimental-https`).
+- `npm run build` creates a production build (`next build`, outputs to `.next/`).
+- `npm run start` serves the production build locally (`next start`).
 - `npm run lint` executes ESLint with the project’s React/TypeScript rules.
-- `npm run preview` serves the last build for local production smoke tests.
 
 ## Deeploy API Integration
-Deeploy workflows talk to the [edge_node](https://github.com/Ratio1/edge_node) API through wrappers in `src/lib/api/deeploy.ts`. Configure the base URL by setting `VITE_API_URL` and `VITE_ENVIRONMENT` in your `.env`; `src/lib/config.ts` routes requests across devnet/testnet/mainnet. Local storage must expose `accessToken`/`refreshToken` to satisfy the Axios interceptors. When working against a local edge node, run its server first, then point `VITE_API_URL` to the exposed port (e.g., `http://localhost:5000`). Mock responses for offline work by stubbing the helpers (`createPipeline`, `getApps`, etc.) instead of bypassing the provider.
+Deeploy workflows talk to the [edge_node](https://github.com/Ratio1/edge_node) API through wrappers in `src/lib/api/deeploy.ts`. Configure the base URL by setting `NEXT_PUBLIC_API_URL` and `NEXT_PUBLIC_ENVIRONMENT` (and optionally `NEXT_PUBLIC_DEV_ADDRESS`) in your env file (prefer `.env.local`); `src/lib/config.ts` routes requests across devnet/testnet/mainnet. Local storage must expose `accessToken`/`refreshToken` to satisfy the Axios interceptors. When working against a local edge node, run its server first, then point `NEXT_PUBLIC_API_URL` to the exposed port (e.g., `http://localhost:5000`).
+
+Because this is Next.js, be mindful of client/server boundaries: modules that access `localStorage` (like `src/lib/api/deeploy.ts`) must only run in client components/hooks (files with `'use client'`) and should not be imported/executed from server components.
 
 ## Coding Style & Naming Conventions
-Prettier (`.prettierrc`) enforces four-space indentation, single quotes, semicolons, and Tailwind class sorting—format before committing. Use PascalCase for components, camelCase for functions and state, and kebab-case for feature folders. Respect path aliases from `tsconfig.app.json` (such as `@components/...`) to avoid brittle relative imports. ESLint relaxes certain hook rules; still supply explicit dependency arrays and delete unused code paths.
+Prettier (`.prettierrc`) enforces four-space indentation, single quotes, semicolons, and Tailwind class sorting—format before committing. Use PascalCase for components, camelCase for functions and state, and kebab-case for feature folders. Respect path aliases from `tsconfig.json` (such as `@components/...`) to avoid brittle relative imports. In the `app/` router, add `'use client'` to components that use hooks, browser APIs, or context providers.
 
 ## Testing Guidelines
 Automated tests are not yet wired into `package.json`. Prefer Vitest plus React Testing Library when adding coverage; place specs alongside source as `*.test.ts(x)` or under `src/__tests__/`. Stub Deeploy API calls and blockchain providers to keep tests deterministic, and document manual QA steps in your PR until the suite matures.
diff --git a/app/(protected)/protected-layout.tsx b/app/(protected)/protected-layout.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import Layout from '@components/layout/Layout';
+import { Spinner } from '@heroui/spinner';
 import { getDevAddress, isUsingDevAddress } from '@lib/config';
 import { AuthenticationContextType, useAuthenticationContext } from '@lib/contexts/authentication';
 import { DeploymentContextType, useDeploymentContext } from '@lib/contexts/deployment';
@@ -16,6 +17,7 @@ export function ProtectedLayout({ children }: { children: ReactNode }) {
     const { address } = isUsingDevAddress ? getDevAddress() : account;
 
     const isAuthenticated = isSignedIn && address !== undefined && isFetchAppsRequired !== undefined;
+    const shouldRedirectToLogin = !isAuthenticated;
 
     useEffect(() => {
         if (account.status === 'disconnected') {
@@ -25,12 +27,21 @@ export function ProtectedLayout({ children }: { children: ReactNode }) {
     }, [account.status, setApps, setFetchAppsRequired]);
 
     useEffect(() => {
-        if (!isAuthenticated) {
+        if (shouldRedirectToLogin) {
             router.replace('/login');
         }
-    }, [isAuthenticated, router]);
+    }, [shouldRedirectToLogin, router]);
 
-    if (!isAuthenticated) return null;
+    if (shouldRedirectToLogin) {
+        return (
+            <div className="center-all w-full flex-1 py-24">
+                <div className="col items-center gap-3">
+                    <Spinner />
+                    <div className="text-sm text-slate-500">Redirecting to login…</div>
+                </div>
+            </div>
+        );
+    }
 
     return <Layout>{children}</Layout>;
 }
diff --git a/app/error.tsx b/app/error.tsx
@@ -0,0 +1,33 @@
+'use client';
+
+import { DetailedAlert } from '@shared/DetailedAlert';
+import { useEffect } from 'react';
+import { RiErrorWarningLine } from 'react-icons/ri';
+
+export default function ErrorPage({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+    useEffect(() => {
+        console.error('[app/error.tsx]', error);
+    }, [error]);
+
+    return (
+        <div className="flex w-full flex-1 justify-center pt-24">
+            <DetailedAlert
+                variant="red"
+                icon={<RiErrorWarningLine />}
+                title="Something went wrong"
+                description={
+                    <div>
+                        An unexpected error occurred. Please try again, or return to the home page.
+                        {process.env.NODE_ENV === 'development' && (
+                            <div className="col gap-1 px-3 py-2 pt-2 font-mono text-sm">
+                                <div>{error.message}</div>
+                                {!!error.digest && <div className="text-slate-500">{error.digest}</div>}
+                            </div>
+                        )}
+                    </div>
+                }
+                fullWidth
+            />
+        </div>
+    );
+}
diff --git a/app/global-error.tsx b/app/global-error.tsx
@@ -0,0 +1,25 @@
+'use client';
+
+import { useEffect } from 'react';
+import '../src/index.css';
+
+export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
+    useEffect(() => {
+        console.error('[app/global-error.tsx]', error);
+    }, [error]);
+
+    return (
+        <html lang="en">
+            <body className="font-mona">
+                <div className="center-all min-h-screen p-6">
+                    <div className="col w-full max-w-[640px] gap-2 text-center">
+                        <div className="text-lg font-semibold">Something went wrong</div>
+                        <div className="text-sm text-slate-600">
+                            The app hit an unexpected error. Please refresh this page or try again later.
+                        </div>
+                    </div>
+                </div>
+            </body>
+        </html>
+    );
+}
diff --git a/src/lib/api/apiError.ts b/src/lib/api/apiError.ts
@@ -0,0 +1,90 @@
+import axios, { type AxiosError } from 'axios';
+
+export class ApiError extends Error {
+    readonly status?: number;
+    readonly url?: string;
+    readonly method?: string;
+    readonly responseData?: unknown;
+    readonly isNetworkError: boolean;
+
+    constructor(
+        message: string,
+        {
+            status,
+            url,
+            method,
+            responseData,
+            isNetworkError,
+            cause,
+        }: {
+            status?: number;
+            url?: string;
+            method?: string;
+            responseData?: unknown;
+            isNetworkError: boolean;
+            cause?: unknown;
+        },
+    ) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.url = url;
+        this.method = method;
+        this.responseData = responseData;
+        this.isNetworkError = isNetworkError;
+        if (cause !== undefined) {
+            Object.defineProperty(this, 'cause', {
+                value: cause,
+                enumerable: false,
+            });
+        }
+    }
+}
+
+export function toApiError(error: unknown, fallbackMessage: string): ApiError {
+    if (axios.isAxiosError(error)) {
+        const axiosError = error as AxiosError;
+        const status = axiosError.response?.status;
+        const url = axiosError.config?.url;
+        const method = axiosError.config?.method?.toUpperCase();
+        const responseData = axiosError.response?.data;
+        const isNetworkError = axiosError.response === undefined;
+
+        const message =
+            extractMessageFromResponseData(responseData) ??
+            axiosError.message ??
+            (isNetworkError ? 'Network error' : undefined) ??
+            fallbackMessage;
+
+        return new ApiError(message, {
+            status,
+            url,
+            method,
+            responseData,
+            isNetworkError,
+            cause: error,
+        });
+    }
+
+    const message = error instanceof Error ? error.message : fallbackMessage;
+    return new ApiError(message, { isNetworkError: false, cause: error });
+}
+
+function extractMessageFromResponseData(data: unknown): string | undefined {
+    if (!isRecord(data)) return;
+
+    const error = data.error;
+    if (typeof error === 'string') return error;
+
+    const message = data.message;
+    if (typeof message === 'string') return message;
+
+    const result = data.result;
+    if (isRecord(result) && typeof result.error === 'string') return result.error;
+
+    return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object';
+}
diff --git a/src/lib/api/backend.tsx b/src/lib/api/backend.tsx
@@ -1,4 +1,5 @@
 import { config } from '@lib/config';
+import { toApiError } from '@lib/api/apiError';
 import { InvoiceDraft, PublicProfileInfo } from '@typedefs/general';
 import axios from 'axios';
 import * as types from '@typedefs/blockchain';
@@ -193,7 +194,7 @@ const axiosDapp = axios.create({
 
 axiosDapp.interceptors.request.use(
     async (config) => {
-        const token = localStorage.getItem('accessToken');
+        const token = typeof window !== 'undefined' ? localStorage.getItem('accessToken') : null;
         if (token) {
             config.headers.Authorization = `Bearer ${token}`;
         }
@@ -209,24 +210,27 @@ axiosDapp.interceptors.response.use(
         return response;
     },
     async (error) => {
-        const originalRequest = error.config;
-        if (error.response.status === 401 && !originalRequest._retry) {
+        const status: number | undefined = error?.response?.status;
+        const originalRequest = error?.config;
+
+        if (status === 401 && originalRequest && !originalRequest._retry) {
             originalRequest._retry = true;
-            const refreshToken = localStorage.getItem('refreshToken');
+            const refreshToken = typeof window !== 'undefined' ? localStorage.getItem('refreshToken') : null;
             if (refreshToken) {
-                return axiosDapp
-                    .post('/auth/refresh', {
-                        refreshToken: refreshToken,
-                    })
-                    .then((res) => {
-                        if (res.status === 200) {
-                            localStorage.setItem('accessToken', res.data.accessToken);
-                            return axiosDapp(originalRequest);
-                        }
+                try {
+                    const refreshClient = axios.create({ baseURL: backendUrl });
+                    const res = await refreshClient.post('/auth/refresh', { refreshToken });
+
+                    if (res.status === 200 && typeof window !== 'undefined' && res.data?.accessToken) {
+                        localStorage.setItem('accessToken', res.data.accessToken);
                         return axiosDapp(originalRequest);
-                    });
+                    }
+                } catch (refreshError) {
+                    return Promise.reject(toApiError(refreshError, 'Session refresh failed.'));
+                }
             }
         }
-        return error.response;
+
+        return Promise.reject(toApiError(error, 'Backend request failed.'));
     },
 );
diff --git a/src/lib/api/deeploy.ts b/src/lib/api/deeploy.ts
@@ -1,4 +1,5 @@
 import { config } from '@lib/config';
+import { toApiError } from '@lib/api/apiError';
 import { EthAddress } from '@typedefs/blockchain';
 import { DeeployDefaultResponse, GetAppsResponse } from '@typedefs/deeployApi';
 import axios from 'axios';
@@ -98,7 +99,7 @@ export const axiosDeeploy = axios.create({
 
 axiosDeeploy.interceptors.request.use(
     async (config) => {
-        const token = localStorage.getItem('accessToken');
+        const token = typeof window !== 'undefined' ? localStorage.getItem('accessToken') : null;
         if (token) {
             config.headers.Authorization = `Bearer ${token}`;
         }
@@ -114,25 +115,28 @@ axiosDeeploy.interceptors.response.use(
         return response;
     },
     async (error) => {
-        const originalRequest = error.config;
-        if (error.response.status === 401 && !originalRequest._retry) {
+        const status: number | undefined = error?.response?.status;
+        const originalRequest = error?.config;
+
+        if (status === 401 && originalRequest && !originalRequest._retry) {
             originalRequest._retry = true;
-            const refreshToken = localStorage.getItem('refreshToken');
+            const refreshToken = typeof window !== 'undefined' ? localStorage.getItem('refreshToken') : null;
             if (refreshToken) {
-                return axiosDeeploy
-                    .post('/auth/refresh', {
-                        refreshToken: refreshToken,
-                    })
-                    .then((res) => {
-                        if (res.status === 200) {
-                            localStorage.setItem('accessToken', res.data.accessToken);
-                            return axiosDeeploy(originalRequest);
-                        }
+                try {
+                    const refreshClient = axios.create({ baseURL: config.deeployUrl });
+                    const res = await refreshClient.post('/auth/refresh', { refreshToken });
+
+                    if (res.status === 200 && typeof window !== 'undefined' && res.data?.accessToken) {
+                        localStorage.setItem('accessToken', res.data.accessToken);
                         return axiosDeeploy(originalRequest);
-                    });
+                    }
+                } catch (refreshError) {
+                    return Promise.reject(toApiError(refreshError, 'Session refresh failed.'));
+                }
             }
         }
-        return error.response;
+
+        return Promise.reject(toApiError(error, 'Deeploy request failed.'));
     },
 );
 
diff --git a/src/lib/api/oracles.tsx b/src/lib/api/oracles.tsx
@@ -1,4 +1,5 @@
 import { config } from '@lib/config';
+import { toApiError } from '@lib/api/apiError';
 import axios from 'axios';
 import * as types from '@typedefs/blockchain';
 
@@ -90,6 +91,6 @@ axiosInstance.interceptors.response.use(
         return response;
     },
     async (error) => {
-        return error.response;
+        return Promise.reject(toApiError(error, 'Oracles request failed.'));
     },
 );
