@getvitops/astro 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/astro",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Astro integration for the Vitops design system — favicons/PWA, web-component scripts, and CSS, via a getvitops() integration + <Head /> component.",
   "license": "MIT",
   "files": [
@@ -9,8 +9,11 @@
     "src/components/Seo.astro",
     "src/seo.ts",
     "src/components/Analytics.astro",
+    "src/components/Ads.astro",
+    "src/components/GatedTags.astro",
     "src/components/CookieConsent.astro",
     "src/analytics.ts",
+    "src/ads.ts",
     "src/components/Subgrid.astro",
     "src/components/Cards.astro",
     "src/components/NodeRenderer.astro",
@@ -45,6 +48,7 @@
     "./Head.astro": "./src/components/Head.astro",
     "./Seo.astro": "./src/components/Seo.astro",
     "./Analytics.astro": "./src/components/Analytics.astro",
+    "./Ads.astro": "./src/components/Ads.astro",
     "./CookieConsent.astro": "./src/components/CookieConsent.astro",
     "./Tracking.astro": "./src/components/Tracking.astro",
     "./components/Subgrid.astro": "./src/components/Subgrid.astro",
@@ -66,10 +70,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/generator": "4.0.0",
-    "@getvitops/vite": "4.0.0",
-    "@getvitops/core": "4.0.0",
-    "@getvitops/utils": "4.0.0"
+    "@getvitops/core": "4.1.0",
+    "@getvitops/generator": "4.1.0",
+    "@getvitops/vite": "4.1.0",
+    "@getvitops/utils": "4.1.0"
   },
   "devDependencies": {
     "@astrojs/sitemap": "^3.7.3",

package/src/ads.ts

@@ -0,0 +1,156 @@
+/**
+ * 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.
+ */
+import { AD_PLATFORMS, AD_PROVIDER_KEYS, type AdProvider } from '@getvitops/utils/ads';
+import type { AnalyticsStrategy, ConsentCategory, GatedTag } from './analytics.ts';
+
+/**
+ * One ad property, mirroring a `site.ads` entry field for field.
+ *
+ * Structural rather than `SiteAdProperty` imported from the generator, matching
+ * how `GetvitopsSeoOptions` and `GetvitopsTrackingOptions` already work: the
+ * component surface must stay usable by a consumer who passes a plain object.
+ */
+export interface GetvitopsAdProperty {
+  accountId?: string;
+  pixelId?: string;
+  conversionLabel?: string;
+  /** Default `marketing`. `analytics` for a property used purely for measurement. */
+  category?: 'marketing' | 'analytics';
+  /** False keeps the property on record without emitting its tag. */
+  enabled?: boolean;
+}
+
+export type GetvitopsAdsOptions = Partial<Record<AdProvider, GetvitopsAdProperty>>;
+
+/** One ad tag. `key` is the platform, so a caller can find one without matching prose. */
+export interface ResolvedAdTag extends GatedTag {
+  key: AdProvider;
+}
+
+export interface ResolvedAds {
+  tags: ResolvedAdTag[];
+  /** Does anything here need `@getvitops/core/consent` loaded? */
+  needsRuntime: boolean;
+  /** Configuration problems, as prose. The integration logs these. */
+  warnings: string[];
+}
+
+export interface ResolveAdsContext {
+  /** Is the consent gate enabled on this site (`vitops({ consent })`)? */
+  consent?: boolean;
+  /** Categories the banner offers, so we can catch a demand with no row. */
+  consentCategories?: readonly string[];
+  /** `environments.<env>.ads` — false switches every tag off for this build. */
+  enabled?: boolean;
+  /** When the tags load. Default `idle`: a pixel is never worth the critical path. */
+  strategy?: AnalyticsStrategy;
+}
+
+/**
+ * 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. */
+export function resolveAds(
+  ads: GetvitopsAdsOptions | undefined,
+  ctx: ResolveAdsContext = {},
+): ResolvedAds {
+  const warnings: string[] = [];
+  const tags: ResolvedAdTag[] = [];
+  const strategy = ctx.strategy ?? 'idle';
+
+  const configured = AD_PROVIDER_KEYS.filter((p) => ads?.[p] != null);
+  if (configured.length === 0) return { tags, needsRuntime: false, warnings };
+
+  // A whole-environment switch, checked before anything else: a preview deploy
+  // must be able to carry the same config without firing a single pixel.
+  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: ConsentCategory = entry.category ?? 'marketing';
+    tags.push({
+      key: provider,
+      provider: platform.name,
+      category,
+      // Every platform in the table sets cookies; the tag is gated whenever the
+      // site has a gate. With no gate the tag still renders — and the warning
+      // below says what that means, rather than silently declining to advertise.
+      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 };
+}

package/src/analytics.ts

@@ -105,9 +105,22 @@ export interface GetvitopsConsentOptions {
   policyUrl?: string;
 }
 
-/** One tag, fully resolved. */
-export interface ResolvedTag {
-  key: 'googleAnalytics' | 'clarity' | 'matomo' | 'plausible';
+/**
+ * A third-party tag, fully resolved — everything `<GatedTags />` needs to render
+ * one, with nothing left to decide.
+ *
+ * Shared by `<Analytics />` and `<Ads />` on purpose: the inert-markup rule
+ * (`type="text/plain"`, the URL on `data-src`, never a live `src`) is the whole
+ * consent gate, and it must have exactly one implementation. What differs between
+ * the two is where the tag comes from and who decides its category, which is why
+ * they have separate resolvers over one shape rather than one resolver over two
+ * vocabularies.
+ *
+ * `key` is left to each resolver: analytics keys are its four providers, ads keys
+ * are `AdProvider`. Widening it into one union here would let a provider from
+ * either side satisfy a check meant for the other.
+ */
+export interface GatedTag {
   /** The provider as a reader would recognise it — used in warnings. */
   provider: string;
   category: ConsentCategory;
@@ -127,6 +140,11 @@ export interface ResolvedTag {
   attrs: Record<string, string>;
 }
 
+/** One analytics tag. */
+export interface ResolvedTag extends GatedTag {
+  key: 'googleAnalytics' | 'clarity' | 'matomo' | 'plausible';
+}
+
 export interface ResolvedAnalytics {
   tags: ResolvedTag[];
   /** Does anything here need `@getvitops/core/consent` loaded? */
@@ -316,7 +334,7 @@ export function resolveAnalytics(
 }
 
 /** Which optional categories a set of tags actually needs a visitor to decide. */
-export function consentCategories(tags: ResolvedTag[]): OptionalConsentCategory[] {
+export function consentCategories(tags: GatedTag[]): OptionalConsentCategory[] {
   const used = new Set<OptionalConsentCategory>();
   for (const tag of tags) {
     if (tag.category !== 'necessary') used.add(tag.category);

package/src/components/Ads.astro

@@ -0,0 +1,47 @@
+---
+/**
+ * <Ads /> — the site's advertising pixels, off the critical path and behind the
+ * consent gate. Place in your layout's <head>; requires the vitops()
+ * integration, which supplies `virtual:getvitops/head`.
+ *
+ * A dumb renderer over `resolveAds()` (src/ads.ts) — which properties, which
+ * consent category, which cookies and whether this environment fires at all are
+ * decided there and unit-tested. Nothing in this file chooses anything.
+ *
+ * The properties come from the site config's `site.ads` block, not from an
+ * integration option: the ad account is a fact about the site, and the same block
+ * drives `vitops ads setup` (the domain-verification record), `vitops ads lint`
+ * and the cookie notice `vitops legal` generates. One source, so a pixel cannot be
+ * running while the site's own notice omits it.
+ *
+ * Pairs with <Tracking />, which captures the click ID the pixel's platform
+ * stamped on the landing URL. Neither implies the other — attribution works with
+ * no pixel, and a pixel works with no attribution — but a site running ads
+ * normally wants both.
+ */
+import { resolveAds } from '../ads.ts';
+import type { AnalyticsStrategy } from '../analytics.ts';
+import GatedTags from './GatedTags.astro';
+// @ts-ignore — virtual module provided by the vitops() integration at build time
+import head from 'virtual:getvitops/head';
+
+interface Props {
+  /** Render nothing on this page. Defaults to true (the per-environment switch is `environments.<env>.ads`). */
+  enabled?: boolean;
+  /** Override the load strategy for this page. */
+  strategy?: AnalyticsStrategy;
+}
+const { enabled = true, strategy } = Astro.props;
+
+// `head.ads` is already environment-resolved by the integration; `enabled` here is
+// the per-page override on top of it.
+const { tags } = enabled
+  ? resolveAds(head.ads?.properties, {
+      consent: head.consent,
+      enabled: head.ads?.enabled,
+      ...(strategy ? { strategy } : {}),
+    })
+  : { tags: [] };
+---
+
+<GatedTags tags={tags} />

package/src/components/Analytics.astro

@@ -8,17 +8,14 @@
  * about which tag, which consent category and which cookies lives there and is
  * unit-tested. Nothing in this file chooses anything.
  *
- * The gated tags are `type="text/plain"`, which is the whole trick: the browser
- * never parses the body as script and never fetches the library, so an undecided
- * or declining visitor's page issues no third-party request at all. Consent
- * implemented by *asking a tracker not to track* is a promise; this is a fact
- * about the document. `@getvitops/core/consent` (loaded by <Head />) activates
- * them when their category is granted and their strategy has fired.
- *
- * Emits no `preconnect` on purpose: warming a connection at parse time is exactly
- * the critical-path cost the `idle` strategy exists to avoid.
+ * The markup itself is <GatedTags />, shared with <Ads />: the inert
+ * `type="text/plain"` + `data-src` shape is the whole gate, and it has exactly one
+ * implementation. <Ads /> is a sibling rather than part of this component because
+ * ad properties come from the site config, state their own consent category and
+ * switch per environment separately — see src/ads.ts.
  */
 import { type AnalyticsStrategy, resolveAnalytics } from '../analytics.ts';
+import GatedTags from './GatedTags.astro';
 // @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 
@@ -36,24 +33,4 @@ const { tags } = enabled
   : { tags: [] };
 ---
 
-{tags.map((tag) => tag.gated
-  ? (
-      <script
-        is:inline
-        type="text/plain"
-        data-vitops-tag
-        data-consent={tag.category}
-        data-strategy={tag.strategy}
-        data-src={tag.src}
-        data-consent-cookies={tag.cookies.length ? tag.cookies.join(',') : undefined}
-        {...tag.attrs}
-        set:html={tag.inline}
-      />
-    )
-  : (
-      <>
-        {tag.inline && <script is:inline set:html={tag.inline} />}
-        {tag.src && <script is:inline async src={tag.src} {...tag.attrs}></script>}
-      </>
-    )
-)}
+<GatedTags tags={tags} />

package/src/components/GatedTags.astro

@@ -0,0 +1,46 @@
+---
+/**
+ * <GatedTags /> — the one place a third-party tag becomes markup.
+ *
+ * Shared by <Analytics /> and <Ads />, and shared deliberately: the gate is
+ * `type="text/plain"` with the URL on `data-src`, so the browser never parses the
+ * body as script and never fetches the library. An undecided or declining
+ * visitor's page issues no third-party request at all. Consent implemented by
+ * *asking a tracker not to track* is a promise; this is a fact about the document
+ * — and a fact with two implementations is one rewrite away from being neither.
+ *
+ * Decides nothing. Every tag arrives fully resolved from `analytics.ts` or
+ * `ads.ts`, both of which are pure and unit-tested.
+ *
+ * Emits no `preconnect` on purpose: warming a connection at parse time is exactly
+ * the critical-path cost the `idle` strategy exists to avoid.
+ */
+import type { GatedTag } from '../analytics.ts';
+
+interface Props {
+  tags: GatedTag[];
+}
+const { tags } = Astro.props;
+---
+
+{tags.map((tag) => tag.gated
+  ? (
+      <script
+        is:inline
+        type="text/plain"
+        data-vitops-tag
+        data-consent={tag.category}
+        data-strategy={tag.strategy}
+        data-src={tag.src}
+        data-consent-cookies={tag.cookies.length ? tag.cookies.join(',') : undefined}
+        {...tag.attrs}
+        set:html={tag.inline}
+      />
+    )
+  : (
+      <>
+        {tag.inline && <script is:inline set:html={tag.inline} />}
+        {tag.src && <script is:inline async src={tag.src} {...tag.attrs}></script>}
+      </>
+    )
+)}

package/src/scripts/tracking.ts

@@ -39,6 +39,8 @@ const CLICK_ID_PARAMS = [
   'rdt_cid', // Reddit
   'ScCid', // Snapchat
   'msclkid', // Microsoft/Bing
+  'li_fat_id', // LinkedIn
+  'epik', // Pinterest
 ] as const;
 
 const UTM_PARAMS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'] as const;

package/virtual.d.ts

@@ -52,6 +52,12 @@ declare module 'virtual:getvitops/head' {
     // the others, and the offered consent categories it checks against are known
     // only there.
     tracking: { enabled: boolean; category: string; cookies: string[] } | null;
+    // The site config's `site.ads` block plus this environment's switch —
+    // structurally `{ enabled, properties }` (src/ads.ts), re-typed by <Ads /> on
+    // the way into `resolveAds`. Read in the integration because that is where the
+    // site config is already parsed, and because a pixel is a `marketing` demand
+    // the banner must have a row for.
+    ads: { enabled: boolean; properties: Record<string, unknown> } | null;
   }
   const data: HeadData;
   export default data;