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.

33.7 KB
Raw Blame
import { apiMutator } from '../../../../frontend/src/lib/api-orval-mutator'
/**
 * Auto-generated from the Django backend OpenAPI schema.
 * To modify these types, update the Django serializers or views, then run:
 *   hogli build:openapi
 * Questions or issues? #team-devex on Slack
 *
 * PostHog API - generated
 * OpenAPI spec version: 1.0.0
 */
import type {
    CanvasActionInvokeApi,
    CanvasActionResultApi,
    CanvasActionsResponseApi,
    CanvasAgentRequestApi,
    CanvasAgentRequestResultApi,
    CanvasApi,
    CanvasBuildActionApi,
    CanvasBuildApi,
    CanvasBuildsResponseApi,
    CanvasCommentDetailApi,
    CanvasCommentsResponseApi,
    CanvasConnectorCallApi,
    CanvasConnectorCallResultApi,
    CanvasConnectorsResponseApi,
    CanvasCreateApi,
    CanvasDraftApi,
    CanvasErrorReportResultApi,
    CanvasFixRequestResultApi,
    CanvasLayoutPatchApi,
    CanvasLayoutPublishApi,
    CanvasLayoutPublishResponseApi,
    CanvasLayoutWithComponentsResponseApi,
    CanvasPromoteApi,
    CanvasPublishCurrentVersionApi,
    CanvasReportErrorApi,
    CanvasRequestFixApi,
    CanvasRevertApi,
    CanvasSourceDraftApi,
    CanvasSourceDraftResponseApi,
    CanvasSourceEditApi,
    CanvasSourcePublishApi,
    CanvasSourcePublishResponseApi,
    CanvasSourceResponseApi,
    CanvasStateEntryApi,
    CanvasStateResponseApi,
    CanvasStateSetApi,
    CanvasStateValueResponseApi,
    CanvasToolInvokeApi,
    CanvasToolResultApi,
    CanvasValidateRequestApi,
    CanvasValidateResponseApi,
    CanvasViewResponseApi,
    CanvasesBuildsRetrieveParams,
    CanvasesCommentsListParams,
    CanvasesCommentsRetrieveParams,
    CanvasesConnectorsRetrieveParams,
    CanvasesLayoutRetrieveParams,
    CanvasesListParams,
    CanvasesSourceRetrieveParams,
    CanvasesStateRetrieveParams,
    CanvasesStateValueRetrieveParams,
    CanvasesVersionsRetrieveParams,
    PaginatedCanvasListApi,
    PaginatedCanvasVersionListApi,
    PatchedCanvasUpdateApi,
} from './api.schemas'

export const getCanvasesListUrl = (projectId: string, params?: CanvasesListParams) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/`
}

/**
 * Canvases: agent-built sandboxed browser apps, filed into channels.
 *
 * Source is versioned per publish and built server-side; the canvas app
 * renders the published build's artifact from the isolated artifact origin.
 */
export const canvasesList = async (
    projectId: string,
    params?: CanvasesListParams,
    options?: RequestInit
): Promise<PaginatedCanvasListApi> => {
    return apiMutator<PaginatedCanvasListApi>(getCanvasesListUrl(projectId, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesCreateUrl = (projectId: string) => {
    return `/api/projects/${projectId}/canvases/`
}

/**
 * Create a new, empty canvas in a channel; give it source by publishing a project.
 */
export const canvasesCreate = async (
    projectId: string,
    canvasCreateApi: CanvasCreateApi,
    options?: RequestInit
): Promise<CanvasApi> => {
    return apiMutator<CanvasApi>(getCanvasesCreateUrl(projectId), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasCreateApi),
    })
}

export const getCanvasesRetrieveUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/`
}

/**
 * Canvases: agent-built sandboxed browser apps, filed into channels.
 *
 * Source is versioned per publish and built server-side; the canvas app
 * renders the published build's artifact from the isolated artifact origin.
 */
