@meowpanel/api 0.3.0 → 0.4.0

package/esm/src/resources/roles.js

@@ -0,0 +1,142 @@
+import { ResourceNamespace } from '../namespace.js';
+import { ReactiveResource } from '../reactive.js';
+import { toNanoID } from '../types.js';
+import { grantsToBody, parseGrant, } from './permissions.js';
+/**
+ * A named bundle of permissions that can be assigned to users.
+ *
+ * A role carries no permissions inline; fetch them via {@link RolesNamespace.permissions}.
+ * Its assignment scope and order live on the user-role link.
+ *
+ * Retrieved via {@link RolesNamespace.get} or {@link RolesNamespace.list}.
+ */
+export class Role extends ReactiveResource {
+    /** The role's unique NanoID. */
+    id;
+    /** Display title, e.g. `"Support"`. */
+    title;
+    /** Optional description. */
+    description;
+    /** Color used in the UI for grouping, or `null`. */
+    color;
+    /** Internal notes. Requires `permissions.roles.notes.read`. */
+    notes;
+    /** When this role was created. */
+    createdAt;
+    /** When this role was last updated. */
+    updatedAt;
+    /** @internal */
+    constructor(data) {
+        super();
+        this.id = toNanoID(data.id);
+        this.applyData(data);
+    }
+    /** Apply raw API data to this role instance, updating all mutable fields. */
+    applyData(data) {
+        this.title = data.title;
+        this.description = data.description;
+        this.color = data.color;
+        this.notes = data.notes;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+        this.notify();
+    }
+}
+/**
+ * Manages the permission grants attached to a specific role.
+ *
+ * Access via `api.roles.permissions(roleId)`.
+ */
+export class RolePermissionsManager {
+    roleId;
+    http;
+    /** @internal */
+    constructor(roleId, http) {
+        this.roleId = roleId;
+        this.http = http;
+    }
+    /** List the role's direct permission grants. */
+    async list() {
+        const data = await this.http.get(`/roles/${this.roleId}/permissions`);
+        return data.map(parseGrant);
+    }
+    /**
+     * Grant one or more permissions to the role.
+     *
+     * Re-granting an existing `(permission, scope)` updates it. You cannot grant a
+     * permission you do not hold yourself at the target scope.
+     */
+    async grant(grants) {
+        await this.http.post(`/roles/${this.roleId}/permissions`, grantsToBody(grants));
+    }
+    /**
+     * Revoke a permission from the role.
+     *
+     * @param permission The permission name to revoke.
+     * @param scope      The namespaced scope (`"<type>:<id>"`) to revoke at, or omit for the global grant.
+     */
+    async revoke(permission, scope) {
+        const params = scope ? { scope } : undefined;
+        await this.http.delete(`/roles/${this.roleId}/permissions/${encodeURIComponent(permission)}`, { params });
+    }
+}
+/**
+ * Namespace for role management.
+ *
+ * Access via `api.roles`.
+ *
+ * @example
+ * ```ts ignore
+ * const roles = await api.roles.list();
+ * const role = await api.roles.create({ title: 'Support', color: 'blue' });
+ * await api.roles.permissions(role.id).grant({ permission: 'server.console.read' });
+ * ```
+ */
+export class RolesNamespace extends ResourceNamespace {
+    /** @internal */
+    constructor(http) {
+        super(http);
+    }
+    /**
+     * Fetch a paginated list of roles.
+     *
+     * @param opts Pagination and search options.
+     */
+    async list(opts = {}) {
+        const result = await this.http.list('/roles', opts);
+        const roles = result.data.map((d) => new Role(d));
+        this.setCache(roles);
+        return { ...result, data: roles };
+    }
+    /** Fetch a single role by ID. */
+    async get(id) {
+        const data = await this.http.get(`/roles/${id}`);
+        return new Role(data);
+    }
+    /** Create a new role. */
+    async create(payload) {
+        const data = await this.http.post('/roles', payload);
+        const role = new Role(data);
+        this.addToCache(role);
+        this.emit('created', role);
+        return role;
+    }
+    /** Update a role's title, description, color, or notes. */
+    async update(id, payload) {
+        const data = await this.http.patch(`/roles/${id}`, payload);
+        const role = new Role(data);
+        this.upsertCache(role);
+        this.emit('updated', role);
+        return role;
+    }
+    /** Delete a role. Fails if the role is still assigned to any actor. */
+    async delete(id) {
+        await this.http.delete(`/roles/${id}`);
+        this.removeFromCache(id);
+        this.emit('deleted', id);
+    }
+    /** Manage the permission grants attached to a role. */
+    permissions(roleId) {
+        return new RolePermissionsManager(roleId, this.http);
+    }
+}

