flagsmith-nodejs 2.0.0 → 2.0.3

package/build/sdk/index.js

@@ -0,0 +1,492 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Flagsmith = void 0;
+var flagsmith_engine_1 = require("../flagsmith-engine");
+var util_1 = require("../flagsmith-engine/environments/util");
+var models_1 = require("../flagsmith-engine/identities/models");
+var models_2 = require("../flagsmith-engine/identities/traits/models");
+var analytics_1 = require("./analytics");
+var errors_1 = require("./errors");
+var models_3 = require("./models");
+var polling_manager_1 = require("./polling_manager");
+var utils_1 = require("./utils");
+var evaluators_1 = require("../flagsmith-engine/segments/evaluators");
+var DEFAULT_API_URL = 'https://edge.api.flagsmith.com/api/v1/';
+var Flagsmith = /** @class */ (function () {
+    /**
+     * 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
+     */
+    function Flagsmith(data) {
+        this.apiUrl = DEFAULT_API_URL;
+        this.enableLocalEvaluation = false;
+        this.environmentRefreshIntervalSeconds = 60;
+        this.enableAnalytics = false;
+        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 = "".concat(this.apiUrl, "flags/");
+        this.identitiesUrl = "".concat(this.apiUrl, "identities/");
+        this.environmentUrl = "".concat(this.apiUrl, "environment-document/");
+        this.onEnvironmentChange = data.onEnvironmentChange;
+        if (!!data.cache) {
+            var missingMethods = ['has', 'get', 'set'].filter(function (method) { return data.cache && !data.cache[method]; });
+            if (missingMethods.length > 0) {
+                throw new Error("Please implement the following methods in your cache: ".concat(missingMethods.join(', ')));
+            }
+            this.cache = data.cache;
+        }
+        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 polling_manager_1.EnvironmentDataPollingManager(this, this.environmentRefreshIntervalSeconds);
+            this.environmentDataPollingManager.start();
+            this.updateEnvironment();
+        }
+        this.analyticsProcessor = data.enableAnalytics
+            ? new analytics_1.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.
+     */
+    Flagsmith.prototype.getEnvironmentFlags = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var cachedItem, _a;
+            var _this = this;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _a = !!this.cache;
+                        if (!_a) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.cache.get("flags")];
+                    case 1:
+                        _a = (_b.sent());
+                        _b.label = 2;
+                    case 2:
+                        cachedItem = _a;
+                        if (!!cachedItem) {
+                            return [2 /*return*/, cachedItem];
+                        }
+                        if (this.enableLocalEvaluation) {
+                            return [2 /*return*/, new Promise(function (resolve) {
+                                    return _this.environmentPromise.then(function () {
+                                        resolve(_this.getEnvironmentFlagsFromDocument());
+                                    });
+                                })];
+                        }
+                        if (this.environment) {
+                            return [2 /*return*/, this.getEnvironmentFlagsFromDocument()];
+                        }
+                        return [2 /*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.
+     */
+    Flagsmith.prototype.getIdentityFlags = function (identifier, traits) {
+        return __awaiter(this, void 0, void 0, function () {
+            var cachedItem, _a;
+            var _this = this;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _a = !!this.cache;
+                        if (!_a) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.cache.get("flags-".concat(identifier))];
+                    case 1:
+                        _a = (_b.sent());
+                        _b.label = 2;
+                    case 2:
+                        cachedItem = _a;
+                        if (!!cachedItem) {
+                            return [2 /*return*/, cachedItem];
+                        }
+                        traits = traits || {};
+                        if (this.enableLocalEvaluation) {
+                            return [2 /*return*/, new Promise(function (resolve) {
+                                    return _this.environmentPromise.then(function () {
+                                        resolve(_this.getIdentityFlagsFromDocument(identifier, traits || {}));
+                                    });
+                                })];
+                        }
+                        return [2 /*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.
+     */
+    Flagsmith.prototype.getIdentitySegments = function (identifier, traits) {
+        var _this = this;
+        traits = traits || {};
+        if (this.enableLocalEvaluation) {
+            return this.environmentPromise.then(function () {
+                return new Promise(function (resolve) {
+                    var identityModel = _this.buildIdentityModel(identifier, Object.keys(traits || {}).map(function (key) { return ({
+                        key: key,
+                        value: traits === null || traits === void 0 ? void 0 : traits[key]
+                    }); }));
+                    var segments = (0, evaluators_1.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.
+     */
+    Flagsmith.prototype.updateEnvironment = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var request, _a, e_1;
+            var _this = this;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _b.trys.push([0, 5, , 6]);
+                        request = this.getEnvironmentFromApi();
+                        if (!!this.environmentPromise) return [3 /*break*/, 2];
+                        this.environmentPromise = request.then(function (res) {
+                            _this.environment = res;
+                        });
+                        return [4 /*yield*/, this.environmentPromise];
+                    case 1:
+                        _b.sent();
+                        return [3 /*break*/, 4];
+                    case 2:
+                        _a = this;
+                        return [4 /*yield*/, request];
+                    case 3:
+                        _a.environment = _b.sent();
+                        _b.label = 4;
+                    case 4:
+                        if (this.onEnvironmentChange) {
+                            this.onEnvironmentChange(null, this.environment);
+                        }
+                        return [3 /*break*/, 6];
+                    case 5:
+                        e_1 = _b.sent();
+                        if (this.onEnvironmentChange) {
+                            this.onEnvironmentChange(e_1, this.environment);
+                        }
+                        return [3 /*break*/, 6];
+                    case 6: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    Flagsmith.prototype.getJSONResponse = function (url, method, body) {
+        return __awaiter(this, void 0, void 0, function () {
+            var headers, _a, _b, _c, k, v, data;
+            var e_2, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        headers = { 'Content-Type': 'application/json' };
+                        if (this.environmentKey) {
+                            headers['X-Environment-Key'] = this.environmentKey;
+                        }
+                        if (this.customHeaders) {
+                            try {
+                                for (_a = __values(Object.entries(this.customHeaders)), _b = _a.next(); !_b.done; _b = _a.next()) {
+                                    _c = __read(_b.value, 2), k = _c[0], v = _c[1];
+                                    headers[k] = v;
+                                }
+                            }
+                            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                            finally {
+                                try {
+                                    if (_b && !_b.done && (_d = _a.return)) _d.call(_a);
+                                }
+                                finally { if (e_2) throw e_2.error; }
+                            }
+                        }
+                        return [4 /*yield*/, (0, utils_1.retryFetch)(url, {
+                                method: method,
+                                timeout: this.requestTimeoutSeconds || undefined,
+                                body: JSON.stringify(body),
+                                headers: headers
+                            }, this.retries, (this.requestTimeoutSeconds || 10) * 1000)];
+                    case 1:
+                        data = _e.sent();
+                        if (data.status !== 200) {
+                            throw new errors_1.FlagsmithAPIError("Invalid request made to Flagsmith API. Response status code: ".concat(data.status));
+                        }
+                        return [2 /*return*/, data.json()];
+                }
+            });
+        });
+    };
+    Flagsmith.prototype.getEnvironmentFromApi = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var environment_data;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.getJSONResponse(this.environmentUrl, 'GET')];
+                    case 1:
+                        environment_data = _a.sent();
+                        return [2 /*return*/, (0, util_1.buildEnvironmentModel)(environment_data)];
+                }
+            });
+        });
+    };
+    Flagsmith.prototype.getEnvironmentFlagsFromDocument = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var flags;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        flags = models_3.Flags.fromFeatureStateModels({
+                            featureStates: (0, flagsmith_engine_1.getEnvironmentFeatureStates)(this.environment),
+                            analyticsProcessor: this.analyticsProcessor,
+                            defaultFlagHandler: this.defaultFlagHandler
+                        });
+                        if (!!!this.cache) return [3 /*break*/, 2];
+                        // @ts-ignore node-cache types are incorrect, ttl should be optional
+                        return [4 /*yield*/, this.cache.set('flags', flags)];
+                    case 1:
+                        // @ts-ignore node-cache types are incorrect, ttl should be optional
+                        _a.sent();
+                        _a.label = 2;
+                    case 2: return [2 /*return*/, flags];
+                }
+            });
+        });
+    };
+    Flagsmith.prototype.getIdentityFlagsFromDocument = function (identifier, traits) {
+        return __awaiter(this, void 0, void 0, function () {
+            var identityModel, featureStates, flags;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        identityModel = this.buildIdentityModel(identifier, Object.keys(traits).map(function (key) { return ({
+                            key: key,
+                            value: traits[key]
+                        }); }));
+                        featureStates = (0, flagsmith_engine_1.getIdentityFeatureStates)(this.environment, identityModel);
+                        flags = models_3.Flags.fromFeatureStateModels({
+                            featureStates: featureStates,
+                            analyticsProcessor: this.analyticsProcessor,
+                            defaultFlagHandler: this.defaultFlagHandler
+                        });
+                        if (!!!this.cache) return [3 /*break*/, 2];
+                        // @ts-ignore node-cache types are incorrect, ttl should be optional
+                        return [4 /*yield*/, this.cache.set("flags-".concat(identifier), flags)];
+                    case 1:
+                        // @ts-ignore node-cache types are incorrect, ttl should be optional
+                        _a.sent();
+                        _a.label = 2;
+                    case 2: return [2 /*return*/, flags];
+                }
+            });
+        });
+    };
+    Flagsmith.prototype.getEnvironmentFlagsFromApi = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var apiFlags, flags, e_3;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 4, , 5]);
+                        return [4 /*yield*/, this.getJSONResponse(this.environmentFlagsUrl, 'GET')];
+                    case 1:
+                        apiFlags = _a.sent();
+                        flags = models_3.Flags.fromAPIFlags({
+                            apiFlags: apiFlags,
+                            analyticsProcessor: this.analyticsProcessor,
+                            defaultFlagHandler: this.defaultFlagHandler
+                        });
+                        if (!!!this.cache) return [3 /*break*/, 3];
+                        // @ts-ignore node-cache types are incorrect, ttl should be optional
+                        return [4 /*yield*/, this.cache.set('flags', flags)];
+                    case 2:
+                        // @ts-ignore node-cache types are incorrect, ttl should be optional
+                        _a.sent();
+                        _a.label = 3;
+                    case 3: return [2 /*return*/, flags];
+                    case 4:
+                        e_3 = _a.sent();
+                        if (this.defaultFlagHandler) {
+                            return [2 /*return*/, new models_3.Flags({
+                                    flags: {},
+                                    defaultFlagHandler: this.defaultFlagHandler
+                                })];
+                        }
+                        throw e_3;
+                    case 5: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    Flagsmith.prototype.getIdentityFlagsFromApi = function (identifier, traits) {
+        return __awaiter(this, void 0, void 0, function () {
+            var data, jsonResponse, flags, e_4;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 4, , 5]);
+                        data = (0, utils_1.generateIdentitiesData)(identifier, traits);
+                        return [4 /*yield*/, this.getJSONResponse(this.identitiesUrl, 'POST', data)];
+                    case 1:
+                        jsonResponse = _a.sent();
+                        flags = models_3.Flags.fromAPIFlags({
+                            apiFlags: jsonResponse['flags'],
+                            analyticsProcessor: this.analyticsProcessor,
+                            defaultFlagHandler: this.defaultFlagHandler
+                        });
+                        if (!!!this.cache) return [3 /*break*/, 3];
+                        // @ts-ignore node-cache types are incorrect, ttl should be optional
+                        return [4 /*yield*/, this.cache.set("flags-".concat(identifier), flags)];
+                    case 2:
+                        // @ts-ignore node-cache types are incorrect, ttl should be optional
+                        _a.sent();
+                        _a.label = 3;
+                    case 3: return [2 /*return*/, flags];
+                    case 4:
+                        e_4 = _a.sent();
+                        if (this.defaultFlagHandler) {
+                            return [2 /*return*/, new models_3.Flags({
+                                    flags: {},
+                                    defaultFlagHandler: this.defaultFlagHandler
+                                })];
+                        }
+                        throw e_4;
+                    case 5: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    Flagsmith.prototype.buildIdentityModel = function (identifier, traits) {
+        var traitModels = traits.map(function (trait) { return new models_2.TraitModel(trait.key, trait.value); });
+        return new models_1.IdentityModel('0', traitModels, [], this.environment.apiKey, identifier);
+    };
+    return Flagsmith;
+}());
+exports.Flagsmith = Flagsmith;
+exports.default = Flagsmith;

