utneque 1.0.0

package/packages/node/README.md

@@ -0,0 +1,138 @@
+# @ht-sdks/events-sdk-js-node
+
+https://www.npmjs.com/package/@ht-sdks/events-sdk-js-node
+
+
+## Runtime Support
+- Node.js >= 14
+- AWS Lambda
+- Cloudflare Workers
+- Vercel Edge Functions
+- Web Workers (experimental)
+
+## Quick Start
+### Install library
+```bash
+# npm
+npm install @ht-sdks/events-sdk-js-node
+# yarn
+yarn add @ht-sdks/events-sdk-js-node
+# pnpm
+pnpm install @ht-sdks/events-sdk-js-node
+```
+
+### Usage
+Assuming some express-like web framework.
+```ts
+import { Analytics } from '@ht-sdks/events-sdk-js-node'
+// or, if you use require:
+const { Analytics } = require('@ht-sdks/events-sdk-js-node')
+
+// instantiation
+const analytics = new Analytics({ writeKey: '<MY_WRITE_KEY>' })
+
+app.post('/login', (req, res) => {
+   analytics.identify({
+      userId: req.body.userId,
+      previousId: req.body.previousId
+  })
+  res.sendStatus(200)
+})
+
+app.post('/cart', (req, res) => {
+  analytics.track({
+    userId: req.body.userId,
+    event: 'Add to cart',
+    properties: { productId: '123456' }
+  })
+   res.sendStatus(201)
+});
+```
+
+
+## Settings & Configuration
+
+You can also see the complete list of settings in the [AnalyticsSettings interface](src/app/settings.ts).
+
+
+## Usage in non-node runtimes
+### Usage in AWS Lambda
+- [AWS lambda execution environment](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtime-environment.html) is challenging for typically non-response-blocking async activites like tracking or logging, since the runtime terminates / freezes after a response is emitted.
+
+Here is an example of using analytics.js within a handler:
+```ts
+const { Analytics } = require('@ht-sdks/events-sdk-js-node');
+
+// since analytics has the potential to be stateful if there are any plugins added,
+// to be on the safe side, we should instantiate a new instance of analytics on every request (the cost of instantiation is low).
+const analytics = () => new Analytics({
+      maxEventsInBatch: 1,
+      writeKey: '<MY_WRITE_KEY>',
+    })
+    .on('error', console.error);
+
+module.exports.handler = async (event) => {
+  ...
+  // we need to await before returning, otherwise the lambda will exit before sending the request.
+  await new Promise((resolve) =>
+    analytics().track({ ... }, resolve)
+   )
+
+  ...
+  return {
+    statusCode: 200,
+  };
+  ....
+};
+```
+
+### Usage in Vercel Edge Functions
+```ts
+import { Analytics } from '@ht-sdks/events-sdk-js-node';
+import { NextRequest, NextResponse } from 'next/server';
+
+export const analytics = new Analytics({
+  writeKey: '<MY_WRITE_KEY>',
+  maxEventsInBatch: 1,
+})
+  .on('error', console.error)
+
+export const config = {
+  runtime: 'edge',
+};
+
+export default async (req: NextRequest) => {
+  await new Promise((resolve) =>
+    analytics.track({ ... }, resolve)
+  );
+  return NextResponse.json({ ... })
+};
+```
+
+### Usage in Cloudflare Workers
+```ts
+import { Analytics, Context } from '@ht-sdks/events-sdk-js-node';
+
+export default {
+  async fetch(
+    request: Request,
+    env: Env,
+    ctx: ExecutionContext
+  ): Promise<Response> {
+    const analytics = new Analytics({
+      maxEventsInBatch: 1,
+      writeKey: '<MY_WRITE_KEY>',
+    }).on('error', console.error);
+
+    await new Promise((resolve, reject) =>
+      analytics.track({ ... }, resolve)
+    );
+
+    ...
+    return new Response(...)
+  },
+};
+
+```
+
+

package/packages/node/jest.config.js

@@ -0,0 +1,5 @@
+const { createJestTSConfig } = require('@internal/config')
+
+module.exports = createJestTSConfig(__dirname, {
+  setupFilesAfterEnv: ['./jest.setup.js'],
+})

package/packages/node/jest.setup.js

@@ -0,0 +1,4 @@
+const fetch = require('node-fetch')
+
+// eslint-disable-next-line no-undef
+globalThis.fetch = fetch // polyfill fetch so nock will work correctly on node 18 (https://github.com/nock/nock/issues/2336)

