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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.483",
+  "version": "0.0.484",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/utils/__tests__/first-touch-attribution-persistence.test.ts

@@ -0,0 +1,58 @@
+/**
+ * The "write silently failed" path, isolated.
+ *
+ * Mocked at the ADAPTER seam rather than by patching Web Storage: this repo runs vitest on a
+ * Node that ships its own experimental `localStorage`/`sessionStorage`, so neither an instance
+ * spy on `window.sessionStorage` nor a `Storage.prototype` patch reliably intercepts what the
+ * adapter actually calls. The contract under test belongs to the adapter boundary anyway —
+ * `save()` returns `void` and swallows its errors, so the only way to know a write stuck is
+ * to read it back.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const store: { value: unknown } = { value: null }
+/** When true, `save()` accepts the call and drops the value — a blocked/full quota. */
+let swallowWrites = false
+
+vi.mock('../local-storage-adapter', () => ({
+  createLocalStorageAdapter: () => ({
+    load: () => store.value,
+    save: (value: unknown) => {
+      if (swallowWrites) return
+      store.value = value
+    },
+    clear: () => {
+      store.value = null
+    },
+  }),
+}))
+
+const { captureFirstTouchAttribution, getFirstTouchAttribution } = await import(
+  '../first-touch-attribution'
+)
+
+beforeEach(() => {
+  store.value = null
+  swallowWrites = false
+  Object.defineProperty(window, 'location', {
+    value: new URL('https://www.openmsp.ai/waitlist?utm_source=reddit'),
+    writable: true,
+    configurable: true,
+  })
+})
+
+describe('captureFirstTouchAttribution persistence', () => {
+  it('returns the record when the write sticks', () => {
+    expect(captureFirstTouchAttribution().utm_source).toBe('reddit')
+    expect(getFirstTouchAttribution().utm_source).toBe('reddit')
+  })
+
+  it('returns {} — NOT the record — when the write is swallowed', () => {
+    swallowWrites = true
+    // Returning the record here would hand the caller attribution that no later read can
+    // recover: it would be replayed on this page view and absent on the next, which is worse
+    // than never replaying it, because it looks like it worked.
+    expect(captureFirstTouchAttribution()).toEqual({})
+    expect(getFirstTouchAttribution()).toEqual({})
+  })
+})

package/src/utils/__tests__/first-touch-attribution.test.ts

