utneque 1.0.0

package/packages/browser/src/core/events/index.ts

@@ -0,0 +1,280 @@
+import { v4 as uuid } from '@lukeed/uuid'
+import { dset } from 'dset'
+import { ID, User } from '../user'
+import {
+  Options,
+  Integrations,
+  EventProperties,
+  Traits,
+  HightouchEvent,
+} from './interfaces'
+import md5 from 'spark-md5'
+import { addPageContext, PageContext } from '../page'
+
+export * from './interfaces'
+
+export class EventFactory {
+  constructor(public user: User) {}
+
+  track(
+    event: string,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): HightouchEvent {
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        event,
+        type: 'track' as const,
+        properties,
+        options: { ...options },
+        integrations: { ...globalIntegrations },
+      },
+      pageCtx
+    )
+  }
+
+  page(
+    category: string | null,
+    page: string | null,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): HightouchEvent {
+    const event: Partial<HightouchEvent> = {
+      type: 'page' as const,
+      properties: { ...properties },
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    }
+
+    if (category !== null) {
+      event.category = category
+      event.properties = event.properties ?? {}
+      event.properties.category = category
+    }
+
+    if (page !== null) {
+      event.name = page
+    }
+
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        ...event,
+      } as HightouchEvent,
+      pageCtx
+    )
+  }
+
+  screen(
+    category: string | null,
+    screen: string | null,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): HightouchEvent {
+    const event: Partial<HightouchEvent> = {
+      type: 'screen' as const,
+      properties: { ...properties },
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    }
+
+    if (category !== null) {
+      event.category = category
+    }
+
+    if (screen !== null) {
+      event.name = screen
+    }
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        ...event,
+      } as HightouchEvent,
+      pageCtx
+    )
+  }
+
+  identify(
+    userId: ID,
+    traits?: Traits,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): HightouchEvent {
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        type: 'identify' as const,
+        userId,
+        traits,
+        options: { ...options },
+        integrations: { ...globalIntegrations },
+      },
+      pageCtx
+    )
+  }
+
+  group(
+    groupId: ID,
+    traits?: Traits,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): HightouchEvent {
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        type: 'group' as const,
+        traits,
+        options: { ...options },
+        integrations: { ...globalIntegrations },
+        groupId,
+      },
+      pageCtx
+    )
+  }
+
+  alias(
+    to: string,
+    from: string | null,
+    options?: Options,
+    globalIntegrations?: Integrations,
+    pageCtx?: PageContext
+  ): HightouchEvent {
+    const base: Partial<HightouchEvent> = {
+      userId: to,
+      type: 'alias' as const,
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    }
+
+    if (from !== null) {
+      base.previousId = from
+    }
+
+    if (to === undefined) {
+      return this.normalize({
+        ...base,
+        ...this.baseEvent(),
+      } as HightouchEvent)
+    }
+
+    return this.normalize(
+      {
+        ...this.baseEvent(),
+        ...base,
+      } as HightouchEvent,
+      pageCtx
+    )
+  }
+
+  private baseEvent(): Partial<HightouchEvent> {
+    const base: Partial<HightouchEvent> = {
+      integrations: {},
+      options: {},
+    }
+
+    const user = this.user
+
+    if (user.id()) {
+      base.userId = user.id()
+    }
+
+    if (user.anonymousId()) {
+      base.anonymousId = user.anonymousId()
+    }
+
+    return base
+  }
+
+  /**
+   * Builds the context part of an event based on "foreign" keys that
+   * are provided in the `Options` parameter for an Event
+   */
+  private context(event: HightouchEvent): [object, object] {
+    const optionsKeys = ['integrations', 'anonymousId', 'timestamp', 'userId']
+
+    const options = event.options ?? {}
+    delete options['integrations']
+
+    const providedOptionsKeys = Object.keys(options)
+
+    const context = event.options?.context ?? {}
+    const overrides = {}
+
+    providedOptionsKeys.forEach((key) => {
+      if (key === 'context') {
+        return
+      }
+
+      if (optionsKeys.includes(key)) {
+        dset(overrides, key, options[key])
+      } else {
+        dset(context, key, options[key])
+      }
+    })
+
+    return [context, overrides]
+  }
+
+  public normalize(
+    event: HightouchEvent,
+    pageCtx?: PageContext
+  ): HightouchEvent {
+    // set anonymousId globally if we encounter an override
+    event.options?.anonymousId &&
+      this.user.anonymousId(event.options.anonymousId)
+
+    const integrationBooleans = Object.keys(event.integrations ?? {}).reduce(
+      (integrationNames, name) => {
+        return {
+          ...integrationNames,
+          [name]: Boolean(event.integrations?.[name]),
+        }
+      },
+      {} as Record<string, boolean>
+    )
+
+    // This is pretty trippy, but here's what's going on:
+    // - a) We don't pass initial integration options as part of the event, only if they're true or false
+    // - b) We do accept per integration overrides (like integrations.Amplitude.sessionId) at the event level
+    // Hence the need to convert base integration options to booleans, but maintain per event integration overrides
+    const allIntegrations = {
+      // Base config integrations object as booleans
+      ...integrationBooleans,
+
+      // Per event overrides, for things like amplitude sessionId, for example
+      ...event.options?.integrations,
+    }
+
+    const [context, overrides] = this.context(event)
+    const { options, ...rest } = event
+
+    const newEvent: HightouchEvent = {
+      timestamp: new Date(),
+      ...rest,
+      context,
+      integrations: allIntegrations,
+      ...overrides,
+      messageId: md5.hash(JSON.stringify(event) + uuid()),
+    }
+    addPageContext(newEvent, pageCtx)
+
+    const session = this.user.getAndUpdateSession()
+    if (session != null) {
+      newEvent.context = {
+        ...newEvent.context,
+        ...session,
+      }
+    }
+
+    return newEvent
+  }
+}

