feat(flags): add local feature flag evaluation

Author: marandaneto

.sampo/changesets/venerable-baroness-erika.md

@@ -0,0 +1,5 @@
+---
+hex/posthog: minor
+---
+
+Add local feature flag definition polling and evaluation with safe remote fallback.

CHANGELOG.md

@@ -1,5 +1,11 @@
 # posthog
 
+## Unreleased
+
+### Minor changes
+
+- Add privileged, polled local feature flag evaluation with safe remote fallback, ETag definition loading, person/group/cohort/dependency matching, deterministic variants and payloads, and an optional bounded shared definition cache provider. Configure it with `secret_key`; existing installations without a secret remain remote-only.
+
 ## 2.14.2 — 2026-08-25
 
 ### Patch changes

lib/posthog/api.ex

@@ -13,4 +13,17 @@ defmodule PostHog.API do
       max_retries: client.feature_flags_request_max_retries
     )
   end
+
+  def flag_definitions(%__MODULE__.Client{} = client, project_api_key, secret_key, etag) do
+    headers =
+      [{"authorization", "Bearer #{secret_key}"}]
+      |> then(fn headers ->
+        if is_binary(etag), do: [{"if-none-match", etag} | headers], else: headers
+      end)
+
+    client.module.request(client.client, :get, "/flags/definitions",
+      params: %{token: project_api_key, send_cohorts: true},
+      headers: headers
+    )
+  end
 end

lib/posthog/api/client.ex

@@ -121,8 +121,8 @@ defmodule PostHog.API.Client do
   Response tuple returned by `c:request/4`.
 
   Successful responses must expose at least a numeric `:status` and decoded
-  `:body`; errors should return the exception or error struct from the HTTP
-  client.
+  `:body`; they may also expose response `:headers`. Errors should return the
+  exception or error struct from the HTTP client.
   """
   @type response() :: {:ok, %{status: non_neg_integer(), body: any()}} | {:error, Exception.t()}
 

lib/posthog/config.ex

@@ -38,6 +38,45 @@ defmodule PostHog.Config do
                             doc:
                               "Number of retries for /flags requests after network, transport, or timeout failures. Set to 0 to disable retries."
                           ],
+                          secret_key: [
+                            type: {:or, [:string, nil]},
+                            default: nil,
+                            doc: """
+                            A privileged project secret (`phs_`) or appropriately scoped personal API key (`phx_`)
+                            used only to load definitions for local feature flag evaluation. Local evaluation is inert
+                            and starts no poller when this value is absent or blank.
+                            """
+                          ],
+                          enable_local_evaluation: [
+                            type: :boolean,
+                            default: true,
+                            doc:
+                              "Enable local feature flag evaluation when a non-empty `secret_key` is configured."
+                          ],
+                          feature_flags_poll_interval_ms: [
+                            type: :pos_integer,
+                            default: 30_000,
+                            doc:
+                              "Interval in milliseconds between local feature flag definition refreshes."
+                          ],
+                          flag_definition_cache_provider: [
+                            type: {:or, [{:tuple, [:atom, :any]}, nil]},
+                            default: nil,
+                            doc:
+                              "Optional `{module, state}` implementing `PostHog.FeatureFlags.FlagDefinitionCacheProvider`."
+                          ],
+                          flag_definition_cache_provider_timeout_ms: [
+                            type: :pos_integer,
+                            default: 5_000,
+                            doc:
+                              "Maximum time in milliseconds allowed for each definition cache provider callback."
+                          ],
+                          flag_definition_request_timeout_ms: [
+                            type: :pos_integer,
+                            default: 10_000,
+                            doc:
+                              "Maximum time in milliseconds allowed for a local feature flag definition request."
+                          ],
                           supervisor_name: [
                             type: :atom,
                             default: PostHog,
@@ -219,7 +258,7 @@ defmodule PostHog.Config do
 
   ## Remarks
 
-  String `:api_key` and `:api_host` values are trimmed before validation. A blank
+  String `:api_key`, `:secret_key`, and `:api_host` values are trimmed before validation. A blank
   `:api_host` falls back to the default PostHog US ingestion host.
   """
   @spec validate(options()) ::
@@ -274,6 +313,13 @@ defmodule PostHog.Config do
         normalized_options
       end
     end)
+    |> then(fn normalized_options ->
+      if Keyword.has_key?(normalized_options, :secret_key) do
+        Keyword.update!(normalized_options, :secret_key, &normalize_secret_key/1)
+      else
+        normalized_options
+      end
+    end)
     |> then(fn normalized_options ->
       if Keyword.has_key?(normalized_options, :api_host) do
         Keyword.update!(normalized_options, :api_host, &normalize_api_host/1)
@@ -287,6 +333,15 @@ defmodule PostHog.Config do
   defp normalize_api_key(nil), do: ""
   defp normalize_api_key(api_key), do: api_key
 
+  defp normalize_secret_key(secret_key) when is_binary(secret_key) do
+    case String.trim(secret_key) do
+      "" -> nil
+      value -> value
+    end
+  end
+
+  defp normalize_secret_key(secret_key), do: secret_key
+
   defp normalize_api_host(api_host) when is_binary(api_host) do
     api_host
     |> String.trim()