@customerio/cdp-analytics-node 0.0.1

package/src/app/analytics-node.ts

@@ -0,0 +1,295 @@
+import {
+  CoreAnalytics,
+  bindAll,
+  pTimeout,
+} from '@customerio/cdp-analytics-core'
+import { AnalyticsSettings, validateSettings } from './settings'
+import { version } from '../generated/version'
+import { createConfiguredNodePlugin } from '../plugins/customerio'
+import { NodeEventFactory } from './event-factory'
+import { Callback, dispatchAndEmit } from './dispatch-emit'
+import { NodeEmitter } from './emitter'
+import {
+  AliasParams,
+  GroupParams,
+  IdentifyParams,
+  PageParams,
+  TrackParams,
+  Plugin,
+  CustomerioEvent,
+} from './types'
+import { Context } from './context'
+import { NodeEventQueue } from './event-queue'
+
+export class Analytics extends NodeEmitter implements CoreAnalytics {
+  private readonly _eventFactory: NodeEventFactory
+  private _isClosed = false
+  private _pendingEvents = 0
+  private readonly _closeAndFlushDefaultTimeout: number
+  private readonly _publisher: ReturnType<
+    typeof createConfiguredNodePlugin
+  >['publisher']
+
+  private readonly _queue: NodeEventQueue
+
+  ready: Promise<void>
+
+  constructor(settings: AnalyticsSettings) {
+    super()
+    validateSettings(settings)
+
+    this._eventFactory = new NodeEventFactory()
+    this._queue = new NodeEventQueue()
+
+    const flushInterval = settings.flushInterval ?? 10000
+
+    this._closeAndFlushDefaultTimeout = flushInterval * 1.25 // add arbitrary multiplier in case an event is in a plugin.
+
+    const { plugin, publisher } = createConfiguredNodePlugin(
+      {
+        writeKey: settings.writeKey,
+        host: settings.host,
+        path: settings.path,
+        maxRetries: settings.maxRetries ?? 3,
+        maxEventsInBatch: settings.maxEventsInBatch ?? 15,
+        httpRequestTimeout: settings.httpRequestTimeout,
+        flushInterval,
+      },
+      this as NodeEmitter
+    )
+    this._publisher = publisher
+    this.ready = this.register(plugin).then(() => undefined)
+
+    this.emit('initialize', settings)
+
+    bindAll(this)
+  }
+
+  get VERSION() {
+    return version
+  }
+
+  /**
+   * Call this method to stop collecting new events and flush all existing events.
+   * This method also waits for any event method-specific callbacks to be triggered,
+   * and any of their subsequent promises to be resolved/rejected.
+   */
+  public closeAndFlush({
+    timeout = this._closeAndFlushDefaultTimeout,
+  }: {
+    /** Set a maximum time permitted to wait before resolving. */
+    timeout?: number
+  } = {}): Promise<void> {
+    this._publisher.flushAfterClose(this._pendingEvents)
+    this._isClosed = true
+    const promise = new Promise<void>((resolve) => {
+      if (!this._pendingEvents) {
+        resolve()
+      } else {
+        this.once('drained', () => resolve())
+      }
+    })
+    return timeout ? pTimeout(promise, timeout).catch(() => undefined) : promise
+  }
+
+  private _dispatch(CustomerioEvent: CustomerioEvent, callback?: Callback) {
+    if (this._isClosed) {
+      this.emit('call_after_close', CustomerioEvent as CustomerioEvent)
+      return undefined
+    }
+
+    this._pendingEvents++
+
+    dispatchAndEmit(CustomerioEvent, this._queue, this, callback)
+      .catch((ctx) => ctx)
+      .finally(() => {
+        this._pendingEvents--
+
+        if (!this._pendingEvents) {
+          this.emit('drained')
+        }
+      })
+  }
+
+  /**
+   * Combines two unassociated user identities.
+   */
+  alias(
+    { userId, previousId, context, timestamp, integrations }: AliasParams,
+    callback?: Callback
+  ): void {
+    const CustomerioEvent = this._eventFactory.alias(userId, previousId, {
+      context,
+      integrations,
+      timestamp,
+    })
+    this._dispatch(CustomerioEvent, callback)
+  }
+
+  /**
+   * Associates an identified user with a collective.
+   */
+  group(
+    {
+      timestamp,
+      groupId,
+      userId,
+      anonymousId,
+      traits = {},
+      context,
+      integrations,
+    }: GroupParams,
+    callback?: Callback
+  ): void {
+    const CustomerioEvent = this._eventFactory.group(groupId, traits, {
+      context,
+      anonymousId,
+      userId,
+      timestamp,
+      integrations,
+    })
+
+    this._dispatch(CustomerioEvent, callback)
+  }
+
+  /**
+   * Includes a unique userId and (maybe anonymousId) and any optional traits you know about them.
+   */
+  identify(
+    {
+      userId,
+      anonymousId,
+      traits = {},
+      context,
+      timestamp,
+      integrations,
+    }: IdentifyParams,
+    callback?: Callback
+  ): void {
+    const CustomerioEvent = this._eventFactory.identify(userId, traits, {
+      context,
+      anonymousId,
+      userId,
+      timestamp,
+      integrations,
+    })
+    this._dispatch(CustomerioEvent, callback)
+  }
+
+  /**
+   * The page method lets you record page views on your website, along with optional extra information about the page being viewed.
+   */
+  page(
+    {
+      userId,
+      anonymousId,
+      category,
+      name,
+      properties,
+      context,
+      timestamp,
+      integrations,
+    }: PageParams,
+    callback?: Callback
+  ): void {
+    const CustomerioEvent = this._eventFactory.page(
+      category ?? null,
+      name ?? null,
+      properties,
+      { context, anonymousId, userId, timestamp, integrations }
+    )
+    this._dispatch(CustomerioEvent, callback)
+  }
+
+  /**
+   * Records screen views on your app, along with optional extra information
+   * about the screen viewed by the user.
+   */
+  screen(
+    {
+      userId,
+      anonymousId,
+      category,
+      name,
+      properties,
+      context,
+      timestamp,
+      integrations,
+    }: PageParams,
+    callback?: Callback
+  ): void {
+    const CustomerioEvent = this._eventFactory.screen(
+      category ?? null,
+      name ?? null,
+      properties,
+      { context, anonymousId, userId, timestamp, integrations }
+    )
+
+    this._dispatch(CustomerioEvent, callback)
+  }
+
+  /**
+   * Records actions your users perform.
+   */
+  track(
+    {
+      userId,
+      anonymousId,
+      event,
+      properties,
+      context,
+      timestamp,
+      integrations,
+    }: TrackParams,
+    callback?: Callback
+  ): void {
+    const CustomerioEvent = this._eventFactory.track(event, properties, {
+      context,
+      userId,
+      anonymousId,
+      timestamp,
+      integrations,
+    })
+
+    this._dispatch(CustomerioEvent, callback)
+  }
+
+  /**
+   * Registers one or more plugins to augment Analytics functionality.
+   * @param plugins
+   */
+  register(...plugins: Plugin[]): Promise<void> {
+    return this._queue.criticalTasks.run(async () => {
+      const ctx = Context.system()
+
+      const registrations = plugins.map((xt) =>
+        this._queue.register(ctx, xt, this)
+      )
+      await Promise.all(registrations)
+      this.emit(
+        'register',
+        plugins.map((el) => el.name)
+      )
+    })
+  }
+
+  /**
+   * Deregisters one or more plugins based on their names.
+   * @param pluginNames - The names of one or more plugins to deregister.
+   */
+  async deregister(...pluginNames: string[]): Promise<void> {
+    const ctx = Context.system()
+
+    const deregistrations = pluginNames.map((pl) => {
+      const plugin = this._queue.plugins.find((p) => p.name === pl)
+      if (plugin) {
+        return this._queue.deregister(ctx, plugin, this)
+      } else {
+        ctx.log('warn', `plugin ${pl} not found`)
+      }
+    })
+
+    await Promise.all(deregistrations)
+    this.emit('deregister', pluginNames)
+  }
+}

