@posthog/convex 0.2.33 → 1.0.0

package/src/client/index.ts

@@ -1,20 +1,28 @@
 import type { Scheduler } from 'convex/server'
 import type { ComponentApi } from '../component/_generated/component.js'
+import {
+  type FeatureFlagResult,
+  type FeatureFlagValue,
+  type FlagDefinitions,
+  type JsonType,
+  LocalFeatureFlagEvaluator,
+} from './feature-flags/index.js'
 
 /** Context with a scheduler — available in mutations and actions. */
 type SchedulerCtx = { scheduler: Scheduler }
 
-/** Context with runAction — available in actions only. */
-type ActionCtx = { runAction: (reference: any, args: any) => Promise<any> }
+/** Context with runQuery — available in queries, mutations, and actions. */
+type RunQueryCtx = { runQuery: (reference: any, args: any) => Promise<any> }
 
 type FeatureFlagOptions = {
   groups?: Record<string, string>
-  personProperties?: Record<string, string>
-  groupProperties?: Record<string, Record<string, string>>
-  sendFeatureFlagEvents?: boolean
+  personProperties?: Record<string, any>
+  groupProperties?: Record<string, Record<string, any>>
   disableGeoip?: boolean
 }
 
+type AllFlagsOptions = FeatureFlagOptions & { flagKeys?: string[] }
+
 const DEFAULT_HOST = 'https://us.i.posthog.com'
 
 function normalizeApiKey(value?: unknown): string {
@@ -26,12 +34,7 @@ function normalizeHost(value?: unknown): string {
   return normalizedValue || DEFAULT_HOST
 }
 
-export type FeatureFlagResult = {
-  key: string
-  enabled: boolean
-  variant: string | null
-  payload: unknown
-}
+export type { FeatureFlagResult, FeatureFlagValue, JsonType }
 
 export type PostHogEvent = {
   event: string
@@ -74,8 +77,12 @@ 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> }
+
 export class PostHog {
   private apiKey: string
+  private personalApiKey: string
   private host: string
   private beforeSend?: BeforeSendFn | BeforeSendFn[]
   private identifyFn?: IdentifyFn
@@ -84,17 +91,40 @@ export class PostHog {
     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.
+   */
+  async refreshFlagDefinitions(ctx: RunActionCtx): Promise<unknown> {
+    return await ctx.runAction(this.component.lib.refreshFlagDefinitions, {
+      apiKey: this.apiKey,
+      personalApiKey: this.personalApiKey,
+      host: this.host,
+    })
+  }
+
   private async resolveDistinctId(ctx: unknown, argsDistinctId?: string): Promise<string> {
     if (this.identifyFn) {
       const result = await this.identifyFn(ctx)
@@ -118,6 +148,23 @@ export class PostHog {
     return result
   }
 
+  private async loadEvaluator(ctx: RunQueryCtx): Promise<LocalFeatureFlagEvaluator | null> {
+    const row = (await ctx.runQuery(this.component.lib.getFlagDefinitions, {})) as {
+      data: string
+      fetchedAt: number
+      etag?: string
+    } | null
+    if (!row) return null
+    let parsed: FlagDefinitions
+    try {
+      parsed = JSON.parse(row.data) as FlagDefinitions
+    } catch (e) {
+      console.warn('[PostHog] Failed to parse cached flag definitions; treating as unavailable.', e)
+      return null
+    }
+    return new LocalFeatureFlagEvaluator(parsed)
+  }
+
   // --- Fire-and-forget methods (work in mutations and actions) ---
 
   async capture(
@@ -207,7 +254,10 @@ export class PostHog {
       groupType: args.groupType,
       groupKey: args.groupKey,
       properties: result.properties ? JSON.stringify(result.properties) : undefined,
-      distinctId: args.distinctId,
+      // Use the post-beforeSend distinctId so any mutation (redaction, remapping) is honoured.
+      // Fall back to undefined when the result is the empty placeholder so we don't ship "" to
+      // the component (which would then send `distinct_id: ""` for a group identify).
+      distinctId: result.distinctId || undefined,
       disableGeoip: args.disableGeoip,
     })
   }
@@ -271,104 +321,211 @@ export class PostHog {
     })
   }
 
-  // --- Feature flag methods (require action context) ---
+  // --- Feature flag methods (locally evaluated; work in queries, mutations, and actions) ---
+  //
+  // All feature flag methods evaluate flags locally against the definitions cached by the
+  // component's cron. `undefined` signals that the eval couldn't reach a verdict — either
+  // definitions haven't been fetched yet (POSTHOG_PERSONAL_API_KEY missing, or the cron hasn't
+  // run for the first time), or the flag uses features incompatible with local evaluation
+  // (experience continuity, static cohorts, properties not provided). For payload methods,
+  // `null` is reserved for the case where the flag was evaluated but matched no payload — so
+  // callers can distinguish "no payload" from "eval unavailable".
 
   async getFeatureFlag(
-    ctx: ActionCtx,
+    ctx: RunQueryCtx,
     args: { key: string; distinctId?: string } & FeatureFlagOptions
-  ): Promise<boolean | string | null> {
+  ): Promise<FeatureFlagValue | undefined> {
     const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
-    return await ctx.runAction(this.component.lib.getFeatureFlag, {
-      apiKey: this.apiKey,
-      host: this.host,
-      ...args,
+    const evaluator = await this.loadEvaluator(ctx)
+    if (!evaluator) return undefined
+    return await evaluator.getFeatureFlag(
+      args.key,
       distinctId,
-    })
+      args.groups ?? {},
+      args.personProperties ?? {},
+      args.groupProperties ?? {}
+    )
   }
 
   async isFeatureEnabled(
-    ctx: ActionCtx,
+    ctx: RunQueryCtx,
     args: { key: string; distinctId?: string } & FeatureFlagOptions
-  ): Promise<boolean | null> {
-    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
-    return await ctx.runAction(this.component.lib.isFeatureEnabled, {
-      apiKey: this.apiKey,
-      host: this.host,
-      ...args,
-      distinctId,
-    })
+  ): Promise<boolean | undefined> {
+    const value = await this.getFeatureFlag(ctx, args)
+    if (value === undefined) return undefined
+    return value !== false && value !== null
   }
 
   async getFeatureFlagPayload(
-    ctx: ActionCtx,
+    ctx: RunQueryCtx,
     args: {
       key: string
       distinctId?: string
       matchValue?: boolean | string
     } & FeatureFlagOptions
-  ): Promise<unknown> {
+  ): Promise<JsonType | null | undefined> {
+    const evaluator = await this.loadEvaluator(ctx)
+    // `undefined` means we couldn't evaluate (no definitions cached, or the evaluator returned
+    // inconclusive). `null` means we did evaluate and there's no payload — distinguishing the
+    // two lets callers handle the "definitions not loaded yet" case explicitly.
+    if (!evaluator) return undefined
+    // When a caller supplies `matchValue` the payload lookup doesn't need a distinctId — it's a
+    // pure key+value lookup. Defer resolution until we actually need it, so callers using the
+    // "look up payload for a flag value I already evaluated" pattern don't have to configure an
+    // identify callback or pass a distinctId they don't have.
+    if (args.matchValue !== undefined) {
+      return evaluator.getFeatureFlagPayload(args.key, '', args.matchValue)
+    }
     const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
-    return await ctx.runAction(this.component.lib.getFeatureFlagPayload, {
-      apiKey: this.apiKey,
-      host: this.host,
-      ...args,
+    return await evaluator.getFeatureFlagPayload(
+      args.key,
       distinctId,
-    })
+      undefined,
+      args.groups ?? {},
+      args.personProperties ?? {},
+      args.groupProperties ?? {}
+    )
   }
 
   async getFeatureFlagResult(
-    ctx: ActionCtx,
+    ctx: RunQueryCtx,
+    args: { key: string; distinctId?: string } & FeatureFlagOptions
+  ): Promise<FeatureFlagResult | undefined> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    const evaluator = await this.loadEvaluator(ctx)
+    if (!evaluator) return undefined
+    const result = await evaluator.getFeatureFlagResult(
+      args.key,
+      distinctId,
+      args.groups ?? {},
+      args.personProperties ?? {},
+      args.groupProperties ?? {}
+    )
+    if (!result) return undefined
+    // `null` isn't in `FeatureFlagValue`'s declared type but the evaluator handles it defensively
+    // in several places (payload lookup, flag-dependency cache). Treat it as a disabled value
+    // here so a stray `null` can't slip through as `enabled: true, variant: null`.
+    if (result.value === false || result.value === null) {
+      return { key: args.key, enabled: false, variant: null, payload: result.payload ?? null }
+    }
+    return {
+      key: args.key,
+      enabled: true,
+      variant: typeof result.value === 'string' ? result.value : null,
+      payload: result.payload ?? null,
+    }
+  }
+
+  async getAllFlags(
+    ctx: RunQueryCtx,
+    args: { distinctId?: string } & AllFlagsOptions
+  ): Promise<Record<string, FeatureFlagValue>> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    const evaluator = await this.loadEvaluator(ctx)
+    if (!evaluator) return {}
+    const { featureFlags } = await evaluator.getAllFlagsAndPayloads(
+      distinctId,
+      args.groups ?? {},
+      args.personProperties ?? {},
+      args.groupProperties ?? {},
+      args.flagKeys
+    )
+    return featureFlags
+  }
+
+  async getAllFlagsAndPayloads(
+    ctx: RunQueryCtx,
+    args: { distinctId?: string } & AllFlagsOptions
+  ): Promise<{
+    featureFlags: Record<string, FeatureFlagValue>
+    featureFlagPayloads: Record<string, JsonType>
+  }> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    const evaluator = await this.loadEvaluator(ctx)
+    if (!evaluator) return { featureFlags: {}, featureFlagPayloads: {} }
+    return await evaluator.getAllFlagsAndPayloads(
+      distinctId,
+      args.groups ?? {},
+      args.personProperties ?? {},
+      args.groupProperties ?? {},
+      args.flagKeys
+    )
+  }
+
+  // --- Remote feature flag evaluation (action context) ---
+  //
+  // For flags that can't be evaluated locally — experience continuity, static cohorts,
+  // properties you can't pass in — or when you haven't configured a personal API key. These
+  // hit PostHog's `/flags` endpoint via a component action, so they require an action ctx and
+  // incur a per-call network round trip.
+
+  /**
+   * Evaluate a single flag remotely against PostHog's `/flags` endpoint. Action context only.
+   * Returns the flag value, or `null` if the flag doesn't exist.
+   */
+  async evaluateFlag(
+    ctx: RunActionCtx,
     args: { key: string; distinctId?: string } & FeatureFlagOptions
-  ): Promise<FeatureFlagResult | null> {
+  ): Promise<FeatureFlagValue | null> {
     const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
-    return await ctx.runAction(this.component.lib.getFeatureFlagResult, {
+    return (await ctx.runAction(this.component.lib.evaluateFlag, {
       apiKey: this.apiKey,
       host: this.host,
-      ...args,
+      key: args.key,
       distinctId,
-    })
+      groups: args.groups,
+      personProperties: args.personProperties,
+      groupProperties: args.groupProperties,
+      disableGeoip: args.disableGeoip,
+    })) as FeatureFlagValue | null
   }
 
