posthog-node 5.11.2 → 5.12.0

package/LICENSE

@@ -219,7 +219,7 @@ limitations under the License.
 
 ---
 
-Some files in this codebase contain code from getsentry/sentry-javascript by Software, Inc. dba Sentry.
+Some files in this codebase contain code from getsentry/sentry-javascript or getsentry/sentry-react-native by Software, Inc. dba Sentry.
 In such cases it is explicitly stated in the file header. This license only applies to the relevant code in such cases. 
 
 MIT License
@@ -242,4 +242,58 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.
+
+---
+
+Some files in this codebase contain code from facebook/metro by Meta Platforms, Inc. and affiliates.
+In such cases it is explicitly stated in the file header. This license only applies to the relevant code in such cases. 
+
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Some files in this codebase contain code from expo/expo by 650 Industries, Inc. (aka Expo).
+In such cases it is explicitly stated in the file header. This license only applies to the relevant code in such cases. 
+
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -65,7 +65,8 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
                 onLoad: (count)=>{
                     this._events.emit('localEvaluationFlagsLoaded', count);
                 },
-                customHeaders: this.getCustomHeaders()
+                customHeaders: this.getCustomHeaders(),
+                cacheProvider: options.flagDefinitionCacheProvider
             });
         }
         this.errorTracking = new (index_js_default())(this, options, this._logger);
@@ -299,7 +300,7 @@ class PostHogBackendClient extends core_namespaceObject.PostHogCoreStateless {
         await this.featureFlagsPoller?.loadFeatureFlags(true);
     }
     async _shutdown(shutdownTimeoutMs) {
-        this.featureFlagsPoller?.stopPoller();
+        this.featureFlagsPoller?.stopPoller(shutdownTimeoutMs);
         this.errorTracking.shutdown();
         return super._shutdown(shutdownTimeoutMs);
     }

package/dist/client.mjs

@@ -27,7 +27,8 @@ class PostHogBackendClient extends PostHogCoreStateless {
                 onLoad: (count)=>{
                     this._events.emit('localEvaluationFlagsLoaded', count);
                 },
-                customHeaders: this.getCustomHeaders()
+                customHeaders: this.getCustomHeaders(),
+                cacheProvider: options.flagDefinitionCacheProvider
             });
         }
         this.errorTracking = new error_tracking(this, options, this._logger);
@@ -261,7 +262,7 @@ class PostHogBackendClient extends PostHogCoreStateless {
         await this.featureFlagsPoller?.loadFeatureFlags(true);
     }
     async _shutdown(shutdownTimeoutMs) {
-        this.featureFlagsPoller?.stopPoller();
+        this.featureFlagsPoller?.stopPoller(shutdownTimeoutMs);
         this.errorTracking.shutdown();
         return super._shutdown(shutdownTimeoutMs);
     }

package/dist/experimental.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Experimental APIs
+ *
+ * This module exports experimental features that may change or be removed in minor versions.
+ * Use these APIs with caution and be prepared for breaking changes.
+ *
+ * @packageDocumentation
+ * @experimental
+ */
+export type { FlagDefinitionCacheProvider, FlagDefinitionCacheData } from './extensions/feature-flags/cache';
+//# sourceMappingURL=experimental.d.ts.map

package/dist/experimental.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experimental.d.ts","sourceRoot":"","sources":["../src/experimental.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAA"}

package/dist/experimental.js

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/extensions/feature-flags/cache.d.ts

