@customerio/cdp-analytics-core 0.0.1

package/src/events/interfaces.ts

@@ -0,0 +1,447 @@
+import { CoreContext } from '../context'
+import { ID } from '../user'
+import { DeepNullable } from '../utils/ts-helpers'
+
+export type Callback<Ctx extends CoreContext = CoreContext> = (
+  ctx: Ctx
+) => Promise<unknown> | unknown
+
+export type CustomerioEventType =
+  | 'track'
+  | 'page'
+  | 'identify'
+  | 'group'
+  | 'alias'
+  | 'screen'
+
+export type JSONPrimitive = string | number | boolean | null
+export type JSONValue = JSONPrimitive | JSONObject | JSONArray
+export type JSONObject = { [member: string]: JSONValue }
+export type JSONArray = JSONValue[]
+
+export type EventProperties = Record<string, any>
+
+export type Integrations = {
+  All?: boolean
+  [integration: string]: boolean | JSONObject | undefined
+}
+
+export interface CoreOptions {
+  integrations?: Integrations
+  timestamp?: Timestamp
+  context?: CoreExtraContext
+  anonymousId?: string
+  userId?: string
+  traits?: Traits
+  // ugh, this is ugly, but we allow literally any property to be passed to options (which get spread onto the event)
+  [key: string]: any
+}
+
+/**
+ * Context is a dictionary of extra information that provides useful context about a datapoint, for example the user’s ip address or locale. You should only use Context fields for their intended meaning.
+ */
+export interface CoreExtraContext {
+  /**
+   * This is usually used to flag an .identify() call to just update the trait, rather than "last seen".
+   */
+  active?: boolean
+
+  /**
+   * Current user's IP address.
+   */
+  ip?: string
+
+  /**
+   * Locale string for the current user, for example en-US.
+   * @example en-US
+   */
+  locale?: string
+  /**
+   * Dictionary of information about the user’s current location.
+   */
+  location?: {
+    /**
+     * @example San Francisco
+     */
+    city?: string
+    /**
+     * @example United States
+     */
+    country?: string
+    /**
+     * @example 40.2964197
+     */
+    latitude?: string
+    /**
+     * @example -76.9411617
+     */
+    longitude?: string
+    /**
+     * @example CA
+     */
+    region?: string
+    /**
+     * @example 100
+     */
+    speed?: number
+  }
+
+  /**
+   * Dictionary of information about the current web page.
+   */
+  page?: {
+    /**
+     * @example /academy/
+     */
+    path?: string
+    /**
+     * @example https://www.foo.com/
+     */
+    referrer?: string
+    /**
+     * @example projectId=123
+     */
+    search?: string
+    /**
+     * @example Analytics Academy
+     */
+    title?: string
+    /**
+     * @example https://foobar.com/academy/
+     */
+    url?: string
+  }
+
+  /**
+   * User agent of the device making the request.
+   */
+  userAgent?: string
+
+  /**
+   * Information about the current library.
+   *
+   * **Automatically filled out by the library.**
+   *
+   * This type should probably be "never"
+   */
+  library?: {
+    /**
+     * @example analytics-node-next/latest
+     */
+    name: string
+    /**
+     * @example  "1.43.1"
+     */
+    version: string
+  }
+
+  /**
+   * This is useful in cases where you need to track an event,
+   * but also associate information from a previous identify call.
+   * You should fill this object the same way you would fill traits in an identify call.
+   */
+  traits?: Traits
+
+  /**
+   * Dictionary of information about the campaign that resulted in the API call, containing name, source, medium, term, content, and any other custom UTM parameter.
+   */
+  campaign?: {
+    name: string
+    term: string
+    source: string
+    medium: string
+    content: string
+  }
+
+  /**
+   * Dictionary of information about the way the user was referred to the website or app.
+   */
+  referrer?: {
+    type?: string
+    name?: string
+    url?: string
+    link?: string
+
+    id?: string // undocumented
+    btid?: string // undocumented?
+    urid?: string // undocumented?
+  }
+
+  amp?: {
+    // undocumented?
+    id: string
+  }
+
+  [key: string]: any
+}
+
+export interface CoreCustomerioEvent {
+  messageId?: string
+  type: CustomerioEventType
+
+  // page specific
+  category?: string
+  name?: string
+
+  properties?: EventProperties
+
+  traits?: Traits // Traits is only defined in 'identify' and 'group', even if it can be passed in other calls.
+
+  integrations?: Integrations
+  context?: CoreExtraContext
+  options?: CoreOptions
+
+  userId?: ID
+  anonymousId?: ID
+  groupId?: ID
+  previousId?: ID
+
+  event?: string
+
+  writeKey?: string
+
+  sentAt?: Date
+
+  _metadata?: CustomerioEventMetadata
+
+  timestamp?: Timestamp
+}
+
+export interface CustomerioEventMetadata {
+  failedInitializations?: unknown[]
+  bundled?: string[]
+  unbundled?: string[]
+  nodeVersion?: string
+  bundledConfigIds?: string[]
+  unbundledConfigIds?: string[]
+  bundledIds?: string[]
+}
+
+export type Timestamp = Date | string
+
+/**
+ * A Plan allows users to specify events and which destinations they would like them to be sent to
+ */
+export interface Plan {
+  track?: TrackPlan
+  identify?: TrackPlan
+  group?: TrackPlan
+}
+
+export interface TrackPlan {
+  [key: string]: PlanEvent | undefined
+  // __default SHOULD always exist, but marking as optional for extra safety.
+  __default?: PlanEvent
+}
+
+export interface PlanEvent {
+  /**
+   * Whether or not this plan event is enabled
+   */
+  enabled: boolean
+  /**
+   * Which integrations the plan event applies to
+   */
+  integrations?: {
+    [key: string]: boolean
+  }
+}
+
+type DbId = string | number // TODO: the docs says that this can only be a string?
+type PhoneNumber = string | number // TODO: the docs say this can only be a string?
+
+/**
+ * Traits are pieces of information you know about a group.
+ */
+type BaseGroupTraits = DeepNullable<{
+  /**
+   * Street address of a group.
+   */
+  address?: BaseUserTraits['address']
+
+  /**
+   * URL to an avatar image for the group.
+   */
+  avatar?: BaseUserTraits['avatar']
+
+  /**
+   * Date the group's account was first created. We recommend ISO-8601 date strings.
+   */
+  createdAt?: BaseUserTraits['createdAt']
+
+  /**
+   * Description of a group
+   */
+  description?: BaseUserTraits['description']
+  /**
+   * Email address of group.
+   */
+  email?: BaseUserTraits['email']
+  /**
+   * Number of employees of a group, typically used for companies.
+   */
+  employees?: string | number // TODO: the docs says that this must be a string?
+
+  /**
+   * Unique ID in your database for a group.
+   */
+  id?: BaseUserTraits['id']
+
+  /**
+   * Industry a group is part of.
+   */
+  industry?: BaseUserTraits['industry']
+
+  /**
+   * Name of a group.
+   */
+  name?: BaseUserTraits['name']
+
+  /**
+   * Phone number of a group
+   */
+  phone?: BaseUserTraits['phone']
+
+  /**
+   * Website of a group.
+   */
+  website?: BaseUserTraits['website']
+
+  /**
+   * 	Plan that a group is in.
+   */
+  plan?: BaseUserTraits['plan']
+}>
+
+/**
+ * Traits are pieces of information you know about a user.
+ */
+type BaseUserTraits = DeepNullable<{
+  /**
+   * Unique ID in your database for a user
+   */
+  id?: DbId
+
+  /**
+   * Industry a user works in
+   */
+  industry?: string
+
+  /**
+   * First name of a user.
+   */
+  firstName?: string
+
+  /**
+   * Last name of a user.
+   */
+  lastName?: string
+
+  /**
+   * Full name of a user. If you only pass a first and last name we will automatically fill in the full name for you.
+   */
+  name?: string
+
+  /**
+   * Phone number of a user
+   */
+  phone?: PhoneNumber
+
+  /**
+   * Title of a user, usually related to their position at a specific company.
+   * @example VP of Engineering
+   */
+  title?: string
+
+  /**
+   * User's username. This should be unique to each user, like the usernames of Twitter or GitHub.
+   */
+  username?: string
+
+  /**
+   * Website of a user.
+   */
+  website?: string
+
+  /**
+   * Street address of a user.
+   */
+  address?: {
+    city?: string
+    country?: string
+    postalCode?: string
+    state?: string
+    street?: string
+  }
+  /**
+   * Age of a user.
+   */
+  age?: number
+
+  /**
+   * URL to an avatar image for the user.
+   */
+  avatar?: string
+
+  /**
+   * User's birthday.
+   */
+  birthday?: Timestamp
+
+  /**
+   * User's company.
+   */
+  company?: {
+    name?: string
+    id?: DbId
+    industry?: BaseUserTraits['industry']
+    employee_count?: number
+    plan?: BaseUserTraits['plan']
+  }
+
+  /**
+    Plan that a user is in.
+
+   * @example enterprise
+   */
+  plan?: string
+
+  /**
+   * 	Date the user's account was first created. We recommend using ISO-8601 date strings.
+   */
+  createdAt?: Timestamp
+
+  /**
+   * Description of user, such as bio.
+   */
+  description?: string
+
+  /**
+   * Email address of a user.
+   */
+  email?: string
+
+  /**
+   * @example female
+   */
+  gender?: string
+}>
+
+/**
+ * Traits are pieces of information you know about a group.
+ */
+export type GroupTraits = BaseGroupTraits & {
+  [customTrait: string]: any
+}
+
+/**
+ * Traits are pieces of information you know about a user.
+ */
+export type UserTraits = BaseUserTraits & {
+  [customTrait: string]: any
+}
+
+/**
+ * Traits are pieces of information you know about a user or group.
+ */
+export type Traits = UserTraits | GroupTraits