export const canvasesRetrieve = async (projectId: string, id: string, options?: RequestInit): Promise<CanvasApi> => {
    return apiMutator<CanvasApi>(getCanvasesRetrieveUrl(projectId, id), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesPartialUpdateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/`
}

/**
 * Update canvas metadata, including the space it belongs to.
 */
export const canvasesPartialUpdate = async (
    projectId: string,
    id: string,
    patchedCanvasUpdateApi?: PatchedCanvasUpdateApi,
    options?: RequestInit
): Promise<CanvasApi> => {
    return apiMutator<CanvasApi>(getCanvasesPartialUpdateUrl(projectId, id), {
        ...options,
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(patchedCanvasUpdateApi),
    })
}

export const getCanvasesDestroyUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/`
}

/**
 * Canvases: agent-built sandboxed browser apps, filed into channels.
 *
 * Source is versioned per publish and built server-side; the canvas app
 * renders the published build's artifact from the isolated artifact origin.
 */
export const canvasesDestroy = async (projectId: string, id: string, options?: RequestInit): Promise<void> => {
    return apiMutator<void>(getCanvasesDestroyUrl(projectId, id), {
        ...options,
        method: 'DELETE',
    })
}

export const getCanvasesActionsInvokeUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/actions/invoke/`
}

/**
 * Invoke one registered action verb as the viewer.
 *
 * The canvas must declare the verb in capabilities.posthog.actions (the
 * reviewed permission boundary); the write itself runs with the viewer's
 * own permissions, exactly as if they acted in the app.
 */
export const canvasesActionsInvoke = async (
    projectId: string,
    id: string,
    canvasActionInvokeApi: CanvasActionInvokeApi,
    options?: RequestInit
): Promise<CanvasActionResultApi> => {
    return apiMutator<CanvasActionResultApi>(getCanvasesActionsInvokeUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasActionInvokeApi),
    })
}

export const getCanvasesBuildsRetrieveUrl = (projectId: string, id: string, params?: CanvasesBuildsRetrieveParams) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/${id}/builds/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/${id}/builds/`
}

/**
 * Read the canvas's build lifecycle: live pointers plus recent builds.
 *
 * A publish queues a build; poll this until it is ready (the live pointer
 * advances) or failed (fix the error diagnostics and publish again — the
 * last good build stays live). Send the response's ETag back as
 * If-None-Match to make the poll revalidate without a body.
 */
