wip

Author: silesky

.changeset/violet-actors-pump.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-next': minor
+---
+
+Add public settings API

packages/browser/src/browser/__tests__/integration.test.ts

@@ -1,5 +1,8 @@
 /* eslint-disable @typescript-eslint/no-floating-promises */
-import { cdnSettingsKitchenSink } from '../../test-helpers/fixtures/cdn-settings'
+import {
+  cdnSettingsKitchenSink,
+  cdnSettingsMinimal,
+} from '../../test-helpers/fixtures/cdn-settings'
 import { createMockFetchImplementation } from '../../test-helpers/fixtures/create-fetch-method'
 import { Context } from '../../core/context'
 import { Plugin } from '../../core/plugin'
@@ -23,8 +26,10 @@ import {
   highEntropyTestData,
   lowEntropyTestData,
 } from '../../test-helpers/fixtures/client-hints'
-import { getGlobalAnalytics, NullAnalytics } from '../..'
+import { getGlobalAnalytics } from '../../lib/global-analytics-helper'
+import { NullAnalytics } from '../../core/analytics'
 import { recordIntegrationMetric } from '../../core/stats/metric-helpers'
+import { TestAnalytics } from '../../test-helpers/factories'
 
 let fetchCalls: ReturnType<typeof parseFetchCall>[] = []
 