package/src/app/context.ts

@@ -0,0 +1,11 @@
+// create a derived class since we may want to add node specific things to Context later
+
+import { CoreContext } from '@customerio/cdp-analytics-core'
+import { CustomerioEvent } from './types'
+
+// While this is not a type, it is a definition
+export class Context extends CoreContext<CustomerioEvent> {
+  static override system() {
+    return new this({ type: 'track', event: 'system' })
+  }
+}

package/src/app/dispatch-emit.ts

@@ -0,0 +1,42 @@
+import { dispatch } from '@customerio/cdp-analytics-core'
+import type { NodeEmitter } from './emitter'
+import { Context } from './context'
+import { NodeEventQueue } from './event-queue'
+import { CustomerioEvent } from './types'
+
+export type Callback = (err?: unknown, ctx?: Context) => void
+
+const normalizeDispatchCb = (cb: Callback) => (ctx: Context) => {
+  const failedDelivery = ctx.failedDelivery()
+  return failedDelivery ? cb(failedDelivery.reason, ctx) : cb(undefined, ctx)
+}
+
+/* Dispatch function, but swallow promise rejections and use event emitter instead */
+export const dispatchAndEmit = async (
+  event: CustomerioEvent,
+  queue: NodeEventQueue,
+  emitter: NodeEmitter,
+  callback?: Callback
+): Promise<void> => {
+  try {
+    const context = new Context(event)
+    const ctx = await dispatch(context, queue, emitter, {
+      ...(callback ? { callback: normalizeDispatchCb(callback) } : {}),
+    })
+    const failedDelivery = ctx.failedDelivery()
+    if (failedDelivery) {
+      emitter.emit('error', {
+        code: 'delivery_failure',
+        reason: failedDelivery.reason,
+        ctx: ctx,
+      })
+    } else {
+      emitter.emit(event.type, ctx)
+    }
+  } catch (err) {
+    emitter.emit('error', {
+      code: 'unknown',
+      reason: err,
+    })
+  }
+}