@@ -0,0 +1,185 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  FIRST_TOUCH_ATTRIBUTION_KEY,
+  captureFirstTouchAttribution,
+  clearFirstTouchAttribution,
+  getFirstTouchAttribution,
+  parseAttributionFromUrl,
+  sanitizeLandingUrl,
+  withFirstTouchAttribution,
+} from '../first-touch-attribution'
+
+const LANDING = 'https://www.openmsp.ai/waitlist?utm_source=reddit&utm_medium=cpc'
+
+function setHref(href: string) {
+  // jsdom's location is read-only; replace it for the duration of the test.
+  Object.defineProperty(window, 'location', {
+    value: new URL(href),
+    writable: true,
+    configurable: true,
+  })
+}
+
+/**
+ * `window.localStorage` is NOT reliably present here: Node 26 ships an experimental global
+ * `localStorage` that requires `--localstorage-file` and shadows jsdom's implementation, so it
+ * resolves to undefined. `sessionStorage` — the only backend this module uses — is fine.
+ */
+const localStorageOrNull = (() => {
+  try {
+    return window.localStorage ?? null
+  } catch {
+    return null
+  }
+})()
+
+beforeEach(() => {
+  window.sessionStorage.clear()
+  localStorageOrNull?.clear()
+  setHref(LANDING)
+})
+
+describe('parseAttributionFromUrl', () => {
+  it('picks up the tracked params and nothing else', () => {
+    expect(parseAttributionFromUrl(`${LANDING}&unrelated=x`)).toEqual({
+      utm_source: 'reddit',
+      utm_medium: 'cpc',
+    })
+  })
+
+  it('returns {} for a URL with no attribution, and for garbage', () => {
+    expect(parseAttributionFromUrl('https://x.com/')).toEqual({})
+    expect(parseAttributionFromUrl('not a url')).toEqual({})
+  })
+})
+
+describe('sanitizeLandingUrl', () => {
+  it('keeps origin + pathname only', () => {
+    expect(sanitizeLandingUrl(LANDING)).toBe('https://www.openmsp.ai/waitlist')
+  })
+
+  it('drops the fragment, where implicit-flow tokens live', () => {
+    expect(sanitizeLandingUrl('https://x.com/cb#access_token=SECRET&token_type=bearer')).toBe(
+      'https://x.com/cb',
+    )
+  })
+
+  it.each([
+    'https://x.com/auth?code=SECRET&state=abc',
+    'https://x.com/reset?token=SECRET',
+    'https://x.com/invite?email=jane%40acme.com',
+  ])('drops the query entirely: %s', (url) => {
+    const out = sanitizeLandingUrl(url)!
+    expect(out).not.toContain('SECRET')
+    expect(out).not.toContain('jane')
+    expect(out).not.toContain('?')
+  })
+
+  it('rejects non-http(s) schemes and garbage', () => {
+    expect(sanitizeLandingUrl('javascript:alert(1)')).toBeUndefined()
+    expect(sanitizeLandingUrl('not a url')).toBeUndefined()
+  })
+})
+
+describe('captureFirstTouchAttribution', () => {
+  it('stores a sanitized record and reads back identically', () => {
+    const stored = captureFirstTouchAttribution()
+    expect(stored.utm_source).toBe('reddit')
+    expect(stored.landing_url).toBe('https://www.openmsp.ai/waitlist')
+    expect(stored.captured_at).toBeTruthy()
+    expect(getFirstTouchAttribution()).toEqual(stored)
+  })
+
+  it('never persists a secret from the landing URL', () => {
+    setHref('https://x.com/cb?utm_source=ads&code=SUPERSECRET#access_token=ALSOSECRET')
+    captureFirstTouchAttribution()
+    const raw = window.sessionStorage.getItem(FIRST_TOUCH_ATTRIBUTION_KEY) ?? ''
+    expect(raw).not.toContain('SUPERSECRET')
+    expect(raw).not.toContain('ALSOSECRET')
+    expect(raw).toContain('ads')
+  })
+
+  it('is FIRST touch: a later landing does not overwrite', () => {
+    const first = captureFirstTouchAttribution()
+    setHref('https://www.openmsp.ai/?utm_source=bookmark')
+    expect(captureFirstTouchAttribution()).toEqual(first)
+    expect(getFirstTouchAttribution().utm_source).toBe('reddit')
+  })
+
+  it('stores nothing when the landing URL carries no attribution', () => {
+    setHref('https://www.openmsp.ai/waitlist')
+    expect(captureFirstTouchAttribution()).toEqual({})
+    expect(window.sessionStorage.getItem(FIRST_TOUCH_ATTRIBUTION_KEY)).toBeNull()
+  })
+
+  it('uses sessionStorage, never localStorage', () => {
+    captureFirstTouchAttribution()
+    expect(window.sessionStorage.getItem(FIRST_TOUCH_ATTRIBUTION_KEY)).toBeTruthy()
+    // Skipped where the runtime does not expose localStorage (see the note above); the
+    // sessionStorage assertion is the load-bearing half either way.
+    if (localStorageOrNull) {
+      expect(localStorageOrNull.getItem(FIRST_TOUCH_ATTRIBUTION_KEY)).toBeNull()
+    }
+  })
+
+})
+
+describe('stored-shape validation', () => {
+  it.each([
+    ['a planted unknown key', JSON.stringify({ utm_source: 'x', is_admin: 'true' })],
+    ['a non-string value', JSON.stringify({ utm_source: { $ne: null } })],
+    ['an array', JSON.stringify([{ utm_source: 'x' }])],
+    ['a bare string', JSON.stringify('utm_source=x')],
+    ['malformed JSON', '{oops'],
+  ])('rejects %s rather than replaying it', (_label, raw) => {
+    window.sessionStorage.setItem(FIRST_TOUCH_ATTRIBUTION_KEY, raw)
+    expect(getFirstTouchAttribution()).toEqual({})
+    // The important half: nothing unexpected reaches a submit body.
+    expect(withFirstTouchAttribution({ email: 'a@b.com' })).toEqual({ email: 'a@b.com' })
+  })
+
+  it('accepts a well-formed record', () => {
+    window.sessionStorage.setItem(
+      FIRST_TOUCH_ATTRIBUTION_KEY,
+      JSON.stringify({ utm_source: 'reddit', captured_at: '2026-01-01T00:00:00.000Z' }),
+    )
+    expect(getFirstTouchAttribution().utm_source).toBe('reddit')
+  })
+})
+
+describe('withFirstTouchAttribution', () => {
+  it('merges stored attribution into the body', () => {
+    captureFirstTouchAttribution()
+    expect(withFirstTouchAttribution({ email: 'a@b.com' })).toMatchObject({
+      email: 'a@b.com',
+      utm_source: 'reddit',
+      utm_medium: 'cpc',
+    })
+  })
+
+  it('lets an explicit body value WIN over the stored one', () => {
+    captureFirstTouchAttribution()
+    expect(withFirstTouchAttribution({ utm_source: 'typed-by-form' }).utm_source).toBe(
+      'typed-by-form',
+    )
+  })
+
+  it('strips empty values so a blank never reaches the API', () => {
+    expect(withFirstTouchAttribution({ email: 'a@b.com', phone: '', name: null as any })).toEqual({
+      email: 'a@b.com',
+    })
+  })
+
+  it('is a no-op passthrough when nothing was captured', () => {
+    expect(withFirstTouchAttribution({ email: 'a@b.com' })).toEqual({ email: 'a@b.com' })
+  })
+})
+
+describe('clearFirstTouchAttribution', () => {
+  it('removes the record', () => {
+    captureFirstTouchAttribution()
+    clearFirstTouchAttribution()
+    expect(getFirstTouchAttribution()).toEqual({})
+  })
+})

