: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 { isRecord } from '@/lib/records'
import type { ReportPriority } from '@/model/types'
import { type DismissReason, type ResolveReason, VERDICT_NOTE_MAX_LENGTH } from '@/model/verdictReasons'
import type {
PullRequestChecksResponseApi,
SignalsReportsListParams,
} from '../../../signals/frontend/generated/api.schemas'
import { ApiError, apiJson, apiUrl, projectPath } from './client'
// Shapes follow `products/signals/backend/serializers.py` and `report_read_state.py`, keeping the fields the app reads.
export interface ReportUserApi {
uuid: string
first_name: string
last_name: string
email: string
}
export interface ReportAssigneeApi {
claim_id?: string | null
kind: 'user' | 'task' | 'agent' | 'system'
user: ReportUserApi | null
task_id: string | null
agent: string | null
claimed_at: string | null
}
export interface ReportPullRequestApi {
id?: string | null
url: string
state: 'unknown' | 'draft' | 'open' | 'closed' | 'merged'
merged: boolean
review_decision: 'approved' | 'changes_requested' | 'review_required' | null
}
/** `ReportMetricSerializer`. `query` is only on the detail response, and null when redacted. */
export interface ReportMetricApi {
metric_id: string
title: string
kind: string
role: 'primary' | 'supporting'
/** Null means no snapshot for this viewer, never zero. */
value: number | null
value_at: string | null
/** Trailing per-bucket values, oldest first. */
series: number[] | null
value_format: 'number' | 'count' | 'percentage' | 'percentage_scaled' | 'duration' | 'currency'
unit: string | null
caption: string | null
/** An `InsightVizNode` with a `TrendsQuery` source. */
query?: unknown
}
export interface ReportChartApi {
chart_id: string
title: string
/** An `InsightVizNode`, a `DataVisualizationNode` (a `HogQLQuery` source) or a `SavedInsightNode` (a `shortId`). */
query: unknown
caption?: string | null
size?: 'small' | 'medium' | 'large' | null
}
export interface SignalReportApi {
id: string
title: string | null
summary: string | null
summary_lead: string
status: string
signal_count: number
/** Snooze threshold: the report comes back when `signal_count` reaches it. */
signals_at_run: number
created_at: string
updated_at: string
metrics: ReportMetricApi[]
charts: ReportChartApi[]
suggested_prompts: string[]
priority: string | null
actionability: string | null
already_addressed: boolean | null
is_suggested_reviewer: boolean
source_products: string[]
scout_name: string | null
implementation_pr_url: string | null
pull_requests: ReportPullRequestApi[]
work_state: 'unclaimed' | 'working' | 'in_review' | 'done'
assignee: ReportAssigneeApi | null
/** `ReportRankingSerializer`: outcome head name (such as `pr_merged`) to its probability. Null for non-staff users. */
ranking?: { scores: Record<string, number> } | null
}
export interface PaginatedApi<T> {
count: number
next: string | null
results: T[]
}
export interface SignalNodeApi {
signal_id: string
content: string
source_product: string
source_type: string
source_id: string
timestamp: string
extra: Record<string, unknown> | null
}
export interface ReportSignalsApi {
signals: SignalNodeApi[]
}
/** `SignalReportArtefactSerializer`. `content` is parsed JSON; its shape depends on `type` (`artefact_schemas.py`). */
export interface ReportArtefactApi {
id: string
type: string
content: unknown
created_at: string
actor_kind: 'user' | 'task' | 'agent' | 'system'
actor_agent: string | null
created_by: ReportUserApi | null
task_id: string | null
}
export interface SuggestedReviewerApi {
github_login: string | null
user_uuid: string | null
github_name: string | null
user: ReportUserApi | null
}
/** `SuggestedReviewerEntryWriteSerializer`. One of the two keys is required. */
export interface SuggestedReviewerWriteApi {
user_uuid?: string
github_login?: string
}
export type AvailableReviewersApi = Record<string, { name: string; email: string }>
export interface ReadStatesApi {
states: Record<string, boolean>
}
export interface ProjectScope {
/** Base URL of the PostHog instance, without a trailing slash. */
host: string
projectId: number
}
export function isMissingFeature(error: unknown): boolean {
return error instanceof ApiError && (error.status === 404 || error.status === 403)
}
export function retryUnlessMissing(failureCount: number, error: unknown): boolean {
return !isMissingFeature(error) && failureCount < 1
}
export type ScopeKey = readonly [string, number] | readonly ['none']
export function scopeKey(scope: ProjectScope | null): ScopeKey {
return scope ? [scope.host, scope.projectId] : ['none']
}
/** Query keys. Every key carries the host and project so a project switch never shows stale data. */
export const reportKeys = {
all: (scope: ProjectScope | null) => ['signals', ...scopeKey(scope)] as const,
inbox: (scope: ProjectScope | null) => [...reportKeys.all(scope), 'inbox'] as const,
readStates: (scope: ProjectScope | null, ids: readonly string[]) =>
[...reportKeys.all(scope), 'read_states', ids.join(',')] as const,
readStatesAll: (scope: ProjectScope | null) => [...reportKeys.all(scope), 'read_states'] as const,
report: (scope: ProjectScope | null, id: string) => [...reportKeys.all(scope), 'report', id] as const,
detail: (scope: ProjectScope | null, id: string) => [...reportKeys.report(scope, id), 'detail'] as const,
artefacts: (scope: ProjectScope | null, id: string) => [...reportKeys.report(scope, id), 'artefacts'] as const,
reviewers: (scope: ProjectScope | null, id: string) => [...reportKeys.artefacts(scope, id), 'reviewers'] as const,
signals: (scope: ProjectScope | null, id: string) => [...reportKeys.report(scope, id), 'signals'] as const,
page: (scope: ProjectScope | null, id: string) => ['today', ...scopeKey(scope), 'page', id] as const,
task: (scope: ProjectScope | null, taskId: string | undefined) =>
['tasks', ...scopeKey(scope), 'task', taskId ?? ''] as const,
availableReviewers: (scope: ProjectScope | null, query: string) =>
[...reportKeys.all(scope), 'available_reviewers', query] as const,
}
export interface InboxPageApi {
results: SignalReportApi[]
count: number
next?: string | null
}
export const INBOX_PAGE_SIZE = 20
function isOptionalString(value: unknown): boolean {
return value === undefined || value === null || typeof value === 'string'
}
function isReportDate(value: unknown): boolean {
return typeof value === 'string' && Number.isFinite(Date.parse(value))
}
function isInboxPullRequest(value: unknown): boolean {
return (
isRecord(value) &&
typeof value.url === 'string' &&
typeof value.state === 'string' &&
typeof value.merged === 'boolean' &&
isOptionalString(value.id) &&
isOptionalString(value.review_decision)
)
}
const INBOX_REPORT_FIELDS = {
id: (value) => typeof value === 'string' && value.trim() !== '',
title: isOptionalString,
status: (value) => typeof value === 'string',
source_products: (value) => Array.isArray(value) && value.every((source) => typeof source === 'string'),
created_at: isReportDate,
updated_at: isReportDate,
signal_count: (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0,
is_suggested_reviewer: (value) => value === undefined || typeof value === 'boolean',
implementation_pr_url: isOptionalString,
pull_requests: (value) => Array.isArray(value) && value.every(isInboxPullRequest),
assignee: (value) => value == null || (isRecord(value) && typeof value.kind === 'string'),
ranking: (value) => {
if (value == null) return true
if (!isRecord(value)) return false
const scores = value.scores
if (scores == null) return true
if (!isRecord(scores)) return false
const score = scores.pr_merged
return score == null || (typeof score === 'number' && Number.isFinite(score))
},
} satisfies Partial<Record<keyof SignalReportApi, (value: unknown) => boolean>>
function isInboxReport(value: unknown): boolean {
return isRecord(value) && Object.entries(INBOX_REPORT_FIELDS).every(([field, validate]) => validate(value[field]))
}
export async function fetchInboxPage(offset: number, signal?: AbortSignal): Promise<InboxPageApi> {
const page = await apiJson<InboxPageApi>(projectPath('signals/reports/'), {
query: { view: 'for_you', sort: 'priority', limit: INBOX_PAGE_SIZE, offset } satisfies SignalsReportsListParams,
signal,
})
if (
!isRecord(page) ||
!Array.isArray(page.results) ||
!page.results.every(isInboxReport) ||
!Number.isSafeInteger(page.count) ||
page.count < 0 ||
(page.next !== undefined && page.next !== null && typeof page.next !== 'string')
) {
throw new Error("Couldn't load your inbox. Try again.")
}
return page
}
export function fetchReport(reportId: string, signal?: AbortSignal): Promise<SignalReportApi> {
return apiJson<SignalReportApi>(projectPath(`signals/reports/${encodeURIComponent(reportId)}/`), { signal })
}
export function fetchReportSignals(reportId: string, signal?: AbortSignal): Promise<ReportSignalsApi> {
return apiJson<ReportSignalsApi>(projectPath(`signals/reports/${encodeURIComponent(reportId)}/signals/`), {
signal,
})
}
export const ARTEFACT_PAGE_SIZE = 100
/** `GET signals/reports/{id}/artefacts/`, newest first. */
export function fetchReportArtefacts(
reportId: string,
signal?: AbortSignal,
offset = 0
): Promise<PaginatedApi<ReportArtefactApi>> {
return apiJson<PaginatedApi<ReportArtefactApi>>(
projectPath(`signals/reports/${encodeURIComponent(reportId)}/artefacts/`),
{
query: { limit: ARTEFACT_PAGE_SIZE, ...(offset ? { offset } : {}) },
signal,
}
)
}
/** Find the latest full reviewer assignment, which may be older than the first artefact page. */
export async function fetchLatestReviewerArtefact(
reportId: string,
signal?: AbortSignal
): Promise<ReportArtefactApi | null> {
const path = projectPath(`signals/reports/${encodeURIComponent(reportId)}/artefacts/`)
const firstUrl = new URL(apiUrl(path))
let offset = 0
for (;;) {
const page = await fetchReportArtefacts(reportId, signal, offset)
const reviewer = page.results.find((artefact) => artefact.type === 'suggested_reviewers')
if (reviewer || !page.next) {
return reviewer ?? null
}
const next = new URL(page.next, firstUrl)
const nextOffset = Number(next.searchParams.get('offset'))
if (
next.origin !== firstUrl.origin ||
next.pathname !== firstUrl.pathname ||
!Number.isSafeInteger(nextOffset) ||
nextOffset <= offset
) {
throw new Error('Invalid report artefact page')
}
offset = nextOffset
}
}
/** `read_state/` accepts at most this many ids per request. */
export const READ_STATE_BATCH = 100
/** Without `read` this only reads the states; with it, it sets them for the current user and returns the new states. */
export function postReadStates(reportIds: string[], read?: boolean, signal?: AbortSignal): Promise<ReadStatesApi> {
return apiJson<ReadStatesApi>(projectPath('signals/reports/read_state/'), {
method: 'POST',
json: read === undefined ? { report_ids: reportIds } : { report_ids: reportIds, read },
signal,
})
}
/** `POST signals/reports/{id}/state/` with `potential`: hides the report until `count` more signals arrive. */
export function snoozeReportForSignals(reportId: string, count: number): Promise<SignalReportApi> {
return apiJson<SignalReportApi>(projectPath(`signals/reports/${encodeURIComponent(reportId)}/state/`), {
method: 'POST',
json: { state: 'potential', snooze_for: count },
})
}
function postVerdict(
reportId: string,
state: 'resolved' | 'suppressed',
reason: ResolveReason | DismissReason,
note = ''
): Promise<SignalReportApi> {
const trimmed = note.trim().slice(0, VERDICT_NOTE_MAX_LENGTH)
return apiJson<SignalReportApi>(projectPath(`signals/reports/${encodeURIComponent(reportId)}/state/`), {
method: 'POST',
json: { state, dismissal_reason: reason, ...(trimmed ? { dismissal_note: trimmed } : {}) },
})
}
/**
* `POST signals/reports/{id}/state/` with `resolved`: marks the report done and closes its open implementation PR.
* A 409 means the report's current status cannot move to resolved; its `error` says why.
*/
export function resolveReport(reportId: string, reason: ResolveReason, note?: string): Promise<SignalReportApi> {
return postVerdict(reportId, 'resolved', reason, note)
}
/**
* `POST signals/reports/{id}/state/` with `suppressed`: the report leaves the inbox, and the agent that filed it reads
* the note on its next run. A 409 means the report's current status cannot move to suppressed; its `error` says why.
*/
export function dismissReport(reportId: string, reason: DismissReason, note?: string): Promise<SignalReportApi> {
return postVerdict(reportId, 'suppressed', reason, note)
}
/** `PUT signals/reports/{id}/reviewers/`: replaces the suggested reviewers. Returns the new artefact. */
export function putReportReviewers(reportId: string, content: SuggestedReviewerWriteApi[]): Promise<ReportArtefactApi> {
return apiJson<ReportArtefactApi>(projectPath(`signals/reports/${encodeURIComponent(reportId)}/reviewers/`), {
method: 'PUT',
json: { content },
})
}
/** `SignalReportArtefactWriteResponseSerializer`: the stored row, without the actor fields of the read shape. */
export interface ReportArtefactWriteApi {
id: string
report_id: string
type: string
content: unknown
created_at: string
task_id: string | null
}
/** `PriorityAssessment` requires a non-empty explanation. */
export const MANUAL_PRIORITY_EXPLANATION = 'Priority set by hand from the PostHog mobile app'
/** `POST signals/reports/{id}/artefacts/` with a `priority_judgment`: the newest one is the report's priority. */
export function postPriorityJudgment(reportId: string, priority: ReportPriority): Promise<ReportArtefactWriteApi> {
return apiJson<ReportArtefactWriteApi>(projectPath(`signals/reports/${encodeURIComponent(reportId)}/artefacts/`), {
method: 'POST',
json: { artefact_type: 'priority_judgment', content: { priority, explanation: MANUAL_PRIORITY_EXPLANATION } },
})
}
export function fetchAvailableReviewers(query: string, signal?: AbortSignal): Promise<AvailableReviewersApi> {
return apiJson<AvailableReviewersApi>(projectPath('signals/reports/available_reviewers/'), {
query: { query: query || undefined },
signal,
})
}
export function fetchReportPullRequestChecks(
reportId: string,
pullRequestId: string,
signal?: AbortSignal
): Promise<PullRequestChecksResponseApi> {
return apiJson<PullRequestChecksResponseApi>(
projectPath(`signals/reports/${encodeURIComponent(reportId)}/pr_checks/`),
{ query: { pull_request_id: pullRequestId }, signal }
)
}