flagsmith-nodejs 1.1.3 → 2.0.0-beta.3

package/sdk/index.ts

@@ -0,0 +1,329 @@
+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';
+import { SegmentModel } from '../flagsmith-engine/segments/models';
+import { getIdentitySegments } from '../flagsmith-engine/segments/evaluators';
+
+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?: number;
+    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?: number;
+        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) {
+            if (!this.environmentKey.startsWith('ser.')) {
+                console.error(
+                    'In order to use local evaluation, please generate a server key in the environment settings page.'
+                );
+            }
+            this.environmentDataPollingManager = new EnvironmentDataPollingManager(
+                this,
+                this.environmentRefreshIntervalSeconds
+            );
+            this.environmentDataPollingManager.start();
+            this.updateEnvironment();
+        }
+
+        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.enableLocalEvaluation) {
+            return new Promise(resolve =>
+                this.environmentPromise!.then(() => {
+                    resolve(this.getIdentityFlagsFromDocument(identifier, traits || {}));
+                })
+            );
+        }
+        return this.getIdentityFlagsFromApi(identifier, traits);
+    }
+
+    /**
+     * Get the segments 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 Segments that the given identity belongs to.
+     */
+    getIdentitySegments(
+        identifier: string,
+        traits?: { [key: string]: any }
+    ): Promise<SegmentModel[]> {
+        traits = traits || {};
+        if (this.enableLocalEvaluation) {
+            return this.environmentPromise!.then(() => {
+                return new Promise(resolve => {
+                    const identityModel = this.buildIdentityModel(
+                        identifier,
+                        Object.keys(traits || {}).map(key => ({
+                            key,
+                            value: traits?.[key]
+                        }))
+                    );
+
+                    const segments = getIdentitySegments(this.environment, identityModel);
+                    return resolve(segments);
+                });
+            });
+        }
+        console.error('This function is only permitted with local evaluation.');
+        return Promise.resolve([]);
+    }
+
+    /**
+     * Updates the environment state for local flag evaluation.
+     * Sets a local promise to prevent race conditions in getIdentityFlags / getIdentitySegments.
+     * You only need to call this if you wish to bypass environmentRefreshIntervalSeconds.
+     */
+    async updateEnvironment() {
+        const request = this.getEnvironmentFromApi();
+        if (!this.environmentPromise) {
+            this.environmentPromise = request.then(res => {
+                this.environment = res;
+            });
+            await this.environmentPromise;
+        } else {
+            this.environment = await request;
+        }
+    }
+
+    private async getJSONResponse(
+        url: string,
+        method: string,
+        body?: { [key: string]: any }
+    ): Promise<any> {
+        const headers: { [key: string]: any } = { 'Content-Type': 'application/json' };
+        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();
+    }
+
+    /**
+     * This promise ensures that the environment is retrieved before attempting to locally evaluate.
+     */
+    private environmentPromise: Promise<any> | undefined;
+
+    private async getEnvironmentFromApi() {
+        const environment_data = await this.getJSONResponse(this.environmentUrl, 'GET');
+        return buildEnvironmentModel(environment_data);
+    }
+
+    private getEnvironmentFlagsFromDocument() {
+        return Flags.fromFeatureStateModels({
+            featureStates: getEnvironmentFeatureStates(this.environment),
+            analyticsProcessor: this.analyticsProcessor,
+            defaultFlagHandler: this.defaultFlagHandler
+        });
+    }
+
+    private getIdentityFlagsFromDocument(identifier: string, traits: { [key: string]: any }) {
+        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);
+    }
+}
+
+export default Flagsmith;

package/sdk/models.ts

