@de./sdk 1.0.4 → 2.0.0

package/src/allend/Workspace/index.ts

@@ -0,0 +1,302 @@
+import type { AccessOptions, UserSession } from '../../types/access'
+import type { Workspace as WorkspaceRecord } from '@de./types/workspace'
+import type { Admin, AdminUpdate } from '@de./types/workspace/admin'
+import type { Connector, ConnectorType } from '@de./types/workspace/connector'
+import AccessManager from '../Access'
+import { qs, type Res } from '../../utils'
+
+export type WorkspaceConfig = {
+	context: string
+	accessToken: string
+	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
+	/**
+	 * The signed-in operator.
+	 *
+	 * Required in practice. de.workspace authenticates a *person*, not an
+	 * integration — its routes read `de-auth-token` / `de-auth-device` — so a
+	 * client carrying only a bearer token cannot reach any of them.
+	 */
+	session?: UserSession
+}
+
+/** The four provider kinds a workspace can register, as they appear in a path. */
+export type ProviderKind = 'lsp' | 'csp' | 'dev' | 'iotsp'
+
+/** Context type as the connector routes spell it. */
+export type ContextType = 'LSP' | 'CSP' | 'DEV' | 'IoTSP'
+
+export type ProviderRecord = { xcode: string, name: string, type: string }
+
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Workspace: the control plane — de.workspace routes.
+//
+// A separate service from de.arch, which serves no `/workspace` routes at all.
+// This client previously addressed `/workspace/admins`, `/workspace/connectors`
+// and `/workspace/providers/lsps` against the API host; none of those exist
+// anywhere, so every method 404'd. The real surface is workspace-id scoped:
+// `/v1/:wid/admins`, `/v1/:wid/:ctype/:xcode/connectors`, `/v1/:wid/lsps`.
+//
+// Route shapes are taken from de.workspace/src/api/index.ts.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+export default class Workspace extends AccessManager {
+	constructor( config: WorkspaceConfig ){
+		if( !config.context )     throw new Error('Undefined context. See https://doc.dedot.io/sdk/workspace')
+		if( !config.accessToken ) throw new Error('Undefined accessToken. See https://doc.dedot.io/sdk/auth')
+
+		const access: AccessOptions = {
+			context:      config.context,
+			accessToken:  config.accessToken,
+			env:          config.env      || 'dev',
+			platform:     config.platform || 'proxy',
+			remoteOrigin: config.remoteOrigin,
+			timeout:      config.timeout,
+			baseUrl:      config.baseUrl,
+			session:      config.session
+		}
+		super( access, 'WSP' )
+	}
+
+	/**
+	 * Returns the envelope, like every other client here.
+	 *
+	 * de.workspace answers `{ error, status, message, data }` too, and its
+	 * `status` names a refusal precisely — WORKSPACE::EXISTS on a second
+	 * setup, "already enabled" on a redundant enable. Both are outcomes a
+	 * caller acts on rather than failures.
+	 */
+	private call<T>( method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', url: string, body?: any ): Promise<Res<T>> {
+		return this.request<Res<T>>({ url, method, ...( body !== undefined ? { body } : {}) })
+	}
+
+	// ── Workspace ─────────────────────────────────────────────────────────────
+
+	/**
+	 * A person may own exactly one workspace; a second call answers
+	 * WORKSPACE::EXISTS rather than creating another.
+	 */
+	async create( body: { settings?: { theme?: string } } = {} ): Promise<Res<{ wid: string }>> {
+		return this.call('POST', '/workspace/setup', body )
+	}
+
+	async retrieve( wid: string ): Promise<Res<WorkspaceRecord>> {
+		return this.call('GET', `/workspace/${wid}`)
+	}
+
+	async update( wid: string, body: Partial<Pick<WorkspaceRecord, 'settings'>> ): Promise<Res<WorkspaceRecord>> {
+		return this.call('PATCH', `/workspace/${wid}`, body )
+	}
+
+	/** Deletion is two-step: an intent, then the delete that quotes it. */
+	async requestDeletion( wid: string ): Promise<Res<{ intent: string }>> {
+		return this.call('POST', `/workspace/${wid}/deletion/intent`, {})
+	}
+
+	async remove( wid: string, querystring?: { intent?: string } ): Promise<Res<void>> {
+		return this.call('DELETE', `/workspace/${wid}${qs( querystring )}`)
+	}
+
+	// ── Providers ─────────────────────────────────────────────────────────────
+
+	async createProvider( wid: string, kind: ProviderKind, body: Record<string, any> ): Promise<Res<{ xcode: string, context: string }>> {
+		return this.call('POST', `/${wid}/${kind}/setup`, body )
+	}
+
+	async listProviders( wid: string, kind: ProviderKind ): Promise<Res<Record<string, ProviderRecord[]>>> {
+		return this.call('GET', `/${wid}/${kind}s`)
+	}
+
+	async retrieveProvider( wid: string, kind: ProviderKind, xcode: string ): Promise<Res<ProviderRecord>> {
+		return this.call('GET', `/${wid}/${kind}/${xcode}`)
+	}
+
+	async updateProvider( wid: string, kind: ProviderKind, xcode: string, body: Record<string, any> ): Promise<Res<ProviderRecord>> {
+		return this.call('PATCH', `/${wid}/${kind}/${xcode}`, body )
+	}
+
+	/**
+	 * Base64 of `wid:TYPE:xcode` — the context string every other client in
+	 * this SDK is constructed with.
+	 */
+	async getProviderContext( wid: string, kind: ProviderKind, xcode: string ): Promise<Res<{ context: string }>> {
+		return this.call('GET', `/${wid}/${kind}/${xcode}/context`)
+	}
+
+	async requestProviderDeletion( wid: string, kind: ProviderKind, xcode: string ): Promise<Res<{ intent: string }>> {
+		return this.call('POST', `/${wid}/${kind}/${xcode}/deletion/intent`, {})
+	}
+
+	async removeProvider( wid: string, kind: ProviderKind, xcode: string, querystring?: { intent?: string } ): Promise<Res<void>> {
+		return this.call('DELETE', `/${wid}/${kind}/${xcode}${qs( querystring )}`)
+	}
+
+	// ── Connectors ────────────────────────────────────────────────────────────
+
+	/**
+	 * Created disabled, and the reply carries only the id — the secret has to
+	 * be read back with `getConnector`.
+	 */
+	async createConnector(
+		wid: string, ctype: ContextType, xcode: string,
+		body: { name: string, type: ConnectorType, description?: string, config?: Record<string, any> }
+	): Promise<Res<{ connectorId: string }>> {
+		return this.call('POST', `/${wid}/${ctype}/${xcode}/connectors`, body )
+	}
+
+	async listConnectors( wid: string, ctype: ContextType, xcode: string, querystring?: Record<string, any> ): Promise<Res<{ connectors?: Connector[] }>> {
+		return this.call('GET', `/${wid}/${ctype}/${xcode}/connectors${qs( querystring )}`)
+	}
+
+	async getConnector( wid: string, ctype: ContextType, xcode: string, id: string ): Promise<Res<{ connector: Connector }>> {
+		return this.call('GET', `/${wid}/${ctype}/${xcode}/connectors/${id}`)
+	}
+
+	async updateConnector( wid: string, ctype: ContextType, xcode: string, id: string, body: Record<string, any> ): Promise<Res<Connector>> {
+		return this.call('PATCH', `/${wid}/${ctype}/${xcode}/connectors/${id}`, body )
+	}
+
+	/**
+	 * Enable or disable. Both are bodiless — Fastify rejects a JSON
+	 * content-type with no body, and the transport sends one only when there
+	 * is a body to send.
+	 */
+	async setConnectorEnabled( wid: string, ctype: ContextType, xcode: string, id: string, enabled: boolean ): Promise<Res<void>> {
+		return this.call('PATCH', `/${wid}/${ctype}/${xcode}/connectors/${id}/${enabled ? 'enable' : 'disable'}`)
+	}
+
+	/** Replaces the config wholesale; `patchConnectorConfig` merges instead. */
+	async setConnectorConfig( wid: string, ctype: ContextType, xcode: string, id: string, config: Record<string, any> ): Promise<Res<void>> {
+		return this.call('PUT', `/${wid}/${ctype}/${xcode}/connectors/${id}/config`, config )
+	}
+
+	async patchConnectorConfig( wid: string, ctype: ContextType, xcode: string, id: string, config: Record<string, any> ): Promise<Res<void>> {
+		return this.call('PATCH', `/${wid}/${ctype}/${xcode}/connectors/${id}/config`, config )
+	}
+
+	/**
+	 * Origin allow-list and maintainers.
+	 *
+	 * An empty `origins` means no origin check at all, which is what a client
+	 * that must not pin itself to one hostname wants.
+	 */
+	async setConnectorAccess( wid: string, ctype: ContextType, xcode: string, id: string, body: { origins?: string[], maintainers?: string[] }): Promise<Res<void>> {
+		return this.call('PATCH', `/${wid}/${ctype}/${xcode}/connectors/${id}/access`, body )
+	}
+
+	async rotateConnectorSecret( wid: string, ctype: ContextType, xcode: string, id: string ): Promise<Res<{ secret: string }>> {
+		return this.call('PATCH', `/${wid}/${ctype}/${xcode}/connectors/${id}/secret/rotate`)
+	}
+
+	async requestConnectorDeletion( wid: string, ctype: ContextType, xcode: string, id: string ): Promise<Res<{ intent: string }>> {
+		return this.call('POST', `/${wid}/${ctype}/${xcode}/connectors/${id}/deletion/intent`, {})
+	}
+
+	async removeConnector( wid: string, ctype: ContextType, xcode: string, id: string, querystring?: { intent?: string } ): Promise<Res<void>> {
+		return this.call('DELETE', `/${wid}/${ctype}/${xcode}/connectors/${id}${qs( querystring )}`)
+	}
+
+	// ── Admins ────────────────────────────────────────────────────────────────
+
+	async listAdmins( wid: string, querystring?: Record<string, any> ): Promise<Res<{ admins?: Admin[] }>> {
+		return this.call('GET', `/${wid}/admins${qs( querystring )}`)
+	}
+
+	async getAdmin( wid: string, id: string ): Promise<Res<Admin>> {
+		return this.call('GET', `/${wid}/admins/${id}`)
+	}
+
+	async updateAdmin( wid: string, id: string, body: AdminUpdate ): Promise<Res<Admin>> {
+		return this.call('PATCH', `/${wid}/admins/${id}`, body )
+	}
+
+	async removeAdmin( wid: string, id: string ): Promise<Res<void>> {
+		return this.call('DELETE', `/${wid}/admins/${id}`)
+	}
+
+	// ── Billing ───────────────────────────────────────────────────────────────
+
+	async getBilling( wid: string, querystring?: Record<string, any> ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/billings${qs( querystring )}`)
+	}
+
+	async getBillingUsage( wid: string, querystring?: Record<string, any> ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/billings/usage${qs( querystring )}`)
+	}
+
+	async listBillingNotifications( wid: string, querystring?: Record<string, any> ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/billings/notifications${qs( querystring )}`)
+	}
+
+	async acknowledgeBillingNotification( wid: string, id: string ): Promise<Res<void>> {
+		return this.call('POST', `/${wid}/billings/notifications/${id}/acknowledge`, {})
+	}
+
+	async listInvoices( wid: string, querystring?: Record<string, any> ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/billings/invoices${qs( querystring )}`)
+	}
+
+	async listConnectorBilling( wid: string, querystring?: Record<string, any> ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/billings/connectors${qs( querystring )}`)
+	}
+
+	async getConnectorBilling( wid: string, cid: string ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/billings/connectors/${cid}`)
+	}
+
+	async getConnectorBillingHistory( wid: string, cid: string, querystring?: Record<string, any> ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/billings/connectors/${cid}/history${qs( querystring )}`)
+	}
+
+	async estimateConnectorBilling( wid: string, cid: string, body: Record<string, any> ): Promise<Res<any>> {
+		return this.call('POST', `/${wid}/billings/connectors/${cid}/estimate`, body )
+	}
+
+	async changeConnectorTier( wid: string, cid: string, body: Record<string, any> ): Promise<Res<any>> {
+		return this.call('POST', `/${wid}/billings/connectors/${cid}/tier/change`, body )
+	}
+
+	// ── Users & account ───────────────────────────────────────────────────────
+
+	async listUsers( wid: string, querystring?: Record<string, any> ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/users${qs( querystring )}`)
+	}
+
+	async getUser( wid: string, uid: string ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/users/${uid}`)
+	}
+
+	async removeUser( wid: string, uid: string ): Promise<Res<void>> {
+		return this.call('DELETE', `/${wid}/users/${uid}`)
+	}
+
+	async getAccount( wid: string ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/account`)
+	}
+
+	/** Who this account already knows in the workspace. */
+	async getAccountKnows( wid: string, querystring?: Record<string, any> ): Promise<Res<any>> {
+		return this.call('GET', `/${wid}/account/knows${qs( querystring )}`)
+	}
+
+	// ── Invitation ────────────────────────────────────────────────────────────
+
+	async invite( wid: string, as: string, body: Record<string, any> ): Promise<Res<{ vcode: string }>> {
+		return this.call('POST', `/${wid}/invitation/${as}`, body )
+	}
+
+	async cancelInvitation( wid: string, body: Record<string, any> ): Promise<Res<void>> {
+		return this.call('DELETE', `/${wid}/invitation`, body )
+	}
+
+	async acceptInvitation( wid: string, body: { vcode: string } ): Promise<Res<any>> {
+		return this.call('POST', `/${wid}/invitation/accept`, body )
+	}
+}

