@objectstack/client 0.8.2 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @objectstack/client
 
+## 0.9.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements. All packages updated with unified versioning.
+- Updated dependencies
+  - @objectstack/spec@0.9.1
+  - @objectstack/core@0.9.1
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -157,10 +157,48 @@ try {
 }
 ```
 
-Common error codes:
-- `validation_error`: Input validation failed
-- `unauthenticated`: Authentication required
-- `permission_denied`: Insufficient permissions
-- `resource_not_found`: Resource does not exist
-- `rate_limit_exceeded`: Too many requests
+### Error Code Reference
+
+#### Client Errors (4xx)
+
+| Error Code | HTTP Status | Retryable | Description |
+|------------|-------------|-----------|-------------|
+| `validation_error` | 400 | No | Input validation failed. Check error.details for field-specific errors |
+| `unauthenticated` | 401 | No | Authentication required. Provide valid token |
+| `permission_denied` | 403 | No | Insufficient permissions for this operation |
+| `resource_not_found` | 404 | No | Resource does not exist. Verify object name or record ID |
+| `conflict` | 409 | No | Resource conflict (e.g., duplicate unique field) |
+| `rate_limit_exceeded` | 429 | Yes | Too many requests. Wait before retrying |
+
+#### Server Errors (5xx)
+
+| Error Code | HTTP Status | Retryable | Description |
+|------------|-------------|-----------|-------------|
+| `internal_error` | 500 | Yes | Server encountered an error. Retry with backoff |
+| `service_unavailable` | 503 | Yes | Service temporarily unavailable. Retry later |
+| `gateway_timeout` | 504 | Yes | Request timeout. Consider increasing timeout or retrying |
+
+**Retry Strategy Example:**
+
+```typescript
+async function retryableRequest<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error: any) {
+      if (!error.retryable || i === maxRetries - 1) {
+        throw error;
+      }
+      // Exponential backoff
+      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+
+// Usage
+const data = await retryableRequest(() => 
+  client.data.create('todo_task', { subject: 'Task' })
+);
+```
 

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 } from '@objectstack/spec/api';
+import { BatchUpdateRequest, BatchUpdateResponse, BatchOptions, MetadataCacheRequest, MetadataCacheResponse, StandardErrorCode, ErrorCategory, GetDiscoveryResponse, GetMetaTypesResponse, GetMetaItemsResponse } from '@objectstack/spec/api';
 import { Logger } from '@objectstack/core';
 export interface ClientConfig {
     baseUrl: string;
@@ -17,16 +17,11 @@ export interface ClientConfig {
      */
     debug?: boolean;
 }
-export interface DiscoveryResult {
-    routes: {
-        discovery: string;
-        metadata: string;
-        data: string;
-        auth: string;
-        ui: string;
-    };
-    capabilities?: Record<string, boolean>;
-}
+/**
+ * Discovery Result
+ * Re-export from @objectstack/spec/api for convenience
+ */
+export type DiscoveryResult = GetDiscoveryResponse;
 export interface QueryOptions {
     select?: string[];
     filters?: Record<string, any>;
@@ -52,18 +47,44 @@ export declare class ObjectStackClient {
     private baseUrl;
     private token?;
     private fetchImpl;
-    private routes?;
+    private discoveryInfo?;
     private logger;
     constructor(config: ClientConfig);
     /**
-     * Initialize the client by discovering server capabilities and routes.
+     * Initialize the client by discovering server capabilities.
      */
-    connect(): Promise<DiscoveryResult>;
+    connect(): Promise<{
+        version: string;
+        apiName: string;
+        capabilities?: string[] | undefined;
+        endpoints?: Record<string, string> | undefined;
+    }>;
     /**
      * Metadata Operations
      */
     meta: {
+        /**
+         * Get all available metadata types
+         * Returns types like 'object', 'plugin', 'view', etc.
+         */
+        getTypes: () => Promise<GetMetaTypesResponse>;
+        /**
+         * Get all items of a specific metadata type
+         * @param type - Metadata type name (e.g., 'object', 'plugin')
+         */
+        getItems: (type: string) => Promise<GetMetaItemsResponse>;
+        /**
+         * Get a specific object definition by name
+         * @deprecated Use `getItem('object', name)` instead for consistency with spec protocol
+         * @param name - Object name (snake_case identifier)
+         */
         getObject: (name: string) => Promise<any>;
+        /**
+         * Get a specific metadata item by type and name
+         * @param type - Metadata type (e.g., 'object', 'plugin')
+         * @param name - Item name (snake_case identifier)
+         */
+        getItem: (type: string, name: string) => Promise<any>;
         /**
          * Get object metadata with cache support
          * Supports ETag-based conditional requests for efficient caching
@@ -111,7 +132,11 @@ export declare class ObjectStackClient {
      */
     private isFilterAST;
     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
+     */
     private getRoute;
 }
 export { QueryBuilder, FilterBuilder, createQuery, createFilter } from './query-builder';
-export type { BatchUpdateRequest, BatchUpdateResponse, UpdateManyRequest, DeleteManyRequest, BatchOptions, BatchRecord, BatchOperationResult, MetadataCacheRequest, MetadataCacheResponse, StandardErrorCode, ErrorCategory } from '@objectstack/spec/api';
+export type { BatchUpdateRequest, BatchUpdateResponse, UpdateManyRequest, DeleteManyRequest, BatchOptions, BatchRecord, BatchOperationResult, MetadataCacheRequest, MetadataCacheResponse, StandardErrorCode, ErrorCategory, GetDiscoveryResponse, GetMetaTypesResponse, GetMetaItemsResponse } from '@objectstack/spec/api';

package/dist/index.js

@@ -5,11 +5,44 @@ export class ObjectStackClient {
          * Metadata Operations
          */
         this.meta = {
+            /**
+             * Get all available metadata types
+             * Returns types like 'object', 'plugin', 'view', etc.
+             */
+            getTypes: async () => {
+                const route = this.getRoute('metadata');
+                const res = await this.fetch(`${this.baseUrl}${route}`);
+                return res.json();
+            },
+            /**
+             * Get all items of a specific metadata type
+             * @param type - Metadata type name (e.g., 'object', 'plugin')
+             */
+            getItems: async (type) => {
+                const route = this.getRoute('metadata');
+                const res = await this.fetch(`${this.baseUrl}${route}/${type}`);
+                return res.json();
+            },
+            /**
+             * Get a specific object definition by name
+             * @deprecated Use `getItem('object', name)` instead for consistency with spec protocol
+             * @param name - Object name (snake_case identifier)
+             */
             getObject: async (name) => {
                 const route = this.getRoute('metadata');
                 const res = await this.fetch(`${this.baseUrl}${route}/object/${name}`);
                 return res.json();
             },
+            /**
+             * Get a specific metadata item by type and name
+             * @param type - Metadata type (e.g., 'object', 'plugin')
+             * @param name - Item name (snake_case identifier)
+             */
+            getItem: async (type, name) => {
+                const route = this.getRoute('metadata');
+                const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`);
+                return res.json();
+            },
             /**
              * Get object metadata with cache support
              * Supports ETag-based conditional requests for efficient caching
@@ -212,18 +245,18 @@ export class ObjectStackClient {
         this.logger.debug('ObjectStack client created', { baseUrl: this.baseUrl });
     }
     /**
-     * Initialize the client by discovering server capabilities and routes.
+     * Initialize the client by discovering server capabilities.
      */
     async connect() {
         this.logger.debug('Connecting to ObjectStack server', { baseUrl: this.baseUrl });
         try {
-            // Connect to the discovery endpoint
-            // During boot, we might not know routes, so we check convention /api/v1 first
+            // Connect to the discovery endpoint at /api/v1
             const res = await this.fetch(`${this.baseUrl}/api/v1`);
             const data = await res.json();
-            this.routes = data.routes;
+            this.discoveryInfo = data;
             this.logger.info('Connected to ObjectStack server', {
-                routes: Object.keys(data.routes || {}),
+                version: data.version,
+                apiName: data.apiName,
                 capabilities: data.capabilities
             });
             return data;
@@ -290,16 +323,19 @@ export class ObjectStackClient {
         }
         return res;
     }
-    getRoute(key) {
-        if (!this.routes) {
-            // Fallback for strictness, but we allow bootstrapping
-            this.logger.warn('Accessing route before connect()', {
-                route: key,
-                fallback: `/api/v1/${key}`
-            });
-            return `/api/v1/${key}`;
-        }
-        return this.routes[key] || `/api/v1/${key}`;
+    /**
+     * Get the conventional route path for a given API endpoint type
+     * ObjectStack uses standard conventions: /api/v1/data, /api/v1/meta, /api/v1/ui
+     */
+    getRoute(type) {
+        // Use conventional ObjectStack API paths
+        const routeMap = {
+            data: '/api/v1/data',
+            metadata: '/api/v1/meta',
+            ui: '/api/v1/ui',
+            auth: '/api/v1/auth'
+        };
+        return routeMap[type] || `/api/v1/${type}`;
     }
 }
 // Re-export type-safe query builder

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@objectstack/client",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Official Client SDK for ObjectStack Protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/spec": "0.8.2",
-    "@objectstack/core": "0.8.2"
+    "@objectstack/spec": "0.9.1",
+    "@objectstack/core": "0.9.1"
   },
   "devDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "vitest run"
   }
 }

