chore(packages): add more docs and improve types

packages/api/src/classes/Client.ts

@@ -19,14 +19,27 @@ export default class Client {
         })
     }
 
+    /**
+     * Connects to the WebSocket API
+     * @returns A promise that resolves when the client is ready
+     */
     connect() {
         return this.gateway.connect()
     }
 
+    /**
+     * Checks whether the client is ready
+     * @returns Whether the client is ready
+     */
     isReady(): this is ReadiedClient {
         return this.ready
     }
 
+    /**
+     * Requests the API to parse the given text
+     * @param text The text to parse
+     * @returns An object containing the ID of the request and the labels
+     */
     async parseText(text: string) {
         this.#throwIfNotReady()
 
@@ -42,11 +55,11 @@ export default class Client {
 
         type CorrectPacket = Packet<ServerOperation.ParsedText>
 
-        const promise = new Promise<CorrectPacket>((rs, rj) => {
+        const promise = new Promise<CorrectPacket['d']>((rs, rj) => {
             const parsedTextListener = (packet: CorrectPacket) => {
                 if (packet.d.id !== currentId) return
                 this.gateway.off('parsedText', parsedTextListener)
-                rs(packet)
+                rs(packet.d)
             }
 
             const parseTextFailedListener = (
@@ -54,7 +67,7 @@ export default class Client {
             ) => {
                 if (packet.d.id !== currentId) return
                 this.gateway.off('parseTextFailed', parseTextFailedListener)
-                rj(packet)
+                rj()
             }
 
             this.gateway.on('parsedText', parsedTextListener)
@@ -64,6 +77,11 @@ export default class Client {
         return await promise
     }
 
+    /**
+     * Requests the API to parse the given image and return the text
+     * @param url The URL of the image
+     * @returns An object containing the ID of the request and the parsed text
+     */
     async parseImage(url: string) {
         this.#throwIfNotReady()
 
@@ -79,11 +97,11 @@ export default class Client {
 
         type CorrectPacket = Packet<ServerOperation.ParsedImage>
 
-        const promise = new Promise<CorrectPacket>((rs, rj) => {
+        const promise = new Promise<CorrectPacket['d']>((rs, rj) => {
             const parsedImageListener = (packet: CorrectPacket) => {
                 if (packet.d.id !== currentId) return
                 this.gateway.off('parsedImage', parsedImageListener)
-                rs(packet)
+                rs(packet.d)
             }
 
             const parseImageFailedListener = (
@@ -91,7 +109,7 @@ export default class Client {
             ) => {
                 if (packet.d.id !== currentId) return
                 this.gateway.off('parseImageFailed', parseImageFailedListener)
-                rj(packet)
+                rj()
             }
 
             this.gateway.on('parsedImage', parsedImageListener)
@@ -101,25 +119,46 @@ export default class Client {
         return await promise
     }
 
+    /**
+     * Adds an event listener
+     * @param name The event name to listen for
+     * @param handler The event handler
+     * @returns The event handler function
+     */
     on<TOpName extends keyof ClientGatewayEventHandlers>(
         name: TOpName,
-        handler: ClientGatewayEventHandlers[typeof name]
+        handler: ClientGatewayEventHandlers[TOpName]
     ) {
         this.gateway.on(name, handler)
+        return handler
     }
 
+    /**
+     * Removes an event listener
+     * @param name The event name to remove a listener from
+     * @param handler The event handler to remove
+     * @returns The removed event handler function
+     */
     off<TOpName extends keyof ClientGatewayEventHandlers>(
         name: TOpName,
-        handler: ClientGatewayEventHandlers[typeof name]
+        handler: ClientGatewayEventHandlers[TOpName]
     ) {
         this.gateway.off(name, handler)
+        return handler
     }
 
+    /**
+     * Adds an event listener that will only be called once
+     * @param name The event name to listen for
+     * @param handler The event handler
+     * @returns The event handler function
+     */
     once<TOpName extends keyof ClientGatewayEventHandlers>(
         name: TOpName,
-        handler: ClientGatewayEventHandlers[typeof name]
+        handler: ClientGatewayEventHandlers[TOpName]
     ) {
         this.gateway.once(name, handler)
+        return handler
     }
 
     #throwIfNotReady() {

packages/api/src/classes/ClientGateway.ts

@@ -30,6 +30,10 @@ export default class ClientGateway {
         this.url = options.url
     }
 
+    /**
+     * Connects to the WebSocket API
+     * @returns A promise that resolves when the client is ready
+     */
     connect() {
         return new Promise<void>((rs, rj) => {
             try {
@@ -53,6 +57,12 @@ export default class ClientGateway {
         })
     }
 
+    /**
+     * Adds an event listener
+     * @param name The event name to listen for
+     * @param handler The event handler
+     * @returns The event handler function
+     */
     on<TOpName extends keyof ClientGatewayEventHandlers>(
         name: TOpName,
         handler: ClientGatewayEventHandlers[typeof name]
@@ -60,6 +70,12 @@ export default class ClientGateway {
         this.#emitter.on(name, handler)
     }
 
+    /**
+     * Removes an event listener
+     * @param name The event name to remove a listener from
+     * @param handler The event handler to remove
+     * @returns The removed event handler function
+     */
     off<TOpName extends keyof ClientGatewayEventHandlers>(
         name: TOpName,
         handler: ClientGatewayEventHandlers[typeof name]
@@ -67,6 +83,12 @@ export default class ClientGateway {
         this.#emitter.off(name, handler)
     }
 
+    /**
+     * Adds an event listener that will only be called once
+     * @param name The event name to listen for
+     * @param handler The event handler
+     * @returns The event handler function
+     */
     once<TOpName extends keyof ClientGatewayEventHandlers>(
         name: TOpName,
         handler: ClientGatewayEventHandlers[typeof name]
@@ -74,6 +96,11 @@ export default class ClientGateway {
         this.#emitter.once(name, handler)
     }
 
+    /**
+     * Sends a packet to the server
+     * @param packet The packet to send
+     * @returns A promise that resolves when the packet has been sent
+     */
     send<TOp extends ClientOperation>(packet: Packet<TOp>) {
         this.#throwIfDisconnected(
             'Cannot send a packet when already disconnected from the server'
@@ -86,6 +113,9 @@ export default class ClientGateway {
         )
     }
 
+    /**
+     * Disconnects from the WebSocket API
+     */
     disconnect() {
         this.#throwIfDisconnected(
             'Cannot disconnect when already disconnected from the server'
@@ -94,6 +124,10 @@ export default class ClientGateway {
         this.#handleDisconnect(DisconnectReason.Generic)
     }
 
+    /**
+     * Checks whether the client is ready
+     * @returns Whether the client is ready
+     */
     isReady(): this is ReadiedClientGateway {
         return this.ready
     }