@objectstack/client 2.0.0 → 2.0.2

package/src/query-builder.ts

@@ -106,6 +106,46 @@ export class FilterBuilder<T = any> {
     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
    */
@@ -220,6 +260,41 @@ export class QueryBuilder<T = any> {
     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
    */

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

@@ -0,0 +1,68 @@
+/**
+ * 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: Standard Discovery via .well-known', () => {
+    test('should discover API from .well-known/objectstack', 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.capabilities).toBeDefined();
+      expect(discovery.endpoints).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

@@ -0,0 +1,72 @@
+# 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/vitest.integration.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/integration/**/*.test.ts'],
+    globals: true,
+    environment: 'node',
+    testTimeout: 30000, // 30 seconds for integration tests
+    hookTimeout: 30000,
+    // Run integration tests sequentially to avoid race conditions
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: true
+      }
+    }
+  }
+});