@de./sdk 1.0.5 → 2.1.0

package/src/core.ts

@@ -0,0 +1,146 @@
+// ─── @de./sdk — platform-neutral core ─────────────────────────────────────────
+//
+// Everything that runs unchanged on Node, in a browser and in React Native.
+//
+// The MSI gateway is deliberately absent: it is the one surface that needs a
+// host-specific transport and mounting, so each entry point adds its own --
+// `./index` (iframe + iframe.io) and `./react-native` (WebView + webview.io).
+// Keeping it out of here is what stops the React Native module from being
+// pulled into web and server bundles, where `react-native-webview` cannot
+// resolve.
+//
+// Two-layer architecture:
+//
+//   Layer 1 — Core   : raw API mirror, 1:1 with de.arch endpoints.
+//   Layer 2 — Workflows: use-case composition, many API calls in one.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ── Named exports (preferred — tree-shakeable) ────────────────────────────────
+
+// Server-side auth: connector credentials → access token
+export { default as Auth } from './backend/Auth'
+export type { AuthConfig } from './backend/Auth'
+
+// Client-side OTP auth (de.auth service)
+export { default as OTPAuth } from './allend/OTPAuth'
+
+// Shared tracking API (de.arch /tracking)
+export { default as Tracking } from './allend/Tracking'
+export type { TrackingConfig } from './allend/Tracking'
+
+export { default as Pipelines } from './allend/Pipelines'
+export type { PipelinesConfig } from './allend/Pipelines'
+
+export { default as LSP } from './allend/LSP'
+export type { LSPConfig } from './allend/LSP'
+
+export { default as CSP } from './allend/CSP'
+export type { CSPConfig } from './allend/CSP'
+
+export { default as DEV } from './allend/DEV'
+export type { DEVConfig } from './allend/DEV'
+
+// IoT service provider + IoT Backend socket client (de.iotb service)
+export { default as IoTSP, Records as IoTBackendRecords } from './allend/IoTSP'
+export type { IoTSPConfig } from './allend/IoTSP'
+
+export { default as Workspace } from './allend/Workspace'
+export type { WorkspaceConfig } from './allend/Workspace'
+
+// Realtime socket client (de.arch / Socket)
+export { default as Realtime } from './allend/Realtime'
+
+// Layer 2 — Workflows
+export { default as Workflows } from './allend/Workflows'
+export type { WorkflowsConfig } from './allend/Workflows'
+
+// Utilities
+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/
+// query surfaces.
+//
+// Imported from their own modules rather than the `./allend` barrel: that
+// barrel re-exports the browser MSI, which would pull iframe.io into the React
+// Native bundle. `yarn verify:entries` enforces this.
+export { default as IoTClient } from './allend/IoTClient'
+export type { IoTClientOptions } from './allend/IoTClient'
+
+export { default as Customer } from './allend/Customer'
+export type { CustomerConfig } from './allend/Customer'
+
+export { default as Agent } from './allend/Agent'
+export type { AgentConfig } from './allend/Agent'
+export type { AgentRealtimeContext } from './allend/Agent/realtime'
+
+export { default as Queries } from './allend/Queries'
+export type { QueriesConfig } from './allend/Queries'
+
+export { default as Utilities } from './allend/Utilities'
+export type { UtilitiesConfig } from './allend/Utilities'
+
+// The MSI control surface is shared by both entry points
+export type { default as Controls } from './allend/MSI/Controls'
+export type { default as Handles } from './allend/MSI/Handles'
+export type { Plugin } from './allend/MSI/Plugins'
+
+// Transport contract the MSI control surface is written against
+export type { Channel, Listener, AckFunction } from './types/channel'
+export type { AccessOptions, UserSession } from './types/access'
+
+// Public types (domain + SDK config)
+export type * from './types'
+
+// ── Namespace of the platform-neutral constructors ────────────────────────────
+
+import Auth      from './backend/Auth'
+import OTPAuth   from './allend/OTPAuth'
+import Pipelines from './allend/Pipelines'
+import Realtime  from './allend/Realtime'
+import IoT       from './allend/IoTSP/backend'
+import LSP       from './allend/LSP'
+import CSP       from './allend/CSP'
+import DEV       from './allend/DEV'
+import IoTSP     from './allend/IoTSP'
+import Workspace from './allend/Workspace'
+import Workflows from './allend/Workflows'
+import Tracking  from './allend/Tracking'
+import Utils     from './utils'
+import IoTClient from './allend/IoTClient'
+import Customer  from './allend/Customer'
+import Agent     from './allend/Agent'
+import Queries   from './allend/Queries'
+import Utilities from './allend/Utilities'
+import Client    from './allend/Workflows/Client'
+import Event     from './allend/Realtime'
+
+// DClient groups the workflow client with the realtime event channel
+const DClient = { Client, Event }
+export { DClient }
+
+export const core = {
+	Auth,
+	OTPAuth,
+	Pipelines,
+	Realtime,
+	IoT,
+	LSP,
+	CSP,
+	DEV,
+	IoTSP,
+	Workspace,
+	Workflows,
+	Tracking,
+	Utils,
+	DClient,
+	IoTClient,
+	Customer,
+	Agent,
+	Queries,
+	Utilities
+}

