Merge pull request #548 from objectstack-ai/copilot/evaluate-api-protocol-implementation

Author: hotlong

packages/spec/API_IMPLEMENTATION_PLAN.md

@@ -11,6 +11,10 @@ export const ApiCapabilitiesSchema = z.object({
   files: z.boolean().default(true),
   analytics: z.boolean().default(false).describe('Is the Analytics/BI engine enabled?'),
   hub: z.boolean().default(false).describe('Is Hub management enabled?'),
+  ai: z.boolean().default(false).describe('Is the AI engine enabled?'),
+  workflow: z.boolean().default(false).describe('Is the Workflow engine enabled?'),
+  notifications: z.boolean().default(false).describe('Is the Notification service enabled?'),
+  i18n: z.boolean().default(false).describe('Is the i18n service enabled?'),
 });
 
 /**
@@ -20,31 +24,49 @@ export const ApiCapabilitiesSchema = z.object({
  */
 export const ApiRoutesSchema = z.object({
   /** Base URL for Object CRUD (Data Protocol) */
-  data: z.string().describe('e.g. /api/data'),
+  data: z.string().describe('e.g. /api/v1/data'),
 
   /** Base URL for Schema Definitions (Metadata Protocol) */
-  metadata: z.string().describe('e.g. /api/meta'),
+  metadata: z.string().describe('e.g. /api/v1/meta'),
 
   /** Base URL for UI Configurations (Views, Menus) */
-  ui: z.string().optional().describe('e.g. /api/ui'),
+  ui: z.string().optional().describe('e.g. /api/v1/ui'),
 
   /** Base URL for Authentication */
-  auth: z.string().describe('e.g. /api/auth'),
+  auth: z.string().describe('e.g. /api/v1/auth'),
 
   /** Base URL for Automation (Flows/Scripts) */
-  automation: z.string().optional().describe('e.g. /api/automation'),
+  automation: z.string().optional().describe('e.g. /api/v1/automation'),
 
   /** Base URL for File/Storage operations */
-  storage: z.string().optional().describe('e.g. /api/storage'),
+  storage: z.string().optional().describe('e.g. /api/v1/storage'),
 
   /** Base URL for Analytics/BI operations */
-  analytics: z.string().optional().describe('e.g. /api/analytics'),
+  analytics: z.string().optional().describe('e.g. /api/v1/analytics'),
 
   /** Base URL for Hub Management (Multi-tenant/Marketplace) */
-  hub: z.string().optional().describe('e.g. /api/hub'),
+  hub: z.string().optional().describe('e.g. /api/v1/hub'),
 
   /** GraphQL Endpoint (if enabled) */
   graphql: z.string().optional().describe('e.g. /graphql'),
+
+  /** Base URL for Package Management */
+  packages: z.string().optional().describe('e.g. /api/v1/packages'),
+
+  /** Base URL for Workflow Engine */
+  workflow: z.string().optional().describe('e.g. /api/v1/workflow'),
+
+  /** Base URL for Realtime (WebSocket/SSE) */
+  realtime: z.string().optional().describe('e.g. /api/v1/realtime'),
+
+  /** Base URL for Notification Service */
+  notifications: z.string().optional().describe('e.g. /api/v1/notifications'),
+
+  /** Base URL for AI Engine (NLQ, Chat, Suggest) */
+  ai: z.string().optional().describe('e.g. /api/v1/ai'),
+
+  /** Base URL for Internationalization */
+  i18n: z.string().optional().describe('e.g. /api/v1/i18n'),
 });
 
 /**

packages/spec/src/api/discovery.zod.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect } from 'vitest';
+import {
+  DispatcherRouteSchema,
+  DispatcherConfigSchema,
+  DEFAULT_DISPATCHER_ROUTES,
+  type DispatcherRoute,
+  type DispatcherConfig,
+} from './dispatcher.zod';
+
+describe('DispatcherRouteSchema', () => {
+  it('should accept valid route with all fields', () => {
+    const route: DispatcherRoute = {
+      prefix: '/api/v1/data',
+      service: 'data',
+      authRequired: true,
+      criticality: 'required',
+    };
+
+    expect(() => DispatcherRouteSchema.parse(route)).not.toThrow();
+  });
+
+  it('should apply default values', () => {
+    const route = DispatcherRouteSchema.parse({
+      prefix: '/api/v1/ai',
+      service: 'ai',
+    });
+
+    expect(route.authRequired).toBe(true);
+    expect(route.criticality).toBe('optional');
+  });
+
+  it('should accept public route (no auth)', () => {
+    const route = DispatcherRouteSchema.parse({
+      prefix: '/api/v1/discovery',
+      service: 'metadata',
+      authRequired: false,
+    });
+
+    expect(route.authRequired).toBe(false);
+  });
+
+  it('should accept route with permissions', () => {
+    const route = DispatcherRouteSchema.parse({
+      prefix: '/api/v1/meta',
+      service: 'metadata',
+      permissions: ['system.metadata.read'],
+    });
+
+    expect(route.permissions).toEqual(['system.metadata.read']);
+  });
+
+  it('should reject route without leading slash', () => {
+    expect(() => DispatcherRouteSchema.parse({
+      prefix: 'api/v1/data',
+      service: 'data',
+    })).toThrow();
+  });
+
+  it('should reject invalid service name', () => {
+    expect(() => DispatcherRouteSchema.parse({
+      prefix: '/api/v1/invalid',
+      service: 'not-a-service',
+    })).toThrow();
+  });
+
+  it('should accept all valid criticality levels', () => {
+    const levels = ['required', 'core', 'optional'] as const;
+    levels.forEach(criticality => {
+      const route = DispatcherRouteSchema.parse({
+        prefix: '/api/v1/test',
+        service: 'data',
+        criticality,
+      });
+      expect(route.criticality).toBe(criticality);
+    });
+  });
+});
+
+describe('DispatcherConfigSchema', () => {
+  it('should accept valid config with routes', () => {
+    const config: DispatcherConfig = {
+      routes: [
+        { prefix: '/api/v1/data', service: 'data', authRequired: true, criticality: 'required' },
+        { prefix: '/api/v1/meta', service: 'metadata', authRequired: true, criticality: 'required' },
+      ],
+      fallback: '404',
+    };
+
+    expect(() => DispatcherConfigSchema.parse(config)).not.toThrow();
+  });
+
+  it('should apply default fallback', () => {
+    const config = DispatcherConfigSchema.parse({
+      routes: [],
+    });
+
+    expect(config.fallback).toBe('404');
+  });
+
+  it('should accept proxy fallback with target', () => {
+    const config = DispatcherConfigSchema.parse({
+      routes: [],
+      fallback: 'proxy',
+      proxyTarget: 'https://api.example.com',
+    });
+
+    expect(config.fallback).toBe('proxy');
+    expect(config.proxyTarget).toBe('https://api.example.com');
+  });
+
+  it('should accept custom fallback', () => {
+    const config = DispatcherConfigSchema.parse({
+      routes: [],
+      fallback: 'custom',
+    });
+
+    expect(config.fallback).toBe('custom');
+  });
+});
+
+describe('DEFAULT_DISPATCHER_ROUTES', () => {
+  it('should have routes for all protocol namespaces', () => {
+    expect(DEFAULT_DISPATCHER_ROUTES.length).toBeGreaterThanOrEqual(14);
+  });
+
+  it('should include required services', () => {
+    const services = DEFAULT_DISPATCHER_ROUTES.map(r => r.service);
+    expect(services).toContain('metadata');
+    expect(services).toContain('data');
+    expect(services).toContain('auth');
+  });
+
+  it('should include optional services', () => {
+    const services = DEFAULT_DISPATCHER_ROUTES.map(r => r.service);
+    expect(services).toContain('ai');
+    expect(services).toContain('i18n');
+    expect(services).toContain('ui');
+    expect(services).toContain('workflow');
+    expect(services).toContain('realtime');
+    expect(services).toContain('notification');
+    expect(services).toContain('analytics');
+    expect(services).toContain('automation');
+    expect(services).toContain('hub');
+  });
+
+  it('should have discovery as public route', () => {
+    const discovery = DEFAULT_DISPATCHER_ROUTES.find(r => r.prefix.includes('discovery'));
+    expect(discovery).toBeDefined();
+    expect(discovery!.authRequired).toBe(false);
+  });
+
+  it('should mark required services with required criticality', () => {
+    const required = DEFAULT_DISPATCHER_ROUTES.filter(r => r.criticality === 'required');
+    const requiredServices = required.map(r => r.service);
+    expect(requiredServices).toContain('metadata');
+    expect(requiredServices).toContain('data');
+    expect(requiredServices).toContain('auth');
+  });
+
+  it('should have all prefixes starting with /', () => {
+    DEFAULT_DISPATCHER_ROUTES.forEach(route => {
+      expect(route.prefix).toMatch(/^\//);
+    });
+  });
+
+  it('should be parseable by DispatcherConfigSchema', () => {
+    expect(() => DispatcherConfigSchema.parse({
+      routes: DEFAULT_DISPATCHER_ROUTES,
+    })).not.toThrow();
+  });
+});