dalux-build-api 1.1.3 → 2.0.0

package/src/models/index.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * Zod schemas for Dalux Build API responses. Mirrors the public surface of
+ * python/dalux_build/models/__init__.py, with a `Schema` suffix on every
+ * export name (these are zod schema objects, not constructible classes).
+ */
+
+const { LinkSchema, MetadataSchema } = require('./common');
+
+const {
+  ProjectSchema,
+  ProjectModuleSchema,
+  ProjectMetadataSchema,
+  ProjectTemplateSchema,
+  ProjectCompanySchema,
+  ProjectsListResponseSchema,
+  ProjectResponseSchema,
+} = require('./projects');
+
+const { FileAreaSchema, FileAreasListResponseSchema, FileAreaResponseSchema } = require('./fileAreas');
+
+const { FolderSchema, FoldersListResponseSchema, FolderResponseSchema } = require('./folders');
+
+const {
+  FileSchema,
+  ReferenceSchema,
+  FileNameFilterSchema,
+  FileIntegerPropertySchema,
+  FileDatePropertySchema,
+  FileTextPropertySchema,
+  FileReferencePropertySchema,
+  FilePropertyFieldSchema,
+  FilesListResponseSchema,
+  FileResponseSchema,
+} = require('./files');
+
+const { VersionSetSchema, VersionSetsListResponseSchema, VersionSetResponseSchema } = require('./versionSets');
+
+const { UserSchema, ProjectUserSchema, UsersListResponseSchema, UserResponseSchema } = require('./users');
+
+const { CompaniesListResponseSchema, CompanyResponseSchema } = require('./companies');
+
+const { CompanyCatalogListResponseSchema, CompanyCatalogResponseSchema } = require('./companyCatalog');
+
+const { InspectionPlanSchema, InspectionPlansListResponseSchema } = require('./inspectionPlans');
+
+const { TestPlanSchema, TestPlansListResponseSchema } = require('./testPlans');
+
+const { FormSchema, FormsListResponseSchema, FormResponseSchema } = require('./forms');
+
+const {
+  TaskSchema,
+  TaskAttachmentSchema,
+  TaskChangeSchema,
+  TaskChangeActorSchema,
+  TaskChangeFieldsSchema,
+  TaskChangeLocationSchema,
+  TaskListParamsSchema,
+  TasksListResponseSchema,
+  TaskResponseSchema,
+  TaskChangeResponseSchema,
+  TaskChangesSchema,
+  TaskAttachmentsListResponseSchema,
+} = require('./tasks');
+
+const { FileRevisionSchema } = require('./fileRevisions');
+const { FileUploadSchema } = require('./fileUpload');
+const { WorkPackageSchema, WorkPackagesListResponseSchema } = require('./workPackages');
+
+module.exports = {
+  // Base
+  LinkSchema,
+  MetadataSchema,
+  // Projects
+  ProjectSchema,
+  ProjectModuleSchema,
+  ProjectMetadataSchema,
+  ProjectTemplateSchema,
+  ProjectCompanySchema,
+  ProjectsListResponseSchema,
+  ProjectResponseSchema,
+  // File Areas
+  FileAreaSchema,
+  FileAreasListResponseSchema,
+  FileAreaResponseSchema,
+  // Folders
+  FolderSchema,
+  FoldersListResponseSchema,
+  FolderResponseSchema,
+  // Files
+  FileSchema,
+  ReferenceSchema,
+  FileNameFilterSchema,
+  FileIntegerPropertySchema,
+  FileDatePropertySchema,
+  FileTextPropertySchema,
+  FileReferencePropertySchema,
+  FilePropertyFieldSchema,
+  FilesListResponseSchema,
+  FileResponseSchema,
+  // Version Sets
+  VersionSetSchema,
+  VersionSetsListResponseSchema,
+  VersionSetResponseSchema,
+  // Users
+  UserSchema,
+  ProjectUserSchema,
+  UsersListResponseSchema,
+  UserResponseSchema,
+  // Companies
+  CompaniesListResponseSchema,
+  CompanyResponseSchema,
+  // Company Catalog
+  CompanyCatalogListResponseSchema,
+  CompanyCatalogResponseSchema,
+  // Inspection Plans
+  InspectionPlanSchema,
+  InspectionPlansListResponseSchema,
+  // Test Plans
+  TestPlanSchema,
+  TestPlansListResponseSchema,
+  // Forms
+  FormSchema,
+  FormsListResponseSchema,
+  FormResponseSchema,
+  // Tasks
+  TaskSchema,
+  TaskAttachmentSchema,
+  TaskChangeSchema,
+  TaskChangeActorSchema,
+  TaskChangeFieldsSchema,
+  TaskChangeLocationSchema,
+  TaskListParamsSchema,
+  TasksListResponseSchema,
+  TaskResponseSchema,
+  TaskChangeResponseSchema,
+  TaskChangesSchema,
+  TaskAttachmentsListResponseSchema,
+  // Project Templates (same ProjectTemplateSchema as Projects, re-exported above)
+  // File Revisions
+  FileRevisionSchema,
+  // File Upload
+  FileUploadSchema,
+  // Work Packages
+  WorkPackageSchema,
+  WorkPackagesListResponseSchema,
+};

