@beignet/next 0.0.1

package/src/index.ts

@@ -0,0 +1,519 @@
+import type { ClientConfig } from "@beignet/core/client";
+import { createClient } from "@beignet/core/client";
+import type { AnyPorts, StoragePort } from "@beignet/core/ports";
+import type {
+  ProvidedPortsOfList,
+  ServiceProvider,
+} from "@beignet/core/providers";
+import type {
+  ContractLike,
+  CreateServerOptions,
+  Handler,
+  HttpRequestLike,
+  HttpResponse,
+  ResolveContract,
+  RouteDef,
+  StandardSchemaV1,
+} from "@beignet/core/server";
+import { createServer } from "@beignet/core/server";
+
+export type {
+  CreateServerOptions,
+  RouteGroup,
+  ServerInstance,
+} from "@beignet/core/server";
+export {
+  contractsFromRoutes,
+  createServer,
+  defineRouteGroup,
+  defineRoutes,
+} from "@beignet/core/server";
+
+type AnyProvider = ServiceProvider<
+  unknown,
+  // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
+  StandardSchemaV1<any, any>,
+  AnyPorts
+>;
+
+export type NextClientConfig<TProvidedHeaders extends string = never> = Omit<
+  ClientConfig<TProvidedHeaders>,
+  "baseUrl"
+> & {
+  /**
+   * Explicit base URL for both browser and server calls.
+   *
+   * In browser code, omit this to use same-origin relative requests.
+   */
+  baseUrl?: string | (() => string | undefined);
+  /**
+   * Server-only fallback base URL for SSR, prefetching, tests, and server actions.
+   * Browser calls ignore this value unless `baseUrl` is also provided.
+   */
+  serverBaseUrl?: string | (() => string | undefined);
+};
+
+export type OpenAPIServer = {
+  url: string;
+  description?: string;
+  variables?: Record<
+    string,
+    {
+      default: string;
+      enum?: string[];
+      description?: string;
+    }
+  >;
+};
+
+export type CreateOpenAPIHandlerOptions = {
+  title: string;
+  version: string;
+  description?: string;
+  servers?: OpenAPIServer[] | ((req: Request) => OpenAPIServer[]);
+  jsonMediaType?: string;
+  securitySchemes?: Record<string, unknown>;
+  security?: Array<Record<string, string[]>>;
+  schemaIntrospector?: unknown;
+  headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
+  /**
+   * Add the current request origin as the OpenAPI server when `servers` is omitted.
+   *
+   * @default true
+   */
+  inferServersFromRequest?: boolean;
+};
+
+export type CreateSwaggerUIHandlerOptions = {
+  title?: string;
+  specUrl?: string | ((req: Request) => string);
+  headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
+};
+
+export type CreateStorageRouteOptions = {
+  /**
+   * Public path prefix that maps to storage keys.
+   *
+   * @default "/storage"
+   */
+  basePath?: string;
+  /**
+   * Additional response headers for served objects.
+   */
+  headers?: HeadersInit | ((req: Request) => HeadersInit | undefined);
+};
+
+export interface NextServer<Ctx, Ports extends AnyPorts = AnyPorts> {
+  api: (req: Request) => Promise<Response>;
+  route: <CLike extends ContractLike>(
+    contractLike: CLike,
+  ) => {
+    handle: (
+      fn: Handler<Ctx, ResolveContract<CLike>>,
+    ) => (req: Request) => Promise<Response>;
+  };
+  createContextFromNext: () => Promise<Ctx>;
+  contracts: readonly ContractLike[];
+  stop: () => Promise<void>;
+  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 });
+}
+
+function resolveConfigValue(
+  value: string | (() => string | undefined) | undefined,
+): string | undefined {
+  return typeof value === "function" ? value() : value;
+}
+
+/**
+ * Resolve the right Beignet client base URL for Next.js.
+ *
+ * Browser calls default to same-origin relative URLs. Server calls need an
+ * absolute URL, so this helper checks `NEXT_PUBLIC_API_URL`, then Vercel's
+ * deployment URL, then localhost.
+ */
+export function resolveNextBaseUrl(
+  options: NextClientConfig<string> = {},
+): string {
+  const explicitBaseUrl = resolveConfigValue(options.baseUrl);
+  if (explicitBaseUrl !== undefined) return explicitBaseUrl;
+
+  if (process.env.NEXT_PUBLIC_API_URL) return process.env.NEXT_PUBLIC_API_URL;
+
+  if (typeof window !== "undefined") return "";
+
+  const serverBaseUrl = resolveConfigValue(options.serverBaseUrl);
+  if (serverBaseUrl !== undefined) return serverBaseUrl;
+
+  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;
+
+  return `http://localhost:${process.env.PORT || 3000}`;
+}
+
+/**
+ * Create a Beignet client with Next.js-friendly base URL defaults.
+ */
+export function createNextClient<const TProvidedHeaders extends string = never>(
+  config: NextClientConfig<TProvidedHeaders> = {},
+) {
+  const {
+    baseUrl: _baseUrl,
+    serverBaseUrl: _serverBaseUrl,
+    ...clientConfig
+  } = config;
+
+  return createClient<TProvidedHeaders>({
+    ...clientConfig,
+    baseUrl: resolveNextBaseUrl(config),
+  });
+}
+
+function resolveHeaders(
+  headers:
+    | HeadersInit
+    | ((req: Request) => HeadersInit | undefined)
+    | undefined,
+  req: Request,
+): HeadersInit | undefined {
+  return typeof headers === "function" ? headers(req) : headers;
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code <= 31 || code === 127) return true;
+  }
+
+  return false;
+}
+
+function normalizeStorageBasePath(basePath: string | undefined): string {
+  const path = basePath ?? "/storage";
+
+  if (!path.startsWith("/")) {
+    throw new Error("Storage route basePath must start with '/'.");
+  }
+
+  if (path.includes("?") || path.includes("#")) {
+    throw new Error("Storage route basePath must be a pathname.");
+  }
+
+  return path.replace(/\/+$/, "") || "/";
+}
+
+function keyFromStorageRequest(req: Request, basePath: string): string | null {
+  const pathname = new URL(req.url).pathname;
+  const prefix = basePath === "/" ? "/" : `${basePath}/`;
+
+  if (
+    basePath !== "/" &&
+    pathname !== basePath &&
+    !pathname.startsWith(prefix)
+  ) {
+    return null;
+  }
+
+  const encodedKey =
+    basePath === "/" ? pathname.slice(1) : pathname.slice(prefix.length);
+
+  if (!encodedKey) return null;
+
+  try {
+    const key = encodedKey
+      .split("/")
+      .map((segment) => decodeURIComponent(segment))
+      .join("/");
+
+    const segments = key.split("/");
+    if (
+      !key ||
+      key.includes("\\") ||
+      hasControlCharacter(key) ||
+      segments.some(
+        (segment) =>
+          segment === "" ||
+          segment === "." ||
+          segment === ".." ||
+          segment === ".beignet-storage-meta",
+      )
+    ) {
+      return null;
+    }
+
+    return key;
+  } catch {
+    return null;
+  }
+}
+
+function storageNotFoundResponse(): Response {
+  return new Response(null, { status: 404 });
+}
+
+async function storageResponse(
+  storage: StoragePort,
+  req: Request,
+  basePath: string,
+  options: CreateStorageRouteOptions,
+  includeBody: boolean,
+): Promise<Response> {
+  const key = keyFromStorageRequest(req, basePath);
+  if (!key) return storageNotFoundResponse();
+
+  const object = await storage.get(key);
+  if (!object || object.visibility !== "public") {
+    return storageNotFoundResponse();
+  }
+
+  const headers = new Headers(resolveHeaders(options.headers, req));
+  headers.set("content-length", String(object.size));
+  headers.set("last-modified", object.lastModified.toUTCString());
+
+  if (object.contentType && !headers.has("content-type")) {
+    headers.set("content-type", object.contentType);
+  }
+
+  if (object.cacheControl && !headers.has("cache-control")) {
+    headers.set("cache-control", object.cacheControl);
+  }
+
+  return new Response(includeBody ? object.stream() : null, {
+    status: 200,
+    headers,
+  });
+}
+
+function currentRequestServer(req: Request): OpenAPIServer {
+  const url = new URL(req.url);
+  return {
+    url: `${url.protocol}//${url.host}`,
+    description: "Current server",
+  };
+}
+
+/**
+ * Create a Next.js route handler that returns an OpenAPI document.
+ *
+ * Requires `@beignet/core/openapi` and the `zod` peer dependency.
+ */
+export function createOpenAPIHandler(
+  contracts: readonly ContractLike[],
+  options: CreateOpenAPIHandlerOptions,
+): (req: Request) => Promise<Response> {
+  return async (req: Request) => {
+    const { contractsToOpenAPI } = await import("@beignet/core/openapi");
+    const servers =
+      typeof options.servers === "function"
+        ? options.servers(req)
+        : (options.servers ??
+          (options.inferServersFromRequest === false
+            ? undefined
+            : [currentRequestServer(req)]));
+
+    const spec = contractsToOpenAPI(contracts, {
+      title: options.title,
+      version: options.version,
+      description: options.description,
+      servers,
+      jsonMediaType: options.jsonMediaType,
+      securitySchemes: options.securitySchemes as never,
+      security: options.security,
+      schemaIntrospector: options.schemaIntrospector as never,
+    });
+
+    const headers = new Headers(resolveHeaders(options.headers, req));
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+
+    return Response.json(spec, { headers });
+  };
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function createSwaggerUIHtml(title: string, specUrl: string): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>${escapeHtml(title)}</title>
+	<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" integrity="sha384-+yyzNgM3K92sROwsXxYCxaiLWxWJ0G+v/9A+qIZ2rgefKgkdcmJI+L601cqPD/Ut" crossorigin="anonymous" />
+	<style>
+		body { margin: 0; padding: 0; }
+		.topbar { display: none; }
+	</style>
+</head>
+<body>
+	<div id="swagger-ui"></div>
+	<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" integrity="sha384-qn5tagrAjZi8cSmvZ+k3zk4+eDEEUcP9myuR2J6V+/H6rne++v6ChO7EeHAEzqxQ" crossorigin="anonymous"></script>
+	<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js" integrity="sha384-SiLF+uYBf9lVQW98s/XUYP14enXJN31bn0zu3BS1WFqr5hvnMF+w132WkE/v0uJw" crossorigin="anonymous"></script>
+	<script>
+		window.onload = function() {
+			window.ui = SwaggerUIBundle({
+				url: ${JSON.stringify(specUrl)},
+				dom_id: '#swagger-ui',
+				deepLinking: true,
+				presets: [
+					SwaggerUIBundle.presets.apis,
+					SwaggerUIStandalonePreset
+				],
+				plugins: [
+					SwaggerUIBundle.plugins.DownloadUrl
+				],
+				layout: "StandaloneLayout",
+				defaultModelsExpandDepth: 1,
+				defaultModelExpandDepth: 1,
+				docExpansion: "list",
+				filter: true,
+				showRequestHeaders: true,
+				tryItOutEnabled: true
+			});
+		};
+	</script>
+</body>
+</html>`;
+}
+
+/**
+ * Create a Next.js route handler that serves Swagger UI for an OpenAPI route.
+ */
+export function createSwaggerUIHandler(
+  options: CreateSwaggerUIHandlerOptions = {},
+): (req: Request) => Response {
+  return (req: Request) => {
+    const specUrl =
+      typeof options.specUrl === "function"
+        ? options.specUrl(req)
+        : (options.specUrl ?? "/api/openapi");
+    const headers = new Headers(resolveHeaders(options.headers, req));
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "text/html; charset=utf-8");
+    }
+
+    return new Response(
+      createSwaggerUIHtml(options.title ?? "API Documentation", specUrl),
+      { headers },
+    );
+  };
+}
+
+/**
+ * Create Next.js route handlers that serve public storage objects.
+ *
+ * Missing objects, private objects, invalid keys, and paths outside `basePath`
+ * all return 404 so storage routes do not leak object existence.
+ */
+export function createStorageRoute(
+  storage: StoragePort,
+  options: CreateStorageRouteOptions = {},
+): {
+  GET: (req: Request) => Promise<Response>;
+  HEAD: (req: Request) => Promise<Response>;
+} {
+  const basePath = normalizeStorageBasePath(options.basePath);
+
+  return {
+    GET: (req) => storageResponse(storage, req, basePath, options, true),
+    HEAD: (req) => storageResponse(storage, req, basePath, options, false),
+  };
+}
+
+export async function createNextServer<
+  Ctx,
+  Ports extends AnyPorts = AnyPorts,
+  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>>> {
+  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),
+    route: (contract) => ({
+      handle: (fn) => wrap(runtime.route(contract).handle(fn)),
+    }),
+    createContextFromNext: async () => {
+      const { cookies, headers } = await import("next/headers");
+      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.
+      // 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 };
+      } = {
+        method: "GET",
+        // Use a clearly non-real URL to avoid implying a real network endpoint.
+        url: "http://core/server-component.invalid",
+        headers: new Headers(h),
+        // Server Components don't have a request body, so these return empty values
+        json: async () => ({}),
+        text: async () => "",
+        arrayBuffer: async () => new ArrayBuffer(0),
+        blob: async () => new Blob(),
+        formData: async () => new FormData(),
+        clone: () => req,
+        cookies: {
+          get: (key: string) => c.get(key)?.value,
+        },
+      };
+
+      return options.createContext({
+        req,
+        ports: runtime.ports,
+      });
+    },
+    contracts: runtime.contracts,
+    stop: () => runtime.stop(),
+    ports: runtime.ports,
+  };
+}