theokit-routes

TheoKit Routes

The route() builder

import { route } from 'theokit/server/define'
import { z } from 'zod'

// GET — no body, optional params/query
export const GET = route()
  .policy('public') // who may call it — required
  .params(z.object({ id: z.coerce.number() })) // URL params
  .query(z.object({ page: z.coerce.number().optional() })) // query string
  .handler(({ params, query }) => ({ id: params.id, page: query?.page }))
  .build()

// POST — body validation + custom status
export const POST = route()
  .policy(({ subject }) => subject !== null) // any authenticated caller
  .body(
    z.object({
      title: z.string().min(3),
      done: z.boolean().default(false),
    }),
  )
  .status(201)
  .handler(({ body }) => {
    // body is fully typed from the Zod schema
    return db.insert(tasks).values(body).returning().get()
  })
  .build()

The chain is .policy(), .params(), .query(), .body(), .status(), .response(), .csrf(), .handler(), and .build() closes it. server/routes/health.ts in this project is a working one — read it rather than this block if the two ever disagree.

.csrf(false) opts a single route out of CSRF enforcement. It is for endpoints that legitimately receive third-party POSTs — a Stripe or WhatsApp webhook, an OAuth callback — which authenticate by signature rather than by session. policy('public') answers a different question (may an unauthenticated caller reach this) and does NOT lift the CSRF gate: without .csrf(false) a webhook is refused CSRF_INVALID before its signature is ever checked.

policy — who may call this route

Required on every exported method. The scanner refuses a route file that omits it and names the file, so absence is a build error rather than a route silently open to everyone.

policy: 'public' // open, and said out loud
policy: ({ subject }) => subject !== null // any authenticated caller
policy: ({ subject, params }) => requireOwner(subject, ownerOf(params.id)) // this subject owns this record