package/esm/src/resources/server-groups.d.ts

@@ -1,9 +1,13 @@
 import type { HttpClient } from '../http.js';
 import { ResourceNamespace } from '../namespace.js';
 import { ReactiveResource } from '../reactive.js';
+import type { IncludeOptions, ResourceWith } from '../types.js';
 import { type ISODate, type NanoID, type Paginated } from '../types.js';
 import type { NodeData } from './nodes.js';
 import { Node } from './nodes.js';
+import type { UserData } from './users.js';
+import { User } from './users.js';
+import { type ActivityFeedOptions, type ActivityLog } from './servers/activity.js';
 /** Resource limit values for a server group. @internal */
 export interface ServerGroupLimitsData {
     cpu_percent?: number | null;
@@ -14,6 +18,10 @@ export interface ServerGroupLimitsData {
     database?: number | null;
     allocation?: number | null;
 }
+/**
+ * A suspended group's reason. `null` when the group is active.
+ */
+export type SuspensionState = 'transferring' | 'restricted' | 'expired' | 'overdue' | 'maintenance';
 /** Raw API shape for a server group. @internal */
 export interface ServerGroupData {
     id: string;
@@ -21,13 +29,18 @@ export interface ServerGroupData {
     node_id: string;
     /** @see NodeData */
     node?: NodeData;
+    /** Namespaced owner reference, always present. */
+    owner_id: string;
+    owner?: UserData;
     build?: {
         cpu_threads?: number | null;
         io_weight?: number | null;
     } | null;
     limits?: ServerGroupLimitsData | null;
+    suspension_state: SuspensionState | null;
     created_at: ISODate;
     updated_at: ISODate;
+    deleted_at: ISODate | null;
 }
 /**
  * Resource allocation limits for a server group.
@@ -61,19 +74,29 @@ export declare class ServerGroup extends ReactiveResource {
     readonly id: NanoID;
     /** The ID of the node this group is deployed on. Always present. */
     readonly nodeId: NanoID;
-    /** The full node object. */
+    /** The full node object. Requires `?include=node`. */
     node: Node | undefined;
+    /** 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 owner. Requires `?include=owner`. */
+    owner: User | undefined;
     /** Build settings inherited by all servers in this group. */
     build: {
         cpuThreads: number | null | undefined;
         ioWeight: number | null | undefined;
     } | undefined;
-    /** Resource limits that apply to this group as a whole. */
+    /** Resource limits that apply to this group as a whole. Each field requires its own read permission. */
     limits: ServerGroupLimits | undefined;
+    /** The suspension reason, or `null` when the group is active. */
+    suspensionState: SuspensionState | null;
     /** When this server group was created. */
     createdAt: Date;
     /** When this server group was last updated. */
     updatedAt: Date;
+    /** When this group was soft-deleted, or `null` if active. */
+    deletedAt: Date | null;
     /** @internal */
     constructor(data: ServerGroupData);
 }
@@ -105,10 +128,92 @@ export interface CreateServerGroupPayload {
         allocation?: number;
     };
 }
