@unitn-asa/deliveroo-js-sdk 1.2.1

package/README.MD

@@ -0,0 +1,49 @@
+# @unitn-asa/deliveroo-js-sdk
+
+Shared SDK utilities and types for Deliveroo.js (client & server integration helpers).
+
+This package exposes small helpers for interacting with the Deliveroo.js backend (HTTP API helpers, socket helpers and shared JSDoc typedefs) so frontend and other packages can import them from a single entry point.
+
+## Key features
+
+- Small HTTP helper functions for the Deliveroo REST API (tokens, configs, agents, parcels).
+- Socket-related helpers and types for `Deliveroojs`.
+- JSDoc typedefs that can be used by editors/TypeScript for type hints.
+
+## Installation
+
+This package is part of the monorepo and is consumed via file: references in the workspace. If you publish it standalone, install normally with npm/yarn.
+
+From the monorepo root (already linked via workspace):
+
+```bash
+# frontend or other package: npm install ../packages/@unitn-asa/deliveroo-js-sdk
+```
+
+## Usage (ESM)
+
+Import the functions and types you need from the package root:
+
+```js
+import {
+    DeliveroojsRestClient,
+    DeliveroojsAsyncClient
+} from '@unitn-asa/deliveroo-js-sdk';
+```
+
+## Types
+
+The package contains JSDoc typedef files describing `IOAgent`, `IOParcel`, `IOConfig`, `IOGameOptions` and other structures used across the project. When authoring code that consumes this SDK you can import the types in JSDoc.
+
+Example JSDoc import:
+
+```js
+/** @typedef {import('@unitn-asa/deliveroo-js-sdk/types/IOAgent.js').IOAgent} IOAgent */
+```
+
+## License
+
+ISC
+
+---
+_Maintainer: Marco Robol <marco.robol@unitn.it>_

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@unitn-asa/deliveroo-js-sdk",
+  "version": "1.2.1",
+  "description": "Software development kit for Deliveroo.js",
+  "author": "Marco Robol <marco.robol@unitn.it>",
+  "type": "module",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unitn-ASA/Deliveroo.js.git"
+  },
+  "exports": {
+    ".": "./src/client/index.js",
+    "./types/*": "./src/types/*",
+    "./client": "./src/client/index.js",
+    "./client/*": "./src/client/*",
+    "./server": "./src/server/index.js",
+    "./server/*": "./src/server/*"
+  },
+  "files": [
+    "src/*",
+    "index.js"
+  ],
+  "scripts": {
+    "test": "node test/DeliveroojsApiClient.test.js"
+  },
+  "dependencies": {
+    "args-parser": "^1.3.0"
+  },
+  "peerDependencies": {
+    "socket.io": "^4.7.2",
+    "socket.io-client": "^4.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "66b8c3ba9a75eb7c81e08a500fd3c216c5791f8c"
+}

package/src/client/DjsClientSocket.js

