dashcaddy/sdks/js/types.d.ts

/**
 * DashCaddy API — TypeScript type definitions
 *
 * Generated from the DashCaddy OpenAPI spec (openapi.yaml, v1.15.0).
 * These interfaces model the main resource types returned by the API.
 *
 * Response envelope:
 *   Success: { success: true, ...data }
 *   Error:   { success: false, error: string, code?: string }
 */

// ── Response Envelope ──────────────────────────────────────────

/** Standard success envelope returned by all DashCaddy endpoints. */
export interface SuccessResponse<T = Record<string, unknown>> {
  success: true;
  /** Endpoint-specific payload fields (spread at top level). */
  data?: T;
  [key: string]: unknown;
}

/** Standard error envelope. */
export interface ErrorResponse {
  success: false;
  /** Human-readable error message (may include a DC error code). */
  error: string;
  /** Machine-readable error code, e.g. 'DC-CONT-002'. */
  code?: string;
  /** Extra context — e.g. { requiresTotp: true }. */
  [key: string]: unknown;
}

/** Union type for any API response. */
export type ApiResponse<T = Record<string, unknown>> = SuccessResponse<T> | ErrorResponse;

// ── Service ────────────────────────────────────────────────────

/** A dashboard service registration (from services.json). */
export interface Service {
  /** Unique service identifier. */
  id: string;
  /** Display name shown on the dashboard. */
  name: string;
  /** Service URL (full or relative, resolved via site config). */
  url: string;
  /** Icon path or URL. */
  icon?: string;
  /** Category for grouping. */
  category?: string;
  /** Whether health checking is enabled for this service. */
  healthCheck?: boolean;
  /** Subdomain mapping (optional). */
  subdomain?: string;
  /** Description (optional). */
  description?: string;
}

/** Aggregated status entry for a single service probe. */
export interface ServiceStatus {
  id: string;
  isUp: boolean;
  statusCode: number;
  responseTime: number;
  url?: string;
  error?: string;
  via?: string;
}

// ── Container ──────────────────────────────────────────────────

/** A discovered Docker container (sami.managed). */
export interface Container {
  /** Container ID (Docker). */
  id: string;
  /** Container name (leading '/' stripped). */
  name: string;
  /** Image name and tag. */
  image: string;
  /** Docker state: running, exited, etc. */
  state: string;
  /** Human-readable status string from Docker. */
  status: string;
  /** App template name if deployed via DashCaddy. */
  appTemplate?: string;
  /** Subdomain if configured. */
  subdomain?: string;
  /** Port mappings. */
  ports?: ContainerPort[];
}

/** Port mapping for a container. */
export interface ContainerPort {
  IP?: string;
  PrivatePort?: number;
  PublicPort?: number;
  Type?: string;
}

/** Resource usage stats for a container. */
export interface ContainerStats {
  id: string;
  name: string;
  cpuPercent: number;
  memoryUsage: number;
  memoryLimit: number;
  memoryPercent: number;
  networkRx: number;
  networkTx: number;
  blockRead: number;
  blockWrite: number;
}

// ── Health ─────────────────────────────────────────────────────

/** Health status for a single monitored service. */
export interface HealthStatus {
  /** 'healthy' | 'unhealthy' | 'down' | 'unknown' | 'timeout' */
  status: string;
  /** HTTP status code if probed. */
  statusCode?: number;
  /** Response time in milliseconds. */
  responseTime?: number;
  /** Reason for the status (e.g. error message). */
  reason?: string;
}

/** Liveness / readiness probe result. */
export interface HealthProbeResult {
  status: 'ok' | 'error';
  uptime?: number;
  message?: string;
  checks?: Record<string, boolean>;
}

// ── DNS ────────────────────────────────────────────────────────

/** A DNS record (universal — Technitium, Cloudflare, etc.). */
export interface DNSRecord {
  /** Record type: A, AAAA, CNAME, MX, TXT, etc. */
  type: string;
  /** Domain / zone name. */
  domain: string;
  /** Record value / target. */
  value?: string;
  /** TTL in seconds. */
  ttl?: number;
  /** Priority (for MX/SRV). */
  priority?: number;
  /** Port (for SRV). */
  port?: number;
  /** Whether the record is enabled. */
  enabled?: boolean;
}

/** DNS provider information. */
export interface DNSProvider {
  id: string;
  name: string;
  type: string;
  configured: boolean;
}

// ── Backup ─────────────────────────────────────────────────────

/** Backup system configuration. */
export interface BackupConfig {
  /** List of per-app backup schedules. */
  backups?: BackupSchedule[];
  /** Default retention count. */
  defaultRetention?: number;
}

/** A single app's backup schedule entry. */
export interface BackupSchedule {
  appId: string;
  enabled: boolean;
  schedule: string;
  retention: number;
}

/** A backup history entry. */
export interface BackupHistoryEntry {
  id: string;
  appId: string;
  timestamp: string;
  status: string;
  size?: number;
  file?: string;
}

// ── Config ─────────────────────────────────────────────────────

/** DashCaddy site configuration. */
export interface SiteConfig {
  title?: string;
  theme?: 'light' | 'dark' | 'auto';
  logo?: string;
  favicon?: string;
  customCss?: string;
  dnsServers?: Record<string, unknown>;
  pylon?: { url?: string; key?: string };
  [key: string]: unknown;
}

// ── Monitoring ─────────────────────────────────────────────────

/** Aggregated monitoring stats for all containers. */
export interface MonitoringStats {
  [containerId: string]: {
    name: string;
    cpu: number;
    memory: number;
    memoryUsage: number;
  };
}

/** Alert configuration for resource monitoring. */
export interface AlertConfig {
  cpuThreshold?: number;
  memoryThreshold?: number;
  enabled?: boolean;
  [key: string]: unknown;
}

// ── Client Options ─────────────────────────────────────────────

/** Options for constructing a DashCaddyClient. */
export interface DashCaddyClientOptions {
  /** Base URL, e.g. 'https://status.sami'. */
  baseUrl: string;
  /** API key in format dk_<id>_<secret>. Bypasses CSRF. */
  apiKey?: string;
  /** Session cookie value for cookie-based auth. */
  sessionCookie?: string;
  /** CSRF token (auto-fetched if not provided and not using API key). */
  csrfToken?: string;
  /** Request timeout in ms (default 30000). */
  timeout?: number;
  /** Max retry attempts on 5xx (default 3). */
  maxRetries?: number;
  /** Extra headers to send with every request. */
  headers?: Record<string, string>;
  /** Custom fetch implementation (default global fetch). */
  fetch?: typeof fetch;
}