package/src/models/inspectionPlans/index.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema } = require('../helpers');
+
+/**
+ * Mirrors models/inspection_plans/models.py::InspectionPlan — an empty
+ * placeholder in Python, so list items stay untyped (unwrapped but
+ * otherwise unvalidated).
+ */
+const InspectionPlanSchema = z.any();
+
+const InspectionPlansListResponseSchema = listResponseSchema(InspectionPlanSchema);
+
+module.exports = {
+  InspectionPlanSchema,
+  InspectionPlansListResponseSchema,
+};

package/src/models/projectTemplates/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const { ProjectTemplateSchema } = require('../projects');
+
+/**
+ * Mirrors models/project_templates/models.py::ProjectTemplate — identical
+ * shape to projects/models.py::ProjectTemplate, so it's reused rather than
+ * duplicated. listProjectTemplates returns raw/unmodeled data in Python too
+ * (company-wide endpoint), so no response wrapper is defined here.
+ */
+module.exports = { ProjectTemplateSchema };

package/src/models/projects/index.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/** Mirrors models/projects/models.py::ProjectModule (empty placeholder, passthrough). */
+const ProjectModuleSchema = z.object({}).passthrough();
+
+/** Mirrors models/projects/models.py::Project. Note: `type` is the real JSON key (Python aliases project_type -> "type"). */
+const ProjectSchema = z.object({
+  projectId: z.string(),
+  projectName: z.string(),
+  type: z.string().nullish(),
+  projectTemplateId: z.string().nullish(),
+  address: z.string().nullish(),
+  number: z.string().nullish(),
+  created: z.string().nullish(),
+  closing: z.string().nullish(),
+  modules: z.array(ProjectModuleSchema).nullish(),
+});
+
+/** Mirrors models/projects/models.py::ProjectMetadata. */
+const ProjectMetadataSchema = z.object({
+  key: z.string(),
+  value: z.string().nullish(),
+});
+
+/** Mirrors models/projects/models.py::ProjectTemplate (also duplicated in project_templates/models.py — same shape). */
+const ProjectTemplateSchema = z.object({
+  projectTemplateId: z.string(),
+  name: z.string(),
+});
+
+/** Mirrors models/projects/models.py::ProjectCompany. */
+const ProjectCompanySchema = z.object({
+  companyId: z.string().nullish(),
+  name: z.string().nullish(),
+  vatNumber: z.string().nullish(),
+  address: z.string().nullish(),
+  city: z.string().nullish(),
+  postalCode: z.string().nullish(),
+  country: z.string().nullish(),
+  catalogCompanyId: z.string().nullish(),
+});
+
+const ProjectsListResponseSchema = listResponseSchema(ProjectSchema);
+const ProjectResponseSchema = singleResponseSchema(ProjectSchema);
+
+module.exports = {
+  ProjectModuleSchema,
+  ProjectSchema,
+  ProjectMetadataSchema,
+  ProjectTemplateSchema,
+  ProjectCompanySchema,
+  ProjectsListResponseSchema,
+  ProjectResponseSchema,
+};

