@objectql/sdk 3.0.1 → 4.0.0

package/README.md

@@ -12,10 +12,14 @@ The `@objectql/sdk` package provides a type-safe HTTP client for ObjectQL server
 ## ✨ Features
 
 * **🌍 Universal Runtime** - Works in browsers, Node.js, Deno, and edge environments
-* **📦 Zero Dependencies** - Only depends on `@objectql/types` for type definitions
+* **📦 Zero Dependencies** - Only depends on `@objectql/types` and `@objectstack/spec` for type definitions
 * **🔒 Type-Safe** - Full TypeScript support with generics
 * **🚀 Modern APIs** - Uses native `fetch` API available in all modern JavaScript runtimes
 * **🎯 RESTful Interface** - Clean, predictable API design
+* **✅ DriverInterface v4.0** - Fully compliant with ObjectStack protocol specification
+* **🔐 Authentication** - Built-in support for Bearer tokens and API keys
+* **🔄 Retry Logic** - Automatic retry with exponential backoff for network resilience
+* **📊 Request Logging** - Optional request/response logging for debugging
 
 ---
 
@@ -290,6 +294,274 @@ const actions = await metadataClient.listActions('users');
 
 ---
 
+### RemoteDriver (DriverInterface v4.0)
+
+Client for connecting to a remote ObjectQL server via HTTP. Implements the standard `DriverInterface` from `@objectstack/spec`.
+
+#### Constructor
+
+```typescript
+// Legacy constructor
+new RemoteDriver(baseUrl: string, rpcPath?: string)
+
+// New config-based constructor (recommended)
+new RemoteDriver(config: SdkConfig)
+```
+
+**Config Options:**
+* `baseUrl` (string, required) - Base URL of the ObjectQL server
+* `rpcPath` (string, optional) - JSON-RPC endpoint path (default: /api/objectql)
+* `queryPath` (string, optional) - Query endpoint path (default: /api/query)
+* `commandPath` (string, optional) - Command endpoint path (default: /api/command)
+* `executePath` (string, optional) - Custom execute endpoint path (default: /api/execute)
+* `token` (string, optional) - Authentication token (Bearer)
+* `apiKey` (string, optional) - API key for authentication
+* `headers` (Record<string, string>, optional) - Custom HTTP headers
+* `timeout` (number, optional) - Request timeout in milliseconds (default: 30000)
+* `enableRetry` (boolean, optional) - Enable automatic retry on failure (default: false)
+* `maxRetries` (number, optional) - Maximum retry attempts (default: 3)
+* `enableLogging` (boolean, optional) - Enable request/response logging (default: false)
+
+#### Methods
+
+##### `executeQuery(ast: QueryAST, options?: any): Promise<{ value: any[]; count?: number }>`
+
+Execute a query using QueryAST format (DriverInterface v4.0).
+
+```typescript
+import { RemoteDriver } from '@objectql/sdk';
+
+const driver = new RemoteDriver({
+    baseUrl: 'http://localhost:3000',
+    token: 'your-auth-token',
+    enableRetry: true,
+    maxRetries: 3
+});
+
+// Execute a QueryAST
+const result = await driver.executeQuery({
+    object: 'users',
+    fields: ['name', 'email', 'status'],
+    filters: {
+        type: 'comparison',
+        field: 'status',
+        operator: '=',
+        value: 'active'
+    },
+    sort: [{ field: 'created_at', order: 'desc' }],
+    top: 10,
+    skip: 0
+});
+
+console.log(result.value); // Array of users
+console.log(result.count); // Total count
+```
+
+##### `executeCommand(command: Command, options?: any): Promise<CommandResult>`
+
+Execute a command for mutation operations (create, update, delete, bulk operations).
+
+```typescript
+// Create a record
+const createResult = await driver.executeCommand({
+    type: 'create',
+    object: 'users',
+    data: {
+        name: 'Alice',
+        email: 'alice@example.com',
+        status: 'active'
+    }
+});
+
+console.log(createResult.success); // true
+console.log(createResult.data); // Created record
+console.log(createResult.affected); // 1
+
+// Update a record
+const updateResult = await driver.executeCommand({
+    type: 'update',
+    object: 'users',
+    id: 'user_123',
+    data: { status: 'inactive' }
+});
+
+// Delete a record
+const deleteResult = await driver.executeCommand({
+    type: 'delete',
+    object: 'users',
+    id: 'user_123'
+});
+
+// Bulk create
+const bulkCreateResult = await driver.executeCommand({
+    type: 'bulkCreate',
+    object: 'users',
+    records: [
+        { name: 'Bob', email: 'bob@example.com' },
+        { name: 'Charlie', email: 'charlie@example.com' }
+    ]
+});
+
+// Bulk update
+const bulkUpdateResult = await driver.executeCommand({
+    type: 'bulkUpdate',
+    object: 'users',
+    updates: [
+        { id: 'user_1', data: { status: 'active' } },
+        { id: 'user_2', data: { status: 'inactive' } }
+    ]
+});
+
+// Bulk delete
+const bulkDeleteResult = await driver.executeCommand({
+    type: 'bulkDelete',
+    object: 'users',
+    ids: ['user_1', 'user_2', 'user_3']
+});
+```
+
+##### `execute(endpoint?: string, payload?: any, options?: any): Promise<any>`
+
+Execute a custom operation on the remote server.
+
+```typescript
+// Execute a custom workflow
+const workflowResult = await driver.execute('/api/workflows/approve', {
+    workflowId: 'wf_123',
+    comment: 'Approved by manager'
+});
+
+// Use default execute endpoint
+const customResult = await driver.execute(undefined, {
+    action: 'calculateMetrics',
+    params: { year: 2024, quarter: 'Q1' }
+});
+
+// Call a custom action
+const actionResult = await driver.execute('/api/actions/send-email', {
+    to: 'user@example.com',
+    subject: 'Welcome',
+    body: 'Welcome to our platform!'
+});
+```
+
+#### Legacy CRUD Methods
+
+The RemoteDriver also supports legacy CRUD methods for backward compatibility:
+
+```typescript
+// Find records
+const users = await driver.find('users', {
+    filters: [['status', '=', 'active']],
+    sort: [['name', 'asc']],
+    limit: 10
+});
+
+// Find one record
+const user = await driver.findOne('users', 'user_123');
+
+// Create a record
+const newUser = await driver.create('users', {
+    name: 'Alice',
+    email: 'alice@example.com'
+});
+
+// Update a record
+const updated = await driver.update('users', 'user_123', {
+    status: 'inactive'
+});
+
+// Delete a record
+await driver.delete('users', 'user_123');
+
+// Count records
+const count = await driver.count('users', {
+    filters: [['status', '=', 'active']]
+});
+```
+
+### Authentication Examples
+
+```typescript
+// Bearer token authentication
+const driverWithToken = new RemoteDriver({
+    baseUrl: 'http://localhost:3000',
+    token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+});
+
+// API key authentication
+const driverWithApiKey = new RemoteDriver({
+    baseUrl: 'http://localhost:3000',
+    apiKey: 'sk-1234567890abcdef'
+});
+
+// Both token and API key
+const driverWithBoth = new RemoteDriver({
+    baseUrl: 'http://localhost:3000',
+    token: 'jwt-token',
+    apiKey: 'api-key'
+});
+
+// Custom headers
+const driverWithHeaders = new RemoteDriver({
+    baseUrl: 'http://localhost:3000',
+    headers: {
+        'X-Tenant-ID': 'tenant_123',
+        'X-Request-ID': crypto.randomUUID()
+    }
+});
+```
+
+### Error Handling and Retry
+
+```typescript
+import { ObjectQLError, ApiErrorCode } from '@objectql/types';
+
+// Enable retry with exponential backoff
+const driver = new RemoteDriver({
+    baseUrl: 'http://localhost:3000',
+    enableRetry: true,
+    maxRetries: 3,
+    timeout: 10000
+});
+
+try {
+    const result = await driver.executeQuery({ object: 'users' });
+} catch (error) {
+    if (error instanceof ObjectQLError) {
+        switch (error.code) {
+            case ApiErrorCode.UNAUTHORIZED:
+                console.error('Authentication required');
+                break;
+            case ApiErrorCode.VALIDATION_ERROR:
+                console.error('Validation failed:', error.details);
+                break;
+            case ApiErrorCode.NOT_FOUND:
+                console.error('Resource not found');
+                break;
+            default:
+                console.error('API error:', error.message);
+        }
+    }
+}
+```
+
+### Request Logging
+
+```typescript
+// Enable logging for debugging
+const driver = new RemoteDriver({
+    baseUrl: 'http://localhost:3000',
+    enableLogging: true
+});
+
+// Logs will be printed to console:
+// [RemoteDriver] executeQuery { endpoint: '...', ast: {...} }
+// [RemoteDriver] executeQuery response { value: [...], count: 10 }
+```
+
+---
+
 ## 🌐 Browser Compatibility
 
 The SDK uses modern JavaScript APIs available in all current browsers:

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 /**
  * @objectql/sdk - Universal HTTP Client for ObjectQL
  *
@@ -14,15 +21,226 @@
  *
  * @packageDocumentation
  */