package/src/app/emitter.ts

@@ -0,0 +1,23 @@
+import { CoreEmitterContract, Emitter } from '@customerio/cdp-analytics-core'
+import { Context } from './context'
+import type { AnalyticsSettings } from './settings'
+import { CustomerioEvent } from './types'
+
+/**
+ * Map of emitter event names to method args.
+ */
+export type NodeEmitterEvents = CoreEmitterContract<Context> & {
+  initialize: [AnalyticsSettings]
+  call_after_close: [CustomerioEvent] // any event that did not get dispatched due to close
+  http_request: [
+    {
+      url: string
+      method: string
+      headers: Record<string, string>
+      body: string
+    }
+  ]
+  drained: []
+}
+
+export class NodeEmitter extends Emitter<NodeEmitterEvents> { }

package/src/app/event-factory.ts

@@ -0,0 +1,20 @@
+import { EventFactory } from '@customerio/cdp-analytics-core'
+import { createMessageId } from '../lib/get-message-id'
+import { CustomerioEvent } from './types'
+
+// use declaration merging to downcast CoreCustomerioEvent without adding any runtime code.
+// if/when we decide to add an actual implementation to NodeEventFactory that actually changes the event shape, we can remove this.
+export interface NodeEventFactory {
+  alias(...args: Parameters<EventFactory['alias']>): CustomerioEvent
+  group(...args: Parameters<EventFactory['group']>): CustomerioEvent
+  identify(...args: Parameters<EventFactory['identify']>): CustomerioEvent
+  track(...args: Parameters<EventFactory['track']>): CustomerioEvent
+  page(...args: Parameters<EventFactory['page']>): CustomerioEvent
+  screen(...args: Parameters<EventFactory['screen']>): CustomerioEvent
+}
+
+export class NodeEventFactory extends EventFactory {
+  constructor() {
+    super({ createMessageId })
+  }
+}

package/src/app/event-queue.ts

