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.

15.6 KB
Raw Blame
import { encodeParams } from 'kea-router'

import type { PaginatedResponse } from 'lib/api'
import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'

import { toolbarConfigLogic } from '~/toolbar/shared/toolbarConfigLogic'
import { toolbarFetch } from '~/toolbar/shared/toolbarFetch'
import { toolbarLogger } from '~/toolbar/shared/toolbarLogger'
import type { ElementsEventType, WebExperiment } from '~/toolbar/shared/types'
import type { ActionType, CombinedFeatureFlagAndValueType, EventDefinition, ProductTour } from '~/types'

/**
 * The single, blessed way to talk to the PostHog API from the toolbar.
 *
 * Every authenticated data request should go through `toolbarApi` — preferably one of its
 * resource namespaces (`toolbarApi.actions.list()`, `toolbarApi.productTours.delete(id, …)`), which
 * own the route strings (see the `toolbarApi` export below for the full contract). It wraps
 * `toolbarFetch` (which owns the OAuth bearer + token refresh) and folds the eight different
 * ad-hoc failure-handling styles the toolbar had grown into one consistent contract:
 *
 *   - It never throws. Network-level failures (CORS, offline, a customer page that
 *     replaced `window.fetch`) are caught and returned as a normal failure result,
 *     so no caller needs a `try/catch` and no listener can leak an unhandled rejection.
 *   - It always parses the body and returns a discriminated-union `ToolbarApiResult`,
 *     so every call site branches on `result.ok` the same way.
 *   - It NEVER reports request failures to error tracking. Failed requests - auth
 *     (401/403), client (4xx), server (5xx), network, malformed bodies - are expected
 *     outcomes of running on customer pages; they are logged via `toolbarLogger` and
 *     visible in the `toolbar api request` telemetry, but they are not exceptions.
 *     Error tracking is reserved for genuine toolbar bugs.
 *   - Per-request telemetry (`toolbar api request`) is emitted by `toolbarFetch` itself.
 *
 * What stays at the call site is only what is genuinely call-site specific: the
 * fallback value to use on failure, and any feature side effects (e.g. resetting a
 * form, disabling a mode). Toasting and re-authentication are opt-in via options so
 * that loaders stay quiet while user-initiated writes can surface a message. A call
 * site that needs its kea `*Failure` action to fire converts a failed result into a
 * `throw new ToolbarRequestError(...)` - the global loader handler logs those without
 * capturing them.
 *
 * Auth flows (OAuth code exchange, token refresh, the reachability HEAD check) and the
 * pre-mount feature-flag preload deliberately do NOT use this — they run before the
 * toolbar is authenticated (or before kea is mounted) and own their own fetch behavior.
 */

export type ToolbarApiMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'

export interface ToolbarApiErrorInfo {
    /** HTTP status, or 0 for a network-level failure that never reached the server. */
    status: number
    /** Best human-readable message extracted from the response body, or a fallback. */
    detail: string
    /** Parsed JSON body, when there was one. */
    body: unknown
    /** 401/403 — the session is missing, expired, or lacks access. Handled by the auth flow. */
    isAuthError: boolean
    /** The request never completed (CORS, offline, aborted, customer fetch wrapper threw). */
    isNetworkError: boolean
}

export type ToolbarApiResult<T> =
    | { ok: true; status: number; data: T }
    | { ok: false; status: number; data: null; error: ToolbarApiErrorInfo }

export interface ToolbarApiOptions {
    /**
     * Identifies the call site in logs, telemetry, and error tracking, e.g. `'load_actions'`.
     * Use a short snake_case string.
     */
    context: string
    /**
     * Surface a `lemonToast.error` when the request fails. Pass `true` to show the
     * extracted error detail, or a string to use as the fallback message when the
     * response carries no specific detail. Defaults to `false` (silent — the failure
     * is still logged and, when unexpected, reported). Prefer `false` for background
     * loaders and a string for user-initiated writes.
     */
    toastOnError?: boolean | string
    /**
     * Re-trigger the OAuth flow when the request returns 403 (project access lost or the
     * user switched projects). `toolbarFetch` already clears the session on 403; this
     * additionally kicks off re-authentication. Defaults to `false`.
     */
    reauthenticateOnForbidden?: boolean
    /**
     * Passed through to `toolbarFetch`. Use `'use-as-provided'` for pagination URLs that
     * come from a response body (they are pinned to the uiHost/apiHost origin). Defaults
     * to `'full'`.
     */
    urlConstruction?: 'full' | 'use-as-provided'
}

