lakebed 0.0.17 → 0.0.19

package/src/cli.js

@@ -31,26 +31,27 @@ const packageNodeModules = resolve(packageDir, "node_modules");
 const sourceNamespace = "lakebed-source";
 const defaultDeployApiUrl = "https://api.lakebed.app";
 const execFileAsync = promisify(execFile);
+const endpointBodyMaxBytes = 2 * 1024 * 1024;
 
 function usage() {
   console.log(`lakebed
 
 Usage:
-  lakebed new [name] [--template todo] [--no-git]
-  lakebed create [name] [--template todo] [--no-git]
-  lakebed dev [capsule-dir] [--port 3000]
-  lakebed build [capsule-dir] --target anonymous [--out .lakebed/artifacts/app.json] [--json]
-  lakebed deploy [capsule-dir] [--api <url>] [--public-inspect] [--json]
-  lakebed claim [capsule-dir] [--api <url>] [--json]
-  lakebed domains add <subdomain.lakebed.app> [--api <url>] [--json]
-  lakebed anonymous-server [--port 8787] [--public-root-url <url>] [--app-base-domain <domain>]
-  lakebed inspect <deploy-id-or-url> [--api <url>] [--inspect-token <token>] [--json]
-  lakebed run-many [capsule-dir] [--count 20] [--base-port 4000]
-  lakebed auth as <name>
-  lakebed auth reset
-  lakebed db list [deploy-id-or-url] [--port 3000] [--inspect-token <token>]
-  lakebed db dump [deploy-id-or-url] [--port 3000] [--inspect-token <token>]
-  lakebed logs [deploy-id-or-url] [--port 3000] [--inspect-token <token>]
+  npx lakebed new [name] [--template todo] [--no-git]
+  npx lakebed create [name] [--template todo] [--no-git]
+  npx lakebed dev [capsule-dir] [--port 3000]
+  npx lakebed build [capsule-dir] --target anonymous [--out .lakebed/artifacts/app.json] [--json]
+  npx lakebed deploy [capsule-dir] [--api <url>] [--public-inspect] [--json]
+  npx lakebed claim [capsule-dir] [--api <url>] [--json]
+  npx lakebed domains add <subdomain.lakebed.app> [--api <url>] [--json]
+  npx lakebed anonymous-server [--port 8787] [--public-root-url <url>] [--app-base-domain <domain>]
+  npx lakebed inspect <deploy-id-or-url> [--api <url>] [--inspect-token <token>] [--json]
+  npx lakebed run-many [capsule-dir] [--count 20] [--base-port 4000]
+  npx lakebed auth as <name>
+  npx lakebed auth reset
+  npx lakebed db list [deploy-id-or-url] [--port 3000] [--inspect-token <token>]
+  npx lakebed db dump [deploy-id-or-url] [--port 3000] [--inspect-token <token>]
+  npx lakebed logs [deploy-id-or-url] [--port 3000] [--inspect-token <token>]
 `);
 }
 
@@ -455,6 +456,177 @@ function sendJson(ws, message) {
   ws.send(JSON.stringify(message));
 }
 
