@shware/analytics 8.2.0 → 8.5.0

package/README.md

@@ -9,8 +9,8 @@ Workers), but calling `track()` there shares one session and one visitor across
 isolate serves.
 
 Server-side conversions go the other way: store the client's events, then hand them to
-`@shware/analytics/server`, which takes a `TrackEvent` and forwards it to the Meta, Reddit, OpenAI
-and LinkedIn conversions APIs.
+`@shware/analytics/server`, which takes a `TrackEvent` and forwards it to the Meta, Reddit, OpenAI,
+LinkedIn, Google Ads and Microsoft Advertising conversions APIs.
 
 ## Config
 
@@ -46,6 +46,15 @@ function Button() {
 }
 ```
 
+## Page views
+
+`page_view` fires on a path or query change, never on a hash change — GA4's enhanced measurement,
+Next.js's `usePathname` + `useSearchParams` pattern and PostHog's `history_change` all draw the
+line there (`?page=2` is another page to a funnel, `#faq` is not). Tracking parameters (`utm_*`
+and the ad click ids) are ignored when comparing, so a landing page that cleans them out of its
+URL with `replaceState` does not count itself twice. `page_load_id` rotates on exactly the same
+changes. The framework `Analytics` components wire this up.
+
 ## Backend API
 
 - /analytics/tracks: track events
@@ -124,4 +133,71 @@ We strongly recommend using the Reddit Pixel and Conversions API (CAPI) together
 If we receive an Insight Tag event and a Conversions API event from the same account with the same eventId, we discard the Conversions API event and count only the Insight Tag event in campaign reporting.
 ``
 
+### Microsoft Advertising (Bing Ads)
+
+Microsoft recommends the UET tag and the Conversions API (CAPI) together. The two deduplicate on
+(`tagId`, `eventName`, `eventId`): the browser sends the internal event name as the UET action with
+the event id as `event_id`, the server sends the same name as `eventName` with the same id.
+
+Browser — pass the tag id to the framework `Analytics` component (`<Analytics uetTagId="97267979" />`
+from `@shware/analytics/tanstack`, `/next` or `/react-router`), which inlines Microsoft's snippet
+with `enableAutoSpaTracking: true`: the tag owns page loads, `sendUETEvent` drops `page_view` and
+forwards everything else. Then:
+
+```ts
+import {
+  sendUETEvent,
+  setUETUser,
+  setUETConsent,
+  sendUETIdSync,
+} from '@shware/analytics/third-parties';
+
+setupAnalytics({
+  thirdPartyTrackers: [sendUETEvent],
+  // Enhanced conversions: the tag hashes the email/phone itself before they leave the page.
+  thirdPartyUserSetters: [setUETUser()],
+});
+// Consent mode (EEA/UK/CH): push `default` before the tag loads, `update` on the visitor's choice.
+setUETConsent('default', { ad_storage: 'denied', wait_for_update: 2000 });
+// ID Sync, once per session: ties the visitor id CAPI sends as `anonymousId` to Microsoft's ids.
+// Required for remarketing built from CAPI events, recommended for measurement. `VID` must equal
+// `anonymousId` and `UID` must equal `externalId`: pass the SDK visitor id and the raw user id —
+// the pixel hashes the user id with the same SHA-256 the server sender uses.
+sendUETIdSync({ customerId: 255004870, visitorId: (await getVisitor()).id, userId: user.id });
+```
+
+Server — the token comes from the UET tag's "Use Conversions API" step (or the Campaign Management
+API's `UetTagAuthKey/Query`; an account whose tag setup lacks that option has to ask Microsoft
+Advertising support), `tagId` is the UET tag id:
+
+```ts
+import { sendMicrosoftEvents } from '@shware/analytics/server';
+
+await sendMicrosoftEvents(process.env.MS_ADS_CAPI_TOKEN, 97267979, events, userData, {
+  consent: 'granted',
+});
+```
+
+- msclkid: from url params, kept in the tag's own `_uetmsclkid` cookie (`_uet<id>`, 90 days). That
+  cookie is Microsoft's ITP answer, but bat.js writes it with `document.cookie`, which Safari caps
+  at 7 days (24h on a landing page decorated by a classified domain — a bing.com click). Register
+  the click-id middleware and `resolveClickIdCookies` re-issues it over HTTP on every document
+  response, restoring the 90-day window; give it the same `domain` the tag uses (eTLD+1) so the
+  two write one cookie, not two. Sent to CAPI as a dashed UUID.
+- anonymousId / externalId: the SDK visitor id and SHA-256 of the user id — the same two values
+  `sendUETIdSync` sends as `VID` / `UID`, which Microsoft requires to match.
+- Consent: the tag writes `_uetmsclkid` only with `ad_storage` granted; the middleware writes it
+  from the URL regardless, so gate it with the middleware's `shouldPersist` where consent applies
+  (as for `_fbc` and `_gcl_*`).
+- Validation warnings on a 200 (a removed field, a skipped event) are logged with `console.warn`;
+  monitor them, the status code does not show them.
+- em / ph: SHA-256 of the normalized email (dots and `+alias` stripped from the user part for every
+  domain, lowercase) and of the E.164 phone.
+- `page_view` events are dropped by default (the tag already reports every page load); pass
+  `pageLoads: true` for a CAPI-only site to send them as `pageLoad` events, each `custom` event
+  then carrying the `pageLoadId` of the page load it happened on (the `page_load_id` tag, one
+  v4 UUID per page load). Not yet modelled in that mode: the revenue-only `custom` event a
+  destination-URL goal with variable revenue needs alongside its `pageLoad`. With the tag on the
+  page neither applies — the tag reports page loads itself.
+
 - [Click IDs](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/enabling-first-party-cookies?view=li-lms-2025-10&source=recommendations): get li_fat_id from url params and cookie

package/dist/click-id/index.cjs

@@ -2,8 +2,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let cookie = require("cookie");
 //#region src/click-id/index.ts
 /**
-* Server-side resolution of ad-click-id cookies (`_fbc`, `_gcl_aw`/`_gcl_gb`, `_rdt_cid`) from
-* the incoming request.
+* Server-side resolution of ad-click-id cookies (`_fbc`, `_gcl_aw`/`_gcl_gb`, `_rdt_cid`,
+* `_uetmsclkid`) from the incoming request.
 *
 * This is the framework-agnostic core meant to run on the *document* response (e.g. TanStack Start
 * server middleware, Next middleware). Setting `_fbc` via an HTTP `Set-Cookie` header on the top
@@ -12,16 +12,33 @@ let cookie = require("cookie");
 * cookies on a fbclid-decorated landing page to 24 hours, and the document response is never
 * classified as CNAME/IP cloaking (it is the reference the browser measures cloaking against).
 *
-* reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc
+* The Google pair follows the same architecture Google itself ships for server containers —
+* sGTM's Conversion Linker sets FPGCLAW via Set-Cookie for 90 days — and the sGTM ecosystem
+* productized for gtag's own cookies (stape Cookie Keeper re-issues `_gcl_*` over HTTP; vendor
+* case studies report 5–20% of Google Ads conversions recovered, up to +44% on the Safari
+* slice). One deployment caveat from WebKit's rules: the HTTP-cookie exemption holds only for
+* responses from the site's own infrastructure — a CNAME or third-party-IP host (a tagging
+* subdomain on someone else's cloud) gets its Set-Cookie silently capped to 7 days. This module
+* runs on the host's own document response, which is exactly the exempt case.
+*
+* references:
+* - https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc
+* - https://webkit.org/tracking-prevention/ (7d JS cookies, 24h on ad-decorated landings,
+*   CNAME/third-party-IP HTTP cookies capped to 7d, same-origin HTTP cookies exempt)
+* - https://www.simoahava.com/analytics/google-ads-server-side-tagging-google-tag-manager/
+*   (Conversion Linker → FPGCLAW via Set-Cookie, Google's own server-side equivalent)
+* - https://stape.io/helpdesk/documentation/cookie-keeper-power-up (the productized re-issue)
 */
 const FBC_TTL_MS = 7776e6;
 const RDT_CID_TTL_MS = 7776e6;
+const MSCLKID_TTL_MS = 7776e6;
 const GCL_TTL_MS = 7776e6;
 const CLOCK_SKEW_MS = 864e5;
 const FBC_COOKIE = "_fbc";
 const RDT_CID_COOKIE = "_rdt_cid";
 const GCL_AW_COOKIE = "_gcl_aw";
 const GCL_GB_COOKIE = "_gcl_gb";
