@de./sdk 1.0.0

package/src/allend/MSI/Handles.ts

@@ -0,0 +1,387 @@
+import type {
+  Coordinates,
+  RTLocation,
+  Entity,
+  MapOptions,
+  Caption,
+  Journey,
+  ActivePosition,
+  PickedLocation,
+  RouteOptions
+} from '../../types'
+
+import IOF from 'iframe.io'
+import { EventEmitter } from 'events'
+import Controls from './Controls'
+import Stream from '../../utils/stream'
+
+export interface ControlEntity {
+  add: ( entity: Entity, callback?: () => void ) => void
+  remove: ( id: string, callback?: () => void ) => void
+  move: ( update: ActivePosition, callback?: () => void ) => void
+}
+export type LRSControlsListener = ( controls: ControlEntity ) => void
+export type LRSErrorListener = ( error?: Error | boolean ) => void
+
+export default class Handles extends EventEmitter {
+  private chn: IOF
+  private controls: Controls
+  private options: MapOptions
+
+  constructor( chn: IOF, controls: Controls, options: MapOptions ){
+    super()
+
+    this.chn = chn
+    this.options = options
+    this.controls = controls
+  }
+
+  /**
+   * Listen when user manually picked a location
+   * on the map.
+   * 
+   * @param fn - Event listener function
+   * @return - void
+   */
+  onPickLocation( fn: ( location: PickedLocation ) => void ){
+    this.chn.on('pick:location', fn )
+  }
+
+  /**
+   * Create new stream through which user's current location
+   * details will be pushed to the API level.
+   * 
+   * @param usertype - (Default: `client`) Type of user at the current location
+   * @return - Readable stream
+   */
+  myLocation( usertype?: 'client' | 'agent' ){
+    if( !this.chn ) return
+    this.chn?.emit('pin:current:location', usertype || 'client' )
+
+    const stream = new Stream()
+
+    this.chn
+    .on('current:location', ( location: RTLocation  ) => stream.sync( location ) )
+    .on('live:location:start', ( location: RTLocation  ) => stream.sync( location ) )
+    .on('live:location:update', ( location: RTLocation  ) => stream.sync( location ) )
+    .on('live:location:end', ( location: RTLocation  ) => stream.sync( location ) )
+    .on('current:location:error', ( message: string ) => stream.error( new Error( message ) ) )
+
+    // Listen to stream closed
+    stream
+    .onerror( error => console.error('[Stream Error] ', error ) )
+    .onclose( () => {
+      if( !this.chn ) return
+
+      this.chn
+      .off('current:location')
+      .off('current:location:live')
+      .off('current:location:error')
+    } )
+
+    return stream
+  }
+
+  /**
+   * Create new stream through which the current location details
+   * of user's peer (Eg. `agent`) will be pushed to the API level.
+   * 
+   * @param position - Peer's current GPS location
+   * @param caption - (Optional) Caption information of the peer
+   * @return - Readable stream
+   */
+  peerLocation( position: RTLocation , caption?: Caption ){
+    if( !this.chn ) return
+    this.chn?.emit('pin:peer:location', { id: 'peer', position, caption } )
+    
+    const stream = new Stream
+    
+    // Listen to incoming new position data
+    stream
+    .on('data', ({ position, caption }: any ) => {
+      if( !position )
+        return stream.error( new Error('Invalid Data') )
+
+      this.chn?.emit('pin:peer:location', { id: 'peer', position, caption } )
+    })
+    .onerror( error => console.error('[Stream Error] ', error ) )
+    .onclose( () => this.chn?.emit('unpin:peer:location', 'peer') )
+
+    return stream
+  }
+
+  /**
+   * Open a live stream through which the current location details
+   * and profile information of all nearby entities around 
+   * this user (Eg. `bike`, `car`, ...) will be pushed to the 
+   * API level.
+   * 
+   * @param list - List of detected nearby entities around this user.
+   * @return - Live Readable Stream (LRS)
+   */
+  nearby( list: Entity[] ){
+    if( !this.chn ) return
+
+    const self = this
+    let _CLOSED = false
+    
+    this.chn?.emit('show:nearby', list )
+    
+    const
+    stream = new Stream,
+    controls: ControlEntity = {
+      /**
+       * Add new entity to the nearby list
+       * 
+       * @param entity - GPS location and profile of the entity
+       */
+      add( entity ): Promise<void> {
+        return new Promise( ( resolve, reject ) => {
+          if( _CLOSED ) return
+
+          // Maintain initial list of nearby: Prevent duplicated entity
+          for( let x = 0; x < list.length; x++ )
+            if( list[x].id === entity.id ){
+              list.splice( x, 1 )
+              self.chn?.emit('remove:nearby:entity', entity.id )
+              break
+            }
+          
+          // Track response timeout
+          let TIMEOUT: any
+          
+          // Add new entity
+          list.push( entity )
+          self.chn?.emit('add:nearby:entity', entity, () => {
+            clearTimeout( TIMEOUT )
+            resolve()
+
+            self.emit('nearby--stream', 'add', entity )
+          } )
+
+          setTimeout( () => reject('Add entity timeout'), 8000 )
+        })
+      },
+
+      /**
+       * Remove an entity (vehicle, premises) from the nearby list
+       * 
+       * @param id - ID of targeted entity
+       */
+      remove( id ): Promise<void> {
+        return new Promise( ( resolve, reject ) => {
+          if( _CLOSED ) return
+          
+          // Track response timeout
+          let TIMEOUT: any
+
+          list = list.filter( each => { return each.id !== id } )
+          self.chn?.emit('remove:nearby:entity', id, () => {
+            clearTimeout( TIMEOUT )
+            resolve()
+
+            self.emit('nearby--stream', 'remove', id )
+          } )
+
+          setTimeout( () => reject('Remove entity timeout'), 8000 )
+        } )
+      },
+      
+      /**
+       * Change mobile entities position on the map
+       * 
+       * @param location - New GPS location of the entity
+       */
+      move( location ): Promise<void> {
+        return new Promise( ( resolve, reject ) => {
+          if( _CLOSED ) return
+          
+          // Track response timeout
+          let TIMEOUT: any
+          
+          self.chn?.emit('move:nearby:entity', location, () => {
+            clearTimeout( TIMEOUT )
+            resolve()
+
+            self.emit('nearby--stream', 'move', location )
+          } )
+
+          setTimeout( () => reject('Remove entity timeout'), 8000 )
+        } )
+      }
+    }
+
+    const
+    /**
+     * 
+     */
+    live = ( fn: LRSControlsListener ) => {
+      fn( controls )
+      return stream
+    },
+    close = ( fn?: LRSErrorListener ) => {
+      if( _CLOSED ) return
+
+      this.chn?.emit('remove:nearby', ( error: string | boolean ) => {
+        if( typeof error == 'string' ) 
+          return typeof fn == 'function' && fn( new Error( error ) )
+
+        _CLOSED = true
+        stream.isActive() && stream.close()
+
+        typeof fn == 'function' && fn()
+      })
+    }
+    
+    this.on('nearby--stream', ( action, dataset ) => stream.sync({ action, dataset, list }) )
+    // Listen to stream closed
+    stream
+    .onerror( error => console.error('[Stream Error] ', error ) )
+    .onclose( ( fn?: () => void ) => {
+      this.off('nearby--stream', fn || (() => {}) )
+      close()
+    })
+    
+    return { live, pipe: stream.pipe, close }
+  }
+
+  /**
+   * Set service pickup point.
+   * 
+   * @param location - Location coordinates
+   * @param caption - (Optional) Caption information of the pickup point
+   */
+  async pickupPoint( location: Coordinates, caption?: Caption ): Promise<void> {
+    // Default pickup caption
+    const _caption: Caption = { 
+      label: 'Pickup point',
+      ...(caption || {})
+    }
+    
+    await this.controls?.setRouteOrigin('main', { coords: location, caption: _caption } )
+  }
+
+  /**
+   * Set service dropoff point.
+   * 
+   * @param location - Location coordinates
+   * @param caption - (Optional) Caption information of the pickup point
+   */
+  async dropoffPoint( location: Coordinates, caption?: Caption ): Promise<void> {
+    // Default destination caption
+    const _caption: Caption = {
+      label: 'Destination point',
+      ...(caption || {})
+    }
+    
+    await this.controls?.setRouteDestination('main', { coords: location, caption: _caption } )
+  }
+
+  /**
+   * Create new stream through which navigation details of
+   * this user's peer will be display on the user's map also
+   * pushed to the API level.
+   * 
+   * @return - Readable stream
+   */
+  peerDirection( options?: RouteOptions ){
+    if( !this.chn ) return
+    const stream = new Stream
+
+    stream
+    .on('data', ({ status, direction, position }: any ) => {
+      if( !direction || !position )
+        return stream.error( new Error('Invalid Data') )
+        
+      this.controls?.casting('peer-direction', direction, position, options )
+
+      switch( status ){
+        case 'STALE':
+        case 'STARTED':
+        case 'LONG_STOP':
+        case 'LOW_TRAFFIC':
+        case 'HIGH_TRAFFIC':
+        case 'MODERATE_TRAFFIC':
+        case 'SPEED_WARNING':
+        case 'NEARBY':
+        case 'ARRIVED': this.emit(`pe:${status.toLowerCase()}`); break
+        case 'UNAVAILABLE': {
+          this.emit(`pe:closed`)
+          stream.isActive() && stream.close()
+        } break
+      }
+    })
+    .onerror( error => console.error('[Stream Error] ', error ) )
+
+    return stream
+  }
+
+  /**
+   * Initiate user (Eg. agent) live navigation on the map 
+   * and create a new stream through which the navigation details 
+   * will be pushed to the API level.
+   * 
+   * @param journey - Route origin, waypoints, destination
+   * @return - Readable stream
+   */
+  navigation( journey: Journey ): Promise<Stream> {
+    return new Promise( ( resolve, reject ) => {
+      if( !this.chn ) return
+
+      const initialize = () => {
+        const stream = new Stream
+
+        // Sync with navigation route update
+        this.chn?.on('navigation:direction', ({ status, direction, position }) => {
+          stream.sync({ status, direction, position })
+
+          switch( status ){
+            case 'STALE':
+            case 'STARTED':
+            case 'LONG_STOP':
+            case 'LOW_TRAFFIC':
+            case 'HIGH_TRAFFIC':
+            case 'MODERATE_TRAFFIC':
+            case 'SPEED_WARNING':
+            case 'NEARBY':
+            case 'ARRIVED': this.emit(`pe:${status.toLowerCase()}`); break
+            case 'UNAVAILABLE': {
+              this.emit(`pe:closed`)
+              stream.isActive() && stream.close()
+            } break
+          }
+        })
+
+        stream
+        // Listen location/position update
+        .on('data', ({ position }: any ) => {
+          if( !position )
+            return stream.error( new Error('Invalid Data') )
+          
+          this.controls?.navigate( position )
+        })
+        .onerror( error => console.error('[Stream Error] ', error ) )
+        .onclose( () => {
+          this.chn?.off('navigation:direction')
+          this.controls?.unmountNavigation()
+        })
+
+        resolve( stream )
+      }
+      
+      // Set route
+      this.controls?.setRoute( journey )
+                    .then( async () => {
+                      // Initialize navigation point to current location
+                      const position = journey.origin || await this.controls?.getCurrentLocation()
+                      if( !position ) return reject('Unable to get current location')
+
+                      initialize()
+
+                      await this.controls?.mountNavigation( journey.routeId )
+                      await this.controls?.setInitialNavigationPosition( position as RTLocation )
+                    } )
+                    .catch( reject )
+    } )
+  }
+}