+/** Valid include keys for server group endpoints. */
+export type ServerGroupInclude = 'node' | 'owner';
+/** Maps each {@link ServerGroupInclude} key to the field(s) it guarantees on the {@link ServerGroup} instance. */
+interface ServerGroupIncludeMap {
+    node: {
+        node: Node;
+    };
+    owner: {
+        owner: User;
+    };
+}
+/** A {@link ServerGroup} with specific include fields guaranteed to be populated. */
+export type ServerGroupWith<I extends readonly ServerGroupInclude[] = []> = ResourceWith<ServerGroup, ServerGroupIncludeMap, I>;
+/** Fields accepted when updating a server group. All optional. */
+export interface UpdateServerGroupPayload {
+    /** Reassign the owner (issuer ref `"user:<id>"` or a bare user id). */
+    ownerId?: string;
+    /** Resource limit changes (partial). */
+    limits?: {
+        ramMb?: number;
+        swapMb?: number;
+        storageMb?: number;
+        weightIo?: number;
+        cpuPercent?: number;
+        cpuThreads?: string;
+        backup?: number;
+        database?: number;
+        allocation?: number;
+    };
+    /** New expiry, or `null` to clear it. */
+    expiresAt?: Date | null;
+}
+/** An external identifier linking a server group to a billing/provider record. */
+export interface GroupIdentifier {
+    id: NanoID;
+    /** The provider key, e.g. `"whmcs"`. */
+    provider: string;
+    /** The provider's external id for this group. */
+    externalId: string;
+    /** When the identifier was last used, or `null`. */
+    lastUsedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** The billing provider backing a server group. */
+export type BillingProvider = 'whmcs';
+/** A server group's billing status. */
+export type BillingStatus = 'active' | 'suspended' | 'pending' | 'cancelled' | 'terminated';
+/** A server group's billing cycle. */
+export type BillingCycle = 'free' | 'onetime' | 'monthly' | 'quarterly' | 'semiannually' | 'annually' | 'biennially' | 'triennially';
+/** Provider-neutral billing information for a server group. */
+export interface BillingInfo {
+    provider: BillingProvider;
+    status: BillingStatus | null;
+    /** The recurring amount, as a decimal string. */
+    recurringAmount: string | null;
+    currency: string | null;
+    billingCycle: BillingCycle | null;
+    /** Next due date, as `"YYYY-MM-DD"`. */
+    nextDueDate: string | null;
+}
+/**
+ * Manages a server group's external identifiers.
+ *
+ * Access via `api.serverGroups.identifiers(groupId)`.
+ */
+export declare class GroupIdentifiersManager {
+    private readonly groupId;
+    private readonly http;
+    /** @internal */
+    constructor(groupId: NanoID, http: HttpClient);
+    /** List the group's identifiers. */
+    list(): Promise<GroupIdentifier[]>;
+    /** Link an external id for a provider to this group. */
+    link(provider: string, externalId: string): Promise<void>;
+    /** Remove a provider link from this group. */
+    unlink(provider: string): Promise<void>;
+}
 /** Typed events emitted by {@link ServerGroupsNamespace}. */
 export interface ServerGroupEvents {
     /** Fired after a server group is created. */
     created: ServerGroup;
+    /** Fired after a server group is updated. */
+    updated: ServerGroup;
+    /** Fired after a server group is deleted. */
+    deleted: NanoID;
 }
 /**
  * Namespace for server group management.
@@ -128,23 +233,52 @@ export declare class ServerGroupsNamespace extends ResourceNamespace<ServerGroup
     /**
      * Fetch a paginated list of server groups.
      *
-     * @param opts Pagination and search options.
+     * @param opts Pagination, search, and include options.
      */
-    list(opts?: {
+    list<const I extends readonly ServerGroupInclude[] = []>(opts?: {
         page?: number;
         perPage?: number;
-    }): Promise<Paginated<ServerGroup>>;
+    } & IncludeOptions<ServerGroupInclude, I>): Promise<Paginated<ServerGroupWith<I>>>;
     /**
      * Fetch a single server group by ID.
      *
-     * @param id The server group's NanoID.
+     * @param id   The server group's NanoID.
+     * @param opts Include options.
      */
-    get(id: NanoID): Promise<ServerGroup>;
+    get<const I extends readonly ServerGroupInclude[] = []>(id: NanoID, opts?: IncludeOptions<ServerGroupInclude, I>): Promise<ServerGroupWith<I>>;
     /**
      * Create a new server group.
      *
      * @param payload Server group creation parameters.
      */
     create(payload: CreateServerGroupPayload): Promise<ServerGroup>;
+    /** Update a server group's owner, limits, or expiry. */
+    update(id: NanoID, payload: UpdateServerGroupPayload): Promise<ServerGroup>;
+    /** Soft-delete a server group. Fails if it still has servers. */
+    delete(id: NanoID): Promise<void>;
+    /** Find a server group by one of its external identifiers. */
+    byIdentifier(provider: string, externalId: string): Promise<ServerGroup>;
+    /** Suspend a server group. Defaults to the `restricted` state. */
+    suspend(id: NanoID, state?: SuspensionState): Promise<ServerGroup>;
+    /** Lift a server group's suspension. */
+    unsuspend(id: NanoID): Promise<ServerGroup>;
+    /**
+     * Fetch a server group's billing information.
+     *
+     * @throws {@link ApiError} with `isNotFound === true` if the group has no billing info.
+     */
+    billing(id: NanoID): Promise<BillingInfo>;
+    /**
+     * Fetch a server group's activity feed.
+     *
+     * @param id   The server group's NanoID.
+     * @param opts Pagination, filters, and an optional `scope` (`group` or `server`).
+     */
+    activities(id: NanoID, opts?: ActivityFeedOptions & {
+        scope?: 'group' | 'server';
+    }): Promise<Paginated<ActivityLog>>;
+    /** Manage a server group's external identifiers. */
+    identifiers(groupId: NanoID): GroupIdentifiersManager;
 }
