@flamingo-stack/openframe-frontend-core 0.0.483 → 0.0.484

package/dist/utils/first-touch-attribution.d.ts

@@ -0,0 +1,97 @@
+/**
+ * First-touch attribution capture.
+ *
+ * THE PROBLEM. Server-side UTM extraction reads the request body and, failing that, UTM
+ * params on the `referer` header. But `referer` is the page the form was submitted FROM, and
+ * a visitor who lands on `/?utm_source=reddit` and then navigates before converting arrives
+ * with a clean referer. Measured on the live DB: waitlist rows from the last 90 days have
+ * `ip_address` on 350/350 and `utm_source` on **0/350**. The parameters are not being lost in
+ * transit; they are gone by submit time.
+ *
+ * THE FIX. Capture the landing URL's attribution ONCE, on first page view, and replay it into
+ * every submit body from then on. The server already prefers body-supplied UTMs over the
+ * referer, so nothing changes server-side.
+ *
+ * FIRST touch, not last: `capture()` never overwrites an existing record, so a visitor who
+ * lands on an ad and later arrives via a bookmark keeps the ad attribution.
+ *
+ * Built on `createLocalStorageAdapter` so there is no hand-rolled Web Storage access and no
+ * module-scope `window` — `./utils` is imported by server-safe consumers, so touching
+ * `window` at module scope would break SSR.
+ *
+ * SESSION-SCOPED, deliberately and without an opt-out. Three reasons:
+ *  - first-touch attribution for a single visit is the useful signal;
+ *  - a session record does not persist an identifier across visits, which keeps this out of
+ *    consent-banner territory;
+ *  - `sessionStorage` is per-tab, so `load()`-then-`save()` cannot race another tab.
+ *    `localStorage` is shared, so two tabs opening simultaneously could both observe no
+ *    record and the second write would silently replace the first — breaking the one
+ *    invariant this module exists to hold. Web Storage has no compare-and-swap, so that race
+ *    cannot be closed reliably; the option is therefore not offered rather than offered with
+ *    a caveat. If cross-session persistence is ever needed it belongs in a server-side
+ *    cookie, where it can be written atomically.
+ *
+ * NEVER STORES A RAW URL. See `sanitizeLandingUrl`.
+ */
+/** Attribution parameters worth carrying from the landing URL to the submit body. */
+export interface FirstTouchAttribution {
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_content?: string;
+    utm_term?: string;
+    /** Reddit Ads click id. */
+    rdt_cid?: string;
+    /**
+     * The landing PAGE — `origin + pathname` only. Never the query string or fragment.
+     * See `sanitizeLandingUrl` for why.
+     */
+    landing_url?: string;
+    /** ISO timestamp of first capture, for debugging stale records. */
+    captured_at?: string;
+}
+export declare const FIRST_TOUCH_ATTRIBUTION_KEY = "of.first_touch_attribution";
+/**
+ * Reduce a URL to `origin + pathname`.
+ *
+ * The raw `window.location.href` must NEVER be stored or replayed. It routinely carries
+ * things that have nothing to do with attribution and everything to do with security: OAuth
+ * `code`/`state`, magic-link and password-reset tokens, `access_token` in the fragment,
+ * email addresses and other PII in query params. This value is spread into every submit body,
+ * so anything kept here would be POSTed to our API and forwarded on to HubSpot — a token in
+ * a CRM record is a token in every integration downstream of it.
+ *
+ * The path alone answers the only question worth asking ("which page did they land on"), so
+ * the query and fragment are dropped wholesale rather than filtered. An allowlist of "safe"
+ * params would need updating every time a new auth flow adds one; dropping everything cannot
+ * go stale.
+ */
+export declare function sanitizeLandingUrl(url: string): string | undefined;
+/** Parse the tracked parameters out of a URL. Returns `{}` when none are present. */
+export declare function parseAttributionFromUrl(url: string): FirstTouchAttribution;
+/**
+ * Record the landing URL's attribution if nothing is stored yet.
+ *
+ * Idempotent and first-touch-preserving: a later call with different parameters is ignored.
+ * Safe to call on every page view, and a no-op during SSR.
+ *
+ * @returns what is VERIFIABLY stored after the call — a pre-existing record, the new record
+ *   read back from storage, or `{}` when nothing was captured or the write did not stick.
+ */
+export declare function captureFirstTouchAttribution(options?: {
+    url?: string;
+}): FirstTouchAttribution;
+/** Read the stored attribution. `{}` when nothing was captured or during SSR. */
+export declare function getFirstTouchAttribution(): FirstTouchAttribution;
+/**
+ * Merge stored attribution into a submit body.
+ *
+ * Values already on the body WIN — a form that collected a real value explicitly should not
+ * be overwritten by a stored one. Spread this into every submit payload:
+ *
+ *   body: JSON.stringify(withFirstTouchAttribution({ email, name }))
+ */
+export declare function withFirstTouchAttribution<T extends Record<string, any>>(body: T): T & FirstTouchAttribution;
+/** Clear the stored record. Exposed for tests and for a consent-withdrawal path. */
+export declare function clearFirstTouchAttribution(): void;
+//# sourceMappingURL=first-touch-attribution.d.ts.map

