flagsmith-nodejs 1.0.9 → 2.0.0-beta.1

package/flagsmith-engine/segments/models.ts

@@ -0,0 +1,103 @@
+import { FeatureStateModel } from '../features/models';
+import { getCastingFunction as getCastingFunction } from '../utils';
+import {
+    ALL_RULE,
+    ANY_RULE,
+    NONE_RULE,
+    NOT_CONTAINS,
+    REGEX,
+    CONDITION_OPERATORS
+} from './constants';
+
+export const all = (iterable: Array<any>) => iterable.filter(e => !!e).length === iterable.length;
+export const any = (iterable: Array<any>) => iterable.filter(e => !!e).length > 0;
+
+export const matchingFunctions = {
+    [CONDITION_OPERATORS.EQUAL]: (thisValue: any, otherValue: any) => thisValue == otherValue,
+    [CONDITION_OPERATORS.GREATER_THAN]: (thisValue: any, otherValue: any) => otherValue > thisValue,
+    [CONDITION_OPERATORS.GREATER_THAN_INCLUSIVE]: (thisValue: any, otherValue: any) =>
+        otherValue >= thisValue,
+    [CONDITION_OPERATORS.LESS_THAN]: (thisValue: any, otherValue: any) => thisValue > otherValue,
+    [CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: (thisValue: any, otherValue: any) =>
+        thisValue >= otherValue,
+    [CONDITION_OPERATORS.NOT_EQUAL]: (thisValue: any, otherValue: any) => thisValue != otherValue,
+    [CONDITION_OPERATORS.CONTAINS]: (thisValue: any, otherValue: any) =>
+        otherValue.includes(thisValue),
+    [CONDITION_OPERATORS.NOT_CONTAINS]: (thisValue: any, otherValue: any) =>
+        !otherValue.includes(thisValue)
+};
+
+export class SegmentConditionModel {
+    EXCEPTION_OPERATOR_METHODS: { [key: string]: string } = {
+        [NOT_CONTAINS]: 'evaluateNotContains',
+        [REGEX]: 'evaluateRegex'
+    };
+
+    operator: string;
+    value: string;
+    property_: string | undefined;
+
+    constructor(operator: string, value: string, property?: string) {
+        this.operator = operator;
+        this.value = value;
+        this.property_ = property;
+    }
+
+    matchesTraitValue(traitValue: any) {
+        const evaluators: { [key: string]: CallableFunction } = {
+            evaluateNotContains: (traitValue: any) => {
+                return !traitValue.includes(this.value);
+            },
+            evaluateRegex: (traitValue: any) => {
+                return !!traitValue.match(new RegExp(this.value));
+            }
+        };
+
+        // TODO: move this logic to the evaluator module
+        if (this.EXCEPTION_OPERATOR_METHODS[this.operator]) {
+            const evaluatorFunction = evaluators[this.EXCEPTION_OPERATOR_METHODS[this.operator]];
+            return evaluatorFunction(traitValue);
+        }
+
+        const defaultFunction = (x: any, y: any) => false;
+
+        const matchingFunction = matchingFunctions[this.operator] || defaultFunction;
+
+        const castToTypeOfTraitValue = getCastingFunction(traitValue);
+        return matchingFunction(castToTypeOfTraitValue(this.value), traitValue);
+    }
+}
+
+export class SegmentRuleModel {
+    type: string;
+    rules: SegmentRuleModel[] = [];
+    conditions: SegmentConditionModel[] = [];
+
+    constructor(type: string) {
+        this.type = type;
+    }
+
+    static none(iterable: Array<any>) {
+        return iterable.filter(e => !!e).length === 0;
+    }
+
+    matchingFunction(): CallableFunction {
+        return {
+            [ANY_RULE]: any,
+            [ALL_RULE]: all,
+            [NONE_RULE]: SegmentRuleModel.none
+        }[this.type] as CallableFunction;
+    }
+}
+
+export class SegmentModel {
+    id: number;
+    name: string;
+    rules: SegmentRuleModel[] = [];
+    featureStates: FeatureStateModel[] = [];
+
+    constructor(id: number, name: string) {
+        this.id = id;
+        this.name = name;
+    }
+}

package/flagsmith-engine/segments/util.ts

@@ -0,0 +1,29 @@
+import { buildFeatureStateModel } from '../features/util';
+import { SegmentConditionModel, SegmentModel, SegmentRuleModel } from './models';
+
+export function buildSegmentConditionModel(segmentConditionJSON: any): SegmentConditionModel {
+    return new SegmentConditionModel(
+        segmentConditionJSON.operator,
+        segmentConditionJSON.value,
+        segmentConditionJSON.property_
+    );
+}
+
+export function buildSegmentRuleModel(ruleModelJSON: any): SegmentRuleModel {
+    const ruleModel = new SegmentRuleModel(ruleModelJSON.type);
+
+    ruleModel.rules = ruleModelJSON.rules.map((r: any) => buildSegmentRuleModel(r));
+    ruleModel.conditions = ruleModelJSON.conditions.map((c: any) => buildSegmentConditionModel(c));
+    return ruleModel;
+}
+
+export function buildSegmentModel(segmentModelJSON: any): SegmentModel {
+    const model = new SegmentModel(segmentModelJSON.id, segmentModelJSON.name);
+
+    model.featureStates = segmentModelJSON['feature_states'].map((fs: any) =>
+        buildFeatureStateModel(fs)
+    );
+    model.rules = segmentModelJSON['rules'].map((r: any) => buildSegmentRuleModel(r));
+
+    return model;
+}

package/flagsmith-engine/utils/collections.ts

@@ -0,0 +1,14 @@
+import { FeatureStateModel } from '../features/models';
+
+export class IdentityFeaturesList extends Array<FeatureStateModel> {
+    public push(...e: FeatureStateModel[]): number {
+        for (const [_, item] of e.entries()) {
+            for (const [k, v] of this.entries()) {
+                if (v.djangoID === item.djangoID) {
+                    throw new Error('feature state for this feature already exists');
+                }
+            }
+        }
+        return super.push(...e);
+    }
+}

package/flagsmith-engine/utils/hashing/index.ts

@@ -0,0 +1,57 @@
+import md5 from 'md5';
+import bigInt from 'big-integer';
+
+// def get_hashed_percentage_for_object_ids(
+//   object_ids: typing.Iterable[typing.Any], iterations: int = 1
+// ) -> float:
+//   """
+//   Given a list of object ids, get a floating point number between 0 and 1 based on
+//   the hash of those ids. This should give the same value every time for any
+//   list of ids.
+
+//   :param object_ids: list of object ids to calculate the has for
+//   :param iterations: num times to include each id in the generated string to hash
+//   :return: (float) number between 0 (inclusive) and 100 (exclusive)
+//   """
+
+const makeRepeated = (arr: Array<any>, repeats: number) =>
+    Array.from({ length: repeats }, () => arr).flat();
+
+function h2d(s: any): string {
+    function add(x: any, y: any) {
+        var c = 0,
+            r = [];
+        var x = x.split('').map(Number);
+        var y = y.split('').map(Number);
+        while (x.length || y.length) {
+            var s = (x.pop() || 0) + (y.pop() || 0) + c;
+            r.unshift(s < 10 ? s : s - 10);
+            c = s < 10 ? 0 : 1;
+        }
+        if (c) r.unshift(c);
+        return r.join('');
+    }
+
+    var dec = '0';
+    s.split('').forEach(function (chr: any) {
+        var n = parseInt(chr, 16);
+        for (var t = 8; t; t >>= 1) {
+            dec = add(dec, dec);
+            if (n & t) dec = add(dec, '1');
+        }
+    });
+    return dec;
+}
+
+export function getHashedPercentateForObjIds(objectIds: Array<any>, iterations = 1): number {
+    let to_hash = makeRepeated(objectIds, iterations).join(',');
+    const hashedValue = md5(to_hash);
+    const hashedInt = bigInt(h2d(hashedValue));
+    const value = (hashedInt.mod(9999).toJSNumber() / 9998) * 100;
+
+    if (value === 100) {
+        return getHashedPercentateForObjIds(objectIds, iterations + 1);
+    }
+
+    return value;
+}

package/flagsmith-engine/utils/index.ts

@@ -0,0 +1,10 @@
+export function getCastingFunction(input: any): CallableFunction {
+    switch (typeof input) {
+        case 'boolean':
+            return (x: any) => !['False', 'false'].includes(x);
+        case 'number':
+            return (x: any) => parseFloat(x);
+        default:
+            return (x: any) => String(x);
+    }
+}

package/index.ts

@@ -0,0 +1,3 @@
+import Flagsmith from './sdk';
+
+export default Flagsmith;

package/jest.config.js

@@ -0,0 +1,5 @@
+/** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node'
+};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "flagsmith-nodejs",
-  "version": "1.0.9",
+  "version": "2.0.0-beta.1",
   "description": "Flagsmith lets you manage features flags and remote config across web, mobile and server side applications. Deliver true Continuous Integration. Get builds out faster. Control who has access to new features.",
-  "main": "index.js",
+  "main": "build/index.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/SolidStateGroup/bullet-train-nodejs-client"
@@ -39,7 +39,28 @@
     }
   ],
   "license": "MIT",
+  "scripts": {
+    "lint": "prettier --write .",
+    "test": "jest --coverage --coverageReporters='text'",
+    "build": "tsc",
+    "prepare": "husky install"
+  },
   "dependencies": {
-    "node-fetch": "^2.1.2"
+    "big-integer": "^1.6.51",
+    "md5": "^2.3.0",
+    "node-fetch": "^2.1.2",
+    "uuid": "^8.3.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^27.4.1",
+    "@types/md5": "^2.3.2",
+    "@types/node-fetch": "^2.6.1",
+    "@types/uuid": "^8.3.4",
+    "esbuild": "^0.14.25",
+    "husky": "^7.0.4",
+    "jest": "^27.5.1",
+    "prettier": "^2.2.1",
+    "ts-jest": "^27.1.3",
+    "typescript": "^4.6.2"
   }
 }

package/sdk/analytics.ts

@@ -0,0 +1,88 @@
+import fetch from 'node-fetch';
+
+const ANALYTICS_ENDPOINT = 'analytics/flags/';
+
+// Used to control how often we send data(in seconds)
+const ANALYTICS_TIMER = 10;
+
+const delay = (ms: number) => new Promise(resolve => setTimeout(() => resolve(undefined), ms));
+
+const retryFetch = (
+    url: string,
+    fetchOptions = {},
+    retries = 3,
+    retryDelay = 1000,
+    timeout: number
+) => {
+    return new Promise((resolve, reject) => {
+        // check for timeout
+        if (timeout) setTimeout(() => reject('error: timeout'), timeout);
+
+        const wrapper = (n: number) => {
+            fetch(url, fetchOptions)
+                .then(res => resolve(res))
+                .catch(async err => {
+                    if (n > 0) {
+                        await delay(retryDelay);
+                        wrapper(--n);
+                    } else {
+                        reject(err);
+                    }
+                });
+        };
+
+        wrapper(retries);
+    });
+};
+
+export class AnalyticsProcessor {
+    private analyticsEndpoint: string;
+    private environmentKey: string;
+    private lastFlushed: number;
+    analyticsData: { [key: string]: any };
+    private timeout: number = 3;
+    /**
+     * AnalyticsProcessor is used to track how often individual Flags are evaluated within 
+     * the Flagsmith SDK. Docs: https://docs.flagsmith.com/advanced-use/flag-analytics.
+     * 
+     * @param data.environmentKey environment key obtained from the Flagsmith UI
+     * @param data.baseApiUrl base api url to override when using self hosted version
+     * @param data.timeout used to tell requests to stop waiting for a response after a
+            given number of seconds
+     */
+    constructor(data: { environmentKey: string; baseApiUrl: string; timeout?: number }) {
+        this.analyticsEndpoint = data.baseApiUrl + ANALYTICS_ENDPOINT;
+        this.environmentKey = data.environmentKey;
+        this.lastFlushed = Date.now();
+        this.analyticsData = {};
+        this.timeout = data.timeout || this.timeout;
+    }
+    /**
+     * Sends all the collected data to the api asynchronously and resets the timer
+     */
+    async flush() {
+        if (!Object.keys(this.analyticsData).length) {
+            return;
+        }
+
+        await fetch(this.analyticsEndpoint, {
+            method: 'POST',
+            body: JSON.stringify(this.analyticsData),
+            timeout: this.timeout,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Environment-Key': this.environmentKey
+            }
+        });
+
+        this.analyticsData = {};
+        this.lastFlushed = Date.now();
+    }
+
+    trackFeature(featureId: number) {
+        this.analyticsData[featureId] = (this.analyticsData[featureId] || 0) + 1;
+        if (Date.now() - this.lastFlushed > ANALYTICS_TIMER * 1000) {
+            this.flush();
+        }
+    }
+}

