error-envelope

Purpose

Defines Zod schemas for the standard error response envelope used across all Suaveplan API endpoints. By sharing these schemas between server route handlers, React error-boundary hooks, and OpenAPI generators, every layer of the stack interprets error responses identically — no per-client parsing logic, no mismatched field names, and consistent TypeScript types end-to-end.

Features

ErrorEnvelope schema — {code, message, details?} base shape: stable machine-readable code, human-readable message, and an open-typed optional details field
FieldError schema — per-field validation error descriptor with dot-notation field path, message, and optional code; suitable for populating details on 422 responses
ValidationErrorEnvelope schema — extends ErrorEnvelope with details: FieldError[] for typed 422 Unprocessable Entity responses
Stable code strings enable programmatic error handling without string matching on message
details typed as z.unknown() in the base ErrorEnvelope to remain flexible; ValidationErrorEnvelope provides the typed narrowing for validation failures
Full TypeScript inference via z.infer<> — no manual interface duplication
Zod v4 compatible

Usage: Basic Example

import { ErrorEnvelope } from "@suaveplan/api-schemas/common";

// Parse an error response body from a failed API call
const error = ErrorEnvelope.parse({
  code: "AUTH_TOKEN_EXPIRED",
  message: "The access token has expired.",
});
// → { code: "AUTH_TOKEN_EXPIRED", message: "The access token has expired." }

Usage: Advanced Example

import { ValidationErrorEnvelope } from "@suaveplan/api-schemas/common";

// Parse a 422 response body with per-field errors
const validationError = ValidationErrorEnvelope.parse({
  code: "VALIDATION_FAILED",
  message: "Request body failed validation.",
  details: [
    { field: "email", message: "Must be a valid email address.", code: "INVALID_EMAIL" },
    { field: "password", message: "Must be at least 8 characters.", code: "TOO_SHORT" },
  ],
});

// Display field errors in a React form
for (const fieldErr of validationError.details) {
  console.log(`${fieldErr.field}: ${fieldErr.message}`);
}

API Reference

`ErrorEnvelope`

Zod object schema — base error shape for all API error responses.

Field	Type	Description
`code`	`string` (min 1)	Stable machine-readable error code
`message`	`string` (min 1)	Human-readable error description
`details`	`unknown`	Optional structured context (field errors, sub-errors)

Type export: type ErrorEnvelope = z.infer<typeof ErrorEnvelope>

`FieldError`

Zod object schema — per-field validation failure descriptor.

Field	Type	Description
`field`	`string` (min 1)	Dot-notation path to the offending field
`message`	`string` (min 1)	Human-readable validation failure description
`code`	`string`	Optional machine-readable field-error code

Type export: type FieldError = z.infer<typeof FieldError>

`ValidationErrorEnvelope`

Extends ErrorEnvelope — typed 422 response envelope.

Field	Type	Description
`code`	`string`	Inherited from `ErrorEnvelope`
`message`	`string`	Inherited from `ErrorEnvelope`
`details`	`FieldError[]`	Array of per-field validation errors

Type export: type ValidationErrorEnvelope = z.infer<typeof ValidationErrorEnvelope>

Implementation Notes

The base ErrorEnvelope.details field is typed as z.unknown() to support the full range of structured error payloads that Suaveplan endpoints may return — not just field validation errors but also rate-limit metadata, conflict information, or retry-after hints. Callers that know they are dealing with a validation error should narrow to ValidationErrorEnvelope rather than relying on details being unknown.

4.4 KiB Raw Blame History