package/packages/browser/src/core/events/interfaces.ts

@@ -0,0 +1,36 @@
+import {
+  CoreOptions,
+  CoreHightouchEvent,
+  Callback,
+  Integrations,
+  Plan,
+  TrackPlan,
+  PlanEvent,
+  JSONArray,
+  JSONValue,
+  JSONPrimitive,
+  JSONObject,
+  GroupTraits,
+  UserTraits,
+  Traits,
+} from '@ht-sdks/events-sdk-js-core'
+
+export interface Options extends CoreOptions {}
+
+export type { GroupTraits, UserTraits, Traits }
+
+export type EventProperties = Record<string, any>
+
+export interface HightouchEvent extends CoreHightouchEvent {}
+
+export type {
+  Integrations,
+  Plan,
+  TrackPlan,
+  PlanEvent,
+  Callback,
+  JSONArray,
+  JSONValue,
+  JSONPrimitive,
+  JSONObject,
+}

package/packages/browser/src/core/inspector/index.ts

@@ -0,0 +1,14 @@
+import { getGlobal } from '../../lib/get-global'
+import type { Analytics } from '../analytics'
+
+const env = getGlobal()
+
+// The code below assumes the inspector extension will use Object.assign
+// to add the inspect interface on to this object reference (unless the
+// extension code ran first and has already set up the variable)
+const inspectorHost: {
+  attach: (analytics: Analytics) => void
+} = ((env as any)['__HIGHTOUCH_INSPECTOR__'] ??= {})
+
+export const attachInspector = (analytics: Analytics) =>
+  inspectorHost.attach?.(analytics as any)

package/packages/browser/src/core/page/__tests__/index.test.ts

