@beignet/next 0.0.26 → 0.0.28

package/src/index.ts

@@ -19,16 +19,20 @@ import {
   type StandardSchema,
 } from "@beignet/core/schedules";
 import type {
+  AppEnvironment,
   ContractLike,
   CreateServerOptions,
   Handler,
+  HealthConfig,
+  HttpContractConfig,
   HttpRequestLike,
+  RawRouteInit,
   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 +42,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.
@@ -47,6 +51,7 @@ export type {
   AnyUseCaseLike,
   CreateServerOptions,
   HandlerRouteDef,
+  RawRouteInit,
   RouteDef,
   RouteGroup,
   RouteHook,
@@ -81,6 +86,96 @@ 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;
+}
+
+/**
+ * Unified view over `rawRoute` as exposed by a core `ServerInstance`
+ * (framework-neutral request/response) and a `NextServer` (fetch-native).
+ * Both accept a native `Request` structurally and both produce something
+ * `toWebResponse(...)` normalizes, so route factories can run their handler
+ * through either pipeline without knowing which flavor they were given.
+ */
+type RawRoutePipeline<Ctx> = (init: RawRouteInit) => {
+  handle: (
+    fn: (args: {
+      req: HttpRequestLike;
+      ctx: Ctx;
+    }) => MaybePromise<Response | { status: number }>,
+  ) => (req: HttpRequestLike) => Promise<Response | object>;
+};
+
+function rawRoutePipeline<Ctx>(
+  server: NextRouteServer<Ctx>,
+): RawRoutePipeline<Ctx> | undefined {
+  const candidate = (server as { rawRoute?: unknown }).rawRoute;
+  return typeof candidate === "function"
+    ? (candidate.bind(server) as RawRoutePipeline<Ctx>)
+    : undefined;
+}
+
+/**
+ * Per-route-factory memo for the pipeline-built handler. The handler is
+ * rebuilt only when the resolved server instance changes (fresh server per
+ * test, hot reload), never per request.
+ */
+function createRawPipelineRunner<Ctx>(
+  init: RawRouteInit,
+  fn: (args: { req: HttpRequestLike; ctx: Ctx }) => Promise<Response>,
+): (
+  server: NextRouteServer<Ctx>,
+) => ((req: Request) => Promise<Response>) | undefined {
+  let cached:
+    | {
+        server: NextRouteServer<Ctx>;
+        handler: (req: Request) => Promise<Response>;
+      }
+    | undefined;
+
+  return (server) => {
+    const pipeline = rawRoutePipeline(server);
+    if (!pipeline) return undefined;
+
+    if (!cached || cached.server !== server) {
+      const built = pipeline(init).handle(fn);
+      cached = {
+        server,
+        handler: async (req) =>
+          toWebResponse(
+            (await built(req as unknown as HttpRequestLike)) as Parameters<
+              typeof toWebResponse
+            >[0],
+          ),
+      };
+    }
+
+    return cached.handler;
+  };
+}
+
+/**
+ * Resolve the native `Request` behind a pipeline request. Requests routed
+ * through `createFetchHandler` carry it as `raw`; requests passed straight
+ * into a core handler are the native request itself.
+ */
+function nativeRequestOf(req: HttpRequestLike): Request {
+  const raw = (req as { raw?: unknown }).raw;
+  return (raw instanceof Request ? raw : req) as Request;
+}
+
 /**
  * Beignet client config with Next.js base URL defaults.
  */
@@ -267,14 +362,35 @@ 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.
+ *
+ * When the server also exposes `rawRoute(...)` — real Beignet servers do —
+ * the factories run their handler through the full hooks pipeline (rate
+ * limiting, CORS, logging, error reporting, instrumentation). Minimal fakes
+ * without it keep the direct `createRequestContext` flow.
+ */
+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.
    */
@@ -298,6 +414,17 @@ export type CreateOutboxDrainRouteOptions<Ctx extends OutboxDrainContext> = {
    * Retry delay override passed through to `drainOutbox(...)`.
    */
   retryDelayMs?: DrainOutboxOptions["retryDelayMs"];
+  /**
+   * Identity and metadata for the hooks pipeline when the server exposes
+   * `rawRoute(...)`. `metadata` feeds metadata-driven hooks such as rate
+   * limiting and idempotency; `name` and `path` identify the route to
+   * hooks, instrumentation, and devtools.
+   */
+  pipeline?: {
+    name?: string;
+    path?: string;
+    metadata?: RawRouteInit["metadata"];
+  };
   /**
    * Additional response headers.
    */
@@ -405,9 +532,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.
    */
@@ -433,6 +563,17 @@ export type CreateWebhookRouteOptions<
   handle?: (
     args: WebhookRouteHandlerArgs<Ctx, Webhook, AllowUnknownEvents>,
   ) => Promise<WebhookRouteHandlerResult> | WebhookRouteHandlerResult;
+  /**
+   * Identity and metadata for the hooks pipeline when the server exposes
+   * `rawRoute(...)`. `metadata` feeds metadata-driven hooks such as rate
+   * limiting and idempotency; `name` and `path` identify the route to
+   * hooks, instrumentation, and devtools.
+   */
+  pipeline?: {
+    name?: string;
+    path?: string;
+    metadata?: RawRouteInit["metadata"];
+  };
   /**
    * Additional response headers.
    */
@@ -444,9 +585,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`.
@@ -470,6 +614,17 @@ export type CreateScheduleRouteOptions<Ctx extends ScheduleRouteContext> = {
    * @default "next-cron-route"
    */
   source?: string;
+  /**
+   * Identity and metadata for the hooks pipeline when the server exposes
+   * `rawRoute(...)`. `metadata` feeds metadata-driven hooks such as rate
+   * limiting and idempotency; `name` and `path` identify the route to
+   * hooks, instrumentation, and devtools.
+   */
+  pipeline?: {
+    name?: string;
+    path?: string;
+    metadata?: RawRouteInit["metadata"];
+  };
   /**
    * Additional response headers.
    */
@@ -483,9 +638,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`.
    *
@@ -502,6 +660,17 @@ export type CreatePaymentWebhookRouteOptions<
   ) =>
     | Promise<PaymentWebhookRouteHandlerResult>
     | PaymentWebhookRouteHandlerResult;
+  /**
+   * Identity and metadata for the hooks pipeline when the server exposes
+   * `rawRoute(...)`. `metadata` feeds metadata-driven hooks such as rate
+   * limiting and idempotency; `name` and `path` identify the route to
+   * hooks, instrumentation, and devtools.
+   */
+  pipeline?: {
+    name?: string;
+    path?: string;
+    metadata?: RawRouteInit["metadata"];
+  };
   /**
    * Additional response headers.
    */
@@ -536,6 +705,24 @@ export interface NextServer<
       fn: Handler<Ctx, ResolveContract<CLike>>,
     ) => (req: Request) => Promise<Response>;
   };
