adilallo
86 lines
3.2 KiB
Plaintext
86 lines
3.2 KiB
Plaintext
---
|
|
description: App Router API handler conventions (Next.js + Prisma + Zod)
|
|
globs: app/api/**/*.ts,lib/server/**/*.ts
|
|
alwaysApply: false
|
|
---
|
|
|
|
# API route anatomy
|
|
|
|
Every DB-touching handler in `app/api/**/route.ts` follows the same skeleton.
|
|
Keep new routes within this shape so auth, config, and validation stay uniform.
|
|
|
|
1. **Config guard (first line of the handler).**
|
|
|
|
```typescript
|
|
if (!isDatabaseConfigured()) return dbUnavailable();
|
|
```
|
|
|
|
From `lib/server/env` + `lib/server/responses`. Returns a consistent 503
|
|
when `CLOUDRON_POSTGRESQL_URL` is missing (local dev, preview builds).
|
|
|
|
2. **Auth (when the route requires a user).**
|
|
|
|
```typescript
|
|
const user = await getSessionUser();
|
|
if (!user) {
|
|
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
|
|
}
|
|
```
|
|
|
|
From `lib/server/session`. Never read session cookies or tokens directly.
|
|
|
|
3. **Body parsing + validation (POST/PUT/PATCH).**
|
|
|
|
```typescript
|
|
const parsed = await readLimitedJson(request);
|
|
const result = mySchema.safeParse(parsed);
|
|
if (!result.success) return jsonFromZodError(result.error);
|
|
```
|
|
|
|
Helpers live in `lib/server/validation/{requestBody,zodHttp}.ts`. All
|
|
payload schemas belong in `lib/server/validation/*.ts` (today:
|
|
`createFlowSchemas.ts`) — colocate new schemas there rather than inline in
|
|
the route.
|
|
|
|
4. **Prisma access** via `import { prisma } from "lib/server/db"`. Do not
|
|
instantiate `PrismaClient` directly.
|
|
|
|
5. **Responses** via `NextResponse.json(...)`. Shared shapes
|
|
(`dbUnavailable`, `unauthorized`, `notFound`, `rateLimited`,
|
|
`serverMisconfigured`, `internalError`) and the generic `errorJson(code,
|
|
message, status, opts?)` live in `lib/server/responses.ts`. Add new
|
|
shared responses there when a pattern repeats in two routes.
|
|
|
|
6. **Errors + observability.** All 4xx/5xx bodies use the canonical shape
|
|
`{ error: { code, message }, details? }` with codes from the
|
|
`ApiErrorCode` union in `lib/server/responses.ts`. Wrap handlers with
|
|
`apiRoute("scope.name", async (req, ctx, { requestId }) => { ... })`
|
|
from `lib/server/apiRoute.ts` so an `x-request-id` is generated /
|
|
forwarded onto every response and uncaught throws return a canonical
|
|
500 with the id logged via `lib/logger`.
|
|
|
|
# Server-only isolation
|
|
|
|
`lib/server/*` is the server boundary. Anything that:
|
|
|
|
- imports `@prisma/client`,
|
|
- reads secrets from `env`,
|
|
- sends email, hashes tokens, or touches sessions
|
|
|
|
…lives under `lib/server/`. Never import `lib/server/*` from client
|
|
components, `app/components/**`, or any file marked `"use client"`. Shared
|
|
logic safe for both sides goes in `lib/*`.
|
|
|
|
# Deferred — follow existing code, don't invent
|
|
|
|
These areas are still settling. Match whatever the nearest route already does
|
|
instead of introducing new patterns:
|
|
|
|
- **Rate limiting.** `lib/server/rateLimit.ts` is an in-memory stopgap marked
|
|
for replacement. Reuse `rateLimitKey()` where limiting is needed; don't
|
|
design a new limiter. When returning 429, prefer `rateLimited(retryAfterMs)`
|
|
from `responses.ts` so the body and `Retry-After` header stay uniform.
|
|
- **Pagination / filtering.** Only `rules/route.ts` paginates (`take` capped
|
|
at 100). Mirror it if you add list endpoints; don't invent cursors or
|
|
offset contracts unilaterally.
|