[grade=A] DC-068: Fix all 3 ESLint errors + auto-fix warnings

- Removed orphaned __trace2.js (unnecessary escape error) - Fixed empty block statement in config-migrations.test.js busy-wait - Fixed empty block statement in metrics.test.js busy-wait - Auto-fixed 5 fixable warnings via eslint --fix - Remaining 547 warnings (require-await, no-unused-vars) are non-blocking code quality - 0 errors, 1633 tests pass
2026-08-12 12:35:58 -07:00
parent ccaa923a5a
commit 6b3f6ebeb6
10 changed files with 1850 additions and 9 deletions
@@ -0,0 +1,750 @@
+/**
+ * DashCaddy JavaScript Client — lightweight SDK for the DashCaddy API.
+ *
+ * Zero external dependencies. Works in Node.js 18+ (uses global fetch).
+ *
+ * @example
+ * const { DashCaddyClient } = require('./dashcaddy-client');
+ *
+ * // API key auth (simplest — no CSRF needed)
+ * const client = new DashCaddyClient({
+ *   baseUrl: 'https://status.sami',
+ *   apiKey: 'dk_abc123_xyz'
+ * });
+ *
+ * // Session cookie auth (CSRF handled automatically)
+ * const client2 = new DashCaddyClient({
+ *   baseUrl: 'https://status.sami',
+ *   sessionCookie: 'sid=...'
+ * });
+ *
+ * // List services
+ * const services = await client.services.list();
+ *
+ * // Get health status
+ * const health = await client.health.get();
+ *
+ * // Discover containers
+ * const { containers } = await client.containers.discover();
+ *
+ * // Create a DNS record
+ * await client.dns.createRecord({ type: 'A', domain: 'app.sami', value: '10.0.0.1' });
+ *
+ * // Run an immediate backup
+ * const { backup } = await client.backups.execute();
+ *
+ * @license MIT
+ */
+
+'use strict';
+
+// ── Constants ──────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_MAX_RETRIES = 3;
+const RETRY_BACKOFF_BASE_MS = 500;
+const API_PREFIX = '/api/v1';
+const HEALTH_PREFIX = '';
+const CSRF_PATH = API_PREFIX + '/csrf-token';
+const CSRF_HEADER_NAME = 'x-csrf-token';
+const API_KEY_HEADER = 'x-api-key';
+
+// ── Error Class ────────────────────────────────────────────────
+
+/**
+ * Error thrown when the API returns a non-success response or a network
+ * error occurs after all retries are exhausted.
+ */
+class DashCaddyError extends Error {
+  /**
+   * @param {string} message - Error message.
+   * @param {number} [statusCode] - HTTP status code.
+   * @param {string} [code] - Machine-readable error code from the API.
+   * @param {Record<string, unknown>} [details] - Full error response body.
+   */
+  constructor(message, statusCode, code, details) {
+    super(message);
+    this.name = 'DashCaddyError';
+    this.statusCode = statusCode || 0;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+// ── Internal HTTP Request Helper ───────────────────────────────
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.url
+ * @param {string} opts.method
+ * @param {Record<string, string>} [opts.headers]
+ * @param {unknown} [opts.body]
+ * @param {number} [opts.timeout]
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @param {AbortSignal} [opts.signal]
+ * @returns {Promise<Response>}
+ */
+async function rawRequest({ url, method, headers, body, timeout, fetchImpl, signal }) {
+  const fetchFn = fetchImpl || fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout || DEFAULT_TIMEOUT);
+
+  // Link external signal if provided
+  if (signal) {
+    if (signal.aborted) controller.abort();
+    else signal.addEventListener('abort', () => controller.abort(), { once: true });
+  }
+
+  try {
+    const res = await fetchFn(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    });
+    return res;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── Resource Mixins ────────────────────────────────────────────
+
+// Each resource namespace is created as a plain object with methods bound
+// to the client instance. This keeps the class lean while providing
+// structured access: client.services.list(), client.health.get(), etc.
+
+/**
+ * @param {DashCaddyClient} client
+ * @returns {Object}
+ */
+function createServicesResource(client) {
+  return {
+    /** List all registered services. GET /api/v1/services */
+    async list() {
+      const res = await client._request('GET', '/services');
+      return res;
+    },
+
+    /**
+     * Get aggregated status for all services. GET /api/v1/services/status
+     * @returns {Promise<{ success: boolean, checkedAt?: string, partial?: boolean, statuses?: Record<string, ServiceStatus> }>}
+     */
+    async status() {
+      return client._request('GET', '/services/status');
+    },
+
+    /**
+     * Create a new service. POST /api/v1/services
+     * @param {object} service - Service definition.
+     */
+    async create(service) {
+      return client._request('POST', '/services', { body: service });
+    },
+
+    /**
+     * Update services (bulk replace). PUT /api/v1/services
+     * @param {object[]} services - Full services array.
+     */
+    async updateAll(services) {
+      return client._request('PUT', '/services', { body: services });
+    },
+
+    /**
+     * Delete a service by ID. DELETE /api/v1/services/:id
+     * @param {string} id - Service ID.
+     */
+    async delete(id) {
+      return client._request('DELETE', `/services/${encodeURIComponent(id)}`);
+    },
+
+    /**
+     * Trigger a services update check/apply. POST /api/v1/services/update
+     * @param {object} [opts] - Update options.
+     */
+    async triggerUpdate(opts) {
+      return client._request('POST', '/services/update', { body: opts || {} });
+    },
+  };
+}
+
+/**
+ * @param {DashCaddyClient} client
+ * @returns {Object}
+ */
+function createContainersResource(client) {
+  return {
+    /** Discover all Docker containers. GET /api/v1/containers/discover */
+    async discover() {
+      return client._request('GET', '/containers/discover');
+    },
+
+    /**
+     * Get logs for a container. GET /api/v1/containers/:id/logs
+     * @param {string} id - Container ID.
+     */
+    async logs(id) {
+      return client._request('GET', `/containers/${encodeURIComponent(id)}/logs`);
+    },
+
+    /**
+     * Get resource limits for a container. GET /api/v1/containers/:id/resources
+     * @param {string} id - Container ID.
+     */
+    async resources(id) {
+      return client._request('GET', `/containers/${encodeURIComponent(id)}/resources`);
+    },
+
+    /**
+     * Check if a container image update is available.
+     * GET /api/v1/containers/:id/check-update
+     * @param {string} id - Container ID.
+     */
+    async checkUpdate(id) {
+      return client._request('GET', `/containers/${encodeURIComponent(id)}/check-update`);
+    },
+
+    /** Start a container. POST /api/v1/containers/:id/start */
+    async start(id) {
+      return client._request('POST', `/containers/${encodeURIComponent(id)}/start`, { body: {} });
+    },
+
+    /** Stop a container. POST /api/v1/containers/:id/stop */
+    async stop(id) {
+      return client._request('POST', `/containers/${encodeURIComponent(id)}/stop`, { body: {} });
+    },
+
+    /** Restart a container. POST /api/v1/containers/:id/restart */
+    async restart(id) {
+      return client._request('POST', `/containers/${encodeURIComponent(id)}/restart`, { body: {} });
+    },
+
+    /**
+     * Update a container image. POST /api/v1/containers/:id/update
+     * @param {string} id - Container ID.
+     * @param {object} [opts] - Update options.
+     */
+    async update(id, opts) {
+      return client._request('POST', `/containers/${encodeURIComponent(id)}/update`, { body: opts || {} });
+    },
+
+    /** Remove a container. DELETE /api/v1/containers/:id */
+    async remove(id) {
+      return client._request('DELETE', `/containers/${encodeURIComponent(id)}`);
+    },
+  };
+}
+
+/**
+ * @param {DashCaddyClient} client
+ * @returns {Object}
+ */
+function createHealthResource(client) {
+  return {
+    /** Liveness check (root-level). GET /health */
+    async get() {
+      return client._request('GET', '/health', { root: true });
+    },
+
+    /** Liveness probe. GET /health/live */
+    async live() {
+      return client._request('GET', '/health/live', { root: true });
+    },
+
+    /** Readiness probe. GET /health/ready */
+    async ready() {
+      return client._request('GET', '/health/ready', { root: true });
+    },
+
+    /** Health status for all services. GET /api/v1/health/services */
+    async services() {
+      return client._request('GET', '/health/services');
+    },
+
+    /** Cached health (no re-probe). GET /api/v1/health/cached */
+    async cached() {
+      return client._request('GET', '/health/cached');
+    },
+
+    /**
+     * Health for a specific service. GET /api/v1/health/service/:id
+     * @param {string} id - Service ID.
+     */
+    async service(id) {
+      return client._request('GET', `/health/service/${encodeURIComponent(id)}`);
+    },
+
+    /** CA certificate health. GET /api/v1/health/ca */
+    async ca() {
+      return client._request('GET', '/health/ca');
+    },
+  };
+}
+
+/**
+ * @param {DashCaddyClient} client
+ * @returns {Object}
+ */
+function createDnsResource(client) {
+  return {
+    /** List DNS providers. GET /api/v1/dns/providers */
+    async providers() {
+      return client._request('GET', '/dns/providers');
+    },
+
+    /** DNS provider status. GET /api/v1/dns/provider/status */
+    async providerStatus() {
+      return client._request('GET', '/dns/provider/status');
+    },
+
+    /**
+     * Create a DNS record. POST /api/v1/dns/record
+     * @param {object} record - DNS record definition.
+     */
+    async createRecord(record) {
+      return client._request('POST', '/dns/record', { body: record });
+    },
+
+    /**
+     * Create a DNS record (universal path). POST /api/v1/dns/universal/record
+     * @param {object} record - DNS record definition.
+     */
+    async createUniversalRecord(record) {
+      return client._request('POST', '/dns/universal/record', { body: record });
+    },
+
+    /**
+     * Delete a DNS record. DELETE /api/v1/dns/record
+     * @param {object} record - Record identifier fields.
+     */
+    async deleteRecord(record) {
+      return client._request('DELETE', '/dns/record', { body: record });
+    },
+
+    /**
+     * Resolve a DNS record. GET /api/v1/dns/resolve
+     * @param {object} params - Query params (domain, type).
+     */
+    async resolve(params) {
+      return client._request('GET', '/dns/resolve', { query: params });
+    },
+
+    /** DNS credentials. GET /api/v1/dns/credentials */
+    async credentials() {
+      return client._request('GET', '/dns/credentials');
+    },
+
+    /**
+     * Set DNS credentials. POST /api/v1/dns/credentials
+     * @param {object} creds - Provider credentials.
+     */
+    async setCredentials(creds) {
+      return client._request('POST', '/dns/credentials', { body: creds });
+    },
+
+    /**
+     * Check DNS propagation for a domain. GET /api/v1/dns/propagation/:domain
+     * @param {string} domain - Domain to check.
+     */
+    async propagation(domain) {
+      return client._request('GET', `/dns/propagation/${encodeURIComponent(domain)}`);
+    },
+  };
+}
+
+/**
+ * @param {DashCaddyClient} client
+ * @returns {Object}
+ */
+function createBackupsResource(client) {
+  return {
+    /** Get backup config. GET /api/v1/backups/config */
+    async getConfig() {
+      return client._request('GET', '/backups/config');
+    },
+
+    /**
+     * Update backup config. POST /api/v1/backups/config
+     * @param {object} config - Backup config patch.
+     */
+    async updateConfig(config) {
+      return client._request('POST', '/backups/config', { body: config });
+    },
+
+    /**
+     * Execute an immediate backup. POST /api/v1/backups/execute
+     * @param {object} [opts] - Backup options.
+     */
+    async execute(opts) {
+      return client._request('POST', '/backups/execute', { body: opts || {} });
+    },
+
+    /**
+     * Get backup history. GET /api/v1/backups/history
+     * @param {number} [limit=50] - Max entries.
+     */
+    async history(limit) {
+      const query = limit ? { limit: String(limit) } : undefined;
+      return client._request('GET', '/backups/history', { query });
+    },
+
+    /** Get backup storage info. GET /api/v1/backups/storage-info */
+    async storageInfo() {
+      return client._request('GET', '/backups/storage-info');
+    },
+
+    /**
+     * Restore from a backup. POST /api/v1/backups/restore/:backupId
+     * @param {string} backupId - Backup ID.
+     * @param {object} [opts] - Restore options.
+     */
+    async restore(backupId, opts) {
+      return client._request('POST', `/backups/restore/${encodeURIComponent(backupId)}`, { body: opts || {} });
+    },
+
+    /** List backup files. GET /api/v1/backups/files */
+    async files() {
+      return client._request('GET', '/backups/files');
+    },
+  };
+}
+
+/**
+ * @param {DashCaddyClient} client
+ * @returns {Object}
+ */
+function createConfigResource(client) {
+  return {
+    /** Get site configuration. GET /api/v1/config */
+    async get() {
+      return client._request('GET', '/config');
+    },
+
+    /**
+     * Update site configuration. POST /api/v1/config
+     * @param {object} config - Config patch (merged with existing).
+     */
+    async update(config) {
+      return client._request('POST', '/config', { body: config });
+    },
+  };
+}
+
+/**
+ * @param {DashCaddyClient} client
+ * @returns {Object}
+ */
+function createMonitoringResource(client) {
+  return {
+    /** Aggregated resource stats for all containers. GET /api/v1/monitoring/stats */
+    async stats() {
+      return client._request('GET', '/monitoring/stats');
+    },
+
+    /**
+     * Resource stats for a specific container. GET /api/v1/monitoring/stats/:containerId
+     * @param {string} containerId - Container ID.
+     */
+    async containerStats(containerId) {
+      return client._request('GET', `/monitoring/stats/${encodeURIComponent(containerId)}`);
+    },
+
+    /**
+     * Historical stats for a container. GET /api/v1/monitoring/history/:containerId
+     * @param {string} containerId - Container ID.
+     * @param {object} [query] - e.g. { hours: 24 } or { startTime, endTime }.
+     */
+    async history(containerId, query) {
+      return client._request('GET', `/monitoring/history/${encodeURIComponent(containerId)}`, { query });
+    },
+
+    /** Alert configuration. GET /api/v1/monitoring/alerts/config */
+    async alertConfig() {
+      return client._request('GET', '/monitoring/alerts/config');
+    },
+
+    /**
+     * Update alert configuration. POST /api/v1/monitoring/alerts/config
+     * @param {object} config - Alert config.
+     */
+    async updateAlertConfig(config) {
+      return client._request('POST', '/monitoring/alerts/config', { body: config });
+    },
+
+    /** List configured alerts. GET /api/v1/monitoring/alerts */
+    async alerts() {
+      return client._request('GET', '/monitoring/alerts');
+    },
+  };
+}
+
+// ── Main Client Class ──────────────────────────────────────────
+
+/**
+ * DashCaddy API client.
+ *
+ * Handles authentication (API key, session cookie, or TOTP session),
+ * automatic CSRF token management, retry on 5xx errors, and provides
+ * structured access to all major resource types.
+ */
+class DashCaddyClient {
+  /**
+   * @param {object} options
+   * @param {string} options.baseUrl - Base URL, e.g. 'https://status.sami'.
+   * @param {string} [options.apiKey] - API key (dk_<id>_<secret>). Bypasses CSRF.
+   * @param {string} [options.sessionCookie] - Session cookie value for cookie auth.
+   * @param {string} [options.csrfToken] - Pre-fetched CSRF token.
+   * @param {number} [options.timeout=30000] - Request timeout in ms.
+   * @param {number} [options.maxRetries=3] - Max retries on 5xx.
+   * @param {Record<string, string>} [options.headers] - Extra default headers.
+   * @param {typeof fetch} [options.fetch] - Custom fetch implementation.
+   */
+  constructor(options) {
+    if (!options || !options.baseUrl) {
+      throw new Error('DashCaddyClient: baseUrl is required');
+    }
+
+    this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+    this.apiKey = options.apiKey || null;
+    this.sessionCookie = options.sessionCookie || null;
+    this._csrfToken = options.csrfToken || null;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    this.maxRetries = options.maxRetries !== undefined ? options.maxRetries : DEFAULT_MAX_RETRIES;
+    this.extraHeaders = options.headers || {};
+    this._fetchImpl = options.fetch || null;
+
+    // API key auth bypasses CSRF entirely
+    this._useApiKey = !!this.apiKey;
+
+    // Resource namespaces
+    this.services = createServicesResource(this);
+    this.containers = createContainersResource(this);
+    this.health = createHealthResource(this);
+    this.dns = createDnsResource(this);
+    this.backups = createBackupsResource(this);
+    this.config = createConfigResource(this);
+    this.monitoring = createMonitoringResource(this);
+  }
+
+  // ── CSRF Token Management ──
+
+  /**
+   * Fetch and cache a CSRF token (needed for session-cookie auth on
+   * state-changing requests). Skipped automatically when using API key auth.
+   * @returns {Promise<string|null>}
+   */
+  async ensureCsrfToken() {
+    if (this._useApiKey) return null;
+    if (this._csrfToken) return this._csrfToken;
+
+    try {
+      const res = await this._request('GET', '/csrf-token', { _skipCsrf: true });
+      this._csrfToken = res.token || null;
+      return this._csrfToken;
+    } catch (_) {
+      // CSRF fetch failed — proceed without; server will reject if needed
+      return null;
+    }
+  }
+
+  // ── Core Request Method ──
+
+  /**
+   * Internal: perform an authenticated API request with retry logic.
+   *
+   * @param {string} method - HTTP method (GET, POST, PUT, DELETE, PATCH).
+   * @param {string} path - Path after the API base (e.g. '/services').
+   * @param {object} [opts]
+   * @param {unknown} [opts.body] - Request body (JSON-serialized).
+   * @param {Record<string,string>} [opts.query] - Query string params.
+   * @param {boolean} [opts.root=false] - If true, path is root-level (e.g. /health).
+   * @param {boolean} [opts._skipCsrf=false] - Internal: skip CSRF token injection.
+   * @param {AbortSignal} [opts.signal] - External abort signal.
+   * @returns {Promise<object>} The parsed response body (spread from the success envelope).
+   * @throws {DashCaddyError} On non-success response or network failure after retries.
+   * @private
+   */
+  async _request(method, path, opts = {}) {
+    const { body, query, root, _skipCsrf, signal } = opts;
+
+    // Build URL
+    const prefix = root ? HEALTH_PREFIX : API_PREFIX;
+    let url = `${this.baseUrl}${prefix}${path}`;
+    if (query) {
+      const qs = new URLSearchParams(
+        Object.entries(query).filter(([, v]) => v !== undefined && v !== null)
+      ).toString();
+      if (qs) url += `?${qs}`;
+    }
+
+    // Determine if CSRF is needed for this request
+    const isStateChanging = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method.toUpperCase());
+    const needsCsrf = isStateChanging && !_skipCsrf && !this._useApiKey;
+
+    // CSRF token: ensure we have one for state-changing requests (session auth)
+    let csrfToken = this._csrfToken;
+    if (needsCsrf && !csrfToken) {
+      csrfToken = await this.ensureCsrfToken();
+    }
+
+    // Build headers
+    const headers = {
+      'Content-Type': 'application/json',
+      ...this.extraHeaders,
+    };
+
+    if (this._useApiKey) {
+      headers[API_KEY_HEADER] = this.apiKey;
+    }
+    if (this.sessionCookie) {
+      headers['Cookie'] = this.sessionCookie;
+    }
+    if (csrfToken && !_skipCsrf) {
+      headers[CSRF_HEADER_NAME] = csrfToken;
+    }
+
+    // Retry loop
+    let lastError = null;
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        const res = await rawRequest({
+          url,
+          method,
+          headers,
+          body,
+          timeout: this.timeout,
+          fetchImpl: this._fetchImpl,
+          signal,
+        });
+
+        // Parse response body
+        let json = null;
+        const text = await res.text();
+        if (text) {
+          try {
+            json = JSON.parse(text);
+          } catch (_) {
+            // Non-JSON response — wrap it
+            json = { success: res.ok, raw: text };
+          }
+        }
+
+        // Retry on 5xx
+        if (res.status >= 500 && attempt < this.maxRetries) {
+          await this._backoff(attempt);
+          continue;
+        }
+
+        // Check envelope
+        if (json && json.success === false) {
+          const errorMsg = json.error || `Request failed with status ${res.status}`;
+          throw new DashCaddyError(errorMsg, res.status, json.code, json);
+        }
+
+        if (!res.ok && !(json && json.success === true)) {
+          const errorMsg = (json && json.error) || `HTTP ${res.status}`;
+          throw new DashCaddyError(errorMsg, res.status, json && json.code, json);
+        }
+
+        // Success — return the full envelope (minus the success flag is caller's choice)
+        // We return the spread data: everything except `success` for convenience,
+        // but also keep success for callers who want to check it.
+        return json || { success: true };
+
+      } catch (err) {
+        // Network errors (AbortError, TypeError) — retry if attempts remain
+        if (err instanceof DashCaddyError) {
+          // 5xx errors that exhausted retries are re-thrown
+          if (err.statusCode >= 500 && attempt < this.maxRetries) {
+            lastError = err;
+            await this._backoff(attempt);
+            continue;
+          }
+          throw err;
+        }
+
+        // Network-level error
+        lastError = err;
+        if (attempt < this.maxRetries) {
+          await this._backoff(attempt);
+          continue;
+        }
+
+        throw new DashCaddyError(
+          err.name === 'AbortError'
+            ? `Request timeout after ${this.timeout}ms`
+            : `Network error: ${err.message}`,
+          0,
+          'NETWORK_ERROR',
+          { originalError: err.message }
+        );
+      }
+    }
+
+    // Should not reach here, but guard just in case
+    throw lastError || new DashCaddyError('Request failed after all retries', 0);
+  }
+
+  /**
+   * Exponential backoff with jitter.
+   * @param {number} attempt - Current attempt number (1-based).
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _backoff(attempt) {
+    const delay = RETRY_BACKOFF_BASE_MS * Math.pow(2, attempt - 1);
+    const jitter = Math.random() * delay * 0.3;
+    await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+  }
+
+  // ── Auth Helpers ──
+
+  /**
+   * Exchange an API key for a JWT token.
+   * POST /api/v1/auth/jwt
+   * @param {string} [apiKey] - Override the client's API key.
+   * @returns {Promise<object>}
+   */
+  async exchangeJwt(apiKey) {
+    const key = apiKey || this.apiKey;
+    if (!key) throw new DashCaddyError('API key required for JWT exchange', 0, 'NO_API_KEY');
+    return this._request('POST', '/auth/jwt', { body: { apiKey: key }, _skipCsrf: true });
+  }
+
+  /**
+   * Verify a TOTP code to establish a session.
+   * POST /api/v1/totp/verify
+   * @param {string} code - TOTP code from authenticator.
+   * @returns {Promise<object>} Includes csrfToken and ssoToken on success.
+   */
+  async verifyTotp(code) {
+    const res = await this._request('POST', '/totp/verify', { body: { code }, _skipCsrf: true });
+    // Cache the CSRF token returned after TOTP login
+    if (res.csrfToken) {
+      this._csrfToken = res.csrfToken;
+    }
+    return res;
+  }
+
+  /**
+   * Get the current API version. GET /api/v1/version
+   * @returns {Promise<object>}
+   */
+  async version() {
+    return this._request('GET', '/version');
+  }
+
+  /**
+   * Get API metrics summary. GET /api/v1/metrics
+   * @returns {Promise<object>}
+   */
+  async metrics() {
+    return this._request('GET', '/metrics');
+  }
+}
+
+// ── Exports ────────────────────────────────────────────────────
+
+module.exports = { DashCaddyClient, DashCaddyError };
+module.exports.DashCaddyClient = DashCaddyClient;
+module.exports.DashCaddyError = DashCaddyError;
@@ -0,0 +1,245 @@
+/**
+ * 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;
+}