@de./sdk-rn 1.1.6 → 1.2.0

package/src/allend/Agent/reallocation.ts

@@ -0,0 +1,18 @@
+import type { AgentReallocationRespondValidation } from '@de./types'
+import { type Http, type Res } from '../../utils'
+
+// ─── Agent Reallocation ───────────────────────────────────────────────────────
+
+export default class AgentReallocation {
+	constructor( private http: Http ){}
+
+	async respond( body: AgentReallocationRespondValidation['body'] ): Promise<AgentReallocationRespondValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentReallocationRespondValidation['response']>>({
+			url: '/agent/reallocation/respond',
+			method: 'POST',
+			body
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+}

package/src/allend/Agent/realtime.ts

@@ -0,0 +1,135 @@
+import type { OrderTrackingEvent } from '@de./types'
+import type { RTLocation, Message, Peer } from '../../types'
+import type { SocketAuthCredentials } from '../../types/auth'
+import type { AccessOptions } from '../../types/access'
+
+import io, { Socket } from 'socket.io-client'
+import AccessManager from '../Access'
+import baseURL from '../../baseUrl'
+
+// ─── Agent Realtime ───────────────────────────────────────────────────────────
+//
+// Socket channel for riders. Two jobs:
+//
+// 1. Order rooms — after `join(jrtoken)` (token from the platform's tracking
+//    session, role=agent) the rider streams LOCATION-CHANGE / MESSAGE into
+//    the room and receives ORDER_UPDATE events for the order.
+//
+// 2. Proactive-consolidation responses — CONSOLIDATION_ACK / NACK / POSITION
+//    go over the socket, NOT the REST respond endpoints (those serve relay
+//    and dispatch offers). See de.arch consolidation README: response channels.
+//
+// NOTE — dispatch/consolidation OFFERS do not arrive on this socket: De.
+// emits RALLY_EVENT to service connections only, and the operating platform
+// (e.g. its backend SSE) relays offers to the rider app. Respond to relayed
+// offers via `agent.dispatch.respond(...)` / `agent.consolidation.respond(...)`.
+
+export type AgentRealtimeContext = {
+  wid: string
+  type: string
+  xcode: string
+}
+
+export default class AgentRealtime extends AccessManager {
+  private nsp?: Socket
+  private iosHost: string
+  private agentId?: string
+
+  constructor( access: AccessOptions ){
+    super( access, 'API' )
+
+    // Socket.io is served by the same de.arch API server
+    const { API_SERVER_BASEURL } = baseURL( access.devHostname )
+    this.iosHost = API_SERVER_BASEURL[ access.env || 'dev' ] as string
+  }
+
+  connect( agentId: string ): Promise<void> {
+    return new Promise( ( resolve, reject ) => {
+      const auth: SocketAuthCredentials = {
+        utype: 'agent',
+        id: agentId,
+        remoteOrigin: this.remoteOrigin as string,
+        accessToken: this.accessToken as string
+      }
+
+      this.agentId = agentId
+      this.nsp = io( this.iosHost, { auth } )
+      this.nsp.on('connect', resolve )
+      this.nsp.on('connect_error', reject )
+    } )
+  }
+
+  disconnect(){
+    this.nsp?.disconnect()
+    return true
+  }
+
+  /**
+   * Join an order tracking room with a Join Room Token issued by
+   * GET /v1/tracking/:reference (role must match this socket's utype)
+   */
+  join( jrtoken: string ): Promise<boolean> {
+    return new Promise( ( resolve, reject ) => {
+      this.nsp?.emit('JOIN', jrtoken, ( errmess?: string ) => {
+        errmess ? reject( new Error( errmess ) ) : resolve( true )
+      } )
+    } )
+  }
+
+  // ── Order room streams (after join) ─────────────────────────────────────
+
+  sendLocation( location: RTLocation ){
+    this.nsp?.emit('LOCATION-CHANGE', location )
+    return this
+  }
+
+  sendMessage( message: Message ){
+    this.nsp?.emit('MESSAGE', message )
+    return this
+  }
+
+  onOrderUpdate( fn: ( event: OrderTrackingEvent ) => void ){
+    this.nsp?.on('ORDER_UPDATE', fn )
+    return this
+  }
+
+  onMessage( fn: ( message: Message ) => void ){
+    this.nsp?.on('MESSAGE', fn )
+    return this
+  }
+
+  onConnected( fn: ( peer: Peer ) => void ){
+    this.nsp?.on('CONNECTED', fn )
+    return this
+  }
+
+  onDisconnected( fn: ( peer: Peer ) => void ){
+    this.nsp?.on('DISCONNECTED', fn )
+    return this
+  }
+
+  // ── Proactive consolidation channel (socket-only responses) ─────────────
+
+  ackConsolidation( context: AgentRealtimeContext, offerId: string ){
+    if( !this.agentId ) throw new Error('Not connected')
+    this.nsp?.emit('CONSOLIDATION_ACK', { context, offerId, agentId: this.agentId } )
+    return this
+  }
+
+  nackConsolidation( context: AgentRealtimeContext, offerId: string, nackReason?: string ){
+    if( !this.agentId ) throw new Error('Not connected')
+    this.nsp?.emit('CONSOLIDATION_NACK', { context, offerId, agentId: this.agentId, nackReason } )
+    return this
+  }
+
+  /**
+   * Stream the rider's position into the proactive consolidation engine —
+   * feeds trajectory tracking (ARRIVED / DIVERGING / STATIONARY) for
+   * committed handoffs. Distinct from order-room sendLocation().
+   */
+  positionUpdate( context: AgentRealtimeContext, location: RTLocation, status?: string ){
+    if( !this.agentId ) throw new Error('Not connected')
+    this.nsp?.emit('CONSOLIDATION_POSITION', { context, agentId: this.agentId, location, status } )
+    return this
+  }
+}

package/src/allend/Agent/rides.ts

@@ -0,0 +1,73 @@
+import type {
+	AgentRideListValidation,
+	AgentRideGetValidation,
+	AgentRideAcceptValidation,
+	AgentRideStartValidation,
+	AgentRideCompleteValidation,
+	AgentRideCancelValidation
+} from '@de./types'
+import { qs, type Http, type Res } from '../../utils'
+
+// ─── Agent Ride Orders ────────────────────────────────────────────────────────
+
+export default class AgentRides {
+	constructor( private http: Http ){}
+
+	async list( querystring?: AgentRideListValidation['querystring'] ): Promise<AgentRideListValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentRideListValidation['response']>>({
+			url: `/agent/ride/orders${qs( querystring )}`,
+			method: 'GET'
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async get( reference: string ): Promise<AgentRideGetValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentRideGetValidation['response']>>({
+			url: `/agent/ride/orders/${reference}`,
+			method: 'GET'
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async accept( reference: string, body: AgentRideAcceptValidation['body'] ): Promise<AgentRideAcceptValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentRideAcceptValidation['response']>>({
+			url: `/agent/ride/orders/${reference}/accept`,
+			method: 'POST',
+			body
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async start( reference: string, body: AgentRideStartValidation['body'] ): Promise<AgentRideStartValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentRideStartValidation['response']>>({
+			url: `/agent/ride/orders/${reference}/start`,
+			method: 'POST',
+			body
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async complete( reference: string, body: AgentRideCompleteValidation['body'] ): Promise<AgentRideCompleteValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentRideCompleteValidation['response']>>({
+			url: `/agent/ride/orders/${reference}/complete`,
+			method: 'POST',
+			body
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async cancel( reference: string, body: AgentRideCancelValidation['body'] ): Promise<AgentRideCancelValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentRideCancelValidation['response']>>({
+			url: `/agent/ride/orders/${reference}/cancel`,
+			method: 'POST',
+			body
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+}

package/src/allend/Agent/shipping.ts

@@ -0,0 +1,61 @@
+import type {
+	AgentShippingListValidation,
+	AgentShippingGetValidation,
+	AgentShippingAcceptValidation,
+	AgentShippingUpdateStatusValidation,
+	AgentShippingReportIssueValidation
+} from '@de./types'
+import { qs, type Http, type Res } from '../../utils'
+
+// ─── Agent Shipping Orders ────────────────────────────────────────────────────
+
+export default class AgentShipping {
+	constructor( private http: Http ){}
+
+	async list( querystring?: AgentShippingListValidation['querystring'] ): Promise<AgentShippingListValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentShippingListValidation['response']>>({
+			url: `/agent/shipping/orders${qs( querystring )}`,
+			method: 'GET'
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async get( reference: string ): Promise<AgentShippingGetValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentShippingGetValidation['response']>>({
+			url: `/agent/shipping/orders/${reference}`,
+			method: 'GET'
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async accept( reference: string ): Promise<AgentShippingAcceptValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentShippingAcceptValidation['response']>>({
+			url: `/agent/shipping/orders/${reference}/accept`,
+			method: 'POST'
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async updateStatus( reference: string, body: AgentShippingUpdateStatusValidation['body'] ): Promise<AgentShippingUpdateStatusValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentShippingUpdateStatusValidation['response']>>({
+			url: `/agent/shipping/orders/${reference}/status`,
+			method: 'PATCH',
+			body
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+
+	async reportIssue( reference: string, body: AgentShippingReportIssueValidation['body'] ): Promise<AgentShippingReportIssueValidation['response']> {
+		const { error, message, data } = await this.http.request<Res<AgentShippingReportIssueValidation['response']>>({
+			url: `/agent/shipping/orders/${reference}/issue`,
+			method: 'POST',
+			body
+		})
+		if( error ) throw new Error( message )
+		return data
+	}
+}

package/src/backend/Auth.ts

@@ -6,7 +6,9 @@ const ACCESS_TOKEN_EXPIRY = 3.75 // in 3 minutes 45 seconds
 type AuthResponse = {
   error: boolean
   message: string
-  token: string
+  data: {
+    token: string
+  }
 }
 
 export default class Auth {
@@ -103,13 +105,13 @@ export default class Auth {
       method: 'POST',
       body: this.creds
     },
-    { error, message, token } = await this.request<AuthResponse>( options )
+    { error, message, data } = await this.request<AuthResponse>( options )
     if( error ) throw new Error( message )
 
-    this.accessToken = token
+    this.accessToken = data.token
     this.scheduleRotation() // Schedule auto-refresh
     
-    return token
+    return data.token
   }
 
   async rotateToken(): Promise<string> {
@@ -131,21 +133,21 @@ export default class Auth {
         method: 'PATCH',
         body: { secret: this.creds.secret }
       },
-      { error, message, token } = await this.request<AuthResponse>( options )
+      { error, message, data } = await this.request<AuthResponse>( options )
       if( error ) throw new Error( message )
 
-      this.accessToken = token
+      this.accessToken = data.token
 
       // Notify callback listener
       if( typeof this.onNewToken === 'function' )
-        try { this.onNewToken( token ) }
+        try { this.onNewToken( data.token ) }
         catch( callbackError ){ this.error('[Auth] Error in onNewToken callback:', callbackError) }
 
       // Schedule next rotation
       this.scheduleRotation()
       
       this.debug('Token rotated successfully')
-      return token
+      return data.token
     }
     catch( error: any ){
       this.debug('Refresh access token failed:', error.message)

package/src/index.ts

@@ -1,6 +1,8 @@
 import Utils from './utils'
 import MSI, { type MSIInterface, type MSIProps, type MSIRef } from './allend/MSI'
 import IoTClient, { type IoTClientOptions } from './allend/IoTClient'
+import Agent, { type AgentConfig } from './allend/Agent'
+import { type AgentRealtimeContext } from './allend/Agent/realtime'
 import Order from './allend/DClient/Order'
 import Event from './allend/DClient/Event'
 import Client from './allend/DClient/Client'
@@ -14,8 +16,14 @@ export {
   type MSIInterface,
   type MSIProps,
   type MSIRef,
+  Agent,
+  type AgentConfig,
+  type AgentRealtimeContext,
   Utils,
   DClient,
   IoTClient,
   type IoTClientOptions
-}
+}
+
+// Shared contract types — same source of truth as de.arch and @de./sdk
+export type { RallyEvent, RallyEventType, OrderTrackingEvent } from '@de./types'

package/src/utils/index.ts

@@ -1,4 +1,23 @@
 
+import type { HTTPRequestOptions } from '../types'
+
 import Stream from './stream'
 
-export default { Stream }
+// ─── Requests types ───────────────────────────────────────────────────────────
+
+export type Http = { request<T>( opts: HTTPRequestOptions ): Promise<T> }
+export type Res<T = any> = { error: boolean, status?: string, message?: string, data: T }
+
+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}` : ''
+}
+
+export default { Stream }