export const canvasesBuildsRetrieve = async (
    projectId: string,
    id: string,
    params?: CanvasesBuildsRetrieveParams,
    options?: RequestInit
): Promise<CanvasBuildsResponseApi> => {
    return apiMutator<CanvasBuildsResponseApi>(getCanvasesBuildsRetrieveUrl(projectId, id, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesBuildActionCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/builds/action/`
}

/**
 * Apply a lifecycle action (retry, pin, unpin, cancel) to one build.
 */
export const canvasesBuildActionCreate = async (
    projectId: string,
    id: string,
    canvasBuildActionApi: CanvasBuildActionApi,
    options?: RequestInit
): Promise<CanvasBuildApi> => {
    return apiMutator<CanvasBuildApi>(getCanvasesBuildActionCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasBuildActionApi),
    })
}

export const getCanvasesCommentsListUrl = (projectId: string, id: string, params?: CanvasesCommentsListParams) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/${id}/comments/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/${id}/comments/`
}

/**
 * The comment threads on this canvas, newest first. Open threads only unless include_resolved is set.
 */
export const canvasesCommentsList = async (
    projectId: string,
    id: string,
    params?: CanvasesCommentsListParams,
    options?: RequestInit
): Promise<CanvasCommentsResponseApi> => {
    return apiMutator<CanvasCommentsResponseApi>(getCanvasesCommentsListUrl(projectId, id, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesCommentsRetrieveUrl = (
    projectId: string,
    id: string,
    rootCommentId: string,
    params?: CanvasesCommentsRetrieveParams
) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/${id}/comments/${rootCommentId}/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/${id}/comments/${rootCommentId}/`
}

/**
 * One comment thread on this canvas: the root comment and its replies, oldest first.
 */
export const canvasesCommentsRetrieve = async (
    projectId: string,
    id: string,
    rootCommentId: string,
    params?: CanvasesCommentsRetrieveParams,
    options?: RequestInit
): Promise<CanvasCommentDetailApi> => {
    return apiMutator<CanvasCommentDetailApi>(getCanvasesCommentsRetrieveUrl(projectId, id, rootCommentId, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesConnectorsCallUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/connectors/call/`
}

/**
 * Call one declared connector tool as the viewer.
 *
 * The canvas must declare the provider and tool in capabilities.connectors
 * (the reviewed permission boundary); the call runs with the viewer's own
 * connection, so two viewers of the same canvas see their own data.
 */
export const canvasesConnectorsCall = async (
    projectId: string,
    id: string,
    canvasConnectorCallApi: CanvasConnectorCallApi,
    options?: RequestInit
): Promise<CanvasConnectorCallResultApi> => {
    return apiMutator<CanvasConnectorCallResultApi>(getCanvasesConnectorsCallUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasConnectorCallApi),
    })
}

export const getCanvasesDraftCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/draft/`
}

/**
 * Stage a complete source project as a draft version and build it, without publishing.
 *
 * The draft gets the same validation, versioning, and server-side build as
 * a publish, but the canvas's head and live build never move, so nothing
 * changes for viewers. Promote the version with `promote` to make it live.
 * The response reports how the draft's declared capabilities widen the
 * current head's, so growth in access can be reviewed before it ships.
 * No version guard applies: a draft conflicts with nothing.
 */
export const canvasesDraftCreate = async (
    projectId: string,
    id: string,
    canvasSourceDraftApi: CanvasSourceDraftApi,
    options?: RequestInit
): Promise<CanvasSourceDraftResponseApi> => {
    return apiMutator<CanvasSourceDraftResponseApi>(getCanvasesDraftCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasSourceDraftApi),
    })
}

export const getCanvasesDraftsRetrieveUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/drafts/`
}

/**
 * The canvas's staged draft versions, newest first, each with its latest build status.
 *
 * A draft is a version that was built but never made the head. Preview one
 * with `source?version_id=`, then make it live with `promote`.
 */
export const canvasesDraftsRetrieve = async (
    projectId: string,
    id: string,
    options?: RequestInit
): Promise<CanvasDraftApi[]> => {
    return apiMutator<CanvasDraftApi[]>(getCanvasesDraftsRetrieveUrl(projectId, id), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesEditCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/edit/`
}

/**
 * Publish file edits against the canvas's current source project.
 *
 * Diff-aware alternative to sending the complete project: operations
 * replace text inside a file, write, delete, or rename files, applied in
 * order to the head the caller read. `expected_current_version_id` is mandatory here —
 * relative edits against an unverified base could silently merge into
 * someone else's newer work.
 */
export const canvasesEditCreate = async (
    projectId: string,
    id: string,
    canvasSourceEditApi: CanvasSourceEditApi,
    options?: RequestInit
): Promise<CanvasSourcePublishResponseApi> => {
    return apiMutator<CanvasSourcePublishResponseApi>(getCanvasesEditCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasSourceEditApi),
    })
}

export const getCanvasesLayoutRetrieveUrl = (projectId: string, id: string, params?: CanvasesLayoutRetrieveParams) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/${id}/layout/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/${id}/layout/`
}

/**
 * Read a grid canvas's layout document and its `current_version_id`.
 *
 * Always call this before editing: pass the returned version id as
 * `expected_current_version_id` on publish/patch so concurrent edits are
 * not overwritten. A grid canvas with no versions yet returns the
 * default empty layout with a null version id.
 */
export const canvasesLayoutRetrieve = async (
    projectId: string,
    id: string,
    params?: CanvasesLayoutRetrieveParams,
    options?: RequestInit
): Promise<CanvasLayoutWithComponentsResponseApi> => {
    return apiMutator<CanvasLayoutWithComponentsResponseApi>(getCanvasesLayoutRetrieveUrl(projectId, id, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesLayoutPatchCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/layout/patch/`
}

/**
 * Apply surgical operations to the grid canvas's current layout.
 *
 * The default write path for both the editor and agents: add, move,
 * resize, fill, or remove one placement without resending the layout.
 * `expected_current_version_id` is mandatory so an agent filling a box
 * and a user rearranging widgets cannot overwrite each other.
 */
export const canvasesLayoutPatchCreate = async (
    projectId: string,
    id: string,
    canvasLayoutPatchApi: CanvasLayoutPatchApi,
    options?: RequestInit
): Promise<CanvasLayoutPublishResponseApi> => {
    return apiMutator<CanvasLayoutPublishResponseApi>(getCanvasesLayoutPatchCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasLayoutPatchApi),
    })
}

export const getCanvasesLayoutPublishCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/layout/publish/`
}

/**
 * Publish a complete layout document as the grid canvas's new head version.
 *
 * Layout is data, not code: the new version is live immediately, with no
 * build. Validation errors reject the publish (400) and leave the canvas
 * untouched; a stale `expected_current_version_id` is rejected with 409.
 */
export const canvasesLayoutPublishCreate = async (
    projectId: string,
    id: string,
    canvasLayoutPublishApi: CanvasLayoutPublishApi,
    options?: RequestInit
): Promise<CanvasLayoutPublishResponseApi> => {
    return apiMutator<CanvasLayoutPublishResponseApi>(getCanvasesLayoutPublishCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasLayoutPublishApi),
    })
}

export const getCanvasesPromoteCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/promote/`
}

/**
 * Make a draft version the canvas's live head.
 *
 * A draft whose build is ready goes live immediately, with no rebuild;
 * otherwise a fresh build is queued. Returns that build.
 */
export const canvasesPromoteCreate = async (
    projectId: string,
    id: string,
    canvasPromoteApi: CanvasPromoteApi,
    options?: RequestInit
): Promise<CanvasBuildApi> => {
    return apiMutator<CanvasBuildApi>(getCanvasesPromoteCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasPromoteApi),
    })
}

export const getCanvasesPublishCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/publish/`
}

/**
 * Publish a complete source project as the canvas's new head version.
 *
 * Validation errors reject the publish (400) and leave the canvas
 * untouched; a stale `expected_current_version_id` is rejected with 409.
 * A successful publish queues a server-side build.
 */
export const canvasesPublishCreate = async (
    projectId: string,
    id: string,
    canvasSourcePublishApi: CanvasSourcePublishApi,
    options?: RequestInit
): Promise<CanvasSourcePublishResponseApi> => {
    return apiMutator<CanvasSourcePublishResponseApi>(getCanvasesPublishCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasSourcePublishApi),
    })
}

export const getCanvasesPublishCurrentVersionCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/publish-current-version/`
}

/**
 * Queue a build for the current source version without changing source or metadata.
 */
export const canvasesPublishCurrentVersionCreate = async (
    projectId: string,
    id: string,
    canvasPublishCurrentVersionApi: CanvasPublishCurrentVersionApi,
    options?: RequestInit
): Promise<CanvasBuildApi> => {
    return apiMutator<CanvasBuildApi>(getCanvasesPublishCurrentVersionCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasPublishCurrentVersionApi),
    })
}

export const getCanvasesReportErrorCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/report_error/`
}

/**
 * Report a runtime error observed while rendering a canvas build.
 *
 * Files the report in the authoring task's thread (deduped per build and
 * error type) so the canvas's agent can be asked to fix it. Reports never
 * start an agent run by themselves — dispatch is `request_fix`. Only the
 * error class crosses the server; full messages and stacks stay
 * client-side because rendering sessions can carry viewer data.
 */
export const canvasesReportErrorCreate = async (
    projectId: string,
    id: string,
    canvasReportErrorApi: CanvasReportErrorApi,
    options?: RequestInit
): Promise<CanvasErrorReportResultApi> => {
    return apiMutator<CanvasErrorReportResultApi>(getCanvasesReportErrorCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasReportErrorApi),
    })
}

export const getCanvasesRequestAgentCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/request_agent/`
}

/**
 * Route a viewer-approved change request to the canvas's authoring task.
 */
export const canvasesRequestAgentCreate = async (
    projectId: string,
    id: string,
    canvasAgentRequestApi: CanvasAgentRequestApi,
    options?: RequestInit
): Promise<CanvasAgentRequestResultApi> => {
    return apiMutator<CanvasAgentRequestResultApi>(getCanvasesRequestAgentCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasAgentRequestApi),
    })
}

export const getCanvasesRequestFixCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/request_fix/`
}

/**
 * Wake the canvas's authoring agent to fix a failing build or runtime error.
 *
 * Starts (or signals) an agent run on the authoring task, instructed to
 * stage the fix as a draft the user reviews and promotes. This is the
 * human-initiated dispatch step behind error reports; it spends agent
 * compute, so it never fires automatically, and only the authoring
 * task's creator may dispatch — the run executes with their credentials.
 */