-import { Driver, IDataApiClient, IMetadataApiClient, DataApiClientConfig, MetadataApiClientConfig, DataApiListParams, DataApiListResponse, DataApiItemResponse, DataApiCreateRequest, DataApiCreateManyRequest, DataApiUpdateRequest, DataApiBulkUpdateRequest, DataApiBulkDeleteRequest, DataApiCountResponse, DataApiDeleteResponse, DataApiResponse, MetadataApiObjectListResponse, MetadataApiObjectDetailResponse, FieldMetadataResponse, MetadataApiActionsResponse, MetadataApiListResponse, MetadataApiResponse, FilterExpression } from '@objectql/types';
+import { Driver, IDataApiClient, IMetadataApiClient, DataApiClientConfig, MetadataApiClientConfig, DataApiListParams, DataApiListResponse, DataApiItemResponse, DataApiCreateRequest, DataApiCreateManyRequest, DataApiUpdateRequest, DataApiBulkUpdateRequest, DataApiBulkDeleteRequest, DataApiCountResponse, DataApiDeleteResponse, DataApiResponse, MetadataApiObjectListResponse, MetadataApiObjectDetailResponse, FieldMetadataResponse, MetadataApiActionsResponse, MetadataApiListResponse, MetadataApiResponse, Filter } from '@objectql/types';
+import { DriverInterface, QueryAST } from '@objectstack/spec';
+/**
+ * Command interface for executeCommand method
+ * Defines the structure of mutation commands sent to the remote API
+ */
+export interface Command {
+    type: 'create' | 'update' | 'delete' | 'bulkCreate' | 'bulkUpdate' | 'bulkDelete';
+    object: string;
+    data?: any;
+    id?: string | number;
+    ids?: Array<string | number>;
+    records?: any[];
+    updates?: Array<{
+        id: string | number;
+        data: any;
+    }>;
+    options?: any;
+}
+/**
+ * Command result interface
+ * Standard response format for command execution
+ */
+export interface CommandResult {
+    success: boolean;
+    data?: any;
+    affected: number;
+    error?: string;
+}
+/**
+ * SDK Configuration for the RemoteDriver
+ */
+export interface SdkConfig {
+    /** Base URL of the remote ObjectQL server */
+    baseUrl: string;
+    /** RPC endpoint path (default: /api/objectql) */
+    rpcPath?: string;
+    /** Query endpoint path (default: /api/query) */
+    queryPath?: string;
+    /** Command endpoint path (default: /api/command) */
+    commandPath?: string;
+    /** Custom execute endpoint path (default: /api/execute) */
+    executePath?: string;
+    /** Authentication token */
+    token?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Enable retry on failure (default: false) */
+    enableRetry?: boolean;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Enable request/response logging (default: false) */
+    enableLogging?: boolean;
+}
 /**
  * Legacy Driver implementation that uses JSON-RPC style API
+ *
+ * Implements both the legacy Driver interface from @objectql/types and
+ * the standard DriverInterface from @objectstack/spec for compatibility
+ * with the new kernel-based plugin system.
+ *
+ * @version 4.0.0 - DriverInterface compliant
  */
