@substrat-run/vertical-host 0.156.0 → 0.159.0

package/README.md

@@ -45,6 +45,14 @@ mountPlatformSurface(app, {
 export default app;
 ```
 
+## Automatic API reference
+
+`mountOperations` also serves `/api/docs` and its self-hosted renderer. Keep serving
+`/openapi.json` from your operation declarations; the page uses the app's current
+session and makes try-it requests on the same origin. No app asset build changes
+are required. Register operations before a catch-all route. Set `docs: false` when
+supplying your own reference, or register that reference before mounting operations.
+
 ## What it owns vs. what you supply
 
 - **Generic routes** (`export`, `restore`, `bookmarks`, `rewind`, `snapshot`,

package/dist/api-docs.d.ts

@@ -0,0 +1,5 @@
+/** The reference is platform plumbing; the document and its auth stay with the app. */
+import type { Hono } from 'hono';
+/** Repeated mounts share one reference; an app's existing reference takes precedence. */
+export declare function mountApiDocs(app: Hono<any, any, any>): void;
+//# sourceMappingURL=api-docs.d.ts.map

package/dist/api-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-docs.d.ts","sourceRoot":"","sources":["../src/api-docs.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAwCjC,yFAAyF;AAEzF,wBAAgB,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAU3D"}

package/dist/api-docs.js

@@ -0,0 +1,51 @@
+import { servedPathOf } from './mcp-guard.js';
+import { DOCS_RENDERER } from './docs-renderer.generated.js';
+const HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>API reference</title>
+<style>body{margin:0}#status{font:16px system-ui;padding:24px}</style>
+</head>
+<body>
+<div id="status" role="status">Loading API reference…</div><div id="app"></div>
+<script src="./docs/renderer.js"></script>
+<script>
+(async () => {
+  const status = document.getElementById('status');
+  try {
+    const response = await fetch('/openapi.json', { credentials: 'same-origin', headers: { Accept: 'application/json' } });
+    if (response.status === 401) {
+      status.textContent = 'Sign in to the app, then reload this reference. ';
+      const link = document.createElement('a'); link.href = '/'; link.textContent = 'Open app'; status.append(link);
+      return;
+    }
+    if (response.status === 403) throw new Error('Your account cannot access this API specification.');
+    if (!response.ok) throw new Error('The app has not made its API specification available (' + response.status + ').');
+    const content = await response.json().catch(() => {
+      throw new Error('The app did not return an OpenAPI specification.');
+    });
+    if (!content || !content.openapi || !content.paths) throw new Error('The app did not return an OpenAPI specification.');
+    if (!window.Scalar) throw new Error('The API reference renderer could not load. Reload to try again.');
+    Scalar.createApiReference('#app', { content, hideClientButton: true });
+    status.remove();
+  } catch (error) {
+    status.textContent = error instanceof Error ? error.message : 'Unable to load the API specification.';
+  }
+})();
+</script>
+</body></html>`;
+/** Repeated mounts share one reference; an app's existing reference takes precedence. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function mountApiDocs(app) {
+    if (!app.routes.some((route) => route.method === 'GET' && route.path === servedPathOf(app, '/api/docs'))) {
+        app.get('/api/docs', (c) => c.html(HTML));
+    }
+    if (!app.routes.some((route) => route.method === 'GET' && route.path === servedPathOf(app, '/api/docs/renderer.js'))) {
+        app.get('/api/docs/renderer.js', (c) => c.body(DOCS_RENDERER, 200, {
+            'Content-Type': 'text/javascript; charset=utf-8',
+            'X-Content-Type-Options': 'nosniff',
+        }));
+    }
+}
+//# sourceMappingURL=api-docs.js.map

package/dist/api-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-docs.js","sourceRoot":"","sources":["../src/api-docs.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAkCE,CAAC;AAEhB,yFAAyF;AACzF,8DAA8D;AAC9D,MAAM,UAAU,YAAY,CAAC,GAAwB;IACnD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC;QACzG,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC;QACrH,GAAG,CAAC,GAAG,CAAC,uBAAuB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,EAAE;YACjE,cAAc,EAAE,gCAAgC;YAChD,wBAAwB,EAAE,SAAS;SACpC,CAAC,CAAC,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/docs-renderer.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const DOCS_RENDERER: string;
+//# sourceMappingURL=docs-renderer.generated.d.ts.map

package/dist/docs-renderer.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-renderer.generated.d.ts","sourceRoot":"","sources":["../src/docs-renderer.generated.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,EAAE,MAA68+3I,CAAC"}