@businessdash/sdk 0.9.60 → 0.9.80

package/src/mcp-adapters/index.ts

@@ -0,0 +1,264 @@
+/**
+ * `@businessdash/sdk/mcp-adapters` — mount the MCP connector on any framework.
+ *
+ * `mcpHandler` returns Web-standard `(Request) => Promise<Response>`, which is
+ * exactly right for Next's App Router, Astro, Remix and TanStack Start, and
+ * exactly wrong for everything else: SvelteKit hands you `{ request }`,
+ * Nuxt/Nitro hands you an H3 `event`, Qwik City hands you a `RequestEvent` with
+ * `send()`, and Express hands you Node's `req`/`res`.
+ *
+ * So a consumer on four of the eight frameworks had to work out the bridging
+ * themselves, for a surface whose whole selling point is that an org hands
+ * Claude or ChatGPT a URL on their OWN domain. This module is that bridging,
+ * written once.
+ *
+ * Every adapter is a thin shape-change over the same handler — no adapter
+ * reimplements the proxy, the error mapping or the manifest caching, so a fix
+ * to any of those lands everywhere at once.
+ *
+ * @module
+ */
+
+import {
+	type McpProxyOptions,
+	mcpHandler,
+	mcpManifestHandler,
+} from "../mcp.js";
+
+/**
+ * SvelteKit (and Astro, which has the same shape).
+ *
+ * ```ts
+ * // src/routes/api/mcp/+server.ts
+ * import { sveltekitMcpHandler } from '@businessdash/sdk/mcp-adapters'
+ * export const { POST, GET } = sveltekitMcpHandler({ siteId, baseUrl })
+ * ```
+ */
+export function sveltekitMcpHandler(options: McpProxyOptions): {
+	POST: (event: { request: Request }) => Promise<Response>;
+	GET: () => Promise<Response>;
+} {
+	const handler = mcpHandler(options);
+	return {
+		POST: (event) => handler.POST(event.request),
+		GET: () => handler.GET(),
+	};
+}
+
+/** SvelteKit / Astro manifest route for `.well-known/mcp.json`. */
+export function sveltekitMcpManifestHandler(
+	options: McpProxyOptions,
+): (event: { request: Request }) => Promise<Response> {
+	const handler = mcpManifestHandler(options);
+	return (event) => handler(event.request);
+}
+
+/** Astro is the same shape as SvelteKit; aliased so the import reads right. */
+export const astroMcpHandler = sveltekitMcpHandler;
+export const astroMcpManifestHandler = sveltekitMcpManifestHandler;
+
+/**
+ * The minimum of H3's event we touch. Declared structurally rather than
+ * importing `h3`, so this module adds no dependency for consumers who are not
+ * on Nuxt.
+ */
+type H3EventLike = {
+	node: { req: { method?: string | undefined } };
+	web?: { request?: Request } | undefined;
+};
+
+/**
+ * Nuxt / Nitro.
+ *
+ * ```ts
+ * // server/routes/api/mcp.post.ts
+ * import { nitroMcpHandler } from '@businessdash/sdk/mcp-adapters'
+ * export default defineEventHandler(nitroMcpHandler({ siteId, baseUrl }))
+ * ```
+ *
+ * Nitro exposes the original Web `Request` on `event.web.request` in recent
+ * versions. `toWebRequest` is passed in rather than imported so this stays
+ * dependency-free — on older Nitro, hand it `toWebRequest` from `h3`.
+ */
+export function nitroMcpHandler(
+	options: McpProxyOptions,
+	deps: { toWebRequest?: (event: unknown) => Request } = {},
+): (event: H3EventLike) => Promise<Response> {
+	const handler = mcpHandler(options);
+	return async (event) => {
+		const request = event.web?.request ?? deps.toWebRequest?.(event);
+		if (!request) {
+			// Failing loudly beats proxying an empty body and returning a
+			// confusing JSON-RPC error the consumer cannot trace.
+			throw new Error(
+				"nitroMcpHandler could not read a Web Request from the H3 event. On Nitro versions without `event.web.request`, pass `{ toWebRequest }` from `h3`.",
+			);
+		}
+		return (event.node.req.method ?? "GET").toUpperCase() === "POST"
+			? handler.POST(request)
+			: handler.GET();
+	};
+}
+
+/** Nuxt / Nitro manifest route. */
+export function nitroMcpManifestHandler(
+	options: McpProxyOptions,
+	deps: { toWebRequest?: (event: unknown) => Request } = {},
+): (event: H3EventLike) => Promise<Response> {
+	const handler = mcpManifestHandler(options);
+	return async (event) => {
+		const request = event.web?.request ?? deps.toWebRequest?.(event);
+		if (!request) {
+			throw new Error(
+				"nitroMcpManifestHandler could not read a Web Request from the H3 event. Pass `{ toWebRequest }` from `h3` on older Nitro.",
+			);
+		}
+		return handler(request);
+	};
+}
+
+/** The slice of Qwik City's `RequestEvent` these adapters use. */
+type QwikRequestEventLike = {
+	request: Request;
+	send: (response: Response) => void;
+};
+
+/**
+ * Qwik City.
+ *
+ * ```ts
+ * // src/routes/api/mcp/index.ts
+ * import { qwikMcpHandler } from '@businessdash/sdk/mcp-adapters'
+ * const mcp = qwikMcpHandler({ siteId, baseUrl })
+ * export const onPost = mcp.onPost
+ * export const onGet = mcp.onGet
+ * ```
+ *
+ * Qwik City returns a response by CALLING `send()` rather than returning it,
+ * which is the detail most people get wrong when wiring this by hand.
+ */
+export function qwikMcpHandler(options: McpProxyOptions): {
+	onPost: (event: QwikRequestEventLike) => Promise<void>;
+	onGet: (event: QwikRequestEventLike) => Promise<void>;
+} {
+	const handler = mcpHandler(options);
+	return {
+		onPost: async (event) => {
+			event.send(await handler.POST(event.request));
+		},
+		onGet: async (event) => {
+			event.send(await handler.GET());
+		},
+	};
+}
+
+/** Qwik City manifest route. */
+export function qwikMcpManifestHandler(
+	options: McpProxyOptions,
+): (event: QwikRequestEventLike) => Promise<void> {
+	const handler = mcpManifestHandler(options);
+	return async (event) => {
+		event.send(await handler(event.request));
+	};
+}
+
+/** The Node req/res surface these adapters touch. */
+type NodeRequestLike = {
+	method?: string | undefined;
+	url?: string | undefined;
+	headers: Record<string, string | string[] | undefined>;
+	on(event: string, listener: (chunk?: unknown) => void): unknown;
+};
+
+type NodeResponseLike = {
+	statusCode: number;
+	setHeader(name: string, value: string): void;
+	end(body?: string): void;
+};
+
+/**
+ * Express, and Angular Universal / Analog, which both run on Node's req/res.
+ *
+ * ```ts
+ * const mcp = expressMcpHandler({ siteId, baseUrl })
+ * app.post('/api/mcp', mcp)
+ * app.get('/api/mcp', mcp)
+ * app.get('/.well-known/mcp.json', expressMcpManifestHandler({ siteId, baseUrl }))
+ * ```
+ *
+ * Node gives a stream rather than a `Request`, so the body is collected first.
+ * `origin` matters for the manifest — it is what tells the platform which
+ * domain to advertise — so it is reconstructed from the Host header rather
+ * than guessed.
+ */
+export function expressMcpHandler(
+	options: McpProxyOptions,
+): (req: NodeRequestLike, res: NodeResponseLike) => Promise<void> {
+	const handler = mcpHandler(options);
+	return async (req, res) => {
+		const method = (req.method ?? "GET").toUpperCase();
+		const response =
+			method === "POST"
+				? await handler.POST(
+						new Request(reconstructUrl(req), {
+							method: "POST",
+							headers: {
+								"content-type": "application/json",
+								accept: headerValue(req.headers.accept) ?? "application/json",
+							},
+							body: await readBody(req),
+						}),
+					)
+				: await handler.GET();
+		await writeNodeResponse(res, response);
+	};
+}
+
+/** Express / Node manifest route for `.well-known/mcp.json`. */
+export function expressMcpManifestHandler(
+	options: McpProxyOptions,
+): (req: NodeRequestLike, res: NodeResponseLike) => Promise<void> {
+	const handler = mcpManifestHandler(options);
+	return async (req, res) => {
+		const response = await handler(new Request(reconstructUrl(req)));
+		await writeNodeResponse(res, response);
+	};
+}
+
+function headerValue(value: string | string[] | undefined): string | undefined {
+	return Array.isArray(value) ? value[0] : value;
+}
+
+/**
+ * Rebuild the absolute URL Node does not give us.
+ *
+ * The manifest handler reads `new URL(request.url).origin` to tell the platform
+ * which domain to advertise, so a placeholder host here would publish the wrong
+ * connector URL — the one failure mode of this whole surface.
+ */
+function reconstructUrl(req: NodeRequestLike): string {
+	const host = headerValue(req.headers.host) ?? "localhost";
+	const proto = headerValue(req.headers["x-forwarded-proto"]) ?? "https";
+	return `${proto}://${host}${req.url ?? "/"}`;
+}
+
+function readBody(req: NodeRequestLike): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const chunks: string[] = [];
+		req.on("data", (chunk) => chunks.push(String(chunk)));
+		req.on("end", () => resolve(chunks.join("")));
+		req.on("error", (error) => reject(error));
+	});
+}
+
+async function writeNodeResponse(
+	res: NodeResponseLike,
+	response: Response,
+): Promise<void> {
+	res.statusCode = response.status;
+	response.headers.forEach((value, name) => {
+		res.setHeader(name, value);
+	});
+	const text = await response.text();
+	res.end(text.length > 0 ? text : undefined);
+}

