@de./sdk 2.0.0 → 2.1.1

package/src/allend/MSI/native.tsx

@@ -1,6 +1,6 @@
 import type { MapOptions } from '../../types'
 
-import React, { useRef, useEffect, useState, useCallback, forwardRef, useImperativeHandle } from 'react'
+import React, { useRef, useEffect, useState, useCallback, useMemo, 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'
@@ -8,6 +8,7 @@ import Handles from './Handles'
 import Controls from './Controls'
 import Plugins, { type Plugin } from './Plugins'
 import resolveAccessToken from './token'
+import belongsToGateway from './origin'
 
 export interface MSIInterface {
   controls: Controls
@@ -115,6 +116,18 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
   apiRef = useRef<MSIInterface | null>( null ),
   isInitializedRef = useRef( false ),
 
+  /**
+   * The bridge is built once, so its handlers close over the props of the
+   * render that built it. `bind` resolves the access token at connect time
+   * precisely so a reconnect picks up a rotated one -- but reading it from a
+   * captured `props` gave back whatever `getAccessToken` closed over at mount,
+   * which for the usual `() => token` is the token the host held then. Every
+   * reconnect after a rotation would have re-bound with a dead token. Same for
+   * the callbacks: a host passing inline handlers had the mount-time ones
+   * called forever.
+   */
+  propsRef = useRef( props ),
+
   [ isConnected, setIsConnected ] = useState( false ),
   [ isReady, setIsReady ] = useState( false ),
 
@@ -128,13 +141,46 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
           ? error
           : new Error( typeof error === 'string' ? error : error?.error || 'Unknown MSI error')
 
-    props.onError?.( normalized )
-  }, [ props.onError ] ),
+    propsRef.current.onError?.( normalized )
+  }, [] ),
 
   initializeConnection = useCallback( () => {
     if( !wioRef.current || !webViewRef.current ) return
     wioRef.current.initiate( webViewRef, baseURL )
-  }, [ baseURL ] )
+  }, [ baseURL ] ),
+
+  /**
+   * Refuse to navigate anywhere but the gateway -- see `belongsToGateway`.
+   */
+  isGatewayURL = useCallback( ( url: string ) => belongsToGateway( baseURL, url ), [ baseURL ] ),
+
+  /**
+   * One options object for both ends of the bridge.
+   *
+   * `getInjectedJavaScript()` bakes the transport's own configuration into the
+   * script the WebView runs — the auth secret, the skew tolerance, the replay
+   * window. It used to be called on a throwaway `new WIO({ type: 'WEBVIEW' })`
+   * constructed inline in the JSX, which shares nothing with the instance that
+   * actually holds the connection: the embedded side would have been handed a
+   * null secret and default tolerances no matter what the host was configured
+   * with. Nothing configures cryptoAuth today, so it never showed.
+   */
+  wioOptions = useMemo( () => ({
+    type: 'WEBVIEW' as const,
+    debug: props.env === 'dev',
+    allowedIncomingEvents: ALLOWED_INCOMING_EVENTS,
+    maxMessagesPerSecond: 100,
+    connectionTimeout: 15000,
+    connectionPingInterval: 2000,
+    maxConnectionAttempts: 5,
+    autoReconnect: true,
+    heartbeatInterval: 30000
+  }), [ props.env ] ),
+
+  // Rebuilt only when those options change, rather than on every render.
+  injectedBridge = useMemo( () => new WIO( wioOptions ).getInjectedJavaScript(), [ wioOptions ] )
+
+  useEffect( () => { propsRef.current = props } )
 
   // Expose the control surface to the host
   useImperativeHandle( ref, () => ({
@@ -149,17 +195,7 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
   }), [ 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
-    })
+    const wio = wioRef.current = new WIO( wioOptions )
 
     wio
     .on('connect', async () => {
@@ -168,11 +204,11 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
          * 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
+        const { getAccessToken, onReady, onError, onLoaded, style, ...config } = propsRef.current
 
         await wio.emitAsync('bind', {
           ...config,
-          accessToken: resolveAccessToken( props ),
+          accessToken: resolveAccessToken( propsRef.current ),
           origin: 'react-native'
         }, BIND_TIMEOUT )
 
@@ -182,7 +218,7 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
     })
     .on('ready', () => {
       setIsReady( true )
-      props.onReady?.()
+      propsRef.current.onReady?.()
     })
     .on('disconnect', () => {
       setIsConnected( false )
@@ -201,19 +237,21 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
     })
 
     /**
-     * Pause gateway work while backgrounded, and re-establish the bridge on
-     * resume -- iOS in particular tears down the WebView's socket.
+     * Re-establish the bridge on resume -- iOS in particular tears down the
+     * WebView's socket while the app is backgrounded.
+     *
+     * This used to also emit `app:background` / `app:foreground`, which read
+     * like the gateway paused its work. It never did: the gateway has no
+     * handler for either, and its own allowlist dropped them before they got
+     * that far. Nor should there be a blanket one -- a rider streaming their
+     * position must keep streaming with the phone in their pocket, so whether
+     * backgrounding stops anything is the host's call, made through
+     * `controls.untrackLiveLocation()` and its counterpart.
      */
     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()
