flagsmith-nodejs 6.1.0 → 7.0.2

package/sdk/index.ts

@@ -1,22 +1,21 @@
 import { Dispatcher } from 'undici-types';
-import {
-    getEnvironmentFeatureStates,
-    getIdentityFeatureStates
-} from '../flagsmith-engine/index.js';
-import { EnvironmentModel } from '../flagsmith-engine/index.js';
+
 import { buildEnvironmentModel } from '../flagsmith-engine/environments/util.js';
-import { IdentityModel } from '../flagsmith-engine/index.js';
-import { TraitModel } from '../flagsmith-engine/index.js';
 
 import { ANALYTICS_ENDPOINT, AnalyticsProcessor } from './analytics.js';
 import { BaseOfflineHandler } from './offline_handlers.js';
-import { FlagsmithAPIError } from './errors.js';
+import { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
 
 import { DefaultFlag, Flags } from './models.js';
 import { EnvironmentDataPollingManager } from './polling_manager.js';
-import { Deferred, generateIdentitiesData, retryFetch } from './utils.js';
-import { SegmentModel } from '../flagsmith-engine/index.js';
-import { getIdentitySegments } from '../flagsmith-engine/segments/evaluators.js';
+import { Deferred, generateIdentitiesData, getUserAgent, retryFetch } from './utils.js';
+import {
+    SegmentModel,
+    EnvironmentModel,
+    IdentityModel,
+    TraitModel,
+    getEvaluationResult
+} from '../flagsmith-engine/index.js';
 import {
     Fetch,
     FlagsmithCache,
@@ -25,6 +24,8 @@ import {
     TraitConfig
 } from './types.js';
 import { pino, Logger } from 'pino';
+import { getEvaluationContext } from '../flagsmith-engine/evaluation/evaluationContext/mappers.js';
+import { EvaluationContextWithMetadata } from '../flagsmith-engine/evaluation/models.js';
 
 export { AnalyticsProcessor, AnalyticsProcessorOptions } from './analytics.js';
 export { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
@@ -278,7 +279,13 @@ export class Flagsmith {
             }))
         );
 
