utneque 1.0.0

package/packages/node/src/lib/__tests__/env.test.ts

@@ -0,0 +1,52 @@
+import { detectRuntime, RuntimeEnv } from '../env'
+
+const ogProcessEnv = { ...process.env }
+
+afterEach(() => {
+  process.env = ogProcessEnv
+  // @ts-ignore
+  delete globalThis.window
+
+  // @ts-ignore
+  delete globalThis.WebSocketPair
+
+  // @ts-ignore
+  delete globalThis.EdgeRuntime
+
+  // @ts-ignore
+  delete globalThis.window
+})
+describe(detectRuntime, () => {
+  it('should return node since these tests run in node', () => {
+    expect(detectRuntime()).toEqual<RuntimeEnv>('node')
+  })
+
+  it('should return browser if correct env', () => {
+    // @ts-ignore
+    // eslint-disable-next-line
+    delete process.env
+    // @ts-ignore
+    globalThis.window = {}
+    expect(detectRuntime()).toEqual<RuntimeEnv>('browser')
+  })
+
+  it('should return cloudflare worker if correct env', () => {
+    // @ts-ignore
+    // eslint-disable-next-line
+    delete process.env
+    // @ts-ignore
+    globalThis.WebSocketPair = {}
+    expect(detectRuntime()).toEqual<RuntimeEnv>('cloudflare-worker')
+  })
+
+  it('should return edgeruntime if correct env', () => {
+    // @ts-ignore
+    // eslint-disable-next-line
+    delete process.env
+
+    // @ts-ignore
+    globalThis.EdgeRuntime = 'vercel'
+
+    expect(detectRuntime()).toEqual<RuntimeEnv>('vercel-edge')
+  })
+})

package/packages/node/src/lib/__tests__/get-message-id.test.ts

@@ -0,0 +1,21 @@
+import { createMessageId } from '../get-message-id'
+
+// https://gist.github.com/johnelliott/cf77003f72f889abbc3f32785fa3df8d
+const uuidv4Regex =
+  /^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/i
+
+describe(createMessageId, () => {
+  it('returns a string in the format "node-next-[unix epoch time]-[uuid v4]"', () => {
+    const msg = createMessageId().split('-')
+    expect(msg.length).toBe(8)
+
+    expect(`${msg[0]}-${msg[1]}`).toBe('node-next')
+
+    const epochTimeSeg = msg[2]
+    expect(typeof parseInt(epochTimeSeg)).toBe('number')
+    expect(epochTimeSeg.length > 10).toBeTruthy()
+
+    const uuidSeg = msg.slice(3).join('-')
+    expect(uuidSeg).toEqual(expect.stringMatching(uuidv4Regex))
+  })
+})

package/packages/node/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 '@ht-sdks/events-sdk-js-core'
+import { detectRuntime } from './env'
+
+/**
+ * adapted from: https://www.npmjs.com/package/node-abort-controller
+ */
+export 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 (globalThis.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/packages/node/src/lib/base-64-encode.ts

@@ -0,0 +1,8 @@
+// eslint-disable-next-line import/no-nodejs-modules
+import { Buffer } from 'buffer'
+/**
+ * Base64 encoder that works in browser, worker, node runtimes.
+ */
+export const b64encode = (str: string): string => {
+  return Buffer.from(str).toString('base64')
+}

package/packages/node/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)
+}

package/packages/node/src/lib/env.ts

@@ -0,0 +1,45 @@
+/* eslint-disable no-restricted-globals */
+export type RuntimeEnv =
+  | 'node'
+  | 'browser'
+  | 'web-worker'
+  | 'cloudflare-worker'
+  | 'vercel-edge'
+  | 'unknown'
+
+export const detectRuntime = (): RuntimeEnv => {
+  if (
+    typeof process === 'object' &&
+    process &&
+    typeof process.env === 'object' &&
+    process.env &&
+    typeof process.version === 'string'
+  ) {
+    return 'node'
+  }
+
+  if (typeof window === 'object') {
+    return 'browser'
+  }
+
+  // @ts-ignore
+  if (typeof WebSocketPair !== 'undefined') {
+    return 'cloudflare-worker'
+  }
+
+  // @ts-ignore
+  if (typeof EdgeRuntime === 'string') {
+    return 'vercel-edge'
+  }
+
+  if (
+    // @ts-ignore
+    typeof WorkerGlobalScope !== 'undefined' &&
+    // @ts-ignore
+    typeof importScripts === 'function'
+  ) {
+    return 'web-worker'
+  }
+
+  return 'unknown'
+}

