Skip to content

: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.

8.6 KB
Raw Blame
import { fetch as streamingFetch } from 'expo/fetch'

import { abortError } from '@/lib/abort'
import { withAppReloadBlocked } from '@/lib/appReload'
import { isRecord } from '@/lib/records'

import { BudgetExceededError, type BudgetFamily, budgetFamilyFor, trySpend } from './budget'
import { recordServerDate } from './serverClock'
import { requestWithDeadline, transport } from './transport'

export interface ApiAuth {
    host: string
    accessToken: string | null
    projectId: number | null
    /** Changes when the user signs in or out, but not when a refresh rotates the token. */
    session: number
}

export interface AuthProvider {
    getAuth: () => ApiAuth
    refreshAccessToken: () => Promise<string | null>
}

let provider: AuthProvider | null = null

export function setAuthProvider(next: AuthProvider | null): void {
    provider = next
}

export class ApiError extends Error {
    readonly status: number
    readonly code: string | undefined
    /** PostHog error `detail`, which is user-facing copy for most errors. */
    readonly detail: string | undefined
    readonly body: unknown
    readonly retryAfterSeconds: number | undefined

    constructor(status: number, body: unknown, headers?: Headers) {
        const record = isRecord(body) ? body : {}
        // Signals and tasks errors use `error` where DRF uses `detail`.
        const detail =
            typeof record.detail === 'string'
                ? record.detail
                : typeof record.error === 'string'
                  ? record.error
                  : undefined
        const code = typeof record.code === 'string' ? record.code : undefined
        super(detail ?? code ?? `Request failed with status ${status}`)
        this.name = 'ApiError'
        this.status = status
        this.code = code
        this.detail = detail
        this.body = body
        const retryAfter = headers?.get('Retry-After')
        this.retryAfterSeconds = retryAfter ? Number(retryAfter) || undefined : undefined
    }
}

export class NotSignedInError extends Error {
    constructor() {
        super('Sign in to continue')
        this.name = 'NotSignedInError'
    }
}

export type QueryValue = string | number | boolean | null | undefined

export interface ApiInit extends Omit<RequestInit, 'body' | 'headers'> {
    json?: unknown
    body?: RequestInit['body']
    headers?: Record<string, string>
    query?: Record<string, QueryValue>
    /** Spends this budget instead of the one the path belongs to. */
    budgetFamily?: BudgetFamily
}

function requireAuth(): ApiAuth {
    if (!provider) {
        throw new NotSignedInError()
    }
    const auth = provider.getAuth()
    if (!auth.host || !auth.accessToken) {
        throw new NotSignedInError()
    }
    return auth
}

export function projectPath(path: string): string {
    const auth = requireAuth()
    if (auth.projectId === null) {
        throw new Error('No project selected')
    }
    return `/api/projects/${auth.projectId}/${path.replace(/^\//, '')}`
}

export function buildQuery(query: Record<string, QueryValue> | undefined): string {
    if (!query) {
        return ''
    }
    const params = new URLSearchParams()
    for (const [key, value] of Object.entries(query)) {
        if (value !== null && value !== undefined) {
            params.set(key, String(value))
        }
    }
    const encoded = params.toString()
    return encoded ? `?${encoded}` : ''
}

export function apiUrl(path: string, query?: Record<string, QueryValue>): string {
    const { host } = requireAuth()
    return `${host}${path.startsWith('/') ? path : `/${path}`}${buildQuery(query)}`
}

