@geenius/tools 0.1.0

package/packages/errors/react/src/components/ValidationErrors.tsx

@@ -0,0 +1,102 @@
+// @geenius-tools/errors-react — src/components/ValidationErrors.tsx
+
+import { FC } from 'react'
+import { AlertCircle } from 'lucide-react'
+import type { ValidationError } from '../types'
+import { formatValidationErrors } from '../utils/formatError'
+
+export interface ValidationErrorsProps {
+    errors: ValidationError[]
+    className?: string
+    grouped?: boolean
+}
+
+/**
+ * Validation Errors Component
+ *
+ * Displays validation errors from backend in a user-friendly format.
+ * Automatically groups errors by field.
+ *
+ * @example
+ * <ValidationErrors errors={appError.validationErrors} />
+ */
+export const ValidationErrors: FC<ValidationErrorsProps> = ({
+    errors,
+    className = '',
+    grouped = true,
+}) => {
+    if (!errors || errors.length === 0) return null
+
+    if (!grouped) {
+        return (
+            <div className={className} style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+                {errors.map((error, index) => (
+                    <div
+                        key={index}
+                        style={{
+                            display: 'flex',
+                            alignItems: 'flex-start',
+                            gap: '8px',
+                            padding: '12px',
+                            borderRadius: '8px',
+                            backgroundColor: 'rgba(239, 68, 68, 0.05)',
+                            border: '1px solid rgba(239, 68, 68, 0.2)',
+                        }}
+                    >
+                        <AlertCircle style={{ height: '16px', width: '16px', color: '#dc2626', marginTop: '2px', flexShrink: 0 }} />
+                        <div style={{ flex: 1 }}>
+                            <p style={{ fontSize: '14px', fontWeight: 500, color: '#991b1b', margin: 0 }}>
+                                {error.field}
+                            </p>
+                            <p style={{ fontSize: '14px', color: '#b91c1c', margin: 0 }}>
+                                {error.message}
+                            </p>
+                        </div>
+                    </div>
+                ))}
+            </div>
+        )
+    }
+
+    const groupedErrors = formatValidationErrors(errors)
+
+    return (
+        <div className={className} style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+            <p style={{ fontSize: '14px', fontWeight: 600, margin: 0, textAlign: 'left' }}>
+                Please fix the following fields:
+            </p>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+                {Object.entries(groupedErrors).map(([field, messages]) => (
+                    <div
+                        key={field}
+                        style={{
+                            display: 'flex',
+                            alignItems: 'flex-start',
+                            gap: '8px',
+                            padding: '12px',
+                            borderRadius: '8px',
+                            backgroundColor: 'rgba(234, 179, 8, 0.05)',
+                            border: '1px solid rgba(234, 179, 8, 0.2)',
+                            textAlign: 'left',
+                        }}
+                    >
+                        <AlertCircle style={{ height: '16px', width: '16px', color: '#ca8a04', marginTop: '2px', flexShrink: 0 }} />
+                        <div style={{ flex: 1 }}>
+                            <p style={{ fontSize: '14px', fontWeight: 500, textTransform: 'capitalize', color: '#854d0e', margin: 0 }}>
+                                {field}
+                            </p>
+                            {messages.map((message, index) => (
+                                <p
+                                    key={index}
+                                    style={{ fontSize: '14px', color: '#a16207', margin: 0 }}
+                                >
+                                    {message}
+                                </p>
+                            ))}
+                        </div>
+                    </div>
+                ))}
+            </div>
+        </div>
+    )
+}

package/packages/errors/react/src/config.ts

