@posthog/convex 0.2.32 → 1.0.0

package/dist/component/lib.d.ts

@@ -1,4 +1,3 @@
-import type { FeatureFlagValue, JsonType } from '@posthog/core';
 export declare const capture: import("convex/server").RegisteredAction<"public", {
     disableGeoip?: boolean | undefined;
     groups?: string | undefined;
@@ -43,77 +42,108 @@ export declare const captureException: import("convex/server").RegisteredAction<
     host: string;
     errorMessage: string;
 }, Promise<void>>;
-export declare const getFeatureFlag: import("convex/server").RegisteredAction<"public", {
-    disableGeoip?: boolean | undefined;
-    groups?: any;
-    groupProperties?: any;
-    personProperties?: any;
-    sendFeatureFlagEvents?: boolean | undefined;
-    apiKey: string;
-    distinctId: string;
-    host: string;
-    key: string;
-}, Promise<FeatureFlagValue | null>>;
-export declare const isFeatureEnabled: import("convex/server").RegisteredAction<"public", {
+export declare const evaluateFlag: import("convex/server").RegisteredAction<"public", {
     disableGeoip?: boolean | undefined;
     groups?: any;
+    flagKeys?: string[] | undefined;
     groupProperties?: any;
     personProperties?: any;
-    sendFeatureFlagEvents?: boolean | undefined;
     apiKey: string;
     distinctId: string;
     host: string;
     key: string;
-}, Promise<boolean | null>>;
-export declare const getFeatureFlagPayload: import("convex/server").RegisteredAction<"public", {
+}, Promise<import("@posthog/core").FeatureFlagValue | null>>;
+export declare const evaluateFlagPayload: import("convex/server").RegisteredAction<"public", {
     disableGeoip?: boolean | undefined;
     groups?: any;
+    flagKeys?: string[] | undefined;
     groupProperties?: any;
     personProperties?: any;
-    sendFeatureFlagEvents?: boolean | undefined;
-    matchValue?: string | boolean | undefined;
     apiKey: string;
     distinctId: string;
     host: string;
     key: string;
-}, Promise<JsonType>>;
-export declare const getFeatureFlagResult: import("convex/server").RegisteredAction<"public", {
+}, Promise<string | number | boolean | {
+    [key: string]: import("@posthog/core").JsonType;
+} | import("@posthog/core").JsonType[] | null>>;
+export declare const evaluateAllFlags: import("convex/server").RegisteredAction<"public", {
     disableGeoip?: boolean | undefined;
     groups?: any;
+    flagKeys?: string[] | undefined;
     groupProperties?: any;
     personProperties?: any;
-    sendFeatureFlagEvents?: boolean | undefined;
     apiKey: string;
     distinctId: string;
     host: string;
-    key: string;
 }, Promise<{
-    key: string;
-    enabled: boolean;
-    variant: string | null;
-    payload: JsonType | null;
+    featureFlags: Record<string, unknown>;
+    featureFlagPayloads: Record<string, unknown>;
+}>>;
+/**
+ * Returns the latest cached flag definitions, or `null` if none have been fetched yet.
+ *
+ * The `data` field is a JSON-stringified `FlagDefinitions` object (see `client/feature-flags/types.ts`).
+ */
+export declare const getFlagDefinitions: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+    data: string;
+    fetchedAt: number;
+    etag: string | undefined;
 } | null>>;
