dalux-build-api 1.1.3 → 2.0.0

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 };