@meowpanel/api 0.2.0 → 0.4.0

package/script/src/resources/eggs.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EggsNamespace = exports.Egg = exports.EggNest = void 0;
+exports.EggsNamespace = exports.EggFeaturesManager = exports.EggImagesManager = exports.EggVariablesManager = exports.EggNestsManager = exports.Egg = exports.EggVariable = exports.EggNest = void 0;
 const namespace_js_1 = require("../namespace.js");
 const reactive_js_1 = require("../reactive.js");
 const types_js_1 = require("../types.js");
@@ -10,8 +10,6 @@ const types_js_1 = require("../types.js");
 class EggNest extends reactive_js_1.ReactiveResource {
     /** Unique NanoID of this nest. */
     id;
-    /** The issuer type. */
-    issuerType;
     /** Display name of the nest, e.g. `"Minecraft"`. */
     name;
     /** Description of the nest. */
@@ -24,7 +22,6 @@ class EggNest extends reactive_js_1.ReactiveResource {
     constructor(data) {
         super();
         this.id = (0, types_js_1.toNanoID)(data.id);
-        this.issuerType = data.issuer_type;
         this.name = data.name;
         this.description = data.description;
         this.createdAt = new Date(data.created_at);
@@ -32,6 +29,60 @@ class EggNest extends reactive_js_1.ReactiveResource {
     }
 }
 exports.EggNest = EggNest;
+function makeEggImage(data) {
+    return {
+        id: (0, types_js_1.toNanoID)(data.id),
+        name: data.name,
+        image: data.image,
+        createdAt: new Date(data.created_at),
+        updatedAt: new Date(data.updated_at),
+    };
+}
+/**
+ * An egg environment variable.
+ *
+ * Retrieved via {@link EggVariablesManager.list} or {@link EggVariablesManager.get}.
+ */
+class EggVariable extends reactive_js_1.ReactiveResource {
+    /** The variable's unique NanoID. */
+    id;
+    /** Display name, e.g. `"Server Jar File"`. */
+    name;
+    /** Description shown to the user. */
+    description;
+    /** The environment variable name, e.g. `"SERVER_JARFILE"`. */
+    envVariable;
+    /** The default value. */
+    defaultValue;
+    /** Whether the value is visible to the server user. */
+    userViewable;
+    /** Whether the server user may change the value. */
+    userEditable;
+    /** Validation rules string, e.g. `"required|string"`. */
+    rules;
+    /** When this variable was created. */
+    createdAt;
+    /** When this variable was last updated. */
+    updatedAt;
+    /** @internal */
+    constructor(data) {
+        super();
+        this.id = (0, types_js_1.toNanoID)(data.id);
+        this.name = data.name;
+        this.description = data.description;
+        this.envVariable = data.env_variable;
+        this.defaultValue = data.default_value;
+        this.userViewable = data.user_viewable;
+        this.userEditable = data.user_editable;
+        this.rules = data.rules;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+    }
+}
+exports.EggVariable = EggVariable;
+function makeFeatureGrant(data) {
+    return { name: data.name, defaultEnabled: data.default_enabled, locked: data.locked, obsolete: data.obsolete };
+}
 /**
  * An egg - a game or application configuration template that defines how a server
  * is installed, started, and stopped.
@@ -41,8 +92,6 @@ exports.EggNest = EggNest;
 class Egg extends reactive_js_1.ReactiveResource {
     /** The egg's unique NanoID. */
     id;
-    /** The issuer type. */
-    issuerType;
     /** Display name of the egg, e.g. `"Vanilla Minecraft"`. */
     name;
     /** Description of the egg. */
@@ -63,11 +112,13 @@ class Egg extends reactive_js_1.ReactiveResource {
     stopCommand;
     /** When `true`, the server's outgoing IP is forced to match the allocation IP. */
     forceOutgoingIp;
-    /** Installer configuration for this egg. */
+    /** URL of the egg's background image. Requires `?include=app_background_url`. */
+    appBackgroundUrl;
+    /** Installer configuration for this egg. Requires `?include=installer`. */
     installer;
-    /** Process configuration (startup, stop, logging). */
+    /** Process configuration. Requires `?include=process` and `egg.config.process.read`. */
     process;
-    /** Docker image variants for this egg. */
+    /** Docker image variants for this egg. Requires `?include=images`. */
     images;
     /** When this egg was created. */
     createdAt;
@@ -77,7 +128,6 @@ class Egg extends reactive_js_1.ReactiveResource {
     constructor(data) {
         super();
         this.id = (0, types_js_1.toNanoID)(data.id);
-        this.issuerType = data.issuer_type;
         this.name = data.name;
         this.description = data.description;
         this.nestId = (0, types_js_1.toNanoID)(data.nest_id);
@@ -85,6 +135,7 @@ class Egg extends reactive_js_1.ReactiveResource {
         this.startupCommand = data.startup_command;
         this.stopCommand = data.stop_command;
         this.forceOutgoingIp = data.force_outgoing_ip;
+        this.appBackgroundUrl = data.app_background_url;
         this.installer = data.installer
             ? {
                 image: data.installer.image,
@@ -101,18 +152,163 @@ class Egg extends reactive_js_1.ReactiveResource {
                 fileBlacklistRegex: data.process.file_blacklist_regex,
             }
             : data.process;
-        this.images = data.images?.map((img) => ({
-            id: (0, types_js_1.toNanoID)(img.id),
-            name: img.name,
-            image: img.image,
-            createdAt: new Date(img.created_at),
-            updatedAt: new Date(img.updated_at),
-        }));
+        this.images = data.images?.map(makeEggImage);
         this.createdAt = new Date(data.created_at);
         this.updatedAt = new Date(data.updated_at);
     }
 }
 exports.Egg = Egg;
+function configStartupBody(startup) {
+    return { done: startup.done, user_interaction: startup.userInteraction, strip_ansi: startup.stripAnsi };
+}
+/**
+ * Manages egg nests (categories).
+ *
+ * Access via `api.eggs.nests`.
+ */
+class EggNestsManager {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /** Fetch all nests readable by the caller. */
+    async list() {
+        const data = await this.http.get('/eggs/nests');
+        return data.map((d) => new EggNest(d));
+    }
+    /** Fetch a single nest by ID. */
+    async get(id) {
+        return new EggNest(await this.http.get(`/eggs/nests/${id}`));
+    }
+    /** Create a nest. Omit `hostId` for a global nest. */
+    async create(payload) {
+        const data = await this.http.post('/eggs/nests', {
+            name: payload.name,
+            description: payload.description,
+            host_id: payload.hostId,
+        });
+        return new EggNest(data);
+    }
+    /** Update a nest's name or description. */
+    async update(id, payload) {
+        return new EggNest(await this.http.patch(`/eggs/nests/${id}`, payload));
+    }
+    /** Delete a nest. Fails if it still contains eggs. */
+    async delete(id) {
+        await this.http.delete(`/eggs/nests/${id}`);
+    }
+}
+exports.EggNestsManager = EggNestsManager;
+function variableBody(payload) {
+    return {
+        name: payload.name,
+        description: payload.description,
+        env_variable: payload.envVariable,
+        default_value: payload.defaultValue,
+        user_viewable: payload.userViewable,
+        user_editable: payload.userEditable,
+        rules: payload.rules,
+    };
+}
+/**
+ * Manages the environment variables of a specific egg.
+ *
+ * Access via `api.eggs.variables(eggId)`.
+ */
+class EggVariablesManager {
+    eggId;
+    http;
+    /** @internal */
+    constructor(eggId, http) {
+        this.eggId = eggId;
+        this.http = http;
+    }
+    /** List the egg's variables. */
+    async list() {
+        const data = await this.http.get(`/eggs/${this.eggId}/variables`);
+        return data.map((d) => new EggVariable(d));
+    }
+    /** Fetch a single variable by ID. */
+    async get(variableId) {
+        return new EggVariable(await this.http.get(`/eggs/${this.eggId}/variables/${variableId}`));
+    }
+    /** Create a variable. */
+    async create(payload) {
+        return new EggVariable(await this.http.post(`/eggs/${this.eggId}/variables`, variableBody(payload)));
+    }
+    /** Update a variable. */
+    async update(variableId, payload) {
+        return new EggVariable(await this.http.patch(`/eggs/${this.eggId}/variables/${variableId}`, variableBody(payload)));
+    }
+    /** Delete a variable. */
+    async delete(variableId) {
+        await this.http.delete(`/eggs/${this.eggId}/variables/${variableId}`);
+    }
+}
+exports.EggVariablesManager = EggVariablesManager;
+/**
+ * Manages the Docker image variants of a specific egg.
+ *
+ * Access via `api.eggs.images(eggId)`.
+ */
+class EggImagesManager {
+    eggId;
+    http;
+    /** @internal */
+    constructor(eggId, http) {
+        this.eggId = eggId;
+        this.http = http;
+    }
+    /** List the egg's images. */
+    async list() {
+        const data = await this.http.get(`/eggs/${this.eggId}/images`);
+        return data.map(makeEggImage);
+    }
+    /** Add an image to the egg. */
+    async create(payload) {
+        return makeEggImage(await this.http.post(`/eggs/${this.eggId}/images`, payload));
+    }
+    /** Remove an image. Fails if it is in use or is the egg's last image. */
+    async delete(imageId) {
+        await this.http.delete(`/eggs/${this.eggId}/images/${imageId}`);
+    }
+}
+exports.EggImagesManager = EggImagesManager;
+/**
+ * Manages the feature grants attached to a specific egg.
+ *
+ * Access via `api.eggs.features(eggId)`.
+ */
+class EggFeaturesManager {
+    eggId;
+    http;
+    /** @internal */
+    constructor(eggId, http) {
+        this.eggId = eggId;
+        this.http = http;
+    }
+    /** List the egg's feature grants. */
+    async list() {
+        const data = await this.http.get(`/eggs/${this.eggId}/features`);
+        return data.map(makeFeatureGrant);
+    }
+    /**
+     * Grant a feature on the egg, or update its policy (upsert).
+     *
+     * @param feature The feature key.
+     * @param policy  Defaults to `defaultEnabled: true`, `locked: false`.
+     */
+    async set(feature, policy = {}) {
+        const data = await this.http.put(`/eggs/${this.eggId}/features/${encodeURIComponent(feature)}`, JSON.stringify({ default_enabled: policy.defaultEnabled, locked: policy.locked }), 'application/json');
+        return makeFeatureGrant(data);
+    }
+    /** Remove a feature grant from the egg. */
+    async remove(feature) {
+        await this.http.delete(`/eggs/${this.eggId}/features/${encodeURIComponent(feature)}`);
+    }
+}
+exports.EggFeaturesManager = EggFeaturesManager;
 /**
  * Namespace for egg management.
  *
@@ -123,13 +319,16 @@ exports.Egg = Egg;
  * const eggs = await api.eggs.list();
  * const egg = await api.eggs.get(id);
  * await api.eggs.update(id, { name: 'Paper Minecraft' });
- * await api.eggs.delete(id);
+ * await api.eggs.variables(id).create({ name: 'Jar', description: '', envVariable: 'JAR', defaultValue: 'server.jar' });
  * ```
  */
 class EggsNamespace extends namespace_js_1.ResourceNamespace {
+    /** Manage egg nests (categories). */
+    nests;
     /** @internal */
     constructor(http) {
         super(http);
+        this.nests = new EggNestsManager(http);
     }
     /**
      * Fetch a paginated list of eggs.
@@ -160,6 +359,32 @@ class EggsNamespace extends namespace_js_1.ResourceNamespace {
         const data = await this.http.get(`/eggs/${id}`, { params });
         return new Egg(data);
     }
+    /** Create a new egg. */
+    async create(payload) {
+        const body = {
+            nest_id: payload.nestId,
+            name: payload.name,
+            description: payload.description,
+            startup_command: payload.startupCommand,
+            stop_command: payload.stopCommand,
+            installer: {
+                image: payload.installer.image,
+                entry_command: payload.installer.entryCommand,
+                script: payload.installer.script,
+            },
+            images: payload.images,
+            force_outgoing_ip: payload.forceOutgoingIp,
+            file_blacklist_regex: payload.fileBlacklistRegex,
+            config_files: payload.configFiles,
+            config_startup: payload.configStartup ? configStartupBody(payload.configStartup) : undefined,
+            config_logs: payload.configLogs,
+        };
+        const data = await this.http.post('/eggs', body);
+        const egg = new Egg(data);
+        this.addToCache(egg);
+        this.emit('created', egg);
+        return egg;
+    }
     /**
      * Update an egg's configuration.
      *
@@ -170,20 +395,16 @@ class EggsNamespace extends namespace_js_1.ResourceNamespace {
         const body = {};
         if (payload.name !== undefined)
             body['name'] = payload.name;
-        if (payload.description !== undefined) {
+        if (payload.description !== undefined)
             body['description'] = payload.description;
-        }
         if (payload.nestId !== undefined)
             body['nest_id'] = payload.nestId;
-        if (payload.startupCommand !== undefined) {
+        if (payload.startupCommand !== undefined)
             body['startup_command'] = payload.startupCommand;
-        }
-        if (payload.stopCommand !== undefined) {
+        if (payload.stopCommand !== undefined)
             body['stop_command'] = payload.stopCommand;
-        }
-        if (payload.forceOutgoingIp !== undefined) {
+        if (payload.forceOutgoingIp !== undefined)
             body['force_outgoing_ip'] = payload.forceOutgoingIp;
-        }
         if (payload.installer) {
             body['installer'] = {
                 image: payload.installer.image,
@@ -191,6 +412,14 @@ class EggsNamespace extends namespace_js_1.ResourceNamespace {
                 script: payload.installer.script,
             };
         }
+        if (payload.configFiles !== undefined)
+            body['config_files'] = payload.configFiles;
+        if (payload.configStartup !== undefined)
+            body['config_startup'] = configStartupBody(payload.configStartup);
+        if (payload.configLogs !== undefined)
+            body['config_logs'] = payload.configLogs;
+        if (payload.fileBlacklistRegex !== undefined)
+            body['file_blacklist_regex'] = payload.fileBlacklistRegex;
         const data = await this.http.patch(`/eggs/${id}`, body);
         const egg = new Egg(data);
         this.upsertCache(egg);
@@ -207,5 +436,17 @@ class EggsNamespace extends namespace_js_1.ResourceNamespace {
         this.removeFromCache(id);
         this.emit('deleted', id);
     }
+    /** Manage a specific egg's variables. */
+    variables(eggId) {
+        return new EggVariablesManager(eggId, this.http);
+    }
+    /** Manage a specific egg's images. */
+    images(eggId) {
+        return new EggImagesManager(eggId, this.http);
+    }
+    /** Manage a specific egg's feature grants. */
+    features(eggId) {
+        return new EggFeaturesManager(eggId, this.http);
+    }
 }
 exports.EggsNamespace = EggsNamespace;

package/script/src/resources/features.d.ts

@@ -0,0 +1,35 @@
+import type { HttpClient } from '../http.js';
+/** The variant options a feature offers. */
+export interface FeatureVariants {
+    /** The allowed variant values. */
+    options: string[];
+    /** The default variant. */
+    default: string;
+}
+/** A code-defined feature in the catalog. */
+export interface FeatureCatalogEntry {
+    /** The feature key, e.g. `"minecraft.players"`. */
+    name: string;
+    /** The feature's settings and their default values, keyed by setting name. */
+    settings: Record<string, unknown>;
+    /** The variant options, or `null` when the feature has none. */
+    variants: FeatureVariants | null;
+}
+/**
+ * The code-defined feature catalog.
+ *
+ * Access via `api.features`. Per-server feature state is managed via `server.features`.
+ *
+ * @example
+ * ```ts ignore
+ * const catalog = await api.features.list();
+ * ```
+ */
+export declare class FeaturesResource {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /** List the available features and their defaults. */
+    list(): Promise<FeatureCatalogEntry[]>;
+}
+//# sourceMappingURL=features.d.ts.map

package/script/src/resources/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../../src/src/resources/features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC/B,kCAAkC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IACnC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,gEAAgE;IAChE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAET,OAAO,CAAC,QAAQ,CAAC,IAAI;IADxC,gBAAgB;gBACoB,IAAI,EAAE,UAAU;IAEpD,sDAAsD;IAC/C,IAAI,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;CAG7C"}

package/script/src/resources/features.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeaturesResource = void 0;
+/**
+ * The code-defined feature catalog.
+ *
+ * Access via `api.features`. Per-server feature state is managed via `server.features`.
+ *
+ * @example
+ * ```ts ignore
+ * const catalog = await api.features.list();
+ * ```
+ */
+class FeaturesResource {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /** List the available features and their defaults. */
+    list() {
+        return this.http.get('/features');
+    }
+}
+exports.FeaturesResource = FeaturesResource;

package/script/src/resources/hosts.d.ts

@@ -1,48 +1,146 @@
 import type { HttpClient } from '../http.js';
 import { ResourceNamespace } from '../namespace.js';
 import { ReactiveResource } from '../reactive.js';
+import type { IncludeOptions, ResourceColor, ResourceWith } from '../types.js';
 import { type ISODate, type NanoID, type Paginated } from '../types.js';
-import type { MemberData } from './members.js';
-import { Member } from './members.js';
+import type { UserData } from './users.js';
+import { User } from './users.js';
+import { type ActivityFeedOptions, type ActivityLog } from './servers/activity.js';
 /** Raw API shape for a physical host. @internal */
 export interface HostData {
     id: string;
     hostname: string;
-    name?: string | null;
-    color?: string | null;
+    name: string;
+    color: ResourceColor | null;
     owner_id: string;
-    owner?: MemberData;
-    notes?: string | null;
+    owner?: UserData;
+    notes: string | null;
     created_at: ISODate;
     updated_at: ISODate;
+    deleted_at: ISODate | null;
 }
 /**
  * A physical host machine on which nodes are deployed.
  *
- * Retrieved via {@link HostsNamespace.list}.
+ * Retrieved via {@link HostsNamespace.list} or {@link HostsNamespace.get}.
  */
 export declare class Host extends ReactiveResource {
     /** The host's unique NanoID. */
     readonly id: NanoID;
     /** The host's hostname, e.g. `"host.example.com"`. */
     hostname: string;
-    /** Optional display name for the host. */
-    name: string | null | undefined;
-    /** Optional color used in the UI for grouping. */
-    color: string | null | undefined;
-    /** The owner's NanoID. Always present. */
+    /** Display name for the host. */
+    name: string;
+    /** Color used in the UI for grouping, or `null`. */
+    color: ResourceColor | null;
+    /** The owner's bare NanoID (parsed from the namespaced `owner_id`). Always present. */
     readonly ownerId: NanoID;
+    /** The owner's issuer type, e.g. `'user'` or `'system'`. */
+    readonly ownerType: string;
     /** The full owner object. Requires `?include=owner`. */
-    owner: Member | undefined;
+    owner: User | undefined;
     /** Internal notes. */
-    notes: string | null | undefined;
+    notes: string | null;
     /** When this host was registered. */
     createdAt: Date;
     /** When this host was last updated. */
     updatedAt: Date;
+    /** When this host was soft-deleted, or `null` if active. */
+    deletedAt: Date | null;
     /** @internal */
     constructor(data: HostData);
 }
+/** Fields accepted when creating a host. */
+export interface CreateHostPayload {
+    name: string;
+    hostname: string;
+    color?: ResourceColor;
+    notes?: string;
+}
+/** Fields accepted when updating a host. All optional. */
+export interface UpdateHostPayload {
+    name?: string;
+    hostname?: string;
+    color?: ResourceColor;
+    notes?: string;
+}
+/** Valid include keys for host endpoints. */
+export type HostInclude = 'owner';
+/** Maps each {@link HostInclude} key to the field(s) it guarantees on the {@link Host} instance. */
+interface HostIncludeMap {
+    owner: {
+        owner: User;
+    };
+}
+/** A {@link Host} with specific include fields guaranteed to be populated. */
+export type HostWith<I extends readonly HostInclude[] = []> = ResourceWith<Host, HostIncludeMap, I>;
+/** Typed events emitted by {@link HostsNamespace}. */
+export interface HostEvents {
+    created: Host;
+    updated: Host;
+    deleted: NanoID;
+}
+/** A host's WHMCS billing configuration. Credentials are never returned. */
+export interface WhmcsBillingConfig {
+    /** The WHMCS base URL. */
+    baseUrl: string;
+    /** Whether billing is enabled for this host. */
+    enabled: boolean;
+    /** Whether a Basic-Auth header is configured. The value itself is never returned. */
+    basicAuthSet: boolean;
+    /** When the config was created. */
+    createdAt: Date;
+    /** When the config was last updated. */
+    updatedAt: Date;
+}
+/** Fields accepted when saving a host's WHMCS billing config. */
+export interface SaveWhmcsBillingPayload {
+    /** The WHMCS base URL (http or https). Required on first configuration. */
+    baseUrl?: string;
+    /** WHMCS API identifier (write-only). Required on first configuration. */
+    apiIdentifier?: string;
+    /** WHMCS API secret (write-only). Required on first configuration. */
+    apiSecret?: string;
+    /** Basic-Auth header value. `null` clears it; omit to leave unchanged. */
+    basicAuthBase64?: string | null;
+    /** Enable or disable billing for this host. */
+    enabled?: boolean;
+}
+/**
+ * Manages a host's billing provider configuration.
+ *
+ * Access via `api.hosts.billing(hostId)`.
+ */
+export declare class HostBillingManager {
+    private readonly hostId;
+    private readonly http;
+    /** @internal */
+    constructor(hostId: NanoID, http: HttpClient);
+    /** Fetch all configured billing providers for this host. */
+    providers(): Promise<{
+        whmcs: WhmcsBillingConfig | null;
+    }>;
+    /**
+     * Fetch this host's WHMCS billing config.
+     *
+     * @throws {@link ApiError} with `isNotFound === true` if billing is not configured.
+     */
+    getWhmcs(): Promise<WhmcsBillingConfig>;
+    /**
+     * Save this host's WHMCS billing config. Does not call WHMCS; use {@link testWhmcs} to verify.
+     *
+     * First-time configuration requires `baseUrl`, `apiIdentifier`, and `apiSecret`.
+     */
+    saveWhmcs(payload: SaveWhmcsBillingPayload): Promise<WhmcsBillingConfig>;
+    /**
+     * Verify the stored WHMCS credentials against the live WHMCS API.
+     *
+     * @throws {@link ApiError} if billing is not configured (404) or WHMCS rejects the credentials (502).
+     */
+    testWhmcs(): Promise<void>;
+    /** Remove this host's WHMCS billing config. */
+    deleteWhmcs(): Promise<void>;
+}
 /**
  * Namespace for host management.
  *
@@ -51,20 +149,47 @@ export declare class Host extends ReactiveResource {
  * @example
  * ```ts ignore
  * const hosts = await api.hosts.list();
+ * const host = await api.hosts.create({ name: 'DC1', hostname: 'host.example.com' });
  * ```
  */
-export declare class HostsNamespace extends ResourceNamespace<Host> {
+export declare class HostsNamespace extends ResourceNamespace<Host, HostEvents> {
     /** @internal */
     constructor(http: HttpClient);
     /**
      * Fetch a paginated list of physical hosts.
      *
-     * @param opts Pagination and search options.
+     * @param opts Pagination, search, and include options. Set `includeDeleted` to also return soft-deleted hosts.
      */
-    list(opts?: {
+    list<const I extends readonly HostInclude[] = []>(opts?: {
         page?: number;
         perPage?: number;
         search?: string;
-    }): Promise<Paginated<Host>>;
+        includeDeleted?: boolean;
+    } & IncludeOptions<HostInclude, I>): Promise<Paginated<HostWith<I>>>;
+    /**
+     * Fetch a single host by ID.
+     *
+     * @param id   The host's NanoID.
+     * @param opts Include options. Set `includeDeleted` to return a soft-deleted host.
+     */
+    get<const I extends readonly HostInclude[] = []>(id: NanoID, opts?: IncludeOptions<HostInclude, I> & {
+        includeDeleted?: boolean;
+    }): Promise<HostWith<I>>;
+    /** Create a new host. The caller becomes its owner. */
+    create(payload: CreateHostPayload): Promise<Host>;
+    /** Update a host's name, hostname, color, or notes. */
+    update(id: NanoID, payload: UpdateHostPayload): Promise<Host>;
+    /** Soft-delete a host. Fails if it still owns nodes, locations, types, or nests. */
+    delete(id: NanoID): Promise<void>;
+    /** Manage a host's billing provider configuration. */
+    billing(hostId: NanoID): HostBillingManager;
+    /**
+     * Fetch a host's activity feed (activity on the host and its servers, groups, and nodes).
+     *
+     * @param hostId The host's NanoID.
+     * @param opts   Pagination and filter options.
+     */
+    activities(hostId: NanoID, opts?: ActivityFeedOptions): Promise<Paginated<ActivityLog>>;
 }
+export {};
 //# sourceMappingURL=hosts.d.ts.map