@beignet/next 0.0.1 → 0.0.4

package/src/index.ts

@@ -1,41 +1,80 @@
 import type { ClientConfig } from "@beignet/core/client";
 import { createClient } from "@beignet/core/client";
+import {
+  type DrainOutboxOptions,
+  drainOutbox,
+  type OutboxRegistry,
+} from "@beignet/core/outbox";
 import type { AnyPorts, StoragePort } from "@beignet/core/ports";
 import type {
-  ProvidedPortsOfList,
+  InferProviderPorts,
   ServiceProvider,
 } from "@beignet/core/providers";
+import { resolveProviderInstrumentationPort } from "@beignet/core/providers";
+import {
+  createInlineScheduleRunner,
+  type ScheduleDef,
+  type ScheduleInstrumentation,
+  type StandardSchema,
+} from "@beignet/core/schedules";
 import type {
   ContractLike,
   CreateServerOptions,
   Handler,
   HttpRequestLike,
-  HttpResponse,
   ResolveContract,
   RouteDef,
+  ServerInstance,
   StandardSchemaV1,
 } from "@beignet/core/server";
 import { createServer } from "@beignet/core/server";
+import type { UploadRouter } from "@beignet/core/uploads";
+import { createFetchHandler, toWebResponse } from "@beignet/web";
 
+/**
+ * Server types re-exported for Next.js apps.
+ */
 export type {
+  AnyUseCaseLike,
   CreateServerOptions,
+  HandlerRouteDef,
+  RouteDef,
   RouteGroup,
+  RouteHook,
   ServerInstance,
+  UseCaseRouteDef,
 } from "@beignet/core/server";
+/**
+ * Server helpers re-exported for Next.js apps.
+ */
 export {
   contractsFromRoutes,
   createServer,
+  defaultBinderInput,
+  defineRoute,
   defineRouteGroup,
   defineRoutes,
 } from "@beignet/core/server";
 
+/**
+ * Web Fetch adapter helpers re-exported for Next.js route helpers.
+ */
+export { createFetchHandler, toRequestLike, toWebResponse } from "@beignet/web";
+
 type AnyProvider = ServiceProvider<
   unknown,
   // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
   StandardSchemaV1<any, any>,
-  AnyPorts
+  AnyPorts,
+  // biome-ignore lint/suspicious/noExplicitAny: provider context types are erased at this level
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: provider service-input types are erased at this level
+  any
 >;
 
+/**
+ * Beignet client config with Next.js base URL defaults.
+ */
 export type NextClientConfig<TProvidedHeaders extends string = never> = Omit<
   ClientConfig<TProvidedHeaders>,
   "baseUrl"
@@ -53,9 +92,21 @@ export type NextClientConfig<TProvidedHeaders extends string = never> = Omit<
   serverBaseUrl?: string | (() => string | undefined);
 };
 