-export declare const getAllFlags: import("convex/server").RegisteredAction<"public", {
-    disableGeoip?: boolean | undefined;
-    groups?: any;
-    flagKeys?: string[] | undefined;
-    groupProperties?: any;
-    personProperties?: any;
-    apiKey: string;
-    distinctId: string;
-    host: string;
-}, Promise<Record<string, FeatureFlagValue>>>;
-export declare const getAllFlagsAndPayloads: import("convex/server").RegisteredAction<"public", {
-    disableGeoip?: boolean | undefined;
-    groups?: any;
-    flagKeys?: string[] | undefined;
-    groupProperties?: any;
-    personProperties?: any;
+export declare const _setFlagDefinitions: import("convex/server").RegisteredMutation<"internal", {
+    etag?: string | undefined;
+    data: string;
+}, Promise<void>>;
+export declare const _getCurrentEtag: import("convex/server").RegisteredQuery<"internal", {}, Promise<string | undefined>>;
+/**
+ * Fetches flag definitions from PostHog's local-evaluation endpoint and stores them in the
+ * `flagDefinitions` table. Called by the consumer app's own cron — they pass in the keys via the
+ * `PostHog` client class which knows them already.
+ *
+ * Args:
+ *   - `apiKey` — the project API key (`phc_…`)
+ *   - `personalApiKey` — a feature flags secure API key (`phs_…`, recommended) or personal API
+ *     key (`phx_…`) with feature-flag read access; local eval is disabled if missing
+ *   - `host` — optional, defaults to `https://us.i.posthog.com`
+ */
+export declare const refreshFlagDefinitions: import("convex/server").RegisteredAction<"public", {
+    host?: string | undefined;
     apiKey: string;
-    distinctId: string;
-    host: string;
+    personalApiKey: string;
 }, Promise<{
-    featureFlags?: Record<string, FeatureFlagValue>;
-    featureFlagPayloads?: Record<string, JsonType>;
+    status: "skipped";
+    reason: "missing-keys";
+} | {
+    status: "error";
+    reason: "fetch-failed";
+} | {
+    status: "unchanged";
+    reason?: undefined;
+} | {
+    status: "error";
+    reason: "auth";
+} | {
+    status: "error";
+    reason: "quota";
+} | {
+    status: "error";
+    reason: "rate-limited";
+} | {
+    status: "empty";
+    reason?: undefined;
+} | {
+    status: "stale";
+    reason?: undefined;
+} | {
+    status: "error";
+    reason: "unexpected-status";
+} | {
+    status: "error";
+    reason: "parse-failed";
+} | {
+    status: "error";
+    reason: "invalid-shape";
+} | {
+    status: "updated";
+    reason?: undefined;
 }>>;
 //# sourceMappingURL=lib.d.ts.map

package/dist/component/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/component/lib.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAoB/D,eAAO,MAAM,OAAO;;;;;;;;;;;iBA2BlB,CAAA;AAEF,eAAO,MAAM,QAAQ;;;;;;iBAiBnB,CAAA;AAEF,eAAO,MAAM,aAAa;;;;;;;;iBAqBxB,CAAA;AAEF,eAAO,MAAM,KAAK;;;;;;iBAiBhB,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;iBAkB3B,CAAA;AAgCF,eAAO,MAAM,cAAc;;;;;;;;;;oCAQzB,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;;;2BAQ3B,CAAA;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;qBAgBhC,CAAA;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;SAMxB,MAAM;aACF,OAAO;aACP,MAAM,GAAG,IAAI;aACb,QAAQ,GAAG,IAAI;UAa1B,CAAA;AAaF,eAAO,MAAM,WAAW;;;;;;;;;6CActB,CAAA;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;mBAMhB,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC;0BACzB,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;GAahD,CAAA"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/component/lib.ts"],"names":[],"mappings":"AAoDA,eAAO,MAAM,OAAO;;;;;;;;;;;iBA0BlB,CAAA;AAEF,eAAO,MAAM,QAAQ;;;;;;iBA+BnB,CAAA;AAEF,eAAO,MAAM,aAAa;;;;;;;;iBA0BxB,CAAA;AAEF,eAAO,MAAM,KAAK;;;;;;iBAgBhB,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;iBAiB3B,CAAA;AAqCF,eAAO,MAAM,YAAY;;;;;;;;;;4DAavB,CAAA;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;+CAW9B,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;GAe3B,CAAA;AAYF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;UAO7B,CAAA;AAOF,eAAO,MAAM,mBAAmB;;;iBAW9B,CAAA;AAEF,eAAO,MAAM,eAAe,sFAM1B,CAAA;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmKjC,CAAA"}

package/dist/component/lib.js

@@ -1,8 +1,39 @@
-import { PostHog } from 'posthog-node/edge';
-import { action } from './_generated/server.js';
+import { PostHog as PostHogEdge } from 'posthog-node/edge';
+import { action, internalMutation, internalQuery, query } from './_generated/server.js';
+import { api, internal } from './_generated/api.js';
 import { v } from 'convex/values';