+export {};
 //# sourceMappingURL=server-groups.d.ts.map

package/esm/src/resources/server-groups.d.ts.map

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

package/esm/src/resources/server-groups.js

@@ -1,7 +1,9 @@
 import { ResourceNamespace } from '../namespace.js';
 import { ReactiveResource } from '../reactive.js';
-import { toNanoID } from '../types.js';
+import { joinIncludes, parseIssuerRef, toNanoID } from '../types.js';
 import { Node } from './nodes.js';
+import { User } from './users.js';
+import { listActivities } from './servers/activity.js';
 /**
  * A server group that ties one or more servers to a specific node with shared resource limits.
  *
@@ -12,22 +14,36 @@ export class ServerGroup extends ReactiveResource {
     id;
     /** The ID of the node this group is deployed on. Always present. */
     nodeId;
-    /** The full node object. */
+    /** The full node object. Requires `?include=node`. */
     node;
+    /** The owner's bare NanoID (parsed from the namespaced `owner_id`). Always present. */
+    ownerId;
+    /** The owner's issuer type, e.g. `'user'` or `'system'`. */
+    ownerType;
+    /** The owner. Requires `?include=owner`. */
+    owner;
     /** Build settings inherited by all servers in this group. */
     build;
-    /** Resource limits that apply to this group as a whole. */
+    /** Resource limits that apply to this group as a whole. Each field requires its own read permission. */
     limits;
+    /** The suspension reason, or `null` when the group is active. */
+    suspensionState;
     /** When this server group was created. */
     createdAt;
     /** When this server group was last updated. */
     updatedAt;
