dalux-build-api 1.1.3 → 1.1.5

package/src/configuration.js

@@ -1,24 +1,39 @@
-'use strict';
-
-/**
- * Configuration for the Dalux Build API client.
- */
-class Configuration {
-  /**
-   * @param {object} options
-   * @param {string} options.baseUrl  - The API base URL provided by Dalux (e.g. https://api.dalux.com/build)
-   * @param {string} options.apiKey  - Your company-specific X-API-KEY
-   */
-  constructor({ baseUrl, apiKey } = {}) {
-    if (!baseUrl) {
-      throw new Error('baseUrl is required');
-    }
-    if (!apiKey) {
-      throw new Error('apiKey is required');
-    }
-    this.baseUrl = baseUrl.replace(/\/$/, '');
-    this.apiKey = apiKey;
-  }
-}
-
-module.exports = Configuration;
+'use strict';
+
+// Load .env file when dotenv is available (optional peer dep)
+try {
+  require('dotenv').config();
+} catch (_) { /* dotenv not installed – skip */ }
+
+/**
+ * Configuration for the Dalux Build API client.
+ *
+ * When *baseUrl* or *apiKey* are not provided they are read from the
+ * environment variables ``DALUX_BASE_URL`` and ``DALUX_API_KEY`` respectively,
+ * matching the behaviour of the Python client.
+ */
+class Configuration {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.baseUrl]  - The API base URL provided by Dalux
+   *   (e.g. ``https://<company>.dalux.com/api``).
+   *   Falls back to the ``DALUX_BASE_URL`` environment variable.
+   * @param {string} [options.apiKey]  - Your company-specific X-API-KEY.
+   *   Falls back to the ``DALUX_API_KEY`` environment variable.
+   */
+  constructor({ baseUrl, apiKey } = {}) {
+    const resolvedBaseUrl = baseUrl || process.env.DALUX_BASE_URL;
+    const resolvedApiKey = apiKey || process.env.DALUX_API_KEY;
+
+    if (!resolvedBaseUrl) {
+      throw new Error('baseUrl is required (or set DALUX_BASE_URL env var)');
+    }
+    if (!resolvedApiKey) {
+      throw new Error('apiKey is required (or set DALUX_API_KEY env var)');
+    }
+    this.baseUrl = resolvedBaseUrl.replace(/\/$/, '');
+    this.apiKey = resolvedApiKey;
+  }
+}
+
+module.exports = Configuration;

package/src/index.js