export const canvasesRequestFixCreate = async (
    projectId: string,
    id: string,
    canvasRequestFixApi: CanvasRequestFixApi,
    options?: RequestInit
): Promise<CanvasFixRequestResultApi> => {
    return apiMutator<CanvasFixRequestResultApi>(getCanvasesRequestFixCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasRequestFixApi),
    })
}

export const getCanvasesRevertCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/revert/`
}

/**
 * Move the canvas's head back to an existing source version and rebuild it.
 */
export const canvasesRevertCreate = async (
    projectId: string,
    id: string,
    canvasRevertApi: CanvasRevertApi,
    options?: RequestInit
): Promise<CanvasBuildApi> => {
    return apiMutator<CanvasBuildApi>(getCanvasesRevertCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasRevertApi),
    })
}

export const getCanvasesSourceRetrieveUrl = (projectId: string, id: string, params?: CanvasesSourceRetrieveParams) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/${id}/source/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/${id}/source/`
}

/**
 * Read the canvas's source project and its `current_version_id`.
 *
 * Always call this before editing: edit the returned files, then publish
 * the complete project passing the returned version id as
 * `expected_current_version_id` so concurrent edits are not overwritten.
 * `?version_id=` reads a historical version instead of the head.
 */
export const canvasesSourceRetrieve = async (
    projectId: string,
    id: string,
    params?: CanvasesSourceRetrieveParams,
    options?: RequestInit
): Promise<CanvasSourceResponseApi> => {
    return apiMutator<CanvasSourceResponseApi>(getCanvasesSourceRetrieveUrl(projectId, id, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesStateRetrieveUrl = (projectId: string, id: string, params?: CanvasesStateRetrieveParams) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/${id}/state/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/${id}/state/`
}

/**
 * Read the canvas's runtime key-value state (the ph.state store).
 *
 * Returns shared entries plus the authenticated user's own user-scoped
 * entries — never another user's.
 */
export const canvasesStateRetrieve = async (
    projectId: string,
    id: string,
    params?: CanvasesStateRetrieveParams,
    options?: RequestInit
): Promise<CanvasStateResponseApi> => {
    return apiMutator<CanvasStateResponseApi>(getCanvasesStateRetrieveUrl(projectId, id, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesStateSetUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/state/set/`
}

/**
 * Write one key of the canvas's runtime state, or delete it with a null value.
 */
export const canvasesStateSet = async (
    projectId: string,
    id: string,
    canvasStateSetApi: CanvasStateSetApi,
    options?: RequestInit
): Promise<CanvasStateEntryApi | void> => {
    return apiMutator<CanvasStateEntryApi | void>(getCanvasesStateSetUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasStateSetApi),
    })
}

export const getCanvasesStateValueRetrieveUrl = (
    projectId: string,
    id: string,
    params: CanvasesStateValueRetrieveParams
) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/${id}/state/value/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/${id}/state/value/`
}

/**
 * Canvases: agent-built sandboxed browser apps, filed into channels.
 *
 * Source is versioned per publish and built server-side; the canvas app
 * renders the published build's artifact from the isolated artifact origin.
 */
export const canvasesStateValueRetrieve = async (
    projectId: string,
    id: string,
    params: CanvasesStateValueRetrieveParams,
    options?: RequestInit
): Promise<CanvasStateValueResponseApi> => {
    return apiMutator<CanvasStateValueResponseApi>(getCanvasesStateValueRetrieveUrl(projectId, id, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesToolsInvokeUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/tools/invoke/`
}

/**
 * Run one PostHog MCP tool as the viewer.
 *
 * The canvas must declare the tool in capabilities.posthog.tools. The
 * tool runs on the MCP server with a token minted for the viewer, so it
 * has the viewer's own permissions, exactly as if they called it from
 * an MCP client.
 */
export const canvasesToolsInvoke = async (
    projectId: string,
    id: string,
    canvasToolInvokeApi: CanvasToolInvokeApi,
    options?: RequestInit
): Promise<CanvasToolResultApi> => {
    return apiMutator<CanvasToolResultApi>(getCanvasesToolsInvokeUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasToolInvokeApi),
    })
}

export const getCanvasesValidateCreateUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/validate/`
}

/**
 * Validate a candidate source project without publishing it. Side-effect free.
 */
export const canvasesValidateCreate = async (
    projectId: string,
    id: string,
    canvasValidateRequestApi: CanvasValidateRequestApi,
    options?: RequestInit
): Promise<CanvasValidateResponseApi> => {
    return apiMutator<CanvasValidateResponseApi>(getCanvasesValidateCreateUrl(projectId, id), {
        ...options,
        method: 'POST',
        headers: { 'Content-Type': 'application/json', ...options?.headers },
        body: JSON.stringify(canvasValidateRequestApi),
    })
}

export const getCanvasesVersionsRetrieveUrl = (
    projectId: string,
    id: string,
    params?: CanvasesVersionsRetrieveParams
) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/${id}/versions/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/${id}/versions/`
}

/**
 * The canvas's published source-version history, newest first (metadata only).
 *
 * Drafts are excluded: they are staged versions that have never been the
 * head, so they are not part of the undo/revert timeline. Fetch a draft's
 * files with `source?version_id=` to preview it before promoting.
 */
export const canvasesVersionsRetrieve = async (
    projectId: string,
    id: string,
    params?: CanvasesVersionsRetrieveParams,
    options?: RequestInit
): Promise<PaginatedCanvasVersionListApi> => {
    return apiMutator<PaginatedCanvasVersionListApi>(getCanvasesVersionsRetrieveUrl(projectId, id, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesViewRetrieveUrl = (projectId: string, id: string) => {
    return `/api/projects/${projectId}/canvases/${id}/view/`
}

/**
 * Everything needed to open the canvas, in one round trip.
 *
 * Returns the record, the live build (with its signed artifact URL), and —
 * only when there is nothing built to render — the head source project
 * (freeform/component) or the layout document (grid). Send the response's
 * ETag back as If-None-Match to revalidate without a body.
 */
export const canvasesViewRetrieve = async (
    projectId: string,
    id: string,
    options?: RequestInit
): Promise<CanvasViewResponseApi> => {
    return apiMutator<CanvasViewResponseApi>(getCanvasesViewRetrieveUrl(projectId, id), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesActionsRetrieveUrl = (projectId: string) => {
    return `/api/projects/${projectId}/canvases/actions/`
}

/**
 * List the action registry: every verb and PostHog MCP tool a canvas may declare and invoke.
 */
export const canvasesActionsRetrieve = async (
    projectId: string,
    options?: RequestInit
): Promise<CanvasActionsResponseApi> => {
    return apiMutator<CanvasActionsResponseApi>(getCanvasesActionsRetrieveUrl(projectId), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesConnectorsRetrieveUrl = (projectId: string, params?: CanvasesConnectorsRetrieveParams) => {
    const normalizedParams = new URLSearchParams()

    Object.entries(params || {}).forEach(([key, value]) => {
        if (value !== undefined) {
            normalizedParams.append(key, value === null ? 'null' : String(value))
        }
    })

    const stringifiedParams = normalizedParams.toString()

    return stringifiedParams.length > 0
        ? `/api/projects/${projectId}/canvases/connectors/?${stringifiedParams}`
        : `/api/projects/${projectId}/canvases/connectors/`
}

/**
 * List the connector catalog: every provider and tool a canvas may declare, with the caller's connection state.
 *
 * Authoring agents read this to write ph.connectors.call sites and the
 * matching capabilities.connectors declarations. Sandbox tokens receive
 * only static native tools, with no connection lookup or MCP installation data.
 */
export const canvasesConnectorsRetrieve = async (
    projectId: string,
    params?: CanvasesConnectorsRetrieveParams,
    options?: RequestInit
): Promise<CanvasConnectorsResponseApi> => {
    return apiMutator<CanvasConnectorsResponseApi>(getCanvasesConnectorsRetrieveUrl(projectId, params), {
        ...options,
        method: 'GET',
    })
}

export const getCanvasesHomeCreateUrl = (projectId: string) => {
    return `/api/projects/${projectId}/canvases/home/`
}

/**
 * Get or provision the caller's home canvas.
 *
 * Idempotent: returns the user's existing home canvas, or creates a grid
 * canvas in their personal channel and points their home preference at
 * it. The home surface calls this on open.
 */
export const canvasesHomeCreate = async (projectId: string, options?: RequestInit): Promise<CanvasApi> => {
    return apiMutator<CanvasApi>(getCanvasesHomeCreateUrl(projectId), {
        ...options,
        method: 'POST',
    })
}