@bygghammar/cms-platform 0.90.0-m7.9 → 0.91.0

package/src/server/google-sheets-core.ts

@@ -0,0 +1,463 @@
+/**
+ * Google Sheets delivery.
+ *
+ * The spreadsheet does not have to be public: a service account is granted
+ * access the same way a colleague would be, by sharing the sheet with its email
+ * address. Everything here runs on the server — the browser never sees a
+ * credential, and no Google key is needed in any client bundle.
+ *
+ * `testGoogleSheetConnection` verifies exactly what a real submission needs
+ * (credentials, spreadsheet, worksheet, write permission) using a metadata
+ * read, so testing never leaves a junk row behind.
+ */
+
+import {
+  GOOGLE_SA_EMAIL_ENV,
+  GOOGLE_SA_KEY_ENV,
+  GoogleAuthError,
+  googleAccessToken,
+  googleErrorDetail,
+  googleRequestSignal,
+  googleServiceAccountEmail,
+  resolveGoogleCredentials,
+  SHEETS_SCOPE,
+  SHEETS_TEST_SCOPE,
+  type GoogleFetch,
+} from "./google-service-account";
+import type { Env } from "./provider-secrets";
+
+export const SHEETS_API = "https://sheets.googleapis.com/v4/spreadsheets";
+
+/** Default worksheet name Google gives a brand new spreadsheet. */
+export const DEFAULT_WORKSHEET = "Sheet1";
+
+/** Every distinct way a Sheets call can fail, so the admin UI can be specific. */
+export type SheetsErrorCode =
+  | "credentials-missing"
+  | "credentials-invalid"
+  | "invalid-spreadsheet-id"
+  | "spreadsheet-not-found"
+  | "permission-denied"
+  | "worksheet-not-found"
+  | "write-unconfirmed"
+  | "api-unavailable";
+
+export type SheetsFailure = {
+  ok: false;
+  code: SheetsErrorCode;
+  /** Safe to show an administrator: never contains a key, token or row data. */
+  error: string;
+  /** The address to share the sheet with, when the server has one. */
+  serviceAccountEmail: string | null;
+  /** Worksheet names that do exist, when the tab was the problem. */
+  worksheets?: string[];
+};
+
+export type SheetsTestSuccess = {
+  ok: true;
+  serviceAccountEmail: string;
+  spreadsheetTitle: string;
+  worksheetTitle: string;
+  worksheets: string[];
+  /**
+   * Always `true` here. A connection is only called successful once Drive has
+   * confirmed the account may edit the file — write access that could not be
+   * checked is {@link SheetsTestUnconfirmed}, not a success with a caveat.
+   */
+  canWrite: true;
+};
+
+/**
+ * The spreadsheet and tab are right, and write access could not be verified.
+ *
+ * Its own outcome rather than a footnote on a success, because the difference
+ * matters to the person reading the screen: "this will work" and "this may
+ * fail on the first submission" are not the same sentence, and the second one
+ * printed under a green "Connection works." is the one nobody acts on. `ok` is
+ * false so no caller can mistake it for a guarantee; the spreadsheet details
+ * still come back so the screen stays useful.
+ */
+export type SheetsTestUnconfirmed = {
+  ok: false;
+  code: "write-unconfirmed";
+  error: string;
+  serviceAccountEmail: string;
+  spreadsheetTitle: string;
+  worksheetTitle: string;
+  worksheets: string[];
+  canWrite: null;
+};
+
+export type SheetsTestResult = SheetsTestSuccess | SheetsTestUnconfirmed | SheetsFailure;
+export type SheetsAppendResult = { ok: true } | SheetsFailure;
+
+/** The part of Google's append response that says what was actually written. */
+type AppendResponse = { updates?: { updatedRows?: unknown } };
+
+export type SheetTarget = {
+  /** Spreadsheet ID or a full Google Sheets URL. */
+  spreadsheetId: string;
+  /** Worksheet (tab) name. Empty means `Sheet1`. */
+  tab?: string | null;
+};
+
+/** Google's own ID shape: base64url-ish, always well over 20 characters. */
+const ID_RE = /^[A-Za-z0-9_-]{20,}$/;
+
+/**
+ * Accept either a bare ID or a pasted URL — editors copy the address bar far
+ * more often than they dig the ID out of it.
+ */
+export function normalizeSpreadsheetId(input: string | null | undefined): string {
+  const raw = (input ?? "").trim();
+  if (!raw) return "";
+  const fromUrl = /\/spreadsheets\/d\/([A-Za-z0-9_-]+)/.exec(raw);
+  const candidate = fromUrl ? fromUrl[1]! : raw;
+  return ID_RE.test(candidate) ? candidate : "";
+}
+
+/** Worksheet name to use, with Google's default for an empty setting. */
+export function normalizeWorksheet(tab: string | null | undefined): string {
+  return (tab ?? "").trim() || DEFAULT_WORKSHEET;
+}
+
+/**
+ * A1 range covering a whole worksheet.
+ *
+ * The name is always single-quoted, with internal apostrophes doubled. Google
+ * requires quoting for names containing spaces or anything that could read as a
+ * cell reference, and quoting a plain name is harmless — so quote every time
+ * rather than trying to decide which names need it. Google's own default tab,
+ * "Form Responses 1", contains spaces.
+ */
+export function sheetRange(tab: string): string {
+  return `'${tab.replace(/'/g, "''")}'!A:Z`;
+}
+
+function credentialsMissing(): SheetsFailure {
+  return {
+    ok: false,
+    code: "credentials-missing",
+    error: `No Google service account is configured on this server. Set ${GOOGLE_SA_EMAIL_ENV} and ${GOOGLE_SA_KEY_ENV}, then restart.`,
+    serviceAccountEmail: null,
+  };
+}
+
+function fromAuthError(err: GoogleAuthError, email: string | null): SheetsFailure {
+  return { ok: false, code: err.code, error: err.message, serviceAccountEmail: email };
+}
+
+/**
+ * Turn one Google HTTP response into a classified failure.
+ *
+ * `detail` comes from {@link googleErrorDetail}, which only ever returns
+ * Google's own truncated status text.
+ */
+async function classify(res: Response, email: string | null): Promise<SheetsFailure> {
+  const detail = await googleErrorDetail(res);
+  if (res.status === 401) {
+    return {
+      ok: false,
+      code: "credentials-invalid",
+      error: `Google rejected the service account credentials${detail ? ` (${detail})` : ""}.`,
+      serviceAccountEmail: email,
+    };
+  }
+  if (res.status === 403) {
+    return {
+      ok: false,
+      code: "permission-denied",
+      error: email
+        ? `The service account cannot open this spreadsheet. Share it with ${email} and give it Editor access.`
+        : "The service account cannot open this spreadsheet. Share it with the service account and give it Editor access.",
+      serviceAccountEmail: email,
+    };
+  }
+  if (res.status === 404) {
+    return {
+      ok: false,
+      code: "spreadsheet-not-found",
+      error: "No spreadsheet with that ID exists. Check the Spreadsheet ID.",
+      serviceAccountEmail: email,
+    };
+  }
+  if (res.status === 400 && /unable to parse range|not found/i.test(detail)) {
+    return {
+      ok: false,
+      code: "worksheet-not-found",
+      error: "That worksheet (tab) does not exist in the spreadsheet.",
+      serviceAccountEmail: email,
+    };
+  }
+  if (res.status >= 500) {
+    return {
+      ok: false,
+      code: "api-unavailable",
+      error: `Google Sheets is unavailable right now (HTTP ${res.status}). Try again shortly.`,
+      serviceAccountEmail: email,
+    };
+  }
+  return {
+    ok: false,
+    code: "api-unavailable",
+    error: `Google Sheets returned HTTP ${res.status}${detail ? `: ${detail}` : ""}.`,
+    serviceAccountEmail: email,
+  };
+}
+
+type Metadata = {
+  properties?: { title?: string };
+  sheets?: { properties?: { title?: string } }[];
+};
+
+/**
+ * Verify a form's Sheets configuration end to end without writing anything.
+ *
+ * Three outcomes, deliberately: the sheet is reachable and writable, the sheet
+ * is reachable and write access could not be established, or something is
+ * wrong. Only the first is `ok`. A test that cannot see the difference between
+ * the first two is worth very little, since the whole point of running it is
+ * to find out whether submissions will land.
+ */
+export async function testGoogleSheetConnection(
+  target: SheetTarget,
+  env: Env = process.env,
+  fetchImpl: GoogleFetch = fetch,
+): Promise<SheetsTestResult> {
+  const credentials = resolveGoogleCredentials(env);
+  if (!credentials) return credentialsMissing();
+  const email = credentials.clientEmail;
+
+  const spreadsheetId = normalizeSpreadsheetId(target.spreadsheetId);
+  if (!spreadsheetId) {
+    return {
+      ok: false,
+      code: "invalid-spreadsheet-id",
+      error: (target.spreadsheetId ?? "").trim()
+        ? "That is not a Google Spreadsheet ID. Paste the long ID from the sheet's URL, between /d/ and /edit."
+        : "Enter the Spreadsheet ID first.",
+      serviceAccountEmail: email,
+    };
+  }
+  const tab = normalizeWorksheet(target.tab);
+
+  /*
+   * Two tokens, in order of preference. The Drive metadata scope is what makes
+   * the write probe answer definitively, so the test asks for it — but a
+   * project that has not granted it must still be able to check its
+   * spreadsheet id and tab name, so a refusal falls back to the Sheets scope
+   * alone and the probe simply comes back unknown.
+   */
+  let token: string;
+  let probeToken: string | null = null;
+  try {
+    probeToken = await googleAccessToken(credentials, SHEETS_TEST_SCOPE, fetchImpl);
+    token = probeToken;
+  } catch (err) {
+    if (!(err instanceof GoogleAuthError)) throw err;
+    try {
+      token = await googleAccessToken(credentials, SHEETS_SCOPE, fetchImpl);
+    } catch (fallbackErr) {
+      if (fallbackErr instanceof GoogleAuthError) return fromAuthError(fallbackErr, email);
+      throw fallbackErr;
+    }
+  }
+
+  const url = `${SHEETS_API}/${encodeURIComponent(spreadsheetId)}?fields=properties.title,sheets.properties.title`;
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: googleRequestSignal(),
+    });
+  } catch {
+    return {
+      ok: false,
+      code: "api-unavailable",
+      error: "Google could not be reached. Check the server's outbound network access.",
+      serviceAccountEmail: email,
+    };
+  }
+  if (!res.ok) return classify(res, email);
+
+  const meta = (await res.json().catch(() => null)) as Metadata | null;
+  const worksheets = (meta?.sheets ?? [])
+    .map((s) => s.properties?.title)
+    .filter((t): t is string => typeof t === "string" && t.length > 0);
+
+  const match = worksheets.find((t) => t === tab) ?? worksheets.find((t) => t.toLowerCase() === tab.toLowerCase());
+  if (!match) {
+    return {
+      ok: false,
+      code: "worksheet-not-found",
+      error: worksheets.length
+        ? `The spreadsheet has no tab named "${tab}". It has: ${worksheets.join(", ")}.`
+        : `The spreadsheet has no tab named "${tab}".`,
+      serviceAccountEmail: email,
+      worksheets,
+    };
+  }
+
+  // A read alone cannot prove the account may append, so ask Google what this
+  // caller is allowed to do. Drive's capabilities are authoritative here.
+  const canWrite = probeToken
+    ? await probeWriteAccess(spreadsheetId, probeToken, fetchImpl)
+    : null;
+  const spreadsheetTitle = meta?.properties?.title ?? "Untitled spreadsheet";
+  if (canWrite === false) {
+    return {
+      ok: false,
+      code: "permission-denied",
+      error: `${email} can read this spreadsheet but not write to it. Change its access to Editor.`,
+      serviceAccountEmail: email,
+      worksheets,
+    };
+  }
+
+  if (canWrite !== true) {
+    return {
+      ok: false,
+      code: "write-unconfirmed",
+      error: `Found “${spreadsheetTitle}” and its “${match}” tab, but Google would not say whether ${email} may write to it.`,
+      serviceAccountEmail: email,
+      spreadsheetTitle,
+      worksheetTitle: match,
+      worksheets,
+      canWrite: null,
+    };
+  }
+
+  return {
+    ok: true,
+    serviceAccountEmail: email,
+    spreadsheetTitle,
+    worksheetTitle: match,
+    worksheets,
+    canWrite,
+  };
+}
+
+/**
+ * Ask Drive whether this caller may edit the file.
+ *
+ * Returns `null` when Drive cannot answer (its API may not be enabled on the
+ * project), which is treated as "unknown" rather than as a failure — the append
+ * itself still reports a real permission error if there is one.
+ */
+async function probeWriteAccess(
+  spreadsheetId: string,
+  /** A token carrying the Drive metadata scope; without it Drive says 403. */
+  token: string,
+  fetchImpl: GoogleFetch,
+): Promise<boolean | null> {
+  try {
+    const res = await fetchImpl(
+      `https://www.googleapis.com/drive/v3/files/${encodeURIComponent(spreadsheetId)}?fields=capabilities/canEdit&supportsAllDrives=true`,
+      { headers: { Authorization: `Bearer ${token}` }, signal: googleRequestSignal() },
+    );
+    if (!res.ok) return null;
+    const body = (await res.json().catch(() => null)) as {
+      capabilities?: { canEdit?: unknown };
+    } | null;
+    const canEdit = body?.capabilities?.canEdit;
+    return typeof canEdit === "boolean" ? canEdit : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Append one row. Uses the same credential resolution and the same worksheet
+ * rules as the test, so a passing test is a real guarantee.
+ *
+ * Never throws: the submission itself is already stored, and a Sheets outage
+ * must not turn into a lost enquiry.
+ */
+export async function appendGoogleSheetRow(
+  target: SheetTarget & { values: (string | number)[] },
+  env: Env = process.env,
+  fetchImpl: GoogleFetch = fetch,
+): Promise<SheetsAppendResult> {
+  const credentials = resolveGoogleCredentials(env);
+  if (!credentials) return credentialsMissing();
+  const email = credentials.clientEmail;
+
+  const spreadsheetId = normalizeSpreadsheetId(target.spreadsheetId);
+  if (!spreadsheetId) {
+    return {
+      ok: false,
+      code: "invalid-spreadsheet-id",
+      error: "The form's Google Spreadsheet ID is not a valid spreadsheet ID.",
+      serviceAccountEmail: email,
+    };
+  }
+  const tab = normalizeWorksheet(target.tab);
+
+  let token: string;
+  try {
+    token = await googleAccessToken(credentials, SHEETS_SCOPE, fetchImpl);
+  } catch (err) {
+    if (err instanceof GoogleAuthError) return fromAuthError(err, email);
+    throw err;
+  }
+
+  const url =
+    `${SHEETS_API}/${encodeURIComponent(spreadsheetId)}/values/${encodeURIComponent(sheetRange(tab))}` +
+    // RAW, never USER_ENTERED: these are visitor-supplied values. USER_ENTERED
+    // parses them as though a person had typed them into the grid, so a message
+    // beginning with "=", "+", "-" or "@" would be stored as a live formula.
+    `:append?valueInputOption=RAW&insertDataOption=INSERT_ROWS`;
+
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ values: [target.values] }),
+      signal: googleRequestSignal(),
+    });
+  } catch {
+    return {
+      ok: false,
+      code: "api-unavailable",
+      error: "Google could not be reached in time while appending the row.",
+      serviceAccountEmail: email,
+    };
+  }
+  if (!res.ok) return classify(res, email);
+
+  /*
+   * A 2xx is not delivery. Google answers an append with what it actually
+   * wrote, and reporting `ok` without reading that turns a row that never
+   * landed into a submission the admin screen calls delivered — the one state
+   * nobody goes back and checks. Anything other than a confirmed row is a
+   * failed delivery, which the caller already knows how to retry.
+   */
+  const body = (await res.json().catch(() => null)) as AppendResponse | null;
+  const rows = body?.updates?.updatedRows;
+  if (typeof rows !== "number" || rows < 1) {
+    return {
+      ok: false,
+      code: "api-unavailable",
+      error: "Google accepted the request but did not confirm the row was written.",
+      serviceAccountEmail: email,
+    };
+  }
+  return { ok: true };
+}
+
+/** Whether this server can deliver to Sheets at all, for the admin UI. */
+export function googleSheetsStatus(env: Env = process.env): {
+  configured: boolean;
+  serviceAccountEmail: string | null;
+  emailVariable: string;
+  keyVariable: string;
+} {
+  const serviceAccountEmail = googleServiceAccountEmail(env);
+  return {
+    configured: serviceAccountEmail !== null,
+    serviceAccountEmail,
+    emailVariable: GOOGLE_SA_EMAIL_ENV,
+    keyVariable: GOOGLE_SA_KEY_ENV,
+  };
+}

