@customerio/cdp-analytics-core 0.0.1

package/src/context/index.ts

@@ -0,0 +1,123 @@
+import { CoreCustomerioEvent } from '../events/interfaces'
+
+import { v4 as uuid } from '@lukeed/uuid'
+import { dset } from 'dset'
+import { CoreLogger, LogLevel, LogMessage } from '../logger'
+import { CoreStats, CoreMetric, NullStats } from '../stats'
+
+export interface SerializedContext {
+  id: string
+  event: CoreCustomerioEvent
+  logs: LogMessage[]
+  metrics?: CoreMetric[]
+}
+
+export interface ContextFailedDelivery {
+  reason: unknown
+}
+
+export interface CancelationOptions {
+  retry?: boolean
+  reason?: string
+  type?: string
+}
+
+export class ContextCancelation {
+  retry: boolean
+  type: string
+  reason?: string
+
+  constructor(options: CancelationOptions) {
+    this.retry = options.retry ?? true
+    this.type = options.type ?? 'plugin Error'
+    this.reason = options.reason ?? ''
+  }
+}
+
+export abstract class CoreContext<
+  Event extends CoreCustomerioEvent = CoreCustomerioEvent
+> {
+  event: Event
+  logger: CoreLogger
+  stats: CoreStats
+  attempts = 0
+
+  private _failedDelivery?: ContextFailedDelivery
+  private _id: string
+
+  constructor(
+    event: Event,
+    id = uuid(),
+    stats: CoreStats = new NullStats(),
+    logger = new CoreLogger()
+  ) {
+    this.event = event
+    this._id = id
+    this.logger = logger
+    this.stats = stats
+  }
+
+  static system(): void {
+    // This should be overridden by the subclass to return an instance of the subclass.
+  }
+
+  isSame(other: CoreContext): boolean {
+    return other.id === this.id
+  }
+
+  cancel(error?: Error | ContextCancelation): never {
+    if (error) {
+      throw error
+    }
+
+    throw new ContextCancelation({ reason: 'Context Cancel' })
+  }
+
+  log(level: LogLevel, message: string, extras?: object): void {
+    this.logger.log(level, message, extras)
+  }
+
+  get id(): string {
+    return this._id
+  }
+
+  updateEvent(path: string, val: unknown): Event {
+    // Don't allow integrations that are set to false to be overwritten with integration settings.
+    if (path.split('.')[0] === 'integrations') {
+      const integrationName = path.split('.')[1]
+
+      if (this.event.integrations?.[integrationName] === false) {
+        return this.event
+      }
+    }
+
+    dset(this.event, path, val)
+    return this.event
+  }
+
+  failedDelivery(): ContextFailedDelivery | undefined {
+    return this._failedDelivery
+  }
+
+  setFailedDelivery(options: ContextFailedDelivery) {
+    this._failedDelivery = options
+  }
+
+  logs(): LogMessage[] {
+    return this.logger.logs
+  }
+
+  flush(): void {
+    this.logger.flush()
+    this.stats.flush()
+  }
+
+  toJSON(): SerializedContext {
+    return {
+      id: this._id,
+      event: this.event,
+      logs: this.logger.logs,
+      metrics: this.stats.metrics,
+    }
+  }
+}

package/src/emitter/index.ts

