feature(adapter-posthog): Add PostHog adapter (#114)

* feature(adapter-posthog): PostHog Adapter
* pass flagValue=undefined to getFeatureFlagPayload
* Map NEXT_PUBLIC_POSTHOG_HOST to a PostHog app hostname by default, making appHost optional in getProviderData
* Do not expose synchronous client in the Adapter interface (make it async later)
* Add tests

Author: AAorris

.changeset/twenty-cherries-pull.md

@@ -0,0 +1,5 @@
+---
+'@flags-sdk/posthog': minor
+---
+
+Publish PostHog adapter

packages/adapter-posthog/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @flags-sdk/posthog
+
+## 0.1.0
+
+### Minor Changes
+
+- postHogAdapter: Default adapter is available
+- postHogAdapter.isFeatureEnabled: Check if a feature flag is enabled
+- postHogAdapter.featureFlagValue: Get the value of a feature flag
+- postHogAdapter.featureFlagPayload: Get the payload of a feature flag
+- postHogAdapter.client: Access the PostHog client

packages/adapter-posthog/README.md

@@ -0,0 +1,40 @@
+# Flags SDK — PostHog Adapter
+
+The PostHog adapter for [Flags SDK](https://flags-sdk.dev/) supports dynamic server side feature flags powered by [PostHog](https://posthog.com/).
+
+## Setup
+
+Install the adapter
+
+```bash
+pnpm i @flags-sdk/posthog
+```
+
+## Example Usage
+
+```ts
+import { flag } from 'flags/next';
+import { postHogAdapter } from '@flags-sdk/posthog';
+
+export const marketingGate = flag<boolean>({
+  // The key in PostHog
+  key: 'my_posthog_flag_key_here',
+  // The PostHog feature to use (isFeatureEnabled, featureFlagValue, featureFlagPayload)
+  adapter: postHogAdapter.featureFlagValue(),
+});
+```
+
+## Runtimes
+
+| Runtime      | Supported |
+| ------------ | --------- |
+| Node         | ✅        |
+| Edge Runtime | ❌        |
+
+Note: `posthog-node` does not support the Edge Runtime.
+
+To use with middleware and precompute, read more: [Middleware now supports Node.js](https://vercel.com/changelog/middleware-now-supports-node-js)
+
+## Documentation
+
+View more PostHog documentation at [posthog.com](https://posthog.com?utm_source=github&utm_campaign=flags_sdk).

packages/adapter-posthog/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@flags-sdk/posthog",
+  "version": "0.0.1",
+  "description": "PostHog adapter for the Flags SDK",
+  "keywords": [
+    "flags-sdk",
+    "posthog",
+    "vercel",
+    "edge config",
+    "feature flags",
+    "flags"
+  ],
+  "homepage": "https://flags-sdk.dev",
+  "bugs": {
+    "url": "https://github.com/vercel/flags/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel/flags.git"
+  },
+  "license": "MIT",
+  "author": "",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.js",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "dist/*.d.ts",
+        "dist/*.d.cts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rimraf dist && tsup",
+    "dev": "tsup --watch --clean=false",
+    "eslint": "eslint-runner",
+    "eslint:fix": "eslint-runner --fix",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@vercel/edge-config": "^1.4.0",
+    "posthog-node": "4.11.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.14.0",
+    "eslint-config-custom": "workspace:*",
+    "flags": "workspace:*",
+    "msw": "2.6.4",
+    "rimraf": "6.0.1",
+    "tsconfig": "workspace:*",
+    "tsup": "8.0.1",
+    "typescript": "5.8.2",
+    "vite": "6.2.5",
+    "vitest": "1.4.0"
+  }
+}

packages/adapter-posthog/src/index.test.ts

@@ -0,0 +1,94 @@
+import type { ReadonlyHeaders, ReadonlyRequestCookies } from 'flags';
+import { expect, it, describe, vi, beforeAll } from 'vitest';
+import { postHogAdapter, type PostHogEntities } from '.';
+
+const postHogClientMock = {
+  isFeatureEnabled: vi.fn(),
+  getFeatureFlag: vi.fn(),
+  getFeatureFlagPayload: vi.fn(),
+  getRemoteConfigPayload: vi.fn(),
+};
+
+vi.mock('posthog-node', () => ({
+  PostHog: vi.fn(() => postHogClientMock),
+}));
+
+describe('postHogAdapter', () => {
+  it('isFeatureEnabled should be a function', () => {
+    expect(postHogAdapter.isFeatureEnabled).toBeInstanceOf(Function);
+  });
+
+  describe('with a missing environment', () => {
+    it('should throw an error', () => {
+      expect(() => postHogAdapter.isFeatureEnabled()).toThrowError(
+        'PostHog Adapter: Missing NEXT_PUBLIC_POSTHOG_KEY environment variable',
+      );
+    });
+  });
+
+  describe('with an environment', () => {
+    beforeAll(() => {
+      process.env.NEXT_PUBLIC_POSTHOG_KEY = 'test-posthog-key';
+      process.env.NEXT_PUBLIC_POSTHOG_HOST = 'https://us.i.posthog.com';
+    });
+
+    describe('isFeatureEnabled', () => {
+      it('should decide', async () => {
+        postHogClientMock.isFeatureEnabled.mockReturnValue(true);
+
+        const valuePromise = postHogAdapter.isFeatureEnabled().decide({
+          key: 'test-flag',
+          headers: {} as ReadonlyHeaders,
+          cookies: {} as ReadonlyRequestCookies,
+          entities: {} as PostHogEntities,
+          defaultValue: false,
+        });
+
+        await expect(valuePromise).resolves.toEqual(true);
+        expect(postHogClientMock.isFeatureEnabled).toHaveBeenCalled();
+      });
+    });
+
+    describe('featureValue', () => {
+      it('should decide', async () => {
+        postHogClientMock.getFeatureFlag.mockReturnValue('test_group_1');
+
+        const valuePromise = postHogAdapter.featureFlagValue().decide({
+          key: 'test-flag',
+          headers: {} as ReadonlyHeaders,
+          cookies: {} as ReadonlyRequestCookies,
+          entities: {} as PostHogEntities,
+          defaultValue: false,
+        });
+
+        await expect(valuePromise).resolves.toEqual('test_group_1');
+        expect(postHogClientMock.getFeatureFlag).toHaveBeenCalled();
+      });
+    });
+
+    describe('featurePayload', () => {
+      it('should decide', async () => {
+        postHogClientMock.getFeatureFlag.mockReturnValue('test_group_1');
+        postHogClientMock.getFeatureFlagPayload.mockReturnValue({
+          text: 'hello world',
+        });
+
+        const valuePromise = postHogAdapter
+          .featureFlagPayload<string>(
+            (payload) => (payload as { text: string }).text,
+          )
+          .decide({
+            key: 'test-flag',
+            headers: {} as ReadonlyHeaders,
+            cookies: {} as ReadonlyRequestCookies,
+            entities: {} as PostHogEntities,
+            defaultValue: 'default',
+          });
+
+        await expect(valuePromise).resolves.toEqual('hello world');
+        expect(postHogClientMock.getFeatureFlag).toHaveBeenCalled();
+        expect(postHogClientMock.getFeatureFlagPayload).toHaveBeenCalled();
+      });
+    });
+  });
+});

packages/adapter-posthog/src/index.ts

@@ -0,0 +1,133 @@
+import { PostHog } from 'posthog-node';
+import type { PostHogAdapter, PostHogEntities, JsonType } from './types';
+
+export { getProviderData } from './provider';
+export type { PostHogEntities, JsonType };
+
+export function createPostHogAdapter({
+  postHogKey,
+  postHogOptions,
+}: {
+  postHogKey: ConstructorParameters<typeof PostHog>[0];
+  postHogOptions: ConstructorParameters<typeof PostHog>[1];
+}): PostHogAdapter {
+  const client = new PostHog(postHogKey, postHogOptions);
+
+  const result: PostHogAdapter = {
+    isFeatureEnabled: (options) => {
+      return {
+        async decide({ key, entities, defaultValue }): Promise<boolean> {
+          const parsedEntities = parseEntities(entities);
+          const result =
+            (await client.isFeatureEnabled(
+              trimKey(key),
+              parsedEntities.distinctId,
+              options,
+            )) ?? defaultValue;
+          if (result === undefined) {
+            throw new Error(
+              `PostHog Adapter isFeatureEnabled returned undefined for ${trimKey(key)} and no default value was provided.`,
+            );
+          }
+          return result;
+        },
+      };
+    },
+    featureFlagValue: (options) => {
+      return {
+        async decide({ key, entities, defaultValue }) {
+          const parsedEntities = parseEntities(entities);
+          const flagValue = await client.getFeatureFlag(
+            trimKey(key),
+            parsedEntities.distinctId,
+            options,
+          );
+          if (flagValue === undefined) {
+            if (typeof defaultValue !== 'undefined') {
+              return defaultValue;
+            }
+            throw new Error(
+              `PostHog Adapter featureFlagValue found undefined for ${trimKey(key)} and no default value was provided.`,
+            );
+          }
+          return flagValue;
+        },
+      };
+    },
+    featureFlagPayload: (getValue, options) => {
+      return {
+        async decide({ key, entities, defaultValue }) {
+          const parsedEntities = parseEntities(entities);
+          const payload = await client.getFeatureFlagPayload(
+            trimKey(key),
+            parsedEntities.distinctId,
+            undefined,
+            options,
+          );
+          if (!payload) {
+            if (typeof defaultValue !== 'undefined') {
+              return defaultValue;
+            }
+            throw new Error(
+              `PostHog Adapter featureFlagPayload found undefined for ${trimKey(key)} and no default value was provided.`,
+            );
+          }
+          return getValue(payload);
+        },
+      };
+    },
+  };
+
+  return result;
+}
+
+function parseEntities(entities?: PostHogEntities): PostHogEntities {
+  if (!entities) {
+    throw new Error(
+      'PostHog Adapter: Missing entities, ' +
+        'flag must be defined with an identify() function.',
+    );
+  }
+  return entities;
+}
+
+function assertEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`PostHog Adapter: Missing ${name} environment variable`);
+  }
+  return value;
+}
+
+// Read until the first `.`
+// This supports defining multiple flags with the same key
+// Ex. with my-flag.is-enabled, my-flag.variant and my-flag.payload
+function trimKey(key: string): string {
+  return key.split('.')[0] as string;
+}
+
+let defaultPostHogAdapter: ReturnType<typeof createPostHogAdapter> | undefined;
+function getOrCreateDefaultAdapter() {
+  if (!defaultPostHogAdapter) {
+    defaultPostHogAdapter = createPostHogAdapter({
+      postHogKey: assertEnv('NEXT_PUBLIC_POSTHOG_KEY'),
+      postHogOptions: {
+        host: assertEnv('NEXT_PUBLIC_POSTHOG_HOST'),
+        personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
+        featureFlagsPollingInterval: 10_000,
+        // Presumption: Server IP is likely not a good proxy for user location
+        disableGeoip: true,
+      },
+    });
+  }
+  return defaultPostHogAdapter;
+}
+
+export const postHogAdapter: PostHogAdapter = {
+  isFeatureEnabled: (...args) =>
+    getOrCreateDefaultAdapter().isFeatureEnabled(...args),
+  featureFlagValue: (...args) =>
+    getOrCreateDefaultAdapter().featureFlagValue(...args),
+  featureFlagPayload: (...args) =>
+    getOrCreateDefaultAdapter().featureFlagPayload(...args),
+};

packages/adapter-posthog/src/provider/index.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest';
+import { getAppHost } from '.';
+
+describe('getAppHost', () => {
+  it('maps us.i.posthog.com', () => {
+    expect(getAppHost('https://us.i.posthog.com')).toBe(
+      'https://us.posthog.com',
+    );
+  });
+  it('maps eu.i.posthog.com', () => {
+    expect(getAppHost('https://eu.i.posthog.com')).toBe(
+      'https://eu.posthog.com',
+    );
+  });
+});