@posthog/convex 1.0.9 → 2.0.0

package/src/client/index.ts

@@ -14,6 +14,9 @@ type SchedulerCtx = { scheduler: Scheduler }
 /** Context with runQuery — available in queries, mutations, and actions. */
 type RunQueryCtx = { runQuery: (reference: any, args: any) => Promise<any> }
 
+/** Context with runAction — available in actions. Used by remote flag evaluation methods. */
+type RunActionCtx = { runAction: (reference: any, args: any) => Promise<any> }
+
 type FeatureFlagOptions = {
   groups?: Record<string, string>
   personProperties?: Record<string, any>
@@ -23,17 +26,6 @@ type FeatureFlagOptions = {
 
 type AllFlagsOptions = FeatureFlagOptions & { flagKeys?: string[] }
 
-const DEFAULT_HOST = 'https://us.i.posthog.com'
-
-function normalizeApiKey(value?: unknown): string {
-  return typeof value === 'string' ? value.trim() : ''
-}
-
-function normalizeHost(value?: unknown): string {
-  const normalizedValue = typeof value === 'string' ? value.trim() : ''
-  return normalizedValue || DEFAULT_HOST
-}
-
 export type { FeatureFlagResult, FeatureFlagValue, JsonType }
 
 export type PostHogEvent = {
@@ -77,52 +69,37 @@ export function normalizeError(error: unknown): {
   return { message: String(error) }
 }
 
-/** Context with runAction — available in actions. Used by `refreshFlagDefinitions`. */
-type RunActionCtx = { runAction: (reference: any, args: any) => Promise<any> }
-
+/**
+ * Client-side wrapper around the PostHog Convex component.
+ *
+ * Credentials (`POSTHOG_PROJECT_TOKEN`, `POSTHOG_HOST`, `POSTHOG_PERSONAL_API_KEY`) are declared on the
+ * component in `convex.config.ts` and read directly inside the component's actions — they don't
+ * need to be plumbed through every call site. Configure callbacks (identify, beforeSend) on the
+ * client; everything else lives in env vars.
+ */
 export class PostHog {
-  private apiKey: string
-  private personalApiKey: string
-  private host: string
   private beforeSend?: BeforeSendFn | BeforeSendFn[]
   private identifyFn?: IdentifyFn
 
   constructor(
     public component: ComponentApi,
     options?: {
-      apiKey?: string
-      /**
-       * Either a [feature flags secure API key](https://posthog.com/docs/feature-flags/local-evaluation#step-1-find-your-feature-flags-secure-api-key)
-       * (`phs_…`, recommended) or a personal API key (`phx_…`) with feature-flag read access.
-       * Required for local feature flag evaluation; defaults to `process.env.POSTHOG_PERSONAL_API_KEY`.
-       * The key is captured at construction time and forwarded to the component whenever you call
-       * `refreshFlagDefinitions(ctx)`.
-       */
-      personalApiKey?: string
-      host?: string
       beforeSend?: BeforeSendFn | BeforeSendFn[]
       identify?: IdentifyFn
     }
   ) {
-    this.apiKey = normalizeApiKey(options?.apiKey ?? process.env.POSTHOG_API_KEY)
-    this.personalApiKey = normalizeApiKey(options?.personalApiKey ?? process.env.POSTHOG_PERSONAL_API_KEY)
-    this.host = normalizeHost(options?.host ?? process.env.POSTHOG_HOST)
     this.beforeSend = options?.beforeSend
     this.identifyFn = options?.identify
   }
 
   /**
-   * Trigger a refresh of the cached feature flag definitions. Must be called from an action
-   * context (typically a cron handler) — the component fetches `/flags/definitions` and writes
-   * the result to its singleton table. Returns the component's status object so callers can log
-   * misconfiguration without throwing.
+   * Trigger a one-off refresh of the cached feature flag definitions. Named for parity with
+   * `posthog-node`'s `reloadFeatureFlags()`. The component already refreshes on a cron when
+   * `POSTHOG_PERSONAL_API_KEY` is set, so call this only when you need an immediate refresh
+   * (e.g. after creating a flag in development). Requires an action context.
    */
-  async refreshFlagDefinitions(ctx: RunActionCtx): Promise<unknown> {
-    return await ctx.runAction(this.component.lib.refreshFlagDefinitions, {
-      apiKey: this.apiKey,
-      personalApiKey: this.personalApiKey,
-      host: this.host,
-    })
+  async reloadFeatureFlags(ctx: RunActionCtx): Promise<unknown> {
+    return await ctx.runAction(this.component.lib.refreshFlagDefinitions, {})
   }
 
   private async resolveDistinctId(ctx: unknown, argsDistinctId?: string): Promise<string> {
@@ -150,11 +127,25 @@ export class PostHog {
 
   private async loadEvaluator(ctx: RunQueryCtx): Promise<LocalFeatureFlagEvaluator | null> {
     const row = (await ctx.runQuery(this.component.lib.getFlagDefinitions, {})) as {
-      data: string
-      fetchedAt: number
+      localEvalConfigured: boolean
+      data: string | null
+      fetchedAt: number | null
       etag?: string
-    } | null
-    if (!row) return null
+    }
+    if (!row.localEvalConfigured) {
+      // Loud failure rather than silent `undefined`: a caller invoking a local-eval method
+      // without `POSTHOG_PERSONAL_API_KEY` configured almost certainly meant to use a remote
+      // `evaluate*` method instead. Throwing tells them exactly what to do.
+      throw new Error(
+        'PostHog: local feature flag evaluation is not configured. ' +
+          'Set POSTHOG_PERSONAL_API_KEY on your Convex deployment, or call the remote ' +
+          '`evaluateFlag` / `evaluateFlagPayload` / `evaluateAllFlags` methods instead ' +
+          '(action context only).'
+      )
+    }
+    // PAK is set but the cron hasn't populated the cache yet — return null so callers fall
+    // back to their `undefined` graceful-degrade path until definitions land.
+    if (!row.data) return null
     let parsed: FlagDefinitions
     try {
       parsed = JSON.parse(row.data) as FlagDefinitions
@@ -189,8 +180,6 @@ export class PostHog {
     if (!result) return
 
     await ctx.scheduler.runAfter(0, this.component.lib.capture, {
-      apiKey: this.apiKey,
-      host: this.host,
       distinctId: result.distinctId,
       event: result.event,
       properties: result.properties ? JSON.stringify(result.properties) : undefined,
@@ -223,8 +212,6 @@ export class PostHog {
     if (!result) return
 
     await ctx.scheduler.runAfter(0, this.component.lib.identify, {
-      apiKey: this.apiKey,
-      host: this.host,
       distinctId: result.distinctId,
       properties: result.properties ? JSON.stringify(result.properties) : undefined,
       disableGeoip: args.disableGeoip,
@@ -249,8 +236,6 @@ export class PostHog {
     if (!result) return
 
     await ctx.scheduler.runAfter(0, this.component.lib.groupIdentify, {
-      apiKey: this.apiKey,
-      host: this.host,
       groupType: args.groupType,
       groupKey: args.groupKey,
       properties: result.properties ? JSON.stringify(result.properties) : undefined,
@@ -278,8 +263,6 @@ export class PostHog {
     if (!result) return
 
     await ctx.scheduler.runAfter(0, this.component.lib.alias, {
-      apiKey: this.apiKey,
-      host: this.host,
       distinctId: result.distinctId,
       alias: args.alias,
       disableGeoip: args.disableGeoip,
@@ -311,8 +294,6 @@ export class PostHog {
     if (!result) return
 
     await ctx.scheduler.runAfter(0, this.component.lib.captureException, {
-      apiKey: this.apiKey,
-      host: this.host,
       distinctId: result.distinctId || undefined,
       errorMessage: message,
       errorStack: stack,
@@ -469,8 +450,6 @@ export class PostHog {
   ): Promise<FeatureFlagValue | null> {
     const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
     return (await ctx.runAction(this.component.lib.evaluateFlag, {
-      apiKey: this.apiKey,
-      host: this.host,
       key: args.key,
       distinctId,
       groups: args.groups,
@@ -490,8 +469,6 @@ export class PostHog {
   ): Promise<JsonType | null> {
     const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
     return (await ctx.runAction(this.component.lib.evaluateFlagPayload, {
-      apiKey: this.apiKey,
-      host: this.host,
       key: args.key,
       distinctId,
       groups: args.groups,
@@ -515,8 +492,6 @@ export class PostHog {
   }> {
     const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
     return (await ctx.runAction(this.component.lib.evaluateAllFlags, {
-      apiKey: this.apiKey,
-      host: this.host,
       distinctId,
       groups: args.groups,
       personProperties: args.personProperties,

package/src/component/_generated/api.ts

@@ -8,7 +8,9 @@
  * @module
  */
 
+import type * as crons from "../crons.js";
 import type * as lib from "../lib.js";
+import type * as version from "../version.js";
 
 import type {
   ApiFromModules,
@@ -18,7 +20,9 @@ import type {
 import { anyApi, componentsGeneric } from "convex/server";
 
 const fullApi: ApiFromModules<{
+  crons: typeof crons;
   lib: typeof lib;
+  version: typeof version;
 }> = anyApi as any;
 
 /**

package/src/component/_generated/component.ts

@@ -27,13 +27,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       alias: FunctionReference<
         "action",
         "internal",
-        {
-          alias: string;
-          apiKey: string;
-          disableGeoip?: boolean;
-          distinctId: string;
-          host: string;
-        },
+        { alias: string; disableGeoip?: boolean; distinctId: string },
         any,
         Name
       >;
@@ -41,12 +35,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "action",
         "internal",
         {
-          apiKey: string;
           disableGeoip?: boolean;
           distinctId: string;
           event: string;
           groups?: string;
-          host: string;
           properties?: string;
           sendFeatureFlags?: boolean;
           timestamp?: number;
@@ -60,12 +52,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "internal",
         {
           additionalProperties?: string;
-          apiKey: string;
           distinctId?: string;
           errorMessage: string;
           errorName?: string;
           errorStack?: string;
-          host: string;
         },
         any,
         Name
@@ -74,13 +64,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "action",
         "internal",
         {
-          apiKey: string;
           disableGeoip?: boolean;
           distinctId: string;
           flagKeys?: Array<string>;
           groupProperties?: any;
           groups?: any;
-          host: string;
           personProperties?: any;
         },
         any,
@@ -90,13 +78,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "action",
         "internal",
         {
-          apiKey: string;
           disableGeoip?: boolean;
           distinctId: string;
           flagKeys?: Array<string>;
           groupProperties?: any;
           groups?: any;
-          host: string;
           key: string;
           personProperties?: any;
         },
@@ -107,13 +93,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "action",
         "internal",
         {
-          apiKey: string;
           disableGeoip?: boolean;
           distinctId: string;
           flagKeys?: Array<string>;
           groupProperties?: any;
           groups?: any;
-          host: string;
           key: string;
           personProperties?: any;
         },
@@ -125,12 +109,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "action",
         "internal",
         {
-          apiKey: string;
           disableGeoip?: boolean;
           distinctId?: string;
           groupKey: string;
           groupType: string;
-          host: string;
           properties?: string;
         },
         any,
@@ -139,20 +121,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       identify: FunctionReference<
         "action",
         "internal",
-        {
-          apiKey: string;
-          disableGeoip?: boolean;
-          distinctId: string;
-          host: string;
-          properties?: string;
-        },
+        { disableGeoip?: boolean; distinctId: string; properties?: string },
         any,
         Name
       >;
       refreshFlagDefinitions: FunctionReference<
         "action",
         "internal",
-        { apiKey: string; host?: string; personalApiKey: string },
+        {},
         any,
         Name
       >;

package/src/component/_generated/server.ts

@@ -30,6 +30,16 @@ import {
 } from "convex/server";
 import type { DataModel } from "./dataModel.js";
 
+/**
+ * Typesafe environment variables declared in `convex.config.ts`.
+ */
+type Env = {
+  readonly POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS: string | undefined;
+  readonly POSTHOG_HOST: string | undefined;
+  readonly POSTHOG_PERSONAL_API_KEY: string | undefined;
+  readonly POSTHOG_PROJECT_TOKEN: string;
+};
+
 /**
  * Define a query in this Convex app's public API.
  *
@@ -106,6 +116,7 @@ export const internalAction: ActionBuilder<DataModel, "internal"> =
  * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
  */
 export const httpAction: HttpActionBuilder = httpActionGeneric;
+export const env: Env = process.env as unknown as Env;
 
 /**
  * A set of services for use within Convex query functions.

package/src/component/convex.config.ts

@@ -1,3 +1,23 @@
 import { defineComponent } from 'convex/server'
+import { v } from 'convex/values'
 
-export default defineComponent('posthog')
+/**
+ * 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()),
+  },
+})

package/src/component/crons.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test, beforeEach, afterEach, jest } from '@jest/globals'
+import { DEFAULT_INTERVAL_SECONDS, readPollingIntervalSeconds } from './crons.js'
+
+describe('readPollingIntervalSeconds', () => {
+  let warnSpy: ReturnType<typeof jest.spyOn>
+
+  beforeEach(() => {
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    warnSpy.mockRestore()
+    delete process.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS
+  })
+
+  test('returns the default when the env var is unset', () => {
+    expect(readPollingIntervalSeconds()).toBe(DEFAULT_INTERVAL_SECONDS)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  test('returns the default when the env var is empty or whitespace', () => {
+    process.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS = '   '
+    expect(readPollingIntervalSeconds()).toBe(DEFAULT_INTERVAL_SECONDS)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  test('parses a positive integer', () => {
+    process.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS = '300'
+    expect(readPollingIntervalSeconds()).toBe(300)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  test('trims whitespace before parsing', () => {
+    process.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS = '  120  '
+    expect(readPollingIntervalSeconds()).toBe(120)
+    expect(warnSpy).not.toHaveBeenCalled()
+  })
+
+  test('warns and falls back for non-numeric input', () => {
+    process.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS = 'abc'
+    expect(readPollingIntervalSeconds()).toBe(DEFAULT_INTERVAL_SECONDS)
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('"abc"'))
+  })
+
+  test('warns and falls back for zero', () => {
+    process.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS = '0'
+    expect(readPollingIntervalSeconds()).toBe(DEFAULT_INTERVAL_SECONDS)
+    expect(warnSpy).toHaveBeenCalled()
+  })
+
+  test('warns and falls back for negative values', () => {
+    process.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS = '-30'
+    expect(readPollingIntervalSeconds()).toBe(DEFAULT_INTERVAL_SECONDS)
+    expect(warnSpy).toHaveBeenCalled()
+  })
+
+  test('warns and falls back for fractional values', () => {
+    process.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS = '60.5'
+    expect(readPollingIntervalSeconds()).toBe(DEFAULT_INTERVAL_SECONDS)
+    expect(warnSpy).toHaveBeenCalled()
+  })
+})

package/src/component/crons.ts

@@ -0,0 +1,52 @@
+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(): number {
+  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