@ninedeploy/sdk 0.10.5 → 0.16.0

package/src/resources/deploys.ts

@@ -0,0 +1,161 @@
+// Client surface: deploys, webhooks, jobs, insights, ai.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  AnalyzeRepoInput,
+  WebhookCreate,
+  CreatedWebhook,
+  Deployment,
+  QueueResponse,
+  AiConfigStatus,
+  AiConfigUpdate,
+  RepoInsights,
+  TriggerDeploy,
+  Webhook,
+  ImageTransfer,
+} from '@ninedeploy/schemas';
+import type { JobKind, ScheduledJob, JobRun } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface DeploysApi {
+  deploys: {
+    /**
+     * Queue a deployment of the service's configured branch head. Answers
+     * `alreadyInProgress: true` with the in-flight deployment's id when one
+     * is already building or deploying.
+     */
+    trigger: (serviceId: number, input?: TriggerDeploy) => Promise<{ deploymentId: number; alreadyInProgress?: boolean }>;
+    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 }>;
+    /** Cancel a queued/in-flight deployment (checkpoints abort at step boundaries). */
+    cancel: (serviceId: number, deploymentId: number) => Promise<{ 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; previousDeploymentId: number | null; changed: boolean; diff: string }>;
+    /** Build log download URL (serves the raw log file as an attachment). */
+    logDownloadUrl: (serviceId: number, deploymentId: number) => string;
+    /**
+     * Promote: deploy ANOTHER service at this service's exact running
+     * commit — the staging → production lane hop. Both services must
+     * track the same repository and the caller needs `member` on both.
+     */
+    promote: (serviceId: number, targetServiceId: number) => Promise<{ ok: boolean; deploymentId: number; commitSha: string; promotedFrom: string }>;
+    // ── 0.16 T8 surfaces ──
+    /** Image transfers of one deployment (`GET /v1/deployments/:id/image-transfers`, any seat on its service). */
+    imageTransfers: (deploymentId: number) => Promise<ImageTransfer[]>;
+    // ── end 0.16 T8 ──
+  };
+  webhooks: {
+    list: (serviceId: number) => Promise<Webhook[]>;
+    create: (serviceId: number, input?: WebhookCreate) => Promise<CreatedWebhook>;
+    remove: (serviceId: number, hookId: number) => Promise<void>;
+  };
+  /**
+   * r552: aligned with apps/server/src/modules/jobs.ts — `kind` includes
+   * `'backup'`, and create/update return the full serialized job (the PATCH
+   * was typed `{ ok }`, a field the server never sent).
+   */
+  jobs: {
+    list: (serviceId: number) => Promise<ScheduledJob[]>;
+    create: (serviceId: number, input: { name: string; cron: string; kind: JobKind; command?: string; enabled?: boolean }) => Promise<ScheduledJob>;
+    update: (serviceId: number, jobId: number, input: Partial<{ name: string; cron: string; kind: JobKind; command: string; enabled: boolean }>) => Promise<ScheduledJob>;
+    remove: (serviceId: number, jobId: number) => Promise<{ ok: boolean }>;
+    run: (serviceId: number, jobId: number) => Promise<{ ok: boolean }>;
+    runs: (serviceId: number, jobId: number) => Promise<JobRun[]>;
+  };
+  insights: {
+    /** Pre-deploy repository inspection (DeployWizard): clone + framework detection. */
+    analyze: (input: AnalyzeRepoInput) => Promise<RepoInsights>;
+    /** Latest stored analysis for a service (null before the first deploy/refresh). */
+    get: (serviceId: number) => Promise<RepoInsights | null>;
+    /** Re-analyze the service's repository now and store the result. */
+    refresh: (serviceId: number) => Promise<RepoInsights>;
+  };
+  /** AI failure diagnosis (BYO-key): operator-configured, OpenAI-compatible. */
+  ai: {
+    /** Never carries key material — only endpoint/model + hasApiKey. */
+    getConfig: () => Promise<AiConfigStatus>;
+    updateConfig: (input: AiConfigUpdate) => Promise<{ ok: boolean }>;
+    /** Ask the configured provider to diagnose a failed build log. */
+    diagnose: (serviceId: number, deploymentId: number) => Promise<{ diagnosis: string; model: string }>;
+    /** Describe the app in plain language, get a schema-valid .ninedeploy manifest. */
+    suggestManifest: (description: string) => Promise<{ manifest: Record<string, unknown>; model: string }>;
+  };
+}
+
+export function deploysApi(t: Transport): DeploysApi {
+  const { get, send, request } = t;
+  return {
+    deploys: {
+      trigger: (serviceId, input) =>
+        send<{ deploymentId: number; alreadyInProgress?: boolean }>('POST', `/v1/services/${serviceId}/deploys`, input ?? {}),
+      list: (serviceId) => get<Deployment[]>(`/v1/services/${serviceId}/deploys`),
+      queue: (query) =>
+        get<QueueResponse>(`/v1/services/queue${query ? (query.startsWith('?') ? query : `?${query}`) : ''}`),
+      rollback: (serviceId, deploymentId) =>
+        send<{ deploymentId: number }>('POST', `/v1/services/${serviceId}/deploys/${deploymentId}/rollback`),
+      cancel: (serviceId, deploymentId) =>
+        send<{ ok: boolean; status: string }>('POST', `/v1/services/${serviceId}/deploys/${deploymentId}/cancel`),
+      remove: (serviceId, deploymentId) =>
+        send<{ ok: boolean; id: number }>('DELETE', `/v1/services/${serviceId}/deploys/${deploymentId}`),
+      configDiff: (serviceId, deploymentId) =>
+        get<{ deploymentId: number; previousDeploymentId: number | null; changed: boolean; diff: string }>(
+          `/v1/services/${serviceId}/deploys/${deploymentId}/diff`,
+        ),
+      promote: (serviceId, targetServiceId) =>
+        send<{ ok: boolean; deploymentId: number; commitSha: string; promotedFrom: string }>(
+          'POST',
+          `/v1/services/${serviceId}/promote`,
+          { targetServiceId },
+        ),
+      logDownloadUrl: (serviceId, deploymentId) =>
+        `/v1/services/${serviceId}/deploys/${deploymentId}/logs/download`,
+      // ── 0.16 T8 surfaces ──
+      imageTransfers: (deploymentId) => get<ImageTransfer[]>(`/v1/deployments/${deploymentId}/image-transfers`),
+      // ── end 0.16 T8 ──
+    },
+    webhooks: {
+      list: (serviceId) => get<Webhook[]>(`/v1/services/${serviceId}/webhooks`),
+      create: (serviceId, input) => send<CreatedWebhook>('POST', `/v1/services/${serviceId}/webhooks`, input ?? {}),
+      remove: async (serviceId, hookId) => {
+        await request(`/v1/services/${serviceId}/webhooks/${hookId}`, { method: 'DELETE' });
+      },
+    },
+    jobs: {
+      list: (serviceId) => get(`/v1/services/${serviceId}/jobs`),
+      create: (serviceId, input) => send<ScheduledJob>('POST', `/v1/services/${serviceId}/jobs`, input),
+      update: (serviceId, jobId, input) => send<ScheduledJob>('PATCH', `/v1/services/${serviceId}/jobs/${jobId}`, input),
+      remove: (serviceId, jobId) => send<{ ok: boolean }>('DELETE', `/v1/services/${serviceId}/jobs/${jobId}`),
+      run: (serviceId, jobId) => send<{ ok: boolean }>('POST', `/v1/services/${serviceId}/jobs/${jobId}/run`),
+      runs: (serviceId, jobId) => get(`/v1/services/${serviceId}/jobs/${jobId}/runs`),
+    },
+    insights: {
+      analyze: (input) => send<RepoInsights>('POST', '/v1/insights', input),
+      get: (serviceId) => get<RepoInsights | null>(`/v1/services/${serviceId}/insights`),
+      refresh: (serviceId) => send<RepoInsights>('POST', `/v1/services/${serviceId}/insights/refresh`),
+    },
+    ai: {
+      getConfig: () => get<AiConfigStatus>('/v1/ai/config'),
+      updateConfig: (input) => send<{ ok: boolean }>('PUT', '/v1/ai/config', input),
+      diagnose: (serviceId, deploymentId) =>
+        send<{ diagnosis: string; model: string }>(
+          'POST',
+          `/v1/ai/services/${serviceId}/deploys/${deploymentId}/diagnose`,
+        ),
+      suggestManifest: (description) =>
+        send<{ manifest: Record<string, unknown>; model: string }>('POST', '/v1/ai/suggest-manifest', { description }),
+    },
+  };
+}

