Merge remote-tracking branch 'origin/main' into HEAD

Author: rasendubi

.eslintrc.js

@@ -3,6 +3,7 @@ module.exports = {
   env: {
     es6: true,
     jest: true,
+    node: true,
   },
   extends: [
     'eslint:recommended',
@@ -88,5 +89,11 @@ module.exports = {
         'no-restricted-globals': 'off',
       },
     },
+    {
+      files: ['src/tools/**/*.ts'],
+      rules: {
+        'no-restricted-globals': 'off',
+      },
+    },
   ],
 };

README.md

@@ -50,3 +50,78 @@ When publishing releases, the following rules apply:
 **Note**: The release will not be published if:
 - A pre-release is marked as "latest"
 - A pre-release label is used without checking "Set as pre-release"
+
+## Tools
+
+### Bootstrap Configuration
+
+You can generate a bootstrap configuration string from either the command line or programmatically via the
+ConfigurationWireHelper class.
+
+The tool allows you to specify the target SDK this configuration will be used on. It is important to correctly specify
+the intended SDK, as this determines whether the configuration is obfuscated (for client SDKs) or not (for server SDKs).
+
+#### Command Line Usage
+
+**Install as a project dependency:**
+```bash
+# Install as a dependency
+npm install --save-dev @eppo/js-client-sdk-common
+
+# or, with yarn
+yarn add --dev @eppo/js-client-sdk-common
+```
+
+Common usage examples:
+```bash
+# Basic usage
+yarn bootstrap-config --key <sdkKey> --output bootstrap-config.json
+
+# With custom SDK name (default is 'js-client-sdk')
+yarn bootstrap-config --key <sdkKey> --sdk android
+
+# With custom base URL
+yarn bootstrap-config --key <sdkKey> --base-url https://api.custom-domain.com
+
+# Output configuration to stdout
+yarn bootstrap-config --key <sdkKey> 
+
+# Show help
+yarn bootstrap-config --help
+```
+
+The tool accepts the following arguments:
+- `--key, -k`: SDK key (required, can also be set via EPPO_SDK_KEY environment variable)
+- `--sdk`: Target SDK name (default: 'js-client-sdk')
+- `--base-url`: Custom base URL for the API
+- `--output, -o`: Output file path (if not specified, outputs to console)
+- `--help, -h`: Show help
+
+#### Programmatic Usage
+```typescript
+import { ConfigurationHelper } from '@eppo/js-client-sdk-common';
+
+async function getBootstrapConfig() {
+  // Initialize the helper
+  const helper = ConfigurationHelper.build(
+    'your-sdk-key',
+    {
+      sdkName: 'android', // optional: target SDK name (default: 'js-client-sdk')
+      baseUrl: 'https://api.custom-domain.com', // optional: custom base URL
+    });
+
+  // Fetch the configuration
+  const config = await helper.fetchConfiguration();
+  const configString = config.toString();
+
+  // You are responsible to transport this string to the client
+  const clientInitialData = {eppoConfig: eppoConfigString};
+
+  // Client-side
+  const client = getInstance();
+  const initialConfig = configurationFromString(clientInitialData.eppoConfig);
+  client.setInitialConfig(configurationFromString(configString));
+}
+```
+
+The tool will output a JSON string containing the configuration wire format that can be used to bootstrap Eppo SDKs.

package.json

@@ -31,7 +31,8 @@
     "typecheck": "tsc",
     "test": "yarn test:unit",
     "test:unit": "NODE_ENV=test jest '.*\\.spec\\.ts'",
-    "obfuscate-mock-ufc": "ts-node test/writeObfuscatedMockUFC"
+    "obfuscate-mock-ufc": "ts-node test/writeObfuscatedMockUFC",
+    "bootstrap-config": "ts-node src/tools/get-bootstrap-config"
   },
   "jsdelivr": "dist/eppo-sdk.js",
   "repository": {
@@ -55,7 +56,7 @@
     "@typescript-eslint/parser": "^5.13.0",
     "eslint": "^8.17.0",
     "eslint-config-prettier": "^10.0.1",
-    "eslint-import-resolver-typescript": "^3.7.0",
+    "eslint-import-resolver-typescript": "^4.3.4",
     "eslint-plugin-import": "^2.25.4",
     "eslint-plugin-prettier": "5.2.3",
     "eslint-plugin-promise": "^7.2.1",
@@ -80,7 +81,8 @@
     "pino": "^9.5.0",
     "semver": "^7.5.4",
     "spark-md5": "^3.0.2",
-    "uuid": "^11.0.5"
+    "uuid": "^11.0.5",
+    "yargs": "^17.7.2"
   },
   "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

src/client/eppo-client-assignment-details.spec.ts

@@ -1,6 +1,10 @@
 import * as fs from 'fs';
 
-import { IAssignmentTestCase, readMockUfcConfiguration } from '../../test/testHelpers';
+import {
+  AssignmentVariationValue,
+  IAssignmentTestCase,
+  readMockUfcConfiguration,
+} from '../../test/testHelpers';
 import { AllocationEvaluationCode } from '../flag-evaluation-details-builder';
 import { Variation, VariationType } from '../interfaces';
 import { OperatorType } from '../rules';