/** Pull a human-readable message out of a (possibly DRF) error body. */
export function extractErrorDetail(body: unknown, status: number, fallback: string): string {
    if (status === 401 || status === 403) {
        return 'Your toolbar session lacks permission. Please re-authenticate the toolbar from PostHog.'
    }
    if (body && typeof body === 'object') {
        const obj = body as Record<string, unknown>
        if (typeof obj.detail === 'string' && obj.detail) {
            return obj.detail
        }
        // Surface DRF field-level errors: { name: ["..."], questions: [...] }.
        const fieldMessages: string[] = []
        for (const [key, value] of Object.entries(obj)) {
            if (Array.isArray(value) && value.length > 0 && typeof value[0] === 'string') {
                fieldMessages.push(`${key}: ${value[0]}`)
            } else if (typeof value === 'string') {
                fieldMessages.push(`${key}: ${value}`)
            }
        }
        if (fieldMessages.length > 0) {
            return fieldMessages.join('; ')
        }
    }
    return fallback
}

function pathnameForLog(url: string): string {
    try {
        // url may be a path ("/api/…") or an absolute pagination URL — both parse against a base.
        return new URL(url, 'http://x').pathname
    } catch {
        return url
    }
}

function emitToast(toastOnError: boolean | string, error: ToolbarApiErrorInfo): void {
    if (!toastOnError) {
        return
    }
    const fallback = typeof toastOnError === 'string' ? toastOnError : error.detail
    lemonToast.error(extractErrorDetail(error.body, error.status, fallback))
}

async function request<T>(
    method: ToolbarApiMethod,
    url: string,
    payload: Record<string, any> | FormData | undefined,
    options: ToolbarApiOptions
): Promise<ToolbarApiResult<T>> {
    const { context, toastOnError = false, reauthenticateOnForbidden = false, urlConstruction = 'full' } = options
    const pathname = pathnameForLog(url)

    let response: Response
    try {
        response = await toolbarFetch(url, method, payload, urlConstruction)
    } catch {
        const error: ToolbarApiErrorInfo = {
            status: 0,
            detail: 'Network error',
            body: null,
            isAuthError: false,
            isNetworkError: true,
        }
        toolbarLogger.error('api', `Request failed (network): ${context}`, { context, method, pathname })
        emitToast(toastOnError, error)
        return { ok: false, status: 0, data: null, error }
    }

    const status = response.status

    if (response.ok) {
        // DELETE responses are typically 204/empty — don't try to parse a body we won't use.
        if (method === 'DELETE') {
            return { ok: true, status, data: null as T }
        }
        try {
            const data = (await response.json()) as T
            return { ok: true, status, data }
        } catch {
            const error: ToolbarApiErrorInfo = {
                status,
                detail: 'The server returned a malformed response.',
                body: null,
                isAuthError: false,
                isNetworkError: false,
            }
            toolbarLogger.error('api', `Response was not valid JSON: ${context}`, { context, method, pathname, status })
            emitToast(toastOnError, error)
            return { ok: false, status, data: null, error }
        }
    }

    const body = await response.json().catch(() => null)
    const isAuthError = status === 401 || status === 403
    const isServerError = status >= 500
    const error: ToolbarApiErrorInfo = {
        status,
        detail: extractErrorDetail(body, status, 'Request failed'),
        body,
        isAuthError,
        isNetworkError: false,
    }

    if (status === 403 && reauthenticateOnForbidden) {
        toolbarConfigLogic.actions.authenticate()
    }

    // Any HTTP failure is an expected outcome of talking to the API (stale session,
    // validation, backend incident) - log it, never report it to error tracking.
    if (isServerError) {
        toolbarLogger.error('api', `Request failed (server): ${context}`, { context, method, pathname, status })
    } else {
        toolbarLogger.warn('api', `Request failed: ${context}`, { context, method, pathname, status })
    }

    emitToast(toastOnError, error)
    return { ok: false, status, data: null, error }
}

function apiGet<T = unknown>(url: string, options: ToolbarApiOptions): Promise<ToolbarApiResult<T>> {
    return request<T>('GET', url, undefined, options)
}
function apiPost<T = unknown>(
    url: string,
    payload: Record<string, any> | FormData | undefined,
    options: ToolbarApiOptions
): Promise<ToolbarApiResult<T>> {
    return request<T>('POST', url, payload, options)
}
function apiPatch<T = unknown>(
    url: string,
    payload: Record<string, any> | FormData | undefined,
    options: ToolbarApiOptions
): Promise<ToolbarApiResult<T>> {
    return request<T>('PATCH', url, payload, options)
}
function apiDelete<T = unknown>(url: string, options: ToolbarApiOptions): Promise<ToolbarApiResult<T>> {
    return request<T>('DELETE', url, undefined, options)
}

const PROJECT = '/api/projects/@current'
const ENVIRONMENT = '/api/environments/@current'

/**
 * `toolbarApi` is the single entry point for talking to the PostHog API from the toolbar.
 *
 * Prefer the resource namespaces (`toolbarApi.actions.list()`, `toolbarApi.productTours.delete(id, …)`):
 * they own the route strings so every `/api/projects/@current/…` path lives in exactly one place
 * and call sites read as intent rather than URLs. Each method takes the resource-specific arguments
 * (id, payload, query) plus a `ToolbarApiOptions` and returns the same `ToolbarApiResult<T>`, so
 * failure handling stays identical everywhere.
 *
 * The bare verb methods (`get`/`post`/`patch`/`delete`) remain as the low-level primitive that the
 * namespaces are built on — reach for them only for a one-off route not yet modeled as a resource.
 */
