@ninedeploy/sdk 0.10.5 → 0.16.0

package/src/resources/system.ts

@@ -0,0 +1,281 @@
+// Client surface: system, health, about, dashboard, stats, topology, activity, alerts, metricHistory, buildCache, housekeeping, doctor, demo.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  ActivityEntry,
+  AlertRule,
+  CreateAlertRuleInput,
+  DoctorFixRequestInput,
+  DoctorFixResponse,
+  DoctorReport,
+  DemoSeedResult,
+  DockerResources,
+  MetricSeries,
+  StatsSnapshot,
+  TopologyGraph,
+  UpdateCheckResult,
+  SelfUpdateStatus,
+  AutoPruneConfigUpdateInput,
+  AutoPruneStatus,
+  AutoPruneRunResult,
+  PanelBackupObject,
+  PanelBackupRestore,
+  PanelBackupSettingsPatch,
+  PanelBackupStatus,
+} from '@ninedeploy/schemas';
+import type { HealthStatus, ImageInfo, PruneImagesInput, PruneImagesResult } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface SystemApi {
+  system: {
+    resources: () => Promise<DockerResources>;
+    pruneImages: () => Promise<{ ok: boolean }>;
+    exportUrl: () => string;
+    /** Latest-release check (admin). updateAvailable is null when offline/disabled. */
+    updateCheck: (force?: boolean) => Promise<UpdateCheckResult>;
+    /** State of a panel-initiated upgrade (idle/running/success/failed/unsupported). */
+    updateStatus: () => Promise<SelfUpdateStatus>;
+    /**
+     * Start upgrading the panel itself to an exact release tag; the updater survives the restart it performs.
+     * Refused with 409 `deploys_in_flight` while deployments are executing unless `force` is set (r572).
+     */
+    updateStart: (version: string, opts?: { force?: boolean }) => Promise<{ ok: boolean }>;
+    /** Recent docker daemon events (single-shot, for the Docker dashboard feed). */
+    dockerEvents: (minutes?: number) => Promise<{ events: Array<{ time: string; type: string; action: string; name: string }> }>;
+    /**
+     * Panel self-backup (0.12, operator-only): the `/system/export` archive sealed with a
+     * recovery passphrase and written to a backup destination on a schedule.
+     */
+    panelBackup: {
+      /** Settings, last run, next run (passphrase never returned — only `hasPassphrase`). */
+      get: () => Promise<PanelBackupStatus>;
+      /** Omitted fields keep their stored value; `passphrase` omitted = keep the stored one. */
+      update: (input: PanelBackupSettingsPatch) => Promise<PanelBackupStatus>;
+      /** "Back up now": starts a run in the background (409 while one is running); poll `get()`. */
+      run: () => Promise<{ ok: boolean; started: boolean }>;
+      /** Panel backups in a destination (default: the configured one), newest first. */
+      list: (destinationId?: number) => Promise<{ destinationId: number; items: PanelBackupObject[] }>;
+      /**
+       * DESTRUCTIVE: replaces this panel's database, master key, .env and Traefik config with
+       * the backup's. `confirm` must repeat the object's file name. Restart the panel afterwards.
+       */
+      restore: (input: PanelBackupRestore) => Promise<{ ok: boolean; message: string; meta: unknown; backupPath: string }>;
+    };
+  };
+  health: () => Promise<HealthStatus>;
+  about: {
+    get: () => Promise<{
+      name: string; version: string; description: string; license: string; repo: string; docs: string;
+      techStack: Array<{ category: string; items: string[] }>;
+      changelog: Array<{ version: string; date: string; title: string; changes: string[] }>;
+      /** Instance counts are only returned for authenticated requests. */
+      stats?: { services: number; databases: number; deployments: number; users: number };
+    }>;
+  };
+  dashboard: {
+    get: () => Promise<{
+      stats: { services: number; databases: number; deployments: number; domains: number; webhooks: number; running: number; stopped: number; errored: number; dbRunning: number; /** Whole-node count — operators only, null for members (r470). */ containers: number | null };
+      health: Array<{ serviceId: number; name: string; slug: string; type: string; status: string; healthy: boolean | null; responseMs: number | null; port: number | null; runtimeId: string | null; commitSha: string | null; lastDeploy: string | null }>;
+      recentDeploys: Array<{ id: number; serviceId: number; serviceName: string; status: string; commitSha: string | null; message: string | null; trigger: string; finishedAt: string | null; createdAt: string }>;
+    }>;
+  };
+  stats: {
+    snapshot: () => Promise<StatsSnapshot>;
+    metrics: (serviceId: number, opts?: { kind?: 'cpu' | 'memory'; minutes?: number }) => Promise<MetricSeries>;
+  };
+  topology: {
+    get: () => Promise<TopologyGraph>;
+  };
+  activity: {
+    /**
+     * Filter + paginate the audit trail. Omitted filters return the newest page.
+     * `entity` matches the bare name and `<name> #<id>`; `serviceId` (with the
+     * service name as `entity`) narrows to one service's trail.
+     */
+    list: (query?: { entity?: string; serviceId?: number; action?: string; userId?: number; before?: number }) => Promise<{ entries: ActivityEntry[]; nextCursor: number | null }>;
+  };
+  alerts: {
+    list: () => Promise<AlertRule[]>;
+    create: (input: CreateAlertRuleInput) => Promise<AlertRule>;
+    update: (id: number, input: Partial<CreateAlertRuleInput>) => Promise<AlertRule>;
+    remove: (id: number) => Promise<void>;
+  };
+  metricHistory: {
+    /** Current configuration snapshot (backend choice, enabled flag, retention, last-flush). */
+    get: () => Promise<{
+      enabled: boolean;
+      backend: 'builtin' | 'prometheus' | 'influxdb';
+      events: string[];
+      retentionDays: number;
+      lastFlush: { ts: number; backend: string; count: number };
+    }>;
+    /** Run the built-in backend's retention sweep. Returns the row count trimmed. */
+    flush: () => Promise<{ ok: boolean; backend: 'builtin'; deleted: number }>;
+  };
+  buildCache: {
+    /** Per-backend counters + merged totals. G-01 PR-A. */
+    stats: () => Promise<{
+      backends: Array<{
+        name: string;
+        entries: number;
+        totalBytes: number;
+        hits: number;
+        misses: number;
+        stores: number;
+        evictions: number;
+      }>;
+      totals: {
+        entries: number;
+        totalBytes: number;
+        hits: number;
+        misses: number;
+        stores: number;
+        evictions: number;
+      };
+    }>;
+  };
+  housekeeping: {
+    getAutoPrune: () => Promise<AutoPruneStatus>;
+    updateAutoPrune: (input: AutoPruneConfigUpdateInput) => Promise<AutoPruneStatus>;
+    runPrune: () => Promise<AutoPruneRunResult>;
+    /**
+     * List every image on the host with repo / tag / size /
+     * created / dangling / inUse metadata. The companion to
+     * the auto-prune cron: this is what the operator
+     * inspects before `pruneImages({ keepLast: 5 })`.
+     */
+    listImages: () => Promise<{ images: ImageInfo[]; totalCount: number; totalBytes: number }>;
+    /**
+     * Prune images with operator-supplied filters. `dryRun`
+     * returns the candidate set without deleting. Refused
+     * when no filter is supplied (a naked prune would
+     * delete every unused image).
+     */
+    pruneImages: (input: PruneImagesInput) => Promise<PruneImagesResult>;
+  };
+  /** Host-wide analysis + guarded cleanup. */
+  doctor: {
+    scan: () => Promise<DoctorReport>;
+    fix: (input: DoctorFixRequestInput) => Promise<DoctorFixResponse>;
+  };
+  demo: {
+    seed: () => Promise<DemoSeedResult>;
+  };
+}
+
+export function systemApi(t: Transport): SystemApi {
+  const { get, send, request } = t;
+  return {
+    system: {
+      resources: () => get<DockerResources>('/v1/system/resources'),
+      pruneImages: () => send<{ ok: boolean }>('POST', '/v1/system/prune-images'),
+      updateCheck: (force) => get<UpdateCheckResult>(`/v1/system/update-check${force ? '?force=1' : ''}`),
+      updateStatus: () => get<SelfUpdateStatus>('/v1/system/update-status'),
+      updateStart: (version, opts) => send<{ ok: boolean }>('POST', '/v1/system/update-start', { version, ...opts }),
+      exportUrl: () => '/v1/system/export',
+      dockerEvents: (minutes) =>
+        get<{ events: Array<{ time: string; type: string; action: string; name: string }> }>(
+          `/v1/system/docker-events?minutes=${minutes ?? 60}`,
+        ),
+      panelBackup: {
+        get: () => get<PanelBackupStatus>('/v1/system/panel-backup'),
+        update: (input) => send<PanelBackupStatus>('PUT', '/v1/system/panel-backup', input),
+        run: () => send<{ ok: boolean; started: boolean }>('POST', '/v1/system/panel-backup/run'),
+        list: (destinationId) =>
+          get<{ destinationId: number; items: PanelBackupObject[] }>(
+            `/v1/system/panel-backup/remote${destinationId != null ? `?destinationId=${destinationId}` : ''}`,
+          ),
+        restore: (input) =>
+          send<{ ok: boolean; message: string; meta: unknown; backupPath: string }>('POST', '/v1/system/panel-backup/restore', input),
+      },
+    },
+    health: () => get<HealthStatus>('/health'),
+    about: {
+      get: () => get('/v1/about'),
+    },
+    dashboard: {
+      get: () => get('/v1/dashboard'),
+    },
+    stats: {
+      snapshot: () => get<StatsSnapshot>('/v1/stats'),
+      metrics: (serviceId, opts) =>
+        get<MetricSeries>(
+          `/v1/services/${serviceId}/metrics?kind=${opts?.kind ?? 'cpu'}&minutes=${opts?.minutes ?? 60}`,
+        ),
+    },
+    topology: {
+      get: () => get<TopologyGraph>('/v1/topology'),
+    },
+    activity: {
+      list: (query) => {
+        const parts: string[] = [];
+        if (query?.entity) parts.push(`entity=${encodeURIComponent(query.entity)}`);
+        if (query?.serviceId) parts.push(`serviceId=${query.serviceId}`);
+        if (query?.action) parts.push(`action=${encodeURIComponent(query.action)}`);
+        if (query?.userId) parts.push(`userId=${query.userId}`);
+        if (query?.before) parts.push(`before=${query.before}`);
+        const qs = parts.join('&');
+        return get<{ entries: ActivityEntry[]; nextCursor: number | null }>(`/v1/activity${qs ? `?${qs}` : ''}`);
+      },
+    },
+    alerts: {
+      list: () => get('/v1/alerts'),
+      create: (input) => send('POST', '/v1/alerts', input),
+      update: (id, input) => send('PATCH', `/v1/alerts/${id}`, input),
+      remove: async (id) => {
+        await request(`/v1/alerts/${id}`, { method: 'DELETE' });
+      },
+    },
+    metricHistory: {
+      get: () => get<{
+        enabled: boolean;
+        backend: 'builtin' | 'prometheus' | 'influxdb';
+        events: string[];
+        retentionDays: number;
+        lastFlush: { ts: number; backend: string; count: number };
+      }>('/v1/metric-history'),
+      flush: () => send<{ ok: boolean; backend: 'builtin'; deleted: number }>('POST', '/v1/metric-history/flush'),
+    },
+    buildCache: {
+      stats: () => get<{
+        backends: Array<{
+          name: string;
+          entries: number;
+          totalBytes: number;
+          hits: number;
+          misses: number;
+          stores: number;
+          evictions: number;
+        }>;
+        totals: {
+          entries: number;
+          totalBytes: number;
+          hits: number;
+          misses: number;
+          stores: number;
+          evictions: number;
+        };
+      }>('/v1/build-cache/stats'),
+    },
+    housekeeping: {
+      getAutoPrune: () => get<AutoPruneStatus>('/v1/housekeeping/prune/config'),
+      updateAutoPrune: (input) => send<AutoPruneStatus>('PATCH', '/v1/housekeeping/prune/config', input),
+      runPrune: () => send<AutoPruneRunResult>('POST', '/v1/housekeeping/prune'),
+      listImages: () =>
+        get<{ images: ImageInfo[]; totalCount: number; totalBytes: number }>('/v1/housekeeping/images'),
+      pruneImages: (input) =>
+        send<PruneImagesResult>('POST', '/v1/housekeeping/images/prune', input),
+    },
+    doctor: {
+      /** Full host scan: dead containers, orphan volumes/networks, row-vs-runtime
+       *  desyncs, dangling images, disk pressure — with guarded repair actions. */
+      scan: () => get<DoctorReport>('/v1/doctor'),
+      /** Execute one finding's repair. The server re-scans and re-locates the
+       *  finding first; a stale finding answers 409 instead of acting. */
+      fix: (input: DoctorFixRequestInput) => send<DoctorFixResponse>('POST', '/v1/doctor/fix', input),
+    },
+    demo: {
+      seed: () => send<DemoSeedResult>('POST', '/v1/demo/seed'),
+    },
+  };
+}

