@posthog/convex 1.0.9 → 2.0.0

package/dist/component/_generated/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/server.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAUvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAgB,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,CACxC,CAAC;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAmB,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAAe,CAAC,SAAS,EAAE,UAAU,CAC3C,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,EAAE,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAiB,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,EAAE,UAAU,CACzC,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,iBAAqC,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/server.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAUvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;GAEG;AACH,KAAK,GAAG,GAAG;IACT,QAAQ,CAAC,sCAAsC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,wBAAwB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAgB,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,CACxC,CAAC;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAmB,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAAe,CAAC,SAAS,EAAE,UAAU,CAC3C,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,EAAE,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAiB,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,EAAE,UAAU,CACzC,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,iBAAqC,CAAC;AAC/D,eAAO,MAAM,GAAG,EAAE,GAAmC,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC"}

package/dist/component/_generated/server.js

@@ -75,4 +75,5 @@ export const internalAction = internalActionGeneric;
  * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
  */
 export const httpAction = httpActionGeneric;
+export const env = process.env;
 //# sourceMappingURL=server.js.map

package/dist/component/_generated/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/component/_generated/server.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAaH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAGvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAsC,YAAY,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,oBAAoB,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAyC,eAAe,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,uBAAuB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAuC,aAAa,CAAC;AAExE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,qBAAqB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAsB,iBAAiB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/component/_generated/server.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAaH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAavB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAsC,YAAY,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,oBAAoB,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAyC,eAAe,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,uBAAuB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAuC,aAAa,CAAC;AAExE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,qBAAqB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAsB,iBAAiB,CAAC;AAC/D,MAAM,CAAC,MAAM,GAAG,GAAQ,OAAO,CAAC,GAAqB,CAAC"}

package/dist/component/convex.config.d.ts

@@ -1,3 +1,20 @@
-declare const _default: import("convex/server").ComponentDefinition<any>;
+/**
+ * The component declares the env vars it needs so the installing app can wire them in
+ * `convex/convex.config.ts` (typically via `app.env.*` so existing project-level env vars
+ * pass straight through). All three are read via `process.env` inside the component's
+ * actions and cron — `POSTHOG_PERSONAL_API_KEY`'s presence is also what gates the local
+ * evaluation refresh cron.
+ */
+declare const _default: import("convex/server").ComponentDefinition<any, {
+    readonly POSTHOG_PROJECT_TOKEN: import("convex/values").VString<string, "required">;
+    readonly POSTHOG_HOST: import("convex/values").VString<string | undefined, "optional">;
+    readonly POSTHOG_PERSONAL_API_KEY: import("convex/values").VString<string | undefined, "optional">;
+    /**
+     * Polling interval for the local-evaluation refresh cron, in whole seconds. Optional
+     * (defaults to 60). Convex component env vars are string-typed on the wire, so this is
+     * parsed at module load — invalid values log a warning and fall back to the default.
+     */
+    readonly POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS: import("convex/values").VString<string | undefined, "optional">;
+}>;
 export default _default;
 //# sourceMappingURL=convex.config.d.ts.map

package/dist/component/convex.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convex.config.d.ts","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":";AAEA,wBAAyC"}
+{"version":3,"file":"convex.config.d.ts","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;;;;;IAMC;;;;OAIG;;;AATP,wBAYE"}

package/dist/component/convex.config.js

@@ -1,3 +1,23 @@
 import { defineComponent } from 'convex/server';
-export default defineComponent('posthog');
+import { v } from 'convex/values';
+/**
+ * The component declares the env vars it needs so the installing app can wire them in
+ * `convex/convex.config.ts` (typically via `app.env.*` so existing project-level env vars
+ * pass straight through). All three are read via `process.env` inside the component's
+ * actions and cron — `POSTHOG_PERSONAL_API_KEY`'s presence is also what gates the local
+ * evaluation refresh cron.
+ */
+export default defineComponent('posthog', {
+    env: {
+        POSTHOG_PROJECT_TOKEN: v.string(),
+        POSTHOG_HOST: v.optional(v.string()),
+        POSTHOG_PERSONAL_API_KEY: v.optional(v.string()),
+        /**
+         * Polling interval for the local-evaluation refresh cron, in whole seconds. Optional
+         * (defaults to 60). Convex component env vars are string-typed on the wire, so this is
+         * parsed at module load — invalid values log a warning and fall back to the default.
+         */
+        POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS: v.optional(v.string()),
+    },
+});
 //# sourceMappingURL=convex.config.js.map

