@ninedeploy/sdk 0.3.4 → 0.5.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import type { ActiveSession, ActivityEntry, AlertRule, AnalyzeRepoInput, CreateAlertRuleInput, ApiToken, PasskeyCredential, Attachment, CreateServiceVolumeAttachmentInput, CreateVolumeBackupInput, ServiceVolumeAttachment, UpdateServiceVolumeAttachmentInput, Backup, BackupWithDb, CreateApiToken, CreateDatabaseInput, CreateDomainInput, CreateProjectInput, CreateServiceInput, CreateSourceInput, CreateTunnelInput, CreateWebhookInput, CreatedApiToken, CreatedWebhook, ConfigItem, ConfigListResponse, SetConfigInput, PluginListResponse, PluginInspectResponse, InstallPluginInput, MarketplaceCatalogResponse, MenuListResponse, DemoSeedResult, Deployment, DeployTemplateInput, DockerResources, Domain, DomainPatch, DomainEntry, EnvVar, Label, CreateLabelInput, LabelPatchInput, Login, ManagedDatabase, DatabaseDetail, DatabaseCredentials, PasswordChange, PasswordReset, MetricSeries, ProjectEntry, ProjectPatchInput, PublicUser, Refresh, Register, RepoInsights, Service, ServiceTags, SetServiceTagsInput, Session, SetLimitsInput, Source, StatsSnapshot, Template, TemplateSummary, TopologyGraph, TraefikCertificate, TraefikInfo, TraefikStatus, TunnelEntry, UserCreate, VolumeFileEntry, VolumeFileWriteInput, VolumePathCreateInput, TriggerDeploy, UpdateCheckResult, SelfUpdateStatus, UpdateServiceInput, UpsertEnvVarInput, VolumeEntry, Webhook, LogDrain, LogDrainCreateInput, LogDrainUpdateInput, LogDrainTestResult, AutoPruneConfigUpdateInput, AutoPruneStatus, AutoPruneRunResult, ServerSshTest, ServerSshTestResult, ServerSshBootstrap, ServerBootstrapResult, WorkspaceEntry, WorkspaceDetail, WorkspaceCreateInput, WorkspaceUpdateInput, WorkspaceMemberEntry, WorkspaceMemberInviteEntry, WorkspaceMemberAddInput, WorkspaceMemberRoleUpdateInput, OidcPublicProvider, WorkspaceInvitationEntry, WorkspaceInvitationPublic, WorkspaceRole, OidcProviderEntry, OidcProviderCreateInput, OidcProviderUpdateInput } from '@ninedeploy/schemas';
+import type { ActiveSession, ActivityEntry, AlertRule, AnalyzeRepoInput, CreateAlertRuleInput, ApiToken, PasskeyCredential, Attachment, CreateServiceVolumeAttachmentInput, CreateVolumeBackupInput, ServiceVolumeAttachment, UpdateServiceVolumeAttachmentInput, Backup, BackupWithDb, CreateApiTokenInput, CreateDatabaseInput, CreateDomainInput, CreateProjectInput, CreateServiceInput, CreateSourceInput, CreateTunnelInput, CreateWebhookInput, CreatedApiToken, CreatedWebhook, ConfigItem, ConfigListResponse, SetConfigInput, DoctorFixRequestInput, DoctorFixResponse, DoctorReport, PluginListResponse, PluginInspectResponse, InstallPluginInput, MarketplaceCatalogResponse, MenuListResponse, DemoSeedResult, Deployment, QueueResponse, DeployTemplateInput, DockerResources, Domain, DomainPatch, DomainEntry, EnvVar, Label, CreateLabelInput, LabelPatchInput, Login, ManagedDatabase, DatabaseDetail, DatabaseCredentials, PasswordChange, PasswordReset, MetricSeries, ProjectEntry, ProjectPatchInput, PublicUser, Refresh, Register, RepoInsights, Service, ServiceTags, SetServiceTagsInput, Session, SetLimitsInput, Source, StatsSnapshot, Template, TemplateSummary, CommunityTemplateListResult, TopologyGraph, TraefikCertificate, CertificateInventoryEntry, CertificateInventoryReport, TraefikInfo, TraefikStatus, TunnelEntry, UserCreate, VolumeFileEntry, VolumeFileWriteInput, VolumePathCreateInput, TriggerDeploy, UpdateCheckResult, SelfUpdateStatus, UpdateServiceInput, UpsertEnvVarInput, VolumeEntry, Webhook, LogDrain, LogDrainCreateInput, LogDrainUpdateInput, LogDrainTestResult, AutoPruneConfigUpdateInput, AutoPruneStatus, AutoPruneRunResult, ServerSshTest, ServerSshTestResult, ServerSshBootstrap, ServerBootstrapResult, WorkspaceEntry, WorkspaceDetail, WorkspaceCreateInput, WorkspaceUpdateInput, WorkspaceMemberEntry, WorkspaceMemberInviteEntry, WorkspaceMemberAddInput, WorkspaceMemberRoleUpdateInput, OidcPublicProvider, NinedeployManifest, WorkspaceInvitationEntry, WorkspaceInvitationPublic, WorkspaceRole, OidcProviderEntry, OidcProviderCreateInput, OidcProviderUpdateInput } from '@ninedeploy/schemas';
 import { NineDeployError } from './errors.js';
 export { NineDeployError };
 export type * from '@ninedeploy/schemas';