package/src/resources/templates.ts

@@ -0,0 +1,55 @@
+// Client surface: templates.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  DeployTemplateInput,
+  Template,
+  TemplateSummary,
+  CommunityTemplateListResult,
+} from '@ninedeploy/schemas';
+import type { TemplateDeployResult, TemplatePrepareResult } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface TemplatesApi {
+  templates: {
+    list: () => Promise<TemplateSummary[]>;
+    get: (id: string) => Promise<Template>;
+    prepare: (id: string, input?: DeployTemplateInput) => Promise<TemplatePrepareResult>;
+    deploy: (id: string, input?: DeployTemplateInput) => Promise<TemplateDeployResult>;
+    /**
+     * Community contributions (G-13). The `list` call
+     * already merges community entries with the curated
+     * catalog; the dedicated `community` namespace lets
+     * the panel surface errors and the operator import
+     * a new template from a PR comment or a file.
+     */
+    community: {
+      list: () => Promise<CommunityTemplateListResult>;
+      import: (content: string, opts?: { replace?: boolean }) => Promise<{ ok: boolean; id: string; file: string; bytes: number }>;
+      remove: (id: string) => Promise<{ ok: boolean; id: string; removed: boolean }>;
+    };
+  };
+}
+
+export function templatesApi(t: Transport): TemplatesApi {
+  const { get, send } = t;
+  return {
+    templates: {
+      list: () => get<TemplateSummary[]>('/v1/templates'),
+      get: (id) => get<Template>(`/v1/templates/${encodeURIComponent(id)}`),
+      prepare: (id, input) => send<TemplatePrepareResult>('POST', `/v1/templates/${encodeURIComponent(id)}/prepare`, input ?? {}),
+      deploy: (id, input) => send<TemplateDeployResult>('POST', `/v1/templates/${encodeURIComponent(id)}/deploy`, input ?? {}),
+      community: {
+        list: () => get<CommunityTemplateListResult>('/v1/templates/community'),
+        import: (content, opts) =>
+          send<{ ok: boolean; id: string; file: string; bytes: number }>(
+            'POST',
+            '/v1/templates/community/import',
+            { content, ...(opts ?? {}) },
+          ),
+        remove: (id) =>
+          send<{ ok: boolean; id: string; removed: boolean }>('DELETE', `/v1/templates/community/${encodeURIComponent(id)}`),
+      },
+    },
+  };
+}

