@objectstack/spec 0.8.2 → 0.9.1

package/dist/api/registry.zod.js

@@ -0,0 +1,755 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiRegistry = exports.ApiRegistryEntry = exports.ApiEndpointRegistration = exports.ApiDiscoveryResponseSchema = exports.ApiDiscoveryQuerySchema = exports.ApiRegistrySchema = exports.ConflictResolutionStrategy = exports.ApiRegistryEntrySchema = exports.ApiMetadataSchema = exports.ApiEndpointRegistrationSchema = exports.ApiResponseSchema = exports.ApiParameterSchema = exports.SchemaDefinition = exports.ObjectQLReferenceSchema = exports.HttpStatusCode = exports.ApiProtocolType = void 0;
+const zod_1 = require("zod");
+const http_zod_1 = require("../shared/http.zod");
+const identifiers_zod_1 = require("../shared/identifiers.zod");
+/**
+ * Unified API Registry Protocol
+ *
+ * Provides a centralized registry for managing all API endpoints across different
+ * API types (REST, GraphQL, OData, WebSocket, Auth, File, Plugin-registered).
+ *
+ * This enables:
+ * - Unified API discovery and documentation (similar to Swagger/OpenAPI)
+ * - API testing interfaces
+ * - API governance and monitoring
+ * - Plugin API registration
+ * - Multi-protocol support
+ *
+ * Architecture Alignment:
+ * - Kubernetes: Service Discovery & API Server
+ * - AWS API Gateway: Unified API Management
+ * - Kong Gateway: Plugin-based API Management
+ *
+ * @example API Registry Entry
+ * ```typescript
+ * const apiEntry: ApiRegistryEntry = {
+ *   id: 'customer_crud',
+ *   name: 'Customer CRUD API',
+ *   type: 'rest',
+ *   version: 'v1',
+ *   basePath: '/api/v1/data/customer',
+ *   endpoints: [...],
+ *   metadata: {
+ *     owner: 'sales_team',
+ *     tags: ['customer', 'crm']
+ *   }
+ * }
+ * ```
+ */
+// ==========================================
+// API Type Enumeration
+// ==========================================
+/**
+ * API Protocol Type
+ *
+ * Defines the different types of APIs supported by ObjectStack.
+ */
+exports.ApiProtocolType = zod_1.z.enum([
+    'rest', // RESTful API (CRUD operations)
+    'graphql', // GraphQL API (flexible queries)
+    'odata', // OData v4 API (enterprise integration)
+    'websocket', // WebSocket API (real-time)
+    'file', // File/Storage API (uploads/downloads)
+    'auth', // Authentication/Authorization API
+    'metadata', // Metadata/Schema API
+    'plugin', // Plugin-registered custom API
+    'webhook', // Webhook endpoints
+    'rpc', // JSON-RPC or similar
+]);
+// ==========================================
+// API Endpoint Registration
+// ==========================================
+/**
+ * HTTP Status Code
+ */
+exports.HttpStatusCode = zod_1.z.union([
+    zod_1.z.number().int().min(100).max(599),
+    zod_1.z.enum(['2xx', '3xx', '4xx', '5xx']), // Pattern matching
+]);
+// ==========================================
+// Schema Reference Types
+// ==========================================
+/**
+ * ObjectQL Reference Schema
+ *
+ * Allows referencing ObjectStack data objects instead of static JSON schemas.
+ * When an API parameter or response references an ObjectQL object, the schema
+ * is dynamically derived from the object definition, enabling automatic updates
+ * when the object schema changes.
+ *
+ * **IMPORTANT - Schema Resolution Responsibility:**
+ * The API Registry STORES these references as metadata but does NOT resolve them.
+ * Schema resolution (expanding references into actual JSON Schema) is performed by:
+ * - **API Gateway**: For runtime request/response validation
+ * - **OpenAPI Generator**: For Swagger/OpenAPI documentation
+ * - **GraphQL Schema Builder**: For GraphQL type generation
+ * - **Documentation Tools**: For developer documentation
+ *
+ * This separation allows the Registry to remain lightweight and focused on
+ * registration/discovery, while specialized tools handle schema transformation.
+ *
+ * **Benefits:**
+ * - Auto-updating API documentation when object schemas change
+ * - Consistent type definitions across API and database
+ * - Reduced duplication and maintenance
+ * - Registry remains protocol-agnostic and lightweight
+ *
+ * @example Reference Customer object
+ * ```json
+ * {
+ *   "objectId": "customer",
+ *   "includeFields": ["id", "name", "email"],
+ *   "excludeFields": ["internal_notes"]
+ * }
+ * ```
+ */
+exports.ObjectQLReferenceSchema = zod_1.z.object({
+    /** Referenced object name (snake_case) */
+    objectId: identifiers_zod_1.SnakeCaseIdentifierSchema.describe('Object name to reference'),
+    /** Include only specific fields (optional) */
+    includeFields: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Include only these fields in the schema'),
+    /** Exclude specific fields (optional) */
+    excludeFields: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Exclude these fields from the schema'),
+    /** Include related objects via lookup fields */
+    includeRelated: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Include related objects via lookup fields'),
+});
+/**
+ * Schema Definition
+ *
+ * Unified schema definition that supports both:
+ * 1. Static JSON Schema (traditional approach)
+ * 2. Dynamic ObjectQL reference (linked to object definitions)
+ *
+ * When using ObjectQL references, the API documentation and validation
+ * automatically update when object schemas change, eliminating the need
+ * to manually sync API schemas with data models.
+ */
+exports.SchemaDefinition = zod_1.z.union([
+    zod_1.z.any().describe('Static JSON Schema definition'),
+    zod_1.z.object({
+        $ref: exports.ObjectQLReferenceSchema.describe('Dynamic reference to ObjectQL object'),
+    }).describe('Dynamic ObjectQL reference'),
+]);
+// ==========================================
+// API Parameter & Response Schemas
+// ==========================================
+/**
+ * API Parameter Schema
+ *
+ * Defines a single API parameter (path, query, header, or body).
+ *
+ * **Enhancement: Dynamic Schema Linking**
+ * - Supports both static JSON Schema and dynamic ObjectQL references
+ * - When using ObjectQL references, parameter validation automatically updates
+ *   when the referenced object schema changes
+ *
+ * @example Static schema
+ * ```json
+ * {
+ *   "name": "customer_id",
+ *   "in": "path",
+ *   "schema": {
+ *     "type": "string",
+ *     "format": "uuid"
+ *   }
+ * }
+ * ```
+ *
+ * @example Dynamic ObjectQL reference
+ * ```json
+ * {
+ *   "name": "customer",
+ *   "in": "body",
+ *   "schema": {
+ *     "$ref": {
+ *       "objectId": "customer",
+ *       "excludeFields": ["internal_notes"]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+exports.ApiParameterSchema = zod_1.z.object({
+    /** Parameter name */
+    name: zod_1.z.string().describe('Parameter name'),
+    /** Parameter location */
+    in: zod_1.z.enum(['path', 'query', 'header', 'body', 'cookie']).describe('Parameter location'),
+    /** Parameter description */
+    description: zod_1.z.string().optional().describe('Parameter description'),
+    /** Required flag */
+    required: zod_1.z.boolean().default(false).describe('Whether parameter is required'),
+    /** Parameter type/schema - supports static or dynamic (ObjectQL) schemas */
+    schema: zod_1.z.union([
+        zod_1.z.object({
+            type: zod_1.z.enum(['string', 'number', 'integer', 'boolean', 'array', 'object']).describe('Parameter type'),
+            format: zod_1.z.string().optional().describe('Format (e.g., date-time, email, uuid)'),
+            enum: zod_1.z.array(zod_1.z.any()).optional().describe('Allowed values'),
+            default: zod_1.z.any().optional().describe('Default value'),
+            items: zod_1.z.any().optional().describe('Array item schema'),
+            properties: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Object properties'),
+        }).describe('Static JSON Schema'),
+        zod_1.z.object({
+            $ref: exports.ObjectQLReferenceSchema,
+        }).describe('Dynamic ObjectQL reference'),
+    ]).describe('Parameter schema definition'),
+    /** Example value */
+    example: zod_1.z.any().optional().describe('Example value'),
+});
+/**
+ * API Response Schema
+ *
+ * Defines an API response for a specific status code.
+ *
+ * **Enhancement: Dynamic Schema Linking**
+ * - Response schema can reference ObjectQL objects
+ * - When object definitions change, response documentation auto-updates
+ *
+ * @example Response with ObjectQL reference
+ * ```json
+ * {
+ *   "statusCode": 200,
+ *   "description": "Customer retrieved successfully",
+ *   "schema": {
+ *     "$ref": {
+ *       "objectId": "customer",
+ *       "excludeFields": ["password_hash"]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+exports.ApiResponseSchema = zod_1.z.object({
+    /** HTTP status code */
+    statusCode: exports.HttpStatusCode.describe('HTTP status code'),
+    /** Response description */
+    description: zod_1.z.string().describe('Response description'),
+    /** Response content type */
+    contentType: zod_1.z.string().default('application/json').describe('Response content type'),
+    /** Response schema - supports static or dynamic (ObjectQL) schemas */
+    schema: zod_1.z.union([
+        zod_1.z.any().describe('Static JSON Schema'),
+        zod_1.z.object({
+            $ref: exports.ObjectQLReferenceSchema,
+        }).describe('Dynamic ObjectQL reference'),
+    ]).optional().describe('Response body schema'),
+    /** Response headers */
+    headers: zod_1.z.record(zod_1.z.string(), zod_1.z.object({
+        description: zod_1.z.string().optional(),
+        schema: zod_1.z.any(),
+    })).optional().describe('Response headers'),
+    /** Example response */
+    example: zod_1.z.any().optional().describe('Example response'),
+});
+/**
+ * API Endpoint Registration Schema
+ *
+ * Represents a single API endpoint registration with complete metadata.
+ *
+ * **Enhancements:**
+ * 1. **RBAC Integration**: `requiredPermissions` field for automatic permission checking
+ * 2. **Dynamic Schema Linking**: Parameters and responses can reference ObjectQL objects
+ * 3. **Route Priority**: `priority` field for conflict resolution
+ * 4. **Protocol Config**: `protocolConfig` for protocol-specific extensions
+ *
+ * @example REST Endpoint with RBAC
+ * ```json
+ * {
+ *   "id": "get_customer_by_id",
+ *   "method": "GET",
+ *   "path": "/api/v1/data/customer/:id",
+ *   "summary": "Get customer by ID",
+ *   "requiredPermissions": ["customer.read"],
+ *   "parameters": [
+ *     {
+ *       "name": "id",
+ *       "in": "path",
+ *       "required": true,
+ *       "schema": { "type": "string" }
+ *     }
+ *   ],
+ *   "responses": [
+ *     {
+ *       "statusCode": 200,
+ *       "description": "Customer found",
+ *       "schema": {
+ *         "$ref": {
+ *           "objectId": "customer"
+ *         }
+ *       }
+ *     }
+ *   ],
+ *   "priority": 100
+ * }
+ * ```
+ *
+ * @example Plugin Endpoint with Protocol Config
+ * ```json
+ * {
+ *   "id": "grpc_service_method",
+ *   "path": "/grpc/ServiceName/MethodName",
+ *   "summary": "gRPC service method",
+ *   "protocolConfig": {
+ *     "subProtocol": "grpc",
+ *     "serviceName": "CustomerService",
+ *     "methodName": "GetCustomer"
+ *   },
+ *   "priority": 50
+ * }
+ * ```
+ */
+exports.ApiEndpointRegistrationSchema = zod_1.z.object({
+    /** Unique endpoint identifier */
+    id: zod_1.z.string().describe('Unique endpoint identifier'),
+    /** HTTP method (for HTTP-based APIs) */
+    method: http_zod_1.HttpMethod.optional().describe('HTTP method'),
+    /** URL path pattern */
+    path: zod_1.z.string().describe('URL path pattern'),
+    /** Short summary */
+    summary: zod_1.z.string().optional().describe('Short endpoint summary'),
+    /** Detailed description */
+    description: zod_1.z.string().optional().describe('Detailed endpoint description'),
+    /** Operation ID (OpenAPI) */
+    operationId: zod_1.z.string().optional().describe('Unique operation identifier'),
+    /** Tags for grouping */
+    tags: zod_1.z.array(zod_1.z.string()).optional().default([]).describe('Tags for categorization'),
+    /** Parameters */
+    parameters: zod_1.z.array(exports.ApiParameterSchema).optional().default([]).describe('Endpoint parameters'),
+    /** Request body schema */
+    requestBody: zod_1.z.object({
+        description: zod_1.z.string().optional(),
+        required: zod_1.z.boolean().default(false),
+        contentType: zod_1.z.string().default('application/json'),
+        schema: zod_1.z.any().optional(),
+        example: zod_1.z.any().optional(),
+    }).optional().describe('Request body specification'),
+    /** Response definitions */
+    responses: zod_1.z.array(exports.ApiResponseSchema).optional().default([]).describe('Possible responses'),
+    /**
+     * Required Permissions (RBAC Integration)
+     *
+     * Array of permission names required to access this endpoint.
+     * The gateway layer automatically validates these permissions before
+     * allowing the request to proceed, eliminating the need for permission
+     * checks in individual API handlers.
+     *
+     * **Format:** `<object>.<operation>` or system permission name
+     *
+     * **Object Permissions:**
+     * - `customer.read` - Read customer records
+     * - `customer.create` - Create customer records
+     * - `customer.edit` - Update customer records
+     * - `customer.delete` - Delete customer records
+     * - `customer.viewAll` - View all customer records (bypass sharing)
+     * - `customer.modifyAll` - Modify all customer records (bypass sharing)
+     *
+     * **System Permissions:**
+     * - `manage_users` - User management
+     * - `view_setup` - Access to system setup
+     * - `customize_application` - Modify metadata
+     * - `api_enabled` - API access
+     *
+     * @example Object-level permissions
+     * ```json
+     * {
+     *   "requiredPermissions": ["customer.read"]
+     * }
+     * ```
+     *
+     * @example Multiple permissions (ALL required)
+     * ```json
+     * {
+     *   "requiredPermissions": ["customer.read", "account.read"]
+     * }
+     * ```
+     *
+     * @example System permission
+     * ```json
+     * {
+     *   "requiredPermissions": ["manage_users"]
+     * }
+     * ```
+     *
+     * @see {@link file://../../permission/permission.zod.ts} for permission definitions
+     */
+    requiredPermissions: zod_1.z.array(zod_1.z.string()).optional().default([])
+        .describe('Required RBAC permissions (e.g., "customer.read", "manage_users")'),
+    /** Security requirements */
+    security: zod_1.z.array(zod_1.z.object({
+        type: zod_1.z.enum(['apiKey', 'http', 'oauth2', 'openIdConnect']),
+        scheme: zod_1.z.string().optional(), // bearer, basic, etc.
+        name: zod_1.z.string().optional(), // for apiKey
+        in: zod_1.z.enum(['header', 'query', 'cookie']).optional(),
+    })).optional().describe('Security requirements'),
+    /**
+     * Route Priority
+     *
+     * Priority level for route conflict resolution. Higher priority routes
+     * are registered first and take precedence when multiple routes match
+     * the same path pattern.
+     *
+     * **Default:** 100 (medium priority)
+     * **Range:** 0-1000 (higher = more important)
+     *
+     * **Use Cases:**
+     * - Core system APIs: 900-1000
+     * - Plugin APIs: 100-500
+     * - Custom/override APIs: 500-900
+     * - Fallback routes: 0-100
+     *
+     * @example High priority core endpoint
+     * ```json
+     * {
+     *   "path": "/api/v1/data/:object/:id",
+     *   "priority": 950
+     * }
+     * ```
+     *
+     * @example Medium priority plugin endpoint
+     * ```json
+     * {
+     *   "path": "/api/v1/custom/action",
+     *   "priority": 300
+     * }
+     * ```
+     */
+    priority: zod_1.z.number().int().min(0).max(1000).optional().default(100)
+        .describe('Route priority for conflict resolution (0-1000, higher = more important)'),
+    /**
+     * Protocol-Specific Configuration
+     *
+     * Allows plugins and custom APIs to define protocol-specific metadata
+     * that can be used for specialized handling or documentation generation.
+     *
+     * **Examples:**
+     * - gRPC: Service and method names
+     * - tRPC: Procedure type (query/mutation)
+     * - WebSocket: Event names and handlers
+     * - Custom protocols: Any metadata needed
+     *
+     * @example gRPC configuration
+     * ```json
+     * {
+     *   "protocolConfig": {
+     *     "subProtocol": "grpc",
+     *     "serviceName": "CustomerService",
+     *     "methodName": "GetCustomer",
+     *     "streaming": false
+     *   }
+     * }
+     * ```
+     *
+     * @example tRPC configuration
+     * ```json
+     * {
+     *   "protocolConfig": {
+     *     "subProtocol": "trpc",
+     *     "procedureType": "query",
+     *     "router": "customer"
+     *   }
+     * }
+     * ```
+     *
+     * @example WebSocket configuration
+     * ```json
+     * {
+     *   "protocolConfig": {
+     *     "subProtocol": "websocket",
+     *     "eventName": "customer.updated",
+     *     "direction": "server-to-client"
+     *   }
+     * }
+     * ```
+     */
+    protocolConfig: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional()
+        .describe('Protocol-specific configuration for custom protocols (gRPC, tRPC, etc.)'),
+    /** Deprecation flag */
+    deprecated: zod_1.z.boolean().default(false).describe('Whether endpoint is deprecated'),
+    /** External documentation */
+    externalDocs: zod_1.z.object({
+        description: zod_1.z.string().optional(),
+        url: zod_1.z.string().url(),
+    }).optional().describe('External documentation link'),
+});
+// ==========================================
+// API Registry Entry
+// ==========================================
+/**
+ * API Metadata Schema
+ *
+ * Additional metadata for an API registration.
+ */
+exports.ApiMetadataSchema = zod_1.z.object({
+    /** API owner/team */
+    owner: zod_1.z.string().optional().describe('Owner team or person'),
+    /** API status */
+    status: zod_1.z.enum(['active', 'deprecated', 'experimental', 'beta']).default('active')
+        .describe('API lifecycle status'),
+    /** Categorization tags */
+    tags: zod_1.z.array(zod_1.z.string()).optional().default([]).describe('Classification tags'),
+    /** Plugin source (if plugin-registered) */
+    pluginSource: zod_1.z.string().optional().describe('Source plugin name'),
+    /** Custom metadata */
+    custom: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Custom metadata fields'),
+});
+/**
+ * API Registry Entry Schema
+ *
+ * Complete registration entry for an API in the unified registry.
+ *
+ * @example REST API Entry
+ * ```json
+ * {
+ *   "id": "customer_api",
+ *   "name": "Customer Management API",
+ *   "type": "rest",
+ *   "version": "v1",
+ *   "basePath": "/api/v1/data/customer",
+ *   "description": "CRUD operations for customer records",
+ *   "endpoints": [...],
+ *   "metadata": {
+ *     "owner": "sales_team",
+ *     "status": "active",
+ *     "tags": ["customer", "crm"]
+ *   }
+ * }
+ * ```
+ *
+ * @example Plugin API Entry
+ * ```json
+ * {
+ *   "id": "payment_webhook",
+ *   "name": "Payment Webhook API",
+ *   "type": "plugin",
+ *   "version": "1.0.0",
+ *   "basePath": "/plugins/payment/webhook",
+ *   "endpoints": [...],
+ *   "metadata": {
+ *     "pluginSource": "payment_gateway_plugin",
+ *     "status": "active"
+ *   }
+ * }
+ * ```
+ */
+exports.ApiRegistryEntrySchema = zod_1.z.object({
+    /** Unique API identifier */
+    id: zod_1.z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Unique API identifier (snake_case)'),
+    /** Human-readable name */
+    name: zod_1.z.string().describe('API display name'),
+    /** API protocol type */
+    type: exports.ApiProtocolType.describe('API protocol type'),
+    /** API version */
+    version: zod_1.z.string().describe('API version (e.g., v1, 2024-01)'),
+    /** Base URL path */
+    basePath: zod_1.z.string().describe('Base URL path for this API'),
+    /** API description */
+    description: zod_1.z.string().optional().describe('API description'),
+    /** Endpoints in this API */
+    endpoints: zod_1.z.array(exports.ApiEndpointRegistrationSchema).describe('Registered endpoints'),
+    /** OpenAPI/GraphQL/OData specific configuration */
+    config: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Protocol-specific configuration'),
+    /** API metadata */
+    metadata: exports.ApiMetadataSchema.optional().describe('Additional metadata'),
+    /** Terms of service URL */
+    termsOfService: zod_1.z.string().url().optional().describe('Terms of service URL'),
+    /** Contact information */
+    contact: zod_1.z.object({
+        name: zod_1.z.string().optional(),
+        url: zod_1.z.string().url().optional(),
+        email: zod_1.z.string().email().optional(),
+    }).optional().describe('Contact information'),
+    /** License information */
+    license: zod_1.z.object({
+        name: zod_1.z.string(),
+        url: zod_1.z.string().url().optional(),
+    }).optional().describe('License information'),
+});
+// ==========================================
+// API Registry
+// ==========================================
+/**
+ * Route Conflict Resolution Strategy
+ *
+ * Defines how to handle conflicts when multiple endpoints register
+ * the same or overlapping URL patterns.
+ */
+exports.ConflictResolutionStrategy = zod_1.z.enum([
+    'error', // Throw error on conflict (safest, default)
+    'priority', // Use priority field to resolve (highest priority wins)
+    'first-wins', // First registered endpoint wins
+    'last-wins', // Last registered endpoint wins (override mode)
+]);
+/**
+ * API Registry Schema
+ *
+ * Central registry containing all registered APIs.
+ *
+ * **Enhancement: Route Conflict Detection**
+ * - `conflictResolution`: Strategy for handling route conflicts
+ * - Prevents silent overwrites and unexpected routing behavior
+ *
+ * @example
+ * ```json
+ * {
+ *   "version": "1.0.0",
+ *   "conflictResolution": "priority",
+ *   "apis": [
+ *     { "id": "customer_api", "type": "rest", ... },
+ *     { "id": "graphql_api", "type": "graphql", ... },
+ *     { "id": "file_upload_api", "type": "file", ... }
+ *   ],
+ *   "totalApis": 3,
+ *   "totalEndpoints": 47
+ * }
+ * ```
+ *
+ * @example Priority-based conflict resolution
+ * ```json
+ * {
+ *   "conflictResolution": "priority",
+ *   "apis": [
+ *     {
+ *       "id": "core_api",
+ *       "endpoints": [
+ *         {
+ *           "path": "/api/v1/data/:object",
+ *           "priority": 950
+ *         }
+ *       ]
+ *     },
+ *     {
+ *       "id": "plugin_api",
+ *       "endpoints": [
+ *         {
+ *           "path": "/api/v1/data/custom",
+ *           "priority": 300
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+exports.ApiRegistrySchema = zod_1.z.object({
+    /** Registry version */
+    version: zod_1.z.string().describe('Registry version'),
+    /**
+     * Conflict Resolution Strategy
+     *
+     * Defines how to handle route conflicts when multiple endpoints
+     * register the same or overlapping URL patterns.
+     *
+     * **Strategies:**
+     * - `error`: Throw error on conflict (safest, prevents silent overwrites)
+     * - `priority`: Use endpoint priority field (highest priority wins)
+     * - `first-wins`: First registered endpoint wins (stable, predictable)
+     * - `last-wins`: Last registered endpoint wins (allows overrides)
+     *
+     * **Default:** `error`
+     *
+     * **Best Practices:**
+     * - Use `error` in production to catch configuration issues
+     * - Use `priority` when mixing core and plugin APIs
+     * - Use `last-wins` for development/testing overrides
+     *
+     * @example Prevent accidental conflicts
+     * ```json
+     * {
+     *   "conflictResolution": "error"
+     * }
+     * ```
+     *
+     * @example Allow plugin overrides with priority
+     * ```json
+     * {
+     *   "conflictResolution": "priority"
+     * }
+     * ```
+     */
+    conflictResolution: exports.ConflictResolutionStrategy.optional().default('error')
+        .describe('Strategy for handling route conflicts'),
+    /** Registered APIs */
+    apis: zod_1.z.array(exports.ApiRegistryEntrySchema).describe('All registered APIs'),
+    /** Total API count */
+    totalApis: zod_1.z.number().int().describe('Total number of registered APIs'),
+    /** Total endpoint count across all APIs */
+    totalEndpoints: zod_1.z.number().int().describe('Total number of endpoints'),
+    /** APIs grouped by type */
+    byType: zod_1.z.record(exports.ApiProtocolType, zod_1.z.array(exports.ApiRegistryEntrySchema)).optional()
+        .describe('APIs grouped by protocol type'),
+    /** APIs grouped by status */
+    byStatus: zod_1.z.record(zod_1.z.string(), zod_1.z.array(exports.ApiRegistryEntrySchema)).optional()
+        .describe('APIs grouped by status'),
+    /** Last updated timestamp */
+    updatedAt: zod_1.z.string().datetime().optional().describe('Last registry update time'),
+});
+// ==========================================
+// API Discovery & Query
+// ==========================================
+/**
+ * API Discovery Query Schema
+ *
+ * Query parameters for discovering/filtering APIs in the registry.
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "rest",
+ *   "tags": ["customer"],
+ *   "status": "active"
+ * }
+ * ```
+ */
+exports.ApiDiscoveryQuerySchema = zod_1.z.object({
+    /** Filter by API type */
+    type: exports.ApiProtocolType.optional().describe('Filter by API protocol type'),
+    /** Filter by tags */
+    tags: zod_1.z.array(zod_1.z.string()).optional().describe('Filter by tags (ANY match)'),
+    /** Filter by status */
+    status: zod_1.z.enum(['active', 'deprecated', 'experimental', 'beta']).optional()
+        .describe('Filter by lifecycle status'),
+    /** Filter by plugin source */
+    pluginSource: zod_1.z.string().optional().describe('Filter by plugin name'),
+    /** Search in name/description */
+    search: zod_1.z.string().optional().describe('Full-text search in name/description'),
+    /** Filter by version */
+    version: zod_1.z.string().optional().describe('Filter by specific version'),
+});
+/**
+ * API Discovery Response Schema
+ *
+ * Response for API discovery queries.
+ */
+exports.ApiDiscoveryResponseSchema = zod_1.z.object({
+    /** Matching APIs */
+    apis: zod_1.z.array(exports.ApiRegistryEntrySchema).describe('Matching API entries'),
+    /** Total matches */
+    total: zod_1.z.number().int().describe('Total matching APIs'),
+    /** Applied filters */
+    filters: exports.ApiDiscoveryQuerySchema.optional().describe('Applied query filters'),
+});
+// ==========================================
+// Helper Functions
+// ==========================================
+/**
+ * Helper to create API endpoint registration
+ */
+exports.ApiEndpointRegistration = Object.assign(exports.ApiEndpointRegistrationSchema, {
+    create: (config) => config,
+});
+/**
+ * Helper to create API registry entry
+ */
+exports.ApiRegistryEntry = Object.assign(exports.ApiRegistryEntrySchema, {
+    create: (config) => config,
+});
+/**
+ * Helper to create API registry
+ */
+exports.ApiRegistry = Object.assign(exports.ApiRegistrySchema, {
+    create: (config) => config,
+});