package/src/server/http/sitemap.ts

@@ -4,6 +4,8 @@
  * `sitemapIndexXml` builds the index (one sitemap per configured domain);
  * `sitemapUrlsetXml` builds a per-locale urlset with hreflang alternates.
  */
+import { feedCachePolicy } from "../../http/cache-policy";
+
 export type SitemapIndexEntry = { url: string };
 
 export type SitemapUrlEntry = {
@@ -14,10 +16,25 @@ export type SitemapUrlEntry = {
   priority?: string;
 };
 
-const XML_HEADERS = {
-  "Content-Type": "application/xml",
-  "Cache-Control": "public, max-age=3600",
-} as const;
+/**
+ * How long this sitemap may be cached.
+ *
+ * A sitemap is a list of pages a visitor can reach, and that list changes by
+ * itself when a publication window opens or closes. `revalidateAt` — the next
+ * such instant, which `listPublishedRoutesCore` returns beside the keys — is
+ * the ceiling: without it a flat hour would advertise a page that expired at
+ * noon until one, and hide one that went live at noon just as long. Omitting it
+ * means the caller does not know, and nothing is cached beyond a revalidation.
+ */
+export type SitemapCacheOptions = { revalidateAt?: number | null; now?: number };
+
+function xmlHeaders(options: SitemapCacheOptions = {}): Record<string, string> {
+  const policy = feedCachePolicy(
+    options.revalidateAt === undefined ? 0 : options.revalidateAt,
+    options.now,
+  );
+  return { "Content-Type": "application/xml", "Cache-Control": policy.cacheControl };
+}
 
 export function sitemapIndexXml(entries: SitemapIndexEntry[]): string {
   const sitemaps = entries.map((e) => `  <sitemap>\n    <loc>${e.url}</loc>\n  </sitemap>`);
@@ -29,8 +46,11 @@ export function sitemapIndexXml(entries: SitemapIndexEntry[]): string {
   ].join("\n");
 }
 
-export function sitemapIndexResponse(entries: SitemapIndexEntry[]): Response {
-  return new Response(sitemapIndexXml(entries), { headers: { ...XML_HEADERS } });
+export function sitemapIndexResponse(
+  entries: SitemapIndexEntry[],
+  cache: SitemapCacheOptions = {},
+): Response {
+  return new Response(sitemapIndexXml(entries), { headers: xmlHeaders(cache) });
 }
 
 export function sitemapUrlsetXml(entries: SitemapUrlEntry[], homeKey = "home"): string {
@@ -58,6 +78,10 @@ export function sitemapUrlsetXml(entries: SitemapUrlEntry[], homeKey = "home"):
   ].join("\n");
 }
 
-export function sitemapUrlsetResponse(entries: SitemapUrlEntry[], homeKey = "home"): Response {
-  return new Response(sitemapUrlsetXml(entries, homeKey), { headers: { ...XML_HEADERS } });
+export function sitemapUrlsetResponse(
+  entries: SitemapUrlEntry[],
+  homeKey = "home",
+  cache: SitemapCacheOptions = {},
+): Response {
+  return new Response(sitemapUrlsetXml(entries, homeKey), { headers: xmlHeaders(cache) });
 }