@beignet/next 0.0.27 → 0.0.28

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @beignet/next
 
+## 0.0.28
+
+### Patch Changes
+
+- 57504c5: Add `server.rawRoute(...)`: build handlers for routes that cannot be contracts — third-party callbacks, signature-verified webhooks, streaming endpoints — that still run the full pipeline (hooks, context creation, instrumentation, framework error mapping) with the request body left unconsumed. The Next.js webhook, payment webhook, schedule, and outbox drain route factories now run through this pipeline automatically when the server exposes `rawRoute`, with a new `pipeline` option for route identity and hook metadata.
+- Updated dependencies [f21e8af]
+- Updated dependencies [57504c5]
+  - @beignet/web@0.0.28
+
 ## 0.0.27
 
 ### Patch Changes

package/README.md

@@ -316,6 +316,52 @@ export async function GET(req: Request) {
 }
 ```
 
+#### `server.rawRoute(init)`
+
+Builds a handler for a route that cannot be a contract — third-party callback
+endpoints with externally defined request shapes, signature-verified
+webhooks, streaming endpoints — that still runs the whole server pipeline:
+correlation, 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.
+
+`init.name`, `init.method`, and `init.path` identify the route to hooks,
+instrumentation, and devtools — routing itself belongs to the route file
+that mounts the handler. `init.metadata` feeds metadata-driven hooks exactly
+like contract metadata.
+
+**Returns:** Builder with `handle(fn)` returning
+`(req: Request) => Promise<Response>`.
+
+```typescript
+// app/api/liveblocks-auth/route.ts
+import { getServer } from "@/server";
+
+let roomAuth: ((req: Request) => Promise<Response>) | undefined;
+
+export async function POST(req: Request) {
+  roomAuth ??= (await getServer())
+    .rawRoute({
+      name: "collab.roomAuth",
+      method: "POST",
+      path: "/api/liveblocks-auth",
+      metadata: { rateLimit: { max: 300, windowSec: 60, scope: "user" } },
+    })
+    .handle(async ({ req, ctx }) => {
+      const body = await req.text();
+      return { status: 200, body: { token: "..." } };
+    });
+
+  return roomAuth(req);
+}
+```
+
+The webhook, payment webhook, schedule, and outbox drain route factories run
+through this pipeline automatically when the `server` they receive exposes
+`rawRoute(...)`; their `pipeline` option supplies the route identity and
+metadata.
+
 #### `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.
@@ -556,13 +602,19 @@ The `action` segment must be `prepare`, `upload`, or `complete`.
 
 Use `createPaymentWebhookRoute(...)` for billing flows backed by
 `ctx.ports.payments`. Use `createWebhookRoute(...)` for generic inbound
-webhooks backed by a `defineWebhook(...)` catalog and a provider verifier. Both
-helpers read the raw request body first, then build app context from the real
-request with `server.createRequestContext(...)`, so signature verification
-never races the context factory over one body stream and trace headers
-propagate into context creation. The `server` option accepts any object
-exposing `createRequestContext` — a `NextServer`, a core `ServerInstance`, or
-a test fake — so `server: getServer` keeps working unchanged.
+webhooks backed by a `defineWebhook(...)` catalog and a provider verifier.
+The `server` option accepts any object exposing `createRequestContext` — a
+`NextServer`, a core `ServerInstance`, or a test fake — so
+`server: getServer` keeps working unchanged.
+
+When the server also exposes `rawRoute(...)` — real Beignet servers do — the
+route runs inside the full hooks pipeline: rate limiting, CORS, logging,
+error reporting, and instrumentation apply, the request appears in devtools,
+and the `pipeline` option supplies the route identity and metadata for
+metadata-driven hooks. The raw body stays unconsumed until the route reads
+it, so signature verification still sees the exact bytes. Minimal test fakes
+without `rawRoute` keep the direct flow: raw body first, then app context
+through `server.createRequestContext(...)`.
 
 ```typescript
 // app/api/webhooks/github/route.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/next",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "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.27",
+    "@beignet/web": "^0.0.28",
     "@standard-schema/spec": "^1.0.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -24,7 +24,9 @@ import type {
   CreateServerOptions,
   Handler,
   HealthConfig,
+  HttpContractConfig,
   HttpRequestLike,
+  RawRouteInit,
   ResolveContract,
   RouteDef,
   ServerInstance,
@@ -49,6 +51,7 @@ export type {
   AnyUseCaseLike,
   CreateServerOptions,
   HandlerRouteDef,
+  RawRouteInit,
   RouteDef,
   RouteGroup,
   RouteHook,
@@ -99,6 +102,80 @@ async function resolveServerSource<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.
  */
@@ -293,6 +370,11 @@ type OutboxDrainContext = {
  * 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>;
@@ -332,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.
    */
@@ -470,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.
    */
@@ -510,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.
    */
@@ -545,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.
    */
@@ -579,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.
    */
@@ -1297,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) {
@@ -1312,15 +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 {
-      const server = await resolveServerSource(options.server);
-      ctx = await server.createRequestContext(toRequestLike(req));
       const drainCtx = ctx;
       const result = await drainOutbox({
         outbox: drainCtx.ports.outbox,
@@ -1375,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(
         {
@@ -1388,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,
@@ -1412,13 +1622,154 @@ 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 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.
       const headers = resolveHeaders(options.headers, req);
-      const requestHeaders = headersToRecord(req.headers);
 
       let rawBody: string;
-
       try {
         rawBody = await req.text();
       } catch {
@@ -1432,11 +1783,11 @@ export function createWebhookRoute<
         );
       }
 
-      let ctx: Ctx;
+      const contextRequest = toContextRequest(req, rawBody);
 
+      let ctx: Ctx;
       try {
-        const server = await resolveServerSource(options.server);
-        ctx = await server.createRequestContext(toContextRequest(req, rawBody));
+        ctx = await server.createRequestContext(contextRequest);
       } catch {
         return webhookRouteJson(
           {
@@ -1448,108 +1799,7 @@ export function createWebhookRoute<
         );
       }
 
-      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,
-                  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,
-          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,
-        );
-      }
+      return handleWebhookRequest({ req: toContextRequest(req, rawBody), ctx });
     },
   };
 }
@@ -1573,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,
@@ -1590,7 +1966,6 @@ export function createPaymentWebhookRoute<
       }
 
       let rawBody: string;
-
       try {
         rawBody = await req.text();
       } catch {
@@ -1605,9 +1980,7 @@ export function createPaymentWebhookRoute<
       }
 
       let ctx: Ctx;
-
       try {
-        const server = await resolveServerSource(options.server);
         ctx = await server.createRequestContext(toContextRequest(req, rawBody));
       } catch {
         return paymentWebhookJson(
@@ -1620,76 +1993,7 @@ export function createPaymentWebhookRoute<
         );
       }
 
-      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,
-          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,
-        );
-      }
+      return handlePaymentWebhook({ req: toContextRequest(req, rawBody), ctx });
     },
   };
 }
@@ -1726,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) {
@@ -1742,13 +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 server = await resolveServerSource(options.server);
-      const ctx = await server.createRequestContext(toRequestLike(req));
       const runner = createInlineScheduleRunner<Ctx>({
         ctx,
         instrumentation: resolveProviderInstrumentationPort(ctx.ports),
@@ -1789,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,
@@ -1820,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.