@splitsoftware/splitio-commons 2.7.1 → 2.7.9-rc.0

package/CHANGES.txt

@@ -1,8 +1,8 @@
-2.7.1 (October 8, 2025)
- - Bugfix - Update `debug` option to support log levels when `logger` option is used.
+2.8.0 (October XX, 2025)
+  - Added new configuration for Fallback Treatments, which allows setting a treatment value and optional config to be returned in place of "control", either globally or by flag. Read more in our docs.
 
 2.7.0 (October 7, 2025)
- - Added support for custom loggers: added `logger` configuration option and `factory.Logger.setLogger` method to allow the SDK to use a custom logger.
+ - Added support for custom loggers: added `logger` configuration option and `LoggerAPI.setLogger` method to allow the SDK to use a custom logger.
 
 2.6.0 (September 18, 2025)
  - Added `storage.wrapper` configuration option to allow the SDK to use a custom storage wrapper for the storage type `LOCALSTORAGE`. Default value is `window.localStorage`.

package/cjs/evaluator/fallbackTreatmentsCalculator/constants.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbackDiscardReason = void 0;
+var FallbackDiscardReason;
+(function (FallbackDiscardReason) {
+    FallbackDiscardReason["FlagName"] = "Invalid flag name (max 100 chars, no spaces)";
+    FallbackDiscardReason["Treatment"] = "Invalid treatment (max 100 chars and must match pattern)";
+})(FallbackDiscardReason = exports.FallbackDiscardReason || (exports.FallbackDiscardReason = {}));

package/cjs/evaluator/fallbackTreatmentsCalculator/fallbackSanitizer/index.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbacksSanitizer = void 0;
+var lang_1 = require("../../../utils/lang");
+var constants_1 = require("../constants");
+var FallbacksSanitizer = /** @class */ (function () {
+    function FallbacksSanitizer() {
+    }
+    FallbacksSanitizer.isValidFlagName = function (name) {
+        return name.length <= 100 && !name.includes(' ');
+    };
+    FallbacksSanitizer.isValidTreatment = function (t) {
+        var treatment = (0, lang_1.isObject)(t) ? t.treatment : t;
+        if (!(0, lang_1.isString)(treatment) || treatment.length > 100) {
+            return false;
+        }
+        return FallbacksSanitizer.pattern.test(treatment);
+    };
+    FallbacksSanitizer.sanitizeGlobal = function (logger, treatment) {
+        if (!this.isValidTreatment(treatment)) {
+            logger.error("Fallback treatments - Discarded fallback: " + constants_1.FallbackDiscardReason.Treatment);
+            return undefined;
+        }
+        return treatment;
+    };
+    FallbacksSanitizer.sanitizeByFlag = function (logger, byFlagFallbacks) {
+        var _this = this;
+        var sanitizedByFlag = {};
+        var entries = Object.keys(byFlagFallbacks);
+        entries.forEach(function (flag) {
+            var t = byFlagFallbacks[flag];
+            if (!_this.isValidFlagName(flag)) {
+                logger.error("Fallback treatments - Discarded flag '" + flag + "': " + constants_1.FallbackDiscardReason.FlagName);
+                return;
+            }
+            if (!_this.isValidTreatment(t)) {
+                logger.error("Fallback treatments - Discarded treatment for flag '" + flag + "': " + constants_1.FallbackDiscardReason.Treatment);
+                return;
+            }
+            sanitizedByFlag[flag] = t;
+        });
+        return sanitizedByFlag;
+    };
+    FallbacksSanitizer.pattern = /^[0-9]+[.a-zA-Z0-9_-]*$|^[a-zA-Z]+[a-zA-Z0-9_-]*$/;
+    return FallbacksSanitizer;
+}());
+exports.FallbacksSanitizer = FallbacksSanitizer;

package/cjs/evaluator/fallbackTreatmentsCalculator/index.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbackTreatmentsCalculator = exports.FALLBACK_PREFIX = void 0;
+var fallbackSanitizer_1 = require("./fallbackSanitizer");
+var constants_1 = require("../../utils/constants");
+var lang_1 = require("../../utils/lang");
+exports.FALLBACK_PREFIX = 'fallback - ';
+var FallbackTreatmentsCalculator = /** @class */ (function () {
+    function FallbackTreatmentsCalculator(logger, fallbacks) {
+        var sanitizedGlobal = (fallbacks === null || fallbacks === void 0 ? void 0 : fallbacks.global) ? fallbackSanitizer_1.FallbacksSanitizer.sanitizeGlobal(logger, fallbacks.global) : undefined;
+        var sanitizedByFlag = (fallbacks === null || fallbacks === void 0 ? void 0 : fallbacks.byFlag) ? fallbackSanitizer_1.FallbacksSanitizer.sanitizeByFlag(logger, fallbacks.byFlag) : {};
+        this.fallbacks = {
+            global: sanitizedGlobal,
+            byFlag: sanitizedByFlag
+        };
+    }
+    FallbackTreatmentsCalculator.prototype.resolve = function (flagName, label) {
+        var _a;
+        var treatment = (_a = this.fallbacks.byFlag) === null || _a === void 0 ? void 0 : _a[flagName];
+        if (treatment) {
+            return this.copyWithLabel(treatment, label);
+        }
+        if (this.fallbacks.global) {
+            return this.copyWithLabel(this.fallbacks.global, label);
+        }
+        return {
+            treatment: constants_1.CONTROL,
+            config: null,
+            label: label,
+        };
+    };
+    FallbackTreatmentsCalculator.prototype.copyWithLabel = function (fallback, label) {
+        if ((0, lang_1.isString)(fallback)) {
+            return {
+                treatment: fallback,
+                config: null,
+                label: "" + exports.FALLBACK_PREFIX + label,
+            };
+        }
+        return {
+            treatment: fallback.treatment,
+            config: fallback.config,
+            label: "" + exports.FALLBACK_PREFIX + label,
+        };
+    };
+    return FallbackTreatmentsCalculator;
+}());
+exports.FallbackTreatmentsCalculator = FallbackTreatmentsCalculator;

package/cjs/logger/index.js

