busya
20071b8c7a
Backend: - Add validate_mapping_database_ownership() to verify source/target UUIDs belong to declared environments before persisting mappings (mappings.py) - Add API-key environment scoping to get_mappings (filter) and suggest_mappings_api (enforce) (mappings.py) - Add user_id Column to TaskRecord model + Alembic migration (task.py) - Persist task.user_id on save, restore on load (persistence.py) - Wire current_user.id into migrate_dashboards + backup_dashboards task creation (_action_routes.py) - Fix test_migration_routes.py: module-level patch leak → autouse fixture, SupersetClient→AsyncSupersetClient, AsyncMock for sync_environment/run - Fix 7 Pydantic serializer warnings: 'PENDING'→TaskStatus.PENDING in test_tasks.py + import TaskStatus Frontend: - Deepen isDryRunResult(): validate selection field, risk.items entries (all 5 fields), and diff object uuids individually (ExecutorModel.svelte.ts) Prior work included: task password redaction, resume ownership checks, canonical dry-run DTO alignment, migration UI callback fixes, credential exposure reduction, assistant dry-run await fix.
1263 lines
67 KiB
TypeScript
1263 lines
67 KiB
TypeScript
// #region ApiModule [C:5] [TYPE Module] [SEMANTICS api, client, fetch, auth, error-handling]
|
|
// @BRIEF Core API communication layer — typed fetch wrappers with auth injection, error normalization, toast feedback, and endpoint registry.
|
|
// @LAYER Infrastructure
|
|
// @RELATION DEPENDS_ON -> [ToastsModule]
|
|
// @RELATION CALLED_BY -> [ReportsApi]
|
|
// @RELATION CALLED_BY -> [AssistantApi]
|
|
// @RELATION CALLED_BY -> [TranslateRunsApi]
|
|
// @RELATION CALLED_BY -> [MaintenanceApi]
|
|
// @RELATION CALLED_BY -> [ValidationRunDetailPageLoad]
|
|
// @PRE Auth token is available in localStorage under 'auth_token' after login.
|
|
// @POST Every API call returns typed JSON response or throws typed ApiError with status/detail/error_code.
|
|
// @SIDE_EFFECT Reads localStorage for auth token on every request. Dispatches error toasts on non-suppressed failures.
|
|
// @INVARIANT Every fetch MUST go through fetchApi/requestApi/postApi/deleteApi — never native fetch().
|
|
// @INVARIANT Every response.json() is wrapped in try/catch that converts HTTP errors to ApiError.
|
|
// @INVARIANT FetchOptions.signal is passed to native fetch() for cancellation/timeout support.
|
|
// @DATA_CONTRACT Input: (endpoint, body?, options?) → Output: Promise<T> | Promise<Blob> | Error(ApiError)
|
|
// @RATIONALE FetchOptions.signal added per semantics-core anti-loop protocol — prevents infinite loading
|
|
// state when backend is unreachable. Components can now pass AbortSignal.timeout() or
|
|
// onDestroy-aborted signals to cancel in-flight requests.
|
|
// @RATIONALE fetch wrappers exist to enforce auth token injection, centralized error handling,
|
|
// toast feedback, and trace_id propagation — without wrapping every component in try/catch boilerplate.
|
|
// @REJECTED Native fetch() rejected — would bypass auth header injection, error normalization,
|
|
// and toast feedback. Every component would need its own error handling.
|
|
// @REJECTED Axios rejected — unnecessary dependency for a single-domain API client; native fetch + wrappers
|
|
// is simpler, tree-shakeable, and has zero bundle cost.
|
|
|
|
import { log, setTraceId, getTraceId } from '$lib/cot-logger';
|
|
import { addToast } from './toasts.svelte.js';
|
|
import type { FetchOptions, DashboardListParams } from '../types/api';
|
|
|
|
const API_BASE_URL = '/api';
|
|
|
|
/** Default timeout for API requests in milliseconds (30s). Consumer may override via AbortSignal.timeout(). */
|
|
export const API_REQUEST_TIMEOUT = 30_000;
|
|
|
|
// #region ApiTypes [C:1] [TYPE Block] [SEMANTICS api, types, interfaces]
|
|
// @BRIEF Internal type definitions for error handling and API configuration.
|
|
// @DATA_CONTRACT ApiError: { message, status, detail, error_code }
|
|
|
|
interface ApiError extends Error {
|
|
status?: number;
|
|
detail?: unknown;
|
|
error_code?: string;
|
|
}
|
|
|
|
interface BuildApiErrorResponse {
|
|
detail?: string | { message?: string; error_code?: string; [k: string]: unknown };
|
|
error_code?: string;
|
|
[k: string]: unknown;
|
|
}
|
|
// #endregion ApiTypes
|
|
|
|
// #region buildApiError [C:2] [TYPE Function] [SEMANTICS api, error, parsing]
|
|
// @BRIEF Parse an HTTP Response into a structured ApiError with status, detail, and error_code.
|
|
// @PRE response is a failed HTTP Response object (ok === false).
|
|
// @POST Returns ApiError with message, status, detail, and optional error_code extracted from response body.
|
|
// @SIDE_EFFECT Reads response body via .json() (consumes the response stream).
|
|
// @RELATION CALLED_BY -> [fetchApi]
|
|
// @RELATION CALLED_BY -> [postApi]
|
|
// @RELATION CALLED_BY -> [deleteApi]
|
|
// @RELATION CALLED_BY -> [requestApi]
|
|
// @RATIONALE JSON body parsing is wrapped in .catch() because some error responses (e.g. 502 proxy errors)
|
|
// return non-JSON bodies. Without this, the error itself would throw and mask the original status code.
|
|
async function buildApiError(response: Response): Promise<ApiError> {
|
|
const errorData: BuildApiErrorResponse = await response.json().catch(() => ({}));
|
|
const detail = errorData?.detail;
|
|
const message = detail
|
|
? (typeof detail === 'string' ? detail : (typeof detail?.message === 'string' ? detail.message : JSON.stringify(detail)))
|
|
: `API request failed with status ${response.status}`;
|
|
const error: ApiError = new Error(message) as ApiError;
|
|
error.status = response.status;
|
|
error.detail = detail;
|
|
if (detail && typeof detail === 'object' && (detail as Record<string, unknown>).error_code) {
|
|
error.error_code = String((detail as Record<string, unknown>).error_code);
|
|
}
|
|
return error;
|
|
}
|
|
// #endregion buildApiError
|
|
|
|
// #region notifyApiError [C:2] [TYPE Function] [SEMANTICS api, error, toast, feedback]
|
|
// @BRIEF Dispatch an error toast with severity-based messaging.
|
|
// @PRE error is a structured ApiError (may have status).
|
|
// @POST Toast is dispatched with appropriate message and error severity.
|
|
// @SIDE_EFFECT Calls addToast() which mutates the global toast store.
|
|
// @RELATION DEPENDS_ON -> [addToast:Function]
|
|
// @RELATION CALLED_BY -> [fetchApi]
|
|
// @RELATION CALLED_BY -> [postApi]
|
|
// @RELATION CALLED_BY -> [deleteApi]
|
|
// @RELATION CALLED_BY -> [requestApi]
|
|
// @UX_FEEDBACK 401 → "401 Unauthorized" toast. 500+ → "Server error (N)" toast. Others → error.message toast.
|
|
function notifyApiError(error: ApiError): void {
|
|
if (error?.status === 401) { addToast(`401 Unauthorized: ${error.message}`, 'error'); return; }
|
|
if (error?.status >= 500) { addToast(`Server error (${error.status}): ${error.message}`, 'error'); return; }
|
|
addToast(error.message, 'error');
|
|
}
|
|
// #endregion notifyApiError
|
|
|
|
// #region shouldSuppressApiErrorToast [C:2] [TYPE Function] [SEMANTICS api, error, suppression, heuristics]
|
|
// @BRIEF Determine whether an API error should be silently suppressed (no toast) based on endpoint + error heuristics.
|
|
// @PRE endpoint is a string path. error is a structured ApiError.
|
|
// @POST Returns boolean — true if the error is an expected "non-error" for the given endpoint.
|
|
// @RATIONALE Several endpoints legitimately return 4xx for expected empty states (for example, no Git repository).
|
|
// Suppressing these toasts prevents noise pollution while still throwing for programmatic handling.
|
|
// @REJECTED A global "ignore 4xx" flag rejected — too broad. Each heuristic is endpoint-specific.
|
|
// @RELATION CALLED_BY -> [requestApi]
|
|
function shouldSuppressApiErrorToast(endpoint: string, error: ApiError): boolean {
|
|
const isGitStatusEndpoint = typeof endpoint === 'string' && endpoint.startsWith('/git/repositories/') && endpoint.endsWith('/status');
|
|
const isNoRepoError = (error?.status === 400 || error?.status === 404) && /Repository for dashboard .* not found/i.test(String(error?.message || ''));
|
|
const isGitPullEndpoint = typeof endpoint === 'string' && endpoint.startsWith('/git/repositories/') && endpoint.endsWith('/pull');
|
|
const isUnfinishedMergeError = error?.status === 409 && (String(error?.error_code || '') === 'GIT_UNFINISHED_MERGE' || String((error?.detail as Record<string, unknown>)?.error_code || '') === 'GIT_UNFINISHED_MERGE');
|
|
const isGitRepoEndpoint = typeof endpoint === 'string' && endpoint.startsWith('/git/repositories/');
|
|
const isMissingEnvIdError = error?.status === 400 && /env_id is required/i.test(String(error?.message || ''));
|
|
const isGitConfigReposEndpoint = typeof endpoint === 'string' && /^\/git\/config\/[^/]+\/repositories$/.test(endpoint);
|
|
const isRepoAlreadyExistsError = error?.status === 409 && /already exists/i.test(String(error?.message || ''));
|
|
return (isGitStatusEndpoint && isNoRepoError) || (isGitPullEndpoint && isUnfinishedMergeError) || (isGitRepoEndpoint && isMissingEnvIdError) || (isGitConfigReposEndpoint && isRepoAlreadyExistsError);
|
|
}
|
|
// #endregion shouldSuppressApiErrorToast
|
|
|
|
// #region wsUrlHelpers [C:2] [TYPE Block] [SEMANTICS websocket, url, task-logs, maintenance, translate]
|
|
// @BRIEF WebSocket URL builders — each constructs an authenticated WS endpoint for a specific channel.
|
|
// @PRE taskId / runId are non-empty strings where applicable.
|
|
// @POST Returns fully-qualified ws:// or wss:// URL with auth and x-trace-id query parameters.
|
|
// @SIDE_EFFECT Reads localStorage for auth_token on each call.
|
|
// @RATIONALE WebSocket API does not support custom headers in browser, so auth and trace IDs are
|
|
// appended as query parameters for authentication and cross-stack correlation.
|
|
|
|
function _appendWsCredentials(url: string): string {
|
|
const params = new URLSearchParams();
|
|
if (typeof window !== 'undefined') {
|
|
const token = localStorage.getItem('auth_token');
|
|
if (token) params.set('token', token);
|
|
const traceId = getTraceId();
|
|
if (traceId && traceId !== 'no-trace') params.set('x-trace-id', traceId);
|
|
}
|
|
const query = params.toString();
|
|
return query ? `${url}?${query}` : url;
|
|
}
|
|
|
|
/**
|
|
* Build a WebSocket URL for a task's log stream, including auth token.
|
|
*/
|
|
export const getWsUrl = (taskId: string): string => {
|
|
const protocol = typeof window !== 'undefined' && window.location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|
const host = typeof window !== 'undefined' ? window.location.host : 'localhost:8000';
|
|
return _appendWsCredentials(`${protocol}//${host}/ws/logs/${taskId}`);
|
|
};
|
|
|
|
/**
|
|
* Build a WebSocket URL for global task events, including auth token.
|
|
*/
|
|
export const getTaskEventsWsUrl = (): string => {
|
|
const protocol = typeof window !== 'undefined' && window.location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|
const host = typeof window !== 'undefined' ? window.location.host : 'localhost:8000';
|
|
return _appendWsCredentials(`${protocol}//${host}/ws/task-events`);
|
|
};
|
|
|
|
/**
|
|
* Build a WebSocket URL for maintenance events, including auth token.
|
|
*/
|
|
// #region getMaintenanceEventsWsUrl [C:1] [TYPE Function] [SEMANTICS api, ws, maintenance, url]
|
|
export const getMaintenanceEventsWsUrl = (): string => {
|
|
const protocol = typeof window !== 'undefined' && window.location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|
const host = typeof window !== 'undefined' ? window.location.host : 'localhost:8000';
|
|
return _appendWsCredentials(`${protocol}//${host}/ws/maintenance/events`);
|
|
};
|
|
// #endregion getMaintenanceEventsWsUrl
|
|
|
|
/**
|
|
* Build a WebSocket URL for translation run progress streaming.
|
|
*/
|
|
// #region getTranslateRunWsUrl [C:1] [TYPE Function] [SEMANTICS api, ws, translate, run, url]
|
|
export const getTranslateRunWsUrl = (runId: string): string => {
|
|
const protocol = typeof window !== 'undefined' && window.location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|
const host = typeof window !== 'undefined' ? window.location.host : 'localhost:8000';
|
|
return _appendWsCredentials(`${protocol}//${host}/ws/translate/run/${runId}`);
|
|
};
|
|
// #endregion getTranslateRunWsUrl
|
|
// #endregion wsUrlHelpers
|
|
|
|
// #region getAuthHeaders [C:2] [TYPE Function] [SEMANTICS auth, headers, token, localStorage]
|
|
// @BRIEF Build request headers with Content-Type and optional Bearer token from localStorage.
|
|
// @PRE extraHeaders is an optional map of header key → value.
|
|
// @POST Returns headers object with Content-Type: application/json and Authorization: Bearer <token> if logged in.
|
|
// @SIDE_EFFECT Reads localStorage for auth_token on every call.
|
|
// @RELATION CALLED_BY -> [fetchApi]
|
|
// @RELATION CALLED_BY -> [fetchApiBlob]
|
|
// @RELATION CALLED_BY -> [postApi]
|
|
// @RELATION CALLED_BY -> [deleteApi]
|
|
// @RELATION CALLED_BY -> [requestApi]
|
|
function getAuthHeaders(extraHeaders: Record<string, string> = {}, includeContentType = true): Record<string, string> {
|
|
const headers: Record<string, string> = { ...(includeContentType ? { 'Content-Type': 'application/json' } : {}), ...extraHeaders };
|
|
if (typeof window !== 'undefined') {
|
|
const token = localStorage.getItem('auth_token');
|
|
if (token) headers['Authorization'] = `Bearer ${token}`;
|
|
// Propagate trace_id to backend for cross-stack correlation
|
|
const tid = getTraceId();
|
|
if (tid && tid !== 'no-trace') {
|
|
headers['X-Trace-ID'] = tid;
|
|
}
|
|
}
|
|
return headers;
|
|
}
|
|
// #endregion getAuthHeaders
|
|
|
|
// #region fetchApi [C:4] [TYPE Function] [SEMANTICS api, fetch, get, json]
|
|
// @BRIEF Perform an authenticated GET request and return typed JSON response.
|
|
// @PRE endpoint is a non-empty string path (without /api prefix).
|
|
// @PRE options.headers may override default Content-Type.
|
|
// @POST Returns Promise<T> with parsed JSON. Returns null for 204 No Content.
|
|
// Throws ApiError on non-2xx response.
|
|
// @SIDE_EFFECT Sends HTTP GET request. On failure, dispatches error toast (unless options.suppressToast).
|
|
// Writes CoT log line via log() on entry and failure.
|
|
// @RELATION DEPENDS_ON -> [buildApiError]
|
|
// @RELATION DEPENDS_ON -> [notifyApiError]
|
|
// @RELATION DEPENDS_ON -> [getAuthHeaders]
|
|
/** Endpoints that are polled frequently — suppress CoT REASON/REFLECT to reduce noise.
|
|
* Errors are still logged as EXPLORE. Matches backend's log_requests polling suppression. */
|
|
const _SILENT_POLLING_ENDPOINTS = [
|
|
'/health/summary',
|
|
'/api/tasks',
|
|
];
|
|
|
|
/** Check if an endpoint is a silent polling endpoint (suppress CoT REASON/REFLECT). */
|
|
function _isSilentPolling(endpoint: string): boolean {
|
|
return _SILENT_POLLING_ENDPOINTS.some(e => endpoint.startsWith(e) || endpoint.endsWith(e));
|
|
}
|
|
|
|
/** Extract X-Trace-Id from response headers and seed the CoT logger's trace_id. */
|
|
function _captureTraceId(response: Response): void {
|
|
try {
|
|
const traceId = response.headers?.get?.('x-trace-id');
|
|
if (traceId) setTraceId(traceId);
|
|
} catch {
|
|
// headers unavailable (e.g. test mock without full Headers API)
|
|
}
|
|
}
|
|
|
|
async function fetchApi<T = unknown>(endpoint: string, options: FetchOptions = {}): Promise<T> {
|
|
const _start = performance.now();
|
|
const _silent = _isSilentPolling(endpoint);
|
|
try {
|
|
if (!_silent) log('ApiClient', 'REASON', 'GET data', { endpoint });
|
|
const fetchInit: RequestInit = { headers: getAuthHeaders(options.headers || {}) };
|
|
if (options.signal) fetchInit.signal = options.signal;
|
|
const response = await fetch(`${API_BASE_URL}${endpoint}`, fetchInit);
|
|
if (!response.ok) throw await buildApiError(response);
|
|
if (response.status === 204) return null as T;
|
|
_captureTraceId(response);
|
|
const data = await response.json() as T;
|
|
if (!_silent) log('ApiClient', 'REFLECT', 'GET completed', {
|
|
endpoint, status: response.status,
|
|
elapsed_ms: Math.round(performance.now() - _start),
|
|
});
|
|
return data;
|
|
} catch (error) {
|
|
const apiError = error as ApiError;
|
|
log('ApiClient', 'EXPLORE', 'GET failed', { endpoint }, apiError?.message || 'unknown');
|
|
if (!options.suppressToast) notifyApiError(apiError);
|
|
throw error;
|
|
}
|
|
}
|
|
// #endregion fetchApi
|
|
|
|
// #region fetchApiBlob [C:4] [TYPE Function] [SEMANTICS api, fetch, blob, thumbnail, file]
|
|
// @BRIEF Perform an authenticated GET request and return a Blob (for thumbnails, file downloads).
|
|
// @PRE endpoint is a non-empty string path.
|
|
// @POST Returns Promise<Blob> with binary data. Throws ApiError on failure or 202 "in progress".
|
|
// @SIDE_EFFECT Sends HTTP GET request. On failure (unless notifyError=false), dispatches error toast.
|
|
// Writes CoT log line on entry, success, and failure.
|
|
// @RELATION DEPENDS_ON -> [buildApiError]
|
|
// @RELATION DEPENDS_ON -> [notifyApiError]
|
|
// @RELATION DEPENDS_ON -> [getAuthHeaders]
|
|
// @RATIONALE 202 status is handled as a special case — the thumbnail generation may still be in progress.
|
|
// The caller can retry after a delay. This is NOT treated as a server error.
|
|
async function fetchApiBlob(endpoint: string, options: FetchOptions = {}): Promise<Blob> {
|
|
const _start = performance.now();
|
|
const notifyError = options.notifyError !== false;
|
|
const _silent = _isSilentPolling(endpoint);
|
|
try {
|
|
if (!_silent) log('ApiClient', 'REASON', 'GET blob', { endpoint });
|
|
const fetchInit: RequestInit = { headers: getAuthHeaders(options.headers || {}) };
|
|
if (options.signal) fetchInit.signal = options.signal;
|
|
const response = await fetch(`${API_BASE_URL}${endpoint}`, fetchInit);
|
|
if (response.status === 202) {
|
|
const payload: Record<string, unknown> = await response.json().catch(() => ({ message: "Resource is being prepared" }));
|
|
const error: ApiError = new Error((payload?.message as string) || "Resource is being prepared") as ApiError;
|
|
error.status = 202;
|
|
throw error;
|
|
}
|
|
if (!response.ok) throw await buildApiError(response);
|
|
_captureTraceId(response);
|
|
if (!_silent) log('ApiClient', 'REFLECT', 'GET blob completed', {
|
|
endpoint, status: response.status,
|
|
elapsed_ms: Math.round(performance.now() - _start),
|
|
});
|
|
return await response.blob();
|
|
} catch (error) {
|
|
const apiError = error as ApiError;
|
|
log('ApiClient', 'EXPLORE', 'GET blob failed', { endpoint, status: apiError?.status }, apiError?.message || 'unknown');
|
|
if (notifyError) notifyApiError(apiError);
|
|
throw error;
|
|
}
|
|
}
|
|
// #endregion fetchApiBlob
|
|
|
|
// #region postApi [C:4] [TYPE Function] [SEMANTICS api, post, create, json]
|
|
// @BRIEF Perform an authenticated POST request with JSON body and return typed response.
|
|
// @PRE endpoint is a non-empty string path.
|
|
// @PRE body is JSON-serializable (will be passed through JSON.stringify).
|
|
// @POST Returns Promise<T> with parsed JSON. Returns null for 204 No Content.
|
|
// Throws ApiError on non-2xx response.
|
|
// @SIDE_EFFECT Sends HTTP POST request. On failure, dispatches error toast (unless options.suppressToast).
|
|
// Writes CoT log line on entry and failure.
|
|
// @RELATION DEPENDS_ON -> [buildApiError]
|
|
// @RELATION DEPENDS_ON -> [notifyApiError]
|
|
// @RELATION DEPENDS_ON -> [getAuthHeaders]
|
|
async function postApi<T = unknown>(endpoint: string, body: unknown, options: FetchOptions = {}): Promise<T> {
|
|
const _start = performance.now();
|
|
const _silent = _isSilentPolling(endpoint);
|
|
try {
|
|
if (!_silent) log('ApiClient', 'REASON', 'POST data', { endpoint });
|
|
const fetchInit: RequestInit = {
|
|
method: 'POST', headers: getAuthHeaders(options.headers || {}), body: JSON.stringify(body),
|
|
};
|
|
if (options.signal) fetchInit.signal = options.signal;
|
|
const response = await fetch(`${API_BASE_URL}${endpoint}`, fetchInit);
|
|
if (!response.ok) throw await buildApiError(response);
|
|
if (response.status === 204) return null as T;
|
|
_captureTraceId(response);
|
|
const data = await response.json() as T;
|
|
if (!_silent) log('ApiClient', 'REFLECT', 'POST completed', {
|
|
endpoint, status: response.status,
|
|
elapsed_ms: Math.round(performance.now() - _start),
|
|
});
|
|
return data;
|
|
} catch (error) {
|
|
const apiError = error as ApiError;
|
|
log('ApiClient', 'EXPLORE', 'POST failed', { endpoint }, apiError?.message || 'unknown');
|
|
if (!options.suppressToast) notifyApiError(apiError);
|
|
throw error;
|
|
}
|
|
}
|
|
// #endregion postApi
|
|
|
|
// #region deleteApi [C:4] [TYPE Function] [SEMANTICS api, delete, remove]
|
|
// @BRIEF Perform an authenticated DELETE request and return typed response.
|
|
// @PRE endpoint is a non-empty string path.
|
|
// @POST Returns Promise<T> with parsed JSON. Returns null for 204 No Content.
|
|
// Throws ApiError on non-2xx response. Always dispatches error toast on failure.
|
|
// @SIDE_EFFECT Sends HTTP DELETE request. On failure, dispatches error toast.
|
|
// Writes CoT log line on entry and failure.
|
|
// @RELATION DEPENDS_ON -> [buildApiError]
|
|
// @RELATION DEPENDS_ON -> [notifyApiError]
|
|
// @RELATION DEPENDS_ON -> [getAuthHeaders]
|
|
// @RATIONALE deleteApi always notifies on error (no suppressToast option) because deletions
|
|
// are destructive operations — the user must know if one failed.
|
|
async function deleteApi<T = unknown>(endpoint: string, options: FetchOptions = {}): Promise<T> {
|
|
const _start = performance.now();
|
|
const _silent = _isSilentPolling(endpoint);
|
|
try {
|
|
if (!_silent) log('ApiClient', 'REASON', 'DELETE data', { endpoint });
|
|
const fetchInit: RequestInit = { method: 'DELETE', headers: getAuthHeaders(options.headers || {}) };
|
|
if (options.signal) fetchInit.signal = options.signal;
|
|
const response = await fetch(`${API_BASE_URL}${endpoint}`, fetchInit);
|
|
if (!response.ok) throw await buildApiError(response);
|
|
if (response.status === 204) return null as T;
|
|
_captureTraceId(response);
|
|
const data = await response.json() as T;
|
|
if (!_silent) log('ApiClient', 'REFLECT', 'DELETE completed', {
|
|
endpoint, status: response.status,
|
|
elapsed_ms: Math.round(performance.now() - _start),
|
|
});
|
|
return data;
|
|
} catch (error) {
|
|
const apiError = error as ApiError;
|
|
log('ApiClient', 'EXPLORE', 'DELETE failed', { endpoint }, apiError?.message || 'unknown');
|
|
notifyApiError(apiError);
|
|
throw error;
|
|
}
|
|
}
|
|
// #endregion deleteApi
|
|
|
|
// #region requestApi [C:4] [TYPE Function] [SEMANTICS api, request, generic, patch, put]
|
|
// @BRIEF Generic authenticated HTTP request — supports any method, optional JSON body, and contextual toast suppression.
|
|
// @PRE endpoint is a non-empty string path.
|
|
// @PRE body is JSON-serializable if provided (null = no body).
|
|
// @POST Returns Promise<T> with parsed JSON. Returns null for 204 No Content.
|
|
// Throws ApiError on non-2xx response.
|
|
// Error toast suppressed if shouldSuppressApiErrorToast returns true for the endpoint+error combo.
|
|
// @SIDE_EFFECT Sends HTTP request. On failure, conditionally dispatches error toast (subject to suppression heuristics).
|
|
// Writes CoT log line on entry and failure.
|
|
// @RELATION DEPENDS_ON -> [buildApiError]
|
|
// @RELATION DEPENDS_ON -> [notifyApiError]
|
|
// @RELATION DEPENDS_ON -> [shouldSuppressApiErrorToast]
|
|
// @RELATION DEPENDS_ON -> [getAuthHeaders]
|
|
async function requestApi<T = unknown>(endpoint: string, method: string = 'GET', body: unknown = null, requestOptions: FetchOptions = {}): Promise<T> {
|
|
const _start = performance.now();
|
|
const _silent = _isSilentPolling(endpoint);
|
|
try {
|
|
if (!_silent) log('ApiClient', 'REASON', `${method} data`, { endpoint, method });
|
|
const isFormBody = body instanceof URLSearchParams || body instanceof FormData;
|
|
const fetchInit: RequestInit = {
|
|
method,
|
|
headers: isFormBody ? getAuthHeaders(requestOptions.headers || {}, false) : getAuthHeaders(requestOptions.headers || {}),
|
|
};
|
|
if (body) fetchInit.body = isFormBody ? body : JSON.stringify(body);
|
|
if (requestOptions.signal) fetchInit.signal = requestOptions.signal;
|
|
const response = await fetch(`${API_BASE_URL}${endpoint}`, fetchInit);
|
|
if (!response.ok) throw await buildApiError(response);
|
|
if (response.status === 204) return null as T;
|
|
_captureTraceId(response);
|
|
const data = await response.json() as T;
|
|
if (!_silent) log('ApiClient', 'REFLECT', `${method} completed`, {
|
|
endpoint, method, status: response.status,
|
|
elapsed_ms: Math.round(performance.now() - _start),
|
|
});
|
|
return data;
|
|
} catch (error) {
|
|
const apiError = error as ApiError;
|
|
log('ApiClient', 'EXPLORE', `${method} failed`, { method, endpoint }, apiError?.message || 'unknown');
|
|
if (!requestOptions.suppressToast && !shouldSuppressApiErrorToast(endpoint, apiError)) {
|
|
notifyApiError(apiError);
|
|
}
|
|
throw error;
|
|
}
|
|
}
|
|
// #endregion requestApi
|
|
|
|
// ── Named type helpers for API methods ───────────────────────
|
|
// These are internal interfaces used by the api registry below.
|
|
|
|
interface TaskListQueryOptions {
|
|
limit?: number;
|
|
offset?: number;
|
|
status?: string;
|
|
task_type?: string;
|
|
completed_only?: boolean;
|
|
plugin_id?: string[];
|
|
search?: string;
|
|
}
|
|
|
|
interface TaskLogQueryOptions {
|
|
level?: string;
|
|
source?: string;
|
|
search?: string;
|
|
offset?: number;
|
|
limit?: number;
|
|
}
|
|
|
|
interface DashboardThumbnailOptions {
|
|
force?: boolean;
|
|
}
|
|
|
|
interface DatasetQueryOptions {
|
|
search?: string;
|
|
filter?: string;
|
|
page?: string;
|
|
page_size?: string;
|
|
}
|
|
|
|
interface SupersetAccountOptions {
|
|
search?: string;
|
|
page_index?: number;
|
|
page_size?: number;
|
|
sort_column?: string;
|
|
sort_order?: string;
|
|
}
|
|
|
|
interface ValidationTaskQueryParams {
|
|
page?: number;
|
|
page_size?: number;
|
|
is_active?: boolean;
|
|
environment_id?: string;
|
|
search?: string;
|
|
}
|
|
|
|
interface ValidationRunQueryParams {
|
|
page?: number;
|
|
page_size?: number;
|
|
}
|
|
|
|
// #region uploadFile [C:2] [TYPE Function] [SEMANTICS api, upload, file, multipart]
|
|
// @BRIEF Upload a file via multipart/form-data to the given endpoint.
|
|
// @PRE endpoint is a non-empty string path.
|
|
// @PRE file is a File object.
|
|
// @PRE fields contains optional multipart form fields.
|
|
// @POST Returns Promise<T> with parsed JSON.
|
|
// @SIDE_EFFECT Sends HTTP POST with multipart/form-data.
|
|
// @RATIONALE Uses native fetch because the existing fetchApi/postApi/requestApi wrappers
|
|
// always set Content-Type: application/json, which breaks multipart uploads (the browser
|
|
// must auto-set Content-Type with the boundary). This is the ONLY exception to the
|
|
// "never native fetch" invariant.
|
|
// @RELATION CALLED_BY -> [MapperTool]
|
|
async function uploadFile<T = unknown>(endpoint: string, file: File, fields: Record<string, string> = {}): Promise<T> {
|
|
const _start = performance.now();
|
|
const formData = new FormData();
|
|
formData.append('file', file);
|
|
Object.entries(fields).forEach(([key, value]) => formData.append(key, value));
|
|
try {
|
|
log('ApiClient', 'REASON', 'Upload file', { endpoint, filename: file.name, size: file.size });
|
|
const headers: Record<string, string> = {};
|
|
if (typeof window !== 'undefined') {
|
|
const token = localStorage.getItem('auth_token');
|
|
if (token) headers['Authorization'] = `Bearer ${token}`;
|
|
const tid = getTraceId();
|
|
if (tid && tid !== 'no-trace') {
|
|
headers['X-Trace-ID'] = tid;
|
|
}
|
|
}
|
|
const response = await fetch(`${API_BASE_URL}${endpoint}`, {
|
|
method: 'POST',
|
|
headers,
|
|
body: formData,
|
|
});
|
|
if (!response.ok) throw await buildApiError(response);
|
|
_captureTraceId(response);
|
|
const data = await response.json() as T;
|
|
log('ApiClient', 'REFLECT', 'Upload completed', {
|
|
endpoint, filename: file.name, status: response.status,
|
|
elapsed_ms: Math.round(performance.now() - _start),
|
|
});
|
|
return data;
|
|
} catch (error) {
|
|
const apiError = error as ApiError;
|
|
log('ApiClient', 'EXPLORE', 'Upload failed', { endpoint, filename: file.name }, apiError?.message || 'unknown');
|
|
notifyApiError(apiError);
|
|
throw error;
|
|
}
|
|
}
|
|
// #endregion uploadFile
|
|
|
|
|
|
// #region ApiRegistry [C:3] [TYPE Block] [SEMANTICS api, endpoints, registry]
|
|
// @BRIEF Named endpoint registry — maps backend API paths to typed frontend methods.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @RELATION DEPENDS_ON -> [deleteApi]
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
// @RELATION DEPENDS_ON -> [fetchApiBlob]
|
|
// @RELATION DEPENDS_ON -> [uploadFile]
|
|
// @INVARIANT Every method delegates to fetchApi/postApi/deleteApi/requestApi/uploadFile — never native fetch.
|
|
// @RATIONALE The registry pattern keeps endpoint paths in one place and eliminates path-string duplication across components.
|
|
export const api = {
|
|
login: <T = { access_token: string }>(body: URLSearchParams) => requestApi<T>('/auth/login', 'POST', body, { suppressToast: true }),
|
|
fetchApi: fetchApi as <T = unknown>(endpoint: string, options?: FetchOptions) => Promise<T>,
|
|
postApi: postApi as <T = unknown>(endpoint: string, body: unknown, options?: FetchOptions) => Promise<T>,
|
|
deleteApi: deleteApi as <T = unknown>(endpoint: string, options?: FetchOptions) => Promise<T>,
|
|
requestApi: requestApi as <T = unknown>(endpoint: string, method?: string, body?: unknown, requestOptions?: FetchOptions) => Promise<T>,
|
|
fetchApiBlob: fetchApiBlob as (endpoint: string, options?: FetchOptions) => Promise<Blob>,
|
|
uploadFile: uploadFile as <T = unknown>(endpoint: string, file: File) => Promise<T>,
|
|
|
|
// ═══ Tasks ════════════════════════════════════════════════════
|
|
|
|
// #region getPlugins [C:2] [TYPE Function] [SEMANTICS plugins,api,list]
|
|
// @BRIEF Fetch all registered plugins.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { plugins: { id, name, description, version, category }[] }
|
|
getPlugins: <T = unknown>() => fetchApi<T>('/plugins'),
|
|
// #endregion getPlugins
|
|
|
|
// #region getTasks [C:2] [TYPE Function] [SEMANTICS tasks,api,list,pagination]
|
|
// @BRIEF Fetch paginated task list with optional status/type filters.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { limit?, offset?, status?, task_type?, completed_only?, plugin_id?[] }
|
|
// @DATA_CONTRACT response -> { tasks: { id, plugin_id, status, started_at, completed_at, progress?, error?, retry_count?, params? }[], total: number }
|
|
getTasks: <T = unknown>(options: TaskListQueryOptions = {}) => {
|
|
const params = new URLSearchParams();
|
|
if (options.limit != null) params.append('limit', String(options.limit));
|
|
if (options.offset != null) params.append('offset', String(options.offset));
|
|
if (options.status) params.append('status', options.status);
|
|
if (options.task_type) params.append('task_type', options.task_type);
|
|
if (options.completed_only != null) params.append('completed_only', String(Boolean(options.completed_only)));
|
|
if (Array.isArray(options.plugin_id)) options.plugin_id.forEach((pid: string) => params.append('plugin_id', pid));
|
|
if (options.search) params.append('search', options.search);
|
|
const query = params.toString();
|
|
return fetchApi<T>(`/tasks${query ? `?${query}` : ''}`);
|
|
},
|
|
// #endregion getTasks
|
|
|
|
// #region getTask [C:2] [TYPE Function] [SEMANTICS tasks,api,detail]
|
|
// @BRIEF Fetch a single task by ID with full status and result.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { taskId }
|
|
// @DATA_CONTRACT response -> { id, plugin_id, status, started_at, completed_at, progress?, error?, retry_count?, params?, result?, input_request?: { type, databases?[] } }
|
|
getTask: <T = unknown>(taskId: string) => fetchApi<T>(`/tasks/${taskId}`),
|
|
// #endregion getTask
|
|
|
|
// #region getTaskLogs [C:2] [TYPE Function] [SEMANTICS tasks,api,logs]
|
|
// @BRIEF Fetch paginated task log entries with level/source/search filters.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { taskId, level?, source?, search?, offset?, limit? }
|
|
// @DATA_CONTRACT response -> { logs: { timestamp, level, source, message }[], total: number }
|
|
getTaskLogs: <T = unknown>(taskId: string, options: TaskLogQueryOptions = {}) => {
|
|
const params = new URLSearchParams();
|
|
if (options.level) params.append('level', options.level);
|
|
if (options.source) params.append('source', options.source);
|
|
if (options.search) params.append('search', options.search);
|
|
if (options.offset != null) params.append('offset', String(options.offset));
|
|
if (options.limit != null) params.append('limit', String(options.limit));
|
|
return fetchApi<T>(`/tasks/${taskId}/logs${params.toString() ? `?${params.toString()}` : ''}`);
|
|
},
|
|
// #endregion getTaskLogs
|
|
|
|
// #region createTask [C:2] [TYPE Function] [SEMANTICS tasks,api,create]
|
|
// @BRIEF Create a new background task with plugin ID and params.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT params -> { plugin_id, params: object }
|
|
// @DATA_CONTRACT response -> { task_id: string }
|
|
createTask: <T = unknown>(pluginId: string, params: unknown, requestOptions?: FetchOptions) =>
|
|
postApi<T>('/tasks', { plugin_id: pluginId, params }, requestOptions),
|
|
// #endregion createTask
|
|
|
|
// ═══ Profile ══════════════════════════════════════════════════
|
|
|
|
// #region getProfilePreferences [C:2] [TYPE Function] [SEMANTICS profile,api,preferences]
|
|
// @BRIEF Fetch current user profile preferences.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { auto_open_task_drawer?: boolean, default_environment_id?: string, default_profile_filter?: object }
|
|
getProfilePreferences: <T = unknown>() => fetchApi<T>('/profile/preferences'),
|
|
// #endregion getProfilePreferences
|
|
|
|
// #region updateProfilePreferences [C:2] [TYPE Function] [SEMANTICS profile,api,update]
|
|
// @BRIEF Update user profile preferences (PATCH).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
// @DATA_CONTRACT params -> { auto_open_task_drawer?, default_environment_id?, default_profile_filter? }
|
|
// @DATA_CONTRACT response -> { success: boolean }
|
|
updateProfilePreferences: <T = unknown>(payload: unknown) => requestApi<T>('/profile/preferences', 'PATCH', payload),
|
|
// #endregion updateProfilePreferences
|
|
|
|
// #region lookupSupersetAccounts [C:2] [TYPE Function] [SEMANTICS profile,api,superset,lookup]
|
|
// @BRIEF Search Superset accounts for profile identity mapping.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { environmentId, search?, page_index?, page_size?, sort_column?, sort_order? }
|
|
// @DATA_CONTRACT response -> { accounts: { id, username, first_name?, last_name?, email? }[], total: number }
|
|
lookupSupersetAccounts: <T = unknown>(environmentId: string, options: SupersetAccountOptions = {}) => {
|
|
const eid = String(environmentId || '').trim();
|
|
if (!eid) throw new Error('environmentId is required for Superset account lookup');
|
|
const params = new URLSearchParams({ environment_id: eid });
|
|
if (options.search) params.append('search', options.search);
|
|
if (options.page_index != null) params.append('page_index', String(options.page_index));
|
|
if (options.page_size != null) params.append('page_size', String(options.page_size));
|
|
if (options.sort_column) params.append('sort_column', options.sort_column);
|
|
if (options.sort_order) params.append('sort_order', options.sort_order);
|
|
return fetchApi<T>(`/profile/superset-accounts?${params.toString()}`);
|
|
},
|
|
// #endregion lookupSupersetAccounts
|
|
|
|
// ═══ Settings ═════════════════════════════════════════════════
|
|
|
|
// #region getSettings [C:2] [TYPE Function] [SEMANTICS settings,api,list]
|
|
// @BRIEF Fetch all settings (environments, storage, logging).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { environments, storage, logging, llm, migration, features, system }
|
|
getSettings: <T = unknown>() => fetchApi<T>('/settings'),
|
|
// #endregion getSettings
|
|
|
|
// #region updateGlobalSettings [C:2] [TYPE Function] [SEMANTICS settings,api,update,global]
|
|
// @BRIEF Update global settings (PATCH).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
updateGlobalSettings: <T = unknown>(s: unknown) => requestApi<T>('/settings/global', 'PATCH', s),
|
|
// #endregion updateGlobalSettings
|
|
|
|
// #region getEnvironments [C:2] [TYPE Function] [SEMANTICS settings,api,environments,list]
|
|
// @BRIEF Fetch all configured Superset environments.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { environments: { id, name, url, database?, schedule? }[] }
|
|
getEnvironments: <T = unknown>() => fetchApi<T>('/settings/environments'),
|
|
// #endregion getEnvironments
|
|
|
|
// #region addEnvironment [C:2] [TYPE Function] [SEMANTICS settings,api,environments,create]
|
|
// @BRIEF Add a new Superset environment.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT params -> { name, url, database?, schedule? }
|
|
// @DATA_CONTRACT response -> { id, name, url }
|
|
addEnvironment: <T = unknown>(env: unknown) => postApi<T>('/settings/environments', env),
|
|
// #endregion addEnvironment
|
|
|
|
// #region updateEnvironment [C:2] [TYPE Function] [SEMANTICS settings,api,environments,update]
|
|
// @BRIEF Full update of an environment by ID (PUT).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
updateEnvironment: <T = unknown>(id: string, env: unknown) => requestApi<T>(`/settings/environments/${id}`, 'PUT', env),
|
|
// #endregion updateEnvironment
|
|
|
|
// #region gitReleasePolicy [C:2] [TYPE Function] [SEMANTICS git,release,policy,settings]
|
|
// @BRIEF Read and update the approval policy for Git release candidates.
|
|
getGitReleasePolicy: <T = unknown>() => requestApi<T>('/settings/git-release-policy', 'GET'),
|
|
updateGitReleasePolicy: <T = unknown>(policy: unknown) => requestApi<T>('/settings/git-release-policy', 'PUT', policy),
|
|
// #endregion gitReleasePolicy
|
|
|
|
// #region deleteEnvironment [C:2] [TYPE Function] [SEMANTICS settings,api,environments,delete]
|
|
// @BRIEF Delete an environment by ID.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
deleteEnvironment: <T = unknown>(id: string) => requestApi<T>(`/settings/environments/${id}`, 'DELETE'),
|
|
// #endregion deleteEnvironment
|
|
|
|
// #region testEnvironmentConnection [C:2] [TYPE Function] [SEMANTICS settings,api,environments,test]
|
|
// @BRIEF Test connection to an environment.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT response -> { success: boolean, message?: string }
|
|
testEnvironmentConnection: <T = unknown>(id: string) => postApi<T>(`/settings/environments/${id}/test`, {}),
|
|
// #endregion testEnvironmentConnection
|
|
|
|
// #region updateEnvironmentSchedule [C:2] [TYPE Function] [SEMANTICS settings,api,environments,schedule]
|
|
// @BRIEF Update environment refresh schedule (PUT).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
updateEnvironmentSchedule: <T = unknown>(id: string, s: unknown, options?: FetchOptions) =>
|
|
requestApi<T>(`/environments/${id}/schedule`, 'PUT', s, options),
|
|
// #endregion updateEnvironmentSchedule
|
|
|
|
// #region getStorageSettings [C:2] [TYPE Function] [SEMANTICS settings,api,storage,list]
|
|
// @BRIEF Fetch storage configuration.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { path, max_size?, allowed_types? }
|
|
getStorageSettings: <T = unknown>() => fetchApi<T>('/settings/storage'),
|
|
// #endregion getStorageSettings
|
|
|
|
// #region updateStorageSettings [C:2] [TYPE Function] [SEMANTICS settings,api,storage,update]
|
|
// @BRIEF Update storage configuration (PUT).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
updateStorageSettings: <T = unknown>(s: unknown) => requestApi<T>('/settings/storage', 'PUT', s),
|
|
// #endregion updateStorageSettings
|
|
|
|
// #region getEnvironmentsList [C:2] [TYPE Function] [SEMANTICS settings,api,environments,list,flat]
|
|
// @BRIEF Fetch flat list of environments (simplified form).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { id, name, url, status }[] // flat list form
|
|
getEnvironmentsList: <T = unknown>(options?: FetchOptions) => fetchApi<T>('/environments', options),
|
|
// #endregion getEnvironmentsList
|
|
|
|
// ═══ LLM ══════════════════════════════════════════════════════
|
|
|
|
// #region getLlmStatus [C:2] [TYPE Function] [SEMANTICS llm,api,status]
|
|
// @BRIEF Fetch LLM service status and provider health.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { configured: boolean, providers: { id, name, status }[] }
|
|
getLlmStatus: <T = unknown>() => fetchApi<T>('/llm/status'),
|
|
// #endregion getLlmStatus
|
|
|
|
// #region fetchLlmModels [C:2] [TYPE Function] [SEMANTICS llm,api,providers,fetch-models]
|
|
// @BRIEF Fetch available models from an LLM provider.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
fetchLlmModels: <T = unknown>(p: unknown) => postApi<T>('/llm/providers/fetch-models', p),
|
|
// #endregion fetchLlmModels
|
|
|
|
// #region getEnvironmentDatabases [C:2] [TYPE Function] [SEMANTICS environments,api,databases]
|
|
// @BRIEF Fetch databases for an environment (used for mapping).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { env_id }
|
|
// @DATA_CONTRACT response -> { databases: { uuid, database_name, backend? }[] }
|
|
getEnvironmentDatabases: <T = unknown>(id: string) => fetchApi<T>(`/environments/${id}/databases`),
|
|
// #endregion getEnvironmentDatabases
|
|
|
|
// ═══ Storage ══════════════════════════════════════════════════
|
|
|
|
// #region getStorageFileBlob [C:2] [TYPE Function] [SEMANTICS storage,api,file,blob]
|
|
// @BRIEF Download a storage file as a Blob.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApiBlob]
|
|
// @DATA_CONTRACT params -> { path }
|
|
// @DATA_CONTRACT response -> Blob (binary file)
|
|
getStorageFileBlob: (path: string) => fetchApiBlob(`/storage/file?path=${encodeURIComponent(path)}`),
|
|
// #endregion getStorageFileBlob
|
|
|
|
// #region getStorageFiles [C:2] [TYPE Function] [SEMANTICS storage,api,files,list]
|
|
// @BRIEF List files in a storage category, with optional subpath.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { category, path? }
|
|
// @DATA_CONTRACT response -> StoredFile[]
|
|
getStorageFiles: <T = unknown>(category: string, subpath?: string, options?: FetchOptions) => {
|
|
const query = subpath
|
|
? `/storage/files?category=${encodeURIComponent(category)}&path=${encodeURIComponent(subpath)}`
|
|
: `/storage/files?category=${encodeURIComponent(category)}`;
|
|
return fetchApi<T>(query, options);
|
|
},
|
|
// #endregion getStorageFiles
|
|
|
|
// ═══ Dashboards ═══════════════════════════════════════════════
|
|
|
|
// #region getDashboards [C:2] [TYPE Function] [SEMANTICS dashboards,api,list,pagination]
|
|
// @BRIEF Fetch paginated dashboards for an environment with filters and profile context.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { env_id, page?, page_size?, page_context?, apply_profile_default?, override_show_all?, search?, filters?: { title?, git_status?, llm_status?, changed_on?, actor? } }
|
|
// @DATA_CONTRACT response -> { dashboards: { id, title, slug, last_modified, owners, git_status, last_task }[], total: number, page: number, page_size: number, total_pages: number, effective_profile_filter?: { applied: boolean, override_show_all: boolean, username?: string, match_logic?: string } }
|
|
getDashboards: <T = unknown>(envId: string, options: DashboardListParams = {}) => {
|
|
const params = new URLSearchParams({ env_id: envId });
|
|
if (options.search) params.append('search', options.search);
|
|
if (options.page) params.append('page', options.page);
|
|
if (options.page_size) params.append('page_size', options.page_size);
|
|
if (options.page_context) params.append('page_context', options.page_context);
|
|
if (options.apply_profile_default != null) params.append('apply_profile_default', String(Boolean(options.apply_profile_default)));
|
|
if (options.override_show_all != null) params.append('override_show_all', String(Boolean(options.override_show_all)));
|
|
if (options.filters?.title) for (const v of options.filters.title) params.append('filter_title', v);
|
|
if (options.filters?.git_status) for (const v of options.filters.git_status) params.append('filter_git_status', v);
|
|
if (options.filters?.llm_status) for (const v of options.filters.llm_status) params.append('filter_llm_status', v);
|
|
if (options.filters?.changed_on) for (const v of options.filters.changed_on) params.append('filter_changed_on', v);
|
|
if (options.filters?.actor) for (const v of options.filters.actor) params.append('filter_actor', v);
|
|
if (options.filter_changed_on_from) params.append('filter_changed_on_from', options.filter_changed_on_from);
|
|
if (options.filter_changed_on_to) params.append('filter_changed_on_to', options.filter_changed_on_to);
|
|
return fetchApi<T>(`/dashboards?${params.toString()}`);
|
|
},
|
|
// #endregion getDashboards
|
|
|
|
// #region getDashboardDetail [C:2] [TYPE Function] [SEMANTICS dashboards,api,detail]
|
|
// @BRIEF Fetch a single dashboard by ref (ID or slug).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { env_id, ref: dashboard_id_or_slug }
|
|
// @DATA_CONTRACT response -> { id, title, slug, last_modified, status, chart_count?, dataset_count?, owner_ids?, tags?, metadata_json? }
|
|
getDashboardDetail: <T = unknown>(envId: string, ref: string) => fetchApi<T>(`/dashboards/${encodeURIComponent(String(ref))}?env_id=${envId}`),
|
|
// #endregion getDashboardDetail
|
|
|
|
// #region getDashboardTaskHistory [C:2] [TYPE Function] [SEMANTICS dashboards,api,tasks,history]
|
|
// @BRIEF Fetch task history for a specific dashboard.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { env_id, ref, opts?: { limit? } }
|
|
// @DATA_CONTRACT response -> { tasks: { id, plugin_id, status, started_at, completed_at, error?, params? }[] }
|
|
getDashboardTaskHistory: <T = unknown>(envId: string, ref: string, opts: { limit?: number } = {}) => {
|
|
const params = new URLSearchParams();
|
|
if (envId) params.append('env_id', envId);
|
|
if (opts.limit) params.append('limit', opts.limit);
|
|
return fetchApi<T>(`/dashboards/${encodeURIComponent(String(ref))}/tasks?${params.toString()}`);
|
|
},
|
|
// #endregion getDashboardTaskHistory
|
|
|
|
// #region getDashboardThumbnail [C:2] [TYPE Function] [SEMANTICS dashboards,api,thumbnail,blob]
|
|
// @BRIEF Fetch dashboard thumbnail as Blob with optional force regeneration.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApiBlob]
|
|
// @DATA_CONTRACT params -> { env_id, ref, opts?: { force? } }
|
|
// @DATA_CONTRACT response -> Blob (image/png thumbnail)
|
|
getDashboardThumbnail: (envId: string, ref: string, opts: DashboardThumbnailOptions = {}) => {
|
|
const params = new URLSearchParams({ env_id: envId });
|
|
if (opts.force != null) params.append('force', String(Boolean(opts.force)));
|
|
return fetchApiBlob(`/dashboards/${encodeURIComponent(String(ref))}/thumbnail?${params.toString()}`, { notifyError: false });
|
|
},
|
|
// #endregion getDashboardThumbnail
|
|
|
|
// #region getDatabaseMappings [C:2] [TYPE Function] [SEMANTICS dashboards,api,mappings,database]
|
|
// @BRIEF Fetch database mappings between source and target environments.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { src: source_env_id, tgt: target_env_id }
|
|
// @DATA_CONTRACT response -> { mappings: { source_db_uuid, target_db_uuid, source_db_name, target_db_name, confidence? }[] }
|
|
getDatabaseMappings: <T = unknown>(src: string, tgt: string) => fetchApi<T>(`/dashboards/db-mappings?source_env_id=${src}&target_env_id=${tgt}`),
|
|
// #endregion getDatabaseMappings
|
|
|
|
// #region calculateMigrationDryRun [C:2] [TYPE Function] [SEMANTICS migration,api,dry-run]
|
|
// @BRIEF POST dry-run calculation for dashboard migration preview.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT params -> { source_env_id, target_env_id, selected_dashboard_ids: number[], replace_db_config?, fix_cross_filters? }
|
|
// @DATA_CONTRACT response -> { diff: { dashboards, charts, datasets }, summary: { dashboards, charts, datasets }, risk: { score, level, items[] }, selected_dashboard_titles[] }
|
|
calculateMigrationDryRun: <T = unknown>(p: unknown) => postApi<T>('/migration/dry-run', p),
|
|
// #endregion calculateMigrationDryRun
|
|
|
|
// ═══ Datasets ═════════════════════════════════════════════════
|
|
|
|
// #region getDatasets [C:2] [TYPE Function] [SEMANTICS datasets,api,list,pagination]
|
|
// @BRIEF Fetch paginated datasets for an environment.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { env_id, search?, filter?, page?, page_size? }
|
|
// @DATA_CONTRACT response -> { datasets: { id, table_name, schema, database, mapped_fields?: { total, mapped }, metric_count?, last_task? }[], stats?: object, total: number, page: number, total_pages: number }
|
|
getDatasets: <T = unknown>(envId: string, opts: DatasetQueryOptions = {}) => {
|
|
const params = new URLSearchParams({ env_id: envId });
|
|
if (opts.search) params.append('search', opts.search);
|
|
if (opts.filter) params.append('filter', opts.filter);
|
|
if (opts.page) params.append('page', opts.page);
|
|
if (opts.page_size) params.append('page_size', opts.page_size);
|
|
return fetchApi<T>(`/datasets?${params.toString()}`);
|
|
},
|
|
// #endregion getDatasets
|
|
|
|
// #region getDatasetIds [C:2] [TYPE Function] [SEMANTICS datasets,api,ids,lookup]
|
|
// @BRIEF Fetch dataset IDs with optional search (lightweight lookup).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { env_id, search? }
|
|
// @DATA_CONTRACT response -> { ids: { id, table_name, schema, database }[] }
|
|
getDatasetIds: <T = unknown>(envId: string, opts: { search?: string } = {}) => {
|
|
const params = new URLSearchParams({ env_id: envId });
|
|
if (opts.search) params.append('search', opts.search);
|
|
return fetchApi<T>(`/datasets/ids?${params.toString()}`);
|
|
},
|
|
// #endregion getDatasetIds
|
|
|
|
// #region getDatasetDetail [C:2] [TYPE Function] [SEMANTICS datasets,api,detail]
|
|
// @BRIEF Fetch a single dataset detail with columns and metrics.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { env_id, datasetId }
|
|
// @DATA_CONTRACT response -> { id, table_name, schema, database, columns?: { name, type }[], metrics?: { name, expression }[], mapped_fields?: object }
|
|
getDatasetDetail: <T = unknown>(envId: string, datasetId: string) => fetchApi<T>(`/datasets/${datasetId}?env_id=${envId}`),
|
|
// #endregion getDatasetDetail
|
|
|
|
// ═══ Consolidated Settings ════════════════════════════════════
|
|
|
|
// #region getConsolidatedSettings [C:2] [TYPE Function] [SEMANTICS settings,api,consolidated,list]
|
|
// @BRIEF Fetch all settings in one consolidated response.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { environments, storage, logging, llm, migration, features, system }
|
|
getConsolidatedSettings: <T = unknown>() => fetchApi<T>('/settings/consolidated'),
|
|
// #endregion getConsolidatedSettings
|
|
|
|
// #region getAllowedLanguages [C:1] [TYPE Function] [SEMANTICS settings,api,languages,allowed]
|
|
// @BRIEF Fetch the list of allowed BCP-47 language codes (public, no auth required).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> string[]
|
|
getAllowedLanguages: () => fetchApi<string[]>('/settings/allowed-languages'),
|
|
// #endregion getAllowedLanguages
|
|
|
|
// #region updateConsolidatedSettings [C:2] [TYPE Function] [SEMANTICS settings,api,consolidated,update]
|
|
// @BRIEF Update consolidated settings (PATCH).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
// @DATA_CONTRACT params -> { environments?, storage?, logging?, llm?, migration?, features?, system? }
|
|
// @DATA_CONTRACT response -> { success: boolean }
|
|
updateConsolidatedSettings: <T = unknown>(s: unknown) => requestApi<T>('/settings/consolidated', 'PATCH', s),
|
|
// #endregion updateConsolidatedSettings
|
|
|
|
// ═══ Connections ═══════════════════════════════════════════════
|
|
|
|
// #region fetchConnections [C:1] [TYPE Function] [SEMANTICS settings,api,connections,list]
|
|
// @BRIEF Fetch all database connections with masked passwords.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> [{ id, name, host, port, database, username, dialect, pool_size, extra_params, created_at, updated_at, used_by }]
|
|
fetchConnections: <T = unknown>() => fetchApi<T>('/settings/connections'),
|
|
// #endregion fetchConnections
|
|
|
|
// #region getConnection [C:1] [TYPE Function] [SEMANTICS settings,api,connections,get]
|
|
// @BRIEF Fetch a single database connection by ID.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
getConnection: <T = unknown>(id: string) => fetchApi<T>(`/settings/connections/${id}`),
|
|
// #endregion getConnection
|
|
|
|
// #region createConnection [C:1] [TYPE Function] [SEMANTICS settings,api,connections,create]
|
|
// @BRIEF Create a new database connection.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT body -> { name, host, port, database, username, password, dialect, extra_params?, pool_size? }
|
|
// @DATA_CONTRACT response -> { id, name, host, port, database, username, dialect, ... } (password masked)
|
|
createConnection: <T = unknown>(data: unknown) => postApi<T>('/settings/connections', data),
|
|
// #endregion createConnection
|
|
|
|
// #region updateConnection [C:1] [TYPE Function] [SEMANTICS settings,api,connections,update]
|
|
// @BRIEF Update a database connection by ID. Empty/masked password = keep existing.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
updateConnection: <T = unknown>(id: string, data: unknown) => requestApi<T>(`/settings/connections/${id}`, 'PUT', data),
|
|
// #endregion updateConnection
|
|
|
|
// #region deleteConnection [C:1] [TYPE Function] [SEMANTICS settings,api,connections,delete]
|
|
// @BRIEF Delete a database connection by ID. Blocked if referenced by active jobs.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
// @DATA_CONTRACT response -> { message: "Connection deleted" } or 409 { detail: { blocking_jobs: string[] } }
|
|
deleteConnection: <T = unknown>(id: string) => requestApi<T>(`/settings/connections/${id}`, 'DELETE'),
|
|
// #endregion deleteConnection
|
|
|
|
// #region testConnection [C:1] [TYPE Function] [SEMANTICS settings,api,connections,test]
|
|
// @BRIEF Test connectivity to a database connection. Runs SELECT 1.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT response -> { success: bool, latency_ms?: int, db_version?: string, error?: string }
|
|
testConnection: <T = unknown>(id: string) => postApi<T>(`/settings/connections/${id}/test`, {}),
|
|
// #endregion testConnection
|
|
|
|
// ═══ Automation ═══════════════════════════════════════════════
|
|
|
|
// #region getValidationPolicies [C:2] [TYPE Function] [SEMANTICS automation,api,policies,list]
|
|
// @BRIEF Fetch all validation automation policies.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { policies: { id, name, is_active, schedule?, environment_id, dashboard_ids?, task_type? }[] }
|
|
getValidationPolicies: <T = unknown>() => fetchApi<T>('/settings/automation/policies'),
|
|
// #endregion getValidationPolicies
|
|
|
|
// #region createValidationPolicy [C:2] [TYPE Function] [SEMANTICS automation,api,policies,create]
|
|
// @BRIEF Create a new validation automation policy.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
createValidationPolicy: <T = unknown>(p: unknown) => postApi<T>('/settings/automation/policies', p),
|
|
// #endregion createValidationPolicy
|
|
|
|
// #region updateValidationPolicy [C:2] [TYPE Function] [SEMANTICS automation,api,policies,update]
|
|
// @BRIEF Update a validation policy by ID (PATCH).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
updateValidationPolicy: <T = unknown>(id: string, p: unknown) => requestApi<T>(`/settings/automation/policies/${id}`, 'PATCH', p),
|
|
// #endregion updateValidationPolicy
|
|
|
|
// #region deleteValidationPolicy [C:2] [TYPE Function] [SEMANTICS automation,api,policies,delete]
|
|
// @BRIEF Delete a validation policy by ID.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
deleteValidationPolicy: <T = unknown>(id: string) => requestApi<T>(`/settings/automation/policies/${id}`, 'DELETE'),
|
|
// #endregion deleteValidationPolicy
|
|
|
|
// #region getTranslationSchedules [C:2] [TYPE Function] [SEMANTICS automation,api,translation,schedules]
|
|
// @BRIEF Fetch all translation automation schedules.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { schedules: { id, name, config_id?, cron_expression?, is_active }[] }
|
|
getTranslationSchedules: <T = unknown>() => fetchApi<T>('/settings/automation/translation-schedules'),
|
|
// #endregion getTranslationSchedules
|
|
|
|
// ═══ Health ═══════════════════════════════════════════════════
|
|
|
|
// #region getHealthSummary [C:2] [TYPE Function] [SEMANTICS health,api,summary]
|
|
// @BRIEF Fetch dashboard health summary, optionally scoped to environment.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { environmentId? }
|
|
// @DATA_CONTRACT response -> { summary: { total_dashboards, failing_dashboards, total_datasets, environments }[], items?: { dashboard_id, dashboard_slug, title, last_validation_status, last_validation_run_at, failing_count }[] }
|
|
getHealthSummary: <T = unknown>(environmentId?: string) => {
|
|
const query = environmentId ? `?env_id=${encodeURIComponent(environmentId)}` : '';
|
|
return fetchApi<T>(`/health/summary${query}`, { suppressToast: true });
|
|
},
|
|
// #endregion getHealthSummary
|
|
|
|
// ═══ LLM Providers ════════════════════════════════════════════
|
|
|
|
// #region getLlmProviders [C:2] [TYPE Function] [SEMANTICS llm,api,providers,list]
|
|
// @BRIEF Fetch all configured LLM providers.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { providers: { id, name, type, status }[] }
|
|
getLlmProviders: <T = unknown>() => fetchApi<T>('/llm/providers'),
|
|
// #endregion getLlmProviders
|
|
|
|
// ═══ Validation Tasks ═════════════════════════════════════════
|
|
|
|
// #region parseValidationUrl [C:2] [TYPE Function] [SEMANTICS validation,api,url,parse]
|
|
// @BRIEF Parse a Superset dashboard URL into validation task params.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT params -> { url, environment_id }
|
|
// @DATA_CONTRACT response -> { dashboard_id, title?, environment_id, charts?[] }
|
|
parseValidationUrl: <T = unknown>(url: string, envId: string) => postApi<T>('/validation-tasks/parse-url', { url, environment_id: envId }),
|
|
// #endregion parseValidationUrl
|
|
|
|
// #region getValidationTasks [C:2] [TYPE Function] [SEMANTICS validation,api,tasks,list,pagination]
|
|
// @BRIEF Fetch paginated validation tasks with status/environment/search filters.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { page?, page_size?, is_active?, environment_id?, search? }
|
|
// @DATA_CONTRACT response -> { tasks: { id, name, environment_id, is_active, schedule?, last_run_at?, last_run_status?, dashboard_ids? }[], total: number, page: number, page_size: number }
|
|
getValidationTasks: <T = unknown>(params: ValidationTaskQueryParams = {}) => {
|
|
const qs = new URLSearchParams();
|
|
if (params.page != null) qs.append('page', String(params.page));
|
|
if (params.page_size != null) qs.append('page_size', String(params.page_size));
|
|
if (params.is_active != null) qs.append('is_active', String(Boolean(params.is_active)));
|
|
if (params.environment_id) qs.append('environment_id', params.environment_id);
|
|
if (params.search) qs.append('search', params.search);
|
|
const query = qs.toString();
|
|
return fetchApi<T>(`/validation-tasks${query ? `?${query}` : ''}`);
|
|
},
|
|
// #endregion getValidationTasks
|
|
|
|
// #region createValidationTask [C:2] [TYPE Function] [SEMANTICS validation,api,tasks,create]
|
|
// @BRIEF Create a new validation task with schedule and dashboard scope.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT params -> { name, environment_id, dashboard_ids: number[], schedule?, llm_provider?, validation_type? }
|
|
// @DATA_CONTRACT response -> { id, name }
|
|
createValidationTask: <T = unknown>(data: unknown) => postApi<T>('/validation-tasks', data),
|
|
// #endregion createValidationTask
|
|
|
|
// #region getValidationTask [C:2] [TYPE Function] [SEMANTICS validation,api,tasks,detail]
|
|
// @BRIEF Fetch a single validation task by ID with full config.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { id }
|
|
// @DATA_CONTRACT response -> { id, name, environment_id, is_active, schedule?, params?, dashboard_ids?, last_run?, runs_count? }
|
|
getValidationTask: <T = unknown>(id: string) => fetchApi<T>(`/validation-tasks/${id}`),
|
|
// #endregion getValidationTask
|
|
|
|
// #region updateValidationTask [C:2] [TYPE Function] [SEMANTICS validation,api,tasks,update]
|
|
// @BRIEF Update a validation task by ID (PUT).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
updateValidationTask: <T = unknown>(id: string, data: unknown) => requestApi<T>(`/validation-tasks/${id}`, 'PUT', data),
|
|
// #endregion updateValidationTask
|
|
|
|
// #region deleteValidationTask [C:2] [TYPE Function] [SEMANTICS validation,api,tasks,delete]
|
|
// @BRIEF Delete a validation task and optionally its runs.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [deleteApi]
|
|
// @DATA_CONTRACT params -> { id, deleteRuns?: boolean }
|
|
deleteValidationTask: <T = unknown>(id: string, deleteRuns: boolean = true) => {
|
|
const qs = deleteRuns ? '?delete_runs=true' : '';
|
|
return deleteApi<T>(`/validation-tasks/${id}${qs}`);
|
|
},
|
|
// #endregion deleteValidationTask
|
|
|
|
// #region triggerValidationRun [C:2] [TYPE Function] [SEMANTICS validation,api,run,trigger]
|
|
// @BRIEF Trigger a new validation run for a task.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT params -> { id: policy_id }
|
|
// @DATA_CONTRACT response -> { run_id: string, status: string }
|
|
triggerValidationRun: <T = unknown>(id: string) => postApi<T>(`/validation-tasks/${id}/run`, {}),
|
|
// #endregion triggerValidationRun
|
|
|
|
// #region toggleValidationTaskStatus [C:2] [TYPE Function] [SEMANTICS validation,api,tasks,toggle]
|
|
// @BRIEF Toggle active/inactive status of a validation task (PATCH).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
// @DATA_CONTRACT params -> { id, isActive: boolean }
|
|
toggleValidationTaskStatus: <T = unknown>(id: string, isActive: boolean) => requestApi<T>(`/validation-tasks/${id}/status`, 'PATCH', { is_active: isActive }),
|
|
// #endregion toggleValidationTaskStatus
|
|
|
|
// #region getValidationRuns [C:2] [TYPE Function] [SEMANTICS validation,api,runs,list,pagination]
|
|
// @BRIEF Fetch paginated validation runs for a task.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { taskId, page?, page_size? }
|
|
// @DATA_CONTRACT response -> { runs: { id, status, started_at, completed_at, summary?, error? }[], total: number, page: number }
|
|
getValidationRuns: <T = unknown>(taskId: string, params: ValidationRunQueryParams = {}) => {
|
|
const qs = new URLSearchParams();
|
|
if (params.page != null) qs.append('page', String(params.page));
|
|
if (params.page_size != null) qs.append('page_size', String(params.page_size));
|
|
const query = qs.toString();
|
|
return fetchApi<T>(`/validation-tasks/${taskId}/runs${query ? `?${query}` : ''}`);
|
|
},
|
|
// #endregion getValidationRuns
|
|
|
|
// #region getValidationRunDetail [C:2] [TYPE Function] [SEMANTICS validation,api,runs,detail]
|
|
// @BRIEF Fetch a single validation run detail with results and logs.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { taskId, runId }
|
|
// @DATA_CONTRACT response -> { id, task_id, status, started_at, completed_at, result?: { items?: { dashboard_id, dashboard_title, chart_id?, status, issues? }[] }, error?, logs? }
|
|
getValidationRunDetail: <T = unknown>(taskId: string, runId: string) => fetchApi<T>(`/validation-tasks/${taskId}/runs/${runId}`),
|
|
// #endregion getValidationRunDetail
|
|
|
|
// #region getValidationStatusBatch [C:2] [TYPE Function] [SEMANTICS validation,api,status,batch]
|
|
// @BRIEF Batch-fetch latest validation status for multiple dashboard IDs.
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT params -> { env_id, dashboard_ids: comma-separated string }
|
|
// @DATA_CONTRACT response -> { [dashboard_id]: { status: PASS|FAIL|WARN, last_run_at?, task_name?, run_id?, history?: { status, last_run_at, task_name }[] } }
|
|
getValidationStatusBatch: <T = unknown>(envId: string, dashboardIds: string) =>
|
|
fetchApi<T>(`/validation-tasks/status/batch?env_id=${encodeURIComponent(envId)}&dashboard_ids=${encodeURIComponent(dashboardIds)}`),
|
|
// #endregion getValidationStatusBatch
|
|
|
|
// ═══ API Keys ═════════════════════════════════════════════════
|
|
|
|
// #region listApiKeys [C:2] [TYPE Function] [SEMANTICS admin,api,api-keys,list]
|
|
// @BRIEF List all API keys (admin only).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [fetchApi]
|
|
// @DATA_CONTRACT response -> { api_keys: { id, name, key_prefix, created_at, last_used_at?, is_active }[] }
|
|
listApiKeys: <T = unknown>() => fetchApi<T>('/admin/api-keys/'),
|
|
// #endregion listApiKeys
|
|
|
|
// #region createApiKey [C:2] [TYPE Function] [SEMANTICS admin,api,api-keys,create]
|
|
// @BRIEF Create a new API key, returns the secret once (admin only).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [postApi]
|
|
// @DATA_CONTRACT params -> { name, scopes?[] }
|
|
// @DATA_CONTRACT response -> { id, name, key: string, key_prefix, created_at }
|
|
createApiKey: <T = unknown>(payload: unknown) => postApi<T>('/admin/api-keys/', payload, { suppressToast: true }),
|
|
// #endregion createApiKey
|
|
|
|
// #region revokeApiKey [C:2] [TYPE Function] [SEMANTICS admin,api,api-keys,delete]
|
|
// @BRIEF Revoke an API key (admin only).
|
|
// @LAYER API
|
|
// @RELATION DEPENDS_ON -> [requestApi]
|
|
revokeApiKey: <T = unknown>(keyId: string) => requestApi<T>(`/admin/api-keys/${keyId}`, 'DELETE'),
|
|
// #endregion revokeApiKey
|
|
|
|
// #region getEncryptionHealth [C:2] [TYPE Function] [SEMANTICS security,encryption,health]
|
|
// @BRIEF Inventory all stored encrypted secrets and report broken ones.
|
|
getEncryptionHealth: <T = unknown>() => fetchApi<T>('/security/encryption/health'),
|
|
// #endregion getEncryptionHealth
|
|
|
|
// #region recoverEncryptedSecrets [C:2] [TYPE Function] [SEMANTICS security,encryption,recover]
|
|
// @BRIEF Submit replacement secrets for items that could not be decrypted.
|
|
recoverEncryptedSecrets: <T = unknown>(payload: unknown) => postApi<T>('/security/encryption/recover', payload),
|
|
// #endregion recoverEncryptedSecrets
|
|
};
|
|
// #endregion ApiRegistry
|
|
// #endregion ApiModule
|
|
|
|
export { fetchApi, fetchApiBlob, postApi, deleteApi, requestApi, uploadFile };
|
|
export const getPlugins = api.getPlugins;
|
|
export const getTasks = api.getTasks;
|
|
export const getTask = api.getTask;
|
|
export const createTask = api.createTask;
|
|
export const getProfilePreferences = api.getProfilePreferences;
|
|
export const updateProfilePreferences = api.updateProfilePreferences;
|
|
export const lookupSupersetAccounts = api.lookupSupersetAccounts;
|
|
export const getSettings = api.getSettings;
|
|
export const updateGlobalSettings = api.updateGlobalSettings;
|
|
export const getEnvironments = api.getEnvironments;
|
|
export const addEnvironment = api.addEnvironment;
|
|
export const updateEnvironment = api.updateEnvironment;
|
|
export const deleteEnvironment = api.deleteEnvironment;
|
|
export const testEnvironmentConnection = api.testEnvironmentConnection;
|
|
export const updateEnvironmentSchedule = api.updateEnvironmentSchedule;
|
|
export const getEnvironmentsList = api.getEnvironmentsList;
|
|
export const getStorageSettings = api.getStorageSettings;
|
|
export const updateStorageSettings = api.updateStorageSettings;
|
|
export const getDashboards = api.getDashboards;
|
|
export const getDatasets = api.getDatasets;
|
|
export const getConsolidatedSettings = api.getConsolidatedSettings;
|
|
export const getAllowedLanguages = api.getAllowedLanguages;
|
|
export const updateConsolidatedSettings = api.updateConsolidatedSettings;
|
|
export const getValidationPolicies = api.getValidationPolicies;
|
|
export const createValidationPolicy = api.createValidationPolicy;
|
|
export const updateValidationPolicy = api.updateValidationPolicy;
|
|
export const deleteValidationPolicy = api.deleteValidationPolicy;
|
|
export const getTranslationSchedules = api.getTranslationSchedules;
|
|
export const getHealthSummary = api.getHealthSummary;
|
|
export const getValidationTasks = api.getValidationTasks;
|
|
export const getValidationTask = api.getValidationTask;
|
|
export const createValidationTask = api.createValidationTask;
|
|
export const updateValidationTask = api.updateValidationTask;
|
|
export const deleteValidationTask = api.deleteValidationTask;
|
|
export const triggerValidationRun = api.triggerValidationRun;
|
|
export const toggleValidationTaskStatus = api.toggleValidationTaskStatus;
|
|
export const getValidationRuns = api.getValidationRuns;
|
|
export const getValidationRunDetail = api.getValidationRunDetail;
|
|
export const fetchConnections = api.fetchConnections;
|
|
export const getConnection = api.getConnection;
|
|
export const createConnection = api.createConnection;
|
|
export const updateConnection = api.updateConnection;
|
|
export const deleteConnection = api.deleteConnection;
|
|
export const testConnection = api.testConnection;
|
|
export const getEncryptionHealth = api.getEncryptionHealth;
|
|
export const recoverEncryptedSecrets = api.recoverEncryptedSecrets;
|