@@ -0,0 +1,110 @@
+import type { PostHogFeatureFlag, PropertyGroup } from '../../types';
+/**
+ * Represents the complete set of feature flag data needed for local evaluation.
+ *
+ * This includes flag definitions, group type mappings, and cohort property groups.
+ */
+export interface FlagDefinitionCacheData {
+    /** Array of feature flag definitions */
+    flags: PostHogFeatureFlag[];
+    /** Mapping of group type index to group name */
+    groupTypeMapping: Record<string, string>;
+    /** Cohort property groups for local evaluation */
+    cohorts: Record<string, PropertyGroup>;
+}
+/**
+ * @experimental This API is experimental and may change in minor versions.
+ *
+ * Provider interface for caching feature flag definitions.
+ *
+ * Implementations can use this to control when flag definitions are fetched
+ * and how they're cached (Redis, database, filesystem, etc.).
+ *
+ * This interface is designed for server-side environments where multiple workers
+ * need to share flag definitions and coordinate fetching to reduce API calls.
+ *
+ * All methods may throw errors - the poller will catch and log them gracefully,
+ * ensuring cache provider errors never break flag evaluation.
+ *
+ * @example
+ * ```typescript
+ * import { FlagDefinitionCacheProvider } from 'posthog-node/experimental'
+ *
+ * class RedisFlagCache implements FlagDefinitionCacheProvider {
+ *   constructor(private redis: Redis, private teamKey: string) { }
+ *
+ *   async getFlagDefinitions(): Promise<FlagDefinitionCacheData | undefined> {
+ *     const cached = await this.redis.get(`posthog:flags:${this.teamKey}`)
+ *     return cached ? JSON.parse(cached) : undefined
+ *   }
+ *
+ *   async shouldFetchFlagDefinitions(): Promise<boolean> {
+ *     // Acquire distributed lock - only one worker fetches
+ *     const acquired = await this.redis.set(`posthog:flags:${this.teamKey}:lock`, '1', 'EX', 60, 'NX')
+ *     return acquired === 'OK'
+ *   }
+ *
+ *   async onFlagDefinitionsReceived(data: FlagDefinitionCacheData): Promise<void> {
+ *     await this.redis.set(`posthog:flags:${this.teamKey}`, JSON.stringify(data), 'EX', 300)
+ *     await this.redis.del(`posthog:flags:${this.teamKey}:lock`)
+ *   }
+ *
+ *   async shutdown(): Promise<void> {
+ *     await this.redis.del(`posthog:flags:${this.teamKey}:lock`)
+ *   }
+ * }
+ * ```
+ */
+export interface FlagDefinitionCacheProvider {
+    /**
+     * Retrieve cached flag definitions.
+     *
+     * Called when the poller is refreshing in-memory flag definitions. If this returns undefined
+     * (or throws an error), the poller will fetch fresh data from the PostHog API if no flag
+     * definitions are in memory. Otherwise, stale cache data is used until the next poll cycle.
+     *
+     * @returns cached definitions if available, undefined if cache is empty
+     * @throws if an error occurs while accessing the cache (error will be logged)
+     */
+    getFlagDefinitions(): Promise<FlagDefinitionCacheData | undefined> | FlagDefinitionCacheData | undefined;
+    /**
+     * Determines whether this instance should fetch new flag definitions.
+     *
+     * Use this to implement distributed coordination (e.g., via distributed locks)
+     * to ensure only one instance fetches at a time in a multi-worker setup.
+     *
+     * When multiple workers share a cache, typically only one should fetch while
+     * others use cached data. Implementations can use Redis locks, database locks,
+     * or other coordination mechanisms.
+     *
+     * @returns true if this instance should fetch, false to skip and read cache
+     * @throws if coordination backend is unavailable (error will be logged, fetch continues)
+     */
+    shouldFetchFlagDefinitions(): Promise<boolean> | boolean;
+    /**
+     * Called after successfully receiving new flag definitions from PostHog.
+     *
+     * Store the definitions in your cache backend here. This is called only
+     * after a successful API response with valid flag data.
+     *
+     * If this method throws, the error is logged but flag definitions are still
+     * stored in memory, ensuring local evaluation can still be performed.
+     *
+     * @param data - The complete flag definition data from PostHog
+     * @throws if storage backend is unavailable (error will be logged)
+     */
+    onFlagDefinitionsReceived(data: FlagDefinitionCacheData): Promise<void> | void;
+    /**
+     * Called when the PostHog client shuts down.
+     *
+     * Release any held locks, close connections, or clean up resources here.
+     *
+     * Both sync and async cleanup are supported. Async cleanup has a timeout
+     * (default 30s, configurable via client shutdown options) to prevent the
+     * process shutdown from hanging indefinitely.
+     *
+     * @returns Promise that resolves when cleanup is complete, or void for sync cleanup
+     */
+    shutdown(): Promise<void> | void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/extensions/feature-flags/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/extensions/feature-flags/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEpE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,KAAK,EAAE,kBAAkB,EAAE,CAAA;IAC3B,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;OASG;IACH,kBAAkB,IAAI,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,GAAG,uBAAuB,GAAG,SAAS,CAAA;IAExG;;;;;;;;;;;;OAYG;IACH,0BAA0B,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAExD;;;;;;;;;;;OAWG;IACH,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAE9E;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACjC"}

package/dist/extensions/feature-flags/cache.js

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/extensions/feature-flags/feature-flags.d.ts

@@ -1,5 +1,6 @@
 import { FeatureFlagCondition, PostHogFeatureFlag, PropertyGroup } from '../../types';
 import type { FeatureFlagValue, JsonType, PostHogFetchOptions, PostHogFetchResponse } from '@posthog/core';
+import { FlagDefinitionCacheProvider } from './cache';
 declare class ClientError extends Error {
     constructor(message: string);
 }
@@ -21,6 +22,7 @@ type FeatureFlagsPollerOptions = {
     customHeaders?: {
         [key: string]: string;
     };
+    cacheProvider?: FlagDefinitionCacheProvider;
 };
 declare class FeatureFlagsPoller {
     pollingInterval: number;
@@ -43,6 +45,9 @@ declare class FeatureFlagsPoller {
     shouldBeginExponentialBackoff: boolean;
     backOffCount: number;
     onLoad?: (count: number) => void;
+    private cacheProvider?;
+    private hasAttemptedCacheLoad;
+    private loadingPromise?;
     constructor({ pollingInterval, personalApiKey, projectApiKey, timeout, host, customHeaders, ...options }: FeatureFlagsPollerOptions);
     debug(enabled?: boolean): void;
     private logMsgIfDebug;
@@ -68,6 +73,15 @@ declare class FeatureFlagsPoller {
         valueMax: number;
         key: string;
     }[];
+    /**
+     * Updates the internal flag state with the provided flag data.
+     */
+    private updateFlagState;
+    /**
+     * Attempts to load flags from cache and update internal state.
+     * Returns true if flags were successfully loaded from cache, false otherwise.
+     */
+    private loadFromCache;
     loadFeatureFlags(forceReload?: boolean): Promise<void>;
     /**
      * Returns true if the feature flags poller has loaded successfully at least once and has more than 0 feature flags.
@@ -84,7 +98,7 @@ declare class FeatureFlagsPoller {
     _loadFeatureFlags(): Promise<void>;
     private getPersonalApiKeyRequestOptions;
     _requestFeatureFlagDefinitions(): Promise<PostHogFetchResponse>;
-    stopPoller(): void;
+    stopPoller(timeoutMs?: number): Promise<void>;
 }
 declare function matchProperty(property: FeatureFlagCondition['properties'][number], propertyValues: Record<string, any>, warnFunction?: (msg: string) => void): boolean;
 declare function relativeDateParseForFeatureFlagMatching(value: string): Date | null;

package/dist/extensions/feature-flags/feature-flags.d.ts.map

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

package/dist/extensions/feature-flags/feature-flags.js

@@ -68,6 +68,7 @@ class FeatureFlagsPoller {
         this.debugMode = false;
         this.shouldBeginExponentialBackoff = false;
         this.backOffCount = 0;
+        this.hasAttemptedCacheLoad = false;
         this.pollingInterval = pollingInterval;
         this.personalApiKey = personalApiKey;
         this.featureFlags = [];
@@ -83,6 +84,7 @@ class FeatureFlagsPoller {
         this.onError = options.onError;
         this.customHeaders = customHeaders;
         this.onLoad = options.onLoad;
+        this.cacheProvider = options.cacheProvider;
         this.loadFeatureFlags();
     }
     debug(enabled = true) {
@@ -270,8 +272,39 @@ class FeatureFlagsPoller {
         });
         return lookupTable;
     }
+    updateFlagState(flagData) {
+        this.featureFlags = flagData.flags;
+        this.featureFlagsByKey = flagData.flags.reduce((acc, curr)=>(acc[curr.key] = curr, acc), {});
+        this.groupTypeMapping = flagData.groupTypeMapping;
+        this.cohorts = flagData.cohorts;
+        this.loadedSuccessfullyOnce = true;
+    }
+    async loadFromCache(debugMessage) {
+        if (!this.cacheProvider) return false;
+        try {
+            const cached = await this.cacheProvider.getFlagDefinitions();
+            if (cached) {
+                this.updateFlagState(cached);
+                this.logMsgIfDebug(()=>console.debug(`[FEATURE FLAGS] ${debugMessage} (${cached.flags.length} flags)`));
+                this.onLoad?.(this.featureFlags.length);
+                return true;
+            }
+            return false;
+        } catch (err) {
+            this.onError?.(new Error(`Failed to load from cache: ${err}`));
+            return false;
+        }
+    }
     async loadFeatureFlags(forceReload = false) {
-        if (!this.loadedSuccessfullyOnce || forceReload) await this._loadFeatureFlags();
+        if (this.cacheProvider && !this.hasAttemptedCacheLoad) {
+            this.hasAttemptedCacheLoad = true;
+            await this.loadFromCache('Loaded flags from cache');
+        }
+        if (this.loadingPromise) return this.loadingPromise;
+        if (!this.loadedSuccessfullyOnce || forceReload) {
+            this.loadingPromise = this._loadFeatureFlags();
+            await this.loadingPromise;
+        }
     }
     isLocalEvaluationReady() {
         return (this.loadedSuccessfullyOnce ?? false) && (this.featureFlags?.length ?? 0) > 0;
@@ -287,6 +320,17 @@ class FeatureFlagsPoller {
         }
         this.poller = setTimeout(()=>this._loadFeatureFlags(), this.getPollingInterval());
         try {
+            let shouldFetch = true;
+            if (this.cacheProvider) try {
+                shouldFetch = await this.cacheProvider.shouldFetchFlagDefinitions();
+            } catch (err) {
+                this.onError?.(new Error(`Error in shouldFetchFlagDefinitions: ${err}`));
+            }
+            if (!shouldFetch) {
+                const loaded = await this.loadFromCache('Loaded flags from cache (skipped fetch)');
+                if (loaded) return;
+                if (this.loadedSuccessfullyOnce) return;
+            }
             const res = await this._requestFeatureFlagDefinitions();
             if (!res) return;
             switch(res.status){
@@ -313,13 +357,19 @@ class FeatureFlagsPoller {
                     {
                         const responseJson = await res.json() ?? {};
                         if (!('flags' in responseJson)) return void this.onError?.(new Error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`));
-                        this.featureFlags = responseJson.flags ?? [];
-                        this.featureFlagsByKey = this.featureFlags.reduce((acc, curr)=>(acc[curr.key] = curr, acc), {});
-                        this.groupTypeMapping = responseJson.group_type_mapping || {};
-                        this.cohorts = responseJson.cohorts || {};
-                        this.loadedSuccessfullyOnce = true;
+                        const flagData = {
+                            flags: responseJson.flags ?? [],
+                            groupTypeMapping: responseJson.group_type_mapping || {},
+                            cohorts: responseJson.cohorts || {}
+                        };
+                        this.updateFlagState(flagData);
                         this.shouldBeginExponentialBackoff = false;
                         this.backOffCount = 0;
+                        if (this.cacheProvider && shouldFetch) try {
+                            await this.cacheProvider.onFlagDefinitionsReceived(flagData);
+                        } catch (err) {
+                            this.onError?.(new Error(`Failed to store in cache: ${err}`));
+                        }
                         this.onLoad?.(this.featureFlags.length);
                         break;
                     }
@@ -328,6 +378,8 @@ class FeatureFlagsPoller {
             }
         } catch (err) {
             if (err instanceof ClientError) this.onError?.(err);
+        } finally{
+            this.loadingPromise = void 0;
         }
     }
     getPersonalApiKeyRequestOptions(method = 'GET') {
@@ -340,7 +392,7 @@ class FeatureFlagsPoller {
             }
         };
     }
-    async _requestFeatureFlagDefinitions() {
+    _requestFeatureFlagDefinitions() {
         const url = `${this.host}/api/feature_flag/local_evaluation?token=${this.projectApiKey}&send_cohorts`;
         const options = this.getPersonalApiKeyRequestOptions();
         let abortTimeout = null;
@@ -352,13 +404,22 @@ class FeatureFlagsPoller {
             options.signal = controller.signal;
         }
         try {
-            return await this.fetch(url, options);
+            return this.fetch(url, options);
         } finally{
             clearTimeout(abortTimeout);
         }
     }
-    stopPoller() {
+    async stopPoller(timeoutMs = 30000) {
         clearTimeout(this.poller);
+        if (this.cacheProvider) try {
+            const shutdownResult = this.cacheProvider.shutdown();
+            if (shutdownResult instanceof Promise) await Promise.race([
+                shutdownResult,
+                new Promise((_, reject)=>setTimeout(()=>reject(new Error(`Cache shutdown timeout after ${timeoutMs}ms`)), timeoutMs))
+            ]);
+        } catch (err) {
+            this.onError?.(new Error(`Error during cache shutdown: ${err}`));
+        }
     }
 }
 async function _hash(key, distinctId, salt = '') {

package/dist/extensions/feature-flags/feature-flags.mjs

@@ -35,6 +35,7 @@ class FeatureFlagsPoller {
         this.debugMode = false;
         this.shouldBeginExponentialBackoff = false;
         this.backOffCount = 0;
+        this.hasAttemptedCacheLoad = false;
         this.pollingInterval = pollingInterval;
         this.personalApiKey = personalApiKey;
         this.featureFlags = [];
@@ -50,6 +51,7 @@ class FeatureFlagsPoller {
         this.onError = options.onError;
         this.customHeaders = customHeaders;
         this.onLoad = options.onLoad;
+        this.cacheProvider = options.cacheProvider;
         this.loadFeatureFlags();
     }
     debug(enabled = true) {
@@ -237,8 +239,39 @@ class FeatureFlagsPoller {
         });
         return lookupTable;
     }
+    updateFlagState(flagData) {
+        this.featureFlags = flagData.flags;
+        this.featureFlagsByKey = flagData.flags.reduce((acc, curr)=>(acc[curr.key] = curr, acc), {});
+        this.groupTypeMapping = flagData.groupTypeMapping;
+        this.cohorts = flagData.cohorts;
+        this.loadedSuccessfullyOnce = true;
+    }
+    async loadFromCache(debugMessage) {
+        if (!this.cacheProvider) return false;
+        try {
+            const cached = await this.cacheProvider.getFlagDefinitions();
+            if (cached) {
+                this.updateFlagState(cached);
+                this.logMsgIfDebug(()=>console.debug(`[FEATURE FLAGS] ${debugMessage} (${cached.flags.length} flags)`));
+                this.onLoad?.(this.featureFlags.length);
+                return true;
+            }
+            return false;
+        } catch (err) {
+            this.onError?.(new Error(`Failed to load from cache: ${err}`));
+            return false;
+        }
+    }
     async loadFeatureFlags(forceReload = false) {
-        if (!this.loadedSuccessfullyOnce || forceReload) await this._loadFeatureFlags();
+        if (this.cacheProvider && !this.hasAttemptedCacheLoad) {
+            this.hasAttemptedCacheLoad = true;
+            await this.loadFromCache('Loaded flags from cache');
+        }
+        if (this.loadingPromise) return this.loadingPromise;
+        if (!this.loadedSuccessfullyOnce || forceReload) {
+            this.loadingPromise = this._loadFeatureFlags();
+            await this.loadingPromise;
+        }
     }
     isLocalEvaluationReady() {
         return (this.loadedSuccessfullyOnce ?? false) && (this.featureFlags?.length ?? 0) > 0;
@@ -254,6 +287,17 @@ class FeatureFlagsPoller {
         }
         this.poller = setTimeout(()=>this._loadFeatureFlags(), this.getPollingInterval());
         try {
+            let shouldFetch = true;
+            if (this.cacheProvider) try {
+                shouldFetch = await this.cacheProvider.shouldFetchFlagDefinitions();
+            } catch (err) {
+                this.onError?.(new Error(`Error in shouldFetchFlagDefinitions: ${err}`));
+            }
+            if (!shouldFetch) {
+                const loaded = await this.loadFromCache('Loaded flags from cache (skipped fetch)');
+                if (loaded) return;
+                if (this.loadedSuccessfullyOnce) return;
+            }
             const res = await this._requestFeatureFlagDefinitions();
             if (!res) return;
             switch(res.status){
@@ -280,13 +324,19 @@ class FeatureFlagsPoller {
                     {
                         const responseJson = await res.json() ?? {};
                         if (!('flags' in responseJson)) return void this.onError?.(new Error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`));
-                        this.featureFlags = responseJson.flags ?? [];
-                        this.featureFlagsByKey = this.featureFlags.reduce((acc, curr)=>(acc[curr.key] = curr, acc), {});
-                        this.groupTypeMapping = responseJson.group_type_mapping || {};
-                        this.cohorts = responseJson.cohorts || {};
-                        this.loadedSuccessfullyOnce = true;
+                        const flagData = {
+                            flags: responseJson.flags ?? [],
+                            groupTypeMapping: responseJson.group_type_mapping || {},
+                            cohorts: responseJson.cohorts || {}
+                        };
+                        this.updateFlagState(flagData);
                         this.shouldBeginExponentialBackoff = false;
                         this.backOffCount = 0;
+                        if (this.cacheProvider && shouldFetch) try {
+                            await this.cacheProvider.onFlagDefinitionsReceived(flagData);
+                        } catch (err) {
+                            this.onError?.(new Error(`Failed to store in cache: ${err}`));
+                        }
                         this.onLoad?.(this.featureFlags.length);
                         break;
                     }
@@ -295,6 +345,8 @@ class FeatureFlagsPoller {
             }
         } catch (err) {
             if (err instanceof ClientError) this.onError?.(err);
+        } finally{
+            this.loadingPromise = void 0;
         }
     }
     getPersonalApiKeyRequestOptions(method = 'GET') {
@@ -307,7 +359,7 @@ class FeatureFlagsPoller {
             }
         };
     }
-    async _requestFeatureFlagDefinitions() {
+    _requestFeatureFlagDefinitions() {
         const url = `${this.host}/api/feature_flag/local_evaluation?token=${this.projectApiKey}&send_cohorts`;
         const options = this.getPersonalApiKeyRequestOptions();
         let abortTimeout = null;
@@ -319,13 +371,22 @@ class FeatureFlagsPoller {
             options.signal = controller.signal;
         }
         try {
-            return await this.fetch(url, options);
+            return this.fetch(url, options);
         } finally{
             clearTimeout(abortTimeout);
         }
     }
-    stopPoller() {
+    async stopPoller(timeoutMs = 30000) {
         clearTimeout(this.poller);
+        if (this.cacheProvider) try {
+            const shutdownResult = this.cacheProvider.shutdown();
+            if (shutdownResult instanceof Promise) await Promise.race([
+                shutdownResult,
+                new Promise((_, reject)=>setTimeout(()=>reject(new Error(`Cache shutdown timeout after ${timeoutMs}ms`)), timeoutMs))
+            ]);
+        } catch (err) {
+            this.onError?.(new Error(`Error during cache shutdown: ${err}`));
+        }
     }
 }
 async function _hash(key, distinctId, salt = '') {

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { PostHogCoreOptions, FeatureFlagValue, JsonType, PostHogFetchOptions, PostHogFetchResponse } from '@posthog/core';
+import type { FlagDefinitionCacheProvider } from './extensions/feature-flags/cache';
 export interface IdentifyMessage {
     distinctId: string;
     properties?: Record<string | number, any>;
@@ -52,6 +53,32 @@ export type PostHogOptions = PostHogCoreOptions & {
     maxCacheSize?: number;
     fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
     enableLocalEvaluation?: boolean;
+    /**
+     * @experimental This API is experimental and may change in minor versions.
+     *
+     * Optional cache provider for feature flag definitions.
+     *
+     * Allows custom caching strategies (Redis, database, etc.) for flag definitions
+     * in multi-worker environments. If not provided, defaults to in-memory cache.
+     *
+     * This enables distributed coordination where only one worker fetches flags while
+     * others use cached data, reducing API calls and improving performance.
+     *
+     * @example
+     * ```typescript
+     * import { FlagDefinitionCacheProvider } from 'posthog-node/experimental'
+     *
+     * class RedisCacheProvider implements FlagDefinitionCacheProvider {
+     *   // ... implementation
+     * }
+     *
+     * const client = new PostHog('api-key', {
+     *   personalApiKey: 'personal-key',
+     *   flagDefinitionCacheProvider: new RedisCacheProvider(redis)
+     * })
+     * ```
+     */
+    flagDefinitionCacheProvider?: FlagDefinitionCacheProvider;
     /**
      * Allows modification or dropping of events before they're sent to PostHog.
      * If an array is provided, the functions are run in order.

package/dist/types.d.ts.map

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

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "5.11.2";
+export declare const version = "5.12.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     version: ()=>version
 });
-const version = '5.11.2';
+const version = '5.12.0';
 exports.version = __webpack_exports__.version;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "version"

package/dist/version.mjs

@@ -1,2 +1,2 @@
-const version = '5.11.2';
+const version = '5.12.0';
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "5.11.2",
+  "version": "5.12.0",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "jest": "^29.7.0",
+    "@types/jest": "^29.5.0",
     "@rslib/core": "^0.10.5",
     "@posthog-tooling/tsconfig-base": "1.0.0"
   },
@@ -64,6 +65,9 @@
       },
       "import": "./dist/entrypoints/index.node.mjs",
       "require": "./dist/entrypoints/index.node.js"
+    },
+    "./experimental": {
+      "types": "./dist/experimental.d.ts"
     }
   },
   "scripts": {

package/src/client.ts

@@ -112,6 +112,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
             this._events.emit('localEvaluationFlagsLoaded', count)
           },
           customHeaders: this.getCustomHeaders(),
+          cacheProvider: options.flagDefinitionCacheProvider,
         })
       }
     }
@@ -1179,7 +1180,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @returns Promise that resolves when shutdown is complete
    */
   async _shutdown(shutdownTimeoutMs?: number): Promise<void> {
-    this.featureFlagsPoller?.stopPoller()
+    this.featureFlagsPoller?.stopPoller(shutdownTimeoutMs)
     this.errorTracking.shutdown()
     return super._shutdown(shutdownTimeoutMs)
   }

package/src/experimental.ts

@@ -0,0 +1,11 @@
+/**
+ * Experimental APIs
+ *
+ * This module exports experimental features that may change or be removed in minor versions.
+ * Use these APIs with caution and be prepared for breaking changes.
+ *
+ * @packageDocumentation
+ * @experimental
+ */
+
+export type { FlagDefinitionCacheProvider, FlagDefinitionCacheData } from './extensions/feature-flags/cache'

package/src/extensions/feature-flags/cache.ts

@@ -0,0 +1,114 @@
+import type { PostHogFeatureFlag, PropertyGroup } from '../../types'
+
+/**
+ * Represents the complete set of feature flag data needed for local evaluation.
+ *
+ * This includes flag definitions, group type mappings, and cohort property groups.
+ */
+export interface FlagDefinitionCacheData {
+  /** Array of feature flag definitions */
+  flags: PostHogFeatureFlag[]
+  /** Mapping of group type index to group name */
+  groupTypeMapping: Record<string, string>
+  /** Cohort property groups for local evaluation */
+  cohorts: Record<string, PropertyGroup>
+}
+
+/**
+ * @experimental This API is experimental and may change in minor versions.
+ *
+ * Provider interface for caching feature flag definitions.
+ *
+ * Implementations can use this to control when flag definitions are fetched
+ * and how they're cached (Redis, database, filesystem, etc.).
+ *
+ * This interface is designed for server-side environments where multiple workers
+ * need to share flag definitions and coordinate fetching to reduce API calls.
+ *
+ * All methods may throw errors - the poller will catch and log them gracefully,
+ * ensuring cache provider errors never break flag evaluation.
+ *
+ * @example
+ * ```typescript
+ * import { FlagDefinitionCacheProvider } from 'posthog-node/experimental'
+ *
+ * class RedisFlagCache implements FlagDefinitionCacheProvider {
+ *   constructor(private redis: Redis, private teamKey: string) { }
+ *
+ *   async getFlagDefinitions(): Promise<FlagDefinitionCacheData | undefined> {
+ *     const cached = await this.redis.get(`posthog:flags:${this.teamKey}`)
+ *     return cached ? JSON.parse(cached) : undefined
+ *   }
+ *
+ *   async shouldFetchFlagDefinitions(): Promise<boolean> {
+ *     // Acquire distributed lock - only one worker fetches
+ *     const acquired = await this.redis.set(`posthog:flags:${this.teamKey}:lock`, '1', 'EX', 60, 'NX')
+ *     return acquired === 'OK'
+ *   }
+ *
+ *   async onFlagDefinitionsReceived(data: FlagDefinitionCacheData): Promise<void> {
+ *     await this.redis.set(`posthog:flags:${this.teamKey}`, JSON.stringify(data), 'EX', 300)
+ *     await this.redis.del(`posthog:flags:${this.teamKey}:lock`)
+ *   }
+ *
+ *   async shutdown(): Promise<void> {
+ *     await this.redis.del(`posthog:flags:${this.teamKey}:lock`)
+ *   }
+ * }
+ * ```
+ */
+export interface FlagDefinitionCacheProvider {
+  /**
+   * Retrieve cached flag definitions.
+   *
+   * Called when the poller is refreshing in-memory flag definitions. If this returns undefined
+   * (or throws an error), the poller will fetch fresh data from the PostHog API if no flag
+   * definitions are in memory. Otherwise, stale cache data is used until the next poll cycle.
+   *
+   * @returns cached definitions if available, undefined if cache is empty
+   * @throws if an error occurs while accessing the cache (error will be logged)
+   */
+  getFlagDefinitions(): Promise<FlagDefinitionCacheData | undefined> | FlagDefinitionCacheData | undefined
+
+  /**
+   * Determines whether this instance should fetch new flag definitions.
+   *
+   * Use this to implement distributed coordination (e.g., via distributed locks)
+   * to ensure only one instance fetches at a time in a multi-worker setup.
+   *
+   * When multiple workers share a cache, typically only one should fetch while
+   * others use cached data. Implementations can use Redis locks, database locks,
+   * or other coordination mechanisms.
+   *
+   * @returns true if this instance should fetch, false to skip and read cache
+   * @throws if coordination backend is unavailable (error will be logged, fetch continues)
+   */
+  shouldFetchFlagDefinitions(): Promise<boolean> | boolean
+
+  /**
+   * Called after successfully receiving new flag definitions from PostHog.
+   *
+   * Store the definitions in your cache backend here. This is called only
+   * after a successful API response with valid flag data.
+   *
+   * If this method throws, the error is logged but flag definitions are still
+   * stored in memory, ensuring local evaluation can still be performed.
+   *
+   * @param data - The complete flag definition data from PostHog
+   * @throws if storage backend is unavailable (error will be logged)
+   */
+  onFlagDefinitionsReceived(data: FlagDefinitionCacheData): Promise<void> | void
+
+  /**
+   * Called when the PostHog client shuts down.
+   *
+   * Release any held locks, close connections, or clean up resources here.
+   *
+   * Both sync and async cleanup are supported. Async cleanup has a timeout
+   * (default 30s, configurable via client shutdown options) to prevent the
+   * process shutdown from hanging indefinitely.
+   *
+   * @returns Promise that resolves when cleanup is complete, or void for sync cleanup
+   */
+  shutdown(): Promise<void> | void
+}

package/src/extensions/feature-flags/feature-flags.ts

@@ -2,6 +2,7 @@ import { FeatureFlagCondition, FlagProperty, FlagPropertyValue, PostHogFeatureFl
 import type { FeatureFlagValue, JsonType, PostHogFetchOptions, PostHogFetchResponse } from '@posthog/core'
 import { safeSetTimeout } from '@posthog/core'
 import { hashSHA1 } from './crypto'
+import { FlagDefinitionCacheProvider, FlagDefinitionCacheData } from './cache'
 
 const SIXTY_SECONDS = 60 * 1000
 
@@ -53,6 +54,7 @@ type FeatureFlagsPollerOptions = {
   onError?: (error: Error) => void
   onLoad?: (count: number) => void
   customHeaders?: { [key: string]: string }
+  cacheProvider?: FlagDefinitionCacheProvider
 }
 
 class FeatureFlagsPoller {
@@ -74,6 +76,9 @@ class FeatureFlagsPoller {
   shouldBeginExponentialBackoff: boolean = false
   backOffCount: number = 0
   onLoad?: (count: number) => void
+  private cacheProvider?: FlagDefinitionCacheProvider
+  private hasAttemptedCacheLoad: boolean = false
+  private loadingPromise?: Promise<void>
 
   constructor({
     pollingInterval,
@@ -99,6 +104,7 @@ class FeatureFlagsPoller {
     this.onError = options.onError
     this.customHeaders = customHeaders
     this.onLoad = options.onLoad
+    this.cacheProvider = options.cacheProvider
     void this.loadFeatureFlags()
   }
 
@@ -537,9 +543,59 @@ class FeatureFlagsPoller {
     return lookupTable
   }
 
+  /**
+   * Updates the internal flag state with the provided flag data.
+   */
+  private updateFlagState(flagData: FlagDefinitionCacheData): void {
+    this.featureFlags = flagData.flags
+    this.featureFlagsByKey = flagData.flags.reduce(
+      (acc, curr) => ((acc[curr.key] = curr), acc),
+      <Record<string, PostHogFeatureFlag>>{}
+    )
+    this.groupTypeMapping = flagData.groupTypeMapping
+    this.cohorts = flagData.cohorts
+    this.loadedSuccessfullyOnce = true
+  }
+
+  /**
+   * Attempts to load flags from cache and update internal state.
+   * Returns true if flags were successfully loaded from cache, false otherwise.
+   */
+  private async loadFromCache(debugMessage: string): Promise<boolean> {
+    if (!this.cacheProvider) {
+      return false
+    }
+
+    try {
+      const cached = await this.cacheProvider.getFlagDefinitions()
+      if (cached) {
+        this.updateFlagState(cached)
+        this.logMsgIfDebug(() => console.debug(`[FEATURE FLAGS] ${debugMessage} (${cached.flags.length} flags)`))
+        this.onLoad?.(this.featureFlags.length)
+        return true
+      }
+      return false
+    } catch (err) {
+      this.onError?.(new Error(`Failed to load from cache: ${err}`))
+      return false
+    }
+  }
+
   async loadFeatureFlags(forceReload = false): Promise<void> {
+    // On first load, try to initialize from cache (if a cache provider is configured)
+    if (this.cacheProvider && !this.hasAttemptedCacheLoad) {
+      this.hasAttemptedCacheLoad = true
+      await this.loadFromCache('Loaded flags from cache')
+    }
+
+    // If a fetch is already in progress, wait for it
+    if (this.loadingPromise) {
+      return this.loadingPromise
+    }
+
     if (!this.loadedSuccessfullyOnce || forceReload) {
-      await this._loadFeatureFlags()
+      this.loadingPromise = this._loadFeatureFlags()
+      await this.loadingPromise
     }
   }
 
@@ -574,6 +630,42 @@ class FeatureFlagsPoller {
     this.poller = setTimeout(() => this._loadFeatureFlags(), this.getPollingInterval())
 
     try {
+      let shouldFetch = true
+      if (this.cacheProvider) {
+        try {
+          shouldFetch = await this.cacheProvider.shouldFetchFlagDefinitions()
+        } catch (err) {
+          this.onError?.(new Error(`Error in shouldFetchFlagDefinitions: ${err}`))
+          // Important: if `shouldFetchFlagDefinitions` throws, we
+          // default to fetching.
+        }
+      }
+
+      if (!shouldFetch) {
+        // If we're not supposed to fetch, we assume another instance
+        // is handling it. In this case, we'll just reload from cache.
+        const loaded = await this.loadFromCache('Loaded flags from cache (skipped fetch)')
+        if (loaded) {
+          return
+        }
+
+        if (this.loadedSuccessfullyOnce) {
+          // Respect the decision to not fetch, even if it means
+          // keeping stale feature flags.
+          return
+        }
+
+        // If we've gotten here:
+        // - A cache provider is configured
+        // - We've been asked not to fetch
+        // - We failed to load from cache
+        // - We have no feature flag definitions to work with.
+        //
+        // This is the only case where we'll ignore the shouldFetch
+        // decision and proceed to fetch, because the alternative is
+        // worse: local evaluation is impossible.
+      }
+
       const res = await this._requestFeatureFlagDefinitions()
 
       // Handle undefined res case, this shouldn't happen, but it doesn't hurt to handle it anyway
@@ -637,16 +729,28 @@ class FeatureFlagsPoller {
             return
           }
 
-          this.featureFlags = (responseJson.flags as PostHogFeatureFlag[]) ?? []
-          this.featureFlagsByKey = this.featureFlags.reduce(
-            (acc, curr) => ((acc[curr.key] = curr), acc),
-            <Record<string, PostHogFeatureFlag>>{}
-          )
-          this.groupTypeMapping = (responseJson.group_type_mapping as Record<string, string>) || {}
-          this.cohorts = (responseJson.cohorts as Record<string, PropertyGroup>) || {}
-          this.loadedSuccessfullyOnce = true
+          const flagData: FlagDefinitionCacheData = {
+            flags: (responseJson.flags as PostHogFeatureFlag[]) ?? [],
+            groupTypeMapping: (responseJson.group_type_mapping as Record<string, string>) || {},
+            cohorts: (responseJson.cohorts as Record<string, PropertyGroup>) || {},
+          }
+
+          this.updateFlagState(flagData)
           this.shouldBeginExponentialBackoff = false
           this.backOffCount = 0
+
+          if (this.cacheProvider && shouldFetch) {
+            // Only notify the cache if it's actually expecting new data
+            // E.g., if we weren't supposed to fetch but we missed the
+            // cache, we may not have a lock, so we skip this step
+            try {
+              await this.cacheProvider.onFlagDefinitionsReceived(flagData)
+            } catch (err) {
+              this.onError?.(new Error(`Failed to store in cache: ${err}`))
+              // Continue anyway, the data at least made it to memory
+            }
+          }
+
           this.onLoad?.(this.featureFlags.length)
           break
         }
@@ -660,6 +764,8 @@ class FeatureFlagsPoller {
       if (err instanceof ClientError) {
         this.onError?.(err)
       }
+    } finally {
+      this.loadingPromise = undefined
     }
   }
 
@@ -674,7 +780,7 @@ class FeatureFlagsPoller {
     }
   }
 
-  async _requestFeatureFlagDefinitions(): Promise<PostHogFetchResponse> {
+  _requestFeatureFlagDefinitions(): Promise<PostHogFetchResponse> {
     const url = `${this.host}/api/feature_flag/local_evaluation?token=${this.projectApiKey}&send_cohorts`
 
     const options = this.getPersonalApiKeyRequestOptions()
@@ -690,14 +796,34 @@ class FeatureFlagsPoller {
     }
 
     try {
-      return await this.fetch(url, options)
+      return this.fetch(url, options)
     } finally {
       clearTimeout(abortTimeout)
     }
   }
 
-  stopPoller(): void {
+  async stopPoller(timeoutMs: number = 30000): Promise<void> {
     clearTimeout(this.poller)
+
+    if (this.cacheProvider) {
+      try {
+        const shutdownResult = this.cacheProvider.shutdown()
+
+        if (shutdownResult instanceof Promise) {
+          // This follows the same timeout logic defined in _shutdown.
+          // We time out after some period of time to avoid hanging the entire
+          // shutdown process if the cache provider misbehaves.
+          await Promise.race([
+            shutdownResult,
+            new Promise((_, reject) =>
+              setTimeout(() => reject(new Error(`Cache shutdown timeout after ${timeoutMs}ms`)), timeoutMs)
+            ),
+          ])
+        }
+      } catch (err) {
+        this.onError?.(new Error(`Error during cache shutdown: ${err}`))
+      }
+    }
   }
 }
 

package/src/types.ts

@@ -6,6 +6,8 @@ import type {
   PostHogFetchResponse,
 } from '@posthog/core'
 
+import type { FlagDefinitionCacheProvider } from './extensions/feature-flags/cache'
+
 export interface IdentifyMessage {
   distinctId: string
   properties?: Record<string | number, any>
@@ -72,6 +74,32 @@ export type PostHogOptions = PostHogCoreOptions & {
   // Whether to enable feature flag polling for local evaluation by default. Defaults to true when personalApiKey is provided.
   // We recommend setting this to false if you are only using the personalApiKey for evaluating remote config payloads via `getRemoteConfigPayload` and not using local evaluation.
   enableLocalEvaluation?: boolean
+  /**
+   * @experimental This API is experimental and may change in minor versions.
+   *
+   * Optional cache provider for feature flag definitions.
+   *
+   * Allows custom caching strategies (Redis, database, etc.) for flag definitions
+   * in multi-worker environments. If not provided, defaults to in-memory cache.
+   *
+   * This enables distributed coordination where only one worker fetches flags while
+   * others use cached data, reducing API calls and improving performance.
+   *
+   * @example
+   * ```typescript
+   * import { FlagDefinitionCacheProvider } from 'posthog-node/experimental'
+   *
+   * class RedisCacheProvider implements FlagDefinitionCacheProvider {
+   *   // ... implementation
+   * }
+   *
+   * const client = new PostHog('api-key', {
+   *   personalApiKey: 'personal-key',
+   *   flagDefinitionCacheProvider: new RedisCacheProvider(redis)
+   * })
+   * ```
+   */
+  flagDefinitionCacheProvider?: FlagDefinitionCacheProvider
   /**
    * Allows modification or dropping of events before they're sent to PostHog.
    * If an array is provided, the functions are run in order.

package/src/version.ts

@@ -1 +1 @@
-export const version = '5.11.2'
+export const version = '5.12.0'