@@ -63,6 +63,9 @@ var Logger = /** @class */ (function () {
         if (logger) {
             if ((0, commons_1.isLogger)(logger)) {
                 this.logger = logger;
+                // If custom logger is set, all logs are either enabled or disabled
+                if (this.logLevel !== LogLevelIndexes.NONE)
+                    this.setLogLevel(exports.LogLevels.DEBUG);
                 return;
             }
             else {

package/cjs/sdkClient/client.js

@@ -30,7 +30,7 @@ function stringify(options) {
  * Creator of base client with getTreatments and track methods.
  */
 function clientFactory(params) {
-    var readinessManager = params.sdkReadinessManager.readinessManager, storage = params.storage, settings = params.settings, impressionsTracker = params.impressionsTracker, eventTracker = params.eventTracker, telemetryTracker = params.telemetryTracker;
+    var readinessManager = params.sdkReadinessManager.readinessManager, storage = params.storage, settings = params.settings, impressionsTracker = params.impressionsTracker, eventTracker = params.eventTracker, telemetryTracker = params.telemetryTracker, fallbackTreatmentsCalculator = params.fallbackTreatmentsCalculator;
     var log = settings.log, mode = settings.mode;
     var isAsync = (0, mode_1.isConsumerMode)(mode);
     function getTreatment(key, featureFlagName, attributes, options, withConfig, methodName) {
@@ -115,7 +115,14 @@ function clientFactory(params) {
     function processEvaluation(evaluation, featureFlagName, key, properties, withConfig, invokingMethodName, queue) {
         var matchingKey = (0, key_1.getMatching)(key);
         var bucketingKey = (0, key_1.getBucketing)(key);
-        var treatment = evaluation.treatment, label = evaluation.label, changeNumber = evaluation.changeNumber, _a = evaluation.config, config = _a === void 0 ? null : _a, impressionsDisabled = evaluation.impressionsDisabled;
+        var changeNumber = evaluation.changeNumber, impressionsDisabled = evaluation.impressionsDisabled;
+        var treatment = evaluation.treatment, label = evaluation.label, _a = evaluation.config, config = _a === void 0 ? null : _a;
+        if (treatment === constants_1.CONTROL) {
+            var fallbackTreatment = fallbackTreatmentsCalculator.resolve(featureFlagName, label);
+            treatment = fallbackTreatment.treatment;
+            label = fallbackTreatment.label ? fallbackTreatment.label : label;
+            config = fallbackTreatment.config;
+        }
         log.info(constants_2.IMPRESSION, [featureFlagName, matchingKey, treatment, label]);
         if ((0, splitExistence_1.validateSplitExistence)(log, readinessManager, featureFlagName, label, invokingMethodName)) {
             log.info(constants_2.IMPRESSION_QUEUEING);

package/cjs/sdkClient/clientInputValidation.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clientInputValidationDecorator = void 0;
-var objectAssign_1 = require("../utils/lang/objectAssign");
 var inputValidation_1 = require("../utils/inputValidation");
 var lang_1 = require("../utils/lang");
 var constants_1 = require("../utils/constants");
@@ -11,7 +10,7 @@ var splitFilters_1 = require("../utils/settingsValidation/splitFilters");
  * Decorator that validates the input before actually executing the client methods.
  * We should "guard" the client here, while not polluting the "real" implementation of those methods.
  */
-function clientInputValidationDecorator(settings, client, readinessManager) {
+function clientInputValidationDecorator(settings, client, readinessManager, fallbackTreatmentsCalculator) {
     var log = settings.log, mode = settings.mode;
     var isAsync = (0, mode_1.isConsumerMode)(mode);
     /**
@@ -37,6 +36,16 @@ function clientInputValidationDecorator(settings, client, readinessManager) {
             options: options
         };
     }
+    function evaluateFallBackTreatment(featureFlagName, withConfig) {
+        var _a = fallbackTreatmentsCalculator.resolve(featureFlagName, ''), treatment = _a.treatment, config = _a.config;
+        if (withConfig) {
+            return {
+                treatment: treatment,
+                config: config
+            };
+        }
+        return treatment;
+    }
     function wrapResult(value) {
         return isAsync ? Promise.resolve(value) : value;
     }
@@ -46,7 +55,8 @@ function clientInputValidationDecorator(settings, client, readinessManager) {
             return client.getTreatment(params.key, params.nameOrNames, params.attributes, params.options);
         }
         else {
-            return wrapResult(constants_1.CONTROL);
+            var result = evaluateFallBackTreatment(params.nameOrNames, false);
+            return wrapResult(result);
         }
     }
     function getTreatmentWithConfig(maybeKey, maybeFeatureFlagName, maybeAttributes, maybeOptions) {
@@ -55,7 +65,8 @@ function clientInputValidationDecorator(settings, client, readinessManager) {
             return client.getTreatmentWithConfig(params.key, params.nameOrNames, params.attributes, params.options);
         }
         else {
-            return wrapResult((0, objectAssign_1.objectAssign)({}, constants_1.CONTROL_WITH_CONFIG));
+            var result = evaluateFallBackTreatment(params.nameOrNames, true);
+            return wrapResult(result);
         }
     }
     function getTreatments(maybeKey, maybeFeatureFlagNames, maybeAttributes, maybeOptions) {
@@ -66,7 +77,7 @@ function clientInputValidationDecorator(settings, client, readinessManager) {
         else {
             var res_1 = {};
             if (params.nameOrNames)
-                params.nameOrNames.forEach(function (split) { return res_1[split] = constants_1.CONTROL; });
+                params.nameOrNames.forEach(function (split) { return res_1[split] = evaluateFallBackTreatment(split, false); });
             return wrapResult(res_1);
         }
     }
@@ -78,7 +89,7 @@ function clientInputValidationDecorator(settings, client, readinessManager) {
         else {
             var res_2 = {};
             if (params.nameOrNames)
-                params.nameOrNames.forEach(function (split) { return res_2[split] = (0, objectAssign_1.objectAssign)({}, constants_1.CONTROL_WITH_CONFIG); });
+                params.nameOrNames.forEach(function (split) { return res_2[split] = evaluateFallBackTreatment(split, true); });
             return wrapResult(res_2);
         }
     }

package/cjs/sdkClient/sdkClient.js

@@ -35,7 +35,7 @@ function sdkClientFactory(params, isSharedClient) {
     // Proto-linkage of the readiness Event Emitter
     Object.create(sdkReadinessManager.sdkStatus), 
     // Client API (getTreatment* & track methods)
-    (0, clientInputValidation_1.clientInputValidationDecorator)(settings, (0, client_1.clientFactory)(params), sdkReadinessManager.readinessManager), 
+    (0, clientInputValidation_1.clientInputValidationDecorator)(settings, (0, client_1.clientFactory)(params), sdkReadinessManager.readinessManager, params.fallbackTreatmentsCalculator), 
     // Sdk destroy
     {
         flush: function () {

package/cjs/sdkFactory/index.js

@@ -17,6 +17,7 @@ var uniqueKeysTracker_1 = require("../trackers/uniqueKeysTracker");
 var constants_3 = require("../utils/constants");
 var setRolloutPlan_1 = require("../storages/setRolloutPlan");
 var key_1 = require("../utils/key");
+var fallbackTreatmentsCalculator_1 = require("../evaluator/fallbackTreatmentsCalculator");
 /**
  * Modular SDK factory
  */
@@ -51,6 +52,7 @@ function sdkFactory(params) {
             readiness.splits.emit(constants_2.SDK_SPLITS_CACHE_LOADED);
         }
     });
+    var fallbackTreatmentsCalculator = new fallbackTreatmentsCalculator_1.FallbackTreatmentsCalculator(settings.log, settings.fallbackTreatments);
     if (initialRolloutPlan) {
         (0, setRolloutPlan_1.setRolloutPlan)(log, initialRolloutPlan, storage, key && (0, key_1.getMatching)(key));
         if (storage.splits.getChangeNumber() > -1)
@@ -71,7 +73,7 @@ function sdkFactory(params) {
     var eventTracker = (0, eventTracker_1.eventTrackerFactory)(settings, storage.events, whenInit, integrationsManager, storage.telemetry);
     // splitApi is used by SyncManager and Browser signal listener
     var splitApi = splitApiFactory && splitApiFactory(settings, platform, telemetryTracker);
-    var ctx = { clients: clients, splitApi: splitApi, eventTracker: eventTracker, impressionsTracker: impressionsTracker, telemetryTracker: telemetryTracker, uniqueKeysTracker: uniqueKeysTracker, sdkReadinessManager: sdkReadinessManager, readiness: readiness, settings: settings, storage: storage, platform: platform };
+    var ctx = { clients: clients, splitApi: splitApi, eventTracker: eventTracker, impressionsTracker: impressionsTracker, telemetryTracker: telemetryTracker, uniqueKeysTracker: uniqueKeysTracker, sdkReadinessManager: sdkReadinessManager, readiness: readiness, settings: settings, storage: storage, platform: platform, fallbackTreatmentsCalculator: fallbackTreatmentsCalculator };
     var syncManager = syncManagerFactory && syncManagerFactory(ctx);
     ctx.syncManager = syncManager;
     var signalListener = SignalListener && new SignalListener(syncManager, settings, storage, splitApi);

package/cjs/utils/inputValidation/splitExistence.js

@@ -9,7 +9,7 @@ var constants_1 = require("../../logger/constants");
  */
 function validateSplitExistence(log, readinessManager, splitName, labelOrSplitObj, method) {
     if (readinessManager.isReady()) { // Only if it's ready we validate this, otherwise it may just be that the SDK is not ready yet.
-        if (labelOrSplitObj === labels_1.SPLIT_NOT_FOUND || labelOrSplitObj == null) {
+        if (labelOrSplitObj === labels_1.SPLIT_NOT_FOUND || labelOrSplitObj == null || labelOrSplitObj === labels_1.FALLBACK_SPLIT_NOT_FOUND) {
             log.warn(constants_1.WARN_NOT_EXISTENT_SPLIT, [method, splitName]);
             return false;
         }

package/cjs/utils/labels/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREREQUISITES_NOT_MET = exports.UNSUPPORTED_MATCHER_TYPE = exports.NOT_IN_SPLIT = exports.SPLIT_ARCHIVED = exports.EXCEPTION = exports.SDK_NOT_READY = exports.SPLIT_NOT_FOUND = exports.NO_CONDITION_MATCH = exports.SPLIT_KILLED = void 0;
+exports.FALLBACK_SPLIT_NOT_FOUND = exports.PREREQUISITES_NOT_MET = exports.UNSUPPORTED_MATCHER_TYPE = exports.NOT_IN_SPLIT = exports.SPLIT_ARCHIVED = exports.EXCEPTION = exports.SDK_NOT_READY = exports.SPLIT_NOT_FOUND = exports.NO_CONDITION_MATCH = exports.SPLIT_KILLED = void 0;
+var fallbackTreatmentsCalculator_1 = require("../../evaluator/fallbackTreatmentsCalculator");
 exports.SPLIT_KILLED = 'killed';
 exports.NO_CONDITION_MATCH = 'default rule';
 exports.SPLIT_NOT_FOUND = 'definition not found';
@@ -10,3 +11,4 @@ exports.SPLIT_ARCHIVED = 'archived';
 exports.NOT_IN_SPLIT = 'not in split';
 exports.UNSUPPORTED_MATCHER_TYPE = 'targeting rule type unsupported by sdk';
 exports.PREREQUISITES_NOT_MET = 'prerequisites not met';
+exports.FALLBACK_SPLIT_NOT_FOUND = fallbackTreatmentsCalculator_1.FALLBACK_PREFIX + exports.SPLIT_NOT_FOUND;

package/esm/evaluator/fallbackTreatmentsCalculator/constants.js

@@ -0,0 +1,5 @@
+export var FallbackDiscardReason;
+(function (FallbackDiscardReason) {
+    FallbackDiscardReason["FlagName"] = "Invalid flag name (max 100 chars, no spaces)";
+    FallbackDiscardReason["Treatment"] = "Invalid treatment (max 100 chars and must match pattern)";
+})(FallbackDiscardReason || (FallbackDiscardReason = {}));

package/esm/evaluator/fallbackTreatmentsCalculator/fallbackSanitizer/index.js

@@ -0,0 +1,44 @@
+import { isObject, isString } from '../../../utils/lang';
+import { FallbackDiscardReason } from '../constants';
+var FallbacksSanitizer = /** @class */ (function () {
+    function FallbacksSanitizer() {
+    }
+    FallbacksSanitizer.isValidFlagName = function (name) {
+        return name.length <= 100 && !name.includes(' ');
+    };
+    FallbacksSanitizer.isValidTreatment = function (t) {
+        var treatment = isObject(t) ? t.treatment : t;
+        if (!isString(treatment) || treatment.length > 100) {
+            return false;
+        }
+        return FallbacksSanitizer.pattern.test(treatment);
+    };
+    FallbacksSanitizer.sanitizeGlobal = function (logger, treatment) {
+        if (!this.isValidTreatment(treatment)) {
+            logger.error("Fallback treatments - Discarded fallback: " + FallbackDiscardReason.Treatment);
+            return undefined;
+        }
+        return treatment;
+    };
+    FallbacksSanitizer.sanitizeByFlag = function (logger, byFlagFallbacks) {
+        var _this = this;
+        var sanitizedByFlag = {};
+        var entries = Object.keys(byFlagFallbacks);
+        entries.forEach(function (flag) {
+            var t = byFlagFallbacks[flag];
+            if (!_this.isValidFlagName(flag)) {
+                logger.error("Fallback treatments - Discarded flag '" + flag + "': " + FallbackDiscardReason.FlagName);
+                return;
+            }
+            if (!_this.isValidTreatment(t)) {
+                logger.error("Fallback treatments - Discarded treatment for flag '" + flag + "': " + FallbackDiscardReason.Treatment);
+                return;
+            }
+            sanitizedByFlag[flag] = t;
+        });
+        return sanitizedByFlag;
+    };
+    FallbacksSanitizer.pattern = /^[0-9]+[.a-zA-Z0-9_-]*$|^[a-zA-Z]+[a-zA-Z0-9_-]*$/;
+    return FallbacksSanitizer;
+}());
+export { FallbacksSanitizer };

package/esm/evaluator/fallbackTreatmentsCalculator/index.js

@@ -0,0 +1,45 @@
+import { FallbacksSanitizer } from './fallbackSanitizer';
+import { CONTROL } from '../../utils/constants';
+import { isString } from '../../utils/lang';
+export var FALLBACK_PREFIX = 'fallback - ';
+var FallbackTreatmentsCalculator = /** @class */ (function () {
+    function FallbackTreatmentsCalculator(logger, fallbacks) {
+        var sanitizedGlobal = (fallbacks === null || fallbacks === void 0 ? void 0 : fallbacks.global) ? FallbacksSanitizer.sanitizeGlobal(logger, fallbacks.global) : undefined;
+        var sanitizedByFlag = (fallbacks === null || fallbacks === void 0 ? void 0 : fallbacks.byFlag) ? FallbacksSanitizer.sanitizeByFlag(logger, fallbacks.byFlag) : {};
+        this.fallbacks = {
+            global: sanitizedGlobal,
+            byFlag: sanitizedByFlag
+        };
+    }
+    FallbackTreatmentsCalculator.prototype.resolve = function (flagName, label) {
+        var _a;
+        var treatment = (_a = this.fallbacks.byFlag) === null || _a === void 0 ? void 0 : _a[flagName];
+        if (treatment) {
+            return this.copyWithLabel(treatment, label);
+        }
+        if (this.fallbacks.global) {
+            return this.copyWithLabel(this.fallbacks.global, label);
+        }
+        return {
+            treatment: CONTROL,
+            config: null,
+            label: label,
+        };
+    };
+    FallbackTreatmentsCalculator.prototype.copyWithLabel = function (fallback, label) {
+        if (isString(fallback)) {
+            return {
+                treatment: fallback,
+                config: null,
+                label: "" + FALLBACK_PREFIX + label,
+            };
+        }
+        return {
+            treatment: fallback.treatment,
+            config: fallback.config,
+            label: "" + FALLBACK_PREFIX + label,
+        };
+    };
+    return FallbackTreatmentsCalculator;
+}());
+export { FallbackTreatmentsCalculator };

package/esm/logger/index.js

@@ -58,6 +58,9 @@ var Logger = /** @class */ (function () {
         if (logger) {
             if (isLogger(logger)) {
                 this.logger = logger;
+                // If custom logger is set, all logs are either enabled or disabled
+                if (this.logLevel !== LogLevelIndexes.NONE)
+                    this.setLogLevel(LogLevels.DEBUG);
                 return;
             }
             else {

package/esm/sdkClient/client.js

@@ -27,7 +27,7 @@ function stringify(options) {
  * Creator of base client with getTreatments and track methods.
  */
 export function clientFactory(params) {
-    var readinessManager = params.sdkReadinessManager.readinessManager, storage = params.storage, settings = params.settings, impressionsTracker = params.impressionsTracker, eventTracker = params.eventTracker, telemetryTracker = params.telemetryTracker;
+    var readinessManager = params.sdkReadinessManager.readinessManager, storage = params.storage, settings = params.settings, impressionsTracker = params.impressionsTracker, eventTracker = params.eventTracker, telemetryTracker = params.telemetryTracker, fallbackTreatmentsCalculator = params.fallbackTreatmentsCalculator;
     var log = settings.log, mode = settings.mode;
     var isAsync = isConsumerMode(mode);
     function getTreatment(key, featureFlagName, attributes, options, withConfig, methodName) {
@@ -112,7 +112,14 @@ export function clientFactory(params) {
     function processEvaluation(evaluation, featureFlagName, key, properties, withConfig, invokingMethodName, queue) {
         var matchingKey = getMatching(key);
         var bucketingKey = getBucketing(key);
-        var treatment = evaluation.treatment, label = evaluation.label, changeNumber = evaluation.changeNumber, _a = evaluation.config, config = _a === void 0 ? null : _a, impressionsDisabled = evaluation.impressionsDisabled;
+        var changeNumber = evaluation.changeNumber, impressionsDisabled = evaluation.impressionsDisabled;
+        var treatment = evaluation.treatment, label = evaluation.label, _a = evaluation.config, config = _a === void 0 ? null : _a;
+        if (treatment === CONTROL) {
+            var fallbackTreatment = fallbackTreatmentsCalculator.resolve(featureFlagName, label);
+            treatment = fallbackTreatment.treatment;
+            label = fallbackTreatment.label ? fallbackTreatment.label : label;
+            config = fallbackTreatment.config;
+        }
         log.info(IMPRESSION, [featureFlagName, matchingKey, treatment, label]);
         if (validateSplitExistence(log, readinessManager, featureFlagName, label, invokingMethodName)) {
             log.info(IMPRESSION_QUEUEING);

package/esm/sdkClient/clientInputValidation.js

@@ -1,14 +1,13 @@
-import { objectAssign } from '../utils/lang/objectAssign';
 import { validateAttributes, validateEvent, validateEventValue, validateEventProperties, validateKey, validateSplit, validateSplits, validateTrafficType, validateIfNotDestroyed, validateIfOperational, validateEvaluationOptions } from '../utils/inputValidation';
 import { startsWith } from '../utils/lang';
-import { CONTROL, CONTROL_WITH_CONFIG, GET_TREATMENT, GET_TREATMENTS, GET_TREATMENTS_BY_FLAG_SET, GET_TREATMENTS_BY_FLAG_SETS, GET_TREATMENTS_WITH_CONFIG, GET_TREATMENTS_WITH_CONFIG_BY_FLAG_SET, GET_TREATMENTS_WITH_CONFIG_BY_FLAG_SETS, GET_TREATMENT_WITH_CONFIG, TRACK_FN_LABEL } from '../utils/constants';
+import { GET_TREATMENT, GET_TREATMENTS, GET_TREATMENTS_BY_FLAG_SET, GET_TREATMENTS_BY_FLAG_SETS, GET_TREATMENTS_WITH_CONFIG, GET_TREATMENTS_WITH_CONFIG_BY_FLAG_SET, GET_TREATMENTS_WITH_CONFIG_BY_FLAG_SETS, GET_TREATMENT_WITH_CONFIG, TRACK_FN_LABEL } from '../utils/constants';
 import { isConsumerMode } from '../utils/settingsValidation/mode';
 import { validateFlagSets } from '../utils/settingsValidation/splitFilters';
 /**
  * Decorator that validates the input before actually executing the client methods.
  * We should "guard" the client here, while not polluting the "real" implementation of those methods.
  */
-export function clientInputValidationDecorator(settings, client, readinessManager) {
+export function clientInputValidationDecorator(settings, client, readinessManager, fallbackTreatmentsCalculator) {
     var log = settings.log, mode = settings.mode;
     var isAsync = isConsumerMode(mode);
     /**
@@ -34,6 +33,16 @@ export function clientInputValidationDecorator(settings, client, readinessManage
             options: options
         };
     }
+    function evaluateFallBackTreatment(featureFlagName, withConfig) {
+        var _a = fallbackTreatmentsCalculator.resolve(featureFlagName, ''), treatment = _a.treatment, config = _a.config;
+        if (withConfig) {
+            return {
+                treatment: treatment,
+                config: config
+            };
+        }
+        return treatment;
+    }
     function wrapResult(value) {
         return isAsync ? Promise.resolve(value) : value;
     }
@@ -43,7 +52,8 @@ export function clientInputValidationDecorator(settings, client, readinessManage
             return client.getTreatment(params.key, params.nameOrNames, params.attributes, params.options);
         }
         else {
-            return wrapResult(CONTROL);
+            var result = evaluateFallBackTreatment(params.nameOrNames, false);
+            return wrapResult(result);
         }
     }
     function getTreatmentWithConfig(maybeKey, maybeFeatureFlagName, maybeAttributes, maybeOptions) {
@@ -52,7 +62,8 @@ export function clientInputValidationDecorator(settings, client, readinessManage
             return client.getTreatmentWithConfig(params.key, params.nameOrNames, params.attributes, params.options);
         }
         else {
-            return wrapResult(objectAssign({}, CONTROL_WITH_CONFIG));
+            var result = evaluateFallBackTreatment(params.nameOrNames, true);
+            return wrapResult(result);
         }
     }
     function getTreatments(maybeKey, maybeFeatureFlagNames, maybeAttributes, maybeOptions) {
@@ -63,7 +74,7 @@ export function clientInputValidationDecorator(settings, client, readinessManage
         else {
             var res_1 = {};
             if (params.nameOrNames)
-                params.nameOrNames.forEach(function (split) { return res_1[split] = CONTROL; });
+                params.nameOrNames.forEach(function (split) { return res_1[split] = evaluateFallBackTreatment(split, false); });
             return wrapResult(res_1);
         }
     }
@@ -75,7 +86,7 @@ export function clientInputValidationDecorator(settings, client, readinessManage
         else {
             var res_2 = {};
             if (params.nameOrNames)
-                params.nameOrNames.forEach(function (split) { return res_2[split] = objectAssign({}, CONTROL_WITH_CONFIG); });
+                params.nameOrNames.forEach(function (split) { return res_2[split] = evaluateFallBackTreatment(split, true); });
             return wrapResult(res_2);
         }
     }

package/esm/sdkClient/sdkClient.js

@@ -32,7 +32,7 @@ export function sdkClientFactory(params, isSharedClient) {
     // Proto-linkage of the readiness Event Emitter
     Object.create(sdkReadinessManager.sdkStatus), 
     // Client API (getTreatment* & track methods)
-    clientInputValidationDecorator(settings, clientFactory(params), sdkReadinessManager.readinessManager), 
+    clientInputValidationDecorator(settings, clientFactory(params), sdkReadinessManager.readinessManager, params.fallbackTreatmentsCalculator), 
     // Sdk destroy
     {
         flush: function () {

package/esm/sdkFactory/index.js

@@ -14,6 +14,7 @@ import { uniqueKeysTrackerFactory } from '../trackers/uniqueKeysTracker';
 import { DEBUG, OPTIMIZED } from '../utils/constants';
 import { setRolloutPlan } from '../storages/setRolloutPlan';
 import { getMatching } from '../utils/key';
+import { FallbackTreatmentsCalculator } from '../evaluator/fallbackTreatmentsCalculator';
 /**
  * Modular SDK factory
  */
@@ -48,6 +49,7 @@ export function sdkFactory(params) {
             readiness.splits.emit(SDK_SPLITS_CACHE_LOADED);
         }
     });
+    var fallbackTreatmentsCalculator = new FallbackTreatmentsCalculator(settings.log, settings.fallbackTreatments);
     if (initialRolloutPlan) {
         setRolloutPlan(log, initialRolloutPlan, storage, key && getMatching(key));
         if (storage.splits.getChangeNumber() > -1)
@@ -68,7 +70,7 @@ export function sdkFactory(params) {
     var eventTracker = eventTrackerFactory(settings, storage.events, whenInit, integrationsManager, storage.telemetry);
     // splitApi is used by SyncManager and Browser signal listener
     var splitApi = splitApiFactory && splitApiFactory(settings, platform, telemetryTracker);
-    var ctx = { clients: clients, splitApi: splitApi, eventTracker: eventTracker, impressionsTracker: impressionsTracker, telemetryTracker: telemetryTracker, uniqueKeysTracker: uniqueKeysTracker, sdkReadinessManager: sdkReadinessManager, readiness: readiness, settings: settings, storage: storage, platform: platform };
+    var ctx = { clients: clients, splitApi: splitApi, eventTracker: eventTracker, impressionsTracker: impressionsTracker, telemetryTracker: telemetryTracker, uniqueKeysTracker: uniqueKeysTracker, sdkReadinessManager: sdkReadinessManager, readiness: readiness, settings: settings, storage: storage, platform: platform, fallbackTreatmentsCalculator: fallbackTreatmentsCalculator };
     var syncManager = syncManagerFactory && syncManagerFactory(ctx);
     ctx.syncManager = syncManager;
     var signalListener = SignalListener && new SignalListener(syncManager, settings, storage, splitApi);

package/esm/utils/inputValidation/splitExistence.js

@@ -1,4 +1,4 @@
-import { SPLIT_NOT_FOUND } from '../labels';
+import { FALLBACK_SPLIT_NOT_FOUND, SPLIT_NOT_FOUND } from '../labels';
 import { WARN_NOT_EXISTENT_SPLIT } from '../../logger/constants';
 /**
  * This is defined here and in this format mostly because of the logger and the fact that it's considered a validation at product level.
@@ -6,7 +6,7 @@ import { WARN_NOT_EXISTENT_SPLIT } from '../../logger/constants';
  */
 export function validateSplitExistence(log, readinessManager, splitName, labelOrSplitObj, method) {
     if (readinessManager.isReady()) { // Only if it's ready we validate this, otherwise it may just be that the SDK is not ready yet.
-        if (labelOrSplitObj === SPLIT_NOT_FOUND || labelOrSplitObj == null) {
+        if (labelOrSplitObj === SPLIT_NOT_FOUND || labelOrSplitObj == null || labelOrSplitObj === FALLBACK_SPLIT_NOT_FOUND) {
             log.warn(WARN_NOT_EXISTENT_SPLIT, [method, splitName]);
             return false;
         }

package/esm/utils/labels/index.js

@@ -1,3 +1,4 @@
+import { FALLBACK_PREFIX } from '../../evaluator/fallbackTreatmentsCalculator';
 export var SPLIT_KILLED = 'killed';
 export var NO_CONDITION_MATCH = 'default rule';
 export var SPLIT_NOT_FOUND = 'definition not found';
@@ -7,3 +8,4 @@ export var SPLIT_ARCHIVED = 'archived';
 export var NOT_IN_SPLIT = 'not in split';
 export var UNSUPPORTED_MATCHER_TYPE = 'targeting rule type unsupported by sdk';
 export var PREREQUISITES_NOT_MET = 'prerequisites not met';
+export var FALLBACK_SPLIT_NOT_FOUND = FALLBACK_PREFIX + SPLIT_NOT_FOUND;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splitsoftware/splitio-commons",
-  "version": "2.7.1",
+  "version": "2.7.9-rc.0",
   "description": "Split JavaScript SDK common components",
   "main": "cjs/index.js",
   "module": "esm/index.js",

package/src/evaluator/fallbackTreatmentsCalculator/constants.ts

@@ -0,0 +1,4 @@
+export enum FallbackDiscardReason {
+  FlagName = 'Invalid flag name (max 100 chars, no spaces)',
+  Treatment = 'Invalid treatment (max 100 chars and must match pattern)',
+}

package/src/evaluator/fallbackTreatmentsCalculator/fallbackSanitizer/index.ts

@@ -0,0 +1,62 @@
+import { Treatment, TreatmentWithConfig } from '../../../../types/splitio';
+import { ILogger } from '../../../logger/types';
+import { isObject, isString } from '../../../utils/lang';
+import { FallbackDiscardReason } from '../constants';
+
+
+export class FallbacksSanitizer {
+
+  private static readonly pattern = /^[0-9]+[.a-zA-Z0-9_-]*$|^[a-zA-Z]+[a-zA-Z0-9_-]*$/;
+
+  private static isValidFlagName(name: string): boolean {
+    return name.length <= 100 && !name.includes(' ');
+  }
+
+  private static isValidTreatment(t?: Treatment | TreatmentWithConfig): boolean {
+    const treatment = isObject(t) ? (t as TreatmentWithConfig).treatment : t;
+
+    if (!isString(treatment) || treatment.length > 100) {
+      return false;
+    }
+    return FallbacksSanitizer.pattern.test(treatment);
+  }
+
+  static sanitizeGlobal(logger: ILogger, treatment?: Treatment | TreatmentWithConfig): Treatment | TreatmentWithConfig | undefined {
+    if (!this.isValidTreatment(treatment)) {
+      logger.error(
+        `Fallback treatments - Discarded fallback: ${FallbackDiscardReason.Treatment}`
+      );
+      return undefined;
+    }
+    return treatment;
+  }
+
+  static sanitizeByFlag(
+    logger: ILogger,
+    byFlagFallbacks: Record<string, Treatment | TreatmentWithConfig>
+  ): Record<string, Treatment | TreatmentWithConfig> {
+    const sanitizedByFlag: Record<string, Treatment | TreatmentWithConfig> = {};
+
+    const entries = Object.keys(byFlagFallbacks);
+    entries.forEach((flag) => {
+      const t = byFlagFallbacks[flag];
+      if (!this.isValidFlagName(flag)) {
+        logger.error(
+          `Fallback treatments - Discarded flag '${flag}': ${FallbackDiscardReason.FlagName}`
+        );
+        return;
+      }
+
+      if (!this.isValidTreatment(t)) {
+        logger.error(
+          `Fallback treatments - Discarded treatment for flag '${flag}': ${FallbackDiscardReason.Treatment}`
+        );
+        return;
+      }
+
+      sanitizedByFlag[flag] = t;
+    });
+
+    return sanitizedByFlag;
+  }
+}

package/src/evaluator/fallbackTreatmentsCalculator/index.ts

@@ -0,0 +1,57 @@
+import { FallbackTreatmentConfiguration, Treatment, TreatmentWithConfig } from '../../../types/splitio';
+import { FallbacksSanitizer } from './fallbackSanitizer';
+import { CONTROL } from '../../utils/constants';
+import { isString } from '../../utils/lang';
+import { ILogger } from '../../logger/types';
+
+export type IFallbackTreatmentsCalculator = {
+  resolve(flagName: string, label: string): TreatmentWithConfig & { label: string };
+}
+
+export const FALLBACK_PREFIX = 'fallback - ';
+
+export class FallbackTreatmentsCalculator implements IFallbackTreatmentsCalculator {
+  private readonly fallbacks: FallbackTreatmentConfiguration;
+
+  constructor(logger: ILogger, fallbacks?: FallbackTreatmentConfiguration) {
+    const sanitizedGlobal = fallbacks?.global ? FallbacksSanitizer.sanitizeGlobal(logger, fallbacks.global) : undefined;
+    const sanitizedByFlag = fallbacks?.byFlag ? FallbacksSanitizer.sanitizeByFlag(logger, fallbacks.byFlag) : {};
+    this.fallbacks = {
+      global: sanitizedGlobal,
+      byFlag: sanitizedByFlag
+    };
+  }
+
+  resolve(flagName: string, label: string): TreatmentWithConfig & { label: string } {
+    const treatment = this.fallbacks.byFlag?.[flagName];
+    if (treatment) {
+      return this.copyWithLabel(treatment, label);
+    }
+
+    if (this.fallbacks.global) {
+      return this.copyWithLabel(this.fallbacks.global, label);
+    }
+
+    return {
+      treatment: CONTROL,
+      config: null,
+      label,
+    };
+  }
+
+  private copyWithLabel(fallback: Treatment | TreatmentWithConfig, label: string): TreatmentWithConfig & { label: string } {
+    if (isString(fallback)) {
+      return {
+        treatment: fallback,
+        config: null,
+        label: `${FALLBACK_PREFIX}${label}`,
+      };
+    }
+
+    return {
+      treatment: fallback.treatment,
+      config: fallback.config,
+      label: `${FALLBACK_PREFIX}${label}`,
+    };
+  }
+}

package/src/logger/index.ts

@@ -72,6 +72,8 @@ export class Logger implements ILogger {
     if (logger) {
       if (isLogger(logger)) {
         this.logger = logger;
+        // If custom logger is set, all logs are either enabled or disabled
+        if (this.logLevel !== LogLevelIndexes.NONE) this.setLogLevel(LogLevels.DEBUG);
         return;
       } else {
         this.error('Invalid `logger` instance. It must be an object with `debug`, `info`, `warn` and `error` methods. Defaulting to `console.log`');

package/src/sdkClient/client.ts

@@ -35,7 +35,7 @@ function stringify(options?: SplitIO.EvaluationOptions) {
  * Creator of base client with getTreatments and track methods.
  */
 export function clientFactory(params: ISdkFactoryContext): SplitIO.IClient | SplitIO.IAsyncClient {
-  const { sdkReadinessManager: { readinessManager }, storage, settings, impressionsTracker, eventTracker, telemetryTracker } = params;
+  const { sdkReadinessManager: { readinessManager }, storage, settings, impressionsTracker, eventTracker, telemetryTracker, fallbackTreatmentsCalculator } = params;
   const { log, mode } = settings;
   const isAsync = isConsumerMode(mode);
 
@@ -143,7 +143,16 @@ export function clientFactory(params: ISdkFactoryContext): SplitIO.IClient | Spl
     const matchingKey = getMatching(key);
     const bucketingKey = getBucketing(key);
 
-    const { treatment, label, changeNumber, config = null, impressionsDisabled } = evaluation;
+    const { changeNumber, impressionsDisabled } = evaluation;
+    let { treatment, label, config = null } = evaluation;
+
+    if (treatment === CONTROL) {
+      const fallbackTreatment = fallbackTreatmentsCalculator.resolve(featureFlagName, label);
+      treatment = fallbackTreatment.treatment;
+      label = fallbackTreatment.label ? fallbackTreatment.label : label;
+      config = fallbackTreatment.config;
+    }
+
     log.info(IMPRESSION, [featureFlagName, matchingKey, treatment, label]);
 
     if (validateSplitExistence(log, readinessManager, featureFlagName, label, invokingMethodName)) {

package/src/sdkClient/clientInputValidation.ts

@@ -1,4 +1,3 @@
-import { objectAssign } from '../utils/lang/objectAssign';
 import {
   validateAttributes,
   validateEvent,
@@ -13,19 +12,20 @@ import {
   validateEvaluationOptions
 } from '../utils/inputValidation';
 import { startsWith } from '../utils/lang';
-import { CONTROL, CONTROL_WITH_CONFIG, GET_TREATMENT, GET_TREATMENTS, GET_TREATMENTS_BY_FLAG_SET, GET_TREATMENTS_BY_FLAG_SETS, GET_TREATMENTS_WITH_CONFIG, GET_TREATMENTS_WITH_CONFIG_BY_FLAG_SET, GET_TREATMENTS_WITH_CONFIG_BY_FLAG_SETS, GET_TREATMENT_WITH_CONFIG, TRACK_FN_LABEL } from '../utils/constants';
+import { GET_TREATMENT, GET_TREATMENTS, GET_TREATMENTS_BY_FLAG_SET, GET_TREATMENTS_BY_FLAG_SETS, GET_TREATMENTS_WITH_CONFIG, GET_TREATMENTS_WITH_CONFIG_BY_FLAG_SET, GET_TREATMENTS_WITH_CONFIG_BY_FLAG_SETS, GET_TREATMENT_WITH_CONFIG, TRACK_FN_LABEL } from '../utils/constants';
 import { IReadinessManager } from '../readiness/types';
 import { MaybeThenable } from '../dtos/types';
 import { ISettings } from '../types';
 import SplitIO from '../../types/splitio';
 import { isConsumerMode } from '../utils/settingsValidation/mode';
 import { validateFlagSets } from '../utils/settingsValidation/splitFilters';
+import { IFallbackTreatmentsCalculator } from '../evaluator/fallbackTreatmentsCalculator';
 
 /**
  * Decorator that validates the input before actually executing the client methods.
  * We should "guard" the client here, while not polluting the "real" implementation of those methods.
  */
-export function clientInputValidationDecorator<TClient extends SplitIO.IClient | SplitIO.IAsyncClient>(settings: ISettings, client: TClient, readinessManager: IReadinessManager): TClient {
+export function clientInputValidationDecorator<TClient extends SplitIO.IClient | SplitIO.IAsyncClient>(settings: ISettings, client: TClient, readinessManager: IReadinessManager, fallbackTreatmentsCalculator: IFallbackTreatmentsCalculator): TClient {
 
   const { log, mode } = settings;
   const isAsync = isConsumerMode(mode);
@@ -59,6 +59,19 @@ export function clientInputValidationDecorator<TClient extends SplitIO.IClient |
     };
   }
 
+  function evaluateFallBackTreatment(featureFlagName: string, withConfig: boolean): SplitIO.Treatment | SplitIO.TreatmentWithConfig {
+    const {treatment, config} = fallbackTreatmentsCalculator.resolve(featureFlagName, '');
+
+    if (withConfig) {
+      return {
+        treatment,
+        config
+      };
+    }
+
+    return treatment;
+  }
+
   function wrapResult<T>(value: T): MaybeThenable<T> {
     return isAsync ? Promise.resolve(value) : value;
   }
@@ -69,7 +82,8 @@ export function clientInputValidationDecorator<TClient extends SplitIO.IClient |
     if (params.valid) {
       return client.getTreatment(params.key as SplitIO.SplitKey, params.nameOrNames as string, params.attributes as SplitIO.Attributes | undefined, params.options);
     } else {
-      return wrapResult(CONTROL);
+      const result = evaluateFallBackTreatment(params.nameOrNames as string, false);
+      return wrapResult(result);
     }
   }
 
@@ -79,7 +93,8 @@ export function clientInputValidationDecorator<TClient extends SplitIO.IClient |
     if (params.valid) {
       return client.getTreatmentWithConfig(params.key as SplitIO.SplitKey, params.nameOrNames as string, params.attributes as SplitIO.Attributes | undefined, params.options);
     } else {
-      return wrapResult(objectAssign({}, CONTROL_WITH_CONFIG));
+      const result = evaluateFallBackTreatment(params.nameOrNames as string, true);
+      return wrapResult(result);
     }
   }
 
@@ -90,7 +105,7 @@ export function clientInputValidationDecorator<TClient extends SplitIO.IClient |
       return client.getTreatments(params.key as SplitIO.SplitKey, params.nameOrNames as string[], params.attributes as SplitIO.Attributes | undefined, params.options);
     } else {
       const res: SplitIO.Treatments = {};
-      if (params.nameOrNames) (params.nameOrNames as string[]).forEach((split: string) => res[split] = CONTROL);
+      if (params.nameOrNames) (params.nameOrNames as string[]).forEach((split: string) => res[split] = evaluateFallBackTreatment(split, false) as SplitIO.Treatment);
 
       return wrapResult(res);
     }
@@ -103,7 +118,7 @@ export function clientInputValidationDecorator<TClient extends SplitIO.IClient |
       return client.getTreatmentsWithConfig(params.key as SplitIO.SplitKey, params.nameOrNames as string[], params.attributes as SplitIO.Attributes | undefined, params.options);
     } else {
       const res: SplitIO.TreatmentsWithConfig = {};
-      if (params.nameOrNames) (params.nameOrNames as string[]).forEach(split => res[split] = objectAssign({}, CONTROL_WITH_CONFIG));
+      if (params.nameOrNames) (params.nameOrNames as string[]).forEach(split => res[split] = evaluateFallBackTreatment(split, true) as SplitIO.TreatmentWithConfig);
 
       return wrapResult(res);
     }

package/src/sdkClient/sdkClient.ts

@@ -43,7 +43,8 @@ export function sdkClientFactory(params: ISdkFactoryContext, isSharedClient?: bo
     clientInputValidationDecorator(
       settings,
       clientFactory(params),
-      sdkReadinessManager.readinessManager
+      sdkReadinessManager.readinessManager,
+      params.fallbackTreatmentsCalculator
     ),
 
     // Sdk destroy

package/src/sdkFactory/index.ts

@@ -17,6 +17,7 @@ import { DEBUG, OPTIMIZED } from '../utils/constants';
 import { setRolloutPlan } from '../storages/setRolloutPlan';
 import { IStorageSync } from '../storages/types';
 import { getMatching } from '../utils/key';
+import { FallbackTreatmentsCalculator } from '../evaluator/fallbackTreatmentsCalculator';
 
 /**
  * Modular SDK factory
@@ -60,6 +61,8 @@ export function sdkFactory(params: ISdkFactoryParams): SplitIO.ISDK | SplitIO.IA
     }
   });
 
+  const fallbackTreatmentsCalculator = new FallbackTreatmentsCalculator(settings.log, settings.fallbackTreatments);
+
   if (initialRolloutPlan) {
     setRolloutPlan(log, initialRolloutPlan, storage as IStorageSync, key && getMatching(key));
     if ((storage as IStorageSync).splits.getChangeNumber() > -1) readiness.splits.emit(SDK_SPLITS_CACHE_LOADED);
@@ -85,7 +88,7 @@ export function sdkFactory(params: ISdkFactoryParams): SplitIO.ISDK | SplitIO.IA
   // splitApi is used by SyncManager and Browser signal listener
   const splitApi = splitApiFactory && splitApiFactory(settings, platform, telemetryTracker);
 
-  const ctx: ISdkFactoryContext = { clients, splitApi, eventTracker, impressionsTracker, telemetryTracker, uniqueKeysTracker, sdkReadinessManager, readiness, settings, storage, platform };
+  const ctx: ISdkFactoryContext = { clients, splitApi, eventTracker, impressionsTracker, telemetryTracker, uniqueKeysTracker, sdkReadinessManager, readiness, settings, storage, platform, fallbackTreatmentsCalculator };
 
   const syncManager = syncManagerFactory && syncManagerFactory(ctx as ISdkFactoryContextSync);
   ctx.syncManager = syncManager;

package/src/sdkFactory/types.ts

@@ -3,6 +3,7 @@ import { ISignalListener } from '../listeners/types';
 import { IReadinessManager, ISdkReadinessManager } from '../readiness/types';
 import type { sdkManagerFactory } from '../sdkManager';
 import type { splitApiFactory } from '../services/splitApi';
+import type { IFallbackTreatmentsCalculator } from '../evaluator/fallbackTreatmentsCalculator';
 import { IFetch, ISplitApi, IEventSourceConstructor } from '../services/types';
 import { IStorageAsync, IStorageSync, IStorageFactoryParams } from '../storages/types';
 import { ISyncManager } from '../sync/types';
@@ -51,6 +52,7 @@ export interface ISdkFactoryContext {
   splitApi?: ISplitApi
   syncManager?: ISyncManager,
   clients: Record<string, SplitIO.IBasicClient>,
+  fallbackTreatmentsCalculator: IFallbackTreatmentsCalculator
 }
 
 export interface ISdkFactoryContextSync extends ISdkFactoryContext {

package/src/utils/inputValidation/splitExistence.ts

@@ -1,4 +1,4 @@
-import { SPLIT_NOT_FOUND } from '../labels';
+import { FALLBACK_SPLIT_NOT_FOUND, SPLIT_NOT_FOUND } from '../labels';
 import { IReadinessManager } from '../../readiness/types';
 import { ILogger } from '../../logger/types';
 import { WARN_NOT_EXISTENT_SPLIT } from '../../logger/constants';
@@ -9,7 +9,7 @@ import { WARN_NOT_EXISTENT_SPLIT } from '../../logger/constants';
  */
 export function validateSplitExistence(log: ILogger, readinessManager: IReadinessManager, splitName: string, labelOrSplitObj: any, method: string): boolean {
   if (readinessManager.isReady()) { // Only if it's ready we validate this, otherwise it may just be that the SDK is not ready yet.
-    if (labelOrSplitObj === SPLIT_NOT_FOUND || labelOrSplitObj == null) {
+    if (labelOrSplitObj === SPLIT_NOT_FOUND || labelOrSplitObj == null || labelOrSplitObj === FALLBACK_SPLIT_NOT_FOUND) {
       log.warn(WARN_NOT_EXISTENT_SPLIT, [method, splitName]);
       return false;
     }

package/src/utils/labels/index.ts

@@ -1,3 +1,5 @@
+import { FALLBACK_PREFIX } from '../../evaluator/fallbackTreatmentsCalculator';
+
 export const SPLIT_KILLED = 'killed';
 export const NO_CONDITION_MATCH = 'default rule';
 export const SPLIT_NOT_FOUND = 'definition not found';
@@ -7,3 +9,4 @@ export const SPLIT_ARCHIVED = 'archived';
 export const NOT_IN_SPLIT = 'not in split';
 export const UNSUPPORTED_MATCHER_TYPE = 'targeting rule type unsupported by sdk';
 export const PREREQUISITES_NOT_MET = 'prerequisites not met';
+export const FALLBACK_SPLIT_NOT_FOUND = FALLBACK_PREFIX + SPLIT_NOT_FOUND;

package/types/splitio.d.ts

@@ -93,7 +93,6 @@ interface ISharedSettings {
   urls?: SplitIO.UrlSettings;
   /**
    * Custom logger object. If not provided, the SDK will use the default `console.log` method for all log levels.
-   * Set together with `debug` option to `true` or a log level string to enable logging.
    */
   logger?: SplitIO.Logger;
 }
@@ -146,6 +145,8 @@ interface IPluggableSharedSettings {
    * config.debug = ErrorLogger()
    * ```
    *
+   * When combined with the `logger` option, any log level other than `NONE` (false) will be set to `DEBUG` (true), delegating log level control to the custom logger.
+   *
    * @defaultValue `false`
    */
   debug?: boolean | SplitIO.LogLevel | SplitIO.ILogger;
@@ -169,6 +170,8 @@ interface INonPluggableSharedSettings {
    * config.debug = 'WARN'
    * ```
    *
+   * When combined with the `logger` option, any log level other than `NONE` (false) will be set to `DEBUG` (true), delegating log level control to the custom logger.
+   *
    * @defaultValue `false`
    */
   debug?: boolean | SplitIO.LogLevel;
@@ -618,6 +621,10 @@ declare namespace SplitIO {
      * User consent status if using in client-side. Undefined if using in server-side (Node.js).
      */
     readonly userConsent?: ConsentStatus;
+    /**
+     * Fallback treatments to be used when the SDK is not ready or the flag is not found.
+     */
+    readonly fallbackTreatments?: FallbackTreatmentConfiguration;
   }
   /**
    * Log levels.
@@ -1225,6 +1232,15 @@ declare namespace SplitIO {
    * User consent status.
    */
   type ConsentStatus = 'GRANTED' | 'DECLINED' | 'UNKNOWN';
+  /**
+   * Fallback treatments to be used when the SDK is not ready or the flag is not found.
+   */
+  type FallbackTreatmentConfiguration = {
+    global?: Treatment | TreatmentWithConfig,
+    byFlag?: {
+      [featureFlagName: string]: Treatment | TreatmentWithConfig
+    }
+  }
   /**
    * Logger. Its interface details are not part of the public API. It shouldn't be used directly.
    */