@raketa-cloud/admin 1.8.18 → 1.8.20

package/src/helpers/reports/cwv.js

@@ -0,0 +1,217 @@
+import localCache from "../../localCache";
+
+// Same window as the GA cache (see quick-insights.js): one upstream request per
+// page per 3 hours.
+const CWV_CACHE_TTL = 1000 * 60 * 60 * 3;
+
+// CrUX will not take a service-account bearer token: OAuth credentials get a
+// blanket 400 INVALID_ARGUMENT whatever the body. It authorizes with an API key
+// only (public dataset, no per-resource ACL) — the exact opposite of the
+// Analytics Data API, which rejects keys and needs the service account.
+export const cruxApiKeyConfigured = (ga = {}) =>
+  Boolean(ga.apiKey) && ga.apiKey !== "YOUR-GOOGLE-API-KEY";
+
+const ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord";
+
+const THRESHOLDS = {
+  largest_contentful_paint: [2500, 4000],
+  interaction_to_next_paint: [200, 500],
+  cumulative_layout_shift: [0.1, 0.25],
+  first_contentful_paint: [1800, 3000],
+  experimental_time_to_first_byte: [800, 1800],
+};
+
+const METRICS = [
+  {
+    name: "largest_contentful_paint",
+    key: "lcp",
+    label: "LCP",
+    title: "Largest Contentful Paint",
+    unit: "ms",
+  },
+  {
+    name: "interaction_to_next_paint",
+    key: "inp",
+    label: "INP",
+    title: "Interaction to Next Paint",
+    unit: "ms",
+  },
+  {
+    name: "cumulative_layout_shift",
+    key: "cls",
+    label: "CLS",
+    title: "Cumulative Layout Shift",
+    unit: "",
+  },
+  {
+    name: "first_contentful_paint",
+    key: "fcp",
+    label: "FCP",
+    title: "First Contentful Paint",
+    unit: "ms",
+  },
+  {
+    name: "experimental_time_to_first_byte",
+    key: "ttfb",
+    label: "TTFB",
+    title: "Time to First Byte",
+    unit: "ms",
+  },
+];
+
+export const CWV_METRICS = METRICS.map((meta) => {
+  const [good, needsImprovement] = THRESHOLDS[meta.name];
+
+  return {
+    key: meta.key,
+    label: meta.label,
+    title: meta.title,
+    unit: meta.unit,
+    thresholds: { good, poor: needsImprovement },
+  };
+});
+
+function rate(name, p75) {
+  const [good, needsImprovement] = THRESHOLDS[name];
+  if (p75 <= good) return "good";
+  if (p75 <= needsImprovement) return "needs-improvement";
+  return "poor";
+}
+
+async function query(target, ga, formFactor) {
+  const body = JSON.stringify({
+    ...target,
+    metrics: METRICS.map((m) => m.name),
+    ...(formFactor ? { formFactor } : {}),
+  });
+
+  const response = await fetch(
+    `${ENDPOINT}?key=${encodeURIComponent(ga.apiKey)}`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+    },
+  );
+
+  if (response.status === 404) return null;
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`CrUX API ${response.status}: ${body.slice(0, 200)}`);
+  }
+
+  const json = await response.json();
+
+  return json.record ?? null;
+}
+
+const CORE_VITALS = ["lcp", "inp", "cls"];
+
+function shape(record, scope) {
+  const metrics = [];
+
+  for (const meta of METRICS) {
+    const metric = record.metrics?.[meta.name];
+    if (!metric) continue;
+
+    const p75 = Number(metric.percentiles?.p75 ?? 0);
+    const bins = metric.histogram ?? [];
+    const [good, needsImprovement] = THRESHOLDS[meta.name];
+
+    metrics.push({
+      key: meta.key,
+      label: meta.label,
+      title: meta.title,
+      unit: meta.unit,
+      p75,
+      rating: rate(meta.name, p75),
+
+      thresholds: { good, poor: needsImprovement },
+
+      distribution: {
+        good: Number(bins[0]?.density ?? 0),
+        needsImprovement: Number(bins[1]?.density ?? 0),
+        poor: Number(bins[2]?.density ?? 0),
+      },
+    });
+  }
+
+  const core = metrics.filter((m) => CORE_VITALS.includes(m.key));
+  let assessment = null;
+  if (core.length) {
+    if (core.some((m) => m.rating === "poor")) {
+      assessment = "poor";
+    } else if (core.some((m) => m.rating === "needs-improvement")) {
+      assessment = "needs-improvement";
+    } else {
+      assessment = "good";
+    }
+  }
+
+  return {
+    scope,
+    metrics,
+    assessment,
+    collectionPeriod: record.collectionPeriod ?? null,
+  };
+}
+
+// Report for a page CrUX has no field data for: the full card set with no
+// measurements, so the gauges render their bands and say "no data" rather than
+// showing a made-up p75. `rating` stays null — 0ms is an absence, not a pass.
+function emptyReport() {
+  return {
+    scope: "none",
+    noData: true,
+    assessment: null,
+    collectionPeriod: null,
+    metrics: CWV_METRICS.map((meta) => ({
+      ...meta,
+      p75: 0,
+      rating: null,
+      distribution: { good: 0, needsImprovement: 0, poor: 0 },
+    })),
+  };
+}
+
+const DEFAULT_FORM_FACTOR = "PHONE";
+
+// cacheKey identifies the resource behind pageUrl (see reportCacheKey in
+// reportsUtils) so one resource gets one entry; falls back to the URL.
+export async function pageWebVitals(
+  pageUrl,
+  ga,
+  { formFactor = DEFAULT_FORM_FACTOR, cacheKey } = {},
+) {
+  if (!cruxApiKeyConfigured(ga)) {
+    throw new Error(
+      "CrUX API key is not set. Set GOOGLE_API_KEY in the environment (surfaced via config.ga.apiKey) — CrUX does not accept the service account.",
+    );
+  }
+  if (!pageUrl) {
+    throw new Error("No public URL for this resource.");
+  }
+
+  const origin = new URL(pageUrl).origin;
+  const key = `crux:${formFactor ?? "all"}:${cacheKey || pageUrl}`;
+
+  return localCache.fetch(
+    key,
+    async () => {
+      const urlRecord = await query({ url: pageUrl }, ga, formFactor);
+
+      if (urlRecord) return shape(urlRecord, "url");
+
+      const originRecord = await query({ origin }, ga, formFactor);
+
+      if (originRecord) return shape(originRecord, "origin");
+
+      // CrUX 404s (both URL- and origin-level) when a site hasn't met the
+      // traffic threshold — common on preview/staging domains. Return the card
+      // set unmeasured; `noData` tells the view to say so.
+      return emptyReport();
+    },
+    { ttl: CWV_CACHE_TTL },
+  );
+}

