@beignet/next 0.0.3 → 0.0.5

package/README.md

@@ -1,15 +1,26 @@
 # @beignet/next
 
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
 Next.js adapter for the framework-agnostic `@beignet/core/server` runtime. It
 builds on `@beignet/web` for standard `Request`/`Response` handling and adds
 Next-specific helpers for App Router handlers, Server Component context,
 OpenAPI routes, Swagger UI, uploads, outbox drains, storage routes, and client
 base URLs.
 
+Use `@beignet/next` for Next.js applications. Use `@beignet/web` directly when
+the runtime already accepts standard Web Fetch `Request`/`Response` objects and
+does not need Next-specific route helpers. Both adapters share the same
+framework-neutral core boundary: core owns route matching, hooks, validation,
+errors, response ownership, and provider lifecycle; adapters own platform
+request/response conversion.
+
 ## Installation
 
 ```bash
-npm install @beignet/next next
+npm install @beignet/next @beignet/core next
 ```
 
 ### Optional add-ons
@@ -27,10 +38,10 @@ This package requires TypeScript 5.0 or higher for proper type inference.
 
 ```typescript
 // features/todos/contracts.ts
-import { createContractGroup } from "@beignet/core/contracts";
+import { defineContractGroup } from "@beignet/core/contracts";
 import { z } from "zod";
 
-const todos = createContractGroup()
+const todos = defineContractGroup()
   .namespace("todos")
   .prefix("/api/todos");
 
@@ -44,20 +55,30 @@ export const getTodo = todos
   }) });
 ```
 
-### 2. Create your server
+### 2. Define app context
+
+This adapter quick start uses a tiny demo context. Production Beignet apps
+should use the canonical `AppContext` from the docs and generated starter:
+`requestId`, `actor`, `auth`, `gate`, `ports`, and optional `tenant`.
 
 ```typescript
-// server/index.ts
-import {
-  createNextServer,
-  defineRouteGroup,
-  defineRoutes,
-} from "@beignet/next";
+// app-context.ts
+export type AppContext = {
+  userId: string;
+};
+```
+
+### 3. Wire feature routes
+
+```typescript
+// features/todos/routes.ts
+import { defineRouteGroup } from "@beignet/next";
+import type { AppContext } from "@/app-context";
 import { getTodo } from "@/features/todos/contracts";
 
-export const server = await createNextServer({
-  ports: {},
-  routes: defineRoutes([
+export const todoRoutes = defineRouteGroup<AppContext>({
+  name: "todos",
+  routes: [
     {
       contract: getTodo,
       handle: async ({ path }) => ({
@@ -69,57 +90,59 @@ export const server = await createNextServer({
         },
       }),
     },
-  ]),
-  createContext: async ({ req }) => {
+  ],
+});
+```
+
+For ordinary app routes, route entries live near the feature and bind a
+contract to a use case (`{ contract, useCase }`); the full
+`{ contract, handle }` form shown above is the escape hatch for demo stubs and
+routes that own headers, streaming, or multi-status responses. Compose those
+groups once in `server/routes.ts`:
+
+```typescript
+// server/routes.ts
+import { contractsFromRoutes, defineRoutes } from "@beignet/next";
+import type { AppContext } from "@/app-context";
+import { todoRoutes } from "@/features/todos/routes";
+
+export const routes = defineRoutes<AppContext>([todoRoutes]);
+export const contracts = contractsFromRoutes(routes);
+```
+
+### 4. Create your server
+
+```typescript
+// server/index.ts
+import { createNextServer } from "@beignet/next";
+import type { AppContext } from "@/app-context";
+import { routes } from "@/server/routes";
+
+export const server = await createNextServer<AppContext>({
+  ports: {},
+  routes,
+  context: async ({ req }) => {
     // DEMO ONLY: this reads an unauthenticated header to simulate identity.
     // Real applications should verify a signed token or session cookie first.
     return {
       userId: req.headers.get("x-user-id") || "anonymous",
     };
   },
-  mapUnhandledError: ({ err }) => ({
+  mapUnhandledError: () => ({
     status: 500,
     body: {
       code: "INTERNAL_SERVER_ERROR",
       message: "Internal server error",
-      ...(err instanceof Error ? { details: { message: err.message } } : {}),
     },
   }),
 });
 ```
 