package/build/sdk/models.d.ts

@@ -0,0 +1,55 @@
+import { FeatureStateModel } from '../flagsmith-engine/features/models';
+import { AnalyticsProcessor } from './analytics';
+export declare class BaseFlag {
+    enabled: boolean;
+    value: string | number | boolean | undefined;
+    isDefault: boolean;
+    constructor(value: string | number | boolean | undefined, enabled: boolean, isDefault: boolean);
+}
+export declare class DefaultFlag extends BaseFlag {
+    constructor(value: string | number | boolean | undefined, enabled: boolean);
+}
+export declare class Flag extends BaseFlag {
+    featureId: number;
+    featureName: string;
+    constructor(params: {
+        value: string | number | boolean | undefined;
+        enabled: boolean;
+        isDefault?: boolean;
+        featureId: number;
+        featureName: string;
+    });
+    static fromFeatureStateModel(fsm: FeatureStateModel, identityId: number | string | undefined): Flag;
+    static fromAPIFlag(flagData: any): Flag;
+}
+export declare class Flags {
+    flags: {
+        [key: string]: Flag;
+    };
+    defaultFlagHandler?: (featureName: string) => DefaultFlag;
+    analyticsProcessor?: AnalyticsProcessor;
+    constructor(data: {
+        flags: {
+            [key: string]: Flag;
+        };
+        defaultFlagHandler?: (v: string) => DefaultFlag;
+        analyticsProcessor?: AnalyticsProcessor;
+    });
+    static fromFeatureStateModels(data: {
+        featureStates: FeatureStateModel[];
+        analyticsProcessor?: AnalyticsProcessor;
+        defaultFlagHandler?: (f: string) => DefaultFlag;
+        identityID?: string | number;
+    }): Flags;
+    static fromAPIFlags(data: {
+        apiFlags: {
+            [key: string]: any;
+        }[];
+        analyticsProcessor?: AnalyticsProcessor;
+        defaultFlagHandler?: (v: string) => DefaultFlag;
+    }): Flags;
+    allFlags(): Flag[];
+    getFlag(featureName: string): BaseFlag;
+    getFeatureValue(featureName: string): any;
+    isFeatureEnabled(featureName: string): boolean;
+}