package/packages/node/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ht-sdks/events-sdk-js-node",
+  "version": "1.1.2",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "directory": "packages/node",
+    "type": "git",
+    "url": "https://github.com/ht-sdks/events-sdk-js-mono"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "!**/__tests__/**",
+    "!*.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "scripts": {
+    ".": "yarn run -T turbo run --filter=@ht-sdks/events-sdk-js-node",
+    "test": "yarn jest",
+    "lint": "yarn concurrently 'yarn:eslint .' 'yarn:tsc --noEmit'",
+    "build": "rm -rf dist && yarn concurrently 'yarn:build:*'",
+    "build:cjs": "yarn tsc -p tsconfig.build.json --outDir ./dist/cjs --module commonjs",
+    "version": "sh scripts/version.sh",
+    "build:esm": "yarn tsc -p tsconfig.build.json",
+    "watch": "yarn build:esm --watch",
+    "watch:test": "yarn test --watch",
+    "tsc": "yarn run -T tsc",
+    "eslint": "yarn run -T eslint",
+    "concurrently": "yarn run -T concurrently",
+    "jest": "yarn run -T jest"
+  },
+  "dependencies": {
+    "@ht-sdks/events-sdk-js-core": "^1.0.0",
+    "@lukeed/uuid": "^2.0.0",
+    "buffer": "^6.0.3",
+    "node-fetch": "^2.6.7",
+    "tslib": "^2.4.1"
+  },
+  "devDependencies": {
+    "@internal/config": "0.0.0",
+    "@types/node": "^16",
+    "axios": "^1.4.0"
+  },
+  "packageManager": "yarn@3.4.1"
+}

package/packages/node/scripts/version.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Generate a version.ts file from the version in the package.json
+
+PKG_VERSION=$(node --eval="process.stdout.write(require('./package.json').version)")
+
+cat <<EOF >src/generated/version.ts
+// This file is generated.
+export const version = '$PKG_VERSION'
+EOF
+
+git add src/generated/version.ts

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

@@ -0,0 +1,47 @@
+import { createTestAnalytics } from './test-helpers/create-test-analytics'
+import { Context } from '../app/context'
+
+describe('Callback behavior', () => {
+  it('should handle success', async () => {
+    const ajs = createTestAnalytics({
+      maxEventsInBatch: 1,
+    })
+    const ctx = await new Promise<Context>((resolve, reject) =>
+      ajs.track(
+        {
+          anonymousId: 'bar',
+          event: 'event name',
+        },
+        (err, ctx) => {
+          if (err) reject('test fail')
+          resolve(ctx!)
+        }
+      )
+    )
+    expect(ctx.event.event).toBe('event name')
+    expect(ctx.event.anonymousId).toBe('bar')
+  })
+
+  it('should handle errors', async () => {
+    const ajs = createTestAnalytics(
+      {
+        maxEventsInBatch: 1,
+      },
+      { withError: true }
+    )
+    const [err, ctx] = await new Promise<[any, Context]>((resolve) =>
+      ajs.track(
+        {
+          anonymousId: 'bar',
+          event: 'event name',
+        },
+        (err, ctx) => {
+          resolve([err!, ctx!])
+        }
+      )
+    )
+    expect(ctx.event.event).toBe('event name')
+    expect(ctx.event.anonymousId).toBe('bar')
+    expect(err).toEqual(new Error('[404] Not Found'))
+  })
+})

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

@@ -0,0 +1,42 @@
+import {
+  createTestAnalytics,
+  TestFetchClient,
+} from './test-helpers/create-test-analytics'
+
+describe('disable', () => {
+  const httpClient = new TestFetchClient()
+  const makeReqSpy = jest.spyOn(httpClient, 'makeRequest')
+
+  it('should not emit an http request if disabled', async () => {
+    const analytics = createTestAnalytics({
+      disable: true,
+    })
+    const emitterCb = jest.fn()
+    analytics.on('http_request', emitterCb)
+    await new Promise((resolve) =>
+      analytics.track({ anonymousId: 'foo', event: 'bar' }, resolve)
+    )
+    expect(emitterCb).not.toBeCalled()
+  })
+
+  it('should call .send if disabled is false', async () => {
+    const analytics = createTestAnalytics({
+      disable: false,
+      httpClient: httpClient,
+    })
+    await new Promise((resolve) =>
+      analytics.track({ anonymousId: 'foo', event: 'bar' }, resolve)
+    )
+    expect(makeReqSpy).toBeCalledTimes(1)
+  })
+  it('should not call .send if disabled is true', async () => {
+    const analytics = createTestAnalytics({
+      disable: true,
+      httpClient: httpClient,
+    })
+    await new Promise((resolve) =>
+      analytics.track({ anonymousId: 'foo', event: 'bar' }, resolve)
+    )
+    expect(makeReqSpy).not.toBeCalled()
+  })
+})

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

