utneque 1.0.0

package/packages/browser/src/plugins/analytics-node/index.ts

@@ -0,0 +1,67 @@
+import { Plugin } from '../../core/plugin'
+import { Context } from '../../core/context'
+import { HightouchEvent } from '../../core/events'
+import fetch from 'node-fetch'
+import { version } from '../../generated/version'
+
+interface AnalyticsNodeSettings {
+  writeKey: string
+  name: string
+  type: Plugin['type']
+  version: string
+}
+
+const btoa = (val: string): string => Buffer.from(val).toString('base64')
+
+export async function post(
+  event: HightouchEvent,
+  writeKey: string
+): Promise<HightouchEvent> {
+  const res = await fetch(
+    `https://us-east-1.hightouch-events.com/v1/${event.type}`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'analytics-node-next/latest',
+        Authorization: `Basic ${btoa(writeKey)}`,
+      },
+      body: JSON.stringify(event),
+    }
+  )
+
+  if (!res.ok) {
+    throw new Error('Message Rejected')
+  }
+
+  return event
+}
+
+export function analyticsNode(settings: AnalyticsNodeSettings): Plugin {
+  const send = async (ctx: Context): Promise<Context> => {
+    ctx.updateEvent('context.library.name', 'analytics-node-next')
+    ctx.updateEvent('context.library.version', version)
+    ctx.updateEvent('_metadata.nodeVersion', process.versions.node)
+
+    await post(ctx.event, settings.writeKey)
+    return ctx
+  }
+
+  const plugin: Plugin = {
+    name: settings.name,
+    type: settings.type,
+    version: settings.version,
+
+    load: (ctx) => Promise.resolve(ctx),
+    isLoaded: () => true,
+
+    track: send,
+    identify: send,
+    page: send,
+    alias: send,
+    group: send,
+    screen: send,
+  }
+
+  return plugin
+}

package/packages/browser/src/plugins/env-enrichment/__tests__/index.test.ts

