@de./sdk 1.0.5 → 2.1.0

package/src/allend/Access.ts

@@ -1,35 +1,77 @@
-import type { AccessOptions } from '../types/access'
+import type { AccessOptions, UserSession } from '../types/access'
 import type { HTTPRequestOptions } from '../types'
-import { API_SERVER_BASEURL, ASI_SERVER_BASEURL } from '../baseUrl'
+import { baseURL } from '../baseUrl'
+import APIError from '../error'
+import { rememberStatus } from '../response'
 
-type AccessType = 'API' | 'ASI'
+/**
+ * Which service the client addresses.
+ *
+ * De. is more than one server: de.arch answers the API, de.auth the ASI, and
+ * de.workspace the control plane. They are separate hosts, so the client has
+ * to say which one it means rather than assume the API.
+ */
+type AccessType = 'API' | 'ASI' | 'WSP'
 
 const USER_ACCOUNT_SERVICE = 'De.API'
 
+/**
+ * Resolve a fetch implementation for the host runtime.
+ *
+ * Node 18+, every browser and React Native all expose a global `fetch`, so that
+ * is the first and usual answer. `node-fetch` remains only as a fallback for
+ * Node versions predating the global.
+ *
+ * The previous check tested `globalThis.window && globalThis.fetch`, which was
+ * wrong for React Native: there is no `window` there but `fetch` is global, so
+ * it fell through to importing node-fetch and broke. Testing for `fetch`
+ * directly is what lets one Access layer serve node, browser and native.
+ */
+async function resolveFetch(): Promise<typeof globalThis.fetch> {
+  if( typeof globalThis?.fetch === 'function' )
+    return globalThis.fetch
+
+  return ( await import('node-fetch') ).default as any
+}
+
 export default class AccessManager {
   private atype: AccessType
   private version: number
   private platform: AccessOptions['platform']
   private baseURL: string
+  /**
+   * The client's own `wid:TYPE:xcode`, base64-encoded.
+   *
+   * Not a transport header: de.arch resolves the workspace from the access
+   * token, and its header contract has no context field. It is kept because a
+   * client is scoped to one context for its lifetime, and a caller holding
+   * several — a proxy serving many workspaces — needs to ask which is which.
+   * `scope` decodes it.
+   */
+  readonly context: string
   protected accessToken?: string
   protected remoteOrigin?: string
+  protected session?: UserSession
+  private timeout?: number
 
   constructor( options: AccessOptions, atype: AccessType ){
     if( !options ) throw new Error('Undefined Access Configuration')
     if( !options.context ) throw new Error('Undefined Context Reference. Check https://doc.dedot.io/sdk/auth')
     if( !options.accessToken ) throw new Error('Undefined Access Token. Check https://doc.dedot.io/sdk/auth')
     
+    this.context = options.context
     this.atype = atype
     this.version = options.version || 1
     this.platform = options.platform || 'proxy'
     this.accessToken = options.accessToken
     this.remoteOrigin = options.remoteOrigin
-    this.baseURL = this.atype === 'ASI'
-              ? ASI_SERVER_BASEURL[ options.env || 'dev' ] 
-              : API_SERVER_BASEURL[ options.env || 'dev' ]
+    this.session = options.session
+    this.timeout = options.timeout
+    this.baseURL = options.baseUrl?.replace( /\/+$/, '' )
+                    || baseURL( this.atype, options.env || 'dev', options.devHostname )
   }
 
-  async request<Response>({ url, ...options }: HTTPRequestOptions ): Promise<Response> {
+  async request<Response>({ url, timeout, ...options }: HTTPRequestOptions ): Promise<Response> {
     const rawOptions: any = {
       method: 'GET',
       headers: {
@@ -49,6 +91,17 @@ export default class AccessManager {
     if( this.accessToken )
       rawOptions.headers.authorization = `Bearer ${this.accessToken}`
 
+    /**
+     * User-session credentials, sent alongside the bearer token rather than
+     * instead of it. `isConnected` (AUX agent routes) reads only this pair;
+     * `isAuthorized` reads only the bearer. Routes guarded by either one are
+     * then reachable from a single client.
+     */
+    if( this.session ){
+      rawOptions.headers['de-auth-token'] = this.session.token
+      rawOptions.headers['de-auth-device'] = this.session.device
+    }
+
     if( options.body ){
       rawOptions.headers['content-type'] = 'application/json'
       if( typeof options.body === 'object' )
@@ -63,16 +116,96 @@ export default class AccessManager {
 
     options = { ...rawOptions, ...options }
 
+    /**
+     * Bound the request when a deadline is configured.
+     *
+     * `AbortSignal.timeout` is not in the pre-18 Node the node-fetch fallback
+     * exists for, so this is guarded rather than assumed. A missing signal
+     * leaves the previous unbounded behaviour, which is the right degradation:
+     * the request still goes out.
+     */
+    const deadline = timeout ?? this.timeout
+    if( deadline && typeof AbortSignal?.timeout === 'function' )
+      ( options as any ).signal = AbortSignal.timeout( deadline )
+
     url = `${this.baseURL}/v${this.version}/${url.replace(/^\//, '')}`
 
-    // Support fetch for in both node & browser environment
-    let fetch = globalThis?.window && globalThis?.fetch
-    if( !fetch )
-      fetch = ( await import('node-fetch') ).default as any
+    const fetch = await resolveFetch(),
+          response = await fetch( url, options as any )
+
+    /**
+     * Everything De. answers is the `{ error, message, data }` envelope, so a
+     * body that will not parse did not come from De. — a gateway 502 page, a
+     * proxy timeout, an empty 204. Reporting that as a JSON syntax error hides
+     * the only two facts worth having, which are the status and the URL.
+     */
+    let body: any
+    try { body = await response.json() }
+    catch {
+      /**
+       * Not De. answering — a gateway's HTML 502, a proxy timeout, an empty
+       * 204. There is no envelope to hand back, so this is the one case that
+       * raises, carrying the status and URL rather than a JSON syntax error.
+       */
+      throw new APIError(`${options.method} ${url} — ${response.statusText || 'no JSON body'}`, response.status )
+    }
+
+    /**
+     * A refusal is returned, not raised.
+     *
+     * De.'s answer is the `{ error, status, message, data }` envelope whether
+     * it succeeded or not, and `status` names the refusal precisely —
+     * SENDER_CAP_REACHED, CONSOLIDATION::NOT_IN_PROGRESS. Throwing that away
+     * and reconstructing it from an exception message is what callers were
+     * reduced to; handing back the envelope lets them read it.
+     *
+     * A non-2xx carrying an envelope is still De. answering, so it comes back
+     * the same way.
+     *
+     * What is NOT De. answering is raised. A wrong path gets Fastify's own
+     * 404 body, which is JSON but not the envelope — `error` there is the
+     * string 'Not Found', not a boolean. Returning that as though it were a
+     * refusal is how a client addressing a route that does not exist would
+     * look like a workspace being told no, which is precisely the bug that
+     * hid `/LSP/invitation/agent` behind a plausible-looking failure.
+     */
+    rememberStatus( body, response.status )
 
-    // console.log( options )
-    return await ( await fetch( url, options ) ).json() as Response
+    if( typeof body?.error !== 'boolean' )
+      throw new APIError(
+        body?.message || `${options.method} ${url} — ${response.status} ${response.statusText || 'not a De. response'}`,
+        response.status,
+        body
+      )
+
+    return body as Response
+  }
+
+  /**
+   * The context decoded into its parts.
+   *
+   * Every consumer was decoding the base64 and splitting on ':' by hand,
+   * including validating that it produced three fields. Returns undefined
+   * rather than throwing when the string is not a context, since a caller
+   * asking is usually checking.
+   */
+  get scope(): { wid: string, type: string, xcode: string } | undefined {
+    try {
+      const decoded = typeof atob === 'function'
+                        ? atob( this.context )
+                        : Buffer.from( this.context, 'base64' ).toString('utf8'),
+            [ wid, type, xcode ] = decoded.split(':')
+
+      return wid && type && xcode ? { wid, type, xcode } : undefined
+    }
+    catch { return undefined }
   }
 
   setToken( token: string ): void { this.accessToken = token }
+
+  /** Attach or replace the signed-in user after construction. */
+  setSession( session: UserSession ): void { this.session = session }
+
+  /** Drop the user session — e.g. on sign-out. */
+  clearSession(): void { this.session = undefined }
 }

package/src/allend/Agent/consolidation.ts

@@ -1,8 +1,9 @@
 import type {
 	AgentConsolidationRespondValidation,
-	AgentConsolidationHandoffValidation
+	AgentConsolidationHandoffValidation,
+	AgentConsolidationCompleteValidation
 } from '@de./types'
-import { type Http, type Res } from '../../utils'
+import { type Http, type Res, type Data } from '../../utils'
 
 // ─── Agent Consolidation ──────────────────────────────────────────────────────
 
@@ -10,22 +11,33 @@ export default class AgentConsolidation {
 	constructor( private http: Http ){}
 
 	async respond( body: AgentConsolidationRespondValidation['body'] ): Promise<AgentConsolidationRespondValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentConsolidationRespondValidation['response']>>({
+		return await this.http.request<AgentConsolidationRespondValidation['response']>({
 			url: '/agent/consolidation/respond',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async handoffConfirm( body: AgentConsolidationHandoffValidation['body'] ): Promise<AgentConsolidationHandoffValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentConsolidationHandoffValidation['response']>>({
+		return await this.http.request<AgentConsolidationHandoffValidation['response']>({
 			url: '/agent/consolidation/handoff/confirm',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
+	}
+
+	/**
+	 * The receiving rider reporting leg 2 delivered.
+	 *
+	 * No handoff code — the PIN authenticated the transfer between riders at
+	 * confirm. This is what takes the offer out of IN_PROGRESS and returns the
+	 * rider to their zone pool.
+	 */
+	async handoffComplete( body: AgentConsolidationCompleteValidation['body'] ): Promise<AgentConsolidationCompleteValidation['response']> {
+		return await this.http.request<AgentConsolidationCompleteValidation['response']>({
+			url: '/agent/consolidation/handoff/complete',
+			method: 'POST',
+			body
+		})
 	}
 }

package/src/allend/Agent/delivery.ts

@@ -5,7 +5,7 @@ import type {
 	AgentDeliveryUpdateStatusValidation,
 	AgentDeliveryReportIssueValidation
 } from '@de./types'
-import { qs, type Http, type Res } from '../../utils'
+import { qs, type Http, type Res, type Data } from '../../utils'
 
 // ─── Agent Delivery Orders ────────────────────────────────────────────────────
 
@@ -13,49 +13,39 @@ export default class AgentDelivery {
 	constructor( private http: Http ){}
 
 	async list( querystring?: AgentDeliveryListValidation['querystring'] ): Promise<AgentDeliveryListValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentDeliveryListValidation['response']>>({
+		return await this.http.request<AgentDeliveryListValidation['response']>({
 			url: `/agent/delivery/orders${qs( querystring )}`,
 			method: 'GET'
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async get( reference: string ): Promise<AgentDeliveryGetValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentDeliveryGetValidation['response']>>({
+		return await this.http.request<AgentDeliveryGetValidation['response']>({
 			url: `/agent/delivery/orders/${reference}`,
 			method: 'GET'
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async accept( reference: string ): Promise<AgentDeliveryAcceptValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentDeliveryAcceptValidation['response']>>({
+		return await this.http.request<AgentDeliveryAcceptValidation['response']>({
 			url: `/agent/delivery/orders/${reference}/accept`,
 			method: 'POST'
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async updateStatus( reference: string, body: AgentDeliveryUpdateStatusValidation['body'] ): Promise<AgentDeliveryUpdateStatusValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentDeliveryUpdateStatusValidation['response']>>({
+		return await this.http.request<AgentDeliveryUpdateStatusValidation['response']>({
 			url: `/agent/delivery/orders/${reference}/status`,
 			method: 'PATCH',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async reportIssue( reference: string, body: AgentDeliveryReportIssueValidation['body'] ): Promise<AgentDeliveryReportIssueValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentDeliveryReportIssueValidation['response']>>({
+		return await this.http.request<AgentDeliveryReportIssueValidation['response']>({
 			url: `/agent/delivery/orders/${reference}/issue`,
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 }

package/src/allend/Agent/dispatch.ts

@@ -2,7 +2,7 @@ import type {
 	AgentDispatchRespondValidation,
 	AgentDispatchRateValidation
 } from '@de./types'
-import { type Http, type Res } from '../../utils'
+import { type Http, type Res, type Data } from '../../utils'
 
 // ─── Agent Dispatch ───────────────────────────────────────────────────────────
 
@@ -10,22 +10,18 @@ export default class AgentDispatch {
 	constructor( private http: Http ){}
 
 	async respond( body: AgentDispatchRespondValidation['body'] ): Promise<AgentDispatchRespondValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentDispatchRespondValidation['response']>>({
+		return await this.http.request<AgentDispatchRespondValidation['response']>({
 			url: '/agent/dispatch/respond',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async rate( body: AgentDispatchRateValidation['body'] ): Promise<AgentDispatchRateValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentDispatchRateValidation['response']>>({
+		return await this.http.request<AgentDispatchRateValidation['response']>({
 			url: '/agent/dispatch/rate',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 }

package/src/allend/Agent/index.ts

@@ -1,11 +1,11 @@
-import type { AccessOptions } from '../../types/access'
+import type { AccessOptions, UserSession } from '../../types/access'
 import type {
 	AgentInfoValidation,
 	AgentAvailabilityValidation,
 	AgentUpdateValidation
 } from '@de./types'
 import AccessManager from '../Access'
-import { type Res } from '../../utils'
+import { type Res, type Data } from '../../utils'
 import AgentRides from './rides'
 import AgentDelivery from './delivery'
 import AgentShipping from './shipping'
@@ -14,6 +14,7 @@ import AgentConsolidation from './consolidation'
 import AgentReallocation from './reallocation'
 import AgentDispatch from './dispatch'
 import AgentOrigin from './origin'
+import AgentRealtime from './realtime'
 
 export type AgentConfig = {
 	context: string
@@ -21,13 +22,29 @@ export type AgentConfig = {
 	env?: 'dev' | 'staging' | 'prod'
 	platform?: 'web' | 'mobile' | 'server' | 'proxy'
 	remoteOrigin?: string
+	/** Per-request deadline in ms. See `AccessOptions.timeout`. */
+	timeout?: number
+	/** Explicit service origin, overriding the env table. See `AccessOptions.baseUrl`. */
+	baseUrl?: string
+	/** Host to substitute for `localhost` in `dev` (Eg. a native emulator) */
+	devHostname?: string
+	/**
+	 * The signed-in rider.
+	 *
+	 * Required in practice: AUX agent routes authenticate the caller with
+	 * `isConnected` + `isAgent`, which read `de-auth-token` / `de-auth-device`
+	 * and ignore the bearer token entirely. Without this, every call here
+	 * fails authorization no matter how valid the access token is.
+	 */
+	session?: UserSession
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 //
 // Agent: Agent Operation Interfaces — de.arch AUX/agent routes.
 // Covers profile, availability, orders (ride/delivery/shipping),
-// navigation, consolidation, reallocation, dispatch, and origin.
+// navigation, consolidation, reallocation, dispatch, and origin — plus the
+// realtime socket channel (order rooms + proactive-consolidation responses).
 //
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -40,6 +57,7 @@ export default class Agent extends AccessManager {
 	readonly reallocation:  AgentReallocation
 	readonly dispatch:      AgentDispatch
 	readonly origin:        AgentOrigin
+	readonly realtime:      AgentRealtime
 
 	constructor( config: AgentConfig ){
 		if( !config.context )     throw new Error('Undefined context. See https://doc.dedot.io/sdk/aux')
@@ -50,7 +68,11 @@ export default class Agent extends AccessManager {
 			accessToken:  config.accessToken,
 			env:          config.env      || 'dev',
 			platform:     config.platform || 'proxy',
-			remoteOrigin: config.remoteOrigin
+			remoteOrigin: config.remoteOrigin,
+			timeout:      config.timeout,
+			baseUrl:      config.baseUrl,
+			devHostname:  config.devHostname,
+			session:      config.session
 		}
 		super( access, 'API' )
 
@@ -62,35 +84,30 @@ export default class Agent extends AccessManager {
 		this.reallocation  = new AgentReallocation( this )
 		this.dispatch      = new AgentDispatch( this )
 		this.origin        = new AgentOrigin( this )
+		this.realtime      = new AgentRealtime( access )
 	}
 
 	// ── Agent profile ─────────────────────────────────────────────────────────
 
 	async info(): Promise<AgentInfoValidation['response']> {
-		const { error, message, data } = await this.request<Res<AgentInfoValidation['response']>>({
+		return await this.request<AgentInfoValidation['response']>({
 			url: '/agent',
 			method: 'GET'
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async update( body: AgentUpdateValidation['body'] ): Promise<AgentUpdateValidation['response']> {
-		const { error, message, data } = await this.request<Res<AgentUpdateValidation['response']>>({
+		return await this.request<AgentUpdateValidation['response']>({
 			url: '/agent',
 			method: 'PATCH',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async availability( status: AgentAvailabilityValidation['params']['availability'] ): Promise<AgentAvailabilityValidation['response']> {
-		const { error, message, data } = await this.request<Res<AgentAvailabilityValidation['response']>>({
+		return await this.request<AgentAvailabilityValidation['response']>({
 			url: `/agent/${status}`,
 			method: 'GET'
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 }

package/src/allend/Agent/navigation.ts

@@ -2,7 +2,7 @@ import type {
 	AgentLocationValidation,
 	AgentNearbyValidation
 } from '@de./types'
-import { qs, type Http, type Res } from '../../utils'
+import { qs, type Http, type Res, type Data } from '../../utils'
 
 // ─── Agent Navigation ─────────────────────────────────────────────────────────
 
@@ -10,22 +10,18 @@ export default class AgentNavigation {
 	constructor( private http: Http ){}
 
 	async location( body: AgentLocationValidation['body'] ): Promise<AgentLocationValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentLocationValidation['response']>>({
+		return await this.http.request<AgentLocationValidation['response']>({
 			url: '/agent/navigation/location',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async nearby( body: AgentNearbyValidation['body'], querystring?: AgentNearbyValidation['querystring'] ): Promise<AgentNearbyValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentNearbyValidation['response']>>({
+		return await this.http.request<AgentNearbyValidation['response']>({
 			url: `/agent/navigation/nearby${qs( querystring )}`,
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 }

package/src/allend/Agent/origin.ts

@@ -3,7 +3,7 @@ import type {
 	AgentRegisterPoiValidation,
 	AgentAddPoiNoteValidation
 } from '@de./types'
-import { type Http, type Res } from '../../utils'
+import { type Http, type Res, type Data } from '../../utils'
 
 // ─── Agent Origin ─────────────────────────────────────────────────────────────
 
@@ -11,32 +11,26 @@ export default class AgentOrigin {
 	constructor( private http: Http ){}
 
 	async statusReport( body: AgentOriginStatusReportValidation['body'] ): Promise<AgentOriginStatusReportValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentOriginStatusReportValidation['response']>>({
+		return await this.http.request<AgentOriginStatusReportValidation['response']>({
 			url: '/agent/origin/status',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async registerPoi( body: AgentRegisterPoiValidation['body'] ): Promise<AgentRegisterPoiValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentRegisterPoiValidation['response']>>({
+		return await this.http.request<AgentRegisterPoiValidation['response']>({
 			url: '/agent/origin/poi/register',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 
 	async addPoiNote( body: AgentAddPoiNoteValidation['body'] ): Promise<AgentAddPoiNoteValidation['response']> {
-		const { error, message, data } = await this.http.request<Res<AgentAddPoiNoteValidation['response']>>({
+		return await this.http.request<AgentAddPoiNoteValidation['response']>({
 			url: '/agent/origin/poi/note',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 }

package/src/allend/Agent/reallocation.ts

@@ -1,5 +1,5 @@
 import type { AgentReallocationRespondValidation } from '@de./types'
-import { type Http, type Res } from '../../utils'
+import { type Http, type Res, type Data } from '../../utils'
 
 // ─── Agent Reallocation ───────────────────────────────────────────────────────
 
@@ -7,12 +7,10 @@ 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']>>({
+		return await this.http.request<AgentReallocationRespondValidation['response']>({
 			url: '/agent/reallocation/respond',
 			method: 'POST',
 			body
 		})
-		if( error ) throw new Error( message )
-		return data
 	}
 }