package/src/utils/first-touch-attribution.ts

@@ -0,0 +1,200 @@
+/**
+ * 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`.
+ */
+
+import { createLocalStorageAdapter } from './local-storage-adapter'
+
+/** 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 const FIRST_TOUCH_ATTRIBUTION_KEY = 'of.first_touch_attribution'
+
+const TRACKED_PARAMS = [
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_content',
+  'utm_term',
+  'rdt_cid',
+] as const
+
+/** Every key this module is allowed to store or replay. */
+const ALLOWED_KEYS: ReadonlySet<string> = new Set<string>([
+  ...TRACKED_PARAMS,
+  'landing_url',
+  'captured_at',
+])
+
+/**
+ * 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 function sanitizeLandingUrl(url: string): string | undefined {
+  try {
+    const parsed = new URL(url)
+    // Non-http(s) schemes have no meaningful landing page.
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return undefined
+    return `${parsed.origin}${parsed.pathname}`
+  } catch {
+    return undefined
+  }
+}
+
+function makeAdapter() {
+  return createLocalStorageAdapter<FirstTouchAttribution>({
+    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): parsed is FirstTouchAttribution => {
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return false
+      return Object.entries(parsed as Record<string, unknown>).every(
+        ([key, value]) => ALLOWED_KEYS.has(key) && typeof value === 'string',
+      )
+    },
+  })
+}
+
+/** Parse the tracked parameters out of a URL. Returns `{}` when none are present. */
+export function parseAttributionFromUrl(url: string): FirstTouchAttribution {
+  const out: FirstTouchAttribution = {}
+  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
+}
+
+/**
+ * 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 function captureFirstTouchAttribution(options: { url?: string } = {}): FirstTouchAttribution {
+  if (typeof window === 'undefined') return {}
+
+  const adapter = makeAdapter()
+  const existing = adapter.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: FirstTouchAttribution = {
+    ...parsed,
+    ...(landingUrl ? { landing_url: landingUrl } : {}),
+    captured_at: new Date().toISOString(),
+  }
+  adapter.save(record)
+
+  // Confirm it PERSISTED before reporting success. `save()` returns void and swallows its
+  // errors, so in blocked or quota-exceeded storage (Safari private mode, a full quota) the
+  // write silently no-ops. Returning `record` there would hand the caller data that no
+  // subsequent `getFirstTouchAttribution()` can recover — the caller would replay
+  // attribution on this page view and none on the next, which is worse than replaying none
+  // at all because it looks like it worked.
+  return adapter.load() ?? {}
+}
+
+/** Read the stored attribution. `{}` when nothing was captured or during SSR. */
+export function getFirstTouchAttribution(): FirstTouchAttribution {
+  if (typeof window === 'undefined') return {}
+  return makeAdapter().load() ?? {}
+}
+
+/**
+ * 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 function withFirstTouchAttribution<T extends Record<string, any>>(
+  body: T,
+): T & FirstTouchAttribution {
+  const stored = getFirstTouchAttribution()
+  const merged: Record<string, any> = { ...stored, ...body }
+  for (const [k, v] of Object.entries(merged)) {
+    if (v === undefined || v === null || v === '') delete merged[k]
+  }
+  return merged as T & FirstTouchAttribution
+}
+
+/** Clear the stored record. Exposed for tests and for a consent-withdrawal path. */
+export function clearFirstTouchAttribution(): void {
+  if (typeof window === 'undefined') return
+  makeAdapter().clear()
+}

package/src/utils/index.ts

@@ -338,3 +338,4 @@ export * from './markdown-section-extractor'
 export * from './markdown-to-plain'
 export * from './embed-url-converters'
 export * from './page-header-constants'
+export * from './first-touch-attribution'