package/packages/node/src/lib/extract-promise-parts.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns a promise and its associated `resolve` and `reject` methods.
+ */
+export function extractPromiseParts<T = unknown>(): {
+  promise: Promise<T>
+  resolve: (value: T) => void
+  reject: (reason?: unknown) => void
+} {
+  let resolver: (value: T) => void
+  let rejecter: (reason?: unknown) => void
+  const promise = new Promise<T>((resolve, reject) => {
+    resolver = resolve
+    rejecter = reject
+  })
+
+  return {
+    promise,
+    resolve: resolver!,
+    reject: rejecter!,
+  }
+}

package/packages/node/src/lib/fetch.ts

@@ -0,0 +1,16 @@
+import type { HTTPFetchFn } from './http-client'
+
+export const fetch: HTTPFetchFn = async (...args) => {
+  if (globalThis.fetch) {
+    return globalThis.fetch(...args)
+  }
+  // This guard causes is important, as it causes dead-code elimination to be enabled inside this block.
+  // @ts-ignore
+  else if (typeof EdgeRuntime !== 'string') {
+    return (await import('node-fetch')).default(...args)
+  } else {
+    throw new Error(
+      'Invariant: an edge runtime that does not support fetch should not exist'
+    )
+  }
+}

package/packages/node/src/lib/get-message-id.ts

@@ -0,0 +1,10 @@
+import { uuid } from './uuid'
+
+/**
+ * get a unique messageId with a very low chance of collisions
+ * using @lukeed/uuid/secure uses the node crypto module, which is the fastest
+ * @example "node-next-1668208232027-743be593-7789-4b74-8078-cbcc8894c586"
+ */
+export const createMessageId = (): string => {
+  return `node-next-${Date.now()}-${uuid()}`
+}

package/packages/node/src/lib/http-client.ts

@@ -0,0 +1,95 @@
+import { abortSignalAfterTimeout } from './abort'
+import { fetch as defaultFetch } from './fetch'
+
+/**
+ * This interface is meant to be compatible with different fetch implementations (node and browser).
+ * Using the ambient fetch type is not possible because the AbortSignal type is not compatible with node-fetch.
+ * @link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+ */
+export interface HTTPFetchFn {
+  (url: string, requestInit: HTTPFetchRequest): Promise<HTTPResponse>
+}
+
+/**
+ * This interface is meant to be compatible with the Request interface.
+ * @link https://developer.mozilla.org/en-US/docs/Web/API/Request
+ */
+export interface HTTPFetchRequest {
+  headers: Record<string, string>
+  body: string
+  method: HTTPClientRequest['method']
+  signal: any // AbortSignal type does not play nicely with node-fetch
+}
+
+/**
+ * This interface is meant to very minimally conform to the Response interface.
+ * @link https://developer.mozilla.org/en-US/docs/Web/API/Response
+ */
+export interface HTTPResponse {
+  status: number
+  statusText: string
+}
+
+/**
+ * This interface is meant to be a generic interface for making HTTP requests.
+ * While it may overlap with fetch's Request interface, it is not coupled to it.
+ */
+export interface HTTPClientRequest {
+  /**
+   * URL to be used for the request
+   * @example 'https://us-east-1.hightouch-events.com/v1/batch'
+   */
+  url: string
+  /**
+   * HTTP method to be used for the request. This will always be a 'POST' request.
+   **/
+  method: 'POST'
+  /**
+   * Headers to be sent with the request
+   */
+  headers: Record<string, string>
+  /**
+   * JSON data to be sent with the request (will be stringified)
+   * @example { "batch": [ ... ]}
+   */
+  data: Record<string, any>
+  /**
+   * Specifies the timeout (in milliseconds) for an HTTP client to get an HTTP response from the server
+   * @example 10000
+   */
+  httpRequestTimeout: number
+}
+
+/**
+ * HTTP client interface for making requests
+ */
+export interface HTTPClient {
+  makeRequest(_options: HTTPClientRequest): Promise<HTTPResponse>
+}
+
+/**
+ * Default HTTP client implementation using fetch
+ */
+export class FetchHTTPClient implements HTTPClient {
+  private _fetch: HTTPFetchFn
+  constructor(fetchFn?: HTTPFetchFn) {
+    this._fetch = fetchFn ?? defaultFetch
+  }
+  async makeRequest(options: HTTPClientRequest): Promise<HTTPResponse> {
+    const [signal, timeoutId] = abortSignalAfterTimeout(
+      options.httpRequestTimeout
+    )
+
+    const requestInit = {
+      url: options.url,
+      method: options.method,
+      headers: options.headers,
+      body: JSON.stringify(options.data),
+      signal: signal,
+    }
+
+    return this._fetch(options.url, requestInit).finally(() =>
+      clearTimeout(timeoutId)
+    )
+  }
+}

