@caltho/site-kit 0.2.6 → 0.2.8

package/README.md

@@ -57,7 +57,7 @@ the kit only checks it's a URL.
 | --- | --- |
 | **Content** (`@caltho/site-kit/content`) | `defineSite` and the pieces to build blocks from (`text`, `md`, `image`, `link`, `href`, `business`, …); the checks, including that every link lands on a page and every `#part` exists; the JSON Schema. |
 | **prepare** | Loads the content from CalOS (`CALOS_CONTENT_URL`, `CALOS_SITE_TOKEN`; the site's own while nothing's published there) or `content/site.json`, sends CalOS the schema, checks it, writes the schema, and makes every picture the content names as WebP at the widths screens need plus a 1200×630 share crop, named by content so they cache for a year. |
-| **finish** | After the framework's build: a content security policy in every page (each inline script named by hash), `_headers` (security headers, long caching, `noindex` on preview addresses), and `_redirects` from CalOS (`CALOS_REDIRECTS_URL`; a build that can't reach CalOS fails rather than lose them). |
+| **finish** | After the framework's build: a content security policy in every page (each inline script named by hash), `_headers` (security headers, long caching, `noindex` on preview addresses), and `_redirects` from CalOS (`CALOS_REDIRECTS_URL`; a build that can't reach CalOS fails rather than lose them). Where CalOS counts the site's visits (its content answer says where they go), the analytics script in every published page but the preview, with its addresses in the policy, and phone and map links marked so a tap is counted (`phone_tap`, `directions_tap`; a link marked `data-track` already is left as it is). No cookies. The standard privacy policy then leaves out its claim of no analytics, saying nothing in its place: what to say of the counting is the business's (`extra`). |
 | **check** | Every page in a real browser on a computer and a phone: fails on anything the policy blocks and anything that doesn't load. What axe finds (WCAG 2.0–2.2 A and AA, best practice) is said with where, for the site to weigh (a colour the business chose over the contrast rule is their choice); `--strict` fails on it too, `--allow=rule,rule` leaves named rules out. |
 | **Search** | Titles that fit, canonical addresses, the business as schema.org data (hours, areas, address), FAQ and breadcrumb data, robots.txt, the sitemap. |
 | **Policies** | Privacy, accessibility and terms, written from the business's facts and what the site does. Optional: a site calls `policy()` where it wants them. |

package/dist/content/index.d.ts

@@ -170,7 +170,8 @@ export type SiteBase = {
     footer?: Footer;
     look?: Look;
     redirects: Redirect[]; /** Whether page paths end in a slash (the default). */
-    trailingSlash?: boolean;
+    trailingSlash?: boolean; /** Set by prepare, never in content: CalOS counts this site's visits (its pages carry the script), which its privacy policy says. */
+    countsVisits?: boolean;
 };
 /**
  * The site's menu, as its header draws it: the one edited in CalOS (its links in order, one picked out,

package/dist/finish.d.ts

@@ -1,3 +1,10 @@
+import type { Analytics } from "./prepare.ts";
 type Log = (line: string) => void;
 export declare function finish(root: string, outDir: string, env?: Record<string, string | undefined>, log?: Log): Promise<void>;
+/**
+ * A page with its visits counted: the analytics script, queued before it loads (its pages, the links
+ * out, and what's marked to count), and each phone link and map link marked: a call or directions
+ * tapped is what a business wants to know came from the site. No cookies: nothing to consent to.
+ */
+export declare function counted(html: string, a: Analytics): string;
 export {};

package/dist/finish.js

@@ -1,7 +1,9 @@
 // What a site's build output needs after the framework is done: a content security policy in every
 // page, naming by hash each inline script and style the page carries (Next.js writes its page data
 // as inline scripts; a static page can't carry a per-request nonce), and Cloudflare Pages' `_headers`