-  async getAllFlags(
-    ctx: ActionCtx,
-    args: {
-      distinctId?: string
-      groups?: Record<string, string>
-      personProperties?: Record<string, string>
-      groupProperties?: Record<string, Record<string, string>>
-      disableGeoip?: boolean
-      flagKeys?: string[]
-    }
-  ): Promise<Record<string, boolean | string>> {
+  /**
+   * Evaluate a single flag's payload remotely against PostHog's `/flags` endpoint. Action context
+   * only. Returns the payload, or `null` if the flag doesn't match or has no payload configured.
+   */
+  async evaluateFlagPayload(
+    ctx: RunActionCtx,
+    args: { key: string; distinctId?: string } & FeatureFlagOptions
+  ): Promise<JsonType | null> {
     const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
-    return await ctx.runAction(this.component.lib.getAllFlags, {
+    return (await ctx.runAction(this.component.lib.evaluateFlagPayload, {
       apiKey: this.apiKey,
       host: this.host,
-      ...args,
+      key: args.key,
       distinctId,
-    })
+      groups: args.groups,
+      personProperties: args.personProperties,
+      groupProperties: args.groupProperties,
+      disableGeoip: args.disableGeoip,
+    })) as JsonType | null
   }
 
-  async getAllFlagsAndPayloads(
-    ctx: ActionCtx,
-    args: {
-      distinctId?: string
-      groups?: Record<string, string>
-      personProperties?: Record<string, string>
-      groupProperties?: Record<string, Record<string, string>>
-      disableGeoip?: boolean
-      flagKeys?: string[]
-    }
+  /**
+   * Evaluate every flag for the user remotely in one `/flags` request. Action context only.
+   * Returns both `featureFlags` (key → value) and `featureFlagPayloads` (key → payload). Use
+   * `flagKeys` to scope the request to a specific subset.
+   */
+  async evaluateAllFlags(
+    ctx: RunActionCtx,
+    args: { distinctId?: string } & AllFlagsOptions
   ): Promise<{
-    featureFlags: Record<string, boolean | string>
-    featureFlagPayloads: Record<string, unknown>
+    featureFlags: Record<string, FeatureFlagValue>
+    featureFlagPayloads: Record<string, JsonType>
   }> {
     const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
-    return await ctx.runAction(this.component.lib.getAllFlagsAndPayloads, {
+    return (await ctx.runAction(this.component.lib.evaluateAllFlags, {
       apiKey: this.apiKey,
       host: this.host,
-      ...args,
       distinctId,
-    })
+      groups: args.groups,
+      personProperties: args.personProperties,
+      groupProperties: args.groupProperties,
+      disableGeoip: args.disableGeoip,
+      flagKeys: args.flagKeys,
+    })) as {
+      featureFlags: Record<string, FeatureFlagValue>
+      featureFlagPayloads: Record<string, JsonType>
+    }
   }
 }

package/src/component/_generated/component.ts

@@ -70,7 +70,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         any,
         Name
       >;
-      getAllFlags: FunctionReference<
+      evaluateAllFlags: FunctionReference<
         "action",
         "internal",
         {
@@ -86,7 +86,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         any,
         Name
       >;
-      getAllFlagsAndPayloads: FunctionReference<
+      evaluateFlag: FunctionReference<
         "action",
         "internal",
         {
@@ -97,63 +97,30 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           groupProperties?: any;
           groups?: any;
           host: string;
-          personProperties?: any;
-        },
-        any,
-        Name
-      >;
-      getFeatureFlag: FunctionReference<
-        "action",
-        "internal",
-        {
-          apiKey: string;
-          disableGeoip?: boolean;
-          distinctId: string;
-          groupProperties?: any;
-          groups?: any;
-          host: string;
-          key: string;
-          personProperties?: any;
-          sendFeatureFlagEvents?: boolean;
-        },
-        any,
-        Name
-      >;
-      getFeatureFlagPayload: FunctionReference<
-        "action",
-        "internal",
-        {
-          apiKey: string;
-          disableGeoip?: boolean;
-          distinctId: string;
-          groupProperties?: any;
-          groups?: any;
-          host: string;
           key: string;
-          matchValue?: string | boolean;
           personProperties?: any;
-          sendFeatureFlagEvents?: boolean;
         },
         any,
         Name
       >;
-      getFeatureFlagResult: FunctionReference<
+      evaluateFlagPayload: FunctionReference<
         "action",
         "internal",
         {
           apiKey: string;
           disableGeoip?: boolean;
           distinctId: string;
+          flagKeys?: Array<string>;
           groupProperties?: any;
           groups?: any;
           host: string;
           key: string;
           personProperties?: any;
-          sendFeatureFlagEvents?: boolean;
         },
         any,
         Name
       >;
+      getFlagDefinitions: FunctionReference<"query", "internal", {}, any, Name>;
       groupIdentify: FunctionReference<
         "action",
         "internal",
@@ -182,20 +149,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         any,
         Name
       >;
-      isFeatureEnabled: FunctionReference<
+      refreshFlagDefinitions: FunctionReference<
         "action",
         "internal",
-        {
-          apiKey: string;
-          disableGeoip?: boolean;
-          distinctId: string;
-          groupProperties?: any;
-          groups?: any;
-          host: string;
-          key: string;
-          personProperties?: any;
-          sendFeatureFlagEvents?: boolean;
-        },
+        { apiKey: string; host?: string; personalApiKey: string },
         any,
         Name
       >;