dalux-build-api 1.1.5 → 2.0.0

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

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

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