@@ -0,0 +1,45 @@
+import { createTestAnalytics } from './test-helpers/create-test-analytics'
+import { assertHttpRequestEmittedEvent } from './test-helpers/assert-shape'
+
+describe('http_request', () => {
+  it('emits an http_request event if success', async () => {
+    const analytics = createTestAnalytics()
+    const fn = jest.fn()
+    analytics.on('http_request', fn)
+    await new Promise((resolve) =>
+      analytics.track({ anonymousId: 'foo', event: 'bar' }, resolve)
+    )
+    expect(fn).toBeCalledTimes(1)
+    assertHttpRequestEmittedEvent(fn.mock.lastCall[0])
+  })
+
+  it('emits an http_request event if error', async () => {
+    const analytics = createTestAnalytics(
+      {
+        maxRetries: 0,
+      },
+      { withError: true }
+    )
+    const fn = jest.fn()
+    analytics.on('http_request', fn)
+    await new Promise((resolve) =>
+      analytics.track({ anonymousId: 'foo', event: 'bar' }, resolve)
+    )
+    assertHttpRequestEmittedEvent(fn.mock.lastCall[0])
+  })
+
+  it('if error, emits an http_request event on every retry', async () => {
+    const analytics = createTestAnalytics(
+      {
+        maxRetries: 2,
+      },
+      { withError: true }
+    )
+    const fn = jest.fn()
+    analytics.on('http_request', fn)
+    await new Promise((resolve) =>
+      analytics.track({ anonymousId: 'foo', event: 'bar' }, resolve)
+    )
+    expect(fn).toBeCalledTimes(3)
+  })
+})

package/packages/node/src/__tests__/graceful-shutdown-integration.test.ts