-        return getIdentitySegments(environment, identityModel);
+        const context = getEvaluationContext(environment, identityModel);
+        if (!context) {
+            throw new FlagsmithClientError('Local evaluation required to obtain identity segments');
+        }
+        const evaluationResult = getEvaluationResult(context as EvaluationContextWithMetadata);
+
+        return SegmentModel.fromSegmentResult(evaluationResult.segments, context);
     }
 
     private async fetchEnvironment(): Promise<EnvironmentModel> {
@@ -329,12 +336,14 @@ export class Flagsmith {
         url: string,
         method: string,
         body?: { [key: string]: any }
-    ): Promise<any> {
+    ): Promise<{ response: Response; data: any }> {
         const headers: { [key: string]: any } = { 'Content-Type': 'application/json' };
         if (this.environmentKey) {
             headers['X-Environment-Key'] = this.environmentKey as string;
         }
 
+        headers['User-Agent'] = getUserAgent();
+
         if (this.customHeaders) {
             for (const [k, v] of Object.entries(this.customHeaders)) {
                 headers[k] = v;
@@ -361,7 +370,7 @@ export class Flagsmith {
             );
         }
 
-        return data.json();
+        return { response: data, data: await data.json() };
     }
 
     /**
@@ -391,20 +400,67 @@ export class Flagsmith {
         if (!this.environmentUrl) {
             throw new Error('`apiUrl` argument is missing or invalid.');
         }
-        const environment_data = await this.getJSONResponse(this.environmentUrl, 'GET');
-        return buildEnvironmentModel(environment_data);
+        const startTime = Date.now();
+        const documents: any[] = [];
+        let url = this.environmentUrl;
+        let loggedWarning = false;
+
+        while (true) {
+            try {
+                if (!loggedWarning) {
+                    const elapsedMs = Date.now() - startTime;
+                    if (elapsedMs > this.environmentRefreshIntervalSeconds * 1000) {
+                        this.logger.warn(
+                            `Environment document retrieval exceeded the polling interval of ${this.environmentRefreshIntervalSeconds} seconds.`
+                        );
+                        loggedWarning = true;
+                    }
+                }
+
+                const { response, data } = await this.getJSONResponse(url, 'GET');
+
+                documents.push(data);
+
+                const linkHeader = response.headers.get('link');
+                if (linkHeader) {
+                    const nextMatch = linkHeader.match(/<([^>]+)>;\s*rel="next"/);
+
+                    if (nextMatch) {
+                        const relativeUrl = decodeURIComponent(nextMatch[1]);
+                        url = new URL(relativeUrl, this.apiUrl).href;
+
+                        continue;
+                    }
+                }
+                break;
+            } catch (error) {
+                throw error;
+            }
+        }
+
+        // Compile the document
+        const compiledDocument = documents[0];
+        for (let i = 1; i < documents.length; i++) {
+            compiledDocument.identity_overrides = compiledDocument.identity_overrides || [];
+            compiledDocument.identity_overrides.push(...(documents[i].identity_overrides || []));
+        }
+
+        return buildEnvironmentModel(compiledDocument);
     }
 
     private async getEnvironmentFlagsFromDocument(): Promise<Flags> {
         const environment = await this.getEnvironment();
-        const flags = Flags.fromFeatureStateModels({
-            featureStates: getEnvironmentFeatureStates(environment),
-            analyticsProcessor: this.analyticsProcessor,
-            defaultFlagHandler: this.defaultFlagHandler
-        });
+        const context = getEvaluationContext(environment, undefined, undefined, true);
+        if (!context) {
+            throw new FlagsmithClientError('Unable to get flags. No environment present.');
+        }
+        const evaluationResult = getEvaluationResult(context as EvaluationContextWithMetadata);
+        const flags = Flags.fromEvaluationResult(evaluationResult);
+
         if (!!this.cache) {
             await this.cache.set('flags', flags);
         }
+
         return flags;
     }
 
@@ -422,14 +478,17 @@ export class Flagsmith {
             }))
         );
 
-        const featureStates = getIdentityFeatureStates(environment, identityModel);
+        const context = getEvaluationContext(environment, identityModel);
+        if (!context) {
+            throw new FlagsmithClientError('Unable to get flags. No environment present.');
+        }
+        const evaluationResult = getEvaluationResult(context as EvaluationContextWithMetadata);
 
-        const flags = Flags.fromFeatureStateModels({
-            featureStates: featureStates,
-            analyticsProcessor: this.analyticsProcessor,
-            defaultFlagHandler: this.defaultFlagHandler,
-            identityID: identityModel.djangoID || identityModel.compositeKey
-        });
+        const flags = Flags.fromEvaluationResult(
+            evaluationResult,
+            this.defaultFlagHandler,
+            this.analyticsProcessor
+        );
 
         if (!!this.cache) {
             await this.cache.set(`flags-${identifier}`, flags);
@@ -442,7 +501,7 @@ export class Flagsmith {
         if (!this.environmentFlagsUrl) {
             throw new Error('`apiUrl` argument is missing or invalid.');
         }
-        const apiFlags = await this.getJSONResponse(this.environmentFlagsUrl, 'GET');
+        const { data: apiFlags } = await this.getJSONResponse(this.environmentFlagsUrl, 'GET');
         const flags = Flags.fromAPIFlags({
             apiFlags: apiFlags,
             analyticsProcessor: this.analyticsProcessor,
@@ -463,7 +522,7 @@ export class Flagsmith {
             throw new Error('`apiUrl` argument is missing or invalid.');
         }
         const data = generateIdentitiesData(identifier, traits, transient);
-        const jsonResponse = await this.getJSONResponse(this.identitiesUrl, 'POST', data);
+        const { data: jsonResponse } = await this.getJSONResponse(this.identitiesUrl, 'POST', data);
         const flags = Flags.fromAPIFlags({
             apiFlags: jsonResponse['flags'],
             analyticsProcessor: this.analyticsProcessor,

package/sdk/models.ts

@@ -1,7 +1,12 @@
+import {
+    SDKFeatureMetadata,
+    FlagResultWithMetadata,
+    EvaluationResultWithMetadata
+} from '../flagsmith-engine/evaluation/models.js';
 import { FeatureStateModel } from '../flagsmith-engine/features/models.js';
 import { AnalyticsProcessor } from './analytics.js';
 
-type FlagValue = string | number | boolean | undefined;
+type FlagValue = string | number | boolean | undefined | null;
 
 /**
  * A Flagsmith feature. It has an enabled/disabled state, and an optional {@link FlagValue}.
@@ -49,6 +54,10 @@ export class Flag extends BaseFlag {
      * The programmatic name for this feature, unique per Flagsmith project.
      */
     featureName: string;
+    /**
+     * The reason for this feature, unique per Flagsmith project.
+     */
+    reason?: string;
 
     constructor(params: {
         value: FlagValue;
@@ -56,10 +65,12 @@ export class Flag extends BaseFlag {
         isDefault?: boolean;
         featureId: number;
         featureName: string;
+        reason?: string;
     }) {
         super(params.value, params.enabled, !!params.isDefault);
         this.featureId = params.featureId;
         this.featureName = params.featureName;
+        this.reason = params.reason;
     }
 
     static fromFeatureStateModel(
@@ -79,7 +90,8 @@ export class Flag extends BaseFlag {
             enabled: flagData['enabled'],
             value: flagData['feature_state_value'] ?? flagData['value'],
             featureId: flagData['feature']['id'],
-            featureName: flagData['feature']['name']
+            featureName: flagData['feature']['name'],
+            reason: flagData['feature']['reason']
         });
     }
 }
@@ -99,6 +111,36 @@ export class Flags {
         this.analyticsProcessor = data.analyticsProcessor;
     }
 
+    static fromEvaluationResult(
+        evaluationResult: EvaluationResultWithMetadata,
+        defaultFlagHandler?: (v: string) => DefaultFlag,
+        analyticsProcessor?: AnalyticsProcessor
+    ): Flags {
+        const flags: { [key: string]: Flag } = {};
+        for (const flag of Object.values(evaluationResult.flags)) {
+            const flagMetadataId = flag.metadata?.id;
+            if (!flagMetadataId) {
+                throw new Error(
+                    `FlagResult metadata.id is missing for feature "${flag.name}". ` +
+                        `This indicates a bug in the SDK, please report it.`
+                );
+            }
+
+            flags[flag.name] = new Flag({
+                enabled: flag.enabled,
+                value: flag.value ?? null,
+                featureId: flagMetadataId,
+                featureName: flag.name,
+                reason: flag.reason
+            });
+        }
+        return new Flags({
+            flags: flags,
+            defaultFlagHandler: defaultFlagHandler,
+            analyticsProcessor: analyticsProcessor
+        });
+    }
+
     static fromFeatureStateModels(data: {
         featureStates: FeatureStateModel[];
         analyticsProcessor?: AnalyticsProcessor;

package/sdk/utils.ts

@@ -3,6 +3,9 @@ import { Dispatcher } from 'undici-types';
 
 type Traits = { [key: string]: TraitConfig | FlagsmithTraitValue };
 
+const FLAGSMITH_USER_AGENT = 'flagsmith-nodejs-sdk';
+const FLAGSMITH_UNKNOWN_VERSION = 'unknown';
+
 export function isTraitConfig(
     traitValue: TraitConfig | FlagsmithTraitValue
 ): traitValue is TraitConfig {
@@ -102,3 +105,13 @@ export class Deferred<T> {
         this.rejectPromise(reason);
     }
 }
+
+export function getUserAgent(): string {
+    try {
+        const packageJson = require('../package.json');
+        const version = packageJson?.version;
+        return version ? `${FLAGSMITH_USER_AGENT}/${version}` : FLAGSMITH_UNKNOWN_VERSION;
+    } catch {
+        return FLAGSMITH_UNKNOWN_VERSION;
+    }
+}

package/tests/engine/e2e/engine.test.ts

@@ -1,46 +1,51 @@
-import { getIdentityFeatureStates } from '../../../flagsmith-engine/index.js';
-import { EnvironmentModel } from '../../../flagsmith-engine/environments/models.js';
-import { buildEnvironmentModel } from '../../../flagsmith-engine/environments/util.js';
-import { IdentityModel } from '../../../flagsmith-engine/identities/models.js';
-import { buildIdentityModel } from '../../../flagsmith-engine/identities/util.js';
-import * as testData from '../engine-tests/engine-test-data/data/environment_n9fbf9h3v4fFgH3U3ngWhb.json';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { getEvaluationResult } from '../../../flagsmith-engine/index.js';
+import { Flags } from '../../../sdk/models.js';
+import { EvaluationContext } from '../../../flagsmith-engine/evaluation/evaluationContext/evaluationContext.types.js';
+import { parse as parseJsonc } from 'jsonc-parser';
+import {
+    EvaluationContextWithMetadata,
+    EvaluationResult
+} from '../../../flagsmith-engine/evaluation/models.js';
 
-function extractTestCases(data: any): {
-    environment: EnvironmentModel;
-    identity: IdentityModel;
-    response: any;
-}[] {
-    const environmentModel = buildEnvironmentModel(data['environment']);
-    const test_data = data['identities_and_responses'].map((test_case: any) => {
-        const identity = buildIdentityModel(test_case['identity']);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEST_DATA_DIR = path.join(__dirname, '../engine-tests/engine-test-data/test_cases');
+interface TestCase {
+    context: EvaluationContext;
+    result: EvaluationResult;
+}
 
-        return {
-            environment: environmentModel,
-            identity: identity,
-            response: test_case['response']
-        };
-    });
-    return test_data;
+function getTestFiles(): string[] {
+    const files = fs.readdirSync(TEST_DATA_DIR);
+    return files
+        .filter(f => f.endsWith('.json') || f.endsWith('.jsonc'))
+        .map(f => path.join(TEST_DATA_DIR, f));
 }
 
-test('Test Engine', () => {
-    const testCases = extractTestCases(testData);
-    for (const testCase of testCases) {
-        const engine_response = getIdentityFeatureStates(testCase.environment, testCase.identity);
-        const sortedEngineFlags = engine_response.sort((a, b) =>
-            a.feature.name > b.feature.name ? 1 : -1
-        );
-        const sortedAPIFlags = testCase.response['flags'].sort((a: any, b: any) =>
-            a.feature.name > b.feature.name ? 1 : -1
-        );
+function loadTestFile(filePath: string): TestCase {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseJsonc(content);
+}
 
-        expect(sortedEngineFlags.length).toBe(sortedAPIFlags.length);
+describe('Engine Integration Tests', () => {
+    const testFiles = getTestFiles();
 
-        for (let i = 0; i < sortedEngineFlags.length; i++) {
-            expect(sortedEngineFlags[i].getValue(testCase.identity.djangoID)).toBe(
-                sortedAPIFlags[i]['feature_state_value']
-            );
-            expect(sortedEngineFlags[i].enabled).toBe(sortedAPIFlags[i]['enabled']);
-        }
+    if (testFiles.length === 0) {
+        throw new Error(`No test files found in ${TEST_DATA_DIR}`);
     }
+
+    testFiles.forEach(filePath => {
+        const testName = path.basename(filePath, path.extname(filePath));
+
+        test(testName, () => {
+            const testCase = loadTestFile(filePath);
+            const engine_response = getEvaluationResult(
+                testCase.context as EvaluationContextWithMetadata
+            );
+            expect(engine_response).toStrictEqual(testCase.result);
+        });
+    });
 });