package/sdk/errors.ts

@@ -0,0 +1,2 @@
+export class FlagsmithClientError extends Error {}
+export class FlagsmithAPIError extends Error {}

package/sdk/index.ts

@@ -0,0 +1,282 @@
+import { getEnvironmentFeatureStates, getIdentityFeatureStates } from '../flagsmith-engine';
+import { EnvironmentModel } from '../flagsmith-engine/environments/models';
+import { buildEnvironmentModel } from '../flagsmith-engine/environments/util';
+import { IdentityModel } from '../flagsmith-engine/identities/models';
+import { TraitModel } from '../flagsmith-engine/identities/traits/models';
+
+import { AnalyticsProcessor } from './analytics';
+import { FlagsmithAPIError, FlagsmithClientError } from './errors';
+
+import { DefaultFlag, Flags } from './models';
+import { EnvironmentDataPollingManager } from './polling_manager';
+import { generateIdentitiesData, retryFetch } from './utils';
+
+const DEFAULT_API_URL = 'https://api.flagsmith.com/api/v1/';
+
+export class Flagsmith {
+    environmentKey?: string;
+    apiUrl: string = DEFAULT_API_URL;
+    customHeaders?: { [key: string]: any };
+    requestTimeoutSeconds?: number;
+    enableLocalEvaluation?: boolean = false;
+    environmentRefreshIntervalSeconds: number = 60;
+    retries?: any;
+    enableAnalytics: boolean = false;
+    defaultFlagHandler?: (featureName: string) => DefaultFlag;
+
+    environmentFlagsUrl: string;
+    identitiesUrl: string;
+    environmentUrl: string;
+
+    environmentDataPollingManager?: EnvironmentDataPollingManager;
+    environment?: EnvironmentModel;
+    private analyticsProcessor?: AnalyticsProcessor;
+    /**
+     * A Flagsmith client.
+     *
+     * Provides an interface for interacting with the Flagsmith http API.
+     * Basic Usage::
+     *
+     * import flagsmith from Flagsmith
+     * const flagsmith = new Flagsmith({environmentKey: '<your API key>'});
+     * const environmentFlags = flagsmith.getEnvironmentFlags();
+     * const featureEnabled = environmentFlags.isFeatureEnabled('foo');
+     * const identityFlags = flagsmith.getIdentityFlags('identifier', {'foo': 'bar'});
+     * const featureEnabledForIdentity = identityFlags.isFeatureEnabled("foo")
+     *
+     *  @param {string} data.environmentKey: The environment key obtained from Flagsmith interface
+        @param {string} data.apiUrl: Override the URL of the Flagsmith API to communicate with
+        @param  data.customHeaders: Additional headers to add to requests made to the
+            Flagsmith API
+        @param {number} data.requestTimeoutSeconds: Number of seconds to wait for a request to
+            complete before terminating the request
+        @param {boolean} data.enableLocalEvaluation: Enables local evaluation of flags
+        @param {number} data.environmentRefreshIntervalSeconds: If using local evaluation,
+            specify the interval period between refreshes of local environment data
+        @param {number} data.retries: a urllib3.Retry object to use on all http requests to the
+            Flagsmith API
+        @param {boolean} data.enableAnalytics: if enabled, sends additional requests to the Flagsmith
+            API to power flag analytics charts
+        @param data.defaultFlagHandler: callable which will be used in the case where
+            flags cannot be retrieved from the API or a non existent feature is
+            requested
+     */
+    constructor(data: {
+        environmentKey: string;
+        apiUrl?: string;
+        customHeaders?: { [key: string]: any };
+        requestTimeoutSeconds?: number;
+        enableLocalEvaluation?: boolean;
+        environmentRefreshIntervalSeconds?: number;
+        retries?: any;
+        enableAnalytics?: boolean;
+        defaultFlagHandler?: (featureName: string) => DefaultFlag;
+    }) {
+        this.environmentKey = data.environmentKey;
+        this.apiUrl = data.apiUrl || this.apiUrl;
+        this.customHeaders = data.customHeaders;
+        this.requestTimeoutSeconds = data.requestTimeoutSeconds;
+        this.enableLocalEvaluation = data.enableLocalEvaluation;
+        this.environmentRefreshIntervalSeconds =
+            data.environmentRefreshIntervalSeconds || this.environmentRefreshIntervalSeconds;
+        this.retries = data.retries;
+        this.enableAnalytics = data.enableAnalytics || false;
+        this.defaultFlagHandler = data.defaultFlagHandler;
+
+        this.environmentFlagsUrl = `${this.apiUrl}flags/`;
+        this.identitiesUrl = `${this.apiUrl}identities/`;
+        this.environmentUrl = `${this.apiUrl}environment-document/`;
+
+        if (this.enableLocalEvaluation) {
+            this.environmentDataPollingManager = new EnvironmentDataPollingManager(
+                this,
+                this.environmentRefreshIntervalSeconds
+            );
+            this.environmentDataPollingManager.start();
+        }
+
+        this.analyticsProcessor = data.enableAnalytics
+            ? new AnalyticsProcessor({
+                  environmentKey: this.environmentKey,
+                  baseApiUrl: this.apiUrl,
+                  timeout: this.requestTimeoutSeconds
+              })
+            : undefined;
+    }
+    /**
+     * Get all the default for flags for the current environment.
+     *
+     * @returns Flags object holding all the flags for the current environment.
+     */
+    async getEnvironmentFlags(): Promise<Flags> {
+        if (this.environment) {
+            return new Promise(resolve => resolve(this.getEnvironmentFlagsFromDocument()));
+        }
+
+        return this.getEnvironmentFlagsFromApi();
+    }
+    /**
+     * Get all the flags for the current environment for a given identity. Will also
+        upsert all traits to the Flagsmith API for future evaluations. Providing a
+        trait with a value of None will remove the trait from the identity if it exists.
+     *
+     * @param  {string} identifier a unique identifier for the identity in the current
+            environment, e.g. email address, username, uuid
+     * @param  {{[key:string]:any}} traits? a dictionary of traits to add / update on the identity in
+            Flagsmith, e.g. {"num_orders": 10}
+     * @returns Flags object holding all the flags for the given identity.
+     */
+    getIdentityFlags(identifier: string, traits?: { [key: string]: any }): Promise<Flags> {
+        traits = traits || {};
+        if (this.environment) {
+            return new Promise(resolve =>
+                resolve(this.getIdentityFlagsFromDocument(identifier, traits || {}))
+            );
+        }
+        return this.getIdentityFlagsFromApi(identifier, traits);
+    }
+
+    /**
+     * Updates the environment state for local flag evaluation.
+     * You only need to call this if you wish to bypass environmentRefreshIntervalSeconds.
+     */
+    async updateEnvironment() {
+        this.environment = await this.getEnvironmentFromApi();
+    }
+
+    private async getJSONResponse(
+        url: string,
+        method: string,
+        body?: { [key: string]: any }
+    ): Promise<any> {
+        const headers: { [key: string]: any } = {};
+        if (this.environmentKey) {
+            headers['X-Environment-Key'] = this.environmentKey as string;
+        }
+
+        if (this.customHeaders) {
+            for (const [k, v] of Object.entries(this.customHeaders)) {
+                headers[k] = v;
+            }
+        }
+
+        const data = await retryFetch(
+            url,
+            {
+                method: method,
+                timeout: this.requestTimeoutSeconds || undefined,
+                body: JSON.stringify(body),
+                headers: headers
+            },
+            this.retries,
+            1000,
+            (this.requestTimeoutSeconds || 10) * 1000
+        );
+
+        if (data.status !== 200) {
+            throw new FlagsmithAPIError(
+                `Invalid request made to Flagsmith API. Response status code: ${data.status}`
+            );
+        }
+
+        return data.json();
+    }
+
+    private async getEnvironmentFromApi() {
+        const environment_data = await this.getJSONResponse(this.environmentUrl, 'GET');
+        return buildEnvironmentModel(environment_data);
+    }
+
+    private getEnvironmentFlagsFromDocument() {
+        if (!this.environment) {
+            throw new FlagsmithClientError(
+                'Unable to build identity model when no local environment present.'
+            );
+        }
+
+        return Flags.fromFeatureStateModels({
+            featureStates: getEnvironmentFeatureStates(this.environment),
+            analyticsProcessor: this.analyticsProcessor,
+            defaultFlagHandler: this.defaultFlagHandler
+        });
+    }
+
+    private getIdentityFlagsFromDocument(identifier: string, traits: { [key: string]: any }) {
+        if (!this.environment) {
+            throw new FlagsmithClientError(
+                'Unable to build identity model when no local environment present.'
+            );
+        }
+
+        const identityModel = this.buildIdentityModel(identifier, Object.keys(traits).map((key)=>(
+            {
+                key,
+                value: traits[key]
+            }
+        )));
+
+        const featureStates = getIdentityFeatureStates(this.environment, identityModel);
+
+        return Flags.fromFeatureStateModels({
+            featureStates: featureStates,
+            analyticsProcessor: this.analyticsProcessor,
+            defaultFlagHandler: this.defaultFlagHandler
+        });
+    }
+
+    private async getEnvironmentFlagsFromApi() {
+        try {
+            const apiFlags = await this.getJSONResponse(this.environmentFlagsUrl, 'GET');
+            return Flags.fromAPIFlags({
+                apiFlags: apiFlags,
+                analyticsProcessor: this.analyticsProcessor,
+                defaultFlagHandler: this.defaultFlagHandler
+            });
+        } catch (e) {
+            if (this.defaultFlagHandler) {
+                return new Flags({
+                    flags: {},
+                    defaultFlagHandler: this.defaultFlagHandler
+                });
+            }
+
+            throw e;
+        }
+    }
+
+    private async getIdentityFlagsFromApi(identifier: string, traits: { [key: string]: any }) {
+        try {
+            const data = generateIdentitiesData(identifier, traits);
+            const jsonResponse = await this.getJSONResponse(this.identitiesUrl, 'POST', data);
+            return Flags.fromAPIFlags({
+                apiFlags: jsonResponse['flags'],
+                analyticsProcessor: this.analyticsProcessor,
+                defaultFlagHandler: this.defaultFlagHandler
+            });
+        } catch (e) {
+            if (this.defaultFlagHandler) {
+                return new Flags({
+                    flags: {},
+                    defaultFlagHandler: this.defaultFlagHandler
+                });
+            }
+
+            throw e;
+        }
+    }
+
+    private buildIdentityModel(identifier: string, traits: { key:string, value:any }[]) {
+        if (!this.environment) {
+            throw new FlagsmithClientError(
+                'Unable to build identity model when no local environment present.'
+            );
+        }
+
+        const traitModels = traits.map(trait => new TraitModel(trait.key, trait.value));
+        return new IdentityModel('0', traitModels, [], this.environment.apiKey, identifier);
+    }
+
+    stop() {}
+}
+
+export default Flagsmith;