@cavuno/board 4.15.0 → 4.16.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 This changelog records changes that affect Board API compatibility, exported
 types, runtime behavior, or supported integration patterns.
 
+## 4.16.0 — 2026-08-31
+
+- **`@cavuno/board/analytics`**: new subpath with `install({ publishableKey })`
+  and `track(action, payload?)`. Uses the board publishable key (`pk_…`) only.
+  Default collect URL is Cavuno central collect; pass a first-party
+  `/.well-known/cavuno/collect` URL when the board host serves those handlers.
+- **Stable analytics tenant**: events are keyed by the immutable public board
+  id (`boards_<accountId>`), not the mutable board slug.
+- **Doctor**: `npx @cavuno/board doctor` includes an analytics-surface scan that
+  flags legacy third-party tracker credentials in app source.
+
 ## 4.15.0 — 2026-08-30
 
 - **LinkedIn conversion IDs on `board.context().analytics`**: five nullable

package/dist/analytics.d.mts

@@ -0,0 +1,58 @@
+declare const DEFAULT_COLLECT_URL = "https://cavuno.com/api/analytics/collect";
+declare const DEFAULT_SCRIPT_URL = "https://cavuno.com/js/metrics.js";
+/** Placeholder tenant; collect rewrites from the publishable key. */
+declare const PENDING_TENANT_ID = "boards_pending";
+declare const WELL_KNOWN_ANALYTICS_SCRIPT_PATH = "/.well-known/cavuno/analytics.js";
+declare const WELL_KNOWN_SCRIPT_PATH = "/.well-known/cavuno/analytics.js";
+declare const WELL_KNOWN_COLLECT_PATH = "/.well-known/cavuno/collect";
+
+/**
+ * Optional first-party well-known handlers for board origin Workers.
+ * Central collect remains the default when these paths are not mounted.
+ */
+
+declare const WELL_KNOWN_COLLECT_EVENTS_PATH = "/.well-known/cavuno/collect/v0/events";
+/**
+ * Handle `/.well-known/cavuno/{analytics.js,collect}` when mounted on a Worker.
+ * Returns null for every other path so the host can fall through.
+ */
+declare function matchAnalyticsWellKnown(request: Request): Promise<Response | null>;
+
+/**
+ * `@cavuno/board/analytics` — client write surface for board analytics.
+ *
+ * Emits pageviews (via hosted script) and custom events to Cavuno collect.
+ * Uses the board publishable key only; no second analytics credential.
+ */
+
+type AnalyticsInstallOptions = {
+    publishableKey: string;
+    /** Default: Cavuno central collect (self-host safe) */
+    collectUrl?: string;
+    /** Default: Cavuno-hosted metrics script */
+    scriptUrl?: string;
+};
+/**
+ * Load the Cavuno-hosted metrics script and remember collect credentials.
+ * Safe to call once per page; subsequent calls update collect targets only.
+ */
+declare function install(options: AnalyticsInstallOptions): void;
+/**
+ * Emit a custom analytics event to Cavuno collect.
+ * Prefer `install` first so pageviews and vitals are also recorded.
+ */
+declare function track(action: string, payload?: Record<string, unknown>): void;
+declare const analytics: {
+    install: typeof install;
+    track: typeof track;
+    matchAnalyticsWellKnown: typeof matchAnalyticsWellKnown;
+    DEFAULT_COLLECT_URL: string;
+    DEFAULT_SCRIPT_URL: string;
+    PENDING_TENANT_ID: string;
+    WELL_KNOWN_ANALYTICS_SCRIPT_PATH: string;
+    WELL_KNOWN_SCRIPT_PATH: string;
+    WELL_KNOWN_COLLECT_PATH: string;
+    WELL_KNOWN_COLLECT_EVENTS_PATH: string;
+};
+
+export { type AnalyticsInstallOptions, DEFAULT_COLLECT_URL, DEFAULT_SCRIPT_URL, PENDING_TENANT_ID, WELL_KNOWN_ANALYTICS_SCRIPT_PATH, WELL_KNOWN_COLLECT_EVENTS_PATH, WELL_KNOWN_COLLECT_PATH, WELL_KNOWN_SCRIPT_PATH, analytics, install, matchAnalyticsWellKnown, track };

package/dist/analytics.d.ts

