Fix all client-spec compliance issues identified in code review

- Fix permission routes to use /api/v1/auth (not /api/v1/permissions) per spec
- Update permission check to use POST method with JSON body
- Fix analytics.getMeta() → analytics.meta(cube) in all docs
- Fix automation.trigger() signature to match implementation
- Fix auth.refreshToken() to take string parameter
- Fix permissions.getEffectivePermissions() to take no object argument
- Fix storage.upload() and getDownloadUrl() signatures
- Fix packages.install() to use manifest object
- Remove unused beforeAll import from integration test
- Add assertions to TC-DISC-004 test case
- Update all server references to clarify external dependency
- Remove non-existent hub namespace from documentation
- Update CI/CD examples to show placeholder structure
- Qualify compliance claims to be more accurate

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

content/docs/guides/client-sdk.mdx

@@ -105,7 +105,7 @@ if (discovery.services?.auth?.enabled) {
 
 ## Protocol Coverage
 
-The `@objectstack/client` SDK is **100% compliant** with the ObjectStack API protocol specification. It implements all 13 API namespaces defined in `@objectstack/spec`:
+The `@objectstack/client` SDK aims to implement the ObjectStack API protocol specification. It covers all 13 API namespaces defined in `@objectstack/spec`:
 
 | Namespace | Status | Methods | Purpose |
 |:----------|:------:|:--------|:--------|
@@ -124,7 +124,7 @@ The `@objectstack/client` SDK is **100% compliant** with the ObjectStack API pro
 | **ai** | ✅ | 4 | AI services (NLQ, chat, insights) |
 
 <Callout type="info">
-**Full compliance verification**: See [`CLIENT_SPEC_COMPLIANCE.md`](https://github.com/objectstack-ai/spec/blob/main/packages/client/CLIENT_SPEC_COMPLIANCE.md) for detailed method-by-method verification and [`CLIENT_SERVER_INTEGRATION_TESTS.md`](https://github.com/objectstack-ai/spec/blob/main/packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md) for comprehensive integration test specifications.
+**Protocol compliance & verification**: See [`CLIENT_SPEC_COMPLIANCE.md`](https://github.com/objectstack-ai/spec/blob/main/packages/client/CLIENT_SPEC_COMPLIANCE.md) for detailed method-by-method verification and [`CLIENT_SERVER_INTEGRATION_TESTS.md`](https://github.com/objectstack-ai/spec/blob/main/packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md) for comprehensive integration test specifications.
 </Callout>
 
 ---
@@ -243,12 +243,12 @@ await client.auth.login({ email: 'user@example.com', password: 'pass' });
 await client.auth.register({ email: 'new@example.com', password: 'pass' });
 await client.auth.me();
 await client.auth.logout();
-await client.auth.refreshToken({ refreshToken: 'token' });
+await client.auth.refreshToken('refresh-token-string');
 
 // Permissions — Access control checks
 await client.permissions.check({ object: 'account', action: 'create' });
 await client.permissions.getObjectPermissions('account');
-await client.permissions.getEffectivePermissions('account');
+await client.permissions.getEffectivePermissions();
 
 // Workflow — State machine management
 await client.workflow.getConfig('approval');
@@ -281,22 +281,22 @@ await client.i18n.getTranslations('zh-CN');
 await client.i18n.getFieldLabels('account', 'zh-CN');
 
 // Automation — Trigger workflows and automations
-await client.automation.trigger({ trigger: 'send_welcome_email', payload: { userId } });
+await client.automation.trigger('send_welcome_email', { userId });
 
 // Storage — File upload and management
-await client.storage.upload({ file: fileData, object: 'account', field: 'logo' });
-await client.storage.getDownloadUrl({ fileId: 'file-123' });
+await client.storage.upload(fileData, 'user');
+await client.storage.getDownloadUrl('file-123');
 
 // Views — UI view management
-await client.views.list({ object: 'account' });
-await client.views.get(viewId);
-await client.views.create({ name: 'my_view', object: 'account', ... });
-await client.views.update(viewId, { ... });
-await client.views.delete(viewId);
+await client.views.list('account');
+await client.views.get('account', viewId);
+await client.views.create('account', { name: 'my_view', ... });
+await client.views.update('account', viewId, { ... });
+await client.views.delete('account', viewId);
 ```
 
 <Callout type="info">
-**Service availability**: Optional services (auth, workflow, ai, etc.) are only available when the corresponding plugin is installed on the server. Always check `client.discovery?.services` to verify service availability before calling these methods.
+**Service availability**: Optional services (workflow, ai, etc.) are only available when the corresponding plugin is installed on the server. Always check `client.discovery?.services` to verify service availability before calling these methods.
 </Callout>
 
 ---
@@ -437,12 +437,14 @@ Unit tests use mocks to verify client behavior without requiring a server.
 
 ### Integration Tests
 
+**Note:** Integration tests require a running ObjectStack server. The server is provided by a separate repository and must be set up independently.
+
 ```bash
-# Terminal 1: Start test server
-cd packages/server
-pnpm dev:test
+# Prerequisite: Start an ObjectStack server with test data
+# For example, using the reference server repository
+# Follow the server repository's documentation for local setup
 
-# Terminal 2: Run integration tests
+# From this repository, run the integration test script
 cd packages/client
 pnpm test:integration
 ```

packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md

@@ -838,20 +838,25 @@ export function expectValidResponse<T>(response: any): asserts response is T {
 
 ### Local Development
 
+**Note:** Integration tests require a running ObjectStack server. The server is provided by a separate repository/package and is not included in this spec repository.
+
 ```bash
-# Start test server
-cd packages/server
-pnpm dev:test
+# Start test server (in the ObjectStack server repository)
+# Follow the server project's documentation for setup
+# Example: cd /path/to/objectstack-server && pnpm dev:test
 
-# Run integration tests
+# Run integration tests (in this repository)
 cd packages/client
 pnpm test:integration
 ```
 
 ### CI/CD Pipeline
 
+**Note:** The workflow file referenced below is an example. Actual CI implementation will require setting up the test server infrastructure separately.
+
 ```yaml
-# .github/workflows/client-integration-tests.yml
+# Example: .github/workflows/client-integration-tests.yml
+# This workflow would need to be created and configured with proper server setup
 name: Client Integration Tests
 
 on: [push, pull_request]
@@ -883,13 +888,15 @@ jobs:
       - name: Build spec
         run: pnpm --filter @objectstack/spec build
 
+      # Note: Server setup would require additional configuration
+      # This is a placeholder showing the expected structure
       - name: Start test server
-        run: pnpm --filter @objectstack/server dev:test &
+        run: |
+          # Server startup logic would go here
+          # This depends on the ObjectStack server implementation
+          echo "Server setup required"
         env:
-          DATABASE_URL: postgres://postgres:test@localhost:5432/test
-      
-      - name: Wait for server
-        run: npx wait-on http://localhost:3000
+          DATABASE_URL: postgresql://postgres:test@localhost:5432/test
 
       - name: Run integration tests
         run: pnpm --filter @objectstack/client test:integration

packages/client/CLIENT_SPEC_COMPLIANCE.md

@@ -129,6 +129,8 @@ Protocol methods defined in `packages/spec/src/api/protocol.zod.ts`:
 **Notes:**
 - Permission endpoints are served under `/api/v1/auth` per spec's `plugin-rest-api.zod.ts`
 - Supports action types: `create`, `read`, `edit`, `delete`, `transfer`, `restore`, `purge`
+- `check()` uses POST method as per spec
+- `getObjectPermissions()` and `getEffectivePermissions()` use GET methods
 
 ---
 
@@ -191,6 +193,7 @@ Protocol methods defined in `packages/spec/src/api/protocol.zod.ts`:
 **Notes:**
 - Schema defined in `packages/client/src/index.ts` (lines 50-59)
 - Allows triggering named automations with arbitrary payloads
+- Method signature: `trigger(triggerName: string, payload: any)`
 
 ---
 
@@ -209,7 +212,7 @@ Protocol methods defined in `packages/spec/src/api/protocol.zod.ts`:
 | Spec Method | Request Schema | Response Schema | Client Method | Status |
 |-------------|----------------|-----------------|---------------|:------:|
 | Analytics Query | `AnalyticsQueryRequestSchema` | `AnalyticsResultResponseSchema` | `analytics.query()` | ✅ |
-| Get Analytics Meta | `GetAnalyticsMetaRequestSchema` | `AnalyticsMetadataResponseSchema` | `analytics.getMeta()` | ✅ |
+| Get Analytics Meta | `GetAnalyticsMetaRequestSchema` | `AnalyticsMetadataResponseSchema` | `analytics.meta(cube)` | ✅ |
 
 ---
 

packages/client/QUICK_REFERENCE.md

@@ -68,12 +68,14 @@ Runs existing unit tests:
 
 ### Integration Tests (New)
 
+**Note:** Integration tests require a running ObjectStack server. The server is provided by a separate repository and must be set up independently.
+
 ```bash
-# Terminal 1: Start test server
-cd packages/server
-pnpm dev:test
+# Start test server (in the ObjectStack server repository)
+# Follow that project's documentation for test server setup
+# Example: cd /path/to/objectstack-server && pnpm dev:test
 
-# Terminal 2: Run integration tests
+# Run integration tests (in this repository)
 cd packages/client
 pnpm test:integration
 ```
@@ -93,17 +95,16 @@ Quick reference to all 13 implemented namespaces:
 | **Metadata** | `client.meta.*` | `await client.meta.getItem('object', 'contact')` |
 | **Data** | `client.data.*` | `await client.data.find('contact', { filters: { status: 'active' } })` |
 | **Auth** | `client.auth.*` | `await client.auth.login({ email, password })` |
-| **Packages** | `client.packages.*` | `await client.packages.install({ packageId })` |
-| **Views** | `client.views.*` | `await client.views.list({ object: 'contact' })` |
+| **Packages** | `client.packages.*` | `await client.packages.list()` |
+| **Views** | `client.views.*` | `await client.views.list('contact')` |
 | **Workflow** | `client.workflow.*` | `await client.workflow.transition({ object, recordId, transition })` |
-| **Analytics** | `client.analytics.*` | `await client.analytics.query({ object, aggregations })` |
-| **Automation** | `client.automation.*` | `await client.automation.trigger({ trigger, payload })` |
+| **Analytics** | `client.analytics.*` | `await client.analytics.meta('sales')` |
+| **Automation** | `client.automation.*` | `await client.automation.trigger('name', payload)` |
 | **i18n** | `client.i18n.*` | `await client.i18n.getTranslations('zh-CN')` |
 | **Notifications** | `client.notifications.*` | `await client.notifications.list({ unreadOnly: true })` |
 | **Realtime** | `client.realtime.*` | `await client.realtime.subscribe({ channel, event })` |
 | **AI** | `client.ai.*` | `await client.ai.nlq({ query: 'show active contacts' })` |
-| **Storage** | `client.storage.*` | `await client.storage.upload({ file, object, field })` |
-| **Hub** | `client.hub.*` | `await client.hub.connect()` |
+| **Storage** | `client.storage.*` | `await client.storage.upload(fileData, 'user')` |
 
 ## 🎯 Next Steps for Developers
 

packages/client/README.md

@@ -223,7 +223,7 @@ const data = await retryableRequest(() =>
 
 ## Protocol Compliance
 
-This client is **100% compliant** with the `@objectstack/spec` API protocol specification. It implements all 13 API namespaces:
+The `@objectstack/client` SDK implements all 13 API namespaces defined in the `@objectstack/spec` protocol specification:
 
 | Namespace | Purpose | Status |
 |-----------|---------|:------:|
@@ -268,16 +268,21 @@ await client.auth.login({ email: 'user@example.com', password: 'pass' });
 await client.auth.register({ email: 'new@example.com', password: 'pass' });
 await client.auth.me();
 await client.auth.logout();
+await client.auth.refreshToken('refresh-token-string');
 
 // Package Management
 await client.packages.list();
-await client.packages.install({ packageId: '@vendor/plugin' });
+await client.packages.install({
+  name: 'vendor_plugin',
+  label: 'Vendor Plugin',
+  version: '1.0.0',
+});
 await client.packages.enable('plugin-id');
 
 // Permissions
 await client.permissions.check({ object: 'contact', action: 'create' });
 await client.permissions.getObjectPermissions('contact');
-await client.permissions.getEffectivePermissions('contact');
+await client.permissions.getEffectivePermissions();
 
 // Workflow
 await client.workflow.getConfig('approval');
@@ -309,14 +314,14 @@ await client.i18n.getFieldLabels('contact', 'zh-CN');
 
 // Analytics
 await client.analytics.query({ object: 'sales', aggregations: ['sum:amount'] });
-await client.analytics.getMeta('sales');
+await client.analytics.meta('sales');
 
 // Automation
-await client.automation.trigger({ trigger: 'send_welcome_email', payload: { userId } });
+await client.automation.trigger('send_welcome_email', { userId });
 
 // File Storage
-await client.storage.upload({ file: fileData, object: 'contact', field: 'avatar' });
-await client.storage.getDownloadUrl({ fileId: 'file-123' });
+await client.storage.upload(fileData, 'user');
+await client.storage.getDownloadUrl('file-123');
 ```
 
 ## Testing
@@ -329,15 +334,15 @@ pnpm test
 
 ### Integration Tests
 
-Integration tests verify client-server communication across all protocol methods:
+**Note:** Integration tests require a running ObjectStack server. The server is provided by a separate repository and must be set up independently.
 
 ```bash
-# Start test server
-cd ../server
-pnpm dev:test
+# Start test server (in the ObjectStack server repository)
+# Follow that project's documentation for test server setup
+# Example: cd /path/to/objectstack-server && pnpm dev:test
 
-# Run integration tests
-cd ../client
+# Run integration tests (in this repository)
+cd packages/client
 pnpm test:integration
 ```
 

packages/client/src/index.ts

@@ -613,12 +613,10 @@ export class ObjectStackClient {
      */
     check: async (request: CheckPermissionRequest): Promise<CheckPermissionResponse> => {
       const route = this.getRoute('permissions');
-      const params = new URLSearchParams();
-      params.set('object', request.object);
-      params.set('action', request.action);
-      if (request.recordId) params.set('recordId', request.recordId);
-      if (request.field) params.set('field', request.field);
-      const res = await this.fetch(`${this.baseUrl}${route}/check?${params.toString()}`);
+      const res = await this.fetch(`${this.baseUrl}${route}/check`, {
+        method: 'POST',
+        body: JSON.stringify(request)
+      });
       return this.unwrapResponse<CheckPermissionResponse>(res);
     },
 
@@ -627,7 +625,7 @@ export class ObjectStackClient {
      */
     getObjectPermissions: async (object: string): Promise<GetObjectPermissionsResponse> => {
       const route = this.getRoute('permissions');
-      const res = await this.fetch(`${this.baseUrl}${route}/objects/${encodeURIComponent(object)}`);
+      const res = await this.fetch(`${this.baseUrl}${route}/permissions/${encodeURIComponent(object)}`);
       return this.unwrapResponse<GetObjectPermissionsResponse>(res);
     },
 
@@ -636,7 +634,7 @@ export class ObjectStackClient {
      */
     getEffectivePermissions: async (): Promise<GetEffectivePermissionsResponse> => {
       const route = this.getRoute('permissions');
-      const res = await this.fetch(`${this.baseUrl}${route}/effective`);
+      const res = await this.fetch(`${this.baseUrl}${route}/permissions/effective`);
       return this.unwrapResponse<GetEffectivePermissionsResponse>(res);
     }
   };
@@ -1288,7 +1286,7 @@ export class ObjectStackClient {
       storage: '/api/v1/storage',
       automation: '/api/v1/automation',
       packages: '/api/v1/packages',
-      permissions: '/api/v1/permissions',
+      permissions: '/api/v1/auth', // Permission endpoints are under /api/v1/auth per spec
       realtime: '/api/v1/realtime',
       workflow: '/api/v1/workflow',
       views: '/api/v1/ui/views',

packages/client/tests/integration/01-discovery.test.ts

@@ -7,7 +7,7 @@
  * @see CLIENT_SERVER_INTEGRATION_TESTS.md for full test specification
  */
 
-import { describe, test, expect, beforeAll } from 'vitest';
+import { describe, test, expect } from 'vitest';
 import { ObjectStackClient } from '../../src/index';
 
 const TEST_SERVER_URL = process.env.TEST_SERVER_URL || 'http://localhost:3000';
@@ -58,7 +58,11 @@ describe('Discovery & Connection', () => {
       await client.connect();
 
       // After connection, client should have discovery info
-      // This is tested implicitly by making actual API calls in other test suites
+      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
     });
   });
 });

packages/client/tests/integration/README.md

@@ -6,15 +6,17 @@ This directory contains integration tests that verify `@objectstack/client` agai
 
 ### Prerequisites
 
-1. **Start a test server:**
+**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
-   cd ../../server
-   pnpm dev:test
+   # 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:**
+2. **Run integration tests (from this package):**
    ```bash
-   cd ../../client
    pnpm test:integration
    ```
 
@@ -62,9 +64,9 @@ Tests are organized by protocol namespace:
 
 ## CI/CD
 
-Integration tests run automatically in CI when:
-- Pull requests are created
-- Changes are pushed to main branch
-- Manual workflow dispatch
+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 `.github/workflows/client-integration-tests.yml` for the CI configuration.
+See `CLIENT_SERVER_INTEGRATION_TESTS.md` for example CI configuration structure.