@meowpanel/api 0.3.0 → 0.4.0

package/script/src/resources/nodes.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NodesNamespace = exports.NodeAllocationsManager = exports.Node = exports.NodeAllocationIp = exports.NodeAllocationPort = exports.NodeType = exports.NodeLocation = void 0;
+exports.NodesNamespace = exports.NodeClassifierManager = exports.NodeAllocationsManager = exports.Node = exports.NodeAllocationIp = exports.NodeAllocationPort = exports.NodeType = exports.NodeLocation = void 0;
 const namespace_js_1 = require("../namespace.js");
 const reactive_js_1 = require("../reactive.js");
 const types_js_1 = require("../types.js");
-const members_js_1 = require("./members.js");
+const users_js_1 = require("./users.js");
 const hosts_js_1 = require("./hosts.js");
 const activity_js_1 = require("./servers/activity.js");
 /**
@@ -119,7 +119,7 @@ class NodeAllocationIp extends reactive_js_1.ReactiveResource {
         super();
         this.id = (0, types_js_1.toNanoID)(data.id);
         this.ip = data.ip;
-        this.ipAlias = data.ipAlias;
+        this.ipAlias = data.ip_alias;
         this.ports = data.ports.map((port) => new NodeAllocationPort(port));
         this.nodeId = (0, types_js_1.toNanoID)(data.node_id);
         this.node = data.node ? new Node(data.node) : undefined;
@@ -137,8 +137,6 @@ exports.NodeAllocationIp = NodeAllocationIp;
 class Node extends reactive_js_1.ReactiveResource {
     /** The node's unique NanoID. */
     id;
-    /** The issuer type, always `'node'`. */
-    issuerType;
     /**
      * Auto-generated display name in the format `{type}{num}{location}.{hostname}`,
      * e.g. `"a001use.host.example.com"`.
@@ -146,8 +144,10 @@ class Node extends reactive_js_1.ReactiveResource {
     name;
     /** Optional description of the node. */
     description;
-    /** The owner's NanoID. Always present. */
+    /** 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 full owner object. Requires `?include=owner`. */
     owner;
     /** The location's NanoID. Always present. */