-function createClient(apiKey, host) {
-    return new PostHog(apiKey, { host, flushAt: 1, flushInterval: 0 });
+import { version } from './version.js';
+/**
+ * Brand events sent through this component as `posthog-convex` rather than `posthog-edge` in the
+ * `$lib` / `$lib_version` properties — makes them filterable in PostHog and lets us attribute
+ * issues to the integration vs. raw `posthog-node` usage.
+ */
+class PostHog extends PostHogEdge {
+    getLibraryId() {
+        return 'posthog-convex';
+    }
+    getLibraryVersion() {
+        return version;
+    }
+}
+/**
+ * Cache PostHog clients across action invocations within the same Convex isolate.
+ *
+ * Convex reuses JS isolates between invocations, so module-level state survives. Constructing
+ * a fresh client per call (and tearing it down with `shutdown()`) is wasted work — the client
+ * carries no per-invocation state once `flush()` has drained its queue.
+ *
+ * Keyed by `apiKey|host` to support the rare case of multiple credentials sharing one isolate.
+ */
+const clientCache = new Map();
+function getClient(apiKey, host) {
+    const key = `${apiKey}|${host}`;
+    let client = clientCache.get(key);
+    if (!client) {
+        client = new PostHog(apiKey, { host, flushAt: 1, flushInterval: 0 });
+        clientCache.set(key, client);
+    }
+    return client;
 }
 /** Properties are JSON-serialized to bypass Convex's restriction on `$`-prefixed field names. */
 function parseProperties(json) {
@@ -30,8 +61,8 @@ export const capture = action({
         disableGeoip: v.optional(v.boolean()),
     },
     handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        client.capture({
+        const client = getClient(args.apiKey, args.host);
+        await client.captureImmediate({
             distinctId: args.distinctId,
             event: args.event,
             properties: parseProperties(args.properties),
@@ -41,7 +72,6 @@ export const capture = action({
             uuid: args.uuid,
             disableGeoip: args.disableGeoip,
         });
-        await client.shutdown();
     },
 });
 export const identify = action({
@@ -53,13 +83,23 @@ export const identify = action({
         disableGeoip: v.optional(v.boolean()),
     },
     handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        client.identify({
+        const client = getClient(args.apiKey, args.host);
+        // posthog-node's `identifyImmediate` is missing an `await` on `identifyStatelessImmediate`
+        // (packages/node/src/client.ts:674), so the returned promise resolves before the event hits
+        // the wire. We sidestep that by composing the `$identify` event the same way `identifyImmediate`
+        // does and routing it through `captureImmediate`, which awaits correctly.
+        const properties = parseProperties(args.properties) ?? {};
+        const { $set, $set_once, $anon_distinct_id, ...rest } = properties;
+        await client.captureImmediate({
             distinctId: args.distinctId,
-            properties: parseProperties(args.properties),
+            event: '$identify',
+            properties: {
+                $set: $set ?? rest,
+                $set_once: $set_once ?? {},
+                $anon_distinct_id,
+            },
             disableGeoip: args.disableGeoip,
         });
-        await client.shutdown();
     },
 });
 export const groupIdentify = action({
@@ -73,15 +113,20 @@ export const groupIdentify = action({
         disableGeoip: v.optional(v.boolean()),
     },
     handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        client.groupIdentify({
-            groupType: args.groupType,
-            groupKey: args.groupKey,
-            properties: parseProperties(args.properties),
-            distinctId: args.distinctId,
+        const client = getClient(args.apiKey, args.host);
+        // posthog-node doesn't expose a `groupIdentifyImmediate`, so we send the same `$groupidentify`
+        // event via `captureImmediate` to keep parity with capture/identify/alias/captureException —
+        // resolve when the network call completes, without resorting to shutdown().
+        await client.captureImmediate({
+            distinctId: args.distinctId || `$${args.groupType}_${args.groupKey}`,
+            event: '$groupidentify',
+            properties: {
+                $group_type: args.groupType,
+                $group_key: args.groupKey,
+                $group_set: parseProperties(args.properties) ?? {},
+            },
             disableGeoip: args.disableGeoip,
         });
-        await client.shutdown();
     },
 });
 export const alias = action({
@@ -93,13 +138,12 @@ export const alias = action({
         disableGeoip: v.optional(v.boolean()),
     },
     handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        client.alias({
+        const client = getClient(args.apiKey, args.host);
+        await client.aliasImmediate({
             distinctId: args.distinctId,
             alias: args.alias,
             disableGeoip: args.disableGeoip,
         });
-        await client.shutdown();
     },
 });
 export const captureException = action({
@@ -113,121 +157,289 @@ export const captureException = action({
         additionalProperties: v.optional(v.string()),
     },
     handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
+        const client = getClient(args.apiKey, args.host);
         const error = new Error(args.errorMessage);
         if (args.errorName)
             error.name = args.errorName;
         if (args.errorStack)
             error.stack = args.errorStack;
-        client.captureException(error, args.distinctId, parseProperties(args.additionalProperties));
-        await client.shutdown();
+        await client.captureExceptionImmediate(error, args.distinctId, parseProperties(args.additionalProperties));
     },
 });
-// Feature flag actions — these return values and must be called via ctx.runAction
-const featureFlagArgs = {
+// --- Feature flag remote evaluation ---
+//
+// These actions hit PostHog's `/flags` endpoint directly via `posthog-node`. Use them when
+// local evaluation isn't available (no personal API key) or can't reach a verdict (experience
+// continuity flags, static cohorts, properties you don't have in your server context). They
+// require an action context — that's the trade for not needing flag definitions cached upfront.
+const remoteFlagsArgs = {
     apiKey: v.string(),
     host: v.string(),
-    key: v.string(),
     distinctId: v.string(),
     groups: v.optional(v.any()),
     personProperties: v.optional(v.any()),
     groupProperties: v.optional(v.any()),
-    sendFeatureFlagEvents: v.optional(v.boolean()),
     disableGeoip: v.optional(v.boolean()),
+    flagKeys: v.optional(v.array(v.string())),
 };
-function featureFlagOptions(args) {
+function remoteFlagsOptions(args) {
     return {
         groups: args.groups,
         personProperties: args.personProperties,
         groupProperties: args.groupProperties,
-        sendFeatureFlagEvents: args.sendFeatureFlagEvents,
         disableGeoip: args.disableGeoip,
+        flagKeys: args.flagKeys,
+        onlyEvaluateLocally: false,
     };
 }
-export const getFeatureFlag = action({
-    args: featureFlagArgs,
+export const evaluateFlag = action({
+    args: { ...remoteFlagsArgs, key: v.string() },
     handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        const result = await client.getFeatureFlag(args.key, args.distinctId, featureFlagOptions(args));
-        await client.shutdown();
-        return result ?? null;
+        const client = getClient(args.apiKey, args.host);
+        // Scope the request to just the flag the caller asked about — otherwise PostHog evaluates
+        // every flag in the project on every call. Honour an explicit `flagKeys` override when given.
+        const snapshot = await client.evaluateFlags(args.distinctId, {
+            ...remoteFlagsOptions(args),
+            flagKeys: args.flagKeys ?? [args.key],
+        });
+        const value = snapshot.getFlag(args.key);
+        return value ?? null;
     },
 });
-export const isFeatureEnabled = action({
-    args: featureFlagArgs,
+export const evaluateFlagPayload = action({
+    args: { ...remoteFlagsArgs, key: v.string() },
     handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        const result = await client.isFeatureEnabled(args.key, args.distinctId, featureFlagOptions(args));
-        await client.shutdown();
-        return result ?? null;
+        const client = getClient(args.apiKey, args.host);
+        const snapshot = await client.evaluateFlags(args.distinctId, {
+            ...remoteFlagsOptions(args),
+            flagKeys: args.flagKeys ?? [args.key],
+        });
+        const payload = snapshot.getFlagPayload(args.key);
+        return payload ?? null;
     },
 });
-export const getFeatureFlagPayload = action({
-    args: {
-        ...featureFlagArgs,
-        matchValue: v.optional(v.union(v.string(), v.boolean())),
-    },
+export const evaluateAllFlags = action({
+    args: remoteFlagsArgs,
     handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        const result = await client.getFeatureFlagPayload(args.key, args.distinctId, args.matchValue, featureFlagOptions(args));
-        await client.shutdown();
-        return result ?? null;
+        const client = getClient(args.apiKey, args.host);
+        const snapshot = await client.evaluateFlags(args.distinctId, remoteFlagsOptions(args));
+        const featureFlags = {};
+        const featureFlagPayloads = {};
+        for (const key of snapshot.keys) {
+            const value = snapshot.getFlag(key);
+            if (value !== undefined)
+                featureFlags[key] = value;
+            const payload = snapshot.getFlagPayload(key);
+            if (payload !== undefined)
+                featureFlagPayloads[key] = payload;
+        }
+        return { featureFlags, featureFlagPayloads };
     },
 });
-export const getFeatureFlagResult = action({
-    args: featureFlagArgs,
-    handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        const result = await client.getFeatureFlagResult(args.key, args.distinctId, featureFlagOptions(args));
-        await client.shutdown();
-        if (!result)
+// --- Feature flag local evaluation ---
+//
+// Feature flag definitions are fetched on demand by `refreshFlagDefinitions` and stored in the
+// `flagDefinitions` table. Clients read them via `getFlagDefinitions` and evaluate flags locally
+// — there is no per-call action for flag evaluation.
+//
+// The action takes credentials as args. The consumer's app schedules the refresh cron and passes
+// them in — typically via `posthog.refreshFlagDefinitions(ctx)` on the client class, which
+// forwards the keys it was constructed with.
+/**
+ * Returns the latest cached flag definitions, or `null` if none have been fetched yet.
+ *
+ * The `data` field is a JSON-stringified `FlagDefinitions` object (see `client/feature-flags/types.ts`).
+ */
+export const getFlagDefinitions = query({
+    args: {},
+    handler: async (ctx) => {
+        const row = await ctx.db.query('flagDefinitions').order('desc').first();
+        if (!row)
             return null;
-        return {
-            key: result.key,
-            enabled: result.enabled,
-            variant: result.variant ?? null,
-            payload: result.payload ?? null,
-        };
+        return { data: row.data, fetchedAt: row.fetchedAt, etag: row.etag };
     },
 });
-const allFlagsArgs = {
-    apiKey: v.string(),
-    host: v.string(),
-    distinctId: v.string(),
-    groups: v.optional(v.any()),
-    personProperties: v.optional(v.any()),
-    groupProperties: v.optional(v.any()),
-    disableGeoip: v.optional(v.boolean()),
-    flagKeys: v.optional(v.array(v.string())),
-};
-export const getAllFlags = action({
-    args: allFlagsArgs,
-    handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        const result = await client.getAllFlags(args.distinctId, {
-            groups: args.groups,
-            personProperties: args.personProperties,
-            groupProperties: args.groupProperties,
-            disableGeoip: args.disableGeoip,
-            flagKeys: args.flagKeys,
-        });
-        await client.shutdown();
-        return result;
+// All three queries against `flagDefinitions` use `.order('desc').first()` so they all see the
+// same row even if a stray duplicate ever lands in the table. Without consistent ordering,
+// `_setFlagDefinitions` could upsert against an older row than the one `getFlagDefinitions`
+// returns, leaving the row callers actually read perpetually stale.
+export const _setFlagDefinitions = internalMutation({
+    args: { data: v.string(), etag: v.optional(v.string()) },
+    handler: async (ctx, args) => {
+        const existing = await ctx.db.query('flagDefinitions').order('desc').first();
+        const next = { data: args.data, fetchedAt: Date.now(), etag: args.etag };
+        if (existing) {
+            await ctx.db.replace(existing._id, next);
+        }
+        else {
+            await ctx.db.insert('flagDefinitions', next);
+        }
     },
 });
-export const getAllFlagsAndPayloads = action({
-    args: allFlagsArgs,
-    handler: async (_ctx, args) => {
-        const client = createClient(args.apiKey, args.host);
-        const result = await client.getAllFlagsAndPayloads(args.distinctId, {
-            groups: args.groups,
-            personProperties: args.personProperties,
-            groupProperties: args.groupProperties,
-            disableGeoip: args.disableGeoip,
-            flagKeys: args.flagKeys,
+export const _getCurrentEtag = internalQuery({
+    args: {},
+    handler: async (ctx) => {
+        const row = await ctx.db.query('flagDefinitions').order('desc').first();
+        return row?.etag;
+    },
+});
+/**
+ * Fetches flag definitions from PostHog's local-evaluation endpoint and stores them in the
+ * `flagDefinitions` table. Called by the consumer app's own cron — they pass in the keys via the
+ * `PostHog` client class which knows them already.
+ *
+ * Args:
+ *   - `apiKey` — the project API key (`phc_…`)
+ *   - `personalApiKey` — a feature flags secure API key (`phs_…`, recommended) or personal API
+ *     key (`phx_…`) with feature-flag read access; local eval is disabled if missing
+ *   - `host` — optional, defaults to `https://us.i.posthog.com`
+ */
+export const refreshFlagDefinitions = action({
+    args: {
+        apiKey: v.string(),
+        personalApiKey: v.string(),
+        host: v.optional(v.string()),
+    },
+    handler: async (ctx, args) => {
+        const projectApiKey = args.apiKey.trim();
+        const personalApiKey = args.personalApiKey.trim();
+        const host = (args.host?.trim() || '').replace(/\/$/, '') || 'https://us.i.posthog.com';
+        if (!projectApiKey || !personalApiKey) {
+            // Local evaluation requires both keys. Return a status rather than throwing so the caller
+            // (typically a cron) can surface it cleanly.
+            return { status: 'skipped', reason: 'missing-keys' };
+        }
+        const etag = await ctx.runQuery(internal.lib._getCurrentEtag, {});
+        const url = `${host}/flags/definitions?token=${projectApiKey}&send_cohorts`;
+        const headers = {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${personalApiKey}`,
+        };
+        if (etag)
+            headers['If-None-Match'] = etag;
+        // PostHog's `/flags/definitions` endpoint sits behind a warm-on-demand cache. The first
+        // call after a flag is created — or any time the cache evicts — comes back as a 503 with
+        // "Required data not found in cache. … Please try again later." Retry transient 5xx (and
+        // 429s, since rate limiting on a one-minute cron is similarly worth waiting out) with
+        // bounded exponential backoff so a single cold-cache hit doesn't make callers wait a full
+        // cron tick. Tests override the delays via env var to keep retry-heavy cases snappy.
+        const testOverride = Number(process.env.POSTHOG_FLAGS_RETRY_DELAY_MS_OVERRIDE);
+        const RETRY_DELAYS_MS = Number.isFinite(testOverride) && testOverride >= 0
+            ? [testOverride, testOverride, testOverride]
+            : [1500, 3000, 6000];
+        let response;
+        let attempt = 0;
+        while (true) {
+            try {
+                response = await fetch(url, { method: 'GET', headers });
+            }
+            catch (err) {
+                console.warn('[PostHog] Failed to fetch flag definitions:', err);
+                return { status: 'error', reason: 'fetch-failed' };
+            }
+            const transient = response.status === 429 || (response.status >= 500 && response.status < 600);
+            if (!transient || attempt >= RETRY_DELAYS_MS.length)
+                break;
+            const wait = RETRY_DELAYS_MS[attempt];
+            attempt++;
+            // Drain the body so the connection can be reused.
+            try {
+                await response.text();
+            }
+            catch {
+                // ignore
+            }
+            console.warn(`[PostHog] Flag definitions fetch returned ${response.status}; retrying in ${wait}ms (attempt ${attempt}/${RETRY_DELAYS_MS.length}).`);
+            await new Promise((r) => setTimeout(r, wait));
+        }
+        if (response.status === 304) {
+            return { status: 'unchanged' };
+        }
+        if (response.status === 401 || response.status === 403) {
+            console.warn(`[PostHog] Flag definitions fetch failed with ${response.status}. ` +
+                `Check that the personal/feature-flags-secure API key has read access to feature flags.`);
+            return { status: 'error', reason: 'auth' };
+        }
+        if (response.status === 402) {
+            console.warn('[PostHog] Feature flags quota limit exceeded — disabling local evaluation.');
+            await ctx.runMutation(internal.lib._setFlagDefinitions, {
+                data: JSON.stringify({ flags: [], groupTypeMapping: {}, cohorts: {} }),
+                etag: undefined,
+            });
+            return { status: 'error', reason: 'quota' };
+        }
+        if (response.status === 429) {
+            console.warn('[PostHog] Rate limited while fetching flag definitions (after retries).');
+            return { status: 'error', reason: 'rate-limited' };
+        }
+        if (response.status !== 200) {
+            let bodyText = '<no body>';
+            try {
+                bodyText = (await response.text()).slice(0, 500);
+            }
+            catch {
+                // ignore — body wasn't readable
+            }
+            // PostHog returns 503 with `Required data not found in cache` for two indistinguishable
+            // cases: (a) the project has zero flag definitions configured, and (b) the warm-on-demand
+            // cache evicted and hasn't repopulated yet. We can't tell which, so we treat them the same
+            // way: if we have no existing defs cached, persist an empty snapshot so eval methods can
+            // resolve flag lookups to `undefined` cleanly and the UI stops looking broken. If we
+            // already had defs cached, leave them alone — last-known-good beats a flap.
+            const looksCacheCold = response.status === 503 && bodyText.toLowerCase().includes('required data not found in cache');
+            if (looksCacheCold) {
+                const existing = await ctx.runQuery(api.lib.getFlagDefinitions, {});
+                const STALE_AFTER_MS = 5 * 60 * 1000;
+                if (existing === null) {
+                    // No prior cache — write an empty snapshot so subsequent reads are deterministic and
+                    // the UI shows "no flags" instead of "loading".
+                    await ctx.runMutation(internal.lib._setFlagDefinitions, {
+                        data: JSON.stringify({ flags: [], groupTypeMapping: {}, cohorts: {} }),
+                        etag: undefined,
+                    });
+                    console.info("[PostHog] No flag definitions returned (project may have no flags yet, or PostHog's cache is warming). Cached an empty snapshot.");
+                    return { status: 'empty' };
+                }
+                if (Date.now() - existing.fetchedAt > STALE_AFTER_MS) {
+                    // We had cached defs but haven't successfully refreshed them in a while — could be that
+                    // every flag was deleted upstream and PostHog now responds with "no flags in cache" 503s.
+                    // Replace with an empty snapshot rather than serving stale data indefinitely.
+                    await ctx.runMutation(internal.lib._setFlagDefinitions, {
+                        data: JSON.stringify({ flags: [], groupTypeMapping: {}, cohorts: {} }),
+                        etag: undefined,
+                    });
+                    console.info('[PostHog] Cached flag definitions are >5 minutes stale and PostHog reports an empty cache. Replaced with an empty snapshot.');
+                    return { status: 'empty' };
+                }
+                // Recent cached defs — keep them while PostHog's cache potentially warms back up.
+                return { status: 'stale' };
+            }
+            console.warn(`[PostHog] Unexpected status ${response.status} fetching flag definitions from ${url.replace(projectApiKey, '<token>')}. ` +
+                `Response body: ${bodyText}`);
+            return { status: 'error', reason: 'unexpected-status' };
+        }
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch (err) {
+            console.warn('[PostHog] Failed to parse flag definitions response:', err);
+            return { status: 'error', reason: 'parse-failed' };
+        }
+        if (!('flags' in body)) {
+            console.warn('[PostHog] Flag definitions response missing `flags` field.');
+            return { status: 'error', reason: 'invalid-shape' };
+        }
+        const data = JSON.stringify({
+            flags: body.flags ?? [],
+            groupTypeMapping: body.group_type_mapping ?? {},
+            cohorts: body.cohorts ?? {},
+        });
+        await ctx.runMutation(internal.lib._setFlagDefinitions, {
+            data,
+            etag: response.headers.get('ETag') ?? undefined,
         });
-        await client.shutdown();
-        return result;
+        return { status: 'updated' };
     },
 });
 //# sourceMappingURL=lib.js.map