@@ -0,0 +1,145 @@
+import { FeatureStateModel } from '../flagsmith-engine/features/models';
+import { AnalyticsProcessor } from './analytics';
+import { FlagsmithClientError } from './errors';
+
+export class BaseFlag {
+    enabled: boolean;
+    value: string | number | boolean | undefined;
+    isDefault: boolean;
+
+    constructor(
+        value: string | number | boolean | undefined,
+        enabled: boolean,
+        isDefault: boolean
+    ) {
+        this.value = value;
+        this.enabled = enabled;
+        this.isDefault = isDefault;
+    }
+}
+
+export class DefaultFlag extends BaseFlag {
+    constructor(value: string | number | boolean | undefined, enabled: boolean) {
+        super(value, enabled, true);
+    }
+}
+
+export class Flag extends BaseFlag {
+    featureId: number;
+    featureName: string;
+
+    constructor(params: {
+        value: string | number | boolean | undefined;
+        enabled: boolean;
+        isDefault?: boolean;
+        featureId: number;
+        featureName: string;
+    }) {
+        super(params.value, params.enabled, !!params.isDefault);
+        this.featureId = params.featureId;
+        this.featureName = params.featureName;
+    }
+
+    static fromFeatureStateModel(
+        fsm: FeatureStateModel,
+        identityId: number | string | undefined
+    ): Flag {
+        return new Flag({
+            value: fsm.getValue(identityId),
+            enabled: fsm.enabled,
+            featureId: fsm.feature.id,
+            featureName: fsm.feature.name
+        });
+    }
+
+    static fromAPIFlag(flagData: any): Flag {
+        return new Flag({
+            enabled: flagData['enabled'],
+            value: flagData['feature_state_value'] || flagData['value'],
+            featureId: flagData['feature']['id'],
+            featureName: flagData['feature']['name']
+        });
+    }
+}
+
+export class Flags {
+    flags: { [key: string]: Flag } = {};
+    defaultFlagHandler?: (featureName: string) => DefaultFlag;
+    analyticsProcessor?: AnalyticsProcessor;
+
+    constructor(data: {
+        flags: { [key: string]: Flag };
+        defaultFlagHandler?: (v: string) => DefaultFlag;
+        analyticsProcessor?: AnalyticsProcessor;
+    }) {
+        this.flags = data.flags;
+        this.defaultFlagHandler = data.defaultFlagHandler;
+        this.analyticsProcessor = data.analyticsProcessor;
+    }
+
+    static fromFeatureStateModels(data: {
+        featureStates: FeatureStateModel[];
+        analyticsProcessor?: AnalyticsProcessor;
+        defaultFlagHandler?: (f: string) => DefaultFlag;
+        identityID?: string | number;
+    }): Flags {
+        const flags: { [key: string]: any } = {};
+        for (const fs of data.featureStates) {
+            flags[fs.feature.name] = Flag.fromFeatureStateModel(fs, data.identityID);
+        }
+        return new Flags({
+            flags: flags,
+            defaultFlagHandler: data.defaultFlagHandler,
+            analyticsProcessor: data.analyticsProcessor
+        });
+    }
+
+    static fromAPIFlags(data: {
+        apiFlags: { [key: string]: any }[];
+        analyticsProcessor?: AnalyticsProcessor;
+        defaultFlagHandler?: (v: string) => DefaultFlag;
+    }): Flags {
+        const flags: { [key: string]: any } = {};
+
+        for (const flagData of data.apiFlags) {
+            flags[flagData['feature']['name']] = Flag.fromAPIFlag(flagData);
+        }
+
+        return new Flags({
+            flags: flags,
+            defaultFlagHandler: data.defaultFlagHandler,
+            analyticsProcessor: data.analyticsProcessor
+        });
+    }
+
+    allFlags(): Flag[] {
+        return Object.values(this.flags);
+    }
+
+    getFlag(featureName: string): BaseFlag {
+        const flag = this.flags[featureName];
+
+        if (!flag) {
+            if (this.defaultFlagHandler) {
+                return this.defaultFlagHandler(featureName);
+            }
+
+            return { enabled: false, isDefault: true, value: undefined };
+
+        }
+
+        if (this.analyticsProcessor && flag.featureId) {
+            this.analyticsProcessor.trackFeature(flag.featureId);
+        }
+
+        return flag;
+    }
+
+    getFeatureValue(featureName: string): any {
+        return this.getFlag(featureName).value;
+    }
+
+    isFeatureEnabled(featureName: string): boolean {
+        return this.getFlag(featureName).enabled;
+    }
+}