@@ -0,0 +1,65 @@
+type EventName = string
+type EventFnArgs = any[]
+type EmitterContract = Record<EventName, EventFnArgs>
+
+/**
+ * Event Emitter that takes the expected contract as a generic
+ * @example
+ * ```ts
+ *  type Contract = {
+ *    delivery_success: [DeliverySuccessResponse, Metrics],
+ *    delivery_failure: [DeliveryError]
+ * }
+ *  new Emitter<Contract>()
+ *  .on('delivery_success', (res, metrics) => ...)
+ *  .on('delivery_failure', (err) => ...)
+ * ```
+ */
+export class Emitter<Contract extends EmitterContract = EmitterContract> {
+  private callbacks: Partial<Contract> = {}
+  on<EventName extends keyof Contract>(
+    event: EventName,
+    callback: (...args: Contract[EventName]) => void
+  ): this {
+    if (!this.callbacks[event]) {
+      this.callbacks[event] = [callback] as Contract[EventName]
+    } else {
+      this.callbacks[event]!.push(callback)
+    }
+    return this
+  }
+
+  once<EventName extends keyof Contract>(
+    event: EventName,
+    callback: (...args: Contract[EventName]) => void
+  ): this {
+    const on = (...args: Contract[EventName]): void => {
+      this.off(event, on)
+      callback.apply(this, args)
+    }
+
+    this.on(event, on)
+    return this
+  }
+
+  off<EventName extends keyof Contract>(
+    event: EventName,
+    callback: (...args: Contract[EventName]) => void
+  ): this {
+    const fns = this.callbacks[event] ?? []
+    const without = fns.filter((fn) => fn !== callback) as Contract[EventName]
+    this.callbacks[event] = without
+    return this
+  }
+
+  emit<EventName extends keyof Contract>(
+    event: EventName,
+    ...args: Contract[EventName]
+  ): this {
+    const callbacks = this.callbacks[event] ?? []
+    callbacks.forEach((callback) => {
+      callback.apply(this, args)
+    })
+    return this
+  }
+}

package/src/emitter/interface.ts

@@ -0,0 +1,31 @@
+import { CoreContext } from '../context'
+
+/**
+ * This is the base contract for all emitted errors. This interface may be extended.
+ */
+export interface CoreEmittedError<Ctx extends CoreContext> {
+  /**
+   * e.g. 'delivery_failure'
+   */
+  code: string
+  /**
+   * Why the error occurred. This can be an actual error object or a just a message.
+   */
+  reason?: unknown
+  ctx?: Ctx
+}
+
+export type CoreEmitterContract<
+  Ctx extends CoreContext,
+  Err extends CoreEmittedError<Ctx> = CoreEmittedError<Ctx>
+> = {
+  alias: [ctx: Ctx]
+  track: [ctx: Ctx]
+  identify: [ctx: Ctx]
+  page: [ctx: Ctx]
+  screen: [ctx: Ctx]
+  group: [ctx: Ctx]
+  register: [pluginNames: string[]]
+  deregister: [pluginNames: string[]]
+  error: [error: Err]
+}

package/src/events/index.ts