package/src/allend/index.ts

@@ -2,17 +2,30 @@ import MSI, { type MSIInterface } from './MSI'
 import Utils from '../utils'
 
 import IoTClient, { type IoTClientOptions } from './IoTClient'
-import Order from './DClient/Order'
-import Event from './DClient/Event'
-import Client from './DClient/Client'
+import Event from './Realtime'
+import Client from './Workflows/Client'
+import Customer, { type CustomerConfig } from './Customer'
+import Agent, { type AgentConfig } from './Agent'
+import { type AgentRealtimeContext } from './Agent/realtime'
+import Queries, { type QueriesConfig } from './Queries'
+import Utilities, { type UtilitiesConfig } from './Utilities'
 
-const DClient = { Client, Order, Event }
+const DClient = { Client, Event }
 
 export {
-  type MSIInterface,
-  MSI,
-  Utils,
-  DClient,
-  IoTClient,
-  type IoTClientOptions
+	type MSIInterface,
+	MSI,
+	Utils,
+	DClient,
+	IoTClient,
+	type IoTClientOptions,
+	Customer,
+	type CustomerConfig,
+	Agent,
+	type AgentConfig,
+	type AgentRealtimeContext,
+	Queries,
+	type QueriesConfig,
+	Utilities,
+	type UtilitiesConfig
 }

