oaspect 0.1.0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "oaspect",
+  "version": "0.1.0",
+  "description": "Interactive API reference for OpenAPI documents: one script tag, a web component, a CLI and server helpers.",
+  "license": "MIT",
+  "homepage": "https://oaspect.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oaspect/oaspect.git",
+    "directory": "packages/oaspect"
+  },
+  "bugs": "https://github.com/oaspect/oaspect/issues",
+  "type": "module",
+  "main": "./dist/oaspect.js",
+  "browser": "./dist/oaspect.js",
+  "unpkg": "./dist/oaspect.js",
+  "jsdelivr": "./dist/oaspect.js",
+  "bin": {
+    "oaspect": "./bin/oaspect.mjs"
+  },
+  "exports": {
+    ".": "./dist/oaspect.js",
+    "./server": {
+      "types": "./src/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src/html.js",
+    "src/serve.js",
+    "src/server.js",
+    "src/spec.js",
+    "src/server.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "openapi",
+    "swagger",
+    "api-documentation",
+    "api-reference",
+    "cli",
+    "web-component"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@oaspect/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.12",
+    "jsdom": "^26.1.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "vitest": "^3.2.7",
+    "@oaspect/react": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "vitest run",
+    "typecheck": "true",
+    "lint": "true"
+  }
+}

package/src/html.js

@@ -0,0 +1,73 @@
+// HTML page around the standalone bundle, shared by `oaspect build` (inline
+// script and spec: one self-contained file) and `oaspect serve`.
+
+const escapeHtml = (value) =>
+  String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
+
+// Default page icon: braces on a rounded square, inline so the file stays self-contained.
+const DEFAULT_ICON =
+  "data:image/svg+xml," +
+  encodeURIComponent(
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#16a34a"/><path d="M12 9c-2 0-3 1-3 3v2c0 1-1 2-2 2 1 0 2 1 2 2v2c0 2 1 3 3 3M20 9c2 0 3 1 3 3v2c0 1 1 2 2 2-1 0-2 1-2 2v2c0 2-1 3-3 3" fill="none" stroke="#fff" stroke-width="2.2" stroke-linecap="round"/></svg>',
+  );
+
+// JSON inside <script>: "<" escaped so "</script>" in the data cannot close it.
+const scriptJson = (value) =>
+  JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+
+// Sets <html data-theme> from the reader's stored or system preference before
+// the first paint, so prerendered markup does not flash the wrong theme.
+const themeScript = (storagePrefix) => `(() => {
+  let theme;
+  try { theme = localStorage.getItem(${scriptJson(`${storagePrefix}:theme`)}); } catch {}
+  if (theme !== "light" && theme !== "dark") theme = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  document.documentElement.dataset.theme = theme;
+})();`;
+
+/**
+ * @param {{
+ *   title?: string,
+ *   config?: object,            // Oaspect.init() config (specUrl, locale…)
+ *   spec?: object,              // inlined OpenAPI document
+ *   script?: { src?: string, inline?: string },
+ *   icon?: string,              // favicon URL (default: built-in icon)
+ *   markup?: string,            // prerendered viewer HTML (hydrated instead of rendered)
+ *   css?: string,               // stylesheet to inline, needed with markup
+ * }} options
+ */
+export function renderHtml({ title = "API Reference", config = {}, spec, script = {}, icon = DEFAULT_ICON, markup, css }) {
+  const scriptTag = script.inline
+    ? `<script>${script.inline.replace(/<\/script/gi, "<\\/script")}</script>`
+    : `<script src="${escapeHtml(script.src ?? "oaspect.js")}"></script>`;
+  const specTag = spec ? `\n    <script type="application/json" id="oaspect-spec">${scriptJson(spec)}</script>` : "";
+  const configExpression = spec
+    ? `Object.assign(${scriptJson(config)}, { spec: JSON.parse(document.getElementById("oaspect-spec").textContent) })`
+    : scriptJson(config);
+  const head = [
+    css ? `<style id="oaspect-styles">${css.replace(/<\/style/gi, "<\\/style")}</style>` : "",
+    config.theme ? "" : `<script>${themeScript(config.storagePrefix ?? "oaspect")}</script>`,
+  ]
+    .filter(Boolean)
+    .join("\n    ");
+
+  return `<!doctype html>
+<html lang="${escapeHtml(config.locale ?? config.defaultLocale ?? "en")}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="generator" content="oaspect" />
+    <title>${escapeHtml(title)}</title>
+    <link rel="icon" href="${escapeHtml(icon)}" />
+    <style>body { margin: 0 }</style>${head ? `\n    ${head}` : ""}
+  </head>
+  <body>
+    <div id="oaspect">${markup ?? ""}</div>${specTag}
+    ${scriptTag}
+    <script>Oaspect.${markup ? "hydrate" : "init"}("#oaspect", ${configExpression});</script>
+  </body>
+</html>
+`;
+}