@@ -0,0 +1,58 @@
+declare const DEFAULT_COLLECT_URL = "https://cavuno.com/api/analytics/collect";
+declare const DEFAULT_SCRIPT_URL = "https://cavuno.com/js/metrics.js";
+/** Placeholder tenant; collect rewrites from the publishable key. */
+declare const PENDING_TENANT_ID = "boards_pending";
+declare const WELL_KNOWN_ANALYTICS_SCRIPT_PATH = "/.well-known/cavuno/analytics.js";
+declare const WELL_KNOWN_SCRIPT_PATH = "/.well-known/cavuno/analytics.js";
+declare const WELL_KNOWN_COLLECT_PATH = "/.well-known/cavuno/collect";
+
+/**
+ * Optional first-party well-known handlers for board origin Workers.
+ * Central collect remains the default when these paths are not mounted.
+ */
+
+declare const WELL_KNOWN_COLLECT_EVENTS_PATH = "/.well-known/cavuno/collect/v0/events";
+/**
+ * Handle `/.well-known/cavuno/{analytics.js,collect}` when mounted on a Worker.
+ * Returns null for every other path so the host can fall through.
+ */
+declare function matchAnalyticsWellKnown(request: Request): Promise<Response | null>;
+
+/**
+ * `@cavuno/board/analytics` — client write surface for board analytics.
+ *
+ * Emits pageviews (via hosted script) and custom events to Cavuno collect.
+ * Uses the board publishable key only; no second analytics credential.
+ */
+
+type AnalyticsInstallOptions = {
+    publishableKey: string;
+    /** Default: Cavuno central collect (self-host safe) */
+    collectUrl?: string;
+    /** Default: Cavuno-hosted metrics script */
+    scriptUrl?: string;
+};
+/**
+ * Load the Cavuno-hosted metrics script and remember collect credentials.
+ * Safe to call once per page; subsequent calls update collect targets only.
+ */
+declare function install(options: AnalyticsInstallOptions): void;
+/**
+ * Emit a custom analytics event to Cavuno collect.
+ * Prefer `install` first so pageviews and vitals are also recorded.
+ */
+declare function track(action: string, payload?: Record<string, unknown>): void;
+declare const analytics: {
+    install: typeof install;
+    track: typeof track;
+    matchAnalyticsWellKnown: typeof matchAnalyticsWellKnown;
+    DEFAULT_COLLECT_URL: string;
+    DEFAULT_SCRIPT_URL: string;
+    PENDING_TENANT_ID: string;
+    WELL_KNOWN_ANALYTICS_SCRIPT_PATH: string;
+    WELL_KNOWN_SCRIPT_PATH: string;
+    WELL_KNOWN_COLLECT_PATH: string;
+    WELL_KNOWN_COLLECT_EVENTS_PATH: string;
+};
+
+export { type AnalyticsInstallOptions, DEFAULT_COLLECT_URL, DEFAULT_SCRIPT_URL, PENDING_TENANT_ID, WELL_KNOWN_ANALYTICS_SCRIPT_PATH, WELL_KNOWN_COLLECT_EVENTS_PATH, WELL_KNOWN_COLLECT_PATH, WELL_KNOWN_SCRIPT_PATH, analytics, install, matchAnalyticsWellKnown, track };

package/dist/analytics.js