@@ -0,0 +1,199 @@
+// @geenius-tools/errors-react — src/config.ts
+// Pluggable configuration for toast handling and error messages
+
+import type { AppErrorCode } from './types'
+
+// ============================================================================
+// Toast Configuration
+// ============================================================================
+
+/**
+ * Toast function interface — matches react-hot-toast API shape
+ */
+export interface ToastFn {
+    (message: string): void
+    error: (message: string, options?: { id?: string }) => void
+    success: (message: string, options?: { id?: string }) => void
+    loading: (message: string, options?: { id?: string }) => string | number
+}
+
+/**
+ * Error handler configuration
+ */
+export interface ErrorHandlerConfig {
+    toast?: ToastFn
+    /** Whether to log errors to console in development */
+    logInDev?: boolean
+}
+
+let _errorHandlerConfig: ErrorHandlerConfig = {
+    logInDev: true,
+}
+
+/**
+ * Configure the global error handler
+ *
+ * @example
+ * import toast from 'react-hot-toast'
+ * import { configureErrorHandler } from '@geenius-tools/errors-react'
+ *
+ * configureErrorHandler({ toast })
+ */
+export function configureErrorHandler(config: ErrorHandlerConfig): void {
+    _errorHandlerConfig = { ..._errorHandlerConfig, ...config }
+}
+
+export function getErrorHandlerConfig(): ErrorHandlerConfig {
+    return _errorHandlerConfig
+}
+
+// ============================================================================
+// Error Messages Configuration
+// ============================================================================
+
+/**
+ * Error message set
+ */
+export interface ErrorMessageSet {
+    /** Short error messages keyed by error code */
+    messages: Record<AppErrorCode, string>
+    /** User-friendly titles keyed by error code */
+    titles: Record<AppErrorCode, string>
+    /** Detailed descriptions keyed by error code */
+    descriptions: Record<AppErrorCode, string>
+    /** Suggested actions keyed by error code */
+    actions: Record<AppErrorCode, string>
+    /** Validation message helpers */
+    validation: Record<string, string>
+}
+
+/**
+ * English error messages (default)
+ */
+export const ERROR_MESSAGES_EN: ErrorMessageSet = {
+    messages: {
+        UNAUTHENTICATED: 'Authentication required. Please sign in.',
+        FORBIDDEN: 'Access denied. You do not have permission for this action.',
+        NOT_FOUND: 'The requested resource was not found.',
+        BAD_REQUEST: 'Invalid request. Please check your input.',
+        CONFLICT: 'A conflict occurred with existing data.',
+        INTERNAL: 'An internal error occurred. Please try again later.',
+        VALIDATION_ERROR: 'Some fields are invalid. Please check and try again.',
+        RATE_LIMITED: 'Too many requests. Please try again later.',
+        FEATURE_DISABLED: 'This feature is currently disabled.',
+    },
+    titles: {
+        UNAUTHENTICATED: 'Not Authenticated',
+        FORBIDDEN: 'Access Denied',
+        NOT_FOUND: 'Not Found',
+        BAD_REQUEST: 'Invalid Request',
+        CONFLICT: 'Conflict',
+        INTERNAL: 'Internal Error',
+        VALIDATION_ERROR: 'Validation Error',
+        RATE_LIMITED: 'Too Many Requests',
+        FEATURE_DISABLED: 'Feature Disabled',
+    },
+    descriptions: {
+        UNAUTHENTICATED: 'Please sign in to continue. Your session may have expired.',
+        FORBIDDEN: 'You do not have permission for this action. Contact an administrator if you believe this is an error.',
+        NOT_FOUND: 'The requested resource was not found. It may have been deleted or moved.',
+        BAD_REQUEST: 'Invalid request. Please check your input and try again.',
+        CONFLICT: 'This action could not be completed due to a conflict with existing data.',
+        INTERNAL: 'An internal error occurred. Our team has been notified. Please try again later.',
+        VALIDATION_ERROR: 'Some of your inputs are invalid. Please check the highlighted fields and try again.',
+        RATE_LIMITED: 'You have sent too many requests in a short time. Please wait a moment and try again.',
+        FEATURE_DISABLED: 'This feature is currently disabled. Please try again later or contact support.',
+    },
+    actions: {
+        UNAUTHENTICATED: 'Please sign in again.',
+        FORBIDDEN: 'Contact an administrator if you need access.',
+        NOT_FOUND: 'Go back to the home page or use search.',
+        BAD_REQUEST: 'Check your input and try again.',
+        CONFLICT: 'Refresh the page and try again.',
+        INTERNAL: 'Try again in a few minutes.',
+        VALIDATION_ERROR: 'Fix the highlighted fields.',
+        RATE_LIMITED: 'Wait a moment and try again.',
+        FEATURE_DISABLED: 'Try again later or contact support.',
+    },
+    validation: {
+        required: 'This field is required.',
+        minLength: 'Must be at least {min} characters.',
+        maxLength: 'Must be at most {max} characters.',
+        email: 'Please enter a valid email address.',
+        url: 'Please enter a valid URL.',
+    },
+}
+
+/**
+ * German error messages preset
+ */
+export const ERROR_MESSAGES_DE: ErrorMessageSet = {
+    messages: {
+        UNAUTHENTICATED: 'Authentifizierung erforderlich. Bitte melde dich an.',
+        FORBIDDEN: 'Zugriff verweigert. Du hast keine Berechtigung für diese Aktion.',
+        NOT_FOUND: 'Die angeforderte Ressource wurde nicht gefunden.',
+        BAD_REQUEST: 'Ungültige Anfrage. Bitte überprüfe deine Eingaben.',
+        CONFLICT: 'Ein Konflikt mit bestehenden Daten ist aufgetreten.',
+        INTERNAL: 'Ein interner Fehler ist aufgetreten. Bitte versuche es später erneut.',
+        VALIDATION_ERROR: 'Einige Felder sind ungültig. Bitte überprüfe deine Eingaben.',
+        RATE_LIMITED: 'Zu viele Anfragen. Bitte versuche es später erneut.',
+        FEATURE_DISABLED: 'Diese Funktion ist derzeit deaktiviert.',
+    },
+    titles: {
+        UNAUTHENTICATED: 'Nicht angemeldet',
+        FORBIDDEN: 'Zugriff verweigert',
+        NOT_FOUND: 'Nicht gefunden',
+        BAD_REQUEST: 'Ungültige Anfrage',
+        CONFLICT: 'Konflikt',
+        INTERNAL: 'Interner Fehler',
+        VALIDATION_ERROR: 'Validierungsfehler',
+        RATE_LIMITED: 'Zu viele Anfragen',
+        FEATURE_DISABLED: 'Funktion deaktiviert',
+    },
+    descriptions: {
+        UNAUTHENTICATED: 'Bitte melde dich an, um fortzufahren. Deine Sitzung ist möglicherweise abgelaufen.',
+        FORBIDDEN: 'Du hast keine Berechtigung für diese Aktion. Wenn du glaubst, dass dies ein Fehler ist, wende dich an einen Administrator.',
+        NOT_FOUND: 'Die angeforderte Ressource wurde nicht gefunden. Sie wurde möglicherweise gelöscht oder verschoben.',
+        BAD_REQUEST: 'Ungültige Anfrage. Bitte überprüfe deine Eingaben und versuche es erneut.',
+        CONFLICT: 'Diese Aktion konnte nicht ausgeführt werden, da ein Konflikt mit bestehenden Daten besteht.',
+        INTERNAL: 'Ein interner Fehler ist aufgetreten. Unser Team wurde benachrichtigt. Bitte versuche es später erneut.',
+        VALIDATION_ERROR: 'Einige deiner Eingaben sind ungültig. Bitte überprüfe die markierten Felder und versuche es erneut.',
+        RATE_LIMITED: 'Du hast zu viele Anfragen in kurzer Zeit gesendet. Bitte warte einen Moment und versuche es dann erneut.',
+        FEATURE_DISABLED: 'Diese Funktion ist derzeit deaktiviert. Bitte versuche es später erneut oder wende dich an den Support.',
+    },
+    actions: {
+        UNAUTHENTICATED: 'Bitte melde dich erneut an.',
+        FORBIDDEN: 'Kontaktiere einen Administrator, wenn du Zugriff benötigst.',
+        NOT_FOUND: 'Gehe zurück zur Startseite oder verwende die Suche.',
+        BAD_REQUEST: 'Überprüfe deine Eingaben und versuche es erneut.',
+        CONFLICT: 'Aktualisiere die Seite und versuche es erneut.',
+        INTERNAL: 'Versuche es in einigen Minuten erneut.',
+        VALIDATION_ERROR: 'Korrigiere die markierten Felder.',
+        RATE_LIMITED: 'Warte einen Moment und versuche es dann erneut.',
+        FEATURE_DISABLED: 'Versuche es später erneut oder kontaktiere den Support.',
+    },
+    validation: {
+        required: 'Dieses Feld ist erforderlich.',
+        minLength: 'Mindestens {min} Zeichen erforderlich.',
+        maxLength: 'Maximal {max} Zeichen erlaubt.',
+        email: 'Bitte gib eine gültige E-Mail-Adresse ein.',
+        url: 'Bitte gib eine gültige URL ein.',
+    },
+}
+
+let _currentMessages: ErrorMessageSet = ERROR_MESSAGES_EN
+
+/**
+ * Configure error messages (set locale)
+ *
+ * @example
+ * import { configureErrorMessages, ERROR_MESSAGES_DE } from '@geenius-tools/errors-react'
+ * configureErrorMessages(ERROR_MESSAGES_DE)
+ */
+export function configureErrorMessages(messages: ErrorMessageSet): void {
+    _currentMessages = messages
+}
+
+export function getErrorMessages(): ErrorMessageSet {
+    return _currentMessages
+}

