tubearr/src/types/api.ts

// ── API Response Envelopes ──

/** Standard API response wrapper. */
export interface ApiResponse<T> {
  success: boolean;
  data: T;
}

/** Standard API error shape. */
export interface ApiError {
  error: string;
  statusCode: number;
  message: string;
  stack?: string; // included only in development
}

/** Paginated API response wrapper. */
export interface PaginatedResponse<T> {
  success: boolean;
  data: T[];
  pagination: {
    page: number;
    pageSize: number;
    totalItems: number;
    totalPages: number;
  };
}

// ── Endpoint-Specific Responses ──

export interface ComponentHealth {
  name: string;
  status: 'healthy' | 'degraded' | 'unhealthy';
  message?: string;
  responseTime?: number; // ms
  details?: Record<string, unknown>;
}

export interface HealthResponse {
  status: 'healthy' | 'degraded' | 'unhealthy';
  components: ComponentHealth[];
  uptime: number; // seconds
}

export interface SystemStatusResponse {
  appName: string;
  version: string;
  uptime: number; // seconds
  nodeVersion: string;
  platform: string;
  arch: string;
  memoryUsage: {
    heapUsed: number;
    heapTotal: number;
    rss: number;
  };
}

/** Response shape for API key management endpoints. */
export interface ApiKeyResponse {
  apiKey: string;
}

// ── Channel Content Counts ──

/** Aggregated content counts for a single channel. */
export interface ContentCounts {
  total: number;
  monitored: number;
  downloaded: number;
}

/** App-wide settings (check interval, concurrent downloads). */
export interface AppSettingsResponse {
  checkInterval: number;
  concurrentDownloads: number;
}

/** Channel with aggregated content counts — returned by GET /api/v1/channel. */
export type ChannelWithCounts = import('./index').Channel & {
  contentCounts: ContentCounts;
};

// ── yt-dlp Status ──

/** Response shape for GET /api/v1/system/ytdlp/status. */
export interface YtDlpStatusResponse {
  version: string | null;
  lastUpdated: string | null;
}

/** Response shape for POST /api/v1/system/ytdlp/update. */
export interface YtDlpUpdateResponse {
  updated: boolean;
  version: string | null;
  previousVersion: string | null;
  lastUpdated: string;
}