@objectstack/client 4.0.3 → 4.0.5

package/src/index.ts

@@ -1,1875 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { QueryAST, SortNode, AggregationNode, isFilterAST } from '@objectstack/spec/data';
-import {
-  BatchUpdateRequest,
-  BatchUpdateResponse,
-  UpdateManyRequest,
-  DeleteManyRequest,
-  BatchOptions,
-  MetadataCacheRequest,
-  MetadataCacheResponse,
-  StandardErrorCode,
-  ErrorCategory,
-  GetDiscoveryResponse,
-  GetMetaTypesResponse,
-  GetMetaItemsResponse,
-  LoginRequest,
-  SessionResponse,
-  GetPresignedUrlRequest,
-  PresignedUrlResponse,
-  CompleteUploadRequest,
-  FileUploadResponse,
-  InitiateChunkedUploadRequest,
-  InitiateChunkedUploadResponse,
-  UploadChunkResponse,
-  CompleteChunkedUploadRequest,
-  CompleteChunkedUploadResponse,
-  UploadProgress,
-  CheckPermissionRequest,
-  CheckPermissionResponse,
-  GetObjectPermissionsResponse,
-  GetEffectivePermissionsResponse,
-  RealtimeConnectRequest,
-  RealtimeConnectResponse,
-  RealtimeSubscribeRequest,
-  RealtimeSubscribeResponse,
-  SetPresenceRequest,
-  GetPresenceResponse,
-  GetWorkflowConfigResponse,
-  GetWorkflowStateResponse,
-  WorkflowTransitionRequest,
-  WorkflowTransitionResponse,
-  WorkflowApproveRequest,
-  WorkflowApproveResponse,
-  WorkflowRejectRequest,
-  WorkflowRejectResponse,
-  ListViewsResponse,
-  GetViewResponse,
-  CreateViewRequest,
-  CreateViewResponse,
-  UpdateViewRequest,
-  UpdateViewResponse,
-  DeleteViewResponse,
-  RegisterDeviceRequest,
-  RegisterDeviceResponse,
-  UnregisterDeviceResponse,
-  GetNotificationPreferencesResponse,
-  UpdateNotificationPreferencesRequest,
-  UpdateNotificationPreferencesResponse,
-  ListNotificationsResponse,
-  MarkNotificationsReadResponse,
-  MarkAllNotificationsReadResponse,
-  AiNlqRequest,
-  AiNlqResponse,
-  AiSuggestRequest,
-  AiSuggestResponse,
-  AiInsightsRequest,
-  AiInsightsResponse,
-  GetLocalesResponse,
-  GetTranslationsResponse,
-  GetFieldLabelsResponse,
-  RegisterRequest,
-  GetFeedResponse,
-  CreateFeedItemResponse,
-  UpdateFeedItemResponse,
-  DeleteFeedItemResponse,
-  AddReactionResponse,
-  RemoveReactionResponse,
-  PinFeedItemResponse,
-  UnpinFeedItemResponse,
-  StarFeedItemResponse,
-  UnstarFeedItemResponse,
-  SearchFeedResponse,
-  GetChangelogResponse,
-  SubscribeResponse,
-  UnsubscribeResponse,
-  WellKnownCapabilities,
-  ApiRoutes,
-} from '@objectstack/spec/api';
-import { Logger, createLogger } from '@objectstack/core';
-import { RealtimeAPI } from './realtime-api';
-
-/**
- * Route types that the client can resolve.
- * Covers all keys from `ApiRoutes` (the discovery schema) plus
- * client-specific virtual routes (`views`, `permissions`).
- */
-export type ApiRouteType = keyof ApiRoutes | 'views' | 'permissions';
-
-export interface ClientConfig {
-  baseUrl: string;
-  token?: string;
-  /**
-   * 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;
-}
-
-/**
- * Discovery Result
- * Re-export from @objectstack/spec/api for convenience
- */
-export type DiscoveryResult = GetDiscoveryResponse;
-
-/**
- * @deprecated Use `data.query()` with standard QueryAST parameters instead.
- * This interface uses legacy parameter names (filter/sort/top/skip) that
- * require translation to QueryAST. Prefer QueryAST fields directly:
- *   - filter → where
- *   - select → fields
- *   - sort → orderBy
- *   - skip → offset
- *   - top → limit
- */
-export interface QueryOptions {
-  select?: string[]; // Simplified Selection
-  /** @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;
-  // Advanced features
-  aggregations?: AggregationNode[];
-  groupBy?: string[];
-}
-
-/**
- * Canonical query options using Spec protocol field names.
- * This is the recommended interface for `data.find()` queries.
- *
- *  Canonical field mapping (QueryAST-aligned):
- *   - `where`   — filter conditions (replaces legacy `filter`/`filters`)
- *   - `fields`  — field selection  (replaces legacy `select`)
- *   - `orderBy` — sort definition  (replaces legacy `sort`)
- *   - `limit`   — max records      (replaces legacy `top`)
- *   - `offset`  — skip records     (replaces legacy `skip`)
- *   - `expand`  — relation loading (replaces legacy `populate`)
- */
-export interface QueryOptionsV2 {
-  /** Filter conditions (WHERE clause). Accepts MongoDB-style $op object or FilterCondition AST. */
-  where?: Record<string, any> | unknown[];
-  /** Fields to retrieve (SELECT clause). */
-  fields?: string[];
-  /** Sort definition (ORDER BY clause). */
-  orderBy?: string | string[] | SortNode[];
-  /** Maximum number of records to return (LIMIT). */
-  limit?: number;
-  /** Number of records to skip (OFFSET). */
-  offset?: number;
-  /** Relations to expand (JOIN / eager-load). */
-  expand?: Record<string, any> | string[];
-  /** Aggregation functions. */
-  aggregations?: AggregationNode[];
-  /** Group by fields. */
-  groupBy?: string[];
-}
-
-export interface PaginatedResult<T = any> {
-  /** Spec-compliant: array of matching records */
-  records: T[];
-  /** Total number of matching records (if requested) */
-  total?: number;
-  /** The object name */
-  object?: string;
-  /** Whether more records are available */
-  hasMore?: boolean;
-}
-
-/** Spec: GetDataResponseSchema */
-export interface GetDataResult<T = any> {
-  object: string;
-  id: string;
-  record: T;
-}
-
-/** Spec: CreateDataResponseSchema */
-export interface CreateDataResult<T = any> {
-  object: string;
-  id: string;
-  record: T;
-}
-
-/** Spec: UpdateDataResponseSchema */
-export interface UpdateDataResult<T = any> {
-  object: string;
-  id: string;
-  record: T;
-}
-
-/** Spec: DeleteDataResponseSchema */
-export interface DeleteDataResult {
-  object: string;
-  id: string;
-  deleted: boolean;
-}
-
-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 discoveryInfo?: DiscoveryResult;
-  private logger: Logger;
-  private realtimeAPI: RealtimeAPI;
-
-  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'
-    });
-
-    // Initialize realtime API
-    this.realtimeAPI = new RealtimeAPI(this.baseUrl, this.token);
-
-    this.logger.debug('ObjectStack client created', { baseUrl: this.baseUrl });
-  }
-
-  /**
-   * Initialize the client by discovering server capabilities.
-   */
-  async connect() {
-    this.logger.debug('Connecting to ObjectStack server', { baseUrl: this.baseUrl });
-    
-    try {
-      let data: DiscoveryResult | undefined;
-
-      // 1. Try Standard Discovery (.well-known)
-      try {
-        let wellKnownUrl: string;
-        try {
-          // If baseUrl is absolute, get origin
-          const url = new URL(this.baseUrl);
-          wellKnownUrl = `${url.origin}/.well-known/objectstack`;
-        } catch {
-          // If baseUrl is relative, use absolute path from root
-          wellKnownUrl = '/.well-known/objectstack';
-        }
-
-        this.logger.debug('Probing .well-known discovery', { url: wellKnownUrl });
-        const res = await this.fetchImpl(wellKnownUrl);
-        if (res.ok) {
-          const body = await res.json();
-          data = body.data || body;
-          this.logger.debug('Discovered via .well-known');
-        }
-      } catch (e) {
-        this.logger.debug('Standard discovery probe failed', { error: (e as Error).message });
-      }
-
-      // 2. Fallback to Protocol-standard Discovery Path /api/v1/discovery
-      if (!data) {
-        const fallbackUrl = `${this.baseUrl}/api/v1/discovery`;
-        this.logger.debug('Falling back to standard discovery endpoint', { url: fallbackUrl });
-        const res = await this.fetchImpl(fallbackUrl);
-        if (!res.ok) {
-           throw new Error(`Failed to connect to ${fallbackUrl}: ${res.statusText}`);
-        }
-        const body = await res.json();
-        data = body.data || body;
-      }
-
-      if (!data) {
-         throw new Error('Connection failed: No discovery data returned');
-      }
-
-      this.discoveryInfo = data;
-      
-      this.logger.info('Connected to ObjectStack server', { 
-        version: data.version,
-        apiName: data.apiName,
-        services: data.services 
-      });
-      
-      return data as DiscoveryResult;
-    } catch (e) {
-      this.logger.error('Failed to connect to ObjectStack server', e as Error, { baseUrl: this.baseUrl });
-      throw e;
-    }
-  }
-
-  /**
-   * 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.
-   *
-   * The server may return capabilities in hierarchical format
-   * `{ key: { enabled: boolean } }` or flat boolean format `{ key: boolean }`.
-   * This getter normalizes both to flat `WellKnownCapabilities`.
-   */
-  get capabilities(): WellKnownCapabilities | undefined {
-    const raw = this.discoveryInfo?.capabilities;
-    if (!raw) return undefined;
-    // Normalize: hierarchical { enabled: boolean } → flat boolean
-    const result: Record<string, boolean> = {};
-    for (const [key, value] of Object.entries(raw)) {
-      result[key] = typeof value === 'object' && value !== null ? !!(value as any).enabled : !!value;
-    }
-    return result as unknown as WellKnownCapabilities;
-  }
-
-  /**
-   * 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 this.unwrapResponse<GetMetaTypesResponse>(res);
-    },
-
-    /**
-     * Get all items of a specific metadata type
-     * @param type - Metadata type name (e.g., 'object', 'plugin')
-     * @param options - Optional filters (e.g., packageId to scope by package)
-     */
-    getItems: async (type: string, options?: { packageId?: string }): Promise<GetMetaItemsResponse> => {
-        const route = this.getRoute('metadata');
-        const params = new URLSearchParams();
-        if (options?.packageId) params.set('package', options.packageId);
-        const qs = params.toString();
-        const url = `${this.baseUrl}${route}/${type}${qs ? `?${qs}` : ''}`;
-        const res = await this.fetch(url);
-        return this.unwrapResponse<GetMetaItemsResponse>(res);
-    },
-
-    /**
-     * Get a specific metadata item by type and name
-     * @param type - Metadata type (e.g., 'object', 'plugin')
-     * @param name - Item name (snake_case identifier)
-     * @param options - Optional filters (e.g., packageId to scope by package)
-     */
-    getItem: async (type: string, name: string, options?: { packageId?: string }) => {
-        const route = this.getRoute('metadata');
-        const params = new URLSearchParams();
-        if (options?.packageId) params.set('package', options.packageId);
-        const qs = params.toString();
-        const url = `${this.baseUrl}${route}/${type}/${name}${qs ? `?${qs}` : ''}`;
-        const res = await this.fetch(url);
-        return this.unwrapResponse(res);
-    },
-
-    /**
-     * Save a metadata item
-     * @param type - Metadata type (e.g., 'object', 'plugin')
-     * @param name - Item name
-     * @param item - The metadata content to save
-     */
-    saveItem: async (type: string, name: string, item: any) => {
-        const route = this.getRoute('metadata');
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`, {
-            method: 'PUT',
-            body: JSON.stringify(item)
-        });
-        return this.unwrapResponse(res);
-    },
-
-    /**
-     * Delete a metadata item
-     * @param type - Metadata type (e.g., 'object', 'plugin')
-     * @param name - Item name (snake_case identifier)
-     */
-    deleteItem: async (type: string, name: string): Promise<{ type: string; name: string; deleted: boolean }> => {
-        const route = this.getRoute('metadata');
-        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`, {
-            method: 'DELETE',
-        });
-        return this.unwrapResponse(res);
-    },
-    
-    /**
-     * 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}`);
-        return this.unwrapResponse(res);
-    }
-  };
-
-  /**
-   * 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();
-    }
-  };
-
-  /**
-   * Package Management Services
-   * 
-   * Manages the lifecycle of installed packages.
-   * A package (ManifestSchema) is the unit of installation.
-   * An app (AppSchema) is a UI navigation definition within a package.
-   * A package may contain 0, 1, or many apps, or be a pure functionality plugin.
-   * 
-   * Endpoints:
-   * - GET    /packages               → list installed packages
-   * - GET    /packages/:id           → get package details  
-   * - POST   /packages               → install a package
-   * - DELETE  /packages/:id           → uninstall a package
-   * - PATCH  /packages/:id/enable    → enable a package
-   * - PATCH  /packages/:id/disable   → disable a package
-   */
-  packages = {
-    /**
-     * List all installed packages with optional filters.
-     */
-    list: async (filters?: { status?: string; type?: string; enabled?: boolean }) => {
-        const route = this.getRoute('packages');
-        const params = new URLSearchParams();
-        if (filters?.status) params.set('status', filters.status);
-        if (filters?.type) params.set('type', filters.type);
-        if (filters?.enabled !== undefined) params.set('enabled', String(filters.enabled));
-        const qs = params.toString();
-        const url = `${this.baseUrl}${route}${qs ? '?' + qs : ''}`;
-        const res = await this.fetch(url);
-        return this.unwrapResponse<{ packages: any[]; total: number }>(res);
-    },
-
-    /**
-     * Get a specific installed package by its ID (reverse domain identifier).
-     */
-    get: async (id: string) => {
-        const route = this.getRoute('packages');
-        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}`);
-        return this.unwrapResponse<{ package: any }>(res);
-    },
-
-    /**
-     * Install a new package from its manifest.
-     */
-    install: async (manifest: any, options?: { settings?: Record<string, any>; enableOnInstall?: boolean }) => {
-        const route = this.getRoute('packages');
-        const res = await this.fetch(`${this.baseUrl}${route}`, {
-            method: 'POST',
-            body: JSON.stringify({
-                manifest,
-                settings: options?.settings,
-                enableOnInstall: options?.enableOnInstall,
-            }),
-        });
-        return this.unwrapResponse<{ package: any; message?: string }>(res);
-    },
-
-    /**
-     * Uninstall a package by its ID.
-     */
-    uninstall: async (id: string) => {
-        const route = this.getRoute('packages');
-        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}`, {
-            method: 'DELETE',
-        });
-        return this.unwrapResponse<{ id: string; success: boolean; message?: string }>(res);
-    },
-
-    /**
-     * Enable a disabled package.
-     */
-    enable: async (id: string) => {
-        const route = this.getRoute('packages');
-        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}/enable`, {
-            method: 'PATCH',
-        });
-        return this.unwrapResponse<{ package: any; message?: string }>(res);
-    },
-
-    /**
-     * Disable an installed package.
-     */
-    disable: async (id: string) => {
-        const route = this.getRoute('packages');
-        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(id)}/disable`, {
-            method: 'PATCH',
-        });
-        return this.unwrapResponse<{ package: any; message?: string }>(res);
-    },
-  };
-
-  /**
-   * Authentication Services
-   */
-  auth = {
-    /**
-     * Login with email and password
-     * Uses better-auth endpoint: POST /sign-in/email
-     */
-    login: async (request: LoginRequest): Promise<SessionResponse> => {
-        const route = this.getRoute('auth');
-        const res = await this.fetch(`${this.baseUrl}${route}/sign-in/email`, {
-            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 current user
-     * Uses better-auth endpoint: POST /sign-out
-     */
-    logout: async () => {
-        const route = this.getRoute('auth');
-        await this.fetch(`${this.baseUrl}${route}/sign-out`, { method: 'POST' });
-        this.token = undefined;
-    },
-
-    /**
-     * Get current user session
-     * Uses better-auth endpoint: GET /get-session
-     */
-    me: async (): Promise<SessionResponse> => {
-        const route = this.getRoute('auth');
-        const res = await this.fetch(`${this.baseUrl}${route}/get-session`);
-        return res.json();
-    },
-
-    /**
-     * Register a new user account
-     * Uses better-auth endpoint: POST /sign-up/email
-     */
-    register: async (request: RegisterRequest): Promise<SessionResponse> => {
-      const route = this.getRoute('auth');
-      const res = await this.fetch(`${this.baseUrl}${route}/sign-up/email`, {
-        method: 'POST',
-        body: JSON.stringify(request)
-      });
-      const data = await res.json();
-      if (data.data?.token) {
-        this.token = data.data.token;
-      }
-      return data;
-    },
-
-    /**
-     * Refresh an authentication token
-     * Note: better-auth handles token refresh automatically via /get-session
-     * @param _refreshToken - Not used (better-auth handles refresh automatically)
-     */
-    refreshToken: async (_refreshToken: string): Promise<SessionResponse> => {
-      const route = this.getRoute('auth');
-      // better-auth doesn't have a separate refresh endpoint
-      // Session refresh is handled automatically when calling /get-session
-      const res = await this.fetch(`${this.baseUrl}${route}/get-session`, {
-        method: 'GET'
-      });
-      const data = await res.json();
-      if (data.data?.token) {
-        this.token = data.data.token;
-      }
-      return data;
-    }
-  };
-
-  /**
-   * 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;
-    },
-
-    /**
-     * 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}`, {
-              method: 'POST',
-              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);
-          },
-      },
-  };
-
-  /**
-   * Event Subscription API
-   * Provides real-time event subscriptions for metadata and data changes
-   */
-  get events() {
-    return this.realtimeAPI;
-  }
-
-  /**
-   * Permissions Services
-   */
-  permissions = {
-    /**
-     * Check if current user has permission for an action on an object
-     */
-    check: async (request: CheckPermissionRequest): Promise<CheckPermissionResponse> => {
-      const route = this.getRoute('permissions');
-      const params = new URLSearchParams({ object: request.object, action: request.action });
-      if (request.recordId !== undefined) params.set('recordId', request.recordId);
-      if (request.field !== undefined) params.set('field', request.field);
-      const res = await this.fetch(`${this.baseUrl}${route}/check?${params.toString()}`);
-      return this.unwrapResponse<CheckPermissionResponse>(res);
-    },
-
-    /**
-     * Get all permissions for a specific object
-     */
-    getObjectPermissions: async (object: string): Promise<GetObjectPermissionsResponse> => {
-      const route = this.getRoute('permissions');
-      const res = await this.fetch(`${this.baseUrl}${route}/objects/${encodeURIComponent(object)}`);
-      return this.unwrapResponse<GetObjectPermissionsResponse>(res);
-    },
-
-    /**
-     * Get effective permissions for the current user
-     */
-    getEffectivePermissions: async (): Promise<GetEffectivePermissionsResponse> => {
-      const route = this.getRoute('permissions');
-      const res = await this.fetch(`${this.baseUrl}${route}/effective`);
-      return this.unwrapResponse<GetEffectivePermissionsResponse>(res);
-    }
-  };
-
-  /**
-   * Realtime Services
-   */
-  realtime = {
-    /**
-     * Establish a realtime connection
-     */
-    connect: async (request?: RealtimeConnectRequest): Promise<RealtimeConnectResponse> => {
-      const route = this.getRoute('realtime');
-      const res = await this.fetch(`${this.baseUrl}${route}/connect`, {
-        method: 'POST',
-        body: JSON.stringify(request || {})
-      });
-      return this.unwrapResponse<RealtimeConnectResponse>(res);
-    },
-
-    /**
-     * Disconnect from realtime services
-     */
-    disconnect: async (): Promise<void> => {
-      const route = this.getRoute('realtime');
-      await this.fetch(`${this.baseUrl}${route}/disconnect`, {
-        method: 'POST'
-      });
-    },
-
-    /**
-     * Subscribe to a channel
-     */
-    subscribe: async (request: RealtimeSubscribeRequest): Promise<RealtimeSubscribeResponse> => {
-      const route = this.getRoute('realtime');
-      const res = await this.fetch(`${this.baseUrl}${route}/subscribe`, {
-        method: 'POST',
-        body: JSON.stringify(request)
-      });
-      return this.unwrapResponse<RealtimeSubscribeResponse>(res);
-    },
-
-    /**
-     * Unsubscribe from a channel
-     */
-    unsubscribe: async (subscriptionId: string): Promise<void> => {
-      const route = this.getRoute('realtime');
-      await this.fetch(`${this.baseUrl}${route}/unsubscribe`, {
-        method: 'POST',
-        body: JSON.stringify({ subscriptionId })
-      });
-    },
-
-    /**
-     * Set presence state on a channel
-     */
-    setPresence: async (channel: string, state: SetPresenceRequest['state']): Promise<void> => {
-      const route = this.getRoute('realtime');
-      await this.fetch(`${this.baseUrl}${route}/presence`, {
-        method: 'PUT',
-        body: JSON.stringify({ channel, state })
-      });
-    },
-
-    /**
-     * Get presence information for a channel
-     */
-    getPresence: async (channel: string): Promise<GetPresenceResponse> => {
-      const route = this.getRoute('realtime');
-      const res = await this.fetch(`${this.baseUrl}${route}/presence/${encodeURIComponent(channel)}`);
-      return this.unwrapResponse<GetPresenceResponse>(res);
-    }
-  };
-
-  /**
-   * Workflow Services
-   */
-  workflow = {
-    /**
-     * Get workflow configuration for an object
-     */
-    getConfig: async (object: string): Promise<GetWorkflowConfigResponse> => {
-      const route = this.getRoute('workflow');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/config`);
-      return this.unwrapResponse<GetWorkflowConfigResponse>(res);
-    },
-
-    /**
-     * Get current workflow state for a record
-     */
-    getState: async (object: string, recordId: string): Promise<GetWorkflowStateResponse> => {
-      const route = this.getRoute('workflow');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/state`);
-      return this.unwrapResponse<GetWorkflowStateResponse>(res);
-    },
-
-    /**
-     * Execute a workflow state transition
-     */
-    transition: async (request: WorkflowTransitionRequest): Promise<WorkflowTransitionResponse> => {
-      const route = this.getRoute('workflow');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(request.object)}/${encodeURIComponent(request.recordId)}/transition`, {
-        method: 'POST',
-        body: JSON.stringify({
-          transition: request.transition,
-          comment: request.comment,
-          data: request.data
-        })
-      });
-      return this.unwrapResponse<WorkflowTransitionResponse>(res);
-    },
-
-    /**
-     * Approve a workflow step
-     */
-    approve: async (request: WorkflowApproveRequest): Promise<WorkflowApproveResponse> => {
-      const route = this.getRoute('workflow');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(request.object)}/${encodeURIComponent(request.recordId)}/approve`, {
-        method: 'POST',
-        body: JSON.stringify({
-          comment: request.comment,
-          data: request.data
-        })
-      });
-      return this.unwrapResponse<WorkflowApproveResponse>(res);
-    },
-
-    /**
-     * Reject a workflow step
-     */
-    reject: async (request: WorkflowRejectRequest): Promise<WorkflowRejectResponse> => {
-      const route = this.getRoute('workflow');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(request.object)}/${encodeURIComponent(request.recordId)}/reject`, {
-        method: 'POST',
-        body: JSON.stringify({
-          reason: request.reason,
-          comment: request.comment
-        })
-      });
-      return this.unwrapResponse<WorkflowRejectResponse>(res);
-    }
-  };
-
-  /**
-   * Views CRUD Services
-   */
-  views = {
-    /**
-     * List views for an object
-     */
-    list: async (object: string, type?: 'list' | 'form'): Promise<ListViewsResponse> => {
-      const route = this.getRoute('views');
-      const params = new URLSearchParams();
-      if (type) params.set('type', type);
-      const qs = params.toString();
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}${qs ? `?${qs}` : ''}`);
-      return this.unwrapResponse<ListViewsResponse>(res);
-    },
-
-    /**
-     * Get a specific view
-     */
-    get: async (object: string, viewId: string): Promise<GetViewResponse> => {
-      const route = this.getRoute('views');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(viewId)}`);
-      return this.unwrapResponse<GetViewResponse>(res);
-    },
-
-    /**
-     * Create a new view
-     */
-    create: async (object: string, data: CreateViewRequest['data']): Promise<CreateViewResponse> => {
-      const route = this.getRoute('views');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}`, {
-        method: 'POST',
-        body: JSON.stringify({ object, data })
-      });
-      return this.unwrapResponse<CreateViewResponse>(res);
-    },
-
-    /**
-     * Update an existing view
-     */
-    update: async (object: string, viewId: string, data: UpdateViewRequest['data']): Promise<UpdateViewResponse> => {
-      const route = this.getRoute('views');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(viewId)}`, {
-        method: 'PUT',
-        body: JSON.stringify({ object, viewId, data })
-      });
-      return this.unwrapResponse<UpdateViewResponse>(res);
-    },
-
-    /**
-     * Delete a view
-     */
-    delete: async (object: string, viewId: string): Promise<DeleteViewResponse> => {
-      const route = this.getRoute('views');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(viewId)}`, {
-        method: 'DELETE'
-      });
-      return this.unwrapResponse<DeleteViewResponse>(res);
-    }
-  };
-
-  /**
-   * Notification Services
-   */
-  notifications = {
-    /**
-     * Register a device for push notifications
-     */
-    registerDevice: async (request: RegisterDeviceRequest): Promise<RegisterDeviceResponse> => {
-      const route = this.getRoute('notifications');
-      const res = await this.fetch(`${this.baseUrl}${route}/devices`, {
-        method: 'POST',
-        body: JSON.stringify(request)
-      });
-      return this.unwrapResponse<RegisterDeviceResponse>(res);
-    },
-
-    /**
-     * Unregister a device from push notifications
-     */
-    unregisterDevice: async (deviceId: string): Promise<UnregisterDeviceResponse> => {
-      const route = this.getRoute('notifications');
-      const res = await this.fetch(`${this.baseUrl}${route}/devices/${encodeURIComponent(deviceId)}`, {
-        method: 'DELETE'
-      });
-      return this.unwrapResponse<UnregisterDeviceResponse>(res);
-    },
-
-    /**
-     * Get notification preferences for the current user
-     */
-    getPreferences: async (): Promise<GetNotificationPreferencesResponse> => {
-      const route = this.getRoute('notifications');
-      const res = await this.fetch(`${this.baseUrl}${route}/preferences`);
-      return this.unwrapResponse<GetNotificationPreferencesResponse>(res);
-    },
-
-    /**
-     * Update notification preferences
-     */
-    updatePreferences: async (preferences: UpdateNotificationPreferencesRequest['preferences']): Promise<UpdateNotificationPreferencesResponse> => {
-      const route = this.getRoute('notifications');
-      const res = await this.fetch(`${this.baseUrl}${route}/preferences`, {
-        method: 'PUT',
-        body: JSON.stringify({ preferences })
-      });
-      return this.unwrapResponse<UpdateNotificationPreferencesResponse>(res);
-    },
-
-    /**
-     * List notifications for the current user
-     */
-    list: async (options?: { read?: boolean; type?: string; limit?: number; cursor?: string }): Promise<ListNotificationsResponse> => {
-      const route = this.getRoute('notifications');
-      const params = new URLSearchParams();
-      if (options?.read !== undefined) params.set('read', String(options.read));
-      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}${qs ? `?${qs}` : ''}`);
-      return this.unwrapResponse<ListNotificationsResponse>(res);
-    },
-
-    /**
-     * Mark specific notifications as read
-     */
-    markRead: async (ids: string[]): Promise<MarkNotificationsReadResponse> => {
-      const route = this.getRoute('notifications');
-      const res = await this.fetch(`${this.baseUrl}${route}/read`, {
-        method: 'POST',
-        body: JSON.stringify({ ids })
-      });
-      return this.unwrapResponse<MarkNotificationsReadResponse>(res);
-    },
-
-    /**
-     * Mark all notifications as read
-     */
-    markAllRead: async (): Promise<MarkAllNotificationsReadResponse> => {
-      const route = this.getRoute('notifications');
-      const res = await this.fetch(`${this.baseUrl}${route}/read/all`, {
-        method: 'POST'
-      });
-      return this.unwrapResponse<MarkAllNotificationsReadResponse>(res);
-    }
-  };
-
-  /**
-   * AI Services
-   */
-  ai = {
-    /**
-     * Natural language query — converts natural language to structured query
-     */
-    nlq: async (request: AiNlqRequest): Promise<AiNlqResponse> => {
-      const route = this.getRoute('ai');
-      const res = await this.fetch(`${this.baseUrl}${route}/nlq`, {
-        method: 'POST',
-        body: JSON.stringify(request)
-      });
-      return this.unwrapResponse<AiNlqResponse>(res);
-    },
-
-    // AI chat method removed — use Vercel AI SDK `useChat()` / `@ai-sdk/react` directly.
-
-    /**
-     * AI-powered field value suggestions
-     */
-    suggest: async (request: AiSuggestRequest): Promise<AiSuggestResponse> => {
-      const route = this.getRoute('ai');
-      const res = await this.fetch(`${this.baseUrl}${route}/suggest`, {
-        method: 'POST',
-        body: JSON.stringify(request)
-      });
-      return this.unwrapResponse<AiSuggestResponse>(res);
-    },
-
-    /**
-     * AI-powered data insights
-     */
-    insights: async (request: AiInsightsRequest): Promise<AiInsightsResponse> => {
-      const route = this.getRoute('ai');
-      const res = await this.fetch(`${this.baseUrl}${route}/insights`, {
-        method: 'POST',
-        body: JSON.stringify(request)
-      });
-      return this.unwrapResponse<AiInsightsResponse>(res);
-    }
-  };
-
-  /**
-   * Internationalization Services
-   */
-  i18n = {
-    /**
-     * Get available locales
-     */
-    getLocales: async (): Promise<GetLocalesResponse> => {
-      const route = this.getRoute('i18n');
-      const res = await this.fetch(`${this.baseUrl}${route}/locales`);
-      return this.unwrapResponse<GetLocalesResponse>(res);
-    },
-
-    /**
-     * Get translations for a locale
-     */
-    getTranslations: async (locale: string, options?: { namespace?: string; keys?: string[] }): Promise<GetTranslationsResponse> => {
-      const route = this.getRoute('i18n');
-      const params = new URLSearchParams();
-      params.set('locale', locale);
-      if (options?.namespace) params.set('namespace', options.namespace);
-      if (options?.keys) params.set('keys', options.keys.join(','));
-      const res = await this.fetch(`${this.baseUrl}${route}/translations?${params.toString()}`);
-      return this.unwrapResponse<GetTranslationsResponse>(res);
-    },
-
-    /**
-     * Get translated field labels for an object
-     */
-    getFieldLabels: async (object: string, locale: string): Promise<GetFieldLabelsResponse> => {
-      const route = this.getRoute('i18n');
-      const res = await this.fetch(`${this.baseUrl}${route}/labels/${encodeURIComponent(object)}?locale=${encodeURIComponent(locale)}`);
-      return this.unwrapResponse<GetFieldLabelsResponse>(res);
-    }
-  };
-
-  /**
-   * 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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      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('data');
-      const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/subscribe`, {
-        method: 'DELETE'
-      });
-      return this.unwrapResponse<UnsubscribeResponse>(res);
-    },
-  };
-
-  /**
-   * Data Operations
-   */
-  data = {
-    /**
-     * Advanced Query using ObjectStack Query Protocol
-     * Supports both simplified options and full AST
-     */
-    query: async <T = any>(object: string, query: Partial<QueryAST>): Promise<PaginatedResult<T>> => {
-      const route = this.getRoute('data');
-      // POST for complex query to avoid URL length limits and allow clean JSON AST
-      // Convention: POST /api/v1/data/:object/query
-      const res = await this.fetch(`${this.baseUrl}${route}/${object}/query`, {
-        method: 'POST',
-        body: JSON.stringify(query)
-      });
-      return this.unwrapResponse<PaginatedResult<T>>(res);
-    },
-
-    /**
-     * @deprecated Use `data.query()` with standard QueryAST parameters instead.
-     * This method uses legacy parameter names. Internally adapts to HTTP GET params.
-     */
-    find: async <T = any>(object: string, options: QueryOptions | QueryOptionsV2 = {}): Promise<PaginatedResult<T>> => {
-        const route = this.getRoute('data');
-        const queryParams = new URLSearchParams();
-
-        // ── Normalize V2 canonical options → HTTP transport params ───
-        // Detect V2 options by presence of canonical-only keys.
-        const v2 = options as QueryOptionsV2;
-        const normalizedOptions: QueryOptions = {} as QueryOptions;
-        if ('where' in options || 'fields' in options || 'orderBy' in options || 'offset' in options) {
-            // V2 canonical options detected — map to legacy HTTP transport keys
-            if (v2.where) normalizedOptions.filter = v2.where as any;
-            if (v2.fields) normalizedOptions.select = v2.fields;
-            if (v2.orderBy) normalizedOptions.sort = v2.orderBy as any;
-            if (v2.limit != null) normalizedOptions.top = v2.limit;
-            if (v2.offset != null) normalizedOptions.skip = v2.offset;
-            if (v2.aggregations) normalizedOptions.aggregations = v2.aggregations;
-            if (v2.groupBy) normalizedOptions.groupBy = v2.groupBy;
-        } else {
-            // Legacy QueryOptions — pass through as-is
-            Object.assign(normalizedOptions, options);
-        }
-
-        // 1. Handle Pagination
-        if (normalizedOptions.top) queryParams.set('top', normalizedOptions.top.toString());
-        if (normalizedOptions.skip) queryParams.set('skip', normalizedOptions.skip.toString());
-
-        // 2. Handle Sort
-        if (normalizedOptions.sort) {
-            // Check if it's AST 
-            if (Array.isArray(normalizedOptions.sort) && typeof normalizedOptions.sort[0] === 'object') {
-                 queryParams.set('sort', JSON.stringify(normalizedOptions.sort));
-            } else {
-                 const sortVal = Array.isArray(normalizedOptions.sort) ? normalizedOptions.sort.join(',') : normalizedOptions.sort;
-                 queryParams.set('sort', sortVal as string);
-            }
-        }
-        
-        // 3. Handle Select
-        if (normalizedOptions.select) {
-            queryParams.set('select', normalizedOptions.select.join(','));
-        }
-
-        // 4. Handle Filters (Simple vs AST)
-        // Canonical HTTP param name: `filter` (singular). `filters` (plural) is accepted
-        // for backward compatibility but `filter` is the standard going forward.
-        const filterValue = normalizedOptions.filter ?? normalizedOptions.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 from spec).
-             // For complex filter expressions, use .query() which builds a proper QueryAST.
-             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));
-                     }
-                 });
-             }
-        }
-        
-        // 5. Handle Aggregations & GroupBy (Pass through as JSON if present)
-        if (normalizedOptions.aggregations) {
-            queryParams.set('aggregations', JSON.stringify(normalizedOptions.aggregations));
-        }
-        if (normalizedOptions.groupBy) {
-             queryParams.set('groupBy', normalizedOptions.groupBy.join(','));
-        }
-
-        const res = await this.fetch(`${this.baseUrl}${route}/${object}?${queryParams.toString()}`);
-        return this.unwrapResponse<PaginatedResult<T>>(res);
-    },
-
-    get: async <T = any>(object: string, id: string): Promise<GetDataResult<T>> => {
-        const route = this.getRoute('data');
-        const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`);
-        return this.unwrapResponse<GetDataResult<T>>(res);
-    },
-
-    create: async <T = any>(object: string, data: Partial<T>): Promise<CreateDataResult<T>> => {
-        const route = this.getRoute('data');
-        const res = await this.fetch(`${this.baseUrl}${route}/${object}`, {
-            method: 'POST',
-            body: JSON.stringify(data)
-        });
-        return this.unwrapResponse<CreateDataResult<T>>(res);
-    },
-
-    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}/createMany`, {
-            method: 'POST',
-            body: JSON.stringify(data)
-        });
-        return this.unwrapResponse<T[]>(res);
-    },
-
-    update: async <T = any>(object: string, id: string, data: Partial<T>): Promise<UpdateDataResult<T>> => {
-        const route = this.getRoute('data');
-        const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`, {
-            method: 'PATCH',
-            body: JSON.stringify(data)
-        });
-        return this.unwrapResponse<UpdateDataResult<T>>(res);
-    },
-
-    /**
-     * 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: 'POST',
-            body: JSON.stringify(request)
-        });
-        return this.unwrapResponse<BatchUpdateResponse>(res);
-    },
-
-    /**
-     * 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 this.unwrapResponse<BatchUpdateResponse>(res);
-    },
-
-    delete: async (object: string, id: string): Promise<DeleteDataResult> => {
-        const route = this.getRoute('data');
-        const res = await this.fetch(`${this.baseUrl}${route}/${object}/${id}`, {
-            method: 'DELETE'
-        });
-        return this.unwrapResponse<DeleteDataResult>(res);
-    },
-
-    /**
-     * Delete multiple records by IDs
-     */
-    deleteMany: async(object: string, ids: string[], options?: BatchOptions): Promise<BatchUpdateResponse> => {
-        const route = this.getRoute('data');
-        const request: DeleteManyRequest = {
-          ids,
-          options
-        };
-        const res = await this.fetch(`${this.baseUrl}${route}/${object}/deleteMany`, {
-             method: 'POST',
-             body: JSON.stringify(request)
-        });
-        return this.unwrapResponse<BatchUpdateResponse>(res);
-    }
-  };
-
-
-
-  /**
-   * Private Helpers
-   */
-
-  private isFilterAST(filter: any): boolean {
-    // 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);
-  }
-
-  /**
-   * Unwrap the standard REST API response envelope.
-   * The HTTP layer wraps responses as `{ success: boolean, data: T, meta? }`
-   * (see BaseResponseSchema in contract.zod.ts).
-   * This method strips the envelope and returns the inner `data` payload
-   * so callers receive the spec-level type (e.g. GetMetaTypesResponse).
-   */
-  private async unwrapResponse<T>(res: Response): Promise<T> {
-    const body = await res.json();
-    // If the body has a `success` flag it's a BaseResponse envelope
-    if (body && typeof body.success === 'boolean' && 'data' in body) {
-      return body.data as T;
-    }
-    // Already unwrapped or non-standard
-    return body as T;
-  }
-
-  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> || {}),
-    };
-
-    if (this.token) {
-        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: any;
-        try {
-            errorBody = await res.json();
-        } catch {
-            errorBody = { message: res.statusText };
-        }
-        
-        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;
-  }
-
-  /**
-   * 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: ApiRouteType): string {
-    // 1. Use discovered routes if available (only for ApiRoutes keys, not client-specific keys)
-    const routes = this.discoveryInfo?.routes;
-    if (routes) {
-        const key = type as keyof ApiRoutes;
-        const discovered = routes[key];
-        if (discovered) return discovered;
-    }
-
-    // 2. Fallback to conventions (covers all ApiRoutes keys + client-specific virtual routes)
-    const routeMap: Record<ApiRouteType, string> = {
-      data: '/api/v1/data',
-      metadata: '/api/v1/meta',
-      discovery: '/api/v1/discovery',
-      ui: '/api/v1/ui',
-      auth: '/api/v1/auth',
-      analytics: '/api/v1/analytics',
-      storage: '/api/v1/storage',
-      automation: '/api/v1/automation',
-      packages: '/api/v1/packages',
-      permissions: '/api/v1/permissions',
-      realtime: '/api/v1/realtime',
-      workflow: '/api/v1/workflow',
-      views: '/api/v1/ui/views',
-      notifications: '/api/v1/notifications',
-      ai: '/api/v1/ai',
-      i18n: '/api/v1/i18n',
-      feed: '/api/v1/feed',
-      graphql: '/graphql',
-    };
-    
-    return routeMap[type] || `/api/v1/${type}`;
-  }
-}
-
-// Re-export type-safe query builder
-export { QueryBuilder, FilterBuilder, createQuery, createFilter } from './query-builder';
-
-// Re-export realtime API types
-export { RealtimeAPI, RealtimeSubscriptionFilter, RealtimeEventHandler } from './realtime-api';
-
-// Re-export commonly used types from @objectstack/spec/api for convenience
-export type {
-  BatchUpdateRequest,
-  BatchUpdateResponse,
-  UpdateManyRequest,
-  DeleteManyRequest,
-  BatchOptions,
-  BatchRecord,
-  BatchOperationResult,
-  MetadataCacheRequest,
-  MetadataCacheResponse,
-  StandardErrorCode,
-  ErrorCategory,
-  GetDiscoveryResponse,
-  GetMetaTypesResponse,
-  GetMetaItemsResponse,
-  CheckPermissionRequest,
-  CheckPermissionResponse,
-  GetObjectPermissionsResponse,
-  GetEffectivePermissionsResponse,
-  RealtimeConnectRequest,
-  RealtimeConnectResponse,
-  RealtimeSubscribeRequest,
-  RealtimeSubscribeResponse,
-  GetPresenceResponse,
-  GetWorkflowConfigResponse,
-  GetWorkflowStateResponse,
-  WorkflowTransitionRequest,
-  WorkflowTransitionResponse,
-  WorkflowApproveRequest,
-  WorkflowApproveResponse,
-  WorkflowRejectRequest,
-  WorkflowRejectResponse,
-  ListViewsResponse,
-  GetViewResponse,
-  CreateViewResponse,
-  UpdateViewResponse,
-  DeleteViewResponse,
-  RegisterDeviceRequest,
-  RegisterDeviceResponse,
-  ListNotificationsResponse,
-  AiNlqRequest,
-  AiNlqResponse,
-  AiSuggestRequest,
-  AiSuggestResponse,
-  AiInsightsRequest,
-  AiInsightsResponse,
-  GetLocalesResponse,
-  GetTranslationsResponse,
-  GetFieldLabelsResponse,
-  RegisterRequest,
-  RefreshTokenRequest,
-  GetFeedResponse,
-  CreateFeedItemResponse,
-  UpdateFeedItemResponse,
-  DeleteFeedItemResponse,
-  AddReactionResponse,
-  RemoveReactionResponse,
-  PinFeedItemResponse,
-  UnpinFeedItemResponse,
-  StarFeedItemResponse,
-  UnstarFeedItemResponse,
-  SearchFeedResponse,
-  GetChangelogResponse,
-  SubscribeResponse,
-  UnsubscribeResponse,
-  WellKnownCapabilities,
-} from '@objectstack/spec/api';