feat: buildAndInit for isolated client instances

package.json

@@ -60,7 +60,7 @@
     "webpack-cli": "^6.0.1"
   },
   "dependencies": {
-    "@eppo/js-client-sdk-common": "4.8.4"
+    "@eppo/js-client-sdk-common": "4.9.0"
   },
   "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

src/client-options-converter.spec.ts

@@ -0,0 +1,134 @@
+import {
+  IConfigurationStore,
+  ObfuscatedFlag,
+  Flag,
+  EventDispatcher,
+} from '@eppo/js-client-sdk-common';
+import * as td from 'testdouble';
+
+import { clientOptionsToParameters } from './client-options-converter';
+import { IClientOptions } from './i-client-config';
+import { sdkName, sdkVersion } from './sdk-data';
+
+describe('clientOptionsToParameters', () => {
+  const mockStore = td.object<IConfigurationStore<Flag | ObfuscatedFlag>>();
+
+  it('converts basic client options', () => {
+    const options: IClientOptions = {
+      sdkKey: 'test-key',
+      baseUrl: 'https://test.eppo.cloud',
+      assignmentLogger: { logAssignment: jest.fn() },
+    };
+
+    const result = clientOptionsToParameters(options, mockStore);
+
+    expect(result.isObfuscated).toBe(true);
+    expect(result.flagConfigurationStore).toBeDefined();
+    expect(result.configurationRequestParameters).toEqual({
+      apiKey: 'test-key',
+      baseUrl: 'https://test.eppo.cloud',
+      sdkName,
+      sdkVersion,
+      numInitialRequestRetries: undefined,
+      numPollRequestRetries: undefined,
+      pollingIntervalMs: undefined,
+      requestTimeoutMs: undefined,
+      pollAfterFailedInitialization: undefined,
+      pollAfterSuccessfulInitialization: undefined,
+      throwOnFailedInitialization: undefined,
+      skipInitialPoll: undefined,
+    });
+  });
+
+  it('uses provided flag configuration store', () => {
+    const options: IClientOptions = {
+      sdkKey: 'test-key',
+      assignmentLogger: { logAssignment: jest.fn() },
+    };
+
+    const result = clientOptionsToParameters(options, mockStore);
+
+    expect(result.flagConfigurationStore).toBe(mockStore);
+  });
+
+  it('converts client options with event ingestion config', () => {
+    const options: IClientOptions = {
+      sdkKey: 'test-key',
+      assignmentLogger: { logAssignment: jest.fn() },
+    };
+    const mockDispatcher: EventDispatcher = td.object<EventDispatcher>();
+
+    const result = clientOptionsToParameters(options, mockStore, mockDispatcher);
+
+    expect(result.eventDispatcher).toBeDefined();
+  });
+
+  it('converts client options with polling configuration', () => {
+    const options: IClientOptions = {
+      sdkKey: 'test-key',
+      assignmentLogger: { logAssignment: jest.fn() },
+      pollingIntervalMs: 30000,
+      pollAfterSuccessfulInitialization: true,
+      pollAfterFailedInitialization: true,
+      skipInitialRequest: true,
+    };
+
+    const result = clientOptionsToParameters(options, mockStore);
+
+    expect(result.configurationRequestParameters).toMatchObject({
+      pollingIntervalMs: 30000,
+      pollAfterSuccessfulInitialization: true,
+      pollAfterFailedInitialization: true,
+      skipInitialPoll: true,
+    });
+  });
+
+  it('converts client options with retry configuration', () => {
+    const options: IClientOptions = {
+      sdkKey: 'test-key',
+      assignmentLogger: { logAssignment: jest.fn() },
+      requestTimeoutMs: 5000,
+      numInitialRequestRetries: 3,
+      numPollRequestRetries: 2,
+    };
+
+    const result = clientOptionsToParameters(options, mockStore);
+
+    expect(result.configurationRequestParameters).toMatchObject({
+      requestTimeoutMs: 5000,
+      numInitialRequestRetries: 3,
+      numPollRequestRetries: 2,
+    });
+  });
+
+  it('handles undefined optional parameters', () => {
+    const options: IClientOptions = {
+      sdkKey: 'test-key',
+      assignmentLogger: { logAssignment: jest.fn() },
+    };
+
+    const result = clientOptionsToParameters(options, mockStore);
+
+    expect(result.configurationRequestParameters).toMatchObject({
+      baseUrl: undefined,
+      pollingIntervalMs: undefined,
+      requestTimeoutMs: undefined,
+      numInitialRequestRetries: undefined,
+      numPollRequestRetries: undefined,
+    });
+  });
+
+  it('includes sdk metadata', () => {
+    const options: IClientOptions = {
+      sdkKey: 'test-key',
+      assignmentLogger: { logAssignment: jest.fn() },
+    };
+
+    const result = clientOptionsToParameters(options, mockStore);
+
+    expect(result.configurationRequestParameters).toMatchObject({
+      sdkName,
+      sdkVersion,
+    });
+  });
+});

src/client-options-converter.ts