package/src/index.ts

@@ -0,0 +1,18 @@
+export * from './emitter'
+export * from './emitter/interface'
+export * from './plugins'
+export * from './events/interfaces'
+export * from './events'
+export * from './callback'
+export * from './priority-queue'
+export { backoff } from './priority-queue/backoff'
+export * from './context'
+export * from './queue/event-queue'
+export * from './analytics'
+export * from './analytics/dispatch'
+export * from './validation/helpers'
+export * from './validation/assertions'
+export * from './utils/bind-all'
+export * from './stats'
+export { CoreLogger } from './logger'
+export * from './queue/delivery'

package/src/logger/index.ts

@@ -0,0 +1,74 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+export type LogMessage = {
+  level: LogLevel
+  message: string
+  time?: Date
+  extras?: Record<string, any>
+}
+
+export interface GenericLogger {
+  log(level: LogLevel, message: string, extras?: object): void
+  flush(): void
+  logs: LogMessage[]
+}
+
+export class CoreLogger implements GenericLogger {
+  private _logs: LogMessage[] = []
+
+  log(level: LogLevel, message: string, extras?: object) {
+    const time = new Date()
+    this._logs.push({
+      level,
+      message,
+      time,
+      extras,
+    })
+  }
+
+  public get logs(): LogMessage[] {
+    return this._logs
+  }
+
+  public flush(): void {
+    if (this.logs.length > 1) {
+      const formatted = this._logs.reduce((logs, log) => {
+        const line = {
+          ...log,
+          json: JSON.stringify(log.extras, null, ' '),
+          extras: log.extras,
+        }
+
+        delete line['time']
+
+        let key = log.time?.toISOString() ?? ''
+        if (logs[key]) {
+          key = `${key}-${Math.random()}`
+        }
+
+        return {
+          ...logs,
+          [key]: line,
+        }
+      }, {} as Record<string, LogMessage>)
+
+      // ie doesn't like console.table
+      if (console.table) {
+        console.table(formatted)
+      } else {
+        console.log(formatted)
+      }
+    } else {
+      this.logs.forEach((logEntry) => {
+        const { level, message, extras } = logEntry
+
+        if (level === 'info' || level === 'debug') {
+          console.log(message, extras ?? '')
+        } else {
+          console[level](message, extras ?? '')
+        }
+      })
+    }
+
+    this._logs = []
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,43 @@
+import type { CoreAnalytics } from '../analytics'
+import type { CoreContext } from '../context'
+
+interface CorePluginConfig {
+  options: any
+  priority: 'critical' | 'non-critical' // whether AJS should expect this plugin to be loaded before starting event delivery
+}
+
+export type PluginType =
+  | 'before'
+  | 'after'
+  | 'destination'
+  | 'enrichment'
+  | 'utility'
+
+// enrichment - modifies the event. Enrichment can happen in parallel, by reducing all changes in the final event. Failures in this stage could halt event delivery.
+// destination - runs in parallel at the end of the lifecycle. Cannot modify the event, can fail and not halt execution.
+// utility - do not affect lifecycle. Should be run and executed once. Their `track/identify` calls don't really do anything. example
+
+export interface CorePlugin<
+  Ctx extends CoreContext = CoreContext,
+  Analytics extends CoreAnalytics = any
+> {
+  name: string
+  alternativeNames?: string[]
+  version: string
+  type: PluginType
+  isLoaded: () => boolean
+  load: (
+    ctx: Ctx,
+    instance: Analytics,
+    config?: CorePluginConfig
+  ) => Promise<unknown>
+
+  unload?: (ctx: Ctx, instance: Analytics) => Promise<unknown> | unknown
+  ready?: () => Promise<unknown>
+  track?: (ctx: Ctx) => Promise<Ctx> | Ctx
+  identify?: (ctx: Ctx) => Promise<Ctx> | Ctx
+  page?: (ctx: Ctx) => Promise<Ctx> | Ctx
+  group?: (ctx: Ctx) => Promise<Ctx> | Ctx
+  alias?: (ctx: Ctx) => Promise<Ctx> | Ctx
+  screen?: (ctx: Ctx) => Promise<Ctx> | Ctx
+}

package/src/priority-queue/backoff.ts

@@ -0,0 +1,24 @@
+type BackoffParams = {
+  /** The number of milliseconds before starting the first retry. Default is 500 */
+  minTimeout?: number
+
+  /** The maximum number of milliseconds between two retries. Default is Infinity */
+  maxTimeout?: number
+
+  /** The exponential factor to use. Default is 2. */
+  factor?: number
+
+  /** The current attempt */
+  attempt: number
+}
+
+export function backoff(params: BackoffParams): number {
+  const random = Math.random() + 1
+  const {
+    minTimeout = 500,
+    factor = 2,
+    attempt,
+    maxTimeout = Infinity,
+  } = params
+  return Math.min(random * minTimeout * Math.pow(factor, attempt), maxTimeout)
+}

package/src/priority-queue/index.ts

@@ -0,0 +1,103 @@
+import { Emitter } from '../emitter'
+import { backoff } from './backoff'
+
+/**
+ * @internal
+ */
+export const ON_REMOVE_FROM_FUTURE = 'onRemoveFromFuture'
+
+interface QueueItem {
+  id: string
+}
+
+export class PriorityQueue<Item extends QueueItem = QueueItem> extends Emitter {
+  protected future: Item[] = []
+  protected queue: Item[]
+  protected seen: Record<string, number>
+
+  public maxAttempts: number
+
+  constructor(
+    maxAttempts: number,
+    queue: Item[],
+    seen?: Record<string, number>
+  ) {
+    super()
+    this.maxAttempts = maxAttempts
+    this.queue = queue
+    this.seen = seen ?? {}
+  }
+
+  push(...items: Item[]): boolean[] {
+    const accepted = items.map((operation) => {
+      const attempts = this.updateAttempts(operation)
+
+      if (attempts > this.maxAttempts || this.includes(operation)) {
+        return false
+      }
+
+      this.queue.push(operation)
+      return true
+    })
+
+    this.queue = this.queue.sort(
+      (a, b) => this.getAttempts(a) - this.getAttempts(b)
+    )
+    return accepted
+  }
+
+  pushWithBackoff(item: Item): boolean {
+    if (this.getAttempts(item) === 0) {
+      return this.push(item)[0]
+    }
+
+    const attempt = this.updateAttempts(item)
+
+    if (attempt > this.maxAttempts || this.includes(item)) {
+      return false
+    }
+
+    const timeout = backoff({ attempt: attempt - 1 })
+
+    setTimeout(() => {
+      this.queue.push(item)
+      // remove from future list
+      this.future = this.future.filter((f) => f.id !== item.id)
+      // Lets listeners know that a 'future' message is now available in the queue
+      this.emit(ON_REMOVE_FROM_FUTURE)
+    }, timeout)
+
+    this.future.push(item)
+    return true
+  }
+
+  public getAttempts(item: Item): number {
+    return this.seen[item.id] ?? 0
+  }
+
+  public updateAttempts(item: Item): number {
+    this.seen[item.id] = this.getAttempts(item) + 1
+    return this.getAttempts(item)
+  }
+
+  includes(item: Item): boolean {
+    return (
+      this.queue.includes(item) ||
+      this.future.includes(item) ||
+      Boolean(this.queue.find((i) => i.id === item.id)) ||
+      Boolean(this.future.find((i) => i.id === item.id))
+    )
+  }
+
+  pop(): Item | undefined {
+    return this.queue.shift()
+  }
+
+  public get length(): number {
+    return this.queue.length
+  }
+
+  public get todo(): number {
+    return this.queue.length + this.future.length
+  }
+}