@objectstack/core 0.8.2 → 0.9.1

package/API_REGISTRY.md

@@ -0,0 +1,392 @@
+# API Registry Implementation
+
+## Overview
+
+The API Registry is a centralized service in the ObjectStack kernel that manages API endpoint registration, discovery, and conflict resolution across different protocols and plugins.
+
+## Features
+
+✅ **Multi-Protocol Support** - REST, GraphQL, OData, WebSocket, Plugin APIs, and more  
+✅ **Route Conflict Detection** - Configurable strategies (error, priority, first-wins, last-wins)  
+✅ **RBAC Integration** - Endpoints can specify required permissions  
+✅ **Dynamic Schema Linking** - Reference ObjectQL objects for auto-updating schemas  
+✅ **Protocol Extensions** - Support for gRPC, tRPC, and custom protocols  
+✅ **API Discovery** - Filter and search APIs by type, status, tags, and more  
+
+## Architecture
+
+The API Registry follows the ObjectStack microkernel pattern:
+
+```
+┌─────────────────────────────────────────────────────┐
+│              ObjectKernel (Core)                     │
+│  ┌───────────────────────────────────────────────┐  │
+│  │  Service Registry (DI Container)              │  │
+│  │  ┌─────────────────────────────────────────┐  │  │
+│  │  │    API Registry Service                 │  │  │
+│  │  │    • registerApi()                      │  │  │
+│  │  │    • unregisterApi()                    │  │  │
+│  │  │    • findApis()                         │  │  │
+│  │  │    • getRegistry()                      │  │  │
+│  │  └─────────────────────────────────────────┘  │  │
+│  └───────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────┘
+              │
+    ┌─────────┴─────────┬──────────┬──────────┐
+    │                   │          │          │
+┌───▼────┐      ┌───────▼──┐   ┌──▼───┐  ┌───▼────┐
+│  REST  │      │ GraphQL  │   │WebSkt│  │ Plugin │
+│ Plugin │      │  Plugin  │   │Plugin│  │  APIs  │
+└────────┘      └──────────┘   └──────┘  └────────┘
+```
+
+## Usage
+
+### 1. Register the API Registry Plugin
+
+```typescript
+import { ObjectKernel, createApiRegistryPlugin } from '@objectstack/core';
+
+const kernel = new ObjectKernel();
+
+// Register with default settings (error on conflicts)
+kernel.use(createApiRegistryPlugin());
+
+// Or with custom configuration
+kernel.use(
+  createApiRegistryPlugin({
+    conflictResolution: 'priority', // priority, first-wins, last-wins
+    version: '1.0.0',
+  })
+);
+
+await kernel.bootstrap();
+```
+
+### 2. Register APIs in Plugins
+
+```typescript
+import type { Plugin } from '@objectstack/core';
+import type { ApiRegistry } from '@objectstack/core';
+import type { ApiRegistryEntry } from '@objectstack/spec/api';
+
+const myPlugin: Plugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+  
+  init: async (ctx) => {
+    // Get the API Registry service
+    const registry = ctx.getService<ApiRegistry>('api-registry');
+    
+    // Register your API
+    const api: ApiRegistryEntry = {
+      id: 'customer_api',
+      name: 'Customer API',
+      type: 'rest',
+      version: 'v1',
+      basePath: '/api/v1/customers',
+      endpoints: [
+        {
+          id: 'get_customer',
+          method: 'GET',
+          path: '/api/v1/customers/:id',
+          summary: 'Get customer by ID',
+          requiredPermissions: ['customer.read'], // RBAC
+          parameters: [
+            {
+              name: 'id',
+              in: 'path',
+              required: true,
+              schema: { type: 'string', format: 'uuid' },
+            },
+          ],
+          responses: [
+            {
+              statusCode: 200,
+              description: 'Customer found',
+              schema: {
+                $ref: {
+                  objectId: 'customer', // Dynamic ObjectQL reference
+                  excludeFields: ['password_hash'],
+                },
+              },
+            },
+          ],
+        },
+      ],
+      metadata: {
+        status: 'active',
+        tags: ['customer', 'crm'],
+      },
+    };
+    
+    registry.registerApi(api);
+  },
+};
+```
+
+### 3. Discover APIs
+
+```typescript
+const registry = kernel.getService<ApiRegistry>('api-registry');
+
+// Get all APIs
+const allApis = registry.getAllApis();
+
+// Find REST APIs
+const restApis = registry.findApis({ type: 'rest' });
+
+// Find active APIs with specific tags
+const crmApis = registry.findApis({
+  status: 'active',
+  tags: ['crm'],
+});
+
+// Search by name
+const searchResults = registry.findApis({
+  search: 'customer',
+});
+
+// Get endpoint by route
+const endpoint = registry.findEndpointByRoute('GET', '/api/v1/customers/:id');
+console.log(endpoint?.api.name); // "Customer API"
+console.log(endpoint?.endpoint.summary); // "Get customer by ID"
+```
+
+### 4. Get Registry Snapshot
+
+```typescript
+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(`Conflict Resolution: ${snapshot.conflictResolution}`);
+
+// APIs grouped by type
+snapshot.byType?.rest.forEach((api) => {
+  console.log(`REST API: ${api.name}`);
+});
+
+// APIs grouped by status
+snapshot.byStatus?.active.forEach((api) => {
+  console.log(`Active API: ${api.name}`);
+});
+```
+
+## Conflict Resolution Strategies
+
+### 1. Error (Default)
+
+Throws an error when a route conflict is detected.
+
+```typescript
+kernel.use(createApiRegistryPlugin({ conflictResolution: 'error' }));
+```
+
+**Best for:** Production environments where conflicts should be caught early.
+
+### 2. Priority
+
+Uses the `priority` field on endpoints to resolve conflicts. Higher priority wins.
+
+```typescript
+kernel.use(createApiRegistryPlugin({ conflictResolution: 'priority' }));
+
+// In your plugin
+registry.registerApi({
+  endpoints: [
+    {
+      path: '/api/data/:object',
+      priority: 900, // Core API (high priority)
+    },
+  ],
+});
+```
+
+**Priority Ranges:**
+- **900-1000**: Core system endpoints
+- **500-900**: Custom/override endpoints
+- **100-500**: Plugin endpoints
+- **0-100**: Fallback routes
+
+### 3. First-Wins
+
+First registered endpoint wins. Subsequent registrations are ignored.
+
+```typescript
+kernel.use(createApiRegistryPlugin({ conflictResolution: 'first-wins' }));
+```
+
+**Best for:** Stable, predictable routing where load order matters.
+
+### 4. Last-Wins
+
+Last registered endpoint wins. Previous registrations are overwritten.
+
+```typescript
+kernel.use(createApiRegistryPlugin({ conflictResolution: 'last-wins' }));
+```
+
+**Best for:** Development/testing where you want to override defaults.
+
+## RBAC Integration
+
+Endpoints can specify required permissions that are automatically validated at the gateway level:
+
+```typescript
+{
+  id: 'delete_customer',
+  method: 'DELETE',
+  path: '/api/v1/customers/:id',
+  requiredPermissions: [
+    'customer.delete',
+    'api_enabled',
+  ],
+  responses: [],
+}
+```
+
+**Permission Format:**
+- **Object Permissions:** `<object>.<operation>` (e.g., `customer.read`, `order.delete`)
+- **System Permissions:** `<permission_name>` (e.g., `manage_users`, `api_enabled`)
+
+## Dynamic Schema Linking
+
+Reference ObjectQL objects instead of static schemas:
+
+```typescript
+{
+  statusCode: 200,
+  description: 'Customer retrieved',
+  schema: {
+    $ref: {
+      objectId: 'customer',              // ObjectQL object name
+      excludeFields: ['password_hash'],  // Exclude sensitive fields
+      includeFields: ['id', 'name'],     // Or whitelist specific fields
+      includeRelated: ['account'],       // Include related objects
+    },
+  },
+}
+```
+
+**Benefits:**
+- API documentation auto-updates when object schemas change
+- No schema duplication between API and data model
+- Consistent type definitions across API and database
+
+## Protocol-Specific Configuration
+
+Support custom protocols with `protocolConfig`:
+
+### WebSocket
+
+```typescript
+{
+  id: 'customer_updates',
+  path: '/ws/customers',
+  protocolConfig: {
+    subProtocol: 'websocket',
+    eventName: 'customer.updated',
+    direction: 'server-to-client',
+  },
+}
+```
+
+### gRPC
+
+```typescript
+{
+  id: 'grpc_method',
+  path: '/grpc/CustomerService/GetCustomer',
+  protocolConfig: {
+    subProtocol: 'grpc',
+    serviceName: 'CustomerService',
+    methodName: 'GetCustomer',
+    streaming: false,
+  },
+}
+```
+
+### tRPC
+
+```typescript
+{
+  id: 'trpc_query',
+  path: '/trpc/customer.get',
+  protocolConfig: {
+    subProtocol: 'trpc',
+    procedureType: 'query',
+    router: 'customer',
+  },
+}
+```
+
+## API Registry Methods
+
+### Registration
+
+- `registerApi(api: ApiRegistryEntry): void` - Register an API
+- `unregisterApi(apiId: string): void` - Unregister an API
+
+### Discovery
+
+- `getApi(apiId: string): ApiRegistryEntry | undefined` - Get API by ID
+- `getAllApis(): ApiRegistryEntry[]` - Get all registered APIs
+- `findApis(query: ApiDiscoveryQuery): ApiDiscoveryResponse` - Search/filter APIs
+- `getEndpoint(apiId: string, endpointId: string): ApiEndpointRegistration | undefined` - Get specific endpoint
+- `findEndpointByRoute(method: string, path: string): { api, endpoint } | undefined` - Find endpoint by route
+
+### Registry Info
+
+- `getRegistry(): ApiRegistry` - Get complete registry snapshot
+- `getStats(): RegistryStats` - Get registry statistics
+- `clear(): void` - Clear all registered APIs (for testing)
+
+## Examples
+
+See [api-registry-example.ts](./examples/api-registry-example.ts) for comprehensive examples:
+
+1. **Basic API Registration** - Simple REST API with CRUD endpoints
+2. **Multi-Plugin Discovery** - Multiple plugins registering different API types
+3. **Route Conflict Resolution** - Priority-based conflict handling
+4. **Custom Protocol Support** - WebSocket API with protocol config
+5. **Dynamic Schema Linking** - ObjectQL reference in API responses
+
+## Testing
+
+Run the API Registry tests:
+
+```bash
+pnpm --filter @objectstack/core test api-registry.test.ts
+pnpm --filter @objectstack/core test api-registry-plugin.test.ts
+```
+
+**Test Coverage:**
+- ✅ 32 tests for ApiRegistry service
+- ✅ 9 tests for API Registry plugin
+- ✅ All conflict resolution strategies
+- ✅ Multi-protocol support
+- ✅ API discovery and filtering
+- ✅ Integration with kernel lifecycle
+
+## Next Steps
+
+Based on [API_REGISTRY_ENHANCEMENTS.md](../../API_REGISTRY_ENHANCEMENTS.md), recommended next implementations:
+
+1. **API Explorer Plugin** - UI to visualize the registry
+2. **Gateway Integration** - Implement permission checking in API gateway
+3. **Schema Resolution** - Build engine to resolve ObjectQL references to JSON schemas
+4. **Conflict Detection UI** - Visualization of route conflicts and priorities
+5. **Plugin Examples** - Reference implementations for gRPC and tRPC plugins
+
+## Related Documentation
+
+- [API Registry Schema](../spec/src/api/registry.zod.ts) - Zod schema definitions
+- [API Registry Tests](./src/api-registry.test.ts) - Comprehensive test suite
+- [Plugin System](./README.md) - ObjectStack plugin architecture
+- [Microkernel Design](../../ARCHITECTURE.md) - Overall architecture
+
+## License
+
+MIT

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @objectstack/core
 
