@meowpanel/api 0.1.0-alpha.11 → 1.0.0-beta.2

package/esm/src/resources/servers/server.d.ts

@@ -0,0 +1,136 @@
+import type { HttpClient } from '../../http.js';
+import { ReactiveResource } from '../../reactive.js';
+import type { NanoID, PowerSignal, PowerState, ServerRestrictedState } from '../../types.js';
+import { Egg } from '../eggs.js';
+import { ServerGroup } from '../server-groups.js';
+import { ServerActivityManager } from './activity.js';
+import { ServerAllocationsManager } from './allocations.js';
+import { ServerConnection } from './connection.js';
+import { ServerFilesManager } from './files.js';
+import { ServerProfilesManager } from './profiles.js';
+import { ServerSftpManager } from './sftp.js';
+import type { ServerAllocationsData, ServerData, UpdateServerPayload } from './types.js';
+/** An egg environment variable configured for a server. */
+export interface StartupVariable {
+    key: string;
+    name: string;
+    description: string;
+    value: string;
+    default: string;
+    /** Laravel validation rules, e.g. `"required|numeric|min:1"`. */
+    rules: string;
+}
+/** Real-time power state and utilization. Populated via `include=status`. */
+export interface ServerStatus {
+    state: PowerState;
+    /** `null` when the server is offline. */
+    utilization: {
+        memoryBytes: number;
+        memoryLimitBytes: number;
+        cpuAbsolute: number;
+        networkRxBytes: number;
+        networkTxBytes: number;
+        uptimeSeconds: number;
+        diskBytes: number;
+    } | null;
+}
+/** Build and resource limit configuration. Populated via `include=build`. */
+export interface ServerBuild {
+    cpuThreads: number | null | undefined;
+    /** Block IO weight (1–1000). */
+    ioWeight: number | null | undefined;
+    /** `null` disables the OOM killer. */
+    oomType: string | null | undefined;
+    skipInstallScripts: boolean | undefined;
+    limits: {
+        cpuPercent: number | null | undefined;
+        ramMb: number | null | undefined;
+        swapMb: number | null | undefined;
+        storageMb: number | null | undefined;
+        allocation: number | null | undefined;
+        database: number | null | undefined;
+        backup: number | null | undefined;
+    } | null | undefined;
+}
+/** Startup command and egg variables. Populated via `include=startup`. */
+export interface ServerStartup {
+    command: string;
+    variables: Record<string, StartupVariable>;
+}
+/**
+ * A MeowPanel game server.
+ *
+ * @example
+ * ```ts ignore
+ * const server = await api.servers.get(id, { include: ['status', 'startup'] });
+ * server.status; // ServerStatus (guaranteed by include)
+ *
+ * await server.sendPower('start');
+ * await server.sendCommand('say Hello!');
+ *
+ * const conn = await server.createConnection();
+ * conn.on('console_output', (line) => console.log(line));
+ * await conn.open();
+ * ```
+ */
+export declare class Server extends ReactiveResource {
+    private readonly http;
+    private readonly resolveNodeUrl;
+    private readonly onMutated;
+    readonly id: NanoID;
+    name: string;
+    description: string | null;
+    /** Only visible with `server.notes.read` permission. */
+    notes: string | null | undefined;
+    /** When non-null, overrides the node's reported power state for display. */
+    restrictedState: ServerRestrictedState;
+    readonly groupId: NanoID;
+    readonly eggId: NanoID;
+    eggImageId: NanoID | undefined;
+    /** Populated with `include=group`. */
+    group: ServerGroup | undefined;
+    /** Populated with `include=egg`. */
+    egg: Egg | undefined;
+    eggImageOverride: string | null | undefined;
+    /** Populated with `include=status`. Use {@link getStatus} to fetch on demand. */
+    status: ServerStatus | undefined;
+    /** Populated with `include=build`. */
+    build: ServerBuild | undefined;
+    /** Populated with `include=startup`. */
+    startup: ServerStartup | undefined;
+    /** Populated with `include=allocations`. */
+    allocationPorts: ServerAllocationsData | undefined;
+    createdAt: Date;
+    updatedAt: Date;
+    readonly allocations: ServerAllocationsManager;
+    readonly sftp: ServerSftpManager;
+    readonly profiles: ServerProfilesManager;
+    readonly activity: ServerActivityManager;
+    readonly files: ServerFilesManager;
+    /** @internal */
+    constructor(data: ServerData, http: HttpClient, resolveNodeUrl: () => Promise<string>, onMutated: () => void);
+    /** Apply raw API data, updating all mutable fields. */
+    applyData(data: ServerData): void;
+    /** Update this server's details, startup config, or primary allocation. */
+    update(payload: UpdateServerPayload): Promise<void>;
+    /** Fetch current power state and utilization from the node. */
+    getStatus(): Promise<ServerStatus>;
+    /** Send a power signal: `start`, `stop`, `restart`, or `kill`. */
+    sendPower(signal: PowerSignal): Promise<void>;
+    /** Send one or more console commands. */
+    sendCommand(command: string | string[]): Promise<void>;
+    /**
+     * Create a real-time SSE connection to this server's node daemon.
+     *
+     * Not yet open - call {@link ServerConnection.open} to start streaming.
+     *
+     * @example
+     * ```ts ignore
+     * const conn = await server.createConnection();
+     * conn.on('stats', ({ cpuAbsolute }) => console.log(`CPU: ${cpuAbsolute}%`));
+     * await conn.open();
+     * ```
+     */
+    createConnection(): Promise<ServerConnection>;
+}
+//# sourceMappingURL=server.d.ts.map