@@ -751,7 +756,7 @@ describe('Alias', () => {
 describe('pageview', () => {
   it('makes a page call with the given url', async () => {
     console.warn = (): void => {}
-    const analytics = new Analytics({ writeKey: writeKey })
+    const analytics = new TestAnalytics({ writeKey: writeKey })
     const mockPage = jest.spyOn(analytics, 'page')
     await analytics.pageview('www.foo.com')
 
@@ -1030,24 +1035,47 @@ describe('use', () => {
   })
 })
 
-describe('timeout', () => {
-  it('has a default timeout value', async () => {
+describe('public settings api', () => {
+  it('has expected settings', async () => {
     const [analytics] = await AnalyticsBrowser.load({
       writeKey,
+      cdnSettings: cdnSettingsMinimal,
+    })
+
+    expect(analytics.settings).toEqual({
+      writeKey,
+      cdnSettings: cdnSettingsMinimal,
+      timeout: 300,
     })
-    //@ts-ignore
-    expect(analytics.settings.timeout).toEqual(300)
+  })
+
+  it('should have a writeKey', async () => {
+    const [analytics] = await AnalyticsBrowser.load({
+      writeKey,
+    })
+
+    expect(analytics.settings.writeKey).toBe(writeKey)
+  })
+
+  it('should have cdn settings', async () => {
+    const [analytics] = await AnalyticsBrowser.load({
+      writeKey,
+      cdnSettings: cdnSettingsMinimal,
+    })
+
+    expect(analytics.settings.cdnSettings).toEqual(cdnSettingsMinimal)
   })
 
   it('can set a timeout value', async () => {
     const [analytics] = await AnalyticsBrowser.load({
       writeKey,
     })
+    expect(analytics.settings.timeout).toEqual(300)
     analytics.timeout(50)
-    //@ts-ignore
     expect(analytics.settings.timeout).toEqual(50)
   })
 })
+
 describe('register', () => {
   it('will not invoke any plugins that have initialization errors', async () => {
     const analytics = AnalyticsBrowser.load({

packages/browser/src/browser/index.ts

@@ -2,12 +2,7 @@ import { getProcessEnv } from '../lib/get-process-env'
 import { getCDN, setGlobalCDNUrl } from '../lib/parse-cdn'
 
 import { fetch } from '../lib/fetch'
-import {
-  Analytics,
-  AnalyticsSettings,
-  NullAnalytics,
-  InitOptions,
-} from '../core/analytics'
+import { Analytics, NullAnalytics, InitOptions } from '../core/analytics'
 import { Context } from '../core/context'
 import { Plan } from '../core/events'
 import { Plugin } from '../core/plugin'
@@ -111,7 +106,8 @@ export interface CDNSettings {
   }
 }
 
-export interface AnalyticsBrowserSettings extends AnalyticsSettings {
+export interface AnalyticsBrowserSettings {
+  writeKey: string
   /**
    * The settings for the Segment Source.
    * If provided, `AnalyticsBrowser` will not fetch remote settings
@@ -122,6 +118,14 @@ export interface AnalyticsBrowserSettings extends AnalyticsSettings {
    * If provided, will override the default Segment CDN (https://cdn.segment.com) for this application.
    */
   cdnURL?: string
+  /**
+   * Plugins or npm-installed action destinations
+   */
+  plugins?: (Plugin | PluginFactory)[]
+  /**
+   * npm-installed classic destinations
+   */
+  classicIntegrations?: ClassicIntegrationSource[]
 }
 
 export function loadLegacySettings(
@@ -330,31 +334,31 @@ async function loadAnalytics(
     preInitBuffer.push(new PreInitMethodCall('page', []))
   }
 
-  let legacySettings =
+  let cdnSettings =
     settings.cdnSettings ??
     (await loadLegacySettings(settings.writeKey, settings.cdnURL))
 
   if (options.updateCDNSettings) {
-    legacySettings = options.updateCDNSettings(legacySettings)
+    cdnSettings = options.updateCDNSettings(cdnSettings)
   }
 
   // if options.disable is a function, we allow user to disable analytics based on CDN Settings
   if (typeof options.disable === 'function') {
-    const disabled = await options.disable(legacySettings)
+    const disabled = await options.disable(cdnSettings)
     if (disabled) {
       return [new NullAnalytics(), Context.system()]
     }
   }
 
   const retryQueue: boolean =
-    legacySettings.integrations['Segment.io']?.retryQueue ?? true
+    cdnSettings.integrations['Segment.io']?.retryQueue ?? true
 
   options = {
     retryQueue,
     ...options,
   }
 
-  const analytics = new Analytics(settings, options)
+  const analytics = new Analytics({ ...settings, cdnSettings }, options)
 
   attachInspector(analytics)
 
@@ -367,8 +371,8 @@ async function loadAnalytics(
     | undefined
 
   Stats.initRemoteMetrics({
-    ...legacySettings.metrics,
-    host: segmentLoadOptions?.apiHost ?? legacySettings.metrics?.host,
+    ...cdnSettings.metrics,
+    host: segmentLoadOptions?.apiHost ?? cdnSettings.metrics?.host,
     protocol: segmentLoadOptions?.protocol,
   })
 
@@ -377,7 +381,7 @@ async function loadAnalytics(
 
   const ctx = await registerPlugins(
     settings.writeKey,
-    legacySettings,
+    cdnSettings,
     analytics,
     options,
     plugins,

packages/browser/src/core/__tests__/track-form.test.ts

@@ -1,6 +1,7 @@
 import { Analytics } from '../analytics'
 import { sleep } from '../../lib/sleep'
 import { getDefaultPageContext } from '../page'
+import { TestAnalytics } from '../../test-helpers/factories'
 
 let analytics: Analytics
 let mockTrack: jest.SpiedFunction<Analytics['track']>
@@ -18,7 +19,7 @@ beforeEach(() => {
     writable: true,
   })
   mockTrack = jest.spyOn(Analytics.prototype, 'track')
-  analytics = new Analytics({ writeKey: 'foo' })
+  analytics = new TestAnalytics({ writeKey: 'foo' })
 })
 
 describe('trackForm', () => {

packages/browser/src/core/__tests__/track-link.test.ts

@@ -1,5 +1,6 @@
 import { Analytics } from '../analytics'
 import { sleep } from '../../lib/sleep'
+import { TestAnalytics } from '../../test-helpers/factories'
 
 async function resolveWhen(
   condition: () => boolean,
@@ -36,7 +37,7 @@ beforeEach(() => {
     writable: true,
   })
   mockTrack = jest.spyOn(Analytics.prototype, 'track')
-  analytics = new Analytics({ writeKey: 'foo' })
+  analytics = new TestAnalytics({ writeKey: 'foo' })
 })
 describe('trackLink', () => {
   let link: any

packages/browser/src/core/analytics/__tests__/analytics.test.ts

@@ -16,6 +16,7 @@ import {
   TestDestinationPlugin,
   TestEnrichmentPlugin,
 } from './test-plugins'
+import { TestAnalytics } from '../../../test-helpers/factories'
 
 describe('Analytics', () => {
   describe('plugin error behavior', () => {
@@ -29,7 +30,7 @@ describe('Analytics', () => {
 
         beforeEach(() => {
           const queue = new EventQueue(new PriorityQueue(attemptCount, []))
-          analytics = new Analytics({ writeKey: 'writeKey' }, {}, queue)
+          analytics = new TestAnalytics({ writeKey: 'writeKey' }, {}, queue)
         })
 
         // Indicates plugins should throw
@@ -234,7 +235,7 @@ describe('Analytics', () => {
     })
 
     it('clears user and group data', async () => {
-      const analytics = new Analytics({ writeKey: '' })
+      const analytics = new TestAnalytics({ writeKey: '' })
 
       analytics.user().anonymousId('unknown-user')
       analytics.user().id('known-user')
@@ -264,7 +265,7 @@ describe('Analytics', () => {
     })
 
     it('emits a reset event', async () => {
-      const analytics = new Analytics({ writeKey: '' })
+      const analytics = new TestAnalytics({ writeKey: '' })
       const fn = jest.fn()
       analytics.on('reset', fn)
       analytics.user().id('known-user')
@@ -285,7 +286,7 @@ describe('Analytics', () => {
       jar.set('ajs_anonymous_id', expected)
       localStorage.setItem('ajs_anonymous_id', 'localStorageValue')
 
-      const analytics = new Analytics(
+      const analytics = new TestAnalytics(
         { writeKey: '' },
         {
           storage: {
@@ -311,7 +312,7 @@ describe('Analytics', () => {
       jar.set('ajs_anonymous_id', expected)
       localStorage.setItem('ajs_anonymous_id', 'localStorageValue')
 
-      const analytics = new Analytics(
+      const analytics = new TestAnalytics(
         { writeKey: '' },
         {
           storage: {

packages/browser/src/core/analytics/index.ts

@@ -28,10 +28,7 @@ import { EventQueue } from '../queue/event-queue'
 import { Group, ID, User, UserOptions } from '../user'
 import autoBind from '../../lib/bind-all'
 import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
-import type {
-  LegacyIntegration,
-  ClassicIntegrationSource,
-} from '../../plugins/ajs-destination/types'
+import type { LegacyIntegration } from '../../plugins/ajs-destination/types'
 import type {
   DestinationMiddlewareFunction,
   MiddlewareFunction,
@@ -52,7 +49,6 @@ import {
   initializeStorages,
   isArrayOfStoreType,
 } from '../storage'
-import { PluginFactory } from '../../plugins/remote-loader'
 import { setGlobalAnalytics } from '../../lib/global-analytics-helper'
 import { popPageContext } from '../buffer'
 
@@ -75,11 +71,34 @@ function createDefaultQueue(
   return new EventQueue(priorityQueue)
 }
 
+/**
+ * The public settings that are set on the analytics instance
+ */
+export class AnalyticsInstanceSettings {
+  readonly writeKey: string
+  /**
+   * This is an unstable API, it may change in the future without warning.
+   */
+  readonly cdnSettings: CDNSettings
+  /**
+   * The timeout for the analytics request in milliseconds
+   */
+  // this is an odd setting --
+  //  it's only used in autotrack? Not sure what the history is, or why it's publicly exposed.
+  readonly timeout = 300
+
+  constructor(settings: AnalyticsSettings) {
+    this.writeKey = settings.writeKey
+    this.cdnSettings = settings.cdnSettings ?? { integrations: {} }
+  }
+}
+
+/**
+ * The settings that are used to configure the analytics instance
+ */
 export interface AnalyticsSettings {
   writeKey: string
-  timeout?: number
-  plugins?: (Plugin | PluginFactory)[]
-  classicIntegrations?: ClassicIntegrationSource[]
+  cdnSettings?: CDNSettings
 }
 
 export interface InitOptions {
@@ -155,7 +174,7 @@ export class Analytics
   extends Emitter
   implements AnalyticsCore, AnalyticsClassic
 {
-  protected settings: AnalyticsSettings
+  settings: AnalyticsInstanceSettings
   private _user: User
   private _group: Group
   private eventFactory: EventFactory
@@ -177,8 +196,7 @@ export class Analytics
     super()
     const cookieOptions = options?.cookie
     const disablePersistance = options?.disableClientPersistence ?? false
-    this.settings = settings
-    this.settings.timeout = this.settings.timeout ?? 300
+    this.settings = new AnalyticsInstanceSettings(settings)
     this.queue =
       queue ??
       createDefaultQueue(