@norskvideo/ctl-sdk 0.1.27 → 0.1.29

package/index.d.ts

@@ -13,6 +13,7 @@ export * from "./manifest-fetch.js";
 export * from "./manifest-router.js";
 export * from "./openapi-router.js";
 export * from "./product-health-monitor.js";
+export * from "./product-hub.js";
 export * from "./product-reach.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";

package/index.js

@@ -15,6 +15,7 @@ export * from "./manifest-fetch.js";
 export * from "./manifest-router.js";
 export * from "./openapi-router.js";
 export * from "./product-health-monitor.js";
+export * from "./product-hub.js";
 export * from "./product-reach.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "type": "module",
   "exports": {
     ".": {

package/product-hub.d.ts

@@ -0,0 +1,22 @@
+import type { Express } from "express";
+import type { Manifest } from "./manifest-schema.js";
+/** What a product wants said about itself above the links. One or two
+ *  sentences: the hub is an orientation page, not a marketing page. */
+export interface ProductHubOptions {
+    manifest: Manifest;
+    /** The manifest sidebar route this hub answers, e.g. "/playout". */
+    route: string;
+    description?: string;
+}
+export declare function renderProductHub(opts: ProductHubOptions): string;
+/**
+ * Mount the product's hub at the manifest sidebar route it declares.
+ *
+ * ctl renders every `ui.sidebarEntries` entry as a link under
+ * `/products/<name>/<route>`; before this, four products declared a branded
+ * entry whose backend served nothing, so the button 404'd (fleet review 04c).
+ * The page is built from the manifest the product already publishes, so it
+ * cannot drift from what the product actually offers. The trailing-slash form
+ * redirects to the bare route: relative links then resolve one way only.
+ */
+export declare function serveProductHub(app: Express, opts: ProductHubOptions): void;

package/product-hub.js

@@ -0,0 +1,114 @@
+function esc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** The hub is reached through the daemon's product proxy under
+ *  /products/<name>/, and the product cannot see that prefix — the proxy
+ *  forwards req.url unchanged. A root-absolute href would therefore escape the
+ *  prefix and land on the runner's own SPA, so every link is relative to the
+ *  product root, which is the hub's parent directory either way. */
+function rel(path) {
+    return path.replace(/^\/+/, "");
+}
+function linkCard(label, href, note) {
+    const sub = note ? `<span class="note">${esc(note)}</span>` : "";
+    return `<a class="card" href="${esc(rel(href))}"><span class="label">${esc(label)}</span>${sub}</a>`;
+}
+export function renderProductHub(opts) {
+    const { manifest: m, route, description } = opts;
+    const ui = m.ui ?? { sidebarEntries: [], dashboardWidgets: [], productTemplateActions: [] };
+    const cards = [];
+    if (ui.configScreenUrl) {
+        cards.push(linkCard("Configure", ui.configScreenUrl, "Build a product template"));
+    }
+    for (const entry of ui.sidebarEntries ?? []) {
+        if (entry.route === route)
+            continue;
+        cards.push(linkCard(entry.label, entry.route));
+    }
+    const templates = m.defaultProductTemplates ?? [];
+    const templateList = templates.length > 0
+        ? `<h2>Ready to launch</h2>
+  <p class="lead">Product templates this product registers with norsk-ctl. Launch one from the runner; there is nothing to configure first.</p>
+  <ul class="templates">${templates.map((t) => `<li>${esc(t.name)}</li>`).join("")}</ul>`
+        : "";
+    const api = [linkCard("OpenAPI", m.api.openapiFragmentPath, "This product's API fragment")];
+    if (m.api.productMcpPath)
+        api.push(linkCard("MCP", m.api.productMcpPath, "Always-on control-plane endpoint"));
+    api.push(linkCard("Health", m.api.healthCheckPath ?? "/healthz", "What the runner polls"));
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${esc(m.name)}</title>
+<style>
+  :root { color-scheme: light dark; --bg: #fbfbfa; --fg: #18181b; --muted: #71717a; --line: #e4e4e7; --card: #ffffff; }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg: #18181b; --fg: #fafafa; --muted: #a1a1aa; --line: #3f3f46; --card: #27272a; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; padding: 2.5rem 1.5rem; background: var(--bg); color: var(--fg);
+         font: 14px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+  main { max-width: 46rem; margin: 0 auto; }
+  h1 { font-size: 1.5rem; margin: 0 0 .25rem; letter-spacing: -0.01em; }
+  h2 { font-size: .8rem; text-transform: uppercase; letter-spacing: .08em; color: var(--muted);
+       margin: 2.25rem 0 .75rem; font-weight: 600; }
+  .version { font-size: .75rem; color: var(--muted); font-variant-numeric: tabular-nums; }
+  .lead { color: var(--muted); margin: .5rem 0 0; max-width: 34rem; }
+  .cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(13rem, 1fr)); gap: .75rem; }
+  .card { display: flex; flex-direction: column; gap: .15rem; padding: .8rem .9rem; text-decoration: none;
+          background: var(--card); border: 1px solid var(--line); border-radius: 8px; color: inherit; }
+  .card:hover { border-color: var(--muted); }
+  .label { font-weight: 600; }
+  .note { font-size: .75rem; color: var(--muted); }
+  ul.templates { list-style: none; padding: 0; margin: 0; display: flex; flex-wrap: wrap; gap: .4rem; }
+  ul.templates li { border: 1px solid var(--line); border-radius: 999px; padding: .2rem .7rem;
+                    font-size: .8rem; background: var(--card); font-variant-numeric: tabular-nums; }
+  footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid var(--line);
+           font-size: .75rem; color: var(--muted); }
+</style>
+</head>
+<body>
+<main>
+  <h1>${esc(m.name)}</h1>
+  <div class="version">version ${esc(m.version)}</div>
+  ${description ? `<p class="lead">${esc(description)}</p>` : ""}
+
+  <h2>Start here</h2>
+  <div class="cards">${cards.join("")}</div>
+
+  ${templateList}
+
+  <h2>For integrators</h2>
+  <div class="cards">${api.join("")}</div>
+
+  <footer>Served by this product's own control plane. norsk-ctl links here from the product page.</footer>
+</main>
+</body>
+</html>
+`;
+}
+/**
+ * Mount the product's hub at the manifest sidebar route it declares.
+ *
+ * ctl renders every `ui.sidebarEntries` entry as a link under
+ * `/products/<name>/<route>`; before this, four products declared a branded
+ * entry whose backend served nothing, so the button 404'd (fleet review 04c).
+ * The page is built from the manifest the product already publishes, so it
+ * cannot drift from what the product actually offers. The trailing-slash form
+ * redirects to the bare route: relative links then resolve one way only.
+ */
+export function serveProductHub(app, opts) {
+    const route = `/${rel(opts.route)}`;
+    const html = renderProductHub(opts);
+    // Express's non-strict routing makes `/route` and `/route/` the same match,
+    // so the two cannot be separate handlers (the bare form would hit the
+    // redirect and loop). One handler, told apart by what the client asked for.
+    app.get(route, (req, res) => {
+        if (req.originalUrl.split("?")[0]?.endsWith("/")) {
+            res.redirect(301, route);
+            return;
+        }
+        res.type("html").send(html);
+    });
+}