@@ -0,0 +1,280 @@
+export * from './interfaces'
+import { dset } from 'dset'
+import { ID, User } from '../user'
+import {
+  Integrations,
+  EventProperties,
+  CoreCustomerioEvent,
+  CoreOptions,
+  CoreExtraContext,
+  UserTraits,
+  GroupTraits,
+} from './interfaces'
+import { pickBy } from '../utils/pick'
+import { validateEvent } from '../validation/assertions'
+import type { RemoveIndexSignature } from '../utils/ts-helpers'
+
+interface EventFactorySettings {
+  createMessageId: () => string
+  user?: User
+}
+
+export class EventFactory {
+  createMessageId: EventFactorySettings['createMessageId']
+  user?: User
+
+  constructor(settings: EventFactorySettings) {
+    this.user = settings.user
+    this.createMessageId = settings.createMessageId
+  }
+
+  track(
+    event: string,
+    properties?: EventProperties,
+    options?: CoreOptions,
+    globalIntegrations?: Integrations
+  ) {
+    return this.normalize({
+      ...this.baseEvent(),
+      event,
+      type: 'track',
+      properties: properties ?? {}, // TODO: why is this not a shallow copy like everywhere else?
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    })
+  }
+
+  page(
+    category: string | null,
+    page: string | null,
+    properties?: EventProperties,
+    options?: CoreOptions,
+    globalIntegrations?: Integrations
+  ): CoreCustomerioEvent {
+    const event: CoreCustomerioEvent = {
+      type: 'page',
+      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,
+    })
+  }
+
+  screen(
+    category: string | null,
+    screen: string | null,
+    properties?: EventProperties,
+    options?: CoreOptions,
+    globalIntegrations?: Integrations
+  ): CoreCustomerioEvent {
+    const event: CoreCustomerioEvent = {
+      type: 'screen',
+      properties: { ...properties },
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    }
+
+    if (category !== null) {
+      event.category = category
+    }
+
+    if (screen !== null) {
+      event.name = screen
+    }
+
+    return this.normalize({
+      ...this.baseEvent(),
+      ...event,
+    })
+  }
+
+  identify(
+    userId: ID,
+    traits?: UserTraits,
+    options?: CoreOptions,
+    globalIntegrations?: Integrations
+  ): CoreCustomerioEvent {
+    return this.normalize({
+      ...this.baseEvent(),
+      type: 'identify',
+      userId,
+      traits: traits ?? {},
+      options: { ...options },
+      integrations: globalIntegrations,
+    })
+  }
+
+  group(
+    groupId: ID,
+    traits?: GroupTraits,
+    options?: CoreOptions,
+    globalIntegrations?: Integrations
+  ): CoreCustomerioEvent {
+    return this.normalize({
+      ...this.baseEvent(),
+      type: 'group',
+      traits: traits ?? {},
+      options: { ...options }, // this spreading is intentional
+      integrations: { ...globalIntegrations }, //
+      groupId,
+    })
+  }
+
+  alias(
+    to: string,
+    from: string | null, // TODO: can we make this undefined?
+    options?: CoreOptions,
+    globalIntegrations?: Integrations
+  ): CoreCustomerioEvent {
+    const base: CoreCustomerioEvent = {
+      userId: to,
+      type: 'alias',
+      options: { ...options },
+      integrations: { ...globalIntegrations },
+    }
+
+    if (from !== null) {
+      base.previousId = from
+    }
+
+    if (to === undefined) {
+      return this.normalize({
+        ...base,
+        ...this.baseEvent(),
+      })
+    }
+
+    return this.normalize({
+      ...this.baseEvent(),
+      ...base,
+    })
+  }
+
+  private baseEvent(): Partial<CoreCustomerioEvent> {
+    const base: Partial<CoreCustomerioEvent> = {
+      integrations: {},
+      options: {},
+    }
+
+    if (!this.user) return base
+
+    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(
+    options: CoreOptions
+  ): [CoreExtraContext, Partial<CoreCustomerioEvent>] {
+    type CoreOptionKeys = keyof RemoveIndexSignature<CoreOptions>
+    /**
+     * If the event options are known keys from this list, we move them to the top level of the event.
+     * Any other options are moved to context.
+     */
+    const eventOverrideKeys: CoreOptionKeys[] = [
+      'userId',
+      'anonymousId',
+      'timestamp',
+    ]
+
+    delete options['integrations']
+    const providedOptionsKeys = Object.keys(options) as Exclude<
+      CoreOptionKeys,
+      'integrations'
+    >[]
+
+    const context = options.context ?? {}
+    const eventOverrides = {}
+
+    providedOptionsKeys.forEach((key) => {
+      if (key === 'context') {
+        return
+      }
+
+      if (eventOverrideKeys.includes(key)) {
+        dset(eventOverrides, key, options[key])
+      } else {
+        dset(context, key, options[key])
+      }
+    })
+
+    return [context, eventOverrides]
+  }
+
+  public normalize(event: CoreCustomerioEvent): CoreCustomerioEvent {
+    const integrationBooleans = Object.keys(event.integrations ?? {}).reduce(
+      (integrationNames, name) => {
+        return {
+          ...integrationNames,
+          [name]: Boolean(event.integrations?.[name]),
+        }
+      },
+      {} as Record<string, boolean>
+    )
+
+    // filter out any undefined options
+    event.options = pickBy(event.options || {}, (_, value) => {
+      return value !== undefined
+    })
+
+    // 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] = event.options
+      ? this.context(event.options)
+      : []
+
+    const { options, ...rest } = event
+
+    const body = {
+      timestamp: new Date(),
+      ...rest,
+      integrations: allIntegrations,
+      context,
+      ...overrides,
+    }
+
+    const evt: CoreCustomerioEvent = {
+      ...body,
+      messageId: this.createMessageId(),
+    }
+
+    validateEvent(evt)
+    return evt
+  }
+}