-For larger apps, group related handlers near the feature and compose them with
-`defineRoutes`:
+### 5. Set up routes
 
-```typescript
-const todoRoutes = defineRouteGroup({
-  name: "todos",
-  routes: [
-    {
-      contract: getTodo,
-      handle: async ({ path }) => ({
-        status: 200,
-        body: {
-          id: path.id,
-          title: "Example todo",
-          completed: false,
-        },
-      }),
-    },
-  ],
-});
-
-export const routes = defineRoutes([todoRoutes]);
-```
-
-### 3. Set up routes
-
-You have two options for routing:
-
-#### Option A: catch-all framework route (recommended)
-
-Register handlers centrally in `server/index.ts`, then expose the central
-handler from one catch-all Next.js route file:
+Expose ordinary application routes through one catch-all framework route. Next
+App Router requires literal named exports for each HTTP method, so assign the
+central `server.api` handler to every verb your API should accept:
 
 ```typescript
 // app/api/[[...path]]/route.ts
@@ -134,24 +157,31 @@ export const POST = server.api;
 export const PUT = server.api;
 ```
 
-#### Option B: per-contract routes
+This catch-all file is Next.js adapter glue. It forwards requests to the
+Beignet server, but individual contracts should still use explicit paths with
+single-segment params such as `/posts/:id`, not catch-all contract patterns
+such as `/files/[...path]`.
 
-Create individual route files for each contract:
+#### Focused per-file routes
+
+Use per-file `server.route(contract).handle(...)` handlers for endpoints that
+intentionally sit outside the central route registry, such as webhooks,
+redirects, downloads, or adapter-specific glue:
 
 ```typescript
-// app/api/todos/[id]/route.ts
+// app/api/webhooks/stripe/route.ts
 import { server } from "@/server";
-import { getTodo } from "@/features/todos/contracts";
+import { stripeWebhook } from "@/features/billing/contracts";
 
-export const GET = server
-  .route(getTodo)
-  .handle(async ({ ctx, path }) => {
-    // Implement your handler logic
-    const todo = await fetchTodoById(path.id);
-    return {
-      status: 200,
-      body: todo,
-    };
+export const POST = server
+  .route(stripeWebhook)
+  .handle(async ({ req }) => {
+    const rawBody = await req.text();
+    const signature = req.headers.get("stripe-signature");
+
+    verifyWebhookSignature(rawBody, signature);
+
+    return { status: 200, body: { received: true } };
   });
 ```
 
@@ -208,7 +238,10 @@ Creates a Next.js server instance with the given options.
 **Parameters:**
 - `options`: Same as `createServer` from `@beignet/core/server`:
   - `ports`: **Required** - Ports object defining available service interfaces
-  - `createContext`: Async function to create request context
+  - `context`: **Required** - Context blueprint. Pass a plain request factory
+    for gate-less contexts, or `{ gate, request, service }` when the context
+    type declares a `gate`. The server attaches `ctx.gate` itself; `service`
+    powers `server.createServiceContext(...)`
   - `mapUnhandledError`: Error handler function
   - `routes?`: Array of route configurations (contract + handler)
   - `hooks?`: Optional ordered server hooks
@@ -238,45 +271,42 @@ export const POST = server.api;
 export const PUT = server.api;
 ```
 
+This route file is not a catch-all contract. Keep contract paths explicit and
+use the file only to expose the central server handler.
+
+Next App Router requires literal named exports for each HTTP method, so assign
+the same `server.api` handler to every verb your API should accept.
+
 #### `server.route(contract)`
 
-Returns a route builder for creating custom handlers for a specific contract. The contract is registered globally and available via `server.api`.
+Returns a route builder for focused per-file handlers such as webhooks,
+redirects, downloads, or other adapter-owned endpoints. Use
+`defineRouteGroup(...)` plus `defineRoutes(...)` for ordinary application
+routes; `server.route(contract).handle(...)` route files are not imported by
+the central `server.api` handler.
 
 **Returns:** Route builder with:
 - `handle(fn)`: Create a custom handler function
 
 ```typescript