package/src/helpers/reports/googleAuth.js

@@ -0,0 +1,149 @@
+// Service-account auth for the GA4 Data API (the Insights tab).
+//
+// GA is per-property authorized: it rejects API keys and needs a principal. The
+// key file at config.ga.serviceAccountPath (GOOGLE_APPLICATION_CREDENTIALS)
+// provides one with no human in the loop — sign a JWT with it, swap that for an
+// access token. Nothing is persisted, so a restart costs one token exchange.
+//
+// The key's client_email needs Viewer access on the GA property.
+import { createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const JWT_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+const SCOPE = "https://www.googleapis.com/auth/analytics.readonly";
+
+// Assertions are valid for an hour; ask for the same and refresh a minute early
+// so a token can't expire mid-flight.
+const TOKEN_LIFETIME_S = 3600;
+const EXPIRY_SKEW_MS = 60 * 1000;
+
+// Parsed key files by path, access tokens by client_email, plus the in-flight
+// token exchange per client_email (see accessToken).
+const keyCache = new Map();
+const tokenCache = new Map();
+const pendingTokens = new Map();
+
+// True when a key path is configured — gates the Insights tab, so an
+// unconfigured admin sees no GA UI at all.
+export const serviceAccountConfigured = (ga = {}) =>
+  Boolean(ga.serviceAccountPath);
+
+function serviceAccountKey(ga = {}) {
+  const path = ga.serviceAccountPath;
+
+  if (!path) {
+    throw new Error(
+      "Google service-account key is not set. Point GOOGLE_APPLICATION_CREDENTIALS at the key file (surfaced via config.ga.serviceAccountPath).",
+    );
+  }
+
+  if (keyCache.has(path)) return keyCache.get(path);
+
+  let key;
+  try {
+    key = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `Could not read the service-account key at ${path}: ${err.message}`,
+    );
+  }
+
+  if (!key.client_email || !key.private_key) {
+    throw new Error(
+      `The service-account key at ${path} has no client_email / private_key.`,
+    );
+  }
+
+  keyCache.set(path, key);
+  return key;
+}
+
+const base64url = (input) => Buffer.from(input).toString("base64url");
+
+// Self-signed JWT asserting "this service account, for this scope".
+function signAssertion(key) {
+  const issuedAt = Math.floor(Date.now() / 1000);
+
+  const header = base64url(
+    JSON.stringify({ alg: "RS256", typ: "JWT", kid: key.private_key_id }),
+  );
+  const claims = base64url(
+    JSON.stringify({
+      iss: key.client_email,
+      scope: SCOPE,
+      aud: key.token_uri || TOKEN_ENDPOINT,
+      iat: issuedAt,
+      exp: issuedAt + TOKEN_LIFETIME_S,
+    }),
+  );
+  const signature = createSign("RSA-SHA256")
+    .update(`${header}.${claims}`)
+    .sign(key.private_key, "base64url");
+
+  return `${header}.${claims}.${signature}`;
+}
+
+// Bearer token for the Data API, cached until shortly before it expires.
+//
+// Reports fire several GA calls at once, so on a cold (or just-expired) cache
+// they would each mint their own token. The in-flight exchange is shared: the
+// first caller starts it, the rest await the same promise.
+export async function accessToken(ga) {
+  const key = serviceAccountKey(ga);
+
+  const cached = tokenCache.get(key.client_email);
+  if (cached && cached.expiresAt > Date.now()) return cached.accessToken;
+
+  const pending = pendingTokens.get(key.client_email);
+  if (pending) return pending;
+
+  const exchange = requestToken(key).finally(() => {
+    pendingTokens.delete(key.client_email);
+  });
+
+  pendingTokens.set(key.client_email, exchange);
+
+  return exchange;
+}
+
+async function requestToken(key) {
+  const response = await fetch(key.token_uri || TOKEN_ENDPOINT, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: JWT_GRANT,
+      assertion: signAssertion(key),
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      `Google token request failed (${response.status}): ${body.slice(0, 200)}`,
+    );
+  }
+
+  const json = await response.json();
+
+  if (!json.access_token) {
+    throw new Error("Google token response contained no access_token.");
+  }
+
+  tokenCache.set(key.client_email, {
+    accessToken: json.access_token,
+    expiresAt:
+      Date.now() +
+      (json.expires_in ?? TOKEN_LIFETIME_S) * 1000 -
+      EXPIRY_SKEW_MS,
+  });
+
+  return json.access_token;
+}
+
+// Test / credential-rotation helper.
+export function clearAuthCache() {
+  keyCache.clear();
+  tokenCache.clear();
+  pendingTokens.clear();
+}

