@posthog/convex 0.2.33 → 1.0.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img alt="@posthog/convex" src="https://raw.githubusercontent.com/PostHog/posthog/master/frontend/public/hedgehog/heart-hog.png" width="200">
+  <img alt="@posthog/convex" src="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/posthog_convex_c017c269f8.png" width="500">
 </p>
 
 <h1 align="center">@posthog/convex</h1>
@@ -10,14 +10,12 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@posthog/convex"><img src="https://badge.fury.io/js/@posthog%2Fconvex.svg" alt="npm version"></a>
+  <a href="https://www.convex.dev/components/posthog/convex"><img src="https://www.convex.dev/components/badge/posthog/convex" alt="Convex Component"></a>
 </p>
 
-> [!WARNING]
-> This package is in alpha and under active development. APIs may change between releases.
-
 ## 🦔 What is this?
 
-The official [PostHog](https://posthog.com) component for [Convex](https://convex.dev). Capture events, identify users, manage groups, and evaluate feature flags — all from your mutations and actions.
+The official [PostHog](https://posthog.com) component for [Convex](https://convex.dev). Capture events, identify users, manage groups, and evaluate feature flags — all from your queries, mutations, and actions.
 
 Found a bug? Feature request? [File it here](https://github.com/PostHog/posthog-js/issues).
 
@@ -42,32 +40,63 @@ app.use(posthog);
 export default app;
 ```
 
-Set your PostHog API key and host:
+Set your PostHog credentials on your Convex deployment:
 
 ```sh
 npx convex env set POSTHOG_API_KEY phc_your_project_api_key
 npx convex env set POSTHOG_HOST https://us.i.posthog.com
 ```
 
-Create a `convex/posthog.ts` file to initialize the client:
+To enable local feature flag evaluation, also set a [feature flags secure API key](https://posthog.com/docs/feature-flags/local-evaluation#step-1-find-your-feature-flags-secure-api-key) (`phs_…`) with read access to feature flags:
+
+```sh
+npx convex env set POSTHOG_PERSONAL_API_KEY phs_your_feature_flags_secure_api_key
+```
+
+> Personal API keys (`phx_…`) also still work for local evaluation, but PostHog recommends the project-scoped feature flags secure API key going forward.
+
+Create a `convex/posthog.ts` file to initialize the client. Read the keys from `process.env` and pass them to the constructor — the client captures them and forwards them to component actions as needed:
 
 ```ts
 // convex/posthog.ts
 import { PostHog } from "@posthog/convex";
 import { components } from "./_generated/api";
 
-export const posthog = new PostHog(components.posthog);
+export const posthog = new PostHog(components.posthog, {
+  apiKey: process.env.POSTHOG_API_KEY,
+  personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
+  host: process.env.POSTHOG_HOST,
+});
 ```
 
-You can also pass the API key and host explicitly:
+Schedule a cron in your own `convex/crons.ts` that refreshes the flag definitions on whatever interval suits you. The client class captures the keys you passed in `posthog.ts` and forwards them automatically:
 
 ```ts
-export const posthog = new PostHog(components.posthog, {
-  apiKey: "phc_...",
-  host: "https://eu.i.posthog.com",
+// convex/crons.ts
+import { cronJobs } from "convex/server";
+import { internalAction } from "./_generated/server";
+import { internal } from "./_generated/api";
+import { posthog } from "./posthog";
+
+export const refreshPosthogFlags = internalAction({
+  args: {},
+  handler: async (ctx) => {
+    await posthog.refreshFlagDefinitions(ctx);
+  },
 });
+
+const crons = cronJobs();
+crons.interval(
+  "refresh posthog feature flag definitions",
+  { minutes: 1 },
+  internal.crons.refreshPosthogFlags
+);
+
+export default crons;
 ```
 
+That's the whole setup — feature flag methods will start returning live values on the next cron tick, or you can call `posthog.refreshFlagDefinitions(ctx)` from an action whenever you want an immediate refresh.
+
 ## 📊 Capturing Events
 
 Import `posthog` from your setup file and call methods directly:
@@ -143,11 +172,35 @@ await posthog.alias(ctx, {
 });
 ```
 
+### captureException
+
+Send an exception to PostHog's error tracking pipeline. Accepts an `Error`, a string, or any object with a `message` field.
+
+```ts
+try {
+  await chargeCard(...);
+} catch (error) {
+  await posthog.captureException(ctx, {
+    error,
+    distinctId: "user_123",
+    additionalProperties: { plan: "pro" },
+  });
+  throw error;
+}
+```
+
+If you'd rather have **every** uncaught error from your Convex deployment forwarded to PostHog automatically — including ones you didn't explicitly wrap — wire up Convex's first-party PostHog exception reporting integration from the Convex dashboard. Setup lives at [docs.convex.dev/production/integrations/exception-reporting#configuring-posthog-error-tracking](https://docs.convex.dev/production/integrations/exception-reporting#configuring-posthog-error-tracking). Use `captureException` here for cases where you want explicit control (e.g. attaching custom `additionalProperties`); use the Convex-side integration for catch-all coverage.
+
 All of the above methods schedule the PostHog API call asynchronously via `ctx.scheduler.runAfter`, so they return immediately without blocking your mutation or action.
 
 ## 🚩 Feature Flags
 
-Feature flag methods evaluate flags by calling the PostHog API and returning the result. They require an **action** context (they use `ctx.runAction` internally).
+Two evaluation paths, pick the one that fits the flag:
+
+- **Local** (`getFeatureFlag`, `isFeatureEnabled`, …) — evaluates against definitions cached by the cron. Works in **queries, mutations, and actions**, no per-call network round-trip, reactive (a query reading a flag re-runs when definitions change). Requires `POSTHOG_PERSONAL_API_KEY`. Can't handle every flag — see [the limitations](#local-evaluation--limitations) below.
+- **Remote** (`evaluateFlag`, `evaluateFlagPayload`, `evaluateAllFlags`) — hits PostHog's `/flags` endpoint directly. Action-context only, no `personalApiKey` needed, handles every flag.
+
+The local methods are documented first; remote is at the bottom of this section.
 
 ### getFeatureFlag
 
@@ -155,10 +208,10 @@ Get a flag's value.
 
 ```ts
 import { posthog } from "./posthog";
-import { action } from "./_generated/server";
+import { query } from "./_generated/server";
 import { v } from "convex/values";
 
-export const getDiscount = action({
+export const getDiscount = query({
   args: { userId: v.string() },
   handler: async (ctx, args) => {
     const flag = await posthog.getFeatureFlag(ctx, {
@@ -231,7 +284,70 @@ const { featureFlags, featureFlagPayloads } =
   });
 ```
 
-All feature flag methods accept optional `groups`, `personProperties`, `groupProperties`, `sendFeatureFlagEvents`, and `disableGeoip` options. `getAllFlags` and `getAllFlagsAndPayloads` also accept `flagKeys` to filter which flags to evaluate.
+All feature flag methods accept optional `groups`, `personProperties`, `groupProperties`, and `disableGeoip` options. `getAllFlags` and `getAllFlagsAndPayloads` also accept `flagKeys` to filter which flags to evaluate.
+
+### Local evaluation — limitations
+
+Local eval can't reach a verdict for every flag, and for those this component will return `null`. The cases:
+
+- **Experience continuity flags.** Flags with [persist across authentication steps](https://posthog.com/docs/feature-flags/creating-feature-flags#persisting-feature-flags-across-authentication-steps) need server-side anon→identified tracking and aren't included in local eval.
+- **Static cohorts.** Cohort membership for static cohorts lives only on the server.
+- **Properties not passed in.** Local eval can only see what you give it. If a flag targets `email` or `$browser_version` and you don't pass those in `personProperties`, it can't resolve.
+- **Cohorts that don't fit the local-eval shape.** Cohorts with variant overrides, non-person properties, more than one cohort in the same flag definition, nested AND/OR filters, or grouped with other conditions can't be translated for local eval. See [the PostHog docs](https://posthog.com/docs/feature-flags/local-evaluation#dynamic-cohort-restrictions) for the full list.
+
+Local eval doesn't fire `$feature_flag_called` events. PostHog Experiments counts exposures off these — `posthog-node` emits them automatically on every local eval, but this component can't do the same: Convex queries are pure functions, so they can't schedule a `capture` from inside the eval path without breaking Convex's contract. If you're running an experiment against a locally-evaluated flag, fire one manually from a mutation or action:
+
+```ts
+await posthog.capture(ctx, {
+  event: "$feature_flag_called",
+  distinctId: userId,
+  properties: {
+    $feature_flag: "flag-key",
+    $feature_flag_response: value,
+    locally_evaluated: true,
+  },
+});
+```
+
+There are also reasons you might *not want* local eval at all, even when it's possible:
+
+- **Low-traffic projects.** PostHog bills each `/flags/definitions` poll as 10 flag-request equivalents. For projects that evaluate fewer flags than that per polling interval, remote evaluation is cheaper.
+- **Need-it-now changes.** Local eval accepts up to one polling interval of staleness (default 1 minute with our cron). For flags that must flip in well under that, you want remote eval.
+- **No personal API key.** If you don't want to set `POSTHOG_PERSONAL_API_KEY`, the local methods aren't useful — there's nothing for them to read.
+
+For any of those, use the remote-eval methods below instead.
+
+### Remote evaluation
+
+Sibling methods that hit PostHog's `/flags` endpoint directly. They require an **action** context (each call is a network round trip) and don't need `personalApiKey`. They handle every case local eval can't.
+
+```ts
+import { posthog } from "./posthog";
+import { action } from "./_generated/server";
+import { v } from "convex/values";
+
+export const getContinuityFlag = action({
+  args: { userId: v.string() },
+  handler: async (ctx, args) => {
+    const value = await posthog.evaluateFlag(ctx, {
+      key: "my-experience-continuity-flag",
+      distinctId: args.userId,
+      personProperties: { plan: "pro" },
+    });
+    return value;
+  },
+});
+```
+
+Three methods:
+
+| Method | Returns |
+| --- | --- |
+| `posthog.evaluateFlag(ctx, args)` | `FeatureFlagValue \| null` |
+| `posthog.evaluateFlagPayload(ctx, args)` | `JsonType \| null` |
+| `posthog.evaluateAllFlags(ctx, args)` | `{ featureFlags, featureFlagPayloads }` |
+
+Same option shape as the local methods (`groups`, `personProperties`, `groupProperties`, `disableGeoip`, `flagKeys` on the all-flags variant). Pick local when the flag is suitable and the cost of `/flags/definitions` polling is justified; pick remote when it isn't.
 
 ## 📦 Example
 

package/dist/client/feature-flags/crypto.d.ts

@@ -0,0 +1,2 @@
+export declare function hashSHA1(text: string): Promise<string>;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/client/feature-flags/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/client/feature-flags/crypto.ts"],"names":[],"mappings":"AAEA,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS5D"}

package/dist/client/feature-flags/crypto.js

@@ -0,0 +1,11 @@
+/// <reference lib="dom" />
+export async function hashSHA1(text) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error('SubtleCrypto API not available');
+    }
+    const hashBuffer = await subtle.digest('SHA-1', new TextEncoder().encode(text));
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+//# sourceMappingURL=crypto.js.map

package/dist/client/feature-flags/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../../src/client/feature-flags/crypto.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAE3B,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAA;IACxC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;IACnD,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/E,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC,CAAA;IACxD,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAC7E,CAAC"}

package/dist/client/feature-flags/evaluator.d.ts

@@ -0,0 +1,47 @@
+import type { FeatureFlagEvaluationContext, FeatureFlagValue, FlagDefinitions, JsonType, PostHogFeatureFlag } from './types.js';
+export type EvaluationResult = {
+    value: FeatureFlagValue;
+    payload: JsonType | null;
+};
+export declare class LocalFeatureFlagEvaluator {
+    readonly flags: PostHogFeatureFlag[];
+    readonly flagsByKey: Record<string, PostHogFeatureFlag>;
+    readonly groupTypeMapping: Record<string, string>;
+    readonly cohorts: FlagDefinitions['cohorts'];
+    debugMode: boolean;
+    constructor(definitions: FlagDefinitions);
+    debug(enabled?: boolean): void;
+    private logMsgIfDebug;
+    private createEvaluationContext;
+    /**
+     * Evaluate a single flag locally. Returns the value or `undefined` if eval was inconclusive.
+     * `undefined` means the caller has no way to determine the flag value locally — typically
+     * because the flag uses experience continuity, a static cohort, or properties that weren't
+     * provided.
+     */
+    getFeatureFlag(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, any>, groupProperties?: Record<string, Record<string, any>>): Promise<FeatureFlagValue | undefined>;
+    getFeatureFlagResult(key: string, distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, any>, groupProperties?: Record<string, Record<string, any>>): Promise<EvaluationResult | undefined>;
+    /**
+     * Returns the payload for a flag value, or `null` when the flag is unknown / evaluated to a
+     * non-matching value / has no payload configured. Returns `undefined` when the flag couldn't
+     * be evaluated locally — mirroring `getFeatureFlag` so callers can tell apart "no payload"
+     * from "eval unavailable".
+     */
+    getFeatureFlagPayload(key: string, distinctId: string, matchValue: FeatureFlagValue | undefined, groups?: Record<string, string>, personProperties?: Record<string, any>, groupProperties?: Record<string, Record<string, any>>): Promise<JsonType | null | undefined>;
+    getAllFlagsAndPayloads(distinctId: string, groups?: Record<string, string>, personProperties?: Record<string, any>, groupProperties?: Record<string, Record<string, any>>, flagKeys?: string[]): Promise<{
+        featureFlags: Record<string, FeatureFlagValue>;
+        featureFlagPayloads: Record<string, JsonType>;
+    }>;
+    computeFlagAndPayloadLocally(flag: PostHogFeatureFlag, ctx: FeatureFlagEvaluationContext, options?: {
+        matchValue?: FeatureFlagValue;
+    }): Promise<EvaluationResult>;
+    private computeFlagValueLocally;
+    private getBucketingValueForFlag;
+    private getPayloadForValue;
+    private evaluateFlagDependency;
+    private matchFeatureFlagProperties;
+    private isConditionMatch;
+    private getMatchingVariant;
+    private variantLookupTable;
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/client/feature-flags/evaluator.d.ts.map

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

package/dist/client/feature-flags/evaluator.js

@@ -0,0 +1,346 @@
+import { hashSHA1 } from './crypto.js';
+import { InconclusiveMatchError, RequiresServerEvaluation, matchCohort, matchProperty } from './match-property.js';
+// Matches posthog-node's hashing constant exactly; the value is larger than Number.MAX_SAFE_INTEGER
+// by design and we don't want the no-loss-of-precision rule to coerce it to a different number.
+// eslint-disable-next-line no-loss-of-precision
+const LONG_SCALE = 0xfffffffffffffff;
+async function _hash(key, bucketingValue, salt = '') {
+    const hashString = await hashSHA1(`${key}.${bucketingValue}${salt}`);
+    return parseInt(hashString.slice(0, 15), 16) / LONG_SCALE;
+}
+export class LocalFeatureFlagEvaluator {
+    flags;
+    flagsByKey;
+    groupTypeMapping;
+    cohorts;
+    debugMode = false;
+    constructor(definitions) {
+        this.flags = definitions.flags ?? [];
+        this.flagsByKey = this.flags.reduce((acc, flag) => {
+            acc[flag.key] = flag;
+            return acc;
+        }, {});
+        this.groupTypeMapping = definitions.groupTypeMapping ?? {};
+        this.cohorts = definitions.cohorts ?? {};
+    }
+    debug(enabled = true) {
+        this.debugMode = enabled;
+    }
+    logMsgIfDebug(fn) {
+        if (this.debugMode)
+            fn();
+    }
+    createEvaluationContext(distinctId, groups = {}, personProperties = {}, groupProperties = {}) {
+        return { distinctId, groups, personProperties, groupProperties, evaluationCache: {} };
+    }
+    /**
+     * Evaluate a single flag locally. Returns the value or `undefined` if eval was inconclusive.
+     * `undefined` means the caller has no way to determine the flag value locally — typically
+     * because the flag uses experience continuity, a static cohort, or properties that weren't
+     * provided.
+     */
+    async getFeatureFlag(key, distinctId, groups = {}, personProperties = {}, groupProperties = {}) {
+        const flag = this.flagsByKey[key];
+        if (flag === undefined)
+            return undefined;
+        const ctx = this.createEvaluationContext(distinctId, groups, personProperties, groupProperties);
+        try {
+            const { value } = await this.computeFlagAndPayloadLocally(flag, ctx);
+            return value;
+        }
+        catch (e) {
+            if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) {
+                this.logMsgIfDebug(() => console.debug(`[FEATURE FLAGS] ${e.name} when computing flag locally: ${key}: ${e.message}`));
+                return undefined;
+            }
+            throw e;
+        }
+    }
+    async getFeatureFlagResult(key, distinctId, groups = {}, personProperties = {}, groupProperties = {}) {
+        const flag = this.flagsByKey[key];
+        if (flag === undefined)
+            return undefined;
+        const ctx = this.createEvaluationContext(distinctId, groups, personProperties, groupProperties);
+        try {
+            return await this.computeFlagAndPayloadLocally(flag, ctx);
+        }
+        catch (e) {
+            if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) {
+                this.logMsgIfDebug(() => console.debug(`[FEATURE FLAGS] ${e.name} when computing flag locally: ${key}: ${e.message}`));
+                return undefined;
+            }
+            throw e;
+        }
+    }
+    /**
+     * Returns the payload for a flag value, or `null` when the flag is unknown / evaluated to a
+     * non-matching value / has no payload configured. Returns `undefined` when the flag couldn't
+     * be evaluated locally — mirroring `getFeatureFlag` so callers can tell apart "no payload"
+     * from "eval unavailable".
+     */
+    async getFeatureFlagPayload(key, distinctId, matchValue, groups = {}, personProperties = {}, groupProperties = {}) {
+        const flag = this.flagsByKey[key];
+        if (flag === undefined)
+            return null;
+        if (matchValue !== undefined) {
+            return this.getPayloadForValue(key, matchValue);
+        }
+        const result = await this.getFeatureFlagResult(key, distinctId, groups, personProperties, groupProperties);
+        if (result === undefined)
+            return undefined;
+        return result.payload;
+    }
+    async getAllFlagsAndPayloads(distinctId, groups = {}, personProperties = {}, groupProperties = {}, flagKeys) {
+        const featureFlags = {};
+        const featureFlagPayloads = {};
+        const flagsToEvaluate = flagKeys ? flagKeys.map((k) => this.flagsByKey[k]).filter(Boolean) : this.flags;
+        const sharedContext = {
+            distinctId,
+            groups,
+            personProperties,
+            groupProperties,
+            evaluationCache: {},
+        };
+        await Promise.all(flagsToEvaluate.map(async (flag) => {
+            try {
+                const { value, payload } = await this.computeFlagAndPayloadLocally(flag, sharedContext);
+                featureFlags[flag.key] = value;
+                if (payload != null)
+                    featureFlagPayloads[flag.key] = payload;
+            }
+            catch (e) {
+                if (e instanceof RequiresServerEvaluation || e instanceof InconclusiveMatchError) {
+                    this.logMsgIfDebug(() => console.debug(`[FEATURE FLAGS] ${e.name} when computing flag locally: ${flag.key}: ${e.message}`));
+                    return;
+                }
+                throw e;
+            }
+        }));
+        return { featureFlags, featureFlagPayloads };
+    }
+    async computeFlagAndPayloadLocally(flag, ctx, options = {}) {
+        const flagValue = options.matchValue !== undefined ? options.matchValue : await this.computeFlagValueLocally(flag, ctx);
+        return { value: flagValue, payload: this.getPayloadForValue(flag.key, flagValue) };
+    }
+    async computeFlagValueLocally(flag, ctx) {
+        const { distinctId, groups, personProperties, groupProperties } = ctx;
+        // Order matters: an inactive flag is always false regardless of continuity. Checking
+        // `ensure_experience_continuity` first would cause a disabled-but-continuity flag to come
+        // back as undefined instead of the correct `false`.
+        if (!flag.active)
+            return false;
+        if (flag.ensure_experience_continuity) {
+            throw new InconclusiveMatchError('Flag has experience continuity enabled');
+        }
+        const flagFilters = flag.filters || {};
+        const aggregation_group_type_index = flagFilters.aggregation_group_type_index;
+        if (aggregation_group_type_index != undefined) {
+            const groupName = this.groupTypeMapping[String(aggregation_group_type_index)];
+            if (!groupName) {
+                this.logMsgIfDebug(() => console.warn(`[FEATURE FLAGS] Unknown group type index ${aggregation_group_type_index} for feature flag ${flag.key}`));
+                throw new InconclusiveMatchError('Flag has unknown group type index');
+            }
+            if (!(groupName in groups)) {
+                this.logMsgIfDebug(() => console.warn(`[FEATURE FLAGS] Can't compute group feature flag: ${flag.key} without group names passed in`));
+                return false;
+            }
+            const focusedGroupProperties = groupProperties[groupName];
+            return await this.matchFeatureFlagProperties(flag, groups[groupName], focusedGroupProperties, ctx);
+        }
+        const bucketingValue = this.getBucketingValueForFlag(flag, distinctId, personProperties);
+        if (bucketingValue === undefined) {
+            this.logMsgIfDebug(() => console.warn(`[FEATURE FLAGS] Can't compute feature flag: ${flag.key} without $device_id, falling back to server evaluation`));
+            throw new InconclusiveMatchError(`Can't compute feature flag: ${flag.key} without $device_id`);
+        }
+        return await this.matchFeatureFlagProperties(flag, bucketingValue, personProperties, ctx);
+    }
+    getBucketingValueForFlag(flag, distinctId, properties) {
+        if (flag.filters?.aggregation_group_type_index != undefined)
+            return distinctId;
+        if (flag.bucketing_identifier === 'device_id') {
+            const deviceId = properties?.$device_id;
+            if (deviceId === undefined || deviceId === null || deviceId === '')
+                return undefined;
+            return deviceId;
+        }
+        return distinctId;
+    }
+    getPayloadForValue(key, flagValue) {
+        if (flagValue === false || flagValue === null || flagValue === undefined)
+            return null;
+        let payload = null;
+        const payloads = this.flagsByKey[key]?.filters?.payloads;
+        if (!payloads)
+            return null;
+        if (typeof flagValue === 'boolean') {
+            payload = payloads[flagValue.toString()] || null;
+        }
+        else if (typeof flagValue === 'string') {
+            payload = payloads[flagValue] || null;
+        }
+        if (payload == null)
+            return null;
+        if (typeof payload === 'object')
+            return payload;
+        if (typeof payload === 'string') {
+            try {
+                return JSON.parse(payload);
+            }
+            catch {
+                return payload;
+            }
+        }
+        return payload;
+    }
+    async evaluateFlagDependency(property, ctx) {
+        const { evaluationCache } = ctx;
+        const targetFlagKey = property.key;
+        if (!('dependency_chain' in property)) {
+            throw new InconclusiveMatchError(`Flag dependency property for '${targetFlagKey}' is missing required 'dependency_chain' field`);
+        }
+        const dependencyChain = property.dependency_chain;
+        if (!Array.isArray(dependencyChain)) {
+            throw new InconclusiveMatchError(`Flag dependency property for '${targetFlagKey}' has an invalid 'dependency_chain'`);
+        }
+        if (dependencyChain.length === 0) {
+            throw new InconclusiveMatchError(`Circular dependency detected for flag '${targetFlagKey}'`);
+        }
+        for (const depFlagKey of dependencyChain) {
+            if (!(depFlagKey in evaluationCache)) {
+                const depFlag = this.flagsByKey[depFlagKey];
+                if (!depFlag) {
+                    throw new InconclusiveMatchError(`Missing flag dependency '${depFlagKey}' for flag '${targetFlagKey}'`);
+                }
+                if (!depFlag.active) {
+                    evaluationCache[depFlagKey] = false;
+                }
+                else {
+                    try {
+                        evaluationCache[depFlagKey] = await this.computeFlagValueLocally(depFlag, ctx);
+                    }
+                    catch (error) {
+                        throw new InconclusiveMatchError(`Error evaluating flag dependency '${depFlagKey}' for flag '${targetFlagKey}': ${error}`);
+                    }
+                }
+            }
+            const cached = evaluationCache[depFlagKey];
+            if (cached === null || cached === undefined) {
+                throw new InconclusiveMatchError(`Dependency '${depFlagKey}' could not be evaluated`);
+            }
+        }
+        return flagEvaluatesToExpectedValue(property.value, evaluationCache[targetFlagKey]);
+    }
+    async matchFeatureFlagProperties(flag, bucketingValue, properties, ctx) {
+        const flagFilters = flag.filters || {};
+        const flagConditions = flagFilters.groups || [];
+        const flagAggregation = flagFilters.aggregation_group_type_index;
+        const { groups, groupProperties } = ctx;
+        let isInconclusive = false;
+        let result = undefined;
+        for (const condition of flagConditions) {
+            try {
+                const conditionAggregation = condition.aggregation_group_type_index !== undefined
+                    ? condition.aggregation_group_type_index
+                    : flagAggregation;
+                let effectiveProperties = properties;
+                let effectiveBucketingValue = bucketingValue;
+                if (conditionAggregation !== flagAggregation) {
+                    if (conditionAggregation !== null && conditionAggregation !== undefined) {
+                        const groupName = this.groupTypeMapping[String(conditionAggregation)];
+                        if (!groupName || !(groupName in groups)) {
+                            this.logMsgIfDebug(() => console.debug(`[FEATURE FLAGS] Skipping group condition for flag '${flag.key}': group type index ${conditionAggregation} not available`));
+                            continue;
+                        }
+                        if (!(groupName in groupProperties)) {
+                            isInconclusive = true;
+                            continue;
+                        }
+                        effectiveProperties = groupProperties[groupName];
+                        effectiveBucketingValue = groups[groupName];
+                    }
+                }
+                if (await this.isConditionMatch(flag, effectiveBucketingValue, condition, effectiveProperties, ctx)) {
+                    const variantOverride = condition.variant;
+                    const flagVariants = flagFilters.multivariate?.variants || [];
+                    if (variantOverride && flagVariants.some((variant) => variant.key === variantOverride)) {
+                        result = variantOverride;
+                    }
+                    else {
+                        result = (await this.getMatchingVariant(flag, effectiveBucketingValue)) || true;
+                    }
+                    break;
+                }
+            }
+            catch (e) {
+                if (e instanceof RequiresServerEvaluation)
+                    throw e;
+                if (e instanceof InconclusiveMatchError) {
+                    isInconclusive = true;
+                }
+                else {
+                    throw e;
+                }
+            }
+        }
+        if (result !== undefined)
+            return result;
+        if (isInconclusive) {
+            throw new InconclusiveMatchError("Can't determine if feature flag is enabled or not with given properties");
+        }
+        return false;
+    }
+    async isConditionMatch(flag, bucketingValue, condition, properties, ctx) {
+        const rolloutPercentage = condition.rollout_percentage;
+        const warn = (msg) => this.logMsgIfDebug(() => console.warn(msg));
+        if ((condition.properties || []).length > 0) {
+            for (const prop of condition.properties) {
+                let matches;
+                if (prop.type === 'cohort') {
+                    matches = matchCohort(prop, properties, this.cohorts, this.debugMode);
+                }
+                else if (prop.type === 'flag') {
+                    matches = await this.evaluateFlagDependency(prop, ctx);
+                }
+                else {
+                    matches = matchProperty(prop, properties, warn);
+                }
+                // `matchPropertyGroup` (cohort path) inverts on `negation`; the top-level flag condition
+                // path needs to do the same or any negated property on a flag-level filter quietly passes.
+                if (prop.negation)
+                    matches = !matches;
+                if (!matches)
+                    return false;
+            }
+            if (rolloutPercentage == undefined)
+                return true;
+        }
+        if (rolloutPercentage != undefined && (await _hash(flag.key, bucketingValue)) > rolloutPercentage / 100.0) {
+            return false;
+        }
+        return true;
+    }
+    async getMatchingVariant(flag, bucketingValue) {
+        const hashValue = await _hash(flag.key, bucketingValue, 'variant');
+        return this.variantLookupTable(flag).find((v) => hashValue >= v.valueMin && hashValue < v.valueMax)?.key;
+    }
+    variantLookupTable(flag) {
+        const table = [];
+        let valueMin = 0;
+        const multivariates = flag.filters?.multivariate?.variants || [];
+        for (const variant of multivariates) {
+            const valueMax = valueMin + variant.rollout_percentage / 100.0;
+            table.push({ valueMin, valueMax, key: variant.key });
+            valueMin = valueMax;
+        }
+        return table;
+    }
+}
+function flagEvaluatesToExpectedValue(expectedValue, flagValue) {
+    if (typeof expectedValue === 'boolean') {
+        return expectedValue === flagValue || (typeof flagValue === 'string' && flagValue !== '' && expectedValue === true);
+    }
+    if (typeof expectedValue === 'string')
+        return flagValue === expectedValue;
+    return false;
+}
+//# sourceMappingURL=evaluator.js.map