package/src/resources/domains.ts

@@ -0,0 +1,142 @@
+// Client surface: domains, domainPresets.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  CreateDomainInput,
+  Domain,
+  DomainPatch,
+  DomainEntry,
+} from '@ninedeploy/schemas';
+import type { CreatedDomain, DomainVerifyResult, StartDomainTransferResult, DomainTransferPreview, AcceptDomainTransferInput, AcceptDomainTransferResult } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface DomainsApi {
+  domains: {
+    list: (serviceId: number) => Promise<Domain[]>;
+    /** Add a domain. A non-operator's hostname outside the instance zone comes back `pending` with a TXT `verification` challenge. */
+    create: (serviceId: number, input: CreateDomainInput) => Promise<CreatedDomain>;
+    /**
+     * r332: prove ownership of a `pending` domain and bring it live. Checks
+     * the TXT challenge `create` returned; idempotent (an `active` domain
+     * answers `verified: true`) and safe to poll while DNS propagates.
+     */
+    verify: (serviceId: number, domainId: number) => Promise<DomainVerifyResult>;
+    remove: (serviceId: number, domainId: number) => Promise<void>;
+    /**
+     * DNS status for a domain: does the hostname resolve to the addresses
+     * this panel expects? Advisory — routing is governed by ownership.
+     */
+    dnsCheck: (
+      serviceId: number,
+      domainId: number,
+    ) => Promise<{
+      hostname: string;
+      status: 'ok' | 'mismatch' | 'unresolved';
+      addresses: { a: string[]; aaaa: string[] };
+      expected: string[];
+    }>;
+    /** Update routing extras: ssl toggle, www→apex redirect, custom headers, basicAuth, ipAllowlist, rateLimit. */
+    update: (serviceId: number, domainId: number, input: DomainPatch) => Promise<Domain>;
+    all: () => Promise<DomainEntry[]>;
+    setSsl: (domainId: number, ssl: boolean) => Promise<{ 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;
+    }>;
+  };
+}
+
+export function domainsApi(t: Transport): DomainsApi {
+  const { get, send, request } = t;
+  return {
+    domains: {
+      list: (serviceId) => get<Domain[]>(`/v1/services/${serviceId}/domains`),
+      create: (serviceId, input) => send<CreatedDomain>('POST', `/v1/services/${serviceId}/domains`, input),
+      verify: (serviceId, domainId) =>
+        send<DomainVerifyResult>('POST', `/v1/services/${serviceId}/domains/${domainId}/verify`, {}),
+      dnsCheck: (serviceId, domainId) =>
+        get<{
+          hostname: string;
+          status: 'ok' | 'mismatch' | 'unresolved';
+          addresses: { a: string[]; aaaa: string[] };
+          expected: string[];
+        }>(`/v1/services/${serviceId}/domains/${domainId}/dns`),
+      update: (serviceId, domainId, input) =>
+        send<Domain>('PATCH', `/v1/services/${serviceId}/domains/${domainId}`, input),
+      remove: async (serviceId, domainId) => {
+        await request(`/v1/services/${serviceId}/domains/${domainId}`, { method: 'DELETE' });
+      },
+      all: () => get<DomainEntry[]>('/v1/domains'),
+      setSsl: (domainId, ssl) => send<{ id: number; ssl: boolean }>('PATCH', `/v1/domains/${domainId}`, { ssl }),
+      /** Toggle sticky-session routing (G-28) — sits under `/domains` for legacy compatibility. */
+      setStickySession: (serviceId, enabled) =>
+        send<{ id: number; enabled: boolean; active: boolean }>(
+          'POST',
+          `/v1/services/${serviceId}/sticky-session`,
+          { enabled },
+        ),
+      transfer: (domainId, input) =>
+        send<StartDomainTransferResult>('POST', `/v1/domains/${domainId}/transfer`, input),
+      previewTransfer: (token) => get<DomainTransferPreview>(`/v1/domain-transfers/${token}`),
+      acceptTransfer: (token, input) =>
+        send<AcceptDomainTransferResult>('POST', `/v1/domain-transfers/${token}/accept`, input),
+      cancelTransfer: (token) =>
+        send<{ transferId: number; status: 'cancelled' }>('POST', `/v1/domain-transfers/${token}/cancel`, {}),
+    },
+    domainPresets: {
+      list: () => get<{ providers: string[] }>('/v1/domain-presets'),
+      apply: (input) => send<{
+        hostname: string;
+        provider: string;
+        zone: string;
+        recordId: string;
+        type: 'A' | 'CNAME';
+        content: string;
+      }>('POST', '/v1/domain-presets/apply', input),
+    },
+  };
+}

