@de./sdk 1.0.4 → 2.0.0

package/src/core.ts

@@ -0,0 +1,145 @@
+// ─── @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'
+
+// ── 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,19 +1,27 @@
-import Utils from './utils'
-import MSI, { type MSIInterface } from './allend/MSI'
-import IoTClient, { type IoTClientOptions } from './allend/IoTClient'
-import Order from './allend/DClient/Order'
-import Event from './allend/DClient/Event'
-import Client from './allend/DClient/Client'
-import Auth from './backend/Auth'
+// ─── @de./sdk — web & server entry point ──────────────────────────────────────
+//
+// The platform-neutral core plus the browser MSI gateway (iframe + iframe.io).
+//
+// 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 })
+//
+// ─────────────────────────────────────────────────────────────────────────────
 
-const DClient = { Client, Order, Event }
+export * from './core'
 
-export {
-  Auth,
-  MSI,
-  type MSIInterface,
-  Utils,
-  DClient,
-  IoTClient,
-  type IoTClientOptions
-}
+// Map Service Interface (de.eui service) — browser gateway
+export { default as MSI, type MSIInterface } from './allend/MSI'
+
+import MSI from './allend/MSI'
+import { core } from './core'
+
+const De = {
+	...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/types/access.d.ts

@@ -1,8 +1,65 @@
+/**
+ * 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' | 'prod'
-  platform: 'web' | 'mobile' | 'server' | 'proxy'
-  version?: number
-  context: string
-  accessToken: string
-  remoteOrigin?: string
-}
+	env: 'dev' | 'staging' | 'prod'
+	platform: 'web' | 'mobile' | 'server' | 'proxy'
+	version?: number
+	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/auth.d.ts

@@ -1,27 +1,27 @@
 export type AuthOptions = {
-  env: 'dev' | 'prod'
-  version?: number
-  autorefresh?: boolean
-  onNewToken?: (token: string) => void
+	env: 'dev' | 'staging' | 'prod'
+	version?: number
+	autorefresh?: boolean
+	onNewToken?: ( token: string ) => void
 }
 
 export type AuthCredentials = {
-  context: string
-  remoteOrigin: string
-  cid: string
-  secret: string
+	context: string
+	remoteOrigin: string
+	cid: string
+	secret: string
 }
 
 export type SocketAuthCredentials = {
-  utype: string
-  id: string
-  remoteOrigin: string
-  accessToken: string
+	utype: string
+	id: string
+	remoteOrigin: string
+	accessToken: string
 }
 
 export type AuthRequestOptions = {
-  url: string
-  method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'
-  headers?: { [index: string]: string }
-  body?: any
-}
+	url: string
+	method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'
+	headers?: { [index: string]: string }
+	body?: any
+}

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
+}