@aifabrix/builder 2.37.9 → 2.39.0

package/.cursor/rules/project-rules.mdc

@@ -262,6 +262,8 @@ const appResponse = await registerApplication(controllerUrl, environment, data,
 - Gradually migrate modules to use centralized API client
 - Eventually deprecate direct usage of `lib/utils/api.js`
 
+**API Permissions**: When adding or changing `lib/api` functions that call Controller or Dataplane, document required permissions. See [permissions-guide.md](permissions-guide.md) for how to update `@requiresPermission` JSDoc and [docs/commands/permissions.md](../docs/commands/permissions.md).
+
 ## Code Style
 
 ### JavaScript Conventions
@@ -880,6 +882,7 @@ Define request/response types using JSDoc `@typedef`:
 - ✅ Use centralized API client (`lib/api/`) for new API calls
 - ✅ Define request/response types using JSDoc `@typedef` in `lib/api/types/`
 - ✅ Use domain-specific API modules (`lib/api/*.api.js`) instead of direct `makeApiCall`
+- ✅ When adding lib/api functions that call Controller/Dataplane, add `@requiresPermission` JSDoc per [permissions-guide.md](permissions-guide.md)
 
 ### Must Not Do (❌)
 - ❌ Never hardcode secrets, passwords, or tokens

package/README.md

@@ -9,6 +9,25 @@ Install the AI Fabrix platform and test it locally. Then add external integratio
 
 ---
 
+## Why AI Fabrix Builder?
+
+- **Build perspective:** Everything is driven by declarative config and JSON schemas—no hidden logic, AI assistant–friendly.
+- **Industry standards and security:** Follow industry standards and high security (e.g. ISO 27k); no secrets in version control.
+- **Full lifecycle in your version control:** Configuration, apps, and integrations live in your own VCS (GitHub, GitLab, Azure DevOps).
+- **One tool from day one:** Single CLI for local infra, app and integration creation, build, run, and deploy—same workflow for apps and integrations.
+- **Consistency and production readiness:** Schema-driven; deploy apps and integrations to the same controller/dataplane; production-ready secrets with `kv://` and Azure Key Vault.
+- **Application development:** Use **[miso-client](https://github.com/esystemsdev/aifabrix-miso-client)** for TypeScript and Python to talk to the dataplane and controller (see [templates/applications/dataplane/README.md](templates/applications/dataplane/README.md) and the repo for usage).
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** – Recommended for running the CLI.
+- **AI Fabrix Azure / platform:** Install from **Azure Marketplace** or run via **Docker** (e.g. `aifabrix up-platform`). You need **full access to Docker** (docker commands) where applicable.
+- **Secrets before platform:** Add secrets (e.g. OpenAI or Azure OpenAI) **before** running `aifabrix up-platform`; the platform reads them from the place you configure. See [Infrastructure](docs/infrastructure.md) and secrets configuration.
+
+---
+
 ## Install
 
 ```bash

package/integration/hubspot/hubspot-deploy.json

@@ -22,9 +22,6 @@
     "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
     "type": "openapi",
     "enabled": true,
-    "environment": {
-      "baseUrl": "https://api.hubapi.com"
-    },
     "authentication": {
       "type": "oauth2",
       "mode": "oauth2",
@@ -839,6 +836,5 @@
   ],
   "requiresDatabase": false,
   "requiresRedis": false,
-  "requiresStorage": false,
-  "deploymentKey": "9b5209bed2ef1eccb04fa83be73a74cf3a9c84d5d2580a95028d34fdb8db78a8"
+  "requiresStorage": false
 }

package/integration/hubspot/hubspot-system.json

@@ -4,9 +4,6 @@
   "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
   "type": "openapi",
   "enabled": true,
-  "environment": {
-    "baseUrl": "https://api.hubapi.com"
-  },
   "authentication": {
     "type": "oauth2",
     "mode": "oauth2",

package/lib/api/applications.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * List all template applications
  * GET /api/v1/applications
+ * @requiresPermission {Controller} applications:read
  * @async
  * @function listApplications
  * @param {string} controllerUrl - Controller base URL
@@ -32,6 +33,7 @@ async function listApplications(controllerUrl, authConfig, options = {}) {
 /**
  * Create new template application
  * POST /api/v1/applications
+ * @requiresPermission {Controller} applications:create
  * @async
  * @function createApplication
  * @param {string} controllerUrl - Controller base URL
@@ -55,6 +57,7 @@ async function createApplication(controllerUrl, authConfig, applicationData) {
 /**
  * Get template application details
  * GET /api/v1/applications/{appKey}
+ * @requiresPermission {Controller} applications:read
  * @async
  * @function getApplication
  * @param {string} controllerUrl - Controller base URL
@@ -71,6 +74,7 @@ async function getApplication(controllerUrl, appKey, authConfig) {
 /**
  * Update template application
  * PATCH /api/v1/applications/{appKey}
+ * @requiresPermission {Controller} applications:update
  * @async
  * @function updateApplication
  * @param {string} controllerUrl - Controller base URL
@@ -95,6 +99,7 @@ async function updateApplication(controllerUrl, appKey, authConfig, updateData)
 /**
  * Delete template application
  * DELETE /api/v1/applications/{appKey}
+ * @requiresPermission {Controller} applications:delete
  * @async
  * @function deleteApplication
  * @param {string} controllerUrl - Controller base URL
@@ -111,6 +116,7 @@ async function deleteApplication(controllerUrl, appKey, authConfig) {
 /**
  * Register application in an environment
  * POST /api/v1/environments/{envKey}/applications/register
+ * @requiresPermission {Controller} environments-applications:create
  * @async
  * @function registerApplication
  * @param {string} controllerUrl - Controller base URL
@@ -139,6 +145,7 @@ async function registerApplication(controllerUrl, envKey, authConfig, registrati
 /**
  * Rotate application secret
  * POST /api/v1/environments/{envKey}/applications/{appKey}/rotate-secret
+ * @requiresPermission {Controller} environments-applications:update
  * @async
  * @function rotateApplicationSecret
  * @param {string} controllerUrl - Controller base URL
@@ -153,6 +160,26 @@ async function rotateApplicationSecret(controllerUrl, envKey, appKey, authConfig
   return await client.post(`/api/v1/environments/${envKey}/applications/${appKey}/rotate-secret`);
 }
 
+/**
+ * Get application status (metadata only, no configuration)
+ * GET /api/v1/environments/{envKey}/applications/{appKey}/status
+ * @requiresPermission {Controller} Bearer or app client credentials (environments-applications:read)
+ * @async
+ * @function getApplicationStatus
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {string} appKey - Application key
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<Object>} Response with data: { id, key, displayName, url, internalUrl, port, status, runtimeStatus, environmentId, createdAt, updatedAt, image, description }
+ * @throws {Error} If request fails
+ */
+async function getApplicationStatus(controllerUrl, envKey, appKey, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(
+    `/api/v1/environments/${envKey}/applications/${appKey}/status`
+  );
+}
+
 module.exports = {
   listApplications,
   createApplication,
@@ -160,6 +187,7 @@ module.exports = {
   updateApplication,
   deleteApplication,
   registerApplication,
-  rotateApplicationSecret
+  rotateApplicationSecret,
+  getApplicationStatus
 };
 

package/lib/api/auth.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * Get authentication token using client credentials
  * POST /api/v1/auth/token
+ * @requiresPermission {Controller} Client credentials (no scope in spec)
  * @async
  * @function getToken
  * @param {string} clientId - Client ID
@@ -30,6 +31,7 @@ async function getToken(clientId, clientSecret, controllerUrl) {
 /**
  * Get client token for frontend application
  * GET/POST /api/v1/auth/client-token
+ * @requiresPermission {Controller} Client credentials or unauthenticated
  * @async
  * @function getClientToken
  * @param {string} controllerUrl - Controller base URL
@@ -50,6 +52,7 @@ async function getClientToken(controllerUrl, method = 'POST') {
 /**
  * Get current user information
  * GET /api/v1/auth/user
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function getAuthUser
  * @param {string} controllerUrl - Controller base URL
@@ -65,6 +68,7 @@ async function getAuthUser(controllerUrl, authConfig) {
 /**
  * Get login URL for OAuth2 authorization flow
  * GET /api/v1/auth/login
+ * @requiresPermission {Controller} Client credentials
  * @async
  * @function getAuthLogin
  * @param {string} controllerUrl - Controller base URL
@@ -84,6 +88,7 @@ async function getAuthLogin(controllerUrl, redirect, state, authConfig) {
 /**
  * Initiate OAuth2 Device Code Flow
  * POST /api/v1/auth/login
+ * @requiresPermission {Controller} Public (no auth required for device code initiation)
  * @async
  * @function initiateDeviceCodeFlow
  * @param {string} controllerUrl - Controller base URL
@@ -122,6 +127,7 @@ async function initiateDeviceCodeFlow(controllerUrl, environment, scope) {
 /**
  * Poll for device code token
  * POST /api/v1/auth/login/device/token
+ * @requiresPermission {Controller} Public
  * @async
  * @function pollDeviceCodeToken
  * @param {string} deviceCode - Device code from initiate device code flow
@@ -139,6 +145,7 @@ async function pollDeviceCodeToken(deviceCode, controllerUrl) {
 /**
  * Refresh device code access token
  * POST /api/v1/auth/login/device/refresh
+ * @requiresPermission {Controller} Bearer token (refresh token)
  * @async
  * @function refreshDeviceToken
  * @param {string} refreshToken - Refresh token obtained from device code token flow
@@ -156,6 +163,7 @@ async function refreshDeviceToken(refreshToken, controllerUrl) {
 /**
  * Refresh user access token
  * POST /api/v1/auth/refresh
+ * @requiresPermission {Controller} Bearer token (refresh token)
  * @async
  * @function refreshUserToken
  * @param {string} refreshToken - Refresh token obtained from OAuth callback flow
@@ -173,6 +181,7 @@ async function refreshUserToken(refreshToken, controllerUrl) {
 /**
  * Validate authentication token
  * POST /api/v1/auth/validate
+ * @requiresPermission {Controller} auth:read or client credentials
  * @async
  * @function validateToken
  * @param {string} token - JWT token to validate
@@ -202,6 +211,7 @@ async function validateToken(token, controllerUrl, authConfig, environment, appl
 /**
  * Get user roles
  * GET /api/v1/auth/roles
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function getAuthRoles
  * @param {string} controllerUrl - Controller base URL
@@ -221,6 +231,7 @@ async function getAuthRoles(controllerUrl, authConfig, environment, application)
 /**
  * Refresh user roles
  * GET /api/v1/auth/roles/refresh
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function refreshAuthRoles
  * @param {string} controllerUrl - Controller base URL
@@ -236,6 +247,7 @@ async function refreshAuthRoles(controllerUrl, authConfig) {
 /**
  * Get user permissions
  * GET /api/v1/auth/permissions
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function getAuthPermissions
  * @param {string} controllerUrl - Controller base URL
@@ -255,6 +267,7 @@ async function getAuthPermissions(controllerUrl, authConfig, environment, applic
 /**
  * Refresh user permissions
  * GET /api/v1/auth/permissions/refresh
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function refreshAuthPermissions
  * @param {string} controllerUrl - Controller base URL
@@ -270,6 +283,7 @@ async function refreshAuthPermissions(controllerUrl, authConfig) {
 /**
  * Get device code login diagnostics
  * GET /api/v1/auth/login/diagnostics
+ * @requiresPermission {Controller} Public
  * @async
  * @function getAuthLoginDiagnostics
  * @param {string} controllerUrl - Controller base URL

package/lib/api/credentials.api.js

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Credentials API functions (controller/dataplane credential list)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { ApiClient } = require('./index');
+
+/**
+ * List credentials from controller or dataplane
+ * GET /api/v1/credential
+ * Used by `aifabrix credential list`. Call with controller or dataplane base URL per deployment.
+ * @requiresPermission {Dataplane} credential:read (when baseUrl is dataplane; controller may differ)
+ * @async
+ * @function listCredentials
+ * @param {string} baseUrl - Controller or dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [options] - List options
+ * @param {boolean} [options.activeOnly] - If true, return only active credentials
+ * @param {number} [options.page] - Page number
+ * @param {number} [options.pageSize] - Items per page
+ * @returns {Promise<Object>} Response with credentials (e.g. data.credentials or data.items)
+ * @throws {Error} If request fails
+ */
+async function listCredentials(baseUrl, authConfig, options = {}) {
+  const client = new ApiClient(baseUrl, authConfig);
+  return await client.get('/api/v1/credential', {
+    params: options
+  });
+}
+
+module.exports = {
+  listCredentials
+};

package/lib/api/datasources-core.api.js

@@ -1,67 +1,82 @@
 /**
- * @fileoverview Datasources Core API functions
+ * @fileoverview Datasources Core API functions (Dataplane /api/v1/external/). All functions require Dataplane auth; scope per endpoint in dataplane OpenAPI (e.g. external-system:read, external-system:create).
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
 const { ApiClient } = require('./index');
 
+/** @requiresPermission {Dataplane} external-system:read (datasource list) */
 async function listDatasources(dataplaneUrl, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get('/api/v1/external/', { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:create */
 async function createDatasource(dataplaneUrl, authConfig, datasourceData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/external/', { body: datasourceData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getDatasource(dataplaneUrl, sourceIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function updateDatasource(dataplaneUrl, sourceIdOrKey, authConfig, updateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}`, { body: updateData });
 }
