feat(service-registry): add service registry documentation and enhance client SDK with analytics and hub management services

Author: hotlong

content/docs/references/system/index.mdx

@@ -25,6 +25,7 @@ This section contains all protocol schemas for the system layer of ObjectStack.
   <Card href="./notification" title="Notification" description="Source: packages/spec/src/system/notification.zod.ts" />
   <Card href="./object-storage" title="Object Storage" description="Source: packages/spec/src/system/object-storage.zod.ts" />
   <Card href="./search-engine" title="Search Engine" description="Source: packages/spec/src/system/search-engine.zod.ts" />
+  <Card href="./service-registry" title="Service Registry" description="Source: packages/spec/src/system/service-registry.zod.ts" />
   <Card href="./tracing" title="Tracing" description="Source: packages/spec/src/system/tracing.zod.ts" />
   <Card href="./translation" title="Translation" description="Source: packages/spec/src/system/translation.zod.ts" />
   <Card href="./worker" title="Worker" description="Source: packages/spec/src/system/worker.zod.ts" />

content/docs/references/system/meta.json

@@ -18,6 +18,7 @@
     "notification",
     "object-storage",
     "search-engine",
+    "service-registry",
     "tracing",
     "translation",
     "worker"

packages/client/src/index.ts

@@ -208,6 +208,64 @@ export class ObjectStackClient {
     }
   };
 
+  /**
+   * Analytics Services
+   */
+  analytics = {
+    query: async (payload: any) => {
+      const route = this.getRoute('analytics');
+      const res = await this.fetch(`${this.baseUrl}${route}/query`, {
+         method: 'POST',
+         body: JSON.stringify(payload)
+      });
+      return res.json();
+    },
+    meta: async (cube: string) => {
+        const route = this.getRoute('analytics');
+        const res = await this.fetch(`${this.baseUrl}${route}/meta/${cube}`);
+        return res.json();
+    },
+    explain: async (payload: any) => {
+        const route = this.getRoute('analytics');
+        const res = await this.fetch(`${this.baseUrl}${route}/explain`, {
+            method: 'POST',
+            body: JSON.stringify(payload)
+         });
+         return res.json();
+    }
+  };
+
+  /**
+   * Hub Management Services
+   */
+  hub = {
+    spaces: {
+        list: async () => {
+            const route = this.getRoute('hub');
+            const res = await this.fetch(`${this.baseUrl}${route}/spaces`);
+            return res.json();
+        },
+        create: async (payload: any) => {
+            const route = this.getRoute('hub');
+            const res = await this.fetch(`${this.baseUrl}${route}/spaces`, {
+                method: 'POST',
+                body: JSON.stringify(payload)
+            });
+            return res.json();
+        }
+    },
+    plugins: {
+        install: async (pkg: string, version?: string) => {
+            const route = this.getRoute('hub');
+            const res = await this.fetch(`${this.baseUrl}${route}/plugins/install`, {
+                method: 'POST',
+                body: JSON.stringify({ pkg, version })
+            });
+            return res.json();
+        }
+    }
+  };
+
   /**
    * Data Operations
    */