package/src/client.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackClient } from './index';
+
+describe('ObjectStackClient', () => {
+    it('should initialize with correct configuration', () => {
+        const client = new ObjectStackClient({ baseUrl: 'http://localhost:3000' });
+        expect(client).toBeDefined();
+    });
+
+    it('should normalize base URL', () => {
+        const client: any = new ObjectStackClient({ baseUrl: 'http://localhost:3000/' });
+        expect(client.baseUrl).toBe('http://localhost:3000');
+    });
+
+    it('should make discovery request on connect', async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({ 
+                version: 'v1', 
+                apiName: 'ObjectStack',
+                capabilities: ['metadata', 'data', 'ui'],
+                endpoints: {}
+            })
+        });
+
+        const client = new ObjectStackClient({ 
+            baseUrl: 'http://localhost:3000',
+            fetch: fetchMock
+        });
+
+        await client.connect();
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1', expect.any(Object));
+    });
+
+    it('should get metadata types', async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({ 
+                types: ['object', 'plugin', 'view']
+            })
+        });
+
+        const client = new ObjectStackClient({ 
+            baseUrl: 'http://localhost:3000',
+            fetch: fetchMock
+        });
+
+        const result = await client.meta.getTypes();
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta', expect.any(Object));
+        expect(result.types).toEqual(['object', 'plugin', 'view']);
+    });
+
+    it('should get metadata items by type', async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({ 
+                type: 'object',
+                items: [{ name: 'customer' }, { name: 'order' }]
+            })
+        });
+
+        const client = new ObjectStackClient({ 
+            baseUrl: 'http://localhost:3000',
+            fetch: fetchMock
+        });
+
+        const result = await client.meta.getItems('object');
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta/object', expect.any(Object));
+        expect(result.type).toBe('object');
+        expect(result.items).toHaveLength(2);
+    });
+
+    it('should get metadata item by type and name', async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({ 
+                name: 'customer',
+                fields: []
+            })
+        });
+
+        const client = new ObjectStackClient({ 
+            baseUrl: 'http://localhost:3000',
+            fetch: fetchMock
+        });
+
+        const result = await client.meta.getItem('object', 'customer');
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/meta/object/customer', expect.any(Object));
+        expect(result.name).toBe('customer');
+    });
+});

