# @geenius/errors

Framework-agnostic structured error handling for the Geenius ecosystem.

`@geenius/errors` publishes a single public entrypoint: the package root. It
does not publish `/shared`, `/react`, `/react-css`, `/solidjs`, or other UI
subpaths. UI error boundaries and visual error displays belong in downstream UI
packages.

## Install

```sh
pnpm add @geenius/errors
```

## Usage

```ts
import {
  ErrorCode,
  GeeniusError,
  RateLimitError,
  catchError,
  formatError,
  isErrorCode,
  isGeeniusError,
  makeSafe,
  serializeError,
} from '@geenius/errors'

const error = new RateLimitError({
  message: 'Too many requests',
  context: { bucket: 'api' },
})

const payload = serializeError(error)

isGeeniusError(payload) // true
isErrorCode(payload, ErrorCode.RATE_LIMIT) // true
formatError(error).statusCode // 429
```

Go-style tuple helpers are available for async and sync code:

```ts
const [user, loadError] = await catchError(loadUser(userId), (cause) =>
  new GeeniusError({
    code: ErrorCode.INTERNAL_ERROR,
    message: 'Unable to load user',
    cause,
  }),
)

const safeParse = makeSafe(JSON.parse)
const [value, parseError] = safeParse(input)
```

## API Reference

Error classes:

- `GeeniusError`
- `ValidationError`
- `AuthError`
- `UnauthorizedError`
- `NotFoundError`
- `ConflictError`
- `RateLimitError`
- `InternalServerError`

Core helpers:

- `ErrorCode`
- `getStatusCodeForErrorCode`
- `getErrorCodesForStatusCode`
- `formatError`
- `serializeError`
- `deserializeError`
- `isGeeniusError`
- `isErrorCode`
- `catchError`
- `makeSafe`

Framework-free display helpers:

- `ERROR_DISPLAY_TONES`
- `ERROR_DISPLAY_DENSITIES`
- `normalizeErrorSummary`
- `formatValidationIssues`
- `createErrorReportEnvelope`
- `shouldExposeErrorDetails`
- `isErrorDisplayTone`
- `isErrorDisplayDensity`

Public types:

- `GeeniusErrorOptions`
- `GeeniusErrorKind`
- `SerializedGeeniusError`
- `GeeniusErrorLike`
- `KnownGeeniusError`
- `ErrorTuple`
- `ErrorHandler`
- `FormatErrorOptions`
- `FormattedError`
- `ErrorDisplayTone`
- `ErrorDisplayDensity`
- `ValidationIssue`
- `NormalizedErrorSummary`
- `ErrorReportEnvelope`
- `ErrorReportOptions`

## Public Surface

Only this import is supported:

```ts
import { GeeniusError } from '@geenius/errors'
```

Historical UI scaffold packages remain private and out of scope for this V1
surface. Do not import private package subpaths; the root export map rejects
them.

## Testing

```sh
pnpm build
pnpm type-check
pnpm lint
pnpm test
pnpm test:exports
pnpm test:dist-contract
pnpm test:packed-smoke
pnpm audit:supply-chain
pnpm test:license
```

## License

FSL-1.1-Apache-2.0. See [`LICENSE`](./LICENSE).