utneque 1.0.0

package/packages/node/src/app/analytics-node.ts

@@ -0,0 +1,299 @@
+import { CoreAnalytics, bindAll, pTimeout } from '@ht-sdks/events-sdk-js-core'
+import { AnalyticsSettings, validateSettings } from './settings'
+import { version } from '../generated/version'
+import { createConfiguredNodePlugin } from '../plugins/segmentio'
+import { NodeEventFactory } from './event-factory'
+import { Callback, dispatchAndEmit } from './dispatch-emit'
+import { NodeEmitter } from './emitter'
+import {
+  AliasParams,
+  GroupParams,
+  IdentifyParams,
+  PageParams,
+  TrackParams,
+  Plugin,
+  HightouchEvent,
+} from './types'
+import { Context } from './context'
+import { NodeEventQueue } from './event-queue'
+import { FetchHTTPClient } from '../lib/http-client'
+
+export class Analytics extends NodeEmitter implements CoreAnalytics {
+  private readonly _eventFactory: NodeEventFactory
+  private _isClosed = false
+  private _pendingEvents = 0
+  private readonly _closeAndFlushDefaultTimeout: number
+  private readonly _publisher: ReturnType<
+    typeof createConfiguredNodePlugin
+  >['publisher']
+
+  private readonly _queue: NodeEventQueue
+
+  ready: Promise<void>
+
+  constructor(settings: AnalyticsSettings) {
+    super()
+    validateSettings(settings)
+
+    this._eventFactory = new NodeEventFactory()
+    this._queue = new NodeEventQueue()
+
+    const flushInterval = settings.flushInterval ?? 10000
+
+    this._closeAndFlushDefaultTimeout = flushInterval * 1.25 // add arbitrary multiplier in case an event is in a plugin.
+
+    const { plugin, publisher } = createConfiguredNodePlugin(
+      {
+        writeKey: settings.writeKey,
+        host: settings.host,
+        path: settings.path,
+        maxRetries: settings.maxRetries ?? 3,
+        maxEventsInBatch: settings.maxEventsInBatch ?? 15,
+        httpRequestTimeout: settings.httpRequestTimeout,
+        disable: settings.disable,
+        flushInterval,
+        httpClient:
+          typeof settings.httpClient === 'function'
+            ? new FetchHTTPClient(settings.httpClient)
+            : settings.httpClient ?? new FetchHTTPClient(),
+      },
+      this as NodeEmitter
+    )
+    this._publisher = publisher
+    this.ready = this.register(plugin).then(() => undefined)
+
+    this.emit('initialize', settings)
+
+    bindAll(this)
+  }
+
+  get VERSION() {
+    return version
+  }
+
+  /**
+   * Call this method to stop collecting new events and flush all existing events.
+   * This method also waits for any event method-specific callbacks to be triggered,
+   * and any of their subsequent promises to be resolved/rejected.
+   */
+  public closeAndFlush({
+    timeout = this._closeAndFlushDefaultTimeout,
+  }: {
+    /** Set a maximum time permitted to wait before resolving. */
+    timeout?: number
+  } = {}): Promise<void> {
+    this._publisher.flushAfterClose(this._pendingEvents)
+    this._isClosed = true
+    const promise = new Promise<void>((resolve) => {
+      if (!this._pendingEvents) {
+        resolve()
+      } else {
+        this.once('drained', () => resolve())
+      }
+    })
+    return timeout ? pTimeout(promise, timeout).catch(() => undefined) : promise
+  }
+
+  private _dispatch(segmentEvent: HightouchEvent, callback?: Callback) {
+    if (this._isClosed) {
+      this.emit('call_after_close', segmentEvent as HightouchEvent)
+      return undefined
+    }
+
+    this._pendingEvents++
+
+    dispatchAndEmit(segmentEvent, this._queue, this, callback)
+      .catch((ctx) => ctx)
+      .finally(() => {
+        this._pendingEvents--
+
+        if (!this._pendingEvents) {
+          this.emit('drained')
+        }
+      })
+  }
+
+  /**
+   * Combines two unassociated user identities.
+   */
+  alias(
+    { userId, previousId, context, timestamp, integrations }: AliasParams,
+    callback?: Callback
+  ): void {
+    const segmentEvent = this._eventFactory.alias(userId, previousId, {
+      context,
+      integrations,
+      timestamp,
+    })
+    this._dispatch(segmentEvent, callback)
+  }
+
+  /**
+   * Associates an identified user with a collective.
+   */
+  group(
+    {
+      timestamp,
+      groupId,
+      userId,
+      anonymousId,
+      traits = {},
+      context,
+      integrations,
+    }: GroupParams,
+    callback?: Callback
+  ): void {
+    const segmentEvent = this._eventFactory.group(groupId, traits, {
+      context,
+      anonymousId,
+      userId,
+      timestamp,
+      integrations,
+    })
+
+    this._dispatch(segmentEvent, callback)
+  }
+
+  /**
+   * Includes a unique userId and (maybe anonymousId) and any optional traits you know about them.
+   */
+  identify(
+    {
+      userId,
+      anonymousId,
+      traits = {},
+      context,
+      timestamp,
+      integrations,
+    }: IdentifyParams,
+    callback?: Callback
+  ): void {
+    const segmentEvent = this._eventFactory.identify(userId, traits, {
+      context,
+      anonymousId,
+      userId,
+      timestamp,
+      integrations,
+    })
+    this._dispatch(segmentEvent, callback)
+  }
+
+  /**
+   * The page method lets you record page views on your website, along with optional extra information about the page being viewed.
+   */
+  page(
+    {
+      userId,
+      anonymousId,
+      category,
+      name,
+      properties,
+      context,
+      timestamp,
+      integrations,
+    }: PageParams,
+    callback?: Callback
+  ): void {
+    const segmentEvent = this._eventFactory.page(
+      category ?? null,
+      name ?? null,
+      properties,
+      { context, anonymousId, userId, timestamp, integrations }
+    )
+    this._dispatch(segmentEvent, callback)
+  }
+
+  /**
+   * Records screen views on your app, along with optional extra information
+   * about the screen viewed by the user.
+   *
+   * TODO: This is not documented on the segment docs ATM (for node).
+   */
+  screen(
+    {
+      userId,
+      anonymousId,
+      category,
+      name,
+      properties,
+      context,
+      timestamp,
+      integrations,
+    }: PageParams,
+    callback?: Callback
+  ): void {
+    const segmentEvent = this._eventFactory.screen(
+      category ?? null,
+      name ?? null,
+      properties,
+      { context, anonymousId, userId, timestamp, integrations }
+    )
+
+    this._dispatch(segmentEvent, callback)
+  }
+
+  /**
+   * Records actions your users perform.
+   */
+  track(
+    {
+      userId,
+      anonymousId,
+      event,
+      properties,
+      context,
+      timestamp,
+      integrations,
+    }: TrackParams,
+    callback?: Callback
+  ): void {
+    const segmentEvent = this._eventFactory.track(event, properties, {
+      context,
+      userId,
+      anonymousId,
+      timestamp,
+      integrations,
+    })
+
+    this._dispatch(segmentEvent, callback)
+  }
+
+  /**
+   * Registers one or more plugins to augment Analytics functionality.
+   * @param plugins
+   */
+  register(...plugins: Plugin[]): Promise<void> {
+    return this._queue.criticalTasks.run(async () => {
+      const ctx = Context.system()
+
+      const registrations = plugins.map((xt) =>
+        this._queue.register(ctx, xt, this)
+      )
+      await Promise.all(registrations)
+      this.emit(
+        'register',
+        plugins.map((el) => el.name)
+      )
+    })
+  }
+
+  /**
+   * Deregisters one or more plugins based on their names.
+   * @param pluginNames - The names of one or more plugins to deregister.
+   */
+  async deregister(...pluginNames: string[]): Promise<void> {
+    const ctx = Context.system()
+
+    const deregistrations = pluginNames.map((pl) => {
+      const plugin = this._queue.plugins.find((p) => p.name === pl)
+      if (plugin) {
+        return this._queue.deregister(ctx, plugin, this)
+      } else {
+        ctx.log('warn', `plugin ${pl} not found`)
+      }
+    })
+
+    await Promise.all(deregistrations)
+    this.emit('deregister', pluginNames)
+  }
+}