package/src/serve.js

@@ -0,0 +1,83 @@
+// `oaspect serve`: local preview server. The spec is re-read on every request,
+// so editing the file and reloading the page shows the change.
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { renderHtml } from "./html.js";
+import { createProxyHandler } from "./server.js";
+import { loadSpec } from "./spec.js";
+
+const PROXY_PATH = "/__oaspect/proxy";
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1"]);
+
+function toRequest(req, origin) {
+  const hasBody = req.method !== "GET" && req.method !== "HEAD";
+  return new Request(new URL(req.url, origin), {
+    method: req.method,
+    headers: Object.entries(req.headers).flatMap(([key, value]) => (Array.isArray(value) ? value.map((item) => [key, item]) : [[key, value]])),
+    body: hasBody ? Readable.toWeb(req) : undefined,
+    duplex: hasBody ? "half" : undefined,
+  });
+}
+
+async function send(res, response) {
+  res.writeHead(response.status, Object.fromEntries(response.headers));
+  res.end(Buffer.from(await response.arrayBuffer()));
+}
+
+/**
+ * @param {{ source: string, port?: number, host?: string, proxy?: boolean | string[], bundlePath: string, config?: object }} options
+ */
+export async function serve({ source, port = 8080, host = "127.0.0.1", proxy = true, bundlePath, config = {} }) {
+  await loadSpec(source); // fail fast on a broken document
+  // An open relay on a non-loopback address would let the network reach
+  // anything this machine can see; require an explicit host list there.
+  if (proxy === true && !LOOPBACK.has(host)) {
+    throw new Error(`--host ${host} exposes the proxy to the network; pass --proxy-hosts api.example.com or --no-proxy.`);
+  }
+  const proxyHandler = proxy ? createProxyHandler({ allowedHosts: proxy === true ? "*" : proxy }) : null;
+
+  const html = () =>
+    renderHtml({
+      title: config.title ?? "API Reference",
+      config: { ...config, specUrl: "/openapi.json", proxyUrl: proxyHandler ? PROXY_PATH : null },
+      script: { src: "/oaspect.js" },
+    });
+
+  const server = createServer(async (req, res) => {
+    const origin = `http://${req.headers.host ?? `${host}:${port}`}`;
+    const { pathname } = new URL(req.url, origin);
+    try {
+      if (req.method === "GET" && (pathname === "/" || pathname === "/index.html")) {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+        res.end(html());
+      } else if (req.method === "GET" && pathname === "/openapi.json") {
+        const spec = await loadSpec(source);
+        res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+        res.end(JSON.stringify(spec));
+      } else if (req.method === "GET" && pathname === "/oaspect.js") {
+        res.writeHead(200, { "Content-Type": "text/javascript; charset=utf-8" });
+        res.end(await readFile(bundlePath));
+      } else if (pathname === "/favicon.ico") {
+        // The page declares an inline icon; answer browsers that still ask.
+        res.writeHead(204);
+        res.end();
+      } else if (proxyHandler && pathname === PROXY_PATH) {
+        await send(res, await proxyHandler(toRequest(req, origin)));
+      } else {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not found");
+      }
+    } catch (error) {
+      res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(String(error.message ?? error));
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+  const address = server.address();
+  return { server, url: `http://${address.family === "IPv6" ? `[${address.address}]` : address.address}:${address.port}` };
+}

package/src/server.d.ts

@@ -0,0 +1,29 @@
+export interface ProxyHandlerOptions {
+  /** Hosts ("api.example.com", "localhost:8080") the proxy may call, or "*" for any. */
+  allowedHosts: string[] | "*";
+  /** Upstream timeout. Default 30 s. */
+  timeoutMs?: number;
+  /** Adjusts the target URL before fetching (e.g. map localhost inside Docker). */
+  rewriteHost?: (url: URL) => URL;
+}
+
+/** POST handler relaying the viewer's "Try" requests; mount it at `proxyUrl`. */
+export declare function createProxyHandler(options: ProxyHandlerOptions): (request: Request) => Promise<Response>;
+
+/** Builds FormData from the viewer's multipart parts ({ name, value } or { name, file: { name, type, data } }). */
+export declare function formDataFromParts(parts: Array<{ name: string; value?: string; file?: { name?: string; type?: string; data: string } }>): FormData;
+
+export interface SpecHandlerOptions {
+  /** Live document URL, fetched server-side and cached. */
+  url?: string;
+  /** Document text (or a function returning it) used when `url` fails or is not set. */
+  fallback?: string | (() => string | Promise<string>);
+  /** Cache lifetime for the live document. Default 60. */
+  cacheSeconds?: number;
+  /** Upstream timeout. Default 10 s. */
+  timeoutMs?: number;
+  rewriteHost?: (url: URL) => URL;
+}
+
+/** GET handler serving the spec; sets x-oaspect-spec-source to remote, fallback or static. */
+export declare function createSpecHandler(options: SpecHandlerOptions): (request?: Request) => Promise<Response>;

package/src/server.js

@@ -0,0 +1,168 @@
+// Server helpers built on Web-standard Request/Response, so the same code
+// runs on Node, Next.js route handlers, Hono, Bun, Deno or Cloudflare Workers.
+
+const DROPPED_HEADERS = new Set([
+  "host",
+  "connection",
+  "content-length",
+  "transfer-encoding",
+  "keep-alive",
+  "upgrade",
+  "accept-encoding",
+]);
+
+const json = (body, status = 200) => Response.json(body, { status });
+
+function decodeBase64(data) {
+  const binary = atob(String(data ?? ""));
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+// multipart parts from the viewer: { name, value } or
+// { name, file: { name, type, data: base64 } }.
+export function formDataFromParts(parts) {
+  const data = new FormData();
+  for (const part of parts) {
+    if (part?.file) {
+      const blob = new Blob([decodeBase64(part.file.data)], { type: part.file.type || "application/octet-stream" });
+      data.append(String(part.name), blob, String(part.file.name || "file"));
+    } else {
+      data.append(String(part?.name), String(part?.value ?? ""));
+    }
+  }
+  return data;
+}
+
+function normalizeHosts(allowedHosts) {
+  if (allowedHosts === "*") return "*";
+  return (allowedHosts ?? []).map((host) => String(host).trim().toLowerCase()).filter(Boolean);
+}
+
+/**
+ * Creates a handler that relays the viewer's "Try" requests server-side, so
+ * APIs without CORS headers can be called. Mount it at the URL you pass to
+ * the viewer as `proxyUrl` (POST).
+ *
+ * Restrict `allowedHosts` to your API: an open relay lets anyone reach
+ * addresses your server can see (internal services, cloud metadata).
+ *
+ * @param {{
+ *   allowedHosts: string[] | "*",
+ *   timeoutMs?: number,
+ *   rewriteHost?: (url: URL) => URL,
+ * }} options
+ * @returns {(request: Request) => Promise<Response>}
+ */
+export function createProxyHandler({ allowedHosts, timeoutMs = 30_000, rewriteHost } = {}) {
+  const hosts = normalizeHosts(allowedHosts);
+  if (hosts !== "*" && hosts.length === 0) {
+    throw new Error('createProxyHandler: allowedHosts must list at least one host (or be "*")');
+  }
+
+  const allowed = (target) =>
+    hosts === "*" || hosts.includes(target.host.toLowerCase()) || hosts.includes(target.hostname.toLowerCase());
+
+  return async function proxy(request) {
+    if (request.method !== "POST") return json({ error: "Method not allowed." }, 405);
+
+    let payload;
+    try {
+      payload = await request.json();
+    } catch {
+      return json({ error: "Invalid request body." }, 400);
+    }
+
+    const { method = "GET", url, headers = {}, body, form } = payload ?? {};
+    let target;
+    try {
+      target = new URL(url);
+    } catch {
+      return json({ error: `Invalid URL: ${url}` }, 400);
+    }
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+      return json({ error: "Only http and https are supported." }, 400);
+    }
+    if (!allowed(target)) return json({ error: `${target.host} is not an allowed host.` }, 403);
+
+    if (rewriteHost) target = rewriteHost(new URL(target));
+
+    const upperMethod = String(method).toUpperCase();
+    const multipart = Array.isArray(form);
+    // For multipart, fetch sets Content-Type itself (with the boundary).
+    const forwarded = Object.fromEntries(
+      Object.entries(headers).filter(([key]) => !DROPPED_HEADERS.has(key.toLowerCase()) && !(multipart && key.toLowerCase() === "content-type")),
+    );
+    const started = Date.now();
+
+    try {
+      const response = await fetch(target, {
+        method: upperMethod,
+        headers: forwarded,
+        body: upperMethod === "GET" || upperMethod === "HEAD" ? undefined : multipart ? formDataFromParts(form) : body,
+        redirect: "manual",
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      const text = await response.text();
+      return json({
+        status: response.status,
+        statusText: response.statusText,
+        headers: [...response.headers.entries()],
+        body: text,
+        duration: Date.now() - started,
+      });
+    } catch (error) {
+      const code = error.cause?.code ? ` (${error.cause.code})` : "";
+      return json({ error: `Could not reach ${target.origin}: ${error.message}${code}` }, 502);
+    }
+  };
+}
+
+/**
+ * Creates a GET handler serving the OpenAPI document for the viewer's
+ * `specUrl`. With `url`, the live document is fetched server-side (no CORS
+ * needed on the API) and cached for `cacheSeconds`; when it cannot be
+ * reached, `fallback` is served and the response carries
+ * `x-oaspect-spec-source: fallback` so the viewer shows an out-of-date notice.
+ *
+ * @param {{
+ *   url?: string,
+ *   fallback?: string | (() => string | Promise<string>),
+ *   cacheSeconds?: number,
+ *   timeoutMs?: number,
+ *   rewriteHost?: (url: URL) => URL,
+ * }} options
+ * @returns {(request?: Request) => Promise<Response>}
+ */
+export function createSpecHandler({ url, fallback, cacheSeconds = 60, timeoutMs = 10_000, rewriteHost } = {}) {
+  if (!url && fallback === undefined) throw new Error("createSpecHandler: pass url, fallback or both");
+  let cached = null;
+
+  const respond = (text, source, contentType) =>
+    new Response(text, {
+      headers: {
+        "Content-Type": contentType ?? (text.trimStart().startsWith("{") ? "application/json; charset=utf-8" : "application/yaml; charset=utf-8"),
+        "Cache-Control": `public, max-age=${cacheSeconds}`,
+        "x-oaspect-spec-source": source,
+      },
+    });
+
+  return async function spec() {
+    if (url) {
+      if (cached && Date.now() - cached.at < cacheSeconds * 1000) return respond(cached.text, "remote", cached.type);
+      try {
+        const target = rewriteHost ? rewriteHost(new URL(url)) : url;
+        const response = await fetch(target, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const text = await response.text();
+        cached = { text, type: response.headers.get("content-type") ?? undefined, at: Date.now() };
+        return respond(text, "remote", cached.type);
+      } catch (error) {
+        if (fallback === undefined) return json({ error: `Could not load ${url}: ${error.message}` }, 502);
+      }
+    }
+    const text = typeof fallback === "function" ? await fallback() : fallback;
+    return respond(text, url ? "fallback" : "static");
+  };
+}

package/src/spec.js

@@ -0,0 +1,35 @@
+// Loads an OpenAPI document (JSON or YAML; Swagger 2.0 is converted) from a
+// file path or URL for the CLI.
+import { loadSpec as loadDocument } from "@oaspect/core";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export function isUrl(source) {
+  return /^https?:\/\//i.test(source);
+}
+
+export async function readSpecText(source) {
+  if (isUrl(source)) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`${source}: HTTP ${response.status}`);
+    return response.text();
+  }
+  return readFile(resolve(source), "utf8");
+}
+
+// External $refs: file: URLs from disk, http(s) URLs over the network.
+async function readUrl(url) {
+  if (url.startsWith("file:")) return readFile(fileURLToPath(url), "utf8");
+  return readSpecText(url);
+}
+
+export async function loadSpec(source) {
+  const text = await readSpecText(source);
+  const baseUrl = isUrl(source) ? source : pathToFileURL(resolve(source)).href;
+  try {
+    return await loadDocument(text, { baseUrl, read: readUrl });
+  } catch (error) {
+    throw new Error(`${source}: ${error.message}`);
+  }
+}