@objectstack/client 3.0.8 → 3.0.10

package/src/index.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
+import { QueryAST, SortNode, AggregationNode, isFilterAST } from '@objectstack/spec/data';
 import { 
   BatchUpdateRequest, 
   BatchUpdateResponse, 
@@ -20,6 +20,12 @@ import {
   PresignedUrlResponse,
   CompleteUploadRequest,
   FileUploadResponse,
+  InitiateChunkedUploadRequest,
+  InitiateChunkedUploadResponse,
+  UploadChunkResponse,
+  CompleteChunkedUploadRequest,
+  CompleteChunkedUploadResponse,
+  UploadProgress,
   CheckPermissionRequest,
   CheckPermissionResponse,
   GetObjectPermissionsResponse,
@@ -65,7 +71,22 @@ import {
   GetLocalesResponse,
   GetTranslationsResponse,
   GetFieldLabelsResponse,
-  RegisterRequest
+  RegisterRequest,
+  GetFeedResponse,
+  CreateFeedItemResponse,
+  UpdateFeedItemResponse,
+  DeleteFeedItemResponse,
+  AddReactionResponse,
+  RemoveReactionResponse,
+  PinFeedItemResponse,
+  UnpinFeedItemResponse,
+  StarFeedItemResponse,
+  UnstarFeedItemResponse,
+  SearchFeedResponse,
+  GetChangelogResponse,
+  SubscribeResponse,
+  UnsubscribeResponse,
+  WellKnownCapabilities,
 } from '@objectstack/spec/api';
 import { Logger, createLogger } from '@objectstack/core';
 
@@ -94,7 +115,10 @@ export type DiscoveryResult = GetDiscoveryResponse;
 
 export interface QueryOptions {
   select?: string[]; // Simplified Selection
-  filters?: Record<string, any>; // Map or AST
+  /** @canonical Preferred filter parameter (singular). */
+  filter?: Record<string, any> | unknown[]; // Map or AST
+  /** @deprecated Use `filter` (singular). Kept for backward compatibility. */
+  filters?: Record<string, any> | unknown[]; // Map or AST
   sort?: string | string[] | SortNode[]; // 'name' or ['-created_at'] or AST
   top?: number;
   skip?: number;
@@ -235,6 +259,15 @@ export class ObjectStackClient {
     }
   }
 
+  /**
+   * Well-known capability flags discovered from the server.
+   * Returns undefined if the client has not yet connected or the server
+   * did not include capabilities in its discovery response.
+   */
+  get capabilities(): WellKnownCapabilities | undefined {
+    return this.discoveryInfo?.capabilities;
+  }
+
   /**
    * Metadata Operations
    */
@@ -588,13 +621,94 @@ export class ObjectStackClient {
         const res = await this.fetch(`${this.baseUrl}${route}/files/${fileId}/url`);
         const data = await res.json();
         return data.url;
-    }
+    },
+
+    /**
+     * Get a presigned URL for direct-to-cloud upload
+     */
+    getPresignedUrl: async (req: GetPresignedUrlRequest): Promise<PresignedUrlResponse> => {
+        const route = this.getRoute('storage');
+        const res = await this.fetch(`${this.baseUrl}${route}/upload/presigned`, {
+            method: 'POST',
+            body: JSON.stringify(req)
+        });
+        return res.json();
+    },
+
+    /**
+     * Initiate a chunked (multipart) upload session
+     */
+    initChunkedUpload: async (req: InitiateChunkedUploadRequest): Promise<InitiateChunkedUploadResponse> => {
+        const route = this.getRoute('storage');
+        const res = await this.fetch(`${this.baseUrl}${route}/upload/chunked`, {
+            method: 'POST',
+            body: JSON.stringify(req)
+        });
+        return res.json();
+    },
+
+    /**
+     * Upload a single chunk/part of a multipart upload
+     */
+    uploadPart: async (uploadId: string, chunkIndex: number, resumeToken: string, data: Blob | Buffer): Promise<UploadChunkResponse> => {
+        const route = this.getRoute('storage');
+        const res = await this.fetch(`${this.baseUrl}${route}/upload/chunked/${uploadId}/chunk/${chunkIndex}`, {
+            method: 'PUT',
+            headers: { 'x-resume-token': resumeToken },
+            body: data as any
+        });
+        return res.json();
+    },
+
+    /**
+     * Complete a chunked upload by assembling all parts
+     */
+    completeChunkedUpload: async (req: CompleteChunkedUploadRequest): Promise<CompleteChunkedUploadResponse> => {
+        const route = this.getRoute('storage');
+        const res = await this.fetch(`${this.baseUrl}${route}/upload/chunked/${req.uploadId}/complete`, {
+            method: 'POST',
+            body: JSON.stringify(req)
+        });
+        return res.json();
+    },
+
+    /**
+     * Resume an interrupted chunked upload.
+     * Fetches current progress, then uploads remaining chunks and completes.
+     */
+    resumeUpload: async (uploadId: string, file: Blob | ArrayBuffer, chunkSize: number, resumeToken: string): Promise<CompleteChunkedUploadResponse> => {
+        const route = this.getRoute('storage');
+
+        // 1. Get current progress
+        const progressRes = await this.fetch(`${this.baseUrl}${route}/upload/chunked/${uploadId}/progress`);
+        const progress = await progressRes.json() as UploadProgress;
+
+        const { totalChunks, uploadedChunks } = progress.data;
+        const parts: Array<{ chunkIndex: number; eTag: string }> = [];
+
+        // 2. Upload remaining chunks
+        const fileBuffer = file instanceof ArrayBuffer ? file : await file.arrayBuffer();
+        for (let i = uploadedChunks; i < totalChunks; i++) {
+            const start = i * chunkSize;
+            const end = Math.min(start + chunkSize, fileBuffer.byteLength);
+            const chunk = new Blob([fileBuffer.slice(start, end)]);
+
+            const chunkRes = await this.storage.uploadPart(uploadId, i, resumeToken, chunk);
+            parts.push({ chunkIndex: i, eTag: chunkRes.data.eTag });
+        }
+
+        // 3. Complete
+        return this.storage.completeChunkedUpload({ uploadId, parts });
+    },
   };
 
   /**
    * Automation Services
    */
   automation = {
+      /**
+       * Trigger a named automation flow (legacy endpoint)
+       */
       trigger: async (triggerName: string, payload: any) => {
           const route = this.getRoute('automation');
           const res = await this.fetch(`${this.baseUrl}${route}/trigger/${triggerName}`, {
@@ -602,7 +716,99 @@ export class ObjectStackClient {
               body: JSON.stringify(payload)
           });
           return res.json();
-      }
+      },
+
+      /**
+       * List all registered automation flows
+       */
+      list: async (): Promise<{ flows: string[]; total: number; hasMore: boolean }> => {
+          const route = this.getRoute('automation');
+          const res = await this.fetch(`${this.baseUrl}${route}`);
+          return this.unwrapResponse(res);
+      },
+
+      /**
+       * Get a flow definition by name
+       */
+      get: async (name: string): Promise<any> => {
+          const route = this.getRoute('automation');
+          const res = await this.fetch(`${this.baseUrl}${route}/${name}`);
+          return this.unwrapResponse(res);
+      },
+
+      /**
+       * Create (register) a new flow
+       */
+      create: async (name: string, definition: any): Promise<any> => {
+          const route = this.getRoute('automation');
+          const res = await this.fetch(`${this.baseUrl}${route}`, {
+              method: 'POST',
+              body: JSON.stringify({ name, ...definition }),
+          });
+          return this.unwrapResponse(res);
+      },
+
+      /**
+       * Update an existing flow
+       */
+      update: async (name: string, definition: any): Promise<any> => {
+          const route = this.getRoute('automation');
+          const res = await this.fetch(`${this.baseUrl}${route}/${name}`, {
+              method: 'PUT',
+              body: JSON.stringify({ definition }),
+          });
+          return this.unwrapResponse(res);
+      },
+
+      /**
+       * Delete (unregister) a flow
+       */
+      delete: async (name: string): Promise<{ name: string; deleted: boolean }> => {
+          const route = this.getRoute('automation');
+          const res = await this.fetch(`${this.baseUrl}${route}/${name}`, {
+              method: 'DELETE',
+          });
+          return this.unwrapResponse(res);
+      },
+
+      /**
+       * Enable or disable a flow
+       */
+      toggle: async (name: string, enabled: boolean): Promise<{ name: string; enabled: boolean }> => {
+          const route = this.getRoute('automation');
+          const res = await this.fetch(`${this.baseUrl}${route}/${name}/toggle`, {
+              method: 'POST',
+              body: JSON.stringify({ enabled }),
+          });
+          return this.unwrapResponse(res);
+      },
+
+      /**
+       * Execution run history
+       */
+      runs: {
+          /**
+           * List execution runs for a flow
+           */
+          list: async (flowName: string, options?: { limit?: number; cursor?: string }): Promise<{ runs: any[]; hasMore: boolean }> => {
+              const route = this.getRoute('automation');
+              const params = new URLSearchParams();
+              if (options?.limit) params.set('limit', String(options.limit));
+              if (options?.cursor) params.set('cursor', options.cursor);
+              const qs = params.toString();
+              const res = await this.fetch(`${this.baseUrl}${route}/${flowName}/runs${qs ? `?${qs}` : ''}`);
+              return this.unwrapResponse(res);
+          },
+
+          /**
+           * Get a single execution run
+           */
+          get: async (flowName: string, runId: string): Promise<any> => {
+              const route = this.getRoute('automation');
+              const res = await this.fetch(`${this.baseUrl}${route}/${flowName}/runs/${runId}`);
+              return this.unwrapResponse(res);
+          },
+      },
   };
 
   /**
@@ -1016,6 +1222,188 @@ export class ObjectStackClient {
     }
   };
 
+  /**
+   * Feed / Chatter Services
+   *
+   * Provides access to the activity timeline (comments, field changes, tasks),
+   * emoji reactions, pin/star, search, changelog, and record subscriptions.
+   * Base path: /api/data/{object}/{recordId}/feed
+   */
+  feed = {
+    /**
+     * List feed items for a record
+     */
+    list: async (object: string, recordId: string, options?: { type?: string; limit?: number; cursor?: string }): Promise<GetFeedResponse> => {
+      const route = this.getRoute('feed');
+      const params = new URLSearchParams();
+      if (options?.type) params.set('type', options.type);
+      if (options?.limit) params.set('limit', String(options.limit));
+      if (options?.cursor) params.set('cursor', options.cursor);
+      const qs = params.toString();
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed${qs ? `?${qs}` : ''}`);
+      return this.unwrapResponse<GetFeedResponse>(res);
+    },
+
+    /**
+     * Create a new feed item (comment, note, task, etc.)
+     */
+    create: async (object: string, recordId: string, data: { type: string; body?: string; mentions?: any[]; parentId?: string; visibility?: string }): Promise<CreateFeedItemResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed`, {
+        method: 'POST',
+        body: JSON.stringify(data)
+      });
+      return this.unwrapResponse<CreateFeedItemResponse>(res);
+    },
+
+    /**
+     * Update an existing feed item
+     */
+    update: async (object: string, recordId: string, feedId: string, data: { body?: string; mentions?: any[]; visibility?: string }): Promise<UpdateFeedItemResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}`, {
+        method: 'PUT',
+        body: JSON.stringify(data)
+      });
+      return this.unwrapResponse<UpdateFeedItemResponse>(res);
+    },
+
+    /**
+     * Delete a feed item
+     */
+    delete: async (object: string, recordId: string, feedId: string): Promise<DeleteFeedItemResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}`, {
+        method: 'DELETE'
+      });
+      return this.unwrapResponse<DeleteFeedItemResponse>(res);
+    },
+
+    /**
+     * Add an emoji reaction to a feed item
+     */
+    addReaction: async (object: string, recordId: string, feedId: string, emoji: string): Promise<AddReactionResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/reactions`, {
+        method: 'POST',
+        body: JSON.stringify({ emoji })
+      });
+      return this.unwrapResponse<AddReactionResponse>(res);
+    },
+
+    /**
+     * Remove an emoji reaction from a feed item
+     */
+    removeReaction: async (object: string, recordId: string, feedId: string, emoji: string): Promise<RemoveReactionResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/reactions/${encodeURIComponent(emoji)}`, {
+        method: 'DELETE'
+      });
+      return this.unwrapResponse<RemoveReactionResponse>(res);
+    },
+
+    /**
+     * Pin a feed item to the top of the timeline
+     */
+    pin: async (object: string, recordId: string, feedId: string): Promise<PinFeedItemResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/pin`, {
+        method: 'POST'
+      });
+      return this.unwrapResponse<PinFeedItemResponse>(res);
+    },
+
+    /**
+     * Unpin a feed item
+     */
+    unpin: async (object: string, recordId: string, feedId: string): Promise<UnpinFeedItemResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/pin`, {
+        method: 'DELETE'
+      });
+      return this.unwrapResponse<UnpinFeedItemResponse>(res);
+    },
+
+    /**
+     * Star (bookmark) a feed item
+     */
+    star: async (object: string, recordId: string, feedId: string): Promise<StarFeedItemResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/star`, {
+        method: 'POST'
+      });
+      return this.unwrapResponse<StarFeedItemResponse>(res);
+    },
+
+    /**
+     * Unstar a feed item
+     */
+    unstar: async (object: string, recordId: string, feedId: string): Promise<UnstarFeedItemResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/star`, {
+        method: 'DELETE'
+      });
+      return this.unwrapResponse<UnstarFeedItemResponse>(res);
+    },
+
+    /**
+     * Search feed items
+     */
+    search: async (object: string, recordId: string, query: string, options?: { type?: string; actorId?: string; dateFrom?: string; dateTo?: string; limit?: number; cursor?: string }): Promise<SearchFeedResponse> => {
+      const route = this.getRoute('feed');
+      const params = new URLSearchParams();
+      params.set('query', query);
+      if (options?.type) params.set('type', options.type);
+      if (options?.actorId) params.set('actorId', options.actorId);
+      if (options?.dateFrom) params.set('dateFrom', options.dateFrom);
+      if (options?.dateTo) params.set('dateTo', options.dateTo);
+      if (options?.limit) params.set('limit', String(options.limit));
+      if (options?.cursor) params.set('cursor', options.cursor);
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/search?${params.toString()}`);
+      return this.unwrapResponse<SearchFeedResponse>(res);
+    },
+
+    /**
+     * Get field-level changelog for a record
+     */
+    getChangelog: async (object: string, recordId: string, options?: { field?: string; actorId?: string; dateFrom?: string; dateTo?: string; limit?: number; cursor?: string }): Promise<GetChangelogResponse> => {
+      const route = this.getRoute('feed');
+      const params = new URLSearchParams();
+      if (options?.field) params.set('field', options.field);
+      if (options?.actorId) params.set('actorId', options.actorId);
+      if (options?.dateFrom) params.set('dateFrom', options.dateFrom);
+      if (options?.dateTo) params.set('dateTo', options.dateTo);
+      if (options?.limit) params.set('limit', String(options.limit));
+      if (options?.cursor) params.set('cursor', options.cursor);
+      const qs = params.toString();
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/changelog${qs ? `?${qs}` : ''}`);
+      return this.unwrapResponse<GetChangelogResponse>(res);
+    },
+
+    /**
+     * Subscribe to record notifications
+     */
+    subscribe: async (object: string, recordId: string, options?: { events?: string[]; channels?: string[] }): Promise<SubscribeResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/subscribe`, {
+        method: 'POST',
+        body: JSON.stringify(options || {})
+      });
+      return this.unwrapResponse<SubscribeResponse>(res);
+    },
+
+    /**
+     * Unsubscribe from record notifications
+     */
+    unsubscribe: async (object: string, recordId: string): Promise<UnsubscribeResponse> => {
+      const route = this.getRoute('feed');
+      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/subscribe`, {
+        method: 'DELETE'
+      });
+      return this.unwrapResponse<UnsubscribeResponse>(res);
+    },
+  };
+
   /**
    * Data Operations
    */
