@ht-sdks/events-sdk-js-browser 1.0.4

package/src/core/events/interfaces.ts

@@ -0,0 +1,36 @@
+import {
+  CoreOptions,
+  CoreSegmentEvent,
+  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 SegmentEvent extends CoreSegmentEvent {}
+
+export type {
+  Integrations,
+  Plan,
+  TrackPlan,
+  PlanEvent,
+  Callback,
+  JSONArray,
+  JSONValue,
+  JSONPrimitive,
+  JSONObject,
+}

package/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/src/core/page/add-page-context.ts

@@ -0,0 +1,33 @@
+import { pick } from '../../lib/pick'
+import { EventProperties, SegmentEvent } 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: SegmentEvent,
+  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/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 Segment 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/src/core/page/index.ts

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

package/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/src/core/query-string/gracefulDecodeURIComponent.ts

@@ -0,0 +1,16 @@
+/**
+ * Tries to gets the unencoded version of an encoded component of a
+ * Uniform Resource Identifier (URI). If input string is malformed,
+ * returns it back as-is.
+ *
+ * Note: All occurences of the `+` character become ` ` (spaces).
+ **/
+export function gracefulDecodeURIComponent(
+  encodedURIComponent: string
+): string {
+  try {
+    return decodeURIComponent(encodedURIComponent.replace(/\+/g, ' '))
+  } catch {
+    return encodedURIComponent
+  }
+}

package/src/core/query-string/index.ts

@@ -0,0 +1,64 @@
+import { pickPrefix } from './pickPrefix'
+import { gracefulDecodeURIComponent } from './gracefulDecodeURIComponent'
+import { Analytics } from '../analytics'
+import { Context } from '../context'
+import { isPlainObject } from '@ht-sdks/events-sdk-js-core'
+
+export interface QueryStringParams {
+  [key: string]: string | null
+}
+
+export function queryString(
+  analytics: Analytics,
+  query: string
+): Promise<Context[]> {
+  const a = document.createElement('a')
+  a.href = query
+  const parsed = a.search.slice(1)
+  const params = parsed.split('&').reduce((acc: QueryStringParams, str) => {
+    const [k, v] = str.split('=')
+    acc[k] = gracefulDecodeURIComponent(v)
+    return acc
+  }, {})
+
+  const calls = []
+
+  const { ajs_uid, ajs_event, ajs_aid } = params
+  const { aid: aidPattern = /.+/, uid: uidPattern = /.+/ } = isPlainObject(
+    analytics.options.useQueryString
+  )
+    ? analytics.options.useQueryString
+    : {}
+
+  if (ajs_aid) {
+    const anonId = Array.isArray(params.ajs_aid)
+      ? params.ajs_aid[0]
+      : params.ajs_aid
+
+    if (aidPattern.test(anonId)) {
+      analytics.setAnonymousId(anonId)
+    }
+  }
+
+  if (ajs_uid) {
+    const uid = Array.isArray(params.ajs_uid)
+      ? params.ajs_uid[0]
+      : params.ajs_uid
+
+    if (uidPattern.test(uid)) {
+      const traits = pickPrefix('ajs_trait_', params)
+
+      calls.push(analytics.identify(uid, traits))
+    }
+  }
+
+  if (ajs_event) {
+    const event = Array.isArray(params.ajs_event)
+      ? params.ajs_event[0]
+      : params.ajs_event
+    const props = pickPrefix('ajs_prop_', params)
+    calls.push(analytics.track(event, props))
+  }
+
+  return Promise.all(calls)
+}

package/src/core/query-string/pickPrefix.ts

@@ -0,0 +1,20 @@
+import { QueryStringParams } from '.'
+
+/**
+ * Returns an object containing only the properties prefixed by the input
+ * string.
+ * Ex: prefix('ajs_traits_', { ajs_traits_address: '123 St' })
+ * will return { address: '123 St' }
+ **/
+export function pickPrefix(
+  prefix: string,
+  object: QueryStringParams
+): QueryStringParams {
+  return Object.keys(object).reduce((acc: QueryStringParams, key: string) => {
+    if (key.startsWith(prefix)) {
+      const field = key.substr(prefix.length)
+      acc[field] = object[key]!
+    }
+    return acc
+  }, {})
+}

package/src/core/queue/event-queue.ts

@@ -0,0 +1,22 @@
+import { PriorityQueue } from '../../lib/priority-queue'
+import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
+import { Context } from '../context'
+import { AnyBrowserPlugin } from '../plugin'
+import { CoreEventQueue } from '@ht-sdks/events-sdk-js-core'
+import { isOffline } from '../connection'
+
+export class EventQueue extends CoreEventQueue<Context, AnyBrowserPlugin> {
+  constructor(name: string)
+  constructor(priorityQueue: PriorityQueue<Context>)
+  constructor(nameOrQueue: string | PriorityQueue<Context>) {
+    super(
+      typeof nameOrQueue === 'string'
+        ? new PersistedPriorityQueue(4, nameOrQueue)
+        : nameOrQueue
+    )
+  }
+  async flush(): Promise<Context[]> {
+    if (isOffline()) return []
+    return super.flush()
+  }
+}

package/src/core/session/index.ts

@@ -0,0 +1,107 @@
+// https://github.com/rudderlabs/rudder-sdk-js/blob/3a818accd24e6b3667c75a6b60fb12aba36bdf7e/packages/analytics-js/LICENSE
+// MIT License
+
+// Copyright (c) 2021 RudderStack
+
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+export type SessionInfo = {
+  autoTrack?: boolean
+  manualTrack?: boolean
+  timeout?: number
+  expiresAt?: number
+  id?: number
+  sessionStart?: boolean
+}
+
+export type SessionContext = {
+  sessionId?: number
+  sessionStart?: boolean
+}
+
+/**
+ * A function to validate current session and return true/false depending on that
+ * @returns boolean
+ */
+export const hasSessionExpired = (expiresAt: number): boolean => {
+  const timestamp = Date.now()
+  return Boolean(timestamp > expiresAt)
+}
+
+const generateSessionId = (): number => Date.now()
+
+export const isManualSessionIdValid = (sessionId?: number): boolean => {
+  if (
+    !sessionId ||
+    sessionId.toString().startsWith('-') ||
+    sessionId.toString().length < 10
+  ) {
+    return false
+  }
+  return true
+}
+
+const MIN_SESSION_TIMEOUT_MS = 10 * 1000 // 10 seconds
+const DEFAULT_SESSION_TIMEOUT_MS = 30 * 60 * 1000 // 30 minutes
+
+/**
+ * A function to generate new auto tracking session
+ * @param sessionTimeout current timestamp
+ * @returns SessionInfo
+ */
+export const generateAutoTrackingSession = (
+  sessionTimeout?: number
+): SessionInfo => {
+  const timestamp = Date.now()
+  const timeout: number = sessionTimeout || DEFAULT_SESSION_TIMEOUT_MS
+  if (timeout < MIN_SESSION_TIMEOUT_MS) {
+    console.warn('Session timeouts of less than 10 seconds are not recommended')
+  }
+  return {
+    id: timestamp, // set the current timestamp
+    expiresAt: timestamp + timeout, // set the expiry time of the session
+    timeout,
+    sessionStart: true,
+    autoTrack: true,
+  }
+}
+
+/**
+ * A function to generate new manual tracking session
+ * @param id Provided sessionId
+ * @returns SessionInfo
+ */
+export const generateManualTrackingSession = (id?: number): SessionInfo => {
+  const sessionId: number = isManualSessionIdValid(id)
+    ? (id as number)
+    : generateSessionId()
+  return {
+    id: sessionId,
+    sessionStart: true,
+    manualTrack: true,
+  }
+}
+
+export const updateSessionExpiration = (session: SessionInfo): SessionInfo => {
+  session.sessionStart = false
+  if (session.autoTrack) {
+    session.expiresAt = session.expiresAt! + session.timeout!
+  }
+  return session
+}

package/src/core/stats/index.ts

@@ -0,0 +1,15 @@
+import { CoreStats } from '@ht-sdks/events-sdk-js-core'
+import { MetricsOptions, RemoteMetrics } from './remote-metrics'
+
+let remoteMetrics: RemoteMetrics | undefined
+
+export class Stats extends CoreStats {
+  static initRemoteMetrics(options?: MetricsOptions) {
+    remoteMetrics = new RemoteMetrics(options)
+  }
+
+  override increment(metric: string, by?: number, tags?: string[]): void {
+    super.increment(metric, by, tags)
+    remoteMetrics?.increment(metric, tags ?? [])
+  }
+}

package/src/core/stats/remote-metrics.ts

@@ -0,0 +1,144 @@
+import { fetch } from '../../lib/fetch'
+import { version } from '../../generated/version'
+import { getVersionType } from '../../lib/version-type'
+import { HIGHTOUCH_API_HOST } from '../constants'
+
+export interface MetricsOptions {
+  host?: string
+  sampleRate?: number
+  flushTimer?: number
+  maxQueueSize?: number
+}
+
+/**
+ * Type expected by the segment metrics API endpoint
+ */
+type RemoteMetric = {
+  type: 'Counter'
+  metric: string
+  value: 1
+  tags: {
+    library: string
+    library_version: string
+    [key: string]: string
+  }
+}
+
+const createRemoteMetric = (
+  metric: string,
+  tags: string[],
+  versionType: 'web' | 'npm'
+): RemoteMetric => {
+  const formattedTags = tags.reduce((acc, t) => {
+    const [k, v] = t.split(':')
+    acc[k] = v
+    return acc
+  }, {} as Record<string, string>)
+
+  return {
+    type: 'Counter',
+    metric,
+    value: 1,
+    tags: {
+      ...formattedTags,
+      library: 'analytics.js',
+      library_version:
+        versionType === 'web' ? `next-${version}` : `npm:next-${version}`,
+    },
+  }
+}
+
+function logError(err: unknown): void {
+  console.error('Error sending hightouch performance metrics', err)
+}
+
+export class RemoteMetrics {
+  private host: string
+  private flushTimer: number
+  private maxQueueSize: number
+
+  sampleRate: number
+  queue: RemoteMetric[]
+
+  constructor(options?: MetricsOptions) {
+    this.host = options?.host ?? HIGHTOUCH_API_HOST
+    this.sampleRate = options?.sampleRate ?? 1
+    this.flushTimer = options?.flushTimer ?? 30 * 1000 /* 30s */
+    this.maxQueueSize = options?.maxQueueSize ?? 20
+
+    this.queue = []
+
+    if (this.sampleRate > 0) {
+      let flushing = false
+
+      const run = (): void => {
+        if (flushing) {
+          return
+        }
+
+        flushing = true
+        this.flush().catch(logError)
+
+        flushing = false
+
+        setTimeout(run, this.flushTimer)
+      }
+      run()
+    }
+  }
+
+  increment(metric: string, tags: string[]): void {
+    // All metrics are part of an allow list in Tracking API
+    if (!metric.includes('analytics_js.')) {
+      return
+    }
+
+    // /m doesn't like empty tags
+    if (tags.length === 0) {
+      return
+    }
+
+    if (Math.random() > this.sampleRate) {
+      return
+    }
+
+    if (this.queue.length >= this.maxQueueSize) {
+      return
+    }
+
+    const remoteMetric = createRemoteMetric(metric, tags, getVersionType())
+    this.queue.push(remoteMetric)
+
+    if (metric.includes('error')) {
+      this.flush().catch(logError)
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.queue.length <= 0) {
+      return
+    }
+
+    await this.send().catch((error) => {
+      logError(error)
+      this.sampleRate = 0
+    })
+  }
+
+  private async send(): Promise<Response> {
+    const payload = { series: this.queue }
+    this.queue = []
+
+    const headers = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    }
+    const url = `https://${this.host}/v1/m`
+
+    return fetch(url, {
+      headers,
+      body: JSON.stringify(payload),
+      method: 'POST',
+    })
+  }
+}