+const UET_MSCLKID_COOKIE = "_uetmsclkid";
 /**
 * Parse `fb.<subdomainIndex>.<creationTime>.<fbclid>`.
 * Returns undefined for anything malformed — a fbclid never contains a dot, but joining the tail
@@ -77,6 +94,30 @@ function parseGcl(raw, now = Date.now()) {
 function formatGcl(clickId, now) {
 	return `GCL.${Math.floor(now / 1e3)}.${clickId}`;
 }
+const UET_MSCLKID_PREFIX = "_uet";
+const MSCLKID = /^[0-9a-f]{32}$/i;
+/**
+* Parse a `_uetmsclkid` value: `_uet<32 hex>`. Returns the click id, lowercased, or undefined
+* for anything bat.js itself would not read back.
+*/
+function parseUetMsclkid(raw) {
+	if (!raw || !raw.startsWith(UET_MSCLKID_PREFIX)) return void 0;
+	const clickId = raw.slice(4);
+	return MSCLKID.test(clickId) ? clickId.toLowerCase() : void 0;
+}
+/** Build a `_uetmsclkid` value in bat.js's own format. */
+function formatUetMsclkid(clickId) {
+	return `${UET_MSCLKID_PREFIX}${clickId.toLowerCase()}`;
+}
+/**
+* The click id as the Conversions API wants it: a dashed, lowercase UUID. The URL and the cookie
+* carry the 32-hex form; a value in any other shape is returned untouched for the API to judge.
+*/
+function formatMsclkid(clickId) {
+	const id = clickId.trim().toLowerCase();
+	if (!MSCLKID.test(id)) return id;
+	return `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`;
+}
 function searchParams(url) {
 	try {
 		return new URL(url).searchParams;
@@ -163,6 +204,15 @@ function resolveClickIdCookies(input) {
 		set(RDT_CID_COOKIE, urlRdtCid, RDT_CID_TTL_MS);
 		result.rdt_cid = urlRdtCid;
 	} else if (existingRdtCid) result.rdt_cid = existingRdtCid;
+	const urlMsclkid = params.get("msclkid")?.trim();
+	const existingMsclkid = parseUetMsclkid(jar[UET_MSCLKID_COOKIE]);
+	if (urlMsclkid && MSCLKID.test(urlMsclkid) && urlMsclkid.toLowerCase() !== existingMsclkid) {
+		set(UET_MSCLKID_COOKIE, formatUetMsclkid(urlMsclkid), MSCLKID_TTL_MS);
+		result.msclkid = urlMsclkid.toLowerCase();
+	} else if (existingMsclkid) {
+		result.msclkid = existingMsclkid;
+		if (refresh) set(UET_MSCLKID_COOKIE, formatUetMsclkid(existingMsclkid), MSCLKID_TTL_MS);
+	}
 	return result;
 }
 /** Serialize the resolved cookies into `Set-Cookie` header values. */
@@ -174,10 +224,14 @@ exports.FBC_COOKIE = FBC_COOKIE;
 exports.GCL_AW_COOKIE = GCL_AW_COOKIE;
 exports.GCL_GB_COOKIE = GCL_GB_COOKIE;
 exports.RDT_CID_COOKIE = RDT_CID_COOKIE;
+exports.UET_MSCLKID_COOKIE = UET_MSCLKID_COOKIE;
 exports.formatFbc = formatFbc;
 exports.formatGcl = formatGcl;
+exports.formatMsclkid = formatMsclkid;
+exports.formatUetMsclkid = formatUetMsclkid;
 exports.parseFbc = parseFbc;
 exports.parseGcl = parseGcl;
+exports.parseUetMsclkid = parseUetMsclkid;
 exports.resolveClickIdCookies = resolveClickIdCookies;
 exports.toSetCookieHeaders = toSetCookieHeaders;
 

package/dist/click-id/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["parseCookie","cookie","stringifySetCookie"],"sources":["../../src/click-id/index.ts"],"sourcesContent":["import { type SetCookie, parseCookie, stringifySetCookie } from 'cookie';\n\n/**\n * Server-side resolution of ad-click-id cookies (`_fbc`, `_gcl_aw`/`_gcl_gb`, `_rdt_cid`) from\n * the incoming request.\n *\n * This is the framework-agnostic core meant to run on the *document* response (e.g. TanStack Start\n * server middleware, Next middleware). Setting `_fbc` via an HTTP `Set-Cookie` header on the top\n * document — rather than `document.cookie` on the client — is what Meta officially recommends and is\n * the only reliable way to keep the cookie alive for 90 days in Safari: ITP caps JavaScript-set\n * cookies on a fbclid-decorated landing page to 24 hours, and the document response is never\n * classified as CNAME/IP cloaking (it is the reference the browser measures cloaking against).\n *\n * reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc\n */\n\n// Meta's recommended _fbc cookie expiry. Events Manager warns (\"Server sending expired fbclid\")\n// when the embedded creationTime is older than 90 days and match quality/attribution may degrade;\n// no hard drop is documented.\nconst FBC_TTL_MS = 90 * 24 * 60 * 60 * 1000;\nconst RDT_CID_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// gtag's own expiry for _gcl_* — 90 days, the length of a Google Ads click's upload window.\nconst GCL_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// Tolerate a little clock skew when validating a creationTime against \"now\".\nconst CLOCK_SKEW_MS = 24 * 60 * 60 * 1000;\n\nexport const FBC_COOKIE = '_fbc';\nexport const RDT_CID_COOKIE = '_rdt_cid';\nexport const GCL_AW_COOKIE = '_gcl_aw';\nexport const GCL_GB_COOKIE = '_gcl_gb';\n\nexport type ParsedFbc = { raw: string; creationTime: number; fbclid: string };\n\n/**\n * Parse `fb.<subdomainIndex>.<creationTime>.<fbclid>`.\n * Returns undefined for anything malformed — a fbclid never contains a dot, but joining the tail\n * back together keeps us forward-compatible if that ever changes.\n */\nexport function parseFbc(\n  raw: string | undefined | null,\n  now: number = Date.now()\n): ParsedFbc | undefined {\n  if (!raw) return undefined;\n  const parts = raw.split('.');\n  if (parts.length < 4 || parts[0] !== 'fb') return undefined;\n\n  const creationTime = Number(parts[2]);\n  const fbclid = parts.slice(3).join('.');\n  if (!fbclid) return undefined;\n  // creationTime is UNIX ms; reject seconds-precision or future-dated values as malformed.\n  if (!Number.isFinite(creationTime)) return undefined;\n  if (creationTime < 1e12 || creationTime > now + CLOCK_SKEW_MS) return undefined;\n\n  return { raw, creationTime, fbclid };\n}\n\n/**\n * Build a fresh `_fbc` value. subdomainIndex is the cookie's domain level (com=0, example.com=1,\n * www.example.com=2); 1 is correct for an apex-hosted cookie.\n */\nexport function formatFbc(fbclid: string, now: number, subdomainIndex = 1): string {\n  return `fb.${subdomainIndex}.${now}.${fbclid}`;\n}\n\nexport type ParsedGcl = { raw: string; creationTime: number; clickId: string };\n\n// gtag's own value validator, extracted from gtag.js: the click id segment must match this.\nconst GCL_CLICK_ID = /^[\\w-]+$/;\n\n/**\n * Parse a `_gcl_aw`/`_gcl_gb` value: `GCL.<seconds>.<clickId>[.<labels…>]` — note the timestamp\n * is in SECONDS, unlike `_fbc`'s milliseconds. gtag's parser accepts version `GCL` or `1` and\n * validates the segments exactly this way (`/^\\d+$/` timestamp, `/^[\\w-]+$/` click id); any\n * labels tail is preserved through `raw` so a re-issue stays byte-identical.\n */\nexport function parseGcl(\n  raw: string | undefined | null,\n  now: number = Date.now()\n): ParsedGcl | undefined {\n  if (!raw) return undefined;\n  const parts = raw.split('.');\n  if (parts.length < 3) return undefined;\n  if (parts[0] !== 'GCL' && parts[0] !== '1') return undefined;\n  const seconds = parts[1];\n  const clickId = parts[2];\n  if (seconds === undefined || !/^\\d+$/.test(seconds)) return undefined;\n  if (clickId === undefined || !GCL_CLICK_ID.test(clickId)) return undefined;\n  const creationTime = Number(seconds) * 1000;\n  // Reject millisecond-precision or future-dated values as malformed.\n  if (creationTime >= 1e15 || creationTime > now + CLOCK_SKEW_MS) return undefined;\n  return { raw, creationTime, clickId };\n}\n\n/** Build a fresh `_gcl_aw`/`_gcl_gb` value in gtag's own format. */\nexport function formatGcl(clickId: string, now: number): string {\n  return `GCL.${Math.floor(now / 1000)}.${clickId}`;\n}\n\nexport type ResolveClickIdCookiesInput = {\n  /** The absolute request URL (must include the query string). */\n  url: string;\n  /** The raw `Cookie` request header, if any. */\n  cookieHeader?: string | null;\n  /** Overridable clock, primarily for tests. Defaults to `Date.now()`. */\n  now?: number;\n  /** `Domain` attribute for the emitted cookies, e.g. `.shware.io`. Omit for a host-only cookie. */\n  domain?: string;\n  /** `Secure` attribute, default true. Set false only for local http testing. */\n  secure?: boolean;\n  /** subdomainIndex for a freshly built `_fbc` (see {@link formatFbc}). Default 1. */\n  subdomainIndex?: number;\n  /**\n   * Re-issue a still-valid `_fbc` at its *remaining* lifetime on every call. On by default, as an\n   * ITP self-heal: cookies follow last-writer-wins, so if the Meta Pixel overwrote `_fbc` via\n   * `document.cookie` (Safari caps JS-written cookies on a fbclid-decorated landing to 24h),\n   * re-issuing the long-lived HTTP cookie on the next navigation restores it — the same\n   * continuous-re-issue mitigation the sGTM ecosystem uses (stape Cookie Keeper, Cookie Monster).\n   * The value (and its creationTime) is byte-for-byte identical and the window never slides, so it\n   * cannot trigger Meta's expired/modified-fbclid warnings.\n   *\n   * Set false to strictly follow Meta's documented conditional-write rule (\"only set the cookie if\n   * it doesn't exist or the fbclid changed\") — e.g. to keep pages CDN-cacheable, since the\n   * re-issue attaches a per-user `Set-Cookie` (forcing `no-store`) to every response carrying an\n   * `_fbc`.\n   */\n  refresh?: boolean;\n};\n\nexport type ResolveClickIdCookiesResult = {\n  /**\n   * Cookies to emit on the response, ready for `Set-Cookie`. Empty when nothing needs to change.\n   * A `value: ''`, `maxAge: 0` entry is a deletion (an expired or malformed leftover).\n   */\n  cookies: SetCookie[];\n  /** The resolved `_fbc` value, for immediate server-side use (e.g. Conversions API). */\n  fbc?: string;\n  /** The resolved `_rdt_cid` value. */\n  rdt_cid?: string;\n  /** The resolved Google Ads click id (from the URL or a still-valid `_gcl_aw`). */\n  gclid?: string;\n  /** The resolved iOS web-to-app click id (from the URL or a still-valid `_gcl_gb`). */\n  wbraid?: string;\n};\n\nfunction searchParams(url: string): URLSearchParams {\n  try {\n    return new URL(url).searchParams;\n  } catch {\n    // Fall back to a manual split so a relative or slightly malformed URL still yields the query.\n    const q = url.indexOf('?');\n    return new URLSearchParams(q !== -1 ? url.slice(q + 1) : '');\n  }\n}\n\n/**\n * Resolve the click-id cookies to set on the current document response.\n *\n * `_fbc` follows Meta's documented conditional-write rule value-wise: a new fbclid (or an absent\n * cookie) opens a fresh 90-day window; a same-fbclid cookie keeps its original value and\n * `creationTime`. Expired (>90d) or malformed values are cleared instead of forwarded. By default,\n * ({@link ResolveClickIdCookiesInput.refresh}) a still-valid cookie is re-issued unchanged at its\n * *remaining* lifetime — never `now + 90d` — so a returning visitor's window cannot slide forward\n * (which is what makes Meta flag an expired fbclid).\n */\nexport function resolveClickIdCookies(\n  input: ResolveClickIdCookiesInput\n): ResolveClickIdCookiesResult {\n  const { url, cookieHeader, domain, secure = true, subdomainIndex = 1, refresh = true } = input;\n  const now = input.now ?? Date.now();\n\n  const params = searchParams(url);\n  const jar = parseCookie(cookieHeader ?? '');\n  const cookies: SetCookie[] = [];\n  const result: ResolveClickIdCookiesResult = { cookies };\n\n  const base = { path: '/', secure, sameSite: 'lax', domain } as const;\n  const set = (name: string, value: string, ttlMs: number) =>\n    cookies.push({ name, value, maxAge: Math.floor(ttlMs / 1000), ...base });\n  const del = (name: string) => cookies.push({ name, value: '', maxAge: 0, ...base });\n\n  // --- Meta _fbc ---\n  const urlFbclid = params.get('fbclid') || undefined;\n  const existingFbc = parseFbc(jar[FBC_COOKIE], now);\n\n  if (urlFbclid && urlFbclid !== existingFbc?.fbclid) {\n    // A new click always wins and opens a fresh 90-day window.\n    const raw = formatFbc(urlFbclid, now, subdomainIndex);\n    set(FBC_COOKIE, raw, FBC_TTL_MS);\n    result.fbc = raw;\n  } else if (existingFbc) {\n    const remainingMs = existingFbc.creationTime + FBC_TTL_MS - now;\n    if (remainingMs <= 0) {\n      del(FBC_COOKIE);\n    } else {\n      // Same fbclid: the value and creationTime are preserved (Meta's rule); refresh (default)\n      // re-issues it unchanged at its remaining lifetime as an ITP self-heal.\n      result.fbc = existingFbc.raw;\n      if (refresh) set(FBC_COOKIE, existingFbc.raw, remainingMs);\n    }\n  } else if (jar[FBC_COOKIE]) {\n    // Malformed leftover — clear it rather than forwarding it to Meta.\n    del(FBC_COOKIE);\n  }\n\n  // --- Google Ads _gcl_aw / _gcl_gb ---\n  // The same first-party HTTP persistence Google's own server-side Conversion Linker performs\n  // (it sets FPGCLAW via Set-Cookie for 90 days), applied to gtag's cookies the way the sGTM\n  // ecosystem does (stape Cookie Keeper re-issues _gcl_* over HTTP). Ownership is shared with\n  // gtag, so the rules are stricter than for _fbc: a value this module cannot parse is left\n  // untouched — never rewritten, never deleted — and a re-issue is byte-identical (labels tail\n  // included) at the window's REMAINING lifetime, so the 90-day click window never slides.\n  const gclsrc = params.get('gclsrc') || undefined;\n  const google = [\n    {\n      cookie: GCL_AW_COOKIE,\n      // gtag's own gating, verbatim: a gclid enters _gcl_aw only when gclsrc is absent or\n      // 'aw.ds' — 'ds'/'3p.ds' clicks are Search Ads 360's and belong to _gcl_dc.\n      urlClickId: !gclsrc || gclsrc === 'aw.ds' ? params.get('gclid') || undefined : undefined,\n      assign: (value: string) => (result.gclid = value),\n    },\n    {\n      cookie: GCL_GB_COOKIE,\n      urlClickId: params.get('wbraid') || undefined,\n      assign: (value: string) => (result.wbraid = value),\n    },\n  ];\n  for (const { cookie, urlClickId, assign } of google) {\n    const existing = parseGcl(jar[cookie], now);\n    if (urlClickId && GCL_CLICK_ID.test(urlClickId) && urlClickId !== existing?.clickId) {\n      // A new click always wins and opens a fresh 90-day window, in gtag's exact format.\n      set(cookie, formatGcl(urlClickId, now), GCL_TTL_MS);\n      assign(urlClickId);\n    } else if (existing) {\n      const remainingMs = existing.creationTime + GCL_TTL_MS - now;\n      if (remainingMs > 0) {\n        assign(existing.clickId);\n        if (refresh) set(cookie, existing.raw, remainingMs);\n      }\n      // Expired: not returned and not re-issued, but gtag owns the deletion.\n    }\n  }\n\n  // --- Reddit _rdt_cid ---\n  // No embedded timestamp, so it can only be anchored at first capture; set it once from the URL and\n  // otherwise leave the existing cookie untouched (re-issuing would slide its window).\n  const urlRdtCid = params.get('rdt_cid') || undefined;\n  const existingRdtCid = jar[RDT_CID_COOKIE] || undefined;\n  if (urlRdtCid && urlRdtCid !== existingRdtCid) {\n    set(RDT_CID_COOKIE, urlRdtCid, RDT_CID_TTL_MS);\n    result.rdt_cid = urlRdtCid;\n  } else if (existingRdtCid) {\n    result.rdt_cid = existingRdtCid;\n  }\n\n  return result;\n}\n\n/** Serialize the resolved cookies into `Set-Cookie` header values. */\nexport function toSetCookieHeaders(cookies: SetCookie[]): string[] {\n  return cookies.map((cookie) => stringifySetCookie(cookie));\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["parseCookie","cookie","stringifySetCookie"],"sources":["../../src/click-id/index.ts"],"sourcesContent":["import { type SetCookie, parseCookie, stringifySetCookie } from 'cookie';\n\n/**\n * Server-side resolution of ad-click-id cookies (`_fbc`, `_gcl_aw`/`_gcl_gb`, `_rdt_cid`,\n * `_uetmsclkid`) from the incoming request.\n *\n * This is the framework-agnostic core meant to run on the *document* response (e.g. TanStack Start\n * server middleware, Next middleware). Setting `_fbc` via an HTTP `Set-Cookie` header on the top\n * document — rather than `document.cookie` on the client — is what Meta officially recommends and is\n * the only reliable way to keep the cookie alive for 90 days in Safari: ITP caps JavaScript-set\n * cookies on a fbclid-decorated landing page to 24 hours, and the document response is never\n * classified as CNAME/IP cloaking (it is the reference the browser measures cloaking against).\n *\n * The Google pair follows the same architecture Google itself ships for server containers —\n * sGTM's Conversion Linker sets FPGCLAW via Set-Cookie for 90 days — and the sGTM ecosystem\n * productized for gtag's own cookies (stape Cookie Keeper re-issues `_gcl_*` over HTTP; vendor\n * case studies report 5–20% of Google Ads conversions recovered, up to +44% on the Safari\n * slice). One deployment caveat from WebKit's rules: the HTTP-cookie exemption holds only for\n * responses from the site's own infrastructure — a CNAME or third-party-IP host (a tagging\n * subdomain on someone else's cloud) gets its Set-Cookie silently capped to 7 days. This module\n * runs on the host's own document response, which is exactly the exempt case.\n *\n * references:\n * - https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc\n * - https://webkit.org/tracking-prevention/ (7d JS cookies, 24h on ad-decorated landings,\n *   CNAME/third-party-IP HTTP cookies capped to 7d, same-origin HTTP cookies exempt)\n * - https://www.simoahava.com/analytics/google-ads-server-side-tagging-google-tag-manager/\n *   (Conversion Linker → FPGCLAW via Set-Cookie, Google's own server-side equivalent)\n * - https://stape.io/helpdesk/documentation/cookie-keeper-power-up (the productized re-issue)\n */\n\n// Meta's recommended _fbc cookie expiry. Events Manager warns (\"Server sending expired fbclid\")\n// when the embedded creationTime is older than 90 days and match quality/attribution may degrade;\n// no hard drop is documented.\nconst FBC_TTL_MS = 90 * 24 * 60 * 60 * 1000;\nconst RDT_CID_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// bat.js's own expiry for _uetmsclkid (`msClkIdExpirationTime`), the Microsoft Ads click window.\nconst MSCLKID_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// gtag's own expiry for _gcl_* — 90 days, the length of a Google Ads click's upload window.\nconst GCL_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// Tolerate a little clock skew when validating a creationTime against \"now\".\nconst CLOCK_SKEW_MS = 24 * 60 * 60 * 1000;\n\nexport const FBC_COOKIE = '_fbc';\nexport const RDT_CID_COOKIE = '_rdt_cid';\nexport const GCL_AW_COOKIE = '_gcl_aw';\nexport const GCL_GB_COOKIE = '_gcl_gb';\nexport const UET_MSCLKID_COOKIE = '_uetmsclkid';\n\nexport type ParsedFbc = { raw: string; creationTime: number; fbclid: string };\n\n/**\n * Parse `fb.<subdomainIndex>.<creationTime>.<fbclid>`.\n * Returns undefined for anything malformed — a fbclid never contains a dot, but joining the tail\n * back together keeps us forward-compatible if that ever changes.\n */\nexport function parseFbc(\n  raw: string | undefined | null,\n  now: number = Date.now()\n): ParsedFbc | undefined {\n  if (!raw) return undefined;\n  const parts = raw.split('.');\n  if (parts.length < 4 || parts[0] !== 'fb') return undefined;\n\n  const creationTime = Number(parts[2]);\n  const fbclid = parts.slice(3).join('.');\n  if (!fbclid) return undefined;\n  // creationTime is UNIX ms; reject seconds-precision or future-dated values as malformed.\n  if (!Number.isFinite(creationTime)) return undefined;\n  if (creationTime < 1e12 || creationTime > now + CLOCK_SKEW_MS) return undefined;\n\n  return { raw, creationTime, fbclid };\n}\n\n/**\n * Build a fresh `_fbc` value. subdomainIndex is the cookie's domain level (com=0, example.com=1,\n * www.example.com=2); 1 is correct for an apex-hosted cookie.\n */\nexport function formatFbc(fbclid: string, now: number, subdomainIndex = 1): string {\n  return `fb.${subdomainIndex}.${now}.${fbclid}`;\n}\n\nexport type ParsedGcl = { raw: string; creationTime: number; clickId: string };\n\n// gtag's own value validator, extracted from the live gtag.js bundle (2026-09): its parser\n// accepts version \"GCL\" or \"1\", a /^\\d+$/ seconds timestamp, and a click id matching this.\n// Re-verify against gtag.js before changing anything here — the format is gtag's, not ours.\nconst GCL_CLICK_ID = /^[\\w-]+$/;\n\n/**\n * Parse a `_gcl_aw`/`_gcl_gb` value: `GCL.<seconds>.<clickId>[.<labels…>]` — note the timestamp\n * is in SECONDS, unlike `_fbc`'s milliseconds. gtag's parser accepts version `GCL` or `1` and\n * validates the segments exactly this way (`/^\\d+$/` timestamp, `/^[\\w-]+$/` click id); any\n * labels tail is preserved through `raw` so a re-issue stays byte-identical.\n */\nexport function parseGcl(\n  raw: string | undefined | null,\n  now: number = Date.now()\n): ParsedGcl | undefined {\n  if (!raw) return undefined;\n  const parts = raw.split('.');\n  if (parts.length < 3) return undefined;\n  if (parts[0] !== 'GCL' && parts[0] !== '1') return undefined;\n  const seconds = parts[1];\n  const clickId = parts[2];\n  if (seconds === undefined || !/^\\d+$/.test(seconds)) return undefined;\n  if (clickId === undefined || !GCL_CLICK_ID.test(clickId)) return undefined;\n  const creationTime = Number(seconds) * 1000;\n  // Reject millisecond-precision or future-dated values as malformed.\n  if (creationTime >= 1e15 || creationTime > now + CLOCK_SKEW_MS) return undefined;\n  return { raw, creationTime, clickId };\n}\n\n/** Build a fresh `_gcl_aw`/`_gcl_gb` value in gtag's own format. */\nexport function formatGcl(clickId: string, now: number): string {\n  return `GCL.${Math.floor(now / 1000)}.${clickId}`;\n}\n\n// bat.js writes the click id as `_uet<msclkid>` and reads it back only when what follows the\n// prefix is at most 32 characters (`msClkIdCookieValuePrefix`, `lengthMsClkId`); a msclkid is a\n// 32-hex-digit UUID without dashes. Re-verify against bat.js before changing anything here —\n// the format is UET's, not ours.\nconst UET_MSCLKID_PREFIX = '_uet';\nconst MSCLKID = /^[0-9a-f]{32}$/i;\n\n/**\n * Parse a `_uetmsclkid` value: `_uet<32 hex>`. Returns the click id, lowercased, or undefined\n * for anything bat.js itself would not read back.\n */\nexport function parseUetMsclkid(raw: string | undefined | null): string | undefined {\n  if (!raw || !raw.startsWith(UET_MSCLKID_PREFIX)) return undefined;\n  const clickId = raw.slice(UET_MSCLKID_PREFIX.length);\n  return MSCLKID.test(clickId) ? clickId.toLowerCase() : undefined;\n}\n\n/** Build a `_uetmsclkid` value in bat.js's own format. */\nexport function formatUetMsclkid(clickId: string): string {\n  return `${UET_MSCLKID_PREFIX}${clickId.toLowerCase()}`;\n}\n\n/**\n * The click id as the Conversions API wants it: a dashed, lowercase UUID. The URL and the cookie\n * carry the 32-hex form; a value in any other shape is returned untouched for the API to judge.\n */\nexport function formatMsclkid(clickId: string): string {\n  const id = clickId.trim().toLowerCase();\n  if (!MSCLKID.test(id)) return id;\n  return `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`;\n}\n\nexport type ResolveClickIdCookiesInput = {\n  /** The absolute request URL (must include the query string). */\n  url: string;\n  /** The raw `Cookie` request header, if any. */\n  cookieHeader?: string | null;\n  /** Overridable clock, primarily for tests. Defaults to `Date.now()`. */\n  now?: number;\n  /** `Domain` attribute for the emitted cookies, e.g. `.shware.io`. Omit for a host-only cookie. */\n  domain?: string;\n  /** `Secure` attribute, default true. Set false only for local http testing. */\n  secure?: boolean;\n  /** subdomainIndex for a freshly built `_fbc` (see {@link formatFbc}). Default 1. */\n  subdomainIndex?: number;\n  /**\n   * Re-issue a still-valid `_fbc` at its *remaining* lifetime on every call. On by default, as an\n   * ITP self-heal: cookies follow last-writer-wins, so if the Meta Pixel overwrote `_fbc` via\n   * `document.cookie` (Safari caps JS-written cookies on a fbclid-decorated landing to 24h),\n   * re-issuing the long-lived HTTP cookie on the next navigation restores it — the same\n   * continuous-re-issue mitigation the sGTM ecosystem uses (stape Cookie Keeper, Cookie Monster).\n   * The value (and its creationTime) is byte-for-byte identical and the window never slides, so it\n   * cannot trigger Meta's expired/modified-fbclid warnings.\n   *\n   * Set false to strictly follow Meta's documented conditional-write rule (\"only set the cookie if\n   * it doesn't exist or the fbclid changed\") — e.g. to keep pages CDN-cacheable, since the\n   * re-issue attaches a per-user `Set-Cookie` (forcing `no-store`) to every response carrying an\n   * `_fbc`.\n   */\n  refresh?: boolean;\n};\n\nexport type ResolveClickIdCookiesResult = {\n  /**\n   * Cookies to emit on the response, ready for `Set-Cookie`. Empty when nothing needs to change.\n   * A `value: ''`, `maxAge: 0` entry is a deletion (an expired or malformed leftover).\n   */\n  cookies: SetCookie[];\n  /** The resolved `_fbc` value, for immediate server-side use (e.g. Conversions API). */\n  fbc?: string;\n  /** The resolved `_rdt_cid` value. */\n  rdt_cid?: string;\n  /** The resolved Google Ads click id (from the URL or a still-valid `_gcl_aw`). */\n  gclid?: string;\n  /** The resolved iOS web-to-app click id (from the URL or a still-valid `_gcl_gb`). */\n  wbraid?: string;\n  /** The resolved Microsoft Ads click id (from the URL or `_uetmsclkid`), 32-hex form. */\n  msclkid?: string;\n};\n\nfunction searchParams(url: string): URLSearchParams {\n  try {\n    return new URL(url).searchParams;\n  } catch {\n    // Fall back to a manual split so a relative or slightly malformed URL still yields the query.\n    const q = url.indexOf('?');\n    return new URLSearchParams(q !== -1 ? url.slice(q + 1) : '');\n  }\n}\n\n/**\n * Resolve the click-id cookies to set on the current document response.\n *\n * `_fbc` follows Meta's documented conditional-write rule value-wise: a new fbclid (or an absent\n * cookie) opens a fresh 90-day window; a same-fbclid cookie keeps its original value and\n * `creationTime`. Expired (>90d) or malformed values are cleared instead of forwarded. By default,\n * ({@link ResolveClickIdCookiesInput.refresh}) a still-valid cookie is re-issued unchanged at its\n * *remaining* lifetime — never `now + 90d` — so a returning visitor's window cannot slide forward\n * (which is what makes Meta flag an expired fbclid).\n */\nexport function resolveClickIdCookies(\n  input: ResolveClickIdCookiesInput\n): ResolveClickIdCookiesResult {\n  const { url, cookieHeader, domain, secure = true, subdomainIndex = 1, refresh = true } = input;\n  const now = input.now ?? Date.now();\n\n  const params = searchParams(url);\n  const jar = parseCookie(cookieHeader ?? '');\n  const cookies: SetCookie[] = [];\n  const result: ResolveClickIdCookiesResult = { cookies };\n\n  const base = { path: '/', secure, sameSite: 'lax', domain } as const;\n  const set = (name: string, value: string, ttlMs: number) =>\n    cookies.push({ name, value, maxAge: Math.floor(ttlMs / 1000), ...base });\n  const del = (name: string) => cookies.push({ name, value: '', maxAge: 0, ...base });\n\n  // --- Meta _fbc ---\n  const urlFbclid = params.get('fbclid') || undefined;\n  const existingFbc = parseFbc(jar[FBC_COOKIE], now);\n\n  if (urlFbclid && urlFbclid !== existingFbc?.fbclid) {\n    // A new click always wins and opens a fresh 90-day window.\n    const raw = formatFbc(urlFbclid, now, subdomainIndex);\n    set(FBC_COOKIE, raw, FBC_TTL_MS);\n    result.fbc = raw;\n  } else if (existingFbc) {\n    const remainingMs = existingFbc.creationTime + FBC_TTL_MS - now;\n    if (remainingMs <= 0) {\n      del(FBC_COOKIE);\n    } else {\n      // Same fbclid: the value and creationTime are preserved (Meta's rule); refresh (default)\n      // re-issues it unchanged at its remaining lifetime as an ITP self-heal.\n      result.fbc = existingFbc.raw;\n      if (refresh) set(FBC_COOKIE, existingFbc.raw, remainingMs);\n    }\n  } else if (jar[FBC_COOKIE]) {\n    // Malformed leftover — clear it rather than forwarding it to Meta.\n    del(FBC_COOKIE);\n  }\n\n  // --- Google Ads _gcl_aw / _gcl_gb ---\n  // The same first-party HTTP persistence Google's own server-side Conversion Linker performs\n  // (it sets FPGCLAW via Set-Cookie for 90 days), applied to gtag's cookies the way the sGTM\n  // ecosystem does (stape Cookie Keeper re-issues _gcl_* over HTTP). Ownership is shared with\n  // gtag, so the rules are stricter than for _fbc: a value this module cannot parse is left\n  // untouched — never rewritten, never deleted — and a re-issue is byte-identical (labels tail\n  // included) at the window's REMAINING lifetime, so the 90-day click window never slides.\n  const gclsrc = params.get('gclsrc') || undefined;\n  const google = [\n    {\n      cookie: GCL_AW_COOKIE,\n      // gtag's own gating, verbatim: a gclid enters _gcl_aw only when gclsrc is absent or\n      // 'aw.ds' — 'ds'/'3p.ds' clicks are Search Ads 360's and belong to _gcl_dc.\n      urlClickId: !gclsrc || gclsrc === 'aw.ds' ? params.get('gclid') || undefined : undefined,\n      assign: (value: string) => (result.gclid = value),\n    },\n    {\n      cookie: GCL_GB_COOKIE,\n      urlClickId: params.get('wbraid') || undefined,\n      assign: (value: string) => (result.wbraid = value),\n    },\n  ];\n  for (const { cookie, urlClickId, assign } of google) {\n    const existing = parseGcl(jar[cookie], now);\n    if (urlClickId && GCL_CLICK_ID.test(urlClickId) && urlClickId !== existing?.clickId) {\n      // A new click always wins and opens a fresh 90-day window, in gtag's exact format.\n      set(cookie, formatGcl(urlClickId, now), GCL_TTL_MS);\n      assign(urlClickId);\n    } else if (existing) {\n      const remainingMs = existing.creationTime + GCL_TTL_MS - now;\n      if (remainingMs > 0) {\n        assign(existing.clickId);\n        if (refresh) set(cookie, existing.raw, remainingMs);\n      }\n      // Expired: not returned and not re-issued, but gtag owns the deletion.\n    }\n  }\n\n  // --- Reddit _rdt_cid ---\n  // No embedded timestamp, so it can only be anchored at first capture; set it once from the URL and\n  // otherwise leave the existing cookie untouched (re-issuing would slide its window).\n  const urlRdtCid = params.get('rdt_cid') || undefined;\n  const existingRdtCid = jar[RDT_CID_COOKIE] || undefined;\n  if (urlRdtCid && urlRdtCid !== existingRdtCid) {\n    set(RDT_CID_COOKIE, urlRdtCid, RDT_CID_TTL_MS);\n    result.rdt_cid = urlRdtCid;\n  } else if (existingRdtCid) {\n    result.rdt_cid = existingRdtCid;\n  }\n\n  // --- Microsoft Ads _uetmsclkid ---\n  // The UET tag's own cookie, in its own format, so the tag and this module read each other's\n  // writes. Microsoft's ITP answer is this first-party cookie (plus a localStorage backup), but\n  // bat.js writes it through `document.cookie`, which Safari caps at 7 days — 24 hours on a\n  // landing page decorated by a classified domain, and a bing.com ad click is exactly that.\n  // Persisting it here over HTTP on the document response restores the 90-day window.\n  //\n  // The re-issue (default on, see `refresh`) is the same self-heal as for `_fbc`, and it matters\n  // more here: bat.js rewrites this cookie on EVERY page load, so without the re-issue the HTTP\n  // copy is downgraded to a JS cookie on the very next page. There is no embedded timestamp to\n  // compute a remaining lifetime from, so it is re-issued at a fresh 90 days — which is exactly\n  // what bat.js itself does on each page (`msClkIdExpirationTime` from now), so the window\n  // slides no more than the tag already slides it. A value this module cannot parse belongs to\n  // the tag: never rewritten, never deleted.\n  const urlMsclkid = params.get('msclkid')?.trim();\n  const existingMsclkid = parseUetMsclkid(jar[UET_MSCLKID_COOKIE]);\n  if (urlMsclkid && MSCLKID.test(urlMsclkid) && urlMsclkid.toLowerCase() !== existingMsclkid) {\n    set(UET_MSCLKID_COOKIE, formatUetMsclkid(urlMsclkid), MSCLKID_TTL_MS);\n    result.msclkid = urlMsclkid.toLowerCase();\n  } else if (existingMsclkid) {\n    result.msclkid = existingMsclkid;\n    if (refresh) set(UET_MSCLKID_COOKIE, formatUetMsclkid(existingMsclkid), MSCLKID_TTL_MS);\n  }\n\n  return result;\n}\n\n/** Serialize the resolved cookies into `Set-Cookie` header values. */\nexport function toSetCookieHeaders(cookies: SetCookie[]): string[] {\n  return cookies.map((cookie) => stringifySetCookie(cookie));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAM,aAAa;AACnB,MAAM,iBAAiB;AAEvB,MAAM,iBAAiB;AAEvB,MAAM,aAAa;AAEnB,MAAM,gBAAgB;AAEtB,MAAa,aAAa;AAC1B,MAAa,iBAAiB;AAC9B,MAAa,gBAAgB;AAC7B,MAAa,gBAAgB;AAC7B,MAAa,qBAAqB;;;;;;AASlC,SAAgB,SACd,KACA,MAAc,KAAK,IAAI,GACA;CACvB,IAAI,CAAC,KAAK,OAAO,KAAA;CACjB,MAAM,QAAQ,IAAI,MAAM,GAAG;CAC3B,IAAI,MAAM,SAAS,KAAK,MAAM,OAAO,MAAM,OAAO,KAAA;CAElD,MAAM,eAAe,OAAO,MAAM,EAAE;CACpC,MAAM,SAAS,MAAM,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG;CACtC,IAAI,CAAC,QAAQ,OAAO,KAAA;CAEpB,IAAI,CAAC,OAAO,SAAS,YAAY,GAAG,OAAO,KAAA;CAC3C,IAAI,eAAe,gBAAQ,eAAe,MAAM,eAAe,OAAO,KAAA;CAEtE,OAAO;EAAE;EAAK;EAAc;CAAO;AACrC;;;;;AAMA,SAAgB,UAAU,QAAgB,KAAa,iBAAiB,GAAW;CACjF,OAAO,MAAM,eAAe,GAAG,IAAI,GAAG;AACxC;AAOA,MAAM,eAAe;;;;;;;AAQrB,SAAgB,SACd,KACA,MAAc,KAAK,IAAI,GACA;CACvB,IAAI,CAAC,KAAK,OAAO,KAAA;CACjB,MAAM,QAAQ,IAAI,MAAM,GAAG;CAC3B,IAAI,MAAM,SAAS,GAAG,OAAO,KAAA;CAC7B,IAAI,MAAM,OAAO,SAAS,MAAM,OAAO,KAAK,OAAO,KAAA;CACnD,MAAM,UAAU,MAAM;CACtB,MAAM,UAAU,MAAM;CACtB,IAAI,YAAY,KAAA,KAAa,CAAC,QAAQ,KAAK,OAAO,GAAG,OAAO,KAAA;CAC5D,IAAI,YAAY,KAAA,KAAa,CAAC,aAAa,KAAK,OAAO,GAAG,OAAO,KAAA;CACjE,MAAM,eAAe,OAAO,OAAO,IAAI;CAEvC,IAAI,gBAAgB,mBAAQ,eAAe,MAAM,eAAe,OAAO,KAAA;CACvE,OAAO;EAAE;EAAK;EAAc;CAAQ;AACtC;;AAGA,SAAgB,UAAU,SAAiB,KAAqB;CAC9D,OAAO,OAAO,KAAK,MAAM,MAAM,GAAI,EAAE,GAAG;AAC1C;AAMA,MAAM,qBAAqB;AAC3B,MAAM,UAAU;;;;;AAMhB,SAAgB,gBAAgB,KAAoD;CAClF,IAAI,CAAC,OAAO,CAAC,IAAI,WAAW,kBAAkB,GAAG,OAAO,KAAA;CACxD,MAAM,UAAU,IAAI,MAAM,CAAyB;CACnD,OAAO,QAAQ,KAAK,OAAO,IAAI,QAAQ,YAAY,IAAI,KAAA;AACzD;;AAGA,SAAgB,iBAAiB,SAAyB;CACxD,OAAO,GAAG,qBAAqB,QAAQ,YAAY;AACrD;;;;;AAMA,SAAgB,cAAc,SAAyB;CACrD,MAAM,KAAK,QAAQ,KAAK,CAAC,CAAC,YAAY;CACtC,IAAI,CAAC,QAAQ,KAAK,EAAE,GAAG,OAAO;CAC9B,OAAO,GAAG,GAAG,MAAM,GAAG,CAAC,EAAE,GAAG,GAAG,MAAM,GAAG,EAAE,EAAE,GAAG,GAAG,MAAM,IAAI,EAAE,EAAE,GAAG,GAAG,MAAM,IAAI,EAAE,EAAE,GAAG,GAAG,MAAM,EAAE;AACpG;AAkDA,SAAS,aAAa,KAA8B;CAClD,IAAI;EACF,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;CACtB,QAAQ;EAEN,MAAM,IAAI,IAAI,QAAQ,GAAG;EACzB,OAAO,IAAI,gBAAgB,MAAM,KAAK,IAAI,MAAM,IAAI,CAAC,IAAI,EAAE;CAC7D;AACF;;;;;;;;;;;AAYA,SAAgB,sBACd,OAC6B;CAC7B,MAAM,EAAE,KAAK,cAAc,QAAQ,SAAS,MAAM,iBAAiB,GAAG,UAAU,SAAS;CACzF,MAAM,MAAM,MAAM,OAAO,KAAK,IAAI;CAElC,MAAM,SAAS,aAAa,GAAG;CAC/B,MAAM,OAAA,GAAMA,OAAAA,YAAAA,CAAY,gBAAgB,EAAE;CAC1C,MAAM,UAAuB,CAAC;CAC9B,MAAM,SAAsC,EAAE,QAAQ;CAEtD,MAAM,OAAO;EAAE,MAAM;EAAK;EAAQ,UAAU;EAAO;CAAO;CAC1D,MAAM,OAAO,MAAc,OAAe,UACxC,QAAQ,KAAK;EAAE;EAAM;EAAO,QAAQ,KAAK,MAAM,QAAQ,GAAI;EAAG,GAAG;CAAK,CAAC;CACzE,MAAM,OAAO,SAAiB,QAAQ,KAAK;EAAE;EAAM,OAAO;EAAI,QAAQ;EAAG,GAAG;CAAK,CAAC;CAGlF,MAAM,YAAY,OAAO,IAAI,QAAQ,KAAK,KAAA;CAC1C,MAAM,cAAc,SAAS,IAAI,aAAa,GAAG;CAEjD,IAAI,aAAa,cAAc,aAAa,QAAQ;EAElD,MAAM,MAAM,UAAU,WAAW,KAAK,cAAc;EACpD,IAAI,YAAY,KAAK,UAAU;EAC/B,OAAO,MAAM;CACf,OAAO,IAAI,aAAa;EACtB,MAAM,cAAc,YAAY,eAAe,aAAa;EAC5D,IAAI,eAAe,GACjB,IAAI,UAAU;OACT;GAGL,OAAO,MAAM,YAAY;GACzB,IAAI,SAAS,IAAI,YAAY,YAAY,KAAK,WAAW;EAC3D;CACF,OAAO,IAAI,IAAA,SAET,IAAI,UAAU;CAUhB,MAAM,SAAS,OAAO,IAAI,QAAQ,KAAK,KAAA;CACvC,MAAM,SAAS,CACb;EACE,QAAQ;EAGR,YAAY,CAAC,UAAU,WAAW,UAAU,OAAO,IAAI,OAAO,KAAK,KAAA,IAAY,KAAA;EAC/E,SAAS,UAAmB,OAAO,QAAQ;CAC7C,GACA;EACE,QAAQ;EACR,YAAY,OAAO,IAAI,QAAQ,KAAK,KAAA;EACpC,SAAS,UAAmB,OAAO,SAAS;CAC9C,CACF;CACA,KAAK,MAAM,EAAE,QAAA,UAAQ,YAAY,YAAY,QAAQ;EACnD,MAAM,WAAW,SAAS,IAAIC,WAAS,GAAG;EAC1C,IAAI,cAAc,aAAa,KAAK,UAAU,KAAK,eAAe,UAAU,SAAS;GAEnF,IAAIA,UAAQ,UAAU,YAAY,GAAG,GAAG,UAAU;GAClD,OAAO,UAAU;EACnB,OAAO,IAAI,UAAU;GACnB,MAAM,cAAc,SAAS,eAAe,aAAa;GACzD,IAAI,cAAc,GAAG;IACnB,OAAO,SAAS,OAAO;IACvB,IAAI,SAAS,IAAIA,UAAQ,SAAS,KAAK,WAAW;GACpD;EAEF;CACF;CAKA,MAAM,YAAY,OAAO,IAAI,SAAS,KAAK,KAAA;CAC3C,MAAM,iBAAiB,IAAA,eAAuB,KAAA;CAC9C,IAAI,aAAa,cAAc,gBAAgB;EAC7C,IAAI,gBAAgB,WAAW,cAAc;EAC7C,OAAO,UAAU;CACnB,OAAO,IAAI,gBACT,OAAO,UAAU;CAiBnB,MAAM,aAAa,OAAO,IAAI,SAAS,CAAC,EAAE,KAAK;CAC/C,MAAM,kBAAkB,gBAAgB,IAAI,mBAAmB;CAC/D,IAAI,cAAc,QAAQ,KAAK,UAAU,KAAK,WAAW,YAAY,MAAM,iBAAiB;EAC1F,IAAI,oBAAoB,iBAAiB,UAAU,GAAG,cAAc;EACpE,OAAO,UAAU,WAAW,YAAY;CAC1C,OAAO,IAAI,iBAAiB;EAC1B,OAAO,UAAU;EACjB,IAAI,SAAS,IAAI,oBAAoB,iBAAiB,eAAe,GAAG,cAAc;CACxF;CAEA,OAAO;AACT;;AAGA,SAAgB,mBAAmB,SAAgC;CACjE,OAAO,QAAQ,KAAK,cAAA,GAAWC,OAAAA,mBAAAA,CAAmBD,QAAM,CAAC;AAC3D"}

package/dist/click-id/index.d.cts

@@ -4,6 +4,7 @@ declare const FBC_COOKIE = "_fbc";
 declare const RDT_CID_COOKIE = "_rdt_cid";
 declare const GCL_AW_COOKIE = "_gcl_aw";
 declare const GCL_GB_COOKIE = "_gcl_gb";
+declare const UET_MSCLKID_COOKIE = "_uetmsclkid";
 type ParsedFbc = {
   raw: string;
   creationTime: number;
@@ -34,6 +35,18 @@ type ParsedGcl = {
 declare function parseGcl(raw: string | undefined | null, now?: number): ParsedGcl | undefined;
 /** Build a fresh `_gcl_aw`/`_gcl_gb` value in gtag's own format. */
 declare function formatGcl(clickId: string, now: number): string;
+/**
+ * Parse a `_uetmsclkid` value: `_uet<32 hex>`. Returns the click id, lowercased, or undefined
+ * for anything bat.js itself would not read back.
+ */
+declare function parseUetMsclkid(raw: string | undefined | null): string | undefined;
+/** Build a `_uetmsclkid` value in bat.js's own format. */
+declare function formatUetMsclkid(clickId: string): string;
+/**
+ * The click id as the Conversions API wants it: a dashed, lowercase UUID. The URL and the cookie
+ * carry the 32-hex form; a value in any other shape is returned untouched for the API to judge.
+ */
+declare function formatMsclkid(clickId: string): string;
 type ResolveClickIdCookiesInput = {
   /** The absolute request URL (must include the query string). */
   url: string;
@@ -77,6 +90,8 @@ type ResolveClickIdCookiesResult = {
   gclid?: string;
   /** The resolved iOS web-to-app click id (from the URL or a still-valid `_gcl_gb`). */
   wbraid?: string;
+  /** The resolved Microsoft Ads click id (from the URL or `_uetmsclkid`), 32-hex form. */
+  msclkid?: string;
 };
 /**
  * Resolve the click-id cookies to set on the current document response.
@@ -92,5 +107,5 @@ declare function resolveClickIdCookies(input: ResolveClickIdCookiesInput): Resol
 /** Serialize the resolved cookies into `Set-Cookie` header values. */
 declare function toSetCookieHeaders(cookies: SetCookie[]): string[];
 //#endregion
-export { FBC_COOKIE, GCL_AW_COOKIE, GCL_GB_COOKIE, ParsedFbc, ParsedGcl, RDT_CID_COOKIE, ResolveClickIdCookiesInput, ResolveClickIdCookiesResult, formatFbc, formatGcl, parseFbc, parseGcl, resolveClickIdCookies, toSetCookieHeaders };
+export { FBC_COOKIE, GCL_AW_COOKIE, GCL_GB_COOKIE, ParsedFbc, ParsedGcl, RDT_CID_COOKIE, ResolveClickIdCookiesInput, ResolveClickIdCookiesResult, UET_MSCLKID_COOKIE, formatFbc, formatGcl, formatMsclkid, formatUetMsclkid, parseFbc, parseGcl, parseUetMsclkid, resolveClickIdCookies, toSetCookieHeaders };
 //# sourceMappingURL=index.d.cts.map

package/dist/click-id/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/click-id/index.ts"],"mappings":";;cA0Ba;cACA;cACA;cACA;KAED;EAAc;EAAa;EAAsB;;;;;;;iBAO7C,SACd,gCACA,eACC;;;;;iBAmBa,UAAU,gBAAgB,aAAa;KAI3C;EAAc;EAAa;EAAsB;;;;;;;;iBAW7C,SACd,gCACA,eACC;;iBAgBa,UAAU,iBAAiB;KAI/B;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;EAeA;;KAGU;;;;;EAKV,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;iBAuBc,sBACd,OAAO,6BACN;;iBA4Fa,mBAAmB,SAAS"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/click-id/index.ts"],"mappings":";;cA2Ca;cACA;cACA;cACA;cACA;KAED;EAAc;EAAa;EAAsB;;;;;;;iBAO7C,SACd,gCACA,eACC;;;;;iBAmBa,UAAU,gBAAgB,aAAa;KAI3C;EAAc;EAAa;EAAsB;;;;;;;;iBAa7C,SACd,gCACA,eACC;;iBAgBa,UAAU,iBAAiB;;;;;iBAe3B,gBAAgB;;iBAOhB,iBAAiB;;;;;iBAQjB,cAAc;KAMlB;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;EAeA;;KAGU;;;;;EAKV,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;iBAuBc,sBACd,OAAO,6BACN;;iBAoHa,mBAAmB,SAAS"}

package/dist/click-id/index.d.mts

@@ -4,6 +4,7 @@ declare const FBC_COOKIE = "_fbc";
 declare const RDT_CID_COOKIE = "_rdt_cid";
 declare const GCL_AW_COOKIE = "_gcl_aw";
 declare const GCL_GB_COOKIE = "_gcl_gb";
+declare const UET_MSCLKID_COOKIE = "_uetmsclkid";
 type ParsedFbc = {
   raw: string;
   creationTime: number;
@@ -34,6 +35,18 @@ type ParsedGcl = {
 declare function parseGcl(raw: string | undefined | null, now?: number): ParsedGcl | undefined;
 /** Build a fresh `_gcl_aw`/`_gcl_gb` value in gtag's own format. */
 declare function formatGcl(clickId: string, now: number): string;
+/**
+ * Parse a `_uetmsclkid` value: `_uet<32 hex>`. Returns the click id, lowercased, or undefined
+ * for anything bat.js itself would not read back.
+ */
+declare function parseUetMsclkid(raw: string | undefined | null): string | undefined;
+/** Build a `_uetmsclkid` value in bat.js's own format. */
+declare function formatUetMsclkid(clickId: string): string;
+/**
+ * The click id as the Conversions API wants it: a dashed, lowercase UUID. The URL and the cookie
+ * carry the 32-hex form; a value in any other shape is returned untouched for the API to judge.
+ */
+declare function formatMsclkid(clickId: string): string;
 type ResolveClickIdCookiesInput = {
   /** The absolute request URL (must include the query string). */
   url: string;
@@ -77,6 +90,8 @@ type ResolveClickIdCookiesResult = {
   gclid?: string;
   /** The resolved iOS web-to-app click id (from the URL or a still-valid `_gcl_gb`). */
   wbraid?: string;
+  /** The resolved Microsoft Ads click id (from the URL or `_uetmsclkid`), 32-hex form. */
+  msclkid?: string;
 };
 /**
  * Resolve the click-id cookies to set on the current document response.
@@ -92,5 +107,5 @@ declare function resolveClickIdCookies(input: ResolveClickIdCookiesInput): Resol
 /** Serialize the resolved cookies into `Set-Cookie` header values. */
 declare function toSetCookieHeaders(cookies: SetCookie[]): string[];
 //#endregion
-export { FBC_COOKIE, GCL_AW_COOKIE, GCL_GB_COOKIE, ParsedFbc, ParsedGcl, RDT_CID_COOKIE, ResolveClickIdCookiesInput, ResolveClickIdCookiesResult, formatFbc, formatGcl, parseFbc, parseGcl, resolveClickIdCookies, toSetCookieHeaders };
+export { FBC_COOKIE, GCL_AW_COOKIE, GCL_GB_COOKIE, ParsedFbc, ParsedGcl, RDT_CID_COOKIE, ResolveClickIdCookiesInput, ResolveClickIdCookiesResult, UET_MSCLKID_COOKIE, formatFbc, formatGcl, formatMsclkid, formatUetMsclkid, parseFbc, parseGcl, parseUetMsclkid, resolveClickIdCookies, toSetCookieHeaders };
 //# sourceMappingURL=index.d.mts.map

package/dist/click-id/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/click-id/index.ts"],"mappings":";;cA0Ba;cACA;cACA;cACA;KAED;EAAc;EAAa;EAAsB;;;;;;;iBAO7C,SACd,gCACA,eACC;;;;;iBAmBa,UAAU,gBAAgB,aAAa;KAI3C;EAAc;EAAa;EAAsB;;;;;;;;iBAW7C,SACd,gCACA,eACC;;iBAgBa,UAAU,iBAAiB;KAI/B;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;EAeA;;KAGU;;;;;EAKV,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;iBAuBc,sBACd,OAAO,6BACN;;iBA4Fa,mBAAmB,SAAS"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/click-id/index.ts"],"mappings":";;cA2Ca;cACA;cACA;cACA;cACA;KAED;EAAc;EAAa;EAAsB;;;;;;;iBAO7C,SACd,gCACA,eACC;;;;;iBAmBa,UAAU,gBAAgB,aAAa;KAI3C;EAAc;EAAa;EAAsB;;;;;;;;iBAa7C,SACd,gCACA,eACC;;iBAgBa,UAAU,iBAAiB;;;;;iBAe3B,gBAAgB;;iBAOhB,iBAAiB;;;;;iBAQjB,cAAc;KAMlB;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;EAeA;;KAGU;;;;;EAKV,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;iBAuBc,sBACd,OAAO,6BACN;;iBAoHa,mBAAmB,SAAS"}

package/dist/click-id/index.mjs

@@ -1,8 +1,8 @@
 import { parseCookie, stringifySetCookie } from "cookie";
 //#region src/click-id/index.ts
 /**
-* Server-side resolution of ad-click-id cookies (`_fbc`, `_gcl_aw`/`_gcl_gb`, `_rdt_cid`) from
-* the incoming request.
+* Server-side resolution of ad-click-id cookies (`_fbc`, `_gcl_aw`/`_gcl_gb`, `_rdt_cid`,
+* `_uetmsclkid`) from the incoming request.
 *
 * This is the framework-agnostic core meant to run on the *document* response (e.g. TanStack Start
 * server middleware, Next middleware). Setting `_fbc` via an HTTP `Set-Cookie` header on the top
@@ -11,16 +11,33 @@ import { parseCookie, stringifySetCookie } from "cookie";
 * cookies on a fbclid-decorated landing page to 24 hours, and the document response is never
 * classified as CNAME/IP cloaking (it is the reference the browser measures cloaking against).
 *
-* reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc
+* The Google pair follows the same architecture Google itself ships for server containers —
+* sGTM's Conversion Linker sets FPGCLAW via Set-Cookie for 90 days — and the sGTM ecosystem
+* productized for gtag's own cookies (stape Cookie Keeper re-issues `_gcl_*` over HTTP; vendor
+* case studies report 5–20% of Google Ads conversions recovered, up to +44% on the Safari
+* slice). One deployment caveat from WebKit's rules: the HTTP-cookie exemption holds only for
+* responses from the site's own infrastructure — a CNAME or third-party-IP host (a tagging
+* subdomain on someone else's cloud) gets its Set-Cookie silently capped to 7 days. This module
+* runs on the host's own document response, which is exactly the exempt case.
+*
+* references:
+* - https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc
+* - https://webkit.org/tracking-prevention/ (7d JS cookies, 24h on ad-decorated landings,
+*   CNAME/third-party-IP HTTP cookies capped to 7d, same-origin HTTP cookies exempt)
+* - https://www.simoahava.com/analytics/google-ads-server-side-tagging-google-tag-manager/
+*   (Conversion Linker → FPGCLAW via Set-Cookie, Google's own server-side equivalent)
+* - https://stape.io/helpdesk/documentation/cookie-keeper-power-up (the productized re-issue)
 */
 const FBC_TTL_MS = 7776e6;
 const RDT_CID_TTL_MS = 7776e6;
+const MSCLKID_TTL_MS = 7776e6;
 const GCL_TTL_MS = 7776e6;
 const CLOCK_SKEW_MS = 864e5;
 const FBC_COOKIE = "_fbc";
 const RDT_CID_COOKIE = "_rdt_cid";
 const GCL_AW_COOKIE = "_gcl_aw";
 const GCL_GB_COOKIE = "_gcl_gb";
+const UET_MSCLKID_COOKIE = "_uetmsclkid";
 /**
 * Parse `fb.<subdomainIndex>.<creationTime>.<fbclid>`.
 * Returns undefined for anything malformed — a fbclid never contains a dot, but joining the tail
@@ -76,6 +93,30 @@ function parseGcl(raw, now = Date.now()) {
 function formatGcl(clickId, now) {
 	return `GCL.${Math.floor(now / 1e3)}.${clickId}`;
 }
+const UET_MSCLKID_PREFIX = "_uet";
+const MSCLKID = /^[0-9a-f]{32}$/i;
+/**
+* Parse a `_uetmsclkid` value: `_uet<32 hex>`. Returns the click id, lowercased, or undefined
+* for anything bat.js itself would not read back.
+*/
+function parseUetMsclkid(raw) {
+	if (!raw || !raw.startsWith(UET_MSCLKID_PREFIX)) return void 0;
+	const clickId = raw.slice(4);
+	return MSCLKID.test(clickId) ? clickId.toLowerCase() : void 0;
+}
+/** Build a `_uetmsclkid` value in bat.js's own format. */
+function formatUetMsclkid(clickId) {
+	return `${UET_MSCLKID_PREFIX}${clickId.toLowerCase()}`;
+}
+/**
+* The click id as the Conversions API wants it: a dashed, lowercase UUID. The URL and the cookie
+* carry the 32-hex form; a value in any other shape is returned untouched for the API to judge.
+*/
+function formatMsclkid(clickId) {
+	const id = clickId.trim().toLowerCase();
+	if (!MSCLKID.test(id)) return id;
+	return `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`;
+}
 function searchParams(url) {
 	try {
 		return new URL(url).searchParams;
@@ -162,6 +203,15 @@ function resolveClickIdCookies(input) {
 		set(RDT_CID_COOKIE, urlRdtCid, RDT_CID_TTL_MS);
 		result.rdt_cid = urlRdtCid;
 	} else if (existingRdtCid) result.rdt_cid = existingRdtCid;
+	const urlMsclkid = params.get("msclkid")?.trim();
+	const existingMsclkid = parseUetMsclkid(jar[UET_MSCLKID_COOKIE]);
+	if (urlMsclkid && MSCLKID.test(urlMsclkid) && urlMsclkid.toLowerCase() !== existingMsclkid) {
+		set(UET_MSCLKID_COOKIE, formatUetMsclkid(urlMsclkid), MSCLKID_TTL_MS);
+		result.msclkid = urlMsclkid.toLowerCase();
+	} else if (existingMsclkid) {
+		result.msclkid = existingMsclkid;
+		if (refresh) set(UET_MSCLKID_COOKIE, formatUetMsclkid(existingMsclkid), MSCLKID_TTL_MS);
+	}
 	return result;
 }
 /** Serialize the resolved cookies into `Set-Cookie` header values. */
@@ -169,6 +219,6 @@ function toSetCookieHeaders(cookies) {
 	return cookies.map((cookie) => stringifySetCookie(cookie));
 }
 //#endregion
-export { FBC_COOKIE, GCL_AW_COOKIE, GCL_GB_COOKIE, RDT_CID_COOKIE, formatFbc, formatGcl, parseFbc, parseGcl, resolveClickIdCookies, toSetCookieHeaders };
+export { FBC_COOKIE, GCL_AW_COOKIE, GCL_GB_COOKIE, RDT_CID_COOKIE, UET_MSCLKID_COOKIE, formatFbc, formatGcl, formatMsclkid, formatUetMsclkid, parseFbc, parseGcl, parseUetMsclkid, resolveClickIdCookies, toSetCookieHeaders };
 
 //# sourceMappingURL=index.mjs.map

package/dist/click-id/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/click-id/index.ts"],"sourcesContent":["import { type SetCookie, parseCookie, stringifySetCookie } from 'cookie';\n\n/**\n * Server-side resolution of ad-click-id cookies (`_fbc`, `_gcl_aw`/`_gcl_gb`, `_rdt_cid`) from\n * the incoming request.\n *\n * This is the framework-agnostic core meant to run on the *document* response (e.g. TanStack Start\n * server middleware, Next middleware). Setting `_fbc` via an HTTP `Set-Cookie` header on the top\n * document — rather than `document.cookie` on the client — is what Meta officially recommends and is\n * the only reliable way to keep the cookie alive for 90 days in Safari: ITP caps JavaScript-set\n * cookies on a fbclid-decorated landing page to 24 hours, and the document response is never\n * classified as CNAME/IP cloaking (it is the reference the browser measures cloaking against).\n *\n * reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc\n */\n\n// Meta's recommended _fbc cookie expiry. Events Manager warns (\"Server sending expired fbclid\")\n// when the embedded creationTime is older than 90 days and match quality/attribution may degrade;\n// no hard drop is documented.\nconst FBC_TTL_MS = 90 * 24 * 60 * 60 * 1000;\nconst RDT_CID_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// gtag's own expiry for _gcl_* — 90 days, the length of a Google Ads click's upload window.\nconst GCL_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// Tolerate a little clock skew when validating a creationTime against \"now\".\nconst CLOCK_SKEW_MS = 24 * 60 * 60 * 1000;\n\nexport const FBC_COOKIE = '_fbc';\nexport const RDT_CID_COOKIE = '_rdt_cid';\nexport const GCL_AW_COOKIE = '_gcl_aw';\nexport const GCL_GB_COOKIE = '_gcl_gb';\n\nexport type ParsedFbc = { raw: string; creationTime: number; fbclid: string };\n\n/**\n * Parse `fb.<subdomainIndex>.<creationTime>.<fbclid>`.\n * Returns undefined for anything malformed — a fbclid never contains a dot, but joining the tail\n * back together keeps us forward-compatible if that ever changes.\n */\nexport function parseFbc(\n  raw: string | undefined | null,\n  now: number = Date.now()\n): ParsedFbc | undefined {\n  if (!raw) return undefined;\n  const parts = raw.split('.');\n  if (parts.length < 4 || parts[0] !== 'fb') return undefined;\n\n  const creationTime = Number(parts[2]);\n  const fbclid = parts.slice(3).join('.');\n  if (!fbclid) return undefined;\n  // creationTime is UNIX ms; reject seconds-precision or future-dated values as malformed.\n  if (!Number.isFinite(creationTime)) return undefined;\n  if (creationTime < 1e12 || creationTime > now + CLOCK_SKEW_MS) return undefined;\n\n  return { raw, creationTime, fbclid };\n}\n\n/**\n * Build a fresh `_fbc` value. subdomainIndex is the cookie's domain level (com=0, example.com=1,\n * www.example.com=2); 1 is correct for an apex-hosted cookie.\n */\nexport function formatFbc(fbclid: string, now: number, subdomainIndex = 1): string {\n  return `fb.${subdomainIndex}.${now}.${fbclid}`;\n}\n\nexport type ParsedGcl = { raw: string; creationTime: number; clickId: string };\n\n// gtag's own value validator, extracted from gtag.js: the click id segment must match this.\nconst GCL_CLICK_ID = /^[\\w-]+$/;\n\n/**\n * Parse a `_gcl_aw`/`_gcl_gb` value: `GCL.<seconds>.<clickId>[.<labels…>]` — note the timestamp\n * is in SECONDS, unlike `_fbc`'s milliseconds. gtag's parser accepts version `GCL` or `1` and\n * validates the segments exactly this way (`/^\\d+$/` timestamp, `/^[\\w-]+$/` click id); any\n * labels tail is preserved through `raw` so a re-issue stays byte-identical.\n */\nexport function parseGcl(\n  raw: string | undefined | null,\n  now: number = Date.now()\n): ParsedGcl | undefined {\n  if (!raw) return undefined;\n  const parts = raw.split('.');\n  if (parts.length < 3) return undefined;\n  if (parts[0] !== 'GCL' && parts[0] !== '1') return undefined;\n  const seconds = parts[1];\n  const clickId = parts[2];\n  if (seconds === undefined || !/^\\d+$/.test(seconds)) return undefined;\n  if (clickId === undefined || !GCL_CLICK_ID.test(clickId)) return undefined;\n  const creationTime = Number(seconds) * 1000;\n  // Reject millisecond-precision or future-dated values as malformed.\n  if (creationTime >= 1e15 || creationTime > now + CLOCK_SKEW_MS) return undefined;\n  return { raw, creationTime, clickId };\n}\n\n/** Build a fresh `_gcl_aw`/`_gcl_gb` value in gtag's own format. */\nexport function formatGcl(clickId: string, now: number): string {\n  return `GCL.${Math.floor(now / 1000)}.${clickId}`;\n}\n\nexport type ResolveClickIdCookiesInput = {\n  /** The absolute request URL (must include the query string). */\n  url: string;\n  /** The raw `Cookie` request header, if any. */\n  cookieHeader?: string | null;\n  /** Overridable clock, primarily for tests. Defaults to `Date.now()`. */\n  now?: number;\n  /** `Domain` attribute for the emitted cookies, e.g. `.shware.io`. Omit for a host-only cookie. */\n  domain?: string;\n  /** `Secure` attribute, default true. Set false only for local http testing. */\n  secure?: boolean;\n  /** subdomainIndex for a freshly built `_fbc` (see {@link formatFbc}). Default 1. */\n  subdomainIndex?: number;\n  /**\n   * Re-issue a still-valid `_fbc` at its *remaining* lifetime on every call. On by default, as an\n   * ITP self-heal: cookies follow last-writer-wins, so if the Meta Pixel overwrote `_fbc` via\n   * `document.cookie` (Safari caps JS-written cookies on a fbclid-decorated landing to 24h),\n   * re-issuing the long-lived HTTP cookie on the next navigation restores it — the same\n   * continuous-re-issue mitigation the sGTM ecosystem uses (stape Cookie Keeper, Cookie Monster).\n   * The value (and its creationTime) is byte-for-byte identical and the window never slides, so it\n   * cannot trigger Meta's expired/modified-fbclid warnings.\n   *\n   * Set false to strictly follow Meta's documented conditional-write rule (\"only set the cookie if\n   * it doesn't exist or the fbclid changed\") — e.g. to keep pages CDN-cacheable, since the\n   * re-issue attaches a per-user `Set-Cookie` (forcing `no-store`) to every response carrying an\n   * `_fbc`.\n   */\n  refresh?: boolean;\n};\n\nexport type ResolveClickIdCookiesResult = {\n  /**\n   * Cookies to emit on the response, ready for `Set-Cookie`. Empty when nothing needs to change.\n   * A `value: ''`, `maxAge: 0` entry is a deletion (an expired or malformed leftover).\n   */\n  cookies: SetCookie[];\n  /** The resolved `_fbc` value, for immediate server-side use (e.g. Conversions API). */\n  fbc?: string;\n  /** The resolved `_rdt_cid` value. */\n  rdt_cid?: string;\n  /** The resolved Google Ads click id (from the URL or a still-valid `_gcl_aw`). */\n  gclid?: string;\n  /** The resolved iOS web-to-app click id (from the URL or a still-valid `_gcl_gb`). */\n  wbraid?: string;\n};\n\nfunction searchParams(url: string): URLSearchParams {\n  try {\n    return new URL(url).searchParams;\n  } catch {\n    // Fall back to a manual split so a relative or slightly malformed URL still yields the query.\n    const q = url.indexOf('?');\n    return new URLSearchParams(q !== -1 ? url.slice(q + 1) : '');\n  }\n}\n\n/**\n * Resolve the click-id cookies to set on the current document response.\n *\n * `_fbc` follows Meta's documented conditional-write rule value-wise: a new fbclid (or an absent\n * cookie) opens a fresh 90-day window; a same-fbclid cookie keeps its original value and\n * `creationTime`. Expired (>90d) or malformed values are cleared instead of forwarded. By default,\n * ({@link ResolveClickIdCookiesInput.refresh}) a still-valid cookie is re-issued unchanged at its\n * *remaining* lifetime — never `now + 90d` — so a returning visitor's window cannot slide forward\n * (which is what makes Meta flag an expired fbclid).\n */\nexport function resolveClickIdCookies(\n  input: ResolveClickIdCookiesInput\n): ResolveClickIdCookiesResult {\n  const { url, cookieHeader, domain, secure = true, subdomainIndex = 1, refresh = true } = input;\n  const now = input.now ?? Date.now();\n\n  const params = searchParams(url);\n  const jar = parseCookie(cookieHeader ?? '');\n  const cookies: SetCookie[] = [];\n  const result: ResolveClickIdCookiesResult = { cookies };\n\n  const base = { path: '/', secure, sameSite: 'lax', domain } as const;\n  const set = (name: string, value: string, ttlMs: number) =>\n    cookies.push({ name, value, maxAge: Math.floor(ttlMs / 1000), ...base });\n  const del = (name: string) => cookies.push({ name, value: '', maxAge: 0, ...base });\n\n  // --- Meta _fbc ---\n  const urlFbclid = params.get('fbclid') || undefined;\n  const existingFbc = parseFbc(jar[FBC_COOKIE], now);\n\n  if (urlFbclid && urlFbclid !== existingFbc?.fbclid) {\n    // A new click always wins and opens a fresh 90-day window.\n    const raw = formatFbc(urlFbclid, now, subdomainIndex);\n    set(FBC_COOKIE, raw, FBC_TTL_MS);\n    result.fbc = raw;\n  } else if (existingFbc) {\n    const remainingMs = existingFbc.creationTime + FBC_TTL_MS - now;\n    if (remainingMs <= 0) {\n      del(FBC_COOKIE);\n    } else {\n      // Same fbclid: the value and creationTime are preserved (Meta's rule); refresh (default)\n      // re-issues it unchanged at its remaining lifetime as an ITP self-heal.\n      result.fbc = existingFbc.raw;\n      if (refresh) set(FBC_COOKIE, existingFbc.raw, remainingMs);\n    }\n  } else if (jar[FBC_COOKIE]) {\n    // Malformed leftover — clear it rather than forwarding it to Meta.\n    del(FBC_COOKIE);\n  }\n\n  // --- Google Ads _gcl_aw / _gcl_gb ---\n  // The same first-party HTTP persistence Google's own server-side Conversion Linker performs\n  // (it sets FPGCLAW via Set-Cookie for 90 days), applied to gtag's cookies the way the sGTM\n  // ecosystem does (stape Cookie Keeper re-issues _gcl_* over HTTP). Ownership is shared with\n  // gtag, so the rules are stricter than for _fbc: a value this module cannot parse is left\n  // untouched — never rewritten, never deleted — and a re-issue is byte-identical (labels tail\n  // included) at the window's REMAINING lifetime, so the 90-day click window never slides.\n  const gclsrc = params.get('gclsrc') || undefined;\n  const google = [\n    {\n      cookie: GCL_AW_COOKIE,\n      // gtag's own gating, verbatim: a gclid enters _gcl_aw only when gclsrc is absent or\n      // 'aw.ds' — 'ds'/'3p.ds' clicks are Search Ads 360's and belong to _gcl_dc.\n      urlClickId: !gclsrc || gclsrc === 'aw.ds' ? params.get('gclid') || undefined : undefined,\n      assign: (value: string) => (result.gclid = value),\n    },\n    {\n      cookie: GCL_GB_COOKIE,\n      urlClickId: params.get('wbraid') || undefined,\n      assign: (value: string) => (result.wbraid = value),\n    },\n  ];\n  for (const { cookie, urlClickId, assign } of google) {\n    const existing = parseGcl(jar[cookie], now);\n    if (urlClickId && GCL_CLICK_ID.test(urlClickId) && urlClickId !== existing?.clickId) {\n      // A new click always wins and opens a fresh 90-day window, in gtag's exact format.\n      set(cookie, formatGcl(urlClickId, now), GCL_TTL_MS);\n      assign(urlClickId);\n    } else if (existing) {\n      const remainingMs = existing.creationTime + GCL_TTL_MS - now;\n      if (remainingMs > 0) {\n        assign(existing.clickId);\n        if (refresh) set(cookie, existing.raw, remainingMs);\n      }\n      // Expired: not returned and not re-issued, but gtag owns the deletion.\n    }\n  }\n\n  // --- Reddit _rdt_cid ---\n  // No embedded timestamp, so it can only be anchored at first capture; set it once from the URL and\n  // otherwise leave the existing cookie untouched (re-issuing would slide its window).\n  const urlRdtCid = params.get('rdt_cid') || undefined;\n  const existingRdtCid = jar[RDT_CID_COOKIE] || undefined;\n  if (urlRdtCid && urlRdtCid !== existingRdtCid) {\n    set(RDT_CID_COOKIE, urlRdtCid, RDT_CID_TTL_MS);\n    result.rdt_cid = urlRdtCid;\n  } else if (existingRdtCid) {\n    result.rdt_cid = existingRdtCid;\n  }\n\n  return result;\n}\n\n/** Serialize the resolved cookies into `Set-Cookie` header values. */\nexport function toSetCookieHeaders(cookies: SetCookie[]): string[] {\n  return cookies.map((cookie) => stringifySetCookie(cookie));\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/click-id/index.ts"],"sourcesContent":["import { type SetCookie, parseCookie, stringifySetCookie } from 'cookie';\n\n/**\n * Server-side resolution of ad-click-id cookies (`_fbc`, `_gcl_aw`/`_gcl_gb`, `_rdt_cid`,\n * `_uetmsclkid`) from the incoming request.\n *\n * This is the framework-agnostic core meant to run on the *document* response (e.g. TanStack Start\n * server middleware, Next middleware). Setting `_fbc` via an HTTP `Set-Cookie` header on the top\n * document — rather than `document.cookie` on the client — is what Meta officially recommends and is\n * the only reliable way to keep the cookie alive for 90 days in Safari: ITP caps JavaScript-set\n * cookies on a fbclid-decorated landing page to 24 hours, and the document response is never\n * classified as CNAME/IP cloaking (it is the reference the browser measures cloaking against).\n *\n * The Google pair follows the same architecture Google itself ships for server containers —\n * sGTM's Conversion Linker sets FPGCLAW via Set-Cookie for 90 days — and the sGTM ecosystem\n * productized for gtag's own cookies (stape Cookie Keeper re-issues `_gcl_*` over HTTP; vendor\n * case studies report 5–20% of Google Ads conversions recovered, up to +44% on the Safari\n * slice). One deployment caveat from WebKit's rules: the HTTP-cookie exemption holds only for\n * responses from the site's own infrastructure — a CNAME or third-party-IP host (a tagging\n * subdomain on someone else's cloud) gets its Set-Cookie silently capped to 7 days. This module\n * runs on the host's own document response, which is exactly the exempt case.\n *\n * references:\n * - https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc\n * - https://webkit.org/tracking-prevention/ (7d JS cookies, 24h on ad-decorated landings,\n *   CNAME/third-party-IP HTTP cookies capped to 7d, same-origin HTTP cookies exempt)\n * - https://www.simoahava.com/analytics/google-ads-server-side-tagging-google-tag-manager/\n *   (Conversion Linker → FPGCLAW via Set-Cookie, Google's own server-side equivalent)\n * - https://stape.io/helpdesk/documentation/cookie-keeper-power-up (the productized re-issue)\n */\n\n// Meta's recommended _fbc cookie expiry. Events Manager warns (\"Server sending expired fbclid\")\n// when the embedded creationTime is older than 90 days and match quality/attribution may degrade;\n// no hard drop is documented.\nconst FBC_TTL_MS = 90 * 24 * 60 * 60 * 1000;\nconst RDT_CID_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// bat.js's own expiry for _uetmsclkid (`msClkIdExpirationTime`), the Microsoft Ads click window.\nconst MSCLKID_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// gtag's own expiry for _gcl_* — 90 days, the length of a Google Ads click's upload window.\nconst GCL_TTL_MS = 90 * 24 * 60 * 60 * 1000;\n// Tolerate a little clock skew when validating a creationTime against \"now\".\nconst CLOCK_SKEW_MS = 24 * 60 * 60 * 1000;\n\nexport const FBC_COOKIE = '_fbc';\nexport const RDT_CID_COOKIE = '_rdt_cid';\nexport const GCL_AW_COOKIE = '_gcl_aw';\nexport const GCL_GB_COOKIE = '_gcl_gb';\nexport const UET_MSCLKID_COOKIE = '_uetmsclkid';\n\nexport type ParsedFbc = { raw: string; creationTime: number; fbclid: string };\n\n/**\n * Parse `fb.<subdomainIndex>.<creationTime>.<fbclid>`.\n * Returns undefined for anything malformed — a fbclid never contains a dot, but joining the tail\n * back together keeps us forward-compatible if that ever changes.\n */\nexport function parseFbc(\n  raw: string | undefined | null,\n  now: number = Date.now()\n): ParsedFbc | undefined {\n  if (!raw) return undefined;\n  const parts = raw.split('.');\n  if (parts.length < 4 || parts[0] !== 'fb') return undefined;\n\n  const creationTime = Number(parts[2]);\n  const fbclid = parts.slice(3).join('.');\n  if (!fbclid) return undefined;\n  // creationTime is UNIX ms; reject seconds-precision or future-dated values as malformed.\n  if (!Number.isFinite(creationTime)) return undefined;\n  if (creationTime < 1e12 || creationTime > now + CLOCK_SKEW_MS) return undefined;\n\n  return { raw, creationTime, fbclid };\n}\n\n/**\n * Build a fresh `_fbc` value. subdomainIndex is the cookie's domain level (com=0, example.com=1,\n * www.example.com=2); 1 is correct for an apex-hosted cookie.\n */\nexport function formatFbc(fbclid: string, now: number, subdomainIndex = 1): string {\n  return `fb.${subdomainIndex}.${now}.${fbclid}`;\n}\n\nexport type ParsedGcl = { raw: string; creationTime: number; clickId: string };\n\n// gtag's own value validator, extracted from the live gtag.js bundle (2026-09): its parser\n// accepts version \"GCL\" or \"1\", a /^\\d+$/ seconds timestamp, and a click id matching this.\n// Re-verify against gtag.js before changing anything here — the format is gtag's, not ours.\nconst GCL_CLICK_ID = /^[\\w-]+$/;\n\n/**\n * Parse a `_gcl_aw`/`_gcl_gb` value: `GCL.<seconds>.<clickId>[.<labels…>]` — note the timestamp\n * is in SECONDS, unlike `_fbc`'s milliseconds. gtag's parser accepts version `GCL` or `1` and\n * validates the segments exactly this way (`/^\\d+$/` timestamp, `/^[\\w-]+$/` click id); any\n * labels tail is preserved through `raw` so a re-issue stays byte-identical.\n */\nexport function parseGcl(\n  raw: string | undefined | null,\n  now: number = Date.now()\n): ParsedGcl | undefined {\n  if (!raw) return undefined;\n  const parts = raw.split('.');\n  if (parts.length < 3) return undefined;\n  if (parts[0] !== 'GCL' && parts[0] !== '1') return undefined;\n  const seconds = parts[1];\n  const clickId = parts[2];\n  if (seconds === undefined || !/^\\d+$/.test(seconds)) return undefined;\n  if (clickId === undefined || !GCL_CLICK_ID.test(clickId)) return undefined;\n  const creationTime = Number(seconds) * 1000;\n  // Reject millisecond-precision or future-dated values as malformed.\n  if (creationTime >= 1e15 || creationTime > now + CLOCK_SKEW_MS) return undefined;\n  return { raw, creationTime, clickId };\n}\n\n/** Build a fresh `_gcl_aw`/`_gcl_gb` value in gtag's own format. */\nexport function formatGcl(clickId: string, now: number): string {\n  return `GCL.${Math.floor(now / 1000)}.${clickId}`;\n}\n\n// bat.js writes the click id as `_uet<msclkid>` and reads it back only when what follows the\n// prefix is at most 32 characters (`msClkIdCookieValuePrefix`, `lengthMsClkId`); a msclkid is a\n// 32-hex-digit UUID without dashes. Re-verify against bat.js before changing anything here —\n// the format is UET's, not ours.\nconst UET_MSCLKID_PREFIX = '_uet';\nconst MSCLKID = /^[0-9a-f]{32}$/i;\n\n/**\n * Parse a `_uetmsclkid` value: `_uet<32 hex>`. Returns the click id, lowercased, or undefined\n * for anything bat.js itself would not read back.\n */\nexport function parseUetMsclkid(raw: string | undefined | null): string | undefined {\n  if (!raw || !raw.startsWith(UET_MSCLKID_PREFIX)) return undefined;\n  const clickId = raw.slice(UET_MSCLKID_PREFIX.length);\n  return MSCLKID.test(clickId) ? clickId.toLowerCase() : undefined;\n}\n\n/** Build a `_uetmsclkid` value in bat.js's own format. */\nexport function formatUetMsclkid(clickId: string): string {\n  return `${UET_MSCLKID_PREFIX}${clickId.toLowerCase()}`;\n}\n\n/**\n * The click id as the Conversions API wants it: a dashed, lowercase UUID. The URL and the cookie\n * carry the 32-hex form; a value in any other shape is returned untouched for the API to judge.\n */\nexport function formatMsclkid(clickId: string): string {\n  const id = clickId.trim().toLowerCase();\n  if (!MSCLKID.test(id)) return id;\n  return `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`;\n}\n\nexport type ResolveClickIdCookiesInput = {\n  /** The absolute request URL (must include the query string). */\n  url: string;\n  /** The raw `Cookie` request header, if any. */\n  cookieHeader?: string | null;\n  /** Overridable clock, primarily for tests. Defaults to `Date.now()`. */\n  now?: number;\n  /** `Domain` attribute for the emitted cookies, e.g. `.shware.io`. Omit for a host-only cookie. */\n  domain?: string;\n  /** `Secure` attribute, default true. Set false only for local http testing. */\n  secure?: boolean;\n  /** subdomainIndex for a freshly built `_fbc` (see {@link formatFbc}). Default 1. */\n  subdomainIndex?: number;\n  /**\n   * Re-issue a still-valid `_fbc` at its *remaining* lifetime on every call. On by default, as an\n   * ITP self-heal: cookies follow last-writer-wins, so if the Meta Pixel overwrote `_fbc` via\n   * `document.cookie` (Safari caps JS-written cookies on a fbclid-decorated landing to 24h),\n   * re-issuing the long-lived HTTP cookie on the next navigation restores it — the same\n   * continuous-re-issue mitigation the sGTM ecosystem uses (stape Cookie Keeper, Cookie Monster).\n   * The value (and its creationTime) is byte-for-byte identical and the window never slides, so it\n   * cannot trigger Meta's expired/modified-fbclid warnings.\n   *\n   * Set false to strictly follow Meta's documented conditional-write rule (\"only set the cookie if\n   * it doesn't exist or the fbclid changed\") — e.g. to keep pages CDN-cacheable, since the\n   * re-issue attaches a per-user `Set-Cookie` (forcing `no-store`) to every response carrying an\n   * `_fbc`.\n   */\n  refresh?: boolean;\n};\n\nexport type ResolveClickIdCookiesResult = {\n  /**\n   * Cookies to emit on the response, ready for `Set-Cookie`. Empty when nothing needs to change.\n   * A `value: ''`, `maxAge: 0` entry is a deletion (an expired or malformed leftover).\n   */\n  cookies: SetCookie[];\n  /** The resolved `_fbc` value, for immediate server-side use (e.g. Conversions API). */\n  fbc?: string;\n  /** The resolved `_rdt_cid` value. */\n  rdt_cid?: string;\n  /** The resolved Google Ads click id (from the URL or a still-valid `_gcl_aw`). */\n  gclid?: string;\n  /** The resolved iOS web-to-app click id (from the URL or a still-valid `_gcl_gb`). */\n  wbraid?: string;\n  /** The resolved Microsoft Ads click id (from the URL or `_uetmsclkid`), 32-hex form. */\n  msclkid?: string;\n};\n\nfunction searchParams(url: string): URLSearchParams {\n  try {\n    return new URL(url).searchParams;\n  } catch {\n    // Fall back to a manual split so a relative or slightly malformed URL still yields the query.\n    const q = url.indexOf('?');\n    return new URLSearchParams(q !== -1 ? url.slice(q + 1) : '');\n  }\n}\n\n/**\n * Resolve the click-id cookies to set on the current document response.\n *\n * `_fbc` follows Meta's documented conditional-write rule value-wise: a new fbclid (or an absent\n * cookie) opens a fresh 90-day window; a same-fbclid cookie keeps its original value and\n * `creationTime`. Expired (>90d) or malformed values are cleared instead of forwarded. By default,\n * ({@link ResolveClickIdCookiesInput.refresh}) a still-valid cookie is re-issued unchanged at its\n * *remaining* lifetime — never `now + 90d` — so a returning visitor's window cannot slide forward\n * (which is what makes Meta flag an expired fbclid).\n */\nexport function resolveClickIdCookies(\n  input: ResolveClickIdCookiesInput\n): ResolveClickIdCookiesResult {\n  const { url, cookieHeader, domain, secure = true, subdomainIndex = 1, refresh = true } = input;\n  const now = input.now ?? Date.now();\n\n  const params = searchParams(url);\n  const jar = parseCookie(cookieHeader ?? '');\n  const cookies: SetCookie[] = [];\n  const result: ResolveClickIdCookiesResult = { cookies };\n\n  const base = { path: '/', secure, sameSite: 'lax', domain } as const;\n  const set = (name: string, value: string, ttlMs: number) =>\n    cookies.push({ name, value, maxAge: Math.floor(ttlMs / 1000), ...base });\n  const del = (name: string) => cookies.push({ name, value: '', maxAge: 0, ...base });\n\n  // --- Meta _fbc ---\n  const urlFbclid = params.get('fbclid') || undefined;\n  const existingFbc = parseFbc(jar[FBC_COOKIE], now);\n\n  if (urlFbclid && urlFbclid !== existingFbc?.fbclid) {\n    // A new click always wins and opens a fresh 90-day window.\n    const raw = formatFbc(urlFbclid, now, subdomainIndex);\n    set(FBC_COOKIE, raw, FBC_TTL_MS);\n    result.fbc = raw;\n  } else if (existingFbc) {\n    const remainingMs = existingFbc.creationTime + FBC_TTL_MS - now;\n    if (remainingMs <= 0) {\n      del(FBC_COOKIE);\n    } else {\n      // Same fbclid: the value and creationTime are preserved (Meta's rule); refresh (default)\n      // re-issues it unchanged at its remaining lifetime as an ITP self-heal.\n      result.fbc = existingFbc.raw;\n      if (refresh) set(FBC_COOKIE, existingFbc.raw, remainingMs);\n    }\n  } else if (jar[FBC_COOKIE]) {\n    // Malformed leftover — clear it rather than forwarding it to Meta.\n    del(FBC_COOKIE);\n  }\n\n  // --- Google Ads _gcl_aw / _gcl_gb ---\n  // The same first-party HTTP persistence Google's own server-side Conversion Linker performs\n  // (it sets FPGCLAW via Set-Cookie for 90 days), applied to gtag's cookies the way the sGTM\n  // ecosystem does (stape Cookie Keeper re-issues _gcl_* over HTTP). Ownership is shared with\n  // gtag, so the rules are stricter than for _fbc: a value this module cannot parse is left\n  // untouched — never rewritten, never deleted — and a re-issue is byte-identical (labels tail\n  // included) at the window's REMAINING lifetime, so the 90-day click window never slides.\n  const gclsrc = params.get('gclsrc') || undefined;\n  const google = [\n    {\n      cookie: GCL_AW_COOKIE,\n      // gtag's own gating, verbatim: a gclid enters _gcl_aw only when gclsrc is absent or\n      // 'aw.ds' — 'ds'/'3p.ds' clicks are Search Ads 360's and belong to _gcl_dc.\n      urlClickId: !gclsrc || gclsrc === 'aw.ds' ? params.get('gclid') || undefined : undefined,\n      assign: (value: string) => (result.gclid = value),\n    },\n    {\n      cookie: GCL_GB_COOKIE,\n      urlClickId: params.get('wbraid') || undefined,\n      assign: (value: string) => (result.wbraid = value),\n    },\n  ];\n  for (const { cookie, urlClickId, assign } of google) {\n    const existing = parseGcl(jar[cookie], now);\n    if (urlClickId && GCL_CLICK_ID.test(urlClickId) && urlClickId !== existing?.clickId) {\n      // A new click always wins and opens a fresh 90-day window, in gtag's exact format.\n      set(cookie, formatGcl(urlClickId, now), GCL_TTL_MS);\n      assign(urlClickId);\n    } else if (existing) {\n      const remainingMs = existing.creationTime + GCL_TTL_MS - now;\n      if (remainingMs > 0) {\n        assign(existing.clickId);\n        if (refresh) set(cookie, existing.raw, remainingMs);\n      }\n      // Expired: not returned and not re-issued, but gtag owns the deletion.\n    }\n  }\n\n  // --- Reddit _rdt_cid ---\n  // No embedded timestamp, so it can only be anchored at first capture; set it once from the URL and\n  // otherwise leave the existing cookie untouched (re-issuing would slide its window).\n  const urlRdtCid = params.get('rdt_cid') || undefined;\n  const existingRdtCid = jar[RDT_CID_COOKIE] || undefined;\n  if (urlRdtCid && urlRdtCid !== existingRdtCid) {\n    set(RDT_CID_COOKIE, urlRdtCid, RDT_CID_TTL_MS);\n    result.rdt_cid = urlRdtCid;\n  } else if (existingRdtCid) {\n    result.rdt_cid = existingRdtCid;\n  }\n\n  // --- Microsoft Ads _uetmsclkid ---\n  // The UET tag's own cookie, in its own format, so the tag and this module read each other's\n  // writes. Microsoft's ITP answer is this first-party cookie (plus a localStorage backup), but\n  // bat.js writes it through `document.cookie`, which Safari caps at 7 days — 24 hours on a\n  // landing page decorated by a classified domain, and a bing.com ad click is exactly that.\n  // Persisting it here over HTTP on the document response restores the 90-day window.\n  //\n  // The re-issue (default on, see `refresh`) is the same self-heal as for `_fbc`, and it matters\n  // more here: bat.js rewrites this cookie on EVERY page load, so without the re-issue the HTTP\n  // copy is downgraded to a JS cookie on the very next page. There is no embedded timestamp to\n  // compute a remaining lifetime from, so it is re-issued at a fresh 90 days — which is exactly\n  // what bat.js itself does on each page (`msClkIdExpirationTime` from now), so the window\n  // slides no more than the tag already slides it. A value this module cannot parse belongs to\n  // the tag: never rewritten, never deleted.\n  const urlMsclkid = params.get('msclkid')?.trim();\n  const existingMsclkid = parseUetMsclkid(jar[UET_MSCLKID_COOKIE]);\n  if (urlMsclkid && MSCLKID.test(urlMsclkid) && urlMsclkid.toLowerCase() !== existingMsclkid) {\n    set(UET_MSCLKID_COOKIE, formatUetMsclkid(urlMsclkid), MSCLKID_TTL_MS);\n    result.msclkid = urlMsclkid.toLowerCase();\n  } else if (existingMsclkid) {\n    result.msclkid = existingMsclkid;\n    if (refresh) set(UET_MSCLKID_COOKIE, formatUetMsclkid(existingMsclkid), MSCLKID_TTL_MS);\n  }\n\n  return result;\n}\n\n/** Serialize the resolved cookies into `Set-Cookie` header values. */\nexport function toSetCookieHeaders(cookies: SetCookie[]): string[] {\n  return cookies.map((cookie) => stringifySetCookie(cookie));\n}\n"],"mappings":"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"}

package/dist/hooks/use-web-analytics.cjs

@@ -4,6 +4,7 @@ const require_constants_storage = require("../constants/storage.cjs");
 const require_setup_session = require("../setup/session.cjs");
 const require_track_index = require("../track/index.cjs");
 const require_hooks_use_previous = require("./use-previous.cjs");
+const require_web_page_key = require("../web/page-key.cjs");
 let _shware_utils = require("@shware/utils");
 let react = require("react");
 //#region src/hooks/use-web-analytics.ts
@@ -51,13 +52,18 @@ function onVisibilityChange() {
 * 1. send session_start event when the page is loaded
 * 2. send scroll event when the user scrolls more than 90% of the page
 * 3. send user_engagement event when the page is hidden or the user is not focused
+* 4. send page_view when the page changes — path or query, see `getPageKey`; `search` is the
+*    router's query string (`?a=1`, or `''`), required so no caller forgets that the query is
+*    part of what makes a page
 */
-function useWebAnalytics(pathname) {
+function useWebAnalytics(pathname, search) {
+	const page = require_web_page_key.getPageKey(pathname, search);
+	const prevPage = require_hooks_use_previous.usePrevious(page);
 	const prevPathname = require_hooks_use_previous.usePrevious(pathname);
 	const hasSendScroll = (0, react.useRef)(false);
 	(0, react.useEffect)(() => {
 		hasSendScroll.current = false;
-	}, [pathname]);
+	}, [page]);
 	(0, react.useEffect)(() => {
 		const session = require_setup_session.getSession();
 		sendFirstVisit(pathname);
@@ -103,10 +109,10 @@ function useWebAnalytics(pathname) {
 			page_title: document.title,
 			page_referrer: document.referrer,
 			page_location: window.location.href,
-			previous_page_path: prevPathname ?? void 0,
-			engagement_time_msec: prevPathname ? require_setup_session.getSession().flush() : void 0
+			previous_page_path: prevPage === void 0 ? void 0 : prevPathname,
+			engagement_time_msec: prevPage === void 0 ? void 0 : require_setup_session.getSession().flush()
 		});
-	}, [pathname]);
+	}, [page]);
 }
 //#endregion
 exports.useWebAnalytics = useWebAnalytics;