package/src/error.ts

@@ -0,0 +1,27 @@
+/**
+ * A request De. answered with a failure.
+ *
+ * Every client threw on `error: true` already, but with a bare Error carrying
+ * only the message — so a caller could not tell an expired offer (404) from a
+ * rejected body (400) from De. being down (502) without parsing prose. A proxy
+ * mapping De.'s answer onto its own response had nothing to map, and a
+ * simulation counting ordinary 404s as ordinary had nothing to count.
+ *
+ * `status` is the HTTP status; `payload` is the envelope as it arrived, for
+ * the field-level detail a validation failure carries.
+ */
+export default class APIError extends Error {
+	readonly status: number
+	readonly payload?: unknown
+
+	constructor( message: string, status: number, payload?: unknown ){
+		super( message )
+
+		this.name = 'APIError'
+		this.status = status
+		this.payload = payload
+
+		// Restores the prototype chain across the ES5 target, so `instanceof` holds
+		Object.setPrototypeOf( this, APIError.prototype )
+	}
+}

package/src/index.ts

@@ -1,116 +1,27 @@
-// ─── @de./sdk ─────────────────────────────────────────────────────────────────
+// ─── @de./sdk — web & server entry point ──────────────────────────────────────
 //
-// Two-layer architecture:
+// The platform-neutral core plus the browser MSI gateway (iframe + iframe.io).
 //
-//   Layer 1 — Core   : raw API mirror, 1:1 with de.arch endpoints.
-//   Layer 2 — Workflows: use-case composition, many API calls in one.
+// React Native consumers import '@de./sdk/react-native' instead, which pairs
+// the same core with a WebView gateway. This module must never reference that
+// one: it would drag react-native-webview into web and server bundles.
+//
+//   import De from '@de./sdk'
+//   const msi = new De.MSI({ element: 'map', accessToken })
 //
 // ─────────────────────────────────────────────────────────────────────────────
 
-// ── Named exports (preferred — tree-shakeable) ────────────────────────────────
-
-// Server-side auth: connector credentials → access token
-export { default as Auth } from './backend/Auth'
-export type { AuthConfig } from './backend/Auth'
-
-// Client-side OTP auth (de.auth service)
-export { default as OTPAuth } from './allend/OTPAuth'
-
-// Shared tracking API (de.arch /tracking)
-export { default as Tracking } from './allend/Tracking'
-export type { TrackingConfig } from './allend/Tracking'
-
-export { default as Pipelines } from './allend/Pipelines'
-export type { PipelinesConfig } from './allend/Pipelines'
-
-export { default as LSP } from './allend/LSP'
-export type { LSPConfig } from './allend/LSP'
-
-export { default as CSP } from './allend/CSP'
-export type { CSPConfig } from './allend/CSP'
-
-export { default as DEV } from './allend/DEV'
-export type { DEVConfig } from './allend/DEV'
-
-// IoT service provider + IoT Backend socket client (de.iotb service)
-export { default as IoTSP, Records as IoTBackendRecords } from './allend/IoTSP'
-export type { IoTSPConfig } from './allend/IoTSP'
+export * from './core'
 
