flagsmith-nodejs 6.2.0 → 7.0.2

package/build/cjs/flagsmith-engine/evaluation/evaluationContext/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * An environment's unique identifier.
+ */
+export type Key = string;
+/**
+ * An environment's human-readable name.
+ */
+export type Name = string;
+/**
+ * A unique identifier for an identity, used for segment and multivariate feature flag targeting, and displayed in the Flagsmith UI.
+ */
+export type Identifier = string;
+/**
+ * Key used when selecting a value for a multivariate feature, or for % split segmentation. Set to an internal identifier or a composite value based on the environment key and identifier, depending on Flagsmith implementation.
+ */
+export type Key1 = string;
+/**
+ * Key used for % split segmentation.
+ */
+export type Key2 = string;
+/**
+ * The name of the segment.
+ */
+export type Name1 = string;
+/**
+ * Segment rule type. Represents a logical quantifier for the conditions and sub-rules.
+ */
+export type Type = 'ALL' | 'ANY' | 'NONE';
+export type SegmentCondition = SegmentCondition1 | InSegmentCondition;
+/**
+ * A reference to the identity trait or value in the evaluation context.
+ */
+export type Property = string;
+/**
+ * The operator to use for evaluating the condition.
+ */
+export type Operator = 'EQUAL' | 'GREATER_THAN' | 'LESS_THAN' | 'LESS_THAN_INCLUSIVE' | 'CONTAINS' | 'GREATER_THAN_INCLUSIVE' | 'NOT_CONTAINS' | 'NOT_EQUAL' | 'REGEX' | 'PERCENTAGE_SPLIT' | 'MODULO' | 'IS_SET' | 'IS_NOT_SET' | 'IN';
+/**
+ * The value to compare against the trait or context value.
+ */
+export type Value = string;
+/**
+ * A reference to the identity trait or value in the evaluation context.
+ */
+export type Property1 = string;
+/**
+ * The operator to use for evaluating the condition.
+ */
+export type Operator1 = 'IN';
+/**
+ * The values to compare against the trait or context value.
+ */
+export type Value1 = string[];
+/**
+ * Conditions that must be met for the rule to apply.
+ */
+export type Conditions = SegmentCondition[];
+/**
+ * Sub-rules nested within the segment rule.
+ */
+export type SubRules = SegmentRule[];
+/**
+ * Rules that define the segment.
+ */
+export type Rules = SegmentRule[];
+/**
+ * Key used when selecting a value for a multivariate feature. Set to an internal identifier or a UUID, depending on Flagsmith implementation.
+ */
+export type Key3 = string;
+/**
+ * Unique feature identifier.
+ */
+export type FeatureKey = string;
+/**
+ * Feature name.
+ */
+export type Name2 = string;
+/**
+ * Indicates whether the feature is enabled in the environment.
+ */
+export type Enabled = boolean;
+/**
+ * A default environment value for the feature. If the feature is multivariate, this will be the control value.
+ */
+export type Value2 = string;
+/**
+ * The value of the feature.
+ */
+export type Value3 = string;
+/**
+ * The weight of the feature value variant, as a percentage number (i.e. 100.0).
+ */
+export type Weight = number;
+/**
+ * An array of environment default values associated with the feature. Contains a single value for standard features, or multiple values for multivariate features.
+ */
+export type Variants = FeatureValue[];
+/**
+ * Priority of the feature context. Lower values indicate a higher priority when multiple contexts apply to the same feature.
+ */
+export type Priority = number;
+/**
+ * Feature overrides for the segment.
+ */
+export type Overrides = FeatureContext[];
+/**
+ * A context object containing the necessary information to evaluate Flagsmith feature flags.
+ */
+export interface EvaluationContext {
+    environment: EnvironmentContext;
+    /**
+     * Identity context used for identity-based evaluation.
+     */
+    identity?: IdentityContext | null;
+    segments?: Segments;
+    features?: Features;
+    [k: string]: unknown;
+}
+/**
+ * Environment context required for evaluation.
+ */
+export interface EnvironmentContext {
+    key: Key;
+    name: Name;
+    [k: string]: unknown;
+}
+/**
+ * Represents an identity context for feature flag evaluation.
+ */
+export interface IdentityContext {
+    identifier: Identifier;
+    key: Key1;
+    traits?: Traits;
+    [k: string]: unknown;
+}
+/**
+ * A map of traits associated with the identity, where the key is the trait name and the value is the trait value.
+ */
+export interface Traits {
+    [k: string]: string | number | boolean | null;
+}
+/**
+ * Segments applicable to the evaluation context.
+ */
+export interface Segments {
+    [k: string]: SegmentContext;
+}
+/**
+ * Represents a segment context for feature flag evaluation.
+ */
+export interface SegmentContext {
+    key: Key2;
+    name: Name1;
+    rules: Rules;
+    overrides?: Overrides;
+    [k: string]: unknown;
+}
+/**
+ * Represents a rule within a segment for feature flag evaluation.
+ */
+export interface SegmentRule {
+    type: Type;
+    conditions?: Conditions;
+    rules?: SubRules;
+    [k: string]: unknown;
+}
+/**
+ * Represents a condition within a segment rule for feature flag evaluation.
+ */
+export interface SegmentCondition1 {
+    property: Property;
+    operator: Operator;
+    value: Value;
+    [k: string]: unknown;
+}
+/**
+ * Represents an IN condition within a segment rule for feature flag evaluation.
+ */
+export interface InSegmentCondition {
+    property: Property1;
+    operator: Operator1;
+    value: Value1;
+    [k: string]: unknown;
+}
+/**
+ * Represents a feature context for feature flag evaluation.
+ */
+export interface FeatureContext {
+    key: Key3;
+    feature_key: FeatureKey;
+    name: Name2;
+    enabled: Enabled;
+    value: Value2;
+    variants?: Variants;
+    priority?: Priority;
+    [k: string]: unknown;
+}
+/**
+ * Represents a multivariate value for a feature flag.
+ */
+export interface FeatureValue {
+    value: Value3;
+    weight: Weight;
+    [k: string]: unknown;
+}
+/**
+ * Features to be evaluated in the context.
+ */
+export interface Features {
+    [k: string]: FeatureContext;
+}

