@de./sdk 1.0.4 → 2.0.0

package/dist/utils/index.d.ts

@@ -1,4 +1,29 @@
+import type { HTTPRequestOptions } from '../types';
 import Stream from './stream';
+export type Http = {
+    request<T>(opts: HTTPRequestOptions): Promise<T>;
+};
+export type Res<T = any> = {
+    error: boolean;
+    status?: string;
+    message?: string;
+    data: T;
+};
+/**
+ * The payload inside De.'s envelope, for a caller who wants only that.
+ *
+ * Clients return the envelope — `{ error, status, message, data }` — because
+ * `status` names a refusal precisely and throwing it away leaves the caller
+ * reconstructing it from prose. This names the `data` half for the places that
+ * want to talk about the payload type on its own.
+ *
+ * A route answering with no payload resolves to `undefined`, and a payload the
+ * route may omit keeps the `| undefined` its schema gave it — the distinction
+ * a conditional on `T extends { data: infer D }` loses, since an optional
+ * property fails that test outright.
+ */
+export type Data<T> = 'data' extends keyof T ? T['data'] : undefined;
+export declare const qs: (params?: Record<string, any>) => string;
 declare const _default: {
     Stream: typeof Stream;
 };

package/dist/utils/index.js

@@ -3,6 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-var stream_1 = __importDefault(require("./stream"));
+exports.qs = void 0;
+const stream_1 = __importDefault(require("./stream"));
+const qs = (params) => {
+    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}` : '';
+};
+exports.qs = qs;
 exports.default = { Stream: stream_1.default };
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;AACA,oDAA6B;AAE7B,kBAAe,EAAE,MAAM,kBAAA,EAAE,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;AACA,sDAA6B;AAsBtB,MAAM,EAAE,GAAG,CAAE,MAA4B,EAAW,EAAE;IAC3D,IAAI,CAAC,MAAM;QAAG,OAAO,EAAE,CAAA;IACvB,MAAM,CAAC,GAAG,IAAI,eAAe,CAC3B,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAE,MAAM,CAAE;SACjB,MAAM,CAAE,CAAE,CAAC,EAAE,CAAC,CAAC,EAAG,EAAE,CAAC,CAAC,IAAI,IAAI,CAAE;SAChC,GAAG,CAAE,CAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAG,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,CAAE,CAAC,CAAE,CAAC,CAAE,CAC7C,CACF,CAAC,QAAQ,EAAE,CAAA;IACZ,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;AACzB,CAAC,CAAA;AAVY,QAAA,EAAE,MAUd;AAED,kBAAe,EAAE,MAAM,EAAN,gBAAM,EAAE,CAAA"}

package/dist/utils/stream.js

@@ -1,44 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-var Stream = /** @class */ (function () {
-    function Stream() {
+class Stream {
+    constructor() {
         this._STALED = false;
         this._CLOSED = false;
         this._fns = [];
-        this._exitFn = (function () { });
-        this._errorFn = (function (error) { });
+        this._exitFn = (() => { });
+        this._errorFn = ((error) => { });
     }
-    Stream.prototype._upstream = function (stream) {
+    _upstream(stream) {
         this._upStream = stream;
         return this;
-    };
-    Stream.prototype._backpressure = function (data) {
-        !this._CLOSED && this._fns.map(function (fn) { return fn(data); });
-    };
-    Stream.prototype.sync = function (data) {
+    }
+    _backpressure(data) {
+        !this._CLOSED && this._fns.map(fn => fn(data));
+    }
+    sync(data) {
         var _a;
         !this._CLOSED && ((_a = this._downStream) === null || _a === void 0 ? void 0 : _a._backpressure(data));
-    };
-    Stream.prototype.on = function (_event, fn) {
+    }
+    on(_event, fn) {
         if (this._CLOSED)
             throw new Error('Stream closed');
         this._fns.push(fn);
         return this;
-    };
-    Stream.prototype.pipe = function (stream) {
+    }
+    pipe(stream) {
         stream._upstream(this);
         this._downStream = stream;
         return this;
-    };
-    Stream.prototype.error = function (error) {
+    }
+    error(error) {
         var _a;
         // Throw error to self
         this._errorFn(typeof error == 'string' ? new Error(error) : error);
         // Throw error to downstream pipe
         (_a = this._downStream) === null || _a === void 0 ? void 0 : _a.error(error);
         return this;
-    };
-    Stream.prototype.close = function () {
+    }
+    close() {
         var _a;
         if (this._CLOSED)
             return;
@@ -47,17 +47,16 @@ var Stream = /** @class */ (function () {
         this._exitFn();
         (_a = this._downStream) === null || _a === void 0 ? void 0 : _a.close(); // Close down streams
         // this._upStream?.close() // Close up streams: Recursive loop call effect
-    };
-    Stream.prototype.isActive = function () { return !this._CLOSED; };
-    Stream.prototype.onerror = function (fn) {
+    }
+    isActive() { return !this._CLOSED; }
+    onerror(fn) {
         this._errorFn = fn;
         return this;
-    };
-    Stream.prototype.onclose = function (fn) {
+    }
+    onclose(fn) {
         this._exitFn = fn;
         return this;
-    };
-    return Stream;
-}());
+    }
+}
 exports.default = Stream;
 //# sourceMappingURL=stream.js.map

package/dist/utils/stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":";;AAGA;IAAA;QACU,YAAO,GAAY,KAAK,CAAA;QACxB,YAAO,GAAY,KAAK,CAAA;QACxB,SAAI,GAAyB,EAAE,CAAA;QAC/B,YAAO,GAAG,CAAC,cAAO,CAAC,CAAC,CAAA;QACpB,aAAQ,GAAG,CAAC,UAAE,KAAY,IAAO,CAAC,CAAC,CAAA;IA2D7C,CAAC;IAvDS,0BAAS,GAAjB,UAAmB,MAAc;QAC/B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAA;QACvB,OAAO,IAAI,CAAA;IACb,CAAC;IACO,8BAAa,GAArB,UAAuB,IAAS;QAC9B,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAE,UAAA,EAAE,IAAI,OAAA,EAAE,CAAE,IAAI,CAAE,EAAV,CAAU,CAAE,CAAA;IACpD,CAAC;IAED,qBAAI,GAAJ,UAAM,IAAS;;QACb,CAAC,IAAI,CAAC,OAAO,KAAI,MAAA,IAAI,CAAC,WAAW,0CAAE,aAAa,CAAE,IAAI,CAAE,CAAA,CAAA;IAC1D,CAAC;IAED,mBAAE,GAAF,UAAI,MAAc,EAAE,EAAsB;QACxC,IAAI,IAAI,CAAC,OAAO;YAAG,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAA;QAEnD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAE,EAAE,CAAE,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,qBAAI,GAAJ,UAAM,MAAc;QAClB,MAAM,CAAC,SAAS,CAAE,IAAI,CAAE,CAAA;QACxB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,sBAAK,GAAL,UAAO,KAAqB;;QAC1B,sBAAsB;QACtB,IAAI,CAAC,QAAQ,CAAE,OAAO,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,KAAK,CAAE,KAAK,CAAE,CAAC,CAAC,CAAE,KAAK,CAAE,CAAA;QACvE,iCAAiC;QACjC,MAAA,IAAI,CAAC,WAAW,0CAAE,KAAK,CAAE,KAAK,CAAE,CAAA;QAEhC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,sBAAK,GAAL;;QACE,IAAI,IAAI,CAAC,OAAO;YAAG,OAAM;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QAEnB,IAAI,CAAC,IAAI,GAAG,EAAE,CAAA;QACd,IAAI,CAAC,OAAO,EAAE,CAAA;QAEd,MAAA,IAAI,CAAC,WAAW,0CAAE,KAAK,EAAE,CAAA,CAAC,qBAAqB;QAC/C,0EAA0E;IAC5E,CAAC;IAED,yBAAQ,GAAR,cAAY,OAAO,CAAC,IAAI,CAAC,OAAO,CAAA,CAAC,CAAC;IAElC,wBAAO,GAAP,UAAS,EAA4B;QACnC,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,wBAAO,GAAP,UAAS,EAAc;QACrB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IACH,aAAC;AAAD,CAAC,AAhED,IAgEC"}
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":";;AAGA,MAAqB,MAAM;IAA3B;QACU,YAAO,GAAY,KAAK,CAAA;QACxB,YAAO,GAAY,KAAK,CAAA;QACxB,SAAI,GAAyB,EAAE,CAAA;QAC/B,YAAO,GAAG,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACpB,aAAQ,GAAG,CAAC,CAAE,KAAY,EAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IA2D7C,CAAC;IAvDS,SAAS,CAAE,MAAc;QAC/B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAA;QACvB,OAAO,IAAI,CAAA;IACb,CAAC;IACO,aAAa,CAAE,IAAS;QAC9B,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAE,IAAI,CAAE,CAAE,CAAA;IACpD,CAAC;IAED,IAAI,CAAE,IAAS;;QACb,CAAC,IAAI,CAAC,OAAO,KAAI,MAAA,IAAI,CAAC,WAAW,0CAAE,aAAa,CAAE,IAAI,CAAE,CAAA,CAAA;IAC1D,CAAC;IAED,EAAE,CAAE,MAAc,EAAE,EAAsB;QACxC,IAAI,IAAI,CAAC,OAAO;YAAG,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAA;QAEnD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAE,EAAE,CAAE,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAE,MAAc;QAClB,MAAM,CAAC,SAAS,CAAE,IAAI,CAAE,CAAA;QACxB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAE,KAAqB;;QAC1B,sBAAsB;QACtB,IAAI,CAAC,QAAQ,CAAE,OAAO,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,KAAK,CAAE,KAAK,CAAE,CAAC,CAAC,CAAE,KAAK,CAAE,CAAA;QACvE,iCAAiC;QACjC,MAAA,IAAI,CAAC,WAAW,0CAAE,KAAK,CAAE,KAAK,CAAE,CAAA;QAEhC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK;;QACH,IAAI,IAAI,CAAC,OAAO;YAAG,OAAM;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QAEnB,IAAI,CAAC,IAAI,GAAG,EAAE,CAAA;QACd,IAAI,CAAC,OAAO,EAAE,CAAA;QAEd,MAAA,IAAI,CAAC,WAAW,0CAAE,KAAK,EAAE,CAAA,CAAC,qBAAqB;QAC/C,0EAA0E;IAC5E,CAAC;IAED,QAAQ,KAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAA,CAAC,CAAC;IAElC,OAAO,CAAE,EAA4B;QACnC,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,CAAE,EAAc;QACrB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAhED,yBAgEC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@de./sdk",
-  "version": "1.0.4",
-  "description": "Complete SDK pack for MSI (Map Service Interface), IoTClient and DClient services",
+  "version": "2.0.0",
+  "description": "Complete SDK pack for MSI (Map Service Interface), IoTClient and DClient services — web, server and React Native",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -11,46 +11,66 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
+    },
+    "./react-native": {
+      "types": "./dist/react-native.d.ts",
+      "import": "./dist/react-native.js",
+      "require": "./dist/react-native.js"
     },
     "./types": {
       "types": "./dist/types/index.d.ts",
       "default": "./dist/types/index.d.ts"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "author": "SCOREX Corporation",
   "private": false,
   "scripts": {
     "build:tsc": "rimraf ./dist && tsc",
-    "build:webpack": "WEBPACK_ENV=build webpack",
     "build:copy-types": "mkdir -p dist/types && cp -r src/types/* dist/types/",
-    "compile": "yarn build:tsc && yarn build:webpack && yarn build:copy-types",
-    "prepack": "yarn run compile",
-    "test": "Echo 'Error: No test specified' && exit 1",
-    "test:auth": "yarn build:tsc && jest test/auth.test.js",
-    "test:client": "yarn build:tsc && jest test/client.test.js",
-    "test:order": "yarn build:tsc && jest test/order.test.js",
-    "test:event": "yarn build:tsc && jest test/event.test.js"
+    "compile": "npm run build:tsc && npm run build:copy-types",
+    "verify:entries": "node scripts/verify-entries.mjs",
+    "prepack": "npm run compile && npm run verify:entries",
+    "test": "npm run build:tsc && jest",
+    "test:auth": "npm run build:tsc && jest test/auth.test.js",
+    "test:client": "npm run build:tsc && jest test/client.test.js",
+    "test:order": "npm run build:tsc && jest test/order.test.js",
+    "test:event": "npm run build:tsc && jest test/event.test.js"
   },
   "dependencies": {
+    "@de./types": "^2.0.0",
     "events": "^3.3.0",
     "iframe.io": "^1.1.0",
     "node-fetch": "2.6.1",
-    "socket.io-client": "^4.6.1"
+    "socket.io-client": "^4.6.1",
+    "webview.io": "^1.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0",
+    "react-native-webview": ">=11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-native": { "optional": true },
+    "react-native-webview": { "optional": true }
   },
   "devDependencies": {
+    "@babel/core": "^7.26.0",
     "@types/jest": "^29.5.0",
     "@types/node-fetch": "^2.6.3",
+    "@types/react": "^18.0.0",
     "expect.js": "^0.3.1",
     "jest": "^29.7.0",
+    "react": "^18.2.0",
+    "react-native": "^0.72.8",
+    "react-native-webview": "13.16.0",
     "rimraf": "^4.4.0",
     "ts-jest": "^29.0.5",
-    "ts-loader": "^9.4.2",
-    "typescript": "^5.0.2",
-    "webpack": "^5.77.0",
-    "webpack-cli": "^5.0.1"
+    "typescript": "^5.9.0"
   },
   "directories": {
     "dist": "dist/",

package/src/allend/Access.ts

@@ -1,35 +1,76 @@
-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'
 
-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 +90,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 +115,94 @@ 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.
+     */
+    if( typeof body?.error !== 'boolean' )
+      throw new APIError(
+        body?.message || `${options.method} ${url} — ${response.status} ${response.statusText || 'not a De. response'}`,
+        response.status,
+        body
+      )
 
-    // console.log( options )
-    return await ( await fetch( url, options ) ).json() as Response
+    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

@@ -0,0 +1,43 @@
+import type {
+	AgentConsolidationRespondValidation,
+	AgentConsolidationHandoffValidation,
+	AgentConsolidationCompleteValidation
+} from '@de./types'
+import { type Http, type Res, type Data } from '../../utils'
+
+// ─── Agent Consolidation ──────────────────────────────────────────────────────
+
+export default class AgentConsolidation {
+	constructor( private http: Http ){}
+
+	async respond( body: AgentConsolidationRespondValidation['body'] ): Promise<AgentConsolidationRespondValidation['response']> {
+		return await this.http.request<AgentConsolidationRespondValidation['response']>({
+			url: '/agent/consolidation/respond',
+			method: 'POST',
+			body
+		})
+	}
+
+	async handoffConfirm( body: AgentConsolidationHandoffValidation['body'] ): Promise<AgentConsolidationHandoffValidation['response']> {
+		return await this.http.request<AgentConsolidationHandoffValidation['response']>({
+			url: '/agent/consolidation/handoff/confirm',
+			method: 'POST',
+			body
+		})
+	}
+
+	/**
+	 * 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

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

package/src/allend/Agent/dispatch.ts

@@ -0,0 +1,27 @@
+import type {
+	AgentDispatchRespondValidation,
+	AgentDispatchRateValidation
+} from '@de./types'
+import { type Http, type Res, type Data } from '../../utils'
+
+// ─── Agent Dispatch ───────────────────────────────────────────────────────────
+
+export default class AgentDispatch {
+	constructor( private http: Http ){}
+
+	async respond( body: AgentDispatchRespondValidation['body'] ): Promise<AgentDispatchRespondValidation['response']> {
+		return await this.http.request<AgentDispatchRespondValidation['response']>({
+			url: '/agent/dispatch/respond',
+			method: 'POST',
+			body
+		})
+	}
+
+	async rate( body: AgentDispatchRateValidation['body'] ): Promise<AgentDispatchRateValidation['response']> {
+		return await this.http.request<AgentDispatchRateValidation['response']>({
+			url: '/agent/dispatch/rate',
+			method: 'POST',
+			body
+		})
+	}
+}