-export { default as Workspace } from './allend/Workspace'
-export type { WorkspaceConfig } from './allend/Workspace'
-
-// Map Service Interface (de.eui service)
+// Map Service Interface (de.eui service) — browser gateway
 export { default as MSI, type MSIInterface } from './allend/MSI'
 
-// Realtime socket client (de.arch / Socket)
-export { default as Realtime } from './allend/Realtime'
-
-// Layer 2 — Workflows
-export { default as Workflows } from './allend/Workflows'
-export type { WorkflowsConfig } from './allend/Workflows'
-
-// Utilities
-export { default as Utils } from './utils'
-
-// ── Client layer (allend) ─────────────────────────────────────────────────────
-// DClient ({ Client, Event }), the IoT socket client, and the customer/agent/
-// query surfaces. Re-exported here so the package entry point is the complete
-// public API (consumers import these from '@de./sdk').
-export { DClient, IoTClient, Customer, Agent, Queries, Utilities } from './allend'
-export type {
-	IoTClientOptions,
-	CustomerConfig,
-	AgentConfig,
-	QueriesConfig,
-	UtilitiesConfig
-} from './allend'
-
-// Public types (domain + SDK config)
-export type * from './types'
-
-// ── Default export — all constructors under one namespace ─────────────────────
-//
-//   import De from '@de./sdk'
-//   const core = new De.Core({ context, accessToken, env })
-//   const msi  = new De.MSI({ element: 'map', accessToken })
-
-import Auth      from './backend/Auth'
-import OTPAuth   from './allend/OTPAuth'
-import Pipelines  from './allend/Pipelines'
-import MSI       from './allend/MSI'
-import Realtime  from './allend/Realtime'
-import IoT       from './allend/IoTSP/backend'
-import LSP       from './allend/LSP'
-import CSP       from './allend/CSP'
-import DEV       from './allend/DEV'
-import IoTSP     from './allend/IoTSP'
-import Workspace from './allend/Workspace'
-import Workflows from './allend/Workflows'
-import Tracking  from './allend/Tracking'
-import Utils     from './utils'
-import { DClient, IoTClient, Customer, Agent, Queries, Utilities } from './allend'
+import MSI from './allend/MSI'
+import { core } from './core'
 
 const De = {
-	Auth,
-	OTPAuth,
-	Pipelines,
-	MSI,
-	Realtime,
-	IoT,
-	LSP,
-	CSP,
-	DEV,
-	IoTSP,
-	Workspace,
-	Workflows,
-	Tracking,
-	Utils,
-	DClient,
-	IoTClient,
-	Customer,
-	Agent,
-	Queries,
-	Utilities
+	...core,
+	MSI
 }
 
 export default De

package/src/react-native.ts

@@ -0,0 +1,43 @@
+// ─── @de./sdk/react-native — React Native entry point ─────────────────────────
+//
+// The platform-neutral core plus the native MSI gateway (WebView + webview.io).
+//
+// Everything outside the gateway is the same code the web entry uses -- the MSI
+// control surface (Controls, Handles, Plugins) is written against a transport
+// contract both iframe.io and webview.io satisfy, so there is no native copy of
+// it to drift.
+//
+//   import De, { MSI } from '@de./sdk/react-native'
+//
+//   <MSI
+//     env="dev"
+//     getAccessToken={() => token}
+//     onLoaded={({ controls, handles }) => …}
+//   />
+//
+// Requires react, react-native and react-native-webview in the host app; they
+// are declared as optional peer dependencies so web and server installs are not
+// asked for them.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+export * from './core'
+
+// Map Service Interface (de.eui service) — WebView gateway
+export {
+	default as MSI,
+	plugin,
+	type MSIInterface,
+	type MSIProps,
+	type MSIRef
+} from './allend/MSI/native'
+
+import MSI from './allend/MSI/native'
+import { core } from './core'
+
+const De = {
+	...core,
+	MSI
+}
+
+export default De

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/types/access.d.ts

