: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 InfiniteData,
type QueryClient,
type QueryKey,
skipToken,
type UseQueryResult,
useInfiniteQuery,
useQueries,
useQuery,
useQueryClient,
} from '@tanstack/react-query'
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { NotSignedInError } from '@/api/client'
import { inboxCacheKey, type SavedInbox } from '@/api/readCacheKeys'
import {
fetchInboxPage,
INBOX_PAGE_SIZE,
type InboxPageApi,
type ProjectScope,
postReadStates,
READ_STATE_BATCH,
type ReadStatesApi,
reportKeys,
retryUnlessMissing,
} from '@/api/reports'
import { useAuthStore } from '@/auth/authStore'
import { useProjectScope } from '@/auth/useProjectScope'
import { useDataMode, useDemoMode } from '@/demo/demoMode'
import { useDemoInboxQuery } from '@/demo/hooks'
import { track } from '@/lib/analytics'
import { useConnectivity } from '@/lib/connectivity'
import { toError } from '@/lib/errors'
import { type AsyncAction, useAsyncAction } from '@/lib/useAsyncAction'
import { useNow } from '@/lib/useNow'
import { inboxFromReports, reportsFromPages, signalCountsFromReports } from '@/model/adapters/inbox'
import { connectionLoadingQuery, errorQuery, loadingQuery } from '@/model/queryStates'
import type { InboxItem, QueryState } from '@/model/types'
import { useAppActive } from '../handoff/useTaskRun'
import { useSnoozeEntries, wakeSnooze } from '../snooze/hooks'
import { applySnoozes } from '../snooze/snoozeEntries'
import { reportScopeError, useFeatureAccess } from '../views/useViewsAccess'
import { applyInboxFilters, DEFAULT_INBOX_FILTERS, type InboxFilters, isDefaultInboxFilters } from './filters'
/** The inbox list, which loads one page of reports at a time. */
export interface InboxQueryState extends QueryState<InboxItem[]> {
/** The server has ranked reports after the loaded ones. */
hasMore: boolean
isLoadingMore: boolean
/** The last next-page request failed. Only `retryLoadMore` sends it again. */
loadMoreFailed: boolean
/** For the list end coming into view. Does nothing after a failed next page. */
loadMore: () => void
retryLoadMore: () => void
matchedCount: number
totalCount: number
/** Loaded items before the filters, so a source filter can still offer the other sources. */
unfiltered: readonly InboxItem[] | undefined
}
type CapturedInboxPage = InboxPageApi & { capturedAt?: number }
type InboxPages = InfiniteData<CapturedInboxPage, number>
const noop = (): void => undefined
const noMorePages = { hasMore: false, isLoadingMore: false, loadMoreFailed: false, loadMore: noop, retryLoadMore: noop }
const noItems = { matchedCount: 0, totalCount: 0, unfiltered: undefined }
let accountGeneration = 0
const readWrites = new Set<AbortController>()
useAuthStore.subscribe((state, previous) => {
if (
state.signedIn !== previous.signedIn ||
state.user?.uuid !== previous.user?.uuid ||
state.host !== previous.host ||
state.projectId !== previous.projectId
) {
accountGeneration += 1
for (const controller of readWrites) controller.abort()
readWrites.clear()
}
})
type ReadSnapshot = [QueryKey, Record<string, boolean> | undefined][]
interface PendingRead {
read: boolean
promise: Promise<void>
rollback: ReadSnapshot
}
const pendingReads = new WeakMap<QueryClient, Map<string, PendingRead>>()
function readKey(scope: ProjectScope | null, reportId: string): string {
return JSON.stringify([accountGeneration, scope, reportId])
}
async function fetchReadStates(ids: readonly string[], signal: AbortSignal): Promise<Record<string, boolean>> {
const batches: string[][] = []
for (let start = 0; start < ids.length; start += READ_STATE_BATCH) {
batches.push(ids.slice(start, start + READ_STATE_BATCH))
}
const responses = await Promise.all(batches.map((batch) => postReadStates(batch, undefined, signal)))
return Object.assign({}, ...responses.map((response: ReadStatesApi) => response.states))
}
function mergeReadStates(results: UseQueryResult<Record<string, boolean>>[]): Record<string, boolean> {
return Object.assign(
{},
...results.map((result) => (result.isFetchedAfterMount && !result.isError ? (result.data ?? {}) : {}))
)
}
function nextOffset(lastPage: InboxPageApi, _pages: InboxPageApi[], lastOffset: number): number | undefined {
return lastPage.next ? lastOffset + INBOX_PAGE_SIZE : undefined
}
// Refetching every loaded page ranks the whole list once per page, so a refresh starts again from the first page.
function keepFirstPage(queryClient: QueryClient, scope: ProjectScope): void {
const key = reportKeys.inbox(scope)
const updatedAt = queryClient.getQueryState(key)?.dataUpdatedAt
queryClient.setQueryData<InboxPages>(
key,
(data) => (data ? { pages: data.pages.slice(0, 1), pageParams: data.pageParams.slice(0, 1) } : data),
{ updatedAt }
)
}
function useLiveInboxItems(
enabled: boolean,
refreshWhileVisible: boolean,
filters: InboxFilters,
now: Date
): InboxQueryState {
const scope = useProjectScope()
const offline = useConnectivity((state) => state.status === 'offline')
const appActive = useAppActive()
const access = useFeatureAccess('inbox')
const active = enabled && scope !== null && access.state === 'ok'
const snoozes = useSnoozeEntries()
const queryClient = useQueryClient()
const [pulling, setPulling] = useState(false)
const list = useInfiniteQuery({
queryKey: reportKeys.inbox(scope),
queryFn: async ({ pageParam, signal }): Promise<CapturedInboxPage> => {
const page = await fetchInboxPage(pageParam, signal)
return { ...page, capturedAt: Date.now() }
},
initialPageParam: 0,
getNextPageParam: nextOffset,
enabled: active,
})
useEffect(() => {
reportScopeError(list.error, 'inbox')
}, [list.error])
const saved = useQuery<SavedInbox>({ queryKey: inboxCacheKey(scope), queryFn: skipToken })
const reports = useMemo(() => (list.data ? reportsFromPages(list.data.pages) : undefined), [list.data])
const baseItems = useMemo(() => (reports ? inboxFromReports(reports) : saved.data?.items), [reports, saved.data])
const signalCounts = useMemo(
() => (reports ? signalCountsFromReports(reports) : (saved.data?.signalCounts ?? {})),
[reports, saved.data]
)
// One read-state request per page, so loading a page does not ask again for the pages before it.
const pageIds = useMemo(
() =>
(list.data?.pages ?? [])
.map((page) => page.results.map((report) => report.id).sort())
.filter((ids) => ids.length > 0),
[list.data]
)
const readStates = useQueries({
queries: pageIds.map((ids) => ({
queryKey: reportKeys.readStates(scope, ids),
queryFn: async ({ signal }: { signal: AbortSignal }) => {
const states = await fetchReadStates(ids, signal)
for (const id of ids) {
const pending = pendingReads.get(queryClient)?.get(readKey(scope, id))
if (pending) states[id] = pending.read
}
return states
},
staleTime: 0,
refetchOnMount: 'always' as const,
refetchInterval: active && appActive && refreshWhileVisible ? 30_000 : false,
enabled: active,
retry: retryUnlessMissing,
})),
combine: mergeReadStates,
})
const firstPage = list.data?.pages[0]
const capturedAt = firstPage?.capturedAt
const savedCounts = useMemo(() => (firstPage ? signalCountsFromReports(firstPage.results) : {}), [firstPage])
const savedItems = useMemo(
() =>
firstPage
? inboxFromReports(firstPage.results).map((item) => ({
...item,
read: readStates[item.reportId] !== false,
}))
: undefined,
[firstPage, readStates]
)
useEffect(() => {
if (!active || !scope || !list.isSuccess || !savedItems || !capturedAt) return
const key = inboxCacheKey(scope)
const previous = queryClient.getQueryData<SavedInbox>(key)
if (previous?.items === savedItems && previous.sourceUpdatedAt === capturedAt) return
queryClient.setQueryData<SavedInbox>(
key,
{ items: savedItems, signalCounts: savedCounts, sourceUpdatedAt: capturedAt },
{ updatedAt: capturedAt }
)
}, [active, scope, list.isSuccess, capturedAt, savedItems, savedCounts, queryClient])
const polling = active && appActive && refreshWhileVisible
const wasPolling = useRef(polling)
useEffect(() => {
if (polling && !wasPolling.current) {
void queryClient.invalidateQueries({ queryKey: reportKeys.readStatesAll(scope) })
}
wasPolling.current = polling
}, [polling, scope, queryClient])
const items = useMemo(() => {
if (!baseItems || !scope) {
return undefined
}
const withRead = reports
? baseItems.map((item) => ({ ...item, read: readStates[item.reportId] !== false }))
: baseItems
return applySnoozes(applyInboxFilters(withRead, filters, now.getTime()), snoozes, scope, now, signalCounts)
}, [baseItems, reports, readStates, filters, snoozes, scope, now, signalCounts])
const {
refetch: refetchList,
fetchNextPage,
hasNextPage,
isFetching,
isFetchingNextPage,
isFetchNextPageError,
} = list
const refetch = useCallback(async (): Promise<void> => {
if (!scope) {
return
}
setPulling(true)
try {
keepFirstPage(queryClient, scope)
await Promise.all([
refetchList(),
queryClient.invalidateQueries({ queryKey: reportKeys.readStatesAll(scope) }),
])
} finally {
setPulling(false)
}
}, [queryClient, scope, refetchList])
const pagesLoaded = list.data?.pages.length ?? 0
// Only a next-page fetch in flight blocks this, not a background refetch: `FlatList` calls `onEndReached` again only
// after the content grows, so a dropped call would stop the list from loading more.
const retryLoadMore = useCallback((): void => {
if (!hasNextPage || isFetchingNextPage) {
return
}
track('mobile_inbox_page_requested', { page: pagesLoaded + 1 })
// The inbox and an open report can both auto-page; without this the second call cancels and repeats the request.
void fetchNextPage({ cancelRefetch: false })
}, [hasNextPage, isFetchingNextPage, fetchNextPage, pagesLoaded])
// The error footer that replaces the spinner changes the content size, which makes `FlatList` call `onEndReached`
// again. Without this guard, a server that keeps failing would get a new request after each failure.
const loadMore = useCallback((): void => {
if (!isFetchNextPageError) {
retryLoadMore()
}
}, [isFetchNextPageError, retryLoadMore])
// A sort or filter over part of the ranking would misorder rows or hide matches on unloaded pages, so it loads every
// page. It waits for any fetch, because a next-page request would cancel a refresh that is still in flight.
const autoPaging = active && !isDefaultInboxFilters(filters) && hasNextPage && !isFetchNextPageError
useEffect(() => {
if (autoPaging && !isFetching) {
retryLoadMore()
}
}, [autoPaging, isFetching, retryLoadMore])
if (!scope) {
return { ...errorQuery(new NotSignedInError()), ...noMorePages, ...noItems }
}
const paging = {
hasMore: hasNextPage,
isLoadingMore: isFetchingNextPage || autoPaging,
loadMoreFailed: isFetchNextPageError,
loadMore,
retryLoadMore,
}
if (items) {
return {
data: items,
isLoading: false,
isError: false,
error: null,
isRefetching: pulling,
refetch,
...paging,
matchedCount: items.length,
totalCount: baseItems?.length ?? 0,
unfiltered: baseItems,
}
}
if (list.isError) {
return { ...errorQuery(toError(list.error), refetch), ...noMorePages, ...noItems }
}
return { ...connectionLoadingQuery<InboxItem[]>(offline, refetch), ...noMorePages, ...noItems }
}
/** `for_you/` has no sort or filter parameters, so `filters` apply on the device to the ranked reports. */
export function useInboxItems({
refreshWhileVisible = false,
filters = DEFAULT_INBOX_FILTERS,
}: {
refreshWhileVisible?: boolean
filters?: InboxFilters
} = {}): InboxQueryState {
const mode = useDataMode()
const now = useNow()
const demoQuery = useDemoInboxQuery()
const liveQuery = useLiveInboxItems(mode === 'live', refreshWhileVisible, filters, now)
const demoItems = useMemo(
() => (demoQuery.data ? applyInboxFilters(demoQuery.data, filters, now.getTime()) : undefined),
[demoQuery.data, filters, now]
)
if (mode === 'loading') {
return { ...loadingQuery(), ...noMorePages, ...noItems }
}
if (mode === 'demo') {
return {
...demoQuery,
data: demoItems,
...noMorePages,
matchedCount: demoItems?.length ?? 0,
totalCount: demoQuery.data?.length ?? 0,
unfiltered: demoQuery.data,
}
}
return liveQuery
}
function setCachedRead(
queryClient: ReturnType<typeof useQueryClient>,
scope: ProjectScope,
reportId: string,
read: boolean
): void {
queryClient.setQueriesData<Record<string, boolean>>(
{
queryKey: reportKeys.readStatesAll(scope),
predicate: (query) => String(query.queryKey.at(-1)).split(',').includes(reportId),
},
(states) => ({ ...states, [reportId]: read })
)
}
function restoreRead(queryClient: QueryClient, reportId: string, snapshot: ReadSnapshot): void {
for (const [queryKey, states] of snapshot) {
queryClient.setQueryData<Record<string, boolean>>(queryKey, (current) => {
if (!current) return current
const restored = { ...current }
if (states && reportId in states) restored[reportId] = states[reportId] as boolean
else delete restored[reportId]
return restored
})
}
}
/** `open` is the mark that opening a report sends by itself; `manual` is a swipe or a row menu choice. */
type ReadTrigger = 'open' | 'manual'
// A write to the opposite value waits for the one in flight, so the server ends with the last value the user chose.
function setReportRead(
queryClient: QueryClient,
scope: ProjectScope,
reportId: string,
read: boolean,
trigger: ReadTrigger
): Promise<void> {
let pending = pendingReads.get(queryClient)
if (!pending) {
pending = new Map()
pendingReads.set(queryClient, pending)
}
const writes = pending
const generation = accountGeneration
const key = readKey(scope, reportId)
const existing = writes.get(key)
if (existing?.read === read) return existing.promise
const controller = new AbortController()
readWrites.add(controller)
const entry: PendingRead = { read, promise: Promise.resolve(), rollback: [] }
// A superseded write leaves the cache to the newer write, which shows the newer value.
const isLatest = (): boolean => writes.get(key) === entry
entry.promise = (async (): Promise<void> => {
const filters = { queryKey: reportKeys.readStatesAll(scope) }
await queryClient.cancelQueries(filters)
if (generation !== accountGeneration) return
entry.rollback = queryClient.getQueriesData<Record<string, boolean>>(filters)
setCachedRead(queryClient, scope, reportId, read)
if (existing) {
const previousSucceeded = await existing.promise.then(
() => true,
() => false
)
if (generation !== accountGeneration) return
// The older write did not reach the server, so a failure here goes back to the value before it.
if (!previousSucceeded) entry.rollback = existing.rollback
}
try {
await postReadStates([reportId], read, controller.signal)
if (generation !== accountGeneration) return
track(read ? 'mobile_report_marked_read' : 'mobile_report_marked_unread', { report_id: reportId, trigger })
if (!isLatest()) return
await queryClient.cancelQueries(filters)
if (generation !== accountGeneration || !isLatest()) return
setCachedRead(queryClient, scope, reportId, read)
} catch (error) {
if (generation !== accountGeneration) return
if (isLatest()) {
await queryClient.cancelQueries(filters)
if (generation !== accountGeneration) return
if (isLatest()) restoreRead(queryClient, reportId, entry.rollback)
}
throw error
}
})().finally(() => {
if (isLatest()) writes.delete(key)
readWrites.delete(controller)
})
writes.set(key, entry)
return entry.promise
}
/** Sets a report's read state for the current user. Not guarded, so swipes on different rows never drop each other. */
export function useSetReportRead(): (reportId: string, read: boolean) => Promise<void> {
const demo = useDemoMode((state) => state.enabled)
const demoMarkRead = useDemoMode((state) => state.markRead)
const demoMarkUnread = useDemoMode((state) => state.markUnread)
const scope = useProjectScope()
const queryClient = useQueryClient()
return useCallback(
async (reportId: string, read: boolean): Promise<void> => {
if (demo) {
if (read) demoMarkRead(reportId)
else demoMarkUnread(reportId)
return
}
if (!scope) {
throw new NotSignedInError()
}
await setReportRead(queryClient, scope, reportId, read, 'manual')
},
[demo, demoMarkRead, demoMarkUnread, scope, queryClient]
)
}
export function useSetReadAction(reportId: string, read: boolean): AsyncAction<[]> {
const setRead = useSetReportRead()
return useAsyncAction(() => setRead(reportId, read))
}
// Posts without `useAsyncAction`, whose in-flight guard would drop the next report's post on a fast Prev/Next.
export function useMarkReadOnOpen(reportId: string | undefined): void {
const demo = useDemoMode((state) => state.enabled)
const demoMarkRead = useDemoMode((state) => state.markRead)
const scope = useProjectScope()
const queryClient = useQueryClient()
useEffect(() => {
if (!reportId) return
if (demo) {
demoMarkRead(reportId)
return
}
if (!scope) {
return
}
setReportRead(queryClient, scope, reportId, true, 'open').catch(() => undefined)
wakeSnooze(scope, reportId).catch(() => undefined)
}, [reportId, demo, demoMarkRead, scope, queryClient])
}