+async function readRequestBody(req, maxBytes = endpointBodyMaxBytes) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of req) {
+    total += chunk.byteLength;
+    if (total > maxBytes) {
+      throw new Error(`Request body exceeds ${maxBytes} bytes.`);
+    }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+function headersFromNodeRequest(headers) {
+  const clean = {};
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    if (Array.isArray(value)) {
+      clean[name.toLowerCase()] = value.join(", ");
+    } else if (value !== undefined) {
+      clean[name.toLowerCase()] = String(value);
+    }
+  }
+  return clean;
+}
+
+function createEndpointRequest({ body, headers, method, url }) {
+  const requestUrl = new URL(url.href);
+  const headerMap = new Map(Object.entries(headersFromNodeRequest(headers)));
+  const requestBody = Buffer.from(body);
+
+  return {
+    headers: {
+      entries() {
+        return headerMap.entries();
+      },
+      get(name) {
+        return headerMap.get(String(name).toLowerCase()) ?? null;
+      },
+      has(name) {
+        return headerMap.has(String(name).toLowerCase());
+      }
+    },
+    method: String(method ?? "GET").toUpperCase(),
+    path: requestUrl.pathname,
+    query: new URLSearchParams(requestUrl.searchParams),
+    url: requestUrl.href,
+    async bytes() {
+      return new Uint8Array(requestBody);
+    },
+    async json() {
+      return JSON.parse(requestBody.toString("utf8"));
+    },
+    async text() {
+      return requestBody.toString("utf8");
+    }
+  };
+}
+
+function endpointBodyToBuffer(body) {
+  if (body === undefined || body === null) {
+    return Buffer.alloc(0);
+  }
+  if (Buffer.isBuffer(body)) {
+    return body;
+  }
+  if (typeof body === "string") {
+    return Buffer.from(body, "utf8");
+  }
+  if (body instanceof ArrayBuffer) {
+    return Buffer.from(body);
+  }
+  if (ArrayBuffer.isView(body)) {
+    return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+  }
+  return Buffer.from(JSON.stringify(body ?? null), "utf8");
+}
+
+function endpointStatus(status, fallback = 200) {
+  const parsed = Number(status);
+  return Number.isInteger(parsed) && parsed >= 100 && parsed <= 599 ? parsed : fallback;
+}
+
+function headersToObject(headers = {}) {
+  if (!headers) {
+    return {};
+  }
+  if (typeof headers.entries === "function") {
+    return Object.fromEntries(Array.from(headers.entries()).map(([key, value]) => [String(key), String(value)]));
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers.map(([key, value]) => [String(key), String(value)]));
+  }
+  if (typeof headers === "object") {
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [String(key), String(value)]));
+  }
+  return {};
+}
+
+async function normalizeEndpointResponse(result) {
+  if (result === undefined || result === null) {
+    return { body: Buffer.alloc(0), headers: {}, status: 204 };
+  }
+
+  if (typeof Response !== "undefined" && result instanceof Response) {
+    return {
+      body: Buffer.from(await result.arrayBuffer()),
+      headers: headersToObject(result.headers),
+      status: endpointStatus(result.status)
+    };
+  }
+
+  if (typeof result === "object" && result?.kind === "response") {
+    return {
+      body: endpointBodyToBuffer(result.body),
+      headers: headersToObject(result.headers),
+      status: endpointStatus(result.status)
+    };
+  }
+
+  if (typeof result === "string") {
+    return {
+      body: endpointBodyToBuffer(result),
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+      status: 200
+    };
+  }
+
+  return {
+    body: endpointBodyToBuffer(result),
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+    status: 200
+  };
+}
+
+function sanitizeEndpointResponseHeaders(headers = {}) {
+  const blocked = new Set(["connection", "content-length", "date", "keep-alive", "transfer-encoding", "upgrade"]);
+  const clean = {};
+  for (const [rawName, rawValue] of Object.entries(headers)) {
+    const name = String(rawName);
+    const lower = name.toLowerCase();
+    if (!/^[a-z0-9!#$%&'*+.^_`|~-]+$/i.test(name) || blocked.has(lower)) {
+      continue;
+    }
+    clean[name] = String(rawValue);
+  }
+  return clean;
+}
+
+function sendEndpointResponse(res, response) {
+  const body = response.body ?? Buffer.alloc(0);
+  res.writeHead(response.status, {
+    ...sanitizeEndpointResponseHeaders(response.headers),
+    "Content-Length": String(body.byteLength)
+  });
+  res.end(body);
+}
+
+function endpointDefinitions(app) {
+  return Object.entries(app.endpoints ?? {}).map(([name, endpoint]) => ({
+    handler: endpoint?.handler ?? endpoint,
+    method: String(endpoint?.method ?? "").toUpperCase(),
+    name,
+    path: String(endpoint?.path ?? "")
+  }));
+}
+
+function findEndpoint(app, method, path) {
+  const requestMethod = String(method ?? "GET").toUpperCase();
+  return endpointDefinitions(app).find((endpoint) => endpoint.method === requestMethod && endpoint.path === path) ?? null;
+}
+
 async function capsuleFileFingerprint(rootDir, dir = rootDir, entries = []) {
   const dirEntries = await readdir(dir, { withFileTypes: true });
 
@@ -518,6 +690,25 @@ async function runMutation({ app, stateCell, auth, logs, env, name, args }) {
   );
 }
 
+async function runEndpoint({ app, stateCell, auth, logs, env, endpoint, request }) {
+  if (typeof endpoint.handler !== "function") {
+    throw new Error(`Unknown endpoint: ${endpoint.name}`);
+  }
+
+  return stateCell.transaction(async (db) => {
+    const result = await endpoint.handler(
+      {
+        auth,
+        db,
+        env,
+        log: logs.createLogger()
+      },
+      request
+    );
+    return normalizeEndpointResponse(result);
+  });
+}
+
 export async function startDevServer({
   capsuleDir,
   sourceStore,
@@ -596,6 +787,38 @@ export async function startDevServer({
         return;
       }
 
+      const endpoint = findEndpoint(currentBuild.app, req.method, requestUrl.pathname);
+      if (endpoint) {
+        const auth = await resolveAuthFromUrl({
+          defaultAuth,
+          onError: (error) => {
+            logs.append("warn", "endpoint auth verification failed", { error: error instanceof Error ? error.message : String(error) });
+          },
+          origin: requestOrigin(req),
+          shooBaseUrl,
+          url: requestUrl
+        });
+        const body = await readRequestBody(req);
+        const endpointRequest = createEndpointRequest({
+          body,
+          headers: req.headers,
+          method: req.method,
+          url: requestUrl
+        });
+        const { result: response } = await runEndpoint({
+          app: currentBuild.app,
+          auth,
+          endpoint,
+          env: currentBuild.env,
+          logs,
+          request: endpointRequest,
+          stateCell
+        });
+        sendEndpointResponse(res, response);
+        await publishAll();
+        return;
+      }
+
       res.writeHead(404);
       res.end("Not found");
     } catch (error) {
@@ -844,7 +1067,7 @@ export default capsule({
         <p className="text-sm font-semibold uppercase tracking-wide text-cyan-300">Lakebed deploy</p>
         <h1 className="mt-3 text-3xl font-semibold">Claim required</h1>
         <p className="mt-4 text-neutral-300">
-          This capsule uses ${feature}. Claim this deploy, then run lakebed deploy again to publish the app.
+          This capsule uses ${feature}. Claim this deploy, then run npx lakebed deploy again to publish the app.
         </p>
       </section>
     </main>
@@ -950,7 +1173,7 @@ function claimUrlFromDeployMetadata(metadata) {
 }
 
 function claimCommandText({ api, capsuleArg }) {
-  const parts = ["lakebed", "claim"];
+  const parts = ["npx", "lakebed", "claim"];
   if (capsuleArg) {
     parts.push(capsuleArg);
   }
@@ -1088,7 +1311,7 @@ async function readResponseJson(response) {
 
 async function deployCommand(args) {
   if (args.some((arg) => arg === "--ttl" || arg.startsWith("--ttl="))) {
-    throw new Error("lakebed deploy no longer accepts --ttl. Deploy expiry is set by the server.");
+    throw new Error("npx lakebed deploy no longer accepts --ttl. Deploy expiry is set by the server.");
   }
 
   const [capsuleArg] = positionals(args);
@@ -1115,7 +1338,7 @@ async function deployCommand(args) {
   if (!currentDeploy?.claimed && hasServerEnvValues) {
     if (canUpdate && currentDeploy) {
       throw new Error(
-        `This capsule defines server env in ${SERVER_ENV_FILE}.\n\nThis deploy is still anonymous. Claim it first, then run lakebed deploy again to sync server env.`
+        `This capsule defines server env in ${SERVER_ENV_FILE}.\n\nThis deploy is still anonymous. Claim it first, then run npx lakebed deploy again to sync server env.`
       );
     }
     try {
@@ -1132,7 +1355,7 @@ async function deployCommand(args) {
     } catch (error) {
       if (error instanceof AnonymousCompilerError && canUpdate && currentDeploy && !currentDeploy.claimed) {
         throw new Error(
-          `${error.message}\n\nThis deploy is still anonymous. Claim it first, then run lakebed deploy again to use server-side fetch.`
+          `${error.message}\n\nThis deploy is still anonymous. Claim it first, then run npx lakebed deploy again to use server-side fetch.`
         );
       }
       if ((!canUpdate || !currentDeploy) && canDeployAfterClaim(error)) {
@@ -1214,7 +1437,7 @@ async function deployCommand(args) {
   if (deployed.claimUrl) {
     console.log(`Claim:      ${claimCommandText({ api, capsuleArg })}`);
   }
-  console.log(`Inspect:    lakebed inspect ${deployed.deployId}`);
+  console.log(`Inspect:    npx lakebed inspect ${deployed.deployId}`);
   if (deployed.inspectPolicy === "public") {
     console.log("Inspect policy: public - data and logs are readable by anyone with the app URL.");
   }
@@ -1232,7 +1455,7 @@ async function deployCommand(args) {
   }
   if (envelope.claimRequired) {
     console.log("\nThis app needs a claimed deploy before server-side fetch or server env can run.");
-    console.log(`Run ${claimCommandText({ api, capsuleArg })}, then run lakebed deploy again.`);
+    console.log(`Run ${claimCommandText({ api, capsuleArg })}, then run npx lakebed deploy again.`);
   }
 }
 
@@ -1243,7 +1466,7 @@ async function claimCommand(args) {
   const metadata = await readDeployMetadata(capsuleDir);
 
   if (!metadata) {
-    throw new Error(`No Lakebed deploy metadata found at ${deployMetadataPath(capsuleDir)}. Run lakebed deploy from this project first.`);
+    throw new Error(`No Lakebed deploy metadata found at ${deployMetadataPath(capsuleDir)}. Run npx lakebed deploy from this project first.`);
   }
 
   if (metadata.api !== api) {
@@ -1307,7 +1530,7 @@ async function domainsCommand(args) {
   const api = deployApiUrl(args);
   const metadata = await readDeployMetadata(capsuleDir);
   if (!metadata) {
-    throw new Error(`No Lakebed deploy metadata found at ${deployMetadataPath(capsuleDir)}. Run lakebed deploy from this project first.`);
+    throw new Error(`No Lakebed deploy metadata found at ${deployMetadataPath(capsuleDir)}. Run npx lakebed deploy from this project first.`);
   }
   if (metadata.api !== api) {
     throw new Error(`Saved deploy metadata is for ${metadata.api}, but this command is using ${api}. Pass --api ${metadata.api} to use it.`);
@@ -1432,6 +1655,10 @@ async function inspectCommand(args) {
   if (Array.isArray(manifest.mutations)) {
     console.log(`Mutations: ${manifest.mutations.join(", ") || "(none)"}`);
   }
+  if (Array.isArray(manifest.endpoints)) {
+    const endpoints = manifest.endpoints.map((endpoint) => `${endpoint.method} ${endpoint.path} -> ${endpoint.name}`);
+    console.log(`Endpoints: ${endpoints.join(", ") || "(none)"}`);
+  }
   if (Array.isArray(manifest.mutationDetails) && manifest.mutationDetails.length > 0) {
     console.log("Mutation runtime:");
     for (const detail of manifest.mutationDetails) {
@@ -1508,13 +1735,34 @@ async function dbCommand(args) {
 }
 
 function agentInstructionsTemplate() {
-  return `# Lakebed App Instructions
+  return `# Building with Lakebed.
 
-This is a Lakebed capsule. Build the app inside this directory using the Lakebed v0 contract.
+This directory is for a Lakebed "capsule". Lakebed is an all-inclusive suite of tools to build web applications purely from code and a CLI.
 
-## File Layout
+Your role is to build software within this capsule. Lakebed is the runtime, the compiler, the database, and the hosting platform. You will be able to control all of this just by writing code and running commands through the CLI.
+
+## Hard rules
+
+- No installing node modules. You can use the built-in APIs. Write TypeScript for anything that is not included.
+- Lakebed CLI should always be run with \`npx lakebed [command]\`. It is not a global. Launch with \`npx\` always.
+- All client code goes in the \`client\` directory, and all server code goes in the \`server\` directory. Shared code can go in \`shared\`.
+- Use \`lakebed/server\` only from \`server/*.ts\`.
+- Use \`lakebed/client\` only from \`client/*.tsx\`.
+- Data needed on client should be fetched through queries. User-driven changes should be done via mutations. Endpoints should be treated as an "escape hatch" for exposing functionality over endpoints for HTTP-based flows.
+- Styling must be done via raw CSS or Tailwind classes in the JSX.
+- Do not add a CSS, PostCSS, or Tailwind build pipeline. They are built in.
+- There is no file based routing. You can define routes yourself through typescript.
+- All imports must be from Lakebed or from relative paths.
+- Do not use Node built-ins in app code.
+- Use auth through \`ctx.auth\` on the server and \`useAuth()\` on the client.
+- Read server-only environment variables through \`ctx.env\`; define them in \`.env.lakebed.server\`.
+- Auth can be added with a Google sign-in using \`<SignInWithGoogle />\` or \`signInWithGoogle()\` from \`lakebed/client\`.
+- Keep \`shared/\` free of DOM, Node, env, and Lakebed runtime imports.
+- Environment variables are only available on the server, and must be defined in \`.env.lakebed.server\`. They are not available during build time. If you need build-time environment variables, define them in code and do conditional logic based on them. They will be synced with production on \`npx lakebed deploy\`.
 
-- \`server/index.ts\`: schema, queries, and mutations.
+## Default project structure
+
+- \`server/index.ts\`: schema, queries, mutations, and external endpoints.
 - \`client/index.tsx\`: Preact UI entrypoint.
 - \`shared/\`: pure TypeScript shared by client and server.
 
@@ -1523,35 +1771,27 @@ This is a Lakebed capsule. Build the app inside this directory using the Lakebed
 Run locally:
 
 \`\`\`sh
-lakebed dev
+npx lakebed dev
 \`\`\`
 
 Deploy:
 
 \`\`\`sh
-lakebed deploy
+npx lakebed deploy
 \`\`\`
 
-Inspect local state while \`lakebed dev\` is running:
+Inspect local state while \`npx lakebed dev\` is running:
 
 \`\`\`sh
-lakebed db list --port 3000
-lakebed db dump --port 3000
-lakebed logs --port 3000
+npx lakebed db list --port 3000
+npx lakebed db dump --port 3000
+npx lakebed logs --port 3000
 \`\`\`
 
-## Rules
+## Additional resources
 
-- Use \`lakebed/server\` only from \`server/index.ts\`.
-- Use \`lakebed/client\` only from \`client/index.tsx\`.
-- Do not import npm packages from app code.
-- Do not use Node built-ins in app code.
-- Use Tailwind classes directly in JSX.
-- Do not add a CSS, PostCSS, or Tailwind build pipeline.
-- Use auth through \`ctx.auth\` on the server and \`useAuth()\` on the client.
-- Read server-only environment variables through \`ctx.env\`; define them in \`.env.lakebed.server\`.
-- Add Google sign-in with \`<SignInWithGoogle />\` or \`signInWithGoogle()\` from \`lakebed/client\`.
-- Keep \`shared/\` free of DOM, Node, env, and Lakebed runtime imports.
+- [Lakebed docs](https://docs.lakebed.dev/)
+- [Capsule API docs](https://docs.lakebed.dev/capsule-api/)
 
 ## Current Limits
 
@@ -1561,7 +1801,8 @@ lakebed logs --port 3000
 - No file storage.
 - No outbound fetch in anonymous deploys. Claim the deploy before using server-side fetch.
 - Non-empty \`.env.lakebed.server\` files sync only after a deploy is claimed.
-- Local state resets when \`lakebed dev\` restarts.
+- Local state resets when \`npx lakebed dev\` restarts.
+- All production deploys are on 'lakebed.app'
 `;
 }
 
@@ -1609,11 +1850,35 @@ export default capsule({
     "client/index.tsx": `import { SignInWithGoogle, signOut, useAuth, useMutation, useQuery } from "lakebed/client";
 import { cleanTodoText, type Todo } from "../shared/todo";
 
+function AuthAvatar({ label, picture }: { label: string; picture?: string }) {
+  const initial = label.trim().slice(0, 1).toUpperCase() || "?";
+
+  if (picture) {
+    return (
+      <img
+        alt=""
+        className="h-7 w-7 shrink-0 rounded-full border border-neutral-800 bg-neutral-900 object-cover"
+        referrerPolicy="no-referrer"
+        src={picture}
+      />
+    );
+  }
+
+  return (
+    <span
+      aria-hidden="true"
+      className="flex h-7 w-7 shrink-0 items-center justify-center rounded-full border border-neutral-800 bg-neutral-900 text-xs font-medium text-neutral-300"
+    >
+      {initial}
+    </span>
+  );
+}
+
 export function App() {
   const auth = useAuth();
   const todos = useQuery<Todo[]>("todos");
   const addTodo = useMutation<[text: string], void>("addTodo");
-  const authLabel = auth.email ?? auth.displayName;
+  const authLabel = auth.displayName;
   const authStatus = auth.isLoading && auth.isGuest ? "checking session" : "signed in as " + authLabel;
 
   async function onSubmit(event: SubmitEvent) {
@@ -1633,11 +1898,14 @@ export function App() {
     <main className="min-h-screen bg-black px-6 py-10 text-white">
       <section className="mx-auto max-w-2xl">
         <div className="mb-3 flex items-center justify-between gap-3">
-          <p className="font-mono text-sm text-neutral-500">{authStatus}</p>
+          <div className="flex min-w-0 items-center gap-2">
+            {!auth.isLoading ? <AuthAvatar label={authLabel} picture={auth.picture} /> : null}
+            <p className="min-w-0 truncate font-mono text-sm text-neutral-500">{authStatus}</p>
+          </div>
           {!auth.isLoading && auth.isGuest ? (
-            <SignInWithGoogle className="border border-neutral-700 px-3 py-1.5 text-sm font-medium text-neutral-200 hover:border-white hover:text-white" />
+            <SignInWithGoogle className="shrink-0 border border-neutral-700 px-3 py-1.5 text-sm font-medium text-neutral-200 hover:border-white hover:text-white" />
           ) : !auth.isLoading ? (
-            <button className="text-sm text-neutral-400 hover:text-white" type="button" onClick={() => signOut()}>
+            <button className="shrink-0 text-sm text-neutral-400 hover:text-white" type="button" onClick={() => signOut()}>
               Sign out
             </button>
           ) : null}
@@ -1678,7 +1946,7 @@ export function cleanTodoText(value: string): string {
 Run this Lakebed capsule:
 
 \`\`\`sh
-pnpm lakebed dev ${name}
+npx lakebed dev
 \`\`\`
 `
   };

package/src/client.d.ts

@@ -9,7 +9,6 @@ export type Auth = {
   isLoading?: boolean;
   email?: string;
   emailVerified?: boolean;
-  name?: string;
   picture?: string;
 };
 

package/src/client.js

@@ -349,13 +349,13 @@ function createGoogleAuthFromToken(token) {
     return null;
   }
 
+  const displayName = typeof claims.name === "string" && claims.name.trim() ? claims.name.trim() : "Google User";
   return {
-    displayName: claims.name ?? claims.email ?? "Google User",
+    displayName,
     email: claims.email,
     emailVerified: claims.email_verified,
     isAuthenticated: true,
     isGuest: false,
-    name: claims.name,
     picture: claims.picture,
     provider: "google",
     userId: `google:${pairwiseSub}`

package/src/server.d.ts

@@ -17,7 +17,6 @@ export type AuthContext = {
   isAuthenticated: boolean;
   email?: string;
   emailVerified?: boolean;
-  name?: string;
   picture?: string;
 };
 
@@ -50,11 +49,60 @@ export type ServerContext = {
   log: LogContext;
 };
 
+export type EndpointRoute = {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | (string & {});
+  path: `/${string}`;
+};
+
+export type EndpointHeaders = {
+  get(name: string): string | null;
+  has(name: string): boolean;
+  entries(): IterableIterator<[string, string]>;
+};
+
+export type EndpointRequest = {
+  method: string;
+  path: string;
+  url: string;
+  headers: EndpointHeaders;
+  query: URLSearchParams;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+  bytes(): Promise<Uint8Array>;
+};
+
+export type EndpointResponse = {
+  kind: "response";
+  status: number;
+  headers?: Record<string, string>;
+  body?: string | Uint8Array | ArrayBuffer;
+};
+
+export type EndpointResponseOptions = {
+  status?: number;
+  headers?: Record<string, string>;
+};
+
+export type EndpointDefinition<TResult = EndpointResponse | string | unknown | void> = {
+  kind: "endpoint";
+  method: string;
+  path: string;
+  handler: (ctx: ServerContext, req: EndpointRequest) => TResult | Promise<TResult>;
+};
+
 export function capsule<T>(definition: T): T;
 export function query<T>(handler: (ctx: ServerContext) => T): (ctx: ServerContext) => T;
 export function mutation<TArgs extends unknown[], TResult>(
   handler: (ctx: ServerContext, ...args: TArgs) => TResult
 ): (ctx: ServerContext, ...args: TArgs) => TResult;
+export function endpoint<TResult>(
+  route: EndpointRoute,
+  handler: (ctx: ServerContext, req: EndpointRequest) => TResult | Promise<TResult>
+): EndpointDefinition<TResult>;
+export function json(value: unknown, options?: EndpointResponseOptions): EndpointResponse;
+export function text(value: unknown, options?: EndpointResponseOptions): EndpointResponse;
+export function empty(options?: EndpointResponseOptions): EndpointResponse;
+export function redirect(url: string, options?: EndpointResponseOptions): EndpointResponse;
 export function table(fields: Record<string, Field<unknown>>): TableDefinition;
 export function string(): Field<string>;
 export function boolean(): Field<boolean>;

package/src/server.js

@@ -10,6 +10,59 @@ export function mutation(handler) {
   return handler;
 }
 
+export function endpoint(route, handler) {
+  return {
+    handler,
+    kind: "endpoint",
+    method: String(route?.method ?? "").toUpperCase(),
+    path: String(route?.path ?? "")
+  };
+}
+
+function response(body, { headers = {}, status = 200 } = {}) {
+  return {
+    body,
+    headers,
+    kind: "response",
+    status
+  };
+}
+
+export function json(value, options = {}) {
+  return response(JSON.stringify(value ?? null), {
+    ...options,
+    headers: {
+      "Content-Type": "application/json; charset=utf-8",
+      ...(options.headers ?? {})
+    }
+  });
+}
+
+export function text(value, options = {}) {
+  return response(String(value ?? ""), {
+    ...options,
+    headers: {
+      "Content-Type": "text/plain; charset=utf-8",
+      ...(options.headers ?? {})
+    }
+  });
+}
+
+export function empty(options = {}) {
+  return response("", { status: 204, ...options });
+}
+
+export function redirect(url, options = {}) {
+  return response("", {
+    status: 302,
+    ...options,
+    headers: {
+      Location: String(url),
+      ...(options.headers ?? {})
+    }
+  });
+}
+
 function field(kind) {
   return {
     kind,