@objectstack/client 0.6.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @objectstack/client
 
+## 0.7.2
+
+### Patch Changes
+
+- fb41cc0: Patch release: Updated documentation and JSON schemas
+- Updated dependencies [fb41cc0]
+  - @objectstack/spec@0.7.2
+  - @objectstack/core@0.7.2
+
+## 0.7.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements
+- Updated dependencies
+  - @objectstack/spec@0.7.1
+  - @objectstack/core@0.7.1
+
 ## 0.6.1
 
 ### Patch Changes

package/README.md

@@ -6,7 +6,11 @@ The official TypeScript client for ObjectStack.
 
 - **Auto-Discovery**: Connects to your ObjectStack server and automatically configures API endpoints.
 - **Typed Metadata**: Retrieve Object and View definitions with full type support.
+- **Metadata Caching**: ETag-based conditional requests for efficient metadata caching.
 - **Unified Data Access**: Simple CRUD operations for any object in your schema.
+- **Batch Operations**: Efficient bulk create/update/delete with transaction support.
+- **View Storage**: Save, load, and share custom UI view configurations.
+- **Standardized Errors**: Machine-readable error codes with retry guidance.
 
 ## Installation
 
@@ -47,8 +51,48 @@ async function main() {
     priority: 1
   });
 
-  // 6. Batch Operations
-  await client.data.deleteMany('todo_task', ['id1', 'id2']);
+  // 6. Batch Operations (New!)
+  const batchResult = await client.data.batch('todo_task', {
+    operation: 'update',
+    records: [
+      { id: '1', data: { status: 'active' } },
+      { id: '2', data: { status: 'active' } }
+    ],
+    options: {
+      atomic: true,        // Rollback on any failure
+      returnRecords: true  // Include full records in response
+    }
+  });
+  console.log(`Updated ${batchResult.succeeded} records`);
+
+  // 7. Metadata Caching (New!)
+  const cachedObject = await client.meta.getCached('todo_task', {
+    ifNoneMatch: '"686897696a7c876b7e"'  // ETag from previous request
+  });
+  if (cachedObject.notModified) {
+    console.log('Using cached metadata');
+  }
+
+  // 8. View Storage (New!)
+  const view = await client.views.create({
+    name: 'active_tasks',
+    label: 'Active Tasks',
+    object: 'todo_task',
+    type: 'list',
+    visibility: 'public',
+    query: {
+      object: 'todo_task',
+      where: { status: 'active' },
+      orderBy: [{ field: 'priority', order: 'desc' }],
+      limit: 50
+    },
+    layout: {
+      columns: [
+        { field: 'subject', label: 'Task', width: 200 },
+        { field: 'priority', label: 'Priority', width: 100 }
+      ]
+    }
+  });
 }
 ```
 
@@ -59,6 +103,7 @@ Initializes the client by fetching the system discovery manifest from `/api/v1`.
 
 ### `client.meta`
 - `getObject(name: string)`: Get object schema.
+- `getCached(name: string, options?)`: Get object schema with ETag-based caching.
 - `getView(name: string)`: Get view configuration.
 
 ### `client.data`
@@ -66,11 +111,21 @@ Initializes the client by fetching the system discovery manifest from `/api/v1`.
 - `get<T>(object, id)`: Get single record by ID.
 - `query<T>(object, ast)`: Execute complex query using full AST.
 - `create<T>(object, data)`: Create record.
-- `createMany<T>(object, data[])`: Batch create records.
+- `batch(object, request)`: **Recommended** - Execute batch operations (create/update/upsert/delete) with full control.
+- `createMany<T>(object, data[])`: Batch create records (convenience method).
 - `update<T>(object, id, data)`: Update record.
-- `updateMany<T>(object, ids[], data)`: Batch update records.
+- `updateMany<T>(object, records[], options?)`: Batch update records (convenience method).
 - `delete(object, id)`: Delete record.
-- `deleteMany(object, ids[])`: Batch delete records.
+- `deleteMany(object, ids[], options?)`: Batch delete records (convenience method).
+
+### `client.views` (New!)
+- `create(request)`: Create a new saved view.
+- `get(id)`: Get a saved view by ID.
+- `list(request?)`: List saved views with optional filters.
+- `update(request)`: Update an existing view.
+- `delete(id)`: Delete a saved view.
+- `share(id, userIds[])`: Share a view with users/teams.
+- `setDefault(id, object)`: Set a view as default for an object.
 
 ### Query Options
 The `find` method accepts an options object:
@@ -80,3 +135,32 @@ The `find` method accepts an options object:
 - `top`: Limit number of records.
 - `skip`: Offset for pagination.
 
+### Batch Options
+Batch operations support the following options:
+- `atomic`: If true, rollback entire batch on any failure (default: true).
+- `returnRecords`: If true, return full record data in response (default: false).
+- `continueOnError`: If true (and atomic=false), continue processing remaining records after errors.
+- `validateOnly`: If true, validate records without persisting changes (dry-run mode).
+
+### Error Handling
+The client provides standardized error handling with machine-readable error codes:
+
+```typescript
+try {
+  await client.data.create('todo_task', { subject: '' });
+} catch (error) {
+  console.error('Error code:', error.code);        // e.g., 'validation_error'
+  console.error('Category:', error.category);      // e.g., 'validation'
+  console.error('HTTP status:', error.httpStatus); // e.g., 400
+  console.error('Retryable:', error.retryable);    // e.g., false
+  console.error('Details:', error.details);        // Additional error info
+}
+```
+
+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
+

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
+import { BatchUpdateRequest, BatchUpdateResponse, BatchOptions, MetadataCacheRequest, MetadataCacheResponse, StandardErrorCode, ErrorCategory, CreateViewRequest, UpdateViewRequest, ListViewsRequest, ListViewsResponse, ViewResponse } from '@objectstack/spec/api';
+import { Logger } from '@objectstack/core';
 export interface ClientConfig {
     baseUrl: string;
     token?: string;
@@ -6,6 +8,14 @@ export interface ClientConfig {
      * Custom fetch implementation (e.g. node-fetch or for Next.js caching)
      */
     fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    /**
+     * Logger instance for debugging
+     */
+    logger?: Logger;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
 }
 export interface DiscoveryResult {
     routes: {
@@ -30,11 +40,20 @@ export interface PaginatedResult<T = any> {
     value: T[];
     count: number;
 }
+export interface StandardError {
+    code: StandardErrorCode;
+    message: string;
+    category: ErrorCategory;
+    httpStatus: number;
+    retryable: boolean;
+    details?: Record<string, any>;
+}
 export declare class ObjectStackClient {
     private baseUrl;
     private token?;
     private fetchImpl;
     private routes?;
+    private logger;
     constructor(config: ClientConfig);
     /**
      * Initialize the client by discovering server capabilities and routes.
@@ -45,6 +64,11 @@ export declare class ObjectStackClient {
      */
     meta: {
         getObject: (name: string) => Promise<any>;
+        /**
+         * Get object metadata with cache support
+         * Supports ETag-based conditional requests for efficient caching
+         */
+        getCached: (name: string, cacheOptions?: MetadataCacheRequest) => Promise<MetadataCacheResponse>;
         getView: (object: string, type?: "list" | "form") => Promise<any>;
     };
     /**
@@ -61,13 +85,62 @@ export declare class ObjectStackClient {
         create: <T = any>(object: string, data: Partial<T>) => Promise<T>;
         createMany: <T = any>(object: string, data: Partial<T>[]) => Promise<T[]>;
         update: <T = any>(object: string, id: string, data: Partial<T>) => Promise<T>;
-        updateMany: <T = any>(object: string, data: Partial<T>, filters?: Record<string, any> | any[]) => Promise<number>;
+        /**
+         * Batch update multiple records
+         * Uses the new BatchUpdateRequest schema with full control over options
+         */
+        batch: (object: string, request: BatchUpdateRequest) => Promise<BatchUpdateResponse>;
+        /**
+         * Update multiple records (simplified batch update)
+         * Convenience method for batch updates without full BatchUpdateRequest
+         */
+        updateMany: <T = any>(object: string, records: Array<{
+            id: string;
+            data: Partial<T>;
+        }>, options?: BatchOptions) => Promise<BatchUpdateResponse>;
         delete: (object: string, id: string) => Promise<{
             success: boolean;
         }>;
-        deleteMany: (object: string, filters?: Record<string, any> | any[]) => Promise<{
-            count: number;
+        /**
+         * Delete multiple records by IDs
+         */
+        deleteMany: (object: string, ids: string[], options?: BatchOptions) => Promise<BatchUpdateResponse>;
+    };
+    /**
+     * View Storage Operations
+     * Save, load, and manage UI view configurations
+     */
+    views: {
+        /**
+         * Create a new saved view
+         */
+        create: (request: CreateViewRequest) => Promise<ViewResponse>;
+        /**
+         * Get a saved view by ID
+         */
+        get: (id: string) => Promise<ViewResponse>;
+        /**
+         * List saved views with optional filters
+         */
+        list: (request?: ListViewsRequest) => Promise<ListViewsResponse>;
+        /**
+         * Update an existing view
+         */
+        update: (request: UpdateViewRequest) => Promise<ViewResponse>;
+        /**
+         * Delete a saved view
+         */
+        delete: (id: string) => Promise<{
+            success: boolean;
         }>;
+        /**
+         * Share a view with users/teams
+         */
+        share: (id: string, userIds: string[]) => Promise<ViewResponse>;
+        /**
+         * Set a view as default for an object
+         */
+        setDefault: (id: string, object: string) => Promise<ViewResponse>;
     };
     /**
      * Private Helpers
@@ -76,3 +149,5 @@ export declare class ObjectStackClient {
     private fetch;
     private getRoute;
 }
+export { QueryBuilder, FilterBuilder, createQuery, createFilter } from './query-builder';
+export type { BatchUpdateRequest, BatchUpdateResponse, UpdateManyRequest, DeleteManyRequest, BatchOptions, BatchRecord, BatchOperationResult, MetadataCacheRequest, MetadataCacheResponse, StandardErrorCode, ErrorCategory, CreateViewRequest, UpdateViewRequest, ListViewsRequest, SavedView, ViewResponse, ListViewsResponse, ViewType, ViewVisibility, ViewColumn, ViewLayout } from '@objectstack/spec/api';

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createLogger } from '@objectstack/core';
 export class ObjectStackClient {
     constructor(config) {
         /**
@@ -9,6 +10,45 @@ export class ObjectStackClient {
                 const res = await this.fetch(`${this.baseUrl}${route}/object/${name}`);
                 return res.json();
             },
+            /**
+             * Get object metadata with cache support
+             * Supports ETag-based conditional requests for efficient caching
+             */
+            getCached: async (name, cacheOptions) => {
+                const route = this.getRoute('metadata');
+                const headers = {};
+                if (cacheOptions?.ifNoneMatch) {
+                    headers['If-None-Match'] = cacheOptions.ifNoneMatch;
+                }
+                if (cacheOptions?.ifModifiedSince) {
+                    headers['If-Modified-Since'] = cacheOptions.ifModifiedSince;
+                }
+                const res = await this.fetch(`${this.baseUrl}${route}/object/${name}`, {
+                    headers
+                });
+                // Check for 304 Not Modified
+                if (res.status === 304) {
+                    return {
+                        notModified: true,
+                        etag: cacheOptions?.ifNoneMatch ? {
+                            value: cacheOptions.ifNoneMatch.replace(/^W\/|"/g, ''),
+                            weak: cacheOptions.ifNoneMatch.startsWith('W/')
+                        } : undefined
+                    };
+                }
+                const data = await res.json();
+                const etag = res.headers.get('ETag');
+                const lastModified = res.headers.get('Last-Modified');
+                return {
+                    data,
+                    etag: etag ? {
+                        value: etag.replace(/^W\/|"/g, ''),
+                        weak: etag.startsWith('W/')
+                    } : undefined,
+                    lastModified: lastModified || undefined,
+                    notModified: false
+                };
+            },
             getView: async (object, type = 'list') => {
                 const route = this.getRoute('ui');
                 const res = await this.fetch(`${this.baseUrl}${route}/view/${object}?type=${type}`);
@@ -96,7 +136,7 @@ export class ObjectStackClient {
             },
             createMany: async (object, data) => {
                 const route = this.getRoute('data');
-                const res = await this.fetch(`${this.baseUrl}${route}/${object}/batch`, {
+                const res = await this.fetch(`${this.baseUrl}${route}/${object}/createMany`, {
                     method: 'POST',
                     body: JSON.stringify(data)
                 });
@@ -110,13 +150,33 @@ export class ObjectStackClient {
                 });
                 return res.json();
             },
-            updateMany: async (object, data, filters) => {
+            /**
+             * Batch update multiple records
+             * Uses the new BatchUpdateRequest schema with full control over options
+             */
+            batch: async (object, request) => {
                 const route = this.getRoute('data');
                 const res = await this.fetch(`${this.baseUrl}${route}/${object}/batch`, {
-                    method: 'PATCH',
-                    body: JSON.stringify({ data, filters })
+                    method: 'POST',
+                    body: JSON.stringify(request)
                 });
-                return res.json(); // Returns count
+                return res.json();
+            },
+            /**
+             * Update multiple records (simplified batch update)
+             * Convenience method for batch updates without full BatchUpdateRequest
+             */
+            updateMany: async (object, records, options) => {
+                const route = this.getRoute('data');
+                const request = {
+                    records,
+                    options
+                };
+                const res = await this.fetch(`${this.baseUrl}${route}/${object}/updateMany`, {
+                    method: 'POST',
+                    body: JSON.stringify(request)
+                });
+                return res.json();
             },
             delete: async (object, id) => {
                 const route = this.getRoute('data');
@@ -125,11 +185,113 @@ export class ObjectStackClient {
                 });
                 return res.json();
             },
-            deleteMany: async (object, filters) => {
+            /**
+             * Delete multiple records by IDs
+             */
+            deleteMany: async (object, ids, options) => {
                 const route = this.getRoute('data');
-                const res = await this.fetch(`${this.baseUrl}${route}/${object}/batch`, {
-                    method: 'DELETE',
-                    body: JSON.stringify({ filters })
+                const request = {
+                    ids,
+                    options
+                };
+                const res = await this.fetch(`${this.baseUrl}${route}/${object}/deleteMany`, {
+                    method: 'POST',
+                    body: JSON.stringify(request)
+                });
+                return res.json();
+            }
+        };
+        /**
+         * View Storage Operations
+         * Save, load, and manage UI view configurations
+         */
+        this.views = {
+            /**
+             * Create a new saved view
+             */
+            create: async (request) => {
+                const route = this.getRoute('ui');
+                const res = await this.fetch(`${this.baseUrl}${route}/views`, {
+                    method: 'POST',
+                    body: JSON.stringify(request)
+                });
+                return res.json();
+            },
+            /**
+             * Get a saved view by ID
+             */
+            get: async (id) => {
+                const route = this.getRoute('ui');
+                const res = await this.fetch(`${this.baseUrl}${route}/views/${id}`);
+                return res.json();
+            },
+            /**
+             * List saved views with optional filters
+             */
+            list: async (request) => {
+                const route = this.getRoute('ui');
+                const queryParams = new URLSearchParams();
+                if (request?.object)
+                    queryParams.set('object', request.object);
+                if (request?.type)
+                    queryParams.set('type', request.type);
+                if (request?.visibility)
+                    queryParams.set('visibility', request.visibility);
+                if (request?.createdBy)
+                    queryParams.set('createdBy', request.createdBy);
+                if (request?.isDefault !== undefined)
+                    queryParams.set('isDefault', String(request.isDefault));
+                if (request?.limit)
+                    queryParams.set('limit', String(request.limit));
+                if (request?.offset)
+                    queryParams.set('offset', String(request.offset));
+                const url = queryParams.toString()
+                    ? `${this.baseUrl}${route}/views?${queryParams.toString()}`
+                    : `${this.baseUrl}${route}/views`;
+                const res = await this.fetch(url);
+                return res.json();
+            },
+            /**
+             * Update an existing view
+             */
+            update: async (request) => {
+                const route = this.getRoute('ui');
+                const { id, ...updateData } = request;
+                const res = await this.fetch(`${this.baseUrl}${route}/views/${id}`, {
+                    method: 'PATCH',
+                    body: JSON.stringify(updateData)
+                });
+                return res.json();
+            },
+            /**
+             * Delete a saved view
+             */
+            delete: async (id) => {
+                const route = this.getRoute('ui');
+                const res = await this.fetch(`${this.baseUrl}${route}/views/${id}`, {
+                    method: 'DELETE'
+                });
+                return res.json();
+            },
+            /**
+             * Share a view with users/teams
+             */
+            share: async (id, userIds) => {
+                const route = this.getRoute('ui');
+                const res = await this.fetch(`${this.baseUrl}${route}/views/${id}/share`, {
+                    method: 'POST',
+                    body: JSON.stringify({ sharedWith: userIds })
+                });
+                return res.json();
+            },
+            /**
+             * Set a view as default for an object
+             */
+            setDefault: async (id, object) => {
+                const route = this.getRoute('ui');
+                const res = await this.fetch(`${this.baseUrl}${route}/views/${id}/set-default`, {
+                    method: 'POST',
+                    body: JSON.stringify({ object })
                 });
                 return res.json();
             }
@@ -137,21 +299,32 @@ export class ObjectStackClient {
         this.baseUrl = config.baseUrl.replace(/\/$/, ''); // Remove trailing slash
         this.token = config.token;
         this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
+        // Initialize logger
+        this.logger = config.logger || createLogger({
+            level: config.debug ? 'debug' : 'info',
+            format: 'pretty'
+        });
+        this.logger.debug('ObjectStack client created', { baseUrl: this.baseUrl });
     }
     /**
      * Initialize the client by discovering server capabilities and routes.
      */
     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
             const res = await this.fetch(`${this.baseUrl}/api/v1`);
             const data = await res.json();
             this.routes = data.routes;
+            this.logger.info('Connected to ObjectStack server', {
+                routes: Object.keys(data.routes || {}),
+                capabilities: data.capabilities
+            });
             return data;
         }
         catch (e) {
-            console.error('Failed to connect to ObjectStack Server', e);
+            this.logger.error('Failed to connect to ObjectStack server', e, { baseUrl: this.baseUrl });
             throw e;
         }
     }
@@ -165,6 +338,11 @@ export class ObjectStackClient {
         return Array.isArray(filter);
     }
     async fetch(url, options = {}) {
+        this.logger.debug('HTTP request', {
+            method: options.method || 'GET',
+            url,
+            hasBody: !!options.body
+        });
         const headers = {
             'Content-Type': 'application/json',
             ...(options.headers || {}),
@@ -173,6 +351,12 @@ export class ObjectStackClient {
             headers['Authorization'] = `Bearer ${this.token}`;
         }
         const res = await this.fetchImpl(url, { ...options, headers });
+        this.logger.debug('HTTP response', {
+            method: options.method || 'GET',
+            url,
+            status: res.status,
+            ok: res.ok
+        });
         if (!res.ok) {
             let errorBody;
             try {
@@ -181,16 +365,37 @@ export class ObjectStackClient {
             catch {
                 errorBody = { message: res.statusText };
             }
-            throw new Error(`[ObjectStack] Request failed: ${res.status} ${JSON.stringify(errorBody)}`);
+            this.logger.error('HTTP request failed', undefined, {
+                method: options.method || 'GET',
+                url,
+                status: res.status,
+                error: errorBody
+            });
+            // Create a standardized error if the response includes error details
+            const errorMessage = errorBody?.message || errorBody?.error?.message || res.statusText;
+            const errorCode = errorBody?.code || errorBody?.error?.code;
+            const error = new Error(`[ObjectStack] ${errorCode ? `${errorCode}: ` : ''}${errorMessage}`);
+            // Attach error details for programmatic access
+            error.code = errorCode;
+            error.category = errorBody?.category;
+            error.httpStatus = res.status;
+            error.retryable = errorBody?.retryable;
+            error.details = errorBody?.details || errorBody;
+            throw error;
         }
         return res;
     }
     getRoute(key) {
         if (!this.routes) {
             // Fallback for strictness, but we allow bootstrapping
-            console.warn(`[ObjectStackClient] Accessing ${key} route before connect(). Using default /api/v1/${key}`);
+            this.logger.warn('Accessing route before connect()', {
+                route: key,
+                fallback: `/api/v1/${key}`
+            });
             return `/api/v1/${key}`;
         }
         return this.routes[key] || `/api/v1/${key}`;
     }
 }
+// Re-export type-safe query builder
+export { QueryBuilder, FilterBuilder, createQuery, createFilter } from './query-builder';