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

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

@@ -0,0 +1,169 @@
+import { ReactiveResource } from '../../reactive.js';
+import { SseConnection } from '../../sse.js';
+/**
+ * A real-time SSE connection to a specific server on its Whisker node daemon.
+ *
+ * Emits typed events for console output, power state changes, and resource utilization.
+ * Also maintains a rolling buffer of console output lines in {@link output}, pre-populated
+ * with recent history fetched from the node on {@link connect}.
+ *
+ * Obtain a connection via {@link import('./server.ts').Server.connect}.
+ *
+ * @example
+ * ```ts ignore
+ * const conn = await server.connect();
+ *
+ * conn.on('status', (state) => console.log('Power state:', state));
+ * conn.on('stats', (stats) => console.log('CPU:', stats.cpuAbsolute + '%'));
+ *
+ * await conn.connect();
+ *
+ * // Reactive: $conn.output is the full rolling buffer of console lines
+ * // Live lines are appended automatically as they arrive over SSE
+ *
+ * // Later...
+ * conn.disconnect();
+ * ```
+ */
+export class ServerConnection extends ReactiveResource {
+    serverId;
+    nodeUrl;
+    token;
+    /** Maximum number of console output lines retained in {@link ServerConnection.output}. */
+    static maxOutputLines = 1024;
+    listeners = new Map();
+    sse;
+    connected = false;
+    /**
+     * Rolling buffer of console output lines, capped at {@link MAX_OUTPUT_LINES}.
+     *
+     * Pre-populated with recent history from the node when {@link connect} is called,
+     * then appended to live as `console_output` SSE events arrive.
+     *
+     * Use as a reactive store: `$conn.output`.
+     */
+    output = [];
+    /** @internal */
+    constructor(serverId, nodeUrl, token) {
+        super();
+        this.serverId = serverId;
+        this.nodeUrl = nodeUrl;
+        this.token = token;
+        this.sse = new SseConnection(`${nodeUrl}/api/servers/${serverId}/sse`, token);
+    }
+    /** `true` if the SSE connection is currently open. */
+    get isConnected() {
+        return this.connected;
+    }
+    /**
+     * Fetch console history and open the SSE stream.
+     *
+     * Populates {@link output} with recent history from the node, then begins streaming
+     * live events.
+     *
+     * Maintains only one instances of the stream.
+     *
+     * @param onError Optional callback invoked if the connection drops unexpectedly.
+     */
+    async open(onError) {
+        this.sse.disconnect(); // close any existing stream
+        try {
+            const res = await fetch(`${this.nodeUrl}/api/servers/${this.serverId}/logs?size=100`, { headers: { Authorization: `Bearer ${this.token}` } });
+            if (res.ok) {
+                const json = (await res.json());
+                this.output = json.data ?? [];
+                this.notify();
+            }
+        }
+        catch {
+            // History is best-effort - don't block the SSE connection
+        }
+        const url = `${this.nodeUrl}/api/servers/${this.serverId}/sse`;
+        this.sse = new SseConnection(url, this.token);
+        this.connected = true;
+        this.sse.connect((event, data) => {
+            this.dispatch(event, data);
+        }, (err) => {
+            this.connected = false;
+            this.notify();
+            onError?.(err);
+        });
+    }
+    /** Close the SSE stream and stop receiving events. */
+    close() {
+        this.sse.disconnect();
+        this.connected = false;
+    }
+    /**
+     * Register a handler for a typed server event.
+     *
+     * @param event   The event name.
+     * @param handler The callback to invoke when the event is received.
+     */
+    on(event, handler) {
+        if (!this.listeners.has(event))
+            this.listeners.set(event, new Set());
+        this.listeners
+            .get(event)
+            .add(handler);
+    }
+    /**
+     * Unregister a previously registered event handler.
+     *
+     * @param event   The event name.
+     * @param handler The exact handler reference passed to {@link on}.
+     */
+    off(event, handler) {
+        this.listeners
+            .get(event)
+            ?.delete(handler);
+    }
+    /** Remove all event handlers for all event types. */
+    removeAllListeners() {
+        this.listeners.clear();
+    }
+    /** Parse and dispatch a raw SSE event to registered handlers. */
+    dispatch(event, rawData) {
+        let payload;
+        try {
+            if (event === 'console_output') {
+                payload = rawData;
+                this.output.push(payload);
+                if (this.output.length > ServerConnection.maxOutputLines) {
+                    this.output.shift();
+                }
+                this.notify();
+            }
+            else if (event === 'status') {
+                const parsed = JSON.parse(rawData);
+                if (typeof parsed?.state !== 'string')
+                    return;
+                payload = parsed.state;
+            }
+            else if (event === 'stats') {
+                const raw = JSON.parse(rawData);
+                if (typeof raw?.cpu_absolute !== 'number' ||
+                    typeof raw?.memory_bytes !== 'number') {
+                    return;
+                }
+                payload = {
+                    cpuAbsolute: raw.cpu_absolute,
+                    memoryBytes: raw.memory_bytes,
+                    memoryLimitBytes: raw.memory_limit_bytes,
+                    diskBytes: raw.disk_bytes,
+                    networkRxBytes: raw.network?.rx_bytes ?? 0,
+                    networkTxBytes: raw.network?.tx_bytes ?? 0,
+                    uptimeSeconds: raw.uptime,
+                };
+            }
+            else {
+                return;
+            }
+        }
+        catch {
+            return;
+        }
+        const handlers = this.listeners.get(event);
+        handlers?.forEach((h) => h(payload));
+    }
+}

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

