@getvitops/utils 2.1.0 → 4.0.0

package/dist/token-BV7tPHh2.mjs

@@ -0,0 +1,96 @@
+import { createSign } from "node:crypto";
+
+//#region src/google/token.ts
+/**
+* Google OAuth2 token exchange — one request, two grants.
+*
+* Both of this package's Google modules need a bearer token, and both used to
+* mint one themselves. The two copies looked different because the *credentials*
+* differ, but everything after building the form body was identical: same
+* endpoint, same content-type, same "surface the response body as the error"
+* rule, same `access_token` extraction. So the seam is precise —
+* **credential → form params differs, params → token does not.**
+*
+* The two grants are kept because they are not accidental duplication; they track
+* how each command is actually run:
+*
+*   - **service account** (RS256 JWT bearer) for `search notify`, which runs on
+*     every deploy in CI. It never expires. A refresh token can be revoked, and
+*     for an OAuth client still in *Testing* publishing status Google expires it
+*     after 7 days — a bad property for a deploy step.
+*   - **user OAuth** (refresh-token grant) for `search setup`, which is a
+*     one-time human operation. Site verification makes the calling identity an
+*     *owner* of the property, and that should be a person, not a project robot.
+*
+* `googleapis` is deliberately not a dependency — this is one REST endpoint in a
+* CLI that installs into every consumer project. See AGENTS.md.
+*
+* Internal: not a published subpath. Both `./indexing` and `./onboarding` import
+* it, so it lands in a shared chunk, which is free for a Node library. (The
+* "don't create a shared chunk" rule in AGENTS.md is about browser bundles and
+* the consent gate.)
+*/
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const b64url = (input) => Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+/** Sign the RS256 JWT assertion a service-account grant carries. */
+function assertionFor(account, scope, now) {
+	const iat = Math.floor(now / 1e3);
+	const header = b64url(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT"
+	}));
+	const claims = b64url(JSON.stringify({
+		iss: account.client_email,
+		scope,
+		aud: TOKEN_URL,
+		iat,
+		exp: iat + 3600
+	}));
+	const signer = createSign("RSA-SHA256");
+	signer.update(`${header}.${claims}`);
+	const pem = account.private_key.replace(/\\n/g, "\n");
+	return `${header}.${claims}.${b64url(signer.sign(pem))}`;
+}
+/** The half that never differs: POST the grant, surface the cause, return the token. */
+async function requestToken(body, fetchImpl) {
+	const res = await fetchImpl(TOKEN_URL, {
+		method: "POST",
+		headers: { "content-type": "application/x-www-form-urlencoded" },
+		body: body.toString()
+	});
+	if (!res.ok) throw new Error(`token exchange failed (${res.status}): ${await res.text()}`);
+	const { access_token } = await res.json();
+	if (!access_token) throw new Error("token exchange returned no access_token");
+	return access_token;
+}
+/**
+* Exchange either credential for a short-lived access token.
+*
+* Throws rather than returning a result: nothing downstream can run without a
+* token, so there is no per-item decision for a caller to make. (The API calls
+* themselves do return structured results — those fail per domain.)
+*
+* `now` is a parameter so the assertion is testable without mocking the clock.
+*/
+function googleAccessToken(credential, fetchImpl = fetch, now = Date.now()) {
+	return requestToken(credential.kind === "oauth" ? new URLSearchParams({
+		grant_type: "refresh_token",
+		client_id: credential.oauth.clientId,
+		client_secret: credential.oauth.clientSecret,
+		refresh_token: credential.oauth.refreshToken
+	}) : new URLSearchParams({
+		grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+		assertion: assertionFor(credential.account, credential.scope, now)
+	}), fetchImpl);
+}
+/** Scopes, named once so a caller never spells one out. */
+const SCOPES = {
+	/** Search Console (`sitemaps.submit`, `urlInspection`, `sites`). */
+	webmasters: "https://www.googleapis.com/auth/webmasters",
+	/** Site Verification API. */
+	siteVerification: "https://www.googleapis.com/auth/siteverification"
+};
+
+//#endregion
+export { googleAccessToken as n, SCOPES as t };
+//# sourceMappingURL=token-BV7tPHh2.mjs.map

