@objectstack/client 4.0.4 → 4.1.0

package/src/query-builder.ts

@@ -1,337 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * 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;
-  }
-
-  /**
-   * BETWEEN filter: field BETWEEN min AND max
-   */
-  between<K extends keyof T>(field: K, min: T[K], max: T[K]): this {
-    this.conditions.push(['and', [field as string, '>=', min], [field as string, '<=', max]] as FilterCondition);
-    return this;
-  }
-
-  /**
-   * CONTAINS filter: field contains value (case-insensitive LIKE %value%)
-   */
-  contains<K extends keyof T>(field: K, value: string): this {
-    this.conditions.push([field as string, 'like', `%${value}%`]);
-    return this;
-  }
-
-  /**
-   * STARTS WITH filter: field starts with value (LIKE value%)
-   */
-  startsWith<K extends keyof T>(field: K, value: string): this {
-    this.conditions.push([field as string, 'like', `${value}%`]);
-    return this;
-  }
-
-  /**
-   * ENDS WITH filter: field ends with value (LIKE %value)
-   */
-  endsWith<K extends keyof T>(field: K, value: string): this {
-    this.conditions.push([field as string, 'like', `%${value}`]);
-    return this;
-  }
-
-  /**
-   * EXISTS filter: field is not null (alias for isNotNull)
-   */
-  exists<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).
-   * @deprecated Prefer `.offset()` for alignment with Spec canonical field names.
-   */
-  skip(count: number): this {
-    this.query.offset = count;
-    return this;
-  }
-
-  /**
-   * Offset records (for pagination) — canonical alias for `.skip()`
-   */
-  offset(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;
-  }
-
-  /**
-   * Expand (eager-load) a related object with an optional sub-query
-   */
-  expand(relation: string, subQuery?: Partial<QueryAST>): this {
-    if (!this.query.expand) {
-      this.query.expand = {};
-    }
-    (this.query.expand as Record<string, any>)[relation] = subQuery || {};
-    return this;
-  }
-
-  /**
-   * Add full-text search
-   */
-  search(query: string, options?: { fields?: string[]; fuzzy?: boolean }): this {
-    (this.query as any).search = { query, ...options };
-    return this;
-  }
-
-  /**
-   * Set cursor for keyset pagination
-   */
-  cursor(cursor: Record<string, any>): this {
-    (this.query as any).cursor = cursor;
-    return this;
-  }
-
-  /**
-   * Enable SELECT DISTINCT
-   */
-  distinct(): this {
-    (this.query as any).distinct = true;
-    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>();
-}

package/src/realtime-api.ts

