@aifabrix/builder 2.11.0 → 2.21.0

package/lib/api/index.js

@@ -0,0 +1,236 @@
+/**
+ * @fileoverview Centralized API client for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { makeApiCall, authenticatedApiCall } = require('../utils/api');
+
+/**
+ * API Client class for making typed API calls
+ * Wraps existing makeApiCall and authenticatedApiCall utilities
+ * @class ApiClient
+ */
+class ApiClient {
+  /**
+   * Create an API client instance
+   * @param {string} baseUrl - Base URL for the API (controller URL)
+   * @param {Object} [authConfig] - Authentication configuration
+   * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-credentials' | 'client-token')
+   * @param {string} [authConfig.token] - Bearer token
+   * @param {string} [authConfig.clientId] - Client ID
+   * @param {string} [authConfig.clientSecret] - Client secret
+   */
+  constructor(baseUrl, authConfig = {}) {
+    if (!baseUrl || typeof baseUrl !== 'string') {
+      throw new Error('baseUrl is required and must be a string');
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
+    this.authConfig = authConfig;
+  }
+
+  /**
+   * Build full URL from endpoint path
+   * @private
+   * @param {string} endpoint - API endpoint path (e.g., '/api/v1/auth/token')
+   * @returns {string} Full URL
+   */
+  _buildUrl(endpoint) {
+    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    return `${this.baseUrl}${path}`;
+  }
+
+  /**
+   * Build request headers with authentication
+   * @private
+   * @param {Object} [additionalHeaders] - Additional headers to include
+   * @returns {Object} Request headers
+   */
+  _buildHeaders(additionalHeaders = {}) {
+    const headers = {
+      'Content-Type': 'application/json',
+      ...additionalHeaders
+    };
+
+    // Add authentication headers based on authConfig
+    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+      if (this.authConfig.token) {
+        headers['Authorization'] = `Bearer ${this.authConfig.token}`;
+      }
+    } else if (this.authConfig.type === 'client-credentials') {
+      if (this.authConfig.clientId) {
+        headers['x-client-id'] = this.authConfig.clientId;
+      }
+      if (this.authConfig.clientSecret) {
+        headers['x-client-secret'] = this.authConfig.clientSecret;
+      }
+    }
+
+    return headers;
+  }
+
+  /**
+   * Make a GET request
+   * @async
+   * @param {string} endpoint - API endpoint path
+   * @param {Object} [options] - Request options
+   * @param {Object} [options.headers] - Additional headers
+   * @param {Object} [options.params] - Query parameters (will be converted to query string)
+   * @returns {Promise<Object>} API response
+   */
+  async get(endpoint, options = {}) {
+    let url = this._buildUrl(endpoint);
+    const headers = this._buildHeaders(options.headers);
+
+    // Add query parameters if provided
+    if (options.params) {
+      const params = new URLSearchParams();
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          params.append(key, String(value));
+        }
+      });
+      const queryString = params.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+
+    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+      return await authenticatedApiCall(url, { method: 'GET', headers }, this.authConfig.token);
+    }
+
+    return await makeApiCall(url, { method: 'GET', headers });
+  }
+
+  /**
+   * Make a POST request
+   * @async
+   * @param {string} endpoint - API endpoint path
+   * @param {Object} [options] - Request options
+   * @param {Object} [options.body] - Request body (will be JSON stringified)
+   * @param {Object} [options.headers] - Additional headers
+   * @param {Object} [options.params] - Query parameters (will be converted to query string)
+   * @returns {Promise<Object>} API response
+   */
+  async post(endpoint, options = {}) {
+    let url = this._buildUrl(endpoint);
+    const headers = this._buildHeaders(options.headers);
+
+    // Add query parameters if provided
+    if (options.params) {
+      const params = new URLSearchParams();
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          params.append(key, String(value));
+        }
+      });
+      const queryString = params.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+
+    const requestOptions = {
+      method: 'POST',
+      headers
+    };
+
+    if (options.body) {
+      requestOptions.body = JSON.stringify(options.body);
+    }
+
+    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+      return await authenticatedApiCall(url, requestOptions, this.authConfig.token);
+    }
+
+    return await makeApiCall(url, requestOptions);
+  }
+
+  /**
+   * Make a PATCH request
+   * @async
+   * @param {string} endpoint - API endpoint path
+   * @param {Object} [options] - Request options
+   * @param {Object} [options.body] - Request body (will be JSON stringified)
+   * @param {Object} [options.headers] - Additional headers
+   * @returns {Promise<Object>} API response
+   */
+  async patch(endpoint, options = {}) {
+    const url = this._buildUrl(endpoint);
+    const headers = this._buildHeaders(options.headers);
+
+    const requestOptions = {
+      method: 'PATCH',
+      headers
+    };
+
+    if (options.body) {
+      requestOptions.body = JSON.stringify(options.body);
+    }
+
+    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+      return await authenticatedApiCall(url, requestOptions, this.authConfig.token);
+    }
+
+    return await makeApiCall(url, requestOptions);
+  }
+
+  /**
+   * Make a PUT request
+   * @async
+   * @param {string} endpoint - API endpoint path
+   * @param {Object} [options] - Request options
+   * @param {Object} [options.body] - Request body (will be JSON stringified)
+   * @param {Object} [options.headers] - Additional headers
+   * @returns {Promise<Object>} API response
+   */
+  async put(endpoint, options = {}) {
+    const url = this._buildUrl(endpoint);
+    const headers = this._buildHeaders(options.headers);
+
+    const requestOptions = {
+      method: 'PUT',
+      headers
+    };
+
+    if (options.body) {
+      requestOptions.body = JSON.stringify(options.body);
+    }
+
+    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+      return await authenticatedApiCall(url, requestOptions, this.authConfig.token);
+    }
+
+    return await makeApiCall(url, requestOptions);
+  }
+
+  /**
+   * Make a DELETE request
+   * @async
+   * @param {string} endpoint - API endpoint path
+   * @param {Object} [options] - Request options
+   * @param {Object} [options.headers] - Additional headers
+   * @returns {Promise<Object>} API response
+   */
+  async delete(endpoint, options = {}) {
+    const url = this._buildUrl(endpoint);
+    const headers = this._buildHeaders(options.headers);
+
+    const requestOptions = {
+      method: 'DELETE',
+      headers
+    };
+
+    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+      return await authenticatedApiCall(url, requestOptions, this.authConfig.token);
+    }
+
+    return await makeApiCall(url, requestOptions);
+  }
+}
+
+module.exports = {
+  ApiClient
+};
+