package/src/helpers/reports/quick-insights.js

@@ -0,0 +1,294 @@
+// GA4 Data API wrapper (admin-side).
+// Quick Insights for a single page path: summary KPIs with period-over-period
+// trend plus a daily page-views series, both over the last 30 days.
+//
+// `ga` below is the whole config.ga object — property id plus the key path the
+// bearer token is minted from (see ./googleAuth).
+import localCache from "../../localCache";
+import { accessToken } from "./googleAuth";
+
+// GA responses are large and change slowly — cache each bundle for 3 hours.
+const GA_CACHE_TTL = 1000 * 60 * 60 * 3;
+
+const GA_ENDPOINT = "https://analyticsdata.googleapis.com/v1beta";
+
+function propertyId(ga = {}) {
+  const id = ga.propertyId;
+  if (!id || id === "YOUR-GA4-PROPERTY-ID") {
+    throw new Error(
+      "GA property id is not set. Set GA_PROPERTY_ID in the environment (surfaced via config.ga.propertyId).",
+    );
+  }
+  return id;
+}
+
+// One POST to the Data API. `method` is the endpoint suffix — runReport for a
+// single report, batchRunReports for several in one round trip.
+async function post(method, body, ga) {
+  const response = await fetch(
+    `${GA_ENDPOINT}/properties/${propertyId(ga)}:${method}`,
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${await accessToken(ga)}`,
+      },
+      body: JSON.stringify(body),
+    },
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`GA Data API ${response.status}: ${text.slice(0, 200)}`);
+  }
+
+  return response.json();
+}
+
+const runReport = (body, ga) => post("runReport", body, ga);
+
+// Several reports, one HTTP request. The property is in the URL, so the
+// individual requests must not repeat it.
+async function batchRunReports(requests, ga) {
+  const json = await post("batchRunReports", { requests }, ga);
+  return json.reports ?? [];
+}
+
+// pagePath EXACT-match filter. Returns undefined when no pagePath is given so
+// the same run* helpers double as site-wide (property-level) reports.
+function pageFilter(pagePath) {
+  if (!pagePath) return undefined;
+  return {
+    filter: {
+      fieldName: "pagePath",
+      stringFilter: { matchType: "EXACT", value: pagePath },
+    },
+  };
+}
+
+const num = (v) => Number(v ?? 0);
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+// "YYYYMMDD" -> "YYYY-MM-DD"
+function fmtDate(d) {
+  return d && d.length === 8
+    ? `${d.slice(0, 4)}-${d.slice(4, 6)}-${d.slice(6, 8)}`
+    : d;
+}
+
+// Every day in [startDate,endDate] — used to backfill days GA omits (it
+// returns no row for zero-activity days, leaving gaps in the chart).
+function expectedDays(startDate, endDate) {
+  if (!ISO_DATE.test(startDate ?? "") || !ISO_DATE.test(endDate ?? "")) {
+    return null;
+  }
+  const end = new Date(`${endDate}T00:00:00Z`);
+  const out = [];
+  for (
+    const d = new Date(`${startDate}T00:00:00Z`);
+    d <= end;
+    d.setUTCDate(d.getUTCDate() + 1)
+  ) {
+    out.push(d.toISOString().slice(0, 10));
+  }
+  return out;
+}
+
+// Given absolute ISO dates, the immediately-preceding period of equal length.
+function previousRange(startDate, endDate) {
+  const s = new Date(`${startDate}T00:00:00Z`);
+  const e = new Date(`${endDate}T00:00:00Z`);
+  const days = Math.round((e - s) / 86400000) + 1;
+  const prevEnd = new Date(s.getTime() - 86400000);
+  const prevStart = new Date(prevEnd.getTime() - (days - 1) * 86400000);
+  const iso = (d) => d.toISOString().slice(0, 10);
+  return { startDate: iso(prevStart), endDate: iso(prevEnd) };
+}
+
+// % change current vs previous. null when there is nothing to divide by — a
+// zero baseline has no percentage, so every metric ships its previous value
+// too and the page can tell "brand new" from "never measured".
+function trend(cur, prev) {
+  if (!prev) return null;
+  return ((cur - prev) / prev) * 100;
+}
+
+// Names for the two periods a summary compares. runReport takes up to four
+// date ranges at once, so both periods come back from a single request; GA
+// tags each row with a synthetic "dateRange" dimension carrying these names.
+const CURRENT_RANGE = "current";
+const PREVIOUS_RANGE = "previous";
+const RANGE_DIMENSION = "dateRange";
+
+const summaryRequest = ({ pagePath, startDate, endDate }) => ({
+  metrics: [
+    { name: "screenPageViews" },
+    { name: "activeUsers" },
+    { name: "userEngagementDuration" },
+    { name: "engagementRate" },
+    { name: "sessions" },
+  ],
+  dateRanges: [
+    { startDate, endDate, name: CURRENT_RANGE },
+    { ...previousRange(startDate, endDate), name: PREVIOUS_RANGE },
+  ],
+  dimensionFilter: pageFilter(pagePath),
+});
+
+function parseSummary(response) {
+  // Only the synthetic dimension is asked for, so it sits first — but read its
+  // position off the headers rather than assume it.
+  const headers = response.dimensionHeaders ?? [];
+  const rangeAt = Math.max(
+    headers.findIndex((header) => header.name === RANGE_DIMENSION),
+    0,
+  );
+
+  // A period with no traffic gets no row at all, which reads as zeros.
+  const period = (name) => {
+    const row = (response.rows ?? []).find(
+      (r) => r.dimensionValues?.[rangeAt]?.value === name,
+    );
+    const m = row?.metricValues ?? [];
+
+    return {
+      views: num(m[0]?.value),
+      users: num(m[1]?.value),
+      engagementSeconds: num(m[2]?.value),
+      engagementRate: num(m[3]?.value),
+      sessions: num(m[4]?.value),
+    };
+  };
+
+  const cur = period(CURRENT_RANGE);
+  const prev = period(PREVIOUS_RANGE);
+
+  const avgDur = (x) => (x.sessions ? x.engagementSeconds / x.sessions : 0);
+
+  return {
+    views: {
+      value: cur.views,
+      previous: prev.views,
+      trend: trend(cur.views, prev.views),
+    },
+    users: {
+      value: cur.users,
+      previous: prev.users,
+      trend: trend(cur.users, prev.users),
+    },
+    avgDuration: {
+      seconds: avgDur(cur),
+      previous: avgDur(prev),
+      trend: trend(avgDur(cur), avgDur(prev)),
+    },
+    engagement: {
+      rate: cur.engagementRate,
+      previous: prev.engagementRate,
+      trend: trend(cur.engagementRate, prev.engagementRate),
+    },
+  };
+}
+
+// Summary KPIs with period-over-period trend (needs absolute ISO dates).
+export async function runSummary({ pagePath, startDate, endDate, ga }) {
+  return parseSummary(
+    await runReport(summaryRequest({ pagePath, startDate, endDate }), ga),
+  );
+}
+
+// The chart plots views and nothing else, so that is all the report asks for.
+const seriesRequest = ({ pagePath, startDate, endDate }) => ({
+  dimensions: [{ name: "date" }],
+  metrics: [{ name: "screenPageViews" }],
+  dateRanges: [{ startDate, endDate }],
+  dimensionFilter: pageFilter(pagePath),
+  orderBys: [{ dimension: { dimensionName: "date" } }],
+});
+
+function parseSeries(response, { startDate, endDate }) {
+  const returned = (response.rows ?? []).map((row) => ({
+    date: fmtDate(row.dimensionValues?.[0]?.value),
+    views: num(row.metricValues?.[0]?.value),
+  }));
+
+  // Backfill days GA omitted for zero-activity periods so the chart line
+  // stays continuous (no false gaps between non-adjacent dates).
+  const days = expectedDays(startDate, endDate);
+  let rows = returned;
+  if (days) {
+    const byDate = new Map(returned.map((r) => [r.date, r]));
+    rows = days.map((date) => byDate.get(date) ?? { date, views: 0 });
+  }
+
+  return { rows, dateRange: { startDate, endDate } };
+}
+
+// Daily page-views series for one page.
+export async function runPageReport({ pagePath, startDate, endDate, ga }) {
+  const response = await runReport(
+    seriesRequest({ pagePath, startDate, endDate }),
+    ga,
+  );
+
+  return parseSeries(response, { startDate, endDate });
+}
+
+// The server's calendar date, not the UTC one. toISOString answers in UTC, so
+// on a host behind or ahead of it the window would start and end on the wrong
+// day for part of every day.
+//
+// GA reads these dates in the property's own timezone, so a property that
+// doesn't share the server's timezone can still be a day out at the edges —
+// that one needs config.ga.timezone and is not what this fixes.
+const localDay = (date) =>
+  [
+    date.getFullYear(),
+    String(date.getMonth() + 1).padStart(2, "0"),
+    String(date.getDate()).padStart(2, "0"),
+  ].join("-");
+
+// Last-N-days window ending today.
+function lastNDays(days = 30) {
+  const end = new Date();
+  const start = new Date();
+  start.setDate(end.getDate() - (days - 1));
+  return { startDate: localDay(start), endDate: localDay(end) };
+}
+
+// Quick Insights for a page path: summary KPIs and the daily views series over
+// the last 30 days. Swallows nothing — caller handles errors.
+//
+// cacheKey identifies the resource this path belongs to (see reportCacheKey in
+// reportsUtils) so one resource gets one entry; it falls back to the path for
+// callers that have no resource at hand.
+export async function pageInsights(pagePath, ga, { cacheKey } = {}) {
+  const { startDate, endDate } = lastNDays(30);
+  const key = `ga:insights:${cacheKey || pagePath}`;
+
+  return localCache.fetch(
+    key,
+    async () => {
+      // Three periods over two report shapes, one HTTP request: the summary
+      // asks for its current and previous period as two date ranges, and it
+      // rides along with the daily series in a batch. The two can't collapse
+      // into a single report — the series is broken down by date and the
+      // summary isn't, and totals over a rate metric are not a number we want
+      // to infer.
+      const [summary, series] = await batchRunReports(
+        [
+          summaryRequest({ pagePath, startDate, endDate }),
+          seriesRequest({ pagePath, startDate, endDate }),
+        ],
+        ga,
+      );
+
+      return {
+        summary: parseSummary(summary ?? {}),
+        rows: parseSeries(series ?? {}, { startDate, endDate }).rows,
+        dateRange: { startDate, endDate },
+      };
+    },
+    { ttl: GA_CACHE_TTL },
+  );
+}