@@ -0,0 +1,244 @@
+import { TestFetchClient } from './test-helpers/create-test-analytics'
+import { performance as perf } from 'perf_hooks'
+import { Analytics } from '../app/analytics-node'
+import { sleep } from './test-helpers/sleep'
+import { Plugin, HightouchEvent } from '../app/types'
+import { Context } from '../app/context'
+
+const testPlugin: Plugin = {
+  type: 'after',
+  load: () => Promise.resolve(),
+  name: 'foo',
+  version: 'bar',
+  isLoaded: () => true,
+}
+
+let testClient: TestFetchClient
+
+describe('Ability for users to exit without losing events', () => {
+  let ajs!: Analytics
+  testClient = new TestFetchClient()
+  const makeReqSpy = jest.spyOn(testClient, 'makeRequest')
+  beforeEach(async () => {
+    ajs = new Analytics({
+      writeKey: 'abc123',
+      maxEventsInBatch: 1,
+      httpClient: testClient,
+    })
+  })
+  const _helpers = {
+    getFetchCalls: () =>
+      makeReqSpy.mock.calls.map(([{ url, method, data, headers }]) => ({
+        url,
+        method,
+        headers,
+        data,
+      })),
+    makeTrackCall: (analytics = ajs, cb?: (...args: any[]) => void) => {
+      analytics.track({ userId: 'foo', event: 'Thing Updated' }, cb)
+    },
+  }
+
+  describe('drained emitted event', () => {
+    test('emits a drained event if only one event is dispatched', async () => {
+      _helpers.makeTrackCall()
+      return expect(
+        new Promise((resolve) => ajs.once('drained', () => resolve(undefined)))
+      ).resolves.toBe(undefined)
+    })
+
+    test('emits a drained event if multiple events are dispatched', async () => {
+      let drainedCalls = 0
+      ajs.on('drained', () => {
+        drainedCalls++
+      })
+      _helpers.makeTrackCall()
+      _helpers.makeTrackCall()
+      _helpers.makeTrackCall()
+      await sleep(200)
+      expect(drainedCalls).toBe(1)
+    })
+
+    test('all callbacks should be called ', async () => {
+      const cb = jest.fn()
+      ajs.track({ userId: 'foo', event: 'bar' }, cb)
+      expect(cb).not.toHaveBeenCalled()
+      await ajs.closeAndFlush()
+      expect(cb).toBeCalled()
+    })
+
+    test('all async callbacks should be called', async () => {
+      const trackCall = new Promise<Context>((resolve) => {
+        ajs.track(
+          {
+            userId: 'abc',
+            event: 'def',
+          },
+          (_, ctx) => sleep(200).then(() => resolve(ctx!))
+        )
+      })
+
+      const res = await Promise.race([ajs.closeAndFlush(), trackCall])
+      expect(res instanceof Context).toBe(true)
+    })
+  })
+
+  describe('.closeAndFlush()', () => {
+    test('default timeout should be related to flush interval', () => {
+      const flushInterval = 500
+      ajs = new Analytics({
+        writeKey: 'abc123',
+        flushInterval,
+        httpClient: testClient,
+      })
+      const closeAndFlushTimeout = ajs['_closeAndFlushDefaultTimeout']
+      expect(closeAndFlushTimeout).toBe(flushInterval * 1.25)
+    })
+
+    test('should force resolve if method call execution time exceeds specified timeout', async () => {
+      const TIMEOUT = 300
+      await ajs.register({
+        ...testPlugin,
+        track: async (ctx) => {
+          await sleep(1000)
+          return ctx
+        },
+      })
+      _helpers.makeTrackCall(ajs)
+      const startTime = perf.now()
+      await ajs.closeAndFlush({ timeout: TIMEOUT })
+      const elapsedTime = Math.round(perf.now() - startTime)
+      expect(elapsedTime).toBeLessThanOrEqual(TIMEOUT + 10)
+      expect(elapsedTime).toBeGreaterThan(TIMEOUT - 10)
+    })
+
+    test('no new events should be accepted (but existing ones should be flushed)', async () => {
+      let trackCallCount = 0
+      ajs.on('track', () => {
+        // track should only happen after successful dispatch
+        trackCallCount += 1
+      })
+      _helpers.makeTrackCall()
+      const closed = ajs.closeAndFlush()
+      _helpers.makeTrackCall() // should not trigger
+      _helpers.makeTrackCall() // should not trigger
+      await closed
+      expect(_helpers.getFetchCalls().length).toBe(1)
+      expect(trackCallCount).toBe(1)
+    })
+
+    test('any events created after close should be emitted', async () => {
+      const events: HightouchEvent[] = []
+      ajs.on('call_after_close', (event) => {
+        events.push(event)
+      })
+      _helpers.makeTrackCall()
+      const closed = ajs.closeAndFlush()
+      _helpers.makeTrackCall() // should be emitted
+      _helpers.makeTrackCall() // should be emitted
+      expect(events.length).toBe(2)
+      expect(events.every((e) => e.type === 'track')).toBeTruthy()
+      await closed
+    })
+
+    test('if queue has multiple track events, all of those items should be dispatched, and drain and track events should be emitted', async () => {
+      let drainedCalls = 0
+      ajs.on('drained', () => {
+        drainedCalls++
+      })
+      let trackCalls = 0
+      ajs.on('track', () => {
+        trackCalls++
+      })
+      await ajs.register({
+        ...testPlugin,
+        track: async (ctx) => {
+          await sleep(300)
+          return ctx
+        },
+      })
+      _helpers.makeTrackCall()
+      _helpers.makeTrackCall()
+
+      await ajs.closeAndFlush()
+
+      expect(_helpers.getFetchCalls().length).toBe(2)
+
+      expect(trackCalls).toBe(2)
+
+      expect(drainedCalls).toBe(1)
+    })
+
+    test('if no pending events, resolves immediately', async () => {
+      const startTime = perf.now()
+      await ajs.closeAndFlush()
+      const elapsedTime = perf.now() - startTime
+      expect(elapsedTime > 0).toBeTruthy()
+      expect(elapsedTime).toBeLessThan(20)
+    })
+
+    test('if no pending events, drained should not be emitted an extra time when close is called', async () => {
+      let called = false
+      ajs.on('drained', () => {
+        called = true
+      })
+      await ajs.closeAndFlush()
+      expect(called).toBeFalsy()
+    })
+
+    test('should flush immediately if close is called and there are events in the hightouch.io plugin, but no more are expected', async () => {
+      const analytics = new Analytics({
+        writeKey: 'foo',
+        flushInterval: 10000,
+        maxEventsInBatch: 15,
+        httpClient: testClient,
+      })
+      _helpers.makeTrackCall(analytics)
+      _helpers.makeTrackCall(analytics)
+      await sleep(100)
+
+      // ensure all track events have reached the hightouch plugin
+      expect(analytics['_publisher']['_batch']!.length).toBe(2)
+
+      const startTime = perf.now()
+      await analytics.closeAndFlush()
+      const elapsedTime = perf.now() - startTime
+      expect(elapsedTime).toBeLessThan(100)
+      const calls = _helpers.getFetchCalls()
+      expect(calls.length).toBe(1)
+      expect(calls[0].data.batch.length).toBe(2)
+    })
+
+    test('should wait to flush if close is called and an event has not made it to the hightouch.io plugin yet', async () => {
+      const TRACK_DELAY = 100
+      const _testPlugin: Plugin = {
+        ...testPlugin,
+        track: async (ctx) => {
+          await sleep(TRACK_DELAY)
+          return ctx
+        },
+      }
+      const analytics = new Analytics({
+        writeKey: 'foo',
+        flushInterval: 10000,
+        maxEventsInBatch: 15,
+        httpClient: testClient,
+      })
+      await analytics.register(_testPlugin)
+      _helpers.makeTrackCall(analytics)
+      _helpers.makeTrackCall(analytics)
+
+      // ensure that track events have not reached the hightouch plugin before closeAndFlush is called.
+      expect(analytics['_publisher']['_batch']).toBeFalsy()
+
+      const startTime = perf.now()
+      await analytics.closeAndFlush()
+      const elapsedTime = perf.now() - startTime
+      expect(elapsedTime).toBeGreaterThan(TRACK_DELAY)
+      expect(elapsedTime).toBeLessThan(TRACK_DELAY * 2)
+      const calls = _helpers.getFetchCalls()
+      expect(calls.length).toBe(1)
+      expect(calls[0].data.batch.length).toBe(2)
+    })
+  })
+})