package/dist/component/convex.config.js.map

@@ -1 +1 @@
-{"version":3,"file":"convex.config.js","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAE/C,eAAe,eAAe,CAAC,SAAS,CAAC,CAAA"}
+{"version":3,"file":"convex.config.js","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAA;AAEjC;;;;;;GAMG;AACH,eAAe,eAAe,CAAC,SAAS,EAAE;IACxC,GAAG,EAAE;QACH,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE;QACjC,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACpC,wBAAwB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAChD;;;;WAIG;QACH,sCAAsC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;KAC/D;CACF,CAAC,CAAA"}

package/dist/component/crons.d.ts

@@ -0,0 +1,12 @@
+declare const crons: import("convex/server").Crons;
+export declare const DEFAULT_INTERVAL_SECONDS = 60;
+/**
+ * Parse the optional `POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS` env var into a positive integer.
+ *
+ * Convex component env vars are string-typed, so we coerce here. Invalid values fall back to
+ * the default rather than failing the deploy — flags will still refresh on the default cadence
+ * and the operator gets a warning to act on. Exported for unit testing.
+ */
+export declare function readPollingIntervalSeconds(): number;
+export default crons;
+//# sourceMappingURL=crons.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crons.d.ts","sourceRoot":"","sources":["../../src/component/crons.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,KAAK,+BAAa,CAAA;AAExB,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAYnD;AAwBD,eAAe,KAAK,CAAA"}

package/dist/component/crons.js

@@ -0,0 +1,42 @@
+import { cronJobs } from 'convex/server';
+import { api } from './_generated/api.js';
+import { env } from './_generated/server.js';
+const crons = cronJobs();
+export const DEFAULT_INTERVAL_SECONDS = 60;
+/**
+ * Parse the optional `POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS` env var into a positive integer.
+ *
+ * Convex component env vars are string-typed, so we coerce here. Invalid values fall back to
+ * the default rather than failing the deploy — flags will still refresh on the default cadence
+ * and the operator gets a warning to act on. Exported for unit testing.
+ */
+export function readPollingIntervalSeconds() {
+    const raw = (env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS ?? '').trim();
+    if (!raw)
+        return DEFAULT_INTERVAL_SECONDS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
+        console.warn(`[PostHog] POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS="${raw}" is not a positive integer; ` +
+            `falling back to ${DEFAULT_INTERVAL_SECONDS}s.`);
+        return DEFAULT_INTERVAL_SECONDS;
+    }
+    return parsed;
+}
+/**
+ * The refresh cron is registered only when `POSTHOG_PERSONAL_API_KEY` is configured for the
+ * component. Without it, local evaluation can't run, so there's no reason to pay the per-tick
+ * resource cost — particularly on idle dev deployments on the free tier.
+ *
+ * Toggling local evaluation on or off therefore requires redeploying the component, which
+ * `npx convex env set` triggers automatically in `npx convex dev`. The cron handler itself also
+ * guards against a stale registration where the env var was cleared after deploy.
+ */
+// Trim before checking, matching how `readConfig()` in `lib.ts` interprets the env var.
+// `npx convex env set` can leave trailing whitespace; without the trim, a value like `" "` would
+// register the cron but then no-op every tick once `readConfig()` rejects the trimmed-to-empty
+// PAK — wasted function calls, especially painful on free-tier deployments.
+if ((env.POSTHOG_PERSONAL_API_KEY ?? '').trim()) {
+    crons.interval('Refresh PostHog feature flag definitions', { seconds: readPollingIntervalSeconds() }, api.lib.refreshFlagDefinitions, {});
+}
+export default crons;
+//# sourceMappingURL=crons.js.map

package/dist/component/crons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crons.js","sourceRoot":"","sources":["../../src/component/crons.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA;AACzC,OAAO,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAA;AAE5C,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAA;AAExB,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B;IACxC,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,sCAAsC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACrE,IAAI,CAAC,GAAG;QAAE,OAAO,wBAAwB,CAAA;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;IAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QACzE,OAAO,CAAC,IAAI,CACV,qDAAqD,GAAG,+BAA+B;YACrF,mBAAmB,wBAAwB,IAAI,CAClD,CAAA;QACD,OAAO,wBAAwB,CAAA;IACjC,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,wFAAwF;AACxF,iGAAiG;AACjG,+FAA+F;AAC/F,4EAA4E;AAC5E,IAAI,CAAC,GAAG,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAChD,KAAK,CAAC,QAAQ,CACZ,0CAA0C,EAC1C,EAAE,OAAO,EAAE,0BAA0B,EAAE,EAAE,EACzC,GAAG,CAAC,GAAG,CAAC,sBAAsB,EAC9B,EAAE,CACH,CAAA;AACH,CAAC;AAED,eAAe,KAAK,CAAA"}