@@ -1,92 +1,128 @@
-'use strict';
-
-const Configuration = require('./configuration');
-const ApiClient = require('./apiClient');
-
-const CompaniesApi = require('./api/CompaniesApi');
-const CompanyCatalogApi = require('./api/CompanyCatalogApi');
-const FileAreasApi = require('./api/FileAreasApi');
-const FileRevisionsApi = require('./api/FileRevisionsApi');
-const FileUploadApi = require('./api/FileUploadApi');
-const FilesApi = require('./api/FilesApi');
-const FoldersApi = require('./api/FoldersApi');
-const FormsApi = require('./api/FormsApi');
-const InspectionPlansApi = require('./api/InspectionPlansApi');
-const ProjectTemplatesApi = require('./api/ProjectTemplatesApi');
-const ProjectsApi = require('./api/ProjectsApi');
-const TasksApi = require('./api/TasksApi');
-const TestPlansApi = require('./api/TestPlansApi');
-const UsersApi = require('./api/UsersApi');
-const VersionSetsApi = require('./api/VersionSetsApi');
-const WorkPackagesApi = require('./api/WorkPackagesApi');
-
-/**
- * Create a fully configured Dalux Build API client.
- *
- * @param {object} options
- * @param {string} options.baseUrl  - The API base URL (obtain from Dalux support)
- * @param {string} options.apiKey  - Your X-API-KEY (manage via Dalux Settings › Integrations › API Identities)
- * @returns {{
- *   projects: ProjectsApi,
- *   companies: CompaniesApi,
- *   companyCatalog: CompanyCatalogApi,
- *   fileAreas: FileAreasApi,
- *   fileRevisions: FileRevisionsApi,
- *   fileUpload: FileUploadApi,
- *   files: FilesApi,
- *   folders: FoldersApi,
- *   forms: FormsApi,
- *   inspectionPlans: InspectionPlansApi,
- *   projectTemplates: ProjectTemplatesApi,
- *   tasks: TasksApi,
- *   testPlans: TestPlansApi,
- *   users: UsersApi,
- *   versionSets: VersionSetsApi,
- *   workPackages: WorkPackagesApi
- * }}
- */
-function createClient({ baseUrl, apiKey } = {}) {
-  const configuration = new Configuration({ baseUrl, apiKey });
-  const apiClient = new ApiClient(configuration);
-
-  return {
-    projects: new ProjectsApi(apiClient),
-    companies: new CompaniesApi(apiClient),
-    companyCatalog: new CompanyCatalogApi(apiClient),
-    fileAreas: new FileAreasApi(apiClient),
-    fileRevisions: new FileRevisionsApi(apiClient),
-    fileUpload: new FileUploadApi(apiClient),
-    files: new FilesApi(apiClient),
-    folders: new FoldersApi(apiClient),
-    forms: new FormsApi(apiClient),
-    inspectionPlans: new InspectionPlansApi(apiClient),
-    projectTemplates: new ProjectTemplatesApi(apiClient),
-    tasks: new TasksApi(apiClient),
-    testPlans: new TestPlansApi(apiClient),
-    users: new UsersApi(apiClient),
-    versionSets: new VersionSetsApi(apiClient),
-    workPackages: new WorkPackagesApi(apiClient),
-  };
-}
-
-module.exports = {
-  createClient,
-  Configuration,
-  ApiClient,
-  CompaniesApi,
-  CompanyCatalogApi,
-  FileAreasApi,
-  FileRevisionsApi,
-  FileUploadApi,
-  FilesApi,
-  FoldersApi,
-  FormsApi,
-  InspectionPlansApi,
-  ProjectTemplatesApi,
-  ProjectsApi,
-  TasksApi,
-  TestPlansApi,
-  UsersApi,
-  VersionSetsApi,
-  WorkPackagesApi,
-};
+'use strict';
+
+const Configuration = require('./configuration');
+const ApiClient = require('./apiClient');
+
+const CompaniesApi = require('./api/CompaniesApi');
+const CompanyCatalogApi = require('./api/CompanyCatalogApi');
+const FileAreasApi = require('./api/FileAreasApi');
+const FileRevisionsApi = require('./api/FileRevisionsApi');
+const FileUploadApi = require('./api/FileUploadApi');
+const FilesApi = require('./api/FilesApi');
+const FoldersApi = require('./api/FoldersApi');
+const FormsApi = require('./api/FormsApi');
+const InspectionPlansApi = require('./api/InspectionPlansApi');
+const ProjectTemplatesApi = require('./api/ProjectTemplatesApi');
+const ProjectsApi = require('./api/ProjectsApi');
+const TasksApi = require('./api/TasksApi');
+const TestPlansApi = require('./api/TestPlansApi');
+const UsersApi = require('./api/UsersApi');
+const VersionSetsApi = require('./api/VersionSetsApi');
+const WorkPackagesApi = require('./api/WorkPackagesApi');
+
+const {
+  DaluxError,
+  NotFoundError,
+  ApiError,
+  ValidationError,
+  AuthenticationError,
+  RateLimitError,
+  hasNextPage,
+  getNextBookmark,
+  paginate,
+  findByField,
+  findAllByField,
+  validateProjectId,
+  validateFileAreaId,
+  validateFolderId,
+  resolveFileAreaByName,
+  resolveFolderIdFromNamedPath,
+} = require('./utils');
+
+/**
+ * Create a fully configured Dalux Build API client.
+ *
+ * @param {object} [options]
+ * @param {string} [options.baseUrl]  - The API base URL (falls back to DALUX_BASE_URL env var)
+ * @param {string} [options.apiKey]  - Your X-API-KEY (falls back to DALUX_API_KEY env var)
+ * @returns {{
+ *   projects: ProjectsApi,
+ *   companies: CompaniesApi,
+ *   companyCatalog: CompanyCatalogApi,
+ *   fileAreas: FileAreasApi,
+ *   fileRevisions: FileRevisionsApi,
+ *   fileUpload: FileUploadApi,
+ *   files: FilesApi,
+ *   folders: FoldersApi,
+ *   forms: FormsApi,
+ *   inspectionPlans: InspectionPlansApi,
+ *   projectTemplates: ProjectTemplatesApi,
+ *   tasks: TasksApi,
+ *   testPlans: TestPlansApi,
+ *   users: UsersApi,
+ *   versionSets: VersionSetsApi,
+ *   workPackages: WorkPackagesApi
+ * }}
+ */
+function createClient({ baseUrl, apiKey } = {}) {
+  const configuration = new Configuration({ baseUrl, apiKey });
+  const apiClient = new ApiClient(configuration);
+
+  return {
+    projects: new ProjectsApi(apiClient),
+    companies: new CompaniesApi(apiClient),
+    companyCatalog: new CompanyCatalogApi(apiClient),
+    fileAreas: new FileAreasApi(apiClient),
+    fileRevisions: new FileRevisionsApi(apiClient),
+    fileUpload: new FileUploadApi(apiClient),
+    files: new FilesApi(apiClient),
+    folders: new FoldersApi(apiClient),
+    forms: new FormsApi(apiClient),
+    inspectionPlans: new InspectionPlansApi(apiClient),
+    projectTemplates: new ProjectTemplatesApi(apiClient),
+    tasks: new TasksApi(apiClient),
+    testPlans: new TestPlansApi(apiClient),
+    users: new UsersApi(apiClient),
+    versionSets: new VersionSetsApi(apiClient),
+    workPackages: new WorkPackagesApi(apiClient),
+  };
+}
+
+module.exports = {
+  createClient,
+  Configuration,
+  ApiClient,
+  CompaniesApi,
+  CompanyCatalogApi,
+  FileAreasApi,
+  FileRevisionsApi,
+  FileUploadApi,
+  FilesApi,
+  FoldersApi,
+  FormsApi,
+  InspectionPlansApi,
+  ProjectTemplatesApi,
+  ProjectsApi,
+  TasksApi,
+  TestPlansApi,
+  UsersApi,
+  VersionSetsApi,
+  WorkPackagesApi,
+  // Utilities
+  DaluxError,
+  NotFoundError,
+  ApiError,
+  ValidationError,
+  AuthenticationError,
+  RateLimitError,
+  hasNextPage,
+  getNextBookmark,
+  paginate,
+  findByField,
+  findAllByField,
+  validateProjectId,
+  validateFileAreaId,
+  validateFolderId,
+  resolveFileAreaByName,
+  resolveFolderIdFromNamedPath,
+};

