flagsmith-nodejs 6.1.0 → 7.0.2

package/build/cjs/flagsmith-engine/segments/evaluators.js

@@ -1,37 +1,149 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.traitsMatchSegmentCondition = exports.evaluateIdentityInSegment = exports.getIdentitySegments = void 0;
+exports.getContextValue = exports.traitsMatchSegmentCondition = exports.getIdentitySegments = void 0;
+const jsonpathModule = require("jsonpath");
 const index_js_1 = require("../utils/hashing/index.js");
+const models_js_1 = require("./models.js");
 const constants_js_1 = require("./constants.js");
-function getIdentitySegments(environment, identity, overrideTraits) {
-    return environment.project.segments.filter(segment => evaluateIdentityInSegment(identity, segment, overrideTraits));
+// Handle ESM/CJS interop - jsonpath exports default in ESM
+const jsonpath = jsonpathModule.default || jsonpathModule;
+/**
+ * Returns all segments that the identity belongs to based on segment rules evaluation.
+ *
+ * An identity belongs to a segment if it matches ALL of the segment's rules.
+ * If the context has no identity or segments, returns an empty array.
+ *
+ * @param context - Evaluation context containing identity and segment definitions
+ * @returns Array of segments that the identity matches
+ */
+function getIdentitySegments(context) {
+    if (!context.identity || !context.segments)
+        return [];
+    return Object.values(context.segments).filter(segment => {
+        if (segment.rules.length === 0)
+            return false;
+        return segment.rules.every(rule => traitsMatchSegmentRule(rule, segment.key, context));
+    });
 }
 exports.getIdentitySegments = getIdentitySegments;
-function evaluateIdentityInSegment(identity, segment, overrideTraits) {
-    return (segment.rules.length > 0 &&
-        segment.rules.filter(rule => traitsMatchSegmentRule(overrideTraits || identity.identityTraits, rule, segment.id, identity.djangoID || identity.compositeKey)).length === segment.rules.length);
-}
-exports.evaluateIdentityInSegment = evaluateIdentityInSegment;
-function traitsMatchSegmentRule(identityTraits, rule, segmentId, identityId) {
-    const matchesConditions = rule.conditions.length > 0
-        ? rule.matchingFunction()(rule.conditions.map(condition => traitsMatchSegmentCondition(identityTraits, condition, segmentId, identityId)))
-        : true;
-    return (matchesConditions &&
-        rule.rules.filter(rule => traitsMatchSegmentRule(identityTraits, rule, segmentId, identityId)).length === rule.rules.length);
-}
-function traitsMatchSegmentCondition(identityTraits, condition, segmentId, identityId) {
-    if (condition.operator == constants_js_1.PERCENTAGE_SPLIT) {
-        var hashedPercentage = (0, index_js_1.getHashedPercentateForObjIds)([segmentId, identityId]);
+/**
+ * Evaluates whether a segment condition matches the identity's traits or context values.
+ *
+ * Handles different types of conditions:
+ * - PERCENTAGE_SPLIT: Deterministic percentage-based bucketing using identity key
+ * - IS_SET/IS_NOT_SET: Checks for trait existence
+ * - Standard operators: EQUAL, NOT_EQUAL, etc. via SegmentConditionModel
+ * - JSONPath expressions: $.identity.identifier, $.environment.name, etc.
+ *
+ * @param condition - The condition to evaluate (property, operator, value)
+ * @param segmentKey - Key of the segment (used for percentage split hashing)
+ * @param context - Evaluation context containing identity, traits, and environment
+ * @returns true if the condition matches
+ */
+function traitsMatchSegmentCondition(condition, segmentKey, context) {
+    if (condition.operator === constants_js_1.PERCENTAGE_SPLIT) {
+        let splitKey;
+        if (!condition.property) {
+            splitKey = context?.identity?.key;
+        }
+        else {
+            splitKey = getContextValue(condition.property, context);
+        }
+        if (!splitKey) {
+            return false;
+        }
+        const hashedPercentage = (0, index_js_1.getHashedPercentageForObjIds)([segmentKey, splitKey]);
         return hashedPercentage <= parseFloat(String(condition.value));
     }
-    const traits = identityTraits.filter(t => t.traitKey === condition.property_);
-    const trait = traits.length > 0 ? traits[0] : undefined;
+    if (!condition.property) {
+        return false;
+    }
+    const traitValue = getTraitValue(condition.property, context);
     if (condition.operator === constants_js_1.IS_SET) {
-        return !!trait;
+        return traitValue !== undefined && traitValue !== null;
+    }
+    if (condition.operator === constants_js_1.IS_NOT_SET) {
+        return traitValue === undefined || traitValue === null;
     }
-    else if (condition.operator === constants_js_1.IS_NOT_SET) {
-        return trait == undefined;
+    if (traitValue !== undefined && traitValue !== null) {
+        const segmentCondition = new models_js_1.SegmentConditionModel(condition.operator, condition.value, condition.property);
+        return segmentCondition.matchesTraitValue(traitValue);
     }
-    return trait ? condition.matchesTraitValue(trait.traitValue) : false;
+    return false;
 }
 exports.traitsMatchSegmentCondition = traitsMatchSegmentCondition;
+function traitsMatchSegmentRule(rule, segmentKey, context) {
+    const matchesConditions = evaluateConditions(rule, segmentKey, context);
+    const matchesSubRules = evaluateSubRules(rule, segmentKey, context);
+    return matchesConditions && matchesSubRules;
+}
+function evaluateConditions(rule, segmentKey, context) {
+    if (!rule.conditions || rule.conditions.length === 0)
+        return true;
+    const conditionResults = rule.conditions.map((condition) => traitsMatchSegmentCondition(condition, segmentKey, context));
+    return evaluateRuleConditions(rule.type, conditionResults);
+}
+function evaluateSubRules(rule, segmentKey, context) {
+    if (!rule.rules || rule.rules.length === 0)
+        return true;
+    return rule.rules.every((subRule) => traitsMatchSegmentRule(subRule, segmentKey, context));
+}
+function evaluateRuleConditions(ruleType, conditionResults) {
+    switch (ruleType) {
+        case 'ALL':
+            return conditionResults.length === 0 || conditionResults.every(result => result);
+        case 'ANY':
+            return conditionResults.length > 0 && conditionResults.some(result => result);
+        case 'NONE':
+            return conditionResults.length === 0 || conditionResults.every(result => !result);
+        default:
+            return false;
+    }
+}
+function getTraitValue(property, context) {
+    if (property.startsWith('$.')) {
+        const contextValue = getContextValue(property, context);
+        if (contextValue !== undefined && isPrimitive(contextValue)) {
+            return contextValue;
+        }
+    }
+    const traits = context?.identity?.traits || {};
+    return traits[property];
+}
+function isPrimitive(value) {
+    if (value === null || value === undefined) {
+        return true;
+    }
+    // Objects and arrays are non-primitive
+    return typeof value !== 'object';
+}
+/**
+ * Evaluates JSONPath expressions against the evaluation context.
+ *
+ * Supports accessing nested context values using JSONPath syntax.
+ * Commonly used paths:
+ * - $.identity.identifier - User's unique identifier
+ * - $.identity.key - User's internal key
+ * - $.environment.name - Environment name
+ * - $.environment.key - Environment key
+ *
+ * @param jsonPath - JSONPath expression starting with '$.'
+ * @param context - Evaluation context to query against
+ * @returns The resolved value, or undefined if path doesn't exist or is invalid
+ */
+function getContextValue(jsonPath, context) {
+    if (!context || !jsonPath?.startsWith('$.'))
+        return undefined;
+    try {
+        const normalizedPath = normalizeJsonPath(jsonPath);
+        const results = jsonpath.query(context, normalizedPath);
+        return results.length > 0 ? results[0] : undefined;
+    }
+    catch (error) {
+        return undefined;
+    }
+}
+exports.getContextValue = getContextValue;
+function normalizeJsonPath(jsonPath) {
+    return jsonPath.replace(/\.([^.\[\]]+)$/, "['$1']");
+}

package/build/cjs/flagsmith-engine/segments/models.d.ts

@@ -1,11 +1,13 @@
 import { FeatureStateModel } from '../features/models.js';
+import { EvaluationContext } from '../evaluation/evaluationContext/evaluationContext.types.js';
+import { EvaluationResultSegments } from '../evaluation/models.js';
 export declare const all: (iterable: Array<any>) => boolean;
 export declare const any: (iterable: Array<any>) => boolean;
 export declare const matchingFunctions: {
     [x: string]: (thisValue: any, otherValue: any) => any;
 };
 export declare const semverMatchingFunction: {
-    [x: string]: ((thisValue: any, otherValue: any) => any) | ((thisValue: any, otherValue: any) => boolean);
+    [x: string]: ((thisValue: any, otherValue: any) => any) | ((conditionValue: any, traitValue: any) => boolean);
 };
 export declare const getMatchingFunctions: (semver: boolean) => {
     [x: string]: (thisValue: any, otherValue: any) => any;
@@ -15,9 +17,9 @@ export declare class SegmentConditionModel {
         [key: string]: string;
     };
     operator: string;
-    value: string | null | undefined;
-    property_: string | null | undefined;
-    constructor(operator: string, value?: string | null | undefined, property?: string | null | undefined);
+    value: string | null | undefined | string[];
+    property: string | null | undefined;
+    constructor(operator: string, value?: string | null | undefined | string[], property?: string | null | undefined);
     matchesTraitValue(traitValue: any): any;
 }
 export declare class SegmentRuleModel {
@@ -34,4 +36,7 @@ export declare class SegmentModel {
     rules: SegmentRuleModel[];
     featureStates: FeatureStateModel[];
     constructor(id: number, name: string);
+    static fromSegmentResult(segmentResults: EvaluationResultSegments, evaluationContext: EvaluationContext): SegmentModel[];
+    private static createFeatureStatesFromOverrides;
+    private static createMultivariateValues;
 }

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

@@ -2,9 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SegmentModel = exports.SegmentRuleModel = exports.SegmentConditionModel = exports.getMatchingFunctions = exports.semverMatchingFunction = exports.matchingFunctions = exports.any = exports.all = void 0;
 const semver = require("semver");
+const models_js_1 = require("../features/models.js");
 const index_js_1 = require("../utils/index.js");
 const constants_js_1 = require("./constants.js");
 const util_js_1 = require("./util.js");
+const constants_js_2 = require("../features/constants.js");
+const models_js_2 = require("../evaluation/models.js");
 const all = (iterable) => iterable.filter(e => !!e).length === iterable.length;
 exports.all = all;
 const any = (iterable) => iterable.filter(e => !!e).length > 0;
@@ -16,15 +19,33 @@ exports.matchingFunctions = {
     [constants_js_1.CONDITION_OPERATORS.LESS_THAN]: (thisValue, otherValue) => thisValue > otherValue,
     [constants_js_1.CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: (thisValue, otherValue) => thisValue >= otherValue,
     [constants_js_1.CONDITION_OPERATORS.NOT_EQUAL]: (thisValue, otherValue) => thisValue != otherValue,
-    [constants_js_1.CONDITION_OPERATORS.CONTAINS]: (thisValue, otherValue) => !!otherValue && otherValue.includes(thisValue)
+    [constants_js_1.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;
+        }
+    };
 };
 exports.semverMatchingFunction = {
     ...exports.matchingFunctions,
-    [constants_js_1.CONDITION_OPERATORS.EQUAL]: (thisValue, otherValue) => semver.eq(thisValue, otherValue),
-    [constants_js_1.CONDITION_OPERATORS.GREATER_THAN]: (thisValue, otherValue) => semver.gt(otherValue, thisValue),
-    [constants_js_1.CONDITION_OPERATORS.GREATER_THAN_INCLUSIVE]: (thisValue, otherValue) => semver.gte(otherValue, thisValue),
-    [constants_js_1.CONDITION_OPERATORS.LESS_THAN]: (thisValue, otherValue) => semver.gt(thisValue, otherValue),
-    [constants_js_1.CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: (thisValue, otherValue) => semver.gte(thisValue, otherValue)
+    [constants_js_1.CONDITION_OPERATORS.EQUAL]: safeSemverCompare((conditionValue, traitValue) => semver.eq(traitValue, conditionValue)),
+    [constants_js_1.CONDITION_OPERATORS.GREATER_THAN]: safeSemverCompare((conditionValue, traitValue) => semver.gt(traitValue, conditionValue)),
+    [constants_js_1.CONDITION_OPERATORS.GREATER_THAN_INCLUSIVE]: safeSemverCompare((conditionValue, traitValue) => semver.gte(traitValue, conditionValue)),
+    [constants_js_1.CONDITION_OPERATORS.LESS_THAN]: safeSemverCompare((conditionValue, traitValue) => semver.lt(traitValue, conditionValue)),
+    [constants_js_1.CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: safeSemverCompare((conditionValue, traitValue) => semver.lte(traitValue, conditionValue))
 };
 const getMatchingFunctions = (semver) => semver ? exports.semverMatchingFunction : exports.matchingFunctions;
 exports.getMatchingFunctions = getMatchingFunctions;
@@ -37,11 +58,11 @@ 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 = {
@@ -51,17 +72,49 @@ 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());
             }
         };
@@ -107,5 +160,54 @@ 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 === models_js_2.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 models_js_1.FeatureModel(overrideMetadataId, override.name, override.variants?.length && override.variants.length > 0
+                ? constants_js_2.CONSTANTS.MULTIVARIATE
+                : constants_js_2.CONSTANTS.STANDARD);
+            const featureState = new models_js_1.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 models_js_1.MultivariateFeatureStateValueModel(new models_js_1.MultivariateFeatureOptionModel(variant.value, variant.id), variant.weight, variant.id));
+    }
 }
 exports.SegmentModel = SegmentModel;

package/build/cjs/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/cjs/flagsmith-engine/utils/hashing/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getHashedPercentateForObjIds = void 0;
+exports.getHashedPercentageForObjIds = void 0;
 const node_crypto_1 = require("node:crypto");
 const md5 = (data) => (0, node_crypto_1.createHash)('md5').update(data).digest('hex');
 const makeRepeated = (arr, repeats) => Array.from({ length: repeats }, () => arr).flat();
@@ -13,7 +13,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)
  */
-function getHashedPercentateForObjIds(objectIds, iterations = 1) {
+function getHashedPercentageForObjIds(objectIds, iterations = 1) {
     let toHash = makeRepeated(objectIds, iterations).join(',');
     const hashedValue = md5(toHash);
     const hashedInt = BigInt('0x' + hashedValue);
@@ -22,8 +22,8 @@ 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;
 }
-exports.getHashedPercentateForObjIds = getHashedPercentateForObjIds;
+exports.getHashedPercentageForObjIds = getHashedPercentageForObjIds;

package/build/cjs/sdk/analytics.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnalyticsProcessor = exports.ANALYTICS_ENDPOINT = void 0;
 const pino_1 = require("pino");
+const utils_js_1 = require("./utils.js");
 exports.ANALYTICS_ENDPOINT = './analytics/flags/';
 /** Duration in seconds to wait before trying to flush collected data after {@link trackFeature} is called. **/
 const ANALYTICS_TIMER = 10;
@@ -47,7 +48,8 @@ class AnalyticsProcessor {
                 signal: AbortSignal.timeout(this.requestTimeoutMs),
                 headers: {
                     'Content-Type': 'application/json',
-                    'X-Environment-Key': this.environmentKey
+                    'X-Environment-Key': this.environmentKey,
+                    'User-Agent': (0, utils_js_1.getUserAgent)()
                 }
             });
             await this.currentFlush;

package/build/cjs/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/cjs/sdk/index.js

@@ -1,17 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Flagsmith = exports.EnvironmentDataPollingManager = exports.Flags = exports.DefaultFlag = exports.BaseFlag = exports.FlagsmithClientError = exports.FlagsmithAPIError = exports.AnalyticsProcessor = void 0;
-const index_js_1 = require("../flagsmith-engine/index.js");
 const util_js_1 = require("../flagsmith-engine/environments/util.js");
-const index_js_2 = require("../flagsmith-engine/index.js");
-const index_js_3 = require("../flagsmith-engine/index.js");
 const analytics_js_1 = require("./analytics.js");
 const errors_js_1 = require("./errors.js");
 const models_js_1 = require("./models.js");
 const polling_manager_js_1 = require("./polling_manager.js");
 const utils_js_1 = require("./utils.js");
-const evaluators_js_1 = require("../flagsmith-engine/segments/evaluators.js");
+const index_js_1 = require("../flagsmith-engine/index.js");
 const pino_1 = require("pino");
+const mappers_js_1 = require("../flagsmith-engine/evaluation/evaluationContext/mappers.js");
 var analytics_js_2 = require("./analytics.js");
 Object.defineProperty(exports, "AnalyticsProcessor", { enumerable: true, get: function () { return analytics_js_2.AnalyticsProcessor; } });
 var errors_js_2 = require("./errors.js");
@@ -230,7 +228,12 @@ class Flagsmith {
             key,
             value: traits?.[key]
         })));