package/dist/token-BV7tPHh2.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-BV7tPHh2.mjs","names":[],"sources":["../src/google/token.ts"],"sourcesContent":["/**\n * Google OAuth2 token exchange — one request, two grants.\n *\n * Both of this package's Google modules need a bearer token, and both used to\n * mint one themselves. The two copies looked different because the *credentials*\n * differ, but everything after building the form body was identical: same\n * endpoint, same content-type, same \"surface the response body as the error\"\n * rule, same `access_token` extraction. So the seam is precise —\n * **credential → form params differs, params → token does not.**\n *\n * The two grants are kept because they are not accidental duplication; they track\n * how each command is actually run:\n *\n *   - **service account** (RS256 JWT bearer) for `search notify`, which runs on\n *     every deploy in CI. It never expires. A refresh token can be revoked, and\n *     for an OAuth client still in *Testing* publishing status Google expires it\n *     after 7 days — a bad property for a deploy step.\n *   - **user OAuth** (refresh-token grant) for `search setup`, which is a\n *     one-time human operation. Site verification makes the calling identity an\n *     *owner* of the property, and that should be a person, not a project robot.\n *\n * `googleapis` is deliberately not a dependency — this is one REST endpoint in a\n * CLI that installs into every consumer project. See AGENTS.md.\n *\n * Internal: not a published subpath. Both `./indexing` and `./onboarding` import\n * it, so it lands in a shared chunk, which is free for a Node library. (The\n * \"don't create a shared chunk\" rule in AGENTS.md is about browser bundles and\n * the consent gate.)\n */\nimport { createSign } from 'node:crypto';\n\nconst TOKEN_URL = 'https://oauth2.googleapis.com/token';\n\n/** The fields we need from a service-account JSON key. */\nexport interface ServiceAccount {\n  client_email: string;\n  private_key: string;\n}\n\n/** A user OAuth credential (refresh-token flow — never a service account). */\nexport interface GoogleOAuth {\n  clientId: string;\n  clientSecret: string;\n  refreshToken: string;\n}\n\n/**\n * Which identity to act as.\n *\n * `scope` rides on the service-account variant because that grant carries its\n * scope in the signed assertion. A user OAuth token's scopes are fixed when the\n * refresh token is minted, so there is nothing to pass at exchange time — the\n * asymmetry is the protocol's, not ours.\n */\nexport type GoogleCredential =\n  | { kind: 'service-account'; account: ServiceAccount; scope: string }\n  | { kind: 'oauth'; oauth: GoogleOAuth };\n\nconst b64url = (input: Buffer | string): string =>\n  Buffer.from(input).toString('base64').replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n\n/** Sign the RS256 JWT assertion a service-account grant carries. */\nfunction assertionFor(account: ServiceAccount, scope: string, now: number): string {\n  const iat = Math.floor(now / 1000);\n  const header = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));\n  const claims = b64url(\n    JSON.stringify({ iss: account.client_email, scope, aud: TOKEN_URL, iat, exp: iat + 3600 }),\n  );\n  const signer = createSign('RSA-SHA256');\n  signer.update(`${header}.${claims}`);\n  // `\\n` survives most secret stores as a literal; normalise so a pasted key works.\n  const pem = account.private_key.replace(/\\\\n/g, '\\n');\n  return `${header}.${claims}.${b64url(signer.sign(pem))}`;\n}\n\n/** The half that never differs: POST the grant, surface the cause, return the token. */\nasync function requestToken(body: URLSearchParams, fetchImpl: typeof fetch): Promise<string> {\n  const res = await fetchImpl(TOKEN_URL, {\n    method: 'POST',\n    headers: { 'content-type': 'application/x-www-form-urlencoded' },\n    body: body.toString(),\n  });\n  if (!res.ok) {\n    // The body names the cause — clock skew, wrong audience or a revoked key for a\n    // service account; `invalid_grant` / `invalid_client` for OAuth — and carries\n    // no secret of ours: the assertion travels in the request, not the response.\n    throw new Error(`token exchange failed (${res.status}): ${await res.text()}`);\n  }\n  const { access_token } = (await res.json()) as { access_token?: string };\n  if (!access_token) throw new Error('token exchange returned no access_token');\n  return access_token;\n}\n\n/**\n * Exchange either credential for a short-lived access token.\n *\n * Throws rather than returning a result: nothing downstream can run without a\n * token, so there is no per-item decision for a caller to make. (The API calls\n * themselves do return structured results — those fail per domain.)\n *\n * `now` is a parameter so the assertion is testable without mocking the clock.\n */\nexport function googleAccessToken(\n  credential: GoogleCredential,\n  fetchImpl: typeof fetch = fetch,\n  now: number = Date.now(),\n): Promise<string> {\n  const body =\n    credential.kind === 'oauth'\n      ? new URLSearchParams({\n          grant_type: 'refresh_token',\n          client_id: credential.oauth.clientId,\n          client_secret: credential.oauth.clientSecret,\n          refresh_token: credential.oauth.refreshToken,\n        })\n      : new URLSearchParams({\n          grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',\n          assertion: assertionFor(credential.account, credential.scope, now),\n        });\n  return requestToken(body, fetchImpl);\n}\n\n/** Scopes, named once so a caller never spells one out. */\nexport const SCOPES = {\n  /** Search Console (`sitemaps.submit`, `urlInspection`, `sites`). */\n  webmasters: 'https://www.googleapis.com/auth/webmasters',\n  /** Site Verification API. */\n  siteVerification: 'https://www.googleapis.com/auth/siteverification',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAM,YAAY;AA2BlB,MAAM,UAAU,UACd,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,OAAO,GAAG,CAAC,CAAC,QAAQ,OAAO,EAAE;;AAGjG,SAAS,aAAa,SAAyB,OAAe,KAAqB;CACjF,MAAM,MAAM,KAAK,MAAM,MAAM,GAAI;CACjC,MAAM,SAAS,OAAO,KAAK,UAAU;EAAE,KAAK;EAAS,KAAK;CAAM,CAAC,CAAC;CAClE,MAAM,SAAS,OACb,KAAK,UAAU;EAAE,KAAK,QAAQ;EAAc;EAAO,KAAK;EAAW;EAAK,KAAK,MAAM;CAAK,CAAC,CAC3F;CACA,MAAM,SAAS,WAAW,YAAY;CACtC,OAAO,OAAO,GAAG,OAAO,GAAG,QAAQ;CAEnC,MAAM,MAAM,QAAQ,YAAY,QAAQ,QAAQ,IAAI;CACpD,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,OAAO,KAAK,GAAG,CAAC;AACvD;;AAGA,eAAe,aAAa,MAAuB,WAA0C;CAC3F,MAAM,MAAM,MAAM,UAAU,WAAW;EACrC,QAAQ;EACR,SAAS,EAAE,gBAAgB,oCAAoC;EAC/D,MAAM,KAAK,SAAS;CACtB,CAAC;CACD,IAAI,CAAC,IAAI,IAIP,MAAM,IAAI,MAAM,0BAA0B,IAAI,OAAO,KAAK,MAAM,IAAI,KAAK,GAAG;CAE9E,MAAM,EAAE,iBAAkB,MAAM,IAAI,KAAK;CACzC,IAAI,CAAC,cAAc,MAAM,IAAI,MAAM,yCAAyC;CAC5E,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,kBACd,YACA,YAA0B,OAC1B,MAAc,KAAK,IAAI,GACN;CAajB,OAAO,aAXL,WAAW,SAAS,UAChB,IAAI,gBAAgB;EAClB,YAAY;EACZ,WAAW,WAAW,MAAM;EAC5B,eAAe,WAAW,MAAM;EAChC,eAAe,WAAW,MAAM;CAClC,CAAC,IACD,IAAI,gBAAgB;EAClB,YAAY;EACZ,WAAW,aAAa,WAAW,SAAS,WAAW,OAAO,GAAG;CACnE,CAAC,GACmB,SAAS;AACrC;;AAGA,MAAa,SAAS;;CAEpB,YAAY;;CAEZ,kBAAkB;AACpB"}

