@minecraft/server-admin 1.0.0-beta.1.26.2-stable → 1.0.0-beta.1.26.20-preview.22

package/README.md

@@ -1,9 +1,9 @@
-# `@minecraft/server-admin`
-
-Contains types related to administering a Bedrock Dedicated Server. These types allow for the configuration of variables and secrets in JSON files in the Bedrock Dedicated Server folder. These types cannot be used on Minecraft clients or within Minecraft Realms.
-
-## **NOTE: This version of this module is still in pre-release.  It may change or it may be removed in future releases.**
-
-See full documentation for this module here:
-
+# `@minecraft/server-admin`
+
+Contains types related to administering a Bedrock Dedicated Server. These types allow for the configuration of variables and secrets in JSON files in the Bedrock Dedicated Server folder. These types cannot be used on Minecraft clients or within Minecraft Realms.
+
+## **NOTE: This version of this module is still in pre-release.  It may change or it may be removed in future releases.**
+
+See full documentation for this module here:
+
 https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/minecraft/server-admin/minecraft-server-admin

package/index.d.ts

@@ -40,6 +40,68 @@ export class AdminBeforeEvents {
     readonly asyncPlayerJoin: AsyncPlayerJoinBeforeEventSignal;
 }
 
+/**
+ * Controls the allow list for the server. Only available on
+ * dedicated server.
+ */
+export class AllowList {
+    private constructor();
+    /**
+     * @remarks
+     * This property can't be edited in restricted-execution mode.
+     *
+     */
+    enabled: boolean;
+    /**
+     * @remarks
+     * Adds a player to the server's allow list.
+     *
+     * @param player
+     * Player or player name that should be added to the allow
+     * list.
+     * @throws This function can throw errors.
+     *
+     * {@link AllowListModificationError}
+     *
+     * {@link minecraftserver.InvalidEntityError}
+     */
+    add(player: minecraftserver.Player | string): void;
+    /**
+     * @remarks
+     * Returns if the player is in the server's allow list.
+     *
+     * @param player
+     * Player or player name that should be checked for.
+     * @throws This function can throw errors.
+     *
+     * {@link minecraftserver.InvalidEntityError}
+     */
+    contains(player: minecraftserver.Player | string): boolean;
+    /**
+     * @remarks
+     * Reloads the server's allow list from disk.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link AllowListFileReloadError}
+     */
+    reloadFile(): void;
+    /**
+     * @remarks
+     * Removes a player from the server's allow list.
+     *
+     * @param player
+     * Player or player name that should be removed from the allow
+     * list.
+     * @throws This function can throw errors.
+     *
+     * {@link AllowListModificationError}
+     *
+     * {@link minecraftserver.InvalidEntityError}
+     */
+    remove(player: minecraftserver.Player | string): void;
+}
+
 /**
  * The data available before a player joins the world.
  */
@@ -120,6 +182,117 @@ export class AsyncPlayerJoinBeforeEventSignal {
     unsubscribe(callback: (arg0: AsyncPlayerJoinBeforeEvent) => Promise<void>): boolean;
 }
 