package/lib/api/pipeline.api.js

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Pipeline API functions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { ApiClient } = require('./index');
+
+/**
+ * Validate deployment configuration
+ * POST /api/v1/pipeline/{envKey}/validate
+ * @async
+ * @function validatePipeline
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {Object} authConfig - Authentication configuration (supports client credentials)
+ * @param {Object} validationData - Validation data
+ * @param {string} validationData.clientId - Client ID for application authentication
+ * @param {string} validationData.repositoryUrl - Repository URL for validation
+ * @param {Object} validationData.applicationConfig - Application configuration
+ * @returns {Promise<Object>} Validation response with validateToken and ACR credentials
+ * @throws {Error} If validation fails
+ */
+async function validatePipeline(controllerUrl, envKey, authConfig, validationData) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(`/api/v1/pipeline/${envKey}/validate`, {
+    body: validationData
+  });
+}
+
+/**
+ * Deploy application using validateToken
+ * POST /api/v1/pipeline/{envKey}/deploy
+ * @async
+ * @function deployPipeline
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {Object} authConfig - Authentication configuration (supports client credentials)
+ * @param {Object} deployData - Deployment data
+ * @param {string} deployData.validateToken - One-time deployment token from /validate endpoint
+ * @param {string} deployData.imageTag - Container image tag to deploy
+ * @returns {Promise<Object>} Deployment response
+ * @throws {Error} If deployment fails
+ */
+async function deployPipeline(controllerUrl, envKey, authConfig, deployData) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(`/api/v1/pipeline/${envKey}/deploy`, {
+    body: deployData
+  });
+}
+
+/**
+ * Get deployment status for CI/CD
+ * GET /api/v1/pipeline/{envKey}/deployments/{deploymentId}
+ * @async
+ * @function getPipelineDeployment
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {string} deploymentId - Deployment ID
+ * @param {Object} authConfig - Authentication configuration (supports client credentials)
+ * @returns {Promise<Object>} Minimal deployment status response
+ * @throws {Error} If request fails
+ */
+async function getPipelineDeployment(controllerUrl, envKey, deploymentId, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`/api/v1/pipeline/${envKey}/deployments/${deploymentId}`);
+}
+
+/**
+ * Pipeline health check
+ * GET /api/v1/pipeline/{envKey}/health
+ * @async
+ * @function getPipelineHealth
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @returns {Promise<Object>} Health check response (public endpoint, no auth required)
+ * @throws {Error} If request fails
+ */
+async function getPipelineHealth(controllerUrl, envKey) {
+  const client = new ApiClient(controllerUrl);
+  return await client.get(`/api/v1/pipeline/${envKey}/health`);
+}
+
+/**
+ * Publish datasource via dataplane pipeline endpoint
+ * POST /api/v1/pipeline/{systemKey}/publish
+ * @async
+ * @function publishDatasourceViaPipeline
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} systemKey - System key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} datasourceConfig - Datasource configuration to publish
+ * @returns {Promise<Object>} Publish response
+ * @throws {Error} If publish fails
+ */
+async function publishDatasourceViaPipeline(dataplaneUrl, systemKey, authConfig, datasourceConfig) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.post(`/api/v1/pipeline/${systemKey}/publish`, {
+    body: datasourceConfig
+  });
+}
+
+/**
+ * Test datasource via dataplane pipeline endpoint
+ * POST /api/v1/pipeline/{systemKey}/{datasourceKey}/test
+ * @async
+ * @function testDatasourceViaPipeline
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} systemKey - System key
+ * @param {string} datasourceKey - Datasource key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} testData - Test data
+ * @param {Object} testData.payloadTemplate - Test payload template
+ * @param {Object} [options] - Request options
+ * @param {number} [options.timeout] - Request timeout in milliseconds
+ * @returns {Promise<Object>} Test response
+ * @throws {Error} If test fails
+ */
+async function testDatasourceViaPipeline(dataplaneUrl, systemKey, datasourceKey, authConfig, testData, options = {}) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  const requestOptions = {
+    body: testData
+  };
+  // Pass through timeout if provided (will be handled by underlying fetch implementation)
+  if (options.timeout) {
+    requestOptions.timeout = options.timeout;
+  }
+  return await client.post(`/api/v1/pipeline/${systemKey}/${datasourceKey}/test`, requestOptions);
+}
+
+/**
+ * Deploy external system via dataplane pipeline endpoint
+ * POST /api/v1/pipeline/deploy
+ * @async
+ * @function deployExternalSystemViaPipeline
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} systemConfig - External system configuration to deploy
+ * @returns {Promise<Object>} Deployment response
+ * @throws {Error} If deployment fails
+ */
+async function deployExternalSystemViaPipeline(dataplaneUrl, authConfig, systemConfig) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.post('/api/v1/pipeline/deploy', {
+    body: systemConfig
+  });
+}
+
+/**
+ * Deploy datasource via dataplane pipeline endpoint
+ * POST /api/v1/pipeline/{systemKey}/deploy
+ * @async
+ * @function deployDatasourceViaPipeline
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} systemKey - System key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} datasourceConfig - Datasource configuration to deploy
+ * @returns {Promise<Object>} Deployment response
+ * @throws {Error} If deployment fails
+ */
+async function deployDatasourceViaPipeline(dataplaneUrl, systemKey, authConfig, datasourceConfig) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.post(`/api/v1/pipeline/${systemKey}/deploy`, {
+    body: datasourceConfig
+  });
+}
+
+/**
+ * Upload application configuration via dataplane pipeline endpoint
+ * POST /api/v1/pipeline/upload
+ * @async
+ * @function uploadApplicationViaPipeline
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} applicationSchema - Application schema configuration
+ * @returns {Promise<Object>} Upload response with uploadId
+ * @throws {Error} If upload fails
+ */
+async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, applicationSchema) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.post('/api/v1/pipeline/upload', {
+    body: applicationSchema
+  });
+}
+
+/**
+ * Validate upload via dataplane pipeline endpoint
+ * POST /api/v1/pipeline/upload/{uploadId}/validate
+ * @async
+ * @function validateUploadViaPipeline
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} uploadId - Upload ID
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<Object>} Validation response with changes and summary
+ * @throws {Error} If validation fails
+ */
+async function validateUploadViaPipeline(dataplaneUrl, uploadId, authConfig) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.post(`/api/v1/pipeline/upload/${uploadId}/validate`);
+}
+
+/**
+ * Publish upload via dataplane pipeline endpoint
+ * POST /api/v1/pipeline/upload/{uploadId}/publish
+ * @async
+ * @function publishUploadViaPipeline
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} uploadId - Upload ID
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [options] - Publish options
+ * @param {boolean} [options.generateMcpContract] - Generate MCP contract (default: true)
+ * @returns {Promise<Object>} Publish response
+ * @throws {Error} If publish fails
+ */
+async function publishUploadViaPipeline(dataplaneUrl, uploadId, authConfig, options = {}) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  const generateMcpContract = options.generateMcpContract !== false; // Default to true
+  return await client.post(`/api/v1/pipeline/upload/${uploadId}/publish?generateMcpContract=${generateMcpContract}`);
+}
+
+module.exports = {
+  validatePipeline,
+  deployPipeline,
+  getPipelineDeployment,
+  getPipelineHealth,
+  publishDatasourceViaPipeline,
+  testDatasourceViaPipeline,
+  deployExternalSystemViaPipeline,
+  deployDatasourceViaPipeline,
+  uploadApplicationViaPipeline,
+  validateUploadViaPipeline,
+  publishUploadViaPipeline
+};
+