package/src/mcp-adapters.ts

@@ -0,0 +1,7 @@
+/**
+ * `@businessdash/sdk/mcp-adapters` — mount the MCP connector on any framework.
+ *
+ * @module
+ */
+
+export * from "./mcp-adapters/index.js";

package/src/model3d-core/index.ts

@@ -0,0 +1,248 @@
+/**
+ * `@businessdash/sdk/model3d` — 3D product models on the org's own site.
+ *
+ * ## This ships no renderer, and that is the point
+ *
+ * A three.js build is ~600KB before your model. `<model-viewer>` is ~300KB. An
+ * SDK that pulled either down on every product page would be an SDK people rip
+ * out, and it would make the choice of engine ours rather than yours.
+ *
+ * So this decides WHAT to show and hands you the facts. You mount whichever
+ * viewer you already use, or none.
+ *
+ * ```ts
+ * const plan = planProductModel(product);
+ * if (plan.ar) showArLink(plan.ar.url);        // zero JS, native iOS
+ * if (plan.viewer) mountYourViewer(plan.viewer.url, plan.viewer.format);
+ * if (plan.download) showLink(plan.download.url, plan.download.label);
+ * ```
+ *
+ * ## The three formats do genuinely different jobs
+ *
+ * **AR Quick Look (`.usdz`)** — the one worth having. On iOS, iPadOS and
+ * visionOS Safari an `<a rel="ar">` opens the model in the room, in the camera,
+ * with no JavaScript at all. No library, no canvas, no WebGL. Where it applies
+ * it beats an embedded viewer on every axis, so it is checked first.
+ *
+ * **Web viewer (`.glb`/`.gltf`/`.obj`/`.stl`)** — the rotatable canvas. `.glb`
+ * carries its own materials and is what you want; `.obj` and `.stl` are
+ * geometry only and render in a neutral grey, which is fine for a machined part
+ * and disappointing for a sofa.
+ *
+ * **CAD download (`.step`/`.stp`/`.iges`)** — NOT renderable, deliberately.
+ * STEP is a boundary-representation format needing a geometry kernel; the
+ * browser WASM builds of OpenCascade that can tessellate it are 10–30MB, which
+ * is not something to pull down for a product photo. It is also the wrong shape
+ * for who asks: an engineer evaluating a bracket wants the file in their own CAD
+ * package, not a spinning preview.
+ *
+ * ## Absent is the normal case
+ *
+ * These fields are stripped unless the org holds the `ecommerce.product_3d`
+ * add-on, and most businesses never attach a model. Every function here treats
+ * missing as ordinary and returns nothing to render.
+ *
+ * @module
+ */
+
+/** The product fields this reads. Anything with these keys works. */
+export type ModelBearingProduct = {
+	id?: string;
+	model3dUrl?: string | null;
+	model3dUsdzUrl?: string | null;
+	/** The API reports availability, never the URL. See `download` below. */
+	model3dCadAvailable?: boolean;
+	model3dCadName?: string | null;
+};
+
+/** What a web viewer can load. */
+export type WebModelFormat = "glb" | "gltf" | "obj" | "stl";
+
+/** What a CAD download might be. */
+export type CadFormat = "step" | "iges" | "native";
+
+export type ModelPlan = {
+	/**
+	 * Present when the model can be placed in the room on this device.
+	 *
+	 * Only on Apple platforms, and only with a `.usdz`. Render as
+	 * `<a rel="ar" href={url}><img …/></a>` — the `<img>` child is required by
+	 * Quick Look, and the link needs no JavaScript whatsoever.
+	 */
+	ar: { url: string } | null;
+	/**
+	 * Present when there is a model a WebGL viewer can load.
+	 *
+	 * `neutralMaterial` is true for `.obj` and `.stl`, which carry geometry but
+	 * no materials — worth knowing, because a viewer that lights them like a
+	 * `.glb` renders a black silhouette.
+	 */
+	viewer: {
+		url: string;
+		format: WebModelFormat;
+		neutralMaterial: boolean;
+	} | null;
+	/**
+	 * Present when the org attached a CAD file.
+	 *
+	 * `url` points at the platform's gated endpoint, never at the file — that
+	 * route requires cookies, rate-limits the caller and re-checks the
+	 * entitlement before handing anything over. Render it as an ordinary link;
+	 * the visitor's browser sends its cookie automatically.
+	 *
+	 * `format` is inferred from the filename when the org supplied one, so a
+	 * page can say "STEP" rather than "CAD" without a round trip.
+	 */
+	download: { url: string; label: string; format: CadFormat } | null;
+	/** True when there is nothing 3D at all — the common case. */
+	empty: boolean;
+};
+
+/** Lowercased extension, ignoring query strings and fragments. */
+function extensionOf(url: string): string {
+	const path = url.split(/[?#]/)[0] ?? "";
+	const last = path.slice(path.lastIndexOf("/") + 1);
+	const dot = last.lastIndexOf(".");
+	return dot === -1 ? "" : last.slice(dot + 1).toLowerCase();
+}
+
+/** Which web viewer format a URL is, if any. */
+export function webModelFormat(
+	url: string | null | undefined,
+): WebModelFormat | null {
+	if (!url) return null;
+	const ext = extensionOf(url);
+	return ext === "glb" || ext === "gltf" || ext === "obj" || ext === "stl"
+		? ext
+		: null;
+}
+
+/** Which CAD family a URL belongs to. Unknown extensions are `native`. */
+export function cadFormat(url: string | null | undefined): CadFormat | null {
+	if (!url) return null;
+	const ext = extensionOf(url);
+	if (ext === "step" || ext === "stp") return "step";
+	if (ext === "iges" || ext === "igs") return "iges";
+	return ext ? "native" : null;
+}
+
+/**
+ * Does THIS browser support AR Quick Look?
+ *
+ * Feature-detected rather than sniffed: Safari advertises support by
+ * recognising `rel="ar"` on an anchor. That is Apple's own documented check and
+ * it survives the next user-agent change, which a regex on "iPhone" does not.
+ *
+ * False on the server, so a plan built during SSR omits the AR branch. Re-plan
+ * on the client if you want the link to appear without a navigation — the check
+ * is a few microseconds.
+ */
+export function supportsArQuickLook(): boolean {
+	if (typeof document === "undefined") return false;
+	const anchor = document.createElement("a");
+	return Boolean(anchor.relList?.supports?.("ar"));
+}
+
+export type PlanProductModelOptions = {
+	/**
+	 * Override the AR capability check.
+	 *
+	 * Pass `true` during SSR when you know the request came from an Apple
+	 * device, or `false` to suppress AR entirely.
+	 */
+	arSupported?: boolean;
+	/**
+	 * Where your app proxies `GET storefront/products/{id}/cad`.
+	 *
+	 * Required for `download` to appear, and required to be YOUR route rather
+	 * than the platform's: the API key is a server secret, so the browser
+	 * cannot call the platform endpoint directly. Proxy it and pass your own
+	 * path — `cadDownloadUrl: `/api/products/${product.id}/cad``.
+	 *
+	 * Without it the plan reports no download even when a file exists, which is
+	 * the safe direction: a dead link is worse than an absent one.
+	 */
+	cadDownloadUrl?: string;
+};
+
+/**
+ * Decide what to render for one product.
+ *
+ * AR is not exclusive with the viewer — a product can offer both, and on an
+ * iPhone the usual arrangement is a canvas with a "View in your room" button
+ * over it. The plan reports each independently rather than picking for you.
+ */
+export function planProductModel(
+	product: ModelBearingProduct,
+	options: PlanProductModelOptions = {},
+): ModelPlan {
+	const arSupported = options.arSupported ?? supportsArQuickLook();
+	const usdz = product.model3dUsdzUrl?.trim() || null;
+	const ar = arSupported && usdz ? { url: usdz } : null;
+
+	const viewerUrl = product.model3dUrl?.trim() || null;
+	const format = webModelFormat(viewerUrl);
+	const viewer =
+		viewerUrl && format
+			? {
+					url: viewerUrl,
+					format,
+					// .obj and .stl are geometry only. A viewer lighting them like
+					// a .glb renders a black silhouette.
+					neutralMaterial: format === "obj" || format === "stl",
+				}
+			: null;
+
+	const cadName = product.model3dCadName?.trim() || null;
+	// Inferred from the filename, since the URL is never in the payload. Falls
+	// back to `native`, which only changes the default label.
+	const cad = product.model3dCadAvailable
+		? (cadFormat(cadName) ?? "native")
+		: null;
+	const download =
+		cad && options.cadDownloadUrl
+			? {
+					url: options.cadDownloadUrl,
+					label: cadName || defaultCadLabel(cad),
+					format: cad,
+				}
+			: null;
+
+	return { ar, viewer, download, empty: !ar && !viewer && !download && !usdz };
+}
+
+function defaultCadLabel(format: CadFormat): string {
+	if (format === "step") return "Download STEP file";
+	if (format === "iges") return "Download IGES file";
+	return "Download CAD file";
+}
+
+/**
+ * The attributes an AR Quick Look anchor needs.
+ *
+ * Spread onto your own `<a>`. Quick Look requires an `<img>` or equivalent
+ * child — an empty anchor silently does nothing, which is the single most
+ * common way this gets implemented wrong.
+ */
+export function arLinkAttributes(url: string): {
+	href: string;
+	rel: string;
+} {
+	return { href: url, rel: "ar" };
+}
+
+/**
+ * True when the org has the 3D add-on, judged from a product payload.
+ *
+ * The API omits these keys entirely without `ecommerce.product_3d`, so their
+ * absence distinguishes "not paid for" from "paid for, none attached" — where
+ * the key is present and null. Useful for deciding whether to show an upsell
+ * rather than nothing.
+ */
+export function hasModel3dEntitlement(product: object): boolean {
+	return (
+		"model3dUrl" in product ||
+		"model3dUsdzUrl" in product ||
+		"model3dCadAvailable" in product
+	);
+}