@cardinali-studio/adminkit 1.0.0

package/dist/functions/_shared/analytics-ga4.js

@@ -0,0 +1,248 @@
+/* Driver Google Analytics 4 per la Panoramica.
+ *
+ * Stesse due domande dell'altro driver («sei configurato?», «dammi i numeri»), stesso formato
+ * di risposta: il pannello non sa quale dei due sta guardando.
+ *
+ * ── Configurazione ─────────────────────────────────────────────────────────────────────────
+ *   GA4_PROPERTY_ID       var — il numero della proprietà GA4 (Amministrazione → Proprietà →
+ *                         Dettagli proprietà). NON è il "measurement ID" `G-XXXXXXX`, che
+ *                         invece sta nel tag: sbagliarli dà un 403 che sembra un problema di
+ *                         permessi.
+ *   GA4_SERVICE_ACCOUNT   secret Pages — il file JSON della chiave del service account, INTERO.
+ *
+ * ── Perché un service account e non l'OAuth che c'è già ────────────────────────────────────
+ * Il sito ha già un OAuth Google per le Prenotazioni (`google-calendar.js`), e verrebbe voglia
+ * di aggiungergli lo scope `analytics.readonly`. Non si fa, per tre ragioni concrete:
+ *
+ *   1. `accessToken()` di quel modulo SCRIVE lo stato della connessione Calendar a ogni
+ *      chiamata (`token_status = 'connected' | 'error'`). Un errore su una lettura di
+ *      statistiche marcherebbe come rotto il sistema delle prenotazioni;
+ *   2. le statistiche smetterebbero di funzionare il giorno in cui si scollega il Calendar,
+ *      che è una cosa che non c'entra niente;
+ *   3. la schermata di consenso chiederebbe l'accesso ad Analytics anche a chi vuole solo le
+ *      prenotazioni.
+ *
+ * Un service account è anche la strada normale per una lettura server-to-server: nessun
+ * consenso da rinnovare e nessun refresh token da custodire. L'unico passo manuale è aggiungere
+ * la sua email come **Visualizzatore** sulla proprietà GA4, altrimenti risponde 403.
+ */
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const API = "https://analyticsdata.googleapis.com/v1beta";
+const SCOPE = "https://www.googleapis.com/auth/analytics.readonly";
+
+export const id = "ga4";
+export const label = "Google Analytics";
+export const config = [
+  { name: "GA4_PROPERTY_ID", secret: false },
+  { name: "GA4_SERVICE_ACCOUNT", secret: true },
+];
+
+export function missing(env) {
+  return config.filter((c) => !env[c.name]);
+}
+
+export async function collect(env, { startAt, endAt, unit }) {
+  const token = await accessToken(env);
+  const current = { startDate: day(startAt), endDate: day(endAt) };
+  /* Il periodo precedente ha la STESSA durata e finisce il giorno prima dell'inizio di questo:
+   * è ciò che rende confrontabili le due cifre della pillola di variazione. */
+  const span = endAt - startAt;
+  const previous = { startDate: day(startAt - span), endDate: day(startAt - 86_400_000) };
+
+  /* GA4 non ha un endpoint "stats": è sempre `runReport`, cambiano dimensioni e metriche.
+   * Le quattro insieme per la stessa ragione dell'altro driver. Le due di contorno possono
+   * cadere da sole senza portarsi via la scheda. */
+  const [totals, series, pages, referrers] = await Promise.all([
+    report(token, env, {
+      dateRanges: [current, previous],
+      metrics: names("screenPageViews", "totalUsers", "sessions", "bounceRate", "userEngagementDuration"),
+    }),
+    report(token, env, {
+      dateRanges: [current],
+      dimensions: names(unit === "hour" ? "dateHour" : "date"),
+      metrics: names("screenPageViews", "sessions"),
+      orderBys: [{ dimension: { dimensionName: unit === "hour" ? "dateHour" : "date" } }],
+      limit: 400,
+    }),
+    report(token, env, {
+      dateRanges: [current],
+      dimensions: names("pagePath"),
+      metrics: names("screenPageViews"),
+      orderBys: [{ metric: { metricName: "screenPageViews" }, desc: true }],
+      limit: 6,
+    }).catch(() => null),
+    report(token, env, {
+      dateRanges: [current],
+      dimensions: names("sessionSource"),
+      metrics: names("sessions"),
+      orderBys: [{ metric: { metricName: "sessions" }, desc: true }],
+      limit: 8,
+    }).catch(() => null),
+  ]);
+
+  const now = periodRow(totals, 0);
+  const before = periodRow(totals, 1);
+
+  return {
+    totals: {
+      pageviews: metric(now.screenPageViews, before.screenPageViews),
+      visitors: metric(now.totalUsers, before.totalUsers),
+      visits: metric(now.sessions, before.sessions),
+      /* `bounceRate` è una FRAZIONE, non un conteggio: moltiplicata per le sessioni torna a
+       * essere la stessa cosa che manda Umami. Il pannello oggi non la mostra, ma il campo
+       * deve contenere ciò che il suo nome promette, o al primo riquadro nuovo si scopre di
+       * avere una percentuale al posto di un numero. */
+      bounces: metric(now.bounceRate * now.sessions, before.bounceRate * before.sessions),
+      totaltime: metric(now.userEngagementDuration, before.userEngagementDuration),
+    },
+    series: (series?.rows || []).map((row) => ({
+      date: stamp(dim(row, 0), unit),
+      pageviews: num(met(row, 0)),
+      sessions: num(met(row, 1)),
+    })).sort((a, b) => a.date.localeCompare(b.date)),
+    pages: topList(pages),
+    /* `(direct)` e `(not set)` non sono siti che portano traffico: sono l'assenza di un sito.
+     * Il riquadro si chiama «Da dove arrivano» e mostrarli lì sarebbe una risposta sbagliata
+     * alla domanda scritta sopra l'elenco. */
+    referrers: topList(referrers).filter((r) => r.name && !/^\(.*\)$/.test(r.name)).slice(0, 6),
+  };
+}
+
+async function report(token, env, body) {
+  const property = String(env.GA4_PROPERTY_ID).replace(/^properties\//, "");
+  const res = await fetch(`${API}/properties/${encodeURIComponent(property)}:runReport`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    /* Il messaggio di Google finisce nell'errore: un 403 «User does not have sufficient
+     * permissions» (service account non aggiunto alla proprietà) e un 400 su un id sbagliato
+     * si curano in due modi diversi, e dal solo numero non si distinguono. */
+    const detail = await res.json().catch(() => null);
+    const text = detail?.error?.message || (await res.text().catch(() => "")).slice(0, 200);
+    throw new Error(`Google Analytics ha risposto ${res.status}${text ? `: ${text}` : ""}`);
+  }
+  return res.json();
+}
+
+/* ---- Autenticazione: JWT firmato, scambiato per un access token ------------------------- */
+
+async function accessToken(env) {
+  let key;
+  try {
+    key = JSON.parse(env.GA4_SERVICE_ACCOUNT);
+  } catch {
+    throw new Error("GA4_SERVICE_ACCOUNT non contiene il JSON della chiave del service account");
+  }
+  if (!key.client_email || !key.private_key) {
+    throw new Error("Nel JSON del service account mancano client_email o private_key");
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const claims = {
+    iss: key.client_email,
+    scope: SCOPE,
+    aud: key.token_uri || TOKEN_URL,
+    iat: now,
+    exp: now + 3600,
+  };
+  const unsigned = `${b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }))}.${b64url(JSON.stringify(claims))}`;
+  const signature = await crypto.subtle.sign(
+    "RSASSA-PKCS1-v1_5",
+    await importPrivateKey(key.private_key),
+    new TextEncoder().encode(unsigned),
+  );
+  const assertion = `${unsigned}.${b64urlBytes(new Uint8Array(signature))}`;
+
+  const res = await fetch(key.token_uri || TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion,
+    }),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || !data.access_token) {
+    throw new Error(
+      `Google non ha rilasciato il token: ${data.error_description || data.error || res.status}`,
+    );
+  }
+  return data.access_token;
+}
+
+/* La chiave arriva come PEM PKCS#8 dentro il JSON. `JSON.parse` ha già trasformato le sequenze
+ * `\n` in a capo veri, quindi qui restano da togliere solo intestazione, coda e spaziatura. */
+async function importPrivateKey(pem) {
+  const body = String(pem)
+    .replace(/-----BEGIN [^-]+-----/, "")
+    .replace(/-----END [^-]+-----/, "")
+    .replace(/\s+/g, "");
+  const bytes = Uint8Array.from(atob(body), (c) => c.charCodeAt(0));
+  return crypto.subtle.importKey(
+    "pkcs8",
+    bytes,
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+}
+
+function b64url(text) {
+  return b64urlBytes(new TextEncoder().encode(text));
+}
+
+function b64urlBytes(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/* ---- Lettura della risposta ------------------------------------------------------------- */
+
+/* Con più `dateRanges`, GA4 aggiunge da sé una dimensione `dateRange` con valori
+ * `date_range_0` / `date_range_1`, e le righe NON arrivano in ordine garantito: si cerca
+ * quella giusta invece di prendere `rows[i]`. Se manca (periodo senza dati) si torna zeri, che
+ * è il caso di un sito appena messo online. */
+function periodRow(response, index) {
+  const headers = (response?.metricHeaders || []).map((h) => h.name);
+  const want = `date_range_${index}`;
+  const row = (response?.rows || []).find(
+    (r) => (r.dimensionValues || []).some((d) => d.value === want),
+  ) || (response?.rows || [])[index];
+  const out = {};
+  headers.forEach((name, i) => { out[name] = num(row?.metricValues?.[i]?.value); });
+  return out;
+}
+
+function metric(value, prev) {
+  return { value: num(value), prev: Number.isFinite(prev) ? num(prev) : null };
+}
+
+/* GA4 dà `20260728` (e `2026072814` a ore); il pannello legge il formato di Umami. Senza
+ * questa conversione il grafico si riempie di «Invalid Date» in silenzio — l'asse resta
+ * disegnato, e a mancare sono solo le etichette. */
+function stamp(raw, unit) {
+  const v = String(raw || "");
+  const date = `${v.slice(0, 4)}-${v.slice(4, 6)}-${v.slice(6, 8)}`;
+  const hour = unit === "hour" ? v.slice(8, 10) || "00" : "00";
+  return `${date} ${hour}:00:00`;
+}
+
+function topList(response) {
+  return (response?.rows || []).map((row) => ({
+    name: String(dim(row, 0) || ""),
+    count: num(met(row, 0)),
+  }));
+}
+
+function names(...list) { return list.map((name) => ({ name })); }
+function dim(row, i) { return row?.dimensionValues?.[i]?.value; }
+function met(row, i) { return row?.metricValues?.[i]?.value; }
+function num(v) { const n = Number(v); return Number.isFinite(n) ? n : 0; }
+function day(ms) { return new Date(ms).toISOString().slice(0, 10); }

package/dist/functions/_shared/analytics-umami.js

@@ -0,0 +1,119 @@
+/* Driver Umami per la Panoramica.
+ *
+ * Un driver risponde a due domande e basta: «sei configurato?» e «dammi i numeri di questa
+ * finestra temporale». Il formato del risultato è quello che il pannello sa leggere, ed è lo
+ * stesso per tutti i driver (vedi `analytics-ga4.js`): chi aggiunge un servizio nuovo non
+ * tocca né l'endpoint né l'interfaccia.
+ *
+ * Configurazione:
+ *   UMAMI_WEBSITE_ID   var — l'id del sito dentro Umami (Settings → Websites)
+ *   UMAMI_API_KEY      secret Pages (Settings → API keys)
+ *   UMAMI_API_URL      opzionale. Assente = Umami Cloud. Un'istanza propria si dichiara qui
+ *                      (es. https://analytics.esempio.it/api) e cambia SOLO l'intestazione di
+ *                      autenticazione: il Cloud vuole `x-umami-api-key`, un'istanza propria un
+ *                      `Bearer`. Le rotte dei dati sono identiche.
+ */
+const CLOUD = "https://api.umami.is/v1";
+
+/* Il fuso decide DOVE cade la mezzanotte, cioè quali visite finiscono nella colonna «oggi».
+ * Senza, Umami usa UTC e d'estate le due ore di sera scivolano nel giorno dopo. */
+const TZ = "Europe/Rome";
+
+export const id = "umami";
+export const label = "Umami";
+/* `secret: true` non è decorazione: è ciò che permette al pannello di dire «questa va in
+   wrangler.toml» e «questa si mette con `wrangler pages secret put`» senza conoscere i
+   servizi uno per uno. */
+export const config = [
+  { name: "UMAMI_WEBSITE_ID", secret: false },
+  { name: "UMAMI_API_KEY", secret: true },
+];
+
+export function missing(env) {
+  return config.filter((c) => !env[c.name]);
+}
+
+export async function collect(env, { startAt, endAt, unit }) {
+  const window = { startAt, endAt };
+
+  /* Le quattro chiamate insieme: sono indipendenti e in fila costerebbero la somma delle
+   * latenze di un servizio esterno. Se cade una sola delle tre di contorno la scheda mostra
+   * il resto — le visite in cima sono l'unica senza cui non c'è niente da vedere. */
+  const [totals, series, pages, referrers] = await Promise.all([
+    call(env, "/stats", window),
+    call(env, "/pageviews", { ...window, unit, timezone: TZ }),
+    call(env, "/metrics", { ...window, type: "url", limit: 6 }).catch(() => []),
+    call(env, "/metrics", { ...window, type: "referrer", limit: 6 }).catch(() => []),
+  ]);
+
+  return {
+    totals: {
+      pageviews: metric(totals?.pageviews),
+      visitors: metric(totals?.visitors),
+      visits: metric(totals?.visits),
+      bounces: metric(totals?.bounces),
+      totaltime: metric(totals?.totaltime),
+    },
+    series: mergeSeries(series),
+    pages: topList(pages),
+    referrers: topList(referrers).filter((r) => r.name),
+  };
+}
+
+async function call(env, path, params) {
+  const base = String(env.UMAMI_API_URL || CLOUD).replace(/\/+$/, "");
+  const url = new URL(`${base}/websites/${encodeURIComponent(env.UMAMI_WEBSITE_ID)}${path}`);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));
+
+  const key = env.UMAMI_API_KEY;
+  const headers = base.startsWith(CLOUD)
+    ? { "x-umami-api-key": key, Accept: "application/json" }
+    : { Authorization: `Bearer ${key}`, Accept: "application/json" };
+
+  const res = await fetch(url.toString(), { headers, cf: { cacheTtl: 0 } });
+  if (!res.ok) {
+    /* Il corpo di Umami finisce nel messaggio: un 401 e un «website not found» si curano in
+     * due modi diversi (chiave sbagliata contro id sbagliato) e distinguerli guardando solo
+     * il numero è impossibile. */
+    const body = (await res.text().catch(() => "")).slice(0, 200);
+    throw new Error(`Umami ha risposto ${res.status}${body ? `: ${body}` : ""}`);
+  }
+  return res.json();
+}
+
+/* Umami restituisce `{ value, prev }` per ogni statistica, ma le versioni più vecchie (e le
+ * istanze proprie non aggiornate) danno un numero secco. Accettarli entrambi costa tre righe e
+ * evita una scheda vuota su un'istanza che risponde benissimo. */
+function metric(raw) {
+  if (raw && typeof raw === "object") {
+    return { value: num(raw.value), prev: raw.prev === undefined ? null : num(raw.prev) };
+  }
+  return { value: num(raw), prev: null };
+}
+
+/* Due serie parallele (viste e sessioni) con la stessa asse dei tempi, che però Umami manda
+ * separate e non garantisce allineate: un'ora senza sessioni manca da una delle due liste.
+ * Si uniscono per data, così il grafico non disegna due curve sfasate. */
+function mergeSeries(raw) {
+  const byDate = new Map();
+  const put = (list, field) => {
+    for (const point of Array.isArray(list) ? list : []) {
+      const date = String(point?.x ?? "");
+      if (!date) continue;
+      const row = byDate.get(date) || { date, pageviews: 0, sessions: 0 };
+      row[field] = num(point?.y);
+      byDate.set(date, row);
+    }
+  };
+  put(raw?.pageviews, "pageviews");
+  put(raw?.sessions, "sessions");
+  return [...byDate.values()].sort((a, b) => a.date.localeCompare(b.date));
+}
+
+function topList(raw) {
+  return (Array.isArray(raw) ? raw : [])
+    .map((row) => ({ name: String(row?.x ?? ""), count: num(row?.y) }))
+    .slice(0, 6);
+}
+
+function num(v) { const n = Number(v); return Number.isFinite(n) ? n : 0; }

