@mauroandre/velojs 0.0.36 → 0.0.38

package/agent/skills/velojs-endpoints/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: velojs-endpoints
+description: "Declarative HTTP endpoints in the route tree (`{ method, handler }`) for REST/JSON APIs, webhooks, downloads, health checks — anything returning a `Response` instead of a page. Use when building an API route or receiving a webhook."
+---
+
+# Endpoints
+
+Endpoints are **declarative HTTP routes** you add to `routes.tsx` alongside your pages. Use them for things a page wouldn't make sense for: webhooks, verification links clicked from email, redirects, health checks, OAuth callbacks.
+
+They are registered on the server only — never on the client (wouter). The Vite plugin strips them from the client bundle so server-only handler imports never ship to the browser.
+
+## When to use an endpoint (and when not to)
+
+- **Use an endpoint** for: webhooks (GitHub, Stripe, banks), email verification links, OAuth redirect callbacks, health checks, short redirects, and any URL not meant to be rendered by a page.
+- **Use a page** (`module: SomePage`) when the URL is visited by a human and the server returns HTML.
+- **Use an action** (`action_*` inside a page module) when logic belongs to a page — form submits, mutations triggered by UI.
+
+Rule of thumb: if the URL is part of the UI flow, it's a page or action. If it's an HTTP endpoint hit by something that isn't your frontend, it's an endpoint.
+
+## Declaring an endpoint
+
+Endpoints live in `routes.tsx` as objects with `path`, `method`, and `handler`:
+
+```tsx
+import type { AppRoutes } from "@mauroandre/velojs";
+import * as Home from "./pages/Home.js";
+import { githubWebhook } from "./webhooks/github.handler.js";
+
+export default [
+    { path: "/", module: Home },
+    { path: "/api/github/webhook", method: "POST", handler: githubWebhook },
+] satisfies AppRoutes;
+```
+
+That's it. The endpoint is now registered on the server.
+
+## The handler signature
+
+```ts
+import type { EndpointHandler } from "@mauroandre/velojs";
+
+export const githubWebhook: EndpointHandler = async ({ c, params, query }) => {
+    const body = await c.req.json();
+    // ...your logic...
+    return c.json({ ok: true });
+};
+```
+
+`EndpointHandlerArgs`:
+
+- `c` — the Hono `Context`. Use `c.req.json()` / `c.req.formData()` / `c.req.text()` / `c.req.header(...)` to read the request. Use `c.json(...)`, `c.text(...)`, `c.redirect(...)`, `c.html(...)` to respond.
+- `params` — URL params (`/api/verify/:token` → `params.token`).
+- `query` — query-string values.
+
+Handlers must return a `Response` (or a `Promise<Response>`). Hono helpers like `c.json`, `c.redirect`, `c.text` return `Response` directly. Unlike `action_*`, endpoints do **not** auto-serialize return values — HTTP endpoints need full control over status, headers, and body format (a GitHub webhook, for example, needs the raw body to verify the HMAC signature).
+
+## Supported HTTP methods
+
+`GET`, `POST`, `PUT`, `PATCH`, `DELETE`. One method per entry. If you need both GET and POST on the same path, declare two entries.
+
+## Inline vs module-only handlers
+
+Both forms work. The Vite plugin strips either one from the client bundle.
+
+```tsx
+// OK inline — handler is trivial and doesn't import anything server-only
+{ path: "/health", method: "GET", handler: ({ c }) => c.text("ok") },
+
+// PREFER module — handler imports server-only libraries
+import { githubWebhook } from "./webhooks/github.handler.js";
+{ path: "/api/github/webhook", method: "POST", handler: githubWebhook },
+```
+
+**Recommendation:** when the handler imports anything server-only (`node:crypto`, DB client, SDK that doesn't bundle for the browser), put it in a separate module file. The plugin strips references on the client, so the handler module is tree-shaken away — but putting it in its own file makes the intent obvious to other readers and avoids edge cases where the client bundle tries to resolve server-only imports.
+
+## Grouping and middleware inheritance
+
+Endpoints inherit middlewares from parent nodes, just like pages:
+
+```tsx
+import { rateLimitMiddleware } from "./middlewares/rate-limit.js";
+import { verifyGithubSignature } from "./middlewares/github-sig.js";
+import { githubWebhook } from "./webhooks/github.handler.js";
+import { pixWebhook } from "./webhooks/pix.handler.js";
+
+export default [
+    {
+        path: "/api",
+        middlewares: [rateLimitMiddleware],
+        children: [
+            {
+                path: "/github/webhook",
+                method: "POST",
+                middlewares: [verifyGithubSignature],
+                handler: githubWebhook,
+            },
+            {
+                path: "/pix",
+                method: "POST",
+                handler: pixWebhook,
+            },
+        ],
+    },
+];
+```
+
+- `/api/github/webhook` runs `[rateLimitMiddleware, verifyGithubSignature]` before the handler.
+- `/api/pix` runs `[rateLimitMiddleware]`.
+
+A node can be a **pure group** — only `path`, `children`, and `middlewares`, no `module` and no `handler`. The children inherit the path prefix and middlewares.
+
+## Redirects from email links
+
+A common use case:
+
+```tsx
+import { verifyEmail } from "./auth/verify.handler.js";
+
+// routes.tsx
+{ path: "/verify/:token", method: "GET", handler: verifyEmail }
+```
+
+```ts
+// auth/verify.handler.ts
+import type { EndpointHandler } from "@mauroandre/velojs";
+import { consumeVerifyToken } from "../services/auth.js";
+
+export const verifyEmail: EndpointHandler = async ({ c, params }) => {
+    const ok = await consumeVerifyToken(params.token);
+    if (!ok) return c.redirect("/login?verified=0", 302);
+    return c.redirect("/stacks?verified=1", 302);
+};
+```
+
+Because the endpoint lives in `routes.tsx`, it's also visible to the testing toolkit — you can test the whole flow end-to-end (see below).
+
+## Path conflicts with pages
+
+An endpoint and a page on the same path with the **same method** (both `GET`) conflict. VeloJS registers pages first, endpoints second, and a page handler answers without deferring — so the **page wins and the endpoint is unreachable**. You'll see a loud warning at startup telling you to rename one.
+
+The page has to win: a page `GET` also serves `?_data=1`, the JSON every client-side navigation fetches. An endpoint taking the path over would silently break that page's navigation.
+
+Different methods on the same path (page `GET` + endpoint `POST`) don't conflict. They're both registered and each is routed according to the request method.
+
+## Validation warnings
+
+The server logs a warning and skips the entry when you declare an invalid combination:
+
+| Problem | Warning |
+|---|---|
+| `handler` without `method` | `"handler" set without "method"; endpoint skipped` |
+| `method` without `handler` | `"method" set without "handler"; endpoint skipped` |
+| Both `module` and `handler` on the same node | `both "module" and "handler" set; endpoint ignored, page kept` |
+| `isRoot: true` on an endpoint | `"isRoot" has no effect on endpoint` |
+
+None of these throw — the server still boots. This keeps dev fast; you just see the problem in the console.
+
+## Testing endpoints
+
+Because endpoints live in `routes.tsx`, `createTestApp` picks them up automatically. No bootstrap required for simple webhooks:
+
+```ts
+import { createTestApp } from "@mauroandre/velojs/testing";
+import routes from "../app/routes.js";
+
+const app = await createTestApp({ routes });
+
+const res = await app.post("/api/github/webhook", {
+    headers: { "x-hub-signature-256": signature },
+    body: { action: "push", ref: "refs/heads/main" },
+});
+expect(res.status).toBe(200);
+
+const verify = await app.get("/verify/abc123");
+expect(verify.status).toBe(302);
+expect(verify.headers.location).toBe("/stacks?verified=1");
+```
+
+See [17-testing.md](/docs/testing) for the full testing API.
+
+## Related
+
+- [Routes](/docs/routes) — page routing and layouts
+- [Loaders](/docs/loaders) — page data fetching
+- [Actions](/docs/actions) — mutations from pages
+- [Middlewares](/docs/middlewares) — authentication, logging, rate limiting
+- [Testing](/docs/testing) — the backend testing toolkit