/** The web app URL of a page in the current project, or undefined when no session or project is set. */
export function projectWebUrl(path: string): string | undefined {
    try {
        return apiUrl(projectPath(path).replace(/^\/api\/projects\//, '/project/'))
    } catch {
        return undefined
    }
}

function buildInit(init: ApiInit, accessToken: string, accept: string): RequestInit {
    const { json, query: _query, budgetFamily: _budgetFamily, headers, ...rest } = init
    const merged: Record<string, string> = {
        Accept: accept,
        Authorization: `Bearer ${accessToken}`,
        // The tasks API reads this to skip warm-sandbox reuse and to label PRs opened from the app.
        'X-PostHog-Client-Platform': 'mobile',
        ...headers,
    }
    let body = rest.body
    if (json !== undefined) {
        merged['Content-Type'] = 'application/json'
        body = JSON.stringify(json)
    }
    return { ...rest, headers: merged, body }
}

type Fetcher = (url: string, init: RequestInit) => Promise<Response>

// Test doubles and some web responses have no `Date` header, or no headers at all.
function noteServerDate(response: Response): void {
    recordServerDate(response.headers?.get?.('Date'))
}

function isSameSession(a: ApiAuth, b: ApiAuth): boolean {
    return a.session === b.session && a.host === b.host
}

async function send(fetcher: Fetcher, path: string, init: ApiInit, accept: string): Promise<Response> {
    const auth = requireAuth()
    const url = apiUrl(path, init.query)
    const family = init.budgetFamily ?? budgetFamilyFor(path)
    if (family && !trySpend(family)) {
        throw new BudgetExceededError(family)
    }
    const sent = auth.accessToken as string
    const fetchResponse = (token: string): Promise<Response> => {
        if (init.signal?.aborted) {
            throw abortError()
        }
        const options = buildInit(init, token, accept)
        return transport(() => fetcher(url, options))
    }
    let response = await fetchResponse(sent)
    if (init.signal?.aborted) {
        throw abortError()
    }
    noteServerDate(response)
    if (response.status === 401 && provider) {
        // The retry goes to `url`, which belongs to the session that sent the request. If the user signed out or
        // into another account while the request was in flight, the current token belongs to a different session,
        // and possibly to a different host. Sending it to `url` would give it to the earlier host.
        const current = provider.getAuth()
        if (!isSameSession(auth, current)) {
            throw new NotSignedInError()
        }
        // A refresh elsewhere may already have rotated the token this request used. Refreshing
        // again would revoke that newer token and 401 every other in-flight request.
        const token =
            current.accessToken && current.accessToken !== sent
                ? current.accessToken
                : await provider.refreshAccessToken()
        // The session can also change while the refresh is in flight.
        if (!token || !isSameSession(auth, provider.getAuth())) {
            throw new NotSignedInError()
        }
        response = await fetchResponse(token)
        noteServerDate(response)
    }
    return response
}

async function parseBody(response: Response): Promise<unknown> {
    const text = await transport(() => response.text())
    if (!text) {
        return undefined
    }
    try {
        return JSON.parse(text) as unknown
    } catch {
        return text
    }
}

export async function apiReadResponse<T>(
    path: string,
    init: ApiInit,
    read: (response: Response) => Promise<T>
): Promise<T> {
    return withAppReloadBlocked(() =>
        requestWithDeadline(async (signal) => {
            const response = await send(
                (url, options) => fetch(url, options),
                path,
                { ...init, signal },
                'application/json'
            )
            if (signal.aborted) {
                throw abortError()
            }
            return read(response)
        }, init.signal)
    )
}

export async function apiJson<T>(path: string, init: ApiInit = {}): Promise<T> {
    return apiReadResponse(path, init, async (response) => {
        const body = await parseBody(response)
        if (!response.ok) {
            throw new ApiError(response.status, body, response.headers)
        }
        return body as T
    })
}

/** Uses expo's fetch, which exposes `response.body` as a readable stream on native. */
export async function apiStream(path: string, init: ApiInit = {}): Promise<Response> {
    const response = await send(
        (url, options) => streamingFetch(url, options as Parameters<typeof streamingFetch>[1]) as Promise<Response>,
        path,
        init,
        // JSON too, so content negotiation never answers 406 when the server replies in JSON, such as with an error.
        'text/event-stream, application/json'
    )
    if (!response.ok) {
        throw new ApiError(response.status, await parseBody(response), response.headers)
    }
    return response
}