+/**
+ * Contains apis that are only available when in Bedrock
+ * Dedicated Server.
+ */
+export class DedicatedServerUtils {
+    private constructor();
+    /**
+     * @remarks
+     * Returns an object that manages the server's allow list.
+     *
+     */
+    readonly allowList: AllowList;
+    /**
+     * @remarks
+     * Returns an object that manages the level's storage.
+     *
+     */
+    readonly levelStorage: LevelStorage;
+    /**
+     * @remarks
+     * Reloads the cdn configuration from disk.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link minecraftcommon.EngineError}
+     */
+    reloadCDNConfig(): void;
+    /**
+     * @remarks
+     * Reloads the permissions for the server from disk.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link minecraftcommon.EngineError}
+     */
+    reloadPermissions(): void;
+    /**
+     * @remarks
+     * Reloads the script configuration for the server from disk.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link minecraftcommon.EngineError}
+     */
+    reloadScriptingConfig(): void;
+    /**
+     * @remarks
+     * Shuts down the dedicated server.
+     *
+     */
+    stopServer(): void;
+}
+
+/**
+ * Controls how the server saves to disk. Only available on
+ * dedicated server.
+ */
+export class LevelStorage {
+    private constructor();
+    /**
+     * @remarks
+     * Disables the server writing to the world files and begins
+     * creating a snapshot.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link LevelStorageSaveStateChangeError}
+     */
+    saveHold(): void;
+    /**
+     * @remarks
+     * Returns the path and size of every file in the current
+     * snapshot if a snapshot is being taken.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link LevelStorageSaveStateChangeError}
+     */
+    saveQuery(): LevelStorageQuerySnapshotFile[];
+    /**
+     * @remarks
+     * Re-enables server writing world state to files and removes
+     * snapshot.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link LevelStorageSaveStateChangeError}
+     */
+    saveResume(): void;
+}
+
+/**
+ * Contains information about a file that was gathered during a
+ * snapshot.
+ */
+export class LevelStorageQuerySnapshotFile {
+    private constructor();
+    /**
+     * @remarks
+     * The path to the file in the snapshot.
+     *
+     */
+    readonly fileName: string;
+    /**
+     * @remarks
+     * The size of the file in the snapshot.
+     *
+     */
+    readonly fileSize: number;
+}
+
 /**
  * This represents a placeholder object that represents a
  * secret string. The contents of that string are not available
@@ -134,28 +307,28 @@ export class SecretString {
  * configuration.
  * @example getPlayerProfile.ts
  * ```typescript
- * import { variables, secrets } from "@minecraft/server-admin";
- * import { http, HttpRequest, HttpRequestMethod, HttpHeader, HttpResponse } from "@minecraft/server-net";
+ * import { variables, secrets } from '@minecraft/server-admin';
+ * import { http, HttpRequest, HttpRequestMethod, HttpHeader, HttpResponse } from '@minecraft/server-net';
  *
  * const serverUrl = variables.get('serverEndpoint');
  *
  * function getPlayerProfile(playerId: string): Promise<HttpResponse> {
- *     const req = new HttpRequest(serverUrl + 'getPlayerProfile');
+ *   const req = new HttpRequest(serverUrl + 'getPlayerProfile');
  *
- *     req.body = JSON.stringify({
- *         playerId,
- *     });
+ *   req.body = JSON.stringify({
+ *     playerId,
+ *   });
  *
- *     const authTokenSec = secrets.get('authtoken');
+ *   const authTokenSec = secrets.get('authtoken');
  *
- *     if (!authTokenSec) {
- *         throw new Error('authtoken secret not defined.');
- *     }
+ *   if (!authTokenSec) {
+ *     throw new Error('authtoken secret not defined.');
+ *   }
  *
- *     req.method = HttpRequestMethod.Post;
- *     req.headers = [new HttpHeader('Content-Type', 'application/json'), new HttpHeader('auth', authTokenSec)];
+ *   req.method = HttpRequestMethod.Post;
+ *   req.headers = [new HttpHeader('Content-Type', 'application/json'), new HttpHeader('auth', authTokenSec)];
  *
- *     return http.request(req);
+ *   return http.request(req);
  * }
  * ```
  */
@@ -187,28 +360,28 @@ export class ServerSecrets {
  * configuration.
  * @example getPlayerProfile.ts
  * ```typescript
- * import { variables, secrets } from "@minecraft/server-admin";
- * import { http, HttpRequest, HttpRequestMethod, HttpHeader, HttpResponse } from "@minecraft/server-net";
+ * import { variables, secrets } from '@minecraft/server-admin';
+ * import { http, HttpRequest, HttpRequestMethod, HttpHeader, HttpResponse } from '@minecraft/server-net';
  *
  * const serverUrl = variables.get('serverEndpoint');
  *
  * function getPlayerProfile(playerId: string): Promise<HttpResponse> {
- *     const req = new HttpRequest(serverUrl + 'getPlayerProfile');
+ *   const req = new HttpRequest(serverUrl + 'getPlayerProfile');
  *
- *     req.body = JSON.stringify({
- *         playerId,
- *     });
+ *   req.body = JSON.stringify({
+ *     playerId,
+ *   });
  *
- *     const authTokenSec = secrets.get('authtoken');
+ *   const authTokenSec = secrets.get('authtoken');
  *
- *     if (!authTokenSec) {
- *         throw new Error('authtoken secret not defined.');
- *     }
+ *   if (!authTokenSec) {
+ *     throw new Error('authtoken secret not defined.');
+ *   }
  *
- *     req.method = HttpRequestMethod.Post;
- *     req.headers = [new HttpHeader('Content-Type', 'application/json'), new HttpHeader('auth', authTokenSec)];
+ *   req.method = HttpRequestMethod.Post;
+ *   req.headers = [new HttpHeader('Content-Type', 'application/json'), new HttpHeader('auth', authTokenSec)];
  *
- *     return http.request(req);
+ *   return http.request(req);
  * }
  * ```
  */
@@ -265,6 +438,42 @@ export interface TransferPlayerNetherNetOptions {
     netherNetId: string;
 }
 
+/**
+ * An error that is thrown when the allow list file fails to
+ * reload.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class AllowListFileReloadError extends Error {
+    private constructor();
+}
+
+/**
+ * An error which is thrown when modifying the allow list has
+ * failed.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class AllowListModificationError extends Error {
+    private constructor();
+}
+
+/**
+ * An error which is thrown when attempting to deop a player
+ * which cannot have their permissions removed.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class CannotDeopPlayerError extends Error {
+    private constructor();
+}
+
+/**
+ * An error which is thrown when attempting to kick a player
+ * who cannot be kicked.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class CannotKickPlayerError extends Error {
+    private constructor();
+}
+
 /**
  * An error that is thrown when trying to interact with a join
  * event and the player is disconnected.
@@ -279,9 +488,81 @@ export class DisconnectedError extends Error {
      * This property can be read in early-execution mode.
      *
      */
-    id: string;
+    readonly id: string;
 }
 
