@objectstack/client 0.6.1 → 0.7.2

package/src/index.ts

@@ -1,4 +1,22 @@
 import { QueryAST, SortNode, AggregationNode, WindowFunctionNode } from '@objectstack/spec/data';
+import { 
+  BatchUpdateRequest, 
+  BatchUpdateResponse, 
+  UpdateManyRequest,
+  DeleteManyRequest,
+  BatchOptions,
+  MetadataCacheRequest,
+  MetadataCacheResponse,
+  StandardErrorCode,
+  ErrorCategory,
+  CreateViewRequest,
+  UpdateViewRequest,
+  ListViewsRequest,
+  SavedView,
+  ListViewsResponse,
+  ViewResponse
+} from '@objectstack/spec/api';
+import { Logger, createLogger } from '@objectstack/core';
 
 export interface ClientConfig {
   baseUrl: string;
@@ -7,6 +25,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 {
@@ -36,22 +62,42 @@ export interface PaginatedResult<T = any> {
   count: number;
 }
 
+export interface StandardError {
+  code: StandardErrorCode;
+  message: string;
+  category: ErrorCategory;
+  httpStatus: number;
+  retryable: boolean;
+  details?: Record<string, any>;
+}
+
 export class ObjectStackClient {
   private baseUrl: string;
   private token?: string;
   private fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
   private routes?: DiscoveryResult['routes'];
+  private logger: Logger;
 
   constructor(config: ClientConfig) {
     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
@@ -59,9 +105,15 @@ export class ObjectStackClient {
       
       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 as DiscoveryResult;
     } catch (e) {
-      console.error('Failed to connect to ObjectStack Server', e);
+      this.logger.error('Failed to connect to ObjectStack server', e as Error, { baseUrl: this.baseUrl });
       throw e;
     }
   }
@@ -76,6 +128,51 @@ export class ObjectStackClient {
         return res.json();
     },
     
+    /**
+     * Get object metadata with cache support
+     * Supports ETag-based conditional requests for efficient caching
+     */
+    getCached: async (name: string, cacheOptions?: MetadataCacheRequest): Promise<MetadataCacheResponse> => {
+        const route = this.getRoute('metadata');
+        const headers: Record<string, string> = {};
+        
+        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: string, type: 'list' | 'form' = 'list') => {
         const route = this.getRoute('ui');
         const res = await this.fetch(`${this.baseUrl}${route}/view/${object}?type=${type}`);
@@ -170,7 +267,7 @@ export class ObjectStackClient {
 
     createMany: async <T = any>(object: string, data: Partial<T>[]): Promise<T[]> => {
         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)
         });
@@ -186,13 +283,38 @@ export class ObjectStackClient {
         return res.json();
     },
 
-    updateMany: async <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: async (object: string, request: BatchUpdateRequest): Promise<BatchUpdateResponse> => {
         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 <T = any>(
+      object: string, 
+      records: Array<{ id: string; data: Partial<T> }>,
+      options?: BatchOptions
+    ): Promise<BatchUpdateResponse> => {
+        const route = this.getRoute('data');
+        const request: UpdateManyRequest = {
+          records,
+          options
+        };
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/updateMany`, {
+            method: 'POST',
+            body: JSON.stringify(request)
+        });
+        return res.json();
     },
 
     delete: async (object: string, id: string): Promise<{ success: boolean }> => {
@@ -203,16 +325,121 @@ export class ObjectStackClient {
         return res.json();
     },
 
-    deleteMany: async(object: string, filters?: Record<string, any> | any[]): Promise<{ count: number }> => {
+    /**
+     * Delete multiple records by IDs
+     */
+    deleteMany: async(object: string, ids: string[], options?: BatchOptions): Promise<BatchUpdateResponse> => {
         const route = this.getRoute('data');
-        const res = await this.fetch(`${this.baseUrl}${route}/${object}/batch`, {
-             method: 'DELETE',
-             body: JSON.stringify({ filters })
+        const request: DeleteManyRequest = {
+          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
+   */
+  views = {
+    /**
+     * Create a new saved view
+     */
+    create: async (request: CreateViewRequest): Promise<ViewResponse> => {
+      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: string): Promise<ViewResponse> => {
+      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?: ListViewsRequest): Promise<ListViewsResponse> => {
+      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: UpdateViewRequest): Promise<ViewResponse> => {
+      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: string): Promise<{ success: boolean }> => {
+      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: string, userIds: string[]): Promise<ViewResponse> => {
+      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: string, object: string): Promise<ViewResponse> => {
+      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();
+    }
+  };
+
   /**
    * Private Helpers
    */
@@ -225,6 +452,12 @@ export class ObjectStackClient {
   }
 
   private async fetch(url: string, options: RequestInit = {}): Promise<Response> {
+    this.logger.debug('HTTP request', { 
+      method: options.method || 'GET',
+      url,
+      hasBody: !!options.body
+    });
+    
     const headers: Record<string, string> = {
       'Content-Type': 'application/json',
       ...(options.headers as Record<string, string> || {}),
@@ -236,14 +469,41 @@ export class ObjectStackClient {
 
     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;
+        let errorBody: any;
         try {
             errorBody = await res.json();
         } 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}`) as any;
+        
+        // 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;
@@ -252,9 +512,40 @@ export class ObjectStackClient {
   private getRoute(key: keyof DiscoveryResult['routes']): string {
     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';
+
+// Re-export commonly used types from @objectstack/spec/api for convenience
+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/src/query-builder.ts

@@ -0,0 +1,251 @@
+/**
+ * Type-Safe Query Builder
+ * 
+ * Provides a fluent API for building ObjectStack queries with:
+ * - Compile-time type checking
+ * - Intelligent code completion
+ * - Runtime validation
+ * - Type-safe filters and selections
+ */
+
+import { QueryAST, FilterCondition, SortNode } from '@objectstack/spec/data';
+
+/**
+ * Type-safe filter builder
+ */
+export class FilterBuilder<T = any> {
+  private conditions: FilterCondition[] = [];
+
+  /**
+   * Equality filter: field = value
+   */
+  equals<K extends keyof T>(field: K, value: T[K]): this {
+    this.conditions.push([field as string, '=', value]);
+    return this;
+  }
+
+  /**
+   * Not equals filter: field != value
+   */
+  notEquals<K extends keyof T>(field: K, value: T[K]): this {
+    this.conditions.push([field as string, '!=', value]);
+    return this;
+  }
+
+  /**
+   * Greater than filter: field > value
+   */
+  greaterThan<K extends keyof T>(field: K, value: T[K]): this {
+    this.conditions.push([field as string, '>', value]);
+    return this;
+  }
+
+  /**
+   * Greater than or equal filter: field >= value
+   */
+  greaterThanOrEqual<K extends keyof T>(field: K, value: T[K]): this {
+    this.conditions.push([field as string, '>=', value]);
+    return this;
+  }
+
+  /**
+   * Less than filter: field < value
+   */
+  lessThan<K extends keyof T>(field: K, value: T[K]): this {
+    this.conditions.push([field as string, '<', value]);
+    return this;
+  }
+
+  /**
+   * Less than or equal filter: field <= value
+   */
+  lessThanOrEqual<K extends keyof T>(field: K, value: T[K]): this {
+    this.conditions.push([field as string, '<=', value]);
+    return this;
+  }
+
+  /**
+   * IN filter: field IN (value1, value2, ...)
+   */
+  in<K extends keyof T>(field: K, values: T[K][]): this {
+    this.conditions.push([field as string, 'in', values]);
+    return this;
+  }
+
+  /**
+   * NOT IN filter: field NOT IN (value1, value2, ...)
+   */
+  notIn<K extends keyof T>(field: K, values: T[K][]): this {
+    this.conditions.push([field as string, 'not_in', values]);
+    return this;
+  }
+
+  /**
+   * LIKE filter: field LIKE pattern
+   */
+  like<K extends keyof T>(field: K, pattern: string): this {
+    this.conditions.push([field as string, 'like', pattern]);
+    return this;
+  }
+
+  /**
+   * IS NULL filter: field IS NULL
+   */
+  isNull<K extends keyof T>(field: K): this {
+    this.conditions.push([field as string, 'is_null', null]);
+    return this;
+  }
+
+  /**
+   * IS NOT NULL filter: field IS NOT NULL
+   */
+  isNotNull<K extends keyof T>(field: K): this {
+    this.conditions.push([field as string, 'is_not_null', null]);
+    return this;
+  }
+
+  /**
+   * Build the filter condition
+   */
+  build(): FilterCondition {
+    if (this.conditions.length === 0) {
+      throw new Error('Filter builder has no conditions');
+    }
+    if (this.conditions.length === 1) {
+      return this.conditions[0];
+    }
+    // Combine multiple conditions with AND
+    return ['and', ...this.conditions];
+  }
+
+  /**
+   * Get raw conditions array
+   */
+  getConditions(): FilterCondition[] {
+    return this.conditions;
+  }
+}
+
+/**
+ * Type-safe query builder
+ */
+export class QueryBuilder<T = any> {
+  private query: Partial<QueryAST> = {};
+  private _object: string;
+
+  constructor(object: string) {
+    this._object = object;
+    this.query.object = object;
+  }
+
+  /**
+   * Select specific fields
+   */
+  select<K extends keyof T>(...fields: K[]): this {
+    this.query.fields = fields as string[];
+    return this;
+  }
+
+  /**
+   * Add filters using a builder function
+   */
+  where(builderFn: (builder: FilterBuilder<T>) => void): this {
+    const builder = new FilterBuilder<T>();
+    builderFn(builder);
+    const conditions = builder.getConditions();
+    
+    if (conditions.length === 1) {
+      this.query.where = conditions[0];
+    } else if (conditions.length > 1) {
+      this.query.where = ['and', ...conditions] as FilterCondition;
+    }
+    
+    return this;
+  }
+
+  /**
+   * Add raw filter condition
+   */
+  filter(condition: FilterCondition): this {
+    this.query.where = condition;
+    return this;
+  }
+
+  /**
+   * Sort by fields
+   */
+  orderBy<K extends keyof T>(field: K, order: 'asc' | 'desc' = 'asc'): this {
+    if (!this.query.orderBy) {
+      this.query.orderBy = [];
+    }
+    (this.query.orderBy as SortNode[]).push({
+      field: field as string,
+      order
+    });
+    return this;
+  }
+
+  /**
+   * Limit the number of results
+   */
+  limit(count: number): this {
+    this.query.limit = count;
+    return this;
+  }
+
+  /**
+   * Skip records (for pagination)
+   */
+  skip(count: number): this {
+    this.query.offset = count;
+    return this;
+  }
+
+  /**
+   * Paginate results
+   */
+  paginate(page: number, pageSize: number): this {
+    this.query.limit = pageSize;
+    this.query.offset = (page - 1) * pageSize;
+    return this;
+  }
+
+  /**
+   * Group by fields
+   */
+  groupBy<K extends keyof T>(...fields: K[]): this {
+    this.query.groupBy = fields as string[];
+    return this;
+  }
+
+  /**
+   * Build the final query AST
+   */
+  build(): QueryAST {
+    return {
+      object: this._object,
+      ...this.query
+    } as QueryAST;
+  }
+
+  /**
+   * Get the current query state
+   */
+  getQuery(): Partial<QueryAST> {
+    return { ...this.query };
+  }
+}
+
+/**
+ * Create a type-safe query builder for an object
+ */
+export function createQuery<T = any>(object: string): QueryBuilder<T> {
+  return new QueryBuilder<T>(object);
+}
+
+/**
+ * Create a type-safe filter builder
+ */
+export function createFilter<T = any>(): FilterBuilder<T> {
+  return new FilterBuilder<T>();
+}