flagsmith-nodejs 6.0.1 → 6.2.0

package/CODEOWNERS

@@ -0,0 +1 @@
+* @flagsmith/flagsmith-back-end

package/README.md

@@ -1,5 +1,3 @@
-<img width="100%" src="https://github.com/Flagsmith/flagsmith/raw/main/static-files/hero.png"/>
-
 # Flagsmith NodeJS Client
 
 [![npm version](https://badge.fury.io/js/flagsmith-nodejs.svg)](https://badge.fury.io/js/flagsmith-nodejs)
@@ -21,10 +19,11 @@ If you encounter a bug or feature request we would like to hear about it. Before
 
 ## Testing
 
-To run the local tests you need to run following command beforehand:
+To run the local tests you need to run following commands beforehand:
 
 ```bash
 git submodule add git@github.com:Flagsmith/engine-test-data.git tests/engine/engine-tests/engine-test-data/
+git submodule update --init --recursive
 ```
 
 ## Get in touch

package/build/cjs/flagsmith-engine/features/util.js

@@ -8,9 +8,9 @@ function buildFeatureModel(featuresModelJSON) {
 exports.buildFeatureModel = buildFeatureModel;
 function buildFeatureStateModel(featuresStateModelJSON) {
     const featureStateModel = new models_js_1.FeatureStateModel(buildFeatureModel(featuresStateModelJSON.feature), featuresStateModelJSON.enabled, featuresStateModelJSON.django_id, featuresStateModelJSON.feature_state_value, featuresStateModelJSON.featurestate_uuid);
-    featureStateModel.featureSegment = featuresStateModelJSON.feature_segment ?
-        buildFeatureSegment(featuresStateModelJSON.feature_segment) :
-        undefined;
+    featureStateModel.featureSegment = featuresStateModelJSON.feature_segment
+        ? buildFeatureSegment(featuresStateModelJSON.feature_segment)
+        : undefined;
     const multivariateFeatureStateValues = featuresStateModelJSON.multivariate_feature_state_values
         ? featuresStateModelJSON.multivariate_feature_state_values.map((fsv) => {
             const featureOption = new models_js_1.MultivariateFeatureOptionModel(fsv.multivariate_feature_option.value, fsv.multivariate_feature_option.id);

package/build/cjs/flagsmith-engine/index.d.ts

@@ -3,7 +3,7 @@ import { FeatureStateModel } from './features/models.js';
 import { IdentityModel } from './identities/models.js';
 import { TraitModel } from './identities/traits/models.js';
 export { EnvironmentModel } from './environments/models.js';
-export { FeatureStateModel } from './features/models.js';
+export { FeatureModel, FeatureStateModel } from './features/models.js';
 export { IdentityModel } from './identities/models.js';
 export { TraitModel } from './identities/traits/models.js';
 export { SegmentModel } from './segments/models.js';

package/build/cjs/flagsmith-engine/index.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getEnvironmentFeatureStates = exports.getEnvironmentFeatureState = exports.getIdentityFeatureStates = exports.getIdentityFeatureState = exports.OrganisationModel = exports.SegmentModel = exports.TraitModel = exports.IdentityModel = exports.FeatureStateModel = exports.EnvironmentModel = void 0;
+exports.getEnvironmentFeatureStates = exports.getEnvironmentFeatureState = exports.getIdentityFeatureStates = exports.getIdentityFeatureState = exports.OrganisationModel = exports.SegmentModel = exports.TraitModel = exports.IdentityModel = exports.FeatureStateModel = exports.FeatureModel = exports.EnvironmentModel = void 0;
 const evaluators_js_1 = require("./segments/evaluators.js");
 const errors_js_1 = require("./utils/errors.js");
 var models_js_1 = require("./environments/models.js");
 Object.defineProperty(exports, "EnvironmentModel", { enumerable: true, get: function () { return models_js_1.EnvironmentModel; } });
 var models_js_2 = require("./features/models.js");
+Object.defineProperty(exports, "FeatureModel", { enumerable: true, get: function () { return models_js_2.FeatureModel; } });
 Object.defineProperty(exports, "FeatureStateModel", { enumerable: true, get: function () { return models_js_2.FeatureStateModel; } });
 var models_js_3 = require("./identities/models.js");
 Object.defineProperty(exports, "IdentityModel", { enumerable: true, get: function () { return models_js_3.IdentityModel; } });

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

@@ -16,7 +16,7 @@ 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) => !!otherValue && otherValue.includes(thisValue)
 };
 exports.semverMatchingFunction = {
     ...exports.matchingFunctions,
@@ -24,9 +24,9 @@ exports.semverMatchingFunction = {
     [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.LESS_THAN_INCLUSIVE]: (thisValue, otherValue) => semver.gte(thisValue, otherValue)
 };
-const getMatchingFunctions = (semver) => (semver ? exports.semverMatchingFunction : exports.matchingFunctions);
+const getMatchingFunctions = (semver) => semver ? exports.semverMatchingFunction : exports.matchingFunctions;
 exports.getMatchingFunctions = getMatchingFunctions;
 class SegmentConditionModel {
     EXCEPTION_OPERATOR_METHODS = {
@@ -46,9 +46,9 @@ class SegmentConditionModel {
     matchesTraitValue(traitValue) {
         const evaluators = {
             evaluateNotContains: (traitValue) => {
-                return typeof traitValue == "string" &&
+                return (typeof traitValue == 'string' &&
                     !!this.value &&
-                    !traitValue.includes(this.value?.toString());
+                    !traitValue.includes(this.value?.toString()));
             },
             evaluateRegex: (traitValue) => {
                 return !!this.value && !!traitValue?.toString().match(new RegExp(this.value));
@@ -57,13 +57,13 @@ class SegmentConditionModel {
                 if (isNaN(parseFloat(traitValue)) || !this.value) {
                     return false;
                 }
-                const parts = (this.value).split("|");
+                const parts = this.value.split('|');
                 const [divisor, reminder] = [parseFloat(parts[0]), parseFloat(parts[1])];
                 return traitValue % divisor === reminder;
             },
             evaluateIn: (traitValue) => {
                 return this.value?.split(',').includes(traitValue.toString());
-            },
+            }
         };
         // TODO: move this logic to the evaluator module
         if (this.EXCEPTION_OPERATOR_METHODS[this.operator]) {

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

@@ -17,7 +17,7 @@ function getHashedPercentateForObjIds(objectIds, iterations = 1) {
     let toHash = makeRepeated(objectIds, iterations).join(',');
     const hashedValue = md5(toHash);
     const hashedInt = BigInt('0x' + hashedValue);
-    const value = (Number((hashedInt % 9999n)) / 9998.0) * 100;
+    const value = (Number(hashedInt % 9999n) / 9998.0) * 100;
     // we ignore this for it's nearly impossible use case to catch
     /* istanbul ignore next */
     if (value === 100) {

package/build/cjs/index.d.ts

@@ -1,4 +1,4 @@
-export { AnalyticsProcessor, AnalyticsProcessorOptions, FlagsmithAPIError, FlagsmithClientError, EnvironmentDataPollingManager, FlagsmithCache, DefaultFlag, Flags, Flagsmith, } from './sdk/index.js';
-export { BaseOfflineHandler, LocalFileHandler, } from './sdk/offline_handlers.js';
-export { FlagsmithConfig } from './sdk/types.js';
-export { EnvironmentModel, FeatureStateModel, IdentityModel, TraitModel, SegmentModel, OrganisationModel } from './flagsmith-engine/index.js';
+export { AnalyticsProcessor, AnalyticsProcessorOptions, FlagsmithAPIError, FlagsmithClientError, EnvironmentDataPollingManager, FlagsmithCache, BaseFlag, DefaultFlag, Flags, Flagsmith } from './sdk/index.js';
+export { BaseOfflineHandler, LocalFileHandler } from './sdk/offline_handlers.js';
+export { FlagsmithConfig, FlagsmithValue, TraitConfig } from './sdk/types.js';
+export { EnvironmentModel, FeatureModel, FeatureStateModel, IdentityModel, TraitModel, SegmentModel, OrganisationModel } from './flagsmith-engine/index.js';

package/build/cjs/index.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OrganisationModel = exports.SegmentModel = exports.TraitModel = exports.IdentityModel = exports.FeatureStateModel = exports.EnvironmentModel = exports.LocalFileHandler = exports.BaseOfflineHandler = exports.Flagsmith = exports.Flags = exports.DefaultFlag = exports.EnvironmentDataPollingManager = exports.FlagsmithClientError = exports.FlagsmithAPIError = exports.AnalyticsProcessor = void 0;
+exports.OrganisationModel = exports.SegmentModel = exports.TraitModel = exports.IdentityModel = exports.FeatureStateModel = exports.FeatureModel = exports.EnvironmentModel = exports.LocalFileHandler = exports.BaseOfflineHandler = exports.Flagsmith = exports.Flags = exports.DefaultFlag = exports.BaseFlag = exports.EnvironmentDataPollingManager = exports.FlagsmithClientError = exports.FlagsmithAPIError = exports.AnalyticsProcessor = void 0;
 var index_js_1 = require("./sdk/index.js");
 Object.defineProperty(exports, "AnalyticsProcessor", { enumerable: true, get: function () { return index_js_1.AnalyticsProcessor; } });
 Object.defineProperty(exports, "FlagsmithAPIError", { enumerable: true, get: function () { return index_js_1.FlagsmithAPIError; } });
 Object.defineProperty(exports, "FlagsmithClientError", { enumerable: true, get: function () { return index_js_1.FlagsmithClientError; } });
 Object.defineProperty(exports, "EnvironmentDataPollingManager", { enumerable: true, get: function () { return index_js_1.EnvironmentDataPollingManager; } });
+Object.defineProperty(exports, "BaseFlag", { enumerable: true, get: function () { return index_js_1.BaseFlag; } });
 Object.defineProperty(exports, "DefaultFlag", { enumerable: true, get: function () { return index_js_1.DefaultFlag; } });
 Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return index_js_1.Flags; } });
 Object.defineProperty(exports, "Flagsmith", { enumerable: true, get: function () { return index_js_1.Flagsmith; } });
@@ -14,6 +15,7 @@ Object.defineProperty(exports, "BaseOfflineHandler", { enumerable: true, get: fu
 Object.defineProperty(exports, "LocalFileHandler", { enumerable: true, get: function () { return offline_handlers_js_1.LocalFileHandler; } });
 var index_js_2 = require("./flagsmith-engine/index.js");
 Object.defineProperty(exports, "EnvironmentModel", { enumerable: true, get: function () { return index_js_2.EnvironmentModel; } });
+Object.defineProperty(exports, "FeatureModel", { enumerable: true, get: function () { return index_js_2.FeatureModel; } });
 Object.defineProperty(exports, "FeatureStateModel", { enumerable: true, get: function () { return index_js_2.FeatureStateModel; } });
 Object.defineProperty(exports, "IdentityModel", { enumerable: true, get: function () { return index_js_2.IdentityModel; } });
 Object.defineProperty(exports, "TraitModel", { enumerable: true, get: function () { return index_js_2.TraitModel; } });

package/build/cjs/sdk/analytics.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from 'pino';
-import { Fetch } from "./types.js";
+import { Fetch } from './types.js';
 export declare const ANALYTICS_ENDPOINT = "./analytics/flags/";
 export interface AnalyticsProcessorOptions {
     /** URL of the Flagsmith analytics events API endpoint

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

@@ -5,10 +5,10 @@ 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 { FlagsmithConfig, FlagsmithTraitValue, ITraitConfig } from './types.js';
+import { FlagsmithConfig, FlagsmithTraitValue, TraitConfig } from './types.js';
 export { AnalyticsProcessor, AnalyticsProcessorOptions } from './analytics.js';
 export { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
-export { DefaultFlag, Flags } from './models.js';
+export { BaseFlag, DefaultFlag, Flags } from './models.js';
 export { EnvironmentDataPollingManager } from './polling_manager.js';
 export { FlagsmithCache, FlagsmithConfig } from './types.js';
 /**
@@ -34,7 +34,7 @@ export { FlagsmithCache, FlagsmithConfig } from './types.js';
  * const bannerVariation: string = identityFlags.getFeatureValue('banner_flag')
  *
  * @see FlagsmithConfig
-*/
+ */
 export declare class Flagsmith {
     environmentKey?: string;
     apiUrl?: string;
@@ -84,12 +84,12 @@ export declare class Flagsmith {
      *
      * @param  {string} identifier a unique identifier for the identity in the current
             environment, e.g. email address, username, uuid
-     * @param  {{[key:string]:any | ITraitConfig}} traits? a dictionary of traits to add / update on the identity in
+     * @param  {{[key:string]:any | TraitConfig}} traits? a dictionary of traits to add / update on the identity in
             Flagsmith, e.g. {"num_orders": 10} or {age: {value: 30, transient: true}}
      * @returns Flags object holding all the flags for the given identity.
      */
     getIdentityFlags(identifier: string, traits?: {
-        [key: string]: FlagsmithTraitValue | ITraitConfig;
+        [key: string]: FlagsmithTraitValue | TraitConfig;
     }, transient?: boolean): Promise<Flags>;
     /**
      * Get the segments for the current environment for a given identity. Will also

package/build/cjs/sdk/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Flagsmith = exports.EnvironmentDataPollingManager = exports.Flags = exports.DefaultFlag = exports.FlagsmithClientError = exports.FlagsmithAPIError = exports.AnalyticsProcessor = void 0;
+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");
@@ -18,6 +18,7 @@ var errors_js_2 = require("./errors.js");
 Object.defineProperty(exports, "FlagsmithAPIError", { enumerable: true, get: function () { return errors_js_2.FlagsmithAPIError; } });
 Object.defineProperty(exports, "FlagsmithClientError", { enumerable: true, get: function () { return errors_js_2.FlagsmithClientError; } });
 var models_js_2 = require("./models.js");
+Object.defineProperty(exports, "BaseFlag", { enumerable: true, get: function () { return models_js_2.BaseFlag; } });
 Object.defineProperty(exports, "DefaultFlag", { enumerable: true, get: function () { return models_js_2.DefaultFlag; } });
 Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return models_js_2.Flags; } });
 var polling_manager_js_2 = require("./polling_manager.js");
@@ -47,7 +48,7 @@ const DEFAULT_REQUEST_TIMEOUT_SECONDS = 10;
  * const bannerVariation: string = identityFlags.getFeatureValue('banner_flag')
  *
  * @see FlagsmithConfig
-*/
+ */
 class Flagsmith {
     environmentKey = undefined;
     apiUrl = undefined;
@@ -116,7 +117,8 @@ class Flagsmith {
             }
             const apiUrl = data.apiUrl || DEFAULT_API_URL;
             this.apiUrl = apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`;
-            this.analyticsUrl = this.analyticsUrl || new URL(analytics_js_1.ANALYTICS_ENDPOINT, new Request(this.apiUrl).url).href;
+            this.analyticsUrl =
+                this.analyticsUrl || new URL(analytics_js_1.ANALYTICS_ENDPOINT, new Request(this.apiUrl).url).href;
             this.environmentFlagsUrl = `${this.apiUrl}flags/`;
             this.identitiesUrl = `${this.apiUrl}identities/`;
             this.environmentUrl = `${this.apiUrl}environment-document/`;
@@ -134,7 +136,7 @@ class Flagsmith {
                     environmentKey: this.environmentKey,
                     analyticsUrl: this.analyticsUrl,
                     requestTimeoutMs: this.requestTimeoutMs,
-                    logger: this.logger,
+                    logger: this.logger
                 });
             }
         }
@@ -173,7 +175,7 @@ class Flagsmith {
      *
      * @param  {string} identifier a unique identifier for the identity in the current
             environment, e.g. email address, username, uuid
-     * @param  {{[key:string]:any | ITraitConfig}} traits? a dictionary of traits to add / update on the identity in
+     * @param  {{[key:string]:any | TraitConfig}} traits? a dictionary of traits to add / update on the identity in
             Flagsmith, e.g. {"num_orders": 10} or {age: {value: 30, transient: true}}
      * @returns Flags object holding all the flags for the given identity.
      */
@@ -277,6 +279,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;
@@ -291,7 +294,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.
@@ -318,8 +321,43 @@ 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();
@@ -355,7 +393,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,
@@ -371,7 +409,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,

package/build/cjs/sdk/models.d.ts

@@ -1,17 +1,42 @@
 import { FeatureStateModel } from '../flagsmith-engine/features/models.js';
 import { AnalyticsProcessor } from './analytics.js';
 type FlagValue = string | number | boolean | undefined;
+/**
+ * A Flagsmith feature. It has an enabled/disabled state, and an optional {@link FlagValue}.
+ */
 export declare class BaseFlag {
+    /**
+     * Indicates whether this feature is enabled.
+     */
     enabled: boolean;
+    /**
+     * An optional {@link FlagValue} for this feature.
+     */
     value: FlagValue;
+    /**
+     * If true, the state for this feature was determined by a default flag handler. See {@link DefaultFlag}.
+     */
     isDefault: boolean;
     constructor(value: FlagValue, enabled: boolean, isDefault: boolean);
 }
+/**
+ * A {@link BaseFlag} returned by a default flag handler when flag evaluation fails.
+ * @see FlagsmithConfig#defaultFlagHandler
+ */
 export declare class DefaultFlag extends BaseFlag {
     constructor(value: FlagValue, enabled: boolean);
 }
+/**
+ * A Flagsmith feature retrieved from a successful flag evaluation.
+ */
 export declare class Flag extends BaseFlag {
+    /**
+     * An identifier for this feature, unique in a single Flagsmith installation.
+     */
     featureId: number;
+    /**
+     * The programmatic name for this feature, unique per Flagsmith project.
+     */
     featureName: string;
     constructor(params: {
         value: FlagValue;

package/build/cjs/sdk/models.js

@@ -1,9 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Flags = exports.Flag = exports.DefaultFlag = exports.BaseFlag = void 0;
+/**
+ * A Flagsmith feature. It has an enabled/disabled state, and an optional {@link FlagValue}.
+ */
 class BaseFlag {
+    /**
+     * Indicates whether this feature is enabled.
+     */
     enabled;
+    /**
+     * An optional {@link FlagValue} for this feature.
+     */
     value;
+    /**
+     * If true, the state for this feature was determined by a default flag handler. See {@link DefaultFlag}.
+     */
     isDefault;
     constructor(value, enabled, isDefault) {
         this.value = value;
@@ -12,14 +24,27 @@ class BaseFlag {
     }
 }
 exports.BaseFlag = BaseFlag;
+/**
+ * A {@link BaseFlag} returned by a default flag handler when flag evaluation fails.
+ * @see FlagsmithConfig#defaultFlagHandler
+ */
 class DefaultFlag extends BaseFlag {
     constructor(value, enabled) {
         super(value, enabled, true);
     }
 }
 exports.DefaultFlag = DefaultFlag;
+/**
+ * A Flagsmith feature retrieved from a successful flag evaluation.
+ */
 class Flag extends BaseFlag {
+    /**
+     * An identifier for this feature, unique in a single Flagsmith installation.
+     */
     featureId;
+    /**
+     * The programmatic name for this feature, unique per Flagsmith project.
+     */
     featureName;
     constructor(params) {
         super(params.value, params.enabled, !!params.isDefault);

package/build/cjs/sdk/types.d.ts

@@ -3,7 +3,10 @@ import { EnvironmentModel } from '../flagsmith-engine/index.js';
 import { Dispatcher } from 'undici-types';
 import { Logger } from 'pino';
 import { BaseOfflineHandler } from './offline_handlers.js';
-export type IFlagsmithValue<T = string | number | boolean | null> = T;
+/**
+ * A concrete type for the possible values of a feature.
+ */
+export type FlagsmithValue<T = string | number | boolean | null> = T;
 /**
  * Stores and retrieves {@link Flags} from a cache.
  */
@@ -89,7 +92,7 @@ export interface FlagsmithConfig {
      * const defaultHandler = () => new DefaultFlag(undefined, false)
      *
      * // Enable only VIP flags by default
-     * const vipDefaultHandler = (key: string) => new Default(undefined, key.startsWith('vip_'))
+     * const vipDefaultHandler = (key: string) => new DefaultFlag(undefined, key.startsWith('vip_'))
      */
     defaultFlagHandler?: (flagKey: string) => DefaultFlag;
     cache?: FlagsmithCache;
@@ -109,8 +112,15 @@ export interface FlagsmithConfig {
      */
     offlineHandler?: BaseOfflineHandler;
 }
-export interface ITraitConfig {
+/**
+ * Represents the configuration for a trait in Flagsmith.
+ *
+ * @property value The {@link FlagsmithTraitValue} for this trait.
+ * @property [transient] Indicates whether the trait should be persisted when used in a remote flag evaluation context.
+ * Defaults to false.
+ */
+export interface TraitConfig {
     value: FlagsmithTraitValue;
     transient?: boolean;
 }
-export declare type FlagsmithTraitValue = IFlagsmithValue;
+export declare type FlagsmithTraitValue = FlagsmithValue;

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

@@ -1,9 +1,9 @@
-import { Fetch, FlagsmithTraitValue, ITraitConfig } from './types.js';
-import { Dispatcher } from "undici-types";
+import { Fetch, FlagsmithTraitValue, TraitConfig } from './types.js';
+import { Dispatcher } from 'undici-types';
 type Traits = {
-    [key: string]: ITraitConfig | FlagsmithTraitValue;
+    [key: string]: TraitConfig | FlagsmithTraitValue;
 };
-export declare function isTraitConfig(traitValue: ITraitConfig | FlagsmithTraitValue): traitValue is ITraitConfig;
+export declare function isTraitConfig(traitValue: TraitConfig | FlagsmithTraitValue): traitValue is TraitConfig;
 export declare function generateIdentitiesData(identifier: string, traits: Traits, transient: boolean): {
     identifier: string;
     traits: ({
@@ -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/cjs/sdk/utils.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Deferred = exports.retryFetch = exports.delay = exports.generateIdentitiesData = exports.isTraitConfig = void 0;
+exports.getUserAgent = exports.Deferred = exports.retryFetch = exports.delay = exports.generateIdentitiesData = exports.isTraitConfig = void 0;
+const FLAGSMITH_USER_AGENT = 'flagsmith-nodejs-sdk';
+const FLAGSMITH_UNKNOWN_VERSION = 'unknown';
 function isTraitConfig(traitValue) {
     return !!traitValue && typeof traitValue == 'object' && traitValue.value !== undefined;
 }
@@ -11,13 +13,13 @@ function generateIdentitiesData(identifier, traits, transient) {
             return {
                 trait_key: key,
                 trait_value: value?.value,
-                transient: value?.transient,
+                transient: value?.transient
             };
         }
         else {
             return {
                 trait_key: key,
-                trait_value: value,
+                trait_value: value
             };
         }
     });
@@ -93,3 +95,14 @@ class Deferred {
     }
 }
 exports.Deferred = Deferred;
+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;
+    }
+}
+exports.getUserAgent = getUserAgent;

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

@@ -1,4 +1,4 @@
-import { randomUUID as uuidv4 } from "node:crypto";
+import { randomUUID as uuidv4 } from 'node:crypto';
 import { getHashedPercentateForObjIds } from '../utils/hashing/index.js';
 export class FeatureModel {
     id;

package/build/esm/flagsmith-engine/features/util.js

@@ -4,9 +4,9 @@ export function buildFeatureModel(featuresModelJSON) {
 }
 export function buildFeatureStateModel(featuresStateModelJSON) {
     const featureStateModel = new FeatureStateModel(buildFeatureModel(featuresStateModelJSON.feature), featuresStateModelJSON.enabled, featuresStateModelJSON.django_id, featuresStateModelJSON.feature_state_value, featuresStateModelJSON.featurestate_uuid);
-    featureStateModel.featureSegment = featuresStateModelJSON.feature_segment ?
-        buildFeatureSegment(featuresStateModelJSON.feature_segment) :
-        undefined;
+    featureStateModel.featureSegment = featuresStateModelJSON.feature_segment
+        ? buildFeatureSegment(featuresStateModelJSON.feature_segment)
+        : undefined;
     const multivariateFeatureStateValues = featuresStateModelJSON.multivariate_feature_state_values
         ? featuresStateModelJSON.multivariate_feature_state_values.map((fsv) => {
             const featureOption = new MultivariateFeatureOptionModel(fsv.multivariate_feature_option.value, fsv.multivariate_feature_option.id);

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

@@ -3,7 +3,7 @@ import { FeatureStateModel } from './features/models.js';
 import { IdentityModel } from './identities/models.js';
 import { TraitModel } from './identities/traits/models.js';
 export { EnvironmentModel } from './environments/models.js';
-export { FeatureStateModel } from './features/models.js';
+export { FeatureModel, FeatureStateModel } from './features/models.js';
 export { IdentityModel } from './identities/models.js';
 export { TraitModel } from './identities/traits/models.js';
 export { SegmentModel } from './segments/models.js';

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

@@ -1,7 +1,7 @@
 import { getIdentitySegments } from './segments/evaluators.js';
 import { FeatureStateNotFound } from './utils/errors.js';
 export { EnvironmentModel } from './environments/models.js';
-export { FeatureStateModel } from './features/models.js';
+export { FeatureModel, FeatureStateModel } from './features/models.js';
 export { IdentityModel } from './identities/models.js';
 export { TraitModel } from './identities/traits/models.js';
 export { SegmentModel } from './segments/models.js';

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

@@ -11,7 +11,7 @@ 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) => !!otherValue && otherValue.includes(thisValue)
 };
 export const semverMatchingFunction = {
     ...matchingFunctions,
@@ -19,9 +19,9 @@ export const semverMatchingFunction = {
     [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.LESS_THAN_INCLUSIVE]: (thisValue, otherValue) => semver.gte(thisValue, otherValue)
 };
-export const getMatchingFunctions = (semver) => (semver ? semverMatchingFunction : matchingFunctions);
+export const getMatchingFunctions = (semver) => semver ? semverMatchingFunction : matchingFunctions;
 export class SegmentConditionModel {
     EXCEPTION_OPERATOR_METHODS = {
         [NOT_CONTAINS]: 'evaluateNotContains',
@@ -40,9 +40,9 @@ export class SegmentConditionModel {
     matchesTraitValue(traitValue) {
         const evaluators = {
             evaluateNotContains: (traitValue) => {
-                return typeof traitValue == "string" &&
+                return (typeof traitValue == 'string' &&
                     !!this.value &&
-                    !traitValue.includes(this.value?.toString());
+                    !traitValue.includes(this.value?.toString()));
             },
             evaluateRegex: (traitValue) => {
                 return !!this.value && !!traitValue?.toString().match(new RegExp(this.value));
@@ -51,13 +51,13 @@ export class SegmentConditionModel {
                 if (isNaN(parseFloat(traitValue)) || !this.value) {
                     return false;
                 }
-                const parts = (this.value).split("|");
+                const parts = this.value.split('|');
                 const [divisor, reminder] = [parseFloat(parts[0]), parseFloat(parts[1])];
                 return traitValue % divisor === reminder;
             },
             evaluateIn: (traitValue) => {
                 return this.value?.split(',').includes(traitValue.toString());
-            },
+            }
         };
         // TODO: move this logic to the evaluator module
         if (this.EXCEPTION_OPERATOR_METHODS[this.operator]) {