package/packages/node/src/lib/uuid.ts

@@ -0,0 +1 @@
+export { v4 as uuid } from '@lukeed/uuid'

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

@@ -0,0 +1,223 @@
+import { NodeEventFactory } from '../../../app/event-factory'
+import { createSuccess } from '../../../__tests__/test-helpers/factories'
+import { createConfiguredNodePlugin } from '../index'
+import { PublisherProps } from '../publisher'
+import { Context } from '../../../app/context'
+import { Emitter } from '@ht-sdks/events-sdk-js-core'
+import {
+  assertHTTPRequestOptions,
+  httpClientOptionsBodyMatcher,
+} from '../../../__tests__/test-helpers/assert-shape'
+import { TestFetchClient } from '../../../__tests__/test-helpers/create-test-analytics'
+
+let emitter: Emitter
+const testClient = new TestFetchClient()
+const fetcher = jest.spyOn(testClient, 'makeRequest')
+
+const createTestNodePlugin = (props: Partial<PublisherProps> = {}) =>
+  createConfiguredNodePlugin(
+    {
+      maxRetries: 3,
+      maxEventsInBatch: 1,
+      flushInterval: 1000,
+      writeKey: '',
+      httpClient: testClient,
+      ...props,
+    },
+    emitter
+  )
+
+const validateFetcherInputs = (...contexts: Context[]) => {
+  const [request] = fetcher.mock.lastCall
+  return assertHTTPRequestOptions(request, contexts)
+}
+
+const eventFactory = new NodeEventFactory()
+
+beforeEach(() => {
+  emitter = new Emitter()
+  fetcher.mockReturnValue(createSuccess())
+  jest.useFakeTimers()
+})
+
+test('alias', async () => {
+  const { plugin: segmentPlugin } = createTestNodePlugin()
+
+  const event = eventFactory.alias('to', 'from')
+  const context = new Context(event)
+
+  fetcher.mockReturnValueOnce(createSuccess())
+  await segmentPlugin.alias(context)
+
+  expect(fetcher).toHaveBeenCalledTimes(1)
+  validateFetcherInputs(context)
+
+  const [request] = fetcher.mock.lastCall
+  const data = request.data
+
+  expect(data.batch).toHaveLength(1)
+  expect(data.batch[0]).toEqual({
+    ...httpClientOptionsBodyMatcher,
+    type: 'alias',
+    previousId: 'from',
+    userId: 'to',
+  })
+})
+
+test('group', async () => {
+  const { plugin: segmentPlugin } = createTestNodePlugin()
+
+  const event = eventFactory.group(
+    'foo-group-id',
+    {
+      name: 'libraries',
+    },
+    { userId: 'foo-user-id' }
+  )
+  const context = new Context(event)
+
+  fetcher.mockReturnValueOnce(createSuccess())
+  await segmentPlugin.group(context)
+
+  expect(fetcher).toHaveBeenCalledTimes(1)
+  validateFetcherInputs(context)
+
+  const [request] = fetcher.mock.lastCall
+  const data = request.data
+
+  expect(data.batch).toHaveLength(1)
+  expect(data.batch[0]).toEqual({
+    ...httpClientOptionsBodyMatcher,
+    traits: {
+      name: 'libraries',
+    },
+    type: 'group',
+    groupId: 'foo-group-id',
+    userId: 'foo-user-id',
+  })
+})
+
+test('identify', async () => {
+  const { plugin: segmentPlugin } = createTestNodePlugin()
+
+  const event = eventFactory.identify('foo-user-id', {
+    name: 'Chris Radek',
+  })
+  const context = new Context(event)
+
+  fetcher.mockReturnValueOnce(createSuccess())
+  await segmentPlugin.identify(context)
+
+  expect(fetcher).toHaveBeenCalledTimes(1)
+  validateFetcherInputs(context)
+
+  const [request] = fetcher.mock.lastCall
+  const data = request.data
+  expect(data.batch).toHaveLength(1)
+  expect(data.batch[0]).toEqual({
+    ...httpClientOptionsBodyMatcher,
+    traits: {
+      name: 'Chris Radek',
+    },
+    type: 'identify',
+    userId: 'foo-user-id',
+  })
+})
+
+test('page', async () => {
+  const { plugin: segmentPlugin } = createTestNodePlugin()
+
+  const event = eventFactory.page(
+    'Category',
+    'Home',
+    { url: 'http://localhost' },
+    { userId: 'foo-user-id' }
+  )
+  const context = new Context(event)
+
+  fetcher.mockReturnValueOnce(createSuccess())
+  await segmentPlugin.page(context)
+
+  expect(fetcher).toHaveBeenCalledTimes(1)
+  validateFetcherInputs(context)
+
+  const [request] = fetcher.mock.lastCall
+  const data = request.data
+
+  expect(data.batch).toHaveLength(1)
+  expect(data.batch[0]).toEqual({
+    ...httpClientOptionsBodyMatcher,
+    type: 'page',
+    userId: 'foo-user-id',
+    name: 'Home',
+    category: 'Category',
+    properties: {
+      category: 'Category',
+      url: 'http://localhost',
+    },
+  })
+})
+
+test('screen', async () => {
+  const { plugin: segmentPlugin } = createTestNodePlugin()
+
+  const event = eventFactory.screen(
+    'Category',
+    'Home',
+    { variation: 'local' },
+    { userId: 'foo-user-id' }
+  )
+  const context = new Context(event)
+
+  fetcher.mockReturnValueOnce(createSuccess())
+  await segmentPlugin.screen(context)
+
+  expect(fetcher).toHaveBeenCalledTimes(1)
+  validateFetcherInputs(context)
+
+  const [request] = fetcher.mock.lastCall
+  const data = request.data
+
+  expect(data.batch).toHaveLength(1)
+  expect(data.batch[0]).toEqual({
+    ...httpClientOptionsBodyMatcher,
+    type: 'screen',
+    userId: 'foo-user-id',
+    name: 'Home',
+    category: 'Category',
+    properties: {
+      variation: 'local',
+    },
+  })
+})
+
+test('track', async () => {
+  const { plugin: segmentPlugin } = createTestNodePlugin()
+
+  const event = eventFactory.track(
+    'test event',
+    { foo: 'bar' },
+    { userId: 'foo-user-id' }
+  )
+  const context = new Context(event)
+
+  fetcher.mockReturnValueOnce(createSuccess())
+  await segmentPlugin.screen(context)
+
+  expect(fetcher).toHaveBeenCalledTimes(1)
+  validateFetcherInputs(context)
+
+  const [request] = fetcher.mock.lastCall
+  const data = request.data
+
+  expect(data.batch).toHaveLength(1)
+  expect(data.batch[0]).toEqual({
+    ...httpClientOptionsBodyMatcher,
+    type: 'track',
+    event: 'test event',
+    userId: 'foo-user-id',
+    properties: {
+      foo: 'bar',
+    },
+  })
+})