@aifabrix/builder 2.40.2 → 2.42.0

package/lib/api/external-test.api.js

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview External test API - dataplane external endpoints (test, test-e2e)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { ApiClient } = require('./index');
+
+/**
+ * Run E2E test for one datasource (config, credential, sync, data, CIP) via dataplane external API.
+ * Requires Bearer token or API key; client credentials are not accepted.
+ * When asyncRun is true, POST returns 202 with { testRunId, status, startedAt }; caller must poll
+ * getE2ETestRun until status is 'completed' or 'failed'. When asyncRun is false, POST returns 200
+ * with sync body { steps, success, error?, ... }.
+ *
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ * @function testDatasourceE2E
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Source ID or datasource key (e.g. hubspot-test-v4-contacts)
+ * @param {Object} authConfig - Authentication configuration (must have token or apiKey; client creds rejected)
+ * @param {Object} [body] - Optional request body (e.g. includeDebug, testCrud, recordId, cleanup, primaryKeyValue)
+ * @param {Object} [options] - Optional options
+ * @param {boolean} [options.asyncRun] - If true, request async run (query param asyncRun=true); response may be 202 with testRunId
+ * @returns {Promise<Object>} Response with success, data (sync: steps/success/error; async start: testRunId/status/startedAt), status
+ * @throws {Error} If auth lacks Bearer/API_KEY or if test fails
+ */
+async function testDatasourceE2E(dataplaneUrl, sourceIdOrKey, authConfig, body = {}, options = {}) {
+  if (!authConfig.token && !authConfig.apiKey) {
+    throw new Error(
+      'E2E tests require Bearer token or API key. Run \'aifabrix login\' or configure API key. ' +
+      'Client credentials are not supported for external test endpoints.'
+    );
+  }
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  const postOptions = { body };
+  if (options.asyncRun === true) {
+    postOptions.params = { asyncRun: 'true' };
+  }
+  return await client.post(`/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/test-e2e`, postOptions);
+}
+
+/**
+ * Poll E2E test run status. Call after testDatasourceE2E with asyncRun true when response has testRunId.
+ * Same auth as E2E (Bearer or API key).
+ *
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ * @function getE2ETestRun
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Source ID or datasource key
+ * @param {string} testRunId - Test run ID from async start response
+ * @param {Object} authConfig - Authentication configuration (must have token or apiKey)
+ * @returns {Promise<Object>} Poll response: { status, completedActions?, steps?, success?, error?, durationSeconds?, debug? }
+ * @throws {Error} If auth lacks Bearer/API_KEY, or if run not found/expired (404)
+ */
+async function getE2ETestRun(dataplaneUrl, sourceIdOrKey, testRunId, authConfig) {
+  if (!authConfig.token && !authConfig.apiKey) {
+    throw new Error(
+      'E2E poll requires Bearer token or API key. Run \'aifabrix login\' or configure API key.'
+    );
+  }
+  if (!testRunId || typeof testRunId !== 'string') {
+    throw new Error('testRunId is required for E2E poll');
+  }
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  const response = await client.get(
+    `/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/test-e2e/${encodeURIComponent(testRunId)}`
+  );
+  if (!response.success) {
+    if (response.status === 404) {
+      throw new Error(
+        `E2E test run not found or expired (run ID: ${testRunId}). The run may have been purged or the ID is invalid.`
+      );
+    }
+    throw new Error(response.formattedError || response.error || 'E2E poll failed');
+  }
+  return response.data || response;
+}
+
+/**
+ * Run config test for one datasource via dataplane external API.
+ * Requires Bearer token or API key; client credentials are not accepted.
+ *
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ * @function testDatasourceConfig
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Source ID or datasource key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [body] - Optional request body
+ * @returns {Promise<Object>} Config test response
+ * @throws {Error} If auth lacks Bearer/API_KEY or if test fails
+ */
+async function testDatasourceConfig(dataplaneUrl, sourceIdOrKey, authConfig, body = {}) {
+  if (!authConfig.token && !authConfig.apiKey) {
+    throw new Error(
+      'External config tests require Bearer token or API key. Run \'aifabrix login\' or configure API key.'
+    );
+  }
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.post(`/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/test`, {
+    body
+  });
+}
+
+module.exports = {
+  testDatasourceE2E,
+  getE2ETestRun,
+  testDatasourceConfig
+};

