Merge branch 'main' into doc_improvements

package.json

@@ -22,7 +22,7 @@
         "lint": "eslint src",
         "pack": "pnpm pack --pack-destination packs"
     },
-    "homepage": "https://thephar.github.io/archipelago.js/",
+    "homepage": "https://archipelago.js.org",
     "repository": "https://github.com/ThePhar/archipelago.js.git",
     "bugs": "https://github.com/ThePhar/archipelago.js/issues",
     "devDependencies": {

src/api/constants.ts

@@ -22,7 +22,7 @@ export const clientStatuses = {
 } as const;
 
 /**
- * Bit flags that define the special characteristics of a {@link NetworkItem}.
+ * Bit flags that define the special characteristics of a {@link API.NetworkItem}.
  */
 export const itemClassifications = {
     /** If set, indicates the item may unlock logical advancement. */
@@ -35,7 +35,7 @@ export const itemClassifications = {
     trap: 0b100,
 
     /** A shorthand with no flags set, also known as 'filler' or 'junk' items. */
-    normal: 0,
+    none: 0,
 } as const;
 
 /**
@@ -48,13 +48,13 @@ export const itemsHandlingFlags = {
     /** Indicates the client get items sent from other worlds. */
     others: 0b001,
 
-    /** Indicates the client get items sent from your own world. Requires `REMOTE_DIFFERENT_WORLDS` to be set. */
+    /** Indicates the client get items sent from your own world. Requires `others` bitflag to be set. */
     own: 0b010,
 
-    /** Indicates the client get your starting inventory sent. Requires `REMOTE_DIFFERENT_WORLDS` to be set. */
+    /** Indicates the client get your starting inventory sent. Requires `others` bitflag to be set. */
     starting: 0b100,
 
-    /** Shorthand for `REMOTE_DIFFERENT_WORLDS`, `REMOTE_OWN_WORLD`, and `REMOTE_STARTING_INVENTORY`. */
+    /** Shorthand for `others`, `own`, and `starting`. */
     all: 0b111,
 } as const;
 

src/classes/Client.ts

@@ -97,9 +97,9 @@ export class Client {
      * @param name The slot name this client will be connecting to.
      * @param game The game name this client will be connecting to. If omitted, client will connect in "TextOnly" mode.
      * @param options Additional optional connection arguments.
-     * @throws ArgumentError If slot name is empty.
-     * @throws LoginError If the server refuses the authentication attempt.
-     * @throws TypeError If provided URL is malformed or invalid protocol.
+     * @throws {@link ArgumentError} if slot name is empty.
+     * @throws {@link LoginError} if the server refuses the authentication attempt.
+     * @throws {@link TypeError} if provided URL is malformed or invalid protocol.
      * @remarks If the port is omitted, the client will default to `38281` (AP default).
      *
      * If the protocol is omitted, client will attempt to connect via wss, then fallback to ws if unsuccessful.
@@ -211,7 +211,7 @@ export class Client {
     /**
      * Update the client status for the current player. For a list of known client statuses, see {@link clientStatuses}.
      * @param status The status to change to.
-     * @throws UnauthenticatedError If not connected and authenticated.
+     * @throws {@link UnauthenticatedError} if not connected and authenticated.
      * @remarks The server will automatically set the player's status to {@link clientStatuses.disconnected} when all
      * clients connected to this slot have disconnected, set the status to {@link clientStatuses.connected} if a client
      * connects to this slot when previously set to {@link clientStatuses.disconnected}, or ignores any future updates
@@ -236,7 +236,7 @@ export class Client {
     /**
      * A shorthand for running `Client.updateStatus(clientStatuses.goal)`. Once set, cannot be changed and if release
      * and/or collect is set to automatic, will release/collect all items.
-     * @throws UnauthenticatedError If not connected and authenticated.
+     * @throws {@link UnauthenticatedError} if not connected and authenticated.
      */
     public goal(): void {
         this.updateStatus(clientStatuses.goal);
@@ -245,7 +245,7 @@ export class Client {
     /**
      * Request the server update this client's tags.
      * @param tags Tags to replace the current ones.
-     * @throws UnauthenticatedError If not connected and authenticated.
+     * @throws {@link UnauthenticatedError} if not connected and authenticated.
      */
     public updateTags(tags: string[]): void {
         if (!this.authenticated) {
@@ -258,7 +258,7 @@ export class Client {
     /**
      * Request the server update the kinds of item received events this client should receive.
      * @param items New item handling flags.
-     * @throws UnauthenticatedError If not connected and authenticated.
+     * @throws {@link UnauthenticatedError} if not connected and authenticated.
      */
     public updateItemsHandling(items: number): void {
         if (!this.authenticated) {
@@ -271,7 +271,7 @@ export class Client {
     /**
      * Marks a list of locations as checked on the server.
      * @param locations Location ids to check.
-     * @throws UnauthenticatedError If attempting to check locations while not authenticated.
+     * @throws {@link UnauthenticatedError} if attempting to check locations while not authenticated.
      * @remarks Locations that do not exist or have already been checked in the multi-world are ignored.
      */
     public check(...locations: number[]): void {
@@ -294,7 +294,7 @@ export class Client {
      * relevant clients.
      * - If set to `2`, this packet will create hints for all locations in this packet and broadcast only new hints to
      * all relevant clients.
-     * @throws UnauthenticatedError If attempting to scout locations while not authenticated.
+     * @throws {@link UnauthenticatedError} if attempting to scout locations while not authenticated.
      */
     public async scout(locations: number[], createHint: 0 | 1 | 2 = 0): Promise<Item[]> {
         if (!this.authenticated) {
@@ -326,7 +326,7 @@ export class Client {
      * @param targets.slots Specific slots that should receive this bounce.
      * @param targets.tags Specific clients with these tags that should receive this bounce.
      * @param data The json-serializable data to send.
-     * @throws UnauthenticatedError If attempting to send a bounce while not authenticated.
+     * @throws {@link UnauthenticatedError} if attempting to send a bounce while not authenticated.
      * @remarks If no targets are specified, no clients will receive this bounce packet.
      */
     public bounce(targets: { games?: string[], slots?: number[], tags?: string[] }, data: JSONRecord): void {

src/classes/Item.ts

@@ -88,7 +88,7 @@ export class Item {
 
     /** Returns `true` if this item has no special flags. */
     public get filler(): boolean {
-        return this.flags === itemClassifications.normal;
+        return this.flags === itemClassifications.none;
     }
 
     /** Returns the item classification bitflags for this item. */

src/classes/managers/DataStorageManager.ts

@@ -146,7 +146,7 @@ export class DataStorageManager {
      * perform certain operations, just chain additional methods until finished, then call `prepare()`.
      * @param key The key to manipulate.
      * @param _default The default value to be used if key does not exist.
-     * @throws TypeError if attempting to modify a read only key.
+     * @throws {@link TypeError} if attempting to modify a read only key.
      * @example
      * // Prepare key "my-key" and set initial value to 100, if key doesn't exist.
      * client.storage

src/classes/managers/DeathLinkManager.ts

@@ -69,7 +69,7 @@ export class DeathLinkManager extends EventBasedManager<DeathEvents> {
      * multiplayer game.
      * @param cause Optional text explaining the cause of death. When provided, this should include the player's name.
      * (e.g., `Phar drowned in a vat of kittens.`)
-     * @throws UnauthenticatedError If attempting to send a death link before authenticating to the server.
+     * @throws {@link UnauthenticatedError} if attempting to send a death link before authenticating to the server.
      * @remarks DeathLinks sent from this client will not fire a {@link DeathEvents.deathReceived} event to avoid
      * an infinite feedback loop of deaths.
      */

src/classes/managers/MessageManager.ts

@@ -51,7 +51,7 @@ export class MessageManager extends EventBasedManager<MessageEvents> {
      * Sends a chat message to the server.
      * @param text The textual message to broadcast to all connected clients.
      * @returns A promise that resolves when the server has broadcast the chat message.
-     * @throws UnauthenticatedError if attempting to send a chat message when not connected or authenticated.
+     * @throws {@link UnauthenticatedError} if attempting to send a chat message when not connected or authenticated.
      */
     public async say(text: string): Promise<void> {
         if (!this.#client.authenticated) {

src/classes/managers/PlayersManager.ts

@@ -57,7 +57,7 @@ export class PlayersManager extends EventBasedManager<PlayerEvents> {
 
     /**
      * Returns the {@link Player} for this client's player.
-     * @throws Error If attempting to lookup {@link Player} object before connecting to the server.
+     * @throws {@link Error} if attempting to lookup {@link Player} object before connecting to the server.
      */
     public get self(): Player {
         if (this.#slot === 0) {

src/classes/managers/SocketManager.ts

@@ -33,7 +33,7 @@ export class SocketManager extends EventBasedManager<SocketEvents> {
      * Send a list of raw client packets to the server.
      * @param packets List of client packets to send.
      * @returns This SocketManager.
-     * @throws SocketError if not connected to a server.
+     * @throws {@link SocketError} if not connected to a server.
      */
     public send(...packets: ClientPacket[]): SocketManager {
         if (this.#socket) {
@@ -50,8 +50,8 @@ export class SocketManager extends EventBasedManager<SocketEvents> {
      * needed to be performed before authenticating, but after connecting (e.g., DataPackage).
      * @param url The url of the server, including the protocol (e.g., `wss://archipelago.gg:38281`).
      * @returns The {@link RoomInfoPacket} received on initial connection.
-     * @throws SocketError If failed to connect or no websocket API is available.
-     * @throws TypeError If provided URL is malformed or invalid protocol.
+     * @throws {@link SocketError} if failed to connect or no websocket API is available.
+     * @throws {@link TypeError} if provided URL is malformed or invalid protocol.
      * @remarks If the port is omitted, client will default to `38281`.
      *
      * If the protocol is omitted, client will attempt to connect via `wss`, then fallback to `ws` if unsuccessful.

src/constants.ts

@@ -1,8 +1,12 @@
 /**
  * Archipelago version this library attempts to target. Support for older versions of the Archipelago API is not
  * guaranteed and some newer enhancements may no longer work or be supported.
+ *
+ * Version is represented in the format: `major.minor.build`.
  */
-export const targetVersion = { major: 0, minor: 5, build: 1 };
+export const targetVersion = { major: 0, minor: 5, build: 1 } as const;
 
 // Phar if you forget to update this on release, I swear to god.
+
+/** The version of this library. */
 export const libraryVersion = "2.0.2";

src/index.ts

@@ -16,6 +16,7 @@ export * from "./classes/MessageNode.ts";
 export * from "./classes/PackageMetadata.ts";
 export * from "./classes/Player.ts";
 export * from "./constants.ts";
+export * from "./errors.ts";
 export * from "./events/DeathLinkEvents.ts";
 export * from "./events/ItemEvents.ts";
 export * from "./events/MessageEvents.ts";
@@ -25,6 +26,9 @@ export * from "./events/SocketEvents.ts";
 export * from "./interfaces/ClientOptions.ts";
 export * from "./interfaces/ConnectionOptions.ts";
 
+/* Export these API consts to the root module. */
+export { clientStatuses, itemClassifications, itemsHandlingFlags, permissions, slotTypes } from "./api";
+
 /**
  * A collection of types, constants, and enumerations that get passed over the Archipelago network protocol.
  *