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

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

@@ -0,0 +1,120 @@
+import type { HttpClient } from '../../http.js';
+import { ReactiveResource } from '../../reactive.js';
+import type { ListOptions, NanoID, Paginated } from '../../types.js';
+import { Member } from '../members.js';
+import type { ActivityJobData, ActivityJobLogData, ActivityLogData } from './types.js';
+/**
+ * A single log entry within an {@link ActivityJob}.
+ */
+export declare class ActivityJobLog {
+    /** The type of log event, e.g. `"info"`, `"error"`. */
+    readonly type: string;
+    /** Structured metadata about this log event. */
+    readonly metadata: Record<string, unknown>;
+    /** When this log entry was created. */
+    readonly createdAt: Date;
+    /** @internal */
+    constructor(data: ActivityJobLogData);
+}
+/**
+ * An asynchronous background job associated with a server activity.
+ *
+ * Jobs represent long-running operations (e.g. installing a server, restoring a backup)
+ * and may contain multiple {@link ActivityJobLog} entries.
+ */
+export declare class ActivityJob extends ReactiveResource {
+    /** The job's unique NanoID. */
+    readonly id: NanoID;
+    /** Current job status. */
+    status: 'in_progress' | 'completed' | 'failed';
+    /** Log entries produced by this job, in chronological order. */
+    logs: ActivityJobLog[];
+    /** When the job completed (or failed), or `null` if still in progress. */
+    completedAt: Date | null;
+    /** When this job was created. */
+    createdAt: Date;
+    /** When this job was last updated. */
+    updatedAt: Date;
+    /** @internal */
+    constructor(data: ActivityJobData);
+    /** `true` if the job is still running. */
+    get isInProgress(): boolean;
+    /** `true` if the job finished successfully. */
+    get isCompleted(): boolean;
+    /** `true` if the job encountered an error. */
+    get isFailed(): boolean;
+}
+/**
+ * An audit log entry recording an action performed on a server.
+ *
+ * Activities track all significant operations (power signals, file edits, permission changes, etc.)
+ * and optionally reference an async {@link ActivityJob}.
+ */
+export declare class ActivityLog extends ReactiveResource {
+    /** The activity log entry's unique NanoID. */
+    readonly id: NanoID;
+    /** The event type identifier, e.g. `"server.power.start"`. */
+    event: string;
+    /** NanoID of the server this activity is associated with, if any. */
+    serverId: NanoID | null;
+    /** NanoID of the node this activity is associated with, if any. */
+    nodeId: NanoID | null;
+    /** NanoID of the issuer (user or API key) who triggered this activity, or `null` for system. */
+    issuerId: NanoID | null;
+    /** The member who triggered this activity. */
+    issuer: Member | null | undefined;
+    /** The IP address the action was performed from, if available. */
+    ip: string | null | undefined;
+    /** Structured metadata about this activity (content depends on the event type). */
+    metadata: Record<string, unknown>;
+    /** NanoID of the associated async job, or `null` if none. */
+    jobId: NanoID | null;
+    /** The associated async job. */
+    job: ActivityJob | null | undefined;
+    /** When this activity occurred. */
+    createdAt: Date;
+    /** @internal */
+    constructor(data: ActivityLogData);
+}
+/**
+ * Manages activity logs and async jobs for a specific server.
+ *
+ * Access via `server.activity`.
+ *
+ * @example
+ * ```ts ignore
+ * const logs = await server.activity.list();
+ * const job = await server.activity.getJob(jobId);
+ * ```
+ */
+export declare class ServerActivityManager {
+    private readonly serverId;
+    private readonly http;
+    /** @internal */
+    constructor(serverId: NanoID, http: HttpClient);
+    /**
+     * Fetch a paginated list of activity log entries for this server.
+     *
+     * @param opts Pagination options.
+     */
+    list(opts?: ListOptions): Promise<Paginated<ActivityLog>>;
+    /**
+     * Fetch a single activity log entry.
+     *
+     * @param activityId The activity log entry's NanoID.
+     */
+    get(activityId: NanoID): Promise<ActivityLog>;
+    /**
+     * Fetch a paginated list of async activity jobs for this server.
+     *
+     * @param opts Pagination options.
+     */
+    listJobs(opts?: ListOptions): Promise<Paginated<ActivityJob>>;
+    /**
+     * Fetch a single async activity job.
+     *
+     * @param jobId The activity job's NanoID.
+     */
+    getJob(jobId: NanoID): Promise<ActivityJob>;
+}
+//# sourceMappingURL=activity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../../src/src/resources/servers/activity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEvF;;GAEG;AACH,qBAAa,cAAc;IAC1B,uDAAuD;IACvD,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,SAAgB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,uCAAuC;IACvC,SAAgB,SAAS,EAAE,IAAI,CAAC;IAEhC,gBAAgB;gBACG,IAAI,EAAE,kBAAkB;CAK3C;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,gBAAgB;IAChD,+BAA+B;IAC/B,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,0BAA0B;IACnB,MAAM,EAAE,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtD,gEAAgE;IACzD,IAAI,EAAE,cAAc,EAAE,CAAC;IAC9B,0EAA0E;IACnE,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IAChC,iCAAiC;IAC1B,SAAS,EAAE,IAAI,CAAC;IACvB,sCAAsC;IAC/B,SAAS,EAAE,IAAI,CAAC;IAEvB,gBAAgB;gBACG,IAAI,EAAE,eAAe;IAUxC,0CAA0C;IAC1C,IAAW,YAAY,IAAI,OAAO,CAEjC;IAED,+CAA+C;IAC/C,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED,8CAA8C;IAC9C,IAAW,QAAQ,IAAI,OAAO,CAE7B;CACD;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,gBAAgB;IAChD,8CAA8C;IAC9C,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IACvD,KAAK,EAAE,MAAM,CAAC;IACrB,qEAAqE;IAC9D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mEAAmE;IAC5D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gGAAgG;IACzF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,8CAA8C;IACvC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACzC,kEAAkE;IAC3D,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC,mFAAmF;IAC5E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,6DAA6D;IACtD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gCAAgC;IACzB,GAAG,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,mCAAmC;IAC5B,SAAS,EAAE,IAAI,CAAC;IAEvB,gBAAgB;gBACG,IAAI,EAAE,eAAe;CAcxC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,qBAAqB;IAGhC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHtB,gBAAgB;gBAEE,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU;IAGlC;;;;OAIG;IACU,IAAI,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAK1E;;;;OAIG;IACU,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAK1D;;;;OAIG;IACU,QAAQ,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAK9E;;;;OAIG;IACU,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAIxD"}

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