+## 0.9.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements. All packages updated with unified versioning.
+- Updated dependencies
+  - @objectstack/spec@0.9.1
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -82,6 +82,42 @@ const service = kernel.getService('my-service');
 await kernel.shutdown();
 ```
 
+## 🤖 AI Quick Reference
+
+**For AI Agents:** This package implements a microkernel architecture. Key concepts:
+
+1. **Plugin Lifecycle**: `init()` → `start()` → `destroy()`
+2. **Service Registry**: Share functionality via `ctx.registerService(name, service)` and `ctx.getService(name)`
+3. **Dependencies**: Declare plugin dependencies for automatic load ordering
+4. **Hooks/Events**: Decouple plugins with `ctx.hook(event, handler)` and `ctx.trigger(event, ...args)`
+5. **Logger**: Always use `ctx.logger` for consistent, structured logging
+
+**Common Plugin Pattern:**
+```typescript
+const plugin: Plugin = {
+  name: 'my-plugin',
+  dependencies: ['other-plugin'], // Load after these plugins
+  
+  async init(ctx: PluginContext) {
+    // Register services and hooks
+    const otherService = ctx.getService('other-service');
+    ctx.registerService('my-service', new MyService(otherService));
+    ctx.hook('data:created', async (data) => { /* ... */ });
+  },
+  
+  async start(ctx: PluginContext) {
+    // Execute business logic
+    const service = ctx.getService('my-service');
+    await service.initialize();
+  },
+  
+  async destroy() {
+    // Cleanup resources
+    await service.close();
+  }
+};
+```
+
 ## Configurable Logger
 
 The logger uses **[Pino](https://github.com/pinojs/pino)** for Node.js environments (high-performance, low-overhead) and a simple console-based logger for browsers. It automatically detects the runtime environment.

package/dist/api-registry-plugin.d.ts

@@ -0,0 +1,54 @@
+import type { Plugin } from './types.js';
+import type { ConflictResolutionStrategy } from '@objectstack/spec/api';
+/**
+ * API Registry Plugin Configuration
+ */
+export interface ApiRegistryPluginConfig {
+    /**
+     * Conflict resolution strategy for route conflicts
+     * @default 'error'
+     */
+    conflictResolution?: ConflictResolutionStrategy;
+    /**
+     * Registry version
+     * @default '1.0.0'
+     */
+    version?: string;
+}
+/**
+ * API Registry Plugin
+ *
+ * Registers the API Registry service in the kernel, making it available
+ * to all plugins for endpoint registration and discovery.
+ *
+ * **Usage:**
+ * ```typescript
+ * const kernel = new ObjectKernel();
+ *
+ * // Register API Registry Plugin
+ * kernel.use(createApiRegistryPlugin({ conflictResolution: 'priority' }));
+ *
+ * // In other plugins, access the API Registry
+ * const plugin: Plugin = {
+ *   name: 'my-plugin',
+ *   init: async (ctx) => {
+ *     const registry = ctx.getService<ApiRegistry>('api-registry');
+ *
+ *     // Register plugin APIs
+ *     registry.registerApi({
+ *       id: 'my_plugin_api',
+ *       name: 'My Plugin API',
+ *       type: 'rest',
+ *       version: 'v1',
+ *       basePath: '/api/v1/my-plugin',
+ *       endpoints: [...]
+ *     });
+ *   }
+ * };
+ * ```
+ *
+ * @param config - Plugin configuration
+ * @returns Plugin instance
+ */
+export declare function createApiRegistryPlugin(config?: ApiRegistryPluginConfig): Plugin;
+//# sourceMappingURL=api-registry-plugin.d.ts.map

package/dist/api-registry-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-registry-plugin.d.ts","sourceRoot":"","sources":["../src/api-registry-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IAEhD;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,GAAE,uBAA4B,GACnC,MAAM,CA2BR"}

package/dist/api-registry-plugin.js

@@ -0,0 +1,53 @@
+import { ApiRegistry } from './api-registry.js';
+/**
+ * API Registry Plugin
+ *
+ * Registers the API Registry service in the kernel, making it available
+ * to all plugins for endpoint registration and discovery.
+ *
+ * **Usage:**
+ * ```typescript
+ * const kernel = new ObjectKernel();
+ *
+ * // Register API Registry Plugin
+ * kernel.use(createApiRegistryPlugin({ conflictResolution: 'priority' }));
+ *
+ * // In other plugins, access the API Registry
+ * const plugin: Plugin = {
+ *   name: 'my-plugin',
+ *   init: async (ctx) => {
+ *     const registry = ctx.getService<ApiRegistry>('api-registry');
+ *
+ *     // Register plugin APIs
+ *     registry.registerApi({
+ *       id: 'my_plugin_api',
+ *       name: 'My Plugin API',
+ *       type: 'rest',
+ *       version: 'v1',
+ *       basePath: '/api/v1/my-plugin',
+ *       endpoints: [...]
+ *     });
+ *   }
+ * };
+ * ```
+ *
+ * @param config - Plugin configuration
+ * @returns Plugin instance
+ */
+export function createApiRegistryPlugin(config = {}) {
+    const { conflictResolution = 'error', version = '1.0.0', } = config;
+    return {
+        name: 'com.objectstack.core.api-registry',
+        version: '1.0.0',
+        init: async (ctx) => {
+            // Create API Registry instance
+            const registry = new ApiRegistry(ctx.logger, conflictResolution, version);
+            // Register as a service
+            ctx.registerService('api-registry', registry);
+            ctx.logger.info('API Registry plugin initialized', {
+                conflictResolution,
+                version,
+            });
+        },
+    };
+}

package/dist/api-registry-plugin.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api-registry-plugin.test.d.ts.map

package/dist/api-registry-plugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-registry-plugin.test.d.ts","sourceRoot":"","sources":["../src/api-registry-plugin.test.ts"],"names":[],"mappings":""}