-export { detectProjectKind, formatManifestYaml, ManifestParseError, ManifestValidationError, parseManifestYaml, starterManifest, } from './manifest.js';
-export type { ProjectKind } from './manifest.js';
+export { detectProjectKind, formatManifestYaml, ManifestParseError, ManifestValidationError, parseManifestYaml, starterManifest, buildManifestFromTemplate, } from './manifest.js';
+export type { ProjectKind, TemplateRegistryEntry } from './manifest.js';
 /**
  * Minimal structural fetch type so the SDK is isomorphic (browser + Node)
  * without pulling in DOM lib types. Both `globalThis.fetch` implementations
@@ -24,6 +24,25 @@ export interface HealthStatus {
     version?: string;
     time?: string;
 }
+/**
+ * Result of `GET /v1/auth/token`. Tells the caller what
+ * the current bearer credential is and what it can do.
+ * `kind` is `'session'` for JWTs and `'api'` for opaque
+ * API tokens. `scopes` lists the resource-scoped
+ * authorities (or the legacy `read` / `write` / `operator`
+ * shorthand); an interactive session reports
+ * `['session']` which is implicit full authority.
+ */
+export interface TokenIntrospection {
+    kind: 'session' | 'api';
+    userId: number;
+    scopes: string[];
+    expiresAt: string | null;
+    isOperator: boolean;
+    /** API tokens only. */
+    tokenId?: number;
+    name?: string;
+}
 export interface TemplateDeployResult {
     serviceId: number;
     serviceName: string;
@@ -52,6 +71,222 @@ export interface TemplatePrepareResult {
     }>;
     stages: TemplateDeployResult['stages'];
 }