-      }
+      state === 'active'
+      && !wio.isConnected()
+      && initializeConnection()
     })
 
     return () => {
@@ -231,16 +269,16 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
 
     const
     chn = wioRef.current,
-    controls = new Controls( chn, props ),
-    handles = new Handles( chn, controls, props ),
-    plugins = new Plugins( chn, handles, controls, props )
+    controls = new Controls( chn, propsRef.current ),
+    handles = new Handles( chn, controls, propsRef.current ),
+    plugins = new Plugins( chn, handles, controls, propsRef.current )
 
     plugins.mount( REGISTERED_PLUGINS )
 
     apiRef.current = { controls, handles, plugins }
     isInitializedRef.current = true
 
-    props.onLoaded?.( apiRef.current )
+    propsRef.current.onLoaded?.( apiRef.current )
   }, [ isConnected, isReady ] )
 
   const onMessage = ( event: any ) => {
@@ -274,7 +312,7 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
         style={styles.webview}
         injectedJavaScript={`
           ${props.env === 'dev' ? injectedConsole() : ''}
-          ${new WIO({ type: 'WEBVIEW' }).getInjectedJavaScript()}
+          ${injectedBridge}
         `}
         javaScriptEnabled
         domStorageEnabled
@@ -287,6 +325,7 @@ export default forwardRef<MSIRef, MSIProps>( ( props, ref ) => {
         bounces={false}
         scrollEnabled={false}
         originWhitelist={[ baseURL ]}
+        onShouldStartLoadWithRequest={( { url }: any ) => isGatewayURL( url )}
         onMessage={onMessage}
         onLoadEnd={initializeConnection}
         onError={( { nativeEvent }: any ) => reportError( new Error( nativeEvent?.description || 'WebView error') )}

package/src/allend/MSI/origin.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether a URL belongs to the MSI gateway itself.
+ *
+ * React Native's `originWhitelist` is prefix-matched and unanchored at the
+ * end, so a whitelist of `https://msi.dedot.io` also admits
+ * `https://msi.dedot.io.example.com`. That matters more in a WebView than it
+ * would in a browser: the injected bridge — and the auth secret baked into
+ * it — runs in whatever page the WebView ends up on. So the origin has to
+ * match exactly, and only a path, query or fragment separator may follow it.
+ *
+ * @param baseURL - Gateway origin, without a trailing slash
+ * @param url - URL the WebView is asking to navigate to
+ * @return - Whether the navigation is to the gateway
+ */
+export default function belongsToGateway( baseURL: string, url: string ): boolean {
+  if( !url || !baseURL ) return false
+  if( url === 'about:blank' || url === baseURL ) return true
+
+  return [ '/', '?', '#' ].some( separator => url.startsWith( baseURL + separator ) )
+}

package/src/allend/OTPAuth/index.ts

@@ -1,3 +1,4 @@
+import type { SigninBody, CreateAccountBody, VerificationBody } from '@de./types'
 import type { AccessOptions, UserSession } from '../../types/access'
 import AccessManager from '../Access'
 import { qs, type Res } from '../../utils'
@@ -16,15 +17,23 @@ import { qs, type Res } from '../../utils'
 // single method it had could never succeed. Route shapes are taken from
 // de.auth/src/routes/{auth,user}/index.ts.
 //
+// The paths now say what they do — `/auth/otp/send` rather than `/signin`,
+// which sent a code and signed nobody in. The method names here are kept as
+// they were: `signin` is what a caller is doing, even when what it costs is
+// one SMS.
+//
 // ─────────────────────────────────────────────────────────────────────────────
 
-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
-}
+/**
+ * Request bodies come from `@de./types`, which is what de.auth validates
+ * against — these were hand-declared here, and said `country?: string` where
+ * de.auth wants the Country OBJECT. Its schema is additionalProperties:false,
+ * so a caller trusting the SDK's type was answered `body/country must be
+ * object`. Nothing caught it because this client could not be constructed at
+ * all: AccessManager demanded a workspace context and a bearer token, which
+ * sign-in is what produces.
+ */
+export type { SigninBody, CreateAccountBody, VerificationBody, Country } from '@de./types'
 
 export type SigninResult = {
 	/** What the caller must do next — verification, or account creation first. */
@@ -38,17 +47,6 @@ export type SigninResult = {
 	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
@@ -57,7 +55,17 @@ export type VerifyResult = {
 
 export default class OTPAuth extends AccessManager {
 	constructor( access: AccessOptions ){
-		super( access, 'ASI' )
+		/**
+		 * de.auth admits an agent that does not start with `De.service` only if
+		 * the request carries an Authorization header — and the whole point of
+		 * this client is the flow that has no token yet. The SDK's default
+		 * platform is `proxy`, so every sign-in through it was answered 412
+		 * before reaching a handler.
+		 *
+		 * `service` is the platform this client is for; a caller that knows
+		 * better can still say so.
+		 */
+		super({ ...access, platform: access.platform || 'service' }, 'ASI' )
 	}
 
 	// ── Sign-in ───────────────────────────────────────────────────────────────
@@ -66,26 +74,26 @@ export default class OTPAuth extends AccessManager {
 	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 })
+		return this.request<Res<SigninResult>>({ url: '/auth/otp/send', 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 })
+		return this.request<Res<VerifyResult>>({ url: '/auth/otp/verify', 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 })
+		return this.request<Res<{ next: string }>>({ url: '/auth/account/create', method: 'POST', body })
 	}
 
 	async resendSms( body: { phone: string }): Promise<Res<void>> {
-		return this.request<Res<void>>({ url: '/resend/sms', method: 'POST', body })
+		return this.request<Res<void>>({ url: '/auth/otp/resend', method: 'POST', body })
 	}
 
-	/** GET, with the scope in the querystring — not a POST. */
+	/** A state change, so a POST — it was a GET, which is cacheable. */
 	async signout( querystring?: { allDevices?: boolean | string }): Promise<Res<void>> {
-		return this.request<Res<void>>({ url: `/signout${qs( querystring )}`, method: 'GET' })
+		return this.request<Res<void>>({ url: `/auth/session/revoke${qs( querystring )}`, method: 'POST' })
 	}
 
 	// ── The signed-in person ──────────────────────────────────────────────────

package/src/baseUrl.ts

@@ -41,11 +41,9 @@ export const API_SERVER_BASEURL = {
  * It is not reachable through the API host: de.arch serves no `/workspace`
  * routes, so a client pointed there gets 404 for the whole surface.
  *
- * The staging and production hosts follow the naming of the other services
- * (auth.dedot.io, iot.dedot.io). Confirm them against the deployment before
- * relying on them, and pass `baseUrl` to address a host that differs — which
- * is also what a self-hosted De. needs, and what a dev machine running
- * de.workspace on a port other than 22200 needs.
+ * Pass `baseUrl` to address a host that differs — what a self-hosted De.
+ * needs, and what a dev machine running de.workspace on a port other than
+ * 22200 needs.
  */
 export const WSP_SERVER_BASEURL = {
 	dev:     `http://localhost:${DEV_PORTS.WSP}`,

package/src/core.ts

@@ -59,6 +59,7 @@ export type { WorkflowsConfig } from './allend/Workflows'
 export { default as Utils } from './utils'
 
 export { default as APIError } from './error'
+export { statusOf } from './response'
 
 // ── Client layer (allend) ─────────────────────────────────────────────────────
 // DClient ({ Client, Event }), the IoT socket client, and the customer/agent/

package/src/response.ts

@@ -0,0 +1,38 @@
+/**
+ * The HTTP status a returned envelope arrived with.
+ *
+ * Clients return De.'s `{ error, status, message, data }` envelope, which is
+ * what makes `status` — the precise refusal code — reachable. It carries no
+ * HTTP status, and for most callers that is right: the envelope says more than
+ * a number can.
+ *
+ * A proxy is the exception. It answers its own client with an HTTP status, and
+ * mapping every De. refusal onto a generic 400 loses the distinction between
+ * "no such order" and "you may not do that" for whoever is downstream.
+ *
+ * So the status is kept beside the response rather than inside it: the type
+ * stays exactly the envelope, and a caller that needs the number asks for it,
+ * keyed on the object it was given. Keying on identity rather than on a
+ * mutable field is what makes it safe under concurrency — two calls in flight
+ * cannot read each other's status.
+ *
+ * ```ts
+ * const answer = await lsp.orders.get( reference )
+ * if( answer.error ) throw new HTTPException( statusOf( answer ) ?? 400, ... )
+ * ```
+ */
+const statuses = new WeakMap<object, number>()
+
+/** Record the status for a parsed response body. Called by the transport. */
+export const rememberStatus = ( body: unknown, status: number ): void => {
+	if( body && typeof body === 'object' ) statuses.set( body as object, status )
+}
+
+/**
+ * The HTTP status the given envelope arrived with.
+ *
+ * `undefined` when the object did not come from this SDK's transport, or when
+ * the call threw instead of returning — `APIError` carries its own `status`.
+ */
+export const statusOf = ( envelope: unknown ): number | undefined =>
+	envelope && typeof envelope === 'object' ? statuses.get( envelope as object ) : undefined

package/src/utils/index.ts

@@ -21,16 +21,35 @@ export type Res<T = any> = { error: boolean, status?: string, message?: string,
  */
 export type Data<T> = 'data' extends keyof T ? T['data'] : undefined
 
+/**
+ * Serialize a querystring for a De. route.
+ *
+ * Array values are appended as repeated keys — `state=A&state=B` — which is
+ * what Fastify's query parser turns back into an array. `String( value )` on
+ * an array produces `A,B`, a single comma-joined string, and the route answers
+ * `querystring/state must be array`: the schema is right, the request never
+ * matched it. Every array parameter the SDK sent was malformed this way, the
+ * same shape of fault as the coordinates object that once serialized to
+ * `[object Object]`.
+ *
+ * @param params - Query parameters; null and undefined values are dropped
+ * @return - `?a=1&b=2`, or an empty string when there is nothing to send
+ */
 export const qs = ( params?: Record<string, any> ): string => {
   if( !params ) return ''
-  const q = new URLSearchParams(
-    Object.fromEntries(
-      Object.entries( params )
-            .filter( ( [, v] ) => v != null )
-            .map( ( [k, v] ) => [k, String( v )] )
-    )
-  ).toString()
-  return q ? `?${q}` : ''
+
+  const q = new URLSearchParams()
+
+  for( const [ key, value ] of Object.entries( params ) ){
+    if( value === null || value === undefined ) continue
+
+    Array.isArray( value )
+      ? value.forEach( each => each !== null && each !== undefined && q.append( key, String( each ) ) )
+      : q.append( key, String( value ) )
+  }
+
+  const query = q.toString()
+  return query ? `?${query}` : ''
 }
 
 export default { Stream }