package/build/cjs/flagsmith-engine/evaluation/evaluationContext/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/cjs/flagsmith-engine/evaluation/evaluationResult/evaluationResult.types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * Feature name.
+ */
+export type Name = string;
+/**
+ * Indicates if the feature flag is enabled.
+ */
+export type Enabled = boolean;
+/**
+ * Feature flag value.
+ */
+export type Value = string | number | boolean | null;
+/**
+ * Reason for the feature flag evaluation.
+ */
+export type Reason = string;
+/**
+ * Segment name.
+ */
+export type Name1 = string;
+/**
+ * List of segments which the provided context belongs to.
+ */
+export type Segments = SegmentResult[];
+/**
+ * Evaluation result object containing the used context, flag evaluation results, and segments used in the evaluation.
+ */
+export interface EvaluationResult {
+    flags: Flags;
+    segments: Segments;
+    [k: string]: unknown;
+}
+/**
+ * Feature flags evaluated for the context, mapped by feature names.
+ */
+export interface Flags {
+    [k: string]: FlagResult;
+}
+export interface FlagResult {
+    name: Name;
+    enabled: Enabled;
+    value: Value;
+    reason: Reason;
+    metadata?: FeatureMetadata;
+    [k: string]: unknown;
+}
+/**
+ * Additional metadata associated with the feature.
+ */
+export interface FeatureMetadata {
+    [k: string]: unknown;
+}
+export interface SegmentResult {
+    name: Name1;
+    metadata?: SegmentMetadata;
+    [k: string]: unknown;
+}
+/**
+ * Additional metadata associated with the segment.
+ */
+export interface SegmentMetadata {
+    [k: string]: unknown;
+}

package/build/cjs/flagsmith-engine/evaluation/evaluationResult/evaluationResult.types.js

@@ -0,0 +1,8 @@
+"use strict";
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,50 @@
+import type { FlagResult, FeatureMetadata, SegmentMetadata } from './evaluationResult/evaluationResult.types.js';
+import type { FeatureContext, EnvironmentContext, IdentityContext, SegmentContext } from './evaluationContext/evaluationContext.types.js';
+export * from './evaluationContext/evaluationContext.types.js';
+export declare enum SegmentSource {
+    API = "api",
+    IDENTITY_OVERRIDE = "identity_override"
+}
+export interface SDKFeatureMetadata extends FeatureMetadata {
+    id: number;
+}
+export interface FeatureContextWithMetadata<T extends FeatureMetadata = FeatureMetadata> extends FeatureContext {
+    metadata: T;
+    [k: string]: unknown;
+}
+export type FeaturesWithMetadata<T extends FeatureMetadata = FeatureMetadata> = {
+    [k: string]: FeatureContextWithMetadata<T>;
+};
+export type FlagResultWithMetadata<T extends FeatureMetadata = FeatureMetadata> = FlagResult & {
+    metadata: T;
+};
+export type EvaluationResultFlags<T extends FeatureMetadata = FeatureMetadata> = Record<string, FlagResultWithMetadata<T>>;
+export interface SDKSegmentMetadata extends SegmentMetadata {
+    id?: number;
+    source?: SegmentSource;
+}
+export interface SegmentContextWithMetadata<T extends SegmentMetadata = SegmentMetadata> extends SegmentContext {
+    metadata: T;
+    overrides?: FeatureContextWithMetadata<FeatureMetadata>[];
+}
+export type SegmentsWithMetadata<T extends SegmentMetadata = SegmentMetadata> = {
+    [k: string]: SegmentContextWithMetadata<T>;
+};
+export interface SegmentResultWithMetadata {
+    name: string;
+    metadata: SDKSegmentMetadata;
+}
+export type EvaluationResultSegments = SegmentResultWithMetadata[];
+export interface GenericEvaluationContext<T extends FeatureMetadata = FeatureMetadata, S extends SegmentMetadata = SegmentMetadata> {
+    environment: EnvironmentContext;
+    identity?: IdentityContext | null;
+    segments?: SegmentsWithMetadata<S>;
+    features?: FeaturesWithMetadata<T>;
+    [k: string]: unknown;
+}
+export type EvaluationContextWithMetadata = GenericEvaluationContext<SDKFeatureMetadata, SDKSegmentMetadata>;
+export type EvaluationResult<T extends FeatureMetadata = FeatureMetadata> = {
+    flags: EvaluationResultFlags<T>;
+    segments: EvaluationResultSegments;
+};
+export type EvaluationResultWithMetadata = EvaluationResult<SDKFeatureMetadata>;

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

@@ -0,0 +1,26 @@
+"use strict";
+// This file is the entry point for the evaluation module types
+// All types from evaluations should be at least imported here and re-exported
+// Do not use types directly from generated files
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SegmentSource = void 0;
+__exportStar(require("./evaluationContext/evaluationContext.types.js"), exports);
+var SegmentSource;
+(function (SegmentSource) {
+    SegmentSource["API"] = "api";
+    SegmentSource["IDENTITY_OVERRIDE"] = "identity_override";
+})(SegmentSource = exports.SegmentSource || (exports.SegmentSource = {}));

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

@@ -93,7 +93,7 @@ class FeatureStateModel {
                     return myValue.multivariateFeatureOption.value;
                 default:
                     if (percentageValue === undefined) {
-                        percentageValue = (0, index_js_1.getHashedPercentateForObjIds)([
+                        percentageValue = (0, index_js_1.getHashedPercentageForObjIds)([
                             this.djangoID || this.featurestateUUID,
                             identityID
                         ]);

package/build/cjs/flagsmith-engine/features/types.d.ts

@@ -0,0 +1,5 @@
+export declare enum TARGETING_REASONS {
+    DEFAULT = "DEFAULT",
+    TARGETING_MATCH = "TARGETING_MATCH",
+    SPLIT = "SPLIT"
+}

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

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TARGETING_REASONS = void 0;
+var TARGETING_REASONS;
+(function (TARGETING_REASONS) {
+    TARGETING_REASONS["DEFAULT"] = "DEFAULT";
+    TARGETING_REASONS["TARGETING_MATCH"] = "TARGETING_MATCH";
+    TARGETING_REASONS["SPLIT"] = "SPLIT";
+})(TARGETING_REASONS = exports.TARGETING_REASONS || (exports.TARGETING_REASONS = {}));

package/build/cjs/flagsmith-engine/features/util.d.ts

@@ -2,3 +2,4 @@ import { FeatureModel, FeatureSegment, FeatureStateModel } from './models.js';
 export declare function buildFeatureModel(featuresModelJSON: any): FeatureModel;
 export declare function buildFeatureStateModel(featuresStateModelJSON: any): FeatureStateModel;
 export declare function buildFeatureSegment(featureSegmentJSON: any): FeatureSegment;
+export declare function uuidToBigInt(uuid: string): BigInt;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildFeatureSegment = exports.buildFeatureStateModel = exports.buildFeatureModel = void 0;
+exports.uuidToBigInt = exports.buildFeatureSegment = exports.buildFeatureStateModel = exports.buildFeatureModel = void 0;
 const models_js_1 = require("./models.js");
 function buildFeatureModel(featuresModelJSON) {
     return new models_js_1.FeatureModel(featuresModelJSON.id, featuresModelJSON.name, featuresModelJSON.type);
@@ -25,3 +25,7 @@ function buildFeatureSegment(featureSegmentJSON) {
     return new models_js_1.FeatureSegment(featureSegmentJSON.priority);
 }
 exports.buildFeatureSegment = buildFeatureSegment;
+function uuidToBigInt(uuid) {
+    return BigInt('0x' + uuid.replace(/-/g, ''));
+}
+exports.uuidToBigInt = uuidToBigInt;

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

@@ -1,14 +1,66 @@
-import { EnvironmentModel } from './environments/models.js';
-import { FeatureStateModel } from './features/models.js';
-import { IdentityModel } from './identities/models.js';
-import { TraitModel } from './identities/traits/models.js';
+import { EvaluationContextWithMetadata, EvaluationResultSegments, EvaluationResultWithMetadata, FeatureContextWithMetadata, SDKFeatureMetadata } from './evaluation/models.js';
+import { EvaluationResultFlags } from './evaluation/models.js';
 export { EnvironmentModel } from './environments/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';
+export { FeatureModel, FeatureStateModel } from './features/models.js';
 export { OrganisationModel } from './organisations/models.js';
-export declare function getIdentityFeatureState(environment: EnvironmentModel, identity: IdentityModel, featureName: string, overrideTraits?: TraitModel[]): FeatureStateModel;
-export declare function getIdentityFeatureStates(environment: EnvironmentModel, identity: IdentityModel, overrideTraits?: TraitModel[]): FeatureStateModel[];
-export declare function getEnvironmentFeatureState(environment: EnvironmentModel, featureName: string): FeatureStateModel;
-export declare function getEnvironmentFeatureStates(environment: EnvironmentModel): FeatureStateModel[];
+type SegmentOverride = {
+    feature: FeatureContextWithMetadata<SDKFeatureMetadata>;
+    segmentName: string;
+};
+export type SegmentOverrides = Record<string, SegmentOverride>;
+/**
+ * Evaluates flags and segments for the given context.
+ *
+ * This is the main entry point for the evaluation engine. It processes segments,
+ * applies feature overrides based on segment priority, and returns the final flag states with
+ * evaluation reasons.
+ *
+ * @param context - EvaluationContext containing environment, identity, and segment data
+ * @returns EvaluationResult with flags, segments, and original context
+ */
+export declare function getEvaluationResult(context: EvaluationContextWithMetadata): EvaluationResultWithMetadata;
+/**
+ * Evaluates which segments the identity belongs to and collects feature overrides.
+ *
+ * @param context - EvaluationContext containing identity and segment definitions
+ * @returns Object containing segments the identity belongs to and any feature overrides
+ */
+export declare function evaluateSegments(context: EvaluationContextWithMetadata): {
+    segments: EvaluationResultSegments;
+    segmentOverrides: Record<string, SegmentOverride>;
+};
+/**
+ * Processes feature overrides from segments, applying priority rules.
+ *
+ * When multiple segments override the same feature, the segment with
+ * higher priority (lower numeric value) takes precedence.
+ *
+ * @param identitySegments - Segments that the identity belongs to
+ * @returns Map of feature keys to their highest-priority segment overrides
+ */
+export declare function processSegmentOverrides(identitySegments: any[]): Record<string, SegmentOverride>;
+/**
+ * Evaluates all features in the context, applying segment overrides where applicable.
+ * For each feature:
+ * - Checks if a segment override exists
+ * - Uses override values if present, otherwise evaluates the base feature
+ * - Determines appropriate evaluation reason
+ * - Handles multivariate evaluation for features without overrides
+ *
+ * @param context - EvaluationContext containing features and identity
+ * @param segmentOverrides - Map of feature keys to their segment overrides
+ * @returns EvaluationResultFlags containing evaluated flag results
+ */
+export declare function evaluateFeatures(context: EvaluationContextWithMetadata, segmentOverrides: Record<string, SegmentOverride>): EvaluationResultFlags<SDKFeatureMetadata>;
+export declare function shouldApplyOverride(override: any, existingOverrides: Record<string, SegmentOverride>): boolean;
+export declare function isHigherPriority(priorityA: number | undefined, priorityB: number | undefined): boolean;
+export type TargetingMatchReason = {
+    type: 'SEGMENT';
+    override: SegmentOverride;
+} | {
+    type: 'SPLIT';
+    weight: number;
+};