package/src/index.ts

@@ -8,7 +8,10 @@ import {
   MetadataCacheRequest,
   MetadataCacheResponse,
   StandardErrorCode,
-  ErrorCategory
+  ErrorCategory,
+  GetDiscoveryResponse,
+  GetMetaTypesResponse,
+  GetMetaItemsResponse
 } from '@objectstack/spec/api';
 import { Logger, createLogger } from '@objectstack/core';
 
@@ -29,16 +32,11 @@ export interface ClientConfig {
   debug?: boolean;
 }
 
-export interface DiscoveryResult {
-  routes: {
-    discovery: string;
-    metadata: string;
-    data: string;
-    auth: string;
-    ui: string;
-  };
-  capabilities?: Record<string, boolean>;
-}
+/**
+ * Discovery Result
+ * Re-export from @objectstack/spec/api for convenience
+ */
+export type DiscoveryResult = GetDiscoveryResponse;
 
 export interface QueryOptions {
   select?: string[]; // Simplified Selection
@@ -69,7 +67,7 @@ export class ObjectStackClient {
   private baseUrl: string;
   private token?: string;
   private fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
-  private routes?: DiscoveryResult['routes'];
+  private discoveryInfo?: DiscoveryResult;
   private logger: Logger;
 
   constructor(config: ClientConfig) {
@@ -87,21 +85,21 @@ export class ObjectStackClient {
   }
 
   /**
-   * Initialize the client by discovering server capabilities and routes.
+   * Initialize the client by discovering server capabilities.
    */
   async connect() {
     this.logger.debug('Connecting to ObjectStack server', { baseUrl: this.baseUrl });
     
     try {
-      // Connect to the discovery endpoint
-      // During boot, we might not know routes, so we check convention /api/v1 first
+      // Connect to the discovery endpoint at /api/v1
       const res = await this.fetch(`${this.baseUrl}/api/v1`);
       
       const data = await res.json();
-      this.routes = data.routes;
+      this.discoveryInfo = data;
       
       this.logger.info('Connected to ObjectStack server', { 
-        routes: Object.keys(data.routes || {}),
+        version: data.version,
+        apiName: data.apiName,
         capabilities: data.capabilities 
       });
       
@@ -116,11 +114,47 @@ export class ObjectStackClient {
    * Metadata Operations
    */
   meta = {
+    /**
+     * Get all available metadata types
+     * Returns types like 'object', 'plugin', 'view', etc.
+     */
+    getTypes: async (): Promise<GetMetaTypesResponse> => {
+        const route = this.getRoute('metadata');
+        const res = await this.fetch(`${this.baseUrl}${route}`);
+        return res.json();
+    },
+
+    /**
+     * Get all items of a specific metadata type
+     * @param type - Metadata type name (e.g., 'object', 'plugin')
+     */
+    getItems: async (type: string): Promise<GetMetaItemsResponse> => {
+        const route = this.getRoute('metadata');
+        const res = await this.fetch(`${this.baseUrl}${route}/${type}`);
+        return res.json();
+    },
+
+    /**
+     * Get a specific object definition by name
+     * @deprecated Use `getItem('object', name)` instead for consistency with spec protocol
+     * @param name - Object name (snake_case identifier)
+     */
     getObject: async (name: string) => {
         const route = this.getRoute('metadata');
         const res = await this.fetch(`${this.baseUrl}${route}/object/${name}`);
         return res.json();
     },
+
+    /**
+     * Get a specific metadata item by type and name
+     * @param type - Metadata type (e.g., 'object', 'plugin')
+     * @param name - Item name (snake_case identifier)
+     */
+    getItem: async (type: string, name: string) => {
+        const route = this.getRoute('metadata');
+        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`);
+        return res.json();
+    },
     
     /**
      * Get object metadata with cache support
@@ -407,16 +441,20 @@ export class ObjectStackClient {
     return res;
   }
 
-  private getRoute(key: keyof DiscoveryResult['routes']): string {
-    if (!this.routes) {
-        // Fallback for strictness, but we allow bootstrapping
-        this.logger.warn('Accessing route before connect()', { 
-          route: key, 
-          fallback: `/api/v1/${key}` 
-        });
-        return `/api/v1/${key}`;
-    }
-    return this.routes[key] || `/api/v1/${key}`; 
+  /**
+   * Get the conventional route path for a given API endpoint type
+   * ObjectStack uses standard conventions: /api/v1/data, /api/v1/meta, /api/v1/ui
+   */
+  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth'): string {
+    // Use conventional ObjectStack API paths
+    const routeMap: Record<string, string> = {
+      data: '/api/v1/data',
+      metadata: '/api/v1/meta',
+      ui: '/api/v1/ui',
+      auth: '/api/v1/auth'
+    };
+    
+    return routeMap[type] || `/api/v1/${type}`;
   }
 }
 
@@ -435,5 +473,8 @@ export type {
   MetadataCacheRequest,
   MetadataCacheResponse,
   StandardErrorCode,
-  ErrorCategory
+  ErrorCategory,
+  GetDiscoveryResponse,
+  GetMetaTypesResponse,
+  GetMetaItemsResponse
 } from '@objectstack/spec/api';

package/tsconfig.json

@@ -9,5 +9,6 @@
     "esModuleInterop": true,
     "skipLibCheck": true
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }