@getvitops/astro 4.0.0 → 5.0.0

package/dist/index.mjs

@@ -1,9 +1,11 @@
+import { n as TRACKING_ENDPOINT, r as resolveTracking, t as TRACKING_COOKIE } from "./tracking-CmSfxWC3.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 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 +19,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 +174,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,39 +326,6 @@ 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
 /**
@@ -298,6 +366,101 @@ 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;
+	}
+}
+/**
+* The consent + tracking facts a site config already states.
+*
+* These were the one pair the integration did not read. `site.tracking` and
+* `site.legal.cookieConsent` drive the **generated cookie notice**, while
+* `vitops({ consent, tracking })` drove the **runtime** — two hand-synced
+* declarations of the same fact with nothing checking them against each other.
+* The failure that produces is precisely the one the rest of the toolchain is
+* fastidious about avoiding: a site can ship a cookie notice naming categories
+* its banner never offers, or promising attribution that no capture script
+* implements, and the build is clean. That is a compliance defect, not a
+* documentation gap.
+*
+* Read as DEFAULTS, the same as `css` / `fonts` / `favicon` / `ads` — the
+* config is where a site's facts live, and an integration option is how you
+* override one. A genuine contradiction is an error rather than a warning; see
+* `consentTrackingConflicts`.
+*/
+function readSiteConsentTracking(configPath, siteEnv) {
+	try {
+		const cfg = resolveConfig(JSON.parse(readFileSync(configPath, "utf8")), siteEnv);
+		const t = cfg.site.tracking;
+		const cc = cfg.site.legal?.cookieConsent;
+		if (!t && !cc) return null;
+		return {
+			...t ? { tracking: t } : {},
+			...cc ? { consentEnabled: cc.enabled } : {},
+			...cc?.categories ? { categories: cc.categories } : {}
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Contradictions between the config and an explicit integration option.
+*
+* Absent-vs-present is a default and resolves silently. `true` vs `false` on the
+* same fact is not resolvable — one of the two documents is wrong, and picking
+* either quietly is how a notice and a banner get out of step. The message names
+* both sides so the fix does not require guessing which one won.
+*/
+function consentTrackingConflicts(site, opts, configPath) {
+	const out = [];
+	const optConsent = opts.consent === void 0 ? void 0 : !!opts.consent;
+	if (site.consentEnabled !== void 0 && optConsent !== void 0 && site.consentEnabled !== optConsent) out.push(`consent: ${configPath} sets site.legal.cookieConsent.enabled: ${site.consentEnabled}, but vitops({ consent: ${optConsent} }) says the opposite. The generated cookie notice follows the config and the banner follows the option, so one of them would describe a site that does not exist. Set them the same, or drop the option and let the config decide.`);
+	const optTracking = opts.tracking === void 0 ? void 0 : opts.tracking === true ? true : opts.tracking === false ? false : opts.tracking.enabled ?? true;
+	if (site.tracking?.enabled !== void 0 && optTracking !== void 0 && site.tracking.enabled !== optTracking) out.push(`tracking: ${configPath} sets site.tracking.enabled: ${site.tracking.enabled}, but vitops({ tracking: ${optTracking} }) says the opposite. The cookie notice discloses \`_ac\` from the config while the capture script ships from the option — so the site would either disclose a cookie it never sets, or set one it never discloses.`);
+	return out;
+}
+/**
+* Does a route answer `TRACKING_ENDPOINT`?
+*
+* Checked by filename rather than through Astro's route manifest, because this
+* runs in `astro:config:setup` — before routes are collected. The extension set
+* covers the ways a consumer can author the same endpoint; a false negative
+* costs a warning, a false positive costs the whole point of the check, so this
+* errs toward looking in more places.
+*/
+function hasConversionRoute(root) {
+	const base = resolve(root, "src/pages", TRACKING_ENDPOINT.replace(/^\//, ""));
+	return [
+		".ts",
+		".js",
+		".mjs",
+		".astro"
+	].some((ext) => existsSync(`${base}${ext}`) || existsSync(join(base, `index${ext}`)));
+}
 const VIRTUAL_ID = "virtual:getvitops/head";
 const RESOLVED_ID = `\0${VIRTUAL_ID}`;
 function virtualHeadPlugin(data) {
@@ -388,11 +551,20 @@ function vitops(opts = {}) {
 				if (!config.site) logger.warn("seo: needs the `site` astro.config option (your deployed URL) — without it <Seo /> omits canonical, og:url and any relative og:image rather than guessing an origin.");
 				if (config.integrations.some((i) => i.name === "emdash")) logger.warn("seo: emdash() is registered, and its <EmDashHead> emits the same title/description/canonical/og tags from the CMS. Use one or the other — rendering both duplicates every tag.");
 			}
-			const consentEnabled = !!opts.consent;
-			const consentOpts = typeof opts.consent === "object" ? opts.consent : {};
+			const siteConsent = siteInput ? readSiteConsentTracking(resolve(root, siteInput), opts.site?.siteEnv ?? "production") : null;
+			if (siteConsent) {
+				const conflicts = consentTrackingConflicts(siteConsent, opts, siteInput);
+				if (conflicts.length) throw new Error(`vitops: the site config and the integration options disagree about consent.\n\n` + conflicts.map((c) => `  • ${c}`).join("\n\n"));
+			}
+			const consentEnabled = opts.consent !== void 0 ? !!opts.consent : !!siteConsent?.consentEnabled;
+			const consentOpts = typeof opts.consent === "object" ? opts.consent : siteConsent?.categories ? { categories: siteConsent.categories } : {};
 			const analytics = resolveAnalytics(opts.analytics, { consent: consentEnabled });
-			const trackingOpts = opts.tracking === true ? { enabled: true } : opts.tracking || void 0;
-			const detectedCategories = consentCategories(analytics.tags);
+			const trackingOpts = opts.tracking === true ? { enabled: true } : opts.tracking || (siteConsent?.tracking?.enabled ? siteConsent.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");
@@ -403,6 +575,13 @@ function vitops(opts = {}) {
 				consentCategories: offeredCategories
 			});
 			for (const warning of tracking.warnings) logger.warn(warning);
+			if (tracking.enabled && !hasConversionRoute(root)) logger.warn(`tracking is on, so the capture script beacons \`tel:\` conversions to ${TRACKING_ENDPOINT}, but no route answers that path. Add \`src/pages/api/track.ts\` exporting \`createConversionRoute(...)\` from \`@getvitops/astro/routes\` — otherwise every call conversion is silently lost.`);
+			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}.`);
@@ -605,7 +784,8 @@ function vitops(opts = {}) {
 					enabled: true,
 					category: tracking.category,
 					cookies: tracking.cookies
-				} : null
+				} : null,
+				ads: adsConfig
 			})] } });
 			if (opts.css) {
 				const format = opts.css.format ?? "tailwind";
@@ -933,5 +1113,5 @@ function resolveSeo(defaults, props, ctx) {
 }
 
 //#endregion
-export { TRACKING_COOKIE, consentCategories, vitops as default, gitLastmod, resolveAnalytics, resolveSeo, resolveTracking, routeFromPage, slugFromContent };
+export { TRACKING_COOKIE, consentCategories, vitops as default, gitLastmod, resolveAds, resolveAnalytics, resolveSeo, resolveTracking, routeFromPage, slugFromContent };
 //# sourceMappingURL=index.mjs.map