+/**
+ * Response from `services.manifest.apply`. The server returns the
+ * subset of fields the manifest actually changed under each
+ * section; untouched fields stay in the panel-managed column
+ * and do not appear in `diff`.
+ */
+export interface ApplyManifestResult {
+    ok: boolean;
+    serviceId: number;
+    /** Sections the server actually wrote: `service`, `build_config`. */
+    touched: string[];
+    diff: {
+        service: {
+            port?: number;
+            healthPath?: string;
+            publishedPort?: number | null;
+        };
+        build: {
+            installCmd?: string;
+            buildCmd?: string;
+            startCmd?: string;
+            baseDir?: string;
+            dockerfilePath?: string | null;
+            restartPolicy?: string;
+            stopGraceSeconds?: number;
+        };
+    };
+}
+/** Body for `services.manifest.apply`. The manifest shape itself
+ *  comes from `@ninedeploy/schemas`'s `ninedeployManifest` parser. */
+export interface ApplyManifestInput {
+    manifest: NinedeployManifest;
+    /** `merge` (default) preserves fields the manifest omits;
+     *  `replace` is per-field (not per-row) and still leaves
+     *  unmentioned sections alone. */
+    strategy?: 'merge' | 'replace';
+}
+/**
+ * Single row from `GET /v1/databases/:id/drills`. The drill
+ * is an engine-specific smoke check (pg_restore --list,
+ * redis-check-rdb, mysqldump header parse, ...) that proves
+ * a backup is at least parseable without spinning up a real
+ * database container. `details` is the engine-specific
+ * output (object counts, banner, ...).
+ */
+export interface BackupDrillResult {
+    drillId: number;
+    ok: true;
+    status: 'passed' | 'failed';
+    durationMs: number;
+    details: Record<string, unknown> | null;
+    error: string | null;
+}
+/** History row from `GET /v1/databases/:id/drills`. */
+export interface BackupDrillEntry {
+    id: number;
+    databaseId: number;
+    backupId: number;
+    status: 'pending' | 'running' | 'passed' | 'failed';
+    engine: string;
+    durationMs: number;
+    error: string | null;
+    details: Record<string, unknown> | null;
+    startedAt: number;
+    completedAt: number | null;
+}
+/**
+ * Body for `POST /v1/log-drains/search` (G-16). The
+ * search round-trips to the configured Loki drain.
+ */
+export interface LogSearchInput {
+    /** Free-text search (case-insensitive substring). */
+    query: string;
+    /** Restrict to one service. */
+    serviceId?: number;
+    /** Window length in minutes (default 15). */
+    sinceMinutes?: number;
+    /** Hard cap on returned lines (default 200, max 1000). */
+    limit?: number;
+    /** Query a specific drain. */
+    drainId?: number;
+}
+export interface LogSearchLine {
+    ts: number;
+    line: string;
+    service: string | null;
+}
+export interface LogSearchResult {
+    drain: {
+        id: number;
+        name: string;
+        type: string;
+    };
+    serviceId: number | null;
+    window: {
+        since: string;
+        until: string;
+    };
+    lines: LogSearchLine[];
+}
+/**
+ * Built-in email template names (G-30). The full set
+ * lives in `apps/server/src/lib/emailTemplates.ts`; the
+ * union here is the closed set the SDK can name. The
+ * server validates on the wire (zod enum) — a string
+ * the SDK does not know about returns 400.
+ */
+export type EmailTemplateName = 'password-reset' | 'workspace-invitation' | 'domain-transfer' | 'backup-drill-failed';
+/** One row from `GET /v1/workspaces/:wid/email-templates`. */
+export interface EmailTemplateEntry {
+    name: EmailTemplateName;
+    /** True when the workspace has an override for this name. */
+    overridden: boolean;
+    /** Override subject; null when the built-in default applies. */
+    subject: string | null;
+    /** Override text body; null when the built-in default applies. */
+    text: string | null;
+}
+/** Result of `POST /v1/workspaces/:wid/email-templates/preview`. */
+export interface EmailTemplateRender {
+    subject: string;
+    text: string;
+    /** True when the rendered text came from a tenant override. */
+    overridden: boolean;
+}
+/**
+ * Result of `GET /v1/databases/:id/pgbouncer` (and the
+ * post-mutation body of the enable / disable routes).
+ * `pooledConnectionString` is non-null only when `running`
+ * is true — a `docker inspect` failure on the sidecar
+ * reports `enabled: true, running: false` so the panel
+ * can surface the discrepancy.
+ */
+export interface PgbouncerStatus {
+    enabled: boolean;
+    containerName: string | null;
+    port: number;
+    running: boolean;
+    poolMode: string | null;
+    pooledConnectionString: string | null;
+}
+/**
+ * Single image row from `GET /v1/housekeeping/images`. Both
+ * the human-readable `size` ("1.2GB") and a parsed byte
+ * count are returned so the panel can sort without
+ * re-parsing. `inUse` is true when at least one container
+ * is currently using the image id.
+ */
+export interface ImageInfo {
+    repository: string;
+    tag: string;
+    id: string;
+    size: string;
+    sizeBytes: number;
+    createdAt: string;
+    ageHours: number;
+    dangling: boolean;
+    inUse: boolean;
+}
+/** Body for `POST /v1/housekeeping/images/prune`. The server
+ *  refuses the empty-options combination (it would delete
+ *  every image not currently in use). */
+export interface PruneImagesInput {
+    keepLast?: number;
+    olderThanHours?: number;
+    danglingOnly?: boolean;
+    dryRun?: boolean;
+}
+export interface PruneImagesResult {
+    freedBytes: number;
+    removed: string[];
+    removedLabels: string[];
+    dryRun: boolean;
+    output: string;
+}
+/**
+ * Result of `POST /v1/domains/:id/transfer` (start a
+ * transfer). The caller forwards `acceptUrl` to the target
+ * user out-of-band; the token is the only secret embedded
+ * in the URL.
+ */
+export interface StartDomainTransferResult {
+    ok: boolean;
+    transferId: number;
+    acceptUrl: string;
+    expiresAt: number;
+}
+/**
+ * Result of `GET /v1/domain-transfers/:token` (preview).
+ * `effectivelyExpired` is true when the row is still
+ * `pending` server-side but `expiresAt` is in the past;
+ * the route reports it as `expired` and refuses accept.
+ */
+export interface DomainTransferPreview {
+    id: number;
+    status: 'pending' | 'accepted' | 'cancelled' | 'expired';
+    hostname: string;
+    sourceEmail: string;
+    targetEmail: string;
+    expiresAt: number;
+    createdAt: number;
+    acceptedAt: number | null;
+    cancelledAt: number | null;
+    effectivelyExpired: boolean;
+}
+/** Body for `POST /v1/domain-transfers/:token/accept`. */
+export interface AcceptDomainTransferInput {
+    targetServiceId: number;
+}
+export interface AcceptDomainTransferResult {
+    ok: boolean;
+    transferId: number;
+    domainId: number;
+    serviceId: number;
+    hostname: string;
+}
 export interface NineDeployClientOptions {
     /** Base URL of the NineDeploy API, e.g. http://localhost:3000. */
     baseUrl: string;
@@ -65,6 +300,15 @@ export interface NineDeployClient {
         status: () => Promise<{
             initialized: boolean;
         }>;
+        /**
+         * Introspect the current bearer token. Returns the
+         * token's id (when opaque), name, scopes, expiry and
+         * the operator flag. Interactive sessions (JWT) report
+         * `scopes: ['session']`. The MCP server uses this to
+         * discover the token's authority before registering
+         * tools.
+         */
+        introspectToken: () => Promise<TokenIntrospection>;
         setup: (input: Register) => Promise<Session>;
         register: (input: Register) => Promise<Session>;
         login: (input: Login) => Promise<Session>;
@@ -107,7 +351,7 @@ export interface NineDeployClient {
         };
         me: () => Promise<PublicUser>;
         tokens: {
-            create: (input?: CreateApiToken) => Promise<CreatedApiToken>;
+            create: (input?: CreateApiTokenInput) => Promise<CreatedApiToken>;
             list: () => Promise<ApiToken[]>;
             remove: (id: number) => Promise<void>;
         };
@@ -223,6 +467,23 @@ export interface NineDeployClient {
             slug: string;
             message: string;
         }>;
+        /**
+         * `.ninedeploy` manifest endpoints. The server applies
+         * build / run / network sections to the service + build
+         * config rows (operator > manifest > DB merge semantics);
+         * routes / alerts / database reconcile happens at deploy
+         * time via the deploy pipeline and is intentionally
+         * outside this endpoint's scope.
+         */
+        manifest: {
+            /**
+             * Push a parsed manifest to the panel and reconcile it
+             * into the service. Requires the `admin` role on the
+             * service. The response echoes the diff so the CLI can
+             * render a one-shot summary without a follow-up GET.
+             */
+            apply: (serviceId: number, input: ApplyManifestInput) => Promise<ApplyManifestResult>;
+        };
     };
     labels: {
         /** `query` is appended verbatim, e.g. `?workspaceId=1`. */
@@ -244,6 +505,13 @@ export interface NineDeployClient {
             deploymentId: number;
         }>;
         list: (serviceId: number) => Promise<Deployment[]>;
+        /**
+         * Global deploy queue view: every in-flight (queued / building /
+         * deploying) deployment the caller can see, with service + project
+         * metadata. The optional `status` filter is a comma-separated token
+         * list (e.g. `?status=queued,building`).
+         */
+        queue: (query?: string) => Promise<QueueResponse>;
         rollback: (serviceId: number, deploymentId: number) => Promise<{
             deploymentId: number;
         }>;
@@ -252,6 +520,15 @@ export interface NineDeployClient {
             ok: boolean;
             status: string;
         }>;
+        /**
+         * Remove a finished deployment from history, with its build log.
+         * Refused for an in-flight deployment (cancel it first) and for the one
+         * currently serving traffic. Requires the `admin` role on the service.
+         */
+        remove: (serviceId: number, deploymentId: number) => Promise<{
+            ok: boolean;
+            id: number;
+        }>;
         /** Build-config + env-key diff against the previous deployment. */
         configDiff: (serviceId: number, deploymentId: number) => Promise<{
             deploymentId: number;
@@ -271,6 +548,257 @@ export interface NineDeployClient {
             id: number;
             ssl: boolean;
         }>;
+        /** Toggle sticky-session routing for the service (G-28). */
+        setStickySession: (serviceId: number, enabled: boolean) => Promise<{
+            id: number;
+            enabled: boolean;
+            active: boolean;
+        }>;
+        /**
+         * Start a domain transfer (G-29). The source user (admin
+         * on the source service) names the target email; the
+         * server returns a one-time `acceptUrl` to forward. The
+         * target user accepts via `acceptDomainTransfer(token,
+         * { targetServiceId })`. The transfer expires after 7
+         * days; cancelling is one call.
+         */
+        transfer: (domainId: number, input: {
+            targetEmail: string;
+        }) => Promise<StartDomainTransferResult>;
+        /**
+         * Preview a transfer by token. Does NOT require auth
+         * (the token is the secret) — the panel uses this to
+         * render the accept page to a logged-out visitor.
+         */
+        previewTransfer: (token: string) => Promise<DomainTransferPreview>;
+        /**
+         * Accept a transfer. The caller must be authenticated
+         * and the caller's email must equal the transfer's
+         * target email; the panel / CLI surfaces the preview
+         * first so the user knows what they're signing in to.
+         */
+        acceptTransfer: (token: string, input: AcceptDomainTransferInput) => Promise<AcceptDomainTransferResult>;
+        /**
+         * Cancel a pending transfer. Only the source user
+         * (or an instance operator) can cancel.
+         */
+        cancelTransfer: (token: string) => Promise<{
+            transferId: number;
+            status: 'cancelled';
+        }>;
+    };
+    domainPresets: {
+        /** Every `IDomainProvider` the running kernel has registered. */
+        list: () => Promise<{
+            providers: string[];
+        }>;
+        /**
+         * Manually create the DNS record for `hostname` via the operator's
+         * active provider. `content` is optional: when omitted the route
+         * falls back to the panel's `dns_records_content` setting, then to
+         * `detectPublicIp()`. Returns the upstream recordId so the caller
+         * can correlate.
+         */
+        apply: (input: {
+            hostname: string;
+            content?: string;
+        }) => Promise<{
+            hostname: string;
+            provider: string;
+            zone: string;
+            recordId: string;
+            type: 'A' | 'CNAME';
+            content: string;
+        }>;
+    };
+    configPresets: {
+        /** Every preset the kernel has registered. */
+        list: () => Promise<{
+            presets: string[];
+        }>;
+        /** Fetch a single preset's values + description. */
+        get: (id: string) => Promise<{
+            id: string;
+            description: string | null;
+            values: Record<string, unknown>;
+            createdAt: string;
+        }>;
+        /** Register a new preset. Throws if `id` already exists. */
+        register: (input: {
+            id: string;
+            description?: string;
+            values: Record<string, unknown>;
+        }) => Promise<{
+            ok: boolean;
+            id: string;
+            keyCount: number;
+        }>;
+        /** Write every value in the preset to the live configCenter. */
+        apply: (id: string, opts?: {
+            override?: Record<string, unknown>;
+        }) => Promise<{
+            ok: boolean;
+            id: string;
+            keyCount: number;
+            failureCount?: number;
+            failures?: Array<{
+                key: string;
+                status: 'failed';
+                reason?: string;
+            }>;
+        }>;
+        /** Unregister a preset. Does NOT undo the apply. */
+        remove: (id: string) => Promise<{
+            ok: boolean;
+            id: string;
+        }>;
+    };
+    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;
+            };
+        }>;
+    };
+    orchestrators: {
+        /** Every `IOrchestrator` the running kernel has registered. G-10 PR-A. */
+        list: () => Promise<{
+            orchestrators: Array<{
+                name: string;
+                stacks: Array<{
+                    name: string;
+                    serviceCount: number;
+                }>;
+            }>;
+        }>;
+        /** Stable snapshot of one stack. Returns `null` when the orchestrator has no record. */
+        stackStatus: (name: string) => Promise<{
+            name: string;
+            services: Array<{
+                name: string;
+                state: 'running' | 'stopped' | 'partial' | 'unknown';
+                replicas: number;
+            }>;
+            appliedAt: string;
+        } | null>;
+    };
+    branding: {
+        /** Read the four operator-overridable branding fields. G-30. */
+        get: () => Promise<{
+            logoUrl: string | null;
+            primaryColor: string | null;
+            supportEmail: string | null;
+            footerHtml: string | null;
+        }>;
+        /** Set one or more branding fields. Empty strings are stored as `null`. */
+        set: (input: {
+            logoUrl?: string | null;
+            primaryColor?: string | null;
+            supportEmail?: string | null;
+            footerHtml?: string | null;
+        }) => Promise<{
+            ok: boolean;
+        }>;
+    };
+    egress: {
+        /** Every egress IP rule across every registered driver. G-15. */
+        list: () => Promise<{
+            drivers: Array<{
+                name: string;
+                rules: Array<{
+                    selector: {
+                        projectId: number;
+                        sourceCidr?: string;
+                    };
+                    ip: string;
+                    createdAt: string;
+                }>;
+            }>;
+        }>;
+        /** Attach an egress IP to a project on the named (or first) driver. */
+        set: (input: {
+            projectId: number;
+            ip: string;
+            driver?: string;
+        }) => Promise<{
+            ok: boolean;
+            driver: string;
+            rule: {
+                selector: {
+                    projectId: number;
+                    sourceCidr?: string;
+                };
+                ip: string;
+                createdAt: string;
+            };
+        }>;
+        /** Detach the rule for a project. */
+        clear: (projectId: number) => Promise<{
+            ok: boolean;
+            driver: string;
+        }>;
+    };
+    sso: {
+        /** Every configured OIDC / SAML provider. G-22. */
+        listProviders: () => Promise<{
+            providers: Array<{
+                id: number;
+                type: 'oidc' | 'saml';
+                name: string;
+                createdAt: string;
+            }>;
+        }>;
+        /** Add a provider (OIDC issuer URL or SAML metadata URL lives in `config`). */
+        addProvider: (input: {
+            type: 'oidc' | 'saml';
+            name: string;
+            config: Record<string, unknown>;
+        }) => Promise<{
+            ok: boolean;
+            id?: number;
+            name?: string;
+            type?: 'oidc' | 'saml';
+            error?: string;
+        }>;
+        /** Remove a provider by id. */
+        removeProvider: (id: number) => Promise<{
+            ok: boolean;
+        }>;
     };
     volumes: {
         list: () => Promise<VolumeEntry[]>;
@@ -494,6 +1022,41 @@ export interface NineDeployClient {
                 error?: string;
             }>;
         };