@@ -0,0 +1,421 @@
+import cookie from 'js-cookie'
+import assert from 'assert'
+import { Analytics } from '../../../core/analytics'
+import { envEnrichment } from '..'
+import { HightouchioSettings } from '../../hightouchio'
+import { CoreExtraContext } from '@ht-sdks/events-sdk-js-core'
+import { UADataValues } from '../../../lib/client-hints/interfaces'
+import {
+  highEntropyTestData,
+  lowEntropyTestData,
+} from '../../../test-helpers/fixtures/client-hints'
+
+/**
+ * Filters out the calls made for probing cookie availability
+ */
+const ignoreProbeCookieWrites = (
+  fn: jest.SpyInstance<
+    string | undefined,
+    [
+      name: string,
+      value: string | object,
+      options?: cookie.CookieAttributes | undefined
+    ]
+  >
+) => fn.mock.calls.filter((c) => c[0] !== 'ajs_cookies_check')
+
+describe('Other visitor metadata', () => {
+  let options: HightouchioSettings
+  let analytics: Analytics
+  ;(window.navigator as any).userAgentData = {
+    ...lowEntropyTestData,
+    getHighEntropyValues: jest
+      .fn()
+      .mockImplementation((hints: string[]): Promise<UADataValues> => {
+        let result = {}
+        Object.entries(highEntropyTestData).forEach(([k, v]) => {
+          if (hints.includes(k)) {
+            result = {
+              ...result,
+              [k]: v,
+            }
+          }
+        })
+        return Promise.resolve({
+          ...lowEntropyTestData,
+          ...result,
+        })
+      }),
+    toJSON: jest.fn(() => {
+      return lowEntropyTestData
+    }),
+  }
+
+  const amendSearchParams = (search?: any): CoreExtraContext => ({
+    page: { search },
+  })
+
+  beforeEach(async () => {
+    options = { apiKey: 'foo' }
+    analytics = new Analytics({ writeKey: options.apiKey })
+
+    await analytics.register(envEnrichment)
+  })
+
+  afterEach(() => {
+    analytics.reset()
+    Object.keys(cookie.get()).map((k) => cookie.remove(k))
+
+    if (window.localStorage) {
+      window.localStorage.clear()
+    }
+  })
+
+  it('should add .timezone', async () => {
+    const ctx = await analytics.track('test')
+    assert(typeof ctx.event.context?.timezone === 'string')
+  })
+
+  it('should add .library', async () => {
+    const ctx = await analytics.track('test')
+    assert(ctx.event.context?.library)
+    assert(ctx.event.context?.library.name === 'events-sdk-js')
+    // TODO fix why version isn't showing up in this test
+    // assert(ctx.event.context?.library.version === `npm:next-${version}`)
+  })
+
+  it('should allow override of .library', async () => {
+    const customContext = {
+      library: {
+        name: 'analytics-wordpress',
+        version: '1.0.3',
+      },
+    }
+
+    const ctx = await analytics.track('test', {}, { context: customContext })
+
+    assert(ctx.event.context?.library)
+    assert(ctx.event.context?.library.name === 'analytics-wordpress')
+    assert(ctx.event.context?.library.version === '1.0.3')
+  })
+
+  it('should add .userAgent', async () => {
+    const ctx = await analytics.track('test')
+    const removeVersionNum = (agent: string) => agent.replace(/jsdom\/.*/, '')
+    const userAgent1 = removeVersionNum(ctx.event.context?.userAgent as string)
+    const userAgent2 = removeVersionNum(navigator.userAgent)
+    assert(userAgent1 === userAgent2)
+  })
+
+  it('should add .userAgentData when available', async () => {
+    const ctx = await analytics.track('event')
+    expect(ctx.event.context?.userAgentData).toEqual(lowEntropyTestData)
+  })
+
+  it('should add .locale', async () => {
+    const ctx = await analytics.track('test')
+    assert(ctx.event.context?.locale === navigator.language)
+  })
+
+  it('should not replace .locale if provided', async () => {
+    const customContext = {
+      locale: 'foobar',
+    }
+
+    const ctx = await analytics.track('test', {}, { context: customContext })
+    assert(ctx.event.context?.locale === 'foobar')
+  })
+
+  it('should add .campaign', async () => {
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams(
+          'utm_source=source&utm_medium=medium&utm_term=term&utm_content=content&utm_campaign=name'
+        ),
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.campaign)
+    assert(ctx.event.context.campaign.source === 'source')
+    assert(ctx.event.context.campaign.medium === 'medium')
+    assert(ctx.event.context.campaign.term === 'term')
+    assert(ctx.event.context.campaign.content === 'content')
+    assert(ctx.event.context.campaign.name === 'name')
+  })
+
+  it('should decode query params', async () => {
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams('?utm_source=%5BFoo%5D'),
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.campaign)
+    assert(ctx.event.context.campaign.source === '[Foo]')
+  })
+
+  it('should guard against undefined utm params', async () => {
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams('?utm_source'),
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.campaign)
+    assert(ctx.event.context.campaign.source === '')
+  })
+
+  it('should guard against empty utm params', async () => {
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams('?utm_source='),
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.campaign)
+    assert(ctx.event.context.campaign.source === '')
+  })
+
+  it('only parses utm params suffixed with _', async () => {
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams('?utm'),
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert.deepStrictEqual(ctx.event.context.campaign, {})
+  })
+
+  it('should guard against short utm params', async () => {
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams('?utm_'),
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert.deepStrictEqual(ctx.event.context.campaign, {})
+  })
+
+  it('should allow override of .campaign', async () => {
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: {
+          ...amendSearchParams(
+            '?utm_source=source&utm_medium=medium&utm_term=term&utm_content=content&utm_campaign=name'
+          ),
+          campaign: {
+            source: 'overrideSource',
+            medium: 'overrideMedium',
+            term: 'overrideTerm',
+            content: 'overrideContent',
+            name: 'overrideName',
+          },
+        },
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.campaign)
+    assert(ctx.event.context.campaign.source === 'overrideSource')
+    assert(ctx.event.context.campaign.medium === 'overrideMedium')
+    assert(ctx.event.context.campaign.term === 'overrideTerm')
+    assert(ctx.event.context.campaign.content === 'overrideContent')
+    assert(ctx.event.context.campaign.name === 'overrideName')
+  })
+
+  it('should allow override of .search with object', async () => {
+    const searchParams = {
+      something_else: 'bar',
+      utm_custom: 'foo',
+      utm_campaign: 'hello',
+    }
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams(searchParams),
+      }
+    )
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.referrer === undefined)
+    assert(ctx.event.context.campaign)
+    assert(ctx.event.context.page?.search)
+    expect(ctx.event.context.page.search).toEqual(searchParams)
+    expect(ctx.event.context.campaign).toEqual({ name: 'hello', custom: 'foo' })
+  })
+
+  it('should not throw an error if the object is invalid', async () => {
+    const searchParams = {
+      invalidNested: {
+        foo: {
+          bar: null,
+        },
+      },
+    }
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams(searchParams),
+      }
+    )
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.referrer === undefined)
+    expect(ctx.event.context.page?.search).toEqual(searchParams)
+  })
+
+  test.each([
+    {
+      bar: ['123', '456'],
+      utm_campaign: 'hello',
+      utm_custom: ['foo', 'bar'],
+    },
+    '?bar=123&bar=456&utm_campaign=hello&utm_custom=foo&utm_custom=bar',
+  ])(
+    'should work as expected if there are multiple values for the same param (%p)',
+    async (params) => {
+      const ctx = await analytics.track(
+        'test',
+        {},
+        {
+          context: amendSearchParams(params),
+        }
+      )
+      assert(ctx.event)
+      assert(ctx.event.context)
+      assert(ctx.event.context.referrer === undefined)
+      expect(ctx.event.context.page?.search).toEqual(params)
+      expect(ctx.event.context.campaign).toEqual({
+        name: 'hello',
+        custom: 'bar',
+      })
+    }
+  )
+
+  it('should add .referrer.id and .referrer.type (cookies)', async () => {
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams('?utm_source=source&urid=medium'),
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.referrer)
+    expect(ctx.event.context.referrer.id).toBe('medium')
+    assert(ctx.event.context.referrer.type === 'millennial-media')
+    expect(cookie.get('s:context.referrer')).toEqual(
+      JSON.stringify({
+        id: 'medium',
+        type: 'millennial-media',
+      })
+    )
+  })
+
+  it('should add .referrer.id and .referrer.type (cookieless)', async () => {
+    const setCookieSpy = jest.spyOn(cookie, 'set')
+    analytics = new Analytics(
+      { writeKey: options.apiKey },
+      { disableClientPersistence: true }
+    )
+
+    await analytics.register(envEnrichment)
+
+    const ctx = await analytics.track(
+      'test',
+      {},
+      {
+        context: amendSearchParams('utm_source=source&urid=medium'),
+      }
+    )
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.referrer)
+    expect(ctx.event.context.referrer.id).toEqual('medium')
+    assert(ctx.event.context.referrer.type === 'millennial-media')
+    expect(cookie.get('s:context.referrer')).toBeUndefined()
+    expect(ignoreProbeCookieWrites(setCookieSpy).length).toBe(0)
+  })
+
+  it('should add .referrer.id and .referrer.type from cookie', async () => {
+    cookie.set('s:context.referrer', '{"id":"baz","type":"millennial-media"}')
+    const ctx = await analytics.track('test')
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.referrer)
+    assert(ctx.event.context.referrer.id === 'baz')
+    assert(ctx.event.context.referrer.type === 'millennial-media')
+  })
+
+  it('should add .referrer.id and .referrer.type from cookie when no query is given', async () => {
+    cookie.set(
+      's:context.referrer',
+      '{"id":"medium","type":"millennial-media"}'
+    )
+    const ctx = await analytics.track('test')
+
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.referrer)
+    assert(ctx.event.context.referrer.id === 'medium')
+    assert(ctx.event.context.referrer.type === 'millennial-media')
+  })
+
+  it('shouldnt add non amp ga cookie', async () => {
+    cookie.set('_ga', 'some-nonamp-id')
+    const ctx = await analytics.track('test')
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(!ctx.event.context.amp)
+  })
+
+  it('should add .amp.id from store', async () => {
+    cookie.set('_ga', 'amp-foo')
+    const ctx = await analytics.track('test')
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(ctx.event.context.amp)
+    assert(ctx.event.context.amp.id === 'amp-foo')
+  })
+
+  it('should not add .amp if theres no _ga', async () => {
+    cookie.remove('_ga')
+    const ctx = await analytics.track('test')
+    assert(ctx.event)
+    assert(ctx.event.context)
+    assert(!ctx.event.context.amp)
+  })
+})