package/src/resources/env.ts

@@ -0,0 +1,84 @@
+// Client surface: env, projectEnv, previewEnv.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  EnvVar,
+  UpsertEnvVarInput,
+} from '@ninedeploy/schemas';
+import type { Transport } from '../transport.js';
+
+export interface EnvApi {
+  env: {
+    list: (serviceId: number) => Promise<EnvVar[]>;
+    create: (serviceId: number, input: UpsertEnvVarInput) => Promise<EnvVar>;
+    update: (serviceId: number, varId: number, input: UpsertEnvVarInput) => Promise<EnvVar>;
+    remove: (serviceId: number, varId: number) => Promise<void>;
+    /** Bulk import from a .env-formatted string. Returns imported/skipped counts. */
+    import: (serviceId: number, content: string) => Promise<{ imported: number; skipped: number; errors: Array<{ line: number; message: string }> }>;
+    /** Export non-secret env vars as a .env-formatted string (admin floor). */
+    export: (serviceId: number) => Promise<{ content: string; count: number }>;
+    /** Cross-scope key search: where a given env key is defined. */
+    search: (q: string) => Promise<{ results: Array<{ key: string; isSecret: boolean; scope: string; serviceId: number | null; serviceName: string | null }> }>;
+  };
+  projectEnv: {
+    /** Shared env vars applied to every service in a project (service env wins). */
+    list: (projectId: number) => Promise<EnvVar[]>;
+    create: (projectId: number, input: UpsertEnvVarInput) => Promise<EnvVar>;
+    update: (projectId: number, varId: number, input: UpsertEnvVarInput) => Promise<EnvVar>;
+    remove: (projectId: number, varId: number) => Promise<void>;
+  };
+  /**
+   * 0.12 preview-only env: values a service hands ONLY to its PR previews
+   * (they override the parent's non-secret values there; production never
+   * sees them). Same floors as `env`: viewer reads, member writes. A panel
+   * older than 0.12 answers 404.
+   */
+  previewEnv: {
+    list: (serviceId: number) => Promise<EnvVar[]>;
+    create: (serviceId: number, input: UpsertEnvVarInput) => Promise<EnvVar>;
+    update: (serviceId: number, varId: number, input: UpsertEnvVarInput) => Promise<EnvVar>;
+    remove: (serviceId: number, varId: number) => Promise<void>;
+  };
+}
+
+export function envApi(t: Transport): EnvApi {
+  const { get, send, request } = t;
+  return {
+    env: {
+      list: (serviceId) => get<EnvVar[]>(`/v1/services/${serviceId}/env`),
+      create: (serviceId, input) => send<EnvVar>('POST', `/v1/services/${serviceId}/env`, input),
+      update: (serviceId, varId, input) => send<EnvVar>('PATCH', `/v1/services/${serviceId}/env/${varId}`, input),
+      remove: async (serviceId, varId) => {
+        await request(`/v1/services/${serviceId}/env/${varId}`, { method: 'DELETE' });
+      },
+      import: (serviceId, content) =>
+        send<{ imported: number; skipped: number; errors: Array<{ line: number; message: string }> }>(
+          'POST',
+          `/v1/services/${serviceId}/env/import`,
+          { content },
+        ),
+      export: (serviceId) =>
+        get<{ content: string; count: number }>(`/v1/services/${serviceId}/env/export`),
+      search: (q) =>
+        get<{ results: Array<{ key: string; isSecret: boolean; scope: string; serviceId: number | null; serviceName: string | null }> }>(
+          `/v1/env/search?q=${encodeURIComponent(q)}`,
+        ),
+    },
+    projectEnv: {
+      list: (projectId) => get<EnvVar[]>(`/v1/projects/${projectId}/env`),
+      create: (projectId, input) => send<EnvVar>('POST', `/v1/projects/${projectId}/env`, input),
+      update: (projectId, varId, input) => send<EnvVar>('PATCH', `/v1/projects/${projectId}/env/${varId}`, input),
+      remove: async (projectId, varId) => {
+        await request(`/v1/projects/${projectId}/env/${varId}`, { method: 'DELETE' });
+      },
+    },
+    previewEnv: {
+      list: (serviceId) => get<EnvVar[]>(`/v1/services/${serviceId}/env/preview`),
+      create: (serviceId, input) => send<EnvVar>('POST', `/v1/services/${serviceId}/env/preview`, input),
+      update: (serviceId, varId, input) => send<EnvVar>('PATCH', `/v1/services/${serviceId}/env/preview/${varId}`, input),
+      remove: async (serviceId, varId) => {
+        await request(`/v1/services/${serviceId}/env/preview/${varId}`, { method: 'DELETE' });
+      },
+    },
+  };
+}

