@raketa-cloud/admin 1.8.17 → 1.8.19

package/src/report/reports.js

@@ -0,0 +1,390 @@
+// Client-side report loading for the resource Settings page.
+//
+// The page renders skeletons (see _quick_insights.ejs, _traffic_chart.ejs,
+// _core_web_vitals.ejs) and this fetches /:locale/api/:resources/:id/reports —
+// handed over as window.RAKETA_REPORTS = { path } — then fills the values in.
+// Server-side prefetching used to add the full GA + CrUX latency to every page
+// load; this keeps the first paint independent of both.
+(() => {
+  let CFG = window.RAKETA_REPORTS || {};
+  if (!CFG.path) return;
+
+  // Kept in step with the same note in _core_web_vitals.ejs.
+  let NO_DATA_NOTE =
+    "There is not enough data for the past 28 days to generate a report.";
+
+  // Insights covers the last 30 days (see pageInsights), CrUX a rolling 28.
+  let NO_INSIGHTS_NOTE =
+    "There is not enough data for the past 30 days to generate a report.";
+
+  let NO_CHART_NOTE = "Not enough data.";
+
+  let NO_CHART_ERROR = "Chart unavailable.";
+
+  // Shown in place of a percentage when the previous period measured nothing:
+  // "+∞%" is not a number anyone wants to read.
+  let NEW_TREND = "New";
+
+  // "No data" and "the request failed" look identical on the page unless the
+  // reason is spelled out — the server hands one over on every failed side
+  // (missing credentials, a GA/CrUX error, a bad response), so show that
+  // instead of blaming the data.
+  let MAX_NOTE = 160;
+
+  function failureNote(section, error) {
+    if (!error) return section + " could not be loaded.";
+
+    // The full text can carry an API payload; the page gets a readable slice.
+    console.error(section + " report failed:", error);
+
+    let text = String(error);
+    return text.length > MAX_NOTE ? text.slice(0, MAX_NOTE) + "…" : text;
+  }
+
+  // Sits in the same slot as the date range / collection period, so it has to
+  // stop reading like one.
+  function setFailure(el, section, error) {
+    if (!el) return;
+    el.textContent = failureNote(section, error);
+    el.classList.remove("text-raketa-foreground/50");
+    el.classList.add("text-red-600");
+  }
+
+  // Applied to the metric grid, the chart card and the vitals grid when there's
+  // nothing measured, so empty numbers can't be mistaken for results.
+  let MUTED = ["grayscale", "opacity-50"];
+
+  let mute = (el) => el && el.classList.add(...MUTED);
+
+  let RATING_TEXT = {
+    good: "text-emerald-600",
+    "needs-improvement": "text-amber-500",
+    poor: "text-red-600",
+  };
+
+  let ASSESSMENT = {
+    good: {
+      color: "text-emerald-500",
+      label: "Passed",
+      glyph:
+        "M10 18a8 8 0 1 0 0-16 8 8 0 0 0 0 16Zm3.857-9.809a.75.75 0 0 0-1.214-.882l-3.483 4.79-1.88-1.88a.75.75 0 1 0-1.06 1.061l2.5 2.5a.75.75 0 0 0 1.137-.089l4-5.5Z",
+    },
+    "needs-improvement": {
+      color: "text-amber-500",
+      label: "Needs work",
+      glyph:
+        "M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.19-1.458-1.517-2.625L8.485 2.495ZM10 5a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 10 5Zm0 9a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z",
+    },
+    poor: {
+      color: "text-red-500",
+      label: "Failed",
+      glyph:
+        "M10 18a8 8 0 1 0 0-16 8 8 0 0 0 0 16ZM8.28 7.22a.75.75 0 0 0-1.06 1.06L8.94 10l-1.72 1.72a.75.75 0 1 0 1.06 1.06L10 11.06l1.72 1.72a.75.75 0 1 0 1.06-1.06L11.06 10l1.72-1.72a.75.75 0 0 0-1.06-1.06L10 8.94 8.28 7.22Z",
+    },
+    unknown: {
+      color: "text-orange-500",
+      label: "no real-user data yet",
+      glyph:
+        "M18 10a8 8 0 1 1-16 0 8 8 0 0 1 16 0Zm-8-5a.75.75 0 0 1 .75.75v4.5a.75.75 0 0 1-1.5 0v-4.5A.75.75 0 0 1 10 5Zm0 10a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z",
+    },
+  };
+
+  // Formatters mirrored from the EJS partials so server- and client-rendered
+  // values read identically.
+  let nfmt = (v) => Number(v || 0).toLocaleString();
+
+  let fmtDuration = (sec) => {
+    sec = Math.round(sec || 0);
+    return Math.floor(sec / 60) + "m " + (sec % 60) + "s";
+  };
+
+  let fmtPct = (v) => (Number(v || 0) * 100).toFixed(1) + "%";
+
+  let fmtValue = (value, unit) =>
+    unit === "ms"
+      ? value >= 1000
+        ? (value / 1000).toFixed(2) + "s"
+        : Math.round(value) + "ms"
+      : Number(value).toFixed(2);
+
+  let fmtDay = (iso) =>
+    new Date(iso + "T00:00:00Z").toLocaleDateString("en-US", {
+      month: "short",
+      day: "numeric",
+      year: "numeric",
+      timeZone: "UTC",
+    });
+
+  // CrUX collectionPeriod uses {year,month,day} objects, not ISO strings.
+  let fmtPeriod = (p) => {
+    if (!p || !p.firstDate || !p.lastDate) return "";
+    let iso = (d) =>
+      d.year +
+      "-" +
+      String(d.month).padStart(2, "0") +
+      "-" +
+      String(d.day).padStart(2, "0");
+    return fmtDay(iso(p.firstDate)) + " → " + fmtDay(iso(p.lastDate));
+  };
+
+  let find = (selector) => document.querySelector(selector);
+  let findAll = (selector) => Array.from(document.querySelectorAll(selector));
+
+  let byMetric = (hook, metric) =>
+    find('[data-report="' + hook + '"][data-metric="' + metric + '"]');
+
+  // Writing text over a placeholder drops the spinner with it. The muted class
+  // has to come off first — it and the trend colour have equal specificity, so
+  // whichever Tailwind emits later would win and the green/red never showed.
+  function setText(el, text, colorClass) {
+    if (!el) return;
+    el.textContent = text;
+    if (!colorClass) return;
+    el.classList.remove("text-raketa-foreground/50");
+    el.classList.add(colorClass);
+  }
+
+  // A failed request would leave the spinners turning forever, so stop them.
+  function clearLoaders() {
+    findAll("[data-loader]").forEach((el) => el.remove());
+  }
+
+  // GA answers for a page with no traffic with zeros rather than an error, so
+  // "no data" has to be read off the numbers.
+  function hasTraffic(insights) {
+    if (!insights || insights.error || !insights.summary) return false;
+
+    let s = insights.summary;
+    let views = Number(s.views?.value ?? 0);
+    let users = Number(s.users?.value ?? 0);
+    let series = (insights.series && insights.series.data) || [];
+
+    return views > 0 || users > 0 || series.some((value) => Number(value) > 0);
+  }
+
+  function fillInsights(insights) {
+    let range = find('[data-report="range"]');
+    let grid = find('[data-report="insights-grid"]');
+
+    if (!insights || insights.error || !insights.summary) {
+      setFailure(range, "Insights", insights && insights.error);
+      ["views", "users", "avgDuration", "engagement"].forEach((metric) => {
+        setText(byMetric("value", metric), "—");
+        setText(byMetric("trend", metric), "—");
+      });
+      mute(grid);
+      return;
+    }
+
+    let s = insights.summary;
+
+    // Zeros are real numbers, so they stay on the cards — the note beside the
+    // title and the muted grid say they aren't a result.
+    if (!hasTraffic(insights)) {
+      mute(grid);
+      if (range) range.textContent = NO_INSIGHTS_NOTE;
+    } else if (range && insights.dateRange) {
+      range.textContent =
+        fmtDay(insights.dateRange.startDate) +
+        " → " +
+        fmtDay(insights.dateRange.endDate);
+    }
+
+    setText(byMetric("value", "views"), nfmt(s.views.value));
+    setText(byMetric("value", "users"), nfmt(s.users.value));
+    setText(
+      byMetric("value", "avgDuration"),
+      fmtDuration(s.avgDuration.seconds),
+    );
+    setText(byMetric("value", "engagement"), fmtPct(s.engagement.rate));
+
+    [
+      ["views", s.views, s.views.value],
+      ["users", s.users, s.users.value],
+      ["avgDuration", s.avgDuration, s.avgDuration.seconds],
+      ["engagement", s.engagement, s.engagement.rate],
+    ].forEach(([metric, kpi, current]) => {
+      let el = byMetric("trend", metric);
+      if (!el) return;
+
+      let trend = kpi.trend;
+
+      if (trend === null || trend === undefined) {
+        // A zero baseline has no percentage to show, but going from nothing to
+        // something is growth, not missing data. A previous value that isn't
+        // there at all is unknown, and still gets the dash.
+        if (kpi.previous === 0 && Number(current || 0) > 0) {
+          setText(el, NEW_TREND, "text-emerald-600");
+          return;
+        }
+
+        setText(el, "—");
+        return;
+      }
+
+      setText(
+        el,
+        (trend >= 0 ? "+" : "") + trend.toFixed(1) + "%",
+        trend >= 0 ? "text-emerald-600" : "text-red-600",
+      );
+    });
+  }
+
+  function fillChart(insights) {
+    let loader = find('[data-report="chart-loader"]');
+    let card = find('[data-report="chart-card"]');
+
+    // A flat line of zeros reads as data; a note over an empty canvas doesn't.
+    if (!hasTraffic(insights)) {
+      mute(card);
+
+      if (loader) {
+        loader.innerHTML = "";
+        loader.className =
+          "absolute inset-0 flex items-center justify-center body-3 text-raketa-foreground/50";
+        // The heading carries the reason; the canvas only says whether the
+        // chart is missing because of an error or because there's no traffic.
+        loader.textContent =
+          !insights || insights.error ? NO_CHART_ERROR : NO_CHART_NOTE;
+      }
+
+      return;
+    }
+
+    if (loader) loader.remove();
+
+    if (!insights.series) return;
+
+    if (typeof window.gaRenderTrafficChart !== "function") {
+      console.error(
+        "Traffic chart not drawn: /report/analytics.js must load before reports.js.",
+      );
+      return;
+    }
+
+    window.gaRenderTrafficChart({
+      series: insights.series,
+      publishDates: insights.publishDates || [],
+    });
+  }
+
+  function fillVitals(webVitals) {
+    let period = find('[data-report="cwv-period"]');
+    let icon = find('[data-report="cwv-assessment"]');
+
+    let metrics = (
+      (webVitals && !webVitals.error && webVitals.metrics) ||
+      []
+    ).reduce((acc, m) => {
+      acc[m.key] = m;
+      return acc;
+    }, {});
+
+    let measured = Object.values(metrics).some(
+      (m) => m.rating !== null && m.rating !== undefined,
+    );
+
+    // Same slot carries the collection period or, with nothing measured, why
+    // there's no report — mirrors the server-rendered heading. A failed or
+    // unconfigured request is not the same as a page CrUX has no data for.
+    if (!webVitals || webVitals.error) {
+      setFailure(period, "Core Web Vitals", webVitals && webVitals.error);
+    } else if (period) {
+      period.textContent = measured
+        ? fmtPeriod(webVitals.collectionPeriod)
+        : NO_DATA_NOTE;
+    }
+
+    if (icon) {
+      let state =
+        ASSESSMENT[webVitals && webVitals.assessment] || ASSESSMENT.unknown;
+      let title = "Core Web Vitals Assessment: " + state.label;
+
+      icon.classList.remove("invisible", "text-raketa-foreground/50");
+      icon.classList.add(state.color);
+      icon.setAttribute("aria-label", title);
+
+      let titleEl = icon.querySelector("title");
+      if (titleEl) titleEl.textContent = title;
+
+      let path = icon.querySelector("path");
+      if (path) path.setAttribute("d", state.glyph);
+    }
+
+    // Nothing measured — dim and desaturate the gauges so the colour bands
+    // aren't mistaken for a result.
+    if (!measured) mute(find('[data-report="vitals-grid"]'));
+
+    findAll('[data-report="vital"]').forEach((gauge) => {
+      let loader = gauge.querySelector('[data-report="vital-loader"]');
+      let marker = gauge.querySelector('[data-report="marker"]');
+      let metric = metrics[gauge.dataset.metric];
+
+      // Without a measurement the arrow would have to point somewhere, and any
+      // position is a claim — say "no data" over the bands instead.
+      if (!metric || metric.rating === null || metric.rating === undefined) {
+        if (loader) {
+          loader.removeAttribute("data-loader");
+          loader.className =
+            "absolute top-0 left-0 text-[11px] font-medium text-raketa-foreground/50";
+          loader.textContent = "No data";
+        }
+        return;
+      }
+
+      if (loader) loader.remove();
+      if (!marker) return;
+
+      let scaleMax = Number(gauge.dataset.scaleMax) || 1;
+      let share = Math.min(Math.max((metric.p75 / scaleMax) * 100, 1), 99);
+      let color = RATING_TEXT[metric.rating] || "text-raketa-foreground/50";
+
+      marker.style.left = share.toFixed(2) + "%";
+      marker.classList.remove("invisible");
+
+      let value = marker.querySelector('[data-report="vital-value"]');
+      let arrow = marker.querySelector('[data-report="vital-arrow"]');
+
+      if (value) {
+        value.textContent = fmtValue(metric.p75, gauge.dataset.unit);
+        value.classList.add(color);
+      }
+      if (arrow) arrow.classList.add(color);
+    });
+  }
+
+  async function loadReports() {
+    let reports = null;
+    let failure = null;
+
+    try {
+      let response = await fetch(CFG.path, {
+        headers: { accept: "application/json" },
+        credentials: "same-origin",
+      });
+
+      if (response.ok) reports = await response.json();
+      else failure = "The reports request failed (" + response.status + ").";
+    } catch (err) {
+      failure = "The reports request failed: " + (err.message || err);
+    }
+
+    // Both sides went down together, so both say the same thing rather than
+    // sitting empty or claiming there was no data.
+    if (!reports) {
+      clearLoaders();
+      let failed = { error: failure };
+      fillInsights(failed);
+      fillChart(failed);
+      fillVitals(failed);
+      return;
+    }
+
+    fillInsights(reports.insights);
+    fillChart(reports.insights);
+    fillVitals(reports.webVitals);
+  }
+
+  if (document.readyState !== "loading") loadReports();
+  else document.addEventListener("DOMContentLoaded", loadReports);
+})();

