@de./sdk 1.0.5 → 2.0.0

package/src/allend/Workspace/index.ts

@@ -1,6 +1,9 @@
-import type { AccessOptions } from '../../types/access'
-import type { HTTPResponse } from '../../types'
+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
@@ -8,13 +11,39 @@ export type WorkspaceConfig = {
 	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: workspace management API — de.arch /workspace routes.
-// Covers admins, connectors, billings, and provider registrations
-// (LSPs, CSPs, IoTSPs, developers).
+// 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.
 //
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -28,86 +57,246 @@ export default class Workspace extends AccessManager {
 			accessToken:  config.accessToken,
 			env:          config.env      || 'dev',
 			platform:     config.platform || 'proxy',
-			remoteOrigin: config.remoteOrigin
+			remoteOrigin: config.remoteOrigin,
+			timeout:      config.timeout,
+			baseUrl:      config.baseUrl,
+			session:      config.session
 		}
-		super( access, 'API' )
+		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 } : {}) })
 	}
 
-	// ── Index ─────────────────────────────────────────────────────────────────
+	// ── Workspace ─────────────────────────────────────────────────────────────
 
-	async get(): Promise<any> {
-		const { error, message, data } = await this.request<HTTPResponse<any>>({
-			url: '/workspace',
-			method: 'GET'
-		})
-		if( error ) throw new Error( message )
-		return data
+	/**
+	 * 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 )
 	}
 
-	// ── Admins ────────────────────────────────────────────────────────────────
+	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 listAdmins( params?: Record<string, any> ): Promise<any[]> {
-		const qs = params ? '?' + new URLSearchParams( params ).toString() : ''
-		const { error, message, data } = await this.request<HTTPResponse<{ admins: any[] }>>({
-			url: `/workspace/admins${qs}`,
-			method: 'GET'
-		})
-		if( error ) throw new Error( message )
-		return data.admins
+	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 ────────────────────────────────────────────────────────────
 
-	async listConnectors( params?: Record<string, any> ): Promise<any[]> {
-		const qs = params ? '?' + new URLSearchParams( params ).toString() : ''
-		const { error, message, data } = await this.request<HTTPResponse<{ connectors: any[] }>>({
-			url: `/workspace/connectors${qs}`,
-			method: 'GET'
-		})
-		if( error ) throw new Error( message )
-		return data.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 getConnector( connectorId: string ): Promise<any> {
-		const { error, message, data } = await this.request<HTTPResponse<{ connector: any }>>({
-			url: `/workspace/connectors/${connectorId}`,
-			method: 'GET'
-		})
-		if( error ) throw new Error( message )
-		return data.connector
+	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 )}`)
 	}
 
-	// ── Billings ──────────────────────────────────────────────────────────────
+	async getConnector( wid: string, ctype: ContextType, xcode: string, id: string ): Promise<Res<{ connector: Connector }>> {
+		return this.call('GET', `/${wid}/${ctype}/${xcode}/connectors/${id}`)
+	}
 
-	async getBillings( params?: Record<string, any> ): Promise<any> {
-		const qs = params ? '?' + new URLSearchParams( params ).toString() : ''
-		const { error, message, data } = await this.request<HTTPResponse<any>>({
-			url: `/workspace/billings${qs}`,
-			method: 'GET'
-		})
-		if( error ) throw new Error( message )
-		return data
+	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 )
 	}
 
-	// ── Providers ─────────────────────────────────────────────────────────────
+	/**
+	 * 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 listLSPs( params?: Record<string, any> ): Promise<any[]> {
-		const qs = params ? '?' + new URLSearchParams( params ).toString() : ''
-		const { error, message, data } = await this.request<HTTPResponse<{ lsps: any[] }>>({
-			url: `/workspace/providers/lsps${qs}`,
-			method: 'GET'
-		})
-		if( error ) throw new Error( message )
-		return data.lsps
-	}
-
-	async listCSPs( params?: Record<string, any> ): Promise<any[]> {
-		const qs = params ? '?' + new URLSearchParams( params ).toString() : ''
-		const { error, message, data } = await this.request<HTTPResponse<{ csps: any[] }>>({
-			url: `/workspace/providers/csps${qs}`,
-			method: 'GET'
-		})
-		if( error ) throw new Error( message )
-		return data.csps
+	async acceptInvitation( wid: string, body: { vcode: string } ): Promise<Res<any>> {
+		return this.call('POST', `/${wid}/invitation/accept`, body )
 	}
 }

package/src/allend/index.ts

@@ -6,6 +6,7 @@ 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'
 
@@ -22,6 +23,7 @@ export {
 	type CustomerConfig,
 	Agent,
 	type AgentConfig,
+	type AgentRealtimeContext,
 	Queries,
 	type QueriesConfig,
 	Utilities,

package/src/backend/Auth.ts

@@ -1,4 +1,4 @@
-import { API_SERVER_BASEURL } from '../baseUrl'
+import { baseURL } from '../baseUrl'
 import type { AuthRequestOptions } from '../types/auth'
 
 const ACCESS_TOKEN_EXPIRY = 3.75 // in 3 minutes 45 seconds
@@ -18,8 +18,19 @@ export type AuthConfig = {
 	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 = {
@@ -36,6 +47,7 @@ export default class Auth {
   private cid: string
   private secret: string
   private context: string
+  private uid?: string
   private remoteOrigin?: string
   private refreshTimer?: NodeJS.Timeout
   private autorefresh?: boolean
@@ -51,12 +63,13 @@ export default class 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      = API_SERVER_BASEURL[ this.env ]
+    this.baseURL      = baseURL('API', this.env, config.devHostname )
     this.autorefresh  = config.autorefresh || false
     this.onNewToken   = config.onNewToken
   }
@@ -119,7 +132,7 @@ export default class Auth {
     options: AuthRequestOptions = {
       url: '/access/token',
       method: 'POST',
-      body: { context: this.context, cid: this.cid, secret: this.secret, remoteOrigin: this.remoteOrigin }
+      body: { context: this.context, cid: this.cid, secret: this.secret, remoteOrigin: this.remoteOrigin, ...( this.uid ? { uid: this.uid } : {} ) }
     },
     { error, message, data } = await this.request<AuthResponse>( options )
     if( error ) throw new Error( message )

package/src/baseUrl.ts

@@ -1,21 +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',
+	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:24800',
+	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',
+	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',
+	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
+}