Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
import axios from 'axios'
import { API_BASE_URL } from '@/utils/basePath'
import { useAuthStore } from '@/stores/authStore'
import type { AuthMode, AuthUser } from '@/stores/authStore'
import type { InventoryEntry } from '@/types'
export const api = axios.create({
baseURL: API_BASE_URL,
withCredentials: true,
})
// Unauthenticated axios instance — no JWT, no 401 redirect (used for public endpoints)
const publicApi = axios.create({ baseURL: API_BASE_URL })
api.interceptors.request.use((config) => {
const { token, csrfToken } = useAuthStore.getState()
if (token) config.headers.Authorization = `Bearer ${token}`
const method = config.method?.toUpperCase() ?? 'GET'
if (csrfToken && !['GET', 'HEAD', 'OPTIONS'].includes(method)) {
config.headers['X-Homelable-CSRF'] = csrfToken
}
return config
})
api.interceptors.response.use(
(r) => r,
(err) => {
if (err.response?.status === 401) useAuthStore.getState().logout()
return Promise.reject(err)
}
)
export const authApi = {
config: () => publicApi.get<{ mode: AuthMode; oidc_login_url: string | null }>('/auth/config'),
login: (username: string, password: string) =>
api.post<{ access_token: string }>('/auth/login', { username, password }),
me: () => api.get<AuthUser>('/auth/me'),
logout: () => api.post('/auth/logout'),
}
export const canvasApi = {
load: (design_id?: string) => {
const params = design_id ? { design_id } : {}
return api.get('/canvas', { params })
},
save: (payload: {
nodes: object[]
edges: object[]
viewport: object
custom_style?: object | null
design_id?: string | null
}) => api.post('/canvas/save', payload),
}
export const mediaApi = {
/** Upload an image, returns its server URL (e.g. /api/v1/media/<uuid>.png). */
upload: async (file: File): Promise<{ url: string; filename: string }> => {
const form = new FormData()
form.append('file', file)
const res = await api.post<{ url: string; filename: string }>('/media/upload', form)
return res.data
},
delete: (filename: string) => api.delete(`/media/${filename}`),
}
/**
* A canvas node as `GET /nodes` reports it — the fields a reader needs to tell
* two hosts apart. The canvas itself keeps its own richer React Flow shape; this
* is only for pickers and lookups.
*/
export interface ApiCanvasNode {
id: string
design_id: string | null
label: string
type: string
ip: string | null
mac: string | null
hostname: string | null
os: string | null
status: string
check_method: string | null
last_seen: string | null
}
export const nodesApi = {
/** Every node, across every design. `label` filters case-insensitively. */
list: (label?: string) =>
api.get<ApiCanvasNode[]>('/nodes', { params: label ? { label } : {} }),
create: (data: object) => api.post('/nodes', data),
update: (id: string, data: object) => api.patch(`/nodes/${id}`, data),
delete: (id: string) => api.delete(`/nodes/${id}`),
}
export const edgesApi = {
create: (data: object) => api.post('/edges', data),
delete: (id: string) => api.delete(`/edges/${id}`),
}
export const liveviewApi = {
load: (key: string, design?: string) =>
publicApi.get('/liveview', { params: { key, ...(design ? { design_id: design } : {}) } }),
getConfig: () => api.get<{ enabled: boolean; key: string | null }>('/liveview/config'),
}
/**
* The read-only documentation space at `/docs?key=…`.
*
* On `publicApi`, like live view: no JWT rides along, and a 401 must not bounce
* a reader towards a login they do not have. Reads only — the public router
* declares no write for this to call.
*/
export const docsviewApi = {
tree: (key: string) =>
publicApi.get<import('@/documentation/types').DocumentSummary[]>('/docsview/tree', {
params: { key },
}),
get: (key: string, id: string) =>
publicApi.get<import('@/documentation/types').Doc>(`/docsview/${id}`, { params: { key } }),
revisions: (key: string, id: string) =>
publicApi.get<import('@/documentation/types').DocRevision[]>(`/docsview/${id}/revisions`, {
params: { key },
}),
revision: (key: string, revisionId: string) =>
publicApi.get<import('@/documentation/types').DocRevision & { body: string }>(
`/docsview/revisions/${revisionId}`,
{ params: { key } },
),
getConfig: () => api.get<{ enabled: boolean; key: string | null }>('/docsview/config'),
}
export interface DeepScanConfig {
http_ranges: string[]
http_probe_enabled: boolean
verify_tls: boolean
}
export type ScanConfigData = { ranges: string[] } & DeepScanConfig
/** A row of `scan_runs` — what `/scan/runs` and the device rescan return. */
export interface ScanRunSummary {
id: string
// 'failed' is legacy: runs recorded before the backend settled on 'error'
// for the same condition. Still read, never written.
status: 'running' | 'done' | 'cancelled' | 'error' | 'failed'
kind: string
ranges: string[]
devices_found: number
started_at: string
finished_at: string | null
error: string | null
}
// A device the backend refused to place because an equivalent node already
// exists on the target design (same ip/mac/ieee). `existing_node_id` points at
// the node already there so the UI can link to it.
export interface SkippedDevice {
device_id: string
label: string
match: 'ip' | 'mac' | 'ieee'
value: string
existing_node_id: string | null
}
// 409 body from single approve / create when a same-design duplicate is found.
export interface DuplicateNodeConflict {
duplicate: true
existing_node_id: string
existing_label: string
match: 'ip' | 'mac' | 'ieee'
value: string
}
/**
* The Device Inventory rides the scan routes.
*
* `/scan/pending/*` is what the table was called when it was a queue of finds
* awaiting approval; the rows are the Device Inventory now, but the paths are a
* published contract the MCP server also calls, so they stay. The method names
* follow the paths rather than the concept, so a route is easy to find.
*/
export const scanApi = {
trigger: (deepScan?: Partial<DeepScanConfig>) => api.post('/scan/trigger', deepScan ?? {}),
pending: () => api.get('/scan/pending'),
/** Add an inventory entry by hand, for hardware no scan can discover. */
createPending: (data: {
hostname: string
ip?: string | null
mac?: string | null
suggested_type?: string | null
model?: string | null
vendor?: string | null
/** "manual" (default) or "rack" for gear created from a rack canvas. */
discovery_source?: 'manual' | 'rack'
}) => api.post<{ id: string; hostname: string | null }>('/scan/pending', data),
/**
* Edit an inventory row. Partial: only the keys sent are applied, so a caller
* touching one field never clears the rest. Lifecycle (`status`) and discovery
* bookkeeping are not editable — approve/hide own those.
*/
updatePending: (id: string, data: Partial<Omit<InventoryEntry, 'id' | 'status' | 'discovered_at'>>) =>
api.patch<InventoryEntry>(`/scan/pending/${id}`, data),
/**
* Copy an inventory row into a new pending one: specs, properties and front
* panel carried, addresses and services left behind (issue #481).
*/
duplicatePending: (id: string) => api.post<InventoryEntry>(`/scan/pending/${id}/duplicate`),
/**
* Deep-rescan one known device: every TCP port, then re-fingerprint. Answers
* "this device predates the scanner knowing that service" (issue #350).
* Returns the ScanRun, so the caller polls `run` and can `stop` it.
* 409 when the device has no IP, is hidden, or is already being rescanned.
*/
rescanDevice: (id: string, opts?: { full_ports?: boolean; ports?: string; http_probe_enabled?: boolean; verify_tls?: boolean }) =>
api.post<ScanRunSummary>(`/scan/pending/${id}/rescan`, opts ?? {}),
hidden: () => api.get('/scan/hidden'),
/**
* Inventory rows for the guests a Proxmox host runs, resolved from the
* host→guest links the Proxmox import records. Empty for a non-host device.
*/
proxmoxChildren: (id: string) =>
api.get<InventoryEntry[]>(`/scan/pending/${id}/proxmox-children`),
runs: () => api.get('/scan/runs'),
run: (runId: string) => api.get<ScanRunSummary>(`/scan/runs/${runId}`),
clearPending: () => api.delete('/scan/pending'),
/** Remove one inventory entry. 409 when a rack still mounts it. */
deletePending: (id: string) => api.delete<{ deleted: boolean }>(`/scan/pending/${id}`),
approve: (id: string, nodeData: object) =>
api.post<{
approved: boolean
node_id: string
edges_created: number
edges: { id: string; source: string; target: string; type?: string; source_handle?: string | null; target_handle?: string | null; lqi?: number | null }[]
}>(`/scan/pending/${id}/approve`, nodeData),
hide: (id: string) => api.post(`/scan/pending/${id}/hide`),
ignore: (id: string) => api.post(`/scan/pending/${id}/ignore`),
bulkApprove: (ids: string[], designId?: string | null) =>
api.post<{
approved: number
node_ids: string[]
device_ids: string[]
edges_created: number
edges: { id: string; source: string; target: string; type?: string; source_handle?: string | null; target_handle?: string | null; lqi?: number | null }[]
skipped: number
skipped_devices: SkippedDevice[]
}>('/scan/pending/bulk-approve', { device_ids: ids, design_id: designId ?? undefined }),
/**
* Fold several inventory rows into one, keeping `winnerId`. Returns the
* survivor. The losers' facts, canvas nodes, rack mounts and documents move
* onto it first — the identity match only runs when a row is created, so two
* rows for one host never converge on their own.
*/
merge: (winnerId: string, loserIds: string[]) =>
api.post<InventoryEntry>('/scan/pending/merge', { winner_id: winnerId, loser_ids: loserIds }),
bulkHide: (ids: string[]) => api.post<{ hidden: number; skipped: number }>('/scan/pending/bulk-hide', { device_ids: ids }),
restore: (id: string) => api.post<{ restored: boolean; device_id: string }>(`/scan/pending/${id}/restore`),
bulkRestore: (ids: string[]) => api.post<{ restored: number; skipped: number }>('/scan/pending/bulk-restore', { device_ids: ids }),
stop: (runId: string) => api.post(`/scan/${runId}/stop`),
getConfig: () => api.get<ScanConfigData>('/scan/config'),
saveConfig: (data: ScanConfigData) => api.post('/scan/config', data),
}
export interface AppSettings {
interval_seconds: number
service_check_enabled: boolean
service_check_interval: number
}
/** What the server returns: the editable settings plus the env-only
* STATUS_CHECKER_ENABLED switch (absent on older backends = enabled). */
export interface AppSettingsResponse extends AppSettings {
status_checker_enabled?: boolean
}
export const settingsApi = {
get: () => api.get<AppSettingsResponse>('/settings'),
save: (data: AppSettings) => api.post<AppSettingsResponse>('/settings', data),
}
export interface ProxmoxConnection {
host: string
port: number
token_id?: string
token_secret?: string
verify_tls?: boolean
}
export interface ProxmoxConfigData {
host: string
port: number
verify_tls: boolean
sync_enabled: boolean
sync_interval: number
token_configured: boolean
}
export const proxmoxApi = {
testConnection: (data: ProxmoxConnection) =>
api.post<{ connected: boolean; message: string }>('/proxmox/test-connection', data),
importNetwork: (data: ProxmoxConnection) =>
api.post<{
nodes: import('@/components/proxmox/types').ProxmoxNode[]
edges: import('@/components/proxmox/types').ProxmoxEdge[]
device_count: number
}>('/proxmox/import', data),
importToPending: (data: ProxmoxConnection) =>
api.post<{
id: string
status: string
kind: string
ranges: string[]
devices_found: number
started_at: string
finished_at: string | null
error: string | null
}>('/proxmox/import-pending', data),
getConfig: () => api.get<ProxmoxConfigData>('/proxmox/config'),
// Only the auto-sync activation is persisted. Connection config
// (host/port/token/verify_tls) is env-only and never sent.
saveConfig: (data: { sync_enabled: boolean; sync_interval: number }) =>
api.post<ProxmoxConfigData>('/proxmox/config', data),
syncNow: () =>
api.post<{
id: string
status: string
kind: string
ranges: string[]
devices_found: number
started_at: string
finished_at: string | null
error: string | null
}>('/proxmox/sync-now'),
}
export interface UnraidConnection {
host: string
/** Omitted = 443 for HTTPS, 80 for HTTP. */
port?: number
api_key?: string
use_https?: boolean
verify_tls?: boolean
/** Import (and list) stopped containers and VMs too. */
include_offline?: boolean
}
export interface UnraidConfigData {
host: string
port: number
use_https: boolean
verify_tls: boolean
sync_enabled: boolean
sync_interval: number
include_offline: boolean
api_key_configured: boolean
}
export const unraidApi = {
testConnection: (data: UnraidConnection) =>
api.post<{ connected: boolean; message: string }>('/unraid/test-connection', data),
importNetwork: (data: UnraidConnection) =>
api.post<import('@/components/unraid/types').UnraidImportResponse>('/unraid/import', data),
importToPending: (data: UnraidConnection) =>
api.post<ScanRunResult>('/unraid/import-pending', data),
getConfig: () => api.get<UnraidConfigData>('/unraid/config'),
// Only the auto-sync activation is persisted; connection config is env-only.
saveConfig: (data: { sync_enabled: boolean; sync_interval: number; include_offline: boolean }) =>
api.post<UnraidConfigData>('/unraid/config', data),
syncNow: () => api.post<ScanRunResult>('/unraid/sync-now'),
}
export const designsApi = {
list: () => api.get<import('@/types').Design[]>('/designs'),
create: (data: { name: string; icon?: string; design_type?: string }) =>
api.post<import('@/types').Design>('/designs', data),
copy: (sourceId: string, data: { name: string; icon?: string }) =>
api.post<import('@/types').Design>(`/designs/${sourceId}/copy`, data),
update: (id: string, data: { name?: string; icon?: string }) =>
api.put<import('@/types').Design>(`/designs/${id}`, data),
delete: (id: string) => api.delete(`/designs/${id}`),
}
export const documentsApi = {
list: (params?: { kind?: string; parent_id?: string; device_id?: string; tag?: string }) =>
api.get<import('@/documentation/types').DocumentSummary[]>('/documents', { params }),
get: (id: string) => api.get<import('@/documentation/types').Doc>(`/documents/${id}`),
create: (data: {
title: string
kind?: string
parent_id?: string | null
device_id?: string | null
node_id?: string | null
design_id?: string | null
template_id?: string | null
body?: string
}) => api.post<import('@/documentation/types').Doc>('/documents', data),
update: (
id: string,
data: {
title?: string
icon?: string | null
body?: string
parent_id?: string | null
sort_order?: number
starred?: boolean
reviewed?: boolean
resync_facts?: boolean
},
) => api.patch<import('@/documentation/types').Doc>(`/documents/${id}`, data),
delete: (id: string) => api.delete(`/documents/${id}`),
revisions: (id: string) =>
api.get<import('@/documentation/types').DocRevision[]>(`/documents/${id}/revisions`),
revision: (revisionId: string) =>
api.get<import('@/documentation/types').DocRevision & { body: string }>(
`/documents/revisions/${revisionId}`,
),
restore: (id: string, revisionId: string) =>
api.post<import('@/documentation/types').Doc>(`/documents/${id}/revisions/${revisionId}/restore`),
backlinks: (id: string) =>
api.get<import('@/documentation/types').DocBacklink[]>(`/documents/${id}/backlinks`),
regenerate: (id: string) =>
api.post<import('@/documentation/types').Doc>(`/documents/${id}/regenerate`),
updatePreview: (
id: string,
resolutions: import('@/documentation/types').ResolutionItem[] = [],
) =>
api.post<import('@/documentation/types').UpdatePreview>(`/documents/${id}/update-preview`, {
resolutions,
}),
updateFromDevice: (
id: string,
preview_id: string,
resolutions: import('@/documentation/types').ResolutionItem[] = [],
) =>
api.post<import('@/documentation/types').Doc>(`/documents/${id}/update-from-device`, {
preview_id,
resolutions,
}),
search: (q: string, limit = 25) =>
api.get<import('@/documentation/types').DocSearchResult>('/documents/search', {
params: { q, limit },
}),
block: (block: string, deviceId: string) =>
api.get<{ block: string; markdown: string }>('/documents/blocks', {
params: { block, device_id: deviceId },
}),
coverage: () => api.get<import('@/documentation/types').DocCoverage>('/documents/coverage'),
// A zip of `.md` files mirroring the tree. Fetched through axios rather than
// a plain link so the Bearer header rides along.
export: () => api.get<Blob>('/documents/export', { responseType: 'blob' }),
scaffold: (data: { device_ids?: string[]; only_with_notes?: boolean }) =>
api.post<{ created: import('@/documentation/types').DocumentSummary[]; skipped: number }>(
'/documents/scaffold',
data,
),
}
export const racksApi = {
load: (designId: string) =>
api.get<import('@/utils/rackSerializer').ApiRackState>('/racks', { params: { design_id: designId } }),
save: (payload: import('@/utils/rackSerializer').RackSavePayload) =>
api.post<{ saved: boolean }>('/racks/save', payload),
inventory: (designId: string) =>
api.get<{ items: import('@/utils/rackSerializer').ApiInventoryItem[] }>('/racks/inventory', {
params: { design_id: designId },
}),
}
export type ZigbeeImportJobStatus = 'running' | 'done' | 'error'
export interface ZigbeeConfigData {
mqtt_host: string
mqtt_port: number
base_topic: string
mqtt_tls: boolean
sync_enabled: boolean
sync_interval: number
include_mesh_links: boolean
host_configured: boolean
}
export interface ZwaveConfigData {
mqtt_host: string
mqtt_port: number
prefix: string
gateway_name: string
mqtt_tls: boolean
sync_enabled: boolean
sync_interval: number
host_configured: boolean
}
// Shape returned by every background-scan trigger (import-pending / sync-now).
interface ScanRunResult {
id: string
status: string
kind: string
ranges: string[]
devices_found: number
started_at: string
finished_at: string | null
error: string | null
}
export const zigbeeApi = {
testConnection: (data: {
mqtt_host: string
mqtt_port: number
mqtt_username?: string
mqtt_password?: string
mqtt_tls?: boolean
mqtt_tls_insecure?: boolean
}) =>
api.post<{ connected: boolean; message: string }>('/zigbee/test-connection', data),
importNetwork: (data: {
mqtt_host: string
mqtt_port: number
mqtt_username?: string
mqtt_password?: string
base_topic?: string
mqtt_tls?: boolean
mqtt_tls_insecure?: boolean
include_mesh_links?: boolean
}) =>
api.post<{ job_id: string; status: ZigbeeImportJobStatus }>('/zigbee/import', data),
// Poll a canvas import started by importNetwork. The fetch runs server-side
// so a slow mesh cannot outlive a reverse proxy's read timeout.
getImportJob: (jobId: string) =>
api.get<{
job_id: string
status: ZigbeeImportJobStatus
result: {
nodes: import('@/components/zigbee/types').ZigbeeNode[]
edges: import('@/components/zigbee/types').ZigbeeEdge[]
device_count: number
} | null
}>(`/zigbee/import/${jobId}`),
importToPending: (data: {
mqtt_host: string
mqtt_port: number
mqtt_username?: string
mqtt_password?: string
base_topic?: string
mqtt_tls?: boolean
mqtt_tls_insecure?: boolean
include_mesh_links?: boolean
}) =>
api.post<{
id: string
status: string
kind: string
ranges: string[]
devices_found: number
started_at: string
finished_at: string | null
error: string | null
}>('/zigbee/import-pending', data),
getConfig: () => api.get<ZigbeeConfigData>('/zigbee/config'),
// Only the auto-sync activation is persisted. MQTT connection config
// (host/port/credentials/topic/tls) is env-only and never sent.
saveConfig: (data: { sync_enabled: boolean; sync_interval: number; include_mesh_links: boolean }) =>
api.post<ZigbeeConfigData>('/zigbee/config', data),
syncNow: () => api.post<ScanRunResult>('/zigbee/sync-now'),
}
export const zwaveApi = {
testConnection: (data: {
mqtt_host: string
mqtt_port: number
mqtt_username?: string
mqtt_password?: string
mqtt_tls?: boolean
mqtt_tls_insecure?: boolean
}) =>
api.post<{ connected: boolean; message: string }>('/zwave/test-connection', data),
importNetwork: (data: {
mqtt_host: string
mqtt_port: number
mqtt_username?: string
mqtt_password?: string
prefix?: string
gateway_name?: string
mqtt_tls?: boolean
mqtt_tls_insecure?: boolean
}) =>
api.post<{
nodes: import('@/components/zwave/types').ZwaveNode[]
edges: import('@/components/zwave/types').ZwaveEdge[]
device_count: number
}>('/zwave/import', data),
importToPending: (data: {
mqtt_host: string
mqtt_port: number
mqtt_username?: string
mqtt_password?: string
prefix?: string
gateway_name?: string
mqtt_tls?: boolean
mqtt_tls_insecure?: boolean
}) =>
api.post<{
id: string
status: string
kind: string
ranges: string[]
devices_found: number
started_at: string
finished_at: string | null
error: string | null
}>('/zwave/import-pending', data),
getConfig: () => api.get<ZwaveConfigData>('/zwave/config'),
// Only the auto-sync activation is persisted. MQTT connection config
// (host/port/credentials/prefix/gateway/tls) is env-only and never sent.
saveConfig: (data: { sync_enabled: boolean; sync_interval: number }) =>
api.post<ZwaveConfigData>('/zwave/config', data),
syncNow: () => api.post<ScanRunResult>('/zwave/sync-now'),
}
export interface UnifiImportModes {
infrastructure: boolean
known_clients: boolean
active_clients: boolean
}
export interface UnifiConnection {
host: string
port: number
site: string
username?: string
password?: string
verify_tls?: boolean
modes?: UnifiImportModes
}
export interface UnifiConfigData {
host: string
port: number
site: string
verify_tls: boolean
sync_enabled: boolean
sync_interval: number
credentials_configured: boolean
modes: UnifiImportModes
}
export interface UnifiImportResult {
device_count: number
pending_created: number
pending_updated: number
infra_count: number
client_count: number
}
export const unifiApi = {
// `counts` holds a row count per source queried, so the import UI can show
// what a box would pull in before it is ticked.
testConnection: (data: UnifiConnection) =>
api.post<{
connected: boolean
message: string
counts: Partial<Record<keyof UnifiImportModes, number>>
}>('/unifi/test-connection', data),
importToPending: (data: UnifiConnection) =>
api.post<UnifiImportResult>('/unifi/import-pending', data),
getConfig: () => api.get<UnifiConfigData>('/unifi/config'),
// Only auto-sync activation and the import modes are persisted. Connection
// config (host/port/credentials/site) is env-only and never sent.
saveConfig: (data: {
sync_enabled: boolean
sync_interval: number
modes: UnifiImportModes
}) => api.post<UnifiConfigData>('/unifi/config', data),
syncNow: () => api.post<UnifiImportResult>('/unifi/sync-now'),
}