danyelarguelho21-cmd/estoque-saas / .claude/skills/api-route-scaffold
api-route-scaffold
VerifiedUse when adding a new Next.js App Router API route under services/app/src/app/api/** — new endpoint file (route.ts), new HTTP method on an existing route, or a new list/GET endpoint needing pagination. Also use when reviewing a route.ts diff for missing requireRole/handleRoute or ad-hoc error handling.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.8 KB |
SKILL.md
View on GitHub---
name: api-route-scaffold
description: Use when adding a new Next.js App Router API route under services/app/src/app/api/** — new endpoint file (route.ts), new HTTP method on an existing route, or a new list/GET endpoint needing pagination. Also use when reviewing a route.ts diff for missing requireRole/handleRoute or ad-hoc error handling.
---
# API Route Scaffold
## Overview
All 46+ route files under `services/app/src/app/api/**/route.ts` follow one shape:
`handleRoute(async () => { requireRole/requireSession; parseJsonBody/parseQuery; call the
domain module; return ok/created/noContent })`. `handleRoute` (in `services/app/src/lib/http.ts`)
is the ONLY place that translates errors to the API's standard `{code, message, details,
trace_id}` envelope (`api/openapi/_common.yaml`) — domain code never formats an HTTP response
itself. Deviating from this (hand-rolled try/catch, skipping `requireRole`, validating with raw
`await req.json()`) reintroduces exactly the bug QA finding H-1 fixed: an uncaught Prisma P2025
("no record found") falling through to a generic 500 instead of the documented 404.
## The Pattern (evidence: stock/entries/route.ts, products/route.ts)
```ts
import { z } from "zod";
import { requireRole } from "@/modules/auth";
import { doTheThing } from "@/modules/<domain>";
import { created, handleRoute, ok, parseJsonBody, parseQuery } from "@/lib/http";
const BodySchema = z.object({ /* zod schema mirroring api/openapi/<domain>.yaml */ });
export async function POST(req: Request): Promise<Response> {
return handleRoute(async () => {
const ctx = await requireRole("<domain>:write"); // throws 403 if role lacks permission
const input = await parseJsonBody(req, BodySchema); // throws 400 ValidationError on bad JSON/shape
const result = await doTheThing(ctx.tenantId, ctx.userId, input);
return created(result); // 201; use ok() for 200, noContent() for 204
});
}
```
Never write your own `try { ... } catch { return Response.json(...) }` — `handleRoute` already:
maps any `AppError` subclass (`NotFoundError`, `ValidationError`, `ForbiddenError`,
`UnauthorizedError`, ...) to its documented status/body; maps Prisma's `P2025`
(`findUniqueOrThrow`/`findFirstOrThrow` on an RLS-invisible or missing row) to `NotFoundError`
automatically — this is why domain code is free to use `findUniqueOrThrow` directly instead of
manual null-checks; logs genuinely unexpected errors server-side with a `trace_id` (never leaked
to the client) so failures are traceable instead of silent 500s.
## List Endpoints: Cursor Pagination Convention
Every `GET` list endpoint (evidence: `catalog/products.ts` `listProducts`,
`catalog/suppliers.ts`) uses the same Prisma cursor idiom, never offset/page-number pagination:
```ts
// Route: query schema
const ListQuerySchema = z.object({
cursor: z.string().optional(),
limit: z.coerce.number().int().min(1).max(100).optional(), // ALWAYS clamp -- see HI-1 below
// ...domain filters
});
// Module: query
const limit = filters.limit ?? 20;
const rows = await tx.someModel.findMany({
where: { /* ... */ },
orderBy: [{ createdAt: "desc" }, { id: "desc" }], // tie-break on id -- required for a stable cursor
take: limit + 1, // fetch one extra to detect has_more
...(filters.cursor ? { cursor: { id: filters.cursor }, skip: 1 } : {}),
});
const hasMore = rows.length > limit;
const page = hasMore ? rows.slice(0, limit) : rows;
return { items: page, page: { next_cursor: hasMore ? (page.at(-1)?.id ?? null) : null, has_more: hasMore } };
```
If the list needs a derived value per row (e.g. current stock), batch it with ONE query over the
whole page's ids (see `getCurrentStockForProducts` in `stock-operation-scaffold`), never one
query per row in a loop — that exact per-row loop was code-reviewer finding HI-1 across four
endpoints, precisely because a hand-written list endpoint skipped this convention.
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Custom try/catch instead of `handleRoute` | Always wrap the whole handler body in `handleRoute(async () => { ... })` |
| Calling the domain function before `requireRole`/`requireSession` | Auth check is always the FIRST line inside `handleRoute`'s callback |
| Validating body with raw `await req.json()` | Use `parseJsonBody(req, ZodSchema)` — gets the standard 400 `ValidationError` shape for free |
| Unbounded `limit` on a list endpoint | `z.coerce.number().int().min(1).max(100).optional()` — an unclamped limit turns a list endpoint into an unbounded query |
| Per-row query in a `.map`/loop over a list result | Batch with `WHERE id = ANY($1)`-style query over the whole page, per HI-1 |
| New AppError-like condition without a subclass | Add/reuse an `AppError` subclass in `libs/shared` so `handleRoute`/`toErrorResponse` map it automatically — don't format `Response.json` by hand in domain code |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |