flagsmith-nodejs 6.2.0 → 7.0.3

package/flagsmith-engine/evaluation/evaluationContext/mappers.ts

@@ -0,0 +1,204 @@
+import {
+    FeaturesWithMetadata,
+    Traits,
+    GenericEvaluationContext,
+    EnvironmentContext,
+    IdentityContext,
+    SegmentSource,
+    SDKFeatureMetadata,
+    SegmentsWithMetadata,
+    SDKSegmentMetadata
+} from '../models.js';
+import { EnvironmentModel } from '../../environments/models.js';
+import { IdentityModel } from '../../identities/models.js';
+import { TraitModel } from '../../identities/traits/models.js';
+import { IDENTITY_OVERRIDE_SEGMENT_NAME } from '../../segments/constants.js';
+import { createHash } from 'node:crypto';
+import { uuidToBigInt } from '../../features/util.js';
+
+export function getEvaluationContext(
+    environment: EnvironmentModel,
+    identity?: IdentityModel,
+    overrideTraits?: TraitModel[],
+    isEnvironmentEvaluation: boolean = false
+): GenericEvaluationContext {
+    const environmentContext = mapEnvironmentModelToEvaluationContext(environment);
+    if (isEnvironmentEvaluation) {
+        return environmentContext;
+    }
+    const identityContext = identity
+        ? mapIdentityModelToIdentityContext(identity, overrideTraits)
+        : undefined;
+
+    const context = {
+        ...environmentContext,
+        ...(identityContext && { identity: identityContext })
+    };
+
+    return context;
+}
+
+function mapEnvironmentModelToEvaluationContext(
+    environment: EnvironmentModel
+): GenericEvaluationContext {
+    const environmentContext: EnvironmentContext = {
+        key: environment.apiKey,
+        name: environment.name
+    };
+
+    const features: FeaturesWithMetadata<SDKFeatureMetadata> = {};
+    for (const fs of environment.featureStates) {
+        const variants =
+            fs.multivariateFeatureStateValues?.length > 0
+                ? fs.multivariateFeatureStateValues.map(mv => ({
+                      value: mv.multivariateFeatureOption.value,
+                      weight: mv.percentageAllocation,
+                      priority: mv.id ?? uuidToBigInt(mv.mvFsValueUuid)
+                  }))
+                : undefined;
+
+        features[fs.feature.name] = {
+            key: fs.djangoID?.toString() || fs.featurestateUUID,
+            name: fs.feature.name,
+            enabled: fs.enabled,
+            value: fs.getValue(),
+            variants,
+            priority: fs.featureSegment?.priority,
+            metadata: {
+                id: fs.feature.id
+            }
+        };
+    }
+
+    const segmentOverrides: SegmentsWithMetadata<SDKSegmentMetadata> = {};
+    for (const segment of environment.project.segments) {
+        segmentOverrides[segment.id.toString()] = {
+            key: segment.id.toString(),
+            name: segment.name,
+            rules: segment.rules.map(rule => mapSegmentRuleModelToRule(rule)),
+            overrides:
+                segment.featureStates.length > 0
+                    ? segment.featureStates.map(fs => ({
+                          key: fs.djangoID?.toString() || fs.featurestateUUID,
+                          name: fs.feature.name,
+                          enabled: fs.enabled,
+                          value: fs.getValue(),
+                          priority: fs.featureSegment?.priority,
+                          metadata: {
+                              id: fs.feature.id
+                          }
+                      }))
+                    : [],
+            metadata: {
+                source: SegmentSource.API,
+                id: segment.id
+            }
+        };
+    }
+
+    let identityOverrideSegments: SegmentsWithMetadata<SDKSegmentMetadata> = {};
+    if (environment.identityOverrides && environment.identityOverrides.length > 0) {
+        identityOverrideSegments = mapIdentityOverridesToSegments(environment.identityOverrides);
+    }
+
+    return {
+        environment: environmentContext,
+        features,
+        segments: {
+            ...segmentOverrides,
+            ...identityOverrideSegments
+        }
+    };
+}
+
+function mapIdentityModelToIdentityContext(
+    identity: IdentityModel,
+    overrideTraits?: TraitModel[]
+): IdentityContext {
+    const traits = overrideTraits || identity.identityTraits;
+    const traitsContext: Traits = {};
+
+    for (const trait of traits) {
+        traitsContext[trait.traitKey] = trait.traitValue;
+    }
+
+    const identityContext: IdentityContext = {
+        identifier: identity.identifier,
+        traits: traitsContext
+    };
+
+    return identityContext;
+}
+
+function mapSegmentRuleModelToRule(rule: any): any {
+    return {
+        type: rule.type,
+        conditions: rule.conditions.map((condition: any) => ({
+            property: condition.property,
+            operator: condition.operator,
+            value: condition.value
+        })),
+        rules: rule.rules.map((subRule: any) => mapSegmentRuleModelToRule(subRule))
+    };
+}
+
+function mapIdentityOverridesToSegments(
+    identityOverrides: IdentityModel[]
+): SegmentsWithMetadata<SDKSegmentMetadata> {
+    const segments: SegmentsWithMetadata<SDKSegmentMetadata> = {};
+    const featuresToIdentifiers = new Map<string, { identifiers: string[]; overrides: any[] }>();
+
+    for (const identity of identityOverrides) {
+        if (!identity.identityFeatures || identity.identityFeatures.length === 0) {
+            continue;
+        }
+
+        const sortedFeatures = [...identity.identityFeatures].sort((a, b) =>
+            a.feature.name.localeCompare(b.feature.name)
+        );
+        const overridesKey = sortedFeatures.map(fs => ({
+            name: fs.feature.name,
+            enabled: fs.enabled,
+            value: fs.getValue(),
+            priority: -Infinity,
+            metadata: {
+                id: fs.feature.id
+            }
+        }));
+
+        const overridesHash = createHash('sha1').update(JSON.stringify(overridesKey)).digest('hex');
+
+        if (!featuresToIdentifiers.has(overridesHash)) {
+            featuresToIdentifiers.set(overridesHash, { identifiers: [], overrides: overridesKey });
+        }
+
+        featuresToIdentifiers.get(overridesHash)!.identifiers.push(identity.identifier);
+    }
+
+    for (const [overrideHash, { identifiers, overrides }] of featuresToIdentifiers.entries()) {
+        const segmentKey = `identity_override_${overrideHash}`;
+
+        segments[segmentKey] = {
+            key: segmentKey,
+            name: IDENTITY_OVERRIDE_SEGMENT_NAME,
+            rules: [
+                {
+                    type: 'ALL',
+                    conditions: [
+                        {
+                            property: '$.identity.identifier',
+                            operator: 'IN',
+                            value: identifiers.join(',')
+                        }
+                    ]
+                }
+            ],
+            metadata: {
+                source: SegmentSource.IDENTITY_OVERRIDE
+            },
+            overrides: overrides
+        };
+    }
+
+    return segments;
+}