@@ -1,3 +1,16 @@
+/**
+ * End-user session credentials.
+ *
+ * Issued by de.auth when a person signs in (`ctoken` + `deviceId`) and sent
+ * as the `de-auth-token` / `de-auth-device` header pair.
+ */
+export type UserSession = {
+	/** Connection token from de.auth — the `ctoken` field. */
+	token: string
+	/** Device id issued alongside the connection token. */
+	device: string
+}
+
 export type AccessOptions = {
 	env: 'dev' | 'staging' | 'prod'
 	platform: 'web' | 'mobile' | 'server' | 'proxy'
@@ -5,4 +18,48 @@ export type AccessOptions = {
 	context: string
 	accessToken: string
 	remoteOrigin?: string
+	/**
+	 * Host to substitute for `localhost` when `env` is `dev`.
+	 *
+	 * Native apps cannot reach the host machine on localhost -- the Android
+	 * emulator maps it to 10.0.2.2 and a physical device needs the LAN address.
+	 * Ignored outside `dev`.
+	 */
+	devHostname?: string
+	/**
+	 * Signed-in user, when the client acts on someone's behalf.
+	 *
+	 * Some de.arch routes authenticate the *caller* rather than the
+	 * integration: AUX agent routes run `isConnected`, which reads
+	 * `de-auth-token` / `de-auth-device` and never inspects the bearer token.
+	 * A client that sends only `authorization` cannot reach them.
+	 *
+	 * Supply this when acting as a signed-in user — a rider in a driver app, a
+	 * customer in a consumer app. The bearer token is still sent, since it
+	 * identifies the integration; the two credentials travel together.
+	 */
+	session?: UserSession
+	/**
+	 * Deadline for every request this client makes, in milliseconds.
+	 *
+	 * Without one a request has no upper bound. Node closes idle keep-alive
+	 * connections after 5s while the client pool hands one out regardless, so a
+	 * request can be written into a socket the server already closed and then
+	 * wait forever — a hang in the caller, not an error it can handle.
+	 *
+	 * Omit it to keep the runtime's own default (none, in practice).
+	 */
+	timeout?: number
+	/**
+	 * Explicit service origin, overriding the environment table.
+	 *
+	 * The table maps `dev` to fixed localhost ports, which only holds when
+	 * every service runs on the port it was assigned. A self-hosted De., or a
+	 * dev machine running de.workspace on its own port, has no entry there —
+	 * and no host substitution can invent one, since `devHostname` swaps the
+	 * host and keeps the port.
+	 *
+	 * Give an origin (`http://localhost:22200`), not a path.
+	 */
+	baseUrl?: string
 }

package/src/types/channel.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Transport-agnostic message channel.
+ *
+ * The MSI control surface (Controls, Handles, Plugins) talks to the gateway
+ * exclusively through this contract, so the same logic drives a browser iframe
+ * and a React Native WebView without a per-platform copy.
+ *
+ * Both transports satisfy it structurally, with no adapter: `iframe.io` (IOF)
+ * and `webview.io` (WIO) declare identical `Listener` / `AckFunction` types and
+ * identical signatures for every method below. They diverge only at connection
+ * setup -- `initiate()` takes a `Window` on web and a `WebView` ref on native,
+ * and WIO adds `handleMessage()` / `getInjectedJavaScript()`. Those live in the
+ * platform entry points, which hold the concrete transport type and so keep
+ * full access to it; deliberately none of them appear here.
+ */
+
+export type AckFunction = ( error: boolean | string, ...args: any[] ) => void
+export type Listener = ( payload?: any, ack?: AckFunction ) => void
+
+export interface Channel {
+  /**
+   * Send an event to the peer, optionally with an acknowledgement callback.
+   */
+  emit<T = any>( _event: string, payload?: T | AckFunction, fn?: AckFunction ): Channel
+
+  /**
+   * Subscribe to an event from the peer.
+   */
+  on( _event: string, fn: Listener ): Channel
+
+  /**
+   * Subscribe to the next occurrence of an event only.
+   */
+  once( _event: string, fn: Listener ): Channel
+
+  /**
+   * Unsubscribe a listener, or every listener for the event when none is given.
+   */
+  off( _event: string, fn?: Listener ): Channel
+
+  /**
+   * Remove all registered listeners.
+   */
+  removeListeners( fn?: Listener ): Channel
+}

package/src/types/index.d.ts

@@ -1,4 +1,27 @@
 // ─── @de./sdk — public type surface ──────────────────────────────────────────
+
+// Stream is a runtime class in this package; the public surface references it
+// structurally, so it has to be imported here rather than assumed global.
+import type Stream from '../utils/stream'
+import type MSI from '../allend/MSI'
+
+/**
+ * The map engine an MSI extension receives.
+ *
+ * REVIEW: this alias replaces a dangling `Engine` reference that never
+ * resolved to a declaration anywhere in the package — the public surface
+ * simply did not compile for consumers. MSI is the only engine the SDK
+ * exposes, so it is the intended target as far as can be determined.
+ */
+export type Engine = MSI
+
+/**
+ * Styling options for custom map points.
+ *
+ * REVIEW: also previously dangling. Kept permissive so no existing caller
+ * breaks; narrow it once the intended shape is known.
+ */
+export type CustomPointOptions = Record<string, unknown>
 //
 // Rule: import from @de./types whenever the type exists there.
 // Only define types here that are genuinely SDK-specific (MSI map UI, HTTP
@@ -126,6 +149,8 @@ export type HTTPRequestOptions = {
 	method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'
 	headers?: { [index: string]: string }
 	body?: any
+	/** Per-call deadline in ms, overriding the client's own. */
+	timeout?: number
 }
 export type HTTPResponse<T = Record<string, never>> = {
 	error: boolean
@@ -320,10 +345,28 @@ export interface LRStreamer {
 // ─── MSI map interface config ─────────────────────────────────────────────────
 
 export type MapOptions = {
-	element: string
-	accessToken: string
+	/**
+	 * Id of the container element to mount the gateway into.
+	 * Web only -- the React Native entry renders a component instead.
+	 */
+	element?: string
+	/**
+	 * Static access token.
+	 *
+	 * Prefer `getAccessToken` for long-lived sessions: it is read at every bind
+	 * and rebind, so a rotated token is picked up without tearing the map down.
+	 * Supply one or the other -- both entry points reject when neither yields a
+	 * token.
+	 */
+	accessToken?: string
+	getAccessToken?: () => string
 	version?: number
 	env?: 'dev' | 'prod'
+	/**
+	 * Host to substitute for `localhost` when `env` is `dev`. Native apps cannot
+	 * reach the host machine on localhost.
+	 */
+	devHostname?: string
 }
 export type MapLayerStyle = 'streets' | 'outdoors' | 'light' | 'dark' | 'satellite'
 

package/src/utils/index.ts

@@ -6,6 +6,21 @@ 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 const qs = ( params?: Record<string, any> ): string => {
   if( !params ) return ''
   const q = new URLSearchParams(

package/dist/de.sdk/src/allend/Access.d.ts

@@ -1,15 +0,0 @@
-import type { AccessOptions } from '../types/access';
-import type { HTTPRequestOptions } from '../types';
-type AccessType = 'API' | 'ASI';
-export default class AccessManager {
-    private atype;
-    private version;
-    private platform;
-    private baseURL;
-    protected accessToken?: string;
-    protected remoteOrigin?: string;
-    constructor(options: AccessOptions, atype: AccessType);
-    request<Response>({ url, ...options }: HTTPRequestOptions): Promise<Response>;
-    setToken(token: string): void;
-}
-export {};