@@ -0,0 +1,130 @@
+import {
+  BufferedPageContextDiscriminant,
+  getDefaultBufferedPageContext,
+  getDefaultPageContext,
+  isBufferedPageContext,
+} from '../'
+import { pickBy } from 'lodash'
+
+const originalLocation = window.location
+beforeEach(() => {
+  Object.defineProperty(window, 'location', {
+    value: {
+      ...originalLocation,
+    },
+    writable: true,
+  })
+})
+
+describe(isBufferedPageContext, () => {
+  it('should return true if object is page context', () => {
+    expect(isBufferedPageContext(getDefaultBufferedPageContext())).toBe(true)
+  })
+  it('should return false if object is not page context', () => {
+    expect(isBufferedPageContext(undefined)).toBe(false)
+    expect(isBufferedPageContext({})).toBe(false)
+    expect(isBufferedPageContext('')).toBe(false)
+    expect(isBufferedPageContext({ foo: false })).toBe(false)
+    expect(isBufferedPageContext({ u: 'hello' })).toBe(false)
+    expect(isBufferedPageContext(null)).toBe(false)
+
+    expect(
+      isBufferedPageContext({
+        ...getDefaultBufferedPageContext(),
+        some_unknown_key: 123,
+      })
+    ).toBe(false)
+
+    const missingDiscriminant = pickBy(
+      getDefaultBufferedPageContext(),
+      (v) => v !== BufferedPageContextDiscriminant
+    )
+    // should not be missing the dscriminant
+    expect(isBufferedPageContext(missingDiscriminant)).toBe(false)
+  })
+})
+
+describe(getDefaultPageContext, () => {
+  describe('hash', () => {
+    it('strips the hash from the URL', () => {
+      window.location.href = 'http://www.hightouch.local#test'
+      const defs = getDefaultPageContext()
+      expect(defs.url).toBe('http://www.hightouch.local')
+
+      window.location.href = 'http://www.hightouch.local/#test'
+      const defs2 = getDefaultPageContext()
+      expect(defs2.url).toBe('http://www.hightouch.local/')
+    })
+  })
+
+  describe('canonical URL', () => {
+    const el = document.createElement('link')
+    beforeEach(() => {
+      el.setAttribute('rel', 'canonical')
+      el.setAttribute('href', '')
+      document.clear()
+    })
+
+    it('returns location.href if canonical URL does not exist', () => {
+      el.setAttribute('rel', 'nope')
+      document.body.appendChild(el)
+      const defs = getDefaultPageContext()
+      expect(defs.url).toEqual(window.location.href)
+    })
+
+    it('does not throw an error if canonical URL is not a valid URL', () => {
+      el.setAttribute('href', 'foo.com/bar')
+      document.body.appendChild(el)
+      const defs = getDefaultPageContext()
+      expect(defs.url).toEqual('foo.com/bar') // this is analytics.js classic behavior
+      expect(defs.path).toEqual('/foo.com/bar') // this is analytics.js classic behavior
+    })
+
+    it('handles a leading slash', () => {
+      el.setAttribute('href', 'foo')
+      document.body.appendChild(el)
+      const defs = getDefaultPageContext()
+      expect(defs.url).toEqual('foo')
+      expect(defs.path).toEqual('/foo') // this is analytics.js classic behavior
+    })
+
+    it('handles canonical links', () => {
+      el.setAttribute('href', 'http://www.hightouch.local')
+      document.body.appendChild(el)
+      const defs = getDefaultPageContext()
+      expect(defs.url).toEqual('http://www.hightouch.local')
+    })
+
+    it('favors canonical path over location.pathname', () => {
+      window.location.pathname = '/nope'
+      el.setAttribute('href', 'http://www.hightouch.local/test')
+      document.body.appendChild(el)
+      const defs = getDefaultPageContext()
+      expect(defs.path).toEqual('/test')
+    })
+
+    it('handles canonical links with a path', () => {
+      el.setAttribute('href', 'http://www.hightouch.local/test')
+      document.body.appendChild(el)
+      const defs = getDefaultPageContext()
+      expect(defs.url).toEqual('http://www.hightouch.local/test')
+      expect(defs.path).toEqual('/test')
+    })
+
+    it('handles canonical links with search params in the url', () => {
+      el.setAttribute('href', 'http://www.hightouch.local?test=true')
+      document.body.appendChild(el)
+      const defs = getDefaultPageContext()
+      expect(defs.url).toEqual('http://www.hightouch.local?test=true')
+    })
+
+    it('will add search params from the document to the canonical path if it does not have search params', () => {
+      // This seems like weird behavior to me, but I found it in the codebase so adding a test for it.
+      window.location.search = '?foo=123'
+      el.setAttribute('href', 'http://www.hightouch.local')
+      document.body.appendChild(el)
+      const defs = getDefaultPageContext()
+      expect(defs.url).toEqual('http://www.hightouch.local?foo=123')
+    })
+  })
+})

