@unitn-asa/deliveroo-js-sdk 1.3.3 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unitn-asa/deliveroo-js-sdk",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Software development kit for Deliveroo.js",
   "author": "Marco Robol <marco.robol@unitn.it>",
   "type": "module",
@@ -31,6 +31,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {},
-  "dependencies": {}
+  "devDependencies": {
+    "@types/node": "^25.6.0"
+  }
 }

package/src/client/DjsClientSocket.js

@@ -5,7 +5,7 @@ import { Socket } from 'socket.io-client';
  * @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/IOMetrics.js").IOMetrics} IOMetrics
  * 
  * @typedef {import("../types/IOSocketEvents.js").IOSensing} IOSensing
  * @typedef {import("../types/IOSocketEvents.js").IOClientEvents} IOClientEvents
@@ -30,12 +30,12 @@ export class DjsClientSocket extends Socket {
     
     /** @type { Promise < IOAgent > } */
     me = new Promise( (res) => {
-        this.once( 'you', (agent, info) => {
+        this.once( 'you', (agent) => {
             res( agent );
         } );
     } );
     
-    /** @type { Promise } */
+    /** @type { Promise < IOConfig > } */
     config = new Promise( (res) => {
         this.once( 'config', (config) => {
             res( config );
@@ -118,10 +118,10 @@ export class DjsClientSocket extends Socket {
     
     /**
      * Listen to 'info' events
-     * @param { function( IOInfo ) : void } callback
+     * @param { function( ) : void } callback
+     * @deprecated 'info' events are deprecated, use 'metrics' instead (only for admin)
      */
     onInfo ( callback ) {
-        this.on( "info", callback )
     }
     
     /**
@@ -129,7 +129,7 @@ export class DjsClientSocket extends Socket {
      * @param { string } id
      * @param { string } name
      * @param { {} } msg
-     * @param { function( any ) : void } replyAcknowledgmentCallback ( reply )
+     * @param { function( Object ) : void = } replyAcknowledgmentCallback ( reply )
      */
     /**
      * Listen to 'msg' events
@@ -187,6 +187,10 @@ export class DjsClientSocket extends Socket {
         } );
     }
 
+    /**ì
+     * @param {any} msg 
+     * @returns { Promise < { any } > } reply
+     */
     async emitShout ( msg ) {
         return new Promise( (success) => {
             this.emit( 'shout', msg, async ( status ) =>  {
@@ -219,10 +223,10 @@ export class DjsClientSocket extends Socket {
      * - 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
+     * @param { string [] = } selected array of parcels id to drop
      * @returns { Promise < { id:string } [] >}
      */
-    async emitPutdown ( selected = null ) {
+    async emitPutdown ( selected = [] ) {
         return this.emitAndResolveOnAck( 'putdown', selected );
     }
 
@@ -235,7 +239,7 @@ export class DjsClientSocket extends Socket {
     
     /**
      * 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 )
+     * @param { function ( 'server' | { socket:string, id:string, name:string }, ...any) : void } callback ( { src, ms, frame, socket, id, name }, ...msgArgs )
      */
     onLog ( callback ) {
         this.on( "log", callback )
@@ -252,12 +256,15 @@ export class DjsClientSocket extends Socket {
 
         /**
          * Mixin function to copy methods from a class prototype to an object
+         * @param { any } target the object to enhance
+         * @param { any } MixinClass the class whose methods will be copied to the target
          */
         function applyMixin(target, MixinClass) {
             
             let proto = MixinClass.prototype;
 
             const descriptors = Object.getOwnPropertyDescriptors(proto);
+            // @ts-ignore
             delete descriptors.constructor;
             
             Object.defineProperties(target, descriptors);

package/src/client/DjsConnect.js

@@ -25,15 +25,28 @@ export function DjsConnect ( host = process.env.HOST || 'http://localhost:8080',
     console.log( `Connecting to ${host} ${ token ? 'with token '+ (token).substring(0,5)+'...'+(token).substring(token.length-5) : name ? 'as '+name : 'with no token and no name' }` );
     
     enhancedClientSocket.onConnect( () => {
-        console.log( `Connected` )
+        console.log( `Connected` );
     });
 
     enhancedClientSocket.onceYou( me => {
-        console.log( `Authenticated as ${me.name}(${me.id}) in team ${me.teamName}(${me.teamId})` )
+        console.log( `Authenticated as ${me.name}(${me.id}) in team ${me.teamName}(${me.teamId})` );
     });
+
+    // Handle ping events to measure latency. The server will send a 'ping' event with a timestamp, and the client responds with a 'clientTimestamp' to allow the server to calculate round-trip time and network latency.
+    try {
+        enhancedClientSocket.on( "ping", ( pingData, callback ) => {
+            try {
+                callback();
+            } catch (error) {
+                console.warn("Error handling ping event");
+            }
+        } );
+    } catch (error) {
+        console.error("Error setting up ping event:", error);
+    }
     
     enhancedClientSocket.on( 'disconnect', (reason) => {
-        console.log( `Disconnected from ${host} because ${reason}` )
+        console.log( `Disconnected from ${host} because ${reason}` );
     });
 
     enhancedClientSocket.io.on("error", (error) => {

package/src/client/index.js

@@ -10,8 +10,8 @@
  * @typedef {import("../types/IOTile.js").IOTile} IOTile
  * 
  * @typedef {import("../types/IOIdentity.js").IOIdentity} IOIdentity
- * @typedef {import("../types/IOInfo.js").IOInfo} IOInfo
  * @typedef {import("../types/IOSensing.js").IOSensing} IOSensing
+ * @typedef {import("../types/IOMetrics.js").IOMetrics} IOMetrics
  * 
  * @typedef {import("../types/IOSocketEvents.js").IOClientEvents} IOClientEvents
  * @typedef {import("../types/IOSocketEvents.js").IOServerEvents} IOServerEvents

package/src/global.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Global type declarations for Node.js environment
+ */
+
+declare const process: {
+  env: {
+    HOST?: string;
+    TOKEN?: string;
+    NAME?: string;
+    [key: string]: string | undefined;
+  };
+};

package/src/server/DjsServer.js

@@ -6,7 +6,7 @@ import { DjsServerSocket } from './DjsServerSocket.js';
  * @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/IOMetrics.js").IOMetrics} IOMetrics
  *
  * @typedef {import("../types/IOSocketEvents.js").IOSensing} IOSensing
  * @typedef {import("../types/IOSocketEvents.js").IOClientEvents} IOClientEvents on the client side these are to be emitted with .emit
@@ -67,11 +67,10 @@ export class DjsServer extends Server {
     /**
      * Broadcast a log message to all connected clients
      * @param { 'server' | { socket:string, id:string, name:string } } src - 'server' or client
-     * @param { IOInfo } info
      * @param { ...any } message
      */
-    broadcastLog(src, info, ...message) {
-        this.emit('log', src, info, ...message);
+    broadcastLog(src, ...message) {
+        this.emit('log', src, ...message);
     }
 
     // /**
@@ -117,6 +116,7 @@ export class DjsServer extends Server {
             let proto = MixinClass.prototype;
 
             const descriptors = Object.getOwnPropertyDescriptors(proto);
+            // @ts-ignore
             delete descriptors.constructor;
 
             Object.defineProperties(target, descriptors);

package/src/server/DjsServerSocket.js

@@ -5,7 +5,7 @@ import { Socket } from 'socket.io';
  * @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/IOMetrics.js").IOMetrics} IOMetrics
  * 
  * @typedef {import("../types/IOSocketEvents.js").IOSensing} IOSensing
  * @typedef {import("../types/IOSocketEvents.js").IOClientEvents} IOClientEvents on the client side these are to be emitted with .emit
@@ -28,7 +28,9 @@ export class DjsServerSocket extends Socket {
     //  * @param {IOClientEvents[K]} listener
     //  * @returns {void}
     //  */
+    // @ts-ignore
     on ( event, listener ) {
+        // @ts-ignore
         return super.on( event, (...args) => {
             try {
                 return listener.apply( this, args );
@@ -95,10 +97,10 @@ export class DjsServerSocket extends Socket {
     }
     
     /**
-     * @param { IOInfo } info
+     * @param { IOMetrics } metrics
      */
-    emitInfo ( info ) {
-        super.emit( 'info', info );
+    emitMetrics ( metrics ) {
+        super.emit( 'metrics', metrics );
     }
 
 
@@ -106,7 +108,7 @@ export class DjsServerSocket extends Socket {
     /**
      * @callback onMoveCallback
      * @param { 'up' | 'right' | 'left' | 'down' } direction
-     * @param { function( { x:number, y:number } | false ) : void } replyAcknowledgmentCallback ( reply )
+     * @param { function( { x:number, y:number } | false ) : void = } replyAcknowledgmentCallback ( reply )
      */
     /**
      * @param { onMoveCallback } callback ( direction, acknowledgementCallback )
@@ -117,7 +119,7 @@ export class DjsServerSocket extends Socket {
     
     /**
      * @callback onPickupCallback
-     * @param { function( { id:string } [] ) : void } acknowledgementCallback
+     * @param { function( { id:string } [] ) : void = } acknowledgementCallback
      */
     /**
      * @param { onPickupCallback } callback ( acknowledgementCallback )
@@ -128,11 +130,11 @@ export class DjsServerSocket extends Socket {
 
     /**
      * @callback onPutdownCallback
-     * @param { string [] } selected ids of parcels to drop
-     * @param { function( { id:string } [] ) : void } acknowledgementCallback
+     * @param { string [] = } selected ids of parcels to drop
+     * @param { function( { id:string } [] ) : void = } acknowledgementCallback
      */
     /**
-     * @param { onPutdownCallback } callback ( selected, acknowledgementCallback )
+     * @param { onPutdownCallback } callback
      */
     onPutdown ( callback ) {
         super.on( 'putdown', callback );
@@ -184,6 +186,7 @@ export class DjsServerSocket extends Socket {
         const sockets = await super.to( "agent:" + toId ).fetchSockets();
         const emissionPromises = sockets.map( socket => {
             return new Promise( (res) => {
+                // @ts-ignore
                 socket.timeout(1000).emit( 'msg', me.id, me.name, msg, (err, response) => {
                     if (err)
                         res('timeout');
@@ -202,6 +205,7 @@ export class DjsServerSocket extends Socket {
     }
 
     /**
+     * @param { IOAgent } me
      * @param { any } msg
      * @returns { void } reply
      */
@@ -217,21 +221,18 @@ export class DjsServerSocket extends Socket {
     }
     
     /**
-     * @param { string } myId
-     * @param { string } myName
      * @param { 'server' | { socket:string, id:string, name:string } } src - 'server' or client
-     * @param { IOInfo } info
      * @param { ...any } message
      */
-    broadcastLog ( myId, myName, src, info, ...message ) {
-        super.broadcast.emit( 'log', src, info, ...message );
+    broadcastLog ( src, ...message ) {
+        super.broadcast.emit( 'log', src, ...message );
     }
 
 
 
     /**
      * Process request for creating a parcel on x, y or disposing or setting its reward given the id
-     * @param { function ( 'create' | 'dispose' | 'set', {id:string, x:number, y:number, reward:number} ) : void } callback 
+     * @param { function ( 'create' | 'dispose' | 'set', { x:number, y:number } | { id:string, reward?:number } ) : void } callback 
      */
     onParcel ( callback ) {
         super.on( 'parcel', callback );
@@ -265,11 +266,13 @@ export class DjsServerSocket extends Socket {
         /**
          * Mixin function to copy methods from a class prototype to an object
          */
+        // @ts-ignore
         function applyMixin(target, MixinClass) {
             
             let proto = MixinClass.prototype;
 
             const descriptors = Object.getOwnPropertyDescriptors(proto);
+            // @ts-ignore
             delete descriptors.constructor;
             
             Object.defineProperties(target, descriptors);

package/src/server/index.js

@@ -10,8 +10,8 @@
  * @typedef {import("../types/IOTile.js").IOTile} IOTile
  * 
  * @typedef {import("../types/IOIdentity.js").IOIdentity} IOIdentity
- * @typedef {import("../types/IOInfo.js").IOInfo} IOInfo
  * @typedef {import("../types/IOSensing.js").IOSensing} IOSensing
+ * @typedef {import("../types/IOMetrics.js").IOMetrics} IOMetrics
  * 
  * @typedef {import("../types/IOSocketEvents.js").IOClientEvents} IOClientEvents
  * @typedef {import("../types/IOSocketEvents.js").IOServerEvents} IOServerEvents

package/src/types/IOAgent.json

@@ -0,0 +1,62 @@
+[
+  {
+    "type": "object",
+    "title": "IOAgent",
+    "required": [
+      "id",
+      "name",
+      "teamId",
+      "teamName",
+      "x",
+      "y",
+      "score",
+      "penalty"
+    ],
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "teamId": {
+        "type": "string"
+      },
+      "teamName": {
+        "type": "string"
+      },
+      "x": {
+        "type": "object",
+        "anyOf": [
+          {
+            "classRelation": "is-a",
+            "$ref": "#/$defs/number"
+          },
+          {
+            "classRelation": "is-a",
+            "$ref": "#/$defs/undefined"
+          }
+        ]
+      },
+      "y": {
+        "type": "object",
+        "anyOf": [
+          {
+            "classRelation": "is-a",
+            "$ref": "#/$defs/number"
+          },
+          {
+            "classRelation": "is-a",
+            "$ref": "#/$defs/undefined"
+          }
+        ]
+      },
+      "score": {
+        "type": "number"
+      },
+      "penalty": {
+        "type": "number"
+      }
+    }
+  }
+]

package/src/types/IOGameOptions.js

@@ -26,9 +26,8 @@
  * @typedef IONpcsOptions
  * NPC configuration object
  * @property {IOClockEvent} moving_event                Event whenever the NPC moves
- * @property {string} type                              NPC type (random, collector, etc.)
+ * @property {'random'|'intelligent'} type                              NPC type (random, collector, etc.)
  * @property {number} count                             Number of NPCs of this type
- * @property {number} capacity                          Capacity (for collector NPCs)
 */
 
 /**

package/src/types/IOMetrics.js

@@ -0,0 +1,17 @@
+
+/**
+ * @typedef {Object} IOMetrics
+ * @property { {ms: number, frame: number, fps: number, uptime: number} } timing
+ * @property { {heapUsed: number, heapTotal: number, rss: number, external: number} } memory
+ * @property { {current: number} } cpu
+ * @property { {currentLag: number, maxLag: number, avgLag: number} } eventLoop
+ * @property { {avg: number, min: number, max: number, byAgent: Object.<string, {
+ *      id: string,
+ *      name: string,
+ *      teamId: string,
+ *      teamName: string,
+ *      sockets: ( { socketId: string, frame: number, avg: number, min: number, max: number } ) []
+ *  }> } } latency
+ */
+
+export { };

package/src/types/IOSocketEvents.js

@@ -1,8 +1,10 @@
 
 /** @typedef {import('./IOAgent.js').IOAgent} IOAgent */
 /** @typedef {import('./IOTile.js').IOTile} IOTile */
-/** @typedef {import('./IOInfo.js').IOInfo} IOInfo */
 /** @typedef {import('./IOSensing.js').IOSensing} IOSensing */
+/** @typedef {import('./IOMetrics.js').IOMetrics} IOMetrics */
+
+
 
 /**
  * Client -> Server events. Emitted by the client and listened by the server.
@@ -34,7 +36,8 @@
  *      'controller':       function ( 'connected' | 'disconnected', {id:string, name:string, teamId:string, teamName:string, score:number} ) : void,
  *      'you':              function ( IOAgent ) : void,
  *      'sensing':          function ( IOSensing ) : void,
- *      'info':             function ( IOInfo ) : void,
+ *      'ping':             function ( { frame: number, roundTrip: number }, function () : void ) : void,
+ *      'metrics':          function ( IOMetrics ) : void,
  *      'msg':              function ( string, string, Object, function ( Object ) : void = ) : Object,
  *      'log':              function ( 'server' | { socket:string, id:string, name:string }, ...any ) : void
  * }} IOServerEvents

package/src/types/IOInfo.js

@@ -1,11 +0,0 @@
-
-/**
- * @typedef IOInfo
- * @property {number} ms
- * @property {number} frame
- * @property {number} fps
- * @property {number} heapUsed
- * @property {number} heapTotal
- */
-
-export { };