package/src/resources/terminals.ts

@@ -0,0 +1,112 @@
+// Client surface: terminals, traffic, api.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  CreateTerminalSessionInput,
+  ServiceTrafficSummary,
+  TerminalSession,
+  TerminalSessionCreated,
+  TerminalSessionList,
+  TerminalSettingsInput,
+  TerminalSettingsView,
+  TerminalTerminateResult,
+  TrafficSettingsUpdate,
+  TrafficSettingsView,
+  TrafficSummary,
+} from '@ninedeploy/schemas';
+import { apiGetUrl, type ApiQuery } from '../apiPath.js';
+import { terminalAttachInfo, connectTerminal, type TerminalAttachSource, type WebSocketLocation, type TerminalAttachInfo, type TerminalHandlers, type TerminalConnectOptions, type TerminalConnection } from '../terminal.js';
+import type { TerminalListQuery, TrafficQuery } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface TerminalsApi {
+  // ── end 0.15 T4 ──
+  // ── 0.15 T6 surfaces ──
+  /**
+   * Interactive terminals (0.15, operator only). A session is created over
+   * HTTP and attached over a WebSocket with its single-use ticket (valid 30s).
+   * Host shells (`target.kind: 'host'`) are off by default and need an
+   * interactive session plus the account password in `password`.
+   */
+  terminals: {
+    create: (input: CreateTerminalSessionInput) => Promise<TerminalSessionCreated>;
+    /** History, newest first; page back with `before: list.nextBefore`. */
+    list: (query?: TerminalListQuery) => Promise<TerminalSessionList>;
+    get: (id: number) => Promise<TerminalSession>;
+    /** Close a live session (close 4410) or revoke a pending ticket. */
+    terminate: (id: number) => Promise<TerminalTerminateResult>;
+    settings: {
+      get: () => Promise<TerminalSettingsView>;
+      /** Partial. Turning host shells on needs `password` (step-up). */
+      set: (input: TerminalSettingsInput) => Promise<TerminalSettingsView>;
+    };
+    /** The WebSocket URL and subprotocols that attach a created session. */
+    attachInfo: (created: TerminalAttachSource, location?: WebSocketLocation) => TerminalAttachInfo;
+    /** Attach a created session over protocol v1 (see `connectTerminal`). */
+    connect: (created: TerminalAttachSource, handlers?: TerminalHandlers, options?: TerminalConnectOptions) => TerminalConnection;
+  };
+  /** Traffic analytics (0.15, opt-in). Settings and the summary are operator only. */
+  traffic: {
+    settings: {
+      get: () => Promise<TrafficSettingsView>;
+      /**
+       * Enabling or disabling recreates Traefik once (about 1–2s of refused
+       * connections). A browser behind Traefik may lose this response; read
+       * `settings.get()` again on a network error.
+       */
+      set: (input: TrafficSettingsUpdate) => Promise<TrafficSettingsView>;
+    };
+    summary: (query?: TrafficQuery) => Promise<TrafficSummary>;
+    /** One service's series (any seat on the service). Empty series, never 404, without data. */
+    service: (serviceId: number, query?: TrafficQuery) => Promise<ServiceTrafficSummary>;
+  };
+  // ── 0.15 T4 api ──
+  /**
+   * Raw access to the documented API (0.15, see `GET /v1/openapi.json`).
+   * Read-only on purpose: there is no generic write method. The generated MCP
+   * read tools call through here.
+   */
+  api: {
+    /**
+     * GET any `/v1/…` route. The path must match `^/v1/[A-Za-z0-9/_.-]+$` and
+     * may not contain a `..` segment; query values are URL-encoded and
+     * `undefined` values are dropped.
+     */
+    get: <T = unknown>(path: `/v1/${string}`, query?: ApiQuery) => Promise<T>;
+  };
+}
+
+export function terminalsApi(t: Transport): TerminalsApi {
+  const { get, send, baseUrl } = t;
+  return {
+    // ── end 0.15 T4 ──
+    // ── 0.15 T6 surfaces ──
+    terminals: {
+      create: (input) => send<TerminalSessionCreated>('POST', '/v1/terminals', input),
+      list: (query) => get<TerminalSessionList>(apiGetUrl('/v1/terminals', { ...query })),
+      get: (id) => get<TerminalSession>(`/v1/terminals/${id}`),
+      terminate: (id) => send<TerminalTerminateResult>('DELETE', `/v1/terminals/${id}`),
+      settings: {
+        get: () => get<TerminalSettingsView>('/v1/terminals/settings'),
+        set: (input) => send<TerminalSettingsView>('PUT', '/v1/terminals/settings', input),
+      },
+      attachInfo: (created, location) => terminalAttachInfo(baseUrl, created, location),
+      connect: (created, handlers, options) =>
+        connectTerminal(terminalAttachInfo(baseUrl, created, options?.location), handlers, options),
+    },
+    traffic: {
+      settings: {
+        get: () => get<TrafficSettingsView>('/v1/traffic/settings'),
+        set: (input) => send<TrafficSettingsView>('PUT', '/v1/traffic/settings', input),
+      },
+      summary: (query) => get<TrafficSummary>(apiGetUrl('/v1/traffic/summary', { ...query })),
+      service: (serviceId, query) =>
+        get<ServiceTrafficSummary>(apiGetUrl(`/v1/services/${serviceId}/traffic`, { ...query })),
+    },
+    // ── 0.15 T4 api ──
+    api: {
+      // async: a refused path rejects like any other failed call, never throws synchronously.
+      get: async <T = unknown>(path: `/v1/${string}`, query?: ApiQuery) => get<T>(apiGetUrl(path, query)),
+    },
+  };
+}