package/src/resources/logs.ts

@@ -0,0 +1,48 @@
+// Client surface: logDrains.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  LogDrain,
+  LogDrainCreateInput,
+  LogDrainUpdateInput,
+  LogDrainTestResult,
+} from '@ninedeploy/schemas';
+import type { LogSearchInput, LogSearchResult } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface LogsApi {
+  logDrains: {
+    list: (query?: { serviceId?: number }) => Promise<LogDrain[]>;
+    get: (id: number) => Promise<LogDrain>;
+    create: (input: LogDrainCreateInput) => Promise<LogDrain>;
+    update: (id: number, input: LogDrainUpdateInput) => Promise<LogDrain>;
+    remove: (id: number) => Promise<{ 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>;
+  };
+}
+
+export function logsApi(t: Transport): LogsApi {
+  const { get, send } = t;
+  return {
+    logDrains: {
+      list: (query) => {
+        const qs = query?.serviceId !== undefined ? `?serviceId=${encodeURIComponent(String(query.serviceId))}` : '';
+        return get<LogDrain[]>(`/v1/log-drains${qs}`);
+      },
+      get: (id) => get<LogDrain>(`/v1/log-drains/${id}`),
+      create: (input) => send<LogDrain>('POST', '/v1/log-drains', input),
+      update: (id, input) => send<LogDrain>('PATCH', `/v1/log-drains/${id}`, input),
+      remove: (id) => send<{ ok: boolean }>('DELETE', `/v1/log-drains/${id}`),
+      test: (id) => send<LogDrainTestResult>('POST', `/v1/log-drains/${id}/test`),
+      search: (input) => send<LogSearchResult>('POST', '/v1/log-drains/search', input),
+    },
+  };
+}

package/src/resources/network.ts

@@ -0,0 +1,126 @@
+// Client surface: networks, tunnels, firewall, egress.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  CreateTunnelInput,
+  TunnelEntry,
+} from '@ninedeploy/schemas';
+import type { Transport } from '../transport.js';
+
+export interface NetworkApi {
+  networks: {
+    list: () => Promise<{
+      networks: Array<{
+        name: string;
+        driver: string;
+        members: string[];
+        /** True when the network is reserved by NineDeploy (cannot be removed). */
+        isManaged?: boolean;
+      }>;
+      remote: number | null;
+    }>;
+    create: (input: { name: string; driver?: 'bridge' | 'overlay'; serverId?: number | null }) => Promise<{ ok: boolean; name: string }>;
+    remove: (name: string, serverId?: number) => Promise<{ ok: boolean }>;
+    attach: (input: { network: string; container: string; serverId?: number | null }) => Promise<{ ok: boolean }>;
+    detach: (input: { network: string; container: string; serverId?: number | null }) => Promise<{ ok: boolean }>;
+    /**
+     * r557: container names attached to one network (operator-only). The
+     * server answers `{ members: [] }` when docker cannot inspect it.
+     */
+    members: (name: string) => Promise<{ members: string[] }>;
+  };
+  tunnels: {
+    list: () => Promise<TunnelEntry[]>;
+    create: (input: CreateTunnelInput) => Promise<TunnelEntry>;
+    remove: (id: number) => Promise<void>;
+  };
+  firewall: {
+    status: () => Promise<{
+      installed: boolean;
+      active: boolean;
+      supported: boolean;
+      rules: Array<{ id: number; to: string; action: string; from: string; comment?: string }>;
+      defaultIncoming: string;
+      defaultOutgoing: string;
+    }>;
+    toggle: (enabled: boolean) => Promise<{ ok: boolean; status: any }>;
+    addRule: (input: { port: number | string; proto?: 'tcp' | 'udp' | 'any'; action?: 'allow' | 'deny' | 'limit'; from?: string; comment?: string }) => Promise<{ ok: boolean; status: any }>;
+    deleteRule: (id: number | string) => Promise<{ ok: boolean; status: any }>;
+    applyRecommended: () => Promise<{ ok: boolean; status: any }>;
+  };
+  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 };
+      /** Present (with `ok: false`) when the route refused the request. */
+      error?: string;
+    }>;
+    /** Detach the rule for a project (on the named or first driver). */
+    clear: (projectId: number, driver?: string) => Promise<{ ok: boolean; driver: string; error?: string }>;
+  };
+}
+
+export function networkApi(t: Transport): NetworkApi {
+  const { get, send, request } = t;
+  return {
+    networks: {
+      list: () => get<{ networks: Array<{ name: string; driver: string; members: string[] }>; remote: number | null }>('/v1/networks'),
+      create: (input) => send<{ ok: boolean; name: string }>('POST', '/v1/networks', { driver: 'bridge', ...input }),
+      remove: (name, serverId) =>
+        send<{ ok: boolean }>('DELETE', `/v1/networks/${encodeURIComponent(name)}${serverId != null ? `?serverId=${serverId}` : ''}`),
+      attach: (input) => send<{ ok: boolean }>('POST', '/v1/networks/attach', input),
+      detach: (input) => send<{ ok: boolean }>('POST', '/v1/networks/detach', input),
+      members: (name) => get<{ members: string[] }>(`/v1/networks/${encodeURIComponent(name)}/members`),
+    },
+    tunnels: {
+      list: () => get<TunnelEntry[]>('/v1/tunnels'),
+      create: (input) => send<TunnelEntry>('POST', '/v1/tunnels', input),
+      remove: async (id) => {
+        await request(`/v1/tunnels/${id}`, { method: 'DELETE' });
+      },
+    },
+    firewall: {
+      status: () => get<any>('/v1/firewall'),
+      toggle: (enabled) => send<any>('POST', '/v1/firewall/toggle', { enabled }),
+      addRule: (input) => send<any>('POST', '/v1/firewall/rules', input),
+      deleteRule: (id) => request(`/v1/firewall/rules/${id}`, { method: 'DELETE' }),
+      applyRecommended: () => send<any>('POST', '/v1/firewall/recommended'),
+    },
+    egress: {
+      list: () => get<{
+        drivers: Array<{
+          name: string;
+          rules: Array<{
+            selector: { projectId: number; sourceCidr?: string };
+            ip: string;
+            createdAt: string;
+          }>;
+        }>;
+      }>('/v1/egress'),
+      set: (input) => send<{
+        ok: boolean;
+        driver: string;
+        rule: { selector: { projectId: number; sourceCidr?: string }; ip: string; createdAt: string };
+        error?: string;
+      }>('POST', '/v1/egress', input),
+      clear: (projectId, driver) =>
+        send<{ ok: boolean; driver: string; error?: string }>(
+          'DELETE',
+          `/v1/egress/${projectId}${driver ? `?driver=${encodeURIComponent(driver)}` : ''}`,
+        ),
+    },
+  };
+}

