@raketa-cloud/admin 1.8.18 → 1.8.19

package/src/helpers/reports/reportsUtils.js

@@ -0,0 +1,181 @@
+import { cruxApiKeyConfigured, pageWebVitals } from "./cwv";
+import { serviceAccountConfigured } from "./googleAuth";
+import { pageInsights } from "./quick-insights";
+
+const reportsEnabled = (ctx) => Boolean(ctx.resourceConfig?.reports);
+
+// The two APIs take opposite credentials: GA is per-property authorized and
+// rejects API keys (service account), CrUX is a public dataset and rejects
+// OAuth (API key). Each tab is gated on its own.
+const gaEnabled = (ctx) =>
+  reportsEnabled(ctx) &&
+  Boolean(ctx.globalConfig?.ga?.propertyId) &&
+  serviceAccountConfigured(ctx.globalConfig?.ga);
+
+const cwvEnabled = (ctx) =>
+  reportsEnabled(ctx) && cruxApiKeyConfigured(ctx.globalConfig?.ga);
+
+const chartLabel = (iso) =>
+  new Date(`${iso}T00:00:00Z`).toLocaleDateString("en-US", {
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+
+// insertedAt is an ISO timestamp; take its day as written rather than through
+// Date, which would shift a timezone-less string into local time.
+const isoDay = (value) => {
+  if (!value) return null;
+
+  const day = String(value).match(/^\d{4}-\d{2}-\d{2}/);
+  if (day) return day[0];
+
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString().slice(0, 10);
+};
+
+// GA knows nothing about revisions, so the publish markers come from the
+// resource's own change log and are joined onto the series by day.
+async function resourcePublishDates(ctx, resource, resourceType) {
+  try {
+    const changes = await ctx.client.resourceChanges.list(
+      { "f:change_type": ["revision_publish"] },
+      resource.id,
+      ctx.locale,
+      resourceType,
+    );
+
+    return (changes?.list ?? []).map((change) => isoDay(change.insertedAt));
+  } catch {
+    // A missing history shouldn't cost the whole report its chart.
+    return [];
+  }
+}
+
+function buildChartSeries(rows, publishes = []) {
+  const dates = rows.map((r) => r.date);
+  const onAxis = new Set(dates);
+
+  return {
+    series: {
+      dates,
+      labels: dates.map(chartLabel),
+      data: rows.map((r) => r.views),
+    },
+    // Only days the chart actually plots can carry a marker; older publishes
+    // fall outside the 30-day window.
+    publishDates: [...new Set(publishes)]
+      .filter((day) => day && onAxis.has(day))
+      .sort(),
+  };
+}
+
+// Sites rewrite the homepage resource to the site root, so its analytics live
+// under "/" and never under "/<slug>". Override the slug per project with
+// config.ga.homepageSlug.
+const DEFAULT_HOMEPAGE_SLUG = "homepage";
+
+const isHomepage = (ctx, resource) =>
+  resource.slug ===
+  (ctx.globalConfig?.ga?.homepageSlug ?? DEFAULT_HOMEPAGE_SLUG);
+
+function gaPagePath(ctx, resource, resourceType) {
+  if (isHomepage(ctx, resource)) return "/";
+  return ctx.remoteConfig.resourcePath(resource, resourceType, ctx.locale);
+}
+
+function cwvPageUrl(ctx, resource, resourceType) {
+  const base = ctx.globalConfig?.ga?.publicUrl;
+  if (base) {
+    return new URL(gaPagePath(ctx, resource, resourceType), base).toString();
+  }
+
+  const pageUrl = ctx.remoteConfig.resourceUrl(
+    resource,
+    resourceType,
+    ctx.locale,
+  );
+
+  // Without a configured publicUrl the resource URL still carries "/<slug>" —
+  // collapse it to the origin root so CrUX is asked about the real page.
+  if (isHomepage(ctx, resource)) {
+    const url = new URL(pageUrl);
+    url.pathname = "/";
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+  }
+
+  return pageUrl;
+}
+
+// Cache entries are per resource, not per URL: paths collide (the homepage
+// rewrite, locale rewrites), and a shared entry meant one resource's report
+// stood in for another's. Resource ids are unique per locale already.
+const reportCacheKey = (resource, resourceType) =>
+  `${resourceType}:${resource.id}`;
+
+async function fetchWebVitals(ctx, resource, resourceType) {
+  try {
+    const pageUrl = cwvPageUrl(ctx, resource, resourceType);
+
+    const data = await pageWebVitals(pageUrl, ctx.globalConfig?.ga, {
+      cacheKey: reportCacheKey(resource, resourceType),
+    });
+    if (!data) {
+      throw new Error("No Core Web Vitals data (check server logs)");
+    }
+    return { pageUrl, ...data, error: null };
+  } catch (err) {
+    return { error: err.message || String(err) };
+  }
+}
+
+async function fetchQuickInsights(ctx, resource, resourceType) {
+  try {
+    if (!gaEnabled(ctx)) {
+      throw new Error(
+        "Google Analytics is not configured. Set config.ga.propertyId and config.ga.serviceAccountPath (GOOGLE_APPLICATION_CREDENTIALS) to enable reports.",
+      );
+    }
+    const pagePath = gaPagePath(ctx, resource, resourceType);
+
+    const [reports, publishes] = await Promise.all([
+      pageInsights(pagePath, ctx.globalConfig?.ga, {
+        cacheKey: reportCacheKey(resource, resourceType),
+      }),
+      resourcePublishDates(ctx, resource, resourceType),
+    ]);
+
+    if (!reports) {
+      throw new Error("No analytics data (check GA config / server logs)");
+    }
+    return {
+      pagePath,
+      summary: reports.summary,
+      dateRange: reports.dateRange,
+      ...buildChartSeries(reports.rows ?? [], publishes),
+      error: null,
+    };
+  } catch (err) {
+    return { error: err.message || String(err) };
+  }
+}
+
+// Which reports this resource can show, without fetching anything. The Settings
+// page uses it to decide which skeletons to render before the client fetches.
+export const reportsAvailability = (ctx) => ({
+  insights: gaEnabled(ctx),
+  webVitals: cwvEnabled(ctx),
+});
+
+// Both reports for the Settings page, fetched together. Either side is null
+// when its credential isn't configured, so the section simply doesn't render.
+export async function resourceReports(ctx, resource, resourceType) {
+  const [insights, webVitals] = await Promise.all([
+    gaEnabled(ctx) ? fetchQuickInsights(ctx, resource, resourceType) : null,
+    cwvEnabled(ctx) ? fetchWebVitals(ctx, resource, resourceType) : null,
+  ]);
+
+  return { insights, webVitals };
+}

package/src/index.js

@@ -22,6 +22,14 @@ export { default as ResourceRevisions } from "./cloud/ResourceRevisions";
 export { default as Resources } from "./cloud/Resources";
 export { default as Categories } from "./cloud/Categories";
 
+export { default as localCache } from "./localCache";
+export {
+  pageInsights,
+  runPageReport,
+  runSummary,
+} from "./helpers/reports/quick-insights";
+export { pageWebVitals } from "./helpers/reports/cwv";
+
 export { default as ContentTasksHandler } from "./handlers/content_tasks/ContentTasksHandler";
 export { default as RedirectsHandler } from "./handlers/RedirectsHandler";
 export { default as TagsHandler } from "./handlers/TagsHandler";

package/src/localCache.js

@@ -0,0 +1,112 @@
+import { LRUCache } from "lru-cache";
+
+const UNDEFINED_VALUE = Symbol.for("localCache.udef");
+
+const cacheOptions = {
+  max: 8000,
+  maxSize: 300 * 1024 * 1024,
+  // maxSize is in bytes, so entries are measured by their serialized length.
+  // Nothing that can't be measured may take the caller's request down with it:
+  // JSON.stringify answers undefined for undefined / functions / symbols and
+  // throws outright on a circular structure or a BigInt.
+  sizeCalculation: (value) => {
+    if (value === UNDEFINED_VALUE) return 1;
+
+    try {
+      const json = JSON.stringify(value);
+      return json === undefined ? 1 : Buffer.byteLength(json);
+    } catch {
+      return 1;
+    }
+  },
+  ttl: 1000 * 60 * 3, // 3 minutes
+  // When we get a stale result and can't fetch a fresh one - use the stale one more time..
+  allowStale: true,
+  noDeleteOnStaleGet: true,
+};
+
+// Use the globalThis in order to prevent multiple instances of the cache..
+let cacheInstance = null;
+
+if (globalThis.cacheInstance) {
+  cacheInstance = globalThis.cacheInstance;
+} else {
+  cacheInstance = new LRUCache({
+    ...cacheOptions,
+  });
+  globalThis.cacheInstance = cacheInstance;
+}
+
+function fetchFromCache(key) {
+  const status = {};
+
+  // storedValue is what the cache holds, sentinel and all — a stale entry is
+  // written back as it was found, so a failed refresh can't quietly turn a
+  // cached "nothing" into a cached null.
+  const storedValue = cacheInstance.get(key, { status });
+
+  return {
+    cachedValue: storedValue === UNDEFINED_VALUE ? null : storedValue,
+    storedValue,
+    status,
+  };
+}
+
+// lru-cache treats set(key, undefined) as a delete, so the sentinel stands in
+// for it. Only undefined maps to it — 0, "", false and null are real values and
+// must survive a round trip through the cache.
+const toCacheValue = (value) => (value === undefined ? UNDEFINED_VALUE : value);
+
+function setInCache(key, value, ttl) {
+  cacheInstance.set(key, toCacheValue(value), ttl ? { ttl } : undefined);
+}
+
+function clearCache() {
+  cacheInstance.clear();
+}
+
+async function fetchWithCache(cacheKey, fetcher, { ttl } = {}) {
+  const { cachedValue, storedValue, status } = fetchFromCache(cacheKey);
+
+  if (status.get === "hit") {
+    return cachedValue;
+  }
+
+  if (status.get === "stale") {
+    try {
+      const freshEntity = await fetcher();
+
+      setInCache(cacheKey, freshEntity, ttl);
+
+      return freshEntity ?? null;
+    } catch (e) {
+      console.error(e);
+
+      // Reset TTL — with the value exactly as it was stored.
+      setInCache(cacheKey, storedValue, ttl);
+
+      return cachedValue;
+    }
+  }
+
+  try {
+    const freshEntity = await fetcher();
+
+    setInCache(cacheKey, freshEntity, ttl);
+
+    return freshEntity ?? null;
+  } catch (e) {
+    console.error(e);
+
+    // On a cache miss there is no stale value to preserve, so leave the cache
+    // untouched and let the next caller retry immediately.
+    return null;
+  }
+}
+
+export default {
+  fetch: fetchWithCache,
+  clear: clearCache,
+  forEach: (callback) => cacheInstance.forEach(callback),
+  getRemainingTTL: (key) => cacheInstance.getRemainingTTL(key),
+};

package/src/report/analytics.js

@@ -0,0 +1,107 @@
+// Traffic-trends chart. Two entry points:
+//   - a page that inlines its data as window.GA_ANALYTICS, drawn on load
+//   - the Settings page fetches its data and calls window.gaRenderTrafficChart()
+//     (see reports.js)
+//
+// Shape either way:
+//   { series: { dates: ["YYYY-MM-DD", ...], labels: ["July 5", ...], data: [] },
+//     publishDates: ["YYYY-MM-DD", ...] }
+(() => {
+  let gaChart = null;
+
+  function gaRenderTrafficChart(cfg) {
+    let el = document.getElementById("ga-traffic-chart");
+    if (!el || typeof Chart === "undefined") return;
+
+    let series = (cfg && cfg.series) || {};
+    let dates = series.dates || [];
+    let publishDates = new Set((cfg && cfg.publishDates) || []);
+    let isPublish = (i) => publishDates.has(dates[i]);
+
+    // Re-rendering replaces the chart rather than stacking a second one. Ask
+    // Chart.js which instance owns this canvas instead of trusting the local
+    // handle: if the canvas was replaced, that handle points at a detached
+    // chart and the new one would collide with a registry entry we never
+    // cleared ("Canvas is already in use").
+    let existing =
+      (typeof Chart.getChart === "function" && Chart.getChart(el)) || gaChart;
+    if (existing) existing.destroy();
+
+    gaChart = new Chart(el.getContext("2d"), {
+      type: "line",
+      data: {
+        labels: series.labels || [],
+        datasets: [
+          {
+            label: "Page Views",
+            data: series.data || [],
+            borderColor: "#6366f1",
+            backgroundColor: (context) => {
+              let chart = context.chart;
+              let ctx = chart.ctx;
+              let chartArea = chart.chartArea;
+              if (!chartArea) return null;
+              let g = ctx.createLinearGradient(
+                0,
+                chartArea.bottom,
+                0,
+                chartArea.top,
+              );
+              g.addColorStop(0, "rgba(99, 102, 241, 0)");
+              g.addColorStop(1, "rgba(99, 102, 241, 0.15)");
+              return g;
+            },
+            fill: true,
+            tension: 0.4,
+            pointRadius: (c) => (isPublish(c.dataIndex) ? 6 : 4),
+            // Publish markers are yellow-400/500 — kept in step with the
+            // "Published revision" legend dot in _traffic_chart.ejs.
+            pointBackgroundColor: (c) =>
+              isPublish(c.dataIndex) ? "#facc15" : "#fff",
+            pointBorderColor: (c) =>
+              isPublish(c.dataIndex) ? "#eab308" : "#6366f1",
+            pointBorderWidth: 3,
+            pointHoverRadius: (c) => (isPublish(c.dataIndex) ? 10 : 8),
+          },
+        ],
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        plugins: {
+          legend: { display: false },
+          tooltip: {
+            callbacks: {
+              label: (c) => ` Views: ${c.raw}`,
+              afterLabel: (c) =>
+                isPublish(c.dataIndex) ? "Revision published" : "",
+            },
+          },
+        },
+        scales: {
+          y: {
+            beginAtZero: true,
+            grid: { color: "#e2e8f0" },
+            ticks: { color: "#94a3b8", font: { size: 10 } },
+          },
+          x: {
+            grid: { display: false },
+            ticks: { color: "#94a3b8", font: { size: 10 }, maxRotation: 0 },
+          },
+        },
+      },
+    });
+  }
+
+  window.gaRenderTrafficChart = gaRenderTrafficChart;
+
+  // Inlined data (Insights tab) draws itself; the Settings page has none and
+  // waits for reports.js instead.
+  function gaRenderInlined() {
+    if (!window.GA_ANALYTICS) return;
+    gaRenderTrafficChart(window.GA_ANALYTICS);
+  }
+
+  if (document.readyState !== "loading") gaRenderInlined();
+  else document.addEventListener("DOMContentLoaded", gaRenderInlined);
+})();