@@ -0,0 +1,23 @@
+import { CoreEventQueue, PriorityQueue } from '@customerio/cdp-analytics-core'
+import type { Plugin } from '../app/types'
+import type { Context } from './context'
+
+class NodePriorityQueue extends PriorityQueue<Context> {
+  constructor() {
+    super(1, [])
+  }
+  // do not use an internal "seen" map
+  getAttempts(ctx: Context): number {
+    return ctx.attempts ?? 0
+  }
+  updateAttempts(ctx: Context): number {
+    ctx.attempts = this.getAttempts(ctx) + 1
+    return this.getAttempts(ctx)
+  }
+}
+
+export class NodeEventQueue extends CoreEventQueue<Context, Plugin> {
+  constructor() {
+    super(new NodePriorityQueue())
+  }
+}

package/src/app/settings.ts

@@ -0,0 +1,39 @@
+import { ValidationError } from '@customerio/cdp-analytics-core'
+
+export interface AnalyticsSettings {
+  /**
+   * Key for your workspace
+   */
+  writeKey: string
+  /**
+  /**
+   * The base URL of the API. Default: "https://cdp.customer.io"
+   */
+  host?: string
+  /**
+   * The API path route. Default: "/v1/batch"
+   */
+  path?: string
+  /**
+   * The number of times to retry flushing a batch. Default: 3
+   */
+  maxRetries?: number
+  /**
+   * The number of messages to enqueue before flushing. Default: 15
+   */
+  maxEventsInBatch?: number
+  /**
+   * The number of milliseconds to wait before flushing the queue automatically. Default: 10000
+   */
+  flushInterval?: number
+  /**
+   * The maximum number of milliseconds to wait for an http request. Default: 10000
+   */
+  httpRequestTimeout?: number
+}
+
+export const validateSettings = (settings: AnalyticsSettings) => {
+  if (!settings.writeKey) {
+    throw new ValidationError('writeKey', 'writeKey is missing.')
+  }
+}

package/src/app/types/event.ts

@@ -0,0 +1,7 @@
+import type { CoreCustomerioEvent } from '@customerio/cdp-analytics-core'
+
+type CustomerioEventType = 'track' | 'page' | 'identify' | 'alias' | 'screen'
+
+export interface CustomerioEvent extends CoreCustomerioEvent {
+  type: CustomerioEventType
+}

package/src/app/types/index.ts

@@ -0,0 +1,3 @@
+export * from './params'
+export * from './event'
+export * from './plugin'

package/src/app/types/params.ts

@@ -0,0 +1,74 @@
+import type {
+  GroupTraits,
+  UserTraits,
+  CoreExtraContext,
+  EventProperties,
+  Integrations,
+  Timestamp,
+} from '@customerio/cdp-analytics-core'
+
+export type { GroupTraits, UserTraits }
+
+/**
+ * A dictionary of extra context to attach to the call.
+ * Note: context differs from traits because it is not attributes of the user itself.
+ */
+export interface ExtraContext extends CoreExtraContext { }
+
+/**
+ * An ID associated with the user. Note: at least one of userId or anonymousId must be included.
+ **/
+type IdentityOptions =
+  | { userId: string; anonymousId?: string }
+  | { userId?: string; anonymousId: string }
+
+export type AliasParams = {
+  /* The new user id you want to associate with the user. */
+  userId: string
+  /* The previous id that the user was recognized by (this can be either a userId or an anonymousId). */
+  previousId: string
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+}
+
+export type GroupParams = {
+  groupId: string
+  /**
+   * Traits are pieces of information you know about a group.
+   */
+  traits?: GroupTraits
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+} & IdentityOptions
+
+export type IdentifyParams = {
+  /**
+   * Traits are pieces of information you know about a group.
+   */
+  traits?: UserTraits
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+} & IdentityOptions
+
+export type PageParams = {
+  /*  The category of the page. Useful for cases like ecommerce where many pages might live under a single category. */
+  category?: string
+  /* The name of the page.*/
+  name?: string
+  /* A dictionary of properties of the page. */
+  properties?: EventProperties
+  timestamp?: Timestamp
+  context?: ExtraContext
+  integrations?: Integrations
+} & IdentityOptions
+
+export type TrackParams = {
+  event: string
+  properties?: EventProperties
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+} & IdentityOptions

package/src/app/types/plugin.ts

@@ -0,0 +1,5 @@
+import type { CorePlugin } from '@customerio/cdp-analytics-core'
+import type { Analytics } from '../analytics-node'
+import type { Context } from '../context'
+
+export interface Plugin extends CorePlugin<Context, Analytics> { }

