@minecraft/server-admin 1.0.0-beta.00001b50 → 1.0.0-beta.1.12.111-stable

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.
-
-## **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
+# `@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

@@ -1,81 +1,290 @@
-// Type definitions for Minecraft Bedrock Edition script APIs
-// Project: https://docs.microsoft.com/minecraft/creator/
-// Definitions by: Jake Shirley <https://github.com/JakeShirley>
-//                 Mike Ammerlaan <https://github.com/mammerla>
-
-/* *****************************************************************************
-   Copyright (c) Microsoft Corporation.
-   ***************************************************************************** */
-/**
- * @packageDocumentation
- * 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.
- *
- * Manifest Details
- * ```json
- * {
- *   "module_name": "@minecraft/server-admin",
- *   "version": "1.0.0-beta.00001b50"
- * }
- * ```
- *
- */
-/**
- * This represents a placeholder object that represents a
- * secret string. The contents of that string are not available
- * to script; this object is just a placeholder.
- */
-// tslint:disable-next-line:no-unnecessary-class
-export class SecretString {
-    constructor(value: string);
-}
-/**
- * A collection of server secrets defined in dedicated server
- * configuration.
- */
-export class ServerSecrets {
-    /**
-     * A list of available, configured server secrets.
-     */
-    readonly names: string[];
-    /**
-     * @remarks
-     * Returns a SecretString that is a placeholder for a secret
-     * configured in a JSON file. In certain objects, like an
-     * HttpHeader, this Secret is resolved at the time of execution
-     * but is not made available to the script environment.
-     * @param name
-     */
-    get(name: string): SecretString;
-    protected constructor();
-}
-/**
- * A collection of server variables defined in dedicated server
- * configuration.
- */
-export class ServerVariables {
-    /**
-     * A list of available, configured server variables.
-     */
-    readonly names: string[];
-    /**
-     * @remarks
-     * Returns the value of variable that has been configured in a
-     * dedicated server configuration JSON file.
-     * @param name
-     */
-    get(name: string): any;
-    protected constructor();
-}
-/**
- * A globally available object that returns a list of
- * dedicated-server configured secrets.
- */
-export const secrets: ServerSecrets;
-/**
- * A globally available object that returns a list of
- * dedicated-server configured variables.
- */
-export const variables: ServerVariables;
+// Type definitions for Minecraft Bedrock Edition script APIs
+// Project: https://docs.microsoft.com/minecraft/creator/
+// Definitions by: Jake Shirley <https://github.com/JakeShirley>
+//                 Mike Ammerlaan <https://github.com/mammerla>
+
+/* *****************************************************************************
+   Copyright (c) Microsoft Corporation.
+   ***************************************************************************** */
+/**
+ * @beta
+ * @packageDocumentation
+ * 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.
+ *
+ * Manifest Details
+ * ```json
+ * {
+ *   "module_name": "@minecraft/server-admin",
+ *   "version": "1.0.0-beta"
+ * }
+ * ```
+ *
+ */
+import * as minecraftcommon from '@minecraft/common';
+import * as minecraftserver from '@minecraft/server';
+export class AdminBeforeEvents {
+    private constructor();
+    /**
+     * @remarks
+     * This event is fired before a player joins the world. Unlike
+     * other before events, this event is a before event that you
+     * can delay several ticks by not resolving the promise
+     * returned in the subscribe function. If the promise is
+     * rejected, the client is rejected.
+     *
+     */
+    readonly asyncPlayerJoin: AsyncPlayerJoinBeforeEventSignal;
+}
+
+/**
+ * The data available before a player joins the world.
+ */
+export class AsyncPlayerJoinBeforeEvent {
+    private constructor();
+    /**
+     * @remarks
+     * The player's name
+     *
+     */
+    readonly name: string;
+    /**
+     * @remarks
+     * An identifier that can be used to identify a player across
+     * sessions.
+     *
+     */
+    readonly persistentId: string;
+    /**
+     * @remarks
+     * Call this to disconnect a player. They will be allowed to
+     * try to join again.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link DisconnectedError}
+     */
+    disconnect(reason?: string): void;
+    /**
+     * @remarks
+     * Will return true if the player is still waiting to join the
+     * world. If they disconnect then it will return false.
+     *
+     */
+    isValid(): boolean;
+}
+
+export class AsyncPlayerJoinBeforeEventSignal {
+    private constructor();
+    /**
+     * @remarks
+     * Add a callback that's ran before a player joins the world.
+     * This callback returns a promise and the player won't join
+     * until that promise is resolved. If the promise is not
+     * resolved within a reasonable time, the player joining will
+     * be rejected. If the player joining leaves/disconnects, then
+     * the event data's isValid will return false.
+     *
+     */
+    subscribe(
+        callback: (arg0: AsyncPlayerJoinBeforeEvent) => Promise<void>,
+    ): (arg0: AsyncPlayerJoinBeforeEvent) => Promise<void>;
+    unsubscribe(callback: (arg0: AsyncPlayerJoinBeforeEvent) => Promise<void>): boolean;
+}
+
+/**
+ * This represents a placeholder object that represents a
+ * secret string. The contents of that string are not available
+ * to script; this object is just a placeholder.
+ */
+export class SecretString {
+    constructor(value: string);
+}
+
+/**
+ * A collection of server secrets defined in dedicated server
+ * configuration.
+ * @example getPlayerProfile.ts
+ * ```typescript
+ * 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');
+ *
+ *     req.body = JSON.stringify({
+ *         playerId,
+ *     });
+ *
+ *     const authTokenSec = secrets.get('authtoken');
+ *
+ *     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)];
+ *
+ *     return http.request(req);
+ * }
+ * ```
+ */
+export class ServerSecrets {
+    private constructor();
+    /**
+     * @remarks
+     * A list of available, configured server secrets.
+     *
+     */
+    readonly names: string[];
+    /**
+     * @remarks
+     * Returns a SecretString that is a placeholder for a secret
+     * configured in a JSON file. In certain objects, like an
+     * HttpHeader, this Secret is resolved at the time of execution
+     * but is not made available to the script environment.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * This function can be called in early-execution mode.
+     *
+     */
+    get(name: string): SecretString | undefined;
+}
+
+/**
+ * A collection of server variables defined in dedicated server
+ * configuration.
+ * @example getPlayerProfile.ts
+ * ```typescript
+ * 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');
+ *
+ *     req.body = JSON.stringify({
+ *         playerId,
+ *     });
+ *
+ *     const authTokenSec = secrets.get('authtoken');
+ *
+ *     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)];
+ *
+ *     return http.request(req);
+ * }
+ * ```
+ */
+export class ServerVariables {
+    private constructor();
+    /**
+     * @remarks
+     * A list of available, configured server variables.
+     *
+     */
+    readonly names: string[];
+    /**
+     * @remarks
+     * Returns the value of variable that has been configured in a
+     * dedicated server configuration JSON file.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * This function can be called in early-execution mode.
+     *
+     */
+    get(name: string): unknown | undefined;
+}
+
+/**
+ * Options when transferring a player to a server that supports
+ * direct host/port connections.
+ */
+export interface TransferPlayerIpPortOptions {
+    /**
+     * @remarks
+     * Hostname of the destination server.
+     *
+     */
+    hostname: string;
+    /**
+     * @remarks
+     * Port of the destination server.
+     *
+     */
+    port: number;
+}
+
+/**
+ * Options when transferring a player to a server that supports
+ * NetherNet connections.
+ */
+export interface TransferPlayerNetherNetOptions {
+    /**
+     * @remarks
+     * NetherNet ID of the destination server.
+     *
+     */
+    netherNetId: string;
+}
+
+/**
+ * An error that is thrown when trying to interact with a join
+ * event and the player is disconnected.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class DisconnectedError extends Error {
+    private constructor();
+    /**
+     * @remarks
+     * The id of the player that was disconnected.
+     *
+     * This property can be read in early-execution mode.
+     *
+     */
+    id: string;
+}
+
+/**
+ * @remarks
+ * Transfer player to another server.
+ *
+ * This function can't be called in read-only mode.
+ *
+ * @param player
+ * Player to transfer.
+ * @param options
+ * Options for where to send the player.
+ * @throws This function can throw errors.
+ */
+export function transferPlayer(
+    player: minecraftserver.Player,
+    options: TransferPlayerIpPortOptions | TransferPlayerNetherNetOptions,
+): void;
+export const beforeEvents: AdminBeforeEvents;
+/**
+ * @remarks
+ * A globally available object that returns a list of
+ * dedicated-server configured secrets.
+ *
+ */
+export const secrets: ServerSecrets;
+/**
+ * @remarks
+ * A globally available object that returns a list of
+ * dedicated-server configured variables.
+ *
+ */
+export const variables: ServerVariables;

