@beignet/next 0.0.26 → 0.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/next",
-  "version": "0.0.26",
+  "version": "0.0.27",
   "type": "module",
   "description": "Next.js server-side handlers for Beignet",
   "main": "./dist/index.js",
@@ -59,7 +59,7 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0"
   },
   "dependencies": {
-    "@beignet/web": "^0.0.26",
+    "@beignet/web": "^0.0.27",
     "@standard-schema/spec": "^1.0.0"
   },
   "devDependencies": {

package/skills/routes-server/SKILL.md

@@ -64,6 +64,7 @@ registry. If a route is missing from OpenAPI or clients, check this file first.
 `server/index.ts` owns runtime composition:
 
 - `createNextServer(...)`
+- `createNextServerLoader(...)`
 - app ports
 - providers
 - hooks
@@ -79,19 +80,17 @@ feature route files.
 Application API routes usually use one catch-all file:
 
 ```ts
-import { server } from "@/server";
-
-export const DELETE = server.api;
-export const GET = server.api;
-export const HEAD = server.api;
-export const OPTIONS = server.api;
-export const PATCH = server.api;
-export const POST = server.api;
-export const PUT = server.api;
+import { createApiRoute } from "@beignet/next";
+import { getServer } from "@/server";
+
+export const { DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT } =
+  createApiRoute(getServer);
 ```
 
 The catch-all file is adapter glue. Contracts should still use explicit paths
-such as `/projects/:id`, not catch-all contract patterns.
+such as `/projects/:id`, not catch-all contract patterns. Keep provider
+startup behind `getServer` so Next production builds can import route modules
+without booting the app runtime.
 
 ## Focused Routes
 

package/src/index.ts

@@ -19,16 +19,18 @@ import {
   type StandardSchema,
 } from "@beignet/core/schedules";
 import type {
+  AppEnvironment,
   ContractLike,
   CreateServerOptions,
   Handler,
+  HealthConfig,
   HttpRequestLike,
   ResolveContract,
   RouteDef,
   ServerInstance,
   StandardSchemaV1,
 } from "@beignet/core/server";
-import { createServer } from "@beignet/core/server";
+import { createHealthHandler, createServer } from "@beignet/core/server";
 import type { UploadRouter } from "@beignet/core/uploads";
 import {
   type InferWebhookEvent,
@@ -38,7 +40,7 @@ import {
   type WebhookEvent,
   type WebhookEventSchemas,
 } from "@beignet/core/webhooks";
-import { createFetchHandler, toWebResponse } from "@beignet/web";
+import { createFetchHandler, toRequestLike, toWebResponse } from "@beignet/web";
 
 /**
  * Server types re-exported for Next.js apps.
@@ -81,6 +83,22 @@ type AnyProvider = ServiceProvider<
   any
 >;
 
+type MaybePromise<T> = T | Promise<T>;
+
+type ServerSource<TServer> = TServer | (() => MaybePromise<TServer>);
+
+function isServerLoader<TServer>(
+  source: ServerSource<TServer>,
+): source is () => MaybePromise<TServer> {
+  return typeof source === "function";
+}
+
+async function resolveServerSource<TServer>(
+  source: ServerSource<TServer>,
+): Promise<TServer> {
+  return isServerLoader(source) ? source() : source;
+}
+
 /**
  * Beignet client config with Next.js base URL defaults.
  */
@@ -267,14 +285,30 @@ type OutboxDrainContext = {
   ports: OutboxDrainPorts;
 };
 
+/**
+ * Minimal server surface required by the Next.js route factories.
+ *
+ * Both a `NextServer` and a core `ServerInstance` satisfy this shape
+ * structurally, so route modules built on these factories are executable
+ * under `bun test`: construct the route with a fake server exposing
+ * `createRequestContext` and invoke the exported handlers with a plain
+ * `Request`. No Next.js runtime (`next/headers`) is involved.
+ */
+export type NextRouteServer<Ctx> = {
+  createRequestContext: (req: HttpRequestLike) => Promise<Ctx>;
+};
+
 /**
  * Options for creating a serverless-safe outbox drain route.
  */
 export type CreateOutboxDrainRouteOptions<Ctx extends OutboxDrainContext> = {
   /**
-   * Beignet Next server that owns app context and ports.
+   * Beignet server that owns app context and ports.
+   *
+   * Any object exposing `createRequestContext` works: a `NextServer`, a core
+   * `ServerInstance`, or a test fake driven from `bun test`.
    */
-  server: Pick<NextServer<Ctx, Ctx["ports"]>, "createContextFromNext">;
+  server: ServerSource<NextRouteServer<Ctx>>;
   /**
    * Registry of events and jobs that may be delivered from the outbox.
    */
@@ -405,9 +439,12 @@ export type CreateWebhookRouteOptions<
   AllowUnknownEvents extends boolean = true,
 > = {
   /**
-   * Beignet Next server that owns app context and ports.
+   * Beignet server that owns app context and ports.
+   *
+   * Any object exposing `createRequestContext` works: a `NextServer`, a core
+   * `ServerInstance`, or a test fake driven from `bun test`.
    */
-  server: Pick<NextServer<Ctx, Ctx["ports"]>, "createContextFromNext">;
+  server: ServerSource<NextRouteServer<Ctx>>;
   /**
    * Inbound webhook definition.
    */
@@ -444,9 +481,12 @@ export type CreateWebhookRouteOptions<
  */
 export type CreateScheduleRouteOptions<Ctx extends ScheduleRouteContext> = {
   /**
-   * Beignet Next server that owns app context and ports.
+   * Beignet server that owns app context and ports.
+   *
+   * Any object exposing `createRequestContext` works: a `NextServer`, a core
+   * `ServerInstance`, or a test fake driven from `bun test`.
    */
-  server: Pick<NextServer<Ctx, Ctx["ports"]>, "createContextFromNext">;
+  server: ServerSource<NextRouteServer<Ctx>>;
   /**
    * Registered schedules, usually the `schedules` array from
    * `server/schedules.ts`.
@@ -483,9 +523,12 @@ export type CreatePaymentWebhookRouteOptions<
   Ctx extends PaymentWebhookRouteContext,
 > = {
   /**
-   * Beignet Next server that owns app context and ports.
+   * Beignet server that owns app context and ports.
+   *
+   * Any object exposing `createRequestContext` works: a `NextServer`, a core
+   * `ServerInstance`, or a test fake driven from `bun test`.
    */
-  server: Pick<NextServer<Ctx, Ctx["ports"]>, "createContextFromNext">;
+  server: ServerSource<NextRouteServer<Ctx>>;
   /**
    * Provider signature header. Stripe uses `stripe-signature`.
    *
@@ -559,6 +602,18 @@ export interface NextServer<
     Ports,
     ServiceInput
   >["createServiceContext"];
+  /**
+   * Build a service context and run `fn` inside a scoped ambient correlation
+   * frame, returning its result.
+   *
+   * This is the script-safe counterpart to `createServiceContext(...)`.
+   * Requires `context.service` to be declared in `createNextServer(...)`.
+   */
+  runServiceContext: ServerInstance<
+    Ctx,
+    Ports,
+    ServiceInput
+  >["runServiceContext"];
   /**
    * Registered contract inputs.
    */
@@ -573,6 +628,108 @@ export interface NextServer<
   ports: Ports;
 }
 
+/**
+ * Lazy, memoized loader for a Beignet Next server.
+ */
+export type NextServerLoader<TServer> = () => Promise<TServer>;
+
+/**
+ * HTTP method handlers for a central Beignet API catch-all route.
+ */
+export type NextApiRouteHandlers = {
+  DELETE: (req: Request) => Promise<Response>;
+  GET: (req: Request) => Promise<Response>;
+  HEAD: (req: Request) => Promise<Response>;
+  OPTIONS: (req: Request) => Promise<Response>;
+  PATCH: (req: Request) => Promise<Response>;
+  POST: (req: Request) => Promise<Response>;
+  PUT: (req: Request) => Promise<Response>;
+};
+
+/**
+ * Create a memoized Next server loader for route modules.
+ *
+ * Next.js imports route modules during production builds. Exporting a lazy
+ * loader lets those modules stay cheap to import while still booting providers
+ * before the first real request in each runtime process.
+ */
+export function createNextServerLoader<TServer>(
+  createServer: () => MaybePromise<TServer>,
+): NextServerLoader<TServer> {
+  let server: Promise<TServer> | undefined;
+
+  return () => {
+    if (!server) {
+      const nextServer = Promise.resolve().then(createServer);
+      server = nextServer;
+      void nextServer.catch(() => {
+        if (server === nextServer) {
+          server = undefined;
+        }
+      });
+    }
+
+    return server;
+  };
+}
+
+/**
+ * Create HTTP method exports for a catch-all API route.
+ */
+export function createApiRoute<
+  TServer extends Pick<NextServer<unknown, AnyPorts, unknown>, "api">,
+>(loadServer: NextServerLoader<TServer>): NextApiRouteHandlers {
+  const handle = async (req: Request) => {
+    const server = await loadServer();
+    return server.api(req);
+  };
+
+  return {
+    DELETE: handle,
+    GET: handle,
+    HEAD: handle,
+    OPTIONS: handle,
+    PATCH: handle,
+    POST: handle,
+    PUT: handle,
+  };
+}
+
+/**
+ * Create a readiness route whose server is loaded only when the route handles
+ * a request.
+ */
+export function createHealthRoute<Ports extends AnyPorts>(
+  loadServer: NextServerLoader<
+    Pick<NextServer<unknown, Ports, unknown>, "ports">
+  >,
+  healthConfig: HealthConfig<Ports> | undefined,
+  environment: AppEnvironment = "production",
+): {
+  GET: (req: Request) => Promise<Response>;
+} {
+  return {
+    GET: async (req) => {
+      const server = await loadServer();
+      const handler = createHealthHandler(
+        server.ports,
+        healthConfig,
+        environment,
+      );
+      const response = await handler(req);
+      const headers = new Headers(response.headers);
+      if (!headers.has("cache-control")) {
+        headers.set("cache-control", "no-store");
+      }
+
+      return Response.json(response.body, {
+        status: response.status,
+        headers,
+      });
+    },
+  };
+}
+
 /**
  * Convert a Beignet response into a native `Response`.
  *
@@ -936,7 +1093,7 @@ export function createSwaggerUIHandler(
  * all return 404 so storage routes do not leak object existence.
  */
 export function createStorageRoute(
-  storage: StoragePort,
+  storage: ServerSource<StoragePort>,
   options: CreateStorageRouteOptions = {},
 ): {
   GET: (req: Request) => Promise<Response>;
@@ -945,8 +1102,22 @@ export function createStorageRoute(
   const basePath = normalizeStorageBasePath(options.basePath);
 
   return {
-    GET: (req) => storageResponse(storage, req, basePath, options, true),
-    HEAD: (req) => storageResponse(storage, req, basePath, options, false),
+    GET: async (req) =>
+      storageResponse(
+        await resolveServerSource(storage),
+        req,
+        basePath,
+        options,
+        true,
+      ),
+    HEAD: async (req) =>
+      storageResponse(
+        await resolveServerSource(storage),
+        req,
+        basePath,
+        options,
+        false,
+      ),
   };
 }
 
@@ -958,7 +1129,7 @@ export function createStorageRoute(
  * `prepare`, `complete`, or `upload`.
  */
 export function createUploadRoute(
-  router: UploadRouter,
+  router: ServerSource<UploadRouter>,
   options: CreateUploadRouteOptions = {},
 ): {
   POST: (req: Request, ctx?: UploadRouteContext) => Promise<Response>;
@@ -999,7 +1170,9 @@ export function createUploadRoute(
         );
       }
 
-      return router.handleRequest(req, {
+      const resolvedRouter = await resolveServerSource(router);
+
+      return resolvedRouter.handleRequest(req, {
         uploadName,
         action,
       });
@@ -1052,6 +1225,24 @@ function toHttpResponseHeaders(
   return result;
 }
 
+/**
+ * Rebuild a request whose body was already consumed.
+ *
+ * Webhook routes read the raw body before anything else so signature
+ * verification never races the context factory over one body stream. Context
+ * creation then receives a rehydrated request carrying the same method, URL,
+ * headers, and raw body.
+ */
+function toContextRequest(req: Request, rawBody: string): HttpRequestLike {
+  return toRequestLike(
+    new Request(req.url, {
+      method: req.method,
+      headers: req.headers,
+      body: rawBody,
+    }),
+  );
+}
+
 function headersToRecord(headers: Headers): Record<string, string> {
   const result: Record<string, string> = {};
   headers.forEach((value, key) => {
@@ -1128,7 +1319,8 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
     let ctx: Ctx | undefined;
 
     try {
-      ctx = await options.server.createContextFromNext();
+      const server = await resolveServerSource(options.server);
+      ctx = await server.createRequestContext(toRequestLike(req));
       const drainCtx = ctx;
       const result = await drainOutbox({
         outbox: drainCtx.ports.outbox,
@@ -1206,9 +1398,10 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
  * Create a Next.js POST handler for generic verified inbound webhooks.
  *
  * The route reads the raw request body as text, normalizes request headers,
- * verifies the event through the webhook definition or a context-aware
- * verifier, validates the matching event payload schema, and delegates
- * fulfillment to app code.
+ * builds app context from the real request through
+ * `server.createRequestContext(...)`, verifies the event through the webhook
+ * definition or a context-aware verifier, validates the matching event
+ * payload schema, and delegates fulfillment to app code.
  */
 export function createWebhookRoute<
   Ctx extends WebhookRouteContext,
@@ -1224,10 +1417,26 @@ export function createWebhookRoute<
       const headers = resolveHeaders(options.headers, req);
       const requestHeaders = headersToRecord(req.headers);
 
+      let rawBody: string;
+
+      try {
+        rawBody = await req.text();
+      } catch {
+        return webhookRouteJson(
+          {
+            ok: false,
+            error: "Webhook body read failed.",
+          },
+          400,
+          headers,
+        );
+      }
+
       let ctx: Ctx;
 
       try {
-        ctx = await options.server.createContextFromNext();
+        const server = await resolveServerSource(options.server);
+        ctx = await server.createRequestContext(toContextRequest(req, rawBody));
       } catch {
         return webhookRouteJson(
           {
@@ -1239,7 +1448,6 @@ export function createWebhookRoute<
         );
       }
 
-      let rawBody: string;
       let event: WebhookRouteHandlerArgs<
         Ctx,
         Webhook,
@@ -1247,7 +1455,6 @@ export function createWebhookRoute<
       >["event"];
 
       try {
-        rawBody = await req.text();
         const input: VerifyWebhookInput = {
           rawBody,
           headers: requestHeaders,
@@ -1350,9 +1557,10 @@ export function createWebhookRoute<
 /**
  * Create a Next.js POST handler for provider-verified payment webhooks.
  *
- * The route reads the raw request body as text, extracts the provider
- * signature header, verifies the event through `ctx.ports.payments`, and then
- * delegates fulfillment to app code. This is the canonical helper for Beignet
+ * The route extracts the provider signature header, reads the raw request
+ * body as text, builds app context from the real request through
+ * `server.createRequestContext(...)`, verifies the event through
+ * `ctx.ports.payments`, and then delegates fulfillment to app code. This is the canonical helper for Beignet
  * billing flows backed by `PaymentsPort`. Keep this route on the Node.js
  * runtime when your provider SDK requires Node APIs.
  */
@@ -1381,10 +1589,26 @@ export function createPaymentWebhookRoute<
         );
       }
 
+      let rawBody: string;
+
+      try {
+        rawBody = await req.text();
+      } catch {
+        return paymentWebhookJson(
+          {
+            ok: false,
+            error: "Payment webhook body read failed.",
+          },
+          400,
+          headers,
+        );
+      }
+
       let ctx: Ctx;
 
       try {
-        ctx = await options.server.createContextFromNext();
+        const server = await resolveServerSource(options.server);
+        ctx = await server.createRequestContext(toContextRequest(req, rawBody));
       } catch {
         return paymentWebhookJson(
           {
@@ -1396,11 +1620,9 @@ export function createPaymentWebhookRoute<
         );
       }
 
-      let rawBody: string;
       let event: PaymentWebhookEvent;
 
       try {
-        rawBody = await req.text();
         event = await ctx.ports.payments.verifyWebhook({
           rawBody,
           signature,
@@ -1476,8 +1698,9 @@ export function createPaymentWebhookRoute<
  * Create Next.js route handlers that trigger one registered schedule.
  *
  * This helper is intended for serverless cron routes. It authenticates the
- * caller with a timing-safe bearer comparison, creates app context, runs the
- * schedule inline, and records `schedule` events through the resolved
+ * caller with a timing-safe bearer comparison, builds app context from the
+ * real request through `server.createRequestContext(...)`, runs the schedule
+ * inline, and records `schedule` events through the resolved
  * provider instrumentation port (`ports.instrumentation`, then
  * `ports.devtools`) when one is installed.
  */
@@ -1524,7 +1747,8 @@ export function createScheduleRoute<Ctx extends ScheduleRouteContext>(
     }
 
     try {
-      const ctx = await options.server.createContextFromNext();
+      const server = await resolveServerSource(options.server);
+      const ctx = await server.createRequestContext(toRequestLike(req));
       const runner = createInlineScheduleRunner<Ctx>({
         ctx,
         instrumentation: resolveProviderInstrumentationPort(ctx.ports),
@@ -1641,6 +1865,7 @@ export async function createNextServer<
     },
     createRequestContext: runtime.createRequestContext,
     createServiceContext: runtime.createServiceContext,
+    runServiceContext: runtime.runServiceContext,
     contracts: runtime.contracts,
     stop: () => runtime.stop(),
     ports: runtime.ports,