@@ -1060,14 +1448,19 @@ export class ObjectStackClient {
         }
 
         // 4. Handle Filters (Simple vs AST)
-        if (options.filters) {
+        // Canonical HTTP param name: `filter` (singular). `filters` (plural) is accepted
+        // for backward compatibility but `filter` is the standard going forward.
+        const filterValue = options.filter ?? options.filters;
+        if (filterValue) {
              // Detect AST filter format vs simple key-value map. AST filters use an array structure
-             // with [field, operator, value] or [logicOp, ...nodes] shape (see isFilterAST).
+             // with [field, operator, value] or [logicOp, ...nodes] shape (see isFilterAST from spec).
              // For complex filter expressions, use .query() which builds a proper QueryAST.
-             if (this.isFilterAST(options.filters)) {
-                 queryParams.set('filters', JSON.stringify(options.filters));
-             } else {
-                 Object.entries(options.filters).forEach(([k, v]) => {
+             if (this.isFilterAST(filterValue) || Array.isArray(filterValue)) {
+                 // AST or any array → serialize as JSON in `filter` param
+                 queryParams.set('filter', JSON.stringify(filterValue));
+             } else if (typeof filterValue === 'object' && filterValue !== null) {
+                 // Plain key-value map → append each as individual query params
+                 Object.entries(filterValue as Record<string, unknown>).forEach(([k, v]) => {
                      if (v !== undefined && v !== null) {
                         queryParams.append(k, String(v));
                      }
@@ -1186,10 +1579,9 @@ export class ObjectStackClient {
    */
 
   private isFilterAST(filter: any): boolean {
-    // Basic check: if array, it's [field, op, val] or [logic, node, node]
-    // If object but not basic KV map... harder to tell without schema
-    // For now, assume if it passes Array.isArray it's an AST root
-    return Array.isArray(filter);
+    // Delegate to the spec-exported structural validator instead of naive Array.isArray.
+    // This checks for valid AST shapes: [field, op, val], [logic, ...nodes], or [[cond], ...].
+    return isFilterAST(filter);
   }
 
   /**
@@ -1271,7 +1663,7 @@ 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
    */
-  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth' | 'analytics' | 'storage' | 'automation' | 'packages' | 'permissions' | 'realtime' | 'workflow' | 'views' | 'notifications' | 'ai' | 'i18n'): string {
+  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth' | 'analytics' | 'storage' | 'automation' | 'packages' | 'permissions' | 'realtime' | 'workflow' | 'views' | 'notifications' | 'ai' | 'i18n' | 'feed'): string {
     // 1. Use discovered routes if available
     if (this.discoveryInfo?.routes && (this.discoveryInfo.routes as any)[type]) {
         return (this.discoveryInfo.routes as any)[type];
@@ -1294,6 +1686,7 @@ export class ObjectStackClient {
       notifications: '/api/v1/notifications',
       ai: '/api/v1/ai',
       i18n: '/api/v1/i18n',
+      feed: '/api/v1/data',
     };
     
     return routeMap[type] || `/api/v1/${type}`;
@@ -1356,5 +1749,20 @@ export type {
   GetTranslationsResponse,
   GetFieldLabelsResponse,
   RegisterRequest,
-  RefreshTokenRequest
+  RefreshTokenRequest,
+  GetFeedResponse,
+  CreateFeedItemResponse,
+  UpdateFeedItemResponse,
+  DeleteFeedItemResponse,
+  AddReactionResponse,
+  RemoveReactionResponse,
+  PinFeedItemResponse,
+  UnpinFeedItemResponse,
+  StarFeedItemResponse,
+  UnstarFeedItemResponse,
+  SearchFeedResponse,
+  GetChangelogResponse,
+  SubscribeResponse,
+  UnsubscribeResponse,
+  WellKnownCapabilities,
 } from '@objectstack/spec/api';