@@ -0,0 +1,164 @@
+import type { NanoID } from '../../types.js';
+import type { FileEntryData } from './types.js';
+/**
+ * A single file or directory entry in a server's file system.
+ */
+export declare class FileEntry {
+    /** The name of the file or directory. */
+    readonly name: string;
+    /** Symbolic file mode string, e.g. `"-rw-r--r--"`. */
+    readonly mode: string;
+    /** Numeric mode bits (octal), e.g. `"644"`. */
+    readonly modeBits: string;
+    /** Size of the file in bytes. `0` for directories. */
+    readonly size: number;
+    /** `true` if this entry is a directory. */
+    readonly isDirectory: boolean;
+    /** MIME type of the file, e.g. `"text/plain"`. */
+    readonly mime: string;
+    /** `true` if this entry is a symbolic link. */
+    readonly isSymlink: boolean;
+    /** When this file or directory was created. */
+    readonly createdAt: Date;
+    /** When this file or directory was last modified. */
+    readonly modifiedAt: Date;
+    /** @internal */
+    constructor(data: FileEntryData);
+}
+/**
+ * Manages file system operations for a specific server via the Whisker node daemon API.
+ *
+ * File operations communicate directly with the node daemon.
+ * The node URL is resolved lazily on first use and cached for subsequent calls.
+ *
+ * @example
+ * ```ts ignore
+ * const entries = await server.files.list('/');
+ * const content = await server.files.read('/server.properties');
+ * await server.files.write('/server.properties', 'motd=Hello World\n');
+ * await server.files.move({ from: '/old.txt', to: '/new.txt' });
+ * await server.files.delete(['/backup.zip']);
+ * ```
+ */
+export declare class ServerFilesManager {
+    private readonly serverId;
+    private readonly token;
+    private readonly resolveNodeUrl;
+    private nodeUrl?;
+    /**
+     * @param serverId      The server's NanoID.
+     * @param token         Bearer token for node authentication.
+     * @param resolveNodeUrl Async function that returns the daemon base URL for this server's node.
+     */
+    constructor(serverId: NanoID, token: string, resolveNodeUrl: () => Promise<string>);
+    /** Lazily resolve and cache the node daemon URL. */
+    private getNodeUrl;
+    /** Build a full node API URL for a file path endpoint. */
+    private buildFileUrl;
+    /** Shared auth headers for node requests. */
+    private get authHeaders();
+    /** Perform a raw fetch to the node and throw on non-2xx. */
+    private nodeFetch;
+    /**
+     * List the contents of a directory.
+     *
+     * @param path Absolute path to the directory, e.g. `"/"` or `"/plugins"`.
+     * @returns An array of {@link FileEntry} objects.
+     */
+    list(path: string): Promise<FileEntry[]>;
+    /**
+     * Read the text content of a file.
+     *
+     * @param path Absolute path to the file, e.g. `"/server.properties"`.
+     * @returns The file content as a UTF-8 string.
+     */
+    read(path: string): Promise<string>;
+    /**
+     * Read the raw binary content of a file.
+     *
+     * @param path Absolute path to the file.
+     * @returns The file content as an `ArrayBuffer`.
+     */
+    readBinary(path: string): Promise<ArrayBuffer>;
+    /**
+     * Write text content to a file, creating it if it doesn't exist.
+     *
+     * @param path    Absolute path to the file.
+     * @param content The UTF-8 text content to write.
+     */
+    write(path: string, content: string): Promise<void>;
+    /**
+     * Write raw binary content to a file.
+     *
+     * @param path        Absolute path to the file.
+     * @param content     Binary content to write.
+     * @param contentType MIME type of the content.
+     */
+    writeBinary(path: string, content: ArrayBuffer | Uint8Array, contentType: string): Promise<void>;
+    /**
+     * Delete one or more files or directories.
+     *
+     * @param paths An array of absolute paths to delete.
+     */
+    delete(paths: string[]): Promise<void>;
+    /**
+     * Move (rename) a file or directory.
+     *
+     * @param from Absolute source path.
+     * @param to   Absolute destination path.
+     */
+    move(from: string, to: string): Promise<void>;
+    /**
+     * Copy a file or directory to a new location.
+     *
+     * @param source   Absolute path of the source file or directory.
+     * @param location Absolute path of the destination directory.
+     */
+    copy(source: string, location: string): Promise<void>;
+    /**
+     * Create an empty file or directory.
+     *
+     * @param path      Absolute path of the new file or directory.
+     * @param directory When `true`, creates a directory instead of a file.
+     */
+    create(path: string, directory?: boolean): Promise<void>;
+    /**
+     * Compress one or more files into an archive.
+     *
+     * @param files      Array of absolute paths to include in the archive.
+     * @param name       Name of the output archive file, e.g. `"backup.tar.gz"`.
+     * @param rootPath   Root directory for resolving relative paths. Defaults to `"/"`.
+     */
+    compress(files: string[], name: string, rootPath?: string): Promise<void>;
+    /**
+     * Decompress (extract) an archive file.
+     *
+     * @param file      Absolute path to the archive to extract.
+     * @param rootPath  Directory to extract the archive into. Defaults to `"/"`.
+     */
+    decompress(file: string, rootPath?: string): Promise<void>;
+    /**
+     * Change the permissions (chmod) of one or more files.
+     *
+     * @param entries    Array of `{ file, mode }` objects.
+     * @param rootPath   Root directory for resolving paths. Defaults to `"/"`.
+     *
+     * @example
+     * ```ts ignore
+     * await server.files.chmod([{ file: 'start.sh', mode: '755' }]);
+     * ```
+     */
+    chmod(entries: {
+        file: string;
+        mode: string;
+    }[], rootPath?: string): Promise<void>;
+    /**
+     * Upload a file to the server using multipart form data.
+     *
+     * @param path     Absolute directory path to upload the file into.
+     * @param filename The name for the uploaded file.
+     * @param content  The file content as a `Blob`, `File`, or `ArrayBuffer`.
+     */
+    upload(path: string, filename: string, content: Blob | File | ArrayBuffer): Promise<void>;
+}
+//# sourceMappingURL=files.d.ts.map

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

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

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