-export declare class RemoteDriver implements Driver {
-    private baseUrl;
+export declare class RemoteDriver implements Driver, DriverInterface {
+    readonly name = "RemoteDriver";
+    readonly version = "4.0.0";
+    readonly supports: {
+        transactions: boolean;
+        joins: boolean;
+        fullTextSearch: boolean;
+        jsonFields: boolean;
+        arrayFields: boolean;
+    };
     private rpcPath;
-    constructor(baseUrl: string, rpcPath?: string);
+    private queryPath;
+    private commandPath;
+    private executePath;
+    private baseUrl;
+    private token?;
+    private apiKey?;
+    private headers;
+    private timeout;
+    private enableRetry;
+    private maxRetries;
+    private enableLogging;
+    constructor(baseUrlOrConfig: string | SdkConfig, rpcPath?: string);
+    /**
+     * Build full endpoint URL
+     * @private
+     */
+    private buildEndpoint;
+    /**
+     * Get authentication headers
+     * @private
+     */
+    private getAuthHeaders;
+    /**
+     * Handle HTTP errors and convert to ObjectQLError
+     * @private
+     */
+    private handleHttpError;
+    /**
+     * Retry logic with exponential backoff
+     * @private
+     */
+    private retryWithBackoff;
+    /**
+     * Log request/response if logging is enabled
+     * @private
+     */
+    private log;
+    /**
+     * Connect to the remote server (for DriverInterface compatibility)
+     */
+    connect(): Promise<void>;
+    /**
+     * Check remote server connection health
+     */
+    checkHealth(): Promise<boolean>;
+    /**
+     * Execute a query using QueryAST format (DriverInterface v4.0)
+     *
+     * Sends a QueryAST to the remote server's /api/query endpoint
+     * and returns the query results.
+     *
+     * @param ast - The QueryAST to execute
+     * @param options - Optional execution options
+     * @returns Query result with value array and optional count
+     *
+     * @example
+     * ```typescript
+     * const result = await driver.executeQuery({
+     *   object: 'users',
+     *   fields: ['name', 'email'],
+     *   filters: {
+     *     type: 'comparison',
+     *     field: 'status',
+     *     operator: '=',
+     *     value: 'active'
+     *   },
+     *   sort: [{ field: 'created_at', order: 'desc' }],
+     *   top: 10
+     * });
+     * ```
+     */
+    executeQuery(ast: QueryAST, options?: any): Promise<{
+        value: any[];
+        count?: number;
+    }>;
+    /**
+     * Execute a command using Command format (DriverInterface v4.0)
+     *
+     * Sends a Command to the remote server's /api/command endpoint
+     * for mutation operations (create, update, delete, bulk operations).
+     *
+     * @param command - The command to execute
+     * @param options - Optional execution options
+     * @returns Command execution result
+     *
+     * @example
+     * ```typescript
+     * // Create a record
+     * const result = await driver.executeCommand({
+     *   type: 'create',
+     *   object: 'users',
+     *   data: { name: 'Alice', email: 'alice@example.com' }
+     * });
+     *
+     * // Bulk update
+     * const bulkResult = await driver.executeCommand({
+     *   type: 'bulkUpdate',
+     *   object: 'users',
+     *   updates: [
+     *     { id: '1', data: { status: 'active' } },
+     *     { id: '2', data: { status: 'inactive' } }
+     *   ]
+     * });
+     * ```
+     */
+    executeCommand(command: Command, options?: any): Promise<CommandResult>;
+    /**
+     * Execute a custom operation on the remote server
+     *
+     * Allows calling custom HTTP endpoints with flexible parameters.
+     * Useful for custom actions, workflows, or specialized operations.
+     *
+     * @param endpoint - Optional custom endpoint path (defaults to /api/execute)
+     * @param payload - Request payload
+     * @param options - Optional execution options
+     * @returns Execution result
+     *
+     * @example
+     * ```typescript
+     * // Execute a custom workflow
+     * const result = await driver.execute('/api/workflows/approve', {
+     *   workflowId: 'wf_123',
+     *   comment: 'Approved'
+     * });
+     *
+     * // Use default execute endpoint
+     * const result = await driver.execute(undefined, {
+     *   action: 'calculateMetrics',
+     *   params: { year: 2024 }
+     * });
+     * ```
+     */
+    execute(endpoint?: string, payload?: any, options?: any): Promise<any>;
     private request;
+    /**
+     * Normalizes query format to support both legacy UnifiedQuery and QueryAST formats.
+     * This ensures backward compatibility while supporting the new @objectstack/spec interface.
+     *
+     * QueryAST format uses 'top' for limit, while UnifiedQuery uses 'limit'.
+     * QueryAST sort is array of {field, order}, while UnifiedQuery is array of [field, order].
+     */
+    private normalizeQuery;
     find(objectName: string, query: any, options?: any): Promise<any[]>;
     findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
     create(objectName: string, data: any, options?: any): Promise<any>;
@@ -79,7 +297,7 @@ export declare class DataApiClient implements IDataApiClient {
     updateMany(objectName: string, request: DataApiBulkUpdateRequest): Promise<DataApiResponse>;
     delete(objectName: string, id: string | number): Promise<DataApiDeleteResponse>;
     deleteMany(objectName: string, request: DataApiBulkDeleteRequest): Promise<DataApiDeleteResponse>;
-    count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse>;
+    count(objectName: string, filters?: Filter): Promise<DataApiCountResponse>;
 }
 /**
  * REST-based Metadata API Client