package/dist/tracking/index.d.mts

@@ -0,0 +1,88 @@
+import { i as TrackingData, n as TrackingCategory, r as TrackingConfig, t as ConversionEvent } from "../types-C3lHaSrU.mjs";
+
+//#region src/tracking/params.d.ts
+/**
+ * The ad-platform vocabulary — the one place that says which URL parameters mean
+ * "this visit came from an ad", and which platform each belongs to.
+ *
+ * Single source of truth on purpose: the capture script reads it to know what to
+ * pull off the URL, and the notification renderer reads it to name the platform.
+ * Two lists would drift into a cookie holding a click ID nothing can attribute.
+ */
+/**
+ * Click-ID parameters, in identification precedence.
+ *
+ * Order matters: `identifyPlatform` and `getPrimaryClickId` return the first
+ * match, and a URL can legitimately carry more than one (a Google Ads link
+ * retargeted through Meta arrives with both `gclid` and `fbclid`). Google first
+ * because its click IDs are the ones that survive redirects intact.
+ */
+declare const PLATFORM_PARAMS: Readonly<Record<string, string>>;
+/** Just the parameter names, in the same precedence order. */
+declare const CLICK_ID_PARAMS: readonly string[];
+declare const UTM_PARAMS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"];
+/** Everything the capture script pulls off the landing URL. */
+declare const TRACKED_PARAMS: readonly string[];
+/**
+ * The attribution cookie.
+ *
+ * First-party and same-site: it is read by this site's own conversion handler and
+ * never sent anywhere. It is still a persistent identifier, which is why writing
+ * it waits on consent.
+ */
+declare const TRACKING_COOKIE = "_ac";
+/** 90 days — an ad click and the conversion it produces are rarely further apart. */
+declare const TRACKING_COOKIE_DAYS = 90;
+/** The A/B variant cookie, assigned by the router when a site runs experiments. */
+declare const AB_COOKIE = "_ab";
+//#endregion
+//#region src/tracking/cookie.d.ts
+/** Read one cookie out of a `document.cookie`-shaped string. */
+declare function readCookie(cookieString: string | null | undefined, name: string): string | null;
+/**
+ * Cookie header → attribution, or `null`.
+ *
+ * Anything unparseable reads as `null` — no attribution — rather than as a
+ * partial record. A half-read cookie would attribute a conversion to whichever
+ * fields happened to survive, which is worse than reporting it unattributed:
+ * "we don't know" is actionable, a wrong campaign is not.
+ */
+declare function parseTrackingCookie(cookieHeader: string | null | undefined): TrackingData | null;
+/** Attribution → cookie value (not the full `Set-Cookie` — see `cookieAttributes`). */
+declare function serializeTrackingCookie(data: TrackingData): string;
+/**
+ * Attributes for the attribution cookie.
+ *
+ * `SameSite=Lax` rather than `Strict`: the visitor arrives here by following a
+ * link from the ad platform, and `Strict` withholds the cookie on exactly that
+ * cross-site navigation — so a returning click would read as a fresh one. No
+ * `HttpOnly`, because the capture script has to write it from the page.
+ */
+declare function cookieAttributes(now: number, secure: boolean): string;
+/**
+ * Fold a fresh capture into whatever was already stored.
+ *
+ * New values win, but `ts` is the **first** capture's — it dates the visitor's
+ * original arrival, which is what a 90-day attribution window is measured from.
+ * Taking the latest would restart the window on every visit and make the cookie
+ * outlive the click it represents.
+ */
+declare function mergeTracking(existing: TrackingData | null, captured: TrackingData, now: number): TrackingData;
+//#endregion
+//#region src/tracking/platform.d.ts
+/**
+ * Which platform sent this visitor.
+ *
+ * Falls back to `utm_source` when no click ID is present: a UTM-tagged link from
+ * a newsletter or a partner site is still attribution, just self-declared rather
+ * than platform-issued. Returns null when there is nothing to go on.
+ */
+declare function identifyPlatform(data: TrackingData): string | null;
+/** The click ID to quote, with the parameter it came from. */
+declare function getPrimaryClickId(data: TrackingData): {
+  param: string;
+  value: string;
+} | null;
+//#endregion
+export { AB_COOKIE, CLICK_ID_PARAMS, type ConversionEvent, PLATFORM_PARAMS, TRACKED_PARAMS, TRACKING_COOKIE, TRACKING_COOKIE_DAYS, type TrackingCategory, type TrackingConfig, type TrackingData, UTM_PARAMS, cookieAttributes, getPrimaryClickId, identifyPlatform, mergeTracking, parseTrackingCookie, readCookie, serializeTrackingCookie };
+//# sourceMappingURL=index.d.mts.map