@@ -291,8 +295,8 @@ describe('EppoClient get*AssignmentDetails', () => {
                 flagKey: string,
                 subjectKey: string,
                 subjectAttributes: Record<string, AttributeType>,
-                defaultValue: boolean | string | number | object,
-              ) => IAssignmentDetails<boolean | string | number | object>;
+                defaultValue: AssignmentVariationValue,
+              ) => IAssignmentDetails<AssignmentVariationValue>;
               if (!assignmentFn) {
                 throw new Error(`Unknown variation type: ${variationType}`);
               }

src/evaluator.ts

@@ -185,7 +185,6 @@ export class Evaluator {
         configFormat ?? '',
       );
     } catch (err: any) {
-      console.error('>>>>', err);
       const flagEvaluationDetails = flagEvaluationDetailsBuilder.gracefulBuild(
         'ASSIGNMENT_ERROR',
         `Assignment Error: ${err.message}`,

src/http-client.ts

@@ -41,6 +41,7 @@ export interface IUniversalFlagConfigResponse {
 }
 
 export interface IBanditParametersResponse {
+  updatedAt: string; // ISO formatted string
   bandits: Record<string, BanditParameters>;
 }
 

src/tools/commands/bootstrap-config.ts

@@ -0,0 +1,86 @@
+import * as fs from 'fs';
+
+import type { CommandModule } from 'yargs';
+
+import ConfigurationRequestor from '../../configuration-requestor';
+import { BroadcastChannel } from '../../broadcast';
+import FetchHttpClient from '../../http-client';
+import ApiEndpoints from '../../api-endpoints';
+import { LIB_VERSION } from '../../version';
+
+export const bootstrapConfigCommand: CommandModule = {
+  command: 'bootstrap-config',
+  describe: 'Generate a bootstrap configuration string',
+  builder: (yargs) => {
+    return yargs.options({
+      key: {
+        type: 'string',
+        description: 'SDK key',
+        alias: 'k',
+        default: process.env.EPPO_SDK_KEY,
+      },
+      sdk: {
+        type: 'string',
+        description: 'Target SDK name',
+        default: 'js-client-sdk',
+      },
+      'base-url': {
+        type: 'string',
+        description: 'Base URL for the API',
+      },
+      output: {
+        type: 'string',
+        description: 'Output file path',
+        alias: 'o',
+      },
+    });
+  },
+  handler: async (argv) => {
+    if (!argv.key) {
+      console.error('Error: SDK key is required');
+      console.error('Provide it either as:');
+      console.error('- Command line argument: --key <sdkKey> or -k <sdkKey>');
+      console.error('- Environment variable: EPPO_SDK_KEY');
+      process.exit(1);
+    }
+
+    try {
+      const apiEndpoints = new ApiEndpoints({
+        baseUrl: argv['base-url'] as string,
+        queryParams: {
+          apiKey: argv.key as string,
+          sdkName: argv.sdk as string,
+          sdkVersion: LIB_VERSION,
+        },
+      });
+
+      const httpClient = new FetchHttpClient(apiEndpoints, 10000);
+
+      const requestor = new ConfigurationRequestor(httpClient, new BroadcastChannel(), {
+        wantsBandits: true,
+      });
+
+      const config = await requestor.fetchConfiguration();
+
+      if (!config) {
+        console.error('Error: Failed to fetch configuration');
+        process.exit(1);
+      }
+
+      const jsonConfig = JSON.stringify(config, null, 2);
+
+      if (argv.output && typeof argv.output === 'string') {
+        fs.writeFileSync(argv.output, jsonConfig);
+        console.log(`Configuration written to ${argv.output}`);
+      } else {
+        console.log('Configuration:');
+        console.log('--------------------------------');
+        console.log(jsonConfig);
+        console.log('--------------------------------');
+      }
+    } catch (error) {
+      console.error('Error fetching configuration:', error);
+      process.exit(1);
+    }
+  },
+};

src/tools/get-bootstrap-config.ts

@@ -0,0 +1,27 @@
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+import { bootstrapConfigCommand } from './commands/bootstrap-config';
+
+/**
+ * Script to run the bootstrap-config command directly.
+ *
+ * For usage, run: `ts-node src/tools/get-bootstrap-config.ts --help`
+ */
+async function main() {
+  await yargs(hideBin(process.argv))
+    .command({
+      command: '$0',
+      describe: bootstrapConfigCommand.describe,
+      builder: bootstrapConfigCommand.builder,
+      handler: bootstrapConfigCommand.handler,
+    })
+    .help()
+    .alias('help', 'h')
+    .parse();
+}
+
+main().catch((error) => {
+  console.error('Error in main:', error);
+  process.exit(1);
+});

src/tools/node-shim.ts

@@ -0,0 +1,8 @@
+// Required type shape for `process`.
+// We don't pin this project to node so eslint complains about the use of `process`. We declare a type shape here to
+// appease the linter.
+export declare const process: {
+  exit: (code: number) => void;
+  env: { [key: string]: string | undefined };
+  argv: string[];
+};