package/packages/node/src/app/context.ts

@@ -0,0 +1,11 @@
+// create a derived class since we may want to add node specific things to Context later
+
+import { CoreContext } from '@ht-sdks/events-sdk-js-core'
+import { HightouchEvent } from './types'
+
+// While this is not a type, it is a definition
+export class Context extends CoreContext<HightouchEvent> {
+  static override system() {
+    return new this({ type: 'track', event: 'system' })
+  }
+}

package/packages/node/src/app/dispatch-emit.ts

@@ -0,0 +1,42 @@
+import { dispatch } from '@ht-sdks/events-sdk-js-core'
+import type { NodeEmitter } from './emitter'
+import { Context } from './context'
+import { NodeEventQueue } from './event-queue'
+import { HightouchEvent } from './types'
+
+export type Callback = (err?: unknown, ctx?: Context) => void
+
+const normalizeDispatchCb = (cb: Callback) => (ctx: Context) => {
+  const failedDelivery = ctx.failedDelivery()
+  return failedDelivery ? cb(failedDelivery.reason, ctx) : cb(undefined, ctx)
+}
+
+/* Dispatch function, but swallow promise rejections and use event emitter instead */
+export const dispatchAndEmit = async (
+  event: HightouchEvent,
+  queue: NodeEventQueue,
+  emitter: NodeEmitter,
+  callback?: Callback
+): Promise<void> => {
+  try {
+    const context = new Context(event)
+    const ctx = await dispatch(context, queue, emitter, {
+      ...(callback ? { callback: normalizeDispatchCb(callback) } : {}),
+    })
+    const failedDelivery = ctx.failedDelivery()
+    if (failedDelivery) {
+      emitter.emit('error', {
+        code: 'delivery_failure',
+        reason: failedDelivery.reason,
+        ctx: ctx,
+      })
+    } else {
+      emitter.emit(event.type, ctx)
+    }
+  } catch (err) {
+    emitter.emit('error', {
+      code: 'unknown',
+      reason: err,
+    })
+  }
+}