package/dist/component/lib.d.ts

@@ -5,41 +5,31 @@ export declare const capture: import("convex/server").RegisteredAction<"public",
     sendFeatureFlags?: boolean | undefined;
     timestamp?: number | undefined;
     uuid?: string | undefined;
-    apiKey: string;
     distinctId: string;
-    host: string;
     event: string;
 }, Promise<void>>;
 export declare const identify: import("convex/server").RegisteredAction<"public", {
     disableGeoip?: boolean | undefined;
     properties?: string | undefined;
-    apiKey: string;
     distinctId: string;
-    host: string;
 }, Promise<void>>;
 export declare const groupIdentify: import("convex/server").RegisteredAction<"public", {
     disableGeoip?: boolean | undefined;
     distinctId?: string | undefined;
     properties?: string | undefined;
-    apiKey: string;
-    host: string;
     groupKey: string;
     groupType: string;
 }, Promise<void>>;
 export declare const alias: import("convex/server").RegisteredAction<"public", {
     disableGeoip?: boolean | undefined;
     alias: string;
-    apiKey: string;
     distinctId: string;
-    host: string;
 }, Promise<void>>;
 export declare const captureException: import("convex/server").RegisteredAction<"public", {
     distinctId?: string | undefined;
     additionalProperties?: string | undefined;
     errorName?: string | undefined;
     errorStack?: string | undefined;
-    apiKey: string;
-    host: string;
     errorMessage: string;
 }, Promise<void>>;
 export declare const evaluateFlag: import("convex/server").RegisteredAction<"public", {
@@ -48,9 +38,7 @@ export declare const evaluateFlag: import("convex/server").RegisteredAction<"pub
     flagKeys?: string[] | undefined;
     groupProperties?: any;
     personProperties?: any;
-    apiKey: string;
     distinctId: string;
-    host: string;
     key: string;
 }, Promise<import("@posthog/core").FeatureFlagValue | null>>;
 export declare const evaluateFlagPayload: import("convex/server").RegisteredAction<"public", {
@@ -59,9 +47,7 @@ export declare const evaluateFlagPayload: import("convex/server").RegisteredActi
     flagKeys?: string[] | undefined;
     groupProperties?: any;
     personProperties?: any;
-    apiKey: string;
     distinctId: string;
-    host: string;
     key: string;
 }, Promise<string | number | boolean | {
     [key: string]: import("@posthog/core").JsonType;
@@ -72,23 +58,32 @@ export declare const evaluateAllFlags: import("convex/server").RegisteredAction<
     flagKeys?: string[] | undefined;
     groupProperties?: any;
     personProperties?: any;
-    apiKey: string;
     distinctId: string;
-    host: string;
 }, Promise<{
     featureFlags: Record<string, unknown>;
     featureFlagPayloads: Record<string, unknown>;
 }>>;
 /**
- * Returns the latest cached flag definitions, or `null` if none have been fetched yet.
+ * Returns the cached flag definitions plus whether local evaluation is configured at all.
  *
- * The `data` field is a JSON-stringified `FlagDefinitions` object (see `client/feature-flags/types.ts`).
+ * `localEvalConfigured` reflects whether `POSTHOG_PERSONAL_API_KEY` is set on the component —
+ * the client uses this to distinguish "you haven't set up local eval" (throw, point the user
+ * at the remote `evaluateFlag` methods) from "PAK is set but the cron hasn't fetched yet"
+ * (return `undefined` gracefully). `data` is null until the first successful refresh.
+ *
+ * `data` is a JSON-stringified `FlagDefinitions` object (see `client/feature-flags/types.ts`).
  */
 export declare const getFlagDefinitions: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+    localEvalConfigured: boolean;