package/packages/errors/react/src/constants.ts

@@ -0,0 +1,74 @@
+// @geenius-tools/errors-react — src/constants.ts
+
+import {
+    AlertCircle,
+    AlertTriangle,
+    ShieldAlert,
+    Clock,
+    Ban,
+    type LucideIcon,
+} from 'lucide-react'
+import type { AppErrorCode } from './types'
+
+/**
+ * Icon mapping for each error code
+ */
+export const ERROR_CODE_ICONS: Record<AppErrorCode, LucideIcon> = {
+    UNAUTHENTICATED: ShieldAlert,
+    FORBIDDEN: ShieldAlert,
+    NOT_FOUND: AlertCircle,
+    BAD_REQUEST: AlertTriangle,
+    CONFLICT: AlertTriangle,
+    INTERNAL: AlertCircle,
+    VALIDATION_ERROR: AlertTriangle,
+    RATE_LIMITED: Clock,
+    FEATURE_DISABLED: Ban,
+}
+
+/**
+ * Color classes for each error code
+ */
+export const ERROR_CODE_COLORS: Record<AppErrorCode, string> = {
+    UNAUTHENTICATED: 'text-purple-600 dark:text-purple-400',
+    FORBIDDEN: 'text-red-600 dark:text-red-400',
+    NOT_FOUND: 'text-blue-600 dark:text-blue-400',
+    BAD_REQUEST: 'text-yellow-600 dark:text-yellow-400',
+    CONFLICT: 'text-orange-600 dark:text-orange-400',
+    INTERNAL: 'text-red-600 dark:text-red-400',
+    VALIDATION_ERROR: 'text-yellow-600 dark:text-yellow-400',
+    RATE_LIMITED: 'text-orange-600 dark:text-orange-400',
+    FEATURE_DISABLED: 'text-gray-600 dark:text-gray-400',
+}
+
+/**
+ * Background color classes for error code icons
+ */
+export const ERROR_CODE_BG_COLORS: Record<AppErrorCode, string> = {
+    UNAUTHENTICATED: 'bg-purple-100 dark:bg-purple-900/30',
+    FORBIDDEN: 'bg-red-100 dark:bg-red-900/30',
+    NOT_FOUND: 'bg-blue-100 dark:bg-blue-900/30',
+    BAD_REQUEST: 'bg-yellow-100 dark:bg-yellow-900/30',
+    CONFLICT: 'bg-orange-100 dark:bg-orange-900/30',
+    INTERNAL: 'bg-red-100 dark:bg-red-900/30',
+    VALIDATION_ERROR: 'bg-yellow-100 dark:bg-yellow-900/30',
+    RATE_LIMITED: 'bg-orange-100 dark:bg-orange-900/30',
+    FEATURE_DISABLED: 'bg-gray-100 dark:bg-gray-900/30',
+}
+
+/**
+ * Error severity levels for analytics
+ */
+export const ERROR_CODE_SEVERITY: Record<
+    AppErrorCode,
+    'low' | 'medium' | 'high' | 'critical'
+> = {
+    UNAUTHENTICATED: 'low',
+    FORBIDDEN: 'medium',
+    NOT_FOUND: 'low',
+    BAD_REQUEST: 'medium',
+    CONFLICT: 'medium',
+    INTERNAL: 'critical',
+    VALIDATION_ERROR: 'low',
+    RATE_LIMITED: 'medium',
+    FEATURE_DISABLED: 'low',
+}

