@sarimarcus/content-sites-core 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.22.0 (2026-10-04)
+
+- New `./affiliate`: `createGygCmp(siteKey)` (the GYG `cmp=` tagger and `tagGygLinksInHtml`), `gygProductId` (one `-t<digits>` pattern for every site), `cmpSegment`, `amazonProductUrl`, `bookingSearchUrl` and `travelpayoutsWidgetSrc`. Sites pass their partner ids and destinations in; output is byte-identical to the per-site builders it replaces. `./url` now exports `pageTypeOf` (SLA-2919).
+
 ## 0.21.0 (2026-10-02)
 
 - New `./images`: one width ladder (`IMAGE_LADDER`, `ladderWidths`, `snapWidth`, `variantRungs`) and `./images/service`, an Astro image service that never encodes. It serves committed WebP variants from the site's `image-variants/` and the source bytes at the native width, so production srcsets point at real files of the width they claim; previously every width resolved to one file under the noop service. `./images/variants` and the `content-sites-image-variants` bin generate, prune and check the variants (`sharp` is an optional peer). `defineSiteConfig` installs the service on every build in place of noop/sharp (SLA-2912).

package/README.md

@@ -4,7 +4,7 @@ Non-visual code shared by the content sites: generic utilities, Astro config bui
 and the type contracts `ui` and `tourism` build on (for example the card item and tag-link shapes that
 today's ui components import from tourism code).
 
-Named entry points: `url`, `dates`, `geo`, `dom`, `text`, `config`, `types`, `schema`, `interludes` and `images` (`src/internal` is never exported). No `.astro`
+Named entry points: `url`, `affiliate`, `dates`, `geo`, `dom`, `text`, `config`, `types`, `schema`, `interludes` and `images` (`src/internal` is never exported). No `.astro`
 files. Lowest layer: imports nothing from the other packages; its one runtime dependency is `marked` (`readingTime`). Ownership per path is in
 `.planning/platform/catalogue.json` (owner `core`).
 

package/dist/affiliate/gyg.d.ts

@@ -0,0 +1,28 @@
+/** GetYourGuide product id: the `-t<digits>` segment of a tour URL. */
+export declare function gygProductId(url: string): string;
+/**
+ * cmp segments are lowercased and non-alphanumerics collapse to a single hyphen.
+ *
+ * Exported so a component can stamp the SAME normalised string into its data-track-*-placement attributes.
+ */
+export declare function cmpSegment(raw: string): string;
+export interface GygCmp {
+    /** Append `cmp=<siteKey>__<pageType>__<placement>` to a GetYourGuide affiliate URL. */
+    withGygCmp(href: string, pathname: string, placement: string): string;
+    /** Tag every GetYourGuide partner link inside already-rendered HTML. */
+    tagGygLinksInHtml(html: string, pathname: string, placement?: string): string;
+}
+/**
+ * The GYG campaign tagger for one site. `siteKey` is the first cmp segment; scripts/validate-gyg-cmp.mjs enforces
+ * the `<siteKey>__<pageType>__<placement>` shape against the built dist.
+ *
+ * Three deliberate no-ops, each a wrong-attribution bug if dropped:
+ *   - non-GYG hosts pass through (cmp is a GYG parameter, meaningless elsewhere);
+ *   - GYG URLs with no partner id pass through: those are editorial citations, not monetized CTAs;
+ *   - an existing `cmp` is left alone, so tagging is idempotent. That is not an escape hatch for a hand-set
+ *     campaign value: the gate refuses any other shape.
+ *
+ * The cmp is appended textually rather than via `searchParams.set` + `toString()`, because that round-trip
+ * re-serializes the whole query string (`extra=a%20b` becomes `extra=a+b`).
+ */
+export declare function createGygCmp(siteKey: string): GygCmp;

package/dist/affiliate/gyg.js

@@ -0,0 +1,60 @@
+import { pageTypeOf } from "../url/pageType.js";
+const GYG_HOST = /(^|\.)getyourguide\.com$/;
+/** GetYourGuide product id: the `-t<digits>` segment of a tour URL. */
+export function gygProductId(url) {
+    return url.match(/-t(\d+)/)?.[1] ?? '';
+}
+/**
+ * cmp segments are lowercased and non-alphanumerics collapse to a single hyphen.
+ *
+ * Exported so a component can stamp the SAME normalised string into its data-track-*-placement attributes.
+ */
+export function cmpSegment(raw) {
+    return raw.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+/**
+ * The GYG campaign tagger for one site. `siteKey` is the first cmp segment; scripts/validate-gyg-cmp.mjs enforces
+ * the `<siteKey>__<pageType>__<placement>` shape against the built dist.
+ *
+ * Three deliberate no-ops, each a wrong-attribution bug if dropped:
+ *   - non-GYG hosts pass through (cmp is a GYG parameter, meaningless elsewhere);
+ *   - GYG URLs with no partner id pass through: those are editorial citations, not monetized CTAs;
+ *   - an existing `cmp` is left alone, so tagging is idempotent. That is not an escape hatch for a hand-set
+ *     campaign value: the gate refuses any other shape.
+ *
+ * The cmp is appended textually rather than via `searchParams.set` + `toString()`, because that round-trip
+ * re-serializes the whole query string (`extra=a%20b` becomes `extra=a+b`).
+ */
+export function createGygCmp(siteKey) {
+    function withGygCmp(href, pathname, placement) {
+        let u;
+        try {
+            u = new URL(href);
+        }
+        catch {
+            return href;
+        }
+        if (!GYG_HOST.test(u.hostname.replace(/^www\./, '')))
+            return href;
+        if (!u.searchParams.has('partner_id'))
+            return href;
+        if (u.searchParams.has('cmp'))
+            return href;
+        const type = cmpSegment(pageTypeOf(pathname));
+        const place = cmpSegment(placement);
+        if (!type || !place)
+            return href;
+        // cmp is [a-z0-9-] segments joined by `__`, so it needs no percent-encoding.
+        const hashAt = href.indexOf('#');
+        const base = hashAt === -1 ? href : href.slice(0, hashAt);
+        const frag = hashAt === -1 ? '' : href.slice(hashAt);
+        return `${base}${base.includes('?') ? '&' : '?'}cmp=${siteKey}__${type}__${place}${frag}`;
+    }
+    function tagGygLinksInHtml(html, pathname, placement = 'prose') {
+        return html.replace(/href="(https?:\/\/[^"]*getyourguide\.com[^"]*)"/g, 
+        // `&amp;` is the standard encoding inside an attribute; without decoding it first, new URL() reads the key
+        // as `amp;partner_id` and the link ships untagged.
+        (_m, href) => `href="${withGygCmp(href.replace(/&amp;/g, '&'), pathname, placement).replace(/&(?!amp;|lt;|gt;|quot;|apos;|#\d)/g, '&amp;')}"`);
+    }
+    return { withGygCmp, tagGygLinksInHtml };
+}

package/dist/affiliate/index.d.ts

@@ -0,0 +1,6 @@
+export { gygProductId, cmpSegment, createGygCmp } from './gyg.ts';
+export type { GygCmp } from './gyg.ts';
+export { amazonProductUrl, bookingSearchUrl } from './links.ts';
+export type { BookingSearch } from './links.ts';
+export { travelpayoutsWidgetSrc } from './travelpayouts.ts';
+export type { WidgetLoader, WidgetAccount, WidgetOptions } from './travelpayouts.ts';

package/dist/affiliate/index.js

@@ -0,0 +1,4 @@
+// Public surface of @sarimarcus/content-sites-core/affiliate.
+export { gygProductId, cmpSegment, createGygCmp } from "./gyg.js";
+export { amazonProductUrl, bookingSearchUrl } from "./links.js";
+export { travelpayoutsWidgetSrc } from "./travelpayouts.js";

package/dist/affiliate/links.d.ts

@@ -0,0 +1,17 @@
+/** Amazon product page. With a tag (even an empty one) the path gains a trailing slash before the query; without one it has none. */
+export declare function amazonProductUrl(asin: string, tag?: string): string;
+export interface BookingSearch {
+    /** Free text. Alone it resolves to a property; with `destId` the destination wins. */
+    ss: string;
+    destId?: string;
+    destType?: string;
+    checkin?: string;
+    checkout?: string;
+}
+/**
+ * A Booking.com search for two adults in one room.
+ *
+ * Carries no affiliate parameter: Travelpayouts' Emerald Link Switcher rewrites raw booking.com hrefs into tracked
+ * redirects at click time. Parameter order is fixed (ss, dest_id, dest_type, checkin, checkout, then the party).
+ */
+export declare function bookingSearchUrl({ ss, destId, destType, checkin, checkout }: BookingSearch): string;

package/dist/affiliate/links.js

@@ -0,0 +1,27 @@
+/** Amazon product page. With a tag (even an empty one) the path gains a trailing slash before the query; without one it has none. */
+export function amazonProductUrl(asin, tag) {
+    const base = `https://www.amazon.com/dp/${asin}`;
+    return tag === undefined ? base : `${base}/?${new URLSearchParams({ tag })}`;
+}
+/**
+ * A Booking.com search for two adults in one room.
+ *
+ * Carries no affiliate parameter: Travelpayouts' Emerald Link Switcher rewrites raw booking.com hrefs into tracked
+ * redirects at click time. Parameter order is fixed (ss, dest_id, dest_type, checkin, checkout, then the party).
+ */
+export function bookingSearchUrl({ ss, destId, destType = 'city', checkin, checkout }) {
+    const params = new URLSearchParams({ ss });
+    if (destId) {
+        params.set('dest_id', destId);
+        params.set('dest_type', destType);
+    }
+    if (checkin)
+        params.set('checkin', checkin);
+    if (checkout)
+        params.set('checkout', checkout);
+    params.set('group_adults', '2');
+    params.set('group_children', '0');
+    params.set('no_rooms', '1');
+    params.set('lang', 'en-gb');
+    return `https://www.booking.com/searchresults.html?${params.toString()}`;
+}

package/dist/affiliate/travelpayouts.d.ts

@@ -0,0 +1,38 @@
+/** Where a Travelpayouts widget kind loads from and the ids it reports under. Declared in ui affiliate/resources.ts. */
+export interface WidgetLoader {
+    /** The loader script URL without its query, e.g. `https://<host>/content`. */
+    url: string;
+    promoId: string;
+    campaignId?: string;
+}
+export interface WidgetAccount {
+    /** The site's traffic source, which splits revenue per site. */
+    trs: string;
+    /** The Travelpayouts marker. */
+    marker: string;
+}
+export type WidgetOptions = {
+    kind: 'hotel';
+    direction: string;
+} | {
+    kind: 'activity';
+    place: string;
+} | {
+    kind: 'train';
+} | {
+    kind: 'car';
+    country: string;
+    city: string;
+    colors: {
+        background: string;
+        font: string;
+        button: string;
+        buttonFont: string;
+    };
+    buttonText?: string;
+};
+/**
+ * A Travelpayouts widget loader URL. Each kind keeps the parameter order Travelpayouts issued, which differs per kind
+ * (hotel puts promo_id before campaign_id, activity and car after).
+ */
+export declare function travelpayoutsWidgetSrc(loader: WidgetLoader, account: WidgetAccount, options: WidgetOptions): string;

package/dist/affiliate/travelpayouts.js

@@ -0,0 +1,33 @@
+/**
+ * A Travelpayouts widget loader URL. Each kind keeps the parameter order Travelpayouts issued, which differs per kind
+ * (hotel puts promo_id before campaign_id, activity and car after).
+ */
+export function travelpayoutsWidgetSrc(loader, account, options) {
+    const ids = (order) => {
+        const promo = ['promo_id', loader.promoId];
+        const campaign = loader.campaignId ? [['campaign_id', loader.campaignId]] : [];
+        return order === 'promo-first' ? [promo, ...campaign] : [...campaign, promo];
+    };
+    const who = [['trs', account.trs], ['shmarker', account.marker]];
+    let pairs;
+    switch (options.kind) {
+        case 'hotel':
+            pairs = [...who, ['locale', 'en'], ['default_direction', options.direction], ['sustainable', 'false'], ['deals', 'false'],
+                ['border_radius', '5'], ['plain', 'true'], ['powered_by', 'true'], ...ids('promo-first')];
+            break;
+        case 'activity':
+            pairs = [...who, ['place', options.place], ['items', '3'], ['locale', 'en-US'], ['powered_by', 'true'], ...ids('campaign-first')];
+            break;
+        case 'train':
+            pairs = [['currency', 'USD'], ...who, ['powered_by', 'true'], ['locale', 'en'], ['mode', 'default'], ['theme', 'white'],
+                ['layout', 'fluid'], ...ids('promo-first')];
+            break;
+        case 'car':
+            pairs = [['currency', 'usd'], ...who, ['country', options.country], ['city', options.city], ['locale', 'en'], ['powered_by', 'true'],
+                ['bg_color', options.colors.background], ['font_color', options.colors.font], ['button_color', options.colors.button],
+                ['button_font_color', options.colors.buttonFont], ['button_text', options.buttonText ?? 'Search'], ['rounded_corners', 'true'],
+                ['benefits', 'true'], ['dc_powered_by', 'false'], ['supplier_logos', 'false'], ...ids('campaign-first')];
+            break;
+    }
+    return `${loader.url}?${pairs.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}`;
+}

package/dist/url/index.d.ts

@@ -4,3 +4,4 @@ export { normalizeHref, extractProseHrefs, dedupRelated } from './relatedDedup.t
 export { buildImageMap, keyBySlug } from './imageMap.ts';
 export { articleFeedItem } from './feed.ts';
 export type { FeedArticle, FeedItem } from './feed.ts';
+export { pageTypeOf } from './pageType.ts';

package/dist/url/index.js

@@ -4,3 +4,4 @@ export { getOgImagePath } from "./ogImage.js";
 export { normalizeHref, extractProseHrefs, dedupRelated } from "./relatedDedup.js";
 export { buildImageMap, keyBySlug } from "./imageMap.js";
 export { articleFeedItem } from "./feed.js";
+export { pageTypeOf } from "./pageType.js";

package/dist/url/pageType.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Page type: the first path segment, 'home' at the root.
+ *
+ * The single definition behind both the GA4 `page_type` param (runtime pathname, '/plan/x') and a site's GYG `cmp`
+ * segment (BUILD-time `Astro.url.pathname`, '/index.html' under build.format 'file'). The `.html`/`index`
+ * normalisation is what makes the two agree.
+ */
+export declare function pageTypeOf(pathname: string): string;

package/dist/url/pageType.js

@@ -0,0 +1,14 @@
+/**
+ * Page type: the first path segment, 'home' at the root.
+ *
+ * The single definition behind both the GA4 `page_type` param (runtime pathname, '/plan/x') and a site's GYG `cmp`
+ * segment (BUILD-time `Astro.url.pathname`, '/index.html' under build.format 'file'). The `.html`/`index`
+ * normalisation is what makes the two agree.
+ */
+export function pageTypeOf(pathname) {
+    const first = pathname.split('/').filter(Boolean)[0];
+    if (!first)
+        return 'home';
+    const bare = first.replace(/\.html$/, '');
+    return bare === 'index' || bare === '' ? 'home' : bare;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,10 @@
       "types": "./dist/url/index.d.ts",
       "default": "./dist/url/index.js"
     },
+    "./affiliate": {
+      "types": "./dist/affiliate/index.d.ts",
+      "default": "./dist/affiliate/index.js"
+    },
     "./dates": {
       "types": "./dist/dates/index.d.ts",
       "default": "./dist/dates/index.js"

package/src/affiliate/gyg.ts

@@ -0,0 +1,66 @@
+import { pageTypeOf } from '../url/pageType.ts';
+
+const GYG_HOST = /(^|\.)getyourguide\.com$/;
+
+/** GetYourGuide product id: the `-t<digits>` segment of a tour URL. */
+export function gygProductId(url: string): string {
+  return url.match(/-t(\d+)/)?.[1] ?? '';
+}
+
+/**
+ * cmp segments are lowercased and non-alphanumerics collapse to a single hyphen.
+ *
+ * Exported so a component can stamp the SAME normalised string into its data-track-*-placement attributes.
+ */
+export function cmpSegment(raw: string): string {
+  return raw.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+export interface GygCmp {
+  /** Append `cmp=<siteKey>__<pageType>__<placement>` to a GetYourGuide affiliate URL. */
+  withGygCmp(href: string, pathname: string, placement: string): string;
+  /** Tag every GetYourGuide partner link inside already-rendered HTML. */
+  tagGygLinksInHtml(html: string, pathname: string, placement?: string): string;
+}
+
+/**
+ * The GYG campaign tagger for one site. `siteKey` is the first cmp segment; scripts/validate-gyg-cmp.mjs enforces
+ * the `<siteKey>__<pageType>__<placement>` shape against the built dist.
+ *
+ * Three deliberate no-ops, each a wrong-attribution bug if dropped:
+ *   - non-GYG hosts pass through (cmp is a GYG parameter, meaningless elsewhere);
+ *   - GYG URLs with no partner id pass through: those are editorial citations, not monetized CTAs;
+ *   - an existing `cmp` is left alone, so tagging is idempotent. That is not an escape hatch for a hand-set
+ *     campaign value: the gate refuses any other shape.
+ *
+ * The cmp is appended textually rather than via `searchParams.set` + `toString()`, because that round-trip
+ * re-serializes the whole query string (`extra=a%20b` becomes `extra=a+b`).
+ */
+export function createGygCmp(siteKey: string): GygCmp {
+  function withGygCmp(href: string, pathname: string, placement: string): string {
+    let u: URL;
+    try { u = new URL(href); } catch { return href; }
+    if (!GYG_HOST.test(u.hostname.replace(/^www\./, ''))) return href;
+    if (!u.searchParams.has('partner_id')) return href;
+    if (u.searchParams.has('cmp')) return href;
+    const type = cmpSegment(pageTypeOf(pathname));
+    const place = cmpSegment(placement);
+    if (!type || !place) return href;
+    // cmp is [a-z0-9-] segments joined by `__`, so it needs no percent-encoding.
+    const hashAt = href.indexOf('#');
+    const base = hashAt === -1 ? href : href.slice(0, hashAt);
+    const frag = hashAt === -1 ? '' : href.slice(hashAt);
+    return `${base}${base.includes('?') ? '&' : '?'}cmp=${siteKey}__${type}__${place}${frag}`;
+  }
+
+  function tagGygLinksInHtml(html: string, pathname: string, placement = 'prose'): string {
+    return html.replace(
+      /href="(https?:\/\/[^"]*getyourguide\.com[^"]*)"/g,
+      // `&amp;` is the standard encoding inside an attribute; without decoding it first, new URL() reads the key
+      // as `amp;partner_id` and the link ships untagged.
+      (_m, href: string) => `href="${withGygCmp(href.replace(/&amp;/g, '&'), pathname, placement).replace(/&(?!amp;|lt;|gt;|quot;|apos;|#\d)/g, '&amp;')}"`,
+    );
+  }
+
+  return { withGygCmp, tagGygLinksInHtml };
+}

package/src/affiliate/index.ts

@@ -0,0 +1,7 @@
+// Public surface of @sarimarcus/content-sites-core/affiliate.
+export { gygProductId, cmpSegment, createGygCmp } from './gyg.ts';
+export type { GygCmp } from './gyg.ts';
+export { amazonProductUrl, bookingSearchUrl } from './links.ts';
+export type { BookingSearch } from './links.ts';
+export { travelpayoutsWidgetSrc } from './travelpayouts.ts';
+export type { WidgetLoader, WidgetAccount, WidgetOptions } from './travelpayouts.ts';

package/src/affiliate/links.ts

@@ -0,0 +1,35 @@
+/** Amazon product page. With a tag (even an empty one) the path gains a trailing slash before the query; without one it has none. */
+export function amazonProductUrl(asin: string, tag?: string): string {
+  const base = `https://www.amazon.com/dp/${asin}`;
+  return tag === undefined ? base : `${base}/?${new URLSearchParams({ tag })}`;
+}
+
+export interface BookingSearch {
+  /** Free text. Alone it resolves to a property; with `destId` the destination wins. */
+  ss: string;
+  destId?: string;
+  destType?: string;
+  checkin?: string;
+  checkout?: string;
+}
+
+/**
+ * A Booking.com search for two adults in one room.
+ *
+ * Carries no affiliate parameter: Travelpayouts' Emerald Link Switcher rewrites raw booking.com hrefs into tracked
+ * redirects at click time. Parameter order is fixed (ss, dest_id, dest_type, checkin, checkout, then the party).
+ */
+export function bookingSearchUrl({ ss, destId, destType = 'city', checkin, checkout }: BookingSearch): string {
+  const params = new URLSearchParams({ ss });
+  if (destId) {
+    params.set('dest_id', destId);
+    params.set('dest_type', destType);
+  }
+  if (checkin) params.set('checkin', checkin);
+  if (checkout) params.set('checkout', checkout);
+  params.set('group_adults', '2');
+  params.set('group_children', '0');
+  params.set('no_rooms', '1');
+  params.set('lang', 'en-gb');
+  return `https://www.booking.com/searchresults.html?${params.toString()}`;
+}

package/src/affiliate/travelpayouts.ts

@@ -0,0 +1,62 @@
+/** Where a Travelpayouts widget kind loads from and the ids it reports under. Declared in ui affiliate/resources.ts. */
+export interface WidgetLoader {
+  /** The loader script URL without its query, e.g. `https://<host>/content`. */
+  url: string;
+  promoId: string;
+  campaignId?: string;
+}
+
+export interface WidgetAccount {
+  /** The site's traffic source, which splits revenue per site. */
+  trs: string;
+  /** The Travelpayouts marker. */
+  marker: string;
+}
+
+export type WidgetOptions =
+  | { kind: 'hotel'; direction: string }
+  | { kind: 'activity'; place: string }
+  | { kind: 'train' }
+  | {
+      kind: 'car';
+      country: string;
+      city: string;
+      colors: { background: string; font: string; button: string; buttonFont: string };
+      buttonText?: string;
+    };
+
+type Pair = [string, string];
+
+/**
+ * A Travelpayouts widget loader URL. Each kind keeps the parameter order Travelpayouts issued, which differs per kind
+ * (hotel puts promo_id before campaign_id, activity and car after).
+ */
+export function travelpayoutsWidgetSrc(loader: WidgetLoader, account: WidgetAccount, options: WidgetOptions): string {
+  const ids = (order: 'promo-first' | 'campaign-first'): Pair[] => {
+    const promo: Pair = ['promo_id', loader.promoId];
+    const campaign: Pair[] = loader.campaignId ? [['campaign_id', loader.campaignId]] : [];
+    return order === 'promo-first' ? [promo, ...campaign] : [...campaign, promo];
+  };
+  const who: Pair[] = [['trs', account.trs], ['shmarker', account.marker]];
+  let pairs: Pair[];
+  switch (options.kind) {
+    case 'hotel':
+      pairs = [...who, ['locale', 'en'], ['default_direction', options.direction], ['sustainable', 'false'], ['deals', 'false'],
+        ['border_radius', '5'], ['plain', 'true'], ['powered_by', 'true'], ...ids('promo-first')];
+      break;
+    case 'activity':
+      pairs = [...who, ['place', options.place], ['items', '3'], ['locale', 'en-US'], ['powered_by', 'true'], ...ids('campaign-first')];
+      break;
+    case 'train':
+      pairs = [['currency', 'USD'], ...who, ['powered_by', 'true'], ['locale', 'en'], ['mode', 'default'], ['theme', 'white'],
+        ['layout', 'fluid'], ...ids('promo-first')];
+      break;
+    case 'car':
+      pairs = [['currency', 'usd'], ...who, ['country', options.country], ['city', options.city], ['locale', 'en'], ['powered_by', 'true'],
+        ['bg_color', options.colors.background], ['font_color', options.colors.font], ['button_color', options.colors.button],
+        ['button_font_color', options.colors.buttonFont], ['button_text', options.buttonText ?? 'Search'], ['rounded_corners', 'true'],
+        ['benefits', 'true'], ['dc_powered_by', 'false'], ['supplier_logos', 'false'], ...ids('campaign-first')];
+      break;
+  }
+  return `${loader.url}?${pairs.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}`;
+}

package/src/url/index.ts

@@ -5,3 +5,4 @@ export { normalizeHref, extractProseHrefs, dedupRelated } from './relatedDedup.t
 export { buildImageMap, keyBySlug } from './imageMap.ts';
 export { articleFeedItem } from './feed.ts';
 export type { FeedArticle, FeedItem } from './feed.ts';
+export { pageTypeOf } from './pageType.ts';

package/src/url/pageType.ts

@@ -0,0 +1,13 @@
+/**
+ * Page type: the first path segment, 'home' at the root.
+ *
+ * The single definition behind both the GA4 `page_type` param (runtime pathname, '/plan/x') and a site's GYG `cmp`
+ * segment (BUILD-time `Astro.url.pathname`, '/index.html' under build.format 'file'). The `.html`/`index`
+ * normalisation is what makes the two agree.
+ */
+export function pageTypeOf(pathname: string): string {
+  const first = pathname.split('/').filter(Boolean)[0];
+  if (!first) return 'home';
+  const bare = first.replace(/\.html$/, '');
+  return bare === 'index' || bare === '' ? 'home' : bare;
+}