utneque 1.0.0

package/packages/node/src/__tests__/integration.test.ts

@@ -0,0 +1,357 @@
+import { Plugin } from '../app/types'
+import { resolveCtx } from './test-helpers/resolve-ctx'
+import { testPlugin } from './test-helpers/test-plugin'
+import { createError } from './test-helpers/factories'
+import {
+  createTestAnalytics,
+  TestFetchClient,
+} from './test-helpers/create-test-analytics'
+
+const writeKey = 'foo'
+jest.setTimeout(10000)
+const timestamp = new Date()
+
+const testClient = new TestFetchClient()
+const makeReqSpy = jest.spyOn(testClient, 'makeRequest')
+
+describe('Settings / Configuration Init', () => {
+  it('throws if no writeKey', () => {
+    expect(() =>
+      createTestAnalytics({
+        writeKey: undefined as any,
+      })
+    ).toThrowError(/writeKey/i)
+  })
+
+  it('allows host/path to override default client', async () => {
+    const analytics = createTestAnalytics({
+      host: 'http://foo.com',
+      path: '/bar',
+      httpClient: testClient,
+    })
+    const track = resolveCtx(analytics, 'track')
+    analytics.track({ event: 'foo', userId: 'sup' })
+    await track
+    expect(makeReqSpy.mock.calls[0][0].url).toBe('http://foo.com/bar')
+  })
+
+  it('throws if host / path is bad', async () => {
+    expect(() =>
+      createTestAnalytics({
+        writeKey,
+        host: 'SHOULD_FAIL',
+        path: '/bar',
+      })
+    ).toThrowError()
+  })
+})
+
+describe('Error handling', () => {
+  it('surfaces property thrown errors', async () => {
+    const analytics = createTestAnalytics()
+    expect(() => analytics.track({} as any)).toThrowError(/event/i)
+  })
+
+  it('should emit on an error', async () => {
+    const err = createError({
+      statusText: 'Service Unavailable',
+      status: 503,
+    })
+    const analytics = createTestAnalytics({
+      maxRetries: 0,
+      httpClient: new TestFetchClient({ response: err }),
+    })
+    try {
+      const promise = resolveCtx(analytics, 'track')
+      analytics.track({ event: 'foo', userId: 'sup' })
+      await promise
+      throw new Error('fail')
+    } catch (err: any) {
+      expect(err.reason).toEqual(new Error('[503] Service Unavailable'))
+      expect(err.code).toMatch(/delivery_failure/)
+    }
+  })
+})
+
+describe('alias', () => {
+  it('generates alias events', async () => {
+    const analytics = createTestAnalytics()
+    analytics.alias({
+      userId: 'chris radek',
+      previousId: 'chris',
+      timestamp: timestamp,
+    })
+    const ctx = await resolveCtx(analytics, 'alias')
+
+    expect(ctx.event.userId).toEqual('chris radek')
+    expect(ctx.event.previousId).toEqual('chris')
+    expect(ctx.event.timestamp).toEqual(timestamp)
+  })
+})
+
+describe('group', () => {
+  const analytics = createTestAnalytics()
+  it('generates group events', async () => {
+    analytics.group({
+      groupId: 'coolKids',
+      traits: { coolKids: true },
+      userId: 'foo',
+      anonymousId: 'bar',
+      timestamp: timestamp,
+    })
+    const ctx = await resolveCtx(analytics, 'group')
+    expect(ctx.event.groupId).toEqual('coolKids')
+    expect(ctx.event.traits).toEqual({ coolKids: true })
+    expect(ctx.event.userId).toEqual('foo')
+    expect(ctx.event.anonymousId).toBe('bar')
+    expect(ctx.event.timestamp).toEqual(timestamp)
+  })
+
+  it('invocations are isolated', async () => {
+    const analytics = createTestAnalytics()
+    analytics.group({
+      groupId: 'coolKids',
+      traits: { foo: 'foo' },
+      anonymousId: 'unknown',
+    })
+    const ctx1 = await resolveCtx(analytics, 'group')
+
+    analytics.group({
+      groupId: 'coolKids',
+      traits: { bar: 'bar' },
+      userId: 'me',
+    })
+
+    const ctx2 = await resolveCtx(analytics, 'group')
+
+    expect(ctx1.event.traits).toEqual({ foo: 'foo' })
+    expect(ctx1.event.anonymousId).toEqual('unknown')
+    expect(ctx1.event.userId).toBeUndefined()
+
+    expect(ctx2.event.traits).toEqual({ bar: 'bar' })
+    expect(ctx2.event.anonymousId).toBeUndefined()
+    expect(ctx2.event.userId).toEqual('me')
+  })
+})
+
+describe('identify', () => {
+  it('generates identify events', async () => {
+    const analytics = createTestAnalytics()
+    analytics.identify({
+      timestamp: timestamp,
+      userId: 'user-id',
+      traits: {
+        name: 'Chris Radek',
+      },
+    })
+    const ctx1 = await resolveCtx(analytics, 'identify')
+
+    expect(ctx1.event.userId).toEqual('user-id')
+    expect(ctx1.event.anonymousId).toBeUndefined()
+    expect(ctx1.event.traits).toEqual({ name: 'Chris Radek' })
+    expect(ctx1.event.timestamp).toEqual(timestamp)
+
+    analytics.identify({ userId: 'user-id', anonymousId: 'unknown' })
+    const ctx2 = await resolveCtx(analytics, 'identify')
+
+    expect(ctx2.event.userId).toEqual('user-id')
+    expect(ctx2.event.anonymousId).toEqual('unknown')
+    expect(ctx2.event.traits).toEqual({})
+    expect(ctx2.event.timestamp).toEqual(expect.any(Date))
+  })
+})
+
+describe('page', () => {
+  it('generates page events', async () => {
+    const analytics = createTestAnalytics()
+    const category = 'Docs'
+    const name = 'How to write a test'
+    analytics.page({
+      category,
+      name,
+      anonymousId: 'unknown',
+      timestamp: timestamp,
+    })
+    const ctx1 = await resolveCtx(analytics, 'page')
+    expect(ctx1.event.type).toEqual('page')
+    expect(ctx1.event.name).toEqual(name)
+    expect(ctx1.event.anonymousId).toEqual('unknown')
+    expect(ctx1.event.userId).toBeUndefined()
+    expect(ctx1.event.properties).toEqual({ category })
+    expect(ctx1.event.timestamp).toEqual(timestamp)
+
+    analytics.page({ name, properties: { title: 'wip' }, userId: 'user-id' })
+
+    const ctx2 = await resolveCtx(analytics, 'page')
+
+    expect(ctx2.event.type).toEqual('page')
+    expect(ctx2.event.name).toEqual(name)
+    expect(ctx2.event.anonymousId).toBeUndefined()
+    expect(ctx2.event.userId).toEqual('user-id')
+    expect(ctx2.event.properties).toEqual({ title: 'wip' })
+    expect(ctx2.event.timestamp).toEqual(expect.any(Date))
+
+    analytics.page({ properties: { title: 'invisible' }, userId: 'user-id' })
+    const ctx3 = await resolveCtx(analytics, 'page')
+
+    expect(ctx3.event.type).toEqual('page')
+    expect(ctx3.event.name).toBeUndefined()
+    expect(ctx3.event.anonymousId).toBeUndefined()
+    expect(ctx3.event.userId).toEqual('user-id')
+    expect(ctx3.event.properties).toEqual({ title: 'invisible' })
+  })
+})
+
+describe('screen', () => {
+  it('generates screen events', async () => {
+    const analytics = createTestAnalytics()
+    const name = 'Home Screen'
+
+    analytics.screen({
+      name,
+      properties: { title: 'wip' },
+      userId: 'user-id',
+      timestamp: timestamp,
+    })
+
+    const ctx1 = await resolveCtx(analytics, 'screen')
+
+    expect(ctx1.event.type).toEqual('screen')
+    expect(ctx1.event.name).toEqual(name)
+    expect(ctx1.event.anonymousId).toBeUndefined()
+    expect(ctx1.event.userId).toEqual('user-id')
+    expect(ctx1.event.properties).toEqual({ title: 'wip' })
+    expect(ctx1.event.timestamp).toEqual(timestamp)
+
+    analytics.screen({
+      properties: { title: 'invisible' },
+      userId: 'user-id',
+    })
+
+    const ctx2 = await resolveCtx(analytics, 'screen')
+
+    expect(ctx2.event.type).toEqual('screen')
+    expect(ctx2.event.name).toBeUndefined()
+    expect(ctx2.event.anonymousId).toBeUndefined()
+    expect(ctx2.event.userId).toEqual('user-id')
+    expect(ctx2.event.properties).toEqual({ title: 'invisible' })
+    expect(ctx2.event.timestamp).toEqual(expect.any(Date))
+  })
+})
+
+describe('track', () => {
+  it('sends sentAt field in payload', async () => {
+    const analytics = createTestAnalytics({
+      httpClient: testClient,
+    })
+    const track = resolveCtx(analytics, 'track')
+    analytics.track({ event: 'hello', userId: 'foo' })
+    await track
+    expect(makeReqSpy.mock.calls[0][0].data.sentAt).toBeInstanceOf(Date)
+  })
+  it('generates track events', async () => {
+    const analytics = createTestAnalytics()
+    const eventName = 'Test Event'
+
+    analytics.track({
+      event: eventName,
+      anonymousId: 'unknown',
+      userId: 'known',
+      timestamp: timestamp,
+    })
+
+    const ctx1 = await resolveCtx(analytics, 'track')
+
+    expect(ctx1.event.type).toEqual('track')
+    expect(ctx1.event.event).toEqual(eventName)
+    expect(ctx1.event.properties).toEqual({})
+    expect(ctx1.event.anonymousId).toEqual('unknown')
+    expect(ctx1.event.userId).toEqual('known')
+    expect(ctx1.event.timestamp).toEqual(timestamp)
+
+    analytics.track({
+      event: eventName,
+      properties: { foo: 'bar' },
+      userId: 'known',
+    })
+    const ctx2 = await resolveCtx(analytics, 'track')
+
+    expect(ctx2.event.type).toEqual('track')
+    expect(ctx2.event.event).toEqual(eventName)
+    expect(ctx2.event.properties).toEqual({ foo: 'bar' })
+    expect(ctx2.event.anonymousId).toBeUndefined()
+    expect(ctx2.event.userId).toEqual('known')
+    expect(ctx2.event.timestamp).toEqual(expect.any(Date))
+  })
+})
+
+describe('register', () => {
+  it('registers a plugin', async () => {
+    const analytics = createTestAnalytics()
+    await analytics.register(testPlugin)
+
+    expect(testPlugin.load).toHaveBeenCalledTimes(1)
+  })
+
+  it('should wait for plugins to be registered before dispatching events', async () => {
+    const analytics = createTestAnalytics()
+    // TODO: ensure that this test _actually_ tests criticalTasks =S
+    analytics.identify({ userId: 'foo' })
+
+    const register = new Promise((resolve) =>
+      analytics.on('register', (plugins) => {
+        if (plugins.includes('Test Plugin')) {
+          resolve('register')
+        }
+      })
+    )
+    let resolveId: Function
+
+    const identifyPluginCall = new Promise((_resolve) => {
+      resolveId = _resolve
+    })
+    const plugin: Plugin = {
+      ...testPlugin,
+      identify: (ctx) => {
+        resolveId('identify')
+        return Promise.resolve(ctx)
+      },
+    }
+    void analytics.register(plugin)
+
+    const result = await Promise.race([identifyPluginCall, register])
+    expect(result).toEqual('register')
+    await identifyPluginCall
+  })
+})
+
+describe('deregister', () => {
+  it('deregisters a plugin given its name', async () => {
+    const analytics = createTestAnalytics()
+    await analytics.register(testPlugin)
+
+    await analytics.deregister(testPlugin.name)
+    expect(testPlugin.unload).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('version', () => {
+  it('should return the version', () => {
+    const analytics = createTestAnalytics()
+    expect(typeof +analytics.VERSION).toBe('number')
+  })
+})
+
+describe('ready', () => {
+  it('should only resolve when plugin registration is done', async () => {
+    const analytics = createTestAnalytics()
+    expect(analytics['_queue'].plugins.length).toBe(0)
+    const result = await analytics.ready
+    expect(result).toBeUndefined()
+    expect(analytics['_queue'].plugins.length).toBeGreaterThan(0)
+  })
+
+  it.todo(
+    'should not reject if a plugin fails registration during initialization?'
+  )
+})

package/packages/node/src/__tests__/plugins.test.ts

@@ -0,0 +1,16 @@
+import { createTestAnalytics } from './test-helpers/create-test-analytics'
+
+describe('Plugins', () => {
+  describe('Initialize', () => {
+    it('loads analytics-node-next plugin', async () => {
+      const analytics = createTestAnalytics()
+      await analytics.ready
+
+      const ajsNodeXt = analytics['_queue'].plugins.find(
+        (xt) => xt.name === 'Hightouch.io'
+      )
+      expect(ajsNodeXt).toBeDefined()
+      expect(ajsNodeXt?.isLoaded()).toBeTruthy()
+    })
+  })
+})

package/packages/node/src/__tests__/settings.test.ts

@@ -0,0 +1,9 @@
+import { validateSettings } from '../app/settings'
+
+describe('validateSettings', () => {
+  it('should throw an error if no write key', () => {
+    expect(() => validateSettings({ writeKey: undefined as any })).toThrowError(
+      /writeKey/i
+    )
+  })
+})

package/packages/node/src/__tests__/test-helpers/assert-shape/http-request-event.ts

@@ -0,0 +1,13 @@
+import { NodeEmitterEvents } from '../../../app/emitter'
+type HttpRequestEmitterEvent = NodeEmitterEvents['http_request'][0]
+
+export const assertHttpRequestEmittedEvent = (
+  event: HttpRequestEmitterEvent
+) => {
+  const body = event.body
+  expect(Array.isArray(body.batch)).toBeTruthy()
+  expect(body.batch.length).toBe(1)
+  expect(typeof event.headers).toBe('object')
+  expect(typeof event.method).toBe('string')
+  expect(typeof event.url).toBe('string')
+}

package/packages/node/src/__tests__/test-helpers/assert-shape/index.ts

@@ -0,0 +1,2 @@
+export * from './http-request-event'
+export * from './segment-http-api'

package/packages/node/src/__tests__/test-helpers/assert-shape/segment-http-api.ts

@@ -0,0 +1,43 @@
+import { Context } from '../../../app/context'
+import { HTTPClientRequest } from '../../../lib/http-client'
+
+/**
+ * These map to the data properties of the HTTPClient options (the input value of 'makeRequest')
+ */
+export const httpClientOptionsBodyMatcher = {
+  messageId: expect.stringMatching(/^node-next-\d*-\w*-\w*-\w*-\w*-\w*/),
+  timestamp: expect.any(Date),
+  _metadata: expect.any(Object),
+  context: {
+    library: {
+      name: '@ht-sdks/events-sdk-js-node',
+      version: expect.any(String),
+    },
+  },
+  integrations: {},
+}
+
+export function assertHTTPRequestOptions(
+  { data, headers, method, url }: HTTPClientRequest,
+  contexts: Context[]
+) {
+  expect(url).toBe('https://us-east-1.hightouch-events.com/v1/batch')
+  expect(method).toBe('POST')
+  expect(headers).toMatchInlineSnapshot(`
+    Object {
+      "Authorization": "Basic Og==",
+      "Content-Type": "application/json",
+      "User-Agent": "analytics-node-next/latest",
+    }
+  `)
+
+  expect(data.batch).toHaveLength(contexts.length)
+  let idx = 0
+  for (const context of contexts) {
+    expect(data.batch[idx]).toEqual({
+      ...context.event,
+      ...httpClientOptionsBodyMatcher,
+    })
+    idx += 1
+  }
+}

package/packages/node/src/__tests__/test-helpers/create-test-analytics.ts

@@ -0,0 +1,42 @@
+import { Analytics } from '../../app/analytics-node'
+import { AnalyticsSettings } from '../../app/settings'
+import { FetchHTTPClient, HTTPFetchFn } from '../../lib/http-client'
+import { createError, createSuccess } from './factories'
+
+export const createTestAnalytics = (
+  settings: Partial<AnalyticsSettings> = {},
+  {
+    withError,
+    useRealHTTPClient,
+  }: TestFetchClientOptions & { useRealHTTPClient?: boolean } = {}
+) => {
+  return new Analytics({
+    writeKey: 'foo',
+    flushInterval: 100,
+    ...(useRealHTTPClient
+      ? {}
+      : { httpClient: new TestFetchClient({ withError }) }),
+    ...settings,
+  })
+}
+
+export type TestFetchClientOptions = {
+  withError?: boolean
+  /** override response (if needed) */
+  response?: Response | Promise<Response>
+}
+
+/**
+ * Test http client. By default, it will return a successful response.
+ */
+export class TestFetchClient extends FetchHTTPClient {
+  constructor({ withError, response }: TestFetchClientOptions = {}) {
+    const _mockFetch: HTTPFetchFn = (..._args) => {
+      if (response) {
+        return Promise.resolve(response)
+      }
+      return Promise.resolve(withError ? createError() : createSuccess())
+    }
+    super(_mockFetch)
+  }
+}

package/packages/node/src/__tests__/test-helpers/factories.ts

@@ -0,0 +1,17 @@
+export const createSuccess = (body?: any) => {
+  return Promise.resolve({
+    json: () => Promise.resolve(body),
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+  }) as Promise<Response>
+}
+
+export const createError = (overrides: Partial<Response> = {}) => {
+  return Promise.resolve({
+    ok: false,
+    status: 404,
+    statusText: 'Not Found',
+    ...overrides,
+  }) as Promise<Response>
+}

package/packages/node/src/__tests__/test-helpers/is-valid-date.ts

@@ -0,0 +1,6 @@
+export const isValidDate = (date: string) => {
+  if (!date) {
+    throw new Error('no date found.')
+  }
+  return !isNaN(Date.parse(date))
+}

package/packages/node/src/__tests__/test-helpers/resolve-ctx.ts

@@ -0,0 +1,19 @@
+import type { Analytics } from '../../app/analytics-node'
+import type { Context } from '../../app/context'
+
+/** Tester helper that resolves context from emitter event */
+export const resolveCtx = (
+  analytics: Analytics,
+  eventName: 'track' | 'identify' | 'page' | 'screen' | 'group' | 'alias',
+  { log = false } = {}
+): Promise<Context> => {
+  return new Promise((resolve, reject) => {
+    analytics.once(eventName, resolve)
+    analytics.once('error', (err) => {
+      if (typeof err === 'object' && typeof err.ctx?.['logs'] === 'function') {
+        log && console.error(err.ctx.logs())
+      }
+      reject(err)
+    })
+  })
+}

package/packages/node/src/__tests__/test-helpers/resolve-emitter.ts

@@ -0,0 +1,11 @@
+import { NodeEmitter, NodeEmitterEvents } from '../../app/emitter'
+
+/** Tester helper that resolves args from emitter event */
+export const resolveEmitterEvent = <EventName extends keyof NodeEmitterEvents>(
+  emitter: NodeEmitter,
+  eventName: EventName
+): Promise<NodeEmitterEvents[EventName]> => {
+  return new Promise<NodeEmitterEvents[EventName]>((resolve) => {
+    emitter.once(eventName, (...args) => resolve(args))
+  })
+}

package/packages/node/src/__tests__/test-helpers/sleep.ts

@@ -0,0 +1,3 @@
+export function sleep(timeoutInMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, timeoutInMs))
+}

package/packages/node/src/__tests__/test-helpers/test-plugin.ts

@@ -0,0 +1,16 @@
+import { Plugin } from '../../app/types'
+
+export const testPlugin: Plugin = {
+  isLoaded: jest.fn().mockReturnValue(true),
+  load: jest.fn().mockResolvedValue(undefined),
+  unload: jest.fn().mockResolvedValue(undefined),
+  name: 'Test Plugin',
+  type: 'destination',
+  version: '0.1.0',
+  alias: jest.fn((ctx) => Promise.resolve(ctx)),
+  group: jest.fn((ctx) => Promise.resolve(ctx)),
+  identify: jest.fn((ctx) => Promise.resolve(ctx)),
+  page: jest.fn((ctx) => Promise.resolve(ctx)),
+  screen: jest.fn((ctx) => Promise.resolve(ctx)),
+  track: jest.fn((ctx) => Promise.resolve(ctx)),
+}

package/packages/node/src/__tests__/typedef-tests.ts

@@ -0,0 +1,120 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+import axios from 'axios'
+import {
+  Analytics,
+  Context,
+  Plugin,
+  UserTraits,
+  GroupTraits,
+  HTTPClient,
+  FetchHTTPClient,
+  HTTPFetchFn,
+  HTTPClientRequest,
+} from '../'
+
+/**
+ * These are general typescript definition tests;
+ * They aren't meant to be run by anything but the typescript compiler.
+ */
+export default {
+  'analytics.VERSION should be readonly': () => {
+    const analytics = new Analytics({ writeKey: 'abc' })
+    // should work
+    analytics.VERSION
+
+    // @ts-expect-error - should not be possible
+    analytics.VERSION = 'foo'
+  },
+
+  'Analytics should accept an entire HTTP Client': () => {
+    class CustomClient implements HTTPClient {
+      makeRequest = () => Promise.resolve({} as Response)
+    }
+
+    new Analytics({
+      writeKey: 'foo',
+      httpClient: new CustomClient(),
+    })
+
+    new Analytics({
+      writeKey: 'foo',
+      httpClient: new FetchHTTPClient(globalThis.fetch),
+    })
+
+    new Analytics({
+      writeKey: 'foo',
+      httpClient: new FetchHTTPClient(),
+    })
+  },
+
+  'track/id/pg/screen/grp calls should require either userId or anonymousId':
+    () => {
+      const analytics = new Analytics({ writeKey: 'abc' })
+      const method: 'track' | 'identify' | 'page' | 'screen' | 'group' = 'track'
+
+      // @ts-expect-error - no userID
+      analytics[method]({ event: 'foo' })
+
+      analytics[method]({ event: 'foo', userId: 'bar' })
+      analytics[method]({ event: 'foo', anonymousId: 'bar' })
+      analytics[method]({ event: 'foo', anonymousId: 'bar', userId: 'bar' })
+    },
+
+  'alias does not need a userId': () => {
+    const analytics = new Analytics({ writeKey: 'abc' })
+
+    // @ts-expect-error - no userId
+    analytics.alias({ previousId: 'old_id_either_anon_or_regular' })
+
+    analytics.alias({
+      userId: 'new',
+      previousId: 'old_id_either_anon_or_regular',
+    })
+
+    analytics.alias({
+      // @ts-expect-error - anonymousId is not valid
+      anonymousId: 'old_id_either_anon_or_regular',
+      previousId: 'foo',
+    })
+  },
+
+  'context should be exported': () => {
+    console.log(Context)
+  },
+  'plugin should be exported': () => {
+    interface MyPlugin extends Plugin {}
+    console.log({} as MyPlugin)
+  },
+  'traits should be exported': () => {
+    console.log({} as GroupTraits)
+    console.log({} as UserTraits)
+  },
+
+  'HTTPFetchFn should be compatible with standard fetch and node-fetch interface, as well as functions':
+    () => {
+      const fetch: HTTPFetchFn = require('node-fetch')
+      new Analytics({ writeKey: 'foo', httpClient: fetch })
+      new Analytics({ writeKey: 'foo', httpClient: globalThis.fetch })
+    },
+
+  'HTTPFetchFn options should be the expected type': () => {
+    type BadFetch = (url: string, requestInit: { _bad_object?: string }) => any
+
+    // @ts-expect-error
+    new Analytics({ writeKey: 'foo', httpClient: {} as BadFetch })
+  },
+
+  'httpClient setting should be compatible with axios': () => {
+    new (class implements HTTPClient {
+      async makeRequest(options: HTTPClientRequest) {
+        return axios({
+          url: options.url,
+          method: options.method,
+          data: options.data,
+          headers: options.headers,
+          timeout: options.httpRequestTimeout,
+        })
+      }
+    })()
+  },
+}