export const toolbarApi = {
    get: apiGet,
    post: apiPost,
    patch: apiPatch,
    delete: apiDelete,

    actions: {
        list: (options: ToolbarApiOptions): Promise<ToolbarApiResult<{ results: ActionType[] }>> =>
            apiGet(`${PROJECT}/actions/`, options),
        create: (payload: Record<string, any>, options: ToolbarApiOptions): Promise<ToolbarApiResult<ActionType>> =>
            apiPost(`${PROJECT}/actions/`, payload, options),
        update: (
            id: number | string,
            payload: Record<string, any>,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<ActionType>> => apiPatch(`${PROJECT}/actions/${id}/`, payload, options),
    },

    webExperiments: {
        list: (options: ToolbarApiOptions): Promise<ToolbarApiResult<{ results: WebExperiment[] }>> =>
            apiGet(`${PROJECT}/web_experiments/`, options),
        create: (payload: Record<string, any>, options: ToolbarApiOptions): Promise<ToolbarApiResult<WebExperiment>> =>
            apiPost(`${PROJECT}/web_experiments/`, payload, options),
        update: (
            id: number | string,
            payload: Record<string, any>,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<WebExperiment>> => apiPatch(`${PROJECT}/web_experiments/${id}/`, payload, options),
    },

    productTours: {
        list: (options: ToolbarApiOptions): Promise<ToolbarApiResult<{ results?: ProductTour[] } | ProductTour[]>> =>
            apiGet(`${PROJECT}/product_tours/`, options),
        create: (payload: Record<string, any>, options: ToolbarApiOptions): Promise<ToolbarApiResult<ProductTour>> =>
            apiPost(`${PROJECT}/product_tours/`, payload, options),
        updateDraft: (
            id: number | string,
            payload: Record<string, any>,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<ProductTour>> =>
            apiPatch(`${PROJECT}/product_tours/${id}/draft/`, payload, options),
        delete: (id: number | string, options: ToolbarApiOptions): Promise<ToolbarApiResult<null>> =>
            apiDelete(`${PROJECT}/product_tours/${id}/`, options),
    },

    fieldNotes: {
        listPending: <T = unknown>(options: ToolbarApiOptions): Promise<ToolbarApiResult<T>> =>
            apiGet<T>(`${PROJECT}/field_notes/?field_note_status=pending`, options),
        create: <T = unknown>(payload: Record<string, any>, options: ToolbarApiOptions): Promise<ToolbarApiResult<T>> =>
            apiPost<T>(`${PROJECT}/field_notes/`, payload, options),
        delete: (id: number | string, options: ToolbarApiOptions): Promise<ToolbarApiResult<null>> =>
            apiDelete(`${PROJECT}/field_notes/${id}/`, options),
    },

    featureFlags: {
        myFlags: (
            params: Record<string, any>,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<CombinedFeatureFlagAndValueType[]>> =>
            apiGet(`${PROJECT}/feature_flags/my_flags${encodeParams(params, '?')}`, options),
        evaluationReasons: <T = unknown>(
            distinctId: string,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<T>> =>
            apiGet<T>(
                `${PROJECT}/feature_flags/evaluation_reasons${encodeParams({ distinct_id: distinctId }, '?')}`,
                options
            ),
    },

    webVitals: {
        get: <T = unknown>(params: { pathname: string }, options: ToolbarApiOptions): Promise<ToolbarApiResult<T>> =>
            apiGet<T>(`${ENVIRONMENT}/web_vitals${encodeParams(params, '?')}`, options),
    },

    eventDefinitions: {
        search: (
            query: string,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<{ results?: EventDefinition[] }>> =>
            apiGet(
                `${PROJECT}/event_definitions/${encodeParams(
                    { search: query, limit: 20, event_type: 'event_custom' },
                    '?'
                )}`,
                options
            ),
    },

    objectMediaPreviews: {
        create: (payload: Record<string, any>, options: ToolbarApiOptions): Promise<ToolbarApiResult<unknown>> =>
            apiPost(`${PROJECT}/object_media_previews/`, payload, options),
    },

    savedHeatmaps: {
        capture: (
            formData: FormData,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<{ id: string; short_id: string }>> =>
            apiPost(`${PROJECT}/saved/capture/`, formData, options),
    },

    elementStats: {
        list: (
            params: Record<string, any>,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<PaginatedResponse<ElementsEventType>>> =>
            apiGet(`/api/element/stats/${encodeParams(params, '?')}`, options),
        // Pagination URLs come from a response body — pinned to the uiHost/apiHost origin.
        page: (
            url: string,
            options: ToolbarApiOptions
        ): Promise<ToolbarApiResult<PaginatedResponse<ElementsEventType>>> =>
            apiGet(url, { ...options, urlConstruction: 'use-as-provided' }),
    },
}