package/esm/src/resources/servers/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/resources/servers/server.ts"],"names":[],"mappings":"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"}

package/esm/src/resources/servers/server.js

@@ -0,0 +1,202 @@
+import { ReactiveResource } from '../../reactive.js';
+import { toNanoID } from '../../types.js';
+import { Egg } from '../eggs.js';
+import { ServerGroup } from '../server-groups.js';
+import { ServerActivityManager } from './activity.js';
+import { ServerAllocationsManager } from './allocations.js';
+import { ServerConnection } from './connection.js';
+import { ServerFilesManager } from './files.js';
+import { ServerProfilesManager } from './profiles.js';
+import { ServerSftpManager } from './sftp.js';
+/**
+ * A MeowPanel game server.
+ *
+ * @example
+ * ```ts ignore
+ * const server = await api.servers.get(id, { include: ['status', 'startup'] });
+ * server.status; // ServerStatus (guaranteed by include)
+ *
+ * await server.sendPower('start');
+ * await server.sendCommand('say Hello!');
+ *
+ * const conn = await server.createConnection();
+ * conn.on('console_output', (line) => console.log(line));
+ * await conn.open();
+ * ```
+ */
+export class Server extends ReactiveResource {
+    http;
+    resolveNodeUrl;
+    onMutated;
+    id;
+    name;
+    description;
+    /** Only visible with `server.notes.read` permission. */
+    notes;
+    /** When non-null, overrides the node's reported power state for display. */
+    restrictedState;
+    groupId;
+    eggId;
+    eggImageId;
+    /** Populated with `include=group`. */
+    group;
+    /** Populated with `include=egg`. */
+    egg;
+    eggImageOverride;
+    /** Populated with `include=status`. Use {@link getStatus} to fetch on demand. */
+    status;
+    /** Populated with `include=build`. */
+    build;
+    /** Populated with `include=startup`. */
+    startup;
+    /** Populated with `include=allocations`. */
+    allocationPorts;
+    createdAt;
+    updatedAt;
+    allocations;
+    sftp;
+    profiles;
+    activity;
+    files;
+    /** @internal */
+    constructor(data, http, resolveNodeUrl, onMutated) {
+        super();
+        this.http = http;
+        this.resolveNodeUrl = resolveNodeUrl;
+        this.onMutated = onMutated;
+        this.id = toNanoID(data.id);
+        this.groupId = toNanoID(data.group_id);
+        this.eggId = toNanoID(data.egg_id);
+        this.allocations = new ServerAllocationsManager(this.id, http);
+        this.sftp = new ServerSftpManager(this.id, http);
+        this.profiles = new ServerProfilesManager(this.id, http);
+        this.activity = new ServerActivityManager(this.id, http);
+        this.files = new ServerFilesManager(this.id, http.getToken(), resolveNodeUrl);
+        this.applyData(data);
+    }
+    /** Apply raw API data, updating all mutable fields. */
+    applyData(data) {
+        this.name = data.name;
+        this.description = data.description;
+        this.notes = data.notes;
+        this.restrictedState = data.restricted_state;
+        this.eggImageId = data.egg_image_id ? toNanoID(data.egg_image_id) : undefined;
+        this.eggImageOverride = data.egg_image_override;
+        // Include-gated fields: only overwrite if present in response
+        if (data.group)
+            this.group = new ServerGroup(data.group);
+        if (data.egg)
+            this.egg = new Egg(data.egg);
+        if (data.status !== undefined) {
+            this.status = data.status ? parseStatus(data.status) : undefined;
+        }
+        if (data.build !== undefined) {
+            this.build = data.build ? parseBuild(data.build) : undefined;
+        }
+        if (data.startup !== undefined) {
+            this.startup = data.startup
+                ? {
+                    command: data.startup.command,
+                    variables: Object.fromEntries(Object.entries(data.startup.variables).map(([k, v]) => [
+                        k,
+                        { key: k, ...v, default: v.default },
+                    ])),
+                }
+                : undefined;
+        }
+        if (data.allocations !== undefined) {
+            this.allocationPorts = data.allocations ?? undefined;
+        }
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+        this.notify();
+    }
+    /** Update this server's details, startup config, or primary allocation. */
+    async update(payload) {
+        const body = {};
+        if (payload.name !== undefined)
+            body['name'] = payload.name;
+        if (payload.description !== undefined) {
+            body['description'] = payload.description;
+        }
+        if (payload.notes !== undefined)
+            body['notes'] = payload.notes;
+        if (payload.allocationPrimary) {
+            body['allocation_primary'] = payload.allocationPrimary;
+        }
+        if (payload.startup) {
+            body['startup'] = {
+                command: payload.startup.command,
+                variables: payload.startup.variables,
+            };
+        }
+        const data = await this.http.patch(`/servers/${this.id}`, body);
+        this.applyData(data);
+        this.onMutated();
+    }
+    /** Fetch current power state and utilization from the node. */
+    async getStatus() {
+        const data = await this.http.get(`/servers/${this.id}/status`);
+        return parseStatus(data);
+    }
+    /** Send a power signal: `start`, `stop`, `restart`, or `kill`. */
+    async sendPower(signal) {
+        await this.http.post(`/servers/${this.id}/power`, { signal });
+    }
+    /** Send one or more console commands. */
+    async sendCommand(command) {
+        const commands = Array.isArray(command) ? command : [command];
+        await this.http.post(`/servers/${this.id}/commands`, { commands });
+    }
+    /**
+     * Create a real-time SSE connection to this server's node daemon.
+     *
+     * Not yet open - call {@link ServerConnection.open} to start streaming.
+     *
+     * @example
+     * ```ts ignore
+     * const conn = await server.createConnection();
+     * conn.on('stats', ({ cpuAbsolute }) => console.log(`CPU: ${cpuAbsolute}%`));
+     * await conn.open();
+     * ```
+     */
+    async createConnection() {
+        const nodeUrl = await this.resolveNodeUrl();
+        return new ServerConnection(this.id, nodeUrl, this.http.getToken());
+    }
+}
+function parseStatus(data) {
+    return {
+        state: data.state,
+        utilization: data.utilization
+            ? {
+                memoryBytes: data.utilization.memory_bytes,
+                memoryLimitBytes: data.utilization.memory_limit_bytes,
+                cpuAbsolute: data.utilization.cpu_absolute,
+                networkRxBytes: data.utilization.network.rx_bytes,
+                networkTxBytes: data.utilization.network.tx_bytes,
+                uptimeSeconds: data.utilization.uptime,
+                diskBytes: data.utilization.disk_bytes,
+            }
+            : null,
+    };
+}
+function parseBuild(data) {
+    return {
+        cpuThreads: data.cpu_threads,
+        ioWeight: data.io_weight,
+        oomType: data.oom_type,
+        skipInstallScripts: data.skip_install_scripts,
+        limits: data.limits
+            ? {
+                cpuPercent: data.limits.cpu_percent,
+                ramMb: data.limits.ram_mb,
+                swapMb: data.limits.swap_mb,
+                storageMb: data.limits.storage_mb,
+                allocation: data.limits.allocation,
+                database: data.limits.database,
+                backup: data.limits.backup,
+            }
+            : data.limits,
+    };
+}