package/src/utils/errors.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Base exception for all Dalux API errors.
+ */
+class DaluxError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+/**
+ * Resource not found (HTTP 404).
+ */
+class NotFoundError extends DaluxError {}
+
+/**
+ * API request failed (4xx / 5xx other than 401, 404, 429).
+ */
+class ApiError extends DaluxError {}
+
+/**
+ * Input validation failed.
+ */
+class ValidationError extends DaluxError {}
+
+/**
+ * Authentication failed (HTTP 401).
+ */
+class AuthenticationError extends DaluxError {}
+
+/**
+ * Rate limit exceeded (HTTP 429).
+ */
+class RateLimitError extends DaluxError {}
+
+module.exports = {
+  DaluxError,
+  NotFoundError,
+  ApiError,
+  ValidationError,
+  AuthenticationError,
+  RateLimitError,
+};

package/src/utils/index.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { DaluxError, NotFoundError, ApiError, ValidationError, AuthenticationError, RateLimitError } = require('./errors');
+const { hasNextPage, getNextBookmark, paginate } = require('./pagination');
+const { findByField, findAllByField } = require('./search');
+const { validateProjectId, validateFileAreaId, validateFolderId } = require('./validation');
+const { resolveFileAreaByName, resolveFolderIdFromNamedPath } = require('./pathResolver');
+
+module.exports = {
+  DaluxError,
+  NotFoundError,
+  ApiError,
+  ValidationError,
+  AuthenticationError,
+  RateLimitError,
+  hasNextPage,
+  getNextBookmark,
+  paginate,
+  findByField,
+  findAllByField,
+  validateProjectId,
+  validateFileAreaId,
+  validateFolderId,
+  resolveFileAreaByName,
+  resolveFolderIdFromNamedPath,
+};