@@ -0,0 +1,47 @@
+import {
+  BanditParameters,
+  BanditVariation, EppoClientParameters,
+  EventDispatcher,
+  Flag,
+  FlagConfigurationRequestParameters,
+  IConfigurationStore,
+  ObfuscatedFlag,
+} from '@eppo/js-client-sdk-common';
+
+import { IClientOptions } from './i-client-config';
+import { sdkName, sdkVersion } from './sdk-data';
+
+/**
+ * Converts IClientOptions to EppoClientParameters
+ * @internal
+ */
+export function clientOptionsToParameters(
+  options: IClientOptions,
+  flagConfigurationStore: IConfigurationStore<Flag>,
+  eventDispatcher?: EventDispatcher,
+): EppoClientParameters {
+  const parameters: EppoClientParameters = {
+    flagConfigurationStore,
+    isObfuscated: true,
+  };
+
+  parameters.eventDispatcher = eventDispatcher;
+
+  // Always include configuration request parameters
+  parameters.configurationRequestParameters = {
+    apiKey: options.sdkKey,
+    sdkVersion, // dynamically picks up version.
+    sdkName, // Hardcoded to `js-client-sdk`
+    baseUrl: options.baseUrl,
+    requestTimeoutMs: options.requestTimeoutMs,
+    numInitialRequestRetries: options.numInitialRequestRetries,
+    numPollRequestRetries: options.numPollRequestRetries,
+    pollAfterSuccessfulInitialization: options.pollAfterSuccessfulInitialization,
+    pollAfterFailedInitialization: options.pollAfterFailedInitialization,
+    pollingIntervalMs: options.pollingIntervalMs,
+    throwOnFailedInitialization: options.throwOnFailedInitialization,
+    skipInitialPoll: options.skipInitialRequest,
+  };
+
+  return parameters;
+}

src/i-client-config.ts

@@ -6,6 +6,7 @@
   IAssignmentLogger,
   IAsyncStore,
   IBanditLogger,
+  IConfigurationStore,
 } from '@eppo/js-client-sdk-common';
 
 import { ServingStoreUpdateStrategy } from './isolatable-hybrid.store';
@@ -104,10 +105,41 @@
 }
 
 /**
- * Configuration for regular client initialization
- * @public
+ * Base options for the EppoClient SDK
  */
-export interface IClientConfig extends IBaseRequestConfig {
+export type IApiOptions = {
+  /**
+   * Your key for accessing Eppo through the Eppo SDK.
+   */
+  sdkKey: string;
+
+  /**
+   * Override the endpoint the SDK uses to load configuration.
+   */
+  baseUrl?: string;
+
+  /**
+   * Force reinitialize the SDK if it is already initialized.
+   */
+  forceReinitialize?: boolean;
+
+  /**
+   * Timeout in milliseconds for the HTTPS request for the experiment configuration. (Default: 5000)
+   */
+  requestTimeoutMs?: number;
+
+  /**
+   * Number of additional times the initial configuration request will be attempted if it fails.
+   * This is the request typically synchronously waited (via await) for completion. A small wait will be
+   * done between requests. (Default: 1)
+   */
+  numInitialRequestRetries?: number;
+
+  /**
+   * Skip the request for new configurations during initialization. (default: false)
+   */
+  skipInitialRequest?: boolean;
+
   /**
    * Throw an error if unable to fetch an initial configuration during initialization. (default: true)
    */
@@ -135,18 +167,13 @@
   updateOnFetch?: ServingStoreUpdateStrategy;
 
   /**
-   * A custom class to use for storing flag configurations.
-   * This is useful for cases where you want to use a different storage mechanism
-   * than the default storage provided by the SDK.
+   * A configuration string to bootstrap the client without having to make a network fetch.
    */
-  persistentStore?: IAsyncStore<Flag>;
+  initialConfiguration: string;
+};
 
-  /**
-   * Force reinitialize the SDK if it is already initialized.
-   */
-  forceReinitialize?: boolean;
 
-  /** Configuration settings for the event dispatcher */
+export type IEventOptions = {
   eventIngestionConfig?: {
     /** Number of milliseconds to wait between each batch delivery. Defaults to 10 seconds. */
     deliveryIntervalMs?: number;
@@ -165,4 +192,77 @@
      */
     maxQueueSize?: number;
   };
+};
+
+export type IStorageOptions = {
+  /**
+   * Custom implementation of the flag configuration store for advanced use-cases.
+   */
+  flagConfigurationStore?: IConfigurationStore<Flag>;
+
+  /**
+   * A custom class to use for storing flag configurations.
+   * This is useful for cases where you want to use a different storage mechanism
+   * than the default storage provided by the SDK.
+   */
+  persistentStore?: IAsyncStore<Flag>;
+};
+
+export type IPollingOptions = {
+  /**
+   * Poll for new configurations even if the initial configuration request failed. (default: false)
+   */
+  pollAfterFailedInitialization?: boolean;
+
+  /**
+   * Poll for new configurations (every `pollingIntervalMs`) after successfully requesting the initial configuration. (default: false)
+   */
+  pollAfterSuccessfulInitialization?: boolean;
+
+  /**
+   * Amount of time to wait between API calls to refresh configuration data. Default of 30_000 (30 seconds).
+   */
+  pollingIntervalMs?: number;
+
+  /**
+   * Number of additional times polling for updated configurations will be attempted before giving up.
+   * Polling is done after a successful initial request. Subsequent attempts are done using an exponential
+   * backoff. (Default: 7)
+   */
+  numPollRequestRetries?: number;
+};
+
+export type ILoggers = {
+  /**
+   * Pass a logging implementation to send variation assignments to your data warehouse.
+   */
+  assignmentLogger: IAssignmentLogger;
+
+  /**
+   * Pass a logging implementation to send bandit assignments to your data warehouse.
+   */
+  banditLogger?: IBanditLogger;
+};
+
+/**
+ * Config shape for client v2.
+ */
+export type IClientOptions = IApiOptions &
+  ILoggers &
+  IEventOptions &
+  IStorageOptions &
+  IPollingOptions;
+
+/**
+ * Configuration for regular client initialization
+ * @public
+ */
+export type IClientConfig = Omit<IClientOptions, 'sdkKey' | 'offline'> &
+  Pick<IBaseRequestConfig, 'apiKey'>;
+
+export function convertClientOptionsToClientConfig(options: IClientOptions): IClientConfig {
+  return {
+    ...options,
+    apiKey: options.sdkKey,
+  };
 }