@@ -0,0 +1,163 @@
+import { ReactiveResource } from '../../reactive.js';
+import { toNanoID } from '../../types.js';
+import { Member } from '../members.js';
+/**
+ * A single log entry within an {@link ActivityJob}.
+ */
+export class ActivityJobLog {
+    /** The type of log event, e.g. `"info"`, `"error"`. */
+    type;
+    /** Structured metadata about this log event. */
+    metadata;
+    /** When this log entry was created. */
+    createdAt;
+    /** @internal */
+    constructor(data) {
+        this.type = data.type;
+        this.metadata = data.metadata;
+        this.createdAt = new Date(data.created_at);
+    }
+}
+/**
+ * An asynchronous background job associated with a server activity.
+ *
+ * Jobs represent long-running operations (e.g. installing a server, restoring a backup)
+ * and may contain multiple {@link ActivityJobLog} entries.
+ */
+export class ActivityJob extends ReactiveResource {
+    /** The job's unique NanoID. */
+    id;
+    /** Current job status. */
+    status;
+    /** Log entries produced by this job, in chronological order. */
+    logs;
+    /** When the job completed (or failed), or `null` if still in progress. */
+    completedAt;
+    /** When this job was created. */
+    createdAt;
+    /** When this job was last updated. */
+    updatedAt;
+    /** @internal */
+    constructor(data) {
+        super();
+        this.id = toNanoID(data.id);
+        this.status = data.status;
+        this.logs = data.logs.map((l) => new ActivityJobLog(l));
+        this.completedAt = data.completed_at ? new Date(data.completed_at) : null;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+    }
+    /** `true` if the job is still running. */
+    get isInProgress() {
+        return this.status === 'in_progress';
+    }
+    /** `true` if the job finished successfully. */
+    get isCompleted() {
+        return this.status === 'completed';
+    }
+    /** `true` if the job encountered an error. */
+    get isFailed() {
+        return this.status === 'failed';
+    }
+}
+/**
+ * An audit log entry recording an action performed on a server.
+ *
+ * Activities track all significant operations (power signals, file edits, permission changes, etc.)
+ * and optionally reference an async {@link ActivityJob}.
+ */
+export class ActivityLog extends ReactiveResource {
+    /** The activity log entry's unique NanoID. */
+    id;
+    /** The event type identifier, e.g. `"server.power.start"`. */
+    event;
+    /** NanoID of the server this activity is associated with, if any. */
+    serverId;
+    /** NanoID of the node this activity is associated with, if any. */
+    nodeId;
+    /** NanoID of the issuer (user or API key) who triggered this activity, or `null` for system. */
+    issuerId;
+    /** The member who triggered this activity. */
+    issuer;
+    /** The IP address the action was performed from, if available. */
+    ip;
+    /** Structured metadata about this activity (content depends on the event type). */
+    metadata;
+    /** NanoID of the associated async job, or `null` if none. */
+    jobId;
+    /** The associated async job. */
+    job;
+    /** When this activity occurred. */
+    createdAt;
+    /** @internal */
+    constructor(data) {
+        super();
+        this.id = toNanoID(data.id);
+        this.event = data.event;
+        this.serverId = data.server_id ? toNanoID(data.server_id) : null;
+        this.nodeId = data.node_id ? toNanoID(data.node_id) : null;
+        this.issuerId = data.issuer_id ? toNanoID(data.issuer_id) : null;
+        this.issuer = data.issuer ? new Member(data.issuer) : data.issuer;
+        this.ip = data.ip;
+        this.metadata = data.metadata;
+        this.jobId = data.job_id ? toNanoID(data.job_id) : null;
+        this.job = data.job ? new ActivityJob(data.job) : data.job;
+        this.createdAt = new Date(data.created_at);
+    }
+}
+/**
+ * Manages activity logs and async jobs for a specific server.
+ *
+ * Access via `server.activity`.
+ *
+ * @example
+ * ```ts ignore
+ * const logs = await server.activity.list();
+ * const job = await server.activity.getJob(jobId);
+ * ```
+ */
+export class ServerActivityManager {
+    serverId;
+    http;
+    /** @internal */
+    constructor(serverId, http) {
+        this.serverId = serverId;
+        this.http = http;
+    }
+    /**
+     * Fetch a paginated list of activity log entries for this server.
+     *
+     * @param opts Pagination options.
+     */
+    async list(opts = {}) {
+        const result = await this.http.list(`/servers/${this.serverId}/activities`, opts);
+        return { ...result, data: result.data.map((d) => new ActivityLog(d)) };
+    }
+    /**
+     * Fetch a single activity log entry.
+     *
+     * @param activityId The activity log entry's NanoID.
+     */
+    async get(activityId) {
+        const data = await this.http.get(`/servers/${this.serverId}/activities/${activityId}`);
+        return new ActivityLog(data);
+    }
+    /**
+     * Fetch a paginated list of async activity jobs for this server.
+     *
+     * @param opts Pagination options.
+     */
+    async listJobs(opts = {}) {
+        const result = await this.http.list(`/servers/${this.serverId}/activities/jobs`, opts);
+        return { ...result, data: result.data.map((d) => new ActivityJob(d)) };
+    }
+    /**
+     * Fetch a single async activity job.
+     *
+     * @param jobId The activity job's NanoID.
+     */
+    async getJob(jobId) {
+        const data = await this.http.get(`/servers/${this.serverId}/activities/jobs/${jobId}`);
+        return new ActivityJob(data);
+    }
+}

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