+    data: null;
+    fetchedAt: null;
+    etag: undefined;
+} | {
+    localEvalConfigured: boolean;
     data: string;
     fetchedAt: number;
     etag: string | undefined;
-} | null>>;
+}>>;
 export declare const _setFlagDefinitions: import("convex/server").RegisteredMutation<"internal", {
     etag?: string | undefined;
     data: string;
@@ -96,20 +91,11 @@ export declare const _setFlagDefinitions: import("convex/server").RegisteredMuta
 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`
+ * `flagDefinitions` table. Called automatically by the cron registered in `crons.ts` when
+ * `POSTHOG_PERSONAL_API_KEY` is set, and also exposed publicly so the client's
+ * `reloadFeatureFlags(ctx)` method (parity with `posthog-node`) can trigger an on-demand refresh.
  */
-export declare const refreshFlagDefinitions: import("convex/server").RegisteredAction<"public", {
-    host?: string | undefined;
-    apiKey: string;
-    personalApiKey: string;
-}, Promise<{
+export declare const refreshFlagDefinitions: import("convex/server").RegisteredAction<"public", {}, Promise<{
     status: "skipped";
     reason: "missing-keys";
 } | {

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/component/lib.ts"],"names":[],"mappings":"AAgFA,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;AAmCF,eAAO,MAAM,YAAY;;;;;;;;4DAevB,CAAA;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;+CAa9B,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;;;GAiB3B,CAAA;AASF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;GAU7B,CAAA;AAOF,eAAO,MAAM,mBAAmB;;;iBAW9B,CAAA;AAEF,eAAO,MAAM,eAAe,sFAM1B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8JjC,CAAA"}

package/dist/component/lib.js

@@ -1,5 +1,5 @@
 import { PostHog as PostHogEdge } from 'posthog-node/edge';
-import { action, internalMutation, internalQuery, query } from './_generated/server.js';
+import { action, env, internalMutation, internalQuery, query } from './_generated/server.js';
 import { api, internal } from './_generated/api.js';
 import { v } from 'convex/values';
 import { version } from './version.js';
@@ -16,6 +16,29 @@ class PostHog extends PostHogEdge {
         return version;
     }
 }
+const DEFAULT_HOST = 'https://us.i.posthog.com';
+/**
+ * Resolve the credentials and host the component was configured with.
+ *
+ * Reads the typed `env` from `_generated/server` (declared in `convex.config.ts`). The
+ * installing app wires the values via `app.use(posthog, { env: { ... } })`, typically
+ * threading them straight through from its own deployment env vars. Trimming guards
+ * against accidental whitespace from `npx convex env set`.
+ */
+function readConfig() {
+    const projectToken = (env.POSTHOG_PROJECT_TOKEN ?? '').trim();
+    const host = (env.POSTHOG_HOST ?? '').trim() || DEFAULT_HOST;
+    const personalApiKey = (env.POSTHOG_PERSONAL_API_KEY ?? '').trim();
+    if (!projectToken) {
+        // Convex's typed env-var validation should prevent an empty `POSTHOG_PROJECT_TOKEN` at deploy time,
+        // but the gate is enforced at the app's `convex.config.ts`. Log loudly here so anyone hitting
+        // an unexpected empty value (e.g. the token was cleared post-deploy on a stale isolate) has a trail
+        // to follow rather than silently dropped events.
+        console.warn('[PostHog] POSTHOG_PROJECT_TOKEN is not configured; this event will be dropped. ' +
+            'Set it with `npx convex env set POSTHOG_PROJECT_TOKEN phc_…` and redeploy.');
+    }
+    return { projectToken, host, personalApiKey };
+}
 /**
  * Cache PostHog clients across action invocations within the same Convex isolate.
  *
@@ -23,14 +46,15 @@ class PostHog extends PostHogEdge {
  * 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.
+ * Keyed by `projectToken|host` so a deployment that rotates its env vars (via `npx convex env set`)
+ * picks up the new client without restarting the isolate.
  */
 const clientCache = new Map();
-function getClient(apiKey, host) {
-    const key = `${apiKey}|${host}`;
+function getClient(projectToken, host) {
+    const key = `${projectToken}|${host}`;
     let client = clientCache.get(key);
     if (!client) {
-        client = new PostHog(apiKey, { host, flushAt: 1, flushInterval: 0 });
+        client = new PostHog(projectToken, { host, flushAt: 1, flushInterval: 0 });
         clientCache.set(key, client);
     }
     return client;
@@ -49,8 +73,6 @@ function parseProperties(json) {
 }
 export const capture = action({
     args: {
-        apiKey: v.string(),
-        host: v.string(),
         distinctId: v.string(),
         event: v.string(),
         properties: v.optional(v.string()),
@@ -61,7 +83,10 @@ export const capture = action({
         disableGeoip: v.optional(v.boolean()),
     },
     handler: async (_ctx, args) => {
-        const client = getClient(args.apiKey, args.host);
+        const { projectToken, host } = readConfig();
+        if (!projectToken)
+            return;
+        const client = getClient(projectToken, host);
         await client.captureImmediate({
             distinctId: args.distinctId,
             event: args.event,
@@ -76,14 +101,15 @@ export const capture = action({
 });
 export const identify = action({
     args: {
-        apiKey: v.string(),
-        host: v.string(),
         distinctId: v.string(),
         properties: v.optional(v.string()),
         disableGeoip: v.optional(v.boolean()),
     },
     handler: async (_ctx, args) => {
-        const client = getClient(args.apiKey, args.host);
+        const { projectToken, host } = readConfig();
+        if (!projectToken)
+            return;
+        const client = getClient(projectToken, 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`
@@ -104,8 +130,6 @@ export const identify = action({
 });
 export const groupIdentify = action({
     args: {
-        apiKey: v.string(),
-        host: v.string(),
         groupType: v.string(),
         groupKey: v.string(),
         properties: v.optional(v.string()),
@@ -113,7 +137,10 @@ export const groupIdentify = action({
         disableGeoip: v.optional(v.boolean()),
     },
     handler: async (_ctx, args) => {
-        const client = getClient(args.apiKey, args.host);
+        const { projectToken, host } = readConfig();
+        if (!projectToken)
+            return;
+        const client = getClient(projectToken, 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().
@@ -131,14 +158,15 @@ export const groupIdentify = action({
 });
 export const alias = action({
     args: {
-        apiKey: v.string(),
-        host: v.string(),
         distinctId: v.string(),
         alias: v.string(),
         disableGeoip: v.optional(v.boolean()),
     },
     handler: async (_ctx, args) => {
-        const client = getClient(args.apiKey, args.host);
+        const { projectToken, host } = readConfig();
+        if (!projectToken)
+            return;
+        const client = getClient(projectToken, host);
         await client.aliasImmediate({
             distinctId: args.distinctId,
             alias: args.alias,
@@ -148,8 +176,6 @@ export const alias = action({
 });
 export const captureException = action({
     args: {
-        apiKey: v.string(),
-        host: v.string(),
         distinctId: v.optional(v.string()),
         errorMessage: v.string(),
         errorStack: v.optional(v.string()),
@@ -157,7 +183,10 @@ export const captureException = action({
         additionalProperties: v.optional(v.string()),
     },
     handler: async (_ctx, args) => {
-        const client = getClient(args.apiKey, args.host);
+        const { projectToken, host } = readConfig();
+        if (!projectToken)
+            return;
+        const client = getClient(projectToken, host);
         const error = new Error(args.errorMessage);
         if (args.errorName)
             error.name = args.errorName;
@@ -173,8 +202,6 @@ export const captureException = action({
 // 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(),
     distinctId: v.string(),
     groups: v.optional(v.any()),
     personProperties: v.optional(v.any()),
@@ -195,7 +222,10 @@ function remoteFlagsOptions(args) {
 export const evaluateFlag = action({
     args: { ...remoteFlagsArgs, key: v.string() },
     handler: async (_ctx, args) => {
-        const client = getClient(args.apiKey, args.host);
+        const { projectToken, host } = readConfig();
+        if (!projectToken)
+            return null;
+        const client = getClient(projectToken, 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, {
@@ -209,7 +239,10 @@ export const evaluateFlag = action({
 export const evaluateFlagPayload = action({
     args: { ...remoteFlagsArgs, key: v.string() },
     handler: async (_ctx, args) => {
-        const client = getClient(args.apiKey, args.host);
+        const { projectToken, host } = readConfig();
+        if (!projectToken)
+            return null;
+        const client = getClient(projectToken, host);
         const snapshot = await client.evaluateFlags(args.distinctId, {
             ...remoteFlagsOptions(args),
             flagKeys: args.flagKeys ?? [args.key],
@@ -221,7 +254,10 @@ export const evaluateFlagPayload = action({
 export const evaluateAllFlags = action({
     args: remoteFlagsArgs,
     handler: async (_ctx, args) => {
-        const client = getClient(args.apiKey, args.host);
+        const { projectToken, host } = readConfig();
+        if (!projectToken)
+            return { featureFlags: {}, featureFlagPayloads: {} };
+        const client = getClient(projectToken, host);
         const snapshot = await client.evaluateFlags(args.distinctId, remoteFlagsOptions(args));
         const featureFlags = {};
         const featureFlagPayloads = {};
@@ -238,25 +274,29 @@ export const evaluateAllFlags = action({
 });
 // --- 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.
+// Flag definitions are fetched on a cron registered inside this component (only when
+// `POSTHOG_PERSONAL_API_KEY` is set — see `crons.ts`) and stored in the `flagDefinitions`
+// table. Clients read them via `getFlagDefinitions` and evaluate flags locally — there is
+// no per-call action for flag evaluation.
 /**
- * Returns the latest cached flag definitions, or `null` if none have been fetched yet.
+ * Returns the cached flag definitions plus whether local evaluation is configured at all.
+ *
+ * `localEvalConfigured` reflects whether `POSTHOG_PERSONAL_API_KEY` is set on the component —
+ * the client uses this to distinguish "you haven't set up local eval" (throw, point the user
+ * at the remote `evaluateFlag` methods) from "PAK is set but the cron hasn't fetched yet"
+ * (return `undefined` gracefully). `data` is null until the first successful refresh.
  *
- * The `data` field is a JSON-stringified `FlagDefinitions` object (see `client/feature-flags/types.ts`).
+ * `data` is a JSON-stringified `FlagDefinitions` object (see `client/feature-flags/types.ts`).
  */
 export const getFlagDefinitions = query({
     args: {},
     handler: async (ctx) => {
+        const localEvalConfigured = !!(env.POSTHOG_PERSONAL_API_KEY ?? '').trim();
         const row = await ctx.db.query('flagDefinitions').order('desc').first();
-        if (!row)
-            return null;
-        return { data: row.data, fetchedAt: row.fetchedAt, etag: row.etag };
+        if (!row) {
+            return { localEvalConfigured, data: null, fetchedAt: null, etag: undefined };
+        }
+        return { localEvalConfigured, data: row.data, fetchedAt: row.fetchedAt, etag: row.etag };
     },
 });
 // All three queries against `flagDefinitions` use `.order('desc').first()` so they all see the
@@ -285,32 +325,22 @@ export const _getCurrentEtag = internalQuery({
 });
 /**
  * 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`
+ * `flagDefinitions` table. Called automatically by the cron registered in `crons.ts` when
+ * `POSTHOG_PERSONAL_API_KEY` is set, and also exposed publicly so the client's
+ * `reloadFeatureFlags(ctx)` method (parity with `posthog-node`) can trigger an on-demand refresh.
  */
 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.
+    args: {},
+    handler: async (ctx) => {
+        const { projectToken, host, personalApiKey } = readConfig();
+        if (!projectToken || !personalApiKey) {
+            // The cron is conditionally registered on `POSTHOG_PERSONAL_API_KEY`, so reaching this branch
+            // means either env vars were cleared after deploy (cron still scheduled) or the project token wasn't
+            // configured. Return a status rather than throwing so the cron doesn't churn on errors.
             return { status: 'skipped', reason: 'missing-keys' };
         }
         const etag = await ctx.runQuery(internal.lib._getCurrentEtag, {});
-        const url = `${host}/flags/definitions?token=${projectApiKey}&send_cohorts`;
+        const url = `${host.replace(/\/$/, '')}/flags/definitions?token=${projectToken}&send_cohorts`;
         const headers = {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${personalApiKey}`,
@@ -390,7 +420,7 @@ export const refreshFlagDefinitions = action({
             if (looksCacheCold) {
                 const existing = await ctx.runQuery(api.lib.getFlagDefinitions, {});
                 const STALE_AFTER_MS = 5 * 60 * 1000;
-                if (existing === null) {
+                if (existing.fetchedAt === 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, {
@@ -414,7 +444,7 @@ export const refreshFlagDefinitions = action({
                 // 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>')}. ` +
+            console.warn(`[PostHog] Unexpected status ${response.status} fetching flag definitions from ${url.replace(projectToken, '<token>')}. ` +
                 `Response body: ${bodyText}`);
             return { status: 'error', reason: 'unexpected-status' };
         }