package/src/backend/Auth.ts

@@ -1,18 +1,54 @@
-import { API_SERVER_BASEURL } from '../baseUrl'
-import type { AuthCredentials, AuthOptions, AuthRequestOptions } from '../types/auth'
+import { baseURL } from '../baseUrl'
+import type { AuthRequestOptions } from '../types/auth'
 
 const ACCESS_TOKEN_EXPIRY = 3.75 // in 3 minutes 45 seconds
 
+// ─── Config ───────────────────────────────────────────────────────────────────
+//
+// Server-side Auth — connector credentials (cid + secret) → access token.
+// Use on the backend; never expose cid/secret to the client.
+//
+//   const auth = new Auth({ context, cid, secret, env })
+//   const token = await auth.getToken()
+
+export type AuthConfig = {
+	context: string
+	cid: string
+	secret: string
+	remoteOrigin?: string
+	env?: 'dev' | 'staging' | 'prod'
+	version?: number
+	/**
+	 * Operator uid to embed in the minted token's scope.
+	 *
+	 * Routes behind `isAllowed` look the caller up in the `operators`
+	 * collection by uid, so a token minted without one is rejected with
+	 * "Require <uid> generated accessToken" no matter how valid the connector
+	 * credentials are. Omit it for pure machine-to-machine access.
+	 */
+	uid?: string
+	autorefresh?: boolean
+	onNewToken?: ( token: string ) => void
+	/** Host to substitute for `localhost` in `dev` (Eg. a native emulator) */
+	devHostname?: string
+}
+
 type AuthResponse = {
   error: boolean
   message: string
-  token: string
+  data: {
+    token: string
+  }
 }
 
 export default class Auth {
   private version: number
-  private options: AuthOptions
-  protected creds: AuthCredentials
+  private env: AuthConfig['env']
+  private cid: string
+  private secret: string
+  private context: string
+  private uid?: string
+  private remoteOrigin?: string
   private refreshTimer?: NodeJS.Timeout
   private autorefresh?: boolean
   private onNewToken?: (token: string) => void
@@ -20,32 +56,29 @@ export default class Auth {
   private isRotating: boolean = false
   public accessToken?: string
 
-  constructor( creds: AuthCredentials, options?: AuthOptions ){
-    if( !creds ) throw new Error('Undefined Credentials. Check https://doc.dedot.io/sdk/auth')
-    if( !creds.context ) throw new Error('Undefined Context Reference. Check https://doc.dedot.io/sdk/auth')
-    if( !creds.remoteOrigin ) throw new Error('Undefined Remote Origin. Check https://doc.dedot.io/sdk/auth')
-    if( !creds.cid ) throw new Error('Undefined Connector ID. Check https://doc.dedot.io/sdk/auth')
-    if( !creds.secret ) throw new Error('Undefined Connector Secret. Check https://doc.dedot.io/sdk/auth')
-
-    this.creds = creds
-    this.options = options || { env: 'dev' }
-    
-    this.version = this.options.version || 1
-    this.baseURL = API_SERVER_BASEURL[ this.options.env || 'dev' ]
-    this.autorefresh = this.options.autorefresh || false
-    this.onNewToken = this.options.onNewToken
+  constructor( config: AuthConfig ){
+    if( !config )         throw new Error('Undefined config. Check https://doc.dedot.io/sdk/auth')
+    if( !config.context ) throw new Error('Undefined context. Check https://doc.dedot.io/sdk/auth')
+    if( !config.cid )     throw new Error('Undefined cid. Check https://doc.dedot.io/sdk/auth')
+    if( !config.secret )  throw new Error('Undefined secret. Check https://doc.dedot.io/sdk/auth')
+
+    this.context      = config.context
+    this.uid          = config.uid
+    this.cid          = config.cid
+    this.secret       = config.secret
+    this.remoteOrigin = config.remoteOrigin
+    this.env          = config.env || 'dev'
+    this.version      = config.version || 1
+    this.baseURL      = baseURL('API', this.env, config.devHostname )
+    this.autorefresh  = config.autorefresh || false
+    this.onNewToken   = config.onNewToken
   }
 
   private async request<T>({ url, ...options }: AuthRequestOptions ): Promise<T> {
     const rawOptions: any = {
       method: 'GET',
       headers: {
-        /**
-         * Default User agent for SDK request calls
-         * 
-         * NOTE: Later replace by latest SDK version
-         */
-        'origin': this.creds.remoteOrigin,
+        'origin': this.remoteOrigin,
         'de-user-agent': `De.remote/${this.version}.0`
       }
     }
@@ -68,7 +101,7 @@ export default class Auth {
   }
 
   private debug( ...args: any[] ){
-    this.options?.env === 'dev' && console.debug('[Auth]', ...args )
+    this.env === 'dev' && console.debug('[Auth]', ...args )
   }
   private error( ...args: any[] ){
     console.error('[Auth]', ...args )
@@ -99,15 +132,15 @@ export default class Auth {
     options: AuthRequestOptions = {
       url: '/access/token',
       method: 'POST',
-      body: this.creds
+      body: { context: this.context, cid: this.cid, secret: this.secret, remoteOrigin: this.remoteOrigin, ...( this.uid ? { uid: this.uid } : {} ) }
     },
-    { error, message, token } = await this.request<AuthResponse>( options )
+    { error, message, data } = await this.request<AuthResponse>( options )
     if( error ) throw new Error( message )
 
-    this.accessToken = token
+    this.accessToken = data.token
     this.scheduleRotation() // Schedule auto-refresh
     
-    return token
+    return data.token
   }
 
   async rotateToken(): Promise<string> {
@@ -127,23 +160,23 @@ export default class Auth {
       options: AuthRequestOptions = {
         url: '/access/token/rotate',
         method: 'PATCH',
-        body: { secret: this.creds.secret }
+        body: { secret: this.secret }
       },
-      { error, message, token } = await this.request<AuthResponse>( options )
+      { error, message, data } = await this.request<AuthResponse>( options )
       if( error ) throw new Error( message )
 
-      this.accessToken = token
+      this.accessToken = data.token
 
       // Notify callback listener
       if( typeof this.onNewToken === 'function' )
-        try { this.onNewToken( token ) }
+        try { this.onNewToken( data.token ) }
         catch( callbackError ){ this.error('[Auth] Error in onNewToken callback:', callbackError) }
 
       // Schedule next rotation
       this.scheduleRotation()
       
       this.debug('Token rotated successfully')
-      return token
+      return data.token
     }
     catch( error: any ){
       this.debug('Refresh access token failed:', error.message)

package/src/baseUrl.ts

@@ -1,13 +1,87 @@
+/**
+ * Service base URLs per environment.
+ *
+ * Only the `dev` hosts are overridable. A React Native app cannot reach the
+ * host machine on `localhost` -- the Android emulator maps it to 10.0.2.2, and
+ * a physical device needs the machine's LAN address -- so the platform entry
+ * resolves an appropriate host and passes it down as `devHostname`.
+ *
+ * The resolution deliberately lives in the caller rather than here: importing
+ * react-native's `Platform` at this level would drag the whole framework into
+ * the Node and browser builds.
+ */
+
+const DEV_PORTS = {
+	ASI: 44000,
+	RTS: 24800,
+	API: 24800,
+	IOT: 11011,
+	WSP: 22200
+}
 
 export const ASI_SERVER_BASEURL = {
-  dev: 'http://localhost:44000',
-  prod: 'https://auth.dedot.io'
+	dev:     `http://localhost:${DEV_PORTS.ASI}`,
+	staging: 'https://auth.staging.dedot.io',
+	prod:    'https://auth.dedot.io'
+}
+// Realtime Socket
+export const RTS_SERVER_BASEURL = {
+	dev:     `http://localhost:${DEV_PORTS.RTS}`,
+	staging: 'https://api.staging.dedot.io',
+	prod:    'https://api.dedot.io'
 }
 export const API_SERVER_BASEURL = {
-  dev: 'http://localhost:24800',
-  prod: 'https://api.dedot.io'
+	dev:     `http://localhost:${DEV_PORTS.API}`,
+	staging: 'https://api.staging.dedot.io',
+	prod:    'https://api.dedot.io'
+}
+/**
+ * de.workspace — the control plane, a separate service from de.arch.
+ *
+ * It is not reachable through the API host: de.arch serves no `/workspace`
+ * routes, so a client pointed there gets 404 for the whole surface.
+ *
+ * The staging and production hosts follow the naming of the other services
+ * (auth.dedot.io, iot.dedot.io). Confirm them against the deployment before
+ * relying on them, and pass `baseUrl` to address a host that differs — which
+ * is also what a self-hosted De. needs, and what a dev machine running
+ * de.workspace on a port other than 22200 needs.
+ */
+export const WSP_SERVER_BASEURL = {
+	dev:     `http://localhost:${DEV_PORTS.WSP}`,
+	staging: 'https://workspace.staging.dedot.io',
+	prod:    'https://workspace.dedot.io'
 }
 export const IOT_SERVER_BASEURL = {
-  dev: 'http://localhost:11011',
-  prod: 'https://iot.dedot.io'
-}
+	dev:     `http://localhost:${DEV_PORTS.IOT}`,
+	staging: 'https://iot.staging.dedot.io',
+	prod:    'https://iot.dedot.io'
+}
+
+export type ServerEnv = 'dev' | 'staging' | 'prod'
+export type ServerName = keyof typeof DEV_PORTS
+
+const BASEURLS = {
+	ASI: ASI_SERVER_BASEURL,
+	RTS: RTS_SERVER_BASEURL,
+	API: API_SERVER_BASEURL,
+	IOT: IOT_SERVER_BASEURL,
+	WSP: WSP_SERVER_BASEURL
+}
+
+/**
+ * Resolve a service's base URL for an environment.
+ *
+ * @param server - Which service to address
+ * @param env - (Default: `dev`) Target environment
+ * @param devHostname - (Optional) Host to substitute for `localhost` in `dev`
+ * @return - Base URL
+ */
+export function baseURL( server: ServerName, env: ServerEnv = 'dev', devHostname?: string ): string {
+	const url = BASEURLS[ server ][ env ]
+
+	// Staging and production are fixed hosts -- an override there is meaningless
+	return env === 'dev' && devHostname
+					? `http://${devHostname}:${DEV_PORTS[ server ]}`
+					: url
+}