package/packages/browser/src/core/page/add-page-context.ts

@@ -0,0 +1,33 @@
+import { pick } from '../../lib/pick'
+import { EventProperties, HightouchEvent } from '../events'
+import { getDefaultPageContext } from './get-page-context'
+
+/**
+ * Augments an event with information about the current page.
+ * Page information like URL changes frequently, so this is meant to be captured as close to the event call as possible.
+ * Things like `userAgent` do not change, so they can be added later in the flow.
+ * We prefer not to add this information to this function, as it increases the main bundle size.
+ */
+export const addPageContext = (
+  event: HightouchEvent,
+  pageCtx = getDefaultPageContext()
+): void => {
+  const evtCtx = event.context! // Context should be set earlier in the flow
+  let pageContextFromEventProps: Pick<EventProperties, string> | undefined
+  if (event.type === 'page') {
+    pageContextFromEventProps =
+      event.properties && pick(event.properties, Object.keys(pageCtx))
+
+    event.properties = {
+      ...pageCtx,
+      ...event.properties,
+      ...(event.name ? { name: event.name } : {}),
+    }
+  }
+
+  evtCtx.page = {
+    ...pageCtx,
+    ...pageContextFromEventProps,
+    ...evtCtx.page,
+  }
+}

package/packages/browser/src/core/page/get-page-context.ts

