@getvitops/astro 3.0.0 → 4.1.0

package/dist/index.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import { isConfig, resolveConfig } from "@getvitops/generator";
 import { collectIconRefs, faviconLinks, generateFavicons, generateIconInclude, resolveIcon, scanFiles, writeFaviconManifest } from "@getvitops/utils";
 import vitopsPlugin from "@getvitops/vite";
+import { AD_PLATFORMS, AD_PROVIDER_KEYS } from "@getvitops/utils/ads";
 import { fontProviders } from "astro/config";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -17,9 +18,9 @@ export * from "@getvitops/utils"
 * the guard is one regex and the cost of not having it is arbitrary script
 * injection from a config file.
 */
-const SAFE_ID = /^[\w.-]+$/;
+const SAFE_ID$1 = /^[\w.-]+$/;
 function bad(value) {
-	return !SAFE_ID.test(value);
+	return !SAFE_ID$1.test(value);
 }
 /** JSON is a subset of JS object-literal syntax; `<` can't appear unescaped. */
 function literal(value) {
@@ -172,6 +173,105 @@ function consentCategories(tags) {
 	].filter((c) => used.has(c));
 }
 
+//#endregion
+//#region src/ads.ts
+/**
+* The `<Ads />` resolution layer — the site's ad properties in, the exact tags to
+* emit out.
+*
+* A sibling of `analytics.ts`, deliberately not part of it. The two render the
+* same gated markup, but they answer different questions and four things differ:
+*
+*  - **Where they come from.** Analytics providers are integration options
+*    (`vitops({ analytics })`); ad properties are `site.ads` in the site config,
+*    because the ad account is a fact about the site that `vitops ads setup`,
+*    `vitops ads lint` and the generated cookie notice all read too.
+*  - **Who decides the consent category.** `resolveAnalytics` *derives* it from
+*    whether the provider sets cookies, so a consumer cannot mark Google Analytics
+*    `necessary` to dodge a banner. Every ad pixel sets cookies and is advertising,
+*    so the answer is `marketing` unless the config says `analytics` — a stated
+*    fact, not a derivation.
+*  - **What the key means.** `ResolvedTag['key']` is the four analytics providers,
+*    and `analytics.ts` pairs that set against the generator's processor table.
+*    Widening it to eight ad platforms would make that check answer for tags it
+*    does not govern.
+*  - **When they fire.** Analytics is gated per environment by
+*    `environments.<env>.analytics`; a preview deployment sending pageviews is
+*    survivable, one firing conversion pixels is not, so ads gets its own switch.
+*
+* Everything decidable is here and unit-tested; `Ads.astro` renders what this
+* returns and chooses nothing.
+*/
+/**
+* IDs land inside an inline `<script>`, so they are checked rather than trusted —
+* the same guard, for the same reason, as `analytics.ts`'s `SAFE_ID`. A `<\/script>`
+* in a pixel ID is not a plausible accident; arbitrary script injection from a
+* config file is not a plausible thing to allow either.
+*/
+const SAFE_ID = /^[\w.-]+$/;
+/** Resolve the configured ad properties into the tags `<Ads />` emits. */
+function resolveAds(ads, ctx = {}) {
+	const warnings = [];
+	const tags = [];
+	const strategy = ctx.strategy ?? "idle";
+	const configured = AD_PROVIDER_KEYS.filter((p) => ads?.[p] != null);
+	if (configured.length === 0) return {
+		tags,
+		needsRuntime: false,
+		warnings
+	};
+	if (ctx.enabled === false) return {
+		tags,
+		needsRuntime: false,
+		warnings
+	};
+	for (const provider of configured) {
+		const entry = ads[provider];
+		if (entry.enabled === false) continue;
+		const platform = AD_PLATFORMS[provider];
+		const id = entry[platform.tag.needs];
+		if (!id) {
+			warnings.push(`ads: ${provider} has no ${platform.tag.needs}, so no tag is emitted. Run \`vitops ads setup\` to be prompted for it.`);
+			continue;
+		}
+		if (!SAFE_ID.test(id)) {
+			warnings.push(`ads: ${provider} ${platform.tag.needs} "${id}" is not a valid ID. Skipped.`);
+			continue;
+		}
+		const category = entry.category ?? "marketing";
+		tags.push({
+			key: provider,
+			provider: platform.name,
+			category,
+			setsCookies: true,
+			cookies: platform.tag.cookies,
+			strategy,
+			gated: ctx.consent === true,
+			inline: platform.tag.bootstrap(id, {
+				provider,
+				...entry
+			}),
+			src: platform.tag.src ? platform.tag.src(id) : null,
+			attrs: {}
+		});
+	}
+	if (tags.length === 0) return {
+		tags,
+		needsRuntime: false,
+		warnings
+	};
+	if (ctx.consent !== true) warnings.push(`ads: ${tags.map((t) => t.provider).join(", ")} ${tags.length === 1 ? "sets" : "set"} advertising cookies, and \`consent\` is off — so they load for every visitor with no way to decline. Set \`consent: true\`.`);
+	else {
+		const missing = [...new Set(tags.map((t) => t.category))].filter((c) => ctx.consentCategories && !ctx.consentCategories.includes(c));
+		if (missing.length) warnings.push(`ads: the tags demand the ${missing.join(", ")} consent categor${missing.length === 1 ? "y" : "ies"}, but the banner offers ${ctx.consentCategories?.join(", ") || "nothing"}. Add ${missing.join(", ")} to \`consent.categories\`, or the tags wait on a question the banner never asks.`);
+	}
+	return {
+		tags,
+		needsRuntime: true,
+		warnings
+	};
+}
+
 //#endregion
 //#region src/fonts.ts
 /**
@@ -225,6 +325,39 @@ function resolveFonts(decls) {
 	};
 }
 
+//#endregion
+//#region src/tracking.ts
+/** The cookie the capture script writes. Mirrors `TRACKING_COOKIE` in utils. */
+const TRACKING_COOKIE = "_ac";
+/**
+* Resolve the tracking config into what the component emits.
+*
+* Two warnings, both about the same failure — a persistent identifier written
+* with no way for the visitor to decline, or a permission asked for with no way
+* to answer. Returned as data rather than logged here so the check is a test
+* rather than a line someone might scroll past, exactly as `resolveAnalytics`
+* does.
+*/
+function resolveTracking(opts, ctx = {}) {
+	const warnings = [];
+	const category = opts?.category ?? "marketing";
+	const enabled = opts?.enabled === true;
+	if (!enabled) return {
+		enabled: false,
+		category,
+		cookies: [],
+		warnings
+	};
+	if (!ctx.consent) warnings.push(`tracking is on, so this site writes the \`${"_ac"}\` cookie — a 90-day identifier tying a visitor to the ad that brought them — and \`consent\` is off, so it is written for every visitor with no way to decline. Set \`consent: true\`.`);
+	else if (ctx.consentCategories && !ctx.consentCategories.includes(category)) warnings.push(`tracking demands the \`${category}\` consent category, but the banner offers ${ctx.consentCategories.join(", ") || "nothing"}. Add \`${category}\` to \`consent.categories\`, or the visitor is asked about something the banner never names.`);
+	return {
+		enabled,
+		category,
+		cookies: ["_ac"],
+		warnings
+	};
+}
+
 //#endregion
 //#region src/integration.ts
 /**
@@ -265,6 +398,34 @@ function undisclosedProviders(configPath, analytics) {
 	}
 	return Object.keys(SITE_CONFIG_KEYS).filter((key) => analytics[key] !== void 0 && !declared[SITE_CONFIG_KEYS[key]]);
 }
+/**
+* Read `site.ads` and this environment's ads switch out of the site config.
+*
+* Best-effort, like `undisclosedProviders`: every other consumer of this file
+* validates it loudly elsewhere in the same hook, and a second copy of that error
+* helps nobody. `resolveConfig` is used rather than a bare `JSON.parse` so an A/B
+* variant's `overrides` are applied first — a variant that changes which pixels
+* run is exactly the kind of thing overrides exist for.
+*
+* The environment switch cascades `ads` → `analytics` → true. An environment that
+* has already said "no analytics here" has said the interesting half of it; making
+* a consumer repeat themselves to stop conversion pixels would mean a preview
+* deploy fires them by default, which is the wrong way for this to fail.
+*/
+function readSiteAds(configPath, siteEnv) {
+	try {
+		const cfg = resolveConfig(JSON.parse(readFileSync(configPath, "utf8")), siteEnv);
+		const properties = cfg.site.ads;
+		if (!properties || Object.keys(properties).length === 0) return null;
+		const env = cfg.site.environments?.[siteEnv];
+		return {
+			enabled: env?.ads ?? env?.analytics ?? true,
+			properties
+		};
+	} catch {
+		return null;
+	}
+}
 const VIRTUAL_ID = "virtual:getvitops/head";
 const RESOLVED_ID = `\0${VIRTUAL_ID}`;
 function virtualHeadPlugin(data) {
@@ -358,9 +519,28 @@ function vitops(opts = {}) {
 			const consentEnabled = !!opts.consent;
 			const consentOpts = typeof opts.consent === "object" ? opts.consent : {};
 			const analytics = resolveAnalytics(opts.analytics, { consent: consentEnabled });
-			const detectedCategories = consentCategories(analytics.tags);
-			const offeredCategories = consentOpts.categories ?? (detectedCategories.length ? detectedCategories : ["analytics"]);
+			const trackingOpts = opts.tracking === true ? { enabled: true } : opts.tracking || void 0;
+			const adsConfig = siteInput ? readSiteAds(resolve(root, siteInput), opts.site?.siteEnv ?? "production") : null;
+			const detectedCategories = consentCategories([...analytics.tags, ...resolveAds(adsConfig?.properties, {
+				consent: consentEnabled,
+				enabled: true
+			}).tags]);
+			const defaultCategories = ["analytics", "preferences"];
+			const trackingCategory = trackingOpts?.enabled ? trackingOpts.category ?? "marketing" : null;
+			if (detectedCategories.includes("marketing") || trackingCategory === "marketing") defaultCategories.push("marketing");
+			const offeredCategories = consentOpts.categories ?? defaultCategories;
 			for (const warning of analytics.warnings) logger.warn(warning);
+			const tracking = resolveTracking(trackingOpts, {
+				consent: consentEnabled,
+				consentCategories: offeredCategories
+			});
+			for (const warning of tracking.warnings) logger.warn(warning);
+			const ads = resolveAds(adsConfig?.properties, {
+				consent: consentEnabled,
+				consentCategories: offeredCategories,
+				enabled: adsConfig?.enabled ?? true
+			});
+			for (const warning of ads.warnings) logger.warn(warning);
 			if (opts.analytics && legalInput) {
 				const undisclosed = undisclosedProviders(resolve(root, legalInput), opts.analytics);
 				if (undisclosed.length) logger.warn(`analytics: ${undisclosed.join(", ")} ${undisclosed.length === 1 ? "is" : "are"} configured here but absent from your site config's \`analytics\` block, so the cookie notice \`legal\` generates will not disclose ${undisclosed.length === 1 ? "it" : "them"}. Add ${undisclosed.map((k) => SITE_CONFIG_KEYS[k]).join(", ")} to ${legalInput}.`);
@@ -558,7 +738,13 @@ function vitops(opts = {}) {
 				consent: consentEnabled,
 				consentCategories: offeredCategories,
 				consentPolicyUrl: consentOpts.policyUrl ?? null,
-				consentRuntime
+				consentRuntime,
+				tracking: tracking.enabled ? {
+					enabled: true,
+					category: tracking.category,
+					cookies: tracking.cookies
+				} : null,
+				ads: adsConfig
 			})] } });
 			if (opts.css) {
 				const format = opts.css.format ?? "tailwind";
@@ -609,7 +795,7 @@ function vitops(opts = {}) {
 * Real per-page `<lastmod>` for the sitemap, derived from git.
 *
 * This is the one lever that reliably moves Google. It is also load-bearing for
-* `vitops indexing`, which decides what to submit by diffing lastmod against the
+* `vitops search notify`, which decides what to submit by diffing lastmod against the
 * previous build — with no lastmod, that diff can see pages appear and disappear
 * but never see one *change*, so an edited page is never resubmitted.
 *
@@ -886,5 +1072,5 @@ function resolveSeo(defaults, props, ctx) {
 }
 
 //#endregion
-export { consentCategories, vitops as default, gitLastmod, resolveAnalytics, resolveSeo, routeFromPage, slugFromContent };
+export { TRACKING_COOKIE, consentCategories, vitops as default, gitLastmod, resolveAds, resolveAnalytics, resolveSeo, resolveTracking, routeFromPage, slugFromContent };
 //# sourceMappingURL=index.mjs.map