package/dist/tracking/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/tracking/params.ts","../../src/tracking/cookie.ts","../../src/tracking/platform.ts"],"mappings":";;;;;;AAiBA;;;;AAA6C;AAY7C;;;;AAA8E;AAE9E;;;AAFA,cAZa,eAAA,EAAiB,QAAQ,CAAC,MAAA;AAoB7B;AAAA,cARG,eAAA;AAAA,cAEA,UAAA;;cASA,cAAA;AAAuE;AASpF;;;;AAA4B;AAG5B;AAZoF,cASvE,eAAA;;cAGA,oBAAA;AAAoB;AAAA,cAGpB,SAAA;;;;iBCxCG,UAAA,CAAW,YAAA,6BAAyC,IAAY;ADEhF;;;;AAA6C;AAY7C;;;AAZA,iBCegB,mBAAA,CAAoB,YAAA,8BAA0C,YAAY;ADHZ;AAAA,iBCgB9D,uBAAA,CAAwB,IAAkB,EAAZ,YAAY;;;;ADRhD;AAGV;;;;iBCoBgB,gBAAA,CAAiB,GAAA,UAAa,MAAe;ADX7D;;;;AAA4B;AAG5B;;;AAHA,iBCwBgB,aAAA,CACd,QAAA,EAAU,YAAA,SACV,QAAA,EAAU,YAAA,EACV,GAAA,WACC,YAAA;;;;;AD5DH;;;;AAA6C;iBEC7B,gBAAA,CAAiB,IAAkB,EAAZ,YAAY;;iBASnC,iBAAA,CAAkB,IAAA,EAAM,YAAY;EAAK,KAAA;EAAe,KAAA;AAAA"}