package/packages/browser/src/plugins/env-enrichment/index.ts

@@ -0,0 +1,208 @@
+import jar from 'js-cookie'
+import type { Context } from '../../core/context'
+import type { Plugin } from '../../core/plugin'
+import { version } from '../../generated/version'
+import { HightouchEvent } from '../../core/events'
+import { Campaign, PluginType } from '@ht-sdks/events-sdk-js-core'
+import { getVersionType } from '../../lib/version-type'
+import { tld } from '../../core/user/tld'
+import { gracefulDecodeURIComponent } from '../../core/query-string/gracefulDecodeURIComponent'
+import { CookieStorage, UniversalStorage } from '../../core/storage'
+import { Analytics } from '../../core/analytics'
+import { clientHints } from '../../lib/client-hints'
+import { UADataValues } from '../../lib/client-hints/interfaces'
+
+let cookieOptions: jar.CookieAttributes | undefined
+function getCookieOptions(): jar.CookieAttributes {
+  if (cookieOptions) {
+    return cookieOptions
+  }
+
+  const domain = tld(window.location.href)
+  cookieOptions = {
+    expires: 31536000000, // 1 year
+    secure: false,
+    path: '/',
+  }
+  if (domain) {
+    cookieOptions.domain = domain
+  }
+
+  return cookieOptions
+}
+
+type Ad = { id: string; type: string }
+
+function ads(query: string): Ad | undefined {
+  const queryIds: Record<string, string> = {
+    btid: 'dataxu',
+    urid: 'millennial-media',
+  }
+
+  if (query.startsWith('?')) {
+    query = query.substring(1)
+  }
+  query = query.replace(/\?/g, '&')
+  const parts = query.split('&')
+
+  for (const part of parts) {
+    const [k, v] = part.split('=')
+    if (queryIds[k]) {
+      return {
+        id: v,
+        type: queryIds[k],
+      }
+    }
+  }
+}
+
+export function utm(query: string): Campaign {
+  if (query.startsWith('?')) {
+    query = query.substring(1)
+  }
+  query = query.replace(/\?/g, '&')
+
+  return query.split('&').reduce((acc, str) => {
+    const [k, v = ''] = str.split('=')
+    if (k.includes('utm_') && k.length > 4) {
+      let utmParam = k.slice(4) as keyof Campaign
+      if (utmParam === 'campaign') {
+        utmParam = 'name'
+      }
+      acc[utmParam] = gracefulDecodeURIComponent(v)
+    }
+    return acc
+  }, {} as Campaign)
+}
+
+export function ampId(): string | undefined {
+  const ampId = jar.get('_ga')
+  if (ampId && ampId.startsWith('amp')) {
+    return ampId
+  }
+}
+
+function referrerId(
+  query: string,
+  ctx: HightouchEvent['context'],
+  disablePersistance: boolean
+): void {
+  const storage = new UniversalStorage<{
+    's:context.referrer': Ad
+  }>(disablePersistance ? [] : [new CookieStorage(getCookieOptions())])
+
+  const stored = storage.get('s:context.referrer')
+
+  const ad = ads(query) ?? stored
+
+  if (!ad) {
+    return
+  }
+
+  if (ctx) {
+    ctx.referrer = { ...ctx.referrer, ...ad }
+  }
+
+  storage.set('s:context.referrer', ad)
+}
+
+/**
+ *
+ * @param obj e.g. { foo: 'b', bar: 'd', baz: ['123', '456']}
+ * @returns e.g. 'foo=b&bar=d&baz=123&baz=456'
+ */
+const objectToQueryString = (
+  obj: Record<string, string | string[]>
+): string => {
+  try {
+    const searchParams = new URLSearchParams()
+    Object.entries(obj).forEach(([k, v]) => {
+      if (Array.isArray(v)) {
+        v.forEach((value) => searchParams.append(k, value))
+      } else {
+        searchParams.append(k, v)
+      }
+    })
+    return searchParams.toString()
+  } catch {
+    return ''
+  }
+}
+
+class EnvironmentEnrichmentPlugin implements Plugin {
+  private instance!: Analytics
+  private userAgentData: UADataValues | undefined
+
+  name = 'Page Enrichment'
+  type: PluginType = 'before'
+  version = '0.1.0'
+  isLoaded = () => true
+  load = async (_ctx: Context, instance: Analytics) => {
+    this.instance = instance
+    try {
+      this.userAgentData = await clientHints(
+        this.instance.options.highEntropyValuesClientHints
+      )
+    } catch (_) {
+      // if client hints API doesn't return anything leave undefined
+    }
+    return Promise.resolve()
+  }
+
+  private enrich = (ctx: Context): Context => {
+    // Note: Types are off - context should never be undefined here, since it is set as part of event creation.
+    const evtCtx = ctx.event.context!
+
+    const search = evtCtx.page!.search || ''
+
+    const query =
+      typeof search === 'object' ? objectToQueryString(search) : search
+
+    evtCtx.userAgent = navigator.userAgent
+    evtCtx.userAgentData = this.userAgentData
+
+    // @ts-ignore
+    const locale = navigator.userLanguage || navigator.language
+
+    if (typeof evtCtx.locale === 'undefined' && typeof locale !== 'undefined') {
+      evtCtx.locale = locale
+    }
+
+    evtCtx.library ??= {
+      name: 'events-sdk-js',
+      version: `${getVersionType() === 'web' ? 'web' : 'npm'}-${version}`,
+    }
+
+    if (query && !evtCtx.campaign) {
+      evtCtx.campaign = utm(query)
+    }
+
+    const amp = ampId()
+    if (amp) {
+      evtCtx.amp = { id: amp }
+    }
+
+    referrerId(
+      query,
+      evtCtx,
+      this.instance.options.disableClientPersistence ?? false
+    )
+
+    try {
+      evtCtx.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+    } catch (_) {
+      // If browser doesn't have support leave timezone undefined
+    }
+
+    return ctx
+  }
+
+  track = this.enrich
+  identify = this.enrich
+  page = this.enrich
+  group = this.enrich
+  alias = this.enrich
+  screen = this.enrich
+}
+
+export const envEnrichment = new EnvironmentEnrichmentPlugin()