package/lib/api/types/applications.types.js

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Applications API type definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Pagination metadata
+ * @typedef {Object} PaginationMeta
+ * @property {number} page - Current page number
+ * @property {number} pageSize - Number of items per page
+ * @property {number} total - Total number of items
+ * @property {number} totalPages - Total number of pages
+ */
+
+/**
+ * Pagination links
+ * @typedef {Object} PaginationLinks
+ * @property {string} self - Current page URL
+ * @property {string} first - First page URL
+ * @property {string} last - Last page URL
+ * @property {string|null} prev - Previous page URL (null if on first page)
+ * @property {string|null} next - Next page URL (null if on last page)
+ */
+
+/**
+ * Application configuration (references application-config.schema.yaml)
+ * @typedef {Object} ApplicationConfig
+ * @property {string} key - Unique application identifier
+ * @property {string} displayName - Human-readable application name
+ * @property {string} description - Application description
+ * @property {string} type - Azure application type ('webapp' | 'functionapp' | 'api' | 'service' | 'external')
+ * @property {string} deploymentKey - SHA256 hash of deployment manifest
+ * @property {string} [image] - Container image reference
+ * @property {string} [registryMode] - Registry mode ('acr' | 'external' | 'public')
+ * @property {number} [port] - Application port number
+ * @property {Object} [externalIntegration] - External systems & data sources configuration
+ * @property {Object} [system] - Inline external system configuration
+ * @property {Object[]} [dataSources] - Inline external data source configurations
+ * @property {boolean} [requiresDatabase] - Whether application requires database
+ * @property {Object[]} [databases] - Database configurations
+ * @property {boolean} [requiresRedis] - Whether application requires Redis
+ * @property {boolean} [requiresStorage] - Whether application requires storage
+ * @property {Object[]} [configuration] - Core application configuration
+ * @property {Object[]} [conditionalConfiguration] - Conditional configuration
+ * @property {Object} [healthCheck] - Health check configuration
+ * @property {Object} [frontDoorRouting] - Front Door routing configuration
+ * @property {Object} [authentication] - Authentication configuration
+ * @property {Object[]} [roles] - Application roles
+ * @property {Object[]} [permissions] - Application permissions
+ * @property {Object} [repository] - Repository deployment configuration
+ * @property {string} [startupCommand] - Application startup command
+ * @property {Object} [runtimeVersion] - Runtime version configuration
+ * @property {Object} [scaling] - Application scaling configuration
+ * @property {Object} [build] - Build and local development configuration
+ * @property {Object} [deployment] - Deployment configuration for pipeline API
+ */
+
+/**
+ * Application entity
+ * @typedef {Object} Application
+ * @property {string} id - Application ID
+ * @property {string} key - Application key (unique identifier)
+ * @property {string} displayName - Display name
+ * @property {string|null} description - Application description
+ * @property {string|null} url - Application URL
+ * @property {ApplicationConfig} configuration - Application configuration
+ * @property {string} status - Application status ('healthy' | 'degraded' | 'deploying' | 'error' | 'maintenance')
+ * @property {string} createdAt - Creation timestamp (ISO 8601)
+ * @property {string} updatedAt - Update timestamp (ISO 8601)
+ */
+
+/**
+ * List applications request options
+ * @typedef {Object} ListApplicationsRequest
+ * @property {number} [page] - Page number (default: 1)
+ * @property {number} [pageSize] - Items per page (default: 10)
+ * @property {string} [sort] - Sort parameter
+ * @property {string} [filter] - Filter parameter
+ * @property {string} [search] - Search term to match across key, displayName, name, and description fields
+ */
+
+/**
+ * List applications response
+ * @typedef {Object} ListApplicationsResponse
+ * @property {Application[]} data - Array of template applications
+ * @property {PaginationMeta} meta - Pagination metadata
+ * @property {PaginationLinks} links - Pagination links
+ */
+
+/**
+ * Create application request
+ * @typedef {Object} CreateApplicationRequest
+ * @property {string} key - Application key (lowercase, numbers, hyphens only)
+ * @property {string} displayName - Display name
+ * @property {string} [description] - Application description
+ * @property {string} [url] - Application URL
+ * @property {ApplicationConfig} configuration - Application configuration
+ */
+
+/**
+ * Create application response
+ * @typedef {Object} CreateApplicationResponse
+ * @property {Application} data - Created template application
+ */
+
+/**
+ * Get application response
+ * @typedef {Object} GetApplicationResponse
+ * @property {Application} data - Template application details
+ */
+
+/**
+ * Update application request
+ * @typedef {Object} UpdateApplicationRequest
+ * @property {string} [displayName] - Display name
+ * @property {string} [description] - Application description
+ * @property {string} [url] - Application URL
+ * @property {ApplicationConfig} [configuration] - Application configuration
+ * @property {string} [status] - Application status ('healthy' | 'degraded' | 'deploying' | 'error' | 'maintenance')
+ */
+
+/**
+ * Update application response
+ * @typedef {Object} UpdateApplicationResponse
+ * @property {Application} data - Updated template application
+ */
+
+/**
+ * Delete application response
+ * @typedef {Object} DeleteApplicationResponse
+ * @property {null} data - Always null for DELETE operations
+ */
+
+module.exports = {};
+