create-api-endpoints

name	create-api-endpoints
description	Use when creating new Next.js route handlers using the custom helper wrapper.

Create API Endpoints Playbook

To build route handlers quickly and securely without writing boilerplate validation or session-guard blocks, use the custom createApiRoute helper located in src/lib/api.ts.

Step-by-Step Flow:

1. Import the Helper & Zod:

   import { createApiRoute } from "@/lib/api";
   import { z } from "zod";
   import { prisma } from "@/lib/prisma";
   

2. Define the Route Handler: Wrap your execution inside createApiRoute. You can specify guards and parse schemas:

   export const POST = createApiRoute({
     requireAuth: true,     // Optional: set true to force user login
     requireAdmin: false,   // Optional: set true to restrict to ADMIN role
     schema: z.object({     // Optional: parses and validates JSON body
       amount: z.number().positive(),
       description: z.string().min(3)
     }),
     handler: async (req, { session, body, params }) => {
       // Request body is parsed and typed
       // Session details are guaranteed to be active
       const newRecord = await prisma.item.create({
         data: {
           title: body.description,
           category: "LOGS",
           ownerId: session.user.id
         }
       });
       
       // Simply return your database result object.
       // The wrapper automatically sends status 200 with JSON payload.
       return newRecord;
     }
   });
   

3. Exception Handling: Do not wrap the inner handler in extensive try/catch blocks unless you want custom responses. The wrapper intercepts database errors and returns a formatted 500 Internal Server Error automatically.