/**
 * Standardized API response envelope types.
 *
 * These wrappers mirror the backend response envelope contract defined in
 * `backend/app/models/response.py`.
 */

export interface CollectionResponse<T> {
  /** Data items in the collection. */
  items: T[];
  /** Total number of items in the collection. */
  total: number;
}

export interface PaginatedListResponse<T> extends CollectionResponse<T> {
  /** Current page number (1-based). */
  page: number;
  /** Number of items per page. */
  page_size: number;
  /** Total number of pages (only for offset pagination; -1 for cursor). */
  total_pages: number;
  /** Pagination mode discriminator: 'offset' or 'cursor'. */
  pagination_mode: "offset" | "cursor";
}

export interface CommandResponse {
  /** Human-readable result message. */
  message: string;
  /** Whether the command succeeded. */
  success: boolean;
}

export interface ErrorResponse {
  /** Machine-readable error code for client-side branching (e.g., "jail_not_found", "rate_limit_exceeded"). */
  code: string;
  /** Human-readable error description for display to users. */
  detail: string;
  /** Optional structured context for the error (field names, constraint violations, etc.). */
  metadata: Record<string, string | number | boolean | null | undefined>;
  /** Unique ID for correlating this error with request logs on both frontend and backend. */
  correlation_id?: string;
}

/**
 * Standardized health check response.
 * Mirrors `backend/app/models/response.py:HealthResponse`.
 */
export interface HealthResponse {
  /** Application health status: 'ok' when healthy, 'unavailable' otherwise. */
  status: "ok" | "unavailable";
  /** fail2ban daemon status: 'online' when reachable, 'offline' otherwise. */
  fail2ban: "online" | "offline";
}

/**
 * Standardized flush-logs command response.
 * Mirrors `backend/app/models/response.py:FlushLogsResponse`.
 */
export interface FlushLogsResponse {
  /** Human-readable result message from fail2ban. */
  message: string;
}