@@ -0,0 +1,312 @@
+import { Socket } from 'socket.io-client';
+
+/**
+ * @typedef {import("../types/IOAgent.js").IOAgent} IOAgent
+ * @typedef {import("../types/IOParcel.js").IOParcel} IOParcel
+ * @typedef {import("../types/IOTile.js").IOTile} IOTile
+ * @typedef {import("../types/IOConfig.js").IOConfig} IOConfig
+ * @typedef {import("../types/IOInfo.js").IOInfo} IOInfo
+ * 
+ * @typedef {import("../types/IOSocketEvents.js").IOSensing} IOSensing
+ * @typedef {import("../types/IOSocketEvents.js").IOClientEvents} IOClientEvents
+ * @typedef {import("../types/IOSocketEvents.js").IOServerEvents} IOServerEvents
+ */
+
+
+
+/**
+ * @class
+ * @extends { Socket<IOServerEvents, IOClientEvents> }
+ */
+export class DjsClientSocket extends Socket {
+
+    /** @type { Promise < string > } */
+    token = new Promise( (res) => {
+        this.once( 'token', (token) => {
+            // console.log( 'New token for ' + NAME + ': ' + token )
+            res( token );
+        } );
+    } );
+    
+    /** @type { Promise < IOAgent > } */
+    me = new Promise( (res) => {
+        this.once( 'you', (agent, info) => {
+            res( agent );
+        } );
+    } );
+    
+    /** @type { Promise } */
+    config = new Promise( (res) => {
+        this.once( 'config', (config) => {
+            res( config );
+        } );
+    } );
+
+    /** @type { Promise < { width:number, height:number, tiles: IOTile [] } > } */
+    map = new Promise ( (res) => {
+        this.once( 'map', (width, height, tiles) => {
+            res( {width, height, tiles} );
+        } );
+    } );
+
+
+
+    /**
+     * @param { function() : void } callback 
+     */
+    onConnect ( callback ) {
+        this.on( "connect", callback )
+    }
+
+    /**
+     * @param { function() : void } callback 
+     */
+    onDisconnect ( callback ) {
+        this.on( "disconnect", callback )
+    }
+
+    /**
+     * @param { function(IOConfig) : void } callback
+     */
+    onConfig ( callback ) {
+        this.on( "config", callback )
+    }
+
+    /**
+     * @param { function( number, number, IOTile[] ) : void } callback ( width, height, tiles )
+     */
+    onMap ( callback ) {
+        this.on( "map", callback )
+    }
+    
+    /**
+     * @param { function( IOTile, IOInfo ) : void } callback
+     */
+    onTile ( callback ) {
+        this.on( "tile", callback )
+    }
+
+    // @param { serverEvents['controller']  } callback
+    /**
+     * @param { function( string, { id:string, name:string, teamId:string, teamName:string, score:number } ) : void } callback
+     */
+    onAgentConnected ( callback ) {
+        this.on( "controller", callback )
+    }
+    
+    /**
+     * @param { function( IOAgent, IOInfo ) : void } callback
+     */
+    onYou ( callback ) {
+        this.on( "you", callback )
+    }
+
+    /**
+     * @param { function( IOAgent, IOInfo ) : void } callback
+     */
+    onceYou ( callback ) {
+        this.once( "you", callback )
+    }
+    
+    /**
+     * Listen to 'agents sensing' events
+     * @param { function( IOSensing [] ) : void } callback
+     */
+    onAgentsSensing ( callback ) {
+        this.on( "agents sensing", callback )
+    }
+    
+    /**
+     * Listen to 'parcels sensing' events
+     * @param { function( IOSensing [] ) : void } callback
+     */
+    onParcelsSensing ( callback ) {
+        this.on( "parcels sensing", callback )
+    }
+
+    /**
+     * Listen to 'crates sensing' events
+     * @param { function( IOSensing [] ) : void } callback
+     */
+    onCratesSensing ( callback ) {
+        this.on( "crates sensing", callback )
+    }
+    
+    /**
+     * @callback onMsgCallback
+     * @param { string } id
+     * @param { string } name
+     * @param { {} } msg
+     * @param { function( any ) : void } replyAcknowledgmentCallback ( reply )
+     */
+    /**
+     * Listen to 'msg' events
+     * @param {onMsgCallback} callback (id, name, msg, replyAcknowledgmentCallback)
+     */
+    onMsg ( callback ) {
+        this.on( "msg", callback )
+    }
+
+    /**
+     * @template T
+     * @typedef {T extends [...infer _, infer L] ? L : never} Last
+     */
+
+    /**
+     * @template T
+     * @typedef {T extends [...infer R, any] ? R : T} AllButLast
+     */
+
+    /**
+     * @template {keyof IOClientEvents} K
+     * @param {K} event
+     * @param {AllButLast<Parameters<IOClientEvents[K]>>} args
+     * @returns {Promise<Last<Parameters<IOClientEvents[K]>>>}
+     */
+    // @ts-ignore
+    async emitAndResolveOnAck ( event, ...args ) {
+        // @ts-ignore
+        return this.timeout( 1000 ).emitWithAck( event, ...args );
+    }
+
+    /**
+     * @param {string} toId
+     * @param {any} msg
+     * @returns { Promise < 'successful' > } status
+     */
+    async emitSay ( toId, msg ) {
+        return new Promise( (success) => {
+            this.emit( 'say', toId, msg, async ( status ) =>  {
+                success( status );
+            } );
+        } );
+    }
+
+    /**
+     * @param {string} toId 
+     * @param {any} msg 
+     * @returns { Promise < { any } > } reply
+     */
+    async emitAsk ( toId, msg ) {
+        return new Promise( (success) => {
+            this.emit( 'ask', toId, msg, async ( reply ) =>  {
+                success( reply );
+            } );
+        } );
+    }
+
+    async emitShout ( msg ) {
+        return new Promise( (success) => {
+            this.emit( 'shout', msg, async ( status ) =>  {
+                success( status );
+            } );
+        } );
+    }
+
+    /**
+     * When movement completes, it resolves to true.
+     * In case of failure when moving, it resolves to false
+     * @param { 'up' | 'right' | 'left' | 'down' | { x:number, y:number } } directionOrXy It can be either: 'up', 'right', 'left', 'down', or destination Xy
+     * @returns { Promise < { x:number, y:number } | false > }
+     */
+    async emitMove ( directionOrXy ) {
+        return this.emitAndResolveOnAck( 'move', directionOrXy );
+    }
+
+    /**
+     * Pick up all parcels in the agent tile.
+     * When completed, resolves to the array of picked up parcels
+     * @returns { Promise < { id:string } [] > } array of picked up parcels
+     */
+    async emitPickup (  ) {
+        return this.emitAndResolveOnAck( 'pickup' );
+    }
+
+    /**
+     * Put down parcels:
+     * - if array of ids is provided: putdown only specified parcels
+     * - if no list is provided: put down all parcels
+     * When completed, resolves to the list of dropped parcels
+     * @param { string [] } selected array of parcels id to drop
+     * @returns { Promise < { id:string } [] >}
+     */
+    async emitPutdown ( selected = null ) {
+        return this.emitAndResolveOnAck( 'putdown', selected );
+    }
+
+    /**
+     * @param { any [] } message
+     */
+    emitLog ( ...message ) {
+        this.emit( "log", ...message );
+    }
+    
+    /**
+     * Listen to 'log' events from server and those redirected here from others client
+     * @param { function ( { src:'server'|'client', ms:number, frame: number, socket:string, id:string, name:string }, ...any) : void } callback ( { src, ms, frame, socket, id, name }, ...msgArgs )
+     */
+    onLog ( callback ) {
+        this.on( "log", callback )
+    }
+
+
+
+    /**
+     * Enhance a Socket.io-client Socket into a DjsSocket
+     * @param { Socket } socket
+     * @returns { DjsClientSocket }
+    */
+    static enhance (socket) {
+
+        /**
+         * Mixin function to copy methods from a class prototype to an object
+         */
+        function applyMixin(target, MixinClass) {
+            
+            let proto = MixinClass.prototype;
+
+            const descriptors = Object.getOwnPropertyDescriptors(proto);
+            delete descriptors.constructor;
+            
+            Object.defineProperties(target, descriptors);
+
+            return target;
+        }
+        applyMixin(socket, DjsClientSocket);
+
+        /**
+         * Original socket enhanced with ClientSocketEnhancer methods casted as EnhancedSocket
+         * @type { DjsClientSocket }
+        */
+        // @ts-ignore
+        return socket;
+
+    }
+}
+
+
+
+
+
+
+// import io from 'socket.io-client';
+// const host = 'http://localhost:8080';
+// const opts = {
+//     autoConnect: false,
+//     withCredentials: false,
+//     extraHeaders: { 'x-token': 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQzMDhhYiIsIm5hbWUiOiJwYW9sbyIsInRlYW1JZCI6IjYwNzA4ZCIsInRlYW1OYW1lIjoiZGlzaSIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzQ4MzUzNTU4fQ.pzZxyGjv0WPbyh45Grr_sYqzGU1EUH-XK7hZEcWX5Js' },
+//     // query: { name: 'marco' }
+// };
+// const socket = io( host, opts );
+// const enhancedSocket = DjsClientSocket.enhance( socket );
+// enhancedSocket.emitMove( 'up' ).then( ( result ) => {
+//     console.log( 'Move result:', result );
+// } );
+// enhancedSocket.emitShout( 'hellooooo!' );
+// enhancedSocket.onceYou( ( agent, info ) => {
+//     console.log( 'enhanceClientSocket.js I am', agent, info );
+// } );
+// // enhancedSocket.emitAndResolveOnAck( 'putdown' ).then( ( ack ) => {
+// //     console.log( 'Acknowledged with', ack );
+// // } );
+// enhancedSocket.connect();