Zod Route

Le module zod-route.ts fournit des handlers d'API type-safe via next-zod-route avec validation, authentification et autorisation integrees.

Handlers disponibles

route - Handler de base

Handler de base avec gestion automatique des erreurs et validation. Pas d'authentification requise.

import { route } from "@/lib/zod-route";

export const POST = route
  .params(z.object({ id: z.string() }))
  .body(z.object({ name: z.string() }))
  .query(z.object({ page: z.number().optional() }))
  .handler(async (req, { params, body, query }) => {
    return { success: true };
  });

authRoute - Handler authentifie

Requiert une session utilisateur valide. Fournit ctx.user dans le handler.

import { authRoute } from "@/lib/zod-route";

export const GET = authRoute.handler(async (req, { ctx }) => {
  const { user } = ctx;
  return { userId: user.id };
});

orgRoute - Handler d'organisation

Requiert l'appartenance a une organisation avec des verifications de roles/permissions optionnelles. Fournit ctx.organization dans le handler.

import { orgRoute } from "@/lib/zod-route";

// Route d'organisation basique
export const GET = orgRoute.handler(async (req, { ctx }) => {
  const { organization } = ctx;
  return { orgId: organization.id };
});

// Avec permissions
export const POST = orgRoute
  .metadata({ permissions: { users: ["create"] } })
  .body(z.object

Validation des requetes

Parametres d'URL

Utilisez .params() pour les segments dynamiques :

// Route : /api/users/[id]/route.ts
export const GET = route
  .params(z.object({ id: z.string().uuid() }))
  .handler(async (req, { params }) => {
    return await getUser(params.id);
  });

Corps de la requete

Utilisez .body() pour valider le JSON :

export const POST = route
  .body(
    z.object({
      name: z.string().min(1),
      email: z.string().email(),
      age: z.number().positive().optional(),
    }),
  )
  .handler(async (req, { body }) => {
    return await createUser(body);

Parametres de requete

Utilisez .query() pour les parametres d'URL :

export const GET = route
  .query(
    z.object({
      page: z.coerce.number().default(1),
      limit: z.coerce.number().default(10),
      search: z.string().optional(),
    }),
  )
  .handler(async (req, { query }) => {
    return await listItems(query);

Gestion des erreurs

Les handlers gerent automatiquement les erreurs :

Type d'erreur	Statut	Comportement
ZodRouteError	Custom	Retourne le message avec le statut specifie
ApplicationError	400	Retourne le message d'erreur
Erreur inconnue (dev)	500	Retourne le message complet
Erreur inconnue (prod)	500	Retourne "Internal server error"

Lancer des erreurs

import { ZodRouteError } from "@/lib/errors/zod-route-error";

export const GET = authRoute
  .params(z.object({ id: z.string() }))
  .handler(async (req, { params, ctx }) => {
    const item = await getItem(params.id);

    if (!item) {
      throw new ZodRouteError("Item not found", 404

Metadonnees d'autorisation

Utilisez .metadata() avec orgRoute pour definir les roles ou permissions requis :

// Exiger des roles specifiques
export const DELETE = orgRoute
  .metadata({ roles: ["admin", "owner"] })
  .handler(async (req, { ctx }) => {
    // Seuls admin ou owner peuvent acceder
  });

// Exiger des permissions specifiques
export const POST = orgRoute
  .metadata({ permissions: { billing: ["update"] } })
  .handler(async (req, { ctx