@reblu/site-client 5.21.0 → 5.22.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @reblu/site-client
 
+## 5.22.0
+
+### Minor Changes
+
+- 53d5b0e: Lead origin captured in the browser (REB-1366). `@reblu/site-client` adds `leadTouchFromVisit()`, `createLeadAttributionStore()` and the shared `getLeadAttributionStore()`: on each full page load the visit's raw touch (the `utm_*` params, the NAMES of ad click ids, the external referrer's host, the landing path) is kept as the first touch and, unless it is direct, as the last touch. Memory only until the visitor grants the `analytics` cookie category; then a 90-day first-party cookie, `reblu_attribution`, removed again when consent is denied or withdrawn. `buildContactFormMetadata()` now adds `metadata.attribution` when the page recorded a touch (omitted otherwise, so its output is unchanged for a SITE that does not capture); pass `attribution: null` to send none. base-api classifies the channel. `@reblu/site-next/consent` adds the drop-in `<LeadAttributionCapture />`: mount it once inside `<ConsentProvider>`. Additive only: nothing existing changes. List the `reblu_attribution` cookie (analytics, 90 days) in the tenant's cookie policy.
+
 ## 5.21.0
 
 ### Minor Changes

package/README.md

@@ -451,6 +451,23 @@ await fetch('/api/contact-form', {
 buildContactFormMetadata({ fromPage: '/landing/verano', leadSource: { platform: 'instagram' } })
 ```
 
+`metadata.attribution` (REB-1366) is added when the page recorded where the
+visitor came from: mount `<LeadAttributionCapture />` from
+`@reblu/site-next/consent` once inside `<ConsentProvider>` (see that README).
+The touches live in `getLeadAttributionStore()` — in memory before the
+visitor grants the `analytics` cookie category, in the 90-day first-party
+cookie `reblu_attribution` after. Without a capture the key is omitted and
+base-api reads the UTMs from `currentUrl` as before. A SITE without React
+records the visit itself:
+
+```ts
+import { getLeadAttributionStore } from '@reblu/site-client'
+
+const store = getLeadAttributionStore()
+store.recordVisit() // once per full page load
+store.setConsent(visitorAcceptedAnalytics) // whenever the choice is known or changes
+```
+
 Do not hardcode `fromPage` (e.g. `'home'`): every lead would then report the
 same page. base-api still accepts such a value and falls back to the path of
 `currentUrl`. `currentPagePath()` returns just the path, for a SITE that builds

package/dist/index.cjs

@@ -724,6 +724,214 @@ function makeWithdrawalRequestsNamespace(ctx) {
   };
 }
 
+// src/lead-attribution.ts
+var LEAD_ATTRIBUTION_COOKIE_NAME = "reblu_attribution";
+var LEAD_ATTRIBUTION_MAX_AGE_SECONDS = 90 * 24 * 60 * 60;
+var LEAD_ATTRIBUTION_CLICK_IDS = [
+  "gclid",
+  "gbraid",
+  "wbraid",
+  "dclid",
+  "msclkid",
+  "ttclid",
+  "li_fat_id",
+  "fbclid"
+];
+var UTM_KEYS = ["source", "medium", "campaign", "content", "term"];
+var VALUE_MAX_LENGTH = 100;
+var PATH_MAX_LENGTH = 200;
+var SHAPE_VERSION = 1;
+var CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+var HOST = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/;
+var IGNORED_HOSTS = [
+  "checkout.stripe.com",
+  "billing.stripe.com",
+  "paypal.com",
+  "accounts.google.com"
+];
+function cleanValue(value, max = VALUE_MAX_LENGTH) {
+  if (typeof value !== "string" || CONTROL_CHARS.test(value)) return void 0;
+  const clean = value.trim().slice(0, max);
+  return clean && !clean.includes("@") ? clean : void 0;
+}
+function cleanHost(value) {
+  const host = cleanValue(value)?.toLowerCase();
+  return host && HOST.test(host) ? host : void 0;
+}
+function cleanPath(value) {
+  const path = cleanValue(value, PATH_MAX_LENGTH)?.split(/[?#]/, 1)[0];
+  return path && path.startsWith("/") && !path.startsWith("//") ? path : void 0;
+}
+function cleanAt(value) {
+  return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? value : void 0;
+}
+var withoutWww = (host) => host.replace(/^www\./, "");
+var matchesDomain = (host, domain) => host === domain || host.endsWith(`.${domain}`);
+function sanitizeTouch(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return void 0;
+  const input = raw;
+  const touch = {};
+  const rawUtm = input.utm;
+  if (typeof rawUtm === "object" && rawUtm !== null) {
+    const utm = {};
+    for (const key of UTM_KEYS) {
+      const value = cleanValue(rawUtm[key]);
+      if (value) utm[key] = value;
+    }
+    if (Object.keys(utm).length > 0) touch.utm = utm;
+  }
+  const rawClickIds = input.clickIds;
+  if (Array.isArray(rawClickIds)) {
+    const known = LEAD_ATTRIBUTION_CLICK_IDS.filter((id) => rawClickIds.includes(id));
+    if (known.length > 0) touch.clickIds = known;
+  }
+  const referrer = cleanHost(input.referrer);
+  if (referrer) touch.referrer = referrer;
+  const landingPath = cleanPath(input.landingPath);
+  if (landingPath) touch.landingPath = landingPath;
+  const at = cleanAt(input.at);
+  if (at) touch.at = at;
+  return Object.keys(touch).length > 0 ? touch : void 0;
+}
+function isDirect(touch) {
+  return !touch.utm && !touch.clickIds && !touch.referrer;
+}
+function leadTouchFromVisit(visit = {}) {
+  const g = globalThis;
+  const href = visit.href ?? g.location?.href;
+  const referrer = visit.referrer === void 0 ? g.document?.referrer : visit.referrer;
+  let url;
+  try {
+    url = new URL(href ?? "");
+  } catch {
+    return null;
+  }
+  const raw = {};
+  const utm = {};
+  for (const key of UTM_KEYS) {
+    const value = url.searchParams.get(`utm_${key}`);
+    if (value) utm[key] = value;
+  }
+  if (Object.keys(utm).length > 0) raw.utm = utm;
+  const clickIds = LEAD_ATTRIBUTION_CLICK_IDS.filter((id) => url.searchParams.has(id));
+  if (clickIds.length > 0) raw.clickIds = clickIds;
+  let referrerHost;
+  try {
+    referrerHost = referrer ? new URL(referrer).hostname.toLowerCase() : void 0;
+  } catch {
+  }
+  const ownHost = withoutWww(url.hostname.toLowerCase());
+  const external = referrerHost && withoutWww(referrerHost) !== ownHost && !IGNORED_HOSTS.some((domain) => matchesDomain(referrerHost, domain));
+  if (external) raw.referrer = referrerHost;
+  if (referrerHost && !external && !raw.utm && !raw.clickIds) return null;
+  raw.landingPath = url.pathname;
+  raw.at = (visit.now ?? /* @__PURE__ */ new Date()).toISOString();
+  return sanitizeTouch(raw) ?? null;
+}
+function documentCookieJar() {
+  const doc = globalThis.document;
+  if (!doc) return null;
+  const name = LEAD_ATTRIBUTION_COOKIE_NAME;
+  return {
+    read() {
+      const match = doc.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
+      if (!match) return null;
+      try {
+        return decodeURIComponent(match[1]);
+      } catch {
+        return null;
+      }
+    },
+    write(value, maxAgeSeconds) {
+      const https = globalThis.location?.protocol === "https:";
+      doc.cookie = `${name}=${encodeURIComponent(value)}; path=/; max-age=${maxAgeSeconds}; SameSite=Lax${https ? "; Secure" : ""}`;
+    },
+    remove() {
+      doc.cookie = `${name}=; path=/; max-age=0; SameSite=Lax`;
+    }
+  };
+}
+var atOf = (touch) => touch?.at ? Date.parse(touch.at) : Number.NaN;
+function createLeadAttributionStore(options = {}) {
+  const cookies = options.cookies === void 0 ? documentCookieJar() : options.cookies;
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  let first;
+  let last;
+  let granted = false;
+  const fresh = (touch) => {
+    const at = atOf(touch);
+    return touch && now().getTime() - at < LEAD_ATTRIBUTION_MAX_AGE_SECONDS * 1e3 ? touch : void 0;
+  };
+  const persist = () => {
+    if (!granted || !cookies) return;
+    const state = { v: SHAPE_VERSION, first: fresh(first), last: fresh(last) };
+    try {
+      if (state.first || state.last) {
+        cookies.write(JSON.stringify(state), LEAD_ATTRIBUTION_MAX_AGE_SECONDS);
+      } else {
+        cookies.remove();
+      }
+    } catch {
+    }
+  };
+  const loadStored = () => {
+    let stored;
+    try {
+      const raw = cookies?.read();
+      const parsed = raw ? JSON.parse(raw) : void 0;
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        stored = parsed;
+      }
+    } catch {
+    }
+    const storedFirst = fresh(sanitizeTouch(stored?.first));
+    const storedLast = fresh(sanitizeTouch(stored?.last));
+    if (storedFirst && !(atOf(first) < atOf(storedFirst))) first = storedFirst;
+    if (storedLast && !(atOf(last) > atOf(storedLast))) last = storedLast;
+  };
+  const store = {
+    recordVisit(visit) {
+      store.record(leadTouchFromVisit(visit));
+    },
+    record(touch) {
+      if (!touch) return;
+      if (!fresh(first)) first = touch;
+      if (!isDirect(touch)) last = touch;
+      persist();
+    },
+    setConsent(next) {
+      granted = next;
+      if (!cookies) return;
+      if (granted) {
+        loadStored();
+        persist();
+      } else {
+        try {
+          cookies.remove();
+        } catch {
+        }
+      }
+    },
+    get() {
+      const f = fresh(first);
+      const l = fresh(last);
+      if (!f && !l) return void 0;
+      return { ...f && { first: f }, ...l && { last: l } };
+    }
+  };
+  return store;
+}
+var GLOBAL_KEY = "__rebluLeadAttributionStore";
+function getLeadAttributionStore() {
+  const g = globalThis;
+  if (typeof g.window === "undefined") return createLeadAttributionStore({ cookies: null });
+  g[GLOBAL_KEY] ??= createLeadAttributionStore();
+  return g[GLOBAL_KEY];
+}
+function resetLeadAttributionStore() {
+  delete globalThis[GLOBAL_KEY];
+}
+
 // src/contact-form-metadata.ts
 function browserLocation() {
   const location = globalThis.location;
@@ -735,11 +943,13 @@ function currentPagePath(location = browserLocation()) {
 }
 function buildContactFormMetadata(options = {}) {
   const location = options.location === void 0 ? browserLocation() : options.location;
+  const attribution = options.attribution === void 0 ? getLeadAttributionStore().get() : options.attribution;
   return {
     fromPage: options.fromPage ?? currentPagePath(location),
     timestamp: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
     currentUrl: location?.href ?? "",
-    leadSource: options.leadSource ?? { platform: "organic" }
+    leadSource: options.leadSource ?? { platform: "organic" },
+    ...attribution && { attribution }
   };
 }
 
@@ -781,14 +991,21 @@ exports.AcademyCheckoutError = AcademyCheckoutError;
 exports.AmbiguousPageSlugError = AmbiguousPageSlugError;
 exports.ApiError = ApiError;
 exports.DEFAULT_CHECKOUT_REDIRECT_HOSTS = DEFAULT_CHECKOUT_REDIRECT_HOSTS;
+exports.LEAD_ATTRIBUTION_CLICK_IDS = LEAD_ATTRIBUTION_CLICK_IDS;
+exports.LEAD_ATTRIBUTION_COOKIE_NAME = LEAD_ATTRIBUTION_COOKIE_NAME;
+exports.LEAD_ATTRIBUTION_MAX_AGE_SECONDS = LEAD_ATTRIBUTION_MAX_AGE_SECONDS;
 exports.PlainCacheAdapter = PlainCacheAdapter;
 exports.RETRY_AFTER_CAP_MS = RETRY_AFTER_CAP_MS;
 exports.UnsafeCheckoutRedirectError = UnsafeCheckoutRedirectError;
 exports.VISITOR_IP_HEADER = VISITOR_IP_HEADER;
 exports.buildContactFormMetadata = buildContactFormMetadata;
+exports.createLeadAttributionStore = createLeadAttributionStore;
 exports.createRebluClient = createRebluClient;
 exports.currentPagePath = currentPagePath;
+exports.getLeadAttributionStore = getLeadAttributionStore;
 exports.isSafeCheckoutRedirectUrl = isSafeCheckoutRedirectUrl;
+exports.leadTouchFromVisit = leadTouchFromVisit;
+exports.resetLeadAttributionStore = resetLeadAttributionStore;
 exports.visitorIpFromHeaders = visitorIpFromHeaders;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map