dalux-build-api 1.1.3 → 2.0.0

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,133 @@
-'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');
+
+const models = require('./models');
+
+/**
+ * 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,
+  // 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 };

package/src/models/files/index.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema, nullableDefault } = require('../helpers');
+
+/** Mirrors models/files/models.py::Reference. */
+const ReferenceSchema = z.object({
+  key: z.string(),
+  value: z.string(),
+});
+
+/** Mirrors models/files/models.py::FileIntegerProperty. */
+const FileIntegerPropertySchema = z.object({
+  integer: z.number().nullish(),
+});
+
+/** Mirrors models/files/models.py::FileDateProperty. */
+const FileDatePropertySchema = z.object({
+  date: z.string().nullish(),
+});
+
+/** Mirrors models/files/models.py::FileTextProperty. */
+const FileTextPropertySchema = z.object({
+  text: z.string().nullish(),
+});
+
+/** Mirrors models/files/models.py::FileReferenceProperty. */
+const FileReferencePropertySchema = z.object({
+  reference: ReferenceSchema.nullish(),
+});
+
+/** Mirrors models/files/models.py::FilePropertyField. */
+const FilePropertyFieldSchema = z.object({
+  key: z.string(),
+  name: z.string(),
+  values: z.array(z.any()).nullish(),
+});
+
+/**
+ * Mirrors models/files/models.py::FileNameFilter. Client-side filter params
+ * (not part of any API response), so field names stay plain camelCase with
+ * no aliasing concerns on either side.
+ */
+const FileNameFilterSchema = z.object({
+  contains: z.array(z.string()).optional(),
+  containsMatch: z.enum(['any', 'all']).default('any'),
+  notContains: z.array(z.string()).optional(),
+  startswith: z.array(z.string()).optional(),
+  notStartswith: z.array(z.string()).optional(),
+  endswith: z.array(z.string()).optional(),
+  notEndswith: z.array(z.string()).optional(),
+  extensions: z.array(z.string()).optional(),
+  notExtensions: z.array(z.string()).optional(),
+});
+
+/**
+ * Mirrors models/files/models.py::File. `uploaded`/`lastModified` are kept
+ * as ISO date strings (not coerced to JS Date) so JSON round-tripping and
+ * existing string-based consumer code keeps working.
+ */
+const FileSchema = z.object({
+  fileId: z.string(),
+  fileRevisionId: z.string().nullish(),
+  fileName: z.string(),
+  fileAreaId: z.string(),
+  folderId: z.string().nullish(),
+  uploadedByUserId: z.string().nullish(),
+  uploaded: z.string().nullish(),
+  lastModifiedByUserId: z.string().nullish(),
+  lastModified: z.string().nullish(),
+  version: z.string().nullish(),
+  deleted: nullableDefault(z.boolean(), false),
+  fileType: z.string().nullish(),
+  fileSize: z.number().nullish(),
+  contentHash: z.string().nullish(),
+  downloadLink: z.string().nullish(),
+  properties: z.array(FilePropertyFieldSchema).nullish(),
+  // Local-only fields set by bulk-download helpers, not present in raw API responses.
+  savedFilePath: z.string().nullish(),
+  savedMetadataPath: z.string().nullish(),
+});
+
+const FilesListResponseSchema = listResponseSchema(FileSchema);
+const FileResponseSchema = singleResponseSchema(FileSchema);
+
+module.exports = {
+  ReferenceSchema,
+  FileIntegerPropertySchema,
+  FileDatePropertySchema,
+  FileTextPropertySchema,
+  FileReferencePropertySchema,
+  FilePropertyFieldSchema,
+  FileNameFilterSchema,
+  FileSchema,
+  FilesListResponseSchema,
+  FileResponseSchema,
+};

package/src/models/folders/index.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/** Mirrors models/folders/models.py::Folder. */
+const FolderSchema = z.object({
+  folderId: z.string(),
+  folderName: z.string(),
+  parentFolderId: z.string().nullish(),
+});
+
+const FoldersListResponseSchema = listResponseSchema(FolderSchema);
+const FolderResponseSchema = singleResponseSchema(FolderSchema);
+
+module.exports = {
+  FolderSchema,
+  FoldersListResponseSchema,
+  FolderResponseSchema,
+};

package/src/models/forms/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const { z } = require('zod');
+const { listResponseSchema, singleResponseSchema } = require('../helpers');
+
+/**
+ * Mirrors models/forms/models.py::Form — empty placeholder in Python, so
+ * items stay untyped.
+ */
+const FormSchema = z.any();
+
+const FormsListResponseSchema = listResponseSchema(FormSchema);
+const FormResponseSchema = singleResponseSchema(FormSchema);
+
+module.exports = {
+  FormSchema,
+  FormsListResponseSchema,
+  FormResponseSchema,
+};

package/src/models/helpers.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { z } = require('zod');
+const { LinkSchema, MetadataSchema } = require('./common');
+
+/**
+ * Unwraps a `{ data: {...} }` wrapper before validating against `schema`.
+ * Bare objects (no `data` wrapper) pass straight through.
+ * Mirrors the `unwrap_and_convert_items` field_validator repeated across
+ * every Python `responses.py` file.
+ * @param {import('zod').ZodTypeAny} schema
+ */
+function unwrapData(schema) {
+  return z.preprocess((value) => {
+    if (value && typeof value === 'object' && !Array.isArray(value) && 'data' in value) {
+      return value.data;
+    }
+    return value;
+  }, schema);
+}
+
+/**
+ * Builds a `{ items, metadata?, links? }` list-response schema.
+ * Accepts a bare array payload too (wraps it as `{ items: [...] }`) —
+ * mirrors TaskChanges' `wrap_list_payloads` model_validator.
+ * @param {import('zod').ZodTypeAny} itemSchema
+ */
+function listResponseSchema(itemSchema) {
+  return z.preprocess(
+    (value) => (Array.isArray(value) ? { items: value } : value),
+    z.object({
+      items: z.array(unwrapData(itemSchema)).default([]),
+      metadata: MetadataSchema.optional(),
+      links: z.array(LinkSchema).optional(),
+    }),
+  );
+}
+
+/**
+ * Builds a `{ data, links? }` single-item response schema.
+ * @param {import('zod').ZodTypeAny} itemSchema
+ */
+function singleResponseSchema(itemSchema) {
+  return z.object({
+    data: itemSchema,
+    links: z.array(LinkSchema).optional(),
+  });
+}
+
+/**
+ * A defaulted field that also accepts an explicit JSON `null` (treated the
+ * same as an absent field) — mirrors Pydantic's `Optional[T] = default`,
+ * which accepts both a missing key and an explicit `null`. Plain
+ * `schema.default(x)` alone only fires on `undefined`, not `null`.
+ * @param {import('zod').ZodTypeAny} schema
+ * @param {*} defaultValue
+ */
+function nullableDefault(schema, defaultValue) {
+  return z.preprocess((v) => (v === null ? undefined : v), schema.default(defaultValue));
+}
+
+module.exports = { unwrapData, listResponseSchema, singleResponseSchema, nullableDefault };