@norskvideo/ctl-sdk 0.1.2 → 0.1.4

package/browser.d.ts

@@ -1,3 +1,4 @@
+export * from "./iframe-protocol.js";
 export * from "./manifest-schema.js";
 export * from "./parsing.js";
 export * from "./product-error.js";

package/browser.js

@@ -1,6 +1,7 @@
 // Browser-safe surface: types, schemas, parsers, validators.
 // Anything with Node-only deps (fs, child_process, express) lives in the
 // default entry only.
+export * from "./iframe-protocol.js";
 export * from "./manifest-schema.js";
 export * from "./parsing.js";
 export * from "./product-error.js";

package/components/ProductIframe.d.ts

@@ -1,10 +1,5 @@
-export type SubmitResult = {
-    ok: true;
-    formValues: Record<string, unknown>;
-} | {
-    ok: false;
-    error?: string;
-};
+import { type SubmitResult } from "../iframe-protocol.js";
+export type { SubmitResult };
 export type ProductIframeHandle = {
     submit: () => Promise<SubmitResult>;
 };

package/components/ProductIframe.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from "react";
-const PROTOCOL_VERSION = 1;
+import { IFRAME_PROTOCOL_VERSION, parseChildMessage, } from "../iframe-protocol.js";
 const SUBMIT_TIMEOUT_MS = 30_000;
 function resolveSrc(productName, configScreenUrl) {
     const path = configScreenUrl.startsWith("/") ? configScreenUrl : `/${configScreenUrl}`;
@@ -27,13 +27,14 @@ export const ProductIframe = forwardRef(function ProductIframe({ productName, co
         const onMessage = (event) => {
             if (event.source !== iframeRef.current?.contentWindow)
                 return;
-            const data = event.data;
-            if (!data || typeof data !== "object")
+            const msg = parseChildMessage(event.data);
+            if (!msg)
                 return;
-            if (data.v !== PROTOCOL_VERSION)
-                return;
-            const payload = data.payload ?? {};
-            switch (data.type) {
+            // Payload fields stay runtime-checked despite the typed union: the wire
+            // is a product we don't control, and legacy shapes (option-a
+            // submit-result) predate it.
+            const payload = (msg.payload ?? {});
+            switch (msg.type) {
                 case "ready":
                 case "resize":
                     if (typeof payload.height === "number" && payload.height > 0)
@@ -88,16 +89,19 @@ export const ProductIframe = forwardRef(function ProductIframe({ productName, co
     const launchContextRef = useRef(launchContext);
     launchContextRef.current = launchContext;
     const sendInit = useCallback(() => {
-        iframeRef.current?.contentWindow?.postMessage({
-            v: PROTOCOL_VERSION,
+        const init = {
+            v: IFRAME_PROTOCOL_VERSION,
             type: "init",
             payload: {
                 instanceContext: { basename },
                 theme: "dark",
                 locale: "en",
+                // The prop is a verbatim-forwarded record by design; the protocol
+                // types the keys the products read.
                 ...(launchContextRef.current ? { launchContext: launchContextRef.current } : {}),
             },
-        }, "*");
+        };
+        iframeRef.current?.contentWindow?.postMessage(init, "*");
     }, [basename]);
     useImperativeHandle(ref, () => ({
         submit: () => new Promise((resolve) => {
@@ -106,7 +110,8 @@ export const ProductIframe = forwardRef(function ProductIframe({ productName, co
                 return;
             }
             submitResolverRef.current = resolve;
-            iframeRef.current.contentWindow.postMessage({ v: PROTOCOL_VERSION, type: "submit", payload: {} }, "*");
+            const submit = { v: IFRAME_PROTOCOL_VERSION, type: "submit", payload: {} };
+            iframeRef.current.contentWindow.postMessage(submit, "*");
             setTimeout(() => {
                 if (submitResolverRef.current === resolve) {
                     submitResolverRef.current = null;

package/http-proxy.d.ts

@@ -0,0 +1,34 @@
+import type { Request, RequestHandler, Response } from "express";
+export declare const HOP_BY_HOP_HEADERS: ReadonlySet<string>;
+/** Forwardable copy of an incoming request's headers: hop-by-hop, host and
+ *  content-length stripped (fetch derives the latter two from the target URL
+ *  and the buffered body). */
+export declare function buildForwardHeaders(req: Request): Headers;
+/** Buffer the request body (small JSON control messages — buffering is robust
+ *  across the fetch duplex-body edge cases). GET/HEAD and empty bodies yield
+ *  undefined. */
+export declare function readRequestBody(req: Request): Promise<Uint8Array | undefined>;
+export type ForwardResponseOptions = {
+    /** Transform response header values before relaying (e.g. re-prefix a
+     *  root-absolute redirect Location). Return the value to send. */
+    rewriteHeader?: (key: string, value: string) => string;
+    /** Observe mid-stream body failures (the response is ended regardless). */
+    onStreamError?: (err: unknown) => void;
+};
+/** Relay an upstream fetch Response: status, headers (hop-by-hop plus
+ *  content-length/content-encoding stripped — fetch already decompressed the
+ *  body), then the streamed body. */
+export declare function forwardUpstreamResponse(res: Response, upstream: globalThis.Response, opts?: ForwardResponseOptions): Promise<void>;
+export type ProxyHttpOptions = ForwardResponseOptions & {
+    /** Abort the upstream fetch (headers AND body) after this long. Defaults to
+     *  30s; pass 0 for no timeout (long-lived streams). */
+    timeoutMs?: number;
+};
+/** Proxy one HTTP request to `targetUrl`, streaming the response body back.
+ *  Never throws into express: an unreachable/booting upstream surfaces as a
+ *  502 the caller retries. */
+export declare function proxyHttp(req: Request, res: Response, targetUrl: string, opts?: ProxyHttpOptions): Promise<void>;
+/** Express handler proxying whatever path it is mounted on to
+ *  `resolveBase(req) + req.originalUrl` (so /live/api/<id>/x reaches
+ *  <studio>/live/api/<id>/x). */
+export declare function makeHttpProxy(resolveBase: (req: Request) => string, opts?: ProxyHttpOptions): RequestHandler;

package/http-proxy.js

@@ -0,0 +1,131 @@
+// Dependency-free fetch-based reverse-proxy core, shared by the runner's
+// product proxy (proxy-middleware.ts) and by instance-side product backends
+// fronting a launched Studio (lifted from funke's live-proxy.ts).
+//
+// Zero new dependency is deliberate: `bun build --target=bun` can mis-bundle a
+// fat CJS proxy dep, only caught in the image. A hand-rolled proxy bundles
+// trivially. WebSocket upgrades are OUT of scope: bun's node:http "upgrade"
+// socket is not writable back to the client, so an in-process WS relay cannot
+// forward the 101 — bridge upstream WS feeds by consuming them as a client and
+// re-emitting same-origin SSE instead (see sse.ts).
+import { Readable } from "node:stream";
+// RFC 7230 §6.1 hop-by-hop headers, which must not travel end-to-end. Includes
+// both "trailer" (the actual header) and "trailers" (the TE value, present in
+// one of the copies this replaces) so neither survives in either direction.
+export const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "trailers",
+    "transfer-encoding",
+    "upgrade",
+]);
+// fetch decompresses upstream bodies and sets host/content-length itself, so
+// the originals must not be relayed alongside the transformed message.
+const REQUEST_ONLY_STRIP = new Set(["host", "content-length"]);
+const RESPONSE_ONLY_STRIP = new Set(["content-length", "content-encoding"]);
+/** Forwardable copy of an incoming request's headers: hop-by-hop, host and
+ *  content-length stripped (fetch derives the latter two from the target URL
+ *  and the buffered body). */
+export function buildForwardHeaders(req) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        const lower = key.toLowerCase();
+        if (HOP_BY_HOP_HEADERS.has(lower) || REQUEST_ONLY_STRIP.has(lower))
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                headers.append(key, v);
+        }
+        else if (value !== undefined) {
+            headers.set(key, value);
+        }
+    }
+    return headers;
+}
+/** Buffer the request body (small JSON control messages — buffering is robust
+ *  across the fetch duplex-body edge cases). GET/HEAD and empty bodies yield
+ *  undefined. */
+export function readRequestBody(req) {
+    const method = req.method.toUpperCase();
+    if (method === "GET" || method === "HEAD")
+        return Promise.resolve(undefined);
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => {
+            const buf = Buffer.concat(chunks);
+            resolve(buf.byteLength > 0 ? new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) : undefined);
+        });
+        req.on("error", reject);
+    });
+}
+/** Relay an upstream fetch Response: status, headers (hop-by-hop plus
+ *  content-length/content-encoding stripped — fetch already decompressed the
+ *  body), then the streamed body. */
+export async function forwardUpstreamResponse(res, upstream, opts = {}) {
+    res.status(upstream.status);
+    upstream.headers.forEach((value, key) => {
+        const lower = key.toLowerCase();
+        if (HOP_BY_HOP_HEADERS.has(lower) || RESPONSE_ONLY_STRIP.has(lower))
+            return;
+        res.setHeader(key, opts.rewriteHeader ? opts.rewriteHeader(lower, value) : value);
+    });
+    if (!upstream.body) {
+        res.end();
+        return;
+    }
+    const nodeStream = Readable.fromWeb(upstream.body);
+    await new Promise((resolve) => {
+        nodeStream.on("error", (err) => {
+            opts.onStreamError?.(err);
+            if (!res.headersSent)
+                res.status(502);
+            res.end();
+            resolve();
+        });
+        res.on("close", resolve);
+        nodeStream.pipe(res);
+    });
+}
+const DEFAULT_PROXY_TIMEOUT_MS = 30_000;
+/** Proxy one HTTP request to `targetUrl`, streaming the response body back.
+ *  Never throws into express: an unreachable/booting upstream surfaces as a
+ *  502 the caller retries. */
+export async function proxyHttp(req, res, targetUrl, opts = {}) {
+    const headers = buildForwardHeaders(req);
+    const body = await readRequestBody(req);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_PROXY_TIMEOUT_MS;
+    let upstream;
+    try {
+        upstream = await fetch(targetUrl, {
+            method: req.method.toUpperCase(),
+            headers,
+            body: body,
+            redirect: "manual",
+            ...(timeoutMs > 0 ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
+        });
+    }
+    catch (err) {
+        if (!res.headersSent) {
+            res.status(502).json({ error: "bad gateway", message: err instanceof Error ? err.message : String(err) });
+        }
+        else {
+            res.end();
+        }
+        return;
+    }
+    await forwardUpstreamResponse(res, upstream, opts);
+}
+/** Express handler proxying whatever path it is mounted on to
+ *  `resolveBase(req) + req.originalUrl` (so /live/api/<id>/x reaches
+ *  <studio>/live/api/<id>/x). */
+export function makeHttpProxy(resolveBase, opts = {}) {
+    return (req, res) => {
+        const target = resolveBase(req).replace(/\/+$/, "") + req.originalUrl;
+        void proxyHttp(req, res, target, opts);
+    };
+}

package/iframe-protocol.d.ts

@@ -0,0 +1,112 @@
+export declare const IFRAME_PROTOCOL_VERSION = 1;
+export type IframeTheme = "light" | "dark";
+export type InstanceContext = {
+    /** Path prefix where the product is mounted on the runner's origin (e.g.
+     *  `/products/norsk-probe`) — feed it to the product router's basename. */
+    basename?: string;
+};
+/** Present only for the instance-launch config screen: the product template
+ *  being launched (name + parameters), so the screen can prefill. */
+export type LaunchContext = {
+    productTemplateName?: string;
+    parameters?: {
+        name: string;
+        default?: string;
+    }[];
+};
+/** The iframe reports the form values it captured; the runner POSTs them to
+ *  the product's /api/product-template to get the tar. formValues is
+ *  product-specific. */
+export type SubmitResult = {
+    ok: true;
+    formValues: Record<string, unknown>;
+} | {
+    ok: false;
+    error?: string;
+};
+export type IframeChildMessage = {
+    v: 1;
+    type: "ready";
+    payload: {
+        height: number;
+    };
+} | {
+    v: 1;
+    type: "resize";
+    payload: {
+        height: number;
+    };
+} | {
+    v: 1;
+    type: "validity";
+    payload: {
+        valid: boolean;
+        errors?: string[];
+    };
+} | {
+    v: 1;
+    type: "suggest-name";
+    payload: {
+        name: string;
+    };
+} | {
+    v: 1;
+    type: "dirty";
+    payload: {
+        dirty: boolean;
+    };
+} | {
+    v: 1;
+    type: "submit-result";
+    payload: SubmitResult;
+} | {
+    v: 1;
+    type: "request-cancel";
+    payload: Record<string, never>;
+};
+export type IframeParentMessage = {
+    v: 1;
+    type: "init";
+    payload: {
+        instanceContext?: InstanceContext;
+        theme?: IframeTheme;
+        locale?: string;
+        launchContext?: LaunchContext;
+    };
+} | {
+    v: 1;
+    type: "submit";
+    payload: Record<string, never>;
+} | {
+    v: 1;
+    type: "cancel";
+    payload: Record<string, never>;
+} | {
+    v: 1;
+    type: "theme-change";
+    payload: {
+        theme: IframeTheme;
+    };
+};
+export declare function parseParentMessage(data: unknown): IframeParentMessage | null;
+export declare function parseChildMessage(data: unknown): IframeChildMessage | null;
+export type IframeWindowLike = {
+    parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    };
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    document: {
+        body: {
+            scrollHeight: number;
+        };
+    };
+};
+export declare const isEmbedded: (win?: IframeWindowLike) => boolean;
+export declare const sendToParent: (msg: IframeChildMessage, win?: IframeWindowLike) => void;
+export declare const onParentMessage: (handler: (msg: IframeParentMessage) => void, win?: IframeWindowLike) => (() => void);
+export declare const reportHeight: (win?: IframeWindowLike) => void;

package/iframe-protocol.js

@@ -0,0 +1,44 @@
+// The runner<->product iframe postMessage contract (v1), single-sourced for
+// BOTH sides: the runner's ProductIframe component builds IframeParentMessage
+// values, and a product's config screen imports the child-side helpers below
+// instead of hand-copying them from the iframe-integration doc.
+//
+// Standalone usage (product opened outside the runner): window.parent ===
+// window, so every send becomes a no-op.
+export const IFRAME_PROTOCOL_VERSION = 1;
+// Envelope guard shared by both directions: any v1 object with a string type
+// passes (matching the product copies' onParentMessage filter); per-field
+// payload validation stays with the consumer, which knows its own defaults.
+function isEnvelope(data) {
+    return (data !== null &&
+        typeof data === "object" &&
+        data.v === IFRAME_PROTOCOL_VERSION &&
+        typeof data.type === "string");
+}
+export function parseParentMessage(data) {
+    return isEnvelope(data) ? data : null;
+}
+export function parseChildMessage(data) {
+    return isEnvelope(data) ? data : null;
+}
+// globalThis, not window: node-side consumers (dev-kit, backend) pull this
+// module in via the browser barrel and typecheck without the DOM lib.
+const realWindow = () => globalThis.window;
+export const isEmbedded = (win = realWindow()) => win.parent !== win;
+export const sendToParent = (msg, win = realWindow()) => {
+    if (!isEmbedded(win))
+        return;
+    win.parent.postMessage(msg, "*");
+};
+export const onParentMessage = (handler, win = realWindow()) => {
+    const listener = (event) => {
+        const msg = parseParentMessage(event.data);
+        if (msg)
+            handler(msg);
+    };
+    win.addEventListener("message", listener);
+    return () => win.removeEventListener("message", listener);
+};
+export const reportHeight = (win = realWindow()) => {
+    sendToParent({ v: 1, type: "resize", payload: { height: win.document.body.scrollHeight } }, win);
+};

package/index.d.ts

@@ -3,6 +3,7 @@ export * from "./capabilities-router.js";
 export * from "./cjs-interop.js";
 export * from "./dev-url.js";
 export * from "./docker-runner.js";
+export * from "./http-proxy.js";
 export * from "./license-registration.js";
 export * from "./license-stager.js";
 export * from "./license-v2.js";
@@ -13,3 +14,5 @@ export * from "./product-health-monitor.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";
+export * from "./route-error.js";
+export * from "./sse.js";

package/index.js

@@ -5,6 +5,7 @@ export * from "./capabilities-router.js";
 export * from "./cjs-interop.js";
 export * from "./dev-url.js";
 export * from "./docker-runner.js";
+export * from "./http-proxy.js";
 export * from "./license-registration.js";
 export * from "./license-stager.js";
 export * from "./license-v2.js";
@@ -15,3 +16,5 @@ export * from "./product-health-monitor.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";
+export * from "./route-error.js";
+export * from "./sse.js";

package/manifest-seed.d.ts

@@ -26,3 +26,5 @@ export declare const SeedSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
 }, z.core.$strict>>;
 export type ManifestSeed = z.infer<typeof SeedSchema>;
 export declare function parseManifestSeed(raw: unknown): Result<ManifestSeed, string>;
+export declare const bareTag: (ref: string) => string;
+export declare const repoOf: (ref: string) => string;

package/manifest-seed.js

@@ -38,3 +38,8 @@ export function parseManifestSeed(raw) {
     const parsed = SeedSchema.safeParse(raw);
     return parsed.success ? ok(parsed.data) : err(z.prettifyError(parsed.error));
 }
+// The seed carries FULL repo:tag refs; every product's version.ts splits them
+// into the uniform MEDIA_*/STUDIO_* vocabulary (RFC 0001 §5). Split on the
+// LAST colon so registry:port refs keep the port on the repo side.
+export const bareTag = (ref) => ref.slice(ref.lastIndexOf(":") + 1);
+export const repoOf = (ref) => ref.slice(0, ref.lastIndexOf(":"));

package/package.json

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

package/product-template-error.d.ts

@@ -1,10 +1 @@
-/**
- * Error class for product-template lifecycle issues. Codes cover both the
- * "store + extract" path (used by ctl's ProductTemplateService — extraction,
- * manifest parsing, in-use guarding) and the simpler "store raw bytes"
- * path (used by mgr — name validation + bytes persistence).
- */
-export declare class ProductTemplateError extends Error {
-    code: "INVALID_NAME" | "NAME_CONFLICT" | "FILE_NOT_FOUND" | "EXTRACTION_FAILED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "COMPOSE_MISSING" | "PARAMETERS_INVALID" | "NOT_FOUND" | "IN_USE" | "PRODUCT_MISMATCH";
-    constructor(code: "INVALID_NAME" | "NAME_CONFLICT" | "FILE_NOT_FOUND" | "EXTRACTION_FAILED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "COMPOSE_MISSING" | "PARAMETERS_INVALID" | "NOT_FOUND" | "IN_USE" | "PRODUCT_MISMATCH", message: string);
-}
+export { ProductTemplateError } from "@norskvideo/ctl-product-template-schema/read";

package/product-template-error.js

@@ -1,14 +1,4 @@
-/**
- * Error class for product-template lifecycle issues. Codes cover both the
- * "store + extract" path (used by ctl's ProductTemplateService — extraction,
- * manifest parsing, in-use guarding) and the simpler "store raw bytes"
- * path (used by mgr — name validation + bytes persistence).
- */
-export class ProductTemplateError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = "ProductTemplateError";
-    }
-}
+// Moved to the schema package (the error taxonomy lives with the contract it
+// reports on — see @norskvideo/ctl-product-template-schema/read). Re-exported
+// here so existing importers of @norskvideo/ctl-sdk keep working.
+export { ProductTemplateError } from "@norskvideo/ctl-product-template-schema/read";

package/proxy-middleware.js

@@ -1,48 +1,11 @@
 import { logger } from "@norskvideo/ctl-foundation";
-const HOP_BY_HOP = new Set([
-    "connection",
-    "keep-alive",
-    "proxy-authenticate",
-    "proxy-authorization",
-    "te",
-    "trailers",
-    "transfer-encoding",
-    "upgrade",
-    "host",
-    "content-length",
-]);
+import { buildForwardHeaders, forwardUpstreamResponse, readRequestBody } from "./http-proxy.js";
 function targetBaseUrl(reg) {
     if (reg.spec.kind === "container") {
         return reg.port !== undefined ? `http://127.0.0.1:${reg.port}` : null;
     }
     return reg.spec.url.replace(/\/$/, "");
 }
-function buildOutgoingHeaders(req) {
-    const out = {};
-    for (const [key, value] of Object.entries(req.headers)) {
-        if (HOP_BY_HOP.has(key.toLowerCase()))
-            continue;
-        if (value === undefined)
-            continue;
-        out[key] = Array.isArray(value) ? value.join(", ") : value;
-    }
-    return out;
-}
-async function readRequestBody(req) {
-    if (req.method === "GET" || req.method === "HEAD")
-        return undefined;
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        req.on("data", (chunk) => chunks.push(chunk));
-        req.on("end", () => {
-            if (!chunks.length)
-                return resolve(undefined);
-            const buf = Buffer.concat(chunks);
-            resolve(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
-        });
-        req.on("error", reject);
-    });
-}
 export function createProductProxyMiddleware(svc) {
     return async (req, res, next) => {
         const name = req.params.name;
@@ -60,7 +23,7 @@ export function createProductProxyMiddleware(svc) {
             return;
         }
         const targetUrl = `${base}${req.url}`;
-        const headers = buildOutgoingHeaders(req);
+        const headers = buildForwardHeaders(req);
         const body = await readRequestBody(req);
         let upstream;
         try {
@@ -76,37 +39,13 @@ export function createProductProxyMiddleware(svc) {
             res.status(502).json({ status: "error", message: `upstream fetch failed: ${String(e)}` });
             return;
         }
-        res.status(upstream.status);
         const productPrefix = `/products/${encodeURIComponent(name)}`;
-        upstream.headers.forEach((value, key) => {
-            const lower = key.toLowerCase();
-            if (HOP_BY_HOP.has(lower))
-                return;
+        await forwardUpstreamResponse(res, upstream, {
             // Rewrite root-absolute redirect Locations so 3xx responses don't
             // escape the product prefix and land on the runner SPA. Relative
             // (non-/-prefixed) and full-URL Locations pass through unchanged.
-            if (lower === "location" && value.startsWith("/") && !value.startsWith("//")) {
-                res.setHeader(key, `${productPrefix}${value}`);
-                return;
-            }
-            res.setHeader(key, value);
+            rewriteHeader: (key, value) => key === "location" && value.startsWith("/") && !value.startsWith("//") ? `${productPrefix}${value}` : value,
+            onStreamError: (e) => logger.warn(`Proxy stream from ${targetUrl} broke: ${String(e)}`),
         });
-        if (!upstream.body) {
-            res.end();
-            return;
-        }
-        const reader = upstream.body.getReader();
-        try {
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                res.write(value);
-            }
-        }
-        catch (e) {
-            logger.warn(`Proxy stream from ${targetUrl} broke: ${String(e)}`);
-        }
-        res.end();
     };
 }

package/route-error.d.ts

@@ -0,0 +1,12 @@
+import type { Response } from "express";
+export type RouteErrorClassification = {
+    status: number;
+    error: string;
+};
+export type RouteErrorClassifier = (err: unknown) => RouteErrorClassification | undefined;
+export declare function sendRouteError(res: Response, err: unknown, fallbackError: string, classify?: RouteErrorClassifier): void;
+/** Run a route body, mapping any throw or rejection to the error shape above.
+ *  `fallbackError` is the route's stable failure label (e.g.
+ *  "product-template generation failed"); `classify` upgrades known error
+ *  classes to their own status + label (e.g. a seed error to a 400). */
+export declare function guardRoute(res: Response, fallbackError: string, fn: () => void | Promise<void>, classify?: RouteErrorClassifier): void;

package/route-error.js

@@ -0,0 +1,26 @@
+export function sendRouteError(res, err, fallbackError, classify) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    const classified = classify?.(err);
+    res.status(classified?.status ?? 500).json({
+        error: classified?.error ?? fallbackError,
+        message: err instanceof Error ? err.message : String(err),
+    });
+}
+/** Run a route body, mapping any throw or rejection to the error shape above.
+ *  `fallbackError` is the route's stable failure label (e.g.
+ *  "product-template generation failed"); `classify` upgrades known error
+ *  classes to their own status + label (e.g. a seed error to a 400). */
+export function guardRoute(res, fallbackError, fn, classify) {
+    try {
+        const out = fn();
+        if (out instanceof Promise) {
+            out.catch((err) => sendRouteError(res, err, fallbackError, classify));
+        }
+    }
+    catch (err) {
+        sendRouteError(res, err, fallbackError, classify);
+    }
+}

package/sse.d.ts

@@ -0,0 +1,12 @@
+import type { Request, RequestHandler } from "express";
+export type PollingSseOptions<T> = {
+    /** Produce one snapshot for one client tick. Receives the request so the
+     *  upstream can be addressed per-request (e.g. ?studioBase=). A throw or
+     *  rejection is swallowed; the next tick retries. */
+    snapshot: (req: Request) => T | Promise<T>;
+    /** Time between frames. Defaults to 1s (funke's STREAM_INTERVAL_MS). */
+    intervalMs?: number;
+};
+/** SSE feed: emit a `data: <json>` frame immediately, then every intervalMs
+ *  until the client disconnects. */
+export declare function createPollingSseHandler<T>(opts: PollingSseOptions<T>): RequestHandler;

package/sse.js

@@ -0,0 +1,42 @@
+// Polling Server-Sent-Events bridge, lifted from funke's /api/metrics/stream.
+//
+// Why SSE and not a proxied WebSocket: bun's node:http "upgrade" socket is not
+// writable back to the client, so neither a hand-rolled raw-socket bridge nor
+// http-proxy's .ws() can forward the 101 in-process. A product backend that
+// needs an upstream WS feed (e.g. Studio's /live/firehose) therefore consumes
+// it as a CLIENT and re-emits snapshots same-origin over SSE — a plain
+// long-lived GET that also rides existing /api/* reverse-proxy locations with
+// no Upgrade handshake and no new dependency.
+/** SSE feed: emit a `data: <json>` frame immediately, then every intervalMs
+ *  until the client disconnects. */
+export function createPollingSseHandler(opts) {
+    const intervalMs = opts.intervalMs ?? 1000;
+    return (req, res) => {
+        res.set({
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive",
+        });
+        res.flushHeaders?.();
+        let closed = false;
+        const tick = async () => {
+            if (closed)
+                return;
+            try {
+                const value = await opts.snapshot(req);
+                if (!closed)
+                    res.write(`data: ${JSON.stringify(value)}\n\n`);
+            }
+            catch {
+                // Transient upstream failures are swallowed; the next tick retries.
+            }
+        };
+        void tick();
+        const timer = setInterval(() => void tick(), intervalMs);
+        req.on("close", () => {
+            closed = true;
+            clearInterval(timer);
+            res.end();
+        });
+    };
+}