@@ -1,208 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Realtime API Module for ObjectStackClient
- *
- * Provides real-time event subscription capabilities using long-polling.
- * For production WebSocket/SSE support, extend with transport adapters.
- */
-
-import type { RealtimeEventPayload } from '@objectstack/spec/contracts';
-import type { MetadataEvent, DataEvent } from '@objectstack/spec/api';
-
-export interface RealtimeSubscriptionFilter {
-  /** Metadata/object type filter */
-  type?: string;
-  /** Package ID filter */
-  packageId?: string;
-  /** Event types to listen for */
-  eventTypes?: string[];
-  /** Record ID filter (for data events) */
-  recordId?: string;
-}
-
-export type RealtimeEventHandler = (event: RealtimeEventPayload) => void;
-
-/**
- * Realtime API for subscribing to server events
- *
- * Note: Currently uses in-memory adapter. WebSocket/SSE transport planned for future.
- */
-export class RealtimeAPI {
-  // @ts-expect-error - Reserved for future WebSocket/SSE implementation
-  private _baseUrl: string;
-  // @ts-expect-error - Reserved for future WebSocket/SSE implementation
-  private _token?: string;
-  private subscriptions = new Map<string, {
-    filter: RealtimeSubscriptionFilter;
-    handler: RealtimeEventHandler;
-  }>();
-  private pollInterval?: ReturnType<typeof setInterval>;
-  private eventBuffer: RealtimeEventPayload[] = [];
-
-  constructor(baseUrl: string, token?: string) {
-    this._baseUrl = baseUrl;
-    this._token = token;
-  }
-
-  /**
-   * Subscribe to metadata events
-   * Returns an unsubscribe function
-   */
-  subscribeMetadata(
-    type: string,
-    callback: (event: MetadataEvent) => void,
-    options?: { packageId?: string }
-  ): () => void {
-    const subscriptionId = `metadata-${type}-${Date.now()}`;
-
-    this.subscriptions.set(subscriptionId, {
-      filter: {
-        type,
-        packageId: options?.packageId,
-        eventTypes: [
-          `metadata.${type}.created`,
-          `metadata.${type}.updated`,
-          `metadata.${type}.deleted`
-        ]
-      },
-      handler: (event) => {
-        // Type guard and filter
-        if (event.type.startsWith('metadata.')) {
-          callback(event as any as MetadataEvent);
-        }
-      }
-    });
-
-    // Start polling if not already started
-    this.startPolling();
-
-    // Return unsubscribe function
-    return () => {
-      this.subscriptions.delete(subscriptionId);
-      if (this.subscriptions.size === 0) {
-        this.stopPolling();
-      }
-    };
-  }
-
-  /**
-   * Subscribe to data record events
-   * Returns an unsubscribe function
-   */
-  subscribeData(
-    object: string,
-    callback: (event: DataEvent) => void,
-    options?: { recordId?: string }
-  ): () => void {
-    const subscriptionId = `data-${object}-${Date.now()}`;
-
-    this.subscriptions.set(subscriptionId, {
-      filter: {
-        type: object,
-        recordId: options?.recordId,
-        eventTypes: [
-          'data.record.created',
-          'data.record.updated',
-          'data.record.deleted'
-        ]
-      },
-      handler: (event) => {
-        // Type guard and filter
-        if (event.type.startsWith('data.') && event.object === object) {
-          if (!options?.recordId || (event.payload as any)?.recordId === options.recordId) {
-            callback(event as any as DataEvent);
-          }
-        }
-      }
-    });
-
-    // Start polling if not already started
-    this.startPolling();
-
-    // Return unsubscribe function
-    return () => {
-      this.subscriptions.delete(subscriptionId);
-      if (this.subscriptions.size === 0) {
-        this.stopPolling();
-      }
-    };
-  }
-
-  /**
-   * Emit an event to all matching subscriptions (client-side only)
-   * This is used for in-process event delivery
-   */
-  private emitEvent(event: RealtimeEventPayload): void {
-    for (const sub of this.subscriptions.values()) {
-      // Check if event matches subscription filters
-      const matchesType = !sub.filter.type ||
-        event.type.includes(sub.filter.type) ||
-        event.object === sub.filter.type;
-
-      const matchesEventType = !sub.filter.eventTypes?.length ||
-        sub.filter.eventTypes.includes(event.type);
-
-      const matchesPackage = !sub.filter.packageId ||
-        (event.payload as any)?.packageId === sub.filter.packageId;
-
-      if (matchesType && matchesEventType && matchesPackage) {
-        try {
-          sub.handler(event);
-        } catch (error) {
-          console.error('Error in realtime event handler:', error);
-        }
-      }
-    }
-  }
-
-  /**
-   * Start polling for events (fallback mechanism)
-   * In production, this would be replaced with WebSocket/SSE
-   */
-  private startPolling(): void {
-    if (this.pollInterval) return;
-
-    // For now, we rely on the in-memory adapter within the same process
-    // Events are delivered synchronously via the IRealtimeService
-    // This polling is a placeholder for future WebSocket/SSE implementation
-
-    // Poll every 2 seconds for buffered events
-    this.pollInterval = setInterval(() => {
-      // Process any buffered events
-      while (this.eventBuffer.length > 0) {
-        const event = this.eventBuffer.shift();
-        if (event) {
-          this.emitEvent(event);
-        }
-      }
-    }, 2000);
-  }
-
-  /**
-   * Stop polling for events
-   */
-  private stopPolling(): void {
-    if (this.pollInterval) {
-      clearInterval(this.pollInterval);
-      this.pollInterval = undefined;
-    }
-  }
-
-  /**
-   * Internal method to buffer events from server
-   * This would be called by WebSocket/SSE handlers in production
-   */
-  _bufferEvent(event: RealtimeEventPayload): void {
-    this.eventBuffer.push(event);
-  }
-
-  /**
-   * Disconnect and clean up all subscriptions
-   */
-  disconnect(): void {
-    this.stopPolling();
-    this.subscriptions.clear();
-    this.eventBuffer = [];
-  }
-}

package/tests/integration/01-discovery.test.ts

