@objectql/server 1.3.1 → 1.4.0

package/src/server.ts

@@ -1,5 +1,5 @@
 import { IObjectQL, ObjectQLContext } from '@objectql/types';
-import { ObjectQLRequest, ObjectQLResponse } from './types';
+import { ObjectQLRequest, ObjectQLResponse, ErrorCode } from './types';
 
 export class ObjectQLServer {
     constructor(private app: IObjectQL) {}
@@ -10,6 +10,17 @@ export class ObjectQLServer {
      */
     async handle(req: ObjectQLRequest): Promise<ObjectQLResponse> {
         try {
+            // Log AI context if provided
+            if (req.ai_context) {
+                console.log('[ObjectQL AI Context]', {
+                    object: req.object,
+                    op: req.op,
+                    intent: req.ai_context.intent,
+                    natural_language: req.ai_context.natural_language,
+                    use_case: req.ai_context.use_case
+                });
+            }
+
             // 1. Build Context
             // TODO: integrate with real session/auth
             const contextOptions = {
@@ -23,10 +34,23 @@ export class ObjectQLServer {
             // We need to cast or fix the interface. Assuming 'app' behaves like ObjectQL class.
             const app = this.app as any; 
             if (typeof app.createContext !== 'function') {
-                throw new Error("The provided ObjectQL instance does not support createContext.");
+                return this.errorResponse(
+                    ErrorCode.INTERNAL_ERROR,
+                    "The provided ObjectQL instance does not support createContext."
+                );
             }
             
             const ctx: ObjectQLContext = app.createContext(contextOptions);
+            
+            // Validate object exists
+            const objectConfig = app.getObject(req.object);
+            if (!objectConfig) {
+                return this.errorResponse(
+                    ErrorCode.NOT_FOUND,
+                    `Object '${req.object}' not found`
+                );
+            }
+            
             const repo = ctx.object(req.object);
 
             let result: any;
@@ -36,7 +60,12 @@ export class ObjectQLServer {
                     result = await repo.find(req.args);
                     break;
                 case 'findOne':
-                    result = await repo.findOne(req.args);
+                    // Support both string ID and query object
+                    if (typeof req.args === 'string') {
+                        result = await repo.findOne({ filters: [['_id', '=', req.args]] });
+                    } else {
+                        result = await repo.findOne(req.args);
+                    }
                     break;
                 case 'create':
                     result = await repo.create(req.args);
@@ -46,33 +75,107 @@ export class ObjectQLServer {
                     break;
                 case 'delete':
                     result = await repo.delete(req.args.id);
+                    if (!result) {
+                        return this.errorResponse(
+                            ErrorCode.NOT_FOUND,
+                            `Record with id '${req.args.id}' not found for delete`
+                        );
+                    }
+                    // Return standardized delete response on success
+                    result = { id: req.args.id, deleted: true };
                     break;
                 case 'count':
                     result = await repo.count(req.args);
                     break;
                 case 'action':
-                    // TODO: The repo interface might not expose 'executeAction' directly yet,
-                    // usually it's on the app level or via special method.
-                    // For now, let's assume app.executeAction
+                    // Map generic args to ActionContext
                     result = await app.executeAction(req.object, req.args.action, {
-                         ...ctx, // Pass context with user info
-                         params: req.args.params
+                         ...ctx, // Pass context (user, etc.)
+                         id: req.args.id,
+                         input: req.args.input || req.args.params // Support both for convenience
                     });
                     break;
                 default:
-                    throw new Error(`Unknown operation: ${req.op}`);
+                    return this.errorResponse(
+                        ErrorCode.INVALID_REQUEST,
+                        `Unknown operation: ${req.op}`
+                    );
             }
 
             return { data: result };
 
         } catch (e: any) {
-            console.error('[ObjectQL Server] Error:', e);
-            return {
-                error: {
-                    code: 'INTERNAL_ERROR',
-                    message: e.message || 'An error occurred'
-                }
-            };
+            return this.handleError(e);
+        }
+    }
+
+    /**
+     * Handle errors and convert them to appropriate error responses
+     */
+    private handleError(error: any): ObjectQLResponse {
+        console.error('[ObjectQL Server] Error:', error);
+
+        // Handle validation errors
+        if (error.name === 'ValidationError' || error.code === 'VALIDATION_ERROR') {
+            return this.errorResponse(
+                ErrorCode.VALIDATION_ERROR,
+                'Validation failed',
+                { fields: error.fields || error.details }
+            );
+        }
+
+        // Handle permission errors
+        if (error.name === 'PermissionError' || error.code === 'FORBIDDEN') {
+            return this.errorResponse(
+                ErrorCode.FORBIDDEN,
+                error.message || 'You do not have permission to access this resource',
+                error.details
+            );
+        }
+
+        // Handle not found errors
+        if (error.name === 'NotFoundError' || error.code === 'NOT_FOUND') {
+            return this.errorResponse(
+                ErrorCode.NOT_FOUND,
+                error.message || 'Resource not found'
+            );
+        }
+
+        // Handle conflict errors (e.g., unique constraint violations)
+        if (error.name === 'ConflictError' || error.code === 'CONFLICT') {
+            return this.errorResponse(
+                ErrorCode.CONFLICT,
+                error.message || 'Resource conflict',
+                error.details
+            );
+        }
+
+        // Handle database errors
+        if (error.name === 'DatabaseError' || error.code?.startsWith('DB_')) {
+            return this.errorResponse(
+                ErrorCode.DATABASE_ERROR,
+                'Database operation failed',
+                { originalError: error.message }
+            );
         }
+
+        // Default to internal error
+        return this.errorResponse(
+            ErrorCode.INTERNAL_ERROR,
+            error.message || 'An error occurred'
+        );
+    }
+
+    /**
+     * Create a standardized error response
+     */
+    private errorResponse(code: ErrorCode, message: string, details?: any): ObjectQLResponse {
+        return {
+            error: {
+                code,
+                message,
+                details
+            }
+        };
     }
 }

package/src/{console.ts → studio.ts}

@@ -3,27 +3,40 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 /**
- * Creates a handler to serve the console UI static files.
+ * Creates a handler to serve the Studio UI static files.
  */
-export function createConsoleHandler() {
-    // Try to find the built console files
-    const possiblePaths = [
-        path.join(__dirname, '../../console/dist'),
-        path.join(process.cwd(), 'node_modules/@objectql/console/dist'),
-        path.join(process.cwd(), 'packages/console/dist'),
-    ];
-    
+export function createStudioHandler() {
     let distPath: string | null = null;
-    for (const p of possiblePaths) {
-        if (fs.existsSync(p)) {
-            distPath = p;
-            break;
+
+    // 1. Try to resolve from installed package (Standard way)
+    try {
+        const studioPkg = require.resolve('@objectql/studio/package.json');
+        const candidate = path.join(path.dirname(studioPkg), 'dist');
+        if (fs.existsSync(candidate)) {
+            distPath = candidate;
+        }
+    } catch (e) {
+        // @objectql/studio might not be installed
+    }
+
+    // 2. Fallback for local development (Monorepo)
+    if (!distPath) {
+        const possiblePaths = [
+            path.join(__dirname, '../../studio/dist'),
+            path.join(process.cwd(), 'packages/studio/dist'),
+        ];
+        
+        for (const p of possiblePaths) {
+            if (fs.existsSync(p)) {
+                distPath = p;
+                break;
+            }
         }
     }
     
     return async (req: IncomingMessage, res: ServerResponse) => {
         if (!distPath) {
-            // Return placeholder page if console is not built
+            // Return placeholder page if studio is not built
             const html = getPlaceholderPage();
             res.setHeader('Content-Type', 'text/html');
             res.statusCode = 200;
@@ -31,8 +44,8 @@ export function createConsoleHandler() {
             return;
         }
         
-        // Parse the URL and remove /console prefix
-        let urlPath = (req.url || '').replace(/^\/console/, '') || '/';
+        // Parse the URL and remove /studio prefix
+        let urlPath = (req.url || '').replace(/^\/studio/, '') || '/';
         
         // Default to index.html for SPA routing
         if (urlPath === '/' || !urlPath.includes('.')) {
@@ -97,7 +110,7 @@ function getPlaceholderPage(): string {
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>ObjectQL Console</title>
+    <title>ObjectQL Studio</title>
     <style>
         * { margin: 0; padding: 0; box-sizing: border-box; }
         body {
@@ -133,15 +146,15 @@ function getPlaceholderPage(): string {
 </head>
 <body>
     <div class="container">
-        <h1>ObjectQL Console</h1>
-        <p>Web-based admin console for database management</p>
+        <h1>ObjectQL Studio</h1>
+        <p>Web-based admin studio for database management</p>
         <div class="info">
             <p style="margin-bottom: 1rem;">
-                The console is available but needs to be built separately.
+                The studio is available but needs to be built separately.
             </p>
             <p style="font-size: 1rem;">
-                To use the full console UI, run:<br>
-                <code>cd packages/console && pnpm run build</code>
+                To use the full studio UI, run:<br>
+                <code>cd packages/studio && pnpm run build</code>
             </p>
         </div>
     </div>

package/src/types.ts

@@ -1,4 +1,33 @@
 // src/types.ts
+
+/**
+ * Standardized error codes for ObjectQL API
+ */
+export enum ErrorCode {
+    INVALID_REQUEST = 'INVALID_REQUEST',
+    VALIDATION_ERROR = 'VALIDATION_ERROR',
+    UNAUTHORIZED = 'UNAUTHORIZED',
+    FORBIDDEN = 'FORBIDDEN',
+    NOT_FOUND = 'NOT_FOUND',
+    CONFLICT = 'CONFLICT',
+    INTERNAL_ERROR = 'INTERNAL_ERROR',
+    DATABASE_ERROR = 'DATABASE_ERROR',
+    RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED'
+}
+
+/**
+ * AI context for better logging, debugging, and AI processing
+ */
+export interface AIContext {
+    intent?: string;
+    natural_language?: string;
+    use_case?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * ObjectQL JSON-RPC style request
+ */
 export interface ObjectQLRequest {
     // Identity provided by the framework adapter (e.g. from session)
     user?: {
@@ -13,12 +42,37 @@ export interface ObjectQLRequest {
     
     // Arguments
     args: any;
+    
+    // Optional AI context for explainability
+    ai_context?: AIContext;
+}
+
+/**
+ * Error details structure
+ */
+export interface ErrorDetails {
+    field?: string;
+    reason?: string;
+    fields?: Record<string, string>;
+    required_permission?: string;
+    user_roles?: string[];
+    retry_after?: number;
+    [key: string]: unknown;
 }
 
+/**
+ * ObjectQL API response
+ */
 export interface ObjectQLResponse {
     data?: any;
     error?: {
-        code: string;
+        code: ErrorCode | string;
         message: string;
-    }
+        details?: ErrorDetails;
+    };
+    meta?: {
+        total?: number;
+        page?: number;
+        per_page?: number;
+    };
 }

package/test/rest.test.ts

@@ -0,0 +1,164 @@
+import request from 'supertest';
+import { createServer } from 'http';
+import { ObjectQL } from '@objectql/core';
+import { createRESTHandler } from '../src/adapters/rest';
+import { Driver } from '@objectql/types';
+
+// Simple Mock Driver
+class MockDriver implements Driver {
+    private data: Record<string, any[]> = {
+        user: [
+            { _id: '1', name: 'Alice', email: 'alice@example.com' },
+            { _id: '2', name: 'Bob', email: 'bob@example.com' }
+        ]
+    };
+    private nextId = 3;
+
+    async init() {}
+    
+    async find(objectName: string, query: any) {
+        return this.data[objectName] || [];
+    }
+    
+    async findOne(objectName: string, id: string | number, query?: any, options?: any) {
+        const items = this.data[objectName] || [];
+        if (id !== undefined && id !== null) {
+            const found = items.find(item => item._id === String(id));
+            return found || null;
+        }
+        return items[0] || null;
+    }
+    
+    async create(objectName: string, data: any) {
+        const newItem = { _id: String(this.nextId++), ...data };
+        if (!this.data[objectName]) {
+            this.data[objectName] = [];
+        }
+        this.data[objectName].push(newItem);
+        return newItem;
+    }
+    
+    async update(objectName: string, id: string, data: any) {
+        const items = this.data[objectName] || [];
+        const index = items.findIndex(item => item._id === id);
+        if (index >= 0) {
+            this.data[objectName][index] = { ...items[index], ...data };
+            return 1;
+        }
+        return 0;
+    }
+    
+    async delete(objectName: string, id: string) {
+        const items = this.data[objectName] || [];
+        const index = items.findIndex(item => item._id === id);
+        if (index >= 0) {
+            this.data[objectName].splice(index, 1);
+            return 1;
+        }
+        return 0;
+    }
+    
+    async count(objectName: string, query: any) {
+        return (this.data[objectName] || []).length;
+    }
+    
+    async execute(sql: string) {}
+}
+
+describe('REST API Adapter', () => {
+    let app: ObjectQL;
+    let server: any;
+    let handler: any;
+
+    beforeAll(async () => {
+        app = new ObjectQL({
+            datasources: {
+                default: new MockDriver()
+            }
+        });
+        
+        // Manual schema registration
+        app.metadata.register('object', {
+            type: 'object',
+            id: 'user',
+            content: {
+                name: 'user',
+                fields: {
+                    name: { type: 'text' },
+                    email: { type: 'email' }
+                }
+            }
+        });
+
+        // Create handler and server once for all tests
+        handler = createRESTHandler(app);
+        server = createServer(handler);
+    });
+
+    it('should handle GET /api/data/:object - List records', async () => {
+        const response = await request(server)
+            .get('/api/data/user')
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(200);
+        expect(response.body.data).toHaveLength(2);
+        expect(response.body.data[0].name).toBe('Alice');
+    });
+
+    it('should handle GET /api/data/:object/:id - Get single record', async () => {
+        const response = await request(server)
+            .get('/api/data/user/1')
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.name).toBe('Alice');
+    });
+
+    it('should handle POST /api/data/:object - Create record', async () => {
+        const response = await request(server)
+            .post('/api/data/user')
+            .send({ name: 'Charlie', email: 'charlie@example.com' })
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(201);
+        expect(response.body.data.name).toBe('Charlie');
+        expect(response.body.data._id).toBeDefined();
+    });
+
+    it('should handle PUT /api/data/:object/:id - Update record', async () => {
+        const response = await request(server)
+            .put('/api/data/user/1')
+            .send({ name: 'Alice Updated' })
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(200);
+    });
+
+    it('should handle DELETE /api/data/:object/:id - Delete record', async () => {
+        const response = await request(server)
+            .delete('/api/data/user/1')
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.deleted).toBe(true);
+    });
+
+    it('should return 404 for non-existent object', async () => {
+        const response = await request(server)
+            .get('/api/data/nonexistent')
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(404);
+        expect(response.body.error.code).toBe('NOT_FOUND');
+    });
+
+    it('should return 400 for update without ID', async () => {
+        const response = await request(server)
+            .put('/api/data/user')
+            .send({ name: 'Test' })
+            .set('Accept', 'application/json');
+
+        expect(response.status).toBe(400);
+        expect(response.body.error.code).toBe('INVALID_REQUEST');
+    });
+});