@aifabrix/builder 2.11.0 → 2.21.0

package/lib/api/types/auth.types.js

@@ -0,0 +1,218 @@
+/**
+ * @fileoverview Authentication API type definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Authentication configuration
+ * @typedef {Object} AuthConfig
+ * @property {string} type - Authentication type ('bearer' | 'client-credentials' | 'client-token')
+ * @property {string} [token] - Bearer token (for type='bearer' or type='client-token')
+ * @property {string} [clientId] - Client ID (for type='client-credentials')
+ * @property {string} [clientSecret] - Client secret (for type='client-credentials')
+ */
+
+/**
+ * Standard API response wrapper
+ * @typedef {Object} ApiResponse
+ * @property {boolean} success - Request success flag
+ * @property {*} [data] - Response data
+ * @property {string} [error] - Error message
+ * @property {Object} [errorData] - Error data object
+ * @property {string} [errorType] - Error type
+ * @property {string} [formattedError] - Formatted error message
+ * @property {number} [status] - HTTP status code
+ * @property {string} [timestamp] - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Get token request (x-client-token generation)
+ * @typedef {Object} GetTokenRequest
+ * @property {string} clientId - Client ID (via x-client-id header)
+ * @property {string} clientSecret - Client secret (via x-client-secret header)
+ */
+
+/**
+ * Get token response (x-client-token generation)
+ * @typedef {Object} GetTokenResponse
+ * @property {boolean} success - Request success flag
+ * @property {string} token - Generated x-client-token
+ * @property {number} expiresIn - Token expiry time in seconds
+ * @property {string} expiresAt - Token expiry timestamp (ISO 8601)
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Get client token response (frontend token)
+ * @typedef {Object} GetClientTokenResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - Token data
+ * @property {string} data.token - Generated x-client-token
+ * @property {number} data.expiresIn - Token expiry time in seconds
+ * @property {string} data.expiresAt - Token expiry timestamp (ISO 8601)
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Get auth user response
+ * @typedef {Object} GetAuthUserResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - User data
+ * @property {Object} data.user - User information
+ * @property {string} data.user.id - User ID
+ * @property {string} data.user.username - Username
+ * @property {string} data.user.email - Email address
+ * @property {boolean} data.authenticated - Authentication status
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Get auth login request
+ * @typedef {Object} GetAuthLoginRequest
+ * @property {string} redirect - Redirect URI for OAuth2 callback
+ * @property {string} [state] - State parameter for CSRF protection
+ */
+
+/**
+ * Get auth login response
+ * @typedef {Object} GetAuthLoginResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - Login data
+ * @property {string} data.loginUrl - Login URL for OAuth2 authorization flow
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Initiate device code flow request
+ * @typedef {Object} InitiateDeviceCodeRequest
+ * @property {string} [environment] - Environment key (query or body)
+ * @property {string} [scope] - OAuth2 scope string (defaults to 'openid profile email')
+ */
+
+/**
+ * Device code response
+ * @typedef {Object} DeviceCodeResponse
+ * @property {string} deviceCode - Device code for polling token endpoint
+ * @property {string} userCode - User code to enter at verification URI
+ * @property {string} verificationUri - URI for user to visit and enter user code
+ * @property {string} [verificationUriComplete] - Complete URI with user code pre-filled
+ * @property {number} expiresIn - Device code expiration time in seconds (typically 600)
+ * @property {number} interval - Polling interval in seconds (typically 5)
+ */
+
+/**
+ * Initiate device code flow response
+ * @typedef {Object} InitiateDeviceCodeResponse
+ * @property {boolean} success - Request success flag
+ * @property {DeviceCodeResponse} data - Device code information
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Poll device code token request
+ * @typedef {Object} PollDeviceCodeTokenRequest
+ * @property {string} deviceCode - Device code from initiate device code flow
+ */
+
+/**
+ * Device code token response
+ * @typedef {Object} DeviceCodeTokenResponse
+ * @property {string} accessToken - JWT access token from Keycloak
+ * @property {string} [refreshToken] - Refresh token for obtaining new access tokens
+ * @property {number} expiresIn - Access token expiration time in seconds
+ */
+
+/**
+ * Poll device code token response
+ * @typedef {Object} PollDeviceCodeTokenResponse
+ * @property {boolean} success - Request success flag
+ * @property {DeviceCodeTokenResponse} [data] - Token data (on success)
+ * @property {string} [error] - Error code (on pending: 'authorization_pending' | 'slow_down')
+ * @property {string} [errorDescription] - Error description
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Refresh device token request
+ * @typedef {Object} RefreshDeviceTokenRequest
+ * @property {string} refreshToken - Refresh token obtained from device code token flow
+ */
+
+/**
+ * Refresh device token response
+ * @typedef {Object} RefreshDeviceTokenResponse
+ * @property {boolean} success - Request success flag
+ * @property {DeviceCodeTokenResponse} data - New token data
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Refresh user token request
+ * @typedef {Object} RefreshUserTokenRequest
+ * @property {string} refreshToken - Refresh token obtained from OAuth callback flow
+ */
+
+/**
+ * Refresh user token response
+ * @typedef {Object} RefreshUserTokenResponse
+ * @property {boolean} success - Request success flag
+ * @property {DeviceCodeTokenResponse} data - New token data
+ * @property {string} [message] - Response message
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Validate token request
+ * @typedef {Object} ValidateTokenRequest
+ * @property {string} token - JWT token to validate
+ * @property {string} [environment] - Optional environment key (overrides x-client-token context)
+ * @property {string} [application] - Optional application key (overrides x-client-token context)
+ */
+
+/**
+ * Validate token response
+ * @typedef {Object} ValidateTokenResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - Validation data
+ * @property {boolean} data.authenticated - Authentication status
+ * @property {Object} [data.user] - User information
+ * @property {string} [data.user.id] - User ID
+ * @property {string} [data.user.username] - Username
+ * @property {string} [data.user.email] - Email address
+ * @property {string} [data.expiresAt] - Token expiration timestamp (ISO 8601)
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Get auth roles response
+ * @typedef {Object} GetAuthRolesResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - Roles data
+ * @property {string[]} data.roles - Array of role names
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Get auth permissions response
+ * @typedef {Object} GetAuthPermissionsResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - Permissions data
+ * @property {string[]} data.permissions - Array of permission names
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Get auth login diagnostics response
+ * @typedef {Object} GetAuthLoginDiagnosticsResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - Diagnostic data
+ * @property {Object} data.database - Database health status
+ * @property {Object} data.controller - Controller status
+ * @property {Object} data.environment - Environment status
+ * @property {Object} data.keycloak - Keycloak configuration status
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+module.exports = {};
+

package/lib/api/types/datasources.types.js

@@ -0,0 +1,272 @@
+/**
+ * @fileoverview Datasources API type definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+// Pagination types - shared with other API modules
+
+/**
+ * External data source response
+ * @typedef {Object} ExternalDataSourceResponse
+ * @property {string} id - Datasource ID
+ * @property {string} key - Datasource key (unique identifier)
+ * @property {string} displayName - Display name
+ * @property {string|null} description - Datasource description
+ * @property {string} externalSystemId - External system ID
+ * @property {string} resourceType - Resource type
+ * @property {Object} fieldMappings - Field mappings configuration
+ * @property {string} status - Status ('draft' | 'published' | 'archived')
+ * @property {boolean} isActive - Whether datasource is active
+ * @property {string} createdAt - Creation timestamp (ISO 8601)
+ * @property {string} updatedAt - Update timestamp (ISO 8601)
+ */
+
+/**
+ * External data source create request
+ * @typedef {Object} ExternalDataSourceCreate
+ * @property {string} key - Datasource key
+ * @property {string} displayName - Display name
+ * @property {string} [description] - Description
+ * @property {string} externalSystemId - External system ID
+ * @property {string} resourceType - Resource type
+ * @property {Object} [fieldMappings] - Field mappings
+ * @property {Object} [configuration] - Configuration
+ */
+
+/**
+ * External data source update request
+ * @typedef {Object} ExternalDataSourceUpdate
+ * @property {string} [displayName] - Display name
+ * @property {string} [description] - Description
+ * @property {Object} [fieldMappings] - Field mappings
+ * @property {Object} [configuration] - Configuration
+ * @property {boolean} [isActive] - Active status
+ */
+
+/**
+ * External data source config response (with MCP contract)
+ * @typedef {Object} ExternalDataSourceConfigResponse
+ * @property {ExternalDataSourceResponse} datasource - Datasource configuration
+ * @property {Object} [mcpContract] - MCP contract if generated
+ */
+
+/**
+ * List datasources request options
+ * @typedef {Object} ListDatasourcesRequest
+ * @property {number} [page] - Page number (default: 1)
+ * @property {number} [pageSize] - Items per page (default: 20)
+ * @property {string} [sort] - Sort parameter
+ * @property {string} [filter] - Filter parameter
+ * @property {string} [search] - Search term
+ */
+
+/**
+ * List datasources response
+ * @typedef {Object} ListDatasourcesResponse
+ * @property {ExternalDataSourceResponse[]} items - Array of datasources
+ * @property {PaginationMeta} meta - Pagination metadata
+ * @property {PaginationLinks} links - Pagination links
+ */
+
+/** @typedef {ExternalDataSourceCreate} CreateDatasourceRequest */
+/** @typedef {Object} CreateDatasourceResponse @property {ExternalDataSourceResponse} data */
+/** @typedef {Object} GetDatasourceResponse @property {ExternalDataSourceResponse} data */
+/** @typedef {ExternalDataSourceUpdate} UpdateDatasourceRequest */
+/** @typedef {Object} UpdateDatasourceResponse @property {ExternalDataSourceResponse} data */
+/** @typedef {Object} DeleteDatasourceResponse @property {null} data */
+
+/**
+ * Get datasource config response
+ * @typedef {Object} GetDatasourceConfigResponse
+ * @property {ExternalDataSourceConfigResponse} data - Full config with MCP contract
+ */
+
+/**
+ * Publish datasource request
+ * @typedef {Object} PublishDatasourceRequest
+ * @property {boolean} [generateMcpContract] - Whether to generate MCP contract
+ */
+
+/**
+ * Publish datasource response
+ * @typedef {Object} PublishDatasourceResponse
+ * @property {ExternalDataSourceResponse} data - Published datasource
+ */
+
+/**
+ * Rollback datasource request
+ * @typedef {Object} RollbackDatasourceRequest
+ * @property {number} version - Version to rollback to
+ */
+
+/**
+ * Rollback datasource response
+ * @typedef {Object} RollbackDatasourceResponse
+ * @property {ExternalDataSourceResponse} data - Rolled back datasource
+ */
+
+/**
+ * Test datasource request
+ * @typedef {Object} TestDatasourceRequest
+ * @property {Object} [payloadTemplate] - Payload template for testing
+ */
+
+/**
+ * Test datasource response
+ * @typedef {Object} TestDatasourceResponse
+ * @property {boolean} success - Test success flag
+ * @property {Object} [data] - Test result data
+ * @property {string} [message] - Test message
+ */
+
+/** @typedef {Object} ListDatasourceOpenAPIEndpointsRequest @property {number} [page] @property {number} [pageSize] @property {string} [sort] @property {string} [filter] */
+/** @typedef {Object} ListDatasourceOpenAPIEndpointsResponse @property {Object[]} items @property {Object} meta @property {Object} links */
+
+/**
+ * CIP execution log response
+ * @typedef {Object} CIPExecutionLogResponse
+ * @property {string} id - Execution ID
+ * @property {string} sourceId - Source ID
+ * @property {string} status - Execution status
+ * @property {Object} [result] - Execution result
+ * @property {string} [error] - Error message if failed
+ * @property {string} createdAt - Creation timestamp
+ */
+
+/** @typedef {Object} ListExecutionLogsRequest @property {number} [page] @property {number} [pageSize] @property {string} [sort] @property {string} [filter] */
+/** @typedef {Object} ListExecutionLogsResponse @property {CIPExecutionLogResponse[]} items @property {Object} meta @property {Object} links */
+/** @typedef {Object} GetExecutionLogResponse @property {CIPExecutionLogResponse} data */
+
+/**
+ * Bulk operation request
+ * @typedef {Object} BulkOperationRequest
+ * @property {string} operation - Operation type ('sync' | 'update' | 'delete')
+ * @property {Object[]} [records] - Records to process
+ * @property {Object} [options] - Operation options
+ */
+
+/**
+ * Bulk operation response
+ * @typedef {Object} BulkOperationResponse
+ * @property {boolean} success - Operation success flag
+ * @property {number} processed - Number of records processed
+ * @property {Object} [result] - Operation result
+ */
+
+/**
+ * Get datasource status response
+ * @typedef {Object} GetDatasourceStatusResponse
+ * @property {Object} data - Status data
+ * @property {string} data.status - Sync status
+ * @property {string} [data.lastSyncAt] - Last sync timestamp
+ * @property {number} [data.recordCount] - Record count
+ */
+
+/**
+ * External record response
+ * @typedef {Object} ExternalRecordResponse
+ * @property {string} id - Record ID
+ * @property {string} key - Record key
+ * @property {Object} data - Record data
+ * @property {string} createdAt - Creation timestamp
+ * @property {string} updatedAt - Update timestamp
+ */
+
+/** @typedef {Object} ListRecordsRequest @property {number} [page] @property {number} [pageSize] @property {string} [sort] @property {string} [filter] */
+/** @typedef {Object} ListRecordsResponse @property {ExternalRecordResponse[]} items @property {Object} meta @property {Object} links */
+/** @typedef {Object} CreateRecordRequest @property {string} key @property {Object} data */
+/** @typedef {Object} CreateRecordResponse @property {ExternalRecordResponse} data */
+/** @typedef {Object} GetRecordResponse @property {ExternalRecordResponse} data */
+/** @typedef {Object} UpdateRecordRequest @property {Object} data */
+/** @typedef {Object} UpdateRecordResponse @property {ExternalRecordResponse} data */
+/** @typedef {Object} DeleteRecordResponse @property {null} data */
+
+/**
+ * Access grant response
+ * @typedef {Object} AccessGrantResponse
+ * @property {string} id - Grant ID
+ * @property {string} key - Grant key
+ * @property {string} userId - User ID
+ * @property {string} [groupId] - Group ID
+ * @property {Object} permissions - Permissions
+ * @property {string} createdAt - Creation timestamp
+ */
+
+/** @typedef {Object} ListGrantsRequest @property {number} [page] @property {number} [pageSize] @property {string} [sort] @property {string} [filter] */
+/** @typedef {Object} ListGrantsResponse @property {AccessGrantResponse[]} items @property {Object} meta @property {Object} links */
+/** @typedef {Object} CreateGrantRequest @property {string} key @property {string} userId @property {string} [groupId] @property {Object} permissions */
+/** @typedef {Object} CreateGrantResponse @property {AccessGrantResponse} data */
+/** @typedef {Object} GetGrantResponse @property {AccessGrantResponse} data */
+/** @typedef {Object} UpdateGrantRequest @property {Object} [permissions] */
+/** @typedef {Object} UpdateGrantResponse @property {AccessGrantResponse} data */
+/** @typedef {Object} DeleteGrantResponse @property {null} data */
+
+/**
+ * Policy response
+ * @typedef {Object} PolicyResponse
+ * @property {string} id - Policy ID
+ * @property {string} key - Policy key
+ * @property {string} name - Policy name
+ * @property {Object} rules - Policy rules
+ */
+
+/** @typedef {Object} ListPoliciesRequest @property {number} [page] @property {number} [pageSize] @property {string} [sort] @property {string} [filter] */
+/** @typedef {Object} ListPoliciesResponse @property {PolicyResponse[]} items @property {Object} meta @property {Object} links */
+/** @typedef {Object} AttachPolicyRequest @property {string} policyIdOrKey */
+/** @typedef {Object} AttachPolicyResponse @property {PolicyResponse} data */
+/** @typedef {Object} DetachPolicyResponse @property {null} data */
+
+/**
+ * Sync job response
+ * @typedef {Object} ExternalDataSourceSyncResponse
+ * @property {string} id - Sync job ID
+ * @property {string} sourceId - Source ID
+ * @property {string} status - Sync status
+ * @property {Object} [configuration] - Sync configuration
+ * @property {string} [lastRunAt] - Last run timestamp
+ * @property {string} createdAt - Creation timestamp
+ */
+
+/** @typedef {Object} ListSyncJobsRequest @property {number} [page] @property {number} [pageSize] @property {string} [sort] @property {string} [filter] */
+/** @typedef {Object} ListSyncJobsResponse @property {ExternalDataSourceSyncResponse[]} items @property {Object} meta @property {Object} links */
+/** @typedef {Object} CreateSyncJobRequest @property {string} key @property {Object} configuration */
+/** @typedef {Object} CreateSyncJobResponse @property {ExternalDataSourceSyncResponse} data */
+/** @typedef {Object} GetSyncJobResponse @property {ExternalDataSourceSyncResponse} data */
+/** @typedef {Object} UpdateSyncJobRequest @property {Object} [configuration] @property {string} [status] */
+/** @typedef {Object} UpdateSyncJobResponse @property {ExternalDataSourceSyncResponse} data */
+/** @typedef {Object} ExecuteSyncJobResponse @property {boolean} success @property {Object} [result] */
+
+/**
+ * Validate documents request
+ * @typedef {Object} ValidateDocumentsRequest
+ * @property {Object[]} documents - Array of document metadata to validate
+ */
+
+/**
+ * Validate documents response
+ * @typedef {Object} ValidateDocumentsResponse
+ * @property {Object[]} needsBinary - Documents that need binary retrieval
+ * @property {Object[]} needsUpdate - Documents that need update
+ * @property {Object[]} unchanged - Documents that are unchanged
+ */
+
+/**
+ * Bulk documents request
+ * @typedef {Object} BulkDocumentsRequest
+ * @property {Object[]} documents - Array of documents with binary data
+ */
+
+/**
+ * Bulk documents response
+ * @typedef {Object} BulkDocumentsResponse
+ * @property {boolean} success - Operation success flag
+ * @property {number} processed - Number of documents processed
+ * @property {Object} [result] - Operation result
+ */
+
+/** @typedef {Object} ListDocumentsRequest @property {number} [page] @property {number} [pageSize] @property {string} [sort] @property {string} [filter] */
+/** @typedef {Object} ListDocumentsResponse @property {Object[]} items @property {Object} meta @property {Object} links */
+
+module.exports = {};
+