package/flagsmith-engine/evaluation/evaluationContext/types.ts

@@ -0,0 +1,233 @@
+/* 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.
+ */
+
+/**
+ * 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/flagsmith-engine/evaluation/evaluationResult/evaluationResult.types.ts

@@ -0,0 +1,71 @@
+/* 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.
+ */
+
+/**
+ * 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/flagsmith-engine/evaluation/models.ts

@@ -0,0 +1,96 @@
+// 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
+
+import type {
+    EvaluationResult as EvaluationContextResult,
+    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 enum SegmentSource {
+    API = 'api',
+    IDENTITY_OVERRIDE = 'identity_override'
+}
+
+// Feature types
+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>
+>;
+
+// Segment types
+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[];
+
+// Evaluation context types
+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
+>;
+
+// Evaluation result types
+export type EvaluationResult<T extends FeatureMetadata = FeatureMetadata> = {
+    flags: EvaluationResultFlags<T>;
+    segments: EvaluationResultSegments;
+};
+
+export type EvaluationResultWithMetadata = EvaluationResult<SDKFeatureMetadata>;

package/flagsmith-engine/features/models.ts

@@ -1,5 +1,5 @@
 import { randomUUID as uuidv4 } from 'node:crypto';
-import { getHashedPercentateForObjIds } from '../utils/hashing/index.js';
+import { getHashedPercentageForObjIds } from '../utils/hashing/index.js';
 
 export class FeatureModel {
     id: number;
@@ -103,6 +103,7 @@ export class FeatureStateModel {
         const sortedF = this.multivariateFeatureStateValues.sort((a, b) => {
             return a.id - b.id;
         });
+
         for (const myValue of sortedF) {
             switch (myValue.percentageAllocation) {
                 case 0:
@@ -111,7 +112,7 @@ export class FeatureStateModel {
                     return myValue.multivariateFeatureOption.value;
                 default:
                     if (percentageValue === undefined) {
-                        percentageValue = getHashedPercentateForObjIds([
+                        percentageValue = getHashedPercentageForObjIds([
                             this.djangoID || this.featurestateUUID,
                             identityID
                         ]);

package/flagsmith-engine/features/types.ts

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

package/flagsmith-engine/features/util.ts

@@ -46,3 +46,7 @@ export function buildFeatureStateModel(featuresStateModelJSON: any): FeatureStat
 export function buildFeatureSegment(featureSegmentJSON: any): FeatureSegment {
     return new FeatureSegment(featureSegmentJSON.priority);
 }
+
+export function uuidToBigInt(uuid: string): BigInt {
+    return BigInt('0x' + uuid.replace(/-/g, ''));
+}