@de./sdk 1.0.4 → 2.0.0

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
+}

package/src/allend/OTPAuth/index.ts

@@ -0,0 +1,130 @@
+import type { AccessOptions, UserSession } from '../../types/access'
+import AccessManager from '../Access'
+import { qs, type Res } from '../../utils'
+
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// OTPAuth: sign a person in — de.auth routes.
+//
+// The whole flow is phone-and-OTP, in three steps:
+//
+//   signin( phone, device )  → sends the code, replies `{ next }`
+//   verify( phone, pvc )     → replies the session: ctoken + deviceId
+//   setAccount( … )          → only when `next` says the person is new
+//
+// This client used to POST `/v1/auth/otp`, which de.auth does not serve — the
+// single method it had could never succeed. Route shapes are taken from
+// de.auth/src/routes/{auth,user}/index.ts.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type SigninBody = {
+	phone: string
+	/** Device fingerprint — an object or its JSON string. */
+	device: string | Record<string, any>
+	/** ISO 3166-1 alpha-2. */
+	country?: string
+}
+
+export type SigninResult = {
+	/** What the caller must do next — verification, or account creation first. */
+	next: string
+	/**
+	 * The OTP itself, returned only when de.auth runs with
+	 * NODE_ENV=development. In every other environment the code arrives by SMS
+	 * and this is absent, which is what makes unattended sign-in a dev-only
+	 * capability rather than a hole.
+	 */
+	testVCode?: number
+}
+
+export type CreateAccountBody = {
+	phone: string
+	agreeTerms: boolean | string
+	firstName?: string
+	lastName?: string
+	photo?: string
+	type?: string
+	country?: string
+	newsletters?: boolean | string
+}
+
+export type VerifyResult = {
+	ctoken?: string
+	deviceId?: string
+	[ key: string ]: any
+}
+
+export default class OTPAuth extends AccessManager {
+	constructor( access: AccessOptions ){
+		super( access, 'ASI' )
+	}
+
+	// ── Sign-in ───────────────────────────────────────────────────────────────
+
+	/** Step 1 — sends the code. */
+	async signin( body: SigninBody ): Promise<Res<SigninResult>> {
+		if( !body.phone ) throw new Error('<phone> argument required')
+
+		return this.request<Res<SigninResult>>({ url: '/signin', method: 'POST', body })
+	}
+
+	/** Step 2 — exchanges the code for a session. */
+	async verify( body: { phone: string, pvc: number, new_phone?: string }): Promise<Res<VerifyResult>> {
+		return this.request<Res<VerifyResult>>({ url: '/verification', method: 'POST', body })
+	}
+
+	/** Step 1a — for a phone de.auth has never seen. */
+	async setAccount( body: CreateAccountBody ): Promise<Res<{ next: string }>> {
+		return this.request<Res<{ next: string }>>({ url: '/set-account', method: 'POST', body })
+	}
+
+	async resendSms( body: { phone: string }): Promise<Res<void>> {
+		return this.request<Res<void>>({ url: '/resend/sms', method: 'POST', body })
+	}
+
+	/** GET, with the scope in the querystring — not a POST. */
+	async signout( querystring?: { allDevices?: boolean | string }): Promise<Res<void>> {
+		return this.request<Res<void>>({ url: `/signout${qs( querystring )}`, method: 'GET' })
+	}
+
+	// ── The signed-in person ──────────────────────────────────────────────────
+
+	/**
+	 * Resolve the session to a user, and to a uid.
+	 *
+	 * `scope` is not optional in practice: without it de.auth falls back to the
+	 * calling service's configured scope and then fails its own response
+	 * validation. This is the same scope de.arch asks for.
+	 */
+	async active( session: UserSession, scope = 'name:photo:email:phone:timezone' ): Promise<Res<{ uid: string }>> {
+		return this.request<Res<{ uid: string }>>({
+			url: `/user/active${qs({ scope })}`,
+			method: 'GET',
+			headers: {
+				'de-auth-token':  session.token,
+				'de-auth-device': session.device
+			}
+		})
+	}
+
+	async retrieve( querystring?: { type?: string }): Promise<Res<{ user: any }>> {
+		return this.request<Res<{ user: any }>>({ url: `/user${qs( querystring )}`, method: 'GET' })
+	}
+
+	async search( querystring: Record<string, any> ): Promise<Res<any>> {
+		return this.request<Res<any>>({ url: `/user/search${qs( querystring )}`, method: 'GET' })
+	}
+
+	async updateProfile( body: Record<string, any> ): Promise<Res<any>> {
+		return this.request<Res<any>>({ url: '/user/profile', method: 'PATCH', body })
+	}
+
+	async updateSettings( body: Record<string, any> ): Promise<Res<any>> {
+		return this.request<Res<any>>({ url: '/user/settings', method: 'PATCH', body })
+	}
+
+	async remove( body: Record<string, any> ): Promise<Res<void>> {
+		return this.request<Res<void>>({ url: '/user', method: 'DELETE', body })
+	}
+}

package/src/allend/Pipelines/analytics.ts

@@ -0,0 +1,25 @@
+import type {
+	PipelineAnalyticsOverviewValidation,
+	PipelineAnalyticsPipelineValidation
+} from '@de./types'
+import { qs, type Http, type Res, type Data } from '../../utils'
+
+// ─── Analytics ────────────────────────────────────────────────────────────────
+
+export class PipelinesAnalytics {
+	constructor( private http: Http ){}
+
+	async overview( querystring?: PipelineAnalyticsOverviewValidation['querystring'] ): Promise<PipelineAnalyticsOverviewValidation['response']> {
+		return await this.http.request<PipelineAnalyticsOverviewValidation['response']>({
+			url: `/pipelines/analytics/overview${qs( querystring )}`,
+			method: 'GET'
+		})
+	}
+
+	async pipeline( pid: string, querystring?: PipelineAnalyticsPipelineValidation['querystring'] ): Promise<PipelineAnalyticsPipelineValidation['response']> {
+		return await this.http.request<PipelineAnalyticsPipelineValidation['response']>({
+			url: `/pipelines/analytics/pipeline/${pid}${qs( querystring )}`,
+			method: 'GET'
+		})
+	}
+}

package/src/allend/Pipelines/escalations.ts

@@ -0,0 +1,26 @@
+import type {
+	PipelineEscalationListValidation,
+	PipelineEscalationResolveValidation
+} from '@de./types'
+import { qs, type Http, type Res, type Data } from '../../utils'
+
+// ─── Escalations ──────────────────────────────────────────────────────────────
+
+export class PipelinesEscalations {
+  constructor( private http: Http ){}
+
+  async list( querystring?: PipelineEscalationListValidation['querystring'] ): Promise<PipelineEscalationListValidation['response']> {
+    return await this.http.request<PipelineEscalationListValidation['response']>({
+      url: `/pipelines/escalations${qs( querystring )}`,
+      method: 'GET'
+    })
+  }
+
+  async resolve( id: string, body?: PipelineEscalationResolveValidation['body'] ): Promise<PipelineEscalationResolveValidation['response']> {
+    return await this.http.request<PipelineEscalationResolveValidation['response']>({
+      url: `/pipelines/escalations/${id}/resolve`,
+      method: 'POST',
+      body
+    })
+  }
+}