@crvouga/mockingbird-service-posthog

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of PostHog for test suites: remote feature-flag evaluation (/flags v2 and the legacy /decide shape), remote config, event capture (/batch/, /e/, /i/v0/e/), session-recording intake, the posthog-js asset and survey endpoints, and the slice of the management API our tooling and crons call (feature-flag list/create/patch, HogQL). Every flag is set per test through admin routes, so paths our in-app overrides cannot reach (strict booleans, getConfig payloads, EMR server gates, member-app variants) become controllable, and a stack run never reaches us.i.posthog.com.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from the wire shapes of posthog-node 5.52.2, @posthog/core 1.54.0 (posthog-react-native 4.72.1's base) and posthog-js 1.433.2, and from our own raw fetches. All three SDKs are proven against it (posthog.sdk.test.ts).

Install

npm install -D @crvouga/mockingbird-service-posthog

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-posthog serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

Point the app's PostHog host at the emulator (port 8795 by default):

npx mockingbird-posthog serve --port 8795 --import-flags dev

import { PostHog } from "posthog-node"
import { createRuntime } from "@crvouga/mockingbird-service-posthog"

// Test setup: the emulator and the flags this worker should see.
const emulator = createRuntime()
const admin = (path: string, body: unknown, method = "PUT") =>
  emulator.fetch(
    new Request(`http://posthog.test/__admin${path}`, { method, body: JSON.stringify(body) }),
  )
// Per-worker namespaces: map each worker's project token (the SDKs cannot add headers)…
await admin("/credentials", { credentials: { phc_worker1: "w1" } })
// …then set flags in that namespace.
await admin("/flags/shop-coupons?namespace=w1", { default: true })
await admin("/flags/rx-category-intake?namespace=w1", {
  default: true,
  payload: { categories: ["trt"] },
  overrides: [{ distinct_id: "42", value: false }, { email: "[email protected]", value: "beta" }],
})
await admin("/flags/mobile-smart-links?namespace=w1", undefined, "DELETE") // absent again

// The application's posthog-node client. Only its fetch changes: requests reach the
// emulator in this process instead of us.i.posthog.com.
const posthog = new PostHog("phc_worker1", {
  fetch: (url, options) => emulator.fetch(new Request(url, options)),
})
await posthog.getFeatureFlag("shop-coupons", "7") // true
await posthog.getFeatureFlag("rx-category-intake", "42") // false
posthog.capture({ distinctId: "7", event: "coupon_applied" })
await posthog.shutdown()

Routes

Every route answers with and without its trailing slash. Errors use PostHog's {type, code, detail, attr} body: 401 invalid_api_key without a project token, 400 missing_distinct_id, 400 invalid_payload for an undecodable body, 404 not_found.

Flag semantics

• Absent vs false. A flag whose default is omitted (or null) is not returned at all unless an override matches; default: false returns enabled: false. The member app's hasFlag falls through to static defaults only for the absent case. Inactive or deleted flags are never returned (as in PostHog).
• Targeting: overrides in order, by exact distinct_id or by person_properties.email (case-insensitive), then the default.
• Variants: a string value is a variant (enabled: true, variant: "<key>"); our backend, EMR and Python clients all read it as true.
• Payloads: any JSON; stored and sent as the JSON string PostHog uses. The backend's getConfig only accepts object payloads.
• Management filters → model: distinct_id / email property groups become overrides; a property-less group at 100 % is the default (its variant, else the largest multivariate variant, else true); at 0 % or a partial rollout it is false; cohort and other property groups are ignored (deterministic, no hashing). Create/patch reject array/scalar filters.payloads with 400 before changing flag or linked experiment state. The dictionary requirement is verified against PostHog's serializer regression and the local contract; seed 172181039 passes self-parity, not live management parity.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets), each on /flags and /decide: flags_5xx, flags_429 (retry-after: 1), flags_hang (1.5 s, past the backend strict and EMR 1 s races), errors_while_computing (errorsWhileComputingFlags: true, flags still present), quota_limited (quotaLimited: ["feature_flags"], no flags). Plus capture_5xx on the capture endpoints. Each preset adds one rule per route, so count applies per route.

Namespaces

PostHog SDKs cannot add headers. Choose a namespace by:

• host prefix (primary): POSTHOG_HOST=http://127.0.0.1:8795/__admin/ns/w1. Every SDK builds ${host}/path, so /__admin/ns/w1/flags/?v=2 selects w1.
• project token: PUT /__admin/credentials {"credentials": {"phc_…": "w1"}}. The token is read from /array/{token}/…, ?token=, the body (token, api_key, or a batch's first event's properties.token, after decoding gzip/base64), or a personal key's Authorization: Bearer on the management API.
• x-mockingbird-namespace, for raw clients.

The management API's next page URL preserves the configured admin prefix and namespace. Send the personal key in the Authorization header on each page request.

Deliberately not modelled

• Percentage rollouts, cohorts, group (organisation) targeting and local evaluation (/api/feature_flag/local_evaluation): flags evaluate deterministically from explicit overrides and a default.
• Experiment statistics, exposure cohorts, metric execution, special launch/archive/ship endpoints, approval policies, advanced experiment filters, and feature_flag configuration writes through experiments. Management flags use the existing namespace-wide project alias model; experiment records additionally filter by project id.
• Session-recording content, heatmaps, surveys and web experiments (the endpoints answer empty).
• HogQL execution: queries answer canned results.
• Person profiles: $identify / $set events are stored for assertions but do not feed targeting; send person_properties on /flags as the SDKs do.
• Project isolation by project id on the management API: one flag set per namespace.
• Real remote-config fields beyond what the SDKs read.

API

Part of mockingbird.