-        return (0, evaluators_js_1.getIdentitySegments)(environment, identityModel);
+        const context = (0, mappers_js_1.getEvaluationContext)(environment, identityModel);
+        if (!context) {
+            throw new errors_js_1.FlagsmithClientError('Local evaluation required to obtain identity segments');
+        }
+        const evaluationResult = (0, index_js_1.getEvaluationResult)(context);
+        return index_js_1.SegmentModel.fromSegmentResult(evaluationResult.segments, context);
     }
     async fetchEnvironment() {
         const deferred = new utils_js_1.Deferred();
@@ -279,6 +282,7 @@ class Flagsmith {
         if (this.environmentKey) {
             headers['X-Environment-Key'] = this.environmentKey;
         }
+        headers['User-Agent'] = (0, utils_js_1.getUserAgent)();
         if (this.customHeaders) {
             for (const [k, v] of Object.entries(this.customHeaders)) {
                 headers[k] = v;
@@ -293,7 +297,7 @@ class Flagsmith {
         if (data.status !== 200) {
             throw new errors_js_1.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.
@@ -320,16 +324,52 @@ class Flagsmith {
         if (!this.environmentUrl) {
             throw new Error('`apiUrl` argument is missing or invalid.');
         }
-        const environment_data = await this.getJSONResponse(this.environmentUrl, 'GET');
-        return (0, util_js_1.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 (0, util_js_1.buildEnvironmentModel)(compiledDocument);
     }
     async getEnvironmentFlagsFromDocument() {
         const environment = await this.getEnvironment();
-        const flags = models_js_1.Flags.fromFeatureStateModels({
-            featureStates: (0, index_js_1.getEnvironmentFeatureStates)(environment),
-            analyticsProcessor: this.analyticsProcessor,
-            defaultFlagHandler: this.defaultFlagHandler
-        });
+        const context = (0, mappers_js_1.getEvaluationContext)(environment, undefined, undefined, true);
+        if (!context) {
+            throw new errors_js_1.FlagsmithClientError('Unable to get flags. No environment present.');
+        }
+        const evaluationResult = (0, index_js_1.getEvaluationResult)(context);
+        const flags = models_js_1.Flags.fromEvaluationResult(evaluationResult);
         if (!!this.cache) {
             await this.cache.set('flags', flags);
         }
@@ -341,13 +381,12 @@ class Flagsmith {
             key,
             value: traits[key]
         })));
-        const featureStates = (0, index_js_1.getIdentityFeatureStates)(environment, identityModel);
-        const flags = models_js_1.Flags.fromFeatureStateModels({
-            featureStates: featureStates,
-            analyticsProcessor: this.analyticsProcessor,
-            defaultFlagHandler: this.defaultFlagHandler,
-            identityID: identityModel.djangoID || identityModel.compositeKey
-        });
+        const context = (0, mappers_js_1.getEvaluationContext)(environment, identityModel);
+        if (!context) {
+            throw new errors_js_1.FlagsmithClientError('Unable to get flags. No environment present.');
+        }
+        const evaluationResult = (0, index_js_1.getEvaluationResult)(context);
+        const flags = models_js_1.Flags.fromEvaluationResult(evaluationResult, this.defaultFlagHandler, this.analyticsProcessor);
         if (!!this.cache) {
             await this.cache.set(`flags-${identifier}`, flags);
         }
@@ -357,7 +396,7 @@ 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 = models_js_1.Flags.fromAPIFlags({
             apiFlags: apiFlags,
             analyticsProcessor: this.analyticsProcessor,
@@ -373,7 +412,7 @@ class Flagsmith {
             throw new Error('`apiUrl` argument is missing or invalid.');
         }
         const data = (0, utils_js_1.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 = models_js_1.Flags.fromAPIFlags({
             apiFlags: jsonResponse['flags'],
             analyticsProcessor: this.analyticsProcessor,
@@ -385,13 +424,13 @@ class Flagsmith {
         return flags;
     }
     getIdentityModel(environment, identifier, traits) {
-        const traitModels = traits.map(trait => new index_js_3.TraitModel(trait.key, trait.value));
+        const traitModels = traits.map(trait => new index_js_1.TraitModel(trait.key, trait.value));
         let identityWithOverrides = this.identitiesWithOverridesByIdentifier?.get(identifier);
         if (identityWithOverrides) {
             identityWithOverrides.updateTraits(traitModels);
             return identityWithOverrides;
         }
-        return new index_js_2.IdentityModel('0', traitModels, [], environment.apiKey, identifier);
+        return new index_js_1.IdentityModel('0', traitModels, [], environment.apiKey, identifier);
     }
 }
 exports.Flagsmith = Flagsmith;

package/build/cjs/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;