package/esm/src/resources/servers/sftp.d.ts

@@ -0,0 +1,147 @@
+import type { HttpClient } from '../../http.js';
+import { ReactiveResource } from '../../reactive.js';
+import type { IncludeOptions, ListOptions, NanoID, Paginated, ResourceWith, SftpPermission } from '../../types.js';
+import { Member } from '../members.js';
+import type { SftpUserData } from './types.js';
+/**
+ * Connection details for the SFTP server on a node.
+ */
+export interface SftpConnection {
+    /** Full SFTP URL, e.g. `"sftp://1.2.3.4:2022"`. */
+    url: string;
+    /** Hostname or IP of the SFTP server. */
+    fqdn: string;
+    /** Port the SFTP server listens on. */
+    port: number;
+}
+/**
+ * An SFTP user credential scoped to a specific server with path-level permissions.
+ *
+ * Retrieved via {@link ServerSftpManager.list} or {@link ServerSftpManager.create}.
+ *
+ * > **Note:** The `password` field is automatically included in the creation response.
+ * > On subsequent fetches it requires `include=password` to be populated.
+ */
+export declare class SftpUser extends ReactiveResource {
+    /** The SFTP user's unique NanoID. */
+    readonly id: NanoID;
+    /** Display name for this SFTP user. */
+    name: string;
+    /** The SFTP login username (typically prefixed with the server ID). */
+    username: string;
+    /**
+     * The plaintext password.
+     *
+     * Automatically included on creation. Requires `include=password` on subsequent fetches.
+     */
+    password: string | undefined;
+    /**
+     * A map of path glob patterns to the set of permissions granted for that path.
+     *
+     * Keys are glob patterns (e.g. `"/"`, `"/logs/*"`).
+     * Values are arrays of {@link SftpPermission} scopes.
+     */
+    paths: Record<string, SftpPermission[]>;
+    /** NanoID of the member who owns this SFTP user. */
+    ownerId: NanoID;
+    /** The owner member. */
+    owner: Member | null | undefined;
+    /** When this SFTP user last logged in, or `null` if never. */
+    lastLoginAt: Date | null;
+    /** When this SFTP user was created. */
+    createdAt: Date;
+    /** When this SFTP user was last updated. */
+    updatedAt: Date;
+    /** @internal */
+    constructor(data: SftpUserData);
+}
+/** Valid include keys for SFTP user endpoints. */
+export type SftpUserInclude = 'password';
+/** Maps each {@link SftpUserInclude} key to the field(s) it guarantees on the {@link SftpUser} instance. */
+interface SftpUserIncludeMap {
+    password: {
+        password: string;
+    };
+}
+/** A {@link SftpUser} with specific include fields guaranteed to be populated. */
+export type SftpUserWith<I extends readonly SftpUserInclude[] = []> = ResourceWith<SftpUser, SftpUserIncludeMap, I>;
+/**
+ * The full SFTP details for a server: connection info and the list of SFTP users.
+ */
+export interface SftpDetails {
+    /** How to connect to this server's SFTP endpoint. */
+    connection: SftpConnection;
+    /** All SFTP users configured for this server. */
+    users: SftpUser[];
+}
+/**
+ * Manages SFTP users and credentials for a specific server.
+ *
+ * Access via `server.sftp`.
+ *
+ * @example
+ * ```ts ignore
+ * const details = await server.sftp.details();
+ * console.log(`Connect to: ${details.connection.url}`);
+ *
+ * const user = await server.sftp.create('deploy', {
+ *   '/': ['sftp.content.list', 'sftp.content.read'],
+ *   '/logs': ['sftp.content.list', 'sftp.content.read', 'sftp.content.delete'],
+ * });
+ * console.log(user.password); // Save this!
+ * ```
+ */
+export declare class ServerSftpManager {
+    private readonly serverId;
+    private readonly http;
+    /** @internal */
+    constructor(serverId: NanoID, http: HttpClient);
+    /**
+     * Fetch the SFTP connection details and all SFTP users for this server.
+     */
+    details(): Promise<SftpDetails>;
+    /**
+     * Fetch all SFTP users for this server without the connection details.
+     *
+     * @param opts Pagination and include options.
+     */
+    list<const I extends readonly SftpUserInclude[] = []>(opts?: ListOptions & IncludeOptions<SftpUserInclude, I>): Promise<Paginated<SftpUserWith<I>>>;
+    /**
+     * Fetch a single SFTP user by ID.
+     *
+     * @param userId The SFTP user's NanoID.
+     * @param opts   Include options.
+     */
+    get<const I extends readonly SftpUserInclude[] = []>(userId: NanoID, opts?: IncludeOptions<SftpUserInclude, I>): Promise<SftpUserWith<I>>;
+    /**
+     * Create a new SFTP user for this server.
+     *
+     * The returned {@link SftpUser} includes the `password` field automatically.
+     * On subsequent fetches, request it explicitly with `include=password`.
+     *
+     * @param name  Display name for the SFTP user.
+     * @param paths A map of path glob patterns to an array of {@link SftpPermission} scopes.
+     *              At least one path with at least one permission is required.
+     */
+    create(name: string, paths: Record<string, SftpPermission[]>): Promise<SftpUser>;
+    /**
+     * Update an SFTP user's name and/or path permissions.
+     *
+     * To remove a path, set its permissions array to `[]`.
+     *
+     * @param userId  The SFTP user's NanoID.
+     * @param payload Fields to update.
+     */
+    update(userId: NanoID, payload: {
+        name?: string;
+        paths?: Record<string, SftpPermission[]>;
+    }): Promise<SftpUser>;
+    /**
+     * Delete an SFTP user permanently.
+     *
+     * @param userId The SFTP user's NanoID.
+     */
+    delete(userId: NanoID): Promise<void>;
+}
+export {};
+//# sourceMappingURL=sftp.d.ts.map

