: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
feat(hog): check every PostHog answer against a schema (#129799)
Rafael Audibert5ace115bdff4
diff --git a/hog/src/commands/api/access.ts b/hog/src/commands/api/access.tsindex cfa755ce5f0b..4b906bcb04a9 100644--- a/hog/src/commands/api/access.ts+++ b/hog/src/commands/api/access.ts@@ -1,3 +1,5 @@+import { z } from 'zod'+import type { ApiKeyAccess, ApiToolLibrary } from '@posthog/mcp/src/cli/library-types'import { defineCommand } from '@/core/command'@@ -24,7 +26,7 @@ async function reachesProject(}try {const api = await ctx.posthog()- const project = await api.get<{ organization: string }>(`/api/projects/${projectId}/`)+ const project = await api.get(`/api/projects/${projectId}/`, z.looseObject({ organization: z.string() }))return access.scopedOrganizations.includes(project.organization)} catch (error) {// Without project:read the lookup fails for any project, so a 403 says nothing about the limit.diff --git a/hog/src/commands/auth/migrate.ts b/hog/src/commands/auth/migrate.tsindex 573aa1db8ec6..507b58238712 100644--- a/hog/src/commands/auth/migrate.ts+++ b/hog/src/commands/auth/migrate.ts@@ -25,7 +25,7 @@ type MigrateResult =| { status: 'nothing_to_migrate'; legacyFile: string; next: string }// The fields go through the brand factories below, so a bad value names what is wrong with it.-const LegacyCredentials = z.looseObject({ token: z.unknown(), env_id: z.unknown(), host: z.unknown() })+const LegacyCredentials = z.object({ token: z.unknown(), env_id: z.unknown(), host: z.unknown() })// TODO(v1.1): drop this command. It exists so people moving from posthog-cli keep their key// without logging in again, and hog reads the old file nowhere else.diff --git a/hog/src/commands/endpoints/endpoints.test.ts b/hog/src/commands/endpoints/endpoints.test.tsindex a9ac0c2d8de2..27463ef29e7a 100644--- a/hog/src/commands/endpoints/endpoints.test.ts+++ b/hog/src/commands/endpoints/endpoints.test.ts@@ -42,7 +42,11 @@ const HOGQL = endpoint('by-type', {query: 'SELECT count()\r\nFROM events\r\nWHERE event = {variables.event_type}',variables: { 'var-1': { variableId: 'var-1', code_name: 'event_type', value: '$pageview' } },})-const VARIABLES = [{ id: 'var-1', name: 'event_type', code_name: 'event_type', type: 'String' }]+// PostHog allows a variable without a code name, which no endpoint can use.+const VARIABLES = [+ { id: 'var-1', name: 'event_type', code_name: 'event_type', type: 'String' },+ { id: 'var-0', name: 'Old variable', code_name: null, type: 'String' },+]function server(endpoints: unknown[], extra: (url: string, body: unknown) => unknown = () => undefined) {return (url: string, body: unknown) => {diff --git a/hog/src/commands/endpoints/run.ts b/hog/src/commands/endpoints/run.tsindex e44728a057d6..91ad81bdacb1 100644--- a/hog/src/commands/endpoints/run.ts+++ b/hog/src/commands/endpoints/run.ts@@ -1,3 +1,5 @@+import { z } from 'zod'+import { defineCommand } from '@/core/command'import { EXIT_USAGE, HogError } from '@/core/errors'import { plural } from '@/core/text'@@ -5,11 +7,13 @@ import { listInsightVariables } from '@/endpoints/api'import { readEndpointFiles } from '@/endpoints/files'import { ApiError, type PostHogApi } from '@/posthog/api'-interface RunResponse {- columns?: string[] | null- results?: unknown[] | null- hasMore?: boolean | null-}+const RunResponse = z.looseObject({+ columns: z.array(z.string()).nullish(),+ results: z.array(z.unknown()).nullish(),+ hasMore: z.boolean().nullish(),+})++type RunResponse = z.infer<typeof RunResponse>// HogQL finds a variable by its project ID, so a file's variables must exist in the project. A// value left out uses the variable's default.@@ -113,11 +117,11 @@ export default defineCommand({if (values.size > 0) {query.variables = await queryVariables(api, values)}- return api.post<RunResponse>('query/', { query, name: 'endpoints_cli', refresh: 'blocking' })+ return api.post('query/', { query, name: 'endpoints_cli', refresh: 'blocking' }, RunResponse)}try {- return await api.post<RunResponse>(`endpoints/${encodeURIComponent(args.name!)}/run/`, withVariables)+ return await api.post(`endpoints/${encodeURIComponent(args.name!)}/run/`, withVariables, RunResponse)} catch (error) {if (error instanceof ApiError && error.status === 404) {throw error.withHint(diff --git a/hog/src/commands/query/check.ts b/hog/src/commands/query/check.tsindex 7b65aa79c319..8a3ce9466abd 100644--- a/hog/src/commands/query/check.ts+++ b/hog/src/commands/query/check.ts@@ -1,9 +1,5 @@import { defineCommand } from '@/core/command'-import { printDiagnostics, type Diagnostics } from '@/core/diagnostics'--interface MetadataResponse extends Diagnostics {- isValid?: boolean | null-}+import { DiagnosticsReport, printDiagnostics } from '@/core/diagnostics'export default defineCommand({description: 'Check the syntax and types of a HogQL query without running it',@@ -16,9 +12,11 @@ export default defineCommand({async run({ args, ctx }) {const api = await ctx.posthog()- const response = await api.post<MetadataResponse>('query', {- query: { kind: 'HogQLMetadata', language: 'hogQL', query: args.query },- })+ const response = await api.post(+ 'query',+ { query: { kind: 'HogQLMetadata', language: 'hogQL', query: args.query } },+ DiagnosticsReport+ )return { query: args.query, response }},diff --git a/hog/src/commands/query/query.test.ts b/hog/src/commands/query/query.test.tsindex 58f60a32b654..f13e303c6a71 100644--- a/hog/src/commands/query/query.test.ts+++ b/hog/src/commands/query/query.test.ts@@ -13,6 +13,18 @@ const ROWS = {}describe('hog query', () => {+ test('run fails on an answer of the wrong shape, and names every field that is wrong', async () => {+ const result = await runHog(['query', 'run', 'select 1'], {+ env: TEST_CREDENTIALS,+ respond: () => ({ status: 200, body: { columns: 5, results: 'not rows' } }),+ })++ expect(result.exitCode).toBe(1)+ expect(result.error()).toMatchObject({ code: 'unexpected_response' })+ expect(result.error().message).toContain('columns:')+ expect(result.error().message).toContain('results:')+ })+test.each([['a pipe gets one JSON array per row', false, [], '["$pageview",70]\n["signup",null]\n'],[@@ -141,6 +153,12 @@ describe('hog query', () => {hint: expect.stringContaining('hog query check'),},],+ [+ 'a field of another type keeps the rest of the error',+ 400,+ { type: 'validation_error', code: null, detail: 'Unable to resolve field: nope' },+ { message: 'Unable to resolve field: nope', hint: expect.stringContaining('hog query check') },+ ],['a 403 names the scope the command needs',403,diff --git a/hog/src/commands/query/run.ts b/hog/src/commands/query/run.tsindex 4d7158afd322..c1cd5ce7cd16 100644--- a/hog/src/commands/query/run.ts+++ b/hog/src/commands/query/run.ts@@ -1,14 +1,16 @@+import { z } from 'zod'+import { defineCommand } from '@/core/command'import type { ColumnKind } from '@/core/output'import { plural } from '@/core/text'import { ApiError } from '@/posthog/api'-interface QueryResponse {- columns?: string[] | null- results?: unknown[][] | null- types?: [string, string][] | null- hasMore?: boolean | null-}+const QueryResponse = z.looseObject({+ columns: z.array(z.string()).nullish(),+ results: z.array(z.array(z.unknown())).nullish(),+ types: z.array(z.tuple([z.string(), z.string()])).nullish(),+ hasMore: z.boolean().nullish(),+})// ClickHouse returns 64-bit integers as JSON numbers and dates as strings, so the declared type// colors a column better than its values do.@@ -39,10 +41,11 @@ export default defineCommand({async run({ args, ctx }) {const api = await ctx.posthog()try {- return await api.post<QueryResponse>('query', {- query: { kind: 'HogQLQuery', query: args.query },- refresh: 'blocking',- })+ return await api.post(+ 'query',+ { query: { kind: 'HogQLQuery', query: args.query }, refresh: 'blocking' },+ QueryResponse+ )} catch (error) {if (error instanceof ApiError && error.type === 'validation_error') {throw error.withHint('Run `hog query check` on the query to see where it fails.')diff --git a/hog/src/commands/schema/shared.ts b/hog/src/commands/schema/shared.tsindex 8bda0d10d3a0..10283c9072ae 100644--- a/hog/src/commands/schema/shared.ts+++ b/hog/src/commands/schema/shared.ts@@ -1,4 +1,5 @@import { join } from 'node:path'+import { z } from 'zod'import type { LoadedConfig } from '@/core/config'import type { Context } from '@/core/context'@@ -48,14 +49,12 @@ export function isLanguage(value: string): value is Language {return (LANGUAGES as readonly string[]).includes(value)}-export interface Definitions {- content: string- event_count: number- schema_hash: string-}+const Definitions = z.object({ content: z.string(), event_count: z.number(), schema_hash: z.string() })++export type Definitions = z.infer<typeof Definitions>export function fetchDefinitions(ctx: Context, language: Language): Promise<Definitions> {- return ctx.posthog().then((api) => api.get<Definitions>(`event_definitions/${language}/`))+ return ctx.posthog().then((api) => api.get(`event_definitions/${language}/`, Definitions))}// posthog.json stores paths relative to its own folder. A new file goes in the working folder.diff --git a/hog/src/core/diagnostics.ts b/hog/src/core/diagnostics.tsindex 8137b3c819ca..8b1a0aa667f8 100644--- a/hog/src/core/diagnostics.ts+++ b/hog/src/core/diagnostics.ts@@ -1,22 +1,24 @@+import { z } from 'zod'+import { escapeControls, type Output, type Style } from './output'import { plural } from './text'// One problem the server found in a piece of source text. The offsets count Unicode code points,// as Python strings do, and are null when the problem has no location.-export interface Diagnostic {- message: string- start?: number | null- end?: number | null-}+const DiagnosticMessage = z.looseObject({ message: z.string(), start: z.number().nullish(), end: z.number().nullish() })-export interface Diagnostics {- errors?: Diagnostic[] | null- warnings?: Diagnostic[] | null- notices?: Diagnostic[] | null-}+type DiagnosticMessage = z.infer<typeof DiagnosticMessage>++export const DiagnosticsReport = z.looseObject({+ errors: z.array(DiagnosticMessage).nullish(),+ warnings: z.array(DiagnosticMessage).nullish(),+ notices: z.array(DiagnosticMessage).nullish(),+})++export type DiagnosticsReport = z.infer<typeof DiagnosticsReport>-export function printDiagnostics(out: Output, source: string, diagnostics: Diagnostics): void {- const groups: { label: string; style: Style; items: Diagnostic[] }[] = [+export function printDiagnostics(out: Output, source: string, diagnostics: DiagnosticsReport): void {+ const groups: { label: string; style: Style; items: DiagnosticMessage[] }[] = [{ label: 'error', style: 'red', items: diagnostics.errors ?? [] },{ label: 'warning', style: 'yellow', items: diagnostics.warnings ?? [] },{ label: 'notice', style: 'cyan', items: diagnostics.notices ?? [] },diff --git a/hog/src/core/telemetry.ts b/hog/src/core/telemetry.tsindex 06574e271427..14b3cc269aaf 100644--- a/hog/src/core/telemetry.ts+++ b/hog/src/core/telemetry.ts@@ -111,7 +111,11 @@ function isCloudHost(host: string): boolean {return hostname === 'posthog.com' || hostname.endsWith('.posthog.com')}-const text = (value: unknown): string | undefined => (typeof value === 'string' && value ? value : undefined)+// A field hog can't read, such as a null organization, reads as missing, so the event loses only+// that field.+const Text = z.string().min(1).optional().catch(undefined)+const IdentityUser = z.object({ distinct_id: Text, organization: z.object({ id: Text }).optional().catch(undefined) })+const IdentityProject = z.object({ organization: Text, uuid: Text })// Usage events for the PostHog team. They belong to the PostHog Cloud user whose key hog uses, and// to a random install ID otherwise. Events carry no argument or option values and no error messages,@@ -251,22 +255,25 @@ export class Telemetry {}private async lookup(key: AccessKey): Promise<Identity> {- const get = async (path: string): Promise<Record<string, any> | undefined> => {+ const get = async <S extends z.ZodType>(path: string, schema: S): Promise<z.output<S> | undefined> => {try {const response = await this.runtime.fetch(new URL(path, key.host), {headers: { Authorization: `Bearer ${key.token}` },signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),})- return response.ok ? ((await response.json()) as Record<string, any>) : undefined+ return response.ok ? parseJsonOrUndefined(await response.text(), schema) : undefined} catch {return undefined}}- const [user, project] = await Promise.all([get('/api/users/@me/'), get(`/api/projects/${key.projectId}/`)])+ const [user, project] = await Promise.all([+ get('/api/users/@me/', IdentityUser),+ get(`/api/projects/${key.projectId}/`, IdentityProject),+ ])return {- distinctId: text(user?.distinct_id),- organization: text(project?.organization) ?? text(user?.organization?.id),- project: text(project?.uuid),+ distinctId: user?.distinct_id,+ organization: project?.organization ?? user?.organization?.id,+ project: project?.uuid,}}diff --git a/hog/src/endpoints/api.ts b/hog/src/endpoints/api.tsindex b4ca0daf20e1..6a6b93b0dc3c 100644--- a/hog/src/endpoints/api.ts+++ b/hog/src/endpoints/api.ts@@ -1,47 +1,50 @@-import type { PostHogApi } from '@/posthog/api'+import { z } from 'zod'-import type { Endpoint, InsightVariable } from './model'+import type { PostHogApi } from '@/posthog/api'-interface Page<T> {- results: T[]- next?: string | null-}+import { Endpoint, InsightVariable } from './model'-// Follows `next` links, so a project with more endpoints than one page holds still gets all of them.-async function all<T>(api: PostHogApi, path: string): Promise<T[]> {- const results: T[] = []+// Follows `next` links+async function all<S extends z.ZodType>(api: PostHogApi, path: string, item: S): Promise<z.output<S>[]> {+ const page = z.looseObject({ results: z.array(item), next: z.string().nullish() })+ const results: z.output<S>[] = []let next: string | null | undefined = pathwhile (next) {- const page: Page<T> = await api.get<Page<T>>(next)- results.push(...page.results)- next = page.next ? new URL(page.next).pathname + new URL(page.next).search : undefined+ const current: { results: z.output<S>[]; next?: string | null } = await api.get(next, page)+ results.push(...current.results)+ next = current.next ? new URL(current.next).pathname + new URL(current.next).search : undefined}return results}export function listEndpoints(api: PostHogApi): Promise<Endpoint[]> {- return all<Endpoint>(api, 'endpoints/')+ return all(api, 'endpoints/', Endpoint)}export function getEndpoint(api: PostHogApi, name: string): Promise<Endpoint> {- return api.get<Endpoint>(`endpoints/${encodeURIComponent(name)}/`)+ return api.get(`endpoints/${encodeURIComponent(name)}/`, Endpoint)}-export function listInsightVariables(api: PostHogApi): Promise<InsightVariable[]> {- return all<InsightVariable>(api, 'insight_variables/')+// PostHog allows a variable without a code name, which no query can reference, so the list leaves+// it out.+const ListedVariable = InsightVariable.extend({ code_name: z.string().nullable() })++export async function listInsightVariables(api: PostHogApi): Promise<InsightVariable[]> {+ const variables = await all(api, 'insight_variables/', ListedVariable)+ return variables.flatMap(({ code_name, ...variable }) => (code_name === null ? [] : [{ ...variable, code_name }]))}export function createInsightVariable(api: PostHogApi,variable: { code_name: string; type: string; default_value?: unknown; is_multi?: boolean }): Promise<InsightVariable> {- return api.post<InsightVariable>('insight_variables/', { name: variable.code_name, ...variable })+ return api.post('insight_variables/', { name: variable.code_name, ...variable }, InsightVariable)}export function createEndpoint(api: PostHogApi, body: Record<string, unknown>): Promise<Endpoint> {- return api.post<Endpoint>('endpoints/', body)+ return api.post('endpoints/', body, Endpoint)}export function updateEndpoint(api: PostHogApi, name: string, body: Record<string, unknown>): Promise<Endpoint> {- return api.patch<Endpoint>(`endpoints/${encodeURIComponent(name)}/`, body)+ return api.patch(`endpoints/${encodeURIComponent(name)}/`, body, Endpoint)}diff --git a/hog/src/endpoints/model.ts b/hog/src/endpoints/model.tsindex 2e9eee95975e..95b81d0c67f3 100644--- a/hog/src/endpoints/model.ts+++ b/hog/src/endpoints/model.ts@@ -61,39 +61,43 @@ export const EndpointFile = zexport type EndpointFile = z.infer<typeof EndpointFile>export type EndpointVariable = NonNullable<EndpointFile['variables']>[number]-export interface MaterializationStatus {- status?: string | null- can_materialize?: boolean- last_materialized_at?: string | null- error?: string | null- reason?: string | null-}+// The API answers keep fields hog doesn't name, because `hog endpoints get` prints the whole answer.+const MaterializationStatus = z.looseObject({+ status: z.string().nullish(),+ can_materialize: z.boolean().optional(),+ last_materialized_at: z.string().nullish(),+ error: z.string().nullish(),+ reason: z.string().nullish(),+})-export interface Endpoint {- id: string- name: string- description?: string | null- query: Record<string, unknown>- is_active: boolean- data_freshness_seconds?: number | null- endpoint_path?: string- url?: string | null- ui_url?: string | null- created_at: string- updated_at: string- is_materialized: boolean- current_version?: number- versions_count?: number- materialization?: MaterializationStatus | null-}+export const Endpoint = z.looseObject({+ id: z.string(),+ name: z.string(),+ description: z.string().nullish(),+ query: z.record(z.string(), z.unknown()),+ is_active: z.boolean(),+ data_freshness_seconds: z.number().nullish(),+ url: z.string().nullish(),+ ui_url: z.string().nullish(),+ created_at: z.string(),+ updated_at: z.string(),+ is_materialized: z.boolean(),+ current_version: z.number().optional(),+ versions_count: z.number().optional(),+ materialization: MaterializationStatus.nullish(),+})-export interface InsightVariable {- id: string- name: string- code_name: string- type: string- default_value?: unknown-}+export type Endpoint = z.infer<typeof Endpoint>++export const InsightVariable = z.looseObject({+ id: z.string(),+ name: z.string(),+ code_name: z.string(),+ type: z.string(),+ default_value: z.unknown().optional(),+})++export type InsightVariable = z.infer<typeof InsightVariable>const VARIABLE_REFERENCE = /\{variables\.([a-zA-Z_][a-zA-Z0-9_]*)\}/gdiff --git a/hog/src/error-tracking/release.ts b/hog/src/error-tracking/release.tsindex 9ca5069f19b4..34070846971a 100644--- a/hog/src/error-tracking/release.ts+++ b/hog/src/error-tracking/release.ts@@ -1,15 +1,14 @@+import { z } from 'zod'+import { HogError } from '@/core/errors'import { contentHash } from './container'import type { GitInfo } from './git'import { ApiFailure, errorCode, type SymbolSetClient } from './upload'-export interface Release {- id: string- hash_id: string- version: string- project: string-}+const Release = z.object({ id: z.string(), hash_id: z.string(), version: z.string(), project: z.string() })++export type Release = z.output<typeof Release>export interface ReleaseFields {name?: string@@ -59,7 +58,7 @@ export async function findRelease(async function lookup(client: SymbolSetClient, hashId: string): Promise<Release | undefined> {try {- return (await client.api('GET', `error_tracking/releases/hash/${hashId}`)) as Release+ return await client.api('GET', `error_tracking/releases/hash/${hashId}`, Release)} catch (error) {if (error instanceof ApiFailure && error.status === 404) {return undefined@@ -94,7 +93,7 @@ export async function fetchOrCreateRelease(}Object.assign(body, { hash_id: hashId, version, project: name })try {- const created = (await client.api('POST', 'error_tracking/releases', body)) as Release+ const created = await client.api('POST', 'error_tracking/releases', Release, body)return { ...created, id: created.id.toLowerCase() }} catch (error) {if (error instanceof ApiFailure && errorCode(error.body) === 'release_hash_in_use') {diff --git a/hog/src/error-tracking/symbols.ts b/hog/src/error-tracking/symbols.tsindex ff376fe41a04..5cfd84e1f088 100644--- a/hog/src/error-tracking/symbols.ts+++ b/hog/src/error-tracking/symbols.ts@@ -1,6 +1,7 @@import { mkdirSync, writeFileSync } from 'node:fs'import { dirname, isAbsolute, join, relative, resolve } from 'node:path'import { inflateRawSync, zstdDecompressSync } from 'node:zlib'+import { z } from 'zod'import { HogError } from '@/core/errors'import type { RuntimeFetch } from '@/core/runtime'@@ -326,8 +327,13 @@ const UUID = /^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$export const isSymbolSetId = (text: string): boolean => UUID.test(text)+const SymbolSetPage = z+ .looseObject({ results: z.array(z.looseObject({ id: z.string().optional() })).optional() })+ .optional()+const SymbolSetDownload = z.object({ url: z.string() })+// Turns the answers people can act on into errors with a next step. Others keep their message.-async function lookup(request: () => Promise<unknown>, notFound?: string): Promise<unknown> {+async function lookup<T>(request: () => Promise<T>, notFound?: string): Promise<T> {try {return await request()} catch (error) {@@ -346,11 +352,9 @@ async function lookup(request: () => Promise<unknown>, notFound?: string): Promi}export async function resolveRef(client: SymbolSetClient, reference: string): Promise<string> {- const found = (await lookup(() =>- client.api('GET', `error_tracking/symbol_sets/?ref=${encodeComponent(reference)}&limit=1`)- )) as {- results?: { id?: string }[]- }+ const found = await lookup(() =>+ client.api('GET', `error_tracking/symbol_sets/?ref=${encodeComponent(reference)}&limit=1`, SymbolSetPage)+ )const id = found?.results?.[0]?.idif (!id) {throw new HogError(@@ -370,10 +374,10 @@ export async function downloadSymbolSet(if (!isSymbolSetId(id)) {throw new HogError('invalid_symbol_set_id', `${id} isn't a symbol set ID.`, 'Symbol set IDs are UUIDs.')}- const { url } = (await lookup(- () => client.api('GET', `error_tracking/symbol_sets/${id}/download/`),+ const { url } = await lookup(+ () => client.api('GET', `error_tracking/symbol_sets/${id}/download/`, SymbolSetDownload),`No symbol set has the ID ${id}.`- )) as { url: string }+ )try {const response = await fetcher(url, { timeoutMs: DOWNLOAD_TIMEOUT_MS, skipRateLimit: true })if (!response.ok) {diff --git a/hog/src/error-tracking/upload.ts b/hog/src/error-tracking/upload.tsindex 2d48f49fe15e..2838255d1ef2 100644--- a/hog/src/error-tracking/upload.ts+++ b/hog/src/error-tracking/upload.ts@@ -3,6 +3,7 @@ import { z } from 'zod'import { HogError } from '@/core/errors'import { parseJson, parseJsonOrUndefined } from '@/core/json'import type { Runtime } from '@/core/runtime'+import { parseOrThrow } from '@/core/schema'import { USER_AGENT } from '@/posthog/api'import { hostUrl } from '@/posthog/host'import type { KeySession } from '@/posthog/key-session'@@ -48,9 +49,9 @@ function transferTimeout(bytes: number): number {}const RATE_LIMIT_PER_MINUTE = 480-const ErrorBody = z.looseObject({ code: z.unknown() })+const ErrorBody = z.object({ code: z.string() })-export function errorCode(body: string): unknown {+export function errorCode(body: string): string | undefined {return parseJsonOrUndefined(body, ErrorBody)?.code}@@ -128,18 +129,23 @@ export function uuidv7(now: number): string {return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`}-interface PresignedPost {- url: string- fields: Record<string, string>-}+const PresignedPost = z.object({ url: z.string(), fields: z.record(z.string(), z.string()) })-interface StartEntry {- presigned_url: PresignedPost- fallback_presigned_url?: PresignedPost | null- presigned_put_url?: string | null- fallback_presigned_put_url?: string | null- symbol_set_id: string-}+type PresignedPost = z.output<typeof PresignedPost>++const StartEntry = z.object({+ // Null when PostHog couldn't sign a POST, in which case it sends a PUT URL.+ presigned_url: PresignedPost.nullish(),+ fallback_presigned_url: PresignedPost.nullish(),+ presigned_put_url: z.string().nullish(),+ fallback_presigned_put_url: z.string().nullish(),+ symbol_set_id: z.string(),+})++type StartEntry = z.output<typeof StartEntry>++const CheckResponse = z.object({ chunk_ids_to_upload: z.array(z.string()) })+const StartResponse = z.object({ id_map: z.record(z.string(), StartEntry).nullish() })type Target = { kind: 'put'; url: string } | { kind: 'post'; form: PresignedPost }@@ -163,7 +169,12 @@ export class SymbolSetClient {return new URL(path, hostUrl(host, `api/projects/${projectId}/`))}- async api(method: 'GET' | 'POST', path: string, body?: unknown): Promise<unknown> {+ async api<S extends z.ZodType>(+ method: 'GET' | 'POST',+ path: string,+ schema: S,+ body?: unknown+ ): Promise<z.output<S>> {await this.throttle.wait()const url = this.projectUrl(path)// Only a failed request becomes an ApiFailure. A renewal that fails keeps its own error and hint.@@ -188,12 +199,11 @@ export class SymbolSetClient {if (!response.ok) {throw new ApiFailure(response.status, text, url.toString())}- return text- ? parseJson(text, z.unknown(), {- code: 'unexpected_response',- context: `PostHog answered ${url} with a body hog can't read.`,- })- : undefined+ const failure = {+ code: 'unexpected_response',+ context: `PostHog's answer to ${method} ${url.pathname} isn't what hog expects.`,+ }+ return text ? parseJson(text, schema, failure) : parseOrThrow(schema, undefined, failure)}async upload(uploads: SymbolSetUpload[], options: UploadOptions): Promise<UploadOutcome> {@@ -269,11 +279,13 @@ export class SymbolSetClient {for (let start = 0; start < uploads.length; start += CHECK_BATCH_SIZE) {const slice = uploads.slice(start, start + CHECK_BATCH_SIZE)try {- const response = (await withRetries(+ // The answer is checked after the retries, because an answer of the wrong shape is+ // not worth sending the request again for.+ const answer = await withRetries(this.runtime,3,() =>- this.api('POST', 'error_tracking/symbol_sets/bulk_check_upload', {+ this.api('POST', 'error_tracking/symbol_sets/bulk_check_upload', z.unknown(), {symbol_sets: slice.map((upload) => this.entry(upload)),force: options.force,skip_on_conflict: options.skipOnConflict,@@ -285,12 +297,13 @@ export class SymbolSetClient {error.status >= 400 &&error.status < 500)- )) as { chunk_ids_to_upload?: unknown }- if (!Array.isArray(response?.chunk_ids_to_upload)) {- throw new Error('unexpected check response')- }+ )+ const response = parseOrThrow(CheckResponse, answer, {+ code: 'unexpected_response',+ context: "PostHog's answer to the upload check isn't what hog expects.",+ })for (const chunkId of response.chunk_ids_to_upload) {- needed.add(String(chunkId))+ needed.add(chunkId)}} catch {for (const upload of uploads.slice(start)) {@@ -310,16 +323,20 @@ export class SymbolSetClient {const attemptId = uuidv7(this.runtime.now())let idMap: Record<string, StartEntry>try {- const response = (await withRetries(this.runtime, 3, () =>- this.api('POST', 'error_tracking/symbol_sets/bulk_start_upload', {+ const answer = await withRetries(this.runtime, 3, () =>+ this.api('POST', 'error_tracking/symbol_sets/bulk_start_upload', z.unknown(), {symbol_sets: batch.map((upload) => this.entry(upload)),upload_attempt_id: attemptId,upload_run_id: runId,force: options.force,skip_on_conflict: options.skipOnConflict,})- )) as { id_map?: Record<string, StartEntry> }- idMap = response?.id_map ?? {}+ )+ idMap =+ parseOrThrow(StartResponse, answer, {+ code: 'unexpected_response',+ context: "PostHog's answer to the upload start isn't what hog expects.",+ }).id_map ?? {}} catch (error) {throw startFailure(error)}@@ -353,7 +370,7 @@ export class SymbolSetClient {}try {await withRetries(this.runtime, 3, () =>- this.api('POST', 'error_tracking/symbol_sets/bulk_finish_upload', {+ this.api('POST', 'error_tracking/symbol_sets/bulk_finish_upload', z.unknown(), {content_hashes: finishHashes,upload_attempt_id: attemptId,upload_run_id: runId,@@ -372,9 +389,18 @@ export class SymbolSetClient {// Sends one container to object storage. A target falls back to its alternate endpoint after two// transport errors in a row on the primary, like posthog-cli's endpoint router.private async store(data: Uint8Array, entry: StartEntry): Promise<void> {- const primary: Target = entry.presigned_put_url+ const primary: Target | undefined = entry.presigned_put_url? { kind: 'put', url: entry.presigned_put_url }- : { kind: 'post', form: entry.presigned_url }+ : entry.presigned_url+ ? { kind: 'post', form: entry.presigned_url }+ : undefined+ if (primary === undefined) {+ throw new HogError(+ 'unexpected_response',+ `PostHog sent no upload URL for symbol set ${entry.symbol_set_id}.`,+ 'Run the upload again.'+ )+ }const fallbackUrl = entry.presigned_put_url ? entry.fallback_presigned_put_url : entry.fallback_presigned_urlconst fallback: Target | undefined = !fallbackUrl? undefineddiff --git a/hog/src/posthog/access-key.ts b/hog/src/posthog/access-key.tsindex 863e2abc91b2..5ef2476a2521 100644--- a/hog/src/posthog/access-key.ts+++ b/hog/src/posthog/access-key.ts@@ -1,3 +1,5 @@+import { z } from 'zod'+import type { ApiKeyAccess } from '@posthog/mcp/src/cli/library-types'import { HogError } from '@/core/errors'@@ -60,6 +62,14 @@ export interface AccessKey {const KEY_CHECK_TIMEOUT_MS = 30_000+// If hog doesn't recognize a scope, it drops it instead of failing the login+const KeyScopes = z.object({+ scopes: z+ .array(z.unknown())+ .transform((scopes) => scopes.filter((scope) => typeof scope === 'string'))+ .catch([]),+})+export class PersonalAPIKey implements AccessKey {readonly host: Hostreadonly projectId: ProjectId@@ -125,14 +135,9 @@ export class PersonalAPIKey implements AccessKey {'Check the host, then run the command again.')}- const scopes = (response.json as { scopes?: unknown } | undefined)?.scopesconst { host, projectId, apiKey } = this- return new PersonalAPIKey({- host,- projectId,- apiKey,- scopes: Array.isArray(scopes) ? scopes.filter((scope) => typeof scope === 'string') : [],- })+ const scopes = KeyScopes.safeParse(response.json).data?.scopes ?? []+ return new PersonalAPIKey({ host, projectId, apiKey, scopes })}// A personal API key can't be revoked from hog, so logout says where to delete it.diff --git a/hog/src/posthog/api.ts b/hog/src/posthog/api.tsindex 8eed32462994..ce4892ab4b16 100644--- a/hog/src/posthog/api.ts+++ b/hog/src/posthog/api.ts@@ -1,6 +1,9 @@+import { z } from 'zod'+import { HogError } from '@/core/errors'import { parseLosslessJson } from '@/core/json'import type { RuntimeFetch } from '@/core/runtime'+import { parseOrThrow } from '@/core/schema'import { VERSION } from '@/version'import { hostUrl } from './host'@@ -81,6 +84,14 @@ export class ApiError extends HogError {}}+// A DRF error body. `type` is the DRF error type, such as `validation_error`.+// A field of another type reads as missing, so the others still reach the error message.+const DRFErrorBody = z.object({+ type: z.string().optional().catch(undefined),+ code: z.string().optional().catch(undefined),+ detail: z.string().optional().catch(undefined),+})+export class PostHogApi {constructor(private readonly session: KeySession,@@ -107,23 +118,26 @@ export class PostHogApi {return url}- get<T>(path: string): Promise<T> {- return this.request<T>('GET', path)+ // Each call names the schema of the answer it expects, so a command never works with a shape+ // PostHog didn't send.+ get<S extends z.ZodType>(path: string, schema: S): Promise<z.output<S>> {+ return this.request('GET', path, schema)}- post<T>(path: string, body: unknown): Promise<T> {- return this.request<T>('POST', path, body)+ post<S extends z.ZodType>(path: string, body: unknown, schema: S): Promise<z.output<S>> {+ return this.request('POST', path, schema, body)}- patch<T>(path: string, body: unknown): Promise<T> {- return this.request<T>('PATCH', path, body)+ patch<S extends z.ZodType>(path: string, body: unknown, schema: S): Promise<z.output<S>> {+ return this.request('PATCH', path, schema, body)}- delete<T>(path: string): Promise<T> {- return this.request<T>('DELETE', path)- }-- private async request<T>(method: Method, path: string, body?: unknown): Promise<T> {+ private async request<S extends z.ZodType>(+ method: Method,+ path: string,+ schema: S,+ body?: unknown+ ): Promise<z.output<S>> {const url = this.url(path)const response = await this.session.send((token) => sendRequest(this.fetchFn, url, { method, body, token }),@@ -139,11 +153,15 @@ export class PostHogApi {if (!response.ok) {throw this.failure(response.status, response.json)}- return response.json as T+ return parseOrThrow(schema, response.json, {+ code: 'unexpected_response',+ context: `PostHog's answer to ${method} ${url.pathname} isn't what hog expects.`,+ hint: 'Check that the host runs a recent version of PostHog.',+ })}private failure(status: number, body: unknown): ApiError {- const error = (body ?? {}) as { type?: string; code?: string; detail?: string }+ const error = DRFErrorBody.safeParse(body).data ?? {}const hints: Record<number, string> = {401: 'Check that the personal API key is valid.',403: 'Check that the personal API key has access to this project.',diff --git a/hog/src/posthog/auth-status.ts b/hog/src/posthog/auth-status.tsindex 5a5242be22ce..a12064a8964d 100644--- a/hog/src/posthog/auth-status.ts+++ b/hog/src/posthog/auth-status.ts@@ -1,3 +1,5 @@+import { z } from 'zod'+import type { Context } from '@/core/context'import { HogError } from '@/core/errors'import type { StoreChoice } from '@/posthog/credential-store/types'@@ -50,8 +52,8 @@ export async function checkAuthStatus(ctx: Context): Promise<AuthStatus> {const { kind, scopes, expiresAt, rejected } = key.status()const api = await ctx.posthog()const [user, project] = await Promise.allSettled([- api.get<{ email: string; first_name?: string }>('/api/users/@me/'),- api.get<{ name: string }>(''),+ api.get('/api/users/@me/', z.looseObject({ email: z.string(), first_name: z.string().nullish() })),+ api.get('', z.looseObject({ name: z.string().nullish() })),])const failures = [user, project].flatMap((outcome) => (outcome.status === 'rejected' ? [outcome.reason] : []))if (failures.some((failure) => failure instanceof ApiError && failure.status === 401)) {@@ -73,7 +75,7 @@ export async function checkAuthStatus(ctx: Context): Promise<AuthStatus> {authenticated: true,host,projectId,- projectName: project.status === 'fulfilled' ? project.value.name : null,+ projectName: project.status === 'fulfilled' ? (project.value.name ?? null) : null,kind,source,store: credentials.source === 'store' ? credentials.store : null,diff --git a/hog/src/posthog/device-auth.ts b/hog/src/posthog/device-auth.tsindex 9e86b155cafc..be2d40e0e5b5 100644--- a/hog/src/posthog/device-auth.ts+++ b/hog/src/posthog/device-auth.ts@@ -4,10 +4,12 @@ import { PendingApprovalSchema, type PollOutcome } from '@/core/approval'import { HogError } from '@/core/errors'import { escapeControls } from '@/core/output'import type { Runtime } from '@/core/runtime'+import { parseOrThrow } from '@/core/schema'import { hostKey, HostSchema, hostUrl, type Host } from './host'-import { parseProjectId } from './ids'-import { HOG_CLIENT_ID, OAuthLogin, oauthPost, type TokenResponse } from './oauth'+import { ProjectIdSchema } from './ids'+import { HOG_CLIENT_ID, OAuthErrorBody, OAuthLogin, oauthPost, TokenResponse } from './oauth'+import { OAuthRefreshTokenSchema } from './tokens'const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'@@ -98,8 +100,8 @@ export const PendingLoginSchema = PendingApprovalSchema.extend({export type PendingLogin = z.output<typeof PendingLoginSchema>// PostHog refuses a client it hasn't verified with `unauthorized_client`, and its description says why.-function unauthorizedClient(host: Host, body: { error?: string; error_description?: unknown }): HogError | undefined {- if (body.error !== 'unauthorized_client' || typeof body.error_description !== 'string') {+function unauthorizedClient(host: Host, body: OAuthError | undefined): HogError | undefined {+ if (body?.error !== 'unauthorized_client' || body.error_description === undefined) {return undefined}return new HogError(@@ -109,14 +111,22 @@ function unauthorizedClient(host: Host, body: { error?: string; error_descriptio)}-interface DeviceAuthorizationResponse {- device_code?: string- user_code?: string- verification_uri?: string- verification_uri_complete?: string- expires_in?: number- interval?: number-}+type OAuthError = z.output<typeof OAuthErrorBody>++// A new login has no earlier refresh token or project to fall back on.+const DeviceTokenResponse = TokenResponse.extend({+ refresh_token: OAuthRefreshTokenSchema,+ scoped_teams: z.tuple([ProjectIdSchema], ProjectIdSchema),+})++const DeviceAuthorizationResponse = z.object({+ device_code: z.string().min(1),+ user_code: z.string().min(1),+ verification_uri: z.string().min(1),+ verification_uri_complete: z.string().optional(),+ expires_in: z.number().positive(),+ interval: z.number().optional(),+})// hog opens the approval page only on the host it logs in to. A server that names another origin could// send the person to a look-alike page, and the code check wouldn't catch it: that server chose the code.@@ -141,12 +151,12 @@ export async function startDeviceLogin(runtime: Runtime, host: Host, scopes: rea'Wait a minute, then run `hog auth login` again.')}- const body = (response.json ?? {}) as DeviceAuthorizationResponse & { error?: string; error_description?: unknown }- const refused = unauthorizedClient(host, body)+ const refused = unauthorizedClient(host, OAuthErrorBody.safeParse(response.json).data)if (refused) {throw refused}- if (!response.ok || !body.device_code || !body.user_code || !body.verification_uri || !body.expires_in) {+ const body = response.ok ? DeviceAuthorizationResponse.safeParse(response.json).data : undefined+ if (body === undefined) {throw new HogError('login_unavailable',`${host} didn't start a login: it answered with HTTP ${response.status}.`,@@ -184,29 +194,20 @@ export async function pollDeviceLogin(if (response.status >= 500) {return { state: 'retry', reason: `PostHog answered with HTTP ${response.status}.` }}- const body = (response.json ?? {}) as TokenResponse & { error?: string; error_description?: unknown }if (response.ok) {- const scopedTeam = body.scoped_teams?.[0]- if (scopedTeam === undefined || !body.refresh_token) {- throw new HogError(- 'unexpected_response',- 'PostHog approved the login, but its answer had no project or no refresh token.',- 'Run `hog auth login` to start again.'- )- }+ const body = parseOrThrow(DeviceTokenResponse, response.json, {+ code: 'unexpected_response',+ context: "PostHog approved the login, but its answer isn't what hog expects.",+ hint: 'Run `hog auth login` to start again.',+ })+ const [projectId] = body.scoped_teamsreturn {state: 'approved',- value: OAuthLogin.fromTokens(runtime, body, {- host: pending.host,- projectId: parseProjectId(scopedTeam, {- code: 'unexpected_response',- hint: 'Run `hog auth login` to start again.',- }),- scopes: pending.scopes,- }),+ value: OAuthLogin.fromTokens(runtime, body, { host: pending.host, projectId, scopes: pending.scopes }),}}- switch (body.error) {+ const body = OAuthErrorBody.safeParse(response.json).data+ switch (body?.error) {case 'authorization_pending':return { state: 'pending' }case 'slow_down':diff --git a/hog/src/posthog/oauth.test.ts b/hog/src/posthog/oauth.test.tsindex c39889c0ab79..deadd3a646b7 100644--- a/hog/src/posthog/oauth.test.ts+++ b/hog/src/posthog/oauth.test.ts@@ -75,7 +75,7 @@ describe('OAuth credentials', () => {const api = new PostHogApi(sessionFor(runtime, await resolveCredentials(runtime, {})), runtime.fetch)await runtime.sleep(commandRunsMs)- const outcome = await api.get<{ name: string }>('').catch((error: unknown) => error)+ const outcome = await api.get('', z.looseObject({ name: z.string() })).catch((error: unknown) => error)expect(outcome).toMatchObject(expected)expect(tokenRequests(runtime)).toHaveLength(1)@@ -94,8 +94,8 @@ describe('OAuth credentials', () => {const api = new PostHogApi(sessionFor(runtime, await resolveCredentials(runtime, {})), runtime.fetch)const outcomes = [- await api.get('').catch((error: unknown) => error),- await api.get('').catch((error: unknown) => error),+ await api.get('', z.unknown()).catch((error: unknown) => error),+ await api.get('', z.unknown()).catch((error: unknown) => error),]expect(outcomes).toMatchObject([REJECTED, REJECTED])@@ -114,7 +114,7 @@ describe('OAuth credentials', () => {runtime.files[SETTINGS_FILE] = JSON.stringify(replaced)runtime.keychain[EU] = secret('pha_other')- const outcome = await api.get('').catch((error: unknown) => error)+ const outcome = await api.get('', z.unknown()).catch((error: unknown) => error)expect(outcome).toMatchObject({ code: 'login_changed' })expect(tokenRequests(runtime)).toEqual([])@@ -129,7 +129,7 @@ describe('OAuth credentials', () => {})const api = new PostHogApi(sessionFor(runtime, await resolveCredentials(runtime, {})), runtime.fetch)- const outcome = await api.get('').catch((error: unknown) => error)+ const outcome = await api.get('', z.unknown()).catch((error: unknown) => error)expect(outcome).toMatchObject(REJECTED)expect(runtime.requests).toHaveLength(1)diff --git a/hog/src/posthog/oauth.ts b/hog/src/posthog/oauth.tsindex af97136a6edf..6a6c4f51ce74 100644--- a/hog/src/posthog/oauth.ts+++ b/hog/src/posthog/oauth.ts@@ -1,18 +1,25 @@import { createHash, randomUUID } from 'node:crypto'+import { z } from 'zod'import type { ApiKeyAccess } from '@posthog/mcp/src/cli/library-types'import { HogError } from '@/core/errors'import { withFileLock } from '@/core/file-lock'import type { Runtime } from '@/core/runtime'+import { parseOrThrow } from '@/core/schema'import type { OAuthSecret, StoreChoice } from '@/posthog/credential-store/types'import type { AccessKey, AccessKeyStatus, AccessKeyStorage, LogoutOutcome } from './access-key'import { sendRequest, type HttpResponse } from './api'import { hostKey, hostUrl, type Host } from './host'-import type { ProjectId } from './ids'+import { ProjectIdSchema, type ProjectId } from './ids'import type { LoginRecord } from './settings'-import { parseOAuthAccessToken, parseOAuthRefreshToken, type OAuthAccessToken, type OAuthRefreshToken } from './tokens'+import {+ OAuthAccessTokenSchema,+ OAuthRefreshTokenSchema,+ type OAuthAccessToken,+ type OAuthRefreshToken,+} from './tokens'// hog's CIMD client ID: the URL of its client metadata document, which PostHog fetches.export const HOG_CLIENT_ID = 'https://posthog.com/.well-known/oauth/hog/client-metadata.json'@@ -21,13 +28,21 @@ const REQUEST_TIMEOUT_MS = 30_000// Refresh this long before the access token expires, so it doesn't expire during a command.const REFRESH_MARGIN_MS = 10 * 60_000-export interface TokenResponse {- access_token?: string- refresh_token?: string- expires_in?: number- scope?: string- scoped_teams?: number[]-}+export const TokenResponse = z.object({+ access_token: OAuthAccessTokenSchema,+ refresh_token: OAuthRefreshTokenSchema.optional(),+ expires_in: z.number(),+ scope: z.string().optional(),+ scoped_teams: z.array(ProjectIdSchema).optional(),+})++export type TokenResponse = z.output<typeof TokenResponse>++// An RFC 6749 error answer. hog reads `error` only when the answer is one.+export const OAuthErrorBody = z.object({+ error: z.string().optional().catch(undefined),+ error_description: z.string().optional().catch(undefined),+})export function oauthPost(runtime: Runtime,@@ -93,19 +108,19 @@ export class OAuthLogin implements AccessKey {loginId?: string}): OAuthLogin {- if (!body.access_token || body.expires_in === undefined) {+ const refreshToken = body.refresh_token ?? previous.refreshToken+ if (refreshToken === undefined) {throw new HogError('unexpected_response',- 'PostHog answered without an access token.',+ 'PostHog answered without a refresh token.','Run `hog auth login` to log in again.')}- const unexpected = { code: 'unexpected_response' }return new OAuthLogin({host: previous.host,projectId: previous.projectId,- accessToken: parseOAuthAccessToken(body.access_token, unexpected),- refreshToken: parseOAuthRefreshToken(body.refresh_token ?? previous.refreshToken, unexpected),+ accessToken: body.access_token,+ refreshToken,expiresAt: runtime.now() + body.expires_in * 1000,scopes: body.scope ? body.scope.split(' ').filter(Boolean) : previous.scopes,loginId: previous.loginId ?? randomUUID(),@@ -186,11 +201,15 @@ export class OAuthLogin implements AccessKey {refresh_token: this.refreshToken,client_id: HOG_CLIENT_ID,})- const body = (response.json ?? {}) as TokenResponse & { error?: string }if (response.ok) {+ const body = parseOrThrow(TokenResponse, response.json, {+ code: 'unexpected_response',+ context: "PostHog's answer to the renewal isn't what hog expects.",+ hint: 'Run `hog auth login` to log in again.',+ })return OAuthLogin.fromTokens(runtime, body, this)}- if (body.error === 'invalid_grant') {+ if (OAuthErrorBody.safeParse(response.json).data?.error === 'invalid_grant') {throw new HogError('session_expired','Your hog login expired or was revoked.',