package/dist/functions/_shared/assets.js

@@ -0,0 +1,90 @@
+/* Helper condivisi per il media manager (R2 binding env.MEDIA). */
+
+// prefisso cartella: vuoto (root) oppure segmenti che finiscono con "/"
+export const PREFIX_RE = /^([A-Za-z0-9._-]+\/)+$/;
+// chiave file: segmenti-cartella + nome file finale
+export const KEY_RE = /^([A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+
+// blocca traversal (segmento ".." o "."), backslash, doppie slash
+function unsafe(s) { return /(^|\/)\.\.?(\/|$)/.test(s) || s.includes("\\") || s.includes("//"); }
+
+export function isPrefix(p) { return p === "" || (!unsafe(p) && PREFIX_RE.test(p)); }
+export function isKey(k) { return !!k && !k.endsWith("/") && !unsafe(k) && KEY_RE.test(k); }
+
+export function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status, headers: { "Content-Type": "application/json" },
+  });
+}
+
+// Nome file sicuro: minuscolo, senza spazi/caratteri strani, estensione preservata.
+export function sanitizeName(name) {
+  const raw = String(name || "file");
+  const dot = raw.lastIndexOf(".");
+  let base = dot > 0 ? raw.slice(0, dot) : raw;
+  let ext = dot > 0 ? raw.slice(dot + 1) : "";
+  base = base.toLowerCase().normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "file";
+  ext = ext.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  return ext ? `${base}.${ext}` : base;
+}
+
+export function guessMime(key) {
+  const e = (key.split(".").pop() || "").toLowerCase();
+  return {
+    jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", webp: "image/webp",
+    gif: "image/gif", avif: "image/avif", svg: "image/svg+xml",
+    mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime", pdf: "application/pdf",
+  }[e] || "application/octet-stream";
+}
+
+// Prefisso del cestino (soft-delete). La lifecycle rule R2 purga qui dopo 30 giorni.
+export const TRASH = "_trash/";
+
+// Elenca tutte le chiavi sotto un prefisso (paginato).
+export async function listKeysUnder(bucket, prefix) {
+  const keys = [];
+  let cursor;
+  do {
+    const listed = await bucket.list({ prefix, cursor, limit: 1000 });
+    for (const o of (listed.objects || [])) keys.push(o.key);
+    cursor = listed.truncated ? listed.cursor : undefined;
+  } while (cursor);
+  return keys;
+}
+
+// Soft-delete: sposta un oggetto nel cestino conservando chiave originale e data.
+// (R2 non ha "move": copia + delete. La nuova data d'upload = quando entra nel cestino,
+//  così i 30 giorni della lifecycle partono da adesso, per-file.)
+export async function moveToTrash(bucket, key) {
+  const obj = await bucket.get(key);
+  if (!obj) return null;
+  const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const trashKey = TRASH + id;
+  await bucket.put(trashKey, obj.body, {
+    httpMetadata: obj.httpMetadata || {},
+    customMetadata: {
+      ...(obj.customMetadata || {}),
+      originalKey: key,
+      originalName: key.split("/").pop(),
+      deletedAt: new Date().toISOString(),
+    },
+  });
+  await bucket.delete(key);
+  return trashKey;
+}
+
+// Restituisce una chiave non ancora usata nel bucket (evita sovrascritture accidentali).
+export async function uniqueKey(bucket, prefix, filename) {
+  const name = sanitizeName(filename);
+  const dot = name.lastIndexOf(".");
+  const base = dot > 0 ? name.slice(0, dot) : name;
+  const ext = dot > 0 ? name.slice(dot) : "";
+  let candidate = prefix + name;
+  for (let n = 2; n <= 999; n++) {
+    const head = await bucket.head(candidate);
+    if (!head) return candidate;
+    candidate = `${prefix}${base}-${n}${ext}`;
+  }
+  return `${prefix}${base}-${Date.now()}${ext}`;
+}