@de./sdk 1.0.5 → 2.1.0

package/src/allend/MSI/Handles.ts

@@ -2,6 +2,7 @@ import type {
   Coordinates,
   RTLocation,
   MSIEntity as Entity,
+  MSIEntityType,
   MapOptions,
   Caption,
   Journey,
@@ -13,17 +14,17 @@ import type {
   LRStreamer
 } from '../../types'
 
-import IOF from 'iframe.io'
+import type { Channel } from '../../types/channel'
 import { EventEmitter } from 'events'
 import Controls from './Controls'
 import Stream from '../../utils/stream'
 
 export default class Handles extends EventEmitter {
-  private chn: IOF
+  private chn: Channel
   private controls: Controls
   private options: MapOptions
 
-  constructor( chn: IOF, controls: Controls, options: MapOptions ){
+  constructor( chn: Channel, controls: Controls, options: MapOptions ){
     super()
 
     this.chn = chn
@@ -70,7 +71,9 @@ export default class Handles extends EventEmitter {
 
       this.chn
       .off('current:location')
-      .off('current:location:live')
+      .off('live:location:start')
+      .off('live:location:update')
+      .off('live:location:end')
       .off('current:location:error')
     } )
 
@@ -83,21 +86,27 @@ export default class Handles extends EventEmitter {
    * 
    * @param position - Peer's current GPS location
    * @param caption - (Optional) Caption information of the peer
+   * @param type - (Default: `car`) Marker representing the peer on the map
    * @return - Readable stream
    */
-  peerLocation( position: RTLocation , caption?: Caption ){
+  peerLocation( position: RTLocation, caption?: Caption, type?: MSIEntityType ){
     if( !this.chn ) return
-    this.chn?.emit('pin:peer:location', { id: 'peer', position, caption } )
-    
+    this.chn?.emit('pin:peer:location', { id: 'peer', position, caption, type } )
+
     const stream = new Stream
-    
-    // Listen to incoming new position data
+
+    /**
+     * Listen to incoming new position data.
+     *
+     * Caption is re-sent on every update so a peer can stream a changing
+     * label (Eg. a live ETA) alongside its position.
+     */
     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 } )
+      this.chn?.emit('pin:peer:location', { id: 'peer', position, caption, type } )
     })
     .onerror( error => console.error('[Stream Error] ', error ) )
     .onclose( () => this.chn?.emit('unpin:peer:location', 'peer') )
@@ -154,7 +163,7 @@ export default class Handles extends EventEmitter {
             self.emit('nearby--stream', 'add', entity )
           } )
 
-          setTimeout( () => reject('Add entity timeout'), 8000 )
+          TIMEOUT = setTimeout( () => reject('Add entity timeout'), 8000 )
         })
       },
 
@@ -178,7 +187,7 @@ export default class Handles extends EventEmitter {
             self.emit('nearby--stream', 'remove', id )
           } )
 
-          setTimeout( () => reject('Remove entity timeout'), 8000 )
+          TIMEOUT = setTimeout( () => reject('Remove entity timeout'), 8000 )
         } )
       },
 
@@ -205,7 +214,7 @@ export default class Handles extends EventEmitter {
             self.emit('nearby--stream', 'panto', id )
           } )
 
-          setTimeout( () => reject('PanTo entity timeout'), 8000 )
+          TIMEOUT = setTimeout( () => reject('PanTo entity timeout'), 8000 )
         } )
       },
       
@@ -237,7 +246,7 @@ export default class Handles extends EventEmitter {
             self.emit('nearby--stream', 'move', active )
           } )
 
-          setTimeout( () => reject('Move entity timeout'), 8000 )
+          TIMEOUT = setTimeout( () => reject('Move entity timeout'), 8000 )
         } )
       }
     }

package/src/allend/MSI/Plugins.ts

@@ -1,6 +1,6 @@
 import type { MapOptions } from '../../types'
 
-import IOF from 'iframe.io'
+import type { Channel } from '../../types/channel'
 import Handles from './Handles'
 import Controls from './Controls'
 import Utils from '../../utils'
