@objectstack/client 0.9.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @objectstack/client
 
+## 1.0.0
+
+### Major Changes
+
+- Major version release for ObjectStack Protocol v1.0.
+  - Stabilized Protocol Definitions
+  - Enhanced Runtime Plugin Support
+  - Fixed Type Compliance across Monorepo
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@1.0.0
+  - @objectstack/core@1.0.0
+
+## 0.9.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@0.9.2
+  - @objectstack/core@0.9.2
+
 ## 0.9.1
 
 ### Patch Changes

package/README.md

@@ -12,6 +12,17 @@ The official TypeScript client for ObjectStack.
 - **View Storage**: Save, load, and share custom UI view configurations.
 - **Standardized Errors**: Machine-readable error codes with retry guidance.
 
+## 🤖 AI Development Context
+
+**Role**: Browser/Node Client SDK
+**Usage**:
+- Use this in Frontend Apps (React, etc.) or external Node scripts.
+- Interacts with `packages/runtime` over HTTP.
+
+**Key namespaces**:
+- `client.meta`: Metadata operations.
+- `client.data`: Data operations.
+
 ## Installation
 
 ```bash

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
-import { BatchUpdateRequest, BatchUpdateResponse, BatchOptions, MetadataCacheRequest, MetadataCacheResponse, StandardErrorCode, ErrorCategory, GetDiscoveryResponse, GetMetaTypesResponse, GetMetaItemsResponse } from '@objectstack/spec/api';
+import { BatchUpdateRequest, BatchUpdateResponse, BatchOptions, MetadataCacheRequest, MetadataCacheResponse, StandardErrorCode, ErrorCategory, GetDiscoveryResponse, GetMetaTypesResponse, GetMetaItemsResponse, LoginRequest, SessionResponse, FileUploadResponse } from '@objectstack/spec/api';
 import { Logger } from '@objectstack/core';
 export interface ClientConfig {
     baseUrl: string;
@@ -56,8 +56,24 @@ export declare class ObjectStackClient {
     connect(): Promise<{
         version: string;
         apiName: string;
-        capabilities?: string[] | undefined;
-        endpoints?: Record<string, string> | undefined;
+        capabilities?: {
+            search: boolean;
+            files: boolean;
+            graphql: boolean;
+            analytics: boolean;
+            hub: boolean;
+            websockets: boolean;
+        } | undefined;
+        endpoints?: {
+            data: string;
+            metadata: string;
+            auth: string;
+            graphql?: string | undefined;
+            storage?: string | undefined;
+            automation?: string | undefined;
+            analytics?: string | undefined;
+            hub?: string | undefined;
+        } | undefined;
     }>;
     /**
      * Metadata Operations
@@ -92,6 +108,47 @@ export declare class ObjectStackClient {
         getCached: (name: string, cacheOptions?: MetadataCacheRequest) => Promise<MetadataCacheResponse>;
         getView: (object: string, type?: "list" | "form") => Promise<any>;
     };
+    /**
+     * Analytics Services
+     */
+    analytics: {
+        query: (payload: any) => Promise<any>;
+        meta: (cube: string) => Promise<any>;
+        explain: (payload: any) => Promise<any>;
+    };
+    /**
+     * Hub Management Services
+     */
+    hub: {
+        spaces: {
+            list: () => Promise<any>;
+            create: (payload: any) => Promise<any>;
+        };
+        plugins: {
+            install: (pkg: string, version?: string) => Promise<any>;
+        };
+    };
+    /**
+     * Authentication Services
+     */
+    auth: {
+        login: (request: LoginRequest) => Promise<SessionResponse>;
+        logout: () => Promise<void>;
+        me: () => Promise<SessionResponse>;
+    };
+    /**
+     * Storage Services
+     */
+    storage: {
+        upload: (file: any, scope?: string) => Promise<FileUploadResponse>;
+        getDownloadUrl: (fileId: string) => Promise<string>;
+    };
+    /**
+     * Automation Services
+     */
+    automation: {
+        trigger: (triggerName: string, payload: any) => Promise<any>;
+    };
     /**
      * Data Operations
      */
@@ -134,7 +191,7 @@ export declare class ObjectStackClient {
     private fetch;
     /**
      * 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;
 }

package/dist/index.js

@@ -88,6 +88,148 @@ export class ObjectStackClient {
                 return res.json();
             }
         };
+        /**
+         * Analytics Services
+         */
+        this.analytics = {
+            query: async (payload) => {
+                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) => {
+                const route = this.getRoute('analytics');
+                const res = await this.fetch(`${this.baseUrl}${route}/meta/${cube}`);
+                return res.json();
+            },
+            explain: async (payload) => {
+                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
+         */
+        this.hub = {
+            spaces: {
+                list: async () => {
+                    const route = this.getRoute('hub');
+                    const res = await this.fetch(`${this.baseUrl}${route}/spaces`);
+                    return res.json();
+                },
+                create: async (payload) => {
+                    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, version) => {
+                    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();
+                }
+            }
+        };
+        /**
+         * Authentication Services
+         */
+        this.auth = {
+            login: async (request) => {
+                const route = this.getRoute('auth');
+                const res = await this.fetch(`${this.baseUrl}${route}/login`, {
+                    method: 'POST',
+                    body: JSON.stringify(request)
+                });
+                const data = await res.json();
+                // Auto-set token if present in response
+                if (data.data?.token) {
+                    this.token = data.data.token;
+                }
+                return data;
+            },
+            logout: async () => {
+                const route = this.getRoute('auth');
+                await this.fetch(`${this.baseUrl}${route}/logout`, { method: 'POST' });
+                this.token = undefined;
+            },
+            me: async () => {
+                const route = this.getRoute('auth');
+                const res = await this.fetch(`${this.baseUrl}${route}/me`);
+                return res.json();
+            }
+        };
+        /**
+         * Storage Services
+         */
+        this.storage = {
+            upload: async (file, scope = 'user') => {
+                // 1. Get Presigned URL
+                const presignedReq = {
+                    filename: file.name,
+                    mimeType: file.type,
+                    size: file.size,
+                    scope
+                };
+                const route = this.getRoute('storage');
+                const presignedRes = await this.fetch(`${this.baseUrl}${route}/upload/presigned`, {
+                    method: 'POST',
+                    body: JSON.stringify(presignedReq)
+                });
+                const { data: presigned } = await presignedRes.json();
+                // 2. Upload to Cloud directly (Bypass API Middleware to avoid Auth headers if using S3)
+                // Use fetchImpl directly
+                const uploadRes = await this.fetchImpl(presigned.uploadUrl, {
+                    method: presigned.method,
+                    headers: presigned.headers,
+                    body: file
+                });
+                if (!uploadRes.ok) {
+                    throw new Error(`Storage Upload Failed: ${uploadRes.statusText}`);
+                }
+                // 3. Complete Upload
+                const completeReq = {
+                    fileId: presigned.fileId
+                };
+                const completeRes = await this.fetch(`${this.baseUrl}${route}/upload/complete`, {
+                    method: 'POST',
+                    body: JSON.stringify(completeReq)
+                });
+                return completeRes.json();
+            },
+            getDownloadUrl: async (fileId) => {
+                const route = this.getRoute('storage');
+                const res = await this.fetch(`${this.baseUrl}${route}/files/${fileId}/url`);
+                const data = await res.json();
+                return data.url;
+            }
+        };
+        /**
+         * Automation Services
+         */
+        this.automation = {
+            trigger: async (triggerName, payload) => {
+                const route = this.getRoute('automation');
+                const res = await this.fetch(`${this.baseUrl}${route}/trigger/${triggerName}`, {
+                    method: 'POST',
+                    body: JSON.stringify(payload)
+                });
+                return res.json();
+            }
+        };
         /**
          * Data Operations
          */
@@ -325,15 +467,25 @@ 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
      */
     getRoute(type) {
-        // Use conventional ObjectStack API paths
+        // 1. Use discovered routes if available
+        // Note: Spec uses 'endpoints', mapped dynamically
+        if (this.discoveryInfo?.endpoints && this.discoveryInfo.endpoints[type]) {
+            return this.discoveryInfo.endpoints[type];
+        }
+        // 2. Fallback to conventions
+        // Note: HttpDispatcher expects /metadata, not /meta
         const routeMap = {
             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',
+            automation: '/api/v1/automation'
         };
         return routeMap[type] || `/api/v1/${type}`;
     }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@objectstack/client",
-  "version": "0.9.1",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
   "description": "Official Client SDK for ObjectStack Protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/spec": "0.9.1",
-    "@objectstack/core": "0.9.1"
+    "@objectstack/spec": "1.0.0",
+    "@objectstack/core": "1.0.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/client.test.ts

@@ -46,7 +46,7 @@ describe('ObjectStackClient', () => {
         });
 
         const result = await client.meta.getTypes();
-        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta', expect.any(Object));
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/metadata', expect.any(Object));
         expect(result.types).toEqual(['object', 'plugin', 'view']);
     });
 
@@ -65,7 +65,7 @@ describe('ObjectStackClient', () => {
         });
 
         const result = await client.meta.getItems('object');
-        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta/object', expect.any(Object));
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/metadata/object', expect.any(Object));
         expect(result.type).toBe('object');
         expect(result.items).toHaveLength(2);
     });
@@ -85,7 +85,7 @@ describe('ObjectStackClient', () => {
         });
 
         const result = await client.meta.getItem('object', 'customer');
-        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta/object/customer', expect.any(Object));
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/metadata/object/customer', expect.any(Object));
         expect(result.name).toBe('customer');
     });
 });

package/src/index.ts

@@ -11,7 +11,13 @@ import {
   ErrorCategory,
   GetDiscoveryResponse,
   GetMetaTypesResponse,
-  GetMetaItemsResponse
+  GetMetaItemsResponse,
+  LoginRequest,
+  SessionResponse,
+  GetPresignedUrlRequest,
+  PresignedUrlResponse,
+  CompleteUploadRequest,
+  FileUploadResponse
 } from '@objectstack/spec/api';
 import { Logger, createLogger } from '@objectstack/core';
 
@@ -208,6 +214,161 @@ 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();
+        }
+    }
+  };
+
+  /**
+   * Authentication Services
+   */
+  auth = {
+    login: async (request: LoginRequest): Promise<SessionResponse> => {
+        const route = this.getRoute('auth');
+        const res = await this.fetch(`${this.baseUrl}${route}/login`, {
+            method: 'POST',
+            body: JSON.stringify(request)
+        });
+        const data = await res.json();
+        // Auto-set token if present in response
+        if (data.data?.token) {
+            this.token = data.data.token;
+        }
+        return data;
+    },
+    
+    logout: async () => {
+        const route = this.getRoute('auth');
+        await this.fetch(`${this.baseUrl}${route}/logout`, { method: 'POST' });
+        this.token = undefined;
+    },
+
+    me: async (): Promise<SessionResponse> => {
+        const route = this.getRoute('auth');
+        const res = await this.fetch(`${this.baseUrl}${route}/me`);
+        return res.json();
+    }
+  };
+
+  /**
+   * Storage Services
+   */
+  storage = {
+    upload: async (file: any, scope: string = 'user'): Promise<FileUploadResponse> => {
+        // 1. Get Presigned URL
+        const presignedReq: GetPresignedUrlRequest = {
+            filename: file.name,
+            mimeType: file.type,
+            size: file.size,
+            scope
+        };
+        
+        const route = this.getRoute('storage');
+        const presignedRes = await this.fetch(`${this.baseUrl}${route}/upload/presigned`, {
+            method: 'POST',
+            body: JSON.stringify(presignedReq)
+        });
+        const { data: presigned } = await presignedRes.json() as { data: PresignedUrlResponse['data'] };
+
+        // 2. Upload to Cloud directly (Bypass API Middleware to avoid Auth headers if using S3)
+        // Use fetchImpl directly
+        const uploadRes = await this.fetchImpl(presigned.uploadUrl, {
+            method: presigned.method,
+            headers: presigned.headers,
+            body: file
+        });
+
+        if (!uploadRes.ok) {
+            throw new Error(`Storage Upload Failed: ${uploadRes.statusText}`);
+        }
+
+        // 3. Complete Upload
+        const completeReq: CompleteUploadRequest = {
+            fileId: presigned.fileId
+        };
+        const completeRes = await this.fetch(`${this.baseUrl}${route}/upload/complete`, {
+            method: 'POST',
+            body: JSON.stringify(completeReq)
+        });
+        
+        return completeRes.json();
+    },
+    
+    getDownloadUrl: async (fileId: string): Promise<string> => {
+        const route = this.getRoute('storage');
+        const res = await this.fetch(`${this.baseUrl}${route}/files/${fileId}/url`);
+        const data = await res.json();
+        return data.url;
+    }
+  };
+
+  /**
+   * Automation Services
+   */
+  automation = {
+      trigger: async (triggerName: string, payload: any) => {
+          const route = this.getRoute('automation');
+          const res = await this.fetch(`${this.baseUrl}${route}/trigger/${triggerName}`, {
+              method: 'POST',
+              body: JSON.stringify(payload)
+          });
+          return res.json();
+      }
+  };
+
   /**
    * Data Operations
    */
@@ -443,15 +604,26 @@ 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' | 'automation'): string {
+    // 1. Use discovered routes if available
+    // Note: Spec uses 'endpoints', mapped dynamically
+    if (this.discoveryInfo?.endpoints && (this.discoveryInfo.endpoints as any)[type]) {
+        return (this.discoveryInfo.endpoints 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',
+      automation: '/api/v1/automation'
     };
     
     return routeMap[type] || `/api/v1/${type}`;