utneque 1.0.0

package/packages/core/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/packages/core/src/events/__tests__/index.test.ts

@@ -0,0 +1,394 @@
+import { EventFactory } from '..'
+import { User } from '../../user'
+import { CoreHightouchEvent } from '../..'
+import { isDate } from 'lodash'
+
+describe('Event Factory', () => {
+  let factory: EventFactory
+  let user: User
+  const shoes = { product: 'shoes', total: '$35', category: 'category' }
+  const shopper = { totalSpent: 100 }
+
+  beforeEach(() => {
+    user = {
+      anonymousId: () => undefined,
+      id: () => 'foo',
+    }
+    factory = new EventFactory({
+      user,
+      createMessageId: () => 'foo',
+    })
+  })
+
+  describe('alias', () => {
+    test('creates alias events', () => {
+      const alias = factory.alias('netto', 'netto farah')
+
+      expect(alias.type).toEqual('alias')
+      expect(alias.event).toBeUndefined()
+
+      expect(alias.userId).toEqual('netto')
+      expect(alias.previousId).toEqual('netto farah')
+    })
+
+    it('does not accept traits or properties', () => {
+      // TODO: you can still pass traits here in the options object?
+      const alias = factory.alias('netto', 'netto farah')
+      expect(alias.traits).toBeUndefined()
+      expect(alias.properties).toBeUndefined()
+    })
+  })
+
+  describe('group', () => {
+    test('creates group events', () => {
+      const group = factory.group('userId', { coolkids: true })
+
+      expect(group.traits).toEqual({ coolkids: true })
+      expect(group.type).toEqual('group')
+      expect(group.event).toBeUndefined()
+      expect(group.userId).toBe('foo')
+      expect(group.anonymousId).toBeUndefined()
+    })
+
+    it('accepts traits', () => {
+      const group = factory.group('netto', shopper)
+      expect(group.traits).toEqual(shopper)
+    })
+
+    it('sets the groupId to the message', () => {
+      const group = factory.group('coolKidsId', { coolkids: true })
+      expect(group.groupId).toEqual('coolKidsId')
+    })
+
+    it('allows userId / anonymousId to be specified as an option', () => {
+      const group = factory.group('my_group_id', undefined, {
+        userId: 'bar',
+        anonymousId: 'foo',
+      })
+      expect(group.userId).toBe('bar')
+      expect(group.anonymousId).toBe('foo')
+    })
+
+    it('allows userId / anonymousId to be overridden', function () {
+      const group = factory.group('my_group_id', undefined, {
+        userId: 'bar',
+        anonymousId: 'foo',
+      })
+      expect(group.userId).toBe('bar')
+      expect(group.anonymousId).toBe('foo')
+    })
+
+    it('uses userId / anonymousId from the user class (if specified)', function () {
+      factory = new EventFactory({
+        createMessageId: () => 'foo',
+        user: {
+          id: () => 'abc',
+          anonymousId: () => '123',
+        },
+      })
+      const group = factory.group('my_group_id')
+      expect(group.userId).toBe('abc')
+      expect(group.anonymousId).toBe('123')
+    })
+
+    test('should be capable of working with empty traits', () => {
+      expect(() => factory.group('foo')).not.toThrow()
+      expect(() => factory.group('foo', null as any)).not.toThrow()
+    })
+  })
+
+  describe('page', () => {
+    test('creates page events', () => {
+      const page = factory.page('category', 'name')
+      expect(page.traits).toBeUndefined()
+      expect(page.type).toEqual('page')
+      expect(page.event).toBeUndefined()
+      expect(page.name).toEqual('name')
+      expect(page.category).toEqual('category')
+    })
+
+    it('accepts properties', () => {
+      const page = factory.page('category', 'name', shoes)
+      expect(page.properties).toEqual(shoes)
+    })
+
+    it('ignores category and page if not passed in', () => {
+      const page = factory.page(null, null)
+      expect(page.category).toBeUndefined()
+      expect(page.name).toBeUndefined()
+    })
+  })
+
+  describe('identify', () => {
+    test('creates identify events', () => {
+      const identify = factory.identify('Netto', shopper)
+      expect(identify.traits).toEqual(shopper)
+      expect(identify.properties).toBeUndefined()
+      expect(identify.type).toEqual('identify')
+      expect(identify.event).toBeUndefined()
+    })
+    test('should be capable of working with empty traits', () => {
+      expect(() => factory.identify('foo')).not.toThrow()
+      expect(() => factory.identify('foo', null as any)).not.toThrow()
+    })
+
+    test('should coerce nullish traits to empty object', () => {
+      const id = factory.identify('Order Completed')
+      expect(id.traits).toEqual({})
+      expect(id.properties).toBe(undefined)
+    })
+  })
+
+  describe('track', () => {
+    test('should only accept object literals as properties', () => {
+      expect(() => factory.track('track', [])).toThrowError(/properties/)
+    })
+
+    test('creates track events', () => {
+      const track = factory.track('Order Completed', shoes)
+      expect(track.event).toEqual('Order Completed')
+      expect(track.properties).toEqual(shoes)
+      expect(track.traits).toBeUndefined()
+      expect(track.type).toEqual('track')
+    })
+
+    test('adds a message id', () => {
+      const track = factory.track('Order Completed', shoes)
+      expect(typeof track.messageId).toBe('string')
+    })
+
+    test('adds a timestamp', () => {
+      const track = factory.track('Order Completed', shoes)
+      expect(track.timestamp).toBeInstanceOf(Date)
+    })
+
+    test('sets an user id', () => {
+      user.id = () => '007'
+
+      const track = factory.track('Order Completed', shoes)
+      expect(track.userId).toEqual('007')
+    })
+
+    test('sets an anonymous id', () => {
+      user.anonymousId = () => 'foo'
+
+      const track = factory.track('Order Completed', shoes)
+      expect(track.anonymousId).toEqual(user.anonymousId())
+    })
+
+    test('sets options in the context', () => {
+      const track = factory.track('Order Completed', shoes, {
+        opt1: true,
+      })
+      expect(track.context).toEqual({ opt1: true })
+    })
+
+    test('sets integrations', () => {
+      const track = factory.track(
+        'Order Completed',
+        shoes,
+        {},
+        {
+          amplitude: false,
+        }
+      )
+
+      expect(track.integrations).toEqual({ amplitude: false })
+    })
+
+    test('merges integrations from `options` and `integrations`', () => {
+      const track = factory.track(
+        'Order Completed',
+        shoes,
+        {
+          opt1: true,
+          integrations: {
+            amplitude: false,
+          },
+        },
+        {
+          googleAnalytics: true,
+          amplitude: true,
+        }
+      )
+
+      expect(track.integrations).toEqual({
+        googleAnalytics: true,
+        amplitude: false,
+      })
+    })
+
+    test('do not send integration settings overrides from initialization', () => {
+      const track = factory.track(
+        'Order Completed',
+        shoes,
+        {
+          integrations: {
+            Amplitude: {
+              sessionId: 'session_123',
+            },
+          },
+        },
+        {
+          'Hightouch.io': {
+            apiHost: 'custom',
+          },
+          GoogleAnalytics: false,
+
+          'Customer.io': {},
+        }
+      )
+
+      expect(track.integrations).toEqual({
+        // do not pass Hightouch.io global settings
+        'Hightouch.io': true,
+        // accept amplitude event level settings
+        Amplitude: {
+          sessionId: 'session_123',
+        },
+        // pass along google analytics setting
+        GoogleAnalytics: false,
+        // empty objects are still valid
+        'Customer.io': true,
+      })
+    })
+
+    test('should move foreign options into `context`', () => {
+      const track = factory.track('Order Completed', shoes, {
+        opt1: true,
+        opt2: '🥝',
+        integrations: {
+          amplitude: false,
+        },
+      })
+
+      expect(track.context).toEqual({ opt1: true, opt2: '🥝' })
+    })
+
+    test('should not move known options into `context`', () => {
+      const track = factory.track('Order Completed', shoes, {
+        opt1: true,
+        opt2: '🥝',
+        integrations: {
+          amplitude: false,
+        },
+        anonymousId: 'anon-1',
+        timestamp: new Date(),
+      })
+
+      expect(track.context).toEqual({ opt1: true, opt2: '🥝' })
+    })
+
+    test('accepts an anonymous id', () => {
+      const track = factory.track('Order Completed', shoes, {
+        anonymousId: 'anon-1',
+      })
+
+      expect(track.context).toEqual({})
+      expect(track.anonymousId).toEqual('anon-1')
+    })
+
+    test('accepts a timestamp', () => {
+      const timestamp = new Date()
+      const track = factory.track('Order Completed', shoes, {
+        timestamp,
+      })
+
+      expect(track.context).toEqual({})
+      expect(track.timestamp).toEqual(timestamp)
+    })
+
+    test('accepts traits', () => {
+      const track = factory.track('Order Completed', shoes, {
+        traits: {
+          cell: '📱',
+        },
+      })
+      expect(track.traits).toEqual(undefined) // This seems silly -- should we change this??
+
+      expect(track.context?.traits).toEqual({
+        cell: '📱',
+      })
+    })
+
+    test('accepts a context object', () => {
+      const track = factory.track('Order Completed', shoes, {
+        context: {
+          library: {
+            name: 'ajs-next',
+            version: '0.1.0',
+          },
+        },
+      })
+
+      expect(track.context).toEqual({
+        library: {
+          name: 'ajs-next',
+          version: '0.1.0',
+        },
+      })
+    })
+
+    test('merges a context object', () => {
+      const track = factory.track('Order Completed', shoes, {
+        foreignProp: '🇧🇷',
+        context: {
+          innerProp: '👻',
+          library: {
+            name: 'ajs-next',
+            version: '0.1.0',
+          },
+        },
+      })
+
+      expect(track.context).toEqual({
+        library: {
+          name: 'ajs-next',
+          version: '0.1.0',
+        },
+        foreignProp: '🇧🇷',
+        innerProp: '👻',
+      })
+    })
+  })
+
+  describe('normalize', () => {
+    it('should merge original with normalized', () => {
+      const msg: CoreHightouchEvent = {
+        type: 'track',
+        event: 'My Event',
+        properties: {},
+        options: {
+          integrations: { Hightouch: true },
+        },
+        userId: 'user-id',
+      }
+      const normalized = factory['normalize'](msg)
+
+      delete normalized.messageId
+
+      expect(normalized.timestamp).toBeInstanceOf(Date)
+      delete normalized.timestamp
+
+      expect(normalized).toStrictEqual({
+        type: msg.type,
+        event: msg.event,
+        userId: msg.userId,
+        properties: msg.properties,
+        integrations: { Hightouch: true },
+        context: {},
+      })
+    })
+  })
+
+  it('should ignore undefined options', () => {
+    const event = factory.track(
+      'Order Completed',
+      { ...shoes },
+      { timestamp: undefined, traits: { foo: 123 } }
+    )
+
+    expect(typeof event.timestamp).toBe('object')
+    expect(isDate(event.timestamp)).toBeTruthy()
+  })
+})

package/packages/core/src/events/index.ts

@@ -0,0 +1,280 @@
+export * from './interfaces'
+import { dset } from 'dset'
+import { ID, User } from '../user'
+import {
+  Integrations,
+  EventProperties,
+  CoreHightouchEvent,
+  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
+  ): CoreHightouchEvent {
+    const event: CoreHightouchEvent = {
+      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
+  ): CoreHightouchEvent {
+    const event: CoreHightouchEvent = {
+      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
+  ): CoreHightouchEvent {
+    return this.normalize({
+      ...this.baseEvent(),
+      type: 'identify',
+      userId,
+      traits: traits ?? {},
+      options: { ...options },
+      integrations: globalIntegrations,
+    })
+  }
+
+  group(
+    groupId: ID,
+    traits?: GroupTraits,
+    options?: CoreOptions,
+    globalIntegrations?: Integrations
+  ): CoreHightouchEvent {
+    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
+  ): CoreHightouchEvent {
+    const base: CoreHightouchEvent = {
+      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<CoreHightouchEvent> {
+    const base: Partial<CoreHightouchEvent> = {
+      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<CoreHightouchEvent>] {
+    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: CoreHightouchEvent): CoreHightouchEvent {
+    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: CoreHightouchEvent = {
+      ...body,
+      messageId: this.createMessageId(),
+    }
+
+    validateEvent(evt)
+    return evt
+  }
+}