@@ -0,0 +1,125 @@
+import type { HttpClient } from '../../http.js';
+import { ReactiveResource } from '../../reactive.js';
+import type { ListOptions, NanoID, Paginated } from '../../types.js';
+import type { ServerAllocationPortData } from './types.js';
+/**
+ * Metadata about the underlying port allocation (IP and port number) from the node.
+ */
+export interface AllocationPortMeta {
+    /** Unique NanoID of this port record. */
+    id: NanoID;
+    /** IP address this port is bound to, e.g. `"1.2.3.4"`. */
+    ip: string;
+    /** Port number, e.g. `25565`. */
+    port: number;
+    /** Protocols this port is ready for, e.g. `["tcp", "udp"]`. */
+    readyProtocols: string[];
+    /** `true` if this port is currently assigned to a server. */
+    isInUse: boolean;
+    /** Internal notes. */
+    notes: string | null | undefined;
+    /** When this port was allocated. */
+    createdAt: Date;
+    /** When this port was last updated. */
+    updatedAt: Date;
+}
+/**
+ * A port allocation assigned to a server.
+ *
+ * Ports are the network endpoints (IP:port combinations) that game servers listen on.
+ * One port per server is the primary allocation; additional ports are extra.
+ *
+ * Retrieved via {@link ServerAllocationsManager.list} or {@link ServerAllocationsManager.primary}.
+ */
+export declare class ServerAllocationPort extends ReactiveResource {
+    /** The server allocation record's unique NanoID. */
+    readonly id: NanoID;
+    /** Optional human-readable description for this allocation, e.g. `"Voice Chat"`. */
+    description: string | null;
+    /** NanoID of the underlying port record. */
+    portId: NanoID | undefined;
+    /** Full metadata about the underlying port. */
+    meta: AllocationPortMeta | null | undefined;
+    /** `true` if this is the server's primary allocation. */
+    isPrimary: boolean;
+    /** When this allocation was assigned to the server. */
+    createdAt: Date;
+    /** When this allocation was last updated. */
+    updatedAt: Date;
+    /** Shorthand: the IP address this port is bound to (from meta). */
+    get ip(): string | undefined;
+    /** Shorthand: the port number (from meta). */
+    get port(): number | undefined;
+    /** Shorthand: formatted `ip:port` string, e.g. `"1.2.3.4:25565"`. */
+    get address(): string | undefined;
+    /** @internal */
+    constructor(data: ServerAllocationPortData);
+}
+/** One entry in the array passed to {@link ServerAllocationsManager.add}. */
+export type AddAllocationEntry = {
+    id: NanoID;
+} | {
+    ip: string;
+    port: number;
+} | {
+    ip: `${string}:${number}`;
+};
+/**
+ * Manages port allocations for a specific server.
+ *
+ * Access via `server.allocations`.
+ *
+ * @example
+ * ```ts ignore
+ * const ports = await server.allocations.list();
+ * const primary = await server.allocations.primary();
+ * await server.allocations.update(portId, { description: 'Game port', isPrimary: true });
+ * await server.allocations.add([{ ip: '1.2.3.4', port: 25566 }]);
+ * ```
+ */
+export declare class ServerAllocationsManager {
+    private readonly serverId;
+    private readonly http;
+    /** @internal */
+    constructor(serverId: NanoID, http: HttpClient);
+    /**
+     * Fetch a paginated list of all port allocations for this server.
+     *
+     * @param opts Pagination options.
+     */
+    list(opts?: ListOptions): Promise<Paginated<ServerAllocationPort>>;
+    /**
+     * Fetch the primary port allocation for this server.
+     *
+     * @throws {@link ApiError} with `isNotFound === true` if no primary allocation is set.
+     */
+    primary(): Promise<ServerAllocationPort>;
+    /**
+     * Fetch a single allocation by its record ID.
+     *
+     * @param allocationId The allocation record's NanoID.
+     */
+    get(allocationId: NanoID): Promise<ServerAllocationPort>;
+    /**
+     * Update an allocation's description or promote it to primary.
+     *
+     * @param allocationId The allocation record's NanoID.
+     * @param payload Update fields.
+     */
+    update(allocationId: NanoID, payload: {
+        description?: string;
+        isPrimary?: boolean;
+    }): Promise<ServerAllocationPort>;
+    /**
+     * Add one or more port allocations to this server.
+     *
+     * Each entry can be specified as:
+     * - `{ id: NanoID }` - an existing allocation port record ID
+     * - `{ ip: string, port: number }` - by IP and port number
+     * - `{ ip: 'ip:port' }` - colon-separated IP:port string
+     *
+     * @param entries The allocations to add.
+     */
+    add(entries: AddAllocationEntry[]): Promise<void>;
+}
+//# sourceMappingURL=allocations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"allocations.d.ts","sourceRoot":"","sources":["../../../../src/src/resources/servers/allocations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjC,oCAAoC;IACpC,SAAS,EAAE,IAAI,CAAC;IAChB,uCAAuC;IACvC,SAAS,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;IACzD,oDAAoD;IACpD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IAC7E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,4CAA4C;IACrC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,+CAA+C;IACxC,IAAI,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,CAAC;IACnD,yDAAyD;IAClD,SAAS,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IAChD,SAAS,EAAE,IAAI,CAAC;IACvB,6CAA6C;IACtC,SAAS,EAAE,IAAI,CAAC;IAEvB,mEAAmE;IACnE,IAAW,EAAE,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,8CAA8C;IAC9C,IAAW,IAAI,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,qEAAqE;IACrE,IAAW,OAAO,IAAI,MAAM,GAAG,SAAS,CAGvC;IAED,gBAAgB;gBACG,IAAI,EAAE,wBAAwB;CAqBjD;AAED,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAC3B;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GACd;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,GAAG,MAAM,IAAI,MAAM,EAAE,CAAA;CAAE,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,qBAAa,wBAAwB;IAGnC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHtB,gBAAgB;gBAEE,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU;IAGlC;;;;OAIG;IACU,IAAI,CAChB,IAAI,GAAE,WAAgB,GACpB,OAAO,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;IAW3C;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAOrD;;;;OAIG;IACU,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAOrE;;;;;OAKG;IACU,MAAM,CAClB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GACpD,OAAO,CAAC,oBAAoB,CAAC;IAQhC;;;;;;;;;OASG;IACU,GAAG,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAM9D"}

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