package/src/routeAssets.js

@@ -0,0 +1,74 @@
+// The package ships the report scripts and serves them itself, so a host app
+// only supplies credentials and config — no copying files into its public
+// directory and no build step to keep in sync.
+//
+// They live under /report/* alongside the JSON feed, clear of whatever the
+// host app serves from its own public directory.
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import currentPath from "./currentPath.cjs";
+
+const ASSETS_DIR = join(currentPath, "report");
+
+// Explicit list — the path never comes from the request.
+const ASSETS = ["analytics.js", "reports.js"];
+
+// Chart.js comes from the package's own dependency instead of a CDN: a host
+// app whose CSP restricts script-src to 'self' would never load the external
+// bundle, and the traffic chart would silently stay blank.
+const moduleRequire = createRequire(join(currentPath, "routeAssets.js"));
+
+// The UMD build registers every controller and puts Chart on window, which is
+// what analytics.js expects. It is resolved next to the package's main entry —
+// chart.js does not export the file path directly.
+const chartBundlePath = () =>
+  join(dirname(moduleRequire.resolve("chart.js")), "chart.umd.js");
+
+const JS_HEADERS = {
+  "content-type": "application/javascript; charset=utf-8",
+  "cache-control": "no-cache",
+};
+
+// Reading per request keeps `npm run dev` serving edits without a restart;
+// anywhere else the files never change and a synchronous read on every GET is
+// event-loop time for nothing.
+const isDevelopment = () =>
+  (process.env.RAKETA_ENV ?? process.env.NODE_ENV) === "development";
+
+function routeAssets(adapter) {
+  const sources = new Map();
+
+  const readAsset = (path) => {
+    if (isDevelopment()) return readFileSync(path, "utf8");
+
+    if (!sources.has(path)) sources.set(path, readFileSync(path, "utf8"));
+    return sources.get(path);
+  };
+
+  ASSETS.forEach((file) => {
+    adapter.addRoute("GET", `/report/${file}`, async (routerCtx) => {
+      const source = readAsset(join(ASSETS_DIR, file));
+
+      return routerCtx.body(source, 200, JS_HEADERS);
+    });
+  });
+
+  // Always read once and held, dev included: it only changes when the
+  // dependency does, and it is two orders of magnitude larger than the
+  // scripts above.
+  let chartBundle = null;
+
+  adapter.addRoute("GET", "/report/chart.js", async (routerCtx) => {
+    if (chartBundle === null) {
+      chartBundle = readFileSync(chartBundlePath(), "utf8");
+    }
+
+    return routerCtx.body(chartBundle, 200, {
+      ...JS_HEADERS,
+      "cache-control": "public, max-age=3600",
+    });
+  });
+}
+
+export default routeAssets;