package/packages/errors/react/src/hooks/useErrorBoundary.ts

@@ -0,0 +1,92 @@
+// @geenius-tools/errors-react — src/hooks/useErrorBoundary.ts
+
+import { useState, useCallback } from 'react'
+
+export interface UseErrorBoundaryReturn {
+    error: Error | null
+    hasError: boolean
+    setError: (error: Error | null) => void
+    resetError: () => void
+    throwError: (error: Error) => void
+}
+
+/**
+ * Hook for managing error boundary state
+ *
+ * @example
+ * const { error, hasError, setError, resetError } = useErrorBoundary()
+ *
+ * if (hasError) {
+ *   return <div>Error: {error?.message}</div>
+ * }
+ */
+export function useErrorBoundary(): UseErrorBoundaryReturn {
+    const [error, setErrorState] = useState<Error | null>(null)
+
+    const setError = useCallback((error: Error | null) => {
+        setErrorState(error)
+    }, [])
+
+    const resetError = useCallback(() => {
+        setErrorState(null)
+    }, [])
+
+    const throwError = useCallback((error: Error) => {
+        throw error
+    }, [])
+
+    return {
+        error,
+        hasError: error !== null,
+        setError,
+        resetError,
+        throwError,
+    }
+}
+
+/**
+ * Hook for safe async operations with error handling
+ *
+ * @example
+ * const { execute, loading, error } = useAsyncError()
+ *
+ * const handleClick = async () => {
+ *   await execute(async () => {
+ *     await someAsyncOperation()
+ *   })
+ * }
+ */
+export function useAsyncError() {
+    const [loading, setLoading] = useState(false)
+    const [error, setError] = useState<Error | null>(null)
+
+    const execute = useCallback(
+        async <T>(fn: () => Promise<T>): Promise<T | undefined> => {
+            setLoading(true)
+            setError(null)
+
+            try {
+                const result = await fn()
+                setLoading(false)
+                return result
+            } catch (err) {
+                setError(err instanceof Error ? err : new Error(String(err)))
+                setLoading(false)
+                return undefined
+            }
+        },
+        [],
+    )
+
+    const resetError = useCallback(() => {
+        setError(null)
+    }, [])
+
+    return {
+        execute,
+        loading,
+        error,
+        hasError: error !== null,
+        resetError,
+    }
+}