package/dist/tracking/index.mjs

@@ -0,0 +1,77 @@
+import { a as PLATFORM_PARAMS, c as TRACKING_COOKIE_DAYS, i as CLICK_ID_PARAMS, l as UTM_PARAMS, n as identifyPlatform, o as TRACKED_PARAMS, r as AB_COOKIE, s as TRACKING_COOKIE, t as getPrimaryClickId } from "../platform-CIdwwI_Z.mjs";
+
+//#region src/tracking/cookie.ts
+/**
+* Reading and writing the `_ac` cookie, as functions over a cookie **string**.
+*
+* String in, string out, so one implementation serves both ends: the browser
+* passes `document.cookie`, the conversion handler passes the request's `Cookie`
+* header. A separate server-side parser would be a second thing to keep in step
+* with the writer, and the failure — attribution silently absent from a
+* notification — looks identical to a visitor who arrived organically.
+*
+* The same shape, for the same reason, as `@getvitops/core`'s consent store.
+*/
+/** Read one cookie out of a `document.cookie`-shaped string. */
+function readCookie(cookieString, name) {
+	if (!cookieString) return null;
+	for (const part of cookieString.split(";")) {
+		const raw = part.trim();
+		if (raw.slice(0, name.length + 1) === `${name}=`) return raw.slice(name.length + 1);
+	}
+	return null;
+}
+/**
+* Cookie header → attribution, or `null`.
+*
+* Anything unparseable reads as `null` — no attribution — rather than as a
+* partial record. A half-read cookie would attribute a conversion to whichever
+* fields happened to survive, which is worse than reporting it unattributed:
+* "we don't know" is actionable, a wrong campaign is not.
+*/
+function parseTrackingCookie(cookieHeader) {
+	const raw = readCookie(cookieHeader, "_ac");
+	if (!raw) return null;
+	try {
+		const data = JSON.parse(decodeURIComponent(raw));
+		if (typeof data !== "object" || data === null || Array.isArray(data)) return null;
+		return data;
+	} catch {
+		return null;
+	}
+}
+/** Attribution → cookie value (not the full `Set-Cookie` — see `cookieAttributes`). */
+function serializeTrackingCookie(data) {
+	const clean = Object.fromEntries(Object.entries(data).filter(([, v]) => v !== void 0));
+	return encodeURIComponent(JSON.stringify(clean));
+}
+/**
+* Attributes for the attribution cookie.
+*
+* `SameSite=Lax` rather than `Strict`: the visitor arrives here by following a
+* link from the ad platform, and `Strict` withholds the cookie on exactly that
+* cross-site navigation — so a returning click would read as a fresh one. No
+* `HttpOnly`, because the capture script has to write it from the page.
+*/
+function cookieAttributes(now, secure) {
+	return `;expires=${new Date(now + 90 * 864e5).toUTCString()};path=/;SameSite=Lax${secure ? ";Secure" : ""}`;
+}
+/**
+* Fold a fresh capture into whatever was already stored.
+*
+* New values win, but `ts` is the **first** capture's — it dates the visitor's
+* original arrival, which is what a 90-day attribution window is measured from.
+* Taking the latest would restart the window on every visit and make the cookie
+* outlive the click it represents.
+*/
+function mergeTracking(existing, captured, now) {
+	return {
+		...existing,
+		...captured,
+		ts: existing?.ts ?? now
+	};
+}
+
+//#endregion
+export { AB_COOKIE, CLICK_ID_PARAMS, PLATFORM_PARAMS, TRACKED_PARAMS, TRACKING_COOKIE, TRACKING_COOKIE_DAYS, UTM_PARAMS, cookieAttributes, getPrimaryClickId, identifyPlatform, mergeTracking, parseTrackingCookie, readCookie, serializeTrackingCookie };
+//# sourceMappingURL=index.mjs.map