package/src/allend/MSI/Plugins.ts

@@ -0,0 +1,52 @@
+import type { MapOptions } from '../../types'
+
+import IOF from 'iframe.io'
+import Handles from './Handles'
+import Controls from './Controls'
+import Utils from '../../utils'
+
+export type PluginHook = {
+  handles: Handles,
+  controls: Controls,
+  map: MapOptions,
+  utils: typeof Utils
+}
+export type Plugin<PluginAPI, PluginOptions = {}> = ( hooks: PluginHook, options?: PluginOptions ) => PluginAPI
+
+export default class Plugins {
+  private chn: IOF
+  private handles: Handles
+  private controls: Controls
+  private options: MapOptions
+  private ACTIVE_PLUGINS: Record<string, Plugin<any>>  = {}
+
+  constructor( chn: IOF, handles: Handles, controls: Controls, options: MapOptions ){
+    this.chn = chn
+    this.options = options
+    this.handles = handles
+    this.controls = controls
+  }
+
+  mount( list: Record<string, Plugin<any>> ){
+    Object.entries( list ).forEach( ([name, plugin]) => {
+      // TODO: Allow api level permission settings
+
+      // TODO: Put validation checks in place
+
+      this.ACTIVE_PLUGINS[ name ] = plugin
+    } )
+  }
+
+  use<API, Options>( name: string, options?: Record<string, Options> ){
+    if( !(name in this.ACTIVE_PLUGINS) )
+      throw new Error(`Undefined <${name}> plugin`)
+
+    const plugin: Plugin<API> = this.ACTIVE_PLUGINS[ name ]
+    return plugin({
+      handles: this.handles,
+      controls: this.controls,
+      map: this.options,
+      utils: Utils
+    }, options )
+  }
+}