@@ -0,0 +1,140 @@
+import { isPlainObject } from '@ht-sdks/events-sdk-js-core'
+
+/**
+ * Final Page Context object expected in the Hightouch Event context
+ */
+export interface PageContext {
+  path: string
+  referrer: string
+  search: string
+  title: string
+  url: string
+}
+
+type CanonicalUrl = string | undefined
+
+export const BufferedPageContextDiscriminant = 'bpc' as const
+/**
+ * Page Context expected to be built by the snippet.
+ * Note: The key names are super short because we want to keep the strings in the html snippet short to save bytes.
+ */
+export interface BufferedPageContext {
+  __t: typeof BufferedPageContextDiscriminant // for extra uniqeness
+  c: CanonicalUrl
+  p: PageContext['path']
+  u: PageContext['url']
+  s: PageContext['search']
+  t: PageContext['title']
+  r: PageContext['referrer']
+}
+
+/**
+ * `BufferedPageContext` object builder
+ */
+export const createBufferedPageContext = (
+  url: string,
+  canonicalUrl: CanonicalUrl,
+  search: string,
+  path: string,
+  title: string,
+  referrer: string
+): BufferedPageContext => ({
+  __t: BufferedPageContextDiscriminant,
+  c: canonicalUrl,
+  p: path,
+  u: url,
+  s: search,
+  t: title,
+  r: referrer,
+})
+
+// my clever/dubious way of making sure this type guard does not get out sync with the type definition
+const BUFFERED_PAGE_CONTEXT_KEYS = Object.keys(
+  createBufferedPageContext('', '', '', '', '', '')
+) as (keyof BufferedPageContext)[]
+
+export function isBufferedPageContext(
+  bufferedPageCtx: unknown
+): bufferedPageCtx is BufferedPageContext {
+  if (!isPlainObject(bufferedPageCtx)) return false
+  if (bufferedPageCtx.__t !== BufferedPageContextDiscriminant) return false
+
+  // ensure obj has all the keys we expect, and none we don't.
+  for (const k in bufferedPageCtx) {
+    if (!BUFFERED_PAGE_CONTEXT_KEYS.includes(k as keyof BufferedPageContext)) {
+      return false
+    }
+  }
+  return true
+}
+
+//  Legacy logic: we are we appending search parameters to the canonical URL -- I guess the canonical URL is  "not canonical enough" (lol)
+const createCanonicalURL = (canonicalUrl: string, searchParams: string) => {
+  return canonicalUrl.indexOf('?') > -1
+    ? canonicalUrl
+    : canonicalUrl + searchParams
+}
+
+/**
+ * Strips hash from URL.
+ * http://www.hightouch.local#test -> http://www.hightouch.local
+ */
+const removeHash = (href: string) => {
+  const hashIdx = href.indexOf('#')
+  return hashIdx === -1 ? href : href.slice(0, hashIdx)
+}
+
+const parseCanonicalPath = (canonicalUrl: string): string => {
+  try {
+    return new URL(canonicalUrl).pathname
+  } catch (_e) {
+    // this is classic behavior -- we assume that if the canonical URL is invalid, it's a raw path.
+    return canonicalUrl[0] === '/' ? canonicalUrl : '/' + canonicalUrl
+  }
+}
+
+/**
+ * Create a `PageContext` from a `BufferedPageContext`.
+ * `BufferedPageContext` keys are minified to save bytes in the snippet.
+ */
+export const createPageContext = ({
+  c: canonicalUrl,
+  p: pathname,
+  s: search,
+  u: url,
+  r: referrer,
+  t: title,
+}: BufferedPageContext): PageContext => {
+  const newPath = canonicalUrl ? parseCanonicalPath(canonicalUrl) : pathname
+  const newUrl = canonicalUrl
+    ? createCanonicalURL(canonicalUrl, search)
+    : removeHash(url)
+  return {
+    path: newPath,
+    referrer,
+    search,
+    title,
+    url: newUrl,
+  }
+}
+
+/**
+ * Get page properties from the browser window/document.
+ */
+export const getDefaultBufferedPageContext = (): BufferedPageContext => {
+  const c = document.querySelector("link[rel='canonical']")
+  return createBufferedPageContext(
+    location.href,
+    (c && c.getAttribute('href')) || undefined,
+    location.search,
+    location.pathname,
+    document.title,
+    document.referrer
+  )
+}
+
+/**
+ * Get page properties from the browser window/document.
+ */
+export const getDefaultPageContext = (): PageContext =>
+  createPageContext(getDefaultBufferedPageContext())

package/packages/browser/src/core/page/index.ts

@@ -0,0 +1,2 @@
+export * from './get-page-context'
+export * from './add-page-context'

package/packages/browser/src/core/plugin/index.ts

@@ -0,0 +1,12 @@
+import type { CorePlugin } from '@ht-sdks/events-sdk-js-core'
+import type { DestinationMiddlewareFunction } from '../../plugins/middleware'
+import type { Analytics } from '../analytics'
+import type { Context } from '../context'
+
+export interface Plugin extends CorePlugin<Context, Analytics> {}
+
+export interface DestinationPlugin extends Plugin {
+  addMiddleware: (...fns: DestinationMiddlewareFunction[]) => void
+}
+
+export type AnyBrowserPlugin = Plugin | DestinationPlugin

package/packages/browser/src/core/query-string/__tests__/gracefulDecodeURIComponent.test.ts

@@ -0,0 +1,17 @@
+import { gracefulDecodeURIComponent } from '../gracefulDecodeURIComponent'
+
+describe('gracefulDecodeURIComponent', () => {
+  it('decodes a properly encoded URI component', () => {
+    const output = gracefulDecodeURIComponent(
+      'brown+fox+jumped+%40+the+fence%3F'
+    )
+
+    expect(output).toEqual('brown fox jumped @ the fence?')
+  })
+
+  it('returns the input string back as-is when input is malformed', () => {
+    const output = gracefulDecodeURIComponent('25%%2F35%')
+
+    expect(output).toEqual('25%%2F35%')
+  })
+})