@@ -162,11 +162,6 @@ class Node extends reactive_js_1.ReactiveResource {
     num;
     /** Resource limits configured for this node. */
     limits;
-    /**
-     * Daemon authentication token row id. `null` while the node is unclaimed,
-     * populated once a daemon redeems its install token.
-     */
-    authToken;
     /** Lifecycle state. See {@link NodeStatus}. */
     status;
     /** Timestamp of the first successful claim. `null` until claimed. */
@@ -185,21 +180,24 @@ class Node extends reactive_js_1.ReactiveResource {
     canAutoDeploy;
     /** `true` when the node is behind a reverse proxy. */
     isBehindProxy;
-    /** Internal notes visible to administrators. */
+    /** Internal notes. Requires `node.notes.read`. */
     notes;
     /** When this node was registered. */
     createdAt;
     /** When this node was last updated. */
     updatedAt;
+    /** When this node was soft-deleted, or `null` if active. */
+    deletedAt;
     /** @internal */
     constructor(data) {
         super();
         this.id = (0, types_js_1.toNanoID)(data.id);
-        this.issuerType = data.issuer_type;
         this.name = data.name;
         this.description = data.description;
-        this.ownerId = (0, types_js_1.toNanoID)(data.owner_id);
-        this.owner = data.owner ? new members_js_1.Member(data.owner) : undefined;
+        const owner = (0, types_js_1.parseIssuerRef)(data.owner_id);
+        this.ownerId = owner.id;
+        this.ownerType = owner.type;
+        this.owner = data.owner ? new users_js_1.User(data.owner) : undefined;
         this.locationId = (0, types_js_1.toNanoID)(data.location_id);
         this.location = data.location ? new NodeLocation(data.location) : undefined;
         this.typeId = (0, types_js_1.toNanoID)(data.type_id);
@@ -212,7 +210,6 @@ class Node extends reactive_js_1.ReactiveResource {
             diskOverallocateMb: data.limits.disk_overallocate_mb,
             uploadSizeMb: data.limits.upload_size_mb,
         };
-        this.authToken = data.auth_token;
         this.status = data.status;
         this.claimedAt = data.claimed_at ? new Date(data.claimed_at) : null;
         this.installTokenExpiresAt = data.install_token_expires_at === undefined
@@ -227,6 +224,7 @@ class Node extends reactive_js_1.ReactiveResource {
         this.notes = data.notes;
         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;
     }
 }
 exports.Node = Node;
@@ -280,6 +278,49 @@ class NodeAllocationsManager {
     }
 }
 exports.NodeAllocationsManager = NodeAllocationsManager;
+/**
+ * CRUD for a node classifier (location or type).
+ *
+ * Access via `api.nodes.locations` or `api.nodes.types`.
+ */
+class NodeClassifierManager {
+    http;
+    path;
+    make;
+    /** @internal */
+    constructor(http, path, make) {
+        this.http = http;
+        this.path = path;
+        this.make = make;
+    }
+    /** Fetch a paginated list. */
+    async list(opts = {}) {
+        const result = await this.http.list(this.path, opts);
+        return { ...result, data: result.data.map((d) => this.make(d)) };
+    }
+    /** Fetch a single entry by ID. */
+    async get(id) {
+        return this.make(await this.http.get(`${this.path}/${id}`));
+    }
+    /** Create a new entry. */
+    async create(payload) {
+        return this.make(await this.http.post(this.path, {
+            name: payload.name,
+            short: payload.short,
+            host_id: payload.hostId,
+            notes: payload.notes,
+        }));
+    }
+    /** Update an entry's name, short code, or notes. */
+    async update(id, payload) {
+        return this.make(await this.http.patch(`${this.path}/${id}`, payload));
+    }
+    /** Delete an entry. */
+    async delete(id) {
+        await this.http.delete(`${this.path}/${id}`);
+    }
+}
+exports.NodeClassifierManager = NodeClassifierManager;
 /**
  * Namespace for node management.
  *
@@ -293,9 +334,15 @@ exports.NodeAllocationsManager = NodeAllocationsManager;
  * ```
  */
 class NodesNamespace extends namespace_js_1.ResourceNamespace {
+    /** Manage node locations. */
+    locations;
+    /** Manage node types. */
+    types;
     /** @internal */
     constructor(http) {
         super(http);
+        this.locations = new NodeClassifierManager(http, '/nodes/locations', (d) => new NodeLocation(d));
+        this.types = new NodeClassifierManager(http, '/nodes/types', (d) => new NodeType(d));
     }
     /**
      * Fetch a paginated list of nodes.
@@ -364,6 +411,52 @@ class NodesNamespace extends namespace_js_1.ResourceNamespace {
             installTokenExpiresAt: new Date(data.install_token_expires_at),
         };
     }
+    /** Update a node's connection details, placement, limits, or flags. */
+    async update(id, payload) {
+        const body = {};
+        if (payload.fqdn !== undefined)
+            body['fqdn'] = payload.fqdn;
+        if (payload.scheme !== undefined)
+            body['scheme'] = payload.scheme;
+        if (payload.apiPort !== undefined)
+            body['api_port'] = payload.apiPort;
+        if (payload.sftpPort !== undefined)
+            body['sftp_port'] = payload.sftpPort;
+        if (payload.locationId !== undefined)
+            body['location_id'] = payload.locationId;
+        if (payload.typeId !== undefined)
+            body['type_id'] = payload.typeId;
+        if (payload.num !== undefined)
+            body['num'] = payload.num;
+        if (payload.description !== undefined)
+            body['description'] = payload.description;
+        if (payload.notes !== undefined)
+            body['notes'] = payload.notes;
+        if (payload.isMaintenanceMode !== undefined)
+            body['is_maintenance_mode'] = payload.isMaintenanceMode;
+        if (payload.canAutoDeploy !== undefined)
+            body['can_auto_deploy'] = payload.canAutoDeploy;
+        if (payload.isBehindProxy !== undefined)
+            body['is_behind_proxy'] = payload.isBehindProxy;
+        if (payload.limits) {
+            body['limits'] = {
+                memory_mb: payload.limits.memoryMb,
+                memory_overallocate_mb: payload.limits.memoryOverallocateMb,
+                disk_mb: payload.limits.diskMb,
+                disk_overallocate_mb: payload.limits.diskOverallocateMb,
+                upload_size_mb: payload.limits.uploadSizeMb,
+            };
+        }
+        const data = await this.http.patch(`/nodes/${id}`, body);
+        const node = new Node(data);
+        this.upsertCache(node);
+        return node;
+    }
+    /** Delete a node. */
+    async delete(id) {
+        await this.http.delete(`/nodes/${id}`);
+        this.removeFromCache(id);
+    }
     /**
      * Claim a node by redeeming its install token. Public endpoint, no
      * Authorization header. Returns a permanent daemon token; the install

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

@@ -0,0 +1,45 @@
+import type { ISODate } from '../types.js';
+/** Raw API shape for a permission grant. @internal */
+export interface PermissionGrantData {
+    permission: string;
+    is_allow: boolean;
+    scope: string | null;
+    expires_at: ISODate | null;
+    granted_at: ISODate;
+}
+/**
+ * A permission grant as returned by a grants endpoint.
+ *
+ * These are direct grants on the actor only, not role-derived and not expanded to
+ * ancestor scopes.
+ */
+export interface PermissionGrant {
+    /** The permission name, e.g. `"server.console.read"`. */
+    permission: string;
+    /** `true` for an allow grant, `false` for a deny. */
+    isAllow: boolean;
+    /** The namespaced scope (`"<type>:<id>"`), or `null` for a global grant. */
+    scope: string | null;
+    /** When the grant expires, or `null` if it never expires. */
+    expiresAt: Date | null;
+    /** When the grant was created. */
+    grantedAt: Date;
+}
+/** A permission grant to apply. */
+export interface PermissionGrantInput {
+    /** The permission name, e.g. `"server.console.read"`. */
+    permission: string;
+    /** Namespaced scope (`"<type>:<id>"`). Omit for a global grant. */
+    scope?: string;
+    /** `false` to create a deny grant. Defaults to allow. */
+    isAllow?: boolean;
+    /** Expiry. `null` clears an existing expiry; omit to leave it unchanged. */
+    expiresAt?: Date | null;
+}
+/** Map a raw grant to its client shape. @internal */
+export declare function parseGrant(data: PermissionGrantData): PermissionGrant;
+/** Serialize a grant input to its request body. @internal */
+export declare function grantToBody(input: PermissionGrantInput): Record<string, unknown>;
+/** Normalize one-or-many grant inputs to the array body the grant endpoints accept. @internal */
+export declare function grantsToBody(grants: PermissionGrantInput | PermissionGrantInput[]): Record<string, unknown>[];
+//# sourceMappingURL=permissions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../../src/src/resources/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6DAA6D;IAC7D,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,kCAAkC;IAClC,SAAS,EAAE,IAAI,CAAC;CAChB;AAED,mCAAmC;AACnC,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAQrE;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQhF;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAE7G"}

package/script/src/resources/permissions.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGrant = parseGrant;
+exports.grantToBody = grantToBody;
+exports.grantsToBody = grantsToBody;
+/** Map a raw grant to its client shape. @internal */
+function parseGrant(data) {
+    return {
+        permission: data.permission,
+        isAllow: data.is_allow,
+        scope: data.scope,
+        expiresAt: data.expires_at ? new Date(data.expires_at) : null,
+        grantedAt: new Date(data.granted_at),
+    };
+}
+/** Serialize a grant input to its request body. @internal */
+function grantToBody(input) {
+    const body = { permission: input.permission };
+    if (input.scope !== undefined)
+        body['scope'] = input.scope;
+    if (input.isAllow !== undefined)
+        body['is_allow'] = input.isAllow;
+    if (input.expiresAt !== undefined) {
+        body['expires_at'] = input.expiresAt === null ? null : input.expiresAt.toISOString();
+    }
+    return body;
+}
+/** Normalize one-or-many grant inputs to the array body the grant endpoints accept. @internal */
+function grantsToBody(grants) {
+    return (Array.isArray(grants) ? grants : [grants]).map(grantToBody);
+}

package/script/src/resources/request-logs.d.ts

@@ -0,0 +1,91 @@
+import type { HttpClient } from '../http.js';
+import { type ISODate, type NanoID, type Paginated } from '../types.js';
+import { User, type UserData } from './users.js';
+/** Raw API shape for a request-log line. @internal */
+interface RequestLogLineData {
+    id: string;
+    level: string;
+    message: string;
+    elapsed_time: number;
+    metadata?: Record<string, unknown>;
+    created_at: ISODate;
+}
+/** Raw API shape for a request log. @internal */
+export interface RequestLogData {
+    id: string;
+    method: string;
+    path: string;
+    issuer_id?: string;
+    issuer?: UserData;
+    ip?: string | null;
+    client_request_id: string | null;
+    logs?: RequestLogLineData[];
+    created_at: ISODate;
+}
+/** One log line emitted while handling a request. */
+export interface RequestLogLine {
+    id: NanoID;
+    /** Log level, e.g. `"info"`, `"error"`. */
+    level: string;
+    message: string;
+    /** Time elapsed at this line, in milliseconds. */
+    elapsedTime: number;
+    /** Structured metadata. Requires `application.logs.sensitive.read`. */
+    metadata: Record<string, unknown> | undefined;
+    createdAt: Date;
+}
+/**
+ * A logged HTTP request.
+ *
+ * The `clientRequestId` matches the `x-request-id` response header, so a client can
+ * correlate a response with its server-side log.
+ *
+ * Retrieved via `api.logs.requests` or `api.account.requestLogs`.
+ */
+export declare class RequestLog {
+    /** The request log's unique NanoID. */
+    readonly id: NanoID;
+    /** HTTP method, e.g. `"GET"`. */
+    readonly method: string;
+    /** Request path. */
+    readonly path: string;
+    /** The issuer's bare NanoID (parsed from the namespaced `issuer_id`), or `null` for an unauthenticated request. */
+    readonly issuerId: NanoID | null;
+    /** The issuer's type, e.g. `'user'`, `'system'`, or `null`. */
+    readonly issuerType: string | null;
+    /** The expanded issuer. Requires `?include=issuer`. */
+    readonly issuer: User | undefined;
+    /** The source IP. Requires `application.logs.sensitive.read`. */
+    readonly ip: string | null | undefined;
+    /** The client-supplied correlation id (matches the `x-request-id` header). */
+    readonly clientRequestId: string | null;
+    /** The request's log lines. Requires `?include=logs`. */
+    readonly logs: RequestLogLine[] | undefined;
+    /** When the request was received. */
+    readonly createdAt: Date;
+    /** @internal */
+    constructor(data: RequestLogData);
+}
+/** Which related data to include in a request-log response. */
+export type RequestLogInclude = 'logs' | 'issuer';
+/** Query options for a request-log feed. */
+export interface RequestLogFeedOptions {
+    page?: number;
+    perPage?: number;
+    /** Sort order by creation time. Defaults to oldest-first. */
+    sort?: 'created_at_asc' | 'created_at_desc';
+    /** Filter by HTTP method. */
+    method?: string;
+    /** Filter by request path. */
+    path?: string;
+    /** Filter by the issuer's auth-issuer id. */
+    issuerId?: string;
+    /** Filter by the client correlation id. */
+    clientRequestId?: string;
+    /** Related data to include. */
+    include?: RequestLogInclude[];
+}
+/** Fetch a request-log feed and map the entries to {@link RequestLog} instances. @internal */
+export declare function listRequestLogs(http: HttpClient, path: string, opts?: RequestLogFeedOptions): Promise<Paginated<RequestLog>>;
+export {};
+//# sourceMappingURL=request-logs.d.ts.map

package/script/src/resources/request-logs.d.ts.map

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

package/script/src/resources/request-logs.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestLog = void 0;
+exports.listRequestLogs = listRequestLogs;
+const types_js_1 = require("../types.js");
+const users_js_1 = require("./users.js");
+function makeRequestLogLine(data) {
+    return {
+        id: (0, types_js_1.toNanoID)(data.id),
+        level: data.level,
+        message: data.message,
+        elapsedTime: data.elapsed_time,
+        metadata: data.metadata,
+        createdAt: new Date(data.created_at),
+    };
+}
+/**
+ * A logged HTTP request.
+ *
+ * The `clientRequestId` matches the `x-request-id` response header, so a client can
+ * correlate a response with its server-side log.
+ *
+ * Retrieved via `api.logs.requests` or `api.account.requestLogs`.
+ */
+class RequestLog {
+    /** The request log's unique NanoID. */
+    id;
+    /** HTTP method, e.g. `"GET"`. */
+    method;
+    /** Request path. */
+    path;
+    /** The issuer's bare NanoID (parsed from the namespaced `issuer_id`), or `null` for an unauthenticated request. */
+    issuerId;
+    /** The issuer's type, e.g. `'user'`, `'system'`, or `null`. */
+    issuerType;
+    /** The expanded issuer. Requires `?include=issuer`. */
+    issuer;
+    /** The source IP. Requires `application.logs.sensitive.read`. */
+    ip;
+    /** The client-supplied correlation id (matches the `x-request-id` header). */
+    clientRequestId;
+    /** The request's log lines. Requires `?include=logs`. */
+    logs;
+    /** When the request was received. */
+    createdAt;
+    /** @internal */
+    constructor(data) {
+        this.id = (0, types_js_1.toNanoID)(data.id);
+        this.method = data.method;
+        this.path = data.path;
+        const issuer = data.issuer_id ? (0, types_js_1.parseIssuerRef)(data.issuer_id) : null;
+        this.issuerId = issuer ? issuer.id : null;
+        this.issuerType = issuer ? issuer.type : null;
+        this.issuer = data.issuer ? new users_js_1.User(data.issuer) : undefined;
+        this.ip = data.ip;
+        this.clientRequestId = data.client_request_id;
+        this.logs = data.logs?.map(makeRequestLogLine);
+        this.createdAt = new Date(data.created_at);
+    }
+}
+exports.RequestLog = RequestLog;
+/** Fetch a request-log feed and map the entries to {@link RequestLog} instances. @internal */
+async function listRequestLogs(http, path, opts = {}) {
+    const include = (0, types_js_1.joinIncludes)(opts);
+    const params = {
+        sort: opts.sort,
+        method: opts.method,
+        path: opts.path,
+        issuer_id: opts.issuerId,
+        client_request_id: opts.clientRequestId,
+        include,
+    };
+    const result = await http.list(path, { page: opts.page, perPage: opts.perPage }, params);
+    return { ...result, data: result.data.map((d) => new RequestLog(d)) };
+}

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

@@ -0,0 +1,128 @@
+import type { HttpClient } from '../http.js';
+import { ResourceNamespace } from '../namespace.js';
+import { ReactiveResource } from '../reactive.js';
+import { type ISODate, type NanoID, type Paginated, type ResourceColor } from '../types.js';
+import { type PermissionGrant, type PermissionGrantInput } from './permissions.js';
+/** Raw API shape for a role. @internal */
+export interface RoleData {
+    id: string;
+    title: string;
+    description: string | null;
+    color: ResourceColor | null;
+    /** Requires `permissions.roles.notes.read`. */
+    notes?: string | null;
+    created_at: ISODate;
+    updated_at: ISODate;
+}
+/**
+ * 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 declare class Role extends ReactiveResource {
+    /** The role's unique NanoID. */
+    readonly id: NanoID;
+    /** Display title, e.g. `"Support"`. */
+    title: string;
+    /** Optional description. */
+    description: string | null;
+    /** Color used in the UI for grouping, or `null`. */
+    color: ResourceColor | null;
+    /** Internal notes. Requires `permissions.roles.notes.read`. */
+    notes: string | null | undefined;
+    /** When this role was created. */
+    createdAt: Date;
+    /** When this role was last updated. */
+    updatedAt: Date;
+    /** @internal */
+    constructor(data: RoleData);
+    /** Apply raw API data to this role instance, updating all mutable fields. */
+    applyData(data: RoleData): void;
+}
+/** Fields accepted when creating a role. */
+export interface CreateRolePayload {
+    title: string;
+    description?: string;
+    color?: ResourceColor;
+    notes?: string;
+}
+/** Fields accepted when updating a role. All optional. */
+export interface UpdateRolePayload {
+    title?: string;
+    description?: string;
+    color?: ResourceColor;
+    notes?: string;
+}
+/** Typed events emitted by {@link RolesNamespace}. */
+export interface RoleEvents {
+    created: Role;
+    updated: Role;
+    deleted: NanoID;
+}
+/**
+ * Manages the permission grants attached to a specific role.
+ *
+ * Access via `api.roles.permissions(roleId)`.
+ */
+export declare class RolePermissionsManager {
+    private readonly roleId;
+    private readonly http;
+    /** @internal */
+    constructor(roleId: NanoID, http: HttpClient);
+    /** List the role's direct permission grants. */
+    list(): Promise<PermissionGrant[]>;
+    /**
+     * 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.
+     */
+    grant(grants: PermissionGrantInput | PermissionGrantInput[]): Promise<void>;
+    /**
+     * 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.
+     */
+    revoke(permission: string, scope?: string): Promise<void>;
+}
+/**
+ * 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 declare class RolesNamespace extends ResourceNamespace<Role, RoleEvents> {
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Fetch a paginated list of roles.
+     *
+     * @param opts Pagination and search options.
+     */
+    list(opts?: {
+        page?: number;
+        perPage?: number;
+        search?: string;
+    }): Promise<Paginated<Role>>;
+    /** Fetch a single role by ID. */
+    get(id: NanoID): Promise<Role>;
+    /** Create a new role. */
+    create(payload: CreateRolePayload): Promise<Role>;
+    /** Update a role's title, description, color, or notes. */
+    update(id: NanoID, payload: UpdateRolePayload): Promise<Role>;
+    /** Delete a role. Fails if the role is still assigned to any actor. */
+    delete(id: NanoID): Promise<void>;
+    /** Manage the permission grants attached to a role. */
+    permissions(roleId: NanoID): RolePermissionsManager;
+}
+//# sourceMappingURL=roles.d.ts.map

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

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