@usecarte/server

HTTP handler, server-action factory, and React hook for the Carte pipeline. Web-standard Request/Response only — same handler runs on Next App Router, Cloudflare Workers, Astro, Bun, Deno, and Node 18+.

Install

pnpm add @usecarte/server @usecarte/core

React is an optional peer (only needed for the useCarte client hook).

Handler route

// app/api/carte/route.ts (Next App Router — works the same on Astro, Workers, Bun, Deno)
import { createCarteHandler } from "@usecarte/server";
import { carte } from "@/lib/carte";
import { uiAdapter } from "@/lib/ui";

export const POST = createCarteHandler({
  carte,
  uiAdapter,
  context: ({ request }) => deriveContext(request),
  llm: async (systemPrompt, userMessage) => {
    // Call your LLM, return the JSON string it produced.
    return await callClaude({ system: systemPrompt, user: userMessage });
  },
});

For better-auth users, @usecarte/better-auth gives you a typed betterAuthContext({ auth, map }) factory instead of hand-rolling auth.api.getSession({ headers }).

Server Action (Next.js)

// app/actions.ts
"use server";
import { createCarteAction } from "@usecarte/server";

export const askCarte = createCarteAction({
  carte,
  uiAdapter,
  context: async () => deriveContextFromHeaders(),
  llm: async (system, user) => callClaude({ system, user }),
});

Client hook

// app/page.tsx — "use client"
import { useCarte } from "@usecarte/server/client";

const { submit, plan, results, isLoading, error } = useCarte({ endpoint: "/api/carte" });

Or with a Server Action:

const { submit, plan, results } = useCarte({ action: askCarte });

Repair loop, threat-model commitments

The default maxRetries: 1 repair loop feeds back only structured validationErrors and the model's own previous JSON. Executor errors, ZodErrors on returns, and driver messages bypass repair entirely — the LLM never sees row data, schema, or driver output. See the repo root README and the security model.

License

MIT