-// and `_redirects` beside the pages.
+// and `_redirects` beside the pages. Where CalOS counts its visits, every published page (not the
+// preview) gets the script that sends them, and its phone and map links are marked, so a tap on one
+// is counted too.
 import { createHash } from "node:crypto";
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
@@ -16,6 +18,12 @@ export async function finish(root, outDir, env = process.env, log = console.log)
     const attributes = [];
     for (const file of pages) {
         let html = await readFile(file, "utf8");
+        // The preview shows the draft's pictures from CalOS, before any build has made them; those this
+        // build made, it shows as built (./next/preview.tsx), from the list it carries.
+        const isPreview = relative(outDir, file).replace(/(\/index)?\.html$/, "") === PREVIEW_PATH.slice(1);
+        // Before the hashing: its own little script is named in the policy like any other.
+        if (prepared.analytics && !isPreview)
+            html = counted(html, prepared.analytics);
         const scripts = new Set();
         const styles = new Set();
         for (const m of html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
@@ -31,21 +39,18 @@ export async function finish(root, outDir, env = process.env, log = console.log)
             attributes.push(relative(outDir, file));
         const directives = {
             "default-src": ["'self'"],
-            "script-src": ["'self'", ...[...scripts].map((h) => `'${h}'`)],
+            "script-src": ["'self'", ...[...scripts].map((h) => `'${h}'`), ...(prepared.analytics && !isPreview ? [new URL(prepared.analytics.script).origin] : [])],
             "style-src": ["'self'", ...[...styles].map((h) => `'${h}'`)],
             "img-src": ["'self'", "data:"],
             "font-src": ["'self'"],
             // A form sends with fetch as often as by posting the page: its address for both.
-            "connect-src": ["'self'", ...(formOrigin ? [formOrigin] : [])],
+            "connect-src": ["'self'", ...(formOrigin ? [formOrigin] : []), ...(prepared.analytics && !isPreview ? [new URL(prepared.analytics.api).origin] : [])],
             "form-action": ["'self'", ...(formOrigin ? [formOrigin] : [])],
             "base-uri": ["'self'"],
             "object-src": ["'none'"],
         };
         for (const [directive, sources] of Object.entries(prepared.csp ?? {}))
             directives[directive] = [...new Set([...(directives[directive] ?? ["'self'"]), ...sources])];
-        // The preview shows the draft's pictures from CalOS, before any build has made them; those this
-        // build made, it shows as built (./next/preview.tsx), from the list it carries.
-        const isPreview = relative(outDir, file).replace(/(\/index)?\.html$/, "") === PREVIEW_PATH.slice(1);
         if (isPreview) {
             directives["img-src"].push(...editors);
             const built = JSON.stringify(prepared.images ?? {}).replace(/</g, "\\u003c");
@@ -62,7 +67,24 @@ export async function finish(root, outDir, env = process.env, log = console.log)
     await writeFile(join(outDir, "_headers"), headersFile(editors));
     const redirects = await loadRedirects(site, env.CALOS_REDIRECTS_URL);
     await writeFile(join(outDir, "_redirects"), redirects.file);
-    log(`site-kit: a content security policy in ${pages.length} pages; _headers; _redirects from ${redirects.from}`);
+    log(`site-kit: a content security policy in ${pages.length} pages; _headers; _redirects from ${redirects.from}${prepared.analytics ? "; visits counted" : ""}`);
+}
+/**
+ * A page with its visits counted: the analytics script, queued before it loads (its pages, the links
+ * out, and what's marked to count), and each phone link and map link marked: a call or directions
+ * tapped is what a business wants to know came from the site. No cookies: nothing to consent to.
+ */
+export function counted(html, a) {
+    const init = `window.op=window.op||function(){(window.op.q=window.op.q||[]).push(arguments)};window.op("init",${JSON.stringify({ apiUrl: a.api, clientId: a.client, trackScreenViews: true, trackOutgoingLinks: true, trackAttributes: true })});`;
+    const tags = `<script>${init}</script><script src="${a.script}" defer async></script>`;
+    html = html.replace(/<\/head>/i, () => `${tags}</head>`);
+    return html.replace(/<a\b([^>]*)>/gi, (tag, attrs) => {
+        if (/\sdata-track\s*=/i.test(attrs))
+            return tag;
+        const href = /\shref\s*=\s*["']([^"']*)["']/i.exec(attrs)?.[1] ?? "";
+        const event = /^tel:/i.test(href) ? "phone_tap" : /^https?:\/\/(www\.)?(google\.[a-z.]+\/maps|maps\.google\.[a-z.]+|goo\.gl\/maps|maps\.app\.goo\.gl|maps\.apple\.com)/i.test(href) ? "directions_tap" : null;
+        return event ? `<a${attrs} data-track="${event}">` : tag;
+    });
 }
 const hash = (body) => `sha256-${createHash("sha256").update(body, "utf8").digest("base64")}`;
 async function walk(dir) {

package/dist/policies.js

@@ -1,8 +1,11 @@
 // The policy pages a business's site should have, written from what the business has told us and
 // what the template actually does: no cookies, no analytics, no third-party requests, a contact
 // form that goes to the business's CalOS. So the words stay true as the site changes: add a
-// tracker to the template and this is where it has to be said. Plain language, US-first; a
-// business adds its own paragraphs with `extra`, and should have a lawyer read them once.
+// tracker to the template and this is where it has to be said. Where the business has CalOS count
+// its visits (prepare marks it: site.countsVisits), the claim of no analytics is left out and
+// nothing said in its place: what to say of the counting is the business's, in `extra` (CalOS
+// suggests a paragraph as they turn it on). Plain language, US-first; a business adds its own
+// paragraphs with `extra`, and should have a lawyer read them once.
 /**
  * `collectsFromForm`: the site has a form that takes a visitor's name, email and message, which the
  * privacy policy says (it defaults to the site having a form address).
@@ -13,6 +16,7 @@ export function policy(site, which, o = {}) {
     const reach = [b.email ? `email [${b.email}](mailto:${b.email})` : null, b.phone ? `call ${b.phone}` : null].filter(Boolean).join(" or ");
     const place = b.address ? `${b.address.locality}, ${b.address.region}` : null;
     const hasForm = o.collectsFromForm ?? !!site.form;
+    const counts = !!site.countsVisits;
     if (which === "privacy") {
         return {
             title: "Privacy policy",
@@ -27,7 +31,9 @@ export function policy(site, which, o = {}) {
                 ]
                     .filter(Boolean)
                     .join("\n"),
-                `This site doesn't use cookies, advertising or analytics trackers. Its fonts and pictures come from this site itself, so visiting it doesn't tell anyone else you were here.`,
+                counts
+                    ? `This site doesn't use cookies or advertising trackers. Its fonts and pictures come from this site itself.`
+                    : `This site doesn't use cookies, advertising or analytics trackers. Its fonts and pictures come from this site itself, so visiting it doesn't tell anyone else you were here.`,
                 `## How we use it`,
                 `To answer you, to quote for and do the work you ask about, and to keep the records the law requires. We keep enquiries in our customer records system, which Caltho runs for us. We don't sell or rent your information, and we don't share it for advertising. The companies that help us run this site and our business (hosting, email, records) only use it to do that for us.`,
                 `## How long we keep it`,

package/dist/prepare.d.ts

@@ -25,7 +25,19 @@ export type Prepared = {
     cards?: Record<string, string>;
     /** Whether a page with pictures but no share picture chosen is shared with its first picture rather than its card. */
     preferPicture?: boolean;
+    /** Where its visits are counted, when CalOS counts them (Caltho's analytics server): finish puts its script in every page. */
+    analytics?: Analytics;
 };
+/** A site's visits counted: the id its pages send them with, where they're sent, and the script that sends them. */
+export type Analytics = {
+    client: string;
+    api: string;
+    script: string;
+};
+/** What CalOS says of the site's analytics, taken only when it's whole and its addresses are https (or a laptop's). */
+export declare function analyticsIn(body: {
+    analytics?: unknown;
+} | null): Analytics | undefined;
 type Log = (line: string) => void;
 export declare function prepare(root: string, env?: Record<string, string | undefined>, log?: Log): Promise<Prepared>;
 export {};

package/dist/prepare.js

@@ -21,6 +21,15 @@ import sharp from "sharp";
 import { pathToFileURL } from "node:url";
 import { imagesIn, shareImageOf } from "./images.js";
 import { makeCards } from "./share.js";
+/** What CalOS says of the site's analytics, taken only when it's whole and its addresses are https (or a laptop's). */
+export function analyticsIn(body) {
+    const a = body?.analytics;
+    const address = (v) => typeof v === "string" && /^(https:\/\/|http:\/\/(localhost|127\.0\.0\.1)(:\d+)?\/?)/i.test(v) && URL.canParse(v);
+    if (!a || typeof a.client !== "string" || !/^[\w-]{8,64}$/.test(a.client) || !address(a.api) || !address(a.script))
+        return undefined;
+    // As URL writes them: a quote or an angle bracket escaped, so neither can leave the tag it goes in.
+    return { client: a.client, api: new URL(String(a.api)).href.replace(/\/+$/, ""), script: new URL(String(a.script)).href };
+}
 const WIDTHS = [400, 640, 800, 1024, 1280, 1600, 2000];
 export async function prepare(root, env = process.env, log = console.log) {
     const out = join(root, ".site");
@@ -31,6 +40,7 @@ export async function prepare(root, env = process.env, log = console.log) {
     let raw;
     let from;
     let editors = [];
+    let analytics;
     // A site CalOS has nothing published for yet (just made, its content not brought in) builds from
     // its own until there is: 404 is "nothing published", any other refusal is an error.
     const res = env.CALOS_CONTENT_URL
@@ -42,7 +52,9 @@ export async function prepare(root, env = process.env, log = console.log) {
     const editorsIn = (body) => (Array.isArray(body?.editors) ? body.editors.filter((o) => typeof o === "string" && /^https?:\/\/[a-z0-9.-]+(:\d+)?$/i.test(o)) : []);
     if (res && res.status === 404) {
         // Who may edit it is known before anything's published: its preview can be drawn from the start.
-        editors = editorsIn((await res.json().catch(() => null)));
+        const body = (await res.json().catch(() => null));
+        editors = editorsIn(body);
+        analytics = analyticsIn(body);
         log("site-kit: nothing published in CalOS yet; building from content/site.json");
     }
     if (res && res.status !== 404) {
@@ -51,6 +63,7 @@ export async function prepare(root, env = process.env, log = console.log) {
         const body = (await res.json());
         raw = body.content;
         editors = editorsIn(body);
+        analytics = analyticsIn(body);
         from = "CalOS";
         // Pictures uploaded in CalOS, fetched into the images folder once each.
         for (const [name, url] of Object.entries(body.images ?? {})) {
@@ -79,6 +92,11 @@ export async function prepare(root, env = process.env, log = console.log) {
     if (parsed.problems)
         throw new Error(`The site's content needs fixing (${from}):\n  - ${parsed.problems.join("\n  - ")}`);
     const site = parsed.site;
+    // Its pages will count visits (finish puts the script in): what its privacy policy says follows.
+    if (analytics)
+        site.countsVisits = true;
+    else
+        delete site.countsVisits;
     for (const w of parsed.warnings)
         log(`site-kit: warning: ${w}`);
     const schema = definition.jsonSchema();
@@ -89,9 +107,9 @@ export async function prepare(root, env = process.env, log = console.log) {
     const images = await pictures(site, imagesDir, pub, log);
     const cards = await makeCards(site, definition.share, root, pub, log);
     const preferPicture = !!definition.share && definition.share.prefer === "picture";
-    const prepared = { site, images, csp: definition.csp, cards, ...(preferPicture ? { preferPicture } : {}), ...(editors.length ? { editors } : {}) };
+    const prepared = { site, images, csp: definition.csp, cards, ...(preferPicture ? { preferPicture } : {}), ...(editors.length ? { editors } : {}), ...(analytics ? { analytics } : {}) };
     await writeFile(join(out, "prepared.json"), JSON.stringify(prepared));
-    log(`site-kit: content from ${from}, ${site.pages.length} pages, ${Object.keys(images).length} images`);
+    log(`site-kit: content from ${from}, ${site.pages.length} pages, ${Object.keys(images).length} images${analytics ? ", visits counted" : ""}`);
     return prepared;
 }
 // ---- pictures ----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caltho/site-kit",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "What every Caltho site is built with: the contract with CalOS (content, and how a site declares what is editable), images, search and security, and the checks",
   "license": "MIT",
   "type": "module",