Merge branch 'main' into add_tiptap_doc_loading_indicator

Author: jhodapp

src/app/page.tsx

@@ -3,7 +3,7 @@ import Link from "next/link";
 
 import { cn } from "@/components/lib/utils";
 import { buttonVariants } from "@/components/ui/button";
-import { UserAuthForm } from "@/components/user-auth-form";
+import { UserAuthForm } from "@/components/ui/login/user-auth-form";
 import { siteConfig } from "@/site.config";
 import { Icons } from "@/components/ui/icons";
 

src/components/user-auth-form.tsx renamed to src/components/ui/login/user-auth-form.tsx

@@ -4,6 +4,7 @@ import * as React from "react";
 
 import { cn } from "@/components/lib/utils";
 import { useUserSessionMutation } from "@/lib/api/user-sessions";
+import { EntityApiError } from "@/lib/api/entity-api";
 import { useAuthStore } from "@/lib/providers/auth-store-provider";
 import { useRouter } from "next/navigation";
 import { Icons } from "@/components/ui/icons";
@@ -49,8 +50,25 @@ export function UserAuthForm({ className, ...props }: UserAuthFormProps) {
       })
       .catch((err) => {
         setIsLoading(false);
-        console.error("Login failed, err: " + err);
-        setError(err.message);
+        console.error("Login failed:", err);
+        
+        // Enhanced error handling with EntityApiError
+        if (err instanceof EntityApiError) {
+          // Handle specific HTTP status codes for better UX
+          if (err.status === 401) {
+            setError("Invalid email or password. Please try again.");
+          } else if (err.status === 429) {
+            setError("Too many login attempts. Please wait before trying again.");
+          } else if (err.isServerError()) {
+            setError("Server error occurred. Please try again later.");
+          } else if (err.isNetworkError()) {
+            setError("Network error. Please check your connection and try again.");
+          } else {
+            setError(err.message);
+          }
+        } else {
+          setError(err.message || "An unexpected error occurred");
+        }
       });
   }
 

src/lib/api/entity-api.ts

@@ -1,9 +1,12 @@
 import { siteConfig } from "@/site.config";
-import { Id } from "@/types/general";
+import { Id, EntityApiError } from "@/types/general";
 import axios from "axios";
 import { useState } from "react";
 import useSWR, { KeyedMutator, SWRConfiguration, useSWRConfig } from "swr";
 