@@ -0,0 +1,137 @@
+import { ReactiveResource } from '../../reactive.js';
+import { toNanoID } from '../../types.js';
+/**
+ * A port allocation assigned to a server.
+ *
+ * Ports are the network endpoints (IP:port combinations) that game servers listen on.
+ * One port per server is the primary allocation; additional ports are extra.
+ *
+ * Retrieved via {@link ServerAllocationsManager.list} or {@link ServerAllocationsManager.primary}.
+ */
+export class ServerAllocationPort extends ReactiveResource {
+    /** The server allocation record's unique NanoID. */
+    id;
+    /** Optional human-readable description for this allocation, e.g. `"Voice Chat"`. */
+    description;
+    /** NanoID of the underlying port record. */
+    portId;
+    /** Full metadata about the underlying port. */
+    meta;
+    /** `true` if this is the server's primary allocation. */
+    isPrimary;
+    /** When this allocation was assigned to the server. */
+    createdAt;
+    /** When this allocation was last updated. */
+    updatedAt;
+    /** Shorthand: the IP address this port is bound to (from meta). */
+    get ip() {
+        return this.meta?.ip;
+    }
+    /** Shorthand: the port number (from meta). */
+    get port() {
+        return this.meta?.port;
+    }
+    /** Shorthand: formatted `ip:port` string, e.g. `"1.2.3.4:25565"`. */
+    get address() {
+        if (!this.meta)
+            return undefined;
+        return `${this.meta.ip}:${this.meta.port}`;
+    }
+    /** @internal */
+    constructor(data) {
+        super();
+        this.id = toNanoID(data.id);
+        this.description = data.description ?? null;
+        this.portId = data.port_id ? toNanoID(data.port_id) : undefined;
+        this.meta = data.meta
+            ? {
+                id: toNanoID(data.meta.id),
+                ip: data.meta.ip,
+                port: data.meta.port,
+                readyProtocols: data.meta.ready_protocols ?? [],
+                isInUse: data.meta.is_in_use ?? false,
+                notes: data.meta.notes,
+                createdAt: new Date(data.meta.created_at),
+                updatedAt: new Date(data.meta.updated_at),
+            }
+            : data.meta;
+        this.isPrimary = data.is_primary;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+    }
+}
+/**
+ * Manages port allocations for a specific server.
+ *
+ * Access via `server.allocations`.
+ *
+ * @example
+ * ```ts ignore
+ * const ports = await server.allocations.list();
+ * const primary = await server.allocations.primary();
+ * await server.allocations.update(portId, { description: 'Game port', isPrimary: true });
+ * await server.allocations.add([{ ip: '1.2.3.4', port: 25566 }]);
+ * ```
+ */
+export class ServerAllocationsManager {
+    serverId;
+    http;
+    /** @internal */
+    constructor(serverId, http) {
+        this.serverId = serverId;
+        this.http = http;
+    }
+    /**
+     * Fetch a paginated list of all port allocations for this server.
+     *
+     * @param opts Pagination options.
+     */
+    async list(opts = {}) {
+        const result = await this.http.list(`/servers/${this.serverId}/allocations`, opts);
+        return {
+            ...result,
+            data: result.data.map((d) => new ServerAllocationPort(d)),
+        };
+    }
+    /**
+     * Fetch the primary port allocation for this server.
+     *
+     * @throws {@link ApiError} with `isNotFound === true` if no primary allocation is set.
+     */
+    async primary() {
+        const data = await this.http.get(`/servers/${this.serverId}/allocations/primary`);
+        return new ServerAllocationPort(data);
+    }
+    /**
+     * Fetch a single allocation by its record ID.
+     *
+     * @param allocationId The allocation record's NanoID.
+     */
+    async get(allocationId) {
+        const data = await this.http.get(`/servers/${this.serverId}/allocations/${allocationId}`);
+        return new ServerAllocationPort(data);
+    }
+    /**
+     * Update an allocation's description or promote it to primary.
+     *
+     * @param allocationId The allocation record's NanoID.
+     * @param payload Update fields.
+     */
+    async update(allocationId, payload) {
+        const data = await this.http.patch(`/servers/${this.serverId}/allocations/${allocationId}`, { description: payload.description, is_primary: payload.isPrimary });
+        return new ServerAllocationPort(data);
+    }
+    /**
+     * Add one or more port allocations to this server.
+     *
+     * Each entry can be specified as:
+     * - `{ id: NanoID }` - an existing allocation port record ID
+     * - `{ ip: string, port: number }` - by IP and port number
+     * - `{ ip: 'ip:port' }` - colon-separated IP:port string
+     *
+     * @param entries The allocations to add.
+     */
+    async add(entries) {
+        await this.http.post(`/servers/${this.serverId}/allocations`, entries);
+    }
+}

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