package/packages/errors/react/src/hooks/useErrorHandler.ts

@@ -0,0 +1,87 @@
+// @geenius-tools/errors-react — src/hooks/useErrorHandler.ts
+
+import { useCallback } from 'react'
+import {
+    handleAppError,
+    shouldRetryError,
+    getRetryDelay,
+} from '../utils/errorPolicy'
+import { extractAppError } from '../utils/extractAppError'
+
+/**
+ * Hook for handling errors with the global error policy
+ *
+ * @example
+ * const { handleError } = useErrorHandler()
+ *
+ * try {
+ *   await mutation(...)
+ * } catch (error) {
+ *   handleError(error)
+ * }
+ */
+export function useErrorHandler() {
+    const handleError = useCallback((error: unknown) => {
+        handleAppError(error)
+    }, [])
+
+    return { handleError }
+}
+
+/**
+ * Hook for mutation error handling
+ *
+ * Provides error handler compatible with TanStack Query mutations.
+ *
+ * @example
+ * const mutation = useMutation({
+ *   mutationFn: createUser,
+ *   ...useMutationErrorHandler()
+ * })
+ */
+export function useMutationErrorHandler() {
+    const { handleError } = useErrorHandler()
+
+    return {
+        onError: handleError,
+    }
+}
+
+/**
+ * Hook for query error handling
+ */
+export function useQueryErrorHandler() {
+    const { handleError } = useErrorHandler()
+
+    return {
+        onError: handleError,
+    }
+}
+
+/**
+ * Hook for error retry logic
+ *
+ * Provides retry configuration for TanStack Query based on error type.
+ */
+export function useErrorRetry(maxRetries = 3) {
+    return {
+        retry: (failureCount: number, error: unknown) => {
+            if (failureCount >= maxRetries) return false
+            return shouldRetryError(error)
+        },
+        retryDelay: (attemptIndex: number, error: unknown) => {
+            return getRetryDelay(error, attemptIndex + 1)
+        },
+    }
+}
+
+/**
+ * Hook for getting error information
+ */
+export function useErrorInfo() {
+    const getErrorInfo = useCallback((error: unknown) => {
+        return extractAppError(error)
+    }, [])
+
+    return { getErrorInfo }
+}