package/src/generated/version.ts

@@ -0,0 +1,2 @@
+// This file is generated.
+export const version = '1.0.0-beta.22'

package/src/index.ts

@@ -0,0 +1,17 @@
+export { Analytics } from './app/analytics-node'
+export { Context } from './app/context'
+export type {
+  Plugin,
+  GroupTraits,
+  UserTraits,
+  TrackParams,
+  IdentifyParams,
+  AliasParams,
+  GroupParams,
+  PageParams,
+} from './app/types'
+export type { AnalyticsSettings } from './app/settings'
+
+// export Analytics as both a named export and a default export (for backwards-compat. reasons)
+import { Analytics } from './app/analytics-node'
+export default Analytics

package/src/lib/abort.ts

@@ -0,0 +1,77 @@
+/**
+ * use non-native event emitter for the benefit of non-node runtimes like CF workers.
+ */
+import { Emitter } from '@customerio/cdp-analytics-core'
+import { detectRuntime } from './env'
+
+/**
+ * adapted from: https://www.npmjs.com/package/node-abort-controller
+ */
+class AbortSignal {
+  onabort: globalThis.AbortSignal['onabort'] = null
+  aborted = false
+  eventEmitter = new Emitter()
+
+  toString() {
+    return '[object AbortSignal]'
+  }
+  get [Symbol.toStringTag]() {
+    return 'AbortSignal'
+  }
+  removeEventListener(...args: Parameters<Emitter['off']>) {
+    this.eventEmitter.off(...args)
+  }
+  addEventListener(...args: Parameters<Emitter['on']>) {
+    this.eventEmitter.on(...args)
+  }
+  dispatchEvent(type: string) {
+    const event = { type, target: this }
+
+    const handlerName = `on${type}`
+
+    if (typeof (this as any)[handlerName] === 'function') {
+      ; (this as any)[handlerName](event)
+    }
+
+    this.eventEmitter.emit(type, event)
+  }
+}
+
+/**
+ * This polyfill is only neccessary to support versions of node < 14.17.
+ * Can be removed once node 14 support is dropped.
+ */
+class AbortController {
+  signal = new AbortSignal()
+  abort() {
+    if (this.signal.aborted) return
+
+    this.signal.aborted = true
+    this.signal.dispatchEvent('abort')
+  }
+  toString() {
+    return '[object AbortController]'
+  }
+  get [Symbol.toStringTag]() {
+    return 'AbortController'
+  }
+}
+
+/**
+ * @param timeoutMs - Set a request timeout, after which the request is cancelled.
+ */
+export const abortSignalAfterTimeout = (timeoutMs: number) => {
+  if (detectRuntime() === 'cloudflare-worker') {
+    return [] // TODO: this is broken in cloudflare workers, otherwise results in "A hanging Promise was canceled..." error.
+  }
+  const ac = new (global.AbortController || AbortController)()
+
+  const timeoutId = setTimeout(() => {
+    ac.abort()
+  }, timeoutMs)
+
+  // Allow Node.js processes to exit early if only the timeout is running
+  timeoutId?.unref?.()
+
+  return [ac.signal, timeoutId] as const
+}

package/src/lib/base-64-encode.ts

@@ -0,0 +1,14 @@
+/**
+ * Base64 encoder that works in browser, worker, node runtimes.
+ */
+export const b64encode = (str: string): string => {
+  if (
+    // in node env
+    typeof Buffer !== 'undefined'
+  ) {
+    return Buffer.from(str).toString('base64')
+  } else {
+    // in worker env
+    return btoa(str)
+  }
+}

package/src/lib/create-url.ts

@@ -0,0 +1,11 @@
+const stripTrailingSlash = (str: string) => str.replace(/\/$/, '')
+
+/**
+ *
+ * @param host e.g. "http://foo.com"
+ * @param path e.g. "/bar"
+ * @returns "e.g." "http://foo.com/bar"
+ */
+export const tryCreateFormattedUrl = (host: string, path?: string) => {
+  return stripTrailingSlash(new URL(path || '', host).href)
+}