+/** @requiresPermission {Dataplane} external-system:delete */
 async function deleteDatasource(dataplaneUrl, sourceIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getDatasourceConfig(dataplaneUrl, sourceIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/config`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function publishDatasource(dataplaneUrl, sourceIdOrKey, authConfig, publishData = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/publish`, { body: publishData });
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function rollbackDatasource(dataplaneUrl, sourceIdOrKey, authConfig, rollbackData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/rollback`, { body: rollbackData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function testDatasource(dataplaneUrl, sourceIdOrKey, authConfig, testData = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/test`, { body: testData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function listDatasourceOpenAPIEndpoints(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/openapi-endpoints`, { params: options });
 }
+/** @requiresPermission {Dataplane} audit:read or external-system:read */
 async function listExecutionLogs(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/executions`, { params: options });
 }
+/** @requiresPermission {Dataplane} audit:read or external-system:read */
 async function getExecutionLog(dataplaneUrl, sourceIdOrKey, executionId, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/executions/${executionId}`);
 }
+/** @requiresPermission {Dataplane} audit:read */
 async function listAllExecutionLogs(dataplaneUrl, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get('/api/v1/external/executions', { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function bulkOperation(dataplaneUrl, sourceIdOrKey, authConfig, bulkData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/bulk`, { body: bulkData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getDatasourceStatus(dataplaneUrl, sourceIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/status`);

package/lib/api/datasources-extended.api.js

@@ -1,43 +1,52 @@
 /**
- * @fileoverview Datasources Extended API functions (records, grants, policies, sync, documents)
+ * @fileoverview Datasources Extended API functions (records, grants, policies, sync, documents). All require Dataplane; scope per endpoint in dataplane OpenAPI.
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
 const { ApiClient } = require('./index');
 
+/** @requiresPermission {Dataplane} external-system:read (records) */
 async function listRecords(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/records`, { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:create */
 async function createRecord(dataplaneUrl, sourceIdOrKey, authConfig, recordData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/records`, { body: recordData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function updateRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig, updateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`, { body: updateData });
 }
+/** @requiresPermission {Dataplane} external-system:delete */
 async function deleteRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:read (grants) */
 async function listGrants(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/grants`, { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function createGrant(dataplaneUrl, sourceIdOrKey, authConfig, grantData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/grants`, { body: grantData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function updateGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig, updateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`, { body: updateData });
@@ -46,10 +55,12 @@ async function deleteGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:read (policies) */
 async function listPolicies(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/policies`, { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function attachPolicy(dataplaneUrl, sourceIdOrKey, authConfig, policyData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/policies`, { body: policyData });
@@ -58,6 +69,7 @@ async function detachPolicy(dataplaneUrl, sourceIdOrKey, policyIdOrKey, authConf
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/policies/${policyIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:read (sync) */
 async function listSyncJobs(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/sync`, { params: options });
@@ -66,10 +78,12 @@ async function createSyncJob(dataplaneUrl, sourceIdOrKey, authConfig, syncData)
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/sync`, { body: syncData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function updateSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig, updateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}`, { body: updateData });
@@ -78,14 +92,17 @@ async function executeSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}/execute`);
 }
+/** @requiresPermission {Dataplane} document-record or external-system scope */
 async function validateDocuments(dataplaneUrl, sourceIdOrKey, authConfig, validateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/data-sources/${sourceIdOrKey}/documents/validate`, { body: validateData });
 }
+/** @requiresPermission {Dataplane} document-record or external-system scope */
 async function bulkDocuments(dataplaneUrl, sourceIdOrKey, authConfig, bulkData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/data-sources/${sourceIdOrKey}/documents/bulk`, { body: bulkData });
 }
+/** @requiresPermission {Dataplane} document-record:read or external-system:read */
 async function listDocuments(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/data-sources/${sourceIdOrKey}/documents`, { params: options });

package/lib/api/deployments.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * Deploy an application to an environment
  * POST /api/v1/environments/{envKey}/applications/deploy
+ * @requiresPermission {Controller} applications:deploy
  * @async
  * @function deployApplication
  * @param {string} controllerUrl - Controller base URL
@@ -32,6 +33,7 @@ async function deployApplication(controllerUrl, envKey, authConfig, deployData)
 /**
  * Deploy environment infrastructure
  * POST /api/v1/environments/{envKey}/deploy
+ * @requiresPermission {Controller} controller:deploy
  * @async
  * @function deployEnvironment
  * @param {string} controllerUrl - Controller base URL
@@ -53,6 +55,7 @@ async function deployEnvironment(controllerUrl, envKey, authConfig, deployData)
 /**
  * List deployments for an environment
  * GET /api/v1/environments/{envKey}/deployments
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function listDeployments
  * @param {string} controllerUrl - Controller base URL
@@ -79,6 +82,7 @@ async function listDeployments(controllerUrl, envKey, authConfig, options = {})
 /**
  * Get deployment with jobs and logs
  * GET /api/v1/environments/{envKey}/deployments/{deploymentId}
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function getDeployment
  * @param {string} controllerUrl - Controller base URL
@@ -96,6 +100,7 @@ async function getDeployment(controllerUrl, envKey, deploymentId, authConfig) {
 /**
  * Get deployment job logs
  * GET /api/v1/environments/{envKey}/deployments/{deploymentId}/logs
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function getDeploymentLogs
  * @param {string} controllerUrl - Controller base URL
@@ -116,10 +121,37 @@ async function getDeploymentLogs(controllerUrl, envKey, deploymentId, authConfig
   });
 }
 
+/**
+ * List deployments for a single application in an environment
+ * GET /api/v1/environments/{envKey}/applications/{appKey}/deployments
+ * @requiresPermission {Controller} deployments:read
+ * @async
+ * @function listApplicationDeployments
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {string} appKey - Application key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [options] - List options
+ * @param {number} [options.page] - Page number
+ * @param {number} [options.pageSize] - Items per page (default 50)
+ * @param {string} [options.sort] - Sort parameter
+ * @param {string} [options.filter] - Filter parameter
+ * @returns {Promise<Object>} Paginated list of deployments for the application
+ * @throws {Error} If request fails
+ */
+async function listApplicationDeployments(controllerUrl, envKey, appKey, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(
+    `/api/v1/environments/${envKey}/applications/${appKey}/deployments`,
+    { params: options }
+  );
+}
+
 module.exports = {
   deployApplication,
   deployEnvironment,
   listDeployments,
+  listApplicationDeployments,
   getDeployment,
   getDeploymentLogs
 };

package/lib/api/environments.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * List all environments
  * GET /api/v1/environments
+ * @requiresPermission {Controller} environments:read
  * @async
  * @function listEnvironments
  * @param {string} controllerUrl - Controller base URL
@@ -34,6 +35,7 @@ async function listEnvironments(controllerUrl, authConfig, options = {}) {
 /**
  * Create new environment
  * POST /api/v1/environments
+ * @requiresPermission {Controller} environments:create
  * @async
  * @function createEnvironment
  * @param {string} controllerUrl - Controller base URL
@@ -55,6 +57,7 @@ async function createEnvironment(controllerUrl, authConfig, environmentData) {
 /**
  * Get environment by key
  * GET /api/v1/environments/{envKey}
+ * @requiresPermission {Controller} environments:read
  * @async
  * @function getEnvironment
  * @param {string} controllerUrl - Controller base URL
@@ -71,6 +74,7 @@ async function getEnvironment(controllerUrl, envKey, authConfig) {
 /**
  * Update environment by key
  * PATCH /api/v1/environments/{envKey}
+ * @requiresPermission {Controller} environments:update
  * @async
  * @function updateEnvironment
  * @param {string} controllerUrl - Controller base URL
@@ -91,6 +95,7 @@ async function updateEnvironment(controllerUrl, envKey, authConfig, updateData)
 /**
  * Get environment status
  * GET /api/v1/environments/{envKey}/status
+ * @requiresPermission {Controller} environments:read
  * @async
  * @function getEnvironmentStatus
  * @param {string} controllerUrl - Controller base URL
@@ -107,6 +112,7 @@ async function getEnvironmentStatus(controllerUrl, envKey, authConfig) {
 /**
  * List applications in an environment
  * GET /api/v1/environments/{envKey}/applications
+ * @requiresPermission {Controller} environments-applications:read
  * @async
  * @function listEnvironmentApplications
  * @param {string} controllerUrl - Controller base URL
@@ -131,6 +137,7 @@ async function listEnvironmentApplications(controllerUrl, envKey, authConfig, op
 /**
  * List deployments for environment
  * GET /api/v1/environments/{envKey}/deployments
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function listEnvironmentDeployments
  * @param {string} controllerUrl - Controller base URL
@@ -156,6 +163,7 @@ async function listEnvironmentDeployments(controllerUrl, envKey, authConfig, opt
 /**
  * List roles for environment
  * GET /api/v1/environments/{envKey}/roles
+ * @requiresPermission {Controller} environments:read
  * @async
  * @function listEnvironmentRoles
  * @param {string} controllerUrl - Controller base URL
@@ -172,6 +180,7 @@ async function listEnvironmentRoles(controllerUrl, envKey, authConfig) {
 /**
  * Map role to groups for environment
  * PATCH /api/v1/environments/{envKey}/roles/{value}/groups
+ * @requiresPermission {Controller} environments:update
  * @async
  * @function updateRoleGroups
  * @param {string} controllerUrl - Controller base URL
@@ -192,6 +201,7 @@ async function updateRoleGroups(controllerUrl, envKey, roleValue, authConfig, gr
 /**
  * Get application details in an environment
  * GET /api/v1/environments/{envKey}/applications/{appKey}
+ * @requiresPermission {Controller} environments-applications:read
  * @async
  * @function getEnvironmentApplication
  * @param {string} controllerUrl - Controller base URL
@@ -209,6 +219,7 @@ async function getEnvironmentApplication(controllerUrl, envKey, appKey, authConf
 /**
  * List datasources in an environment
  * GET /api/v1/environments/{envKey}/datasources
+ * @requiresPermission {Controller} environments:read (or datasources scope per controller spec)
  * @async
  * @function listEnvironmentDatasources
  * @param {string} controllerUrl - Controller base URL