Relevant source files

The following files were used as context for generating this wiki page: - [packages/errors/src/index.ts](https://github.com/lwhite702/wrelik-kit/blob/main/packages/errors/src/index.ts) - [packages/errors/package.json](https://github.com/lwhite702/wrelik-kit/blob/main/packages/errors/package.json) - [README.md](https://github.com/lwhite702/wrelik-kit/blob/main/README.md) - [DECISIONS.md](https://github.com/lwhite702/wrelik-kit/blob/main/DECISIONS.md) - [packages/db/src/index.ts](https://github.com/lwhite702/wrelik-kit/blob/main/packages/db/src/index.ts) - [packages/auth/src/index.test.ts](https://github.com/lwhite702/wrelik-kit/blob/main/packages/auth/src/index.test.ts)

# Error Handling (@wrelik/errors) The `@wrelik/errors` package serves as the centralized error management system for the Wrelik ecosystem. It provides a set of typed application errors and integration with Sentry for centralized tracking. By standardizing error structures, the package ensures consistent error reporting across all shared packages and consumer applications. Sources: [README.md:23-24](), [DECISIONS.md:12]() ## Core Architecture The architecture is built around a base `AppError` class that extends the native JavaScript `Error`. This base class introduces specialized properties for error codes and HTTP status codes, enabling programmatic handling in API layers. The package integrates with `@sentry/node` to provide global error monitoring. ### Error Class Hierarchy The system uses inheritance to define specific error types used throughout the monorepo: ```mermaid classDiagram class Error { <> +string message } class AppError { +string code +number statusCode +Record context +constructor(message, code, statusCode, context) } class AuthRequiredError { +constructor(message, context) } class TenantRequiredError { +constructor(message, context) } class PermissionDeniedError { +constructor(message, context) } class ValidationError { +constructor(message, context) } Error <|-- AppError AppError <|-- AuthRequiredError AppError <|-- TenantRequiredError AppError <|-- PermissionDeniedError AppError <|-- ValidationError ``` The diagram shows the relationship between the native Error object and the specialized typed errors provided by the package. Sources: [packages/errors/src/index.ts:3-50]() ### Error Definitions | Class | Error Code | Default Status | Description | | :--- | :--- | :--- | :--- | | `AppError` | (Variable) | 500 | Base class for all application errors. | | `AuthRequiredError` | `AUTH_REQUIRED` | 401 | Thrown when a user session is missing or invalid. | | `TenantRequiredError` | `TENANT_REQUIRED` | 400 | Thrown when a multi-tenant operation lacks a tenant context. | | `PermissionDeniedError` | `PERMISSION_DENIED` | 403 | Thrown when a user lacks sufficient RBAC permissions. | | `ValidationError` | `VALIDATION_ERROR` | 400 | Thrown when input data fails validation logic. | Sources: [packages/errors/src/index.ts:3-50]() ## Reporting and Monitoring The package provides utilities for capturing errors and managing user context in Sentry. ### Error Capture Logic The `captureError` function manages how errors are logged and reported based on their type and severity: ```mermaid flowchart TD Start([Capture Error]) --> TypeCheck{Is AppError?} TypeCheck -- Yes --> LogWarn[Log Warning with Code] LogWarn --> SeverityCheck{Status >= 500?} SeverityCheck -- Yes --> SentryApp[Report to Sentry] SeverityCheck -- No --> End([End]) TypeCheck -- No --> LogErr[Log Error Message] LogErr --> SentryUn[Report to Sentry] SentryApp --> End SentryUn --> End ``` The flow shows that while all errors are logged locally, only server-side errors (500+) or unexpected errors are forwarded to Sentry. Sources: [packages/errors/src/index.ts:52-66]() ### Monitoring Configuration Global monitoring is configured through initialization and context-setting functions: * **`initErrors(dsn: string)`**: Initializes the Sentry SDK with a 1.0 traces sample rate. * **`setUserContext(user)`**: Associates subsequent errors with a specific user ID and optional email. * **`captureError(err, context)`**: A unified entry point for error reporting that handles both `AppError` instances and unknown error types. Sources: [packages/errors/src/index.ts:52-79](), [packages/errors/package.json:16]() ## Cross-Package Integration Other packages in the `@wrelik` scope rely on these error definitions to enforce business rules and security boundaries. * **@wrelik/auth**: Uses `AuthRequiredError` within the `requireUser` helper to enforce authentication state. * **@wrelik/db**: Uses `TenantRequiredError` and `PermissionDeniedError` within tenant access checkers and the `withTenant` wrapper to ensure data isolation. * **@wrelik/storage & @wrelik/analytics**: Depend on `@wrelik/errors` to provide consistent failure responses during service interactions. Sources: [packages/auth/src/index.test.ts:7-10](), [packages/db/src/index.ts:1-25](), [packages/storage/package.json:14](), [packages/analytics/package.json:14]() ## Summary The `@wrelik/errors` package is a foundational infrastructure component that standardizes how failures are represented and monitored. By using Sentry as the backend and providing a strictly typed hierarchy of error classes, it enables reliable error tracking and predictable error handling across the entire monorepo.