@de./sdk 2.1.0 → 2.2.0

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/allend/Realtime/index.ts

@@ -1,50 +1,99 @@
-import type { RTLocation , Message, Peer } from '../../types'
-import type { SocketAuthCredentials } from '../../types/auth'
-import type { AccessOptions } from '../../types/access'
+import type { OrderTrackingEvent } from '@de./types'
+import type { RTLocation, Message, Peer } from '../../types'
 
-import io, { Socket } from 'socket.io-client'
-import AccessManager from '../Access'
-import { baseURL } from '../../baseUrl'
+import RealtimeSocket, { type RealtimeConnectOptions } from '../realtime-socket'
 
-export default class Realtime extends AccessManager {
-  private nsp?: Socket
-  private iosHost: string
+// ─── Realtime ─────────────────────────────────────────────────────────────────
+//
+// The non-agent side of an order room: the person waiting for the delivery,
+// the merchant who dispatched it, or a platform's own client connection.
+//
+// The flow is two steps and they are not interchangeable:
+//
+//   connect( id, utype )   opens the socket. `id` is the uid the tracking
+//                          session was minted for, and `utype` must match the
+//                          `role` it was minted with.
+//   join( jrtoken )        enters the order's room.
+//
+// De. checks the second against the first — the JRT's seal is `role:uid`, and
+// JOIN compares it to the connection's own `utype:id`. Connecting as one
+// person and presenting another's token is refused, and so is connecting as
+// 'client' with a token minted for role 'customer', which is what this client
+// used to do unconditionally.
+//
+// Distinct from `AgentRealtime` (allend/Agent/realtime), which is the rider's
+// socket and carries the consolidation response channel as well.
+//
+// ─────────────────────────────────────────────────────────────────────────────
 
-  constructor( access: AccessOptions ){
-    super( access, 'API' )
-    // Socket server host
-    // An explicit origin governs the socket as it governs the requests.
-    this.iosHost = access.baseUrl?.replace( /\/+$/, '' )
-                    || baseURL('RTS', access.env, access.devHostname )
+/**
+ * Who this connection is, in De.'s vocabulary.
+ *
+ * A client is the party that engaged the provider — a CSP, a merchant, a
+ * branch. A customer is the person the delivery is handed to. They are not
+ * the same party and De. does not put them in the same room, so a customer
+ * app connecting as 'client' hears nothing addressed to customers and cannot
+ * redeem a customer's tracking token.
+ */
+export type RealtimeUserType = 'client' | 'customer' | 'vendor'
+
+export default class Realtime extends RealtimeSocket {
+  private as: RealtimeUserType = 'client'
+
+  protected get utype(): string { return this.as }
+
+  /**
+   * @param id       The uid the tracking session was issued for.
+   * @param utype    Must equal the `role` that session was issued with.
+   * @param options  `getToken` supplies a fresh access token per attempt —
+   *                 without it a reconnect after the token's short life is
+   *                 refused, and the app is left with an open socket that
+   *                 delivers nothing.
+   */
+  connect( id: string, utype: RealtimeUserType = 'client', options?: RealtimeConnectOptions ): Promise<void> {
+    this.as = utype
+    return this.open( id, options )
   }
 
-  connect( clientId: string ): Promise<void> {
-    return new Promise( ( resolve, reject ) => {
-      // Connect to main clients namespace
-      const auth: SocketAuthCredentials = {
-        utype: 'client',
-        id: clientId,
-        remoteOrigin: globalThis?.window ? globalThis.origin : this.remoteOrigin as string,
-        accessToken: this.accessToken as string
-      }
-      
-      this.nsp = io( this.iosHost, { auth } )
-      this.nsp.on('connect', resolve )
-      this.nsp.on('connect_error', reject )
-    } )
+  // ── Order room streams (after join) ─────────────────────────────────────
+
+  /**
+   * The rider's position, as it moves.
+   *
+   * Rate-limited by De. to 10 per second per sender, so this is a stream and
+   * not a trickle: render from it directly rather than re-fetching anything.
+   */
+  onLocation( fn: ( location: RTLocation ) => void ){
+    this.nsp?.on('LOCATION-CHANGE', fn )
+    return this
   }
-  disconnect(){
-    this.nsp?.disconnect()
-    return true
+
+  onRoute( fn: ( route: any ) => void ){
+    this.nsp?.on('ROUTE-CHANGE', fn )
+    return this
   }
-  join( jrtoken: string ): Promise<boolean> {
-    return new Promise( ( resolve, reject ) => {
-      this.nsp?.emit('JOIN', jrtoken, ( errmess?: string ) => {
-        errmess ? reject( new Error( errmess ) ) : resolve( true )
-      } )
-    } )
+
+  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
+  }
+
+  sendMessage( message: Message ){
+    this.nsp?.emit('MESSAGE', message )
+    return this
+  }
+
+  // ── Presence ────────────────────────────────────────────────────────────
+
+  onJoined( fn: ( peer: Peer ) => void ){
+    this.nsp?.on('JOINED', fn )
+    return this
+  }
   onLeft( fn: ( peer: Peer ) => void ){
     this.nsp?.on('LEFT', fn )
     return this
@@ -57,21 +106,4 @@ export default class Realtime extends AccessManager {
     this.nsp?.on('DISCONNECTED', fn )
     return this
   }
-
-  // onRoute( fn: ( data: any ) => void ){
-  //   this.nsp?.on('ROUTE-CHANGE', fn )
-  //   return this
-  // }
-  // onStage( fn: ( data: OrderStage ) => void ){
-  //   this.nsp?.on('STAGE-CHANGE', fn )
-  //   return this
-  // }
-  // onLocation( fn: ( location: RTLocation  ) => void ){
-  //   this.nsp?.on('LOCATION-CHANGE', fn )
-  //   return this
-  // }
-  // onMessage( fn: ( payload: Message ) => void ){
-  //   this.nsp?.on('MESSAGE', fn )
-  //   return this
-  // }
-}
+}

package/src/allend/realtime-socket.ts

@@ -0,0 +1,171 @@
+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'
+
+// ─── RealtimeSocket ───────────────────────────────────────────────────────────
+//
+// What `Realtime` and `AgentRealtime` share: opening the connection, and
+// getting back into the rooms afterwards.
+//
+// Both used to hand socket.io a plain object for `auth` and call `join` once,
+// which works exactly until the first reconnect — and on a phone the first
+// reconnect is a lift doorway. Two things break there, both silently:
+//
+//   · The token. socket.io captures the auth literal once and replays it on
+//     every attempt. De.'s access tokens are short-lived, so the replayed one
+//     is stale precisely on the reconnect after an outage long enough to have
+//     crossed an expiry. De. refuses the handshake — and until 2026-09-08 that
+//     refusal took de.arch's whole process down with it.
+//
+//   · The rooms. Room membership is per-connection and De. does not restore
+//     it. A reconnected socket is connected to the server and in none of the
+//     rooms it was in, so it stays open, reports itself healthy, and delivers
+//     nothing. That is the worse of the two failures because nothing anywhere
+//     reports it.
+//
+// So `auth` is a function, evaluated per attempt, and every join is remembered
+// and replayed.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type RealtimeConnectOptions = {
+  /**
+   * A fresh access token for each connection attempt.
+   *
+   * An app holds tokens it was given rather than credentials it can mint, so
+   * this is usually "ask my backend for a new tracking session". Omitted, the
+   * token this client was constructed with is used on every attempt, which is
+   * correct only for a process that rotates it in place.
+   */
+  getToken?: () => string | Promise<string>
+}
+
+export default abstract class RealtimeSocket extends AccessManager {
+  protected nsp?: Socket
+  protected iosHost: string
+  protected id?: string
+
+  /**
+   * Every room this socket asked to be in, by the token that got it there.
+   *
+   * Kept so a reconnect can restore them. A JRT outlives an ordinary blip, so
+   * replaying it is right; when one has expired the rejoin fails and
+   * `onRejoinError` is how the app learns to ask for a new session rather than
+   * sitting on a silent connection.
+   */
+  private rooms = new Set<string>()
+  private rejoinError?: ( error: Error ) => void
+
+  constructor( access: AccessOptions ){
+    super( access, 'API' )
+
+    // Socket.io is served by the same de.arch API server, so an explicit
+    // origin governs the socket exactly as it governs the requests.
+    this.iosHost = access.baseUrl?.replace( /\/+$/, '' )
+                    || baseURL('API', access.env || 'dev', access.devHostname )
+  }
+
+  /** The `utype` this client connects as. Must match the JRT's `role`. */
+  protected abstract get utype(): string
+
+  protected open( id: string, options: RealtimeConnectOptions = {} ): Promise<void> {
+    this.id = id
+
+    return new Promise( ( resolve, reject ) => {
+      const credentials = async (): Promise<SocketAuthCredentials> => ({
+        utype:        this.utype,
+        id,
+        remoteOrigin: globalThis?.window ? globalThis.origin : this.remoteOrigin as string,
+        accessToken:  options.getToken ? await options.getToken() : this.accessToken as string
+      })
+
+      this.nsp = io( this.iosHost, {
+        // The function form — re-evaluated before every attempt, which is the
+        // whole point. The object form is read once, at construction.
+        auth: ( cb: ( data: any ) => void ) => {
+          credentials()
+            .then( cb )
+            // A token the app could not fetch is still an attempt: let De.
+            // refuse it and surface a connect_error, rather than hanging.
+            .catch( () => cb({ utype: this.utype, id }) )
+        }
+      })
+
+      this.nsp.on('connect', () => {
+        this.restore()
+        resolve()
+      })
+      this.nsp.on('connect_error', reject )
+    })
+  }
+
+  /** Re-enter every room this socket was in before the connection dropped. */
+  private restore(): void {
+    for( const jrtoken of this.rooms )
+      this.nsp?.emit('JOIN', jrtoken, ( errmess?: string ) => {
+        if( !errmess ) return
+
+        this.rooms.delete( jrtoken )
+        this.rejoinError?.( new Error( errmess ) )
+      })
+  }
+
+  /**
+   * Enter an order room with a Join Room Token from
+   * `GET /v1/tracking/:reference?role=…`.
+   */
+  join( jrtoken: string ): Promise<boolean> {
+    return new Promise( ( resolve, reject ) => {
+      this.nsp?.emit('JOIN', jrtoken, ( errmess?: string ) => {
+        if( errmess ) return reject( new Error( errmess ) )
+
+        this.rooms.add( jrtoken )
+        resolve( true )
+      })
+    })
+  }
+
+  /** Stop replaying a room — the order is closed, or the app navigated away. */
+  leave( jrtoken: string ): void {
+    this.rooms.delete( jrtoken )
+  }
+
+  /**
+   * A room could not be re-entered after a reconnect.
+   *
+   * Almost always an expired JRT. The app's answer is to ask its backend for a
+   * fresh tracking session and `join` again — and, since it is reconnecting,
+   * to `replay` from the `since` that came with it.
+   */
+  onRejoinError( fn: ( error: Error ) => void ){
+    this.rejoinError = fn
+    return this
+  }
+
+  /** Fires on every reconnect, which is where a client should replay its gap. */
+  onReconnect( fn: () => void ){
+    this.nsp?.io.on('reconnect', fn )
+    return this
+  }
+
+  disconnect(){
+    this.rooms.clear()
+    this.nsp?.disconnect()
+    return true
+  }
+
+  /**
+   * Ask for everything a room emitted while this socket was away.
+   *
+   * `since` is the timestamp the tracking session came back with, or that of
+   * the last event actually seen. Reconnecting without it leaves a hole
+   * exactly as long as the outage.
+   */
+  replay( reference: string, since: number ){
+    this.nsp?.emit('REPLAY', { room: `order:${reference}`, since })
+    return this
+  }
+}

package/src/backend/Auth.ts

@@ -1,7 +1,18 @@
 import { baseURL } from '../baseUrl'
 import type { AuthRequestOptions } from '../types/auth'
 
-const ACCESS_TOKEN_EXPIRY = 3.75 // in 3 minutes 45 seconds
+/**
+ * When to rotate, in minutes.
+ *
+ * De.'s own default token life is four minutes, so this beats it by fifteen
+ * seconds. It is a default and not a constant because the server's life is
+ * configurable — `API_ACCESS_TOKEN_EXPIRY` — and these two numbers are
+ * otherwise free to drift apart in the direction that breaks: a deployment
+ * that shortens the token to two minutes leaves every client rotating a
+ * credential that expired ninety seconds ago, and every call in between is
+ * answered 401 with nothing to say why.
+ */
+const ACCESS_TOKEN_EXPIRY = 3.75
 
 // ─── Config ───────────────────────────────────────────────────────────────────
 //
@@ -27,7 +38,20 @@ export type AuthConfig = {
 	 * credentials are. Omit it for pure machine-to-machine access.
 	 */
 	uid?: string
+	/**
+	 * Rotate the token ahead of expiry.
+	 *
+	 * Off by default, which is the trap: a long-lived process that forgets it
+	 * works perfectly until the first expiry and then fails every call until
+	 * it is restarted. Anything holding a token for longer than one request
+	 * wants this on.
+	 */
 	autorefresh?: boolean
+	/**
+	 * Minutes between rotations. Defaults to 3.75 — set it below the De.
+	 * deployment's `API_ACCESS_TOKEN_EXPIRY` when that is not the default 4.
+	 */
+	rotateAfterMins?: number
 	onNewToken?: ( token: string ) => void
 	/** Host to substitute for `localhost` in `dev` (Eg. a native emulator) */
 	devHostname?: string
@@ -51,6 +75,7 @@ export default class Auth {
   private remoteOrigin?: string
   private refreshTimer?: NodeJS.Timeout
   private autorefresh?: boolean
+  private rotateAfterMins: number
   private onNewToken?: (token: string) => void
   private baseURL: string
   private isRotating: boolean = false
@@ -71,6 +96,9 @@ export default class Auth {
     this.version      = config.version || 1
     this.baseURL      = baseURL('API', this.env, config.devHostname )
     this.autorefresh  = config.autorefresh || false
+    this.rotateAfterMins = config.rotateAfterMins && config.rotateAfterMins > 0
+                              ? config.rotateAfterMins
+                              : ACCESS_TOKEN_EXPIRY
     this.onNewToken   = config.onNewToken
   }
 
@@ -114,7 +142,7 @@ export default class Auth {
     if( !this.autorefresh ) return
 
     this.clearRotation()
-    this.refreshTimer = setTimeout( () => this.rotateToken(), ACCESS_TOKEN_EXPIRY * 60 * 1000 )
+    this.refreshTimer = setTimeout( () => this.rotateToken(), this.rotateAfterMins * 60 * 1000 )
   }
 
   /**

package/src/core.ts

@@ -22,6 +22,10 @@
 export { default as Auth } from './backend/Auth'
 export type { AuthConfig } from './backend/Auth'
 
+// Order-room sockets — shared connect/rejoin behaviour
+export type { RealtimeConnectOptions } from './allend/realtime-socket'
+export type { RealtimeUserType } from './allend/Realtime'
+
 // Client-side OTP auth (de.auth service)
 export { default as OTPAuth } from './allend/OTPAuth'
 

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 }