package/src/routeResourceModule.js

@@ -15,6 +15,7 @@ import ClonesHandler from "./handlers/resources/ClonesHandler";
 import DeletesHandler from "./handlers/resources/DeletesHandler";
 import ExportsHandler from "./handlers/resources/ExportsHandler";
 import HistoryHandler from "./handlers/resources/HistoryHandler";
+import ReportsAPIHandler from "./handlers/resources/ReportsAPIHandler";
 import ResourcesAPIHandler from "./handlers/resources/ResourcesAPIHandler";
 import ResourcesHandler from "./handlers/resources/ResourcesHandler";
 import TranslationsHandler from "./handlers/resources/TranslationsHandler";
@@ -38,10 +39,14 @@ function routeResourceModule(
   const viewsRevisions = `${viewsType}_revisions`;
   const viewsChanges = `${viewsType}_changes`;
 
+  const reportsEnabled =
+    adapter.globalConfig?.features?.reports?.[resourceType] || false;
+
   const resourceConfig = {
     resourceType,
     resourceTypePlural,
     dateFields,
+    reports: reportsEnabled,
   };
 
   const exportsMapping = [
@@ -61,6 +66,25 @@ function routeResourceModule(
     viewsFallback: "resources",
   });
 
+  if (reportsEnabled) {
+    // JSON feed for the Settings page, which renders skeletons and fetches the
+    // reports client-side instead of blocking the render on GA / CrUX. Sits
+    // under /report alongside the scripts that consume it (see routeAssets).
+    adapter.routeCollection(
+      [
+        [
+          "GET",
+          `/report/${baseResource}/:id`,
+          `report/${baseResource}`,
+          baseResource,
+          "reports",
+          ReportsAPIHandler.show,
+        ],
+      ],
+      resourceConfig,
+    );
+  }
+
   routeNestedCollection(
     adapter,
     baseResource,

package/src/routeStandard.js

@@ -2,12 +2,16 @@ import DashboardsHandler from "./handlers/DashboardsHandler";
 import RedirectsHandler from "./handlers/RedirectsHandler";
 import TagsAPIHandler from "./handlers/TagsAPIHandler";
 import TagsHandler from "./handlers/TagsHandler";
+import routeAssets from "./routeAssets";
 import routeCollection from "./routeCollection";
 import routeResourceModule from "./routeResourceModule";
 import routeSettings from "./routeSettings";
 import ContentTasksHandler from "./handlers/content_tasks/ContentTasksHandler";
 
 function routeStandard(adapter) {
+  // The package serves its own client scripts (see routeAssets).
+  routeAssets(adapter);
+
   adapter.routeCollection(
     [
       [
@@ -29,7 +33,9 @@ function routeStandard(adapter) {
   routeCollection(adapter, "content_tasks", ContentTasksHandler);
   routeCollection(adapter, "api/tags", TagsAPIHandler);
   routeSettings(adapter);
-  routeResourceModule(adapter, "page", "pages", { dateFields: [] });
+  routeResourceModule(adapter, "page", "pages", {
+    dateFields: [],
+  });
   routeResourceModule(adapter, "article", "articles", {
     dateFields: ["publish_at"],
   });

package/src/styles/application.css

@@ -311,7 +311,7 @@ body {
   }
 
   .page-title {
-    @apply flex items-center justify-between my-6;
+    @apply flex items-center justify-between mt-6;
   }
 
   .actions-toolbar {

package/src/tests/handlers/RedirectsHandler.test/notes.test.js

@@ -0,0 +1,56 @@
+import RedirectsHandler from "../../../handlers/RedirectsHandler";
+import Redirects from "../../../cloud/Redirects";
+
+function buildCtx(redirect, params = {}) {
+  return {
+    client: { redirects: new Redirects(() => ({}), "token") },
+    params,
+    resourceParams: { redirect },
+    locale: "en",
+  };
+}
+
+// The note is optional on the form but the API expects a string.
+describe("Redirects without a note", () => {
+  const redirect = {
+    url: "/old-page",
+    destination: "/new-page",
+    httpResponseCode: "301",
+  };
+
+  test("create sends an empty note", async () => {
+    const ctx = buildCtx(redirect);
+
+    const mockCreate = jest
+      .spyOn(ctx.client.redirects, "create")
+      .mockImplementation(() => ({ errors: null }));
+
+    const result = await RedirectsHandler.create(ctx);
+
+    expect(mockCreate).toHaveBeenCalledWith({
+      url: "/old-page",
+      destination: "/new-page",
+      httpResponseCode: 301,
+      note: "",
+    });
+    expect(result).toEqual({ redirect: "/en/redirects" });
+  });
+
+  test("update sends an empty note", async () => {
+    const ctx = buildCtx(redirect, { id: "42" });
+
+    const mockUpdate = jest
+      .spyOn(ctx.client.redirects, "update")
+      .mockImplementation(() => ({ errors: null }));
+
+    const result = await RedirectsHandler.update(ctx);
+
+    expect(mockUpdate).toHaveBeenCalledWith("42", {
+      url: "/old-page",
+      destination: "/new-page",
+      httpResponseCode: 301,
+      note: "",
+    });
+    expect(result).toEqual({ redirect: "/en/redirects" });
+  });
+});

package/src/tests/handlers/_shared/SettingsHandler.test/global_variables.test.js

@@ -0,0 +1,54 @@
+import SettingsHandler from "../../../../handlers/_shared/SettingsHandler";
+import Settings from "../../../../cloud/Settings";
+
+function buildCtx(params) {
+  return {
+    client: { settings: new Settings(() => ({}), "token") },
+    locale: "en",
+    resourceParams: { resource: params },
+    resourceConfig: { resource: "settings/meta" },
+  };
+}
+
+// Global variables are replaced wholesale rather than deep merged, so removing
+// a variable actually removes it.
+describe("Settings global variables", () => {
+  test("update overwrites the stored global variables", async () => {
+    const current = {
+      meta: { title: "A title" },
+      _global_variables: [{ key: "old", value: "1" }],
+    };
+    const params = {
+      _global_variables: [{ key: "new", value: "2" }],
+    };
+    const ctx = buildCtx(params);
+
+    jest.spyOn(ctx.client.settings, "find").mockImplementation(() => current);
+    const mockUpdate = jest
+      .spyOn(ctx.client.settings, "update")
+      .mockImplementation(() => ({ errors: null }));
+
+    const result = await SettingsHandler.update(ctx);
+
+    expect(mockUpdate).toHaveBeenCalledWith("en", {
+      meta: { title: "A title" },
+      _global_variables: params._global_variables,
+    });
+    expect(result).toEqual({ redirect: "/en/settings/meta/edit?success=1" });
+  });
+
+  test("update clears the global variables when an empty list is sent", async () => {
+    const ctx = buildCtx({ _global_variables: [] });
+
+    jest
+      .spyOn(ctx.client.settings, "find")
+      .mockImplementation(() => ({ _global_variables: [{ key: "old" }] }));
+    const mockUpdate = jest
+      .spyOn(ctx.client.settings, "update")
+      .mockImplementation(() => ({ errors: null }));
+
+    await SettingsHandler.update(ctx);
+
+    expect(mockUpdate.mock.calls[0][1]._global_variables).toEqual([]);
+  });
+});