package/lib/api/types/deployments.types.js

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Deployments 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
+ * @property {string} deploymentKey - SHA256 hash of deployment manifest
+ * @property {*} [additionalProperties] - Additional configuration properties
+ */
+
+/**
+ * Deploy application request
+ * @typedef {Object} DeployApplicationRequest
+ * @property {string} applicationKey - Application key to deploy
+ * @property {string} image - Container image path
+ * @property {ApplicationConfig} [configuration] - Additional deployment configuration
+ * @property {boolean} [dryRun] - If true, perform a dry run without actually deploying
+ */
+
+/**
+ * Deploy application response
+ * @typedef {Object} DeployApplicationResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} data - Deployment data
+ * @property {string} data.deploymentId - Deployment ID
+ * @property {string} data.jobId - Job ID
+ * @property {string} data.status - Deployment status
+ * @property {string} data.message - Deployment message
+ * @property {string} timestamp - Response timestamp (ISO 8601)
+ */
+
+/**
+ * Deploy environment request
+ * @typedef {Object} DeployEnvironmentRequest
+ * @property {Object} environmentConfig - Environment configuration
+ * @property {string} environmentConfig.key - Environment key
+ * @property {string} environmentConfig.environment - Environment type ('dev' | 'tst' | 'pro')
+ * @property {string} environmentConfig.preset - Deployment preset size ('eval' | 's' | 'm' | 'l' | 'xl')
+ * @property {string} environmentConfig.serviceName - Service name for resource naming
+ * @property {string} environmentConfig.location - Azure region location
+ * @property {string} [environmentConfig.resourceGroupName] - Optional resource group name override
+ * @property {string} [environmentConfig.subscriptionId] - Optional Azure subscription ID override
+ * @property {Object} [environmentConfig.customDomain] - Custom domain configuration
+ * @property {Object} [environmentConfig.frontDoor] - Front Door configuration
+ * @property {Object} [environmentConfig.networking] - Networking configuration
+ * @property {string[]} [environmentConfig.allowedIPs] - Allowed IP addresses
+ * @property {Object[]} [environmentConfig.infrastructureAccess] - Infrastructure access configuration
+ * @property {boolean} [dryRun] - If true, perform a dry run without actually deploying
+ */
+
+/**
+ * Deploy environment response
+ * @typedef {Object} DeployEnvironmentResponse
+ * @property {Object} data - Deployment data
+ * @property {string} data.deploymentId - Deployment ID
+ * @property {string} data.jobId - Job ID
+ * @property {string} data.status - Deployment status
+ * @property {string} data.message - Deployment message
+ */
+
+/**
+ * List deployments request options
+ * @typedef {Object} ListDeploymentsRequest
+ * @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 deployment fields
+ * @property {string} [status] - Filter by deployment status (legacy parameter)
+ * @property {string} [deploymentType] - Filter by deployment type (legacy parameter)
+ */
+
+/**
+ * Deployment entity
+ * @typedef {Object} Deployment
+ * @property {string} id - Deployment ID
+ * @property {string} deploymentType - Deployment type ('application' | 'infrastructure')
+ * @property {string} targetId - Target ID (application key or environment key)
+ * @property {string} environment - Environment key
+ * @property {string} status - Deployment status
+ * @property {ApplicationConfig} [configuration] - Deployment configuration
+ * @property {boolean} dryRun - Whether this was a dry run
+ * @property {string} createdAt - Creation timestamp (ISO 8601)
+ * @property {string} updatedAt - Update timestamp (ISO 8601)
+ */
+
+/**
+ * List deployments response
+ * @typedef {Object} ListDeploymentsResponse
+ * @property {PaginationMeta} meta - Pagination metadata
+ * @property {Deployment[]} data - Array of deployments
+ * @property {PaginationLinks} links - Pagination links
+ */
+
+/**
+ * Job log entry
+ * @typedef {Object} JobLog
+ * @property {string} id - Log entry ID
+ * @property {string} jobId - Job ID
+ * @property {string} level - Log level ('debug' | 'info' | 'warn' | 'error')
+ * @property {string} message - Log message
+ * @property {string} timestamp - Log timestamp (ISO 8601)
+ * @property {Object} [details] - Additional log details
+ * @property {string|null} [correlationId] - Correlation ID
+ */
+
+/**
+ * Deployment job
+ * @typedef {Object} DeploymentJob
+ * @property {string} id - Job ID
+ * @property {string} jobId - Job identifier
+ * @property {string} jobType - Job type
+ * @property {string} status - Job status
+ * @property {number} progress - Job progress (0-100)
+ * @property {string|null} message - Job message
+ * @property {string|null} error - Job error message
+ * @property {string|null} startedAt - Job start timestamp (ISO 8601)
+ * @property {string|null} completedAt - Job completion timestamp (ISO 8601)
+ * @property {JobLog[]} logs - Job logs
+ */
+
+/**
+ * Deployment with jobs
+ * @typedef {Object} DeploymentWithJobs
+ * @property {string} id - Deployment ID
+ * @property {string} deploymentType - Deployment type
+ * @property {string} targetId - Target ID
+ * @property {string} environment - Environment key
+ * @property {string} status - Deployment status
+ * @property {ApplicationConfig} [configuration] - Deployment configuration
+ * @property {boolean} dryRun - Whether this was a dry run
+ * @property {string} createdAt - Creation timestamp (ISO 8601)
+ * @property {string} updatedAt - Update timestamp (ISO 8601)
+ * @property {DeploymentJob[]} jobs - Array of deployment jobs
+ */
+
+/**
+ * Get deployment response
+ * @typedef {Object} GetDeploymentResponse
+ * @property {DeploymentWithJobs} data - Full deployment record with jobs and logs
+ */
+
+/**
+ * Get deployment logs request options
+ * @typedef {Object} GetDeploymentLogsRequest
+ * @property {string} [jobId] - Filter logs for specific job ID
+ * @property {string} [level] - Filter by log level ('debug' | 'info' | 'warn' | 'error')
+ * @property {string} [since] - Get logs since timestamp (ISO 8601) for incremental updates
+ */
+
+/**
+ * Get deployment logs response
+ * @typedef {Object} GetDeploymentLogsResponse
+ * @property {JobLog[]} data - Array of job logs
+ */
+
+module.exports = {};
+