package/src/allend/MSI/index.ts

@@ -0,0 +1,160 @@
+import type { MapOptions } from '../../types'
+
+import { EventEmitter } from 'events'
+import IOF from 'iframe.io'
+import Handles from './Handles'
+import Controls from './Controls'
+import Plugins, { type Plugin } from './Plugins'
+
+const
+SANDBOX_RULES = ['allow-scripts', 'allow-same-origin'],
+REQUIRED_FEATURES = ['geolocation'],
+REGISTERED_PLUGINS: Record<string, Plugin<any>> = {}
+
+export interface MSIInterface {
+  controls: Controls,
+  handles: Handles,
+  plugins: Plugins
+}
+
+export default class MSI extends EventEmitter {
+  private isDev: boolean
+  private baseURL: string
+  private isConnected: boolean
+  private options: MapOptions
+  private chn?: IOF
+  
+  /**
+   * Mapbox control Client
+   * 
+   * @param options - Initial options
+   */
+  constructor( options: MapOptions ){
+    super()
+
+    this.options = options
+    if( !this.options.accessToken )
+      throw new Error('Invalid Access Token')
+
+    this.isDev = this.options.env == 'dev' || false
+    this.baseURL = this.isDev ? 'http://localhost:4800' : 'https://msi.dedot.io'
+
+    this.isConnected = false
+  }
+
+  /**
+   * Listen to embedded iframe load
+   * 
+   * @param e - DOM EventTarget object
+   */
+  private onload( e: Event ){
+    const iframe = e.target as HTMLIFrameElement
+
+    // Remove all previous listeners when iframe reloaded
+    this.chn && this.chn.removeListeners()
+
+    this.chn = new IOF({ type: 'WINDOW' })
+    this.chn.initiate( iframe.contentWindow as Window, this.baseURL )
+
+    this.chn
+    .once('connect', () => {
+      this.chn?.emit('bind', { ...this.options, origin: window.origin }, ( error: string | boolean ) => {
+        if( error )
+          return this.emit('error', new Error( error as string ) )
+      
+        this.isConnected = true
+      })
+    })
+    .on('error', ( error: Error | string ) => this.emit('error', typeof error == 'object' ? error : new Error( error ) ) )
+    .on('ready', () => {
+      console.log('Ready by ready-event')
+      this.emit('ready')
+      this.emit('loaded', this.chn )
+    })
+    // .on('event', ( _event: string, ...args: any[] ) => this.emit( _event, ...args ) )
+  }
+
+  /**
+   * Embed the gateway into a web UI using
+   * an iframe.
+   */
+  private render(){
+    const container = document.getElementById( this.options.element )
+    if( !container ) throw new Error(`HTML Element Container <#${this.options.element}> Not Found`)
+    
+    container.innerHTML = `<iframe id="de-sdk:map"
+                                    src="${this.baseURL}"
+                                    style="width:100%;height:100%;border:none;"
+                                    title="De.MSI Gateway"
+                                    importance="high"
+                                    referrerpolicy="origin"
+                                    allow="${REQUIRED_FEATURES.join()}"
+                                    sandbox="${SANDBOX_RULES.join(' ')}"></iframe>`
+
+    const element = document.getElementById('de-sdk:map')
+    if( !element )
+      throw new Error('Unexpected Error Occured. Check HTML Element selector')
+
+    element.onload = this.onload.bind( this )
+  }
+
+  /**
+   * Handle gateway embedding network error
+   */
+  private networkError(){
+    this.isConnected = false
+    this.emit('error', new Error('Internet network problem') )
+  }
+
+  /**
+   * Initiate embedding of gateway into current UI by 
+   * check network and remote gateway availability.
+   */
+  load(): Promise<MSIInterface> {
+    return new Promise( ( resolve, reject ) => {
+      const initializeAPI = ( chn: IOF ) => {
+        const
+        /**
+         * Manual controls of the map remotely
+         */
+        controls = new Controls( chn, this.options ),
+        /**
+         * Initialize handles
+         */
+        handles = new Handles( chn, controls, this.options ),
+        /**
+         * Initialize plugins & mount preloaded ones
+         */
+        plugins = new Plugins( chn, handles, controls, this.options )
+        plugins.mount( REGISTERED_PLUGINS )
+        
+        resolve({ controls, handles, plugins })
+      }
+
+      this
+      .once('loaded', initializeAPI )
+      .once('error', reject )
+
+      window
+      .fetch( this.baseURL, { mode: 'no-cors' })
+      .then( this.render.bind( this ) )
+      .catch( this.networkError.bind( this ) )
+    } )
+  }
+
+  /**
+   * @return - Boolean that tells whether the gateway is 
+   * loaded and ready for interaction
+   */
+  isReady(){ return this.chn && this.isConnected }
+
+  /**
+   * Extend the kit's functionalities
+   * 
+   * @param name - Name of the plugin that will be later used to access the plugin object interface
+   * @param fn - Function containing the logic of the plugin
+   */
+  plugin<T>( name: string, fn: Plugin<T> ){
+    REGISTERED_PLUGINS[ name ] = fn
+  }
+}

package/src/allend/index.ts

@@ -0,0 +1,18 @@
+import MSI, { type MSIInterface } from './MSI'
+import Utils from '../utils'
+
+import IoTClient, { type IoTClientOptions } from './IoTClient'
+import Order from './DClient/Order'
+import Event from './DClient/Event'
+import Client from './DClient/Client'
+
+const DClient = { Client, Order, Event }
+
+export {
+  type MSIInterface,
+  MSI,
+  Utils,
+  DClient,
+  IoTClient,
+  type IoTClientOptions
+}