@@ -1,68 +0,0 @@
-/**
- * Integration Test: Discovery & Connection
- * 
- * Tests the client's ability to discover and connect to an ObjectStack server.
- * These tests require a running server instance.
- * 
- * @see CLIENT_SERVER_INTEGRATION_TESTS.md for full test specification
- */
-
-import { describe, test, expect } from 'vitest';
-import { ObjectStackClient } from '../../src/index';
-
-const TEST_SERVER_URL = process.env.TEST_SERVER_URL || 'http://localhost:3000';
-
-describe('Discovery & Connection', () => {
-  describe('TC-DISC-001: Protocol-standard Discovery via /api/v1/discovery', () => {
-    test('should discover API from /api/v1/discovery', async () => {
-      const client = new ObjectStackClient({
-        baseUrl: TEST_SERVER_URL,
-        debug: true
-      });
-
-      const discovery = await client.connect();
-
-      expect(discovery.version).toBeDefined();
-      expect(discovery.apiName).toBeDefined();
-      expect(discovery.routes).toBeDefined();
-      expect(discovery.services).toBeDefined();
-    });
-  });
-
-  describe('TC-DISC-002: Discovery Information', () => {
-    test('should provide valid API version information', async () => {
-      const client = new ObjectStackClient({ baseUrl: TEST_SERVER_URL });
-      const discovery = await client.connect();
-      
-      // Version should be a semantic version or API version string
-      expect(discovery.version).toMatch(/^v?\d+/);
-      
-      // API name should be non-empty
-      expect(discovery.apiName.length).toBeGreaterThan(0);
-    });
-  });
-
-  describe('TC-DISC-003: Connection Failure Handling', () => {
-    test('should throw error when server is unreachable', async () => {
-      const client = new ObjectStackClient({ 
-        baseUrl: 'http://localhost:9999' // Invalid port
-      });
-      
-      await expect(client.connect()).rejects.toThrow();
-    });
-  });
-
-  describe('TC-DISC-004: Route Resolution', () => {
-    test('should resolve API routes from discovery info', async () => {
-      const client = new ObjectStackClient({ baseUrl: TEST_SERVER_URL });
-      await client.connect();
-      
-      // After connection, client should have discovery info
-      expect(client.discovery).toBeDefined();
-      expect(client.discovery?.version).toBeDefined();
-      
-      // Verify that subsequent API calls can be made (routes are resolved)
-      // This implicitly tests route resolution
-    });
-  });
-});

package/tests/integration/README.md

@@ -1,72 +0,0 @@
-# Client Integration Tests
-
-This directory contains integration tests that verify `@objectstack/client` against a live ObjectStack server.
-
-## Running Tests
-
-### Prerequisites
-
-**Note:** Integration tests require a running ObjectStack server with test data. The server is provided by a separate repository and must be set up independently.
-
-1. **Start a test server (external dependency):**
-   ```bash
-   # In the ObjectStack server repository (separate from this package)
-   # Follow that project's documentation for test server setup
-   # Example: cd /path/to/objectstack-server && pnpm dev:test
-   ```
-
-2. **Run integration tests (from this package):**
-   ```bash
-   pnpm test:integration
-   ```
-
-### Environment Variables
-
-- `TEST_SERVER_URL` - Base URL of the test server (default: `http://localhost:3000`)
-- `TEST_USER_EMAIL` - Test user email (default: `test@example.com`)
-- `TEST_USER_PASSWORD` - Test user password (default: `TestPassword123!`)
-
-## Test Structure
-
-Tests are organized by protocol namespace:
-
-```
-01-discovery.test.ts          # Discovery & connection
-02-auth.test.ts                # Authentication flows
-03-metadata.test.ts            # Metadata operations
-04-data-crud.test.ts           # Basic CRUD operations
-05-data-batch.test.ts          # Batch operations
-06-data-query.test.ts          # Advanced queries
-07-permissions.test.ts         # Permission checking
-08-workflow.test.ts            # Workflow operations
-09-realtime.test.ts            # Realtime subscriptions
-10-notifications.test.ts       # Notifications
-11-ai.test.ts                  # AI services
-12-i18n.test.ts                # Internationalization
-13-analytics.test.ts           # Analytics queries
-14-packages.test.ts            # Package management
-15-views.test.ts               # View management
-16-storage.test.ts             # File storage
-17-automation.test.ts          # Automation triggers
-```
-
-## Test Coverage Goals
-
-- Core Services (discovery, meta, data, auth): **100%**
-- Optional Services: **90%**
-- Error Scenarios: **80%**
-- Edge Cases: **70%**
-
-## Related Documentation
-
-- [Integration Test Specification](../../CLIENT_SERVER_INTEGRATION_TESTS.md)
-- [Client Spec Compliance](../../CLIENT_SPEC_COMPLIANCE.md)
-
-## CI/CD
-
-Integration tests can be run in CI, but require:
-- A running ObjectStack server instance (from separate repository)
-- Test database with sample data
-- Proper environment configuration
-
-See `CLIENT_SERVER_INTEGRATION_TESTS.md` for example CI configuration structure.

package/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "types": ["node"]
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
-}

package/vitest.config.ts

@@ -1,13 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    // Exclude integration tests that require a running server
-    exclude: [
-      '**/node_modules/**',
-      '**/dist/**',
-      'tests/integration/**',
-    ],
-    environment: 'node',
-  }
-});