package/dist/tracking/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/tracking/cookie.ts"],"sourcesContent":["/**\n * Reading and writing the `_ac` cookie, as functions over a cookie **string**.\n *\n * String in, string out, so one implementation serves both ends: the browser\n * passes `document.cookie`, the conversion handler passes the request's `Cookie`\n * header. A separate server-side parser would be a second thing to keep in step\n * with the writer, and the failure — attribution silently absent from a\n * notification — looks identical to a visitor who arrived organically.\n *\n * The same shape, for the same reason, as `@getvitops/core`'s consent store.\n */\nimport { TRACKING_COOKIE, TRACKING_COOKIE_DAYS } from './params.ts';\nimport type { TrackingData } from './types.ts';\n\n/** Read one cookie out of a `document.cookie`-shaped string. */\nexport function readCookie(cookieString: string | null | undefined, name: string): string | null {\n  if (!cookieString) return null;\n  for (const part of cookieString.split(';')) {\n    const raw = part.trim();\n    if (raw.slice(0, name.length + 1) === `${name}=`) return raw.slice(name.length + 1);\n  }\n  return null;\n}\n\n/**\n * Cookie header → attribution, or `null`.\n *\n * Anything unparseable reads as `null` — no attribution — rather than as a\n * partial record. A half-read cookie would attribute a conversion to whichever\n * fields happened to survive, which is worse than reporting it unattributed:\n * \"we don't know\" is actionable, a wrong campaign is not.\n */\nexport function parseTrackingCookie(cookieHeader: string | null | undefined): TrackingData | null {\n  const raw = readCookie(cookieHeader, TRACKING_COOKIE);\n  if (!raw) return null;\n  try {\n    const data: unknown = JSON.parse(decodeURIComponent(raw));\n    if (typeof data !== 'object' || data === null || Array.isArray(data)) return null;\n    return data as TrackingData;\n  } catch {\n    return null;\n  }\n}\n\n/** Attribution → cookie value (not the full `Set-Cookie` — see `cookieAttributes`). */\nexport function serializeTrackingCookie(data: TrackingData): string {\n  // Undefined values would serialize as absent keys anyway; dropping them first\n  // keeps the cookie small and the round-trip exact.\n  const clean = Object.fromEntries(Object.entries(data).filter(([, v]) => v !== undefined));\n  return encodeURIComponent(JSON.stringify(clean));\n}\n\n/**\n * Attributes for the attribution cookie.\n *\n * `SameSite=Lax` rather than `Strict`: the visitor arrives here by following a\n * link from the ad platform, and `Strict` withholds the cookie on exactly that\n * cross-site navigation — so a returning click would read as a fresh one. No\n * `HttpOnly`, because the capture script has to write it from the page.\n */\nexport function cookieAttributes(now: number, secure: boolean): string {\n  const expires = new Date(now + TRACKING_COOKIE_DAYS * 864e5).toUTCString();\n  return `;expires=${expires};path=/;SameSite=Lax${secure ? ';Secure' : ''}`;\n}\n\n/**\n * Fold a fresh capture into whatever was already stored.\n *\n * New values win, but `ts` is the **first** capture's — it dates the visitor's\n * original arrival, which is what a 90-day attribution window is measured from.\n * Taking the latest would restart the window on every visit and make the cookie\n * outlive the click it represents.\n */\nexport function mergeTracking(\n  existing: TrackingData | null,\n  captured: TrackingData,\n  now: number,\n): TrackingData {\n  return { ...existing, ...captured, ts: existing?.ts ?? now };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,SAAgB,WAAW,cAAyC,MAA6B;CAC/F,IAAI,CAAC,cAAc,OAAO;CAC1B,KAAK,MAAM,QAAQ,aAAa,MAAM,GAAG,GAAG;EAC1C,MAAM,MAAM,KAAK,KAAK;EACtB,IAAI,IAAI,MAAM,GAAG,KAAK,SAAS,CAAC,MAAM,GAAG,KAAK,IAAI,OAAO,IAAI,MAAM,KAAK,SAAS,CAAC;CACpF;CACA,OAAO;AACT;;;;;;;;;AAUA,SAAgB,oBAAoB,cAA8D;CAChG,MAAM,MAAM,WAAW,mBAA6B;CACpD,IAAI,CAAC,KAAK,OAAO;CACjB,IAAI;EACF,MAAM,OAAgB,KAAK,MAAM,mBAAmB,GAAG,CAAC;EACxD,IAAI,OAAO,SAAS,YAAY,SAAS,QAAQ,MAAM,QAAQ,IAAI,GAAG,OAAO;EAC7E,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,SAAgB,wBAAwB,MAA4B;CAGlE,MAAM,QAAQ,OAAO,YAAY,OAAO,QAAQ,IAAI,CAAC,CAAC,QAAQ,GAAG,OAAO,MAAM,MAAS,CAAC;CACxF,OAAO,mBAAmB,KAAK,UAAU,KAAK,CAAC;AACjD;;;;;;;;;AAUA,SAAgB,iBAAiB,KAAa,QAAyB;CAErE,OAAO,YADS,IAAI,KAAK,WAA6B,KAAK,CAAC,CAAC,YACpC,EAAE,sBAAsB,SAAS,YAAY;AACxE;;;;;;;;;AAUA,SAAgB,cACd,UACA,UACA,KACc;CACd,OAAO;EAAE,GAAG;EAAU,GAAG;EAAU,IAAI,UAAU,MAAM;CAAI;AAC7D"}

package/dist/types-C3lHaSrU.d.mts

@@ -0,0 +1,69 @@
+//#region src/tracking/types.d.ts
+/**
+ * The tracking module's own option surface.
+ *
+ * Deliberately structural rather than `Config['site']['tracking']` imported from
+ * `@getvitops/generator`: the generator already depends on this package, so
+ * importing back would be a cycle. The vocabulary mirrors that block field for
+ * field — the same arrangement, and for the same reason, as `IndexingConfig`.
+ */
+/** Which consent category the `_ac` cookie waits on. */
+type TrackingCategory = 'marketing' | 'analytics';
+interface TrackingConfig {
+  enabled?: boolean | undefined;
+  /**
+   * Default `marketing`. `_ac` is a 90-day identifier tying a visitor to the ad
+   * that brought them, which is what advertising consent covers — but a site
+   * using click IDs purely for its own campaign reporting may reasonably file it
+   * under `analytics`, so this is stated rather than assumed.
+   */
+  category?: TrackingCategory | undefined;
+  platforms?: string[] | undefined;
+}
+/**
+ * What the `_ac` cookie holds: where a visitor came from, captured once on the
+ * landing page and carried until it expires.
+ *
+ * Click-ID and UTM keys are indexed rather than enumerated because the platform
+ * table is the source of truth for which are recognised — enumerating them here
+ * would be a second list to keep in step.
+ */
+interface TrackingData {
+  [param: string]: string | number | undefined;
+  /** Path of the page the visitor first landed on. */
+  landingPage?: string | undefined;
+  /** `document.referrer` at capture, when there was one. */
+  referrer?: string | undefined;
+  /** Epoch ms of first capture. Preserved across later captures. */
+  ts?: number | undefined;
+  /** A/B variant assigned by the router, when the site runs one. */
+  ab_variant?: string | undefined;
+}
+/**
+ * A conversion, as a fact — the thing every notification channel renders.
+ *
+ * This is the module's load-bearing abstraction. The event says *what happened*;
+ * how it reads is the channel's business, so an SMS channel can render 160
+ * characters from the same event an email renders in full without a second source
+ * of truth. It is the rule the legal templates already follow: the config records
+ * facts, the template owns prose.
+ *
+ * `at` is passed in rather than read from a clock, so `plan`/`render` stay pure
+ * and their tests need no fake timers.
+ */
+interface ConversionEvent {
+  type: 'form' | 'call';
+  /** Submitted fields, for `type: 'form'`. Honeypots are stripped before this. */
+  formData?: Record<string, string> | undefined;
+  /** The dialled number, for `type: 'call'`. */
+  phone?: string | undefined;
+  /** Attribution from the `_ac` cookie, or null when the visitor arrived cold. */
+  tracking: TrackingData | null;
+  userAgent?: string | undefined;
+  ip?: string | undefined;
+  /** Epoch ms. */
+  at: number;
+}
+//#endregion
+export { TrackingData as i, TrackingCategory as n, TrackingConfig as r, ConversionEvent as t };
+//# sourceMappingURL=types-C3lHaSrU.d.mts.map

package/dist/types-C3lHaSrU.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-C3lHaSrU.d.mts","names":[],"sources":["../src/tracking/types.ts"],"mappings":";;AAiBA;;;;AAA4B;AAE5B;;;KAFY,gBAAA;AAAA,UAEK,cAAA;EACf,OAAA;EAOW;;;AACF;AAWX;;EAZE,QAAA,GAAW,gBAAgB;EAC3B,SAAA;AAAA;;;;;;AAoBU;AAeZ;;UAxBiB,YAAA;EAAA,CACd,KAAA;EAwBD;EAtBA,WAAA;EAwBW;EAtBX,QAAA;EA0BA;EAxBA,EAAA;EAyBA;EAvBA,UAAA;AAAA;;AA0BE;;;;;;;;;;;UAXa,eAAA;EACf,IAAA;;EAEA,QAAA,GAAW,MAAA;;EAEX,KAAA;;EAEA,QAAA,EAAU,YAAY;EACtB,SAAA;EACA,EAAA;;EAEA,EAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/utils",
-  "version": "2.1.0",
+  "version": "4.0.0",
   "description": "Shared build-time utilities for the Vitops toolchain — favicon generation and friends.",
   "license": "MIT",
   "files": [
@@ -26,9 +26,21 @@
       "types": "./dist/indexing/index.d.mts",
       "import": "./dist/indexing/index.mjs"
     },
+    "./onboarding": {
+      "types": "./dist/onboarding/index.d.mts",
+      "import": "./dist/onboarding/index.mjs"
+    },
     "./media": {
       "types": "./dist/media/index.d.mts",
       "import": "./dist/media/index.mjs"
+    },
+    "./notify": {
+      "types": "./dist/notify/index.d.mts",
+      "import": "./dist/notify/index.mjs"
+    },
+    "./tracking": {
+      "types": "./dist/tracking/index.d.mts",
+      "import": "./dist/tracking/index.mjs"
     }
   },
   "publishConfig": {