dalux-build-api 1.1.5 → 2.0.1

package/src/api/TasksApi.js

@@ -1,5 +1,15 @@
 'use strict';
 
+const { convertToModel, convertToModelList } = require('../models/convert');
+const {
+  TaskSchema,
+  TaskChangeSchema,
+  TasksListResponseSchema,
+  TaskResponseSchema,
+  TaskChangesSchema,
+  TaskAttachmentsListResponseSchema,
+} = require('../models/tasks');
+
 /**
  * Build query params for GET /5.2/projects/.../tasks (OData).
  * If params contains typeId and no $filter, expands to
@@ -39,8 +49,9 @@ class TasksApi {
    *   OData $filter on task type, or pass $filter (and other OData options) directly.
    * @returns {Promise<object>}
    */
-  getProjectTasks(projectId, params = {}) {
-    return this._client.get(`/5.2/projects/${projectId}/tasks`, normalizeTaskParams(params));
+  async getProjectTasks(projectId, params = {}) {
+    const response = await this._client.get(`/5.2/projects/${projectId}/tasks`, normalizeTaskParams(params));
+    return convertToModel(response, TasksListResponseSchema, 'TasksListResponse');
   }
 
   /**
@@ -119,7 +130,7 @@ class TasksApi {
     if (verbose) {
       console.log(`Done. Total tasks retrieved: ${allItems.length}`);
     }
-    return allItems;
+    return convertToModelList(allItems, TaskSchema, 'Task');
   }
 
   /**
@@ -129,8 +140,9 @@ class TasksApi {
    * @param {string} taskId
    * @returns {Promise<object>}
    */
-  getTask(projectId, taskId) {
-    return this._client.get(`/3.3/projects/${projectId}/tasks/${taskId}`);
+  async getTask(projectId, taskId) {
+    const response = await this._client.get(`/3.3/projects/${projectId}/tasks/${taskId}`);
+    return convertToModel(response, TaskResponseSchema, 'TaskResponse');
   }
 
   /**
@@ -140,8 +152,9 @@ class TasksApi {
    * @param {object} [params] - Optional filters (e.g. updatedAfter)
    * @returns {Promise<object>}
    */
-  getProjectTaskChanges(projectId, params = {}) {
-    return this._client.get(`/2.2/projects/${projectId}/tasks/changes`, params);
+  async getProjectTaskChanges(projectId, params = {}) {
+    const response = await this._client.get(`/2.2/projects/${projectId}/tasks/changes`, params);
+    return convertToModel(response, TaskChangesSchema, 'TaskChanges');
   }
 
   /**
@@ -151,8 +164,9 @@ class TasksApi {
    * @param {object} [params] - Optional filters (e.g. updatedAfter)
    * @returns {Promise<object>}
    */
-  getProjectTaskAttachments(projectId, params = {}) {
-    return this._client.get(`/1.1/projects/${projectId}/tasks/attachments`, params);
+  async getProjectTaskAttachments(projectId, params = {}) {
+    const response = await this._client.get(`/1.1/projects/${projectId}/tasks/attachments`, params);
+    return convertToModel(response, TaskAttachmentsListResponseSchema, 'TaskAttachmentsListResponse');
   }
 
   /**
@@ -164,12 +178,13 @@ class TasksApi {
    */
   async getAllProjectTaskChanges(projectId, params = {}, verbose = false) {
     const { paginate } = require('../utils/pagination');
-    return paginate(
+    const raw = await paginate(
       `/2.2/projects/${projectId}/tasks/changes`,
       this._client,
       params,
       verbose,
     );
+    return convertToModelList(raw, TaskChangeSchema, 'TaskChange');
   }
 }
 

package/src/api/TestPlansApi.js

@@ -1,5 +1,18 @@
 'use strict';
 
+const { convertToModel, convertToModelList } = require('../models/convert');
+const { paginate } = require('../utils/pagination');
+const {
+  TestPlanSchema,
+  TestPlanItemSchema,
+  TestPlanItemZoneSchema,
+  TestPlanRegistrationSchema,
+  TestPlansListResponseSchema,
+  TestPlanItemsListResponseSchema,
+  TestPlanItemZonesListResponseSchema,
+  TestPlanRegistrationsListResponseSchema,
+} = require('../models/testPlans');
+
 /**
  * API methods for test plans.
  */
@@ -16,10 +29,27 @@ class TestPlansApi {
    * GET /1.2/projects/{projectId}/testPlans
    * @param {string} projectId
    * @param {object} [params]
-   * @returns {Promise<object>}
+   * @param {boolean} [fullResponse=false]
+   * @returns {Promise<object[]|object>}
    */
-  listTestPlans(projectId, params = {}) {
-    return this._client.get(`/1.2/projects/${projectId}/testPlans`, params);
+  async listTestPlans(projectId, params = {}, fullResponse = false) {
+    const response = await this._client.get(`/1.2/projects/${projectId}/testPlans`, params);
+    const result = convertToModel(
+      response,
+      TestPlansListResponseSchema,
+      'TestPlansListResponse',
+    );
+    return fullResponse ? result : (result?.items || []);
+  }
+
+  async getAllTestPlans(projectId, params = {}, verbose = false) {
+    const items = await paginate(
+      `/1.2/projects/${projectId}/testPlans`,
+      this._client,
+      params,
+      verbose,
+    );
+    return convertToModelList(items, TestPlanSchema, 'TestPlan');
   }
 
   /**
@@ -29,8 +59,24 @@ class TestPlansApi {
    * @param {object} [params]
    * @returns {Promise<object>}
    */
-  listTestPlanItems(projectId, params = {}) {
-    return this._client.get(`/1.1/projects/${projectId}/testPlanItems`, params);
+  async listTestPlanItems(projectId, params = {}, fullResponse = false) {
+    const response = await this._client.get(`/1.1/projects/${projectId}/testPlanItems`, params);
+    const result = convertToModel(
+      response,
+      TestPlanItemsListResponseSchema,
+      'TestPlanItemsListResponse',
+    );
+    return fullResponse ? result : (result?.items || []);
+  }
+
+  async getAllTestPlanItems(projectId, params = {}, verbose = false) {
+    const items = await paginate(
+      `/1.1/projects/${projectId}/testPlanItems`,
+      this._client,
+      params,
+      verbose,
+    );
+    return convertToModelList(items, TestPlanItemSchema, 'TestPlanItem');
   }
 
   /**
@@ -40,8 +86,24 @@ class TestPlansApi {
    * @param {object} [params]
    * @returns {Promise<object>}
    */
-  listTestPlanItemZones(projectId, params = {}) {
-    return this._client.get(`/1.1/projects/${projectId}/testPlanItemZones`, params);
+  async listTestPlanItemZones(projectId, params = {}, fullResponse = false) {
+    const response = await this._client.get(`/1.1/projects/${projectId}/testPlanItemZones`, params);
+    const result = convertToModel(
+      response,
+      TestPlanItemZonesListResponseSchema,
+      'TestPlanItemZonesListResponse',
+    );
+    return fullResponse ? result : (result?.items || []);
+  }
+
+  async getAllTestPlanItemZones(projectId, params = {}, verbose = false) {
+    const items = await paginate(
+      `/1.1/projects/${projectId}/testPlanItemZones`,
+      this._client,
+      params,
+      verbose,
+    );
+    return convertToModelList(items, TestPlanItemZoneSchema, 'TestPlanItemZone');
   }
 
   /**
@@ -51,8 +113,24 @@ class TestPlansApi {
    * @param {object} [params]
    * @returns {Promise<object>}
    */
-  listTestPlanRegistrations(projectId, params = {}) {
-    return this._client.get(`/1.1/projects/${projectId}/testPlanRegistrations`, params);
+  async listTestPlanRegistrations(projectId, params = {}, fullResponse = false) {
+    const response = await this._client.get(`/1.1/projects/${projectId}/testPlanRegistrations`, params);
+    const result = convertToModel(
+      response,
+      TestPlanRegistrationsListResponseSchema,
+      'TestPlanRegistrationsListResponse',
+    );
+    return fullResponse ? result : (result?.items || []);
+  }
+
+  async getAllTestPlanRegistrations(projectId, params = {}, verbose = false) {
+    const items = await paginate(
+      `/1.1/projects/${projectId}/testPlanRegistrations`,
+      this._client,
+      params,
+      verbose,
+    );
+    return convertToModelList(items, TestPlanRegistrationSchema, 'TestPlanRegistration');
   }
 }
 

package/src/api/UsersApi.js

@@ -1,5 +1,8 @@
 'use strict';
 
+const { convertToModel } = require('../models/convert');
+const { UserResponseSchema, UsersListResponseSchema } = require('../models/users');
+
 /**
  * API methods for users.
  */
@@ -15,10 +18,11 @@ class UsersApi {
    * Get a specific user.
    * GET /1.1/users/{userId}
    * @param {string} userId
-   * @returns {Promise<object>}
+   * @returns {Promise<object>} UserResponse ({ data: User, links? })
    */
-  getUser(userId) {
-    return this._client.get(`/1.1/users/${userId}`);
+  async getUser(userId) {
+    const response = await this._client.get(`/1.1/users/${userId}`);
+    return convertToModel(response, UserResponseSchema, 'UserResponse');
   }
 
   /**
@@ -26,10 +30,11 @@ class UsersApi {
    * GET /1.2/projects/{projectId}/users
    * @param {string} projectId
    * @param {object} [params]
-   * @returns {Promise<object>}
+   * @returns {Promise<object>} UsersListResponse ({ items: ProjectUser[], metadata?, links? })
    */
-  listProjectUsers(projectId, params = {}) {
-    return this._client.get(`/1.2/projects/${projectId}/users`, params);
+  async listProjectUsers(projectId, params = {}) {
+    const response = await this._client.get(`/1.2/projects/${projectId}/users`, params);
+    return convertToModel(response, UsersListResponseSchema, 'UsersListResponse');
   }
 
   /**

package/src/api/VersionSetsApi.js

@@ -1,5 +1,9 @@
 'use strict';
 
+const { convertToModel } = require('../models/convert');
+const { VersionSetsListResponseSchema, VersionSetResponseSchema } = require('../models/versionSets');
+const { FilesListResponseSchema } = require('../models/files');
+
 /**
  * API methods for version sets.
  */
@@ -16,10 +20,11 @@ class VersionSetsApi {
    * GET /2.1/projects/{projectId}/version_sets
    * @param {string} projectId
    * @param {object} [params]
-   * @returns {Promise<object>}
+   * @returns {Promise<object>} VersionSetsListResponse ({ items: VersionSet[], metadata?, links? })
    */
-  getVersionSets(projectId, params = {}) {
-    return this._client.get(`/2.1/projects/${projectId}/version_sets`, params);
+  async getVersionSets(projectId, params = {}) {
+    const response = await this._client.get(`/2.1/projects/${projectId}/version_sets`, params);
+    return convertToModel(response, VersionSetsListResponseSchema, 'VersionSetsListResponse');
   }
 
   /**
@@ -27,10 +32,11 @@ class VersionSetsApi {
    * GET /2.0/projects/{projectId}/version_sets/{versionSetId}
    * @param {string} projectId
    * @param {string} versionSetId
-   * @returns {Promise<object>}
+   * @returns {Promise<object>} VersionSetResponse ({ data: VersionSet, links? })
    */
-  getVersionSet(projectId, versionSetId) {
-    return this._client.get(`/2.0/projects/${projectId}/version_sets/${versionSetId}`);
+  async getVersionSet(projectId, versionSetId) {
+    const response = await this._client.get(`/2.0/projects/${projectId}/version_sets/${versionSetId}`);
+    return convertToModel(response, VersionSetResponseSchema, 'VersionSetResponse');
   }
 
   /**
@@ -39,13 +45,14 @@ class VersionSetsApi {
    * @param {string} projectId
    * @param {string} fileAreaId
    * @param {object} [params]
-   * @returns {Promise<object>}
+   * @returns {Promise<object>} VersionSetsListResponse
    */
-  listFileAreaVersionSets(projectId, fileAreaId, params = {}) {
-    return this._client.get(
+  async listFileAreaVersionSets(projectId, fileAreaId, params = {}) {
+    const response = await this._client.get(
       `/2.1/projects/${projectId}/file_areas/${fileAreaId}/version_sets`,
       params,
     );
+    return convertToModel(response, VersionSetsListResponseSchema, 'VersionSetsListResponse');
   }
 
   /**
@@ -54,13 +61,14 @@ class VersionSetsApi {
    * @param {string} projectId
    * @param {string} versionSetId
    * @param {object} [params]
-   * @returns {Promise<object>}
+   * @returns {Promise<object>} FilesListResponse (cross-endpoint reuse of the Files model, matches Python)
    */
-  listVersionSetFiles(projectId, versionSetId, params = {}) {
-    return this._client.get(
+  async listVersionSetFiles(projectId, versionSetId, params = {}) {
+    const response = await this._client.get(
       `/3.0/projects/${projectId}/version_sets/${versionSetId}/files`,
       params,
     );
+    return convertToModel(response, FilesListResponseSchema, 'FilesListResponse');
   }
 }
 

package/src/api/WorkPackagesApi.js

@@ -1,5 +1,8 @@
 'use strict';
 
+const { convertToModel } = require('../models/convert');
+const { WorkPackagesListResponseSchema } = require('../models/workPackages');
+
 /**
  * API methods for work packages on a project.
  */
@@ -16,10 +19,11 @@ class WorkPackagesApi {
    * GET /1.0/projects/{projectId}/workpackages
    * @param {string} projectId
    * @param {object} [params]
-   * @returns {Promise<object>}
+   * @returns {Promise<object>} WorkPackagesListResponse ({ items: WorkPackage[], metadata?, links? })
    */
-  listWorkPackages(projectId, params = {}) {
-    return this._client.get(`/1.0/projects/${projectId}/workpackages`, params);
+  async listWorkPackages(projectId, params = {}) {
+    const response = await this._client.get(`/1.0/projects/${projectId}/workpackages`, params);
+    return convertToModel(response, WorkPackagesListResponseSchema, 'WorkPackagesListResponse');
   }
 }
 

package/src/browser.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const RESOURCES = [
+  'projects',
+  'companies',
+  'companyCatalog',
+  'fileAreas',
+  'fileRevisions',
+  'fileUpload',
+  'files',
+  'folders',
+  'forms',
+  'inspectionPlans',
+  'projectTemplates',
+  'tasks',
+  'testPlans',
+  'users',
+  'versionSets',
+  'workPackages',
+];
+
+class DaluxProxyError extends Error {
+  constructor(message, { name = 'DaluxProxyError', status, details } = {}) {
+    super(message);
+    this.name = name;
+    this.status = status;
+    this.details = details;
+  }
+}
+
+/**
+ * Create a browser-safe Dalux client backed by a same-origin server route.
+ * The Dalux API key remains on the server; this client never accepts one.
+ *
+ * @param {object} [options]
+ * @param {string} [options.url='/api/dalux']
+ * @param {typeof fetch} [options.fetch]
+ * @param {Record<string, string>} [options.headers]
+ */
+function createBrowserClient({ url = '/api/dalux', fetch: fetchImpl, headers = {} } = {}) {
+  const request = fetchImpl || globalThis.fetch;
+  if (typeof request !== 'function') {
+    throw new Error('A fetch implementation is required');
+  }
+
+  const invoke = async (resource, method, args) => {
+    const response = await request(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify({ resource, method, args }),
+    });
+
+    let payload;
+    try {
+      payload = await response.json();
+    } catch {
+      throw new DaluxProxyError(`Dalux proxy returned HTTP ${response.status} without JSON`, {
+        status: response.status,
+      });
+    }
+
+    if (!response.ok || !payload.ok) {
+      const error = payload.error || {};
+      throw new DaluxProxyError(error.message || `Dalux proxy returned HTTP ${response.status}`, {
+        name: error.name,
+        status: response.status,
+        details: error.details,
+      });
+    }
+    return payload.data;
+  };
+
+  return Object.fromEntries(RESOURCES.map((resource) => [
+    resource,
+    new Proxy({}, {
+      get(_target, method) {
+        if (typeof method !== 'string' || method === 'then') return undefined;
+        return (...args) => invoke(resource, method, args);
+      },
+    }),
+  ]));
+}
+
+module.exports = { createBrowserClient, DaluxProxyError };

package/src/index.js

@@ -39,6 +39,8 @@ const {
   resolveFolderIdFromNamedPath,
 } = require('./utils');
 
+const models = require('./models');
+
 /**
  * Create a fully configured Dalux Build API client.
  *
@@ -125,4 +127,7 @@ module.exports = {
   validateFolderId,
   resolveFileAreaByName,
   resolveFolderIdFromNamedPath,
+  // Data models (zod schemas) - both `models.FolderSchema` and top-level `FolderSchema` work
+  models,
+  ...models,
 };

package/src/models/common.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { z } = require('zod');
+
+/**
+ * API response link. Mirrors python/dalux_build/models/common.py::Link.
+ */
+const LinkSchema = z.object({
+  rel: z.string(),
+  href: z.string(),
+  method: z.string().nullish(),
+});
+
+/**
+ * Response metadata with pagination info. Mirrors common.py::Metadata.
+ */
+const MetadataSchema = z.object({
+  totalItems: z.number().nullish(),
+  totalRemainingItems: z.number().nullish(),
+});
+
+module.exports = { LinkSchema, MetadataSchema };

package/src/models/companies/index.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const { ProjectCompanySchema } = require('../projects');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/** Mirrors models/companies/models.py, which re-exports ProjectCompany. */
+const CompaniesListResponseSchema = listResponseSchema(ProjectCompanySchema);
+const CompanyResponseSchema = singleResponseSchema(ProjectCompanySchema);
+
+module.exports = {
+  ProjectCompanySchema,
+  CompaniesListResponseSchema,
+  CompanyResponseSchema,
+};

package/src/models/companyCatalog/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/**
+ * Mirrors models/company_catalog/responses.py. These are exported for name
+ * parity but, like their Python counterparts, are NOT what the API layer
+ * actually uses — company_catalog.py's get_companies/get_company return
+ * CompaniesListResponse/CompanyResponse (typed ProjectCompany) instead.
+ * See src/api/CompanyCatalogApi.js.
+ */
+const CompanyCatalogListResponseSchema = listResponseSchema(z.any());
+const CompanyCatalogResponseSchema = singleResponseSchema(z.any());
+
+module.exports = {
+  CompanyCatalogListResponseSchema,
+  CompanyCatalogResponseSchema,
+};

package/src/models/convert.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const { z } = require('zod');
+const { ValidationError } = require('../utils/errors');
+const { unwrapData } = require('./helpers');
+
+/**
+ * Validate and convert a raw API response into a typed model, throwing a
+ * ValidationError if the response doesn't match `schema`. Mirrors
+ * response_converter.py::convert_to_model, without its legacy-compat
+ * fallback branches (the JS test suite ships schema-valid fixtures).
+ * @param {*} response
+ * @param {import('zod').ZodTypeAny} schema
+ * @param {string} [schemaName]
+ * @returns {*}
+ */
+function convertToModel(response, schema, schemaName = 'model') {
+  if (response === null || response === undefined) return null;
+  try {
+    return schema.parse(response);
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      throw new ValidationError(`Failed to convert response to ${schemaName}: ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Validate and convert a list of raw items into typed models.
+ * Used by get_all_* pagination methods, which convert each item after
+ * pagination has already collected the raw list.
+ * @param {Array} items
+ * @param {import('zod').ZodTypeAny} itemSchema
+ * @param {string} [schemaName]
+ * @returns {Array}
+ */
+function convertToModelList(items, itemSchema, schemaName = 'model') {
+  if (!Array.isArray(items)) return [];
+  const wrapped = unwrapData(itemSchema);
+  return items.map((item) => convertToModel(item, wrapped, schemaName));
+}
+
+module.exports = { convertToModel, convertToModelList };

package/src/models/fileAreas/index.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/** Mirrors models/file_areas/models.py::FileArea (all fields required). */
+const FileAreaSchema = z.object({
+  fileAreaId: z.string(),
+  fileAreaName: z.string(),
+  fileAreaType: z.string(),
+});
+
+const FileAreasListResponseSchema = listResponseSchema(FileAreaSchema);
+const FileAreaResponseSchema = singleResponseSchema(FileAreaSchema);
+
+module.exports = {
+  FileAreaSchema,
+  FileAreasListResponseSchema,
+  FileAreaResponseSchema,
+};

package/src/models/fileRevisions/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const { z } = require('zod');
+
+/**
+ * Mirrors models/file_revisions/models.py::FileRevision — an empty
+ * placeholder in Python too (get_file_revision_content returns raw
+ * binary/content in both packages, so there's nothing to validate).
+ */
+const FileRevisionSchema = z.object({}).passthrough();
+
+module.exports = { FileRevisionSchema };

package/src/models/fileUpload/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const { z } = require('zod');
+
+/**
+ * Mirrors models/file_upload/models.py::FileUpload — empty placeholder in
+ * Python too; upload/part/finalize responses are provider-specific and
+ * stay raw in both packages.
+ */
+const FileUploadSchema = z.object({}).passthrough();
+
+module.exports = { FileUploadSchema };