@@ -0,0 +1,222 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/analytics/index.ts
+var analytics_exports = {};
+__export(analytics_exports, {
+  DEFAULT_COLLECT_URL: () => DEFAULT_COLLECT_URL,
+  DEFAULT_SCRIPT_URL: () => DEFAULT_SCRIPT_URL,
+  PENDING_TENANT_ID: () => PENDING_TENANT_ID,
+  WELL_KNOWN_ANALYTICS_SCRIPT_PATH: () => WELL_KNOWN_ANALYTICS_SCRIPT_PATH,
+  WELL_KNOWN_COLLECT_EVENTS_PATH: () => WELL_KNOWN_COLLECT_EVENTS_PATH,
+  WELL_KNOWN_COLLECT_PATH: () => WELL_KNOWN_COLLECT_PATH,
+  WELL_KNOWN_SCRIPT_PATH: () => WELL_KNOWN_SCRIPT_PATH,
+  analytics: () => analytics,
+  install: () => install,
+  matchAnalyticsWellKnown: () => matchAnalyticsWellKnown,
+  track: () => track
+});
+module.exports = __toCommonJS(analytics_exports);
+
+// src/analytics/defaults.ts
+var DEFAULT_COLLECT_URL = "https://cavuno.com/api/analytics/collect";
+var DEFAULT_SCRIPT_URL = "https://cavuno.com/js/metrics.js";
+var PENDING_TENANT_ID = "boards_pending";
+var WELL_KNOWN_ANALYTICS_SCRIPT_PATH = "/.well-known/cavuno/analytics.js";
+var WELL_KNOWN_SCRIPT_PATH = WELL_KNOWN_ANALYTICS_SCRIPT_PATH;
+var WELL_KNOWN_COLLECT_PATH = "/.well-known/cavuno/collect";
+
+// src/analytics/well-known.ts
+var WELL_KNOWN_COLLECT_EVENTS_PATH = "/.well-known/cavuno/collect/v0/events";
+var CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Authorization, Content-Type, Accept",
+  "Access-Control-Max-Age": "86400",
+  "Cross-Origin-Resource-Policy": "cross-origin"
+};
+function stripTrailingSlash(pathname) {
+  return pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+}
+function withCors(response) {
+  const headers = new Headers(response.headers);
+  for (const [key, value] of Object.entries(CORS_HEADERS)) {
+    headers.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+function corsPreflight() {
+  return withCors(new Response(null, { status: 204 }));
+}
+async function proxyCollect(request, targetUrl) {
+  if (request.method === "OPTIONS") {
+    return corsPreflight();
+  }
+  if (request.method !== "POST") {
+    return withCors(new Response(null, { status: 405 }));
+  }
+  const headers = new Headers();
+  const authorization = request.headers.get("Authorization");
+  const contentType = request.headers.get("Content-Type");
+  const accept = request.headers.get("Accept");
+  if (authorization) headers.set("Authorization", authorization);
+  if (contentType) headers.set("Content-Type", contentType);
+  if (accept) headers.set("Accept", accept);
+  const body = await request.arrayBuffer();
+  const upstream = await fetch(targetUrl, {
+    method: "POST",
+    headers,
+    body
+  });
+  return withCors(
+    new Response(upstream.body, {
+      status: upstream.status,
+      headers: {
+        "Content-Type": upstream.headers.get("Content-Type") ?? "application/json"
+      }
+    })
+  );
+}
+async function matchAnalyticsWellKnown(request) {
+  const path = stripTrailingSlash(new URL(request.url).pathname);
+  if (path === WELL_KNOWN_ANALYTICS_SCRIPT_PATH) {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      return new Response(null, { status: 405 });
+    }
+    return Response.redirect(DEFAULT_SCRIPT_URL, 302);
+  }
+  if (path === WELL_KNOWN_COLLECT_PATH) {
+    return proxyCollect(request, DEFAULT_COLLECT_URL);
+  }
+  if (path === WELL_KNOWN_COLLECT_EVENTS_PATH) {
+    return proxyCollect(request, `${DEFAULT_COLLECT_URL}/v0/events`);
+  }
+  return null;
+}
+
+// src/analytics/index.ts
+var GLOBAL_NAME = "CavunoAnalytics";
+var installed = null;
+function getRoot() {
+  return globalThis;
+}
+function normalizeCollectUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveDefaultCollectUrl() {
+  return DEFAULT_COLLECT_URL;
+}
+function resolveDefaultScriptUrl() {
+  return DEFAULT_SCRIPT_URL;
+}
+function postCollectJson(state, action, payload) {
+  const body = JSON.stringify({
+    publishableKey: state.publishableKey,
+    action,
+    payload: payload ?? {}
+  });
+  void fetch(state.collectUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${state.publishableKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body,
+    keepalive: true
+  }).catch(() => {
+  });
+}
+function exposeGlobal(state) {
+  const root = getRoot();
+  root[GLOBAL_NAME] = {
+    trackEvent(action, payload) {
+      postCollectJson(state, action, payload);
+    }
+  };
+}
+function injectScript(state, scriptUrl) {
+  const doc = getRoot().document;
+  if (!doc?.createElement) {
+    return;
+  }
+  if (doc.querySelector?.(`script[data-cavuno-analytics="1"]`)) {
+    return;
+  }
+  const el = doc.createElement("script");
+  el.defer = true;
+  el.src = scriptUrl;
+  el.setAttribute("data-cavuno-analytics", "1");
+  el.setAttribute("data-token", state.publishableKey);
+  el.setAttribute("data-host", state.collectUrl);
+  el.setAttribute("data-tenant-id", PENDING_TENANT_ID);
+  el.setAttribute("data-web-vitals", "true");
+  const head = doc.head;
+  if (head?.appendChild) {
+    head.appendChild(el);
+    return;
+  }
+  const first = doc.getElementsByTagName("script")[0];
+  first?.parentNode?.insertBefore(el, first);
+}
+function install(options) {
+  const publishableKey = options.publishableKey.trim();
+  if (!publishableKey.startsWith("pk_")) {
+    throw new Error("analytics.install requires a publishable key (pk_\u2026)");
+  }
+  const collectUrl = normalizeCollectUrl(
+    (options.collectUrl ?? resolveDefaultCollectUrl()).trim() || resolveDefaultCollectUrl()
+  );
+  const scriptUrl = (options.scriptUrl ?? resolveDefaultScriptUrl()).trim() || resolveDefaultScriptUrl();
+  installed = { publishableKey, collectUrl };
+  exposeGlobal(installed);
+  injectScript(installed, scriptUrl);
+}
+function track(action, payload) {
+  const trimmed = action.trim();
+  if (!trimmed) {
+    return;
+  }
+  const root = getRoot();
+  const globalTrack = root[GLOBAL_NAME]?.trackEvent;
+  if (typeof globalTrack === "function" && installed) {
+    globalTrack(trimmed, payload);
+    return;
+  }
+  if (!installed) {
+    return;
+  }
+  postCollectJson(installed, trimmed, payload);
+}
+var analytics = {
+  install,
+  track,
+  matchAnalyticsWellKnown,
+  DEFAULT_COLLECT_URL,
+  DEFAULT_SCRIPT_URL,
+  PENDING_TENANT_ID,
+  WELL_KNOWN_ANALYTICS_SCRIPT_PATH,
+  WELL_KNOWN_SCRIPT_PATH,
+  WELL_KNOWN_COLLECT_PATH,
+  WELL_KNOWN_COLLECT_EVENTS_PATH
+};

package/dist/analytics.mjs

@@ -0,0 +1,199 @@
+// src/analytics/defaults.ts
+var DEFAULT_COLLECT_URL = "https://cavuno.com/api/analytics/collect";
+var DEFAULT_SCRIPT_URL = "https://cavuno.com/js/metrics.js";
+var PENDING_TENANT_ID = "boards_pending";
+var WELL_KNOWN_ANALYTICS_SCRIPT_PATH = "/.well-known/cavuno/analytics.js";
+var WELL_KNOWN_SCRIPT_PATH = WELL_KNOWN_ANALYTICS_SCRIPT_PATH;
+var WELL_KNOWN_COLLECT_PATH = "/.well-known/cavuno/collect";
+
+// src/analytics/well-known.ts
+var WELL_KNOWN_COLLECT_EVENTS_PATH = "/.well-known/cavuno/collect/v0/events";
+var CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Authorization, Content-Type, Accept",
+  "Access-Control-Max-Age": "86400",
+  "Cross-Origin-Resource-Policy": "cross-origin"
+};
+function stripTrailingSlash(pathname) {
+  return pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+}
+function withCors(response) {
+  const headers = new Headers(response.headers);
+  for (const [key, value] of Object.entries(CORS_HEADERS)) {
+    headers.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+function corsPreflight() {
+  return withCors(new Response(null, { status: 204 }));
+}
+async function proxyCollect(request, targetUrl) {
+  if (request.method === "OPTIONS") {
+    return corsPreflight();
+  }
+  if (request.method !== "POST") {
+    return withCors(new Response(null, { status: 405 }));
+  }
+  const headers = new Headers();
+  const authorization = request.headers.get("Authorization");
+  const contentType = request.headers.get("Content-Type");
+  const accept = request.headers.get("Accept");
+  if (authorization) headers.set("Authorization", authorization);
+  if (contentType) headers.set("Content-Type", contentType);
+  if (accept) headers.set("Accept", accept);
+  const body = await request.arrayBuffer();
+  const upstream = await fetch(targetUrl, {
+    method: "POST",
+    headers,
+    body
+  });
+  return withCors(
+    new Response(upstream.body, {
+      status: upstream.status,
+      headers: {
+        "Content-Type": upstream.headers.get("Content-Type") ?? "application/json"
+      }
+    })
+  );
+}
+async function matchAnalyticsWellKnown(request) {
+  const path = stripTrailingSlash(new URL(request.url).pathname);
+  if (path === WELL_KNOWN_ANALYTICS_SCRIPT_PATH) {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      return new Response(null, { status: 405 });
+    }
+    return Response.redirect(DEFAULT_SCRIPT_URL, 302);
+  }
+  if (path === WELL_KNOWN_COLLECT_PATH) {
+    return proxyCollect(request, DEFAULT_COLLECT_URL);
+  }
+  if (path === WELL_KNOWN_COLLECT_EVENTS_PATH) {
+    return proxyCollect(request, `${DEFAULT_COLLECT_URL}/v0/events`);
+  }
+  return null;
+}
+
+// src/analytics/index.ts
+var GLOBAL_NAME = "CavunoAnalytics";
+var installed = null;
+function getRoot() {
+  return globalThis;
+}
+function normalizeCollectUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveDefaultCollectUrl() {
+  return DEFAULT_COLLECT_URL;
+}
+function resolveDefaultScriptUrl() {
+  return DEFAULT_SCRIPT_URL;
+}
+function postCollectJson(state, action, payload) {
+  const body = JSON.stringify({
+    publishableKey: state.publishableKey,
+    action,
+    payload: payload ?? {}
+  });
+  void fetch(state.collectUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${state.publishableKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body,
+    keepalive: true
+  }).catch(() => {
+  });
+}
+function exposeGlobal(state) {
+  const root = getRoot();
+  root[GLOBAL_NAME] = {
+    trackEvent(action, payload) {
+      postCollectJson(state, action, payload);
+    }
+  };
+}
+function injectScript(state, scriptUrl) {
+  const doc = getRoot().document;
+  if (!doc?.createElement) {
+    return;
+  }
+  if (doc.querySelector?.(`script[data-cavuno-analytics="1"]`)) {
+    return;
+  }
+  const el = doc.createElement("script");
+  el.defer = true;
+  el.src = scriptUrl;
+  el.setAttribute("data-cavuno-analytics", "1");
+  el.setAttribute("data-token", state.publishableKey);
+  el.setAttribute("data-host", state.collectUrl);
+  el.setAttribute("data-tenant-id", PENDING_TENANT_ID);
+  el.setAttribute("data-web-vitals", "true");
+  const head = doc.head;
+  if (head?.appendChild) {
+    head.appendChild(el);
+    return;
+  }
+  const first = doc.getElementsByTagName("script")[0];
+  first?.parentNode?.insertBefore(el, first);
+}
+function install(options) {
+  const publishableKey = options.publishableKey.trim();
+  if (!publishableKey.startsWith("pk_")) {
+    throw new Error("analytics.install requires a publishable key (pk_\u2026)");
+  }
+  const collectUrl = normalizeCollectUrl(
+    (options.collectUrl ?? resolveDefaultCollectUrl()).trim() || resolveDefaultCollectUrl()
+  );
+  const scriptUrl = (options.scriptUrl ?? resolveDefaultScriptUrl()).trim() || resolveDefaultScriptUrl();
+  installed = { publishableKey, collectUrl };
+  exposeGlobal(installed);
+  injectScript(installed, scriptUrl);
+}
+function track(action, payload) {
+  const trimmed = action.trim();
+  if (!trimmed) {
+    return;
+  }
+  const root = getRoot();
+  const globalTrack = root[GLOBAL_NAME]?.trackEvent;
+  if (typeof globalTrack === "function" && installed) {
+    globalTrack(trimmed, payload);
+    return;
+  }
+  if (!installed) {
+    return;
+  }
+  postCollectJson(installed, trimmed, payload);
+}
+var analytics = {
+  install,
+  track,
+  matchAnalyticsWellKnown,
+  DEFAULT_COLLECT_URL,
+  DEFAULT_SCRIPT_URL,
+  PENDING_TENANT_ID,
+  WELL_KNOWN_ANALYTICS_SCRIPT_PATH,
+  WELL_KNOWN_SCRIPT_PATH,
+  WELL_KNOWN_COLLECT_PATH,
+  WELL_KNOWN_COLLECT_EVENTS_PATH
+};
+export {
+  DEFAULT_COLLECT_URL,
+  DEFAULT_SCRIPT_URL,
+  PENDING_TENANT_ID,
+  WELL_KNOWN_ANALYTICS_SCRIPT_PATH,
+  WELL_KNOWN_COLLECT_EVENTS_PATH,
+  WELL_KNOWN_COLLECT_PATH,
+  WELL_KNOWN_SCRIPT_PATH,
+  analytics,
+  install,
+  matchAnalyticsWellKnown,
+  track
+};