package/lib/api/index.js

@@ -13,13 +13,12 @@ const { makeApiCall, authenticatedApiCall } = require('../utils/api');
  */
 class ApiClient {
   /**
-   * Create an API client instance
+   * Create an API client instance.
+   * App endpoints receive token-only auth (Bearer). x-client-id/x-client-secret are not sent to app endpoints.
    * @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.type] - Auth type ('bearer' | '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 === null || baseUrl === undefined || typeof baseUrl !== 'string') {
@@ -48,26 +47,23 @@ class ApiClient {
    * Build request headers with authentication
    * @private
    * @param {Object} [additionalHeaders] - Additional headers to include
+   * @param {Object} [opts] - Options
+   * @param {boolean} [opts.skipContentType] - If true, do not set Content-Type (e.g. for FormData when boundary is set by fetch)
    * @returns {Object} Request headers
    */
-  _buildHeaders(additionalHeaders = {}) {
-    const headers = {
-      'Content-Type': 'application/json',
-      ...additionalHeaders
-    };
+  _buildHeaders(additionalHeaders = {}, opts = {}) {
+    const headers = { ...additionalHeaders };
+    if (!opts.skipContentType) {
+      headers['Content-Type'] = 'application/json';
+    }
 
-    // Add authentication headers based on authConfig
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
-      if (this.authConfig.token) {
+    // User token (bearer) → Authorization: Bearer; application token (client-token) → x-client-token
+    if (this.authConfig.token) {
+      if (this.authConfig.type === 'client-token') {
+        headers['x-client-token'] = this.authConfig.token;
+      } else {
         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;
@@ -153,6 +149,33 @@ class ApiClient {
     return await makeApiCall(url, requestOptions);
   }
 
+  /**
+   * POST multipart/form-data (e.g. file upload). Uses same auth as other methods; does not set Content-Type so fetch sets boundary.
+   * @async
+   * @param {string} endpoint - API endpoint path
+   * @param {FormData} formData - FormData body
+   * @param {Object} [options] - Request options
+   * @param {Object} [options.headers] - Additional headers
+   * @returns {Promise<Object>} API response
+   */
+  async postFormData(endpoint, formData, options = {}) {
+    const url = this._buildUrl(endpoint);
+    const headers = this._buildHeaders(options.headers || {}, { skipContentType: true });
+
+    const requestOptions = {
+      method: 'POST',
+      headers,
+      body: formData
+    };
+
+    const hasToken = this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token';
+    if (hasToken && this.authConfig.token) {
+      return await authenticatedApiCall(url, requestOptions, this.authConfig);
+    }
+
+    return await makeApiCall(url, requestOptions);
+  }
+
   /**
    * Make a PATCH request
    * @async

package/lib/api/pipeline.api.js

@@ -14,7 +14,7 @@ const { ApiClient } = require('./index');
  * @function validatePipeline
  * @param {string} controllerUrl - Controller base URL
  * @param {string} envKey - Environment key
- * @param {Object} authConfig - Authentication configuration (supports client credentials)
+ * @param {Object} authConfig - Authentication configuration (Bearer token only for app endpoints)
  * @param {Object} validationData - Validation data
  * @param {string} validationData.clientId - Client ID for application authentication
  * @param {string} validationData.repositoryUrl - Repository URL for validation
@@ -37,7 +37,7 @@ async function validatePipeline(controllerUrl, envKey, authConfig, validationDat
  * @function deployPipeline
  * @param {string} controllerUrl - Controller base URL
  * @param {string} envKey - Environment key
- * @param {Object} authConfig - Authentication configuration (supports client credentials)
+ * @param {Object} authConfig - Authentication configuration (Bearer token only for app endpoints)
  * @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
@@ -60,7 +60,7 @@ async function deployPipeline(controllerUrl, envKey, authConfig, deployData) {
  * @param {string} controllerUrl - Controller base URL
  * @param {string} envKey - Environment key
  * @param {string} deploymentId - Deployment ID
- * @param {Object} authConfig - Authentication configuration (supports client credentials)
+ * @param {Object} authConfig - Authentication configuration (Bearer token only for app endpoints)
  * @returns {Promise<Object>} Minimal deployment status response
  * @throws {Error} If request fails
  */
@@ -85,31 +85,9 @@ async function getPipelineHealth(controllerUrl, envKey) {
   return await client.get(`/api/v1/pipeline/${envKey}/health`);
 }
 
-/**
- * Publish one external system via dataplane pipeline endpoint
- * POST /api/v1/pipeline/publish (Dataplane OpenAPI operationId: publishExternalSystemViaPipeline)
- * Request body: external system JSON (external-system.schema.json). Optional field in body:
- * generateMcpContract (boolean, default true). Optional: generateOpenApiContract (boolean).
- * Do not use query parameters for MCP; use the field in the body only.
- * @requiresPermission {Dataplane} external-system:publish. Auth: OAuth2 (Bearer) or API_KEY only; client id/secret are not accepted.
- * @async
- * @function publishSystemViaPipeline
- * @param {string} dataplaneUrl - Dataplane base URL
- * @param {Object} authConfig - Authentication configuration (must include token for Bearer; client id/secret rejected)
- * @param {Object} systemConfig - External system configuration (conforms to external-system.schema.json)
- * @returns {Promise<Object>} Published external system response
- * @throws {Error} If publish fails
- */
-async function publishSystemViaPipeline(dataplaneUrl, authConfig, systemConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
-  return await client.post('/api/v1/pipeline/publish', {
-    body: systemConfig
-  });
-}
-
 /**
  * Publish datasource via dataplane pipeline endpoint
- * POST /api/v1/pipeline/{systemKey}/publish (Dataplane OpenAPI operationId: publishExternalDataSourceViaPipeline)
+ * POST /api/v1/pipeline/{systemKey}/upload (Dataplane: renamed from /publish)
  * No generateMcpContract for this endpoint; dataplane always uses default (MCP generated).
  * @requiresPermission {Dataplane} external-system:publish. Auth: OAuth2 (Bearer) or API_KEY only; client id/secret are not accepted.
  * @async
@@ -123,15 +101,62 @@ async function publishSystemViaPipeline(dataplaneUrl, authConfig, systemConfig)
  */
 async function publishDatasourceViaPipeline(dataplaneUrl, systemKey, authConfig, datasourceConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
-  return await client.post(`/api/v1/pipeline/${systemKey}/publish`, {
+  return await client.post(`/api/v1/pipeline/${systemKey}/upload`, {
     body: datasourceConfig
   });
 }
 
+/**
+ * Validate pipeline config against Dataplane (dry-run; no publish).
+ * POST /api/v1/pipeline/validate
+ * @requiresPermission {Dataplane} external-system:read or external-system:publish
+ * @async
+ * @function validatePipelineConfig
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} params - Request params
+ * @param {Object} params.config - Full config: { version, application, dataSources }
+ * @returns {Promise<Object>} { isValid, errors, warnings }
+ * @throws {Error} If request fails
+ */
+async function validatePipelineConfig(dataplaneUrl, authConfig, { config }) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.post('/api/v1/pipeline/validate', {
+    body: { config }
+  });
+}
+
+/**
+ * Test external system (all datasources) via dataplane pipeline endpoint
+ * POST /api/v1/pipeline/{systemKey}/test
+ * @requiresPermission {Dataplane} external-system:publish. Auth: Bearer or x-client-token only.
+ * @async
+ * @function testSystemViaPipeline
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} systemKey - System key
+ * @param {Object} authConfig - Authentication configuration (Bearer token)
+ * @param {Object} testData - Test data
+ * @param {Object} [testData.payloadTemplate] - Optional payload template
+ * @param {boolean} [testData.includeDebug] - Include debug output in response
+ * @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 testSystemViaPipeline(dataplaneUrl, systemKey, authConfig, testData = {}, options = {}) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  const requestOptions = { body: testData };
+  if (options.timeout) {
+    requestOptions.timeout = options.timeout;
+  }
+  return await client.post(`/api/v1/pipeline/${systemKey}/test`, requestOptions);
+}
+
 /**
  * Test datasource via dataplane pipeline endpoint
  * POST /api/v1/pipeline/{systemKey}/{datasourceKey}/test (Dataplane OpenAPI operationId: testExternalDataSourceViaPipeline)
- * @requiresPermission {Dataplane} external-system:publish or external-data-source:read. Auth: OAuth2 (Bearer) or API_KEY only; client id/secret are not accepted.
+ * Supports client credentials for CI/CD.
+ * @requiresPermission {Dataplane} external-system:publish or external-data-source:read. Auth: Bearer or x-client-token only.
  * @async
  * @function testDatasourceViaPipeline
  * @param {Object} params - Function parameters
@@ -159,116 +184,37 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
 }
 
 /**
- * Deploy external system via dataplane pipeline endpoint
- * POST /api/v1/pipeline/deploy
- * @requiresPermission {Dataplane} external-system:publish. Auth: OAuth2 (Bearer) or API_KEY only; client id/secret are not accepted.
- * @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
- * @requiresPermission {Dataplane} external-system:publish. Auth: OAuth2 (Bearer) or API_KEY only; client id/secret are not accepted.
- * @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 (Dataplane OpenAPI operationId: uploadApplication)
- * Body: { version, application, dataSources }. Include application.generateMcpContract
- * and/or application.generateOpenApiContract to control contract generation when
- * publishing this upload (publish reads from stored config; no query param on publish).
+ * Upload application configuration via dataplane pipeline endpoint (single call: upload → validate → publish → controller register).
+ * POST /api/v1/pipeline/upload
+ * Body: { version, application, dataSources, status }. status "draft" (default) or "published".
+ * Include application.generateMcpContract and/or application.generateOpenApiContract to control contract generation.
  * @requiresPermission {Dataplane} external-system:publish. Auth: OAuth2 (Bearer) or API_KEY only; client id/secret are not accepted.
  * @async
  * @function uploadApplicationViaPipeline
  * @param {string} dataplaneUrl - Dataplane base URL
  * @param {Object} authConfig - Authentication configuration (must include token for Bearer; client id/secret rejected)
- * @param {Object} applicationSchema - { version, application, dataSources }; application may include generateMcpContract, generateOpenApiContract
- * @returns {Promise<Object>} Upload response with uploadId
+ * @param {Object} payload - { version, application, dataSources }; optional status (default "draft")
+ * @param {string} [payload.status="draft"] - "draft" or "published"; Builder uses "draft"
+ * @returns {Promise<Object>} Publication result (system, datasources, warnings); no uploadId
  * @throws {Error} If upload fails
  */
-async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, applicationSchema) {
+async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, payload) {
+  const body = { ...payload, status: payload.status ?? 'draft' };
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/pipeline/upload', {
-    body: applicationSchema
+    body
   });
 }
 
-/**
- * Validate upload via dataplane pipeline endpoint
- * POST /api/v1/pipeline/upload/{uploadId}/validate (Dataplane OpenAPI operationId: validateApplication)
- * @requiresPermission {Dataplane} external-system:publish. Auth: OAuth2 (Bearer) or API_KEY only; client id/secret are not accepted.
- * @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 (Dataplane OpenAPI operationId: publishApplication)
- * No body or query parameters. MCP/OpenAPI generation is taken from the application config
- * that was uploaded (application.generateMcpContract, application.generateOpenApiContract).
- * To control MCP/OpenAPI, include those fields in the application object when calling
- * uploadApplicationViaPipeline.
- * @requiresPermission {Dataplane} external-system:publish. Auth: OAuth2 (Bearer) or API_KEY only; client id/secret are not accepted.
- * @async
- * @function publishUploadViaPipeline
- * @param {string} dataplaneUrl - Dataplane base URL
- * @param {string} uploadId - Upload ID
- * @param {Object} authConfig - Authentication configuration (must include token for Bearer; client id/secret rejected)
- * @returns {Promise<Object>} Publish response
- * @throws {Error} If publish fails
- */
-async function publishUploadViaPipeline(dataplaneUrl, uploadId, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
-  return await client.post(`/api/v1/pipeline/upload/${uploadId}/publish`);
-}
-
 module.exports = {
   validatePipeline,
   deployPipeline,
   getPipelineDeployment,
   getPipelineHealth,
-  publishSystemViaPipeline,
   publishDatasourceViaPipeline,
+  validatePipelineConfig,
+  testSystemViaPipeline,
   testDatasourceViaPipeline,
-  deployExternalSystemViaPipeline,
-  deployDatasourceViaPipeline,
-  uploadApplicationViaPipeline,
-  validateUploadViaPipeline,
-  publishUploadViaPipeline
+  uploadApplicationViaPipeline
 };
 

package/lib/api/types/credential.types.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Credential API type definitions (Dataplane secret store)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Single secret item for Dataplane credential secret store.
+ * Key is the kv:// path; value must be plain (resolved), never a kv:// reference.
+ * @typedef {Object} SecretStoreItem
+ * @property {string} key - kv:// path (e.g. kv://secrets/client-secret)
+ * @property {string} value - Plain secret value (encrypted at rest by dataplane)
+ */
+
+/**
+ * Response from POST /api/v1/credential/secret (Dataplane).
+ * @typedef {Object} SecretStoreResponse
+ * @property {number} [stored] - Number of secrets stored
+ * @property {boolean} [success] - Request success flag
+ * @property {string} [error] - Error message when success is false
+ */
+
+module.exports = {};

package/lib/api/types/dev.types.js

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Builder Server (dev) API type definitions – issue-cert, settings, users, SSH keys, secrets
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Issue certificate request (POST /api/dev/issue-cert). Public; no client cert.
+ * @typedef {Object} IssueCertDto
+ * @property {string} developerId - Developer ID (must match user for whom PIN was created)
+ * @property {string} pin - One-time PIN from POST /api/dev/users/:id/pin
+ * @property {string} csr - PEM-encoded Certificate Signing Request
+ */
+
+/**
+ * Issue certificate response (POST /api/dev/issue-cert)
+ * @typedef {Object} IssueCertResponseDto
+ * @property {string} certificate - PEM-encoded X.509 certificate
+ * @property {number} validDays - Validity in days
+ * @property {string} validNotAfter - ISO 8601 validity end (UTC)
+ * @property {string} [caCertificate] - Optional PEM-encoded CA certificate (for remote Docker TLS; saved as ca.pem)
+ * @property {string} [ca] - Optional alias for caCertificate
+ */
+
+/**
+ * Developer settings (GET /api/dev/settings). Cert-authenticated.
+ * @typedef {Object} SettingsResponseDto
+ * @property {string} user-mutagen-folder - Server path to workspace root (no app segment)
+ * @property {string} secrets-encryption - Encryption key (hex)
+ * @property {string} aifabrix-secrets - Path or URL for secrets
+ * @property {string} aifabrix-env-config - Env config path
+ * @property {string} remote-server - Builder-server base URL
+ * @property {string} docker-endpoint - Docker API endpoint
+ * @property {string} sync-ssh-user - SSH user for Mutagen
+ * @property {string} sync-ssh-host - SSH host for Mutagen
+ */
+
+/**
+ * User list item (GET /api/dev/users)
+ * @typedef {Object} UserResponseDto
+ * @property {string} id - Developer ID
+ * @property {string} name - Display name
+ * @property {string} email - Email
+ * @property {string} createdAt - ISO 8601
+ * @property {boolean} certificateIssued - Whether cert was issued
+ * @property {string} [certificateValidNotAfter] - Cert validity end (optional)
+ * @property {string[]} groups - Access groups (admin, secret-manager, developer)
+ */
+
+/**
+ * Create user request (POST /api/dev/users)
+ * @typedef {Object} CreateUserDto
+ * @property {string} developerId - Unique developer ID (numeric string)
+ * @property {string} name - Display name
+ * @property {string} email - Email
+ * @property {string[]} [groups] - Default [developer]
+ */
+
+/**
+ * Update user request (PATCH /api/dev/users/:id). At least one field.
+ * @typedef {Object} UpdateUserDto
+ * @property {string} [name] - Display name
+ * @property {string} [email] - Email
+ * @property {string[]} [groups] - Access groups
+ */
+
+/**
+ * Create PIN response (POST /api/dev/users/:id/pin)
+ * @typedef {Object} CreatePinResponseDto
+ * @property {string} pin - One-time PIN
+ * @property {string} expiresAt - ISO 8601
+ */
+
+/**
+ * Add SSH key request (POST /api/dev/users/:id/ssh-keys)
+ * @typedef {Object} AddSshKeyDto
+ * @property {string} publicKey - SSH public key line
+ * @property {string} [label] - Optional label
+ */
+
+/**
+ * SSH key item (list/add response)
+ * @typedef {Object} SshKeyItemDto
+ * @property {string} fingerprint - Key fingerprint
+ * @property {string} [label] - Optional label
+ * @property {string} [createdAt] - ISO 8601
+ */
+
+/**
+ * Deleted response (DELETE endpoints)
+ * @typedef {Object} DeletedResponseDto
+ * @property {string} deleted - ID or key of deleted resource
+ */
+
+/**
+ * Secret item (GET /api/dev/secrets)
+ * @typedef {Object} SecretItemDto
+ * @property {string} name - Secret key
+ * @property {string} value - Decrypted value
+ */
+
+/**
+ * Add secret request (POST /api/dev/secrets)
+ * @typedef {Object} AddSecretDto
+ * @property {string} key - Secret key
+ * @property {string} value - Secret value
+ */
+
+/**
+ * Add secret response
+ * @typedef {Object} AddSecretResponseDto
+ * @property {string} key - Key that was added/updated
+ */
+
+/**
+ * Delete secret response
+ * @typedef {Object} DeleteSecretResponseDto
+ * @property {string} deleted - Key that was removed
+ */
+
+/**
+ * Health response (GET /health)
+ * @typedef {Object} HealthResponseDto
+ * @property {string} status - Overall status, e.g. "ok"
+ * @property {Object} checks - Per-component health checks
+ * @property {string} checks.dataDir - Data directory check ("ok" or error)
+ * @property {string} checks.encryptionKey - Encryption key check ("ok" or error)
+ * @property {string} checks.ca - CA certificate check ("ok" or error)
+ * @property {string} checks.users - Users store check ("ok" or error)
+ * @property {string} checks.tokens - Tokens store check ("ok" or error)
+ */
+
+/**
+ * Error response (all error responses)
+ * @typedef {Object} ErrorResponseDto
+ * @property {number} statusCode - HTTP status
+ * @property {string} error - Short error type
+ * @property {string} message - Human-readable message
+ * @property {string} [code] - Optional machine-readable code
+ */

package/lib/api/types/pipeline.types.js

@@ -121,5 +121,42 @@
  * @property {string} data.environment - Environment key
  */
 
+/**
+ * Dataplane pipeline upload request body (single upload → validate → publish).
+ * @typedef {Object} PipelineUploadRequest
+ * @property {string} version - Config version (e.g. "1.0.0")
+ * @property {Object} application - Application/system config (external-system schema)
+ * @property {Object[]} dataSources - Data source configs
+ * @property {string} [status="draft"] - "draft" or "published"; Builder uses "draft"
+ */
+
+/**
+ * Dataplane pipeline upload response (publication result; no uploadId).
+ * @typedef {Object} PipelineUploadResponse
+ * @property {boolean} success - Request success flag
+ * @property {Object} [data] - Publication result (system, datasources, warnings)
+ * @property {string} [data.systemKey] - Published system key
+ * @property {string[]} [data.datasourceKeys] - Published datasource keys
+ * @property {string[]} [data.warnings] - Warnings if any
+ * @property {string} [formattedError] - Formatted error message on failure
+ */
+
+/**
+ * Dataplane pipeline validate request body (dry-run validation only).
+ * @typedef {Object} PipelineValidateConfigRequest
+ * @property {Object} config - Full config to validate
+ * @property {string} config.version - Config version
+ * @property {Object} config.application - Application config
+ * @property {Object[]} config.dataSources - Data source configs
+ */
+
+/**
+ * Dataplane pipeline validate response.
+ * @typedef {Object} PipelineValidateConfigResponse
+ * @property {boolean} isValid - Whether config is valid
+ * @property {string[]} [errors] - Validation errors
+ * @property {string[]} [warnings] - Validation warnings
+ */
+
 module.exports = {};