@@ -0,0 +1,108 @@
+import { ReactiveResource } from '../../reactive.js';
+import type { NanoID, PowerState } from '../../types.js';
+/** Real-time resource utilization reported by the node. */
+export interface ServerUtilization {
+    /** CPU usage as an absolute percentage (0–100+). */
+    cpuAbsolute: number;
+    /** Memory usage in bytes. */
+    memoryBytes: number;
+    /** Memory limit in bytes. */
+    memoryLimitBytes: number;
+    /** Disk usage in bytes. */
+    diskBytes: number;
+    /** Network received bytes (cumulative since start). */
+    networkRxBytes: number;
+    /** Network transmitted bytes (cumulative since start). */
+    networkTxBytes: number;
+    /** Server uptime in seconds. */
+    uptimeSeconds: number;
+}
+/** Typed events emitted by {@link ServerConnection}. */
+export interface ServerConnectionEvents {
+    /** A line of console output from the server process. */
+    console_output: string;
+    /** The server's power state changed. */
+    status: PowerState;
+    /** New resource utilization stats are available. */
+    stats: ServerUtilization;
+}
+/**
+ * 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 declare class ServerConnection extends ReactiveResource {
+    private readonly serverId;
+    private readonly nodeUrl;
+    private readonly token;
+    /** Maximum number of console output lines retained in {@link ServerConnection.output}. */
+    private static readonly maxOutputLines;
+    private readonly listeners;
+    private sse;
+    private connected;
+    /**
+     * 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: string[];
+    /** @internal */
+    constructor(serverId: NanoID, nodeUrl: string, token: string);
+    /** `true` if the SSE connection is currently open. */
+    get isConnected(): boolean;
+    /**
+     * 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.
+     */
+    open(onError?: (error: Error) => void): Promise<void>;
+    /** Close the SSE stream and stop receiving events. */
+    close(): void;
+    /**
+     * 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<K extends keyof ServerConnectionEvents>(event: K, handler: (payload: ServerConnectionEvents[K]) => void): void;
+    /**
+     * Unregister a previously registered event handler.
+     *
+     * @param event   The event name.
+     * @param handler The exact handler reference passed to {@link on}.
+     */
+    off<K extends keyof ServerConnectionEvents>(event: K, handler: (payload: ServerConnectionEvents[K]) => void): void;
+    /** Remove all event handlers for all event types. */
+    removeAllListeners(): void;
+    /** Parse and dispatch a raw SSE event to registered handlers. */
+    private dispatch;
+}
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/src/resources/servers/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEzD,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IACjC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACtC,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,MAAM,EAAE,UAAU,CAAC;IACnB,oDAAoD;IACpD,KAAK,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,gBAAiB,SAAQ,gBAAgB;IAwBpD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAzBvB,0FAA0F;IAC1F,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAE9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGtB;IAEJ,OAAO,CAAC,GAAG,CAAgB;IAC3B,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;;;;OAOG;IACI,MAAM,EAAE,MAAM,EAAE,CAAM;IAE7B,gBAAgB;gBAEE,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM;IAS/B,sDAAsD;IACtD,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;;;;;;;OASG;IACU,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAiClE,sDAAsD;IAC/C,KAAK,IAAI,IAAI;IAKpB;;;;;OAKG;IACI,EAAE,CAAC,CAAC,SAAS,MAAM,sBAAsB,EAC/C,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,GACnD,IAAI;IAWP;;;;;OAKG;IACI,GAAG,CAAC,CAAC,SAAS,MAAM,sBAAsB,EAChD,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,GACnD,IAAI;IAUP,qDAAqD;IAC9C,kBAAkB,IAAI,IAAI;IAIjC,iEAAiE;IACjE,OAAO,CAAC,QAAQ;CAyChB"}