-// app/api/todos/[id]/route.ts
+// app/api/reports/[id]/download/route.ts
 import { server } from "@/server";
-import { getTodo } from "@/features/todos/contracts";
-import { getTodoUseCase } from "@/features/todos/use-cases/get-todo";
-
-// Option 1: Custom handler
-export const GET = server
-  .route(getTodo)
-  .handle(async ({ req, ctx, path, query, body }) => {
-    // Your implementation
-    return { status: 200, body: { id: path.id, title: "..." } };
-  });
+import { downloadReport } from "@/features/reports/contracts";
 
-// Option 2: Call a use case inside the handler
 export const GET = server
-  .route(getTodo)
-  .handle(async ({ ctx, path }) => {
-    const todo = await getTodoUseCase.run({
-      ctx,
-      input: { id: path.id },
-    });
-
-    return { status: 200, body: todo };
-  });
+  .route(downloadReport)
+  .handle(async ({ ctx, path }) =>
+    new Response(await ctx.ports.reports.loadBytes(path.id), {
+      headers: { "Content-Type": "application/pdf" },
+    }),
+  );
 ```
 
 #### `server.createContextFromNext()`
 
 Creates a context object from Next.js Server Components by automatically extracting headers and cookies. This allows you to call use cases directly from React Server Components without going through API routes.
 
-**Returns:** `Promise<Ctx>` - Your context object from `createContext`
+**Returns:** `Promise<Ctx>` - Your fully assembled app context
 
 ```typescript
 // app/my-page/page.tsx