+// Re-export EntityApiError for easy access
+export { EntityApiError } from "@/types/general";
+
 export namespace EntityApi {
   interface ApiResponse<T> {
     status_code: number;
@@ -77,14 +80,15 @@ export namespace EntityApi {
    * @param data Optional payload data required for POST/PUT operations
    * @param config Optional post/put/delete configuration object
    * @returns Promise resolving to response data of type R
-   * @throws Error for invalid methods or missing required payload data
+   * @throws EntityApiError for axios errors, Error for invalid methods or missing required payload data
    *
    * @remarks This function:
    * - Enforces RESTful conventions for mutation operations
    * - Handles payload data type validation through generics
    * - Applies consistent request configuration (credentials, timeout, headers)
    * - Extracts and returns only the data portion from API responses
    * - Throws explicit errors for invalid method/data combinations
+   * - Wraps axios errors in EntityApiError for enhanced error handling
    *
    * @usage
    * - POST/PUT: Requires data payload matching type T
@@ -105,18 +109,28 @@ export namespace EntityApi {
       ...config,
     };
 
-    let response;
-    if (method === "delete") {
-      response = await axios.delete<ApiResponse<R>>(url, combinedConfig);
-    } else if (method === "put" && data) {
-      response = await axios.put<ApiResponse<R>>(url, data, combinedConfig);
-    } else if (data) {
-      response = await axios.post<ApiResponse<R>>(url, data, combinedConfig);
-    } else {
-      throw new Error("Invalid method or missing data");
-    }
+    try {
+      let response;
+      if (method === "delete") {
+        response = await axios.delete<ApiResponse<R>>(url, combinedConfig);
+      } else if (method === "put" && data) {
+        response = await axios.put<ApiResponse<R>>(url, data, combinedConfig);
+      } else if (data) {
+        response = await axios.post<ApiResponse<R>>(url, data, combinedConfig);
+      } else {
+        throw new Error("Invalid method or missing data");
+      }
 
-    return response.data.data;
+      return response.data.data;
+    } catch (error) {
+      // Wrap axios errors in EntityApiError for enhanced error handling
+      if (axios.isAxiosError(error)) {
+        throw new EntityApiError(method, url, error);
+      }
+      
+      // Re-throw non-axios errors as-is
+      throw error;
+    }
   };
 
   /**
@@ -414,9 +428,9 @@ export namespace EntityApi {
         mutate((key) => typeof key === "string" && key.includes(baseUrl));
         return result;
       } catch (err) {
-        setError(
-          err instanceof Error ? err : new Error("Unknown error occurred")
-        );
+        // Handle both EntityApiError and regular Error types
+        const error = err instanceof Error ? err : new Error("Unknown error occurred");
+        setError(error);
         throw err;
       } finally {
         setIsLoading(false);

src/types/general.ts

@@ -1,8 +1,102 @@
 import { DateTime } from "ts-luxon";
+import { AxiosError, AxiosResponse } from "axios";
+import axios from "axios";
 
 // A type alias for each entity's Id field
 export type Id = string;
 
+/**
+ * Enhanced error type for Entity API operations that preserves axios error information
+ * while providing a more user-friendly interface for error handling.
+ */
+export class EntityApiError extends Error {
+  public readonly method: string;
+  public readonly url: string;
+  public readonly status?: number;
+  public readonly statusText?: string;
+  public readonly response?: AxiosResponse;
+  public readonly request?: any;
+  public readonly data?: any;
+  public readonly originalError: AxiosError | Error;
+
+  constructor(
+    method: string,
+    url: string,
+    originalError: AxiosError | Error,
+    message?: string
+  ) {
+    // Create a descriptive error message
+    const errorMessage =
+      message || EntityApiError.createErrorMessage(method, url, originalError);
+    super(errorMessage);
+
+    this.name = "EntityApiError";
+    this.method = method.toUpperCase();
+    this.url = url;
+    this.originalError = originalError;
+
+    // Extract axios-specific properties if available
+    if (
+      originalError &&
+      "isAxiosError" in originalError &&
+      originalError.isAxiosError
+    ) {
+      const axiosError = originalError as AxiosError;
+      this.status = axiosError.response?.status;
+      this.statusText = axiosError.response?.statusText;
+      this.response = axiosError.response;
+      this.request = axiosError.request;
+      this.data = axiosError.response?.data;
+    }
+  }
+
+  /**
+   * Creates a user-friendly error message from the original error
+   */
+  private static createErrorMessage(
+    method: string,
+    url: string,
+    error: AxiosError | Error
+  ): string {
+    if (axios.isAxiosError(error)) {
+      const status = error.response?.status;
+      const statusText = error.response?.statusText;
+      const serverMessage = error.response?.data?.message;
+
+      if (serverMessage) {
+        return `${method.toUpperCase()} ${url} failed: ${serverMessage}`;
+      } else if (status && statusText) {
+        return `${method.toUpperCase()} ${url} failed: ${status} ${statusText}`;
+      } else {
+        return `${method.toUpperCase()} ${url} failed: ${error.message}`;
+      }
+    } else {
+      return `${method.toUpperCase()} ${url} failed: ${error.message}`;
+    }
+  }
+
+  /**
+   * Returns true if this error represents a client error (4xx status codes)
+   */
+  public isClientError(): boolean {
+    return this.status !== undefined && this.status >= 400 && this.status < 500;
+  }
+
+  /**
+   * Returns true if this error represents a server error (5xx status codes)
+   */
+  public isServerError(): boolean {
+    return this.status !== undefined && this.status >= 500;
+  }
+
+  /**
+   * Returns true if this error represents a network error (no response received)
+   */
+  public isNetworkError(): boolean {
+    return this.status === undefined && "isAxiosError" in this.originalError;
+  }
+}
+
 // A sorting type that can be used by any of our custom types when stored
 // as arrays
 export enum SortOrder {