package/src/resources/traefik.ts

@@ -0,0 +1,116 @@
+// Client surface: traefik.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  TraefikCertificate,
+  CertificateInventoryEntry,
+  CertificateInventoryReport,
+  TraefikInfo,
+  TraefikStatus,
+  TraefikCustomConfig,
+  TraefikCustomConfigApplied,
+  TraefikCustomConfigValidation,
+  CustomCertificate,
+  CustomCertificateReplace,
+  CustomCertificateSaved,
+  CustomCertificateUpload,
+} from '@ninedeploy/schemas';
+import type { TraefikVersionInfo, TraefikRoutingConfig } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface TraefikApi {
+  traefik: {
+    get: () => Promise<TraefikInfo>;
+    status: () => Promise<TraefikStatus>;
+    certificates: () => Promise<TraefikCertificate[]>;
+    /**
+     * Richer certificate inventory (G-15). Same
+     * underlying data as `certificates()` but adds a
+     * `status` classification (valid / expiring-soon /
+     * expired), a `summary` block, and the full set of
+     * fields the Certificates page renders.
+     * `threshold` is the days-out cutoff for the
+     * `expiring-soon` bucket; default 30.
+     */
+    certificateInventory: (opts?: { threshold?: number }) => Promise<CertificateInventoryReport>;
+    /**
+     * Focused "expiring within N days" filter. Default
+     * 30. Used by the alert engine and by the panel's
+     * "About to expire" widget.
+     */
+    expiringCertificates: (opts?: { days?: number }) => Promise<{ threshold: number; count: number; certificates: CertificateInventoryEntry[] }>;
+    logs: (lines?: number) => Promise<{ logs: string[] }>;
+    restart: () => Promise<{ ok: boolean; message?: string }>;
+    /** r334: the server answers the host path of the copied acme.json. */
+    backupCerts: () => Promise<{ ok: boolean; backupPath: string }>;
+    /** r557: routers / services / middlewares from the dynamic config (operator-only). */
+    config: () => Promise<TraefikRoutingConfig>;
+    /** r557: running vs latest Traefik version (operator-only). */
+    version: () => Promise<TraefikVersionInfo>;
+    /**
+     * r557: pull the pinned Traefik image and recreate the proxy container
+     * (operator-only). An image pull outlasts the default request budget, so
+     * this call allows up to 10 minutes unless the client disabled timeouts.
+     */
+    update: () => Promise<{ ok: boolean; newVersion: string | null }>;
+    /**
+     * 0.14: the operator's custom dynamic config (`custom.yml`). `set` throws
+     * a NineDeployError whose `details` is `{ errors, warnings }` on a refusal.
+     */
+    customConfig: {
+      get: () => Promise<TraefikCustomConfig>;
+      /** No state change. */
+      validate: (content: string) => Promise<TraefikCustomConfigValidation>;
+      set: (content: string) => Promise<TraefikCustomConfigApplied>;
+      clear: () => Promise<{ ok: boolean; cleared: boolean }>;
+    };
+    /** 0.14: uploaded TLS certificates (operator-only). No response carries a private key. */
+    customCertificates: {
+      list: () => Promise<CustomCertificate[]>;
+      upload: (input: CustomCertificateUpload) => Promise<CustomCertificateSaved>;
+      replace: (id: number, input: CustomCertificateReplace) => Promise<CustomCertificateSaved>;
+      delete: (id: number) => Promise<{ ok: boolean }>;
+    };
+  };
+}
+
+export function traefikApi(t: Transport): TraefikApi {
+  const { get, send, request } = t;
+  return {
+    traefik: {
+      get: () => get<TraefikInfo>('/v1/traefik'),
+      status: () => get<TraefikStatus>('/v1/traefik/status'),
+      certificates: () => get<TraefikCertificate[]>('/v1/traefik/certificates'),
+      certificateInventory: (opts) =>
+        get<CertificateInventoryReport>(
+          // `!= null` (not truthiness): 0 ("only already-expired") is a real
+          // threshold and must reach the server, not silently become the
+          // server-side default of 30.
+          `/v1/traefik/certificates/inventory${opts?.threshold != null ? `?threshold=${opts.threshold}` : ''}`,
+        ),
+      expiringCertificates: (opts) =>
+        get<{ threshold: number; count: number; certificates: CertificateInventoryEntry[] }>(
+          `/v1/traefik/certificates/expiring${opts?.days != null ? `?days=${opts.days}` : ''}`,
+        ),
+      logs: (lines = 50) => get<{ logs: string[] }>(`/v1/traefik/logs?lines=${lines}`),
+      restart: () => send<{ ok: boolean; message: string }>('POST', '/v1/traefik/restart'),
+      backupCerts: () => send<{ ok: boolean; backupPath: string }>('POST', '/v1/traefik/backup-certs'),
+      config: () => get<TraefikRoutingConfig>('/v1/traefik/config'),
+      version: () => get<TraefikVersionInfo>('/v1/traefik/version'),
+      update: () => request<{ ok: boolean; newVersion: string | null }>('/v1/traefik/update', { method: 'POST' }, 10 * 60_000),
+      customConfig: {
+        get: () => get<TraefikCustomConfig>('/v1/traefik/custom-config'),
+        validate: (content) => send<TraefikCustomConfigValidation>('POST', '/v1/traefik/custom-config/validate', { content }),
+        set: (content) =>
+          request<TraefikCustomConfigApplied>('/v1/traefik/custom-config', { method: 'PUT', body: { content }, findings: true }),
+        clear: () => send<{ ok: boolean; cleared: boolean }>('DELETE', '/v1/traefik/custom-config'),
+      },
+      customCertificates: {
+        list: () => get<CustomCertificate[]>('/v1/traefik/certificates/custom'),
+        upload: (input) => send<CustomCertificateSaved>('POST', '/v1/traefik/certificates/custom', input),
+        replace: (id, input) => send<CustomCertificateSaved>('PUT', `/v1/traefik/certificates/custom/${id}`, input),
+        delete: (id) => send<{ ok: boolean }>('DELETE', `/v1/traefik/certificates/custom/${id}`),
+      },
+    },
+  };
+}