@@ -300,14 +330,40 @@ export default async function MyPage() {
 This method:
 - Automatically calls Next.js's `headers()` and `cookies()` functions
 - Creates a minimal Request-like object with headers and cookies access
-- Calls your `createContext` function with this request object
+- Delegates to `server.createRequestContext(req)` so the request context
+  factory and gate attachment run exactly like API route handlers
 - Returns the same context type you get in API route handlers
-- Uses the HTTP method `"GET"` for the internal Request-like object. If your `createContext` implementation inspects `req.method`, it will always see `"GET"` when invoked via `createContextFromNext()`.
+- Uses the HTTP method `"GET"` for the internal Request-like object. If your request context factory inspects `req.method`, it will always see `"GET"` when invoked via `createContextFromNext()`.
 - The `req.url` is set to a placeholder (`http://core/server-component.invalid`) since Server Components don't have real HTTP URLs
 - The `req.json()` and `req.text()` methods return empty values since there's no actual HTTP request body in Server Components
 
 **Note:** This method can only be called from Next.js Server Components (not in Client Components or during build time).
 
+#### `server.createRequestContext(req)`
+
+Builds a fully assembled request context from a framework-neutral
+`HttpRequestLike`. Use it for adapter entry points outside the route pipeline.
+
+#### `server.createServiceContext(input?)`
+
+Builds a service context through the `service` factory declared in the
+`context` blueprint. Use it for schedules, outbox drains, commands, and
+background work:
+
+```typescript
+// server/schedules.ts
+import { createServiceActor } from "@beignet/core/ports";
+import { server } from "./index";
+
+export async function createScheduleContext() {
+  return server.createServiceContext({
+    actor: createServiceActor("beignet-schedule"),
+  });
+}
+```
+
+Calling it without a declared `context.service` factory throws.
+
 #### `server.stop()`
 
 Stops the server and cleans up resources (closes provider connections, etc.).
@@ -323,7 +379,7 @@ When using `.handle()`, your handler function receives an object with:
 ```typescript
 {
   req: HttpRequestLike,   // Raw request object
-  ctx: Ctx,              // Your custom context from createContext
+  ctx: Ctx,              // Your custom context from the context blueprint
   path: PathParams,      // Validated path parameters
   query: QueryParams,    // Validated query parameters
   body: Body,            // Validated request body
@@ -370,7 +426,7 @@ const logging = createLoggingHooks({
 export const server = await createNextServer({
   ports: {},
   hooks: [logging],
-  createContext: async () => ({}),
+  context: async () => ({}),
   mapUnhandledError: () => ({
     status: 500,
     body: {
@@ -440,6 +496,7 @@ Router route:
 
 ```typescript
 // app/api/uploads/[uploadName]/[action]/route.ts
+import { resolveProviderInstrumentationPort } from "@beignet/core/providers";
 import { createUploadRouter } from "@beignet/core/uploads";
 import { createUploadRoute } from "@beignet/next";
 import { postUploads } from "@/features/posts/uploads";
@@ -449,7 +506,7 @@ const uploadRouter = createUploadRouter({
   uploads: postUploads,
   ctx: () => server.createContextFromNext(),
   storage: server.ports.storage,
-  instrumentation: server.ports.devtools,
+  instrumentation: resolveProviderInstrumentationPort(server.ports),
 });
 
 export const { POST } = createUploadRoute(uploadRouter);
@@ -461,8 +518,10 @@ The `action` segment must be `prepare`, `upload`, or `complete`.
 
 Use `createOutboxDrainRoute` to expose durable outbox delivery from a cron or
 scheduled serverless route. The helper requires a bearer secret, drains one
-bounded batch with `@beignet/core/outbox`, records a devtools event when
-available, and returns a JSON summary.
+bounded batch with `@beignet/core/outbox`, records a drain summary into the
+instrumentation port resolved from `ctx.ports` (`ports.instrumentation`, then
+`ports.devtools`), passes request correlation fields to outbox
+instrumentation, and returns a JSON summary.
 
 ```typescript
 // app/api/cron/outbox/drain/route.ts
@@ -491,23 +550,76 @@ Call the route from your scheduler with:
 Authorization: Bearer <CRON_SECRET>
 ```
 
+The bearer secret is checked with a timing-safe comparison, and a missing
+secret fails closed with a 500 response.
+
 Do not start long-running outbox polling loops from provider lifecycle hooks in
 serverless apps.
 
+## Schedule trigger routes
+
+Use `createScheduleRoute` to trigger one registered schedule from a cron or
+scheduled serverless route. The helper requires a bearer secret, creates app
+context with `server.createContextFromNext()`, runs the schedule with the
+inline runner from `@beignet/core/schedules`, and records `schedule` events
+through the instrumentation port resolved from `ctx.ports`
+(`ports.instrumentation`, then `ports.devtools`) with the request's
+correlation fields.
+
+```typescript
+// app/api/cron/digests/daily-digest/route.ts
+import { createScheduleRoute } from "@beignet/next";
+import { env } from "@/lib/env";
+import { server } from "@/server";
+import { schedules } from "@/server/schedules";
+
+export const runtime = "nodejs";
+
+export const { GET, POST } = createScheduleRoute({
+  server,
+  schedules,
+  schedule: "digests.send-daily",
+  secret: env.CRON_SECRET,
+  source: "vercel-cron",
+});
+```
+
+The schedule name is resolved when the route module loads, so unknown names
+throw at build or boot time instead of at the first cron invocation.
+
+Authentication matches `createOutboxDrainRoute`: the bearer secret is checked
+with a timing-safe comparison, and a missing secret fails closed with a 500
+response. Successful runs return `{ ok: true, scheduleName }`; failed runs log
+through `ctx.ports.logger` and return a 500 so schedule providers can retry.
+
+`source` defaults to `"next-cron-route"` and is recorded on run metadata and
+devtools events.
+
 ## Client creation
 
-Use `createNextClient` when a client may run in both browser and server environments. Browser calls default to same-origin relative URLs. Server calls use `NEXT_PUBLIC_API_URL`, then `VERCEL_URL`, then `http://localhost:${PORT || 3000}`.
+Use `createClient` from `@beignet/core/client` for modules under `client/` or
+Client Component import graphs. Browser calls default to same-origin relative
+URLs when no `baseUrl` is provided.
 
 ```typescript
-// client/api-client.ts
-import { createNextClient } from "@beignet/next";
+// client/index.ts
+import { createClient } from "@beignet/core/client";
 
-export const apiClient = createNextClient({
+export const apiClient = createClient({
   headers: async () => ({}),
+  validateInput: true,
 });
 ```
 
-If your local app runs on a non-default port, provide a server-only fallback:
+The client gets endpoint types from the contract passed to
+`apiClient.endpoint(contract)`. Next-friendly defaults supply same-origin
+browser URLs when no `baseUrl` is provided.
+
+If server-side code must call HTTP instead of a use case or route handler
+directly, pass an absolute `baseUrl` to `createClient(...)` or use
+`createNextClient` outside client-root modules. `createNextClient` resolves
+server calls through `NEXT_PUBLIC_API_URL`, then `VERCEL_URL`, then
+`http://localhost:${PORT || 3000}`.
 
 ```typescript
 export const apiClient = createNextClient({
@@ -517,6 +629,83 @@ export const apiClient = createNextClient({
 
 For deployed apps, prefer setting `NEXT_PUBLIC_API_URL` when API calls should target a different origin.
 
+## App Router data flow
+
+Beignet supports the normal App Router split:
+
+- Server Components can call use cases directly with `server.createContextFromNext()`.
+- Server Components can prefetch contract queries and hydrate Client Components with TanStack Query.
+- Client Components use `createClient()` plus React Query options for interactive server state.
+- Route handlers stay thin and expose `server.api` or focused helpers such as OpenAPI, uploads, storage, devtools, and outbox drains.
+
+### Server Component use-case calls
+
+Use this when the page only needs server-rendered data and does not need a
+browser cache for the result:
+
+```typescript
+// app/posts/[slug]/page.tsx
+import { server } from "@/server";
+import { getPostUseCase } from "@/features/posts/use-cases/get-post";
+
+type PageProps = {
+  params: Promise<{
+    slug: string;
+  }>;
+};
+
+export default async function Page({ params }: PageProps) {
+  const { slug } = await params;
+  const ctx = await server.createContextFromNext();
+  const post = await getPostUseCase.run({
+    ctx,
+    input: { slug },
+  });
+
+  return <article>{post.title}</article>;
+}
+```
+
+### Server prefetch plus hydration
+
+Use this when the first render should be server-prefetched, but a Client
+Component should keep using TanStack Query for refetching, mutations,
+invalidation, and optimistic updates:
+
+```typescript
+// app/posts/[slug]/page.tsx
+import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
+import { makeQueryClient, rq } from "@/client";
+import { getPost } from "@/features/posts/contracts";
+import { PostDetail } from "@/features/posts/components/post-detail";
+
+type PageProps = {
+  params: Promise<{
+    slug: string;
+  }>;
+};
+
+export default async function Page({ params }: PageProps) {
+  const { slug } = await params;
+  const queryClient = makeQueryClient();
+
+  await queryClient.prefetchQuery(
+    rq(getPost).queryOptions({
+      path: { slug },
+    }),
+  );
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <PostDetail slug={slug} />
+    </HydrationBoundary>
+  );
+}
+```
+
+`params` and `searchParams` are promises in modern App Router pages and route
+handlers. Await them before building contract path or query params.
+
 ## Providers
 
 Providers are service adapters that implement ports (database, cache, logger, etc.):
@@ -536,7 +725,7 @@ export const server = await createNextServer({
     loggerPinoProvider,
   ],
   providerEnv: process.env,
-  createContext: async ({ ports }) => ({
+  context: async ({ ports }) => ({
     // Access providers via ports
     db: ports.db,
     logger: ports.logger,
@@ -558,23 +747,24 @@ export const server = await createNextServer({
 ```typescript
 export const server = await createNextServer({
   ports: {},
-  createContext: async () => ({}),
-  mapUnhandledError: ({ err, ctx }) => {
+  context: async () => ({}),
+  mapUnhandledError: ({ err }) => {
     console.error("Unhandled error:", err);
     return {
       status: 500,
       body: {
         code: "INTERNAL_SERVER_ERROR",
         message: "Internal server error",
-        ...(process.env.NODE_ENV === "development" && err instanceof Error
-          ? { error: err.message }
-          : {}),
       },
     };
   },
 });
 ```
 
+`mapUnhandledError` response bodies are sent to clients. Use `onCaughtError`
+for diagnostics, logging, and error reporting; keep response `details` limited
+to stable public fields that your app intentionally exposes.
+
 ### Route-level error handling
 
 Declare expected business failures on the contract with `.errors(...)`, then
@@ -640,10 +830,10 @@ These are used internally by the adapter but can be used directly if needed.
 
 ```typescript
 // features/todos/contracts.ts
-import { createContractGroup } from "@beignet/core/contracts";
+import { defineContractGroup } from "@beignet/core/contracts";
 import { z } from "zod";
 
-const todos = createContractGroup()
+const todos = defineContractGroup()
   .namespace("todos")
   .prefix("/api/todos");
 
@@ -677,21 +867,53 @@ export const deleteTodo = todos
   .delete("/:id")
   .pathParams(z.object({ id: z.string() }))
   .responses({ 204: null });
+```
 
-// server/index.ts
-import { createNextServer, defineRoutes } from "@beignet/next";
+```typescript
+// app-context.ts
+export type AppContext = {
+  todos: Array<{ id: string; title: string; completed: boolean }>;
+};
+```
+
+```typescript
+// features/todos/routes.ts
+import { defineRouteGroup } from "@beignet/next";
+import type { AppContext } from "@/app-context";
 import * as todosContracts from "@/features/todos/contracts";
 
-export const server = await createNextServer({
-  ports: {},
-  routes: defineRoutes([
+export const todoRoutes = defineRouteGroup<AppContext>({
+  name: "todos",
+  routes: [
     { contract: todosContracts.listTodos, handle: async () => ({ status: 200, body: [] }) },
     { contract: todosContracts.getTodo, handle: async ({ path }) => ({ status: 200, body: { id: path.id, title: "...", completed: false } }) },
     { contract: todosContracts.createTodo, handle: async ({ body }) => ({ status: 201, body: { id: "1", ...body, completed: false } }) },
     { contract: todosContracts.updateTodo, handle: async ({ path, body }) => ({ status: 200, body: { id: path.id, ...body } }) },
     { contract: todosContracts.deleteTodo, handle: async () => ({ status: 204 }) },
-  ]),
-  createContext: async () => ({ todos: [] }),
+  ],
+});
+```
+
+```typescript
+// server/routes.ts
+import { contractsFromRoutes, defineRoutes } from "@beignet/next";
+import type { AppContext } from "@/app-context";
+import { todoRoutes } from "@/features/todos/routes";
+
+export const routes = defineRoutes<AppContext>([todoRoutes]);
+export const contracts = contractsFromRoutes(routes);
+```
+
+```typescript
+// server/index.ts
+import { createNextServer } from "@beignet/next";
+import type { AppContext } from "@/app-context";
+import { routes } from "@/server/routes";
+
+export const server = await createNextServer<AppContext>({
+  ports: {},
+  routes,
+  context: async () => ({ todos: [] }),
   mapUnhandledError: () => ({
     status: 500,
     body: {
@@ -725,7 +947,7 @@ import { getTodo } from "@/features/todos/contracts";
 
 export const server = await createNextServer({
   ports: {},
-  createContext: async ({ req }) => {
+  context: async ({ req }) => {
     const user = await getUserFromRequest(req);
 
     if (!user) {
@@ -786,10 +1008,10 @@ This approach:
 
 ## Related packages
 
-- [@beignet/core/server](https://beignet.dev/server) - Framework-agnostic server runtime
-- [@beignet/core/contracts](https://beignet.dev/contracts) - Contract definitions
-- [@beignet/core/openapi](https://beignet.dev/openapi) - OpenAPI spec generation
-- [@beignet/core/client](https://beignet.dev/client) - Type-safe HTTP client
+- [@beignet/core/server](https://beignetjs.com/server) - Framework-agnostic server runtime
+- [@beignet/core/contracts](https://beignetjs.com/contracts) - Contract definitions
+- [@beignet/core/openapi](https://beignetjs.com/openapi) - OpenAPI spec generation
+- [@beignet/core/client](https://beignetjs.com/client) - Type-safe HTTP client
 
 ## License