package/packages/node/src/app/emitter.ts

@@ -0,0 +1,23 @@
+import { CoreEmitterContract, Emitter } from '@ht-sdks/events-sdk-js-core'
+import { Context } from './context'
+import type { AnalyticsSettings } from './settings'
+import { HightouchEvent } from './types'
+
+/**
+ * Map of emitter event names to method args.
+ */
+export type NodeEmitterEvents = CoreEmitterContract<Context> & {
+  initialize: [AnalyticsSettings]
+  call_after_close: [HightouchEvent] // any event that did not get dispatched due to close
+  http_request: [
+    {
+      url: string
+      method: string
+      headers: Record<string, string>
+      body: Record<string, any>
+    }
+  ]
+  drained: []
+}
+
+export class NodeEmitter extends Emitter<NodeEmitterEvents> {}

package/packages/node/src/app/event-factory.ts

@@ -0,0 +1,20 @@
+import { EventFactory } from '@ht-sdks/events-sdk-js-core'
+import { createMessageId } from '../lib/get-message-id'
+import { HightouchEvent } from './types'
+
+// use declaration merging to downcast CoreHightouchEvent without adding any runtime code.
+// if/when we decide to add an actual implementation to NodeEventFactory that actually changes the event shape, we can remove this.
+export interface NodeEventFactory {
+  alias(...args: Parameters<EventFactory['alias']>): HightouchEvent
+  group(...args: Parameters<EventFactory['group']>): HightouchEvent
+  identify(...args: Parameters<EventFactory['identify']>): HightouchEvent
+  track(...args: Parameters<EventFactory['track']>): HightouchEvent
+  page(...args: Parameters<EventFactory['page']>): HightouchEvent
+  screen(...args: Parameters<EventFactory['screen']>): HightouchEvent
+}
+
+export class NodeEventFactory extends EventFactory {
+  constructor() {
+    super({ createMessageId })
+  }
+}

package/packages/node/src/app/event-queue.ts

@@ -0,0 +1,23 @@
+import { CoreEventQueue, PriorityQueue } from '@ht-sdks/events-sdk-js-core'
+import type { Plugin } from '../app/types'
+import type { Context } from './context'
+
+class NodePriorityQueue extends PriorityQueue<Context> {
+  constructor() {
+    super(1, [])
+  }
+  // do not use an internal "seen" map
+  getAttempts(ctx: Context): number {
+    return ctx.attempts ?? 0
+  }
+  updateAttempts(ctx: Context): number {
+    ctx.attempts = this.getAttempts(ctx) + 1
+    return this.getAttempts(ctx)
+  }
+}
+
+export class NodeEventQueue extends CoreEventQueue<Context, Plugin> {
+  constructor() {
+    super(new NodePriorityQueue())
+  }
+}

package/packages/node/src/app/settings.ts