+    /** When this group was soft-deleted, or `null` if active. */
+    deletedAt;
     /** @internal */
     constructor(data) {
         super();
         this.id = toNanoID(data.id);
         this.nodeId = toNanoID(data.node_id);
         this.node = data.node ? new Node(data.node) : undefined;
+        const owner = parseIssuerRef(data.owner_id);
+        this.ownerId = owner.id;
+        this.ownerType = owner.type;
+        this.owner = data.owner ? new User(data.owner) : undefined;
         this.build = data.build ? { cpuThreads: data.build.cpu_threads, ioWeight: data.build.io_weight } : undefined;
         this.limits = data.limits
             ? {
@@ -40,8 +56,49 @@ export class ServerGroup extends ReactiveResource {
                 allocation: data.limits.allocation,
             }
             : undefined;
+        this.suspensionState = data.suspension_state ?? null;
         this.createdAt = new Date(data.created_at);
         this.updatedAt = new Date(data.updated_at);
+        this.deletedAt = data.deleted_at ? new Date(data.deleted_at) : null;
+    }
+}
+function makeGroupIdentifier(data) {
+    return {
+        id: toNanoID(data.id),
+        provider: data.provider,
+        externalId: data.external_id,
+        lastUsedAt: data.last_used_at ? new Date(data.last_used_at) : null,
+        createdAt: new Date(data.created_at),
+        updatedAt: new Date(data.updated_at),
+    };
+}
+/**
+ * Manages a server group's external identifiers.
+ *
+ * Access via `api.serverGroups.identifiers(groupId)`.
+ */
+export class GroupIdentifiersManager {
+    groupId;
+    http;
+    /** @internal */
+    constructor(groupId, http) {
+        this.groupId = groupId;
+        this.http = http;
+    }
+    /** List the group's identifiers. */
+    async list() {
+        const data = await this.http.get(`/servers/groups/${this.groupId}/identifiers`);
+        return data.map(makeGroupIdentifier);
+    }
+    /** Link an external id for a provider to this group. */
+    async link(provider, externalId) {
+        await this.http.post(`/servers/groups/${this.groupId}/identifiers/${encodeURIComponent(provider)}`, {
+            external_id: externalId,
+        });
+    }
+    /** Remove a provider link from this group. */
+    async unlink(provider) {
+        await this.http.delete(`/servers/groups/${this.groupId}/identifiers/${encodeURIComponent(provider)}`);
     }
 }
 /**
@@ -64,10 +121,14 @@ export class ServerGroupsNamespace extends ResourceNamespace {
     /**
      * Fetch a paginated list of server groups.
      *
-     * @param opts Pagination and search options.
+     * @param opts Pagination, search, and include options.
      */
     async list(opts = {}) {
-        const result = await this.http.list('/servers/groups', opts);
+        const extra = {};
+        const include = joinIncludes(opts);
+        if (include)
+            extra['include'] = include;
+        const result = await this.http.list('/servers/groups', opts, extra);
         const groups = result.data.map((d) => new ServerGroup(d));
         this.setCache(groups);
         return { ...result, data: groups };
@@ -75,10 +136,15 @@ export class ServerGroupsNamespace extends ResourceNamespace {
     /**
      * Fetch a single server group by ID.
      *
-     * @param id The server group's NanoID.
+     * @param id   The server group's NanoID.
+     * @param opts Include options.
      */
-    async get(id) {
-        const data = await this.http.get(`/servers/groups/${id}`);
+    async get(id, opts = {}) {
+        const params = {};
+        const include = joinIncludes(opts);
+        if (include)
+            params['include'] = include;
+        const data = await this.http.get(`/servers/groups/${id}`, { params });
         return new ServerGroup(data);
     }
     /**
@@ -108,4 +174,87 @@ export class ServerGroupsNamespace extends ResourceNamespace {
         this.emit('created', group);
         return group;
     }
+    /** Update a server group's owner, limits, or expiry. */
+    async update(id, payload) {
+        const body = {};
+        if (payload.ownerId !== undefined)
+            body['owner_id'] = payload.ownerId;
+        if (payload.expiresAt !== undefined) {
+            body['expires_at'] = payload.expiresAt === null ? null : payload.expiresAt.toISOString();
+        }
+        if (payload.limits) {
+            body['limits'] = {
+                ram_mb: payload.limits.ramMb,
+                swap_mb: payload.limits.swapMb,
+                storage_mb: payload.limits.storageMb,
+                weight_io: payload.limits.weightIo,
+                cpu_percent: payload.limits.cpuPercent,
+                cpu_threads: payload.limits.cpuThreads,
+                backup: payload.limits.backup,
+                database: payload.limits.database,
+                allocation: payload.limits.allocation,
+            };
+        }
+        const data = await this.http.patch(`/servers/groups/${id}`, body);
+        const group = new ServerGroup(data);
+        this.upsertCache(group);
+        this.emit('updated', group);
+        return group;
+    }
+    /** Soft-delete a server group. Fails if it still has servers. */
+    async delete(id) {
+        await this.http.delete(`/servers/groups/${id}`);
+        this.removeFromCache(id);
+        this.emit('deleted', id);
+    }
+    /** Find a server group by one of its external identifiers. */
+    async byIdentifier(provider, externalId) {
+        const data = await this.http.get(`/servers/groups/by-identifier/${encodeURIComponent(provider)}/${encodeURIComponent(externalId)}`);
+        return new ServerGroup(data);
+    }
+    /** Suspend a server group. Defaults to the `restricted` state. */
+    async suspend(id, state = 'restricted') {
+        const data = await this.http.post(`/servers/groups/${id}/suspend`, { state });
+        const group = new ServerGroup(data);
+        this.upsertCache(group);
+        this.emit('updated', group);
+        return group;
+    }
+    /** Lift a server group's suspension. */
+    async unsuspend(id) {
+        const data = await this.http.post(`/servers/groups/${id}/unsuspend`);
+        const group = new ServerGroup(data);
+        this.upsertCache(group);
+        this.emit('updated', group);
+        return group;
+    }
+    /**
+     * Fetch a server group's billing information.
+     *
+     * @throws {@link ApiError} with `isNotFound === true` if the group has no billing info.
+     */
+    async billing(id) {
+        const data = await this.http.get(`/servers/groups/${id}/billing`);
+        return {
+            provider: data.provider,
+            status: data.status,
+            recurringAmount: data.recurring_amount,
+            currency: data.currency,
+            billingCycle: data.billing_cycle,
+            nextDueDate: data.next_due_date,
+        };
+    }
+    /**
+     * Fetch a server group's activity feed.
+     *
+     * @param id   The server group's NanoID.
+     * @param opts Pagination, filters, and an optional `scope` (`group` or `server`).
+     */
+    activities(id, opts = {}) {
+        return listActivities(this.http, `/servers/groups/${id}/activities`, opts, opts.scope ? { scope: opts.scope } : {});
+    }
+    /** Manage a server group's external identifiers. */
+    identifiers(groupId) {
+        return new GroupIdentifiersManager(groupId, this.http);
+    }
 }