@@ -0,0 +1,281 @@
+import { ApiError } from '../../errors.js';
+/**
+ * A single file or directory entry in a server's file system.
+ */
+export class FileEntry {
+    /** The name of the file or directory. */
+    name;
+    /** Symbolic file mode string, e.g. `"-rw-r--r--"`. */
+    mode;
+    /** Numeric mode bits (octal), e.g. `"644"`. */
+    modeBits;
+    /** Size of the file in bytes. `0` for directories. */
+    size;
+    /** `true` if this entry is a directory. */
+    isDirectory;
+    /** MIME type of the file, e.g. `"text/plain"`. */
+    mime;
+    /** `true` if this entry is a symbolic link. */
+    isSymlink;
+    /** When this file or directory was created. */
+    createdAt;
+    /** When this file or directory was last modified. */
+    modifiedAt;
+    /** @internal */
+    constructor(data) {
+        this.name = data.name;
+        this.mode = data.mode;
+        this.modeBits = data.mode_bits;
+        this.size = data.size;
+        this.isDirectory = data.type === 'directory';
+        this.mime = data.mime;
+        this.isSymlink = data.symlink;
+        this.createdAt = new Date(data.created);
+        this.modifiedAt = new Date(data.modified);
+    }
+}
+/**
+ * Manages file system operations for a specific server via the Whisker node daemon API.
+ *
+ * File operations communicate directly with the node daemon.
+ * The node URL is resolved lazily on first use and cached for subsequent calls.
+ *
+ * @example
+ * ```ts ignore
+ * const entries = await server.files.list('/');
+ * const content = await server.files.read('/server.properties');
+ * await server.files.write('/server.properties', 'motd=Hello World\n');
+ * await server.files.move({ from: '/old.txt', to: '/new.txt' });
+ * await server.files.delete(['/backup.zip']);
+ * ```
+ */
+export class ServerFilesManager {
+    serverId;
+    token;
+    resolveNodeUrl;
+    nodeUrl;
+    /**
+     * @param serverId      The server's NanoID.
+     * @param token         Bearer token for node authentication.
+     * @param resolveNodeUrl Async function that returns the daemon base URL for this server's node.
+     */
+    constructor(serverId, token, resolveNodeUrl) {
+        this.serverId = serverId;
+        this.token = token;
+        this.resolveNodeUrl = resolveNodeUrl;
+    }
+    /** Lazily resolve and cache the node daemon URL. */
+    async getNodeUrl() {
+        if (!this.nodeUrl)
+            this.nodeUrl = await this.resolveNodeUrl();
+        return this.nodeUrl;
+    }
+    /** Build a full node API URL for a file path endpoint. */
+    async buildFileUrl(endpoint) {
+        const base = await this.getNodeUrl();
+        return `${base}/api/servers/${this.serverId}/files${endpoint}`;
+    }
+    /** Shared auth headers for node requests. */
+    get authHeaders() {
+        return { 'Authorization': `Bearer ${this.token}` };
+    }
+    /** Perform a raw fetch to the node and throw on non-2xx. */
+    async nodeFetch(url, init = {}) {
+        const res = await globalThis.fetch(url, {
+            ...init,
+            headers: { ...this.authHeaders, ...init.headers },
+        });
+        if (!res.ok) {
+            let message = `HTTP ${res.status}`;
+            try {
+                const body = await res.json();
+                if (typeof body.error === 'string')
+                    message = body.error;
+            }
+            catch { /* ignore */ }
+            throw new ApiError({ message, status: res.status });
+        }
+        return res;
+    }
+    /**
+     * List the contents of a directory.
+     *
+     * @param path Absolute path to the directory, e.g. `"/"` or `"/plugins"`.
+     * @returns An array of {@link FileEntry} objects.
+     */
+    async list(path) {
+        const url = await this.buildFileUrl(path.startsWith('/') ? path : `/${path}`);
+        const res = await this.nodeFetch(url);
+        const data = await res.json();
+        return data.entries.map((e) => new FileEntry(e));
+    }
+    /**
+     * Read the text content of a file.
+     *
+     * @param path Absolute path to the file, e.g. `"/server.properties"`.
+     * @returns The file content as a UTF-8 string.
+     */
+    async read(path) {
+        const url = await this.buildFileUrl(path.startsWith('/') ? path : `/${path}`);
+        const res = await this.nodeFetch(url);
+        return res.text();
+    }
+    /**
+     * Read the raw binary content of a file.
+     *
+     * @param path Absolute path to the file.
+     * @returns The file content as an `ArrayBuffer`.
+     */
+    async readBinary(path) {
+        const url = await this.buildFileUrl(path.startsWith('/') ? path : `/${path}`);
+        const res = await this.nodeFetch(url);
+        return res.arrayBuffer();
+    }
+    /**
+     * Write text content to a file, creating it if it doesn't exist.
+     *
+     * @param path    Absolute path to the file.
+     * @param content The UTF-8 text content to write.
+     */
+    async write(path, content) {
+        const url = await this.buildFileUrl(path.startsWith('/') ? path : `/${path}`);
+        await this.nodeFetch(url, {
+            method: 'PUT',
+            body: content,
+            headers: { 'Content-Type': 'text/plain' },
+        });
+    }
+    /**
+     * Write raw binary content to a file.
+     *
+     * @param path        Absolute path to the file.
+     * @param content     Binary content to write.
+     * @param contentType MIME type of the content.
+     */
+    async writeBinary(path, content, contentType) {
+        const url = await this.buildFileUrl(path.startsWith('/') ? path : `/${path}`);
+        const body = content instanceof ArrayBuffer ? new Uint8Array(content) : content;
+        await this.nodeFetch(url, {
+            method: 'PUT',
+            body: body,
+            headers: { 'Content-Type': contentType },
+        });
+    }
+    /**
+     * Delete one or more files or directories.
+     *
+     * @param paths An array of absolute paths to delete.
+     */
+    async delete(paths) {
+        const url = await this.buildFileUrl('');
+        await this.nodeFetch(url, {
+            method: 'DELETE',
+            body: JSON.stringify({ root: '/', files: paths }),
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    /**
+     * Move (rename) a file or directory.
+     *
+     * @param from Absolute source path.
+     * @param to   Absolute destination path.
+     */
+    async move(from, to) {
+        const url = await this.buildFileUrl('/move');
+        await this.nodeFetch(url, {
+            method: 'POST',
+            body: JSON.stringify({ files: [{ from, to }] }),
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    /**
+     * Copy a file or directory to a new location.
+     *
+     * @param source   Absolute path of the source file or directory.
+     * @param location Absolute path of the destination directory.
+     */
+    async copy(source, location) {
+        const url = await this.buildFileUrl('/copy');
+        await this.nodeFetch(url, {
+            method: 'POST',
+            body: JSON.stringify({ location, files: [source] }),
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    /**
+     * Create an empty file or directory.
+     *
+     * @param path      Absolute path of the new file or directory.
+     * @param directory When `true`, creates a directory instead of a file.
+     */
+    async create(path, directory = false) {
+        const url = await this.buildFileUrl('/create');
+        await this.nodeFetch(url, {
+            method: 'POST',
+            body: JSON.stringify({ name: path, directory }),
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    /**
+     * Compress one or more files into an archive.
+     *
+     * @param files      Array of absolute paths to include in the archive.
+     * @param name       Name of the output archive file, e.g. `"backup.tar.gz"`.
+     * @param rootPath   Root directory for resolving relative paths. Defaults to `"/"`.
+     */
+    async compress(files, name, rootPath = '/') {
+        const url = await this.buildFileUrl('/compress');
+        await this.nodeFetch(url, {
+            method: 'POST',
+            body: JSON.stringify({ root_path: rootPath, files, name }),
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    /**
+     * Decompress (extract) an archive file.
+     *
+     * @param file      Absolute path to the archive to extract.
+     * @param rootPath  Directory to extract the archive into. Defaults to `"/"`.
+     */
+    async decompress(file, rootPath = '/') {
+        const url = await this.buildFileUrl('/decompress');
+        await this.nodeFetch(url, {
+            method: 'POST',
+            body: JSON.stringify({ root_path: rootPath, file }),
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    /**
+     * Change the permissions (chmod) of one or more files.
+     *
+     * @param entries    Array of `{ file, mode }` objects.
+     * @param rootPath   Root directory for resolving paths. Defaults to `"/"`.
+     *
+     * @example
+     * ```ts ignore
+     * await server.files.chmod([{ file: 'start.sh', mode: '755' }]);
+     * ```
+     */
+    async chmod(entries, rootPath = '/') {
+        const url = await this.buildFileUrl('/chmod');
+        await this.nodeFetch(url, {
+            method: 'POST',
+            body: JSON.stringify({ root_path: rootPath, files: entries }),
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    /**
+     * Upload a file to the server using multipart form data.
+     *
+     * @param path     Absolute directory path to upload the file into.
+     * @param filename The name for the uploaded file.
+     * @param content  The file content as a `Blob`, `File`, or `ArrayBuffer`.
+     */
+    async upload(path, filename, content) {
+        const url = await this.buildFileUrl(`/upload?directory=${encodeURIComponent(path)}`);
+        const form = new FormData();
+        const blob = content instanceof ArrayBuffer ? new Blob([content]) : content;
+        form.append('files', blob, filename);
+        await this.nodeFetch(url, { method: 'POST', body: form });
+    }
+}