:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import type { PostHogApi } from '@/posthog/api'
import { createEndpoint, createInsightVariable, updateEndpoint } from './api'
import { compare, type Change } from './changes'
import type { LocalEndpoint } from './files'
import {
apiVariableType,
hogqlOf,
remoteVariableNames,
requestBody,
variableReferences,
type Endpoint,
type EndpointFile,
type InsightVariable,
type ResolvedVariables,
} from './model'
export interface VariableChange {
name: string
change: 'add' | 'remove' | 'retype'
type?: string
from?: string
}
export interface PushItem {
name: string
path: string
action: 'create' | 'update' | 'skip'
reason?: string
// PostHog would reject the file, so the push fails.
invalid?: boolean
changes: Change[]
variables: VariableChange[]
file: EndpointFile
}
function variableChanges(
file: EndpointFile,
remoteNames: string[],
existing: Map<string, InsightVariable>
): VariableChange[] {
const changes: VariableChange[] = []
for (const variable of file.variables ?? []) {
const known = existing.get(variable.name)
if (!remoteNames.includes(variable.name)) {
changes.push({ name: variable.name, change: 'add', type: variable.type })
} else if (known && known.type !== apiVariableType(variable.type)) {
changes.push({ name: variable.name, change: 'retype', type: variable.type, from: known.type })
}
}
const localNames = new Set((file.variables ?? []).map((variable) => variable.name))
for (const name of remoteNames.filter((remote) => !localNames.has(remote))) {
changes.push({ name, change: 'remove' })
}
return changes
}
// Why PostHog would reject the file, checked before anything is sent.
function rejection(file: EndpointFile, remoteNames: string[]): string | undefined {
const references = variableReferences(hogqlOf(file))
const localNames = (file.variables ?? []).map((variable) => variable.name)
const removedButUsed = remoteNames.filter((name) => !localNames.includes(name) && references.includes(name))
if (removedButUsed.length > 0) {
return `The query still uses removed variables: ${removedButUsed.join(', ')}`
}
const unused = localNames.filter((name) => !references.includes(name))
if (unused.length > 0) {
return `The query doesn't use these variables, so remove them from the file: ${unused.join(', ')}`
}
return undefined
}
export function planPush(locals: LocalEndpoint[], remotes: Endpoint[], variables: InsightVariable[]): PushItem[] {
const remoteByName = new Map(remotes.map((endpoint) => [endpoint.name, endpoint]))
const existing = new Map(variables.map((variable) => [variable.code_name, variable]))
const seen = new Map<string, string>()
return locals.map(({ path, file }): PushItem => {
const remote = remoteByName.get(file.name)
const remoteNames = remoteVariableNames(remote)
const base = { name: file.name, path, file, changes: [], variables: [] }
const duplicate = seen.get(file.name)
if (duplicate) {
return { ...base, action: 'skip', invalid: true, reason: `${duplicate} defines the same endpoint` }
}
seen.set(file.name, path)
const reason = rejection(file, remoteNames)
if (reason) {
return { ...base, action: 'skip', invalid: true, reason }
}
const variableDiff = variableChanges(file, remoteNames, existing)
if (!remote) {
return { ...base, action: 'create', variables: variableDiff }
}
const changes = compare(file, remote)
// PostHog keeps a variable's type when an endpoint changes, so a type change alone is nothing to push.
const retyped = variableDiff.filter((change) => change.change === 'retype')
if (changes.length === 0 && variableDiff.length === retyped.length) {
const reason = retyped.length
? `No changes hog can push. Change the type of ${retyped.map((change) => change.name).join(', ')} in PostHog`
: 'No changes'
return { ...base, action: 'skip', reason, variables: retyped }
}
return { ...base, action: 'update', changes, variables: variableDiff }
})
}
export interface PushOutcome {
name: string
path: string
status: 'created' | 'updated' | 'failed'
uiUrl?: string | null
error?: string
}
// Creates the variables a file adds that the project doesn't have yet, then the endpoint. A
// failure stops only its own endpoint.
export async function applyPush(
api: PostHogApi,
items: PushItem[],
variables: InsightVariable[]
): Promise<PushOutcome[]> {
const known = new Map(variables.map((variable) => [variable.code_name, variable]))
const outcomes: PushOutcome[] = []
for (const item of items) {
if (item.action === 'skip') {
continue
}
try {
const resolved: ResolvedVariables = new Map()
for (const variable of item.file.variables ?? []) {
let insightVariable = known.get(variable.name)
if (!insightVariable) {
insightVariable = await createInsightVariable(api, {
code_name: variable.name,
type: apiVariableType(variable.type),
...(variable.default !== undefined ? { default_value: variable.default } : {}),
// A single-selection list keeps only the first value of an array default.
...(Array.isArray(variable.default) ? { is_multi: true } : {}),
})
known.set(variable.name, insightVariable)
}
resolved.set(variable.name, insightVariable)
}
const body = requestBody(item.file, resolved)
const saved =
item.action === 'create' ? await createEndpoint(api, body) : await updateEndpoint(api, item.name, body)
outcomes.push({
name: item.name,
path: item.path,
status: item.action === 'create' ? 'created' : 'updated',
uiUrl: saved.ui_url,
})
} catch (error) {
outcomes.push({
name: item.name,
path: item.path,
status: 'failed',
error: error instanceof Error ? error.message : String(error),
})
}
}
return outcomes
}
export interface PullItem {
name: string
path: string
action: 'create' | 'update' | 'skip'
reason?: string
changes: Change[]
endpoint: Endpoint
}
// An endpoint a local file already defines updates that file in place. Any other goes to
// `<folder>/<name>.yaml`, or to `file` when the target is a single YAML file.
export function planPull(remotes: Endpoint[], locals: LocalEndpoint[], pathFor: (name: string) => string): PullItem[] {
const localByName = new Map(locals.map((local) => [local.file.name, local]))
return remotes.map((endpoint): PullItem => {
const local = localByName.get(endpoint.name)
if (!local) {
return { name: endpoint.name, path: pathFor(endpoint.name), action: 'create', changes: [], endpoint }
}
const changes = compare(local.file, endpoint)
return changes.length === 0
? { name: endpoint.name, path: local.path, action: 'skip', reason: 'No changes', changes, endpoint }
: { name: endpoint.name, path: local.path, action: 'update', changes, endpoint }
})
}