+/**
+ * An error that is thrown when level storage save state
+ * management are used out of sequence or are repeated in an
+ * invalid way.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class LevelStorageSaveStateChangeError extends Error {
+    private constructor();
+}
+
+/**
+ * An error which is thrown when attempting to op a player that
+ * already has op permissions.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class PlayerAlreadyOpError extends Error {
+    private constructor();
+}
+
+/**
+ * @remarks
+ * Removes the player's op permissions.
+ *
+ * This function can't be called in restricted-execution mode.
+ *
+ * @param player
+ * Player to remove permissions from.
+ * @throws This function can throw errors.
+ *
+ * {@link CannotDeopPlayerError}
+ *
+ * {@link minecraftcommon.EngineError}
+ *
+ * {@link minecraftcommon.InvalidArgumentError}
+ */
+export function deopPlayer(player: minecraftserver.Player): void;
+/**
+ * @remarks
+ * Kicks a player from the server.
+ *
+ * This function can't be called in restricted-execution mode.
+ *
+ * @param player
+ * Player to kick.
+ * @param reason
+ * Reason for kicking the player.
+ * @throws This function can throw errors.
+ *
+ * {@link CannotKickPlayerError}
+ *
+ * {@link minecraftcommon.EngineError}
+ *
+ * {@link minecraftcommon.InvalidArgumentError}
+ */
+export function kickPlayer(player: minecraftserver.Player, reason?: string): void;
+/**
+ * @remarks
+ * Gives the player op permissions.
+ *
+ * This function can't be called in restricted-execution mode.
+ *
+ * @param player
+ * Player to add permissions to.
+ * @throws This function can throw errors.
+ *
+ * {@link minecraftcommon.EngineError}
+ *
+ * {@link minecraftcommon.InvalidArgumentError}
+ *
+ * {@link PlayerAlreadyOpError}
+ */
+export function opPlayer(player: minecraftserver.Player): void;
 /**
  * @remarks
  * Transfer player to another server.
@@ -299,6 +580,13 @@ export function transferPlayer(
     options: TransferPlayerIpPortOptions | TransferPlayerNetherNetOptions,
 ): void;
 export const beforeEvents: AdminBeforeEvents;
+/**
+ * @remarks
+ * A globally available, optional object that contains
+ * dedicated-server only apis.
+ *
+ */
+export const dedicatedServer: DedicatedServerUtils | undefined;
 /**
  * @remarks
  * A globally available object that returns a list of

package/package.json

@@ -1,20 +1,20 @@
-{
-  "name": "@minecraft/server-admin",
-  "version": "1.0.0-beta.1.26.2-stable",
-  "description": "",
-  "contributors": [
-    {
-      "name": "Jake Shirley",
-      "email": "jake@xbox.com"
-    },
-    {
-      "name": "Mike Ammerlaan",
-      "email": "mikeam@microsoft.com"
-    }
-  ],
-  "peerDependencies": {
-    "@minecraft/common": "^1.0.0",
-    "@minecraft/server": "^1.17.0 || ^2.0.0"
-  },
-  "license": "MIT"
+{
+  "name": "@minecraft/server-admin",
+  "version": "1.0.0-beta.1.26.20-preview.22",
+  "description": "",
+  "contributors": [
+    {
+      "name": "Jake Shirley",
+      "email": "jake@xbox.com"
+    },
+    {
+      "name": "Mike Ammerlaan",
+      "email": "mikeam@microsoft.com"
+    }
+  ],
+  "peerDependencies": {
+    "@minecraft/common": "^1.0.0",
+    "@minecraft/server": "^1.17.0 || ^2.0.0"
+  },
+  "license": "MIT"
 }