flagsmith-nodejs 6.1.0 → 7.0.2

package/build/esm/flagsmith-engine/segments/models.js

@@ -1,7 +1,10 @@
 import * as semver from 'semver';
+import { FeatureModel, FeatureStateModel, MultivariateFeatureOptionModel, MultivariateFeatureStateValueModel } from '../features/models.js';
 import { getCastingFunction as getCastingFunction } from '../utils/index.js';
 import { ALL_RULE, ANY_RULE, NONE_RULE, NOT_CONTAINS, REGEX, MODULO, IN, CONDITION_OPERATORS } from './constants.js';
 import { isSemver } from './util.js';
+import { CONSTANTS } from '../features/constants.js';
+import { SegmentSource } from '../evaluation/models.js';
 export const all = (iterable) => iterable.filter(e => !!e).length === iterable.length;
 export const any = (iterable) => iterable.filter(e => !!e).length > 0;
 export const matchingFunctions = {
@@ -11,15 +14,33 @@ export const matchingFunctions = {
     [CONDITION_OPERATORS.LESS_THAN]: (thisValue, otherValue) => thisValue > otherValue,
     [CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: (thisValue, otherValue) => thisValue >= otherValue,
     [CONDITION_OPERATORS.NOT_EQUAL]: (thisValue, otherValue) => thisValue != otherValue,
-    [CONDITION_OPERATORS.CONTAINS]: (thisValue, otherValue) => !!otherValue && otherValue.includes(thisValue)
+    [CONDITION_OPERATORS.CONTAINS]: (thisValue, otherValue) => {
+        try {
+            return !!otherValue && otherValue.includes(thisValue);
+        }
+        catch {
+            return false;
+        }
+    }
+};
+// Semver library throws an error if the version is invalid, in this case, we want to catch and return false
+const safeSemverCompare = (semverMatchingFunction) => {
+    return (conditionValue, traitValue) => {
+        try {
+            return semverMatchingFunction(conditionValue, traitValue);
+        }
+        catch {
+            return false;
+        }
+    };
 };
 export const semverMatchingFunction = {
     ...matchingFunctions,
-    [CONDITION_OPERATORS.EQUAL]: (thisValue, otherValue) => semver.eq(thisValue, otherValue),
-    [CONDITION_OPERATORS.GREATER_THAN]: (thisValue, otherValue) => semver.gt(otherValue, thisValue),
-    [CONDITION_OPERATORS.GREATER_THAN_INCLUSIVE]: (thisValue, otherValue) => semver.gte(otherValue, thisValue),
-    [CONDITION_OPERATORS.LESS_THAN]: (thisValue, otherValue) => semver.gt(thisValue, otherValue),
-    [CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: (thisValue, otherValue) => semver.gte(thisValue, otherValue)
+    [CONDITION_OPERATORS.EQUAL]: safeSemverCompare((conditionValue, traitValue) => semver.eq(traitValue, conditionValue)),
+    [CONDITION_OPERATORS.GREATER_THAN]: safeSemverCompare((conditionValue, traitValue) => semver.gt(traitValue, conditionValue)),
+    [CONDITION_OPERATORS.GREATER_THAN_INCLUSIVE]: safeSemverCompare((conditionValue, traitValue) => semver.gte(traitValue, conditionValue)),
+    [CONDITION_OPERATORS.LESS_THAN]: safeSemverCompare((conditionValue, traitValue) => semver.lt(traitValue, conditionValue)),
+    [CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: safeSemverCompare((conditionValue, traitValue) => semver.lte(traitValue, conditionValue))
 };
 export const getMatchingFunctions = (semver) => semver ? semverMatchingFunction : matchingFunctions;
 export class SegmentConditionModel {
@@ -31,11 +52,11 @@ export class SegmentConditionModel {
     };
     operator;
     value;
-    property_;
+    property;
     constructor(operator, value, property) {
         this.operator = operator;
         this.value = value;
-        this.property_ = property;
+        this.property = property;
     }
     matchesTraitValue(traitValue) {
         const evaluators = {
@@ -45,17 +66,49 @@ export class SegmentConditionModel {
                     !traitValue.includes(this.value?.toString()));
             },
             evaluateRegex: (traitValue) => {
-                return !!this.value && !!traitValue?.toString().match(new RegExp(this.value));
+                try {
+                    if (!this.value) {
+                        return false;
+                    }
+                    const regex = new RegExp(this.value?.toString());
+                    return !!traitValue?.toString().match(regex);
+                }
+                catch {
+                    return false;
+                }
             },
             evaluateModulo: (traitValue) => {
-                if (isNaN(parseFloat(traitValue)) || !this.value) {
+                const parsedTraitValue = parseFloat(traitValue);
+                if (isNaN(parsedTraitValue) || !this.value) {
+                    return false;
+                }
+                const parts = this.value.toString().split('|');
+                if (parts.length !== 2) {
+                    return false;
+                }
+                const divisor = parseFloat(parts[0]);
+                const remainder = parseFloat(parts[1]);
+                if (isNaN(divisor) || isNaN(remainder) || divisor === 0) {
                     return false;
                 }
-                const parts = this.value.split('|');
-                const [divisor, reminder] = [parseFloat(parts[0]), parseFloat(parts[1])];
-                return traitValue % divisor === reminder;
+                return parsedTraitValue % divisor === remainder;
             },
             evaluateIn: (traitValue) => {
+                if (!traitValue || typeof traitValue === 'boolean') {
+                    return false;
+                }
+                if (Array.isArray(this.value)) {
+                    return this.value.includes(traitValue.toString());
+                }
+                if (typeof this.value === 'string') {
+                    try {
+                        const parsed = JSON.parse(this.value);
+                        if (Array.isArray(parsed)) {
+                            return parsed.includes(traitValue.toString());
+                        }
+                    }
+                    catch { }
+                }
                 return this.value?.split(',').includes(traitValue.toString());
             }
         };
@@ -99,4 +152,53 @@ export class SegmentModel {
         this.id = id;
         this.name = name;
     }
+    static fromSegmentResult(segmentResults, evaluationContext) {
+        const segmentModels = [];
+        if (!evaluationContext.segments) {
+            return [];
+        }
+        for (const segmentResult of segmentResults) {
+            if (segmentResult.metadata?.source === SegmentSource.IDENTITY_OVERRIDE) {
+                continue;
+            }
+            const segmentMetadataId = segmentResult.metadata?.id;
+            if (!segmentMetadataId) {
+                continue;
+            }
+            const segmentContext = evaluationContext.segments[segmentMetadataId.toString()];
+            if (segmentContext) {
+                const segment = new SegmentModel(segmentMetadataId, segmentContext.name);
+                segment.rules = segmentContext.rules.map(rule => new SegmentRuleModel(rule.type));
+                segment.featureStates = SegmentModel.createFeatureStatesFromOverrides(segmentContext.overrides || []);
+                segmentModels.push(segment);
+            }
+        }
+        return segmentModels;
+    }
+    static createFeatureStatesFromOverrides(overrides) {
+        if (!overrides)
+            return [];
+        return overrides
+            .filter(override => {
+            const overrideMetadataId = override?.metadata?.id;
+            return typeof overrideMetadataId === 'number';
+        })
+            .map(override => {
+            const overrideMetadataId = override.metadata.id;
+            const feature = new FeatureModel(overrideMetadataId, override.name, override.variants?.length && override.variants.length > 0
+                ? CONSTANTS.MULTIVARIATE
+                : CONSTANTS.STANDARD);
+            const featureState = new FeatureStateModel(feature, override.enabled, override.priority || 0);
+            if (override.value !== undefined) {
+                featureState.setValue(override.value);
+            }
+            if (override.variants && override.variants.length > 0) {
+                featureState.multivariateFeatureStateValues = this.createMultivariateValues(override.variants);
+            }
+            return featureState;
+        });
+    }
+    static createMultivariateValues(variants) {
+        return variants.map(variant => new MultivariateFeatureStateValueModel(new MultivariateFeatureOptionModel(variant.value, variant.id), variant.weight, variant.id));
+    }
 }

package/build/esm/flagsmith-engine/utils/hashing/index.d.ts

@@ -6,4 +6,4 @@
  * @param  {} iterations=1 num times to include each id in the generated string to hash
  * @returns number number between 0 (inclusive) and 100 (exclusive)
  */
-export declare function getHashedPercentateForObjIds(objectIds: Array<any>, iterations?: number): number;
+export declare function getHashedPercentageForObjIds(objectIds: Array<any>, iterations?: number): number;

package/build/esm/flagsmith-engine/utils/hashing/index.js

@@ -10,7 +10,7 @@ const makeRepeated = (arr, repeats) => Array.from({ length: repeats }, () => arr
  * @param  {} iterations=1 num times to include each id in the generated string to hash
  * @returns number number between 0 (inclusive) and 100 (exclusive)
  */
-export function getHashedPercentateForObjIds(objectIds, iterations = 1) {
+export function getHashedPercentageForObjIds(objectIds, iterations = 1) {
     let toHash = makeRepeated(objectIds, iterations).join(',');
     const hashedValue = md5(toHash);
     const hashedInt = BigInt('0x' + hashedValue);
@@ -19,7 +19,7 @@ export function getHashedPercentateForObjIds(objectIds, iterations = 1) {
     /* istanbul ignore next */
     if (value === 100) {
         /* istanbul ignore next */
-        return getHashedPercentateForObjIds(objectIds, iterations + 1);
+        return getHashedPercentageForObjIds(objectIds, iterations + 1);
     }
     return value;
 }

package/build/esm/sdk/analytics.js

@@ -1,4 +1,5 @@
 import { pino } from 'pino';
+import { getUserAgent } from './utils.js';
 export const ANALYTICS_ENDPOINT = './analytics/flags/';
 /** Duration in seconds to wait before trying to flush collected data after {@link trackFeature} is called. **/
 const ANALYTICS_TIMER = 10;
@@ -44,7 +45,8 @@ export class AnalyticsProcessor {
                 signal: AbortSignal.timeout(this.requestTimeoutMs),
                 headers: {
                     'Content-Type': 'application/json',
-                    'X-Environment-Key': this.environmentKey
+                    'X-Environment-Key': this.environmentKey,
+                    'User-Agent': getUserAgent()
                 }
             });
             await this.currentFlush;

package/build/esm/sdk/index.d.ts

@@ -1,10 +1,8 @@
 import { Dispatcher } from 'undici-types';
-import { EnvironmentModel } from '../flagsmith-engine/index.js';
-import { IdentityModel } from '../flagsmith-engine/index.js';
 import { BaseOfflineHandler } from './offline_handlers.js';
 import { DefaultFlag, Flags } from './models.js';
 import { EnvironmentDataPollingManager } from './polling_manager.js';
-import { SegmentModel } from '../flagsmith-engine/index.js';
+import { SegmentModel, EnvironmentModel, IdentityModel } from '../flagsmith-engine/index.js';
 import { FlagsmithConfig, FlagsmithTraitValue, TraitConfig } from './types.js';
 export { AnalyticsProcessor, AnalyticsProcessorOptions } from './analytics.js';
 export { FlagsmithAPIError, FlagsmithClientError } from './errors.js';

package/build/esm/sdk/index.js

@@ -1,14 +1,12 @@
-import { getEnvironmentFeatureStates, getIdentityFeatureStates } 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 { FlagsmithAPIError } from './errors.js';
+import { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
 import { Flags } from './models.js';
 import { EnvironmentDataPollingManager } from './polling_manager.js';
-import { Deferred, generateIdentitiesData, retryFetch } from './utils.js';
-import { getIdentitySegments } from '../flagsmith-engine/segments/evaluators.js';
+import { Deferred, generateIdentitiesData, getUserAgent, retryFetch } from './utils.js';
+import { SegmentModel, IdentityModel, TraitModel, getEvaluationResult } from '../flagsmith-engine/index.js';
 import { pino } from 'pino';
+import { getEvaluationContext } from '../flagsmith-engine/evaluation/evaluationContext/mappers.js';
 export { AnalyticsProcessor } from './analytics.js';
 export { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
 export { BaseFlag, DefaultFlag, Flags } from './models.js';
@@ -220,7 +218,12 @@ export class Flagsmith {
             key,
             value: traits?.[key]
         })));
-        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);
+        return SegmentModel.fromSegmentResult(evaluationResult.segments, context);
     }
     async fetchEnvironment() {
         const deferred = new Deferred();
@@ -269,6 +272,7 @@ export class Flagsmith {
         if (this.environmentKey) {
             headers['X-Environment-Key'] = this.environmentKey;
         }
+        headers['User-Agent'] = getUserAgent();
         if (this.customHeaders) {
             for (const [k, v] of Object.entries(this.customHeaders)) {
                 headers[k] = v;
@@ -283,7 +287,7 @@ export class Flagsmith {
         if (data.status !== 200) {
             throw new FlagsmithAPIError(`Invalid request made to Flagsmith API. Response status code: ${data.status}`);
         }
-        return data.json();
+        return { response: data, data: await data.json() };
     }
     /**
      * This promise ensures that the environment is retrieved before attempting to locally evaluate.
@@ -310,16 +314,52 @@ 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 = [];
+        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);
     }
     async getEnvironmentFlagsFromDocument() {
         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);
+        const flags = Flags.fromEvaluationResult(evaluationResult);
         if (!!this.cache) {
             await this.cache.set('flags', flags);
         }
@@ -331,13 +371,12 @@ export class Flagsmith {
             key,
             value: traits[key]
         })));
-        const featureStates = getIdentityFeatureStates(environment, identityModel);
-        const flags = Flags.fromFeatureStateModels({
-            featureStates: featureStates,
-            analyticsProcessor: this.analyticsProcessor,
-            defaultFlagHandler: this.defaultFlagHandler,
-            identityID: identityModel.djangoID || identityModel.compositeKey
-        });
+        const context = getEvaluationContext(environment, identityModel);
+        if (!context) {
+            throw new FlagsmithClientError('Unable to get flags. No environment present.');
+        }
+        const evaluationResult = getEvaluationResult(context);
+        const flags = Flags.fromEvaluationResult(evaluationResult, this.defaultFlagHandler, this.analyticsProcessor);
         if (!!this.cache) {
             await this.cache.set(`flags-${identifier}`, flags);
         }
@@ -347,7 +386,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,
@@ -363,7 +402,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/build/esm/sdk/models.d.ts

@@ -1,6 +1,7 @@
+import { 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}.
  */
@@ -38,12 +39,17 @@ export declare 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;
         enabled: boolean;
         isDefault?: boolean;
         featureId: number;
         featureName: string;
+        reason?: string;
     });
     static fromFeatureStateModel(fsm: FeatureStateModel, identityId: number | string | undefined): Flag;
     static fromAPIFlag(flagData: any): Flag;
@@ -61,6 +67,7 @@ export declare class Flags {
         defaultFlagHandler?: (v: string) => DefaultFlag;
         analyticsProcessor?: AnalyticsProcessor;
     });
+    static fromEvaluationResult(evaluationResult: EvaluationResultWithMetadata, defaultFlagHandler?: (v: string) => DefaultFlag, analyticsProcessor?: AnalyticsProcessor): Flags;
     static fromFeatureStateModels(data: {
         featureStates: FeatureStateModel[];
         analyticsProcessor?: AnalyticsProcessor;

package/build/esm/sdk/models.js

@@ -41,10 +41,15 @@ export class Flag extends BaseFlag {
      * The programmatic name for this feature, unique per Flagsmith project.
      */
     featureName;
+    /**
+     * The reason for this feature, unique per Flagsmith project.
+     */
+    reason;
     constructor(params) {
         super(params.value, params.enabled, !!params.isDefault);
         this.featureId = params.featureId;
         this.featureName = params.featureName;
+        this.reason = params.reason;
     }
     static fromFeatureStateModel(fsm, identityId) {
         return new Flag({
@@ -59,7 +64,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']
         });
     }
 }
@@ -72,6 +78,28 @@ export class Flags {
         this.defaultFlagHandler = data.defaultFlagHandler;
         this.analyticsProcessor = data.analyticsProcessor;
     }
+    static fromEvaluationResult(evaluationResult, defaultFlagHandler, analyticsProcessor) {
+        const flags = {};
+        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) {
         const flags = {};
         for (const fs of data.featureStates) {

package/build/esm/sdk/utils.d.ts

@@ -56,4 +56,5 @@ export declare class Deferred<T> {
     resolve(value: T | PromiseLike<T>): void;
     reject(reason?: unknown): void;
 }
+export declare function getUserAgent(): string;
 export {};

package/build/esm/sdk/utils.js

@@ -1,3 +1,5 @@
+const FLAGSMITH_USER_AGENT = 'flagsmith-nodejs-sdk';
+const FLAGSMITH_UNKNOWN_VERSION = 'unknown';
 export function isTraitConfig(traitValue) {
     return !!traitValue && typeof traitValue == 'object' && traitValue.value !== undefined;
 }
@@ -85,3 +87,13 @@ export class Deferred {
         this.rejectPromise(reason);
     }
 }
+export function getUserAgent() {
+    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/flagsmith-engine/environments/models.ts

@@ -38,10 +38,12 @@ export class EnvironmentModel {
     project: ProjectModel;
     featureStates: FeatureStateModel[] = [];
     identityOverrides: IdentityModel[] = [];
+    name: string;
 
-    constructor(id: number, apiKey: string, project: ProjectModel) {
+    constructor(id: number, apiKey: string, project: ProjectModel, name: string) {
         this.id = id;
         this.apiKey = apiKey;
         this.project = project;
+        this.name = name;
     }
 }

package/flagsmith-engine/environments/util.ts

@@ -11,7 +11,8 @@ export function buildEnvironmentModel(environmentJSON: any) {
     const environmentModel = new EnvironmentModel(
         environmentJSON.id,
         environmentJSON.api_key,
-        project
+        project,
+        environmentJSON.name
     );
     environmentModel.featureStates = featureStates;
     if (!!environmentJSON.identity_overrides) {