@reflag/node-sdk 1.3.0 → 1.4.1

package/README.md

@@ -59,10 +59,6 @@ You can also [use the HTTP API directly](https://docs.reflag.com/api/http-api)
 To get started you need to obtain your secret key from the [environment settings](https://app.reflag.com/env-current/settings/app-environments)
 in Reflag.
 
-> [!CAUTION]
-> Secret keys are meant for use in server side SDKs only. Secret keys offer the users the ability to obtain
-> information that is often sensitive and thus should not be used in client-side applications.
-
 Reflag will load settings through the various environment variables automatically (see [Configuring](#configuring) below).
 
 1. Find the Reflag secret key for your development environment under [environment settings](https://app.reflag.com/env-current/settings/app-environments) in Reflag.
@@ -91,7 +87,7 @@ Once the client is initialized, you can obtain flags along with the `isEnabled`
 status to indicate whether the flag is targeted for this user/company:
 
 > [!IMPORTANT]
-> If `user.id` or `company.id` is not given, the whole `user` or `company` object is ignored.
+> If `user.id` is not given, the whole `user` object is ignore. Similarly, without `company.id` the `company` object is ignored.
 
 ```typescript
 // configure the client
@@ -175,15 +171,8 @@ await client.flush();
 ### Rate Limiting
 
 The SDK includes automatic rate limiting for flag events to prevent overwhelming the API.
-Rate limiting is applied per unique combination of flag key and context. The rate limiter window size is configurable:
-
-```typescript
-const client = new ReflagClient({
-  rateLimiterOptions: {
-    windowSizeMs: 60000, // Rate limiting window size in milliseconds
-  },
-});
-```
+Rate limiting is applied per unique combination of flag key and evaluation context.
+This behavior is built in and does not currently require configuration.
 
 ### Flag definitions
 
@@ -206,9 +195,176 @@ const flagDefs = await client.getFlagDefinitions();
 // }]
 ```
 
+### Fallback provider
+
+`flagsFallbackProvider` is a reliability feature that lets the SDK persist the latest successfully fetched raw flag definitions to fallback storage such as a local file, Redis, S3, GCS, or a custom backend.
+
+> [!NOTE]
+>
+> `fallbackFlags` is deprecated. Prefer `flagsFallbackProvider` for startup fallback and outage recovery.
+> `flagsFallbackProvider` is not used in offline mode.
+
+#### How it works
+
+Reflag servers remain the primary source of truth. On `initialize()`, the SDK always tries to fetch a live copy of the flag definitions first, and it continues refreshing those definitions from the Reflag servers over time.
+
+If that initial live fetch fails, the SDK can call `flagsFallbackProvider.load()` and start with the last saved snapshot instead. This is mainly useful for cold starts in the exceedingly rare case that Reflag has an outage.
+
+If Reflag becomes unavailable after the SDK has already initialized successfully, the SDK keeps using the last successfully fetched definitions it already has in memory. In other words, the fallback provider is mainly what helps future processes start, not what keeps an already running process alive.
+
+After successfully fetching updated flag definitions, the SDK calls `flagsFallbackProvider.save()` to keep the stored snapshot up to date.
+
+Typical reliability flow:
+
+1. The SDK starts and tries to fetch live flag definitions from Reflag.
+2. If that succeeds, those definitions are used immediately and the SDK continues operating normally.
+3. After successfully fetching updated flag definitions, the SDK saves the latest snapshot through the fallback provider so a recent copy is available if needed later.
+4. If a future process starts while Reflag is unavailable, it can load the last saved snapshot from the fallback provider and still initialize.
+5. Once Reflag becomes available again, the SDK resumes using live data and refreshes the fallback snapshot.
+
+Most deployments run multiple SDK processes, so more than one process may save identical flag definitions to the fallback storage at roughly the same time. This is expected and generally harmless for backends like a local file, Redis, S3, or GCS because the operation is cheap. In practice, this only becomes worth thinking about once you have many thousands of SDK processes writing to the same fallback storage.
+
+> [!TIP]
+> If you are building a web or client-side application and want the most resilient setup, combine `flagsFallbackProvider` on the server with bootstrapped flags on the client.
+>
+> `flagsFallbackProvider` helps new server processes start if they cannot reach Reflag during initialization. Bootstrapping helps clients render from server-provided flags instead of depending on an initial client-side fetch from the Reflag servers.
+>
+> This applies to React (`getFlagsForBootstrap()` + `ReflagBootstrappedProvider`), the Browser SDK (`bootstrappedFlags`), and the Vue SDK (bootstrapped flags via the provider).
+
+#### Built-in providers
+
+You can access the built-in providers through the `fallbackProviders` namespace:
+
+- `fallbackProviders.static(...)`
+- `fallbackProviders.file(...)`
+- `fallbackProviders.redis(...)`
+- `fallbackProviders.s3(...)`
+- `fallbackProviders.gcs(...)`
+
+##### Static provider
+
+If you just want a fixed fallback copy of simple enabled/disabled flags, you can provide a static map:
+
+```typescript
+import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";
+
+const client = new ReflagClient({
+  secretKey: process.env.REFLAG_SECRET_KEY,
+  flagsFallbackProvider: fallbackProviders.static({
+    flags: {
+      huddle: true,
+      "smart-summaries": false,
+    },
+  }),
+});
+
+await client.initialize();
+```
+
+##### File provider
+
+```typescript
+import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";
+
+const client = new ReflagClient({
+  secretKey: process.env.REFLAG_SECRET_KEY,
+  flagsFallbackProvider: fallbackProviders.file({
+    directory: ".reflag",
+  }),
+});
+
+await client.initialize();
+```
+
+The file provider stores one snapshot file per environment in the configured
+`directory`.
+
+##### Redis provider
+
+The built-in Redis provider creates a Redis client automatically when omitted and uses `REDIS_URL` from the environment. It stores snapshots under the configured `keyPrefix` and uses the first 16 characters of the secret key hash in the Redis key.
+
+Without a `keyPrefix` set, it will default to to the key `reflag:flags-fallback:${secretKeyHash}`.
+
+```typescript
+import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";
+
+const client = new ReflagClient({
+  secretKey: process.env.REFLAG_SECRET_KEY,
+  flagsFallbackProvider: fallbackProviders.redis(),
+});
+
+await client.initialize();
+```
+
+##### S3 provider
+
+The built-in S3 provider works out of the box using the AWS SDK's default credential chain and region resolution. It stores the snapshot object under the configured `keyPrefix` and uses a hash of the secret key in the object name.
+
+Without a `keyPrefix` set, it will default to path `reflag/flags-fallback/${secretKeyHash}`.
+
+```typescript
+import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";
+
+const client = new ReflagClient({
+  secretKey: process.env.REFLAG_SECRET_KEY,
+  flagsFallbackProvider: fallbackProviders.s3({
+    bucket: "reflag-fallback-bucket",
+  }),
+});
+
+await client.initialize();
+```
+
+##### GCS provider
+
+The built-in GCS provider works out of the box using Google Cloud's default application credentials. It stores the snapshot object under the configured `keyPrefix` and uses a hash of the secret key in the object name.
+
+Without a `keyPrefix` set, it will default to path `reflag/flags-fallback/${secretKeyHash}`.
+
+```typescript
+import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";
+
+const client = new ReflagClient({
+  secretKey: process.env.REFLAG_SECRET_KEY,
+  flagsFallbackProvider: fallbackProviders.gcs({
+    bucket: "reflag-fallback-bucket",
+  }),
+});
+
+await client.initialize();
+```
+
+#### Testing fallback startup locally
+
+To test fallback startup in your own app, first run it once with a working Reflag connection so a snapshot is saved. Then restart it with the same secret key and fallback provider configuration, but set `apiBaseUrl` (or set the `REFLAG_API_BASE_URL` environment variable) to `http://127.0.0.1:65535`. That forces the live fetch to fail and lets you verify that the SDK initializes from the saved snapshot instead.
+
+#### Writing a custom provider
+
+If you just store definitions in your database or similar, a custom provider can be very small:
+
+```typescript
+import type {
+  FlagsFallbackProvider,
+  FlagsFallbackSnapshot,
+} from "@reflag/node-sdk";
+
+export const customFallbackProvider: FlagsFallbackProvider = {
+  async load(context) {
+    // load snapshot from database
+    // optionally, look up the snapshot using the context.secretKeyHash as a key
+    return snapshot;
+  },
+
+  async save(context, snapshot) {
+    const serialized = JSON.stringify(snapshot);
+    // write serialized snapshot to database, optionally using context.secretKeyHash as a key
+  },
+};
+```
+
 ## Bootstrapping client-side applications
 
-The `getFlagsForBootstrap()` method is designed for server-side rendering (SSR) scenarios where you need to pass flag data to client-side applications. This method returns raw flag data without wrapper functions, making it suitable for serialization and client-side hydration.
+The `getFlagsForBootstrap()` method is useful whenever you need to pass flag data to another runtime or serialize it without wrapper functions. Server-side rendering (SSR) is a common example, but it is also useful for other bootstrapping and hydration flows.
 
 ```typescript
 const client = new ReflagClient();
@@ -340,7 +496,8 @@ fallback behavior:
 4. **Offline Mode**:
 
    ```typescript
-   // In offline mode, the SDK uses flag overrides
+   // In offline mode, the SDK uses explicit local configuration only.
+   // It does not fetch from Reflag or use flagsFallbackProvider.
    const client = new ReflagClient({
      offline: true,
      flagOverrides: () => ({
@@ -400,16 +557,19 @@ a configuration file on disk or by passing options to the `ReflagClient`
 constructor. By default, the SDK searches for `reflag.config.json` in the
 current working directory.
 
-| Option          | Type                    | Description                                                                                                                                                                                                                                         | Env Var                                     |
-| --------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| `secretKey`     | string                  | The secret key used for authentication with Reflag's servers.                                                                                                                                                                                       | REFLAG_SECRET_KEY                           |
-| `logLevel`      | string                  | The log level for the SDK (e.g., `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`). Default: `INFO`                                                                                                                                                         | REFLAG_LOG_LEVEL                            |
-| `offline`       | boolean                 | Operate in offline mode. Default: `false`, except in tests it will default to `true` based off of the `TEST` env. var.                                                                                                                              | REFLAG_OFFLINE                              |
-| `apiBaseUrl`    | string                  | The base API URL for the Reflag servers.                                                                                                                                                                                                            | REFLAG_API_BASE_URL                         |
-| `flagOverrides` | Record<string, boolean> | An object specifying flag overrides for testing or local development. See [examples/express/app.test.ts](https://github.com/reflagcom/javascript/tree/main/packages/node-sdk/examples/express/app.test.ts) for how to use `flagOverrides` in tests. | REFLAG_FLAGS_ENABLED, REFLAG_FLAGS_DISABLED |
-| `configFile`    | string                  | Load this config file from disk. Default: `reflag.config.json`                                                                                                                                                                                      | REFLAG_CONFIG_FILE                          |
+| Option                  | Type                    | Description                                                                                                                                                                                                                                         | Env Var                                     |
+| ----------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `secretKey`             | string                  | The secret key used for authentication with Reflag's servers.                                                                                                                                                                                       | REFLAG_SECRET_KEY                           |
+| `logLevel`              | string                  | The log level for the SDK (e.g., `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`). Default: `INFO`                                                                                                                                                         | REFLAG_LOG_LEVEL                            |
+| `offline`               | boolean                 | Operate in offline mode. Default: `false`, except in tests it will default to `true` based off of the `TEST` env. var. In offline mode the SDK does not fetch from Reflag and does not use `flagsFallbackProvider`.                                 | REFLAG_OFFLINE                              |
+| `apiBaseUrl`            | string                  | The base API URL for the Reflag servers.                                                                                                                                                                                                            | REFLAG_API_BASE_URL                         |
+| `flagOverrides`         | Record<string, boolean> | An object specifying flag overrides for testing or local development. See [examples/express/app.test.ts](https://github.com/reflagcom/javascript/tree/main/packages/node-sdk/examples/express/app.test.ts) for how to use `flagOverrides` in tests. | REFLAG_FLAGS_ENABLED, REFLAG_FLAGS_DISABLED |
+| `flagsFallbackProvider` | `FlagsFallbackProvider` | Optional provider used to load and save raw flag definitions for fallback startup when the initial live fetch fails. Available only through the constructor. Ignored in offline mode.                                                               | -                                           |
+| `configFile`            | string                  | Load this config file from disk. Default: `reflag.config.json`                                                                                                                                                                                      | REFLAG_CONFIG_FILE                          |
 
-> [!NOTE] > `REFLAG_FLAGS_ENABLED` and `REFLAG_FLAGS_DISABLED` are comma separated lists of flags which will be enabled or disabled respectively.
+> [!NOTE]
+>
+> `REFLAG_FLAGS_ENABLED` and `REFLAG_FLAGS_DISABLED` are comma separated lists of flags which will be enabled or disabled respectively.
 
 `reflag.config.json` example:
 
@@ -496,9 +656,9 @@ reflagClient.initialize().then(() => {
 
 ![Config type check failed](docs/type-check-payload-failed.png "Remote config type check failed")
 
-## Testing
+## Testing with flag overrides
 
-When writing tests that cover code with flags, you can toggle flags on/off programmatically to test different behavior. For tests, you will often want to run the client in offline mode and provide flag overrides directly through the client options.
+When writing tests that cover code with flags, you can toggle flags on/off programmatically to test different behavior. For tests, you will often want to run the client in offline mode:
 
 `reflag.ts`:
 
@@ -510,7 +670,11 @@ export const reflag = new ReflagClient({
 });
 ```
 
-You can then set base overrides for a test run by passing `flagOverrides` in the constructor, replacing them later with `setFlagOverrides()`, or clearing them with `clearFlagOverrides()`:
+There are a few ways to programmatically manipulate the overrides which are appropriate when testing:
+
+### Base overrides
+
+You can set base overrides for a test run by passing `flagOverrides` in the constructor, replacing them later with `setFlagOverrides()` and clearing them with `clearFlagOverrides()`:
 
 ```typescript
 // pass directly in the constructor
@@ -549,6 +713,8 @@ describe("API Tests", () => {
 });
 ```
 
+### Layering overrides
+
 `pushFlagOverrides()` serves a different purpose: it adds a temporary layer on top of the base overrides and returns a remove function that removes only that layer. This is useful for nested tests:
 
 ```typescript
@@ -585,7 +751,9 @@ The precedence is:
 
 If the same flag is set in both places, the pushed override wins until its remove function is called.
 
-`pushFlagOverrides()` also accepts a function if the temporary override depends on the evaluation context:
+### Context dependent overrides
+
+`setFlagOverrides()` and `pushFlagOverrides()` also accept a function if the override depends on the evaluation context:
 
 ```typescript
 const remove = client.pushFlagOverrides((context) => ({
@@ -597,13 +765,9 @@ const remove = client.pushFlagOverrides((context) => ({
 remove();
 ```
 
-## Flag Overrides
+### Additional ways to provide flag overrides
 
-Flag overrides allow you to override flags and their configurations locally. This is particularly useful when testing changes locally, for example when running your app and clicking around to verify behavior before deploying your changes.
-
-For automated tests, see the [Testing](#testing) section above.
-
-When testing locally during development, you also have these additional ways to provide overrides:
+You also have these additional ways to provide overrides, which can be helpful when testing out locally:
 
 1. Through environment variables:
 
@@ -631,29 +795,6 @@ REFLAG_FLAGS_DISABLED=flag3,flag4
 }
 ```
 
-To get dynamic overrides, use a function which takes a context and returns a boolean or an object with the shape of `{isEnabled, config}`:
-
-```typescript
-import { ReflagClient, Context } from "@reflag/node-sdk";
-
-const flagOverrides = (context: Context) => ({
-  "delete-todos": {
-    isEnabled: true,
-    config: {
-      key: "dev-config",
-      payload: {
-        requireConfirmation: true,
-        maxDeletionsPerDay: 5,
-      },
-    },
-  },
-});
-
-const client = new ReflagClient({
-  flagOverrides,
-});
-```
-
 ## Remote Flag Evaluation
 
 In addition to local flag evaluation, Reflag supports remote evaluation using stored context. This is useful when you want to evaluate flags using user/company attributes that were previously sent to Reflag:

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@reflag/node-sdk",
-    "version": "1.3.0",
+    "version": "1.4.1",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -45,6 +45,9 @@
         "vitest": "~1.6.0"
     },
     "dependencies": {
+        "@aws-sdk/client-s3": "^3.888.0",
+        "@google-cloud/storage": "^7.19.0",
+        "@redis/client": "^5.11.0",
         "@reflag/flag-evaluation": "1.0.0"
     }
 }

package/dist/src/batch-buffer.js

@@ -73,7 +73,7 @@ class BatchBuffer {
                 });
             }
             catch (error) {
-                (_c = this.logger) === null || _c === void 0 ? void 0 : _c.error("flush of buffered items failed; discarding items", {
+                (_c = this.logger) === null || _c === void 0 ? void 0 : _c.warn("flush of buffered items failed; discarding items", {
                     error,
                     count: flushingBuffer.length,
                 });

package/dist/src/batch-buffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"batch-buffer.js","sourceRoot":"","sources":["../../src/batch-buffer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"batch-buffer.js","sourceRoot":"","sources":["../../src/batch-buffer.ts"],"names":[],"mappings":"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"}

package/dist/src/client.js

@@ -62,6 +62,7 @@ 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 flagsFallbackProvider_1 = require("./flagsFallbackProvider");
 const flusher_1 = require("./flusher");
 const inRequestCache_1 = __importDefault(require("./inRequestCache"));
 const periodicallyUpdatingCache_1 = __importDefault(require("./periodicallyUpdatingCache"));
@@ -80,6 +81,54 @@ function composeFlagOverrides(baseOverrides, layers) {
     }
     return (context) => layers.reduce((acc, layer) => (Object.assign(Object.assign({}, acc), layer.overrides(context))), baseOverrides(context));
 }
+function compileFlagDefinitions(flags) {
+    return flags.map((flagDef) => {
+        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)(flagDef.config.variants.map((variant) => ({
+                    filter: variant.filter,
+                    value: {
+                        key: variant.key,
+                        payload: variant.payload,
+                    },
+                })))
+                : undefined });
+    });
+}
+function createFlagsFallbackSnapshot(flags) {
+    return {
+        version: 1,
+        savedAt: new Date().toISOString(),
+        flags,
+    };
+}
+function formatFlagsFallbackAge(savedAt) {
+    const savedAtMs = Date.parse(savedAt);
+    if (!Number.isFinite(savedAtMs)) {
+        return undefined;
+    }
+    const ageMs = Math.max(0, Date.now() - savedAtMs);
+    const minuteMs = 60000;
+    const hourMs = 60 * minuteMs;
+    const dayMs = 24 * hourMs;
+    if (ageMs < minuteMs) {
+        return "<1m";
+    }
+    if (ageMs < hourMs) {
+        return `${Math.floor(ageMs / minuteMs)}m`;
+    }
+    if (ageMs < dayMs) {
+        return `${Math.floor(ageMs / hourMs)}h`;
+    }
+    return `${Math.floor(ageMs / dayMs)}d`;
+}
+function createErrorWithCause(message, cause) {
+    const error = new Error(message);
+    error.cause = cause;
+    return error;
+}
 /**
  * The SDK client.
  *
@@ -127,6 +176,7 @@ class ReflagClient {
         this.flagOverrideLayers = [];
         this.nextFlagOverrideLayerId = 0;
         this.initializationFinished = false;
+        this.canLoadFlagsFallbackProvider = true;
         this._initialize = (0, utils_1.once)(() => __awaiter(this, void 0, void 0, function* () {
             const start = Date.now();
             if (!this._config.offline) {
@@ -146,6 +196,10 @@ class ReflagClient {
                 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.flagsFallbackProvider === undefined ||
+            ((0, utils_1.isObject)(options.flagsFallbackProvider) &&
+                typeof options.flagsFallbackProvider.load === "function" &&
+                typeof options.flagsFallbackProvider.save === "function"), "flagsFallbackProvider must be an object with load/save functions");
         (0, utils_1.ok)(options.fallbackFlags === undefined ||
             Array.isArray(options.fallbackFlags) ||
             (0, utils_1.isObject)(options.fallbackFlags), "fallbackFlags must be an array or object");
@@ -217,8 +271,11 @@ class ReflagClient {
                 ["Authorization"]: `Bearer ${config.secretKey}`,
             },
             refetchInterval: config_1.FLAGS_REFETCH_MS,
-            staleWarningInterval: config_1.FLAGS_REFETCH_MS * 5,
             fallbackFlags: fallbackFlags,
+            flagsFallbackProvider: options.flagsFallbackProvider,
+            flagsFallbackProviderContext: {
+                secretKeyHash: config.secretKey ? (0, utils_1.hashString)(config.secretKey) : "",
+            },
             flagOverrides: baseFlagOverrides,
             flagsFetchRetries: (_f = options.flagsFetchRetries) !== null && _f !== void 0 ? _f : 3,
             fetchTimeoutMs: (_g = options.fetchTimeoutMs) !== null && _g !== void 0 ? _g : config_1.API_TIMEOUT_MS,
@@ -234,32 +291,65 @@ class ReflagClient {
         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 yield this.loadFlagsFallbackDefinitions();
             }
-            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 });
-            });
+            void this.saveFlagsFallbackDefinitions(res.features);
+            this.canLoadFlagsFallbackProvider = false;
+            return compileFlagDefinitions(res.features);
         });
         if (this._config.cacheStrategy === "periodically-update") {
-            this.flagsCache = (0, periodicallyUpdatingCache_1.default)(this._config.refetchInterval, this._config.staleWarningInterval, this.logger, fetchFlags);
+            this.flagsCache = (0, periodicallyUpdatingCache_1.default)(this._config.refetchInterval, this.logger, fetchFlags);
         }
         else {
             this.flagsCache = (0, inRequestCache_1.default)(this._config.refetchInterval, this.logger, fetchFlags);
         }
     }
+    loadFlagsFallbackDefinitions() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.canLoadFlagsFallbackProvider) {
+                return undefined;
+            }
+            this.canLoadFlagsFallbackProvider = false;
+            const provider = this._config.flagsFallbackProvider;
+            if (!provider) {
+                return undefined;
+            }
+            try {
+                const snapshot = yield provider.load(this._config.flagsFallbackProviderContext);
+                if (!snapshot) {
+                    this.logger.warn("remote flags unavailable, no fallback flags found in flagsFallbackProvider");
+                    return undefined;
+                }
+                if (!(0, flagsFallbackProvider_1.isFlagsFallbackSnapshot)(snapshot)) {
+                    this.logger.warn("flagsFallbackProvider: invalid snapshot returned");
+                    return undefined;
+                }
+                const fallbackAge = formatFlagsFallbackAge(snapshot.savedAt);
+                this.logger.warn(fallbackAge
+                    ? `remote flags unavailable, using fallback flags fetched ${fallbackAge} ago (${snapshot.savedAt})`
+                    : `remote flags unavailable, using fallback flags (${snapshot.savedAt})`);
+                return compileFlagDefinitions(snapshot.flags);
+            }
+            catch (error) {
+                this.logger.error("flagsFallbackProvider: failed to load flag definitions", error);
+                return undefined;
+            }
+        });
+    }
+    saveFlagsFallbackDefinitions(flags) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const provider = this._config.flagsFallbackProvider;
+            if (!provider) {
+                return;
+            }
+            try {
+                yield provider.save(this._config.flagsFallbackProviderContext, createFlagsFallbackSnapshot(flags));
+            }
+            catch (error) {
+                this.logger.error("flagsFallbackProvider: failed to save flag definitions", error);
+            }
+        });
+    }
     /**
      * Replaces the base flag overrides used by the client.
      *
@@ -659,8 +749,6 @@ class ReflagClient {
      * @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) {
@@ -672,14 +760,11 @@ class ReflagClient {
                 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;
+                    throw createErrorWithCause(`invalid response received from server for "${url}"`, JSON.stringify(response));
                 }
-                return true;
             }
             catch (error) {
-                this.logger.error(`post request to "${url}" failed with error`, error);
-                return false;
+                throw createErrorWithCause(`post request to "${url}" failed with error`, error);
             }
         });
     }
@@ -707,12 +792,12 @@ class ReflagClient {
                     }
                     const _a = response.body, { success: _ } = _a, result = __rest(_a, ["success"]);
                     return result;
-                }), () => {
-                    this.logger.warn("failed to fetch flags, will retry");
+                }), (error) => {
+                    this.logger.warn("failed to fetch flags, will retry", error);
                 }, retries, 1000, 10000);
             }
             catch (error) {
-                this.logger.error(`get request to "${path}" failed with error after ${retries} retries`, error);
+                this.logger.debug(`get request to "${path}" failed with error after ${retries} retries`, error);
                 return undefined;
             }
         });
@@ -727,9 +812,11 @@ class ReflagClient {
     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");
+            try {
+                yield this.post("bulk", events);
+            }
+            catch (error) {
+                throw createErrorWithCause("failed to send bulk events", error);
             }
         });
     }