package/packages/errors/react/src/index.ts

@@ -0,0 +1,96 @@
+// @geenius-tools/errors-react — src/index.ts
+// Main entry point — everything except Convex-dependent analytics
+
+// ===== Types =====
+export type {
+    AppErrorCode,
+    AppErrorPayload,
+    ValidationError,
+    ErrorDisplayVariant,
+    ErrorAnalyticsFilters,
+    ErrorTrend,
+    ErrorAnalyticsEntry,
+    ErrorMute,
+} from './types'
+
+// ===== Config =====
+export {
+    configureErrorHandler,
+    configureErrorMessages,
+    getErrorHandlerConfig,
+    getErrorMessages,
+    ERROR_MESSAGES_EN,
+    ERROR_MESSAGES_DE,
+} from './config'
+export type {
+    ToastFn,
+    ErrorHandlerConfig,
+    ErrorMessageSet,
+} from './config'
+
+// ===== Constants =====
+export {
+    ERROR_CODE_ICONS,
+    ERROR_CODE_COLORS,
+    ERROR_CODE_BG_COLORS,
+    ERROR_CODE_SEVERITY,
+} from './constants'
+
+// ===== Utils =====
+export {
+    extractAppError,
+    extractRequestId,
+    extractFunctionName,
+    getErrorDetails,
+    normalizeErrorMessage,
+} from './utils/extractAppError'
+
+export {
+    getErrorTitle,
+    getFallbackMessage,
+    getErrorDescription,
+    getErrorAction,
+} from './utils/errorMessages'
+
+export {
+    handleAppError,
+    handleAppErrorSilent,
+    shouldRetryError,
+    getRetryDelay,
+} from './utils/errorPolicy'
+
+export {
+    formatValidationErrors,
+    formatValidationErrorsAsString,
+    getFieldError,
+    getFieldErrors,
+    formatTimestamp,
+    formatRelativeTime,
+    truncateMessage,
+    formatErrorCode,
+} from './utils/formatError'
+
+// ===== Components =====
+export { ErrorBoundary } from './components/ErrorBoundary'
+export type { ErrorBoundaryProps } from './components/ErrorBoundary'
+
+export { ErrorDisplay } from './components/ErrorDisplay'
+export type { ErrorDisplayProps } from './components/ErrorDisplay'
+
+export { ValidationErrors } from './components/ValidationErrors'
+export type { ValidationErrorsProps } from './components/ValidationErrors'
+
+// ===== Hooks =====
+export {
+    useErrorHandler,
+    useMutationErrorHandler,
+    useQueryErrorHandler,
+    useErrorRetry,
+    useErrorInfo,
+} from './hooks/useErrorHandler'
+
+export {
+    useErrorBoundary,
+    useAsyncError,
+} from './hooks/useErrorBoundary'
+export type { UseErrorBoundaryReturn } from './hooks/useErrorBoundary'