@@ -0,0 +1,49 @@
+import { ValidationError } from '@ht-sdks/events-sdk-js-core'
+import { HTTPClient, HTTPFetchFn } from '../lib/http-client'
+
+export interface AnalyticsSettings {
+  /**
+   * Key that corresponds to your Hightouch.io project
+   */
+  writeKey: string
+  /**
+   * The base URL of the API. Default: "https://us-east-1.hightouch-events.com"
+   */
+  host?: string
+  /**
+   * The API path route. Default: "/v1/batch"
+   */
+  path?: string
+  /**
+   * The number of times to retry flushing a batch. Default: 3
+   */
+  maxRetries?: number
+  /**
+   * The number of messages to enqueue before flushing. Default: 15
+   */
+  maxEventsInBatch?: number
+  /**
+   * The number of milliseconds to wait before flushing the queue automatically. Default: 10000
+   */
+  flushInterval?: number
+  /**
+   * The maximum number of milliseconds to wait for an http request. Default: 10000
+   */
+  httpRequestTimeout?: number
+  /**
+   * Disable the analytics library. All calls will be a noop. Default: false.
+   */
+  disable?: boolean
+  /**
+   * Supply a default http client implementation (such as one supporting proxy).
+   * Accepts either an HTTPClient instance or a fetch function.
+   * Default: an HTTP client that uses globalThis.fetch, with node-fetch as a fallback.
+   */
+  httpClient?: HTTPFetchFn | HTTPClient
+}
+
+export const validateSettings = (settings: AnalyticsSettings) => {
+  if (!settings.writeKey) {
+    throw new ValidationError('writeKey', 'writeKey is missing.')
+  }
+}

package/packages/node/src/app/types/index.ts

@@ -0,0 +1,3 @@
+export * from './params'
+export * from './segment-event'
+export * from './plugin'

package/packages/node/src/app/types/params.ts

@@ -0,0 +1,76 @@
+import type {
+  GroupTraits,
+  UserTraits,
+  CoreExtraContext,
+  EventProperties,
+  Integrations,
+  Timestamp,
+} from '@ht-sdks/events-sdk-js-core'
+
+export type { GroupTraits, UserTraits }
+
+/**
+ * A dictionary of extra context to attach to the call.
+ * Note: context differs from traits because it is not attributes of the user itself.
+ */
+export interface ExtraContext extends CoreExtraContext {}
+
+/**
+ * An ID associated with the user. Note: at least one of userId or anonymousId must be included.
+ **/
+type IdentityOptions =
+  | { userId: string; anonymousId?: string }
+  | { userId?: string; anonymousId: string }
+
+export type AliasParams = {
+  /* The new user id you want to associate with the user. */
+  userId: string
+  /* The previous id that the user was recognized by (this can be either a userId or an anonymousId). */
+  previousId: string
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+}
+
+export type GroupParams = {
+  groupId: string
+  /**
+   * Traits are pieces of information you know about a group.
+   * This interface represents reserved traits that Hightouch has standardized.
+   */
+  traits?: GroupTraits
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+} & IdentityOptions
+
+export type IdentifyParams = {
+  /**
+   * Traits are pieces of information you know about a group.
+   * This interface represents reserved traits that Hightouch has standardized.
+   */
+  traits?: UserTraits
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+} & IdentityOptions
+
+export type PageParams = {
+  /*  The category of the page. Useful for cases like ecommerce where many pages might live under a single category. */
+  category?: string
+  /* The name of the page.*/
+  name?: string
+  /* A dictionary of properties of the page. */
+  properties?: EventProperties
+  timestamp?: Timestamp
+  context?: ExtraContext
+  integrations?: Integrations
+} & IdentityOptions
+
+export type TrackParams = {
+  event: string
+  properties?: EventProperties
+  context?: ExtraContext
+  timestamp?: Timestamp
+  integrations?: Integrations
+} & IdentityOptions

package/packages/node/src/app/types/plugin.ts

@@ -0,0 +1,5 @@
+import type { CorePlugin } from '@ht-sdks/events-sdk-js-core'
+import type { Analytics } from '../analytics-node'
+import type { Context } from '../context'
+
+export interface Plugin extends CorePlugin<Context, Analytics> {}

package/packages/node/src/app/types/segment-event.ts

@@ -0,0 +1,7 @@
+import type { CoreHightouchEvent } from '@ht-sdks/events-sdk-js-core'
+
+type HightouchEventType = 'track' | 'page' | 'identify' | 'alias' | 'screen'
+
+export interface HightouchEvent extends CoreHightouchEvent {
+  type: HightouchEventType
+}

package/packages/node/src/generated/version.ts