package/src/utils/pagination.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * Check whether an API response has a next page link.
+ * @param {object} response
+ * @returns {boolean}
+ */
+function hasNextPage(response) {
+  if (!response) return false;
+  const links = response.links || [];
+  return links.some((l) => l.rel === 'nextPage');
+}
+
+/**
+ * Extract the bookmark for the next page from an API response.
+ * @param {object} response
+ * @returns {string|null}
+ */
+function getNextBookmark(response) {
+  const links = (response && response.links) || [];
+  const nextLink = links.find((l) => l.rel === 'nextPage');
+  if (!nextLink) return null;
+  try {
+    return new URL(nextLink.href).searchParams.get('bookmark');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generic pagination handler: follows bookmark pages until exhausted.
+ *
+ * @param {string} endpoint - API path.
+ * @param {object} client - ApiClient instance.
+ * @param {object} [params] - Base query parameters.
+ * @param {boolean} [verbose=false] - Log progress to console.
+ * @param {string} [itemAccessor='items'] - Key to read items from each response.
+ * @returns {Promise<any[]>} All items across all pages.
+ */
+async function paginate(endpoint, client, params = {}, verbose = false, itemAccessor = 'items') {
+  const allItems = [];
+  let currentParams = { ...params };
+  let pageCount = 0;
+  const seenBookmarks = new Set();
+
+  while (true) {
+    pageCount += 1;
+    const response = await client.get(endpoint, currentParams);
+    if (!response) break;
+
+    const items = response[itemAccessor] || [];
+    allItems.push(...items);
+
+    if (verbose) {
+      const meta = response.metadata || {};
+      const remaining = meta.totalRemainingItems ?? 0;
+      console.log(
+        `Page ${pageCount}: ${items.length} items, Total: ${allItems.length}, Remaining: ${remaining}`,
+      );
+    }
+
+    if (!hasNextPage(response)) break;
+
+    const bookmark = getNextBookmark(response);
+    if (!bookmark) break;
+    if (seenBookmarks.has(bookmark)) {
+      if (verbose) {
+        console.log(`Detected duplicate bookmark '${bookmark}', stopping pagination to prevent infinite loop`);
+      }
+      break;
+    }
+    seenBookmarks.add(bookmark);
+    currentParams = { ...params, bookmark };
+  }
+
+  if (verbose) {
+    console.log(`Pagination complete. Total items retrieved: ${allItems.length}`);
+  }
+  return allItems;
+}
+
+module.exports = { hasNextPage, getNextBookmark, paginate };

package/src/utils/pathResolver.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { findByField } = require('./search');
+
+/**
+ * Resolve a file area by its displayed name for a project.
+ *
+ * @param {object} apiClient - ApiClient instance.
+ * @param {string} projectId
+ * @param {string} fileAreaName
+ * @param {object} [fileAreasCache] - Optional mutable cache {name -> fileArea item}.
+ * @returns {Promise<object|null>} File area item or null.
+ */
+async function resolveFileAreaByName(apiClient, projectId, fileAreaName, fileAreasCache) {
+  if (fileAreasCache && fileAreasCache[fileAreaName]) {
+    return fileAreasCache[fileAreaName];
+  }
+
+  // Inline import to avoid circular deps
+  const FileAreasApi = require('../api/FileAreasApi');
+  const response = await new FileAreasApi(apiClient).getFileAreas(projectId);
+  const items = (response && response.items) || [];
+
+  if (fileAreasCache) {
+    for (const item of items) {
+      const name = (item.data || {}).fileAreaName || (item.data || {}).name || item.fileAreaName || item.name;
+      if (name) fileAreasCache[name] = item;
+    }
+  }
+
+  return (
+    findByField(items, 'fileAreaName', fileAreaName, (x) => x.data || x) ||
+    findByField(items, 'name', fileAreaName, (x) => x.data || x)
+  );
+}
+
+/**
+ * Resolve "FileAreaName/Folder/SubFolder" to { fileAreaId, folderId }.
+ *
+ * @param {object} apiClient - ApiClient instance.
+ * @param {string} projectId
+ * @param {string} path - e.g. "Files/4_Design/C07_Geometry"
+ * @param {object} [opts]
+ * @param {boolean} [opts.verbose=false]
+ * @param {object} [opts.fileAreasCache]
+ * @param {object} [opts.foldersCache]
+ * @param {object} [opts.resolvedPathsCache]
+ * @returns {Promise<{ fileAreaId: string|null, folderId: string|null }>}
+ */
+async function resolveFolderIdFromNamedPath(apiClient, projectId, path, opts = {}) {
+  const { verbose = false, fileAreasCache, foldersCache, resolvedPathsCache } = opts;
+
+  if (resolvedPathsCache && resolvedPathsCache[path]) {
+    return resolvedPathsCache[path];
+  }
+
+  const parts = path.split('/').map((p) => p.trim()).filter(Boolean);
+  if (parts.length < 2) return { fileAreaId: null, folderId: null };
+
+  const fileAreaName = parts[0];
+  const folderNames = parts.slice(1);
+
+  const fileAreaItem = await resolveFileAreaByName(apiClient, projectId, fileAreaName, fileAreasCache);
+  if (!fileAreaItem) {
+    if (verbose) console.log(`Could not resolve file area: ${fileAreaName}`);
+    return { fileAreaId: null, folderId: null };
+  }
+
+  const fileAreaId =
+    (fileAreaItem.data || {}).fileAreaId ||
+    (fileAreaItem.data || {}).id ||
+    fileAreaItem.fileAreaId ||
+    fileAreaItem.id;
+
+  // Fetch all folders for this file area (with cache)
+  let folders = foldersCache && foldersCache[fileAreaId];
+  if (!folders) {
+    if (verbose) {
+      console.log(`GET /5.1/projects/${projectId}/file_areas/${fileAreaId}/folders`);
+    }
+    const FoldersApi = require('../api/FoldersApi');
+    folders = await new FoldersApi(apiClient).getAllFolders(projectId, fileAreaId);
+    if (foldersCache) foldersCache[fileAreaId] = folders;
+  }
+
+  // Build a lookup: (parentFolderId, folderName) -> folder
+  // Collect all valid folder IDs first
+  const allFolderIds = new Set();
+  for (const f of folders) {
+    const data = f.data || f;
+    const fid = data.folderId || data.id;
+    if (fid) allFolderIds.add(fid);
+  }
+
+  const folderIndex = new Map();
+  for (const f of folders) {
+    const data = f.data || f;
+    const fid = data.folderId || data.id;
+    const pid = data.parentFolderId || data.parentId || null;
+    const name = data.folderName || data.name || '';
+    // Treat root-level folders (parent not in folder list) as children of null
+    const parentKey = allFolderIds.has(pid) ? pid : null;
+    folderIndex.set(`${parentKey}|||${name}`, fid);
+  }
+
+  let parentFolderId = null;
+  for (const folderName of folderNames) {
+    const key = `${parentFolderId}|||${folderName}`;
+    const fid = folderIndex.get(key);
+    if (!fid) {
+      if (verbose) console.log(`Could not resolve folder segment: ${folderName}`);
+      const result = { fileAreaId, folderId: null };
+      if (resolvedPathsCache) resolvedPathsCache[path] = result;
+      return result;
+    }
+    parentFolderId = fid;
+  }
+
+  const result = { fileAreaId, folderId: parentFolderId };
+  if (resolvedPathsCache) resolvedPathsCache[path] = result;
+  return result;
+}
+
+module.exports = { resolveFileAreaByName, resolveFolderIdFromNamedPath };

package/src/utils/search.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Find the first item in an iterable where a field equals a value.
+ *
+ * @param {any[]} items
+ * @param {string} field - Field name (supports camelCase and snake_case).
+ * @param {any} value - Value to match.
+ * @param {Function} [accessor] - Optional function to extract data from each item.
+ * @returns {any|null}
+ */
+function findByField(items, field, value, accessor) {
+  const get = accessor || ((x) => x);
+  for (const item of items) {
+    const itemData = get(item);
+    if (itemData && typeof itemData === 'object') {
+      if (itemData[field] === value) return item;
+      // Also try snake_case ↔ camelCase conversion
+      const camel = snakeToCamel(field);
+      if (camel !== field && itemData[camel] === value) return item;
+      const snake = camelToSnake(field);
+      if (snake !== field && itemData[snake] === value) return item;
+    }
+  }
+  return null;
+}
+
+/**
+ * Find all items in an iterable where a field equals a value.
+ *
+ * @param {any[]} items
+ * @param {string} field - Field name.
+ * @param {any} value - Value to match.
+ * @param {Function} [accessor] - Optional function to extract data from each item.
+ * @returns {any[]}
+ */
+function findAllByField(items, field, value, accessor) {
+  const get = accessor || ((x) => x);
+  return items.filter((item) => {
+    const itemData = get(item);
+    if (!itemData || typeof itemData !== 'object') return false;
+    if (itemData[field] === value) return true;
+    const camel = snakeToCamel(field);
+    if (camel !== field && itemData[camel] === value) return true;
+    const snake = camelToSnake(field);
+    if (snake !== field && itemData[snake] === value) return true;
+    return false;
+  });
+}
+
+/** @param {string} s */
+function snakeToCamel(s) {
+  return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** @param {string} s */
+function camelToSnake(s) {
+  return s.replace(/([A-Z])/g, (c) => `_${c.toLowerCase()}`);
+}
+
+module.exports = { findByField, findAllByField };

package/src/utils/validation.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { ValidationError } = require('./errors');
+
+/**
+ * Validate that projectId is a non-empty string.
+ * @param {string} projectId
+ */
+function validateProjectId(projectId) {
+  if (!projectId || typeof projectId !== 'string' || projectId.trim().length === 0) {
+    throw new ValidationError('projectId must be a non-empty string');
+  }
+}
+
+/**
+ * Validate that fileAreaId is a non-empty string.
+ * @param {string} fileAreaId
+ */
+function validateFileAreaId(fileAreaId) {
+  if (!fileAreaId || typeof fileAreaId !== 'string' || fileAreaId.trim().length === 0) {
+    throw new ValidationError('fileAreaId must be a non-empty string');
+  }
+}
+
+/**
+ * Validate that folderId is a non-empty string (or null/undefined).
+ * @param {string|null|undefined} folderId
+ */
+function validateFolderId(folderId) {
+  if (folderId == null) return;
+  if (typeof folderId !== 'string' || folderId.trim().length === 0) {
+    throw new ValidationError('folderId must be a non-empty string');
+  }
+}
+
+module.exports = { validateProjectId, validateFileAreaId, validateFolderId };