package/dist/utils/first-touch-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-touch-attribution.d.ts","sourceRoot":"","sources":["../../src/utils/first-touch-attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,qFAAqF;AACrF,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,2BAA2B,+BAA+B,CAAA;AAkBvE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASlE;AAoBD,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAY1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,qBAAqB,CA0BlG;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,IAAI,qBAAqB,CAGhE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrE,IAAI,EAAE,CAAC,GACN,CAAC,GAAG,qBAAqB,CAO3B;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD"}

package/dist/utils/index.cjs

@@ -2874,7 +2874,7 @@ function getStorage(backend) {
 }
 function createLocalStorageAdapter(options) {
   const tag = options.logTag ?? "[local-storage]";
-  const backend = options.backend;
+  const backend = options.backend ?? "local";
   const resolveKey = () => {
     const ns = options.namespace?.();
     return ns ? `${ns}.${options.key}` : options.key;
@@ -4127,6 +4127,94 @@ function toFigmaOriginalUrl(url) {
 // src/utils/page-header-constants.ts
 var SECTION_HERO_ICON_CLASS = "h-10 w-10 text-ods-accent";
 
+// src/utils/first-touch-attribution.ts
+var FIRST_TOUCH_ATTRIBUTION_KEY = "of.first_touch_attribution";
+var TRACKED_PARAMS = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term",
+  "rdt_cid"
+];
+var ALLOWED_KEYS = /* @__PURE__ */ new Set([
+  ...TRACKED_PARAMS,
+  "landing_url",
+  "captured_at"
+]);
+function sanitizeLandingUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return void 0;
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return void 0;
+  }
+}
+function makeAdapter() {
+  return createLocalStorageAdapter({
+    key: FIRST_TOUCH_ATTRIBUTION_KEY,
+    backend: "session",
+    logTag: "[first-touch-attribution]",
+    // Anything running on this origin can write to sessionStorage, and whatever `load()`
+    // returns is spread into submit bodies. So the stored shape is validated, not assumed:
+    // allowlisted keys only, string values only. Without this a malformed or planted record
+    // would inject arbitrary keys into an API payload.
+    validate: (parsed) => {
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+      return Object.entries(parsed).every(
+        ([key, value]) => ALLOWED_KEYS.has(key) && typeof value === "string"
+      );
+    }
+  });
+}
+function parseAttributionFromUrl(url) {
+  const out = {};
+  try {
+    const parsed = new URL(url);
+    for (const param of TRACKED_PARAMS) {
+      const value = parsed.searchParams.get(param);
+      if (value && value.trim()) out[param] = value.trim();
+    }
+  } catch {
+    return {};
+  }
+  return out;
+}
+function captureFirstTouchAttribution(options = {}) {
+  if (typeof window === "undefined") return {};
+  const adapter2 = makeAdapter();
+  const existing = adapter2.load();
+  if (existing && Object.keys(existing).length > 0) return existing;
+  const href = options.url ?? window.location.href;
+  const parsed = parseAttributionFromUrl(href);
+  if (Object.keys(parsed).length === 0) return {};
+  const landingUrl = sanitizeLandingUrl(href);
+  const record = {
+    ...parsed,
+    ...landingUrl ? { landing_url: landingUrl } : {},
+    captured_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  adapter2.save(record);
+  return adapter2.load() ?? {};
+}
+function getFirstTouchAttribution() {
+  if (typeof window === "undefined") return {};
+  return makeAdapter().load() ?? {};
+}
+function withFirstTouchAttribution(body) {
+  const stored = getFirstTouchAttribution();
+  const merged = { ...stored, ...body };
+  for (const [k, v] of Object.entries(merged)) {
+    if (v === void 0 || v === null || v === "") delete merged[k];
+  }
+  return merged;
+}
+function clearFirstTouchAttribution() {
+  if (typeof window === "undefined") return;
+  makeAdapter().clear();
+}
+
 exports.ANTHROPIC_SUPPORTED_IMAGE_MIME = ANTHROPIC_SUPPORTED_IMAGE_MIME;
 exports.AUTO_CONTINUATION_DIRECTIVE_PREFIX = AUTO_CONTINUATION_DIRECTIVE_PREFIX;
 exports.BITE_ID_RE = BITE_ID_RE;
@@ -4145,6 +4233,7 @@ exports.DELIVERY_TASK_TYPE_OPTIONS = DELIVERY_TASK_TYPE_OPTIONS;
 exports.DESIGN_PALETTE = DESIGN_PALETTE;
 exports.DEV_SECTION_PARAM_KEYS = DEV_SECTION_PARAM_KEYS;
 exports.ELAPSED_MS_FIELD = ELAPSED_MS_FIELD;
+exports.FIRST_TOUCH_ATTRIBUTION_KEY = FIRST_TOUCH_ATTRIBUTION_KEY;
 exports.GENERIC_EMAIL_DOMAINS = GENERIC_EMAIL_DOMAINS;
 exports.HEX_PATTERN = HEX_PATTERN;
 exports.HONEYPOT_FIELD = HONEYPOT_FIELD;
@@ -4177,10 +4266,12 @@ exports.buildListUrl = buildListUrl;
 exports.buildOgPlaceholderUrl = buildOgPlaceholderUrl;
 exports.buildSuggestionUrl = buildSuggestionUrl;
 exports.canonicalContentRefType = canonicalContentRefType;
+exports.captureFirstTouchAttribution = captureFirstTouchAttribution;
 exports.cleanEmailDomain = cleanEmailDomain;
 exports.clearAnnouncementDismissals = clearAnnouncementDismissals;
 exports.clearDismissCookie = clearDismissCookie;
 exports.clearEmbedProxyAuth = clearEmbedProxyAuth;
+exports.clearFirstTouchAttribution = clearFirstTouchAttribution;
 exports.clearLegacyAnnouncementCache = clearLegacyAnnouncementCache;
 exports.clearWalkthroughDismissal = clearWalkthroughDismissal;
 exports.clickupTaskUrl = clickupTaskUrl;
@@ -4276,6 +4367,7 @@ exports.getDocSourceDefaultPath = getDocSourceDefaultPath;
 exports.getDynamicIcon = getDynamicIcon;
 exports.getEmbedProxyAuth = getEmbedProxyAuth;
 exports.getFirstLastInitials = getFirstLastInitials;
+exports.getFirstTouchAttribution = getFirstTouchAttribution;
 exports.getIconComponent = getIconComponent;
 exports.getInitialExpandedNodeIds = getInitialExpandedNodeIds;
 exports.getOSIcon = getOSIcon;
@@ -4332,6 +4424,7 @@ exports.normalizeOSType = normalizeOSType;
 exports.normalizeToolType = normalizeToolType;
 exports.normalizeToolTypeWithFallback = normalizeToolTypeWithFallback;
 exports.orderContentRefTypes = orderContentRefTypes;
+exports.parseAttributionFromUrl = parseAttributionFromUrl;
 exports.parseFaqHash = parseFaqHash;
 exports.parseScrollAnchor = parseScrollAnchor;
 exports.parseWireCommandOverride = parseWireCommandOverride;
@@ -4350,6 +4443,7 @@ exports.releaseTypeToBadgeColor = releaseTypeToBadgeColor;
 exports.resolveContentFetchPath = resolveContentFetchPath;
 exports.resolveReleaseCover = resolveReleaseCover;
 exports.rgbToHex = rgbToHex;
+exports.sanitizeLandingUrl = sanitizeLandingUrl;
 exports.sanitizeTitleForChat = sanitizeTitleForChat;
 exports.scrollElementIntoView = scrollElementIntoView;
 exports.serializeJsonLd = serializeJsonLd;
@@ -4377,6 +4471,7 @@ exports.validateEmailDomain = validateEmailDomain;
 exports.validateEmailDomainList = validateEmailDomainList;
 exports.validatePhoneNumber = validatePhoneNumber;
 exports.walkthroughDismissCookieName = walkthroughDismissCookieName;
+exports.withFirstTouchAttribution = withFirstTouchAttribution;
 exports.writeDismissCookie = writeDismissCookie;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map