package/src/models/tasks/index.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/** Mirrors models/tasks/models.py::Task (extra="allow" -> passthrough; only taskId is typed). */
+const TaskSchema = z.object({
+  taskId: z.string().nullish(),
+}).passthrough();
+
+/**
+ * Mirrors models/tasks/models.py::TaskListParams. Field names are the
+ * actual OData query keys (matches what src/api/TasksApi.js's
+ * normalizeTaskParams reads/writes) rather than Python's snake_case
+ * attribute names, since JS has no alias layer to bridge the two. These are
+ * developer-supplied query params (not API responses), so plain `.optional()`
+ * is fine.
+ */
+const TaskListParamsSchema = z.object({
+  typeId: z.string().optional(),
+  $filter: z.string().optional(),
+  $select: z.string().optional(),
+  $orderby: z.string().optional(),
+  $top: z.number().optional(),
+  $skip: z.number().optional(),
+  bookmark: z.string().optional(),
+}).passthrough();
+
+/** Mirrors models/tasks/models.py::TaskChangeActor. */
+const TaskChangeActorSchema = z.object({
+  userId: z.string().nullish(),
+  roleId: z.string().nullish(),
+  roleName: z.string().nullish(),
+  userName: z.string().nullish(),
+  name: z.string().nullish(),
+}).passthrough();
+
+/** Mirrors models/tasks/models.py::TaskChangeLocation (empty passthrough). */
+const TaskChangeLocationSchema = z.object({}).passthrough();
+
+/**
+ * Preprocesses the deadline field the same way Python's
+ * `normalize_deadline` field_validator does: unwraps API payloads where
+ * deadline is returned as an object instead of a bare string.
+ */
+const deadlineSchema = z.preprocess((value) => {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    if (value.empty === true) return undefined;
+    if ('value' in value) return value.value;
+    if ('date' in value) return value.date;
+    if ('datetime' in value) return value.datetime;
+  }
+  return value;
+}, z.string().nullish());
+
+/** Mirrors models/tasks/models.py::TaskChangeFields. */
+const TaskChangeFieldsSchema = z.object({
+  currentResponsible: TaskChangeActorSchema.nullish(),
+  assignedTo: TaskChangeActorSchema.nullish(),
+  title: z.string().nullish(),
+  deadline: deadlineSchema,
+  status: z.string().nullish(),
+  modifiedBy: TaskChangeActorSchema.nullish(),
+  userDefinedFields: z.record(z.any()).nullish(),
+  workpackageId: z.string().nullish(),
+  location: TaskChangeLocationSchema.nullish(),
+}).passthrough();
+
+/** Mirrors models/tasks/models.py::TaskChange. */
+const TaskChangeSchema = z.object({
+  taskId: z.string(),
+  description: z.string().nullish(),
+  timestamp: z.string(),
+  action: z.string(),
+  fields: TaskChangeFieldsSchema.nullish(),
+});
+
+/** Mirrors models/tasks/models.py::TaskAttachment. */
+const TaskAttachmentSchema = z.object({
+  attachmentId: z.string().nullish(),
+  taskId: z.string().nullish(),
+  fileId: z.string().nullish(),
+}).passthrough();
+
+const TasksListResponseSchema = listResponseSchema(TaskSchema);
+const TaskResponseSchema = singleResponseSchema(TaskSchema);
+const TaskChangeResponseSchema = singleResponseSchema(TaskChangeSchema);
+/** Bare-list payloads (`[...]` instead of `{items: [...]}`) are handled by listResponseSchema's preprocessor. */
+const TaskChangesSchema = listResponseSchema(TaskChangeSchema);
+const TaskAttachmentsListResponseSchema = listResponseSchema(TaskAttachmentSchema);
+
+module.exports = {
+  TaskSchema,
+  TaskListParamsSchema,
+  TaskChangeActorSchema,
+  TaskChangeLocationSchema,
+  TaskChangeFieldsSchema,
+  TaskChangeSchema,
+  TaskAttachmentSchema,
+  TasksListResponseSchema,
+  TaskResponseSchema,
+  TaskChangeResponseSchema,
+  TaskChangesSchema,
+  TaskAttachmentsListResponseSchema,
+};

package/src/models/testPlans/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema } = require('../helpers');
+
+/**
+ * Mirrors models/test_plans/models.py::TestPlan — empty placeholder in
+ * Python, so list items stay untyped.
+ */
+const TestPlanSchema = z.any();
+
+const TestPlansListResponseSchema = listResponseSchema(TestPlanSchema);
+
+module.exports = {
+  TestPlanSchema,
+  TestPlansListResponseSchema,
+};

package/src/models/users/index.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/** Mirrors models/users/models.py::User. */
+const UserSchema = z.object({
+  userId: z.string(),
+  userType: z.string(),
+  email: z.string().email(),
+  firstName: z.string().nullish(),
+  lastName: z.string().nullish(),
+});
+
+/** Mirrors models/users/models.py::ProjectUser (User + companyId). */
+const ProjectUserSchema = UserSchema.extend({
+  companyId: z.string().nullish(),
+});
+
+const UsersListResponseSchema = listResponseSchema(ProjectUserSchema);
+/** Single-user response wraps User, not ProjectUser — matches Python. */
+const UserResponseSchema = singleResponseSchema(UserSchema);
+
+module.exports = {
+  UserSchema,
+  ProjectUserSchema,
+  UsersListResponseSchema,
+  UserResponseSchema,
+};

package/src/models/versionSets/index.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/** Mirrors models/version_sets/models.py::VersionSet. */
+const VersionSetSchema = z.object({
+  versionSetId: z.string(),
+  name: z.string(),
+  description: z.string().nullish(),
+  status: z.string().nullish(),
+  fileAreaId: z.string(),
+});
+
+const VersionSetsListResponseSchema = listResponseSchema(VersionSetSchema);
+const VersionSetResponseSchema = singleResponseSchema(VersionSetSchema);
+
+module.exports = {
+  VersionSetSchema,
+  VersionSetsListResponseSchema,
+  VersionSetResponseSchema,
+};

package/src/models/workPackages/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema } = require('../helpers');
+
+/** Mirrors models/work_packages/models.py::WorkPackage (extra="allow" -> passthrough). */
+const WorkPackageSchema = z.object({
+  workpackageId: z.string().nullish(),
+  companyId: z.string().nullish(),
+  name: z.string().nullish(),
+}).passthrough();
+
+/** No single-item response class in Python. */
+const WorkPackagesListResponseSchema = listResponseSchema(WorkPackageSchema);
+
+module.exports = {
+  WorkPackageSchema,
+  WorkPackagesListResponseSchema,
+};

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