package/package.json

@@ -1,16 +1,20 @@
-{
-  "name": "@minecraft/server-admin",
-  "version": "1.0.0-beta.00001b50",
-  "description": "",
-  "contributors": [
-    {
-      "name": "Jake Shirley",
-      "email": "jake@xbox.com"
-    },
-    {
-      "name": "Mike Ammerlaan",
-      "email": "mikeam@microsoft.com"
-    }
-  ],
-  "license": "MIT"
+{
+  "name": "@minecraft/server-admin",
+  "version": "1.0.0-beta.1.12.111-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"
 }

package/.eslintrc.json

@@ -1,23 +0,0 @@
-{
-    "env": {
-        "browser": true,
-        "es2021": true
-    },
-    "extends": [
-        "eslint:recommended",
-        "plugin:@typescript-eslint/recommended"
-    ],
-    "overrides": [
-    ],
-    "parser": "@typescript-eslint/parser",
-    "parserOptions": {
-        "ecmaVersion": "latest",
-        "sourceType": "module"
-    },
-    "plugins": [
-        "@typescript-eslint"
-    ],
-    "rules": {
-        "@typescript-eslint/no-explicit-any": "off"
-    }
-}

package/tests.ts

@@ -1,3 +0,0 @@
-import * as serverAdmin from '@minecraft/server-admin';
-
-serverAdmin.secrets.get('authtoken');

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-      "module": "commonjs",
-      "lib": ["es6"],
-      "target": "es6",
-      "forceConsistentCasingInFileNames": true,
-      "noEmit": true,
-      "noImplicitAny": true,
-      "noImplicitThis": true,
-      "strictFunctionTypes": true,
-      "strictNullChecks": true,
-      "baseUrl": "../",
-      "typeRoots": ["../"],
-      "types": []
-  },
-  "files": [
-      "index.d.ts",
-      "tests.ts"
-  ]
-}