@customerio/cdp-analytics-browser 0.0.1

package/src/core/events/index.ts

@@ -0,0 +1,254 @@
+import { v4 as uuid } from '@lukeed/uuid'
+import { dset } from 'dset'
+import { ID, User } from '../user'
+import {
+  Options,
+  Integrations,
+  EventProperties,
+  Traits,
+  CustomerioEvent,
+} from './interfaces'
+import md5 from 'spark-md5'
+
+export * from './interfaces'
+
+export class EventFactory {
+  user: User
+
+  constructor(user: User) {
+    this.user = user
+  }
+
+  track(
+    event: string,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations
+  ): CustomerioEvent {
+    return this.normalize({
+      ...this.baseEvent(),
+      event,
+      type: 'track' as const,
+      properties,
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    })
+  }
+
+  page(
+    category: string | null,
+    page: string | null,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations
+  ): CustomerioEvent {
+    const event: Partial<CustomerioEvent> = {
+      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 CustomerioEvent)
+  }
+
+  screen(
+    category: string | null,
+    screen: string | null,
+    properties?: EventProperties,
+    options?: Options,
+    globalIntegrations?: Integrations
+  ): CustomerioEvent {
+    const event: Partial<CustomerioEvent> = {
+      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 CustomerioEvent)
+  }
+
+  identify(
+    userId: ID,
+    traits?: Traits,
+    options?: Options,
+    globalIntegrations?: Integrations
+  ): CustomerioEvent {
+    return this.normalize({
+      ...this.baseEvent(),
+      type: 'identify' as const,
+      userId,
+      traits,
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    })
+  }
+
+  group(
+    groupId: ID,
+    traits?: Traits,
+    options?: Options,
+    globalIntegrations?: Integrations
+  ): CustomerioEvent {
+    return this.normalize({
+      ...this.baseEvent(),
+      type: 'group' as const,
+      traits,
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+      groupId,
+    })
+  }
+
+  alias(
+    to: string,
+    from: string | null,
+    options?: Options,
+    globalIntegrations?: Integrations
+  ): CustomerioEvent {
+    const base: Partial<CustomerioEvent> = {
+      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 CustomerioEvent)
+    }
+
+    return this.normalize({
+      ...this.baseEvent(),
+      ...base,
+    } as CustomerioEvent)
+  }
+
+  private baseEvent(): Partial<CustomerioEvent> {
+    const base: Partial<CustomerioEvent> = {
+      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: CustomerioEvent): [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: CustomerioEvent): CustomerioEvent {
+    // 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 body = {
+      timestamp: new Date(),
+      ...rest,
+      context,
+      integrations: allIntegrations,
+      ...overrides,
+    }
+
+    const messageId = 'ajs-next-' + md5.hash(JSON.stringify(body) + uuid())
+
+    const evt: CustomerioEvent = {
+      ...body,
+      messageId,
+    }
+
+    return evt
+  }
+}

package/src/core/events/interfaces.ts

@@ -0,0 +1,36 @@
+import {
+  CoreOptions,
+  CoreCustomerioEvent,
+  Callback,
+  Integrations,
+  Plan,
+  TrackPlan,
+  PlanEvent,
+  JSONArray,
+  JSONValue,
+  JSONPrimitive,
+  JSONObject,
+  GroupTraits,
+  UserTraits,
+  Traits,
+} from '@customerio/cdp-analytics-core'
+
+export interface Options extends CoreOptions { }
+
+export type { GroupTraits, UserTraits, Traits }
+
+export type EventProperties = Record<string, any>
+
+export interface CustomerioEvent extends CoreCustomerioEvent { }
+
+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)['__INSPECTOR__'] ??= {})
+
+export const attachInspector = (analytics: Analytics) =>
+  inspectorHost.attach?.(analytics as any)

package/src/core/plugin/index.ts

@@ -0,0 +1,12 @@
+import type { CorePlugin } from '@customerio/cdp-analytics-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 '@customerio/cdp-analytics-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,11 @@
+import { PriorityQueue } from '../../lib/priority-queue'
+import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
+import { Context } from '../context'
+import { AnyBrowserPlugin } from '../plugin'
+import { CoreEventQueue } from '@customerio/cdp-analytics-core'
+
+export class EventQueue extends CoreEventQueue<Context, AnyBrowserPlugin> {
+  constructor(priorityQueue?: PriorityQueue<Context>) {
+    super(priorityQueue ?? new PersistedPriorityQueue(4, 'event-queue'))
+  }
+}

package/src/core/stats/index.ts

@@ -0,0 +1,15 @@
+import { CoreStats } from '@customerio/cdp-analytics-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,137 @@
+import { fetch } from '../../lib/fetch'
+import { version } from '../../generated/version'
+import { getVersionType } from '../../plugins/customerio/normalize'
+
+export interface MetricsOptions {
+  host?: string
+  sampleRate?: number
+  flushTimer?: number
+  maxQueueSize?: number
+}
+
+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 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 ?? 'cdp.customer.io/v1'
+    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 = { 'Content-Type': 'text/plain' }
+    const url = `https://${this.host}/m`
+
+    return fetch(url, {
+      headers,
+      body: JSON.stringify(payload),
+      method: 'POST',
+    })
+  }
+}