@@ -0,0 +1,2 @@
+// This file is generated.
+export const version = '1.1.2'

package/packages/node/src/index.ts

@@ -0,0 +1,26 @@
+export { Analytics } from './app/analytics-node'
+export { Context } from './app/context'
+export {
+  HTTPClient,
+  FetchHTTPClient,
+  HTTPFetchRequest,
+  HTTPResponse,
+  HTTPFetchFn,
+  HTTPClientRequest,
+} from './lib/http-client'
+
+export type {
+  Plugin,
+  GroupTraits,
+  UserTraits,
+  TrackParams,
+  IdentifyParams,
+  AliasParams,
+  GroupParams,
+  PageParams,
+} from './app/types'
+export type { AnalyticsSettings } from './app/settings'
+
+// export Analytics as both a named export and a default export (for backwards-compat. reasons)
+import { Analytics } from './app/analytics-node'
+export default Analytics

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

@@ -0,0 +1,54 @@
+import { abortSignalAfterTimeout } from '../abort'
+import nock from 'nock'
+import { sleep } from '@ht-sdks/events-sdk-js-core'
+import { fetch as _fetch } from '../fetch'
+
+const fetch = _fetch as typeof globalThis.fetch
+
+describe(abortSignalAfterTimeout, () => {
+  const HOST = 'https://foo.com'
+  beforeEach(() => {
+    nock.cleanAll()
+  })
+  it('should not abort operation if timeout has not expired', async () => {
+    jest.useRealTimers()
+    nock(HOST).get('/').reply(201)
+    try {
+      const [signal] = abortSignalAfterTimeout(1000)
+      await fetch(HOST, { signal })
+    } catch (err: any) {
+      throw Error('fail')
+    }
+  })
+
+  it('should abort operation if timeout expires', async () => {
+    jest.useFakeTimers()
+    nock(HOST)
+      .get('/')
+      .reply(201, async () => {
+        await sleep(10000)
+        return true
+      })
+    try {
+      const [signal] = abortSignalAfterTimeout(2000)
+      jest.advanceTimersByTime(6000)
+      await fetch(HOST, { signal })
+      throw Error('fail test.')
+    } catch (err: any) {
+      expect(err.name).toMatch('AbortError')
+      expect(err.message).toMatch('The user aborted a request')
+    }
+  })
+  it('should abort operation immediately if timeout is 0', async () => {
+    jest.useRealTimers()
+    nock(HOST).get('/').reply(201)
+    const [signal] = abortSignalAfterTimeout(0)
+    try {
+      await fetch(HOST, { signal })
+      throw Error('fail test.')
+    } catch (err: any) {
+      expect(err.name).toMatch('AbortError')
+      expect(err.message).toMatch('The user aborted a request')
+    }
+  })
+})

package/packages/node/src/lib/__tests__/create-url.test.ts

@@ -0,0 +1,35 @@
+import { tryCreateFormattedUrl } from '../create-url'
+
+describe(tryCreateFormattedUrl, () => {
+  it('should create a valid url', () => {
+    expect(tryCreateFormattedUrl('http://foo.com', '/bar')).toBe(
+      'http://foo.com/bar'
+    )
+  })
+  it('should work if the path has many', () => {
+    expect(tryCreateFormattedUrl('http://foo.com', '/bar/baz')).toBe(
+      'http://foo.com/bar/baz'
+    )
+  })
+  it('should ignore slashes', () => {
+    const result = 'http://foo.com/bar'
+    expect(tryCreateFormattedUrl('http://foo.com/', '/bar')).toBe(result)
+    expect(tryCreateFormattedUrl('http://foo.com', 'bar')).toBe(result)
+    expect(tryCreateFormattedUrl('http://foo.com', '/bar')).toBe(result)
+  })
+  it('should throw if no http', () => {
+    expect(() => tryCreateFormattedUrl('foo.com', '/bar')).toThrowError()
+  })
+  it('should throw if no url', () => {
+    expect(() => tryCreateFormattedUrl('', '/bar')).toThrowError()
+  })
+  it('should not require .com', () => {
+    expect(tryCreateFormattedUrl('http://foo', 'bar')).toBe('http://foo/bar')
+  })
+  it('should strip the trailing slash if path is', () => {
+    expect(tryCreateFormattedUrl('http://foo.com/')).toBe('http://foo.com')
+    expect(tryCreateFormattedUrl('http://foo.com/', 'bar/')).toBe(
+      'http://foo.com/bar'
+    )
+  })
+})