package/packages/node/src/__tests__/http-client.integration.test.ts

@@ -0,0 +1,69 @@
+import { FetchHTTPClient, HTTPFetchFn } from '..'
+import { AbortSignal as AbortSignalShim } from '../lib/abort'
+import { httpClientOptionsBodyMatcher } from './test-helpers/assert-shape/segment-http-api'
+import { createTestAnalytics } from './test-helpers/create-test-analytics'
+import { createSuccess } from './test-helpers/factories'
+
+const testFetch: jest.MockedFn<HTTPFetchFn> = jest
+  .fn()
+  .mockResolvedValue(createSuccess())
+
+let analytics: ReturnType<typeof createTestAnalytics>
+
+const helpers = {
+  makeTrackCall: () =>
+    new Promise((resolve) =>
+      analytics.track({ event: 'foo', userId: 'bar' }, resolve)
+    ),
+  assertFetchCallRequest: (
+    ...[url, options]: typeof testFetch['mock']['lastCall']
+  ) => {
+    expect(url).toBe('https://us-east-1.hightouch-events.com/v1/batch')
+    expect(options.headers).toEqual({
+      Authorization: 'Basic Zm9vOg==',
+      'Content-Type': 'application/json',
+      'User-Agent': 'analytics-node-next/latest',
+    })
+    expect(options.method).toBe('POST')
+    const getLastBatch = (): object[] => {
+      const [, options] = testFetch.mock.lastCall
+      const batch = JSON.parse(options.body!).batch
+      return batch
+    }
+    const batch = getLastBatch()
+    expect(batch.length).toBe(1)
+    expect(batch[0]).toEqual({
+      ...httpClientOptionsBodyMatcher,
+      timestamp: expect.stringMatching(
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+      ),
+      properties: {},
+      event: 'foo',
+      type: 'track',
+      userId: 'bar',
+    })
+    // @ts-ignore
+    expect(options.signal).toBeInstanceOf(
+      typeof AbortSignal !== 'undefined' ? AbortSignal : AbortSignalShim
+    )
+  },
+}
+
+describe('httpClient option', () => {
+  it('can be a regular custom HTTP client', async () => {
+    analytics = createTestAnalytics({
+      httpClient: new FetchHTTPClient(testFetch),
+    })
+    expect(testFetch).toHaveBeenCalledTimes(0)
+    await helpers.makeTrackCall()
+    expect(testFetch).toHaveBeenCalledTimes(1)
+    helpers.assertFetchCallRequest(...testFetch.mock.lastCall)
+  })
+  it('can be a simple function that matches the fetch interface', async () => {
+    analytics = createTestAnalytics({ httpClient: testFetch })
+    expect(testFetch).toHaveBeenCalledTimes(0)
+    await helpers.makeTrackCall()
+    expect(testFetch).toHaveBeenCalledTimes(1)
+    helpers.assertFetchCallRequest(...testFetch.mock.lastCall)
+  })
+})