+  /**
+   * Build a Next.js route handler for a route that cannot be a contract —
+   * webhooks, third-party auth callbacks, streaming endpoints — that still
+   * runs the whole server pipeline: hooks (rate limiting, idempotency, CORS,
+   * logging, error reporting), context creation, instrumentation, and
+   * framework error mapping.
+   *
+   * Request parsing and validation are skipped and the request body is left
+   * unconsumed, so the handler owns body reading — for example webhook
+   * signature verification over the exact raw bytes. Metadata-driven hooks
+   * read `init.metadata`. Raw routes are not added to the route registry;
+   * export the returned handler from the route file that owns the path.
+   */
+  rawRoute: (init: RawRouteInit) => {
+    handle: (
+      fn: Handler<Ctx, HttpContractConfig>,
+    ) => (req: Request) => Promise<Response>;
+  };
   /**
    * Create app context from `next/headers` for Server Components.
    */
@@ -559,6 +746,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 +772,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 +1237,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 +1246,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 +1273,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 +1314,9 @@ export function createUploadRoute(
         );
       }
 
-      return router.handleRequest(req, {
+      const resolvedRouter = await resolveServerSource(router);
+
+      return resolvedRouter.handleRequest(req, {
         uploadName,
         action,
       });
@@ -1052,6 +1369,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) => {
@@ -1106,8 +1441,15 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
   GET: (req: Request) => Promise<Response>;
   POST: (req: Request) => Promise<Response>;
 } {
-  const drainPendingOutbox = async (req: Request): Promise<Response> => {
-    const headers = resolveHeaders(options.headers, req);
+  const drainWithContext = async ({
+    req,
+    ctx,
+  }: {
+    req: HttpRequestLike;
+    ctx: Ctx;
+  }): Promise<Response> => {
+    const nativeReq = nativeRequestOf(req);
+    const headers = resolveHeaders(options.headers, nativeReq);
     const secret = options.secret;
 
     if (!secret) {
@@ -1121,14 +1463,11 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
       );
     }
 
-    if (!(await isAuthorizedCronRequest(req, secret))) {
+    if (!(await isAuthorizedCronRequest(nativeReq, secret))) {
       return cronRouteJson({ ok: false, error: "Unauthorized" }, 401, headers);
     }
 
-    let ctx: Ctx | undefined;
-
     try {
-      ctx = await options.server.createContextFromNext();
       const drainCtx = ctx;
       const result = await drainOutbox({
         outbox: drainCtx.ports.outbox,
@@ -1183,7 +1522,7 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
         headers,
       );
     } catch (error) {
-      ctx?.ports.logger?.error("Outbox drain failed", { error });
+      ctx.ports.logger?.error("Outbox drain failed", { error });
 
       return cronRouteJson(
         {
@@ -1196,6 +1535,69 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
     }
   };
 
+  const pipelineInit = {
+    name: options.pipeline?.name ?? "outbox.drain",
+    path: options.pipeline?.path ?? "/outbox/drain",
+    metadata: options.pipeline?.metadata,
+  };
+  const pipelineRunners = {
+    GET: createRawPipelineRunner<Ctx>(
+      { ...pipelineInit, method: "GET" },
+      drainWithContext,
+    ),
+    POST: createRawPipelineRunner<Ctx>(
+      { ...pipelineInit, method: "POST" },
+      drainWithContext,
+    ),
+  };
+
+  const drainPendingOutbox = async (req: Request): Promise<Response> => {
+    const server = await resolveServerSource(options.server);
+
+    const runner =
+      pipelineRunners[req.method.toUpperCase() === "GET" ? "GET" : "POST"];
+    const pipelined = runner(server);
+    if (pipelined) return pipelined(req);
+
+    // Minimal servers without rawRoute(...) — usually test fakes — keep the
+    // original flow: authorize before touching context, then drain inline.
+    const headers = resolveHeaders(options.headers, req);
+    const secret = options.secret;
+
+    if (!secret) {
+      return cronRouteJson(
+        {
+          ok: false,
+          error: "CRON_SECRET is not configured.",
+        },
+        500,
+        headers,
+      );
+    }
+
+    if (!(await isAuthorizedCronRequest(req, secret))) {
+      return cronRouteJson({ ok: false, error: "Unauthorized" }, 401, headers);
+    }
+
+    let ctx: Ctx;
+    try {
+      ctx = await server.createRequestContext(toRequestLike(req));
+    } catch (error) {
+      console.error("Outbox drain context failed", { error });
+
+      return cronRouteJson(
+        {
+          ok: false,
+          error: "Outbox drain failed.",
+        },
+        500,
+        headers,
+      );
+    }
+
+    return drainWithContext({ req: toRequestLike(req), ctx });
+  };
+
   return {
     GET: drainPendingOutbox,
     POST: drainPendingOutbox,
@@ -1206,9 +1608,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,
@@ -1219,130 +1622,184 @@ export function createWebhookRoute<
 ): {
   POST: (req: Request) => Promise<Response>;
 } {
+  const handleWebhookRequest = async ({
+    req,
+    ctx,
+  }: {
+    req: HttpRequestLike;
+    ctx: Ctx;
+  }): Promise<Response> => {
+    const nativeReq = nativeRequestOf(req);
+    const headers = resolveHeaders(options.headers, nativeReq);
+    const requestHeaders = headersToRecord(new Headers(req.headers));
+
+    let rawBody: string;
+
+    try {
+      rawBody = await req.text();
+    } catch {
+      return webhookRouteJson(
+        {
+          ok: false,
+          error: "Webhook body read failed.",
+        },
+        400,
+        headers,
+      );
+    }
+
+    let event: WebhookRouteHandlerArgs<
+      Ctx,
+      Webhook,
+      AllowUnknownEvents
+    >["event"];
+
+    try {
+      const input: VerifyWebhookInput = {
+        rawBody,
+        headers: requestHeaders,
+        receivedAt: new Date(),
+      };
+      const routeVerifier = options.verify;
+      const verifier = routeVerifier
+        ? {
+            async verify() {
+              return routeVerifier({
+                req: nativeReq,
+                ctx,
+                rawBody,
+                headers: requestHeaders,
+                input,
+              });
+            },
+          }
+        : undefined;
+
+      event = (await verifyWebhook(options.webhook, input, {
+        verifier,
+        allowUnknownEvents: options.allowUnknownEvents,
+      })) as WebhookRouteHandlerArgs<Ctx, Webhook, AllowUnknownEvents>["event"];
+    } catch (error) {
+      ctx.ports.logger?.error("Webhook verification failed", {
+        error,
+        webhookName: options.webhook.name,
+        provider: options.webhook.provider,
+        requestId: ctx.requestId,
+        traceId: ctx.traceId,
+      });
+
+      return webhookRouteJson(
+        {
+          ok: false,
+          error: "Webhook verification failed.",
+        },
+        400,
+        headers,
+      );
+    }
+
+    try {
+      const result = await options.handle?.({
+        req: nativeReq,
+        ctx,
+        rawBody,
+        event,
+      });
+
+      if (result instanceof Response) return result;
+
+      if (result) {
+        return toWebResponse({
+          status: result.status ?? 200,
+          headers: toHttpResponseHeaders(result.headers ?? headers),
+          body: result.body,
+        });
+      }
+
+      return toWebResponse({
+        status: 200,
+        headers: toHttpResponseHeaders(headers),
+        body: {
+          ok: true,
+          webhookName: options.webhook.name,
+          eventId: event.id,
+          eventType: event.type,
+        },
+      });
+    } catch (error) {
+      ctx.ports.logger?.error("Webhook handler failed", {
+        error,
+        webhookName: options.webhook.name,
+        provider: options.webhook.provider,
+        requestId: ctx.requestId,
+        traceId: ctx.traceId,
+        eventId: event.id,
+        eventType: event.type,
+      });
+
+      return webhookRouteJson(
+        {
+          ok: false,
+          error: "Webhook handler failed.",
+        },
+        500,
+        headers,
+      );
+    }
+  };
+
+  const runPipeline = createRawPipelineRunner<Ctx>(
+    {
+      name: options.pipeline?.name ?? `webhook.${options.webhook.name}`,
+      method: "POST",
+      path: options.pipeline?.path ?? `/webhooks/${options.webhook.name}`,
+      metadata: options.pipeline?.metadata,
+    },
+    handleWebhookRequest,
+  );
+
   return {
     POST: async (req) => {
-      const headers = resolveHeaders(options.headers, req);
-      const requestHeaders = headersToRecord(req.headers);
+      const server = await resolveServerSource(options.server);
 
-      let ctx: Ctx;
+      const pipelined = runPipeline(server);
+      if (pipelined) return pipelined(req);
 
-      try {
-        ctx = await options.server.createContextFromNext();
-      } catch {
-        return webhookRouteJson(
-          {
-            ok: false,
-            error: "Webhook context failed.",
-          },
-          500,
-          headers,
-        );
-      }
+      // Minimal servers without rawRoute(...) — usually test fakes — build
+      // context directly and run the same handler outside the hooks pipeline.
+      const headers = resolveHeaders(options.headers, req);
 
       let rawBody: string;
-      let event: WebhookRouteHandlerArgs<
-        Ctx,
-        Webhook,
-        AllowUnknownEvents
-      >["event"];
-
       try {
         rawBody = await req.text();
-        const input: VerifyWebhookInput = {
-          rawBody,
-          headers: requestHeaders,
-          receivedAt: new Date(),
-        };
-        const routeVerifier = options.verify;
-        const verifier = routeVerifier
-          ? {
-              async verify() {
-                return routeVerifier({
-                  req,
-                  ctx,
-                  rawBody,
-                  headers: requestHeaders,
-                  input,
-                });
-              },
-            }
-          : undefined;
-
-        event = (await verifyWebhook(options.webhook, input, {
-          verifier,
-          allowUnknownEvents: options.allowUnknownEvents,
-        })) as WebhookRouteHandlerArgs<
-          Ctx,
-          Webhook,
-          AllowUnknownEvents
-        >["event"];
-      } catch (error) {
-        ctx.ports.logger?.error("Webhook verification failed", {
-          error,
-          webhookName: options.webhook.name,
-          provider: options.webhook.provider,
-          requestId: ctx.requestId,
-          traceId: ctx.traceId,
-        });
-
+      } catch {
         return webhookRouteJson(
           {
             ok: false,
-            error: "Webhook verification failed.",
+            error: "Webhook body read failed.",
           },
           400,
           headers,
         );
       }
 
-      try {
-        const result = await options.handle?.({
-          req,
-          ctx,
-          rawBody,
-          event,
-        });
-
-        if (result instanceof Response) return result;
-
-        if (result) {
-          return toWebResponse({
-            status: result.status ?? 200,
-            headers: toHttpResponseHeaders(result.headers ?? headers),
-            body: result.body,
-          });
-        }
-
-        return toWebResponse({
-          status: 200,
-          headers: toHttpResponseHeaders(headers),
-          body: {
-            ok: true,
-            webhookName: options.webhook.name,
-            eventId: event.id,
-            eventType: event.type,
-          },
-        });
-      } catch (error) {
-        ctx.ports.logger?.error("Webhook handler failed", {
-          error,
-          webhookName: options.webhook.name,
-          provider: options.webhook.provider,
-          requestId: ctx.requestId,
-          traceId: ctx.traceId,
-          eventId: event.id,
-          eventType: event.type,
-        });
+      const contextRequest = toContextRequest(req, rawBody);
 
+      let ctx: Ctx;
+      try {
+        ctx = await server.createRequestContext(contextRequest);
+      } catch {
         return webhookRouteJson(
           {
             ok: false,
-            error: "Webhook handler failed.",
+            error: "Webhook context failed.",
           },
           500,
           headers,
         );
       }
+
+      return handleWebhookRequest({ req: toContextRequest(req, rawBody), ctx });
     },
   };
 }
@@ -1350,9 +1807,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.
  */
@@ -1365,12 +1823,138 @@ export function createPaymentWebhookRoute<
 } {
   const signatureHeader = options.signatureHeader ?? "stripe-signature";
 
+  const handlePaymentWebhook = async ({
+    req,
+    ctx,
+  }: {
+    req: HttpRequestLike;
+    ctx: Ctx;
+  }): Promise<Response> => {
+    const nativeReq = nativeRequestOf(req);
+    const headers = resolveHeaders(options.headers, nativeReq);
+    const signature = new Headers(req.headers).get(signatureHeader);
+
+    if (!signature) {
+      return paymentWebhookJson(
+        {
+          ok: false,
+          error: `Missing ${signatureHeader} header.`,
+        },
+        400,
+        headers,
+      );
+    }
+
+    let rawBody: string;
+
+    try {
+      rawBody = await req.text();
+    } catch {
+      return paymentWebhookJson(
+        {
+          ok: false,
+          error: "Payment webhook body read failed.",
+        },
+        400,
+        headers,
+      );
+    }
+
+    let event: PaymentWebhookEvent;
+
+    try {
+      event = await ctx.ports.payments.verifyWebhook({
+        rawBody,
+        signature,
+      });
+    } catch (error) {
+      ctx.ports.logger?.error("Payment webhook verification failed", {
+        error,
+        requestId: ctx.requestId,
+        traceId: ctx.traceId,
+      });
+
+      return paymentWebhookJson(
+        {
+          ok: false,
+          error: "Payment webhook verification failed.",
+        },
+        400,
+        headers,
+      );
+    }
+
+    try {
+      const result = await options.handle?.({
+        req: nativeReq,
+        ctx,
+        rawBody,
+        signature,
+        event,
+      });
+
+      if (result instanceof Response) return result;
+
+      if (result) {
+        return toWebResponse({
+          status: result.status ?? 200,
+          headers: toHttpResponseHeaders(result.headers ?? headers),
+          body: result.body,
+        });
+      }
+
+      return toWebResponse({
+        status: 200,
+        headers: toHttpResponseHeaders(headers),
+        body: {
+          ok: true,
+          eventId: event.id,
+          eventType: event.type,
+        },
+      });
+    } catch (error) {
+      ctx.ports.logger?.error("Payment webhook handler failed", {
+        error,
+        requestId: ctx.requestId,
+        traceId: ctx.traceId,
+        eventId: event.id,
+        eventType: event.type,
+      });
+
+      return paymentWebhookJson(
+        {
+          ok: false,
+          error: "Payment webhook handler failed.",
+        },
+        500,
+        headers,
+      );
+    }
+  };
+
+  const runPipeline = createRawPipelineRunner<Ctx>(
+    {
+      name: options.pipeline?.name ?? "webhook.payments",
+      method: "POST",
+      path: options.pipeline?.path ?? "/webhooks/payments",
+      metadata: options.pipeline?.metadata,
+    },
+    handlePaymentWebhook,
+  );
+
   return {
     POST: async (req) => {
+      const server = await resolveServerSource(options.server);
+
+      const pipelined = runPipeline(server);
+      if (pipelined) return pipelined(req);
+
+      // Minimal servers without rawRoute(...) — usually test fakes — build
+      // context directly and run the same handler outside the hooks pipeline.
+      // The signature gate runs first so no context is created without one.
       const headers = resolveHeaders(options.headers, req);
-      const signature = req.headers.get(signatureHeader);
 
-      if (!signature) {
+      if (!req.headers.get(signatureHeader)) {
         return paymentWebhookJson(
           {
             ok: false,
@@ -1381,93 +1965,35 @@ export function createPaymentWebhookRoute<
         );
       }
 
-      let ctx: Ctx;
-
-      try {
-        ctx = await options.server.createContextFromNext();
-      } catch {
-        return paymentWebhookJson(
-          {
-            ok: false,
-            error: "Payment webhook context failed.",
-          },
-          500,
-          headers,
-        );
-      }
-
       let rawBody: string;
-      let event: PaymentWebhookEvent;
-
       try {
         rawBody = await req.text();
-        event = await ctx.ports.payments.verifyWebhook({
-          rawBody,
-          signature,
-        });
-      } catch (error) {
-        ctx.ports.logger?.error("Payment webhook verification failed", {
-          error,
-          requestId: ctx.requestId,
-          traceId: ctx.traceId,
-        });
-
+      } catch {
         return paymentWebhookJson(
           {
             ok: false,
-            error: "Payment webhook verification failed.",
+            error: "Payment webhook body read failed.",
           },
           400,
           headers,
         );
       }
 
+      let ctx: Ctx;
       try {
-        const result = await options.handle?.({
-          req,
-          ctx,
-          rawBody,
-          signature,
-          event,
-        });
-
-        if (result instanceof Response) return result;
-
-        if (result) {
-          return toWebResponse({
-            status: result.status ?? 200,
-            headers: toHttpResponseHeaders(result.headers ?? headers),
-            body: result.body,
-          });
-        }
-
-        return toWebResponse({
-          status: 200,
-          headers: toHttpResponseHeaders(headers),
-          body: {
-            ok: true,
-            eventId: event.id,
-            eventType: event.type,
-          },
-        });
-      } catch (error) {
-        ctx.ports.logger?.error("Payment webhook handler failed", {
-          error,
-          requestId: ctx.requestId,
-          traceId: ctx.traceId,
-          eventId: event.id,
-          eventType: event.type,
-        });
-
+        ctx = await server.createRequestContext(toContextRequest(req, rawBody));
+      } catch {
         return paymentWebhookJson(
           {
             ok: false,
-            error: "Payment webhook handler failed.",
+            error: "Payment webhook context failed.",
           },
           500,
           headers,
         );
       }
+
+      return handlePaymentWebhook({ req: toContextRequest(req, rawBody), ctx });
     },
   };
 }
@@ -1476,8 +2002,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.
  */
@@ -1503,8 +2030,15 @@ export function createScheduleRoute<Ctx extends ScheduleRouteContext>(
     );
   }
 
-  const runScheduleFromRequest = async (req: Request): Promise<Response> => {
-    const headers = resolveHeaders(options.headers, req);
+  const runSchedule = async ({
+    req,
+    ctx,
+  }: {
+    req: HttpRequestLike;
+    ctx: Ctx;
+  }): Promise<Response> => {
+    const nativeReq = nativeRequestOf(req);
+    const headers = resolveHeaders(options.headers, nativeReq);
     const secret = options.secret;
 
     if (!secret) {
@@ -1519,12 +2053,11 @@ export function createScheduleRoute<Ctx extends ScheduleRouteContext>(
       );
     }
 
-    if (!(await isAuthorizedCronRequest(req, secret))) {
+    if (!(await isAuthorizedCronRequest(nativeReq, secret))) {
       return cronRouteJson({ ok: false, error: "Unauthorized" }, 401, headers);
     }
 
     try {
-      const ctx = await options.server.createContextFromNext();
       const runner = createInlineScheduleRunner<Ctx>({
         ctx,
         instrumentation: resolveProviderInstrumentationPort(ctx.ports),
@@ -1565,6 +2098,69 @@ export function createScheduleRoute<Ctx extends ScheduleRouteContext>(
     }
   };
 
+  const pipelineInit = {
+    name: options.pipeline?.name ?? `schedule.${schedule.name}`,
+    path: options.pipeline?.path ?? `/schedules/${schedule.name}`,
+    metadata: options.pipeline?.metadata,
+  };
+  const pipelineRunners = {
+    GET: createRawPipelineRunner<Ctx>(
+      { ...pipelineInit, method: "GET" },
+      runSchedule,
+    ),
+    POST: createRawPipelineRunner<Ctx>(
+      { ...pipelineInit, method: "POST" },
+      runSchedule,
+    ),
+  };
+
+  const runScheduleFromRequest = async (req: Request): Promise<Response> => {
+    const server = await resolveServerSource(options.server);
+
+    const runner =
+      pipelineRunners[req.method.toUpperCase() === "GET" ? "GET" : "POST"];
+    const pipelined = runner(server);
+    if (pipelined) return pipelined(req);
+
+    // Minimal servers without rawRoute(...) — usually test fakes — keep the
+    // original flow: authorize before touching context, then run inline.
+    const headers = resolveHeaders(options.headers, req);
+    const secret = options.secret;
+
+    if (!secret) {
+      return cronRouteJson(
+        {
+          ok: false,
+          error: "CRON_SECRET is not configured.",
+          scheduleName: schedule.name,
+        },
+        500,
+        headers,
+      );
+    }
+
+    if (!(await isAuthorizedCronRequest(req, secret))) {
+      return cronRouteJson({ ok: false, error: "Unauthorized" }, 401, headers);
+    }
+
+    let ctx: Ctx;
+    try {
+      ctx = await server.createRequestContext(toRequestLike(req));
+    } catch {
+      return cronRouteJson(
+        {
+          ok: false,
+          error: "Schedule failed.",
+          scheduleName: schedule.name,
+        },
+        500,
+        headers,
+      );
+    }
+
+    return runSchedule({ req: toRequestLike(req), ctx });
+  };
+
   return {
     GET: runScheduleFromRequest,
     POST: runScheduleFromRequest,
@@ -1596,6 +2192,9 @@ export async function createNextServer<
     route: (contract) => ({
       handle: (fn) => createFetchHandler(runtime.route(contract).handle(fn)),
     }),
+    rawRoute: (init) => ({
+      handle: (fn) => createFetchHandler(runtime.rawRoute(init).handle(fn)),
+    }),
     createContextFromNext: async () => {
       // "next" ships no package exports map, so Node-style ESM resolution
       // (NodeNext) needs the explicit .js subpath. Bundlers resolve it the same.
@@ -1641,6 +2240,7 @@ export async function createNextServer<
     },
     createRequestContext: runtime.createRequestContext,
     createServiceContext: runtime.createServiceContext,
+    runServiceContext: runtime.runServiceContext,
     contracts: runtime.contracts,
     stop: () => runtime.stop(),
     ports: runtime.ports,