package/esm/src/resources/servers/sftp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sftp.d.ts","sourceRoot":"","sources":["../../../../src/src/resources/servers/sftp.ts"],"names":[],"mappings":"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"}

package/esm/src/resources/servers/sftp.js

@@ -0,0 +1,153 @@
+import { ReactiveResource } from '../../reactive.js';
+import { joinIncludes, toNanoID } from '../../types.js';
+import { Member } from '../members.js';
+/**
+ * An SFTP user credential scoped to a specific server with path-level permissions.
+ *
+ * Retrieved via {@link ServerSftpManager.list} or {@link ServerSftpManager.create}.
+ *
+ * > **Note:** The `password` field is automatically included in the creation response.
+ * > On subsequent fetches it requires `include=password` to be populated.
+ */
+export class SftpUser extends ReactiveResource {
+    /** The SFTP user's unique NanoID. */
+    id;
+    /** Display name for this SFTP user. */
+    name;
+    /** The SFTP login username (typically prefixed with the server ID). */
+    username;
+    /**
+     * The plaintext password.
+     *
+     * Automatically included on creation. Requires `include=password` on subsequent fetches.
+     */
+    password;
+    /**
+     * A map of path glob patterns to the set of permissions granted for that path.
+     *
+     * Keys are glob patterns (e.g. `"/"`, `"/logs/*"`).
+     * Values are arrays of {@link SftpPermission} scopes.
+     */
+    paths;
+    /** NanoID of the member who owns this SFTP user. */
+    ownerId;
+    /** The owner member. */
+    owner;
+    /** When this SFTP user last logged in, or `null` if never. */
+    lastLoginAt;
+    /** When this SFTP user was created. */
+    createdAt;
+    /** When this SFTP user was last updated. */
+    updatedAt;
+    /** @internal */
+    constructor(data) {
+        super();
+        this.id = toNanoID(data.id);
+        this.name = data.name;
+        this.username = data.username;
+        this.password = data.password;
+        this.paths = data.paths;
+        this.ownerId = toNanoID(data.owner_id);
+        this.owner = data.owner ? new Member(data.owner) : data.owner;
+        this.lastLoginAt = data.last_login_at ? new Date(data.last_login_at) : null;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+    }
+}
+/**
+ * Manages SFTP users and credentials for a specific server.
+ *
+ * Access via `server.sftp`.
+ *
+ * @example
+ * ```ts ignore
+ * const details = await server.sftp.details();
+ * console.log(`Connect to: ${details.connection.url}`);
+ *
+ * const user = await server.sftp.create('deploy', {
+ *   '/': ['sftp.content.list', 'sftp.content.read'],
+ *   '/logs': ['sftp.content.list', 'sftp.content.read', 'sftp.content.delete'],
+ * });
+ * console.log(user.password); // Save this!
+ * ```
+ */
+export class ServerSftpManager {
+    serverId;
+    http;
+    /** @internal */
+    constructor(serverId, http) {
+        this.serverId = serverId;
+        this.http = http;
+    }
+    /**
+     * Fetch the SFTP connection details and all SFTP users for this server.
+     */
+    async details() {
+        const data = await this.http.get(`/servers/${this.serverId}/sftp`);
+        return {
+            connection: data.connection,
+            users: data.users.map((u) => new SftpUser(u)),
+        };
+    }
+    /**
+     * Fetch all SFTP users for this server without the connection details.
+     *
+     * @param opts Pagination and include options.
+     */
+    async list(opts = {}) {
+        const extra = {};
+        const include = joinIncludes(opts);
+        if (include)
+            extra['include'] = include;
+        const result = await this.http.list(`/servers/${this.serverId}/sftp/users`, opts, extra);
+        return { ...result, data: result.data.map((d) => new SftpUser(d)) };
+    }
+    /**
+     * Fetch a single SFTP user by ID.
+     *
+     * @param userId The SFTP user's NanoID.
+     * @param opts   Include options.
+     */
+    async get(userId, opts = {}) {
+        const params = {};
+        const include = joinIncludes(opts);
+        if (include)
+            params['include'] = include;
+        const data = await this.http.get(`/servers/${this.serverId}/sftp/users/${userId}`, { params });
+        return new SftpUser(data);
+    }
+    /**
+     * Create a new SFTP user for this server.
+     *
+     * The returned {@link SftpUser} includes the `password` field automatically.
+     * On subsequent fetches, request it explicitly with `include=password`.
+     *
+     * @param name  Display name for the SFTP user.
+     * @param paths A map of path glob patterns to an array of {@link SftpPermission} scopes.
+     *              At least one path with at least one permission is required.
+     */
+    async create(name, paths) {
+        const data = await this.http.post(`/servers/${this.serverId}/sftp/users`, { name, paths });
+        return new SftpUser(data);
+    }
+    /**
+     * Update an SFTP user's name and/or path permissions.
+     *
+     * To remove a path, set its permissions array to `[]`.
+     *
+     * @param userId  The SFTP user's NanoID.
+     * @param payload Fields to update.
+     */
+    async update(userId, payload) {
+        const data = await this.http.patch(`/servers/${this.serverId}/sftp/users/${userId}`, payload);
+        return new SftpUser(data);
+    }
+    /**
+     * Delete an SFTP user permanently.
+     *
+     * @param userId The SFTP user's NanoID.
+     */
+    async delete(userId) {
+        await this.http.delete(`/servers/${this.serverId}/sftp/users/${userId}`);
+    }
+}