+/**
+ * OpenAPI server object accepted by `createOpenAPIHandler(...)`.
+ */
 export type OpenAPIServer = {
+  /**
+   * Server URL.
+   */
   url: string;
+  /**
+   * Server description.
+   */
   description?: string;
+  /**
+   * Server URL variables.
+   */
   variables?: Record<
     string,
     {
@@ -66,15 +117,45 @@ export type OpenAPIServer = {
   >;
 };
 
+/**
+ * Options for the Next.js OpenAPI route handler.
+ */
 export type CreateOpenAPIHandlerOptions = {
+  /**
+   * API title.
+   */
   title: string;
+  /**
+   * API version.
+   */
   version: string;
+  /**
+   * API description.
+   */
   description?: string;
+  /**
+   * Static servers or a request-aware server factory.
+   */
   servers?: OpenAPIServer[] | ((req: Request) => OpenAPIServer[]);
+  /**
+   * JSON media type used for generated content.
+   */
   jsonMediaType?: string;
+  /**
+   * OpenAPI security schemes.
+   */
   securitySchemes?: Record<string, unknown>;
+  /**
+   * Global security requirements.
+   */
   security?: Array<Record<string, string[]>>;
+  /**
+   * Custom schema introspector for non-Zod schema libraries.
+   */
   schemaIntrospector?: unknown;
+  /**
+   * Additional response headers.
+   */
   headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
   /**
    * Add the current request origin as the OpenAPI server when `servers` is omitted.
@@ -84,12 +165,27 @@ export type CreateOpenAPIHandlerOptions = {
   inferServersFromRequest?: boolean;
 };
 
+/**
+ * Options for the Next.js Swagger UI route handler.
+ */
 export type CreateSwaggerUIHandlerOptions = {
+  /**
+   * HTML page title.
+   */
   title?: string;
+  /**
+   * URL of the OpenAPI JSON route.
+   */
   specUrl?: string | ((req: Request) => string);
+  /**
+   * Additional response headers.
+   */
   headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
 };
 
+/**
+ * Options for serving public storage objects through a Next.js route.
+ */
 export type CreateStorageRouteOptions = {
   /**
    * Public path prefix that maps to storage keys.
@@ -103,8 +199,163 @@ export type CreateStorageRouteOptions = {
   headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
 };
 
-export interface NextServer<Ctx, Ports extends AnyPorts = AnyPorts> {
+/**
+ * Options for creating a Next.js upload route.
+ */
+export type CreateUploadRouteOptions = {
+  /**
+   * Static upload name. Omit when using a dynamic `[uploadName]` segment.
+   */
+  uploadName?: string;
+  /**
+   * Static upload action. Omit when using a dynamic `[action]` segment.
+   */
+  action?: "prepare" | "complete" | "upload";
+};
+
+type OutboxDrainLogger = {
+  error(message: string, metadata?: Record<string, unknown>): void;
+};
+
+type OutboxDrainInstrumentation = {
+  record(event: {
+    type: "custom";
+    watcher: string;
+    name: string;
+    label: string;
+    summary: string;
+    requestId?: string;
+    traceId?: string;
+    details: unknown;
+  }): unknown;
+};
+
+type OutboxDrainPorts = {
+  outbox: DrainOutboxOptions["outbox"];
+  eventBus?: DrainOutboxOptions["eventBus"];
+  jobs?: DrainOutboxOptions["jobs"];
+  logger?: OutboxDrainLogger;
+  devtools?: OutboxDrainInstrumentation;
+  instrumentation?: OutboxDrainInstrumentation;
+};
+
+type OutboxDrainContext = {
+  requestId?: string;
+  traceId?: string;
+  ports: OutboxDrainPorts;
+};
+
+/**
+ * Options for creating a serverless-safe outbox drain route.
+ */
+export type CreateOutboxDrainRouteOptions<Ctx extends OutboxDrainContext> = {
+  /**
+   * Beignet Next server that owns app context and ports.
+   */
+  server: Pick<NextServer<Ctx, Ctx["ports"]>, "createContextFromNext">;
+  /**
+   * Registry of events and jobs that may be delivered from the outbox.
+   */
+  registry: OutboxRegistry;
+  /**
+   * Shared secret expected in the `Authorization: Bearer <secret>` header.
+   *
+   * Missing secrets fail closed with a 500 response so deployments do not
+   * accidentally expose an unauthenticated drain route.
+   */
+  secret?: string;
+  /**
+   * Maximum messages to claim in one drain pass.
+   */
+  batchSize?: number;
+  /**
+   * Claim lease duration in milliseconds.
+   */
+  leaseMs?: number;
+  /**
+   * Retry delay override passed through to `drainOutbox(...)`.
+   */
+  retryDelayMs?: DrainOutboxOptions["retryDelayMs"];
+  /**
+   * Additional response headers.
+   */
+  headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
+};
+
+type ScheduleRouteLogger = {
+  error(message: string, metadata?: Record<string, unknown>): void;
+};
+
+type ScheduleRoutePorts = {
+  logger?: ScheduleRouteLogger;
+  devtools?: ScheduleInstrumentation;
+  instrumentation?: ScheduleInstrumentation;
+};
+
+type ScheduleRouteContext = {
+  requestId?: string;
+  traceId?: string;
+  ports: ScheduleRoutePorts;
+};
+
+/**
+ * Options for creating a serverless-safe schedule trigger route.
+ */
+export type CreateScheduleRouteOptions<Ctx extends ScheduleRouteContext> = {
+  /**
+   * Beignet Next server that owns app context and ports.
+   */
+  server: Pick<NextServer<Ctx, Ctx["ports"]>, "createContextFromNext">;
+  /**
+   * Registered schedules, usually the `schedules` array from
+   * `server/schedules.ts`.
+   */
+  schedules: readonly ScheduleDef<string, StandardSchema, Ctx>[];
+  /**
+   * Name of the schedule this route triggers. Unknown names throw when the
+   * route module loads so misconfigured routes fail at build or boot time.
+   */
+  schedule: string;
+  /**
+   * Shared secret expected in the `Authorization: Bearer <secret>` header.
+   *
+   * Missing secrets fail closed with a 500 response so deployments do not
+   * accidentally expose an unauthenticated trigger route.
+   */
+  secret?: string;
+  /**
+   * Run source label recorded on run metadata and devtools events.
+   *
+   * @default "next-cron-route"
+   */
+  source?: string;
+  /**
+   * Additional response headers.
+   */
+  headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
+};
+
+type UploadRouteContext = {
+  params?:
+    | Promise<Record<string, string | string[] | undefined>>
+    | Record<string, string | string[] | undefined>;
+};
+
+/**
+ * Beignet server adapted for Next.js route handlers and server components.
+ */
+export interface NextServer<
+  Ctx,
+  Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
+> {
+  /**
+   * Catch-all Next.js route handler.
+   */
   api: (req: Request) => Promise<Response>;
+  /**
+   * Register and build a single Next.js route handler imperatively.
+   */
   route: <CLike extends ContractLike>(
     contractLike: CLike,
   ) => {
@@ -112,42 +363,49 @@ export interface NextServer<Ctx, Ports extends AnyPorts = AnyPorts> {
       fn: Handler<Ctx, ResolveContract<CLike>>,
     ) => (req: Request) => Promise<Response>;
   };
+  /**
+   * Create app context from `next/headers` for Server Components.
+   */
   createContextFromNext: () => Promise<Ctx>;
+  /**
+   * Build a fully assembled request context from a framework-neutral request.
+   */
+  createRequestContext: ServerInstance<
+    Ctx,
+    Ports,
+    ServiceInput
+  >["createRequestContext"];
+  /**
+   * Build a fully assembled service context for schedules, outbox drains,
+   * commands, and background work.
+   *
+   * Requires `context.service` to be declared in `createNextServer(...)`.
+   */
+  createServiceContext: ServerInstance<
+    Ctx,
+    Ports,
+    ServiceInput
+  >["createServiceContext"];
+  /**
+   * Registered contract inputs.
+   */
   contracts: readonly ContractLike[];
+  /**
+   * Stop installed providers.
+   */
   stop: () => Promise<void>;
+  /**
+   * Final app ports after provider setup.
+   */
   ports: Ports;
 }
 
-export function toRequestLike(req: Request): HttpRequestLike {
-  return {
-    method: req.method,
-    url: req.url,
-    headers: new Headers(req.headers),
-    raw: req,
-    json: () => req.json(),
-    text: () => req.text(),
-    arrayBuffer: () => req.arrayBuffer(),
-    blob: () => req.blob(),
-    formData: () => req.formData(),
-    clone: () => toRequestLike(req.clone()),
-  };
-}
-
-export function toNextResponse(resLike: HttpResponse): Response {
-  if (resLike instanceof Response) {
-    return resLike;
-  }
-
-  const headers = new Headers(resLike.headers);
-  const body = resLike.body;
-
-  if (body === undefined || body === null) {
-    return new Response(null, { status: resLike.status, headers });
-  }
-
-  // biome-ignore lint/suspicious/noExplicitAny: Body can be any JSON-serializable value
-  return Response.json(body as any, { status: resLike.status, headers });
-}
+/**
+ * Convert a Beignet response into a native `Response`.
+ *
+ * This is the Next-named alias for `toWebResponse(...)` from `@beignet/web`.
+ */
+export const toNextResponse = toWebResponse;
 
 function resolveConfigValue(
   value: string | (() => string | undefined) | undefined,
@@ -280,6 +538,10 @@ function storageNotFoundResponse(): Response {
   return new Response(null, { status: 404 });
 }
 
+function firstParam(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
 async function storageResponse(
   storage: StoragePort,
   req: Request,
@@ -456,37 +718,351 @@ export function createStorageRoute(
   };
 }
 
+/**
+ * Create a Next.js POST handler for Beignet upload routes.
+ *
+ * Use this in a dynamic route such as
+ * `app/api/uploads/[uploadName]/[action]/route.ts`, where `action` is
+ * `prepare`, `complete`, or `upload`.
+ */
+export function createUploadRoute(
+  router: UploadRouter,
+  options: CreateUploadRouteOptions = {},
+): {
+  POST: (req: Request, ctx?: UploadRouteContext) => Promise<Response>;
+} {
+  return {
+    POST: async (req, ctx) => {
+      const params = await ctx?.params;
+      const uploadName =
+        options.uploadName ?? firstParam(params?.uploadName ?? params?.upload);
+      const action = options.action ?? firstParam(params?.action);
+
+      if (!uploadName) {
+        return Response.json(
+          {
+            error: {
+              code: "UPLOAD_NOT_FOUND",
+              message: "Upload route is missing an upload name.",
+            },
+          },
+          { status: 404 },
+        );
+      }
+
+      if (
+        action !== "prepare" &&
+        action !== "complete" &&
+        action !== "upload"
+      ) {
+        return Response.json(
+          {
+            error: {
+              code: "INVALID_UPLOAD_ACTION",
+              message:
+                'Upload route action must be "prepare", "complete", or "upload".',
+            },
+          },
+          { status: 400 },
+        );
+      }
+
+      return router.handleRequest(req, {
+        uploadName,
+        action,
+      });
+    },
+  };
+}
+
+function cronRouteJson(
+  body: unknown,
+  status: number,
+  headers: HeadersInit | undefined,
+): Response {
+  return Response.json(body, {
+    status,
+    headers,
+  });
+}
+
+/**
+ * Compare two strings without leaking length or prefix timing.
+ *
+ * Both values are hashed with SHA-256 so the XOR comparison always runs over
+ * fixed-size digests, which keeps the check edge-compatible and constant-time.
+ */
+async function timingSafeStringEqual(a: string, b: string): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const [digestA, digestB] = await Promise.all([
+    crypto.subtle.digest("SHA-256", encoder.encode(a)),
+    crypto.subtle.digest("SHA-256", encoder.encode(b)),
+  ]);
+  const bytesA = new Uint8Array(digestA);
+  const bytesB = new Uint8Array(digestB);
+
+  let mismatch = 0;
+  for (let index = 0; index < bytesA.length; index++) {
+    mismatch |= (bytesA[index] ?? 0) ^ (bytesB[index] ?? 0);
+  }
+
+  return mismatch === 0;
+}
+
+async function isAuthorizedCronRequest(
+  req: Request,
+  secret: string,
+): Promise<boolean> {
+  return timingSafeStringEqual(
+    req.headers.get("authorization") ?? "",
+    `Bearer ${secret}`,
+  );
+}
+
+/**
+ * Create Next.js route handlers that drain one durable outbox batch.
+ *
+ * This helper is intended for serverless cron routes. It performs bounded work
+ * and exits; do not start long-running outbox polling loops from provider
+ * lifecycle hooks in serverless apps.
+ */
+export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
+  options: CreateOutboxDrainRouteOptions<Ctx>,
+): {
+  GET: (req: Request) => Promise<Response>;
+  POST: (req: Request) => Promise<Response>;
+} {
+  const drainPendingOutbox = async (req: Request): Promise<Response> => {
+    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 | undefined;
+
+    try {
+      ctx = await options.server.createContextFromNext();
+      const drainCtx = ctx;
+      const result = await drainOutbox({
+        outbox: drainCtx.ports.outbox,
+        registry: options.registry,
+        eventBus: drainCtx.ports.eventBus,
+        jobs: drainCtx.ports.jobs,
+        batchSize: options.batchSize,
+        leaseMs: options.leaseMs,
+        retryDelayMs: options.retryDelayMs,
+        instrumentation: resolveProviderInstrumentationPort(drainCtx.ports),
+        instrumentationContext: {
+          requestId: drainCtx.requestId,
+          traceId: drainCtx.traceId,
+        },
+        onError(error, message) {
+          drainCtx.ports.logger?.error("Outbox delivery failed", {
+            error,
+            outboxMessageId: message.id,
+            kind: message.kind,
+            name: message.name,
+            attempts: message.attempts,
+          });
+        },
+      });
+
+      try {
+        await resolveProviderInstrumentationPort(drainCtx.ports)?.record({
+          type: "custom",
+          watcher: "outbox",
+          name: "outbox.drain",
+          label: "Outbox drain",
+          summary: `${result.delivered} delivered, ${result.retried} retried, ${result.deadLettered} dead-lettered`,
+          requestId: drainCtx.requestId,
+          traceId: drainCtx.traceId,
+          details: result,
+        });
+      } catch (error) {
+        drainCtx.ports.logger?.error(
+          "Outbox drain instrumentation recording failed",
+          {
+            error,
+          },
+        );
+      }
+
+      return cronRouteJson(
+        {
+          ok: true,
+          result,
+        },
+        200,
+        headers,
+      );
+    } catch (error) {
+      ctx?.ports.logger?.error("Outbox drain failed", { error });
+
+      return cronRouteJson(
+        {
+          ok: false,
+          error: "Outbox drain failed.",
+        },
+        500,
+        headers,
+      );
+    }
+  };
+
+  return {
+    GET: drainPendingOutbox,
+    POST: drainPendingOutbox,
+  };
+}
+
+/**
+ * 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
+ * provider instrumentation port (`ports.instrumentation`, then
+ * `ports.devtools`) when one is installed.
+ */
+export function createScheduleRoute<Ctx extends ScheduleRouteContext>(
+  options: CreateScheduleRouteOptions<Ctx>,
+): {
+  GET: (req: Request) => Promise<Response>;
+  POST: (req: Request) => Promise<Response>;
+} {
+  const schedule = options.schedules.find(
+    (candidate) => candidate.name === options.schedule,
+  );
+
+  if (!schedule) {
+    const available = options.schedules
+      .map((candidate) => candidate.name)
+      .sort();
+
+    throw new Error(
+      available.length > 0
+        ? `Unknown schedule "${options.schedule}". Available schedules: ${available.join(", ")}.`
+        : `Unknown schedule "${options.schedule}". No schedules were passed to createScheduleRoute(...).`,
+    );
+  }
+
+  const runScheduleFromRequest = async (req: Request): Promise<Response> => {
+    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);
+    }
+
+    try {
+      const ctx = await options.server.createContextFromNext();
+      const runner = createInlineScheduleRunner<Ctx>({
+        ctx,
+        instrumentation: resolveProviderInstrumentationPort(ctx.ports),
+        instrumentationContext: {
+          requestId: ctx.requestId,
+          traceId: ctx.traceId,
+        },
+        onError({ error }) {
+          ctx.ports.logger?.error("Schedule failed", {
+            error,
+            scheduleName: schedule.name,
+          });
+        },
+      });
+
+      await runner.run(schedule, {
+        source: options.source ?? "next-cron-route",
+      });
+
+      return cronRouteJson(
+        {
+          ok: true,
+          scheduleName: schedule.name,
+        },
+        200,
+        headers,
+      );
+    } catch {
+      return cronRouteJson(
+        {
+          ok: false,
+          error: "Schedule failed.",
+          scheduleName: schedule.name,
+        },
+        500,
+        headers,
+      );
+    }
+  };
+
+  return {
+    GET: runScheduleFromRequest,
+    POST: runScheduleFromRequest,
+  };
+}
+
+/**
+ * Create a Beignet server adapted for Next.js.
+ *
+ * The returned `api` handler is intended for a catch-all route. Focused routes
+ * such as OpenAPI, Swagger UI, devtools, and public storage can use their own
+ * route helpers.
+ */
 export async function createNextServer<
   Ctx,
   Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
   Routes extends readonly RouteDef<Ctx>[] = readonly RouteDef<Ctx>[],
   Providers extends readonly AnyProvider[] = readonly AnyProvider[],
 >(
-  options: CreateServerOptions<Ctx, Ports, Routes, Providers>,
-): Promise<NextServer<Ctx, Ports & ProvidedPortsOfList<Providers>>> {
+  options: CreateServerOptions<Ctx, Ports, ServiceInput, Routes, Providers>,
+): Promise<
+  NextServer<Ctx, Ports & InferProviderPorts<Providers>, ServiceInput>
+> {
   const runtime = await createServer(options);
 
-  const wrap = (handler: (req: HttpRequestLike) => Promise<HttpResponse>) => {
-    return async (req: Request) => {
-      const res = await handler(toRequestLike(req));
-      return toNextResponse(res);
-    };
-  };
-
   return {
-    api: wrap(runtime.api),
+    api: createFetchHandler(runtime),
     route: (contract) => ({
-      handle: (fn) => wrap(runtime.route(contract).handle(fn)),
+      handle: (fn) => createFetchHandler(runtime.route(contract).handle(fn)),
     }),
     createContextFromNext: async () => {
-      const { cookies, headers } = await import("next/headers");
+      // "next" ships no package exports map, so Node-style ESM resolution
+      // (NodeNext) needs the explicit .js subpath. Bundlers resolve it the same.
+      const { cookies, headers } = await import("next/headers.js");
       const h = await headers();
       const c = await cookies();
 
       // Minimal Request-like object for Next.js Server Components.
       // Note: Server Components don't have a real HTTP URL; this is a synthetic placeholder.
       // Do not rely on `url` for routing, security, or network behavior.
-      // Extended with cookies property for easier access in createContext.
+      // Extended with cookies property for easier access in context factories.
       // The json() and text() methods return empty values since there's no actual HTTP request body.
       const req: HttpRequestLike & {
         cookies?: { get: (key: string) => string | undefined };
@@ -507,11 +1083,10 @@ export async function createNextServer<
         },
       };
 
-      return options.createContext({
-        req,
-        ports: runtime.ports,
-      });
+      return runtime.createRequestContext(req);
     },
+    createRequestContext: runtime.createRequestContext,
+    createServiceContext: runtime.createServiceContext,
     contracts: runtime.contracts,
     stop: () => runtime.stop(),
     ports: runtime.ports,