@objectstack/core 0.8.2 → 0.9.1

package/examples/api-registry-example.ts

@@ -0,0 +1,557 @@
+/**
+ * API Registry Example
+ * 
+ * Demonstrates how to use the API Registry in the ObjectStack kernel
+ * to register and discover API endpoints across plugins.
+ */
+
+import { ObjectKernel, createApiRegistryPlugin, ApiRegistry } from '@objectstack/core';
+import type { Plugin } from '@objectstack/core';
+import type { ApiRegistryEntry } from '@objectstack/spec/api';
+
+// Example 1: Basic API Registration
+async function example1_BasicApiRegistration() {
+  console.log('\n=== Example 1: Basic API Registration ===\n');
+
+  const kernel = new ObjectKernel();
+
+  // Register API Registry plugin with default settings
+  kernel.use(createApiRegistryPlugin());
+
+  // Create a plugin that registers a simple REST API
+  const customerPlugin: Plugin = {
+    name: 'customer-plugin',
+    version: '1.0.0',
+    init: async (ctx) => {
+      const registry = ctx.getService<ApiRegistry>('api-registry');
+
+      const customerApi: ApiRegistryEntry = {
+        id: 'customer_api',
+        name: 'Customer Management API',
+        type: 'rest',
+        version: 'v1',
+        basePath: '/api/v1/customers',
+        description: 'CRUD operations for customer records',
+        endpoints: [
+          {
+            id: 'list_customers',
+            method: 'GET',
+            path: '/api/v1/customers',
+            summary: 'List all customers',
+            parameters: [
+              {
+                name: 'limit',
+                in: 'query',
+                schema: { type: 'number' },
+                description: 'Maximum number of results',
+              },
+              {
+                name: 'offset',
+                in: 'query',
+                schema: { type: 'number' },
+                description: 'Offset for pagination',
+              },
+            ],
+            responses: [
+              {
+                statusCode: 200,
+                description: 'Customers retrieved successfully',
+                schema: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      id: { type: 'string' },
+                      name: { type: 'string' },
+                      email: { type: 'string' },
+                    },
+                  },
+                },
+              },
+            ],
+          },
+          {
+            id: 'get_customer',
+            method: 'GET',
+            path: '/api/v1/customers/:id',
+            summary: 'Get customer by ID',
+            requiredPermissions: ['customer.read'], // RBAC integration
+            parameters: [
+              {
+                name: 'id',
+                in: 'path',
+                required: true,
+                schema: { type: 'string', format: 'uuid' },
+              },
+            ],
+            responses: [
+              {
+                statusCode: 200,
+                description: 'Customer found',
+              },
+              {
+                statusCode: 404,
+                description: 'Customer not found',
+              },
+            ],
+          },
+          {
+            id: 'create_customer',
+            method: 'POST',
+            path: '/api/v1/customers',
+            summary: 'Create new customer',
+            requiredPermissions: ['customer.create'],
+            requestBody: {
+              required: true,
+              contentType: 'application/json',
+              schema: {
+                type: 'object',
+                properties: {
+                  name: { type: 'string' },
+                  email: { type: 'string', format: 'email' },
+                },
+              },
+            },
+            responses: [
+              {
+                statusCode: 201,
+                description: 'Customer created',
+              },
+            ],
+          },
+        ],
+        metadata: {
+          status: 'active',
+          tags: ['customer', 'crm', 'data'],
+          owner: 'sales_team',
+        },
+      };
+
+      registry.registerApi(customerApi);
+      ctx.logger.info('Customer API registered', {
+        endpointCount: customerApi.endpoints.length,
+      });
+    },
+  };
+
+  kernel.use(customerPlugin);
+  await kernel.bootstrap();
+
+  // Access the registry
+  const registry = kernel.getService<ApiRegistry>('api-registry');
+  const snapshot = registry.getRegistry();
+
+  console.log(`Total APIs: ${snapshot.totalApis}`);
+  console.log(`Total Endpoints: ${snapshot.totalEndpoints}`);
+  console.log('\nRegistered APIs:');
+  snapshot.apis.forEach((api) => {
+    console.log(`  - ${api.name} (${api.type}) - ${api.endpoints.length} endpoints`);
+  });
+
+  await kernel.shutdown();
+}
+
+// Example 2: Multi-Plugin API Discovery
+async function example2_MultiPluginDiscovery() {
+  console.log('\n=== Example 2: Multi-Plugin API Discovery ===\n');
+
+  const kernel = new ObjectKernel();
+  kernel.use(createApiRegistryPlugin());
+
+  // Data Plugin - REST APIs
+  const dataPlugin: Plugin = {
+    name: 'data-plugin',
+    init: async (ctx) => {
+      const registry = ctx.getService<ApiRegistry>('api-registry');
+
+      registry.registerApi({
+        id: 'customer_api',
+        name: 'Customer API',
+        type: 'rest',
+        version: 'v1',
+        basePath: '/api/v1/customers',
+        endpoints: [
+          {
+            id: 'get_customers',
+            method: 'GET',
+            path: '/api/v1/customers',
+            responses: [],
+          },
+        ],
+        metadata: {
+          status: 'active',
+          tags: ['data', 'crm'],
+        },
+      });
+
+      registry.registerApi({
+        id: 'product_api',
+        name: 'Product API',
+        type: 'rest',
+        version: 'v1',
+        basePath: '/api/v1/products',
+        endpoints: [
+          {
+            id: 'get_products',
+            method: 'GET',
+            path: '/api/v1/products',
+            responses: [],
+          },
+        ],
+        metadata: {
+          status: 'active',
+          tags: ['data', 'inventory'],
+        },
+      });
+    },
+  };
+
+  // GraphQL Plugin
+  const graphqlPlugin: Plugin = {
+    name: 'graphql-plugin',
+    init: async (ctx) => {
+      const registry = ctx.getService<ApiRegistry>('api-registry');
+
+      registry.registerApi({
+        id: 'graphql_api',
+        name: 'GraphQL API',
+        type: 'graphql',
+        version: 'v1',
+        basePath: '/graphql',
+        endpoints: [
+          {
+            id: 'query',
+            path: '/graphql',
+            summary: 'GraphQL Query Endpoint',
+            responses: [],
+          },
+        ],
+        metadata: {
+          status: 'active',
+          tags: ['query', 'flexible'],
+        },
+      });
+    },
+  };
+
+  // Analytics Plugin - Beta API
+  const analyticsPlugin: Plugin = {
+    name: 'analytics-plugin',
+    init: async (ctx) => {
+      const registry = ctx.getService<ApiRegistry>('api-registry');
+
+      registry.registerApi({
+        id: 'analytics_api',
+        name: 'Analytics API',
+        type: 'rest',
+        version: 'v1',
+        basePath: '/api/v1/analytics',
+        endpoints: [
+          {
+            id: 'get_reports',
+            method: 'GET',
+            path: '/api/v1/analytics/reports',
+            responses: [],
+          },
+        ],
+        metadata: {
+          status: 'beta',
+          tags: ['analytics', 'reporting'],
+        },
+      });
+    },
+  };
+
+  kernel.use(dataPlugin);
+  kernel.use(graphqlPlugin);
+  kernel.use(analyticsPlugin);
+  await kernel.bootstrap();
+
+  const registry = kernel.getService<ApiRegistry>('api-registry');
+
+  // Discovery 1: Find all REST APIs
+  console.log('All REST APIs:');
+  const restApis = registry.findApis({ type: 'rest' });
+  restApis.apis.forEach((api) => console.log(`  - ${api.name}`));
+
+  // Discovery 2: Find active APIs
+  console.log('\nActive APIs:');
+  const activeApis = registry.findApis({ status: 'active' });
+  console.log(`  Total: ${activeApis.total}`);
+
+  // Discovery 3: Find data-related APIs
+  console.log('\nData-related APIs:');
+  const dataApis = registry.findApis({ tags: ['data'] });
+  dataApis.apis.forEach((api) => console.log(`  - ${api.name}`));
+
+  // Discovery 4: Search by name
+  console.log('\nSearch for "analytics":');
+  const analyticsApis = registry.findApis({ search: 'analytics' });
+  analyticsApis.apis.forEach((api) => console.log(`  - ${api.name} (${api.metadata?.status})`));
+
+  await kernel.shutdown();
+}
+
+// Example 3: Route Conflict Resolution
+async function example3_ConflictResolution() {
+  console.log('\n=== Example 3: Route Conflict Resolution ===\n');
+
+  const kernel = new ObjectKernel();
+
+  // Use priority-based conflict resolution
+  kernel.use(
+    createApiRegistryPlugin({
+      conflictResolution: 'priority',
+    })
+  );
+
+  // Core Plugin - High priority
+  const corePlugin: Plugin = {
+    name: 'core-plugin',
+    init: async (ctx) => {
+      const registry = ctx.getService<ApiRegistry>('api-registry');
+
+      registry.registerApi({
+        id: 'core_data_api',
+        name: 'Core Data API',
+        type: 'rest',
+        version: 'v1',
+        basePath: '/api',
+        endpoints: [
+          {
+            id: 'core_data',
+            method: 'GET',
+            path: '/api/data/:object',
+            priority: 900, // High priority
+            summary: 'Core data endpoint (generic)',
+            responses: [],
+          },
+        ],
+      });
+
+      ctx.logger.info('Core API registered with priority 900');
+    },
+  };
+
+  // Custom Plugin - Medium priority
+  const customPlugin: Plugin = {
+    name: 'custom-plugin',
+    init: async (ctx) => {
+      const registry = ctx.getService<ApiRegistry>('api-registry');
+
+      registry.registerApi({
+        id: 'custom_data_api',
+        name: 'Custom Data API',
+        type: 'rest',
+        version: 'v1',
+        basePath: '/api',
+        endpoints: [
+          {
+            id: 'custom_data',
+            method: 'GET',
+            path: '/api/data/:object',
+            priority: 300, // Lower priority
+            summary: 'Custom data endpoint (specialized)',
+            responses: [],
+          },
+        ],
+      });
+
+      ctx.logger.info('Custom API registered with priority 300');
+    },
+  };
+
+  kernel.use(corePlugin);
+  kernel.use(customPlugin);
+  await kernel.bootstrap();
+
+  const registry = kernel.getService<ApiRegistry>('api-registry');
+
+  // Check which endpoint won
+  const winner = registry.findEndpointByRoute('GET', '/api/data/:object');
+  console.log('\nConflict Resolution Result:');
+  console.log(`  Route: GET /api/data/:object`);
+  console.log(`  Winner: ${winner?.api.name}`);
+  console.log(`  Endpoint: ${winner?.endpoint.summary}`);
+  console.log(`  Priority: ${winner?.endpoint.priority}`);
+
+  await kernel.shutdown();
+}
+
+// Example 4: Plugin-specific APIs with Custom Protocol
+async function example4_CustomProtocol() {
+  console.log('\n=== Example 4: Custom Protocol Support ===\n');
+
+  const kernel = new ObjectKernel();
+  kernel.use(createApiRegistryPlugin());
+
+  const websocketPlugin: Plugin = {
+    name: 'websocket-plugin',
+    init: async (ctx) => {
+      const registry = ctx.getService<ApiRegistry>('api-registry');
+
+      registry.registerApi({
+        id: 'realtime_api',
+        name: 'Real-time WebSocket API',
+        type: 'websocket',
+        version: 'v1',
+        basePath: '/ws',
+        endpoints: [
+          {
+            id: 'customer_updates',
+            path: '/ws/customers',
+            summary: 'Customer update notifications',
+            protocolConfig: {
+              subProtocol: 'websocket',
+              eventName: 'customer.updated',
+              direction: 'server-to-client',
+            },
+            responses: [],
+          },
+          {
+            id: 'order_updates',
+            path: '/ws/orders',
+            summary: 'Order update notifications',
+            protocolConfig: {
+              subProtocol: 'websocket',
+              eventName: 'order.updated',
+              direction: 'bidirectional',
+            },
+            responses: [],
+          },
+        ],
+        metadata: {
+          status: 'active',
+          tags: ['realtime', 'websocket'],
+          pluginSource: 'websocket-plugin',
+        },
+      });
+    },
+  };
+
+  kernel.use(websocketPlugin);
+  await kernel.bootstrap();
+
+  const registry = kernel.getService<ApiRegistry>('api-registry');
+  const wsApis = registry.findApis({ type: 'websocket' });
+
+  console.log('WebSocket APIs:');
+  wsApis.apis.forEach((api) => {
+    console.log(`\n${api.name}:`);
+    api.endpoints.forEach((endpoint) => {
+      console.log(`  - ${endpoint.summary}`);
+      console.log(`    Event: ${endpoint.protocolConfig?.eventName}`);
+      console.log(`    Direction: ${endpoint.protocolConfig?.direction}`);
+    });
+  });
+
+  await kernel.shutdown();
+}
+
+// Example 5: Dynamic Schema Linking with ObjectQL
+async function example5_DynamicSchemas() {
+  console.log('\n=== Example 5: Dynamic Schema Linking ===\n');
+
+  const kernel = new ObjectKernel();
+  kernel.use(createApiRegistryPlugin());
+
+  const dynamicPlugin: Plugin = {
+    name: 'dynamic-plugin',
+    init: async (ctx) => {
+      const registry = ctx.getService<ApiRegistry>('api-registry');
+
+      registry.registerApi({
+        id: 'dynamic_customer_api',
+        name: 'Dynamic Customer API',
+        type: 'rest',
+        version: 'v1',
+        basePath: '/api/v1/customers',
+        endpoints: [
+          {
+            id: 'get_customer_dynamic',
+            method: 'GET',
+            path: '/api/v1/customers/:id',
+            summary: 'Get customer (with dynamic schema)',
+            responses: [
+              {
+                statusCode: 200,
+                description: 'Customer retrieved',
+                // Dynamic schema linked to ObjectQL
+                // 
+                // IMPORTANT: The API Registry stores this ObjectQL reference as-is.
+                // The actual schema resolution (expanding the reference into a full JSON Schema)
+                // is performed by downstream tools:
+                // - API Gateway: For runtime request/response validation
+                // - OpenAPI/Swagger Generator: For API documentation generation
+                // - GraphQL Schema Builder: For GraphQL type generation
+                // 
+                // The Registry's responsibility is to STORE the reference metadata,
+                // not to resolve or transform it.
+                schema: {
+                  $ref: {
+                    objectId: 'customer', // References ObjectQL object
+                    excludeFields: ['password_hash', 'internal_notes'], // Exclude sensitive fields
+                    includeRelated: ['account', 'primary_contact'], // Include related objects
+                  },
+                },
+              },
+            ],
+          },
+        ],
+      });
+
+      ctx.logger.info('Dynamic Customer API registered with ObjectQL schema references');
+    },
+  };
+
+  kernel.use(dynamicPlugin);
+  await kernel.bootstrap();
+
+  const registry = kernel.getService<ApiRegistry>('api-registry');
+  const endpoint = registry.getEndpoint('dynamic_customer_api', 'get_customer_dynamic');
+
+  console.log('Dynamic Endpoint:');
+  console.log(`  Path: ${endpoint?.path}`);
+  console.log(`  Summary: ${endpoint?.summary}`);
+  
+  if (endpoint?.responses?.[0]?.schema && '$ref' in endpoint.responses[0].schema) {
+    const ref = endpoint.responses[0].schema.$ref;
+    console.log('\n  Schema Reference (stored as metadata):');
+    console.log(`    Object: ${ref.objectId}`);
+    console.log(`    Excluded Fields: ${ref.excludeFields?.join(', ')}`);
+    console.log(`    Included Related: ${ref.includeRelated?.join(', ')}`);
+    console.log('\n  ℹ️  Note: Schema resolution is handled by gateway/documentation tools,');
+    console.log('     not by the API Registry itself.');
+  }
+
+  await kernel.shutdown();
+}
+
+// Run all examples
+async function main() {
+  try {
+    await example1_BasicApiRegistration();
+    await example2_MultiPluginDiscovery();
+    await example3_ConflictResolution();
+    await example4_CustomProtocol();
+    await example5_DynamicSchemas();
+    
+    console.log('\n=== All examples completed successfully! ===\n');
+  } catch (error) {
+    console.error('Example failed:', error);
+    process.exit(1);
+  }
+}
+
+// Only run if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export {
+  example1_BasicApiRegistration,
+  example2_MultiPluginDiscovery,
+  example3_ConflictResolution,
+  example4_CustomProtocol,
+  example5_DynamicSchemas,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/core",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Microkernel Core for ObjectStack",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,7 @@
     "pino": "^8.17.0",
     "pino-pretty": "^10.3.0",
     "zod": "^4.3.6",
-    "@objectstack/spec": "0.8.2"
+    "@objectstack/spec": "0.9.1"
   },
   "peerDependencies": {
     "pino": "^8.0.0"