+        /** Namecheap DNS-record auto-provisioning for added domains (G-07 PR-A). */
+        namecheap: {
+            get: () => Promise<{
+                configured: boolean;
+                apiUser: string | null;
+                clientIp: string | null;
+                hasKey: boolean;
+            }>;
+            set: (input: {
+                apiUser: string;
+                apiKey: string;
+                clientIp: string;
+            }) => Promise<{
+                ok: boolean;
+                apiUser: string;
+            }>;
+        };
+        /**
+         * Master-key rotation. `rotate` re-encrypts every stored secret onto the
+         * highest key version in `NINEDEPLOY_MASTER_KEYS`; it does NOT rewrite
+         * backup envelopes, which is what `warning` reports.
+         */
+        masterKey: {
+            get: () => Promise<{
+                activeVersion: number;
+                knownVersions: number[];
+                rotatable: boolean;
+            }>;
+            rotate: () => Promise<{
+                rotated: number;
+                activeVersion: number;
+                backupsNotRotated: number;
+                warning: string | null;
+            }>;
+        };
     };
     firewall: {
         status: () => Promise<{
@@ -556,6 +1119,19 @@ export interface NineDeployClient {
             url: string;
             expiresAt: string;
         }>;
+        /**
+         * Operator-only: grant or revoke the INSTANCE-operator flag.
+         *
+         * Not a workspace role — this is the flag that gates operator-only routes
+         * and the host-privilege boundary (PM2/compose deploys, lifecycle hooks,
+         * docker-socket templates). Creating a workspace does NOT confer it. The
+         * last remaining operator cannot be demoted.
+         */
+        setOperator: (id: number, isOperator: boolean) => Promise<{
+            ok: boolean;
+            id: number;
+            isOperator: boolean;
+        }>;
     };
     projects: {
         /** `query` is appended verbatim, e.g. `?workspaceId=2` (workspace scoping). */
@@ -600,6 +1176,7 @@ export interface NineDeployClient {
             type: string;
             eventFilter: string;
             active: boolean;
+            configJson: string | null;
             createdAt: string;
         }>>;
         createChannel: (input: {
@@ -607,6 +1184,7 @@ export interface NineDeployClient {
             type: string;
             target: string;
             eventFilter?: string;
+            configJson?: string | null;
         }) => Promise<{
             id: number;
             name: string;
@@ -617,6 +1195,7 @@ export interface NineDeployClient {
             target?: string;
             eventFilter?: string;
             active?: boolean;
+            configJson?: string | null;
         }) => Promise<{
             id: number;
             active: boolean;
@@ -708,6 +1287,38 @@ export interface NineDeployClient {
         stopStudio: (id: number) => Promise<{
             ok: boolean;
         }>;
+        /**
+         * PgBouncer sidecar (G-32). Returns the current sidecar
+         * state — `enabled` + `running` + the URL the services
+         * should connect to. Use the same call after
+         * `enablePgbouncer` / `disablePgbouncer` for a fresh
+         * read (the route returns the post-mutation status).
+         */
+        pgbouncerStatus: (id: number) => Promise<PgbouncerStatus>;
+        /**
+         * Spin up the sidecar. `port` is optional — the row's
+         * existing `pgbouncerPort` (default 6432) is used
+         * when omitted. Only `engine='postgres'` is supported;
+         * the server returns 422 for any other engine.
+         */
+        enablePgbouncer: (id: number, input?: {
+            port?: number;
+        }) => Promise<PgbouncerStatus>;
+        /** Stop + remove the sidecar and clear the row's flags. */
+        disablePgbouncer: (id: number) => Promise<PgbouncerStatus>;
+        /**
+         * Run an engine-specific smoke check against a backup
+         * file (pg_restore --list, redis-check-rdb, mysqldump
+         * header parse, ...). Returns the drill row with `status`
+         * of `passed` or `failed`; a failed drill is a real
+         * signal that the backup cannot be restored cleanly, not
+         * a warning. Requires the `member` role on the database.
+         */
+        drillBackup: (id: number, input: {
+            backupId: number;
+        }) => Promise<BackupDrillResult>;
+        /** List the most recent drills for a database, newest first. */
+        drills: (id: number) => Promise<BackupDrillEntry[]>;
     };
     attachments: {
         list: (serviceId: number) => Promise<Attachment[]>;
@@ -979,6 +1590,29 @@ export interface NineDeployClient {
         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;
+            }>;
+        };
     };
     limits: {
         setService: (serviceId: number, input: SetLimitsInput) => Promise<{
@@ -994,6 +1628,30 @@ export interface NineDeployClient {
         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[];
         }>;
@@ -1025,7 +1683,9 @@ export interface NineDeployClient {
     };
     plugins: {
         list: () => Promise<PluginListResponse>;
-        marketplace: () => Promise<MarketplaceCatalogResponse>;
+        marketplace: (opts?: {
+            refresh?: boolean;
+        }) => Promise<MarketplaceCatalogResponse>;
         install: (input: InstallPluginInput) => Promise<{
             ok: boolean;
             id: string;
@@ -1071,11 +1731,62 @@ export interface NineDeployClient {
             ok: boolean;
         }>;
         test: (id: number) => Promise<LogDrainTestResult>;
+        /**
+         * Search the configured Loki drain for `query` over
+         * the last `sinceMinutes` (default 15). The route
+         * round-trips to the drain's `url` so the upstream
+         * does the heavy lifting; this is the same shape
+         * the operator sees in the Loki Grafana panel.
+         */
+        search: (input: LogSearchInput) => Promise<LogSearchResult>;
+    };
+    /**
+     * Per-workspace email template overrides (G-30).
+     * Read-side is open to members; write-side requires the
+     * workspace's admin role. The list / preview are safe
+     * to call from a CI script; `set` / `reset` mutate the
+     * panel's outbound email and should be operator-only.
+     */
+    emailTemplates: {
+        list: (workspaceId: number) => Promise<{
+            workspaceId: number;
+            templates: EmailTemplateEntry[];
+        }>;
+        preview: (workspaceId: number, name: EmailTemplateName, vars?: Record<string, string | number | null>) => Promise<EmailTemplateRender>;
+        set: (workspaceId: number, name: EmailTemplateName, subject: string, text: string) => Promise<{
+            ok: boolean;
+        }>;
+        reset: (workspaceId: number, name: EmailTemplateName) => Promise<{
+            ok: boolean;
+        }>;
     };
     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>;
     };
     health: () => Promise<HealthStatus>;
 }