@reflag/node-sdk 1.0.0-alpha.1

package/dist/src/client.js

@@ -0,0 +1,1141 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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 __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundReflagClient = exports.ReflagClient = void 0;
+const fs_1 = __importDefault(require("fs"));
+const flag_evaluation_1 = require("@reflag/flag-evaluation");
+const batch_buffer_1 = __importDefault(require("./batch-buffer"));
+const config_1 = require("./config");
+const fetch_http_client_1 = __importStar(require("./fetch-http-client"));
+const flusher_1 = require("./flusher");
+const inRequestCache_1 = __importDefault(require("./inRequestCache"));
+const periodicallyUpdatingCache_1 = __importDefault(require("./periodicallyUpdatingCache"));
+const rate_limiter_1 = require("./rate-limiter");
+const utils_1 = require("./utils");
+const reflagConfigDefaultFile = "reflag.config.json";
+/**
+ * The SDK client.
+ *
+ * @remarks
+ * This is the main class for interacting with Reflag.
+ * It is used to evaluate flags, update user and company contexts, and track events.
+ *
+ * @example
+ * ```ts
+ * // set the REFLAG_SECRET_KEY environment variable or pass the secret key to the constructor
+ * const client = new ReflagClient();
+ *
+ * // evaluate a flag
+ * const isFlagEnabled = client.getFlag("flag-key", {
+ *   user: { id: "user-id" },
+ *   company: { id: "company-id" },
+ * });
+ * ```
+ **/
+class ReflagClient {
+    /**
+     * Creates a new SDK client.
+     * See README for configuration options.
+     *
+     * @param options - The options for the client or an existing client to clone.
+     * @param options.secretKey - The secret key to use for the client.
+     * @param options.apiBaseUrl - The base URL to send requests to (optional).
+     * @param options.logger - The logger to use for logging (optional).
+     * @param options.httpClient - The HTTP client to use for sending requests (optional).
+     * @param options.logLevel - The log level to use for logging (optional).
+     * @param options.offline - Whether to run in offline mode (optional).
+     * @param options.fallbackFlags - The fallback flags to use if the flag is not found (optional).
+     * @param options.batchOptions - The options for the batch buffer (optional).
+     * @param options.flagOverrides - The flag overrides to use for the client (optional).
+     * @param options.configFile - The path to the config file (optional).
+     * @param options.flagsFetchRetries - Number of retries for fetching flags (optional, defaults to 3).
+     * @param options.fetchTimeoutMs - Timeout for fetching flags (optional, defaults to 10000ms).
+     * @param options.cacheStrategy - The cache strategy to use for the client (optional, defaults to "periodically-update").
+     *
+     * @throws An error if the options are invalid.
+     **/
+    constructor(options = {}) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        this.initializationFinished = false;
+        this._initialize = (0, utils_1.once)(() => __awaiter(this, void 0, void 0, function* () {
+            const start = Date.now();
+            if (!this._config.offline) {
+                yield this.flagsCache.refresh();
+            }
+            this.logger.info("Reflag initialized in " +
+                Math.round(Date.now() - start) +
+                "ms" +
+                (this._config.offline ? " (offline mode)" : ""));
+            this.initializationFinished = true;
+        }));
+        (0, utils_1.ok)((0, utils_1.isObject)(options), "options must be an object");
+        (0, utils_1.ok)(options.host === undefined ||
+            (typeof options.host === "string" && options.host.length > 0), "host must be a string");
+        (0, utils_1.ok)(options.apiBaseUrl === undefined ||
+            (typeof options.apiBaseUrl === "string" &&
+                options.apiBaseUrl.length > 0), "apiBaseUrl must be a string");
+        (0, utils_1.ok)(options.logger === undefined || (0, utils_1.isObject)(options.logger), "logger must be an object");
+        (0, utils_1.ok)(options.httpClient === undefined || (0, utils_1.isObject)(options.httpClient), "httpClient must be an object");
+        (0, utils_1.ok)(options.fallbackFlags === undefined ||
+            Array.isArray(options.fallbackFlags) ||
+            (0, utils_1.isObject)(options.fallbackFlags), "fallbackFlags must be an array or object");
+        (0, utils_1.ok)(options.batchOptions === undefined || (0, utils_1.isObject)(options.batchOptions), "batchOptions must be an object");
+        (0, utils_1.ok)(options.configFile === undefined ||
+            typeof options.configFile === "string", "configFile must be a string");
+        (0, utils_1.ok)(options.flagsFetchRetries === undefined ||
+            (Number.isInteger(options.flagsFetchRetries) &&
+                options.flagsFetchRetries >= 0), "flagsFetchRetries must be a non-negative integer");
+        (0, utils_1.ok)(options.fetchTimeoutMs === undefined ||
+            (Number.isInteger(options.fetchTimeoutMs) &&
+                options.fetchTimeoutMs >= 0), "fetchTimeoutMs must be a non-negative integer");
+        if (!options.configFile) {
+            options.configFile =
+                ((_a = process.env.REFLAG_CONFIG_FILE) !== null && _a !== void 0 ? _a : fs_1.default.existsSync(reflagConfigDefaultFile))
+                    ? reflagConfigDefaultFile
+                    : undefined;
+        }
+        const externalConfig = (0, config_1.loadConfig)(options.configFile);
+        const config = (0, utils_1.mergeSkipUndefined)(externalConfig, options);
+        const offline = (_b = config.offline) !== null && _b !== void 0 ? _b : process.env.NODE_ENV === "test";
+        if (!offline) {
+            (0, utils_1.ok)(typeof config.secretKey === "string", "secretKey must be a string, or set offline=true");
+            (0, utils_1.ok)(config.secretKey.length > 22, "invalid secretKey specified");
+        }
+        // use the supplied logger or apply the log level to the console logger
+        const logLevel = (_d = (_c = options.logLevel) !== null && _c !== void 0 ? _c : config === null || config === void 0 ? void 0 : config.logLevel) !== null && _d !== void 0 ? _d : "INFO";
+        this.logger = options.logger
+            ? options.logger
+            : (0, utils_1.applyLogLevel)((0, utils_1.decorateLogger)(config_1.REFLAG_LOG_PREFIX, console), logLevel);
+        const fallbackFlags = Array.isArray(options.fallbackFlags)
+            ? options.fallbackFlags.reduce((acc, key) => {
+                acc[key] = {
+                    isEnabled: true,
+                    key,
+                };
+                return acc;
+            }, {})
+            : (0, utils_1.isObject)(options.fallbackFlags)
+                ? Object.entries(options.fallbackFlags).reduce((acc, [key, fallback]) => {
+                    acc[key] = {
+                        isEnabled: typeof fallback === "object"
+                            ? fallback.isEnabled
+                            : !!fallback,
+                        key,
+                        config: typeof fallback === "object" && fallback.config
+                            ? {
+                                key: fallback.config.key,
+                                payload: fallback.config.payload,
+                            }
+                            : undefined,
+                    };
+                    return acc;
+                }, {})
+                : undefined;
+        this.rateLimiter = (0, rate_limiter_1.newRateLimiter)(config_1.FLAG_EVENT_RATE_LIMITER_WINDOW_SIZE_MS);
+        this.httpClient = options.httpClient || fetch_http_client_1.default;
+        this.batchBuffer = new batch_buffer_1.default(Object.assign(Object.assign({}, options === null || options === void 0 ? void 0 : options.batchOptions), { flushHandler: (items) => this.sendBulkEvents(items), logger: this.logger }));
+        this._config = {
+            offline,
+            emitEvaluationEvents: (_e = config.emitEvaluationEvents) !== null && _e !== void 0 ? _e : true,
+            apiBaseUrl: ((_f = config.apiBaseUrl) !== null && _f !== void 0 ? _f : config.host) || config_1.API_BASE_URL,
+            headers: {
+                "Content-Type": "application/json",
+                [config_1.SDK_VERSION_HEADER_NAME]: config_1.SDK_VERSION,
+                ["Authorization"]: `Bearer ${config.secretKey}`,
+            },
+            refetchInterval: config_1.FLAGS_REFETCH_MS,
+            staleWarningInterval: config_1.FLAGS_REFETCH_MS * 5,
+            fallbackFlags: fallbackFlags,
+            flagOverrides: typeof config.flagOverrides === "function"
+                ? config.flagOverrides
+                : () => config.flagOverrides,
+            flagsFetchRetries: (_g = options.flagsFetchRetries) !== null && _g !== void 0 ? _g : 3,
+            fetchTimeoutMs: (_h = options.fetchTimeoutMs) !== null && _h !== void 0 ? _h : config_1.API_TIMEOUT_MS,
+            cacheStrategy: (_j = options.cacheStrategy) !== null && _j !== void 0 ? _j : "periodically-update",
+        };
+        if (((_l = (_k = config.batchOptions) === null || _k === void 0 ? void 0 : _k.flushOnExit) !== null && _l !== void 0 ? _l : true) && !this._config.offline) {
+            (0, flusher_1.subscribe)(() => this.flush());
+        }
+        if (!new URL(this._config.apiBaseUrl).pathname.endsWith("/")) {
+            this._config.apiBaseUrl += "/";
+        }
+        const fetchFlags = () => __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.get("features", this._config.flagsFetchRetries);
+            if (!(0, utils_1.isObject)(res) || !Array.isArray(res === null || res === void 0 ? void 0 : res.features)) {
+                this.logger.warn("flags cache: invalid response", res);
+                return undefined;
+            }
+            return res.features.map((flagDef) => {
+                var _a;
+                return Object.assign(Object.assign({}, flagDef), { enabledEvaluator: (0, flag_evaluation_1.newEvaluator)(flagDef.targeting.rules.map((rule) => ({
+                        filter: rule.filter,
+                        value: true,
+                    }))), configEvaluator: flagDef.config
+                        ? (0, flag_evaluation_1.newEvaluator)((_a = flagDef.config) === null || _a === void 0 ? void 0 : _a.variants.map((variant) => ({
+                            filter: variant.filter,
+                            value: {
+                                key: variant.key,
+                                payload: variant.payload,
+                            },
+                        })))
+                        : undefined });
+            });
+        });
+        if (this._config.cacheStrategy === "periodically-update") {
+            this.flagsCache = (0, periodicallyUpdatingCache_1.default)(this._config.refetchInterval, this._config.staleWarningInterval, this.logger, fetchFlags);
+        }
+        else {
+            this.flagsCache = (0, inRequestCache_1.default)(this._config.refetchInterval, this.logger, fetchFlags);
+        }
+    }
+    /**
+     * Sets the flag overrides.
+     *
+     * @param overrides - The flag overrides.
+     *
+     * @remarks
+     * The flag overrides are used to override the flag definitions.
+     * This is useful for testing or development.
+     *
+     * @example
+     * ```ts
+     * client.flagOverrides = {
+     *   "flag-1": true,
+     *   "flag-2": false,
+     * };
+     * ```
+     **/
+    set flagOverrides(overrides) {
+        if (typeof overrides === "object") {
+            this._config.flagOverrides = () => overrides;
+        }
+        else {
+            this._config.flagOverrides = overrides;
+        }
+    }
+    /**
+     * Clears the flag overrides.
+     *
+     * @remarks
+     * This is useful for testing or development.
+     *
+     * @example
+     * ```ts
+     * afterAll(() => {
+     *   client.clearFlagOverrides();
+     * });
+     * ```
+     **/
+    clearFlagOverrides() {
+        this._config.flagOverrides = () => ({});
+    }
+    /**
+     * Returns a new BoundReflagClient with the user/company/otherContext
+     * set to be used in subsequent calls.
+     * For example, for evaluating flag targeting or tracking events.
+     *
+     * @param context - The context to bind the client to.
+     * @param context.enableTracking - Whether to enable tracking for the context.
+     * @param context.user - The user context.
+     * @param context.company - The company context.
+     * @param context.other - The other context.
+     *
+     * @returns A new client bound with the arguments given.
+     *
+     * @throws An error if the user/company is given but their ID is not a string.
+     *
+     * @remarks
+     * The `updateUser` / `updateCompany` methods will automatically be called when
+     * the user/company is set respectively.
+     **/
+    bindClient(_a) {
+        var { enableTracking = true } = _a, context = __rest(_a, ["enableTracking"]);
+        return new BoundReflagClient(this, Object.assign({ enableTracking }, context));
+    }
+    /**
+     * Updates the associated user in Reflag.
+     *
+     * @param userId - The userId of the user to update.
+     * @param options - The options for the user.
+     * @param options.attributes - The additional attributes of the user (optional).
+     * @param options.meta - The meta context associated with tracking (optional).
+     *
+     * @throws An error if the company is not set or the options are invalid.
+     * @remarks
+     * The company must be set using `withCompany` before calling this method.
+     * If the user is set, the company will be associated with the user.
+     **/
+    updateUser(userId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, utils_1.idOk)(userId, "userId");
+            (0, utils_1.ok)(options === undefined || (0, utils_1.isObject)(options), "options must be an object");
+            (0, utils_1.ok)((options === null || options === void 0 ? void 0 : options.attributes) === undefined || (0, utils_1.isObject)(options.attributes), "attributes must be an object");
+            checkMeta(options === null || options === void 0 ? void 0 : options.meta);
+            if (this._config.offline) {
+                return;
+            }
+            if (this.rateLimiter.isAllowed((0, utils_1.hashObject)(Object.assign(Object.assign({}, options), { userId })))) {
+                yield this.batchBuffer.add({
+                    type: "user",
+                    userId,
+                    attributes: options === null || options === void 0 ? void 0 : options.attributes,
+                    context: options === null || options === void 0 ? void 0 : options.meta,
+                });
+            }
+        });
+    }
+    /**
+     * Updates the associated company in Reflag.
+     *
+     * @param companyId - The companyId of the company to update.
+     * @param options - The options for the company.
+     * @param options.attributes - The additional attributes of the company (optional).
+     * @param options.meta - The meta context associated with tracking (optional).
+     * @param options.userId - The userId of the user to associate with the company (optional).
+     *
+     * @throws An error if the company is not set or the options are invalid.
+     * @remarks
+     * The company must be set using `withCompany` before calling this method.
+     * If the user is set, the company will be associated with the user.
+     **/
+    updateCompany(companyId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, utils_1.idOk)(companyId, "companyId");
+            (0, utils_1.ok)(options === undefined || (0, utils_1.isObject)(options), "options must be an object");
+            (0, utils_1.ok)((options === null || options === void 0 ? void 0 : options.attributes) === undefined || (0, utils_1.isObject)(options.attributes), "attributes must be an object");
+            checkMeta(options === null || options === void 0 ? void 0 : options.meta);
+            if (typeof (options === null || options === void 0 ? void 0 : options.userId) !== "undefined") {
+                (0, utils_1.idOk)(options === null || options === void 0 ? void 0 : options.userId, "userId");
+            }
+            if (this._config.offline) {
+                return;
+            }
+            if (this.rateLimiter.isAllowed((0, utils_1.hashObject)(Object.assign(Object.assign({}, options), { companyId })))) {
+                yield this.batchBuffer.add({
+                    type: "company",
+                    companyId,
+                    userId: options === null || options === void 0 ? void 0 : options.userId,
+                    attributes: options === null || options === void 0 ? void 0 : options.attributes,
+                    context: options === null || options === void 0 ? void 0 : options.meta,
+                });
+            }
+        });
+    }
+    /**
+     * Tracks an event in Reflag.
+  
+     * @param options.companyId - Optional company ID for the event (optional).
+     *
+     * @throws An error if the user is not set or the event is invalid or the options are invalid.
+     * @remarks
+     * If the company is set, the event will be associated with the company.
+     **/
+    track(userId, event, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, utils_1.idOk)(userId, "userId");
+            (0, utils_1.ok)(typeof event === "string" && event.length > 0, "event must be a string");
+            (0, utils_1.ok)(options === undefined || (0, utils_1.isObject)(options), "options must be an object");
+            (0, utils_1.ok)((options === null || options === void 0 ? void 0 : options.attributes) === undefined || (0, utils_1.isObject)(options.attributes), "attributes must be an object");
+            (0, utils_1.ok)((options === null || options === void 0 ? void 0 : options.meta) === undefined || (0, utils_1.isObject)(options.meta), "meta must be an object");
+            if ((options === null || options === void 0 ? void 0 : options.companyId) !== undefined) {
+                (0, utils_1.idOk)(options === null || options === void 0 ? void 0 : options.companyId, "companyId");
+            }
+            if (this._config.offline) {
+                return;
+            }
+            yield this.batchBuffer.add({
+                type: "event",
+                event,
+                companyId: options === null || options === void 0 ? void 0 : options.companyId,
+                userId,
+                attributes: options === null || options === void 0 ? void 0 : options.attributes,
+                context: options === null || options === void 0 ? void 0 : options.meta,
+            });
+        });
+    }
+    /**
+     * Initializes the client by caching the flags definitions.
+     *
+     * @remarks
+     * Call this method before calling `getFlags` to ensure the flag definitions are cached.
+     * The client will ignore subsequent calls to this method.
+     **/
+    initialize() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._initialize();
+            return;
+        });
+    }
+    /**
+     * Flushes and completes any in-flight fetches in the flag cache.
+     *
+     * @remarks
+     * It is recommended to call this method when the application is shutting down to ensure all events are sent
+     * before the process exits.
+     *
+     * This method is automatically called when the process exits if `batchOptions.flushOnExit` is `true` in the options (default).
+     */
+    flush() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this._config.offline) {
+                return;
+            }
+            yield this.batchBuffer.flush();
+            yield this.flagsCache.waitRefresh();
+        });
+    }
+    /**
+     * Gets the flag definitions, including all config values.
+     * To evaluate which flags are enabled for a given user/company, use `getFlags`.
+     *
+     * @returns The flags definitions.
+     */
+    getFlagDefinitions() {
+        const flags = this.flagsCache.get() || [];
+        return flags.map((f) => ({
+            key: f.key,
+            description: f.description,
+            flag: f.targeting,
+            config: f.config,
+        }));
+    }
+    /**
+     * Gets the evaluated flags for the current context which includes the user, company, and custom context.
+     *
+     * @param options - The options for the context.
+     * @param options.enableTracking - Whether to enable tracking for the context.
+     * @param options.meta - The meta context associated with the context.
+     * @param options.user - The user context.
+     * @param options.company - The company context.
+     * @param options.other - The other context.
+     *
+     * @returns The evaluated flags.
+     *
+     * @remarks
+     * Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise.
+     **/
+    getFlags(_a) {
+        var { enableTracking = true } = _a, context = __rest(_a, ["enableTracking"]);
+        return this._getFlags(Object.assign({ enableTracking }, context));
+    }
+    /**
+     * Gets the evaluated flag for the current context which includes the user, company, and custom context.
+     * Using the `isEnabled` property sends a `check` event to Reflag.
+     *
+     * @param key - The key of the flag to get.
+     * @returns The evaluated flag.
+     *
+     * @remarks
+     * Call `initialize` before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise.
+     **/
+    getFlag(_a, key) {
+        var { enableTracking = true } = _a, context = __rest(_a, ["enableTracking"]);
+        return this._getFlags(Object.assign({ enableTracking }, context), key);
+    }
+    /**
+     * Gets evaluated flags with the usage of remote context.
+     * This method triggers a network request every time it's called.
+     *
+     * @param userId - The userId of the user to get the flags for.
+     * @param companyId - The companyId of the company to get the flags for.
+     * @param additionalContext - The additional context to get the flags for.
+     *
+     * @returns evaluated flags
+     */
+    getFlagsRemote(userId, companyId, additionalContext) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._getFlagsRemote(undefined, userId, companyId, additionalContext);
+        });
+    }
+    /**
+     * Gets evaluated flag with the usage of remote context.
+     * This method triggers a network request every time it's called.
+     *
+     * @param key - The key of the flag to get.
+     * @param userId - The userId of the user to get the flag for.
+     * @param companyId - The companyId of the company to get the flag for.
+     * @param additionalContext - The additional context to get the flag for.
+     *
+     * @returns evaluated flag
+     */
+    getFlagRemote(key, userId, companyId, additionalContext) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._getFlagsRemote(key, userId, companyId, additionalContext);
+        });
+    }
+    buildUrl(path) {
+        if (path.startsWith("/")) {
+            path = path.slice(1);
+        }
+        const url = new URL(path, this._config.apiBaseUrl);
+        return url.toString();
+    }
+    /**
+     * Sends a POST request to the specified path.
+     *
+     * @param path - The path to send the request to.
+     * @param body - The body of the request.
+     *
+     * @returns A boolean indicating if the request was successful.
+     *
+     * @throws An error if the path or body is invalid.
+     **/
+    post(path, body) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, utils_1.ok)(typeof path === "string" && path.length > 0, "path must be a string");
+            (0, utils_1.ok)(typeof body === "object", "body must be an object");
+            const url = this.buildUrl(path);
+            try {
+                const response = yield this.httpClient.post(url, this._config.headers, body);
+                this.logger.debug(`post request to "${url}"`, response);
+                if (!response.ok || !(0, utils_1.isObject)(response.body) || !response.body.success) {
+                    this.logger.warn(`invalid response received from server for "${url}"`, JSON.stringify(response));
+                    return false;
+                }
+                return true;
+            }
+            catch (error) {
+                this.logger.error(`post request to "${url}" failed with error`, error);
+                return false;
+            }
+        });
+    }
+    /**
+     * Sends a GET request to the specified path.
+     *
+     * @param path - The path to send the request to.
+     * @param retries - Optional number of retries for the request.
+     *
+     * @returns The response from the server.
+     * @throws An error if the path is invalid.
+     **/
+    get(path_1) {
+        return __awaiter(this, arguments, void 0, function* (path, retries = 3) {
+            (0, utils_1.ok)(typeof path === "string" && path.length > 0, "path must be a string");
+            try {
+                const url = this.buildUrl(path);
+                return yield (0, fetch_http_client_1.withRetry)(() => __awaiter(this, void 0, void 0, function* () {
+                    const response = yield this.httpClient.get(url, this._config.headers, this._config.fetchTimeoutMs);
+                    this.logger.debug(`get request to "${url}"`, response);
+                    if (!response.ok ||
+                        !(0, utils_1.isObject)(response.body) ||
+                        !response.body.success) {
+                        throw new Error(`invalid response received from server for "${url}": ${JSON.stringify(response.body)}`);
+                    }
+                    const _a = response.body, { success: _ } = _a, result = __rest(_a, ["success"]);
+                    return result;
+                }), () => {
+                    this.logger.warn("failed to fetch flags, will retry");
+                }, retries, 1000, 10000);
+            }
+            catch (error) {
+                this.logger.error(`get request to "${path}" failed with error after ${retries} retries`, error);
+                return undefined;
+            }
+        });
+    }
+    /**
+     * Sends a batch of events to the Reflag API.
+     *
+     * @param events - The events to send.
+     *
+     * @throws An error if the send fails.
+     **/
+    sendBulkEvents(events) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, utils_1.ok)(Array.isArray(events) && events.length > 0, "events must be a non-empty array");
+            const sent = yield this.post("bulk", events);
+            if (!sent) {
+                throw new Error("Failed to send bulk events");
+            }
+        });
+    }
+    /**
+     * Sends a flag event to the Reflag API.
+     *
+     * Flag events are used to track the evaluation of flag targeting rules.
+     * "check" events are sent when a flag's `isEnabled` property is checked.
+     * "evaluate" events are sent when a flag's targeting rules are matched against
+     * the current context.
+     *
+     * @param event - The event to send.
+     * @param event.action - The action to send.
+     * @param event.key - The key of the flag to send.
+     * @param event.targetingVersion - The targeting version of the flag to send.
+     * @param event.evalResult - The evaluation result of the flag to send.
+     * @param event.evalContext - The evaluation context of the flag to send.
+     * @param event.evalRuleResults - The evaluation rule results of the flag to send.
+     * @param event.evalMissingFields - The evaluation missing fields of the flag to send.
+     *
+     * @throws An error if the event is invalid.
+     *
+     * @remarks
+     * This method is rate-limited to prevent too many events from being sent.
+     **/
+    sendFlagEvent(event) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, utils_1.ok)(typeof event === "object", "event must be an object");
+            (0, utils_1.ok)(typeof event.action === "string" &&
+                (event.action === "evaluate" ||
+                    event.action === "evaluate-config" ||
+                    event.action === "check" ||
+                    event.action === "check-config"), "event must have an action");
+            (0, utils_1.ok)(typeof event.key === "string" && event.key.length > 0, "event must have a flag key");
+            (0, utils_1.ok)(typeof event.targetingVersion === "number" ||
+                event.targetingVersion === undefined, "event must have a targeting version");
+            (0, utils_1.ok)(typeof event.evalResult === "boolean" || (0, utils_1.isObject)(event.evalResult), "event must have an evaluation result");
+            (0, utils_1.ok)(event.evalContext === undefined || typeof event.evalContext === "object", "event context must be an object");
+            (0, utils_1.ok)(event.evalRuleResults === undefined ||
+                Array.isArray(event.evalRuleResults), "event rule results must be an array");
+            (0, utils_1.ok)(event.evalMissingFields === undefined ||
+                Array.isArray(event.evalMissingFields), "event missing fields must be an array");
+            const contextKey = new URLSearchParams((0, flag_evaluation_1.flattenJSON)(event.evalContext || {})).toString();
+            if (this._config.offline) {
+                return;
+            }
+            if (!this._config.emitEvaluationEvents &&
+                (event.action === "evaluate" || event.action === "evaluate-config")) {
+                return;
+            }
+            if (!this.rateLimiter.isAllowed((0, utils_1.hashObject)({
+                action: event.action,
+                key: event.key,
+                targetingVersion: event.targetingVersion,
+                evalResult: event.evalResult,
+                contextKey,
+            }))) {
+                return;
+            }
+            yield this.batchBuffer.add({
+                type: "feature-flag-event",
+                action: event.action,
+                key: event.key,
+                targetingVersion: event.targetingVersion,
+                evalContext: event.evalContext,
+                evalResult: event.evalResult,
+                evalRuleResults: event.evalRuleResults,
+                evalMissingFields: event.evalMissingFields,
+            });
+        });
+    }
+    /**
+     * Updates the context in Reflag (if needed).
+     * This method should be used before requesting flags or binding a client.
+     *
+     * @param options - The options for the context.
+     * @param options.enableTracking - Whether to enable tracking for the context.
+     * @param options.meta - The meta context associated with the context.
+     * @param options.user - The user context.
+     * @param options.company - The company context.
+     * @param options.other - The other context.
+     */
+    syncContext(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            if (!options.enableTracking) {
+                this.logger.debug("tracking disabled, not updating user/company");
+                return;
+            }
+            const promises = [];
+            if (typeof ((_a = options.company) === null || _a === void 0 ? void 0 : _a.id) !== "undefined") {
+                const _c = options.company, { id: _ } = _c, attributes = __rest(_c, ["id"]);
+                promises.push(this.updateCompany(options.company.id, {
+                    attributes,
+                    meta: options.meta,
+                }));
+            }
+            if (typeof ((_b = options.user) === null || _b === void 0 ? void 0 : _b.id) !== "undefined") {
+                const _d = options.user, { id: _ } = _d, attributes = __rest(_d, ["id"]);
+                promises.push(this.updateUser(options.user.id, {
+                    attributes,
+                    meta: options.meta,
+                }));
+            }
+            if (promises.length > 0) {
+                yield Promise.all(promises);
+            }
+        });
+    }
+    /**
+     * Warns if a flag has targeting rules that require context fields that are missing.
+     *
+     * @param context - The context.
+     * @param flag - The flag to check.
+     */
+    _warnMissingFlagContextFields(context, flag) {
+        var _a, _b;
+        const report = {};
+        const { config } = flag, flagData = __rest(flag, ["config"]);
+        if (((_a = flagData.missingContextFields) === null || _a === void 0 ? void 0 : _a.length) &&
+            this.rateLimiter.isAllowed((0, utils_1.hashObject)({
+                flagKey: flagData.key,
+                missingContextFields: flagData.missingContextFields,
+                context,
+            }))) {
+            report[flagData.key] = flagData.missingContextFields;
+        }
+        if (((_b = config === null || config === void 0 ? void 0 : config.missingContextFields) === null || _b === void 0 ? void 0 : _b.length) &&
+            this.rateLimiter.isAllowed((0, utils_1.hashObject)({
+                flagKey: flagData.key,
+                configKey: config.key,
+                missingContextFields: config.missingContextFields,
+                context,
+            }))) {
+            report[`${flagData.key}.config`] = config.missingContextFields;
+        }
+        if (Object.keys(report).length > 0) {
+            this.logger.warn(`flag targeting rules might not be correctly evaluated due to missing context fields.`, report);
+        }
+    }
+    _getFlags(options, key) {
+        checkContextWithTracking(options);
+        if (!this.initializationFinished) {
+            this.logger.error("getFlag(s): ReflagClient is not initialized yet.");
+        }
+        void this.syncContext(options);
+        let flagDefinitions = [];
+        if (!this._config.offline) {
+            const flagDefs = this.flagsCache.get();
+            if (!flagDefs) {
+                this.logger.warn("no flag definitions available, using fallback flags.");
+                const fallbackFlags = this._config.fallbackFlags || {};
+                if (key) {
+                    return this._wrapRawFlag(Object.assign(Object.assign({}, options), { enableChecks: true }), Object.assign({ key }, fallbackFlags[key]));
+                }
+                return Object.fromEntries(Object.entries(fallbackFlags).map(([k, v]) => [
+                    k,
+                    this._wrapRawFlag(options, v),
+                ]));
+            }
+            flagDefinitions = flagDefs;
+        }
+        const { enableTracking = true, meta: _ } = options, context = __rest(options, ["enableTracking", "meta"]);
+        const evaluated = flagDefinitions
+            .filter(({ key: flagKey }) => (key ? key === flagKey : true))
+            .map((flag) => {
+            var _a, _b, _c;
+            return ({
+                flagKey: flag.key,
+                targetingVersion: flag.targeting.version,
+                configVersion: (_a = flag.config) === null || _a === void 0 ? void 0 : _a.version,
+                enabledResult: flag.enabledEvaluator(context, flag.key),
+                configResult: (_c = (_b = flag.configEvaluator) === null || _b === void 0 ? void 0 : _b.call(flag, context, flag.key)) !== null && _c !== void 0 ? _c : {
+                    flagKey: flag.key,
+                    context,
+                    value: undefined,
+                    ruleEvaluationResults: [],
+                    missingContextFields: [],
+                },
+            });
+        });
+        if (enableTracking) {
+            const promises = evaluated
+                .map((res) => {
+                var _a;
+                const outPromises = [];
+                outPromises.push(this.sendFlagEvent({
+                    action: "evaluate",
+                    key: res.flagKey,
+                    targetingVersion: res.targetingVersion,
+                    evalResult: (_a = res.enabledResult.value) !== null && _a !== void 0 ? _a : false,
+                    evalContext: res.enabledResult.context,
+                    evalRuleResults: res.enabledResult.ruleEvaluationResults,
+                    evalMissingFields: res.enabledResult.missingContextFields,
+                }));
+                const config = res.configResult;
+                if (config.value) {
+                    outPromises.push(this.sendFlagEvent({
+                        action: "evaluate-config",
+                        key: res.flagKey,
+                        targetingVersion: res.configVersion,
+                        evalResult: config.value,
+                        evalContext: config.context,
+                        evalRuleResults: config.ruleEvaluationResults,
+                        evalMissingFields: config.missingContextFields,
+                    }));
+                }
+                return outPromises;
+            })
+                .flat();
+            void Promise.allSettled(promises).then((results) => {
+                const failed = results
+                    .map((result) => result.status === "rejected" ? result.reason : undefined)
+                    .filter(Boolean);
+                if (failed.length > 0) {
+                    this.logger.error(`failed to queue some evaluate events.`, {
+                        errors: failed,
+                    });
+                }
+            });
+        }
+        let evaluatedFlags = evaluated.reduce((acc, res) => {
+            var _a, _b, _c, _d, _e, _f, _g;
+            acc[res.flagKey] = {
+                key: res.flagKey,
+                isEnabled: (_a = res.enabledResult.value) !== null && _a !== void 0 ? _a : false,
+                ruleEvaluationResults: res.enabledResult.ruleEvaluationResults,
+                missingContextFields: res.enabledResult.missingContextFields,
+                targetingVersion: res.targetingVersion,
+                config: {
+                    key: (_c = (_b = res.configResult) === null || _b === void 0 ? void 0 : _b.value) === null || _c === void 0 ? void 0 : _c.key,
+                    payload: (_e = (_d = res.configResult) === null || _d === void 0 ? void 0 : _d.value) === null || _e === void 0 ? void 0 : _e.payload,
+                    targetingVersion: res.configVersion,
+                    ruleEvaluationResults: (_f = res.configResult) === null || _f === void 0 ? void 0 : _f.ruleEvaluationResults,
+                    missingContextFields: (_g = res.configResult) === null || _g === void 0 ? void 0 : _g.missingContextFields,
+                },
+            };
+            return acc;
+        }, {});
+        // apply flag overrides
+        const overrides = Object.entries(this._config.flagOverrides(context))
+            .filter(([flagKey]) => (key ? key === flagKey : true))
+            .map(([flagKey, override]) => [
+            flagKey,
+            (0, utils_1.isObject)(override)
+                ? {
+                    key: flagKey,
+                    isEnabled: override.isEnabled,
+                    config: override.config,
+                }
+                : {
+                    key: flagKey,
+                    isEnabled: !!override,
+                    config: undefined,
+                },
+        ]);
+        if (overrides.length > 0) {
+            // merge overrides into evaluated flags
+            evaluatedFlags = Object.assign(Object.assign({}, evaluatedFlags), Object.fromEntries(overrides));
+        }
+        if (key) {
+            return this._wrapRawFlag(Object.assign(Object.assign({}, options), { enableChecks: true }), Object.assign({ key }, evaluatedFlags[key]));
+        }
+        return Object.fromEntries(Object.entries(evaluatedFlags).map(([k, v]) => [
+            k,
+            this._wrapRawFlag(options, v),
+        ]));
+    }
+    _wrapRawFlag(_a, _b) {
+        var { enableTracking, enableChecks = false } = _a, context = __rest(_a, ["enableTracking", "enableChecks"]);
+        var config = _b.config, flag = __rest(_b, ["config"]);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const client = this;
+        const simplifiedConfig = config
+            ? { key: config.key, payload: config.payload }
+            : { key: undefined, payload: undefined };
+        return {
+            get isEnabled() {
+                var _a, _b;
+                if (enableTracking && enableChecks) {
+                    client._warnMissingFlagContextFields(context, flag);
+                    void client
+                        .sendFlagEvent({
+                        action: "check",
+                        key: flag.key,
+                        targetingVersion: flag.targetingVersion,
+                        evalResult: (_a = flag.isEnabled) !== null && _a !== void 0 ? _a : false,
+                        evalContext: context,
+                        evalRuleResults: flag.ruleEvaluationResults,
+                        evalMissingFields: flag.missingContextFields,
+                    })
+                        .catch((err) => {
+                        var _a;
+                        (_a = client.logger) === null || _a === void 0 ? void 0 : _a.error(`failed to send check event for "${flag.key}": ${err}`, err);
+                    });
+                }
+                return (_b = flag.isEnabled) !== null && _b !== void 0 ? _b : false;
+            },
+            get config() {
+                if (enableTracking && enableChecks) {
+                    client._warnMissingFlagContextFields(context, flag);
+                    void client
+                        .sendFlagEvent({
+                        action: "check-config",
+                        key: flag.key,
+                        targetingVersion: config === null || config === void 0 ? void 0 : config.targetingVersion,
+                        evalResult: simplifiedConfig,
+                        evalContext: context,
+                        evalRuleResults: config === null || config === void 0 ? void 0 : config.ruleEvaluationResults,
+                        evalMissingFields: config === null || config === void 0 ? void 0 : config.missingContextFields,
+                    })
+                        .catch((err) => {
+                        var _a;
+                        (_a = client.logger) === null || _a === void 0 ? void 0 : _a.error(`failed to send check event for "${flag.key}": ${err}`, err);
+                    });
+                }
+                return simplifiedConfig;
+            },
+            key: flag.key,
+            track: () => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                if (typeof ((_a = context.user) === null || _a === void 0 ? void 0 : _a.id) === "undefined") {
+                    this.logger.warn("no user set, cannot track event");
+                    return;
+                }
+                if (enableTracking) {
+                    yield this.track(context.user.id, flag.key, {
+                        companyId: (_b = context.company) === null || _b === void 0 ? void 0 : _b.id,
+                    });
+                }
+                else {
+                    this.logger.debug("tracking disabled, not tracking event");
+                }
+            }),
+        };
+    }
+    _getFlagsRemote(key, userId, companyId, additionalContext) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const context = additionalContext || {};
+            if (userId) {
+                context.user = { id: userId };
+            }
+            if (companyId) {
+                context.company = { id: companyId };
+            }
+            const contextWithTracking = Object.assign(Object.assign({}, context), { enableTracking: true });
+            checkContextWithTracking(contextWithTracking);
+            const params = new URLSearchParams(Object.keys(context).length ? (0, flag_evaluation_1.flattenJSON)({ context }) : undefined);
+            if (key) {
+                params.append("key", key);
+            }
+            const res = yield this.get(`features/evaluated?${params}`);
+            if (key) {
+                const flag = res === null || res === void 0 ? void 0 : res.features[key];
+                if (!flag) {
+                    this.logger.error(`flag ${key} not found`);
+                }
+                return this._wrapRawFlag(contextWithTracking, Object.assign({ key }, flag));
+            }
+            else {
+                return (res === null || res === void 0 ? void 0 : res.features)
+                    ? Object.fromEntries(Object.entries(res === null || res === void 0 ? void 0 : res.features).map(([flagKey, flag]) => [
+                        flagKey,
+                        this._wrapRawFlag(contextWithTracking, flag),
+                    ]))
+                    : {};
+            }
+        });
+    }
+}
+exports.ReflagClient = ReflagClient;
+/**
+ * A client bound with a specific user, company, and other context.
+ */
+class BoundReflagClient {
+    /**
+     * (Internal) Creates a new BoundReflagClient. Use `bindClient` to create a new client bound with a specific context.
+     *
+     * @param client - The `ReflagClient` to use.
+     * @param options - The options for the client.
+     * @param options.enableTracking - Whether to enable tracking for the client.
+     *
+     * @internal
+     */
+    constructor(client, _a) {
+        var { enableTracking = true } = _a, context = __rest(_a, ["enableTracking"]);
+        this._client = client;
+        this._options = Object.assign({ enableTracking }, context);
+        checkContextWithTracking(this._options);
+        void this._client["syncContext"](this._options);
+    }
+    /**
+     * Gets the "other" context associated with the client.
+     *
+     * @returns The "other" context or `undefined` if it is not set.
+     **/
+    get otherContext() {
+        return this._options.other;
+    }
+    /**
+     * Gets the user associated with the client.
+     *
+     * @returns The user or `undefined` if it is not set.
+     **/
+    get user() {
+        return this._options.user;
+    }
+    /**
+     * Gets the company associated with the client.
+     *
+     * @returns The company or `undefined` if it is not set.
+     **/
+    get company() {
+        return this._options.company;
+    }
+    /**
+     * Get flags for the user/company/other context bound to this client.
+     * Meant for use in serialization of flags for transferring to the client-side/browser.
+     *
+     * @returns Flags for the given user/company and whether each one is enabled or not
+     */
+    getFlags() {
+        return this._client.getFlags(this._options);
+    }
+    /**
+     * Get a specific flag for the user/company/other context bound to this client.
+     * Using the `isEnabled` property sends a `check` event to Reflag.
+     *
+     * @param key - The key of the flag to get.
+     *
+     * @returns Flags for the given user/company and whether each one is enabled or not
+     */
+    getFlag(key) {
+        return this._client.getFlag(this._options, key);
+    }
+    /**
+     * Get remotely evaluated flag for the user/company/other context bound to this client.
+     *
+     * @returns Flags for the given user/company and whether each one is enabled or not
+     */
+    getFlagsRemote() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const _a = this._options, { enableTracking: _, meta: __ } = _a, context = __rest(_a, ["enableTracking", "meta"]);
+            return yield this._client.getFlagsRemote(undefined, undefined, context);
+        });
+    }
+    /**
+     * Get remotely evaluated flag for the user/company/other context bound to this client.
+     *
+     * @param key - The key of the flag to get.
+     *
+     * @returns Flag for the given user/company and key and whether it's enabled or not
+     */
+    getFlagRemote(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const _a = this._options, { enableTracking: _, meta: __ } = _a, context = __rest(_a, ["enableTracking", "meta"]);
+            return yield this._client.getFlagRemote(key, undefined, undefined, context);
+        });
+    }
+    /**
+     * Track an event in Reflag.
+     *
+     * @param event - The event to track.
+     * @param options - The options for the event.
+     * @param options.attributes - The attributes of the event (optional).
+     * @param options.meta - The meta context associated with tracking (optional).
+     * @param options.companyId - Optional company ID for the event (optional).
+     *
+     * @throws An error if the event is invalid or the options are invalid.
+     */
+    track(event, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            (0, utils_1.ok)(options === undefined || (0, utils_1.isObject)(options), "options must be an object");
+            checkMeta(options === null || options === void 0 ? void 0 : options.meta);
+            const userId = (_a = this._options.user) === null || _a === void 0 ? void 0 : _a.id;
+            if (!userId) {
+                (_b = this._client.logger) === null || _b === void 0 ? void 0 : _b.warn("no user set, cannot track event");
+                return;
+            }
+            if (!this._options.enableTracking) {
+                (_c = this._client.logger) === null || _c === void 0 ? void 0 : _c.debug("tracking disabled for this bound client, not tracking event");
+                return;
+            }
+            yield this._client.track(userId, event, (options === null || options === void 0 ? void 0 : options.companyId)
+                ? options
+                : Object.assign(Object.assign({}, options), { companyId: (_d = this._options.company) === null || _d === void 0 ? void 0 : _d.id }));
+        });
+    }
+    /**
+     * Create a new client bound with the additional context.
+     * Note: This performs a shallow merge for user/company/other individually.
+     *
+     * @param context - The context to bind the client to.
+     * @param context.user - The user to bind the client to.
+     * @param context.company - The company to bind the client to.
+     * @param context.other - The other context to bind the client to.
+     * @param context.enableTracking - Whether to enable tracking for the client.
+     * @param context.meta - The meta context to bind the client to.
+     *
+     * @returns new client bound with the additional context
+     */
+    bindClient({ user, company, other, enableTracking, meta, }) {
+        // merge new context into existing
+        const boundConfig = Object.assign(Object.assign({}, this._options), { user: user ? Object.assign(Object.assign({}, this._options.user), user) : undefined, company: company ? Object.assign(Object.assign({}, this._options.company), company) : undefined, other: Object.assign(Object.assign({}, this._options.other), other), enableTracking: enableTracking !== null && enableTracking !== void 0 ? enableTracking : this._options.enableTracking, meta: meta !== null && meta !== void 0 ? meta : this._options.meta });
+        return new BoundReflagClient(this._client, boundConfig);
+    }
+    /**
+     * Flushes the batch buffer.
+     */
+    flush() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._client.flush();
+        });
+    }
+}
+exports.BoundReflagClient = BoundReflagClient;
+function checkMeta(meta) {
+    (0, utils_1.ok)(typeof meta === "undefined" || (0, utils_1.isObject)(meta), "meta must be an object if given");
+    (0, utils_1.ok)((meta === null || meta === void 0 ? void 0 : meta.active) === undefined || typeof (meta === null || meta === void 0 ? void 0 : meta.active) === "boolean", "meta.active must be a boolean if given");
+}
+function checkContextWithTracking(context) {
+    var _a, _b;
+    (0, utils_1.ok)((0, utils_1.isObject)(context), "context must be an object");
+    (0, utils_1.ok)(typeof context.user === "undefined" || (0, utils_1.isObject)(context.user), "user must be an object if given");
+    if (typeof ((_a = context.user) === null || _a === void 0 ? void 0 : _a.id) !== "undefined") {
+        (0, utils_1.idOk)(context.user.id, "user.id");
+    }
+    (0, utils_1.ok)(typeof context.company === "undefined" || (0, utils_1.isObject)(context.company), "company must be an object if given");
+    if (typeof ((_b = context.company) === null || _b === void 0 ? void 0 : _b.id) !== "undefined") {
+        (0, utils_1.idOk)(context.company.id, "company.id");
+    }
+    (0, utils_1.ok)(context.other === undefined || (0, utils_1.isObject)(context.other), "other must be an object if given");
+    (0, utils_1.ok)(typeof context.enableTracking === "boolean", "enableTracking must be a boolean");
+    checkMeta(context.meta);
+}
+//# sourceMappingURL=client.js.map