@@ -443,15 +501,24 @@ export class ObjectStackClient {
 
   /**
    * Get the conventional route path for a given API endpoint type
-   * ObjectStack uses standard conventions: /api/v1/data, /api/v1/meta, /api/v1/ui
+   * ObjectStack uses standard conventions: /api/v1/data, /api/v1/metadata, /api/v1/ui
    */
-  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth'): string {
-    // Use conventional ObjectStack API paths
+  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth' | 'analytics' | 'hub' | 'storage'): string {
+    // 1. Use discovered routes if available
+    if (this.discoveryInfo?.routes && (this.discoveryInfo.routes as any)[type]) {
+        return (this.discoveryInfo.routes as any)[type];
+    }
+
+    // 2. Fallback to conventions
+    // Note: HttpDispatcher expects /metadata, not /meta
     const routeMap: Record<string, string> = {
       data: '/api/v1/data',
-      metadata: '/api/v1/meta',
+      metadata: '/api/v1/metadata',
       ui: '/api/v1/ui',
-      auth: '/api/v1/auth'
+      auth: '/api/v1/auth',
+      analytics: '/api/v1/analytics',
+      hub: '/api/v1/hub',
+      storage: '/api/v1/storage'
     };
 
     return routeMap[type] || `/api/v1/${type}`;

packages/runtime/src/http-dispatcher.ts

@@ -1,5 +1,5 @@
 import { ObjectKernel } from '@objectstack/core';
-import { CoreServiceName } from '@objectstack/spec/src/system/service-registry.zod';
+import { CoreServiceName } from '@objectstack/spec/system';
 
 export interface HttpProtocolContext {
     request: any;

packages/spec/json-schema/system/CoreServiceName.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/CoreServiceName",
+  "definitions": {
+    "CoreServiceName": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

packages/spec/json-schema/system/KernelServiceMap.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/KernelServiceMap",
+  "definitions": {
+    "KernelServiceMap": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

packages/spec/json-schema/system/ServiceConfig.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/ServiceConfig",
+  "definitions": {
+    "ServiceConfig": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

packages/spec/json-schema/system/ServiceStatus.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/ServiceStatus",
+  "definitions": {
+    "ServiceStatus": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

packages/spec/src/system/index.ts

@@ -39,3 +39,4 @@ export * from './collaboration.zod';
 // Types
 export * from './types';
 export * from './service-registry.zod';
+export * from './service-registry.zod';

verify-refactor.ts

@@ -0,0 +1,58 @@
+
+import { ObjectKernel, ObjectRegistry } from './packages/objectql/src';
+import { CoreServiceName } from './packages/spec/src/system/service-registry.zod';
+import { HttpDispatcher } from './packages/runtime/src/http-dispatcher';
+import { ObjectStackClient } from './packages/client/src';
+
+async function verify() {
+    console.log("--- Verifying ObjectStack Components ---");
+
+    // 1. ObjectQL Engine & Registry
+    console.log("\n1. Testing ObjectQL Engine Status:");
+    const registry = new ObjectRegistry();
+    const kernel = new ObjectKernel(registry);
+    const status = kernel.getStatus();
+    console.log("Kernel Status:", JSON.stringify(status, null, 2));
+
+    if (status.service !== CoreServiceName.data) {
+        console.error("FAIL: Kernel service name mismatch.");
+    } else {
+        console.log("PASS: Kernel service name matches.");
+    }
+
+
+    // 2. Runtime Dispatcher
+    console.log("\n2. Testing Runtime HttpDispatcher:");
+    const dispatcher = new HttpDispatcher();
+    const dataService = dispatcher.getService(CoreServiceName.data);
+    const analyticsService = dispatcher.getService(CoreServiceName.analytics);
+
+    console.log(`Data Service URL: ${dataService?.url}`);
+    console.log(`Analytics Service URL: ${analyticsService?.url}`);
+
+    if (dataService?.url && analyticsService?.url) {
+         console.log("PASS: Services resolved correctly.");
+    } else {
+         console.error("FAIL: Service resolution failed.");
+    }
+
+    // 3. Client SDK
+     console.log("\n3. Testing Client SDK Structure:");
+     const client = new ObjectStackClient({
+         baseUrl: 'http://localhost:5000'
+     });
+
+     if (typeof client.analytics === 'object' && typeof client.hub === 'object') {
+         console.log("PASS: Client has 'analytics' and 'hub' namespaces.");
+         if (typeof client.analytics.query === 'function' && typeof client.hub.spaces.list === 'function') {
+              console.log("PASS: Client methods are functions.");
+         } else {
+              console.error("FAIL: Client methods are missing.");
+         }
+     } else {
+          console.error("FAIL: Client missing namespaces.");
+     }
+
+}
+
+verify().catch(console.error);