@posthog/convex 0.2.33 → 1.0.1

package/src/component/lib.ts

@@ -1,10 +1,42 @@
-import type { FeatureFlagValue, JsonType } from '@posthog/core'
-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'
+import { version } from './version.js'
 
-function createClient(apiKey: string, host: string) {
-  return new PostHog(apiKey, { host, flushAt: 1, flushInterval: 0 })
+/**
+ * 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(): string {
+    return 'posthog-convex'
+  }
+  getLibraryVersion(): string {
+    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<string, PostHog>()
+
+function getClient(apiKey: string, host: string): PostHog {
+  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. */
@@ -32,8 +64,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),
@@ -43,7 +75,6 @@ export const capture = action({
       uuid: args.uuid,
       disableGeoip: args.disableGeoip,
     })
-    await client.shutdown()
   },
 })
 
@@ -56,13 +87,27 @@ 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 as {
+      $set?: Record<string, unknown>
+      $set_once?: Record<string, unknown>
+      $anon_distinct_id?: string
+    } & Record<string, unknown>
+    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()
   },
 })
 
@@ -77,15 +122,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()
   },
 })
 
@@ -98,13 +148,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()
   },
 })
 
@@ -119,152 +168,316 @@ 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
+// --- 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 featureFlagArgs = {
+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: {
-  groups?: Record<string, string>
-  personProperties?: Record<string, string>
-  groupProperties?: Record<string, Record<string, string>>
-  sendFeatureFlagEvents?: boolean
+function remoteFlagsOptions(args: {
+  groups?: unknown
+  personProperties?: unknown
+  groupProperties?: unknown
   disableGeoip?: boolean
+  flagKeys?: string[]
 }) {
   return {
-    groups: args.groups,
-    personProperties: args.personProperties,
-    groupProperties: args.groupProperties,
-    sendFeatureFlagEvents: args.sendFeatureFlagEvents,
+    groups: args.groups as Record<string, string> | undefined,
+    personProperties: args.personProperties as Record<string, any> | undefined,
+    groupProperties: args.groupProperties as Record<string, Record<string, any>> | undefined,
     disableGeoip: args.disableGeoip,
+    flagKeys: args.flagKeys,
+    onlyEvaluateLocally: false,
   }
 }
 
-export const getFeatureFlag = action({
-  args: featureFlagArgs,
-  handler: async (_ctx, args): Promise<FeatureFlagValue | null> => {
-    const client = createClient(args.apiKey, args.host)
-    const result = await client.getFeatureFlag(args.key, args.distinctId, featureFlagOptions(args))
-    await client.shutdown()
-    return result ?? null
+export const evaluateFlag = action({
+  args: { ...remoteFlagsArgs, key: v.string() },
+  handler: async (_ctx, args) => {
+    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 = getClient(args.apiKey, args.host)
+    const snapshot = await client.evaluateFlags(args.distinctId, remoteFlagsOptions(args))
+    const featureFlags: Record<string, unknown> = {}
+    const featureFlagPayloads: Record<string, unknown> = {}
+    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 }
   },
-  handler: async (_ctx, args): Promise<JsonType> => {
-    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
+})
+
+// --- 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 { data: row.data, fetchedAt: row.fetchedAt, etag: row.etag }
   },
 })
 
-export const getFeatureFlagResult = action({
-  args: featureFlagArgs,
-  handler: async (
-    _ctx,
-    args
-  ): Promise<{
-    key: string
-    enabled: boolean
-    variant: string | null
-    payload: JsonType | null
-  } | null> => {
-    const client = createClient(args.apiKey, args.host)
-    const result = await client.getFeatureFlagResult(args.key, args.distinctId, featureFlagOptions(args))
-    await client.shutdown()
-    if (!result) return null
-    return {
-      key: result.key,
-      enabled: result.enabled,
-      variant: result.variant ?? null,
-      payload: result.payload ?? null,
+// 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)
     }
   },
 })
 
-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): Promise<Record<string, FeatureFlagValue>> => {
-    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
+export const _getCurrentEtag = internalQuery({
+  args: {},
+  handler: async (ctx) => {
+    const row = await ctx.db.query('flagDefinitions').order('desc').first()
+    return row?.etag
   },
 })
 
-export const getAllFlagsAndPayloads = action({
-  args: allFlagsArgs,
-  handler: async (
-    _ctx,
-    args
-  ): Promise<{
-    featureFlags?: Record<string, FeatureFlagValue>
-    featureFlagPayloads?: Record<string, JsonType>
-  }> => {
-    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,
+/**
+ * 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' as const, reason: 'missing-keys' as const }
+    }
+
+    const etag = await ctx.runQuery(internal.lib._getCurrentEtag, {})
+
+    const url = `${host}/flags/definitions?token=${projectApiKey}&send_cohorts`
+    const headers: Record<string, string> = {
+      '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: 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' as const, reason: 'fetch-failed' as const }
+      }
+      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' as const }
+    }
+    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' as const, reason: 'auth' as const }
+    }
+    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' as const, reason: 'quota' as const }
+    }
+    if (response.status === 429) {
+      console.warn('[PostHog] Rate limited while fetching flag definitions (after retries).')
+      return { status: 'error' as const, reason: 'rate-limited' as const }
+    }
+    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' as const }
+        }
+        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' as const }
+        }
+        // Recent cached defs — keep them while PostHog's cache potentially warms back up.
+        return { status: 'stale' as const }
+      }
+
+      console.warn(
+        `[PostHog] Unexpected status ${response.status} fetching flag definitions from ${url.replace(projectApiKey, '<token>')}. ` +
+          `Response body: ${bodyText}`
+      )
+      return { status: 'error' as const, reason: 'unexpected-status' as const }
+    }
+
+    let body: { flags?: unknown; group_type_mapping?: unknown; cohorts?: unknown }
+    try {
+      body = (await response.json()) as typeof body
+    } catch (err) {
+      console.warn('[PostHog] Failed to parse flag definitions response:', err)
+      return { status: 'error' as const, reason: 'parse-failed' as const }
+    }
+    if (!('flags' in body)) {
+      console.warn('[PostHog] Flag definitions response missing `flags` field.')
+      return { status: 'error' as const, reason: 'invalid-shape' as const }
+    }
+
+    const data = JSON.stringify({
+      flags: body.flags ?? [],
+      groupTypeMapping: body.group_type_mapping ?? {},
+      cohorts: body.cohorts ?? {},
     })
-    await client.shutdown()
-    return result
+
+    await ctx.runMutation(internal.lib._setFlagDefinitions, {
+      data,
+      etag: response.headers.get('ETag') ?? undefined,
+    })
+
+    return { status: 'updated' as const }
   },
 })

package/src/component/schema.ts

@@ -1,3 +1,17 @@
-import { defineSchema } from 'convex/server'
+import { defineSchema, defineTable } from 'convex/server'
+import { v } from 'convex/values'
 
-export default defineSchema({})
+export default defineSchema({
+  /**
+   * Singleton table holding the latest feature flag definitions fetched from the PostHog API.
+   * The cron action upserts a single row; clients read it for local evaluation.
+   *
+   * `data` is a JSON-stringified `FlagDefinitions` object to bypass Convex's restriction on
+   * field names beginning with `$` (flag conditions reference properties like `$device_id`).
+   */
+  flagDefinitions: defineTable({
+    data: v.string(),
+    fetchedAt: v.number(),
+    etag: v.optional(v.string()),
+  }),
+})

package/src/component/version.ts

@@ -0,0 +1 @@
+export const version = '1.0.1'