@@ -14,13 +14,13 @@ export type PluginHook = {
 export type Plugin<PluginAPI, PluginOptions = {}> = ( hooks: PluginHook, options?: PluginOptions ) => PluginAPI
 
 export default class Plugins {
-  private chn: IOF
+  private chn: Channel
   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 ){
+  constructor( chn: Channel, handles: Handles, controls: Controls, options: MapOptions ){
     this.chn = chn
     this.options = options
     this.handles = handles

package/src/allend/MSI/index.ts

@@ -5,11 +5,32 @@ import IOF from 'iframe.io'
 import Handles from './Handles'
 import Controls from './Controls'
 import Plugins, { type Plugin } from './Plugins'
+import resolveAccessToken from './token'
 
 const
 SANDBOX_RULES = ['allow-scripts', 'allow-same-origin'],
 REQUIRED_FEATURES = ['geolocation'],
-REGISTERED_PLUGINS: Record<string, Plugin<any>> = {}
+REGISTERED_PLUGINS: Record<string, Plugin<any>> = {},
+
+// How long to wait for the gateway to embed, connect and bind
+LOAD_TIMEOUT = 30000,
+
+/**
+ * Events the gateway is allowed to send us. Anything else is dropped by the
+ * transport before it reaches a listener.
+ */
+ALLOWED_INCOMING_EVENTS = [
+  'error',
+  'ready',
+  'pick:location',
+  'current:location',
+  'current:location:error',
+  'live:location:start',
+  'live:location:update',
+  'live:location:end',
+  'route',
+  'navigation:direction'
+]
 
 export interface MSIInterface {
   controls: Controls,
@@ -22,6 +43,7 @@ export default class MSI extends EventEmitter {
   private baseURL: string
   private isConnected: boolean
   private options: MapOptions
+  private element: string
   private chn?: IOF
   
   /**
@@ -33,11 +55,23 @@ export default class MSI extends EventEmitter {
     super()
 
     this.options = options
-    if( !this.options.accessToken )
-      throw new Error('Invalid Access Token')
+
+    /**
+     * `element` is optional on MapOptions because the React Native entry
+     * renders a component instead, but the web entry cannot mount without it.
+     */
+    if( !this.options.element )
+      throw new Error('Undefined HTML Element Container')
+
+    this.element = this.options.element
+
+    // Throws when neither `accessToken` nor `getAccessToken` yields a token
+    resolveAccessToken( this.options )
 
     this.isDev = this.options.env == 'dev' || false
-    this.baseURL = this.isDev ? 'http://localhost:4800' : 'https://msi.dedot.io'
+    this.baseURL = this.isDev
+              ? `http://${this.options.devHostname || 'localhost'}:4800`
+              : 'https://msi.dedot.io'
 
     this.isConnected = false
   }
@@ -53,12 +87,28 @@ export default class MSI extends EventEmitter {
     // Remove all previous listeners when iframe reloaded
     this.chn && this.chn.removeListeners()
 
-    this.chn = new IOF({ type: 'WINDOW' })
+    this.chn = new IOF({
+      type: 'WINDOW',
+      allowedIncomingEvents: ALLOWED_INCOMING_EVENTS,
+      maxMessagesPerSecond: 100,
+      connectionTimeout: 10000
+    })
     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 ) => {
+      /**
+       * Resolve the token at bind time rather than reusing the one captured at
+       * construction, so a host supplying `getAccessToken` reconnects with a
+       * fresh token after a reload.
+       */
+      const { getAccessToken, ...config } = this.options
+
+      this.chn?.emit('bind', {
+        ...config,
+        accessToken: resolveAccessToken( this.options ),
+        origin: window.origin
+      }, ( error: string | boolean ) => {
         if( error )
           return this.emit('error', new Error( error as string ) )
       
@@ -67,7 +117,6 @@ export default class MSI extends EventEmitter {
     })
     .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 )
     })
@@ -79,8 +128,8 @@ export default class MSI extends EventEmitter {
    * an iframe.
    */
   private render(){
-    const container = document.getElementById( this.options.element )
-    if( !container ) throw new Error(`HTML Element Container <#${this.options.element}> Not Found`)
+    const container = document.getElementById( this.element )
+    if( !container ) throw new Error(`HTML Element Container <#${this.element}> Not Found`)
     
     container.innerHTML = `<iframe id="de-sdk:map"
                                     src="${this.baseURL}"
@@ -99,20 +148,31 @@ export default class MSI extends EventEmitter {
   }
 
   /**
-   * Handle gateway embedding network error
+   * Surface a failure that happened while embedding the gateway
    */
-  private networkError(){
+  private embedError( error: Error ){
     this.isConnected = false
-    this.emit('error', new Error('Internet network problem') )
+    this.emit('error', error )
   }
 
   /**
    * Initiate embedding of gateway into current UI by 
    * check network and remote gateway availability.
    */
-  load(): Promise<MSIInterface> {
+  load( timeout: number = LOAD_TIMEOUT ): Promise<MSIInterface> {
     return new Promise( ( resolve, reject ) => {
+      /**
+       * Without this the promise stays pending forever whenever the iframe
+       * never loads or the host never completes `bind`.
+       */
+      const timer = setTimeout( () => {
+        this.isConnected = false
+        reject( new Error('MSI gateway load timeout') )
+      }, timeout )
+
       const initializeAPI = ( chn: IOF ) => {
+        clearTimeout( timer )
+
         const
         /**
          * Manual controls of the map remotely
@@ -133,12 +193,21 @@ export default class MSI extends EventEmitter {
 
       this
       .once('loaded', initializeAPI )
-      .once('error', reject )
+      .once('error', ( error: Error ) => {
+        clearTimeout( timer )
+        reject( error )
+      } )
 
       window
       .fetch( this.baseURL, { mode: 'no-cors' })
-      .then( this.render.bind( this ) )
-      .catch( this.networkError.bind( this ) )
+      // Only a genuine reachability failure is a network problem
+      .catch( () => { throw new Error('Internet network problem') } )
+      /**
+       * Kept in a separate step so a `render` failure (Eg. a missing container
+       * element) reports itself rather than being relabelled a network error.
+       */
+      .then( () => this.render() )
+      .catch( this.embedError.bind( this ) )
     } )
   }
 

package/src/allend/MSI/native.tsx

@@ -0,0 +1,314 @@
+import type { MapOptions } from '../../types'
+
+import React, { useRef, useEffect, useState, useCallback, forwardRef, useImperativeHandle } from 'react'
+import { View, StyleSheet, AppState, type AppStateStatus, Platform } from 'react-native'
+import { WebView } from 'react-native-webview'
+import WIO from 'webview.io'
+import Handles from './Handles'
+import Controls from './Controls'
+import Plugins, { type Plugin } from './Plugins'
+import resolveAccessToken from './token'
+
+export interface MSIInterface {
+  controls: Controls
+  handles: Handles
+  plugins: Plugins
+}
+
+const
+REGISTERED_PLUGINS: Record<string, Plugin<any>> = {},
+
+// Time allowed for the gateway to acknowledge `bind`
+BIND_TIMEOUT = 10000,
+
+/**
+ * Events the gateway is allowed to send us. Anything else is dropped by the
+ * transport before it reaches a listener.
+ *
+ * Kept identical to the web entry: the gateway speaks one protocol, and the
+ * two entries differ only in transport.
+ */
+ALLOWED_INCOMING_EVENTS = [
+  'error',
+  'ready',
+  'pick:location',
+  'current:location',
+  'current:location:error',
+  'live:location:start',
+  'live:location:update',
+  'live:location:end',
+  'route',
+  'navigation:direction'
+]
+
+/**
+ * Forward the WebView's console into the React Native log.
+ *
+ * Injected only in dev: in production it turns every gateway log into a bridge
+ * message, which is pure overhead on the very traffic the map depends on.
+ */
+function injectedConsole(): string {
+  return `
+    (function(){
+      var forward = function( level ){
+        var original = console[ level ]
+        console[ level ] = function(){
+          var args = Array.prototype.slice.call( arguments )
+          try {
+            window.ReactNativeWebView.postMessage( JSON.stringify({
+              type: '__console',
+              level: level,
+              message: args.map( String ).join(' ')
+            }) )
+          }
+          catch( error ){}
+
+          original.apply( console, args )
+        }
+      }
+
+      forward('log')
+      forward('warn')
+      forward('error')
+    })();
+  `
+}
+
+/**
+ * Resolve the gateway host for the running platform.
+ *
+ * A native app cannot reach the developer's machine on `localhost`: the Android
+ * emulator maps the host to 10.0.2.2, and a physical device needs the LAN
+ * address, supplied as `devHostname`.
+ */
+function gatewayURL({ env, devHostname }: MapOptions ): string {
+  if( env !== 'dev' ) return 'https://msi.dedot.io'
+
+  const host = devHostname
+        || Platform.select({ android: '10.0.2.2', default: 'localhost' })
+
+  return `http://${host}:4800`
+}
+
+export interface MSIProps extends MapOptions {
+  onReady?: () => void
+  onError?: ( error: Error ) => void
+  onLoaded?: ( msi: MSIInterface ) => void
+  style?: any
+}
+
+export interface MSIRef extends Partial<MSIInterface> {
+  isReady: () => boolean
+  retry: () => void
+}
+
+/**
+ * MSI gateway for React Native.
+ *
+ * Mirrors the web entry: same Controls/Handles/Plugins surface, same protocol,
+ * same event allowlist -- only the transport and the mounting differ.
+ */
+export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
+  const
+  webViewRef = useRef<WebView>( null ),
+  wioRef = useRef<WIO | null>( null ),
+  apiRef = useRef<MSIInterface | null>( null ),
+  isInitializedRef = useRef( false ),
+
+  [ isConnected, setIsConnected ] = useState( false ),
+  [ isReady, setIsReady ] = useState( false ),
+
+  baseURL = gatewayURL( props ),
+
+  /**
+   * Report an error once, in Error form, whatever shape the transport used.
+   */
+  reportError = useCallback( ( error: any ) => {
+    const normalized = error instanceof Error
+          ? error
+          : new Error( typeof error === 'string' ? error : error?.error || 'Unknown MSI error')
+
+    props.onError?.( normalized )
+  }, [ props.onError ] ),
+
+  initializeConnection = useCallback( () => {
+    if( !wioRef.current || !webViewRef.current ) return
+    wioRef.current.initiate( webViewRef, baseURL )
+  }, [ baseURL ] )
+
+  // Expose the control surface to the host
+  useImperativeHandle( ref, () => ({
+    get controls(){ return apiRef.current?.controls },
+    get handles(){ return apiRef.current?.handles },
+    get plugins(){ return apiRef.current?.plugins },
+    isReady: () => isConnected && isReady,
+    retry: () => {
+      isInitializedRef.current = false
+      initializeConnection()
+    }
+  }), [ isConnected, isReady, initializeConnection ] )
+
+  useEffect( () => {
+    const wio = wioRef.current = new WIO({
+      type: 'WEBVIEW',
+      debug: props.env === 'dev',
+      allowedIncomingEvents: ALLOWED_INCOMING_EVENTS,
+      maxMessagesPerSecond: 100,
+      connectionTimeout: 15000,
+      connectionPingInterval: 2000,
+      maxConnectionAttempts: 5,
+      autoReconnect: true,
+      heartbeatInterval: 30000
+    })
+
+    wio
+    .on('connect', async () => {
+      try {
+        /**
+         * Resolve the token here rather than at mount, so a reconnect after a
+         * backgrounded app or a dropped bridge binds with a current token.
+         */
+        const { getAccessToken, onReady, onError, onLoaded, style, ...config } = props
+
+        await wio.emitAsync('bind', {
+          ...config,
+          accessToken: resolveAccessToken( props ),
+          origin: 'react-native'
+        }, BIND_TIMEOUT )
+
+        setIsConnected( true )
+      }
+      catch( error ){ reportError( error ) }
+    })
+    .on('ready', () => {
+      setIsReady( true )
+      props.onReady?.()
+    })
+    .on('disconnect', () => {
+      setIsConnected( false )
+      setIsReady( false )
+    })
+    .on('reconnecting', () => {
+      setIsConnected( false )
+      setIsReady( false )
+    })
+    .on('connect_timeout', ({ attempts }: any ) => reportError( new Error(`Failed to connect after ${attempts} attempts`) ) )
+    .on('reconnection_failed', ({ attempts }: any ) => reportError( new Error(`Reconnection failed after ${attempts} attempts`) ) )
+    .on('error', ( error: any ) => {
+      // Rate limiting is throttling, not a failure of the map
+      if( error?.type === 'RATE_LIMIT_EXCEEDED' ) return
+      reportError( error )
+    })
+
+    /**
+     * Pause gateway work while backgrounded, and re-establish the bridge on
+     * resume -- iOS in particular tears down the WebView's socket.
+     */
+    const subscription = AppState.addEventListener('change', ( state: AppStateStatus ) => {
+      if( state === 'background' ){
+        wio.emit('app:background')
+        return
+      }
+
+      if( state === 'active' ){
+        wio.emit('app:foreground')
+        !wio.isConnected() && initializeConnection()
+      }
+    })
+
+    return () => {
+      subscription.remove()
+      wio.disconnect()
+
+      apiRef.current = null
+      isInitializedRef.current = false
+    }
+  }, [] )
+
+  // Build the control surface once the bridge is both connected and ready
+  useEffect( () => {
+    if( isInitializedRef.current || !wioRef.current || !isConnected || !isReady ) return
+
+    const
+    chn = wioRef.current,
+    controls = new Controls( chn, props ),
+    handles = new Handles( chn, controls, props ),
+    plugins = new Plugins( chn, handles, controls, props )
+
+    plugins.mount( REGISTERED_PLUGINS )
+
+    apiRef.current = { controls, handles, plugins }
+    isInitializedRef.current = true
+
+    props.onLoaded?.( apiRef.current )
+  }, [ isConnected, isReady ] )
+
+  const onMessage = ( event: any ) => {
+    // Console forwarding rides the same bridge; peel it off before WIO sees it
+    try {
+      const data = JSON.parse( event.nativeEvent.data )
+      if( data?.type === '__console' ){
+        const message = `[MSI gateway] ${data.message}`
+
+        switch( data.level ){
+          case 'error': console.error( message ); break
+          case 'warn': console.warn( message ); break
+          default: console.debug( message )
+        }
+
+        return
+      }
+    }
+    catch( error ){
+      // Not console traffic -- fall through to the transport
+    }
+
+    wioRef.current?.handleMessage( event )
+  }
+
+  return (
+    <View style={[ styles.container, props.style ]}>
+      <WebView
+        ref={webViewRef}
+        source={{ uri: baseURL }}
+        style={styles.webview}
+        injectedJavaScript={`
+          ${props.env === 'dev' ? injectedConsole() : ''}
+          ${new WIO({ type: 'WEBVIEW' }).getInjectedJavaScript()}
+        `}
+        javaScriptEnabled
+        domStorageEnabled
+        geolocationEnabled
+        allowsInlineMediaPlayback
+        cacheEnabled={props.env !== 'dev'}
+        incognito={props.env === 'dev'}
+        androidLayerType="hardware"
+        allowsBackForwardNavigationGestures={false}
+        bounces={false}
+        scrollEnabled={false}
+        originWhitelist={[ baseURL ]}
+        onMessage={onMessage}
+        onLoadEnd={initializeConnection}
+        onError={( { nativeEvent }: any ) => reportError( new Error( nativeEvent?.description || 'WebView error') )}
+      />
+    </View>
+  )
+} )
+
+/**
+ * Register a plugin to be mounted on every MSI instance.
+ */
+export function plugin<T>( name: string, fn: Plugin<T> ){
+  REGISTERED_PLUGINS[ name ] = fn
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#f0f0f0'
+  },
+  webview: {
+    flex: 1,
+    backgroundColor: 'transparent'
+  }
+})

package/src/allend/MSI/token.ts

@@ -0,0 +1,20 @@
+import type { MapOptions } from '../../types'
+
+/**
+ * Resolve the access token to bind the gateway with.
+ *
+ * `getAccessToken` wins when supplied, and is deliberately called at every bind
+ * rather than read once: a host that rotates tokens can hand back a fresh one
+ * on reconnect without the caller having to drive `controls.refreshToken()`.
+ *
+ * @param options - Map options carrying either form of the token
+ * @return - A non-empty access token
+ */
+export default function resolveAccessToken( options: MapOptions ): string {
+  const token = options.getAccessToken?.() || options.accessToken
+
+  if( !token )
+    throw new Error('Invalid Access Token')
+
+  return token
+}