Make segment settings type safe

Author: silesky

.changeset/heavy-taxis-suffer.md

@@ -1,7 +1,8 @@
 ---
 '@segment/analytics-next': minor
 ---
-Add new `headers` setting, along with `fetchPriority`.
+- Make Segment.io config type-safe
+- Add new `headers` setting, along with `priority`.
 
 ```ts
 analytics.load("<YOUR_WRITE_KEY>",
@@ -19,5 +20,6 @@ analytics.load("<YOUR_WRITE_KEY>",
     },
   }
 )
-
 ```
+
+

packages/browser/src/browser/__tests__/analytics-lazy-init.integration.test.ts

@@ -1,5 +1,6 @@
 import { CorePlugin, PluginType, sleep } from '@segment/analytics-core'
 import {
+  cdnSettingsMinimal,
   createMockFetchImplementation,
   createRemotePlugin,
   getBufferedPageCtxFixture,
@@ -92,7 +93,9 @@ describe('Lazy destination loading', () => {
   beforeEach(() => {
     jest.mocked(unfetch).mockImplementation(
       createMockFetchImplementation({
+        ...cdnSettingsMinimal,
         integrations: {
+          ...cdnSettingsMinimal.integrations,
           braze: {},
           google: {},
         },

packages/browser/src/browser/__tests__/anon-id-and-reset.integration.test.ts

@@ -14,7 +14,14 @@ const helpers = {
       .mockImplementation(() => createSuccess({ integrations: {} }))
   },
   loadAnalytics() {
-    return AnalyticsBrowser.load({ writeKey: 'foo' })
+    return AnalyticsBrowser.load(
+      { writeKey: 'foo' },
+      {
+        integrations: {
+          'Segment.io': {},
+        },
+      }
+    )
   },
 }
 

packages/browser/src/browser/__tests__/csp-detection.test.ts

@@ -4,9 +4,12 @@ import { CDNSettings } from '..'
 import { pWhile } from '../../lib/p-while'
 import { snippet } from '../../tester/__fixtures__/segment-snippet'
 import * as Factory from '../../test-helpers/factories'
+import { cdnSettingsMinimal } from '../../test-helpers/fixtures'
 
 const cdnResponse: CDNSettings = {
+  ...cdnSettingsMinimal,
   integrations: {
+    ...cdnSettingsMinimal.integrations,
     Zapier: {
       type: 'server',
     },

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

@@ -11,7 +11,7 @@ import { Analytics, InitOptions } from '../../core/analytics'
 import { LegacyDestination } from '../../plugins/ajs-destination'
 import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
 // @ts-ignore loadCDNSettings mocked dependency is accused as unused
-import { AnalyticsBrowser, loadCDNSettings } from '..'
+import { AnalyticsBrowser, CDNSettings, loadCDNSettings } from '..'
 // @ts-ignore isOffline mocked dependency is accused as unused
 import { isOffline } from '../../core/connection'
 import * as SegmentPlugin from '../../plugins/segmentio'
@@ -376,7 +376,7 @@ describe('Initialization', () => {
     it('does not fetch source settings if cdnSettings is set', async () => {
       await AnalyticsBrowser.load({
         writeKey,
-        cdnSettings: { integrations: {} },
+        cdnSettings: cdnSettingsMinimal,
       })
 
       expect(fetchCalls.length).toBe(0)
@@ -666,8 +666,10 @@ describe('Dispatch', () => {
       {
         writeKey,
         cdnSettings: {
+          ...cdnSettingsMinimal,
           integrations: {
             'Segment.io': {
+              ...cdnSettingsMinimal.integrations['Segment.io'],
               apiHost: 'cdnSettings.api.io',
             },
           },
@@ -1331,6 +1333,7 @@ describe('Segment.io overrides', () => {
         integrations: {
           'Segment.io': {
             apiHost: 'https://my.endpoint.com',
+            // @ts-ignore
             anotherSettings: '👻',
           },
         },
@@ -1526,13 +1529,13 @@ describe('Options', () => {
       const disableSpy = jest.fn().mockReturnValue(true)
       const [analytics] = await AnalyticsBrowser.load(
         {
-          cdnSettings: { integrations: {}, foo: 123 },
+          cdnSettings: cdnSettingsMinimal,
           writeKey,
         },
         { disable: disableSpy }
       )
       expect(analytics).toBeInstanceOf(NullAnalytics)
-      expect(disableSpy).toBeCalledWith({ integrations: {}, foo: 123 })
+      expect(disableSpy).toHaveBeenCalledWith(cdnSettingsMinimal)
     })
   })
 })

packages/browser/src/browser/__tests__/standalone-errors.test.ts

@@ -5,9 +5,12 @@ import { pWhile } from '../../lib/p-while'
 import unfetch from 'unfetch'
 import { RemoteMetrics } from '../../core/stats/remote-metrics'
 import * as Factory from '../../test-helpers/factories'
+import { cdnSettingsMinimal } from '../../test-helpers/fixtures'
 
 const cdnResponse: CDNSettings = {
+  ...cdnSettingsMinimal,
   integrations: {
+    ...cdnSettingsMinimal.integrations,
     Zapier: {
       type: 'server',
     },

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

@@ -5,9 +5,12 @@ import { pWhile } from '../../lib/p-while'
 import { snippet } from '../../tester/__fixtures__/segment-snippet'
 import * as Factory from '../../test-helpers/factories'
 import { getGlobalAnalytics } from '../..'
+import { cdnSettingsMinimal } from '../../test-helpers/fixtures'
 
 const cdnResponse: CDNSettings = {
+  ...cdnSettingsMinimal,
   integrations: {
+    ...cdnSettingsMinimal.integrations,
     Zapier: {
       type: 'server',
     },

packages/browser/src/browser/__tests__/update-cdn-settings.test.ts

@@ -3,12 +3,15 @@ import { setGlobalCDNUrl } from '../../lib/parse-cdn'
 import { remoteLoader } from '../../plugins/remote-loader'
 import unfetch from 'unfetch'
 import { createSuccess } from '../../test-helpers/factories'
+import { cdnSettingsMinimal } from '../../test-helpers/fixtures'
 jest.mock('unfetch')
 
 const INTG_TO_DELETE = 'deleteMe'
 
 const cdnSettings = {
+  ...cdnSettingsMinimal,
   integrations: {
+    ...cdnSettingsMinimal.integrations,
     [INTG_TO_DELETE]: { bar: true },
     otherIntegration: { foo: true },
   },

packages/browser/src/browser/settings.ts

@@ -1,7 +1,7 @@
 /**
  * These settings will be exposed via the public API
  */
-import { IntegrationsOptions, Plan } from '../core/events'
+import { Plan } from '../core/events'
 import { MetricsOptions } from '../core/stats/remote-metrics'
 import { ClassicIntegrationSource } from '../plugins/ajs-destination/types'
 import { PluginFactory, RemotePlugin } from '../plugins/remote-loader'
@@ -10,17 +10,20 @@ import { RoutingRule } from '../plugins/routing-middleware'
 import { CookieOptions, StorageSettings } from '../core/storage'
 import { UserOptions } from '../core/user'
 import { HighEntropyHint } from '../lib/client-hints/interfaces'
+import { IntegrationsOptions } from '@segment/analytics-core'
+import { DeliveryStrategy } from '../plugins/segmentio/shared-dispatcher'
+
+interface VersionSettings {
+  version?: string
+  override?: string
+  componentTypes?: ('browser' | 'android' | 'ios' | 'server')[]
+}
 
 export interface RemoteIntegrationSettings {
   /* @deprecated - This does not indicate browser types anymore */
   type?: string
 
-  versionSettings?: {
-    version?: string
-    override?: string
-    componentTypes?: ('browser' | 'android' | 'ios' | 'server')[]
-  }
-
+  versionSettings?: VersionSettings
   /**
    * We know if an integration is device mode if it has `bundlingStatus: 'bundled'` and the `browser` componentType in `versionSettings`.
    * History: The term 'bundle' is left over from before action destinations, when a device mode destinations were 'bundled' in a custom bundle for every analytics.js source.
@@ -38,20 +41,48 @@ export interface RemoteIntegrationSettings {
     categories: string[]
   }
 
-  // Segment.io specific
-  retryQueue?: boolean
-
   // any extra unknown settings
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   [key: string]: any
 }
 
+export interface RemoteSegmentIOIntegrationSettings
+  extends RemoteIntegrationSettings {
+  /**
+   * Segment write key
+   */
+  apiKey: string
+
+  /**
+   * Whether or not offline events are stored and retried.
+   *
+   * Originally, each plugin was concieved to use global retry logic (e.g. throwing magic errors would result in retries),
+   * but this was not really used and is no longer encouraged. Instead, we favor of per-plugin retry logic, since it's confusing to have multiple levels of retries, and most device mode destinations contain their own retry behavior.
+   * The segmentio plugin itself has its own internal retry queue and is not affected by this setting.
+   *
+   * @default true
+   */
+  retryQueue?: boolean
+
+  /**
+   * Host of the segment cdn - this may need to be manually enabled on the source.
+   * @default 'api.segment.io/v1'
+   */
+  apiHost?: string
+  addBundledMetadata?: boolean
+  unbundledIntegrations?: string[]
+  bundledConfigIds?: string[]
+  unbundledConfigIds?: string[]
+  maybeBundledConfigIds?: Record<string, string[]>
+}
+
 /**
  * The remote settings object for a source, typically fetched from the Segment CDN.
  * Warning: this is an *unstable* object.
  */
 export interface CDNSettings {
   integrations: {
+    'Segment.io': RemoteSegmentIOIntegrationSettings
     [creationName: string]: RemoteIntegrationSettings
   }
 
@@ -108,6 +139,21 @@ export interface CDNSettings {
   autoInstrumentationSettings?: {
     sampleRate: number
   }
+
+  /**
+   * Allow misc settings to be passed through, but
+   */
+  [key: string]: unknown
+}
+
+export interface BrowserIntegrationsOptions extends IntegrationsOptions {
+  'Segment.io'?: // subset of the SegmentSettings, since we don't want to expose all of them to the user
+  | {
+        apiHost?: string
+        protocol?: 'http' | 'https'
+        deliveryStrategy?: DeliveryStrategy
+      }
+    | boolean
 }
 
 /**
@@ -121,7 +167,7 @@ export interface AnalyticsBrowserSettings {
    * If provided, `AnalyticsBrowser` will not fetch remote settings
    * for the source.
    */
-  cdnSettings?: CDNSettings & Record<string, unknown>
+  cdnSettings?: CDNSettings
   /**
    * If provided, will override the default Segment CDN (https://cdn.segment.com) for this application.
    */
@@ -164,7 +210,7 @@ export interface InitOptions {
   storage?: StorageSettings
   user?: UserOptions
   group?: UserOptions
-  integrations?: IntegrationsOptions
+  integrations?: BrowserIntegrationsOptions
   plan?: Plan
   retryQueue?: boolean
   obfuscate?: boolean

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

@@ -18,7 +18,6 @@ import { Emitter } from '@segment/analytics-generic-utils'
 import {
   Callback,
   EventFactory,
-  IntegrationsOptions,
   EventProperties,
   SegmentEvent,
 } from '../events'
@@ -52,7 +51,11 @@ import {
   isSegmentPlugin,
   SegmentIOPluginMetadata,
 } from '../../plugins/segmentio'
-import { AnalyticsSettings, InitOptions } from '../../browser/settings'
+import {
+  AnalyticsSettings,
+  BrowserIntegrationsOptions,
+  InitOptions,
+} from '../../browser/settings'
 
 export type { InitOptions, AnalyticsSettings }
 
@@ -99,10 +102,17 @@ export class AnalyticsInstanceSettings {
     this._getSegmentPluginMetadata = () =>
       queue.plugins.find(isSegmentPlugin)?.metadata
     this.writeKey = settings.writeKey
-    this.cdnSettings = settings.cdnSettings ?? {
-      integrations: {},
-      edgeFunction: {},
+
+    // this is basically just to satisfy typescript / so we don't need to change the function sig of every test.
+    // when loadAnalytics is called, cdnSettings will always be available.
+    const emptyCDNSettings: CDNSettings = {
+      integrations: {
+        'Segment.io': {
+          apiKey: '',
+        },
+      },
     }
+    this.cdnSettings = settings.cdnSettings ?? emptyCDNSettings
     this.cdnURL = settings.cdnURL
   }
 }
@@ -124,7 +134,7 @@ export class Analytics
   private _universalStorage: UniversalStorage
 
   initialized = false
-  integrations: IntegrationsOptions
+  integrations: BrowserIntegrationsOptions
   options: InitOptions
   queue: EventQueue