package/src/resources/plugins.ts

@@ -0,0 +1,52 @@
+// Client surface: plugins, menus.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  PluginListResponse,
+  PluginInspectResponse,
+  InstallPluginInput,
+  MarketplaceCatalogResponse,
+  MenuListResponse,
+} from '@ninedeploy/schemas';
+import type { Transport } from '../transport.js';
+
+export interface PluginsApi {
+  plugins: {
+    list: () => Promise<PluginListResponse>;
+    marketplace: (opts?: { refresh?: boolean }) => Promise<MarketplaceCatalogResponse>;
+    install: (input: InstallPluginInput) => Promise<{ ok: boolean; id: string; status: string }>;
+    enable: (id: string) => Promise<{ ok: boolean; id: string; status: string }>;
+    disable: (id: string) => Promise<{ ok: boolean; id: string; status: string }>;
+    reload: (id: string) => Promise<{ ok: boolean; id: string; status: string }>;
+    inspect: (id: string) => Promise<PluginInspectResponse>;
+    uninstall: (id: string) => Promise<{ ok: boolean; id: string }>;
+  };
+  menus: {
+    list: (query?: { slot?: string }) => Promise<MenuListResponse>;
+  };
+}
+
+export function pluginsApi(t: Transport): PluginsApi {
+  const { get, send } = t;
+  return {
+    plugins: {
+      list: () => get<PluginListResponse>('/v1/plugins'),
+      marketplace: (opts) =>
+        get<MarketplaceCatalogResponse>(
+          `/v1/plugins/marketplace${opts?.refresh ? '?refresh=true' : ''}`,
+        ),
+      install: (input) => send<{ ok: boolean; id: string; status: string }>('POST', '/v1/plugins/install', input),
+      enable: (id) => send<{ ok: boolean; id: string; status: string }>('POST', `/v1/plugins/${encodeURIComponent(id)}/enable`),
+      disable: (id) => send<{ ok: boolean; id: string; status: string }>('POST', `/v1/plugins/${encodeURIComponent(id)}/disable`),
+      reload: (id) => send<{ ok: boolean; id: string; status: string }>('POST', `/v1/plugins/${encodeURIComponent(id)}/reload`),
+      inspect: (id) => get<PluginInspectResponse>(`/v1/plugins/${encodeURIComponent(id)}/inspect`),
+      uninstall: (id) => send<{ ok: boolean; id: string }>('POST', `/v1/plugins/${encodeURIComponent(id)}/uninstall`),
+    },
+    menus: {
+      list: (query) => {
+        const qs = query?.slot ? `?slot=${encodeURIComponent(query.slot)}` : '';
+        return get<MenuListResponse>(`/v1/menus${qs}`);
+      },
+    },
+  };
+}