package/sdk/polling_manager.ts

@@ -0,0 +1,31 @@
+import Flagsmith from '.';
+
+export class EnvironmentDataPollingManager {
+    private interval?: NodeJS.Timer;
+    private main: Flagsmith;
+    private refreshIntervalSeconds: number;
+
+    constructor(main: Flagsmith, refreshIntervalSeconds: number) {
+        this.main = main;
+        this.refreshIntervalSeconds = refreshIntervalSeconds;
+    }
+
+    start() {
+        const updateEnvironment = () => {
+            if (this.interval) clearInterval(this.interval);
+            this.interval = setInterval(async () => {
+                await this.main.updateEnvironment();
+            }, this.refreshIntervalSeconds * 1000);
+        };
+        // todo: this call should be awaited for getIdentityFlags/getEnvironmentFlags when enableLocalEvaluation is true
+        this.main.updateEnvironment();
+        updateEnvironment();
+    }
+
+    stop() {
+        if (!this.interval) {
+            return;
+        }
+        clearInterval(this.interval);
+    }
+}

package/sdk/utils.ts

@@ -0,0 +1,45 @@
+import fetch, { Response } from 'node-fetch';
+// @ts-ignore
+if (typeof fetch.default !== 'undefined') fetch = fetch.default;
+
+export function generateIdentitiesData(identifier: string, traits?: { [key: string]: any }) {
+    const traitsGenerated = Object.entries(traits || {}).map(trait => ({
+        trait_key: trait[0],
+        trait_value: trait[1]
+    }));
+    return {
+        identifier: identifier,
+        traits: traitsGenerated
+    };
+}
+
+export const delay = (ms: number) =>
+    new Promise(resolve => setTimeout(() => resolve(undefined), ms));
+
+export const retryFetch = (
+    url: string,
+    fetchOptions = {},
+    retries = 3,
+    retryDelay = 1000,
+    timeout: number
+): Promise<Response> => {
+    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);
+    });
+};

package/tests/engine/e2e/engine.test.ts

@@ -0,0 +1,51 @@
+import { readFileSync } from 'fs';
+import { 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 { buildIdentityModel } from '../../../flagsmith-engine/identities/util';
+
+function extractTestCases(
+    filePath: string
+): {
+    environment: EnvironmentModel;
+    identity: IdentityModel;
+    response: any;
+}[] {
+    const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+    const environmentModel = buildEnvironmentModel(data['environment']);
+    const test_data = data['identities_and_responses'].map((test_case: any) => {
+        const identity = buildIdentityModel(test_case['identity']);
+
+        return {
+            environment: environmentModel,
+            identity: identity,
+            response: test_case['response']
+        };
+    });
+    return test_data;
+}
+
+test('Test Engine', () => {
+    const testCases = extractTestCases(
+        __dirname + '/../engine-tests/engine-test-data/data/environment_n9fbf9h3v4fFgH3U3ngWhb.json'
+    );
+    for (const testCase of testCases) {
+        const engine_response = getIdentityFeatureStates(testCase.environment, testCase.identity);
+        const sortedEngineFlags = engine_response.sort((a, b) =>
+            a.feature.name > b.feature.name ? 1 : -1
+        );
+        const sortedAPIFlags = testCase.response['flags'].sort((a: any, b: any) =>
+            a.feature.name > b.feature.name ? 1 : -1
+        );
+
+        expect(sortedEngineFlags.length).toBe(sortedAPIFlags.length);
+
+        for (let i = 0; i < sortedEngineFlags.length; i++) {
+            expect(sortedEngineFlags[i].getValue(testCase.identity.djangoID)).toBe(
+                